feat(role): add versioned role configs + escalation ladder + scheduler (Phase 5)

Two parts:

Part A (fixes a gap from Phase 1): Groq/OpenRouter/OpenAI were documented in
docs/api-keys-setup.md as usable once configured, but nothing actually
constructed runners for them. internal/cli/cloudrunners.go consolidates
anthropic/google/groq/openrouter/openai NativeRunner construction into one
table-driven registerCloudRunners() helper, replacing the two hand-written
per-provider blocks in serve.go/run.go. Groq/OpenRouter/OpenAI reuse
openaicompat (no new adapter code) at SandboxKind: "docker".

Part B: the token-husbanding harness's core routing mechanism.

- internal/role: RoleConfig/Tier/Rung -- a role's system prompt and a
  multi-tier (provider, model) escalation ladder, versioned via config_json.
- storage: new role_configs table (draft/active/retired, UNIQUE(role,
  version)) with transactional activate-retires-prior-active semantics;
  new executions.escalation_rung column.
- task.AgentConfig.Role string -- purely additive; every existing task shape
  (Agent.Role == "") is unaffected, proven by TestPool_Execute_NonRoleTask_Unaffected
  plus the full pre-existing suite passing unchanged.
- executor.Pool.execute(): role-typed tasks with no Agent.Type yet resolve
  tier 0 of their active ladder (round-robin across multi-candidate tiers,
  skipping rate-limited providers, falling back to soonest-clearing) before
  the existing pickAgent/Classifier path runs; SystemPrompt applies to
  Agent.SystemPromptAppend. Already-resolved role tasks (scheduler resubmits)
  get their escalation_rung re-derived read-only via findTierIndex.
- internal/scheduler: polls role-typed FAILED tasks, retries at the same
  rung under MaxRetries or escalates to the next tier's first candidate when
  budget.Accountant.Allow() permits (emitting event.KindEscalated), else
  leaves the task FAILED with a final:true KindEscalated event. An
  in-memory per-execution-ID "handled" set keeps the poll loop convergent.
  Started by `serve` only, config knob [scheduler].poll_interval_seconds.
- internal/api: POST/GET /api/roles/{role}/versions, POST
  /api/roles/{role}/activate -- unauthenticated, matching the existing
  projects/tasks REST endpoints' auth posture (only chatbot MCP, agent MCP,
  and WebSocket are api_token-gated in this codebase today).

Documented as stored-but-not-yet-enforced (CLAUDE.md Design Debt, matching
how task.Priority/RetryConfig are already documented): RoleConfig.Tools/
SandboxKind don't affect dispatch yet; DefaultBudgetUSD is read narrowly as
the scheduler's escalation cost estimate, not enforced at initial dispatch;
scheduler escalation always targets Candidates[0] (no round-robin, unlike
initial-dispatch tier-0 resolution); the scheduler's dedupe is per-process
and resets on restart (idempotent, harmless).

go build/vet/test -race -count=1 all pass, 21 packages.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01V1moSNCJRcP6kykA4tyUSs

1 files changed, 177 insertions, 0 deletions

diff --git a/internal/api/roles_test.go b/internal/api/roles_test.go
new file mode 100644
index 0000000..97afdfe
--- /dev/null
+++ b/internal/api/roles_test.go
@@ -0,0 +1,177 @@
+package api
+
+import (
+	"bytes"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strconv"
+	"testing"
+
+	"github.com/thepeterstone/claudomator/internal/role"
+)
+
+// TestServer_CreateRoleVersion_CreatesDraft mirrors the projects endpoint
+// test pattern (see server_test.go's testServer/httptest.NewRequest usage):
+// POSTing a role.RoleConfig body creates a new draft version.
+func TestServer_CreateRoleVersion_CreatesDraft(t *testing.T) {
+	srv, _ := testServer(t)
+
+	body, _ := json.Marshal(map[string]any{
+		"system_prompt": "You are a careful coder.",
+		"escalation_ladder": []map[string]any{
+			{
+				"candidates":     []map[string]any{{"provider": "local", "model": "llama3.1:8b"}},
+				"selection_mode": "single",
+				"max_retries":    2,
+			},
+		},
+	})
+	req := httptest.NewRequest("POST", "/api/roles/coder/versions", bytes.NewReader(body))
+	w := httptest.NewRecorder()
+	srv.Handler().ServeHTTP(w, req)
+
+	if w.Code != http.StatusCreated {
+		t.Fatalf("expected 201, got %d: %s", w.Code, w.Body.String())
+	}
+	var got struct {
+		Role    string          `json:"role"`
+		Version int             `json:"version"`
+		Status  string          `json:"status"`
+		Config  role.RoleConfig `json:"config"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &got); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if got.Role != "coder" {
+		t.Errorf("role = %q, want %q", got.Role, "coder")
+	}
+	if got.Version != 1 {
+		t.Errorf("version = %d, want 1", got.Version)
+	}
+	if got.Status != "draft" {
+		t.Errorf("status = %q, want draft", got.Status)
+	}
+	if got.Config.SystemPrompt != "You are a careful coder." {
+		t.Errorf("system_prompt round-trip failed: got %q", got.Config.SystemPrompt)
+	}
+	if len(got.Config.EscalationLadder) != 1 {
+		t.Fatalf("expected 1 tier, got %d", len(got.Config.EscalationLadder))
+	}
+}
+
+// TestServer_ListRoleVersions_ReturnsAllVersions posts two versions and
+// confirms the list endpoint returns both, ordered by version.
+func TestServer_ListRoleVersions_ReturnsAllVersions(t *testing.T) {
+	srv, _ := testServer(t)
+
+	for i := 0; i < 2; i++ {
+		body, _ := json.Marshal(map[string]any{"system_prompt": "v"})
+		req := httptest.NewRequest("POST", "/api/roles/coder/versions", bytes.NewReader(body))
+		w := httptest.NewRecorder()
+		srv.Handler().ServeHTTP(w, req)
+		if w.Code != http.StatusCreated {
+			t.Fatalf("create version %d: expected 201, got %d", i, w.Code)
+		}
+	}
+
+	req := httptest.NewRequest("GET", "/api/roles/coder/versions", nil)
+	w := httptest.NewRecorder()
+	srv.Handler().ServeHTTP(w, req)
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d: %s", w.Code, w.Body.String())
+	}
+
+	var got []struct {
+		Version int    `json:"version"`
+		Status  string `json:"status"`
+	}
+	if err := json.Unmarshal(w.Body.Bytes(), &got); err != nil {
+		t.Fatalf("decode response: %v", err)
+	}
+	if len(got) != 2 {
+		t.Fatalf("expected 2 versions, got %d", len(got))
+	}
+	if got[0].Version != 1 || got[1].Version != 2 {
+		t.Errorf("expected versions [1,2], got [%d,%d]", got[0].Version, got[1].Version)
+	}
+	for _, v := range got {
+		if v.Status != "draft" {
+			t.Errorf("version %d: expected status draft, got %q", v.Version, v.Status)
+		}
+	}
+}
+
+// TestServer_ActivateRoleVersion_ActivatesAndRetiresPrior exercises the full
+// create -> activate -> create -> activate cycle over HTTP, confirming the
+// exactly-one-active-row invariant surfaces correctly through the API.
+func TestServer_ActivateRoleVersion_ActivatesAndRetiresPrior(t *testing.T) {
+	srv, store := testServer(t)
+
+	post := func(body string) {
+		req := httptest.NewRequest("POST", "/api/roles/coder/versions", bytes.NewReader([]byte(body)))
+		w := httptest.NewRecorder()
+		srv.Handler().ServeHTTP(w, req)
+		if w.Code != http.StatusCreated {
+			t.Fatalf("create version: expected 201, got %d: %s", w.Code, w.Body.String())
+		}
+	}
+	post(`{"system_prompt":"v1"}`)
+	post(`{"system_prompt":"v2"}`)
+
+	activate := func(version int) int {
+		req := httptest.NewRequest("POST", "/api/roles/coder/activate?version="+strconv.Itoa(version), nil)
+		w := httptest.NewRecorder()
+		srv.Handler().ServeHTTP(w, req)
+		return w.Code
+	}
+
+	if code := activate(1); code != http.StatusOK {
+		t.Fatalf("activate v1: expected 200, got %d", code)
+	}
+	active, err := store.GetActiveRoleConfig("coder")
+	if err != nil {
+		t.Fatalf("GetActiveRoleConfig: %v", err)
+	}
+	if active.Version != 1 {
+		t.Fatalf("expected active version 1, got %d", active.Version)
+	}
+
+	if code := activate(2); code != http.StatusOK {
+		t.Fatalf("activate v2: expected 200, got %d", code)
+	}
+	active, err = store.GetActiveRoleConfig("coder")
+	if err != nil {
+		t.Fatalf("GetActiveRoleConfig: %v", err)
+	}
+	if active.Version != 2 {
+		t.Fatalf("expected active version 2 after activating it, got %d", active.Version)
+	}
+
+	versions, err := store.ListRoleConfigVersions("coder")
+	if err != nil {
+		t.Fatalf("ListRoleConfigVersions: %v", err)
+	}
+	activeCount := 0
+	for _, v := range versions {
+		if v.Status == "active" {
+			activeCount++
+		}
+	}
+	if activeCount != 1 {
+		t.Fatalf("expected exactly 1 active version, got %d", activeCount)
+	}
+}
+
+// TestServer_ActivateRoleVersion_UnknownVersion_Returns400 confirms
+// activating a version that doesn't exist is a client error, not a panic or
+// 500.
+func TestServer_ActivateRoleVersion_UnknownVersion_Returns400(t *testing.T) {
+	srv, _ := testServer(t)
+	req := httptest.NewRequest("POST", "/api/roles/coder/activate?version=99", nil)
+	w := httptest.NewRecorder()
+	srv.Handler().ServeHTTP(w, req)
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d: %s", w.Code, w.Body.String())
+	}
+}