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, 206 insertions, 0 deletions

diff --git a/internal/executor/role_dispatch_test.go b/internal/executor/role_dispatch_test.go
new file mode 100644
index 0000000..5628bdb
--- /dev/null
+++ b/internal/executor/role_dispatch_test.go
@@ -0,0 +1,206 @@
+package executor
+
+import (
+	"context"
+	"encoding/json"
+	"log/slog"
+	"os"
+	"testing"
+	"time"
+
+	"github.com/thepeterstone/claudomator/internal/role"
+)
+
+// TestPool_Execute_RoleTypedTask_ResolvesTier0 is the Pool.execute()-level
+// verification (Phase 5 item 3) that a role-typed task with an empty
+// Agent.Type resolves tier 0 of the active role_configs ladder before
+// dispatch: it should run through the tier-0 provider/model, and the
+// resulting execution should be stamped with EscalationRung 0.
+func TestPool_Execute_RoleTypedTask_ResolvesTier0(t *testing.T) {
+	store := testStore(t)
+
+	rc := role.RoleConfig{
+		Role: "coder",
+		EscalationLadder: []role.Tier{
+			{
+				Candidates:    []role.Rung{{Provider: "groq", Model: "llama-3.3-70b-versatile"}},
+				SelectionMode: "single",
+				MaxRetries:    1,
+			},
+			{
+				Candidates: []role.Rung{{Provider: "anthropic", Model: "claude-sonnet-5"}},
+				MaxRetries: 1,
+			},
+		},
+	}
+	configJSON, err := json.Marshal(rc)
+	if err != nil {
+		t.Fatalf("marshal role config: %v", err)
+	}
+	created, err := store.CreateRoleConfig("coder", string(configJSON), "human")
+	if err != nil {
+		t.Fatalf("CreateRoleConfig: %v", err)
+	}
+	if err := store.ActivateRoleConfigVersion("coder", created.Version); err != nil {
+		t.Fatalf("ActivateRoleConfigVersion: %v", err)
+	}
+
+	runners := map[string]Runner{
+		"groq": &mockRunner{},
+	}
+	logger := slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelError}))
+	pool := NewPool(2, runners, store, logger)
+
+	tk := makeTask("role-task-1")
+	tk.Agent.Type = ""
+	tk.Agent.Model = ""
+	tk.Agent.Role = "coder"
+	tk.Agent.SkipPlanning = true
+	if err := store.CreateTask(tk); err != nil {
+		t.Fatalf("CreateTask: %v", err)
+	}
+
+	if err := pool.Submit(context.Background(), tk); err != nil {
+		t.Fatalf("Submit: %v", err)
+	}
+
+	select {
+	case result := <-pool.Results():
+		if result.Err != nil {
+			t.Fatalf("expected no error, got: %v", result.Err)
+		}
+		if result.Execution.Agent != "groq" {
+			t.Errorf("execution.Agent: want %q, got %q", "groq", result.Execution.Agent)
+		}
+		if result.Execution.EscalationRung != 0 {
+			t.Errorf("execution.EscalationRung: want 0, got %d", result.Execution.EscalationRung)
+		}
+	case <-time.After(5 * time.Second):
+		t.Fatal("timed out waiting for result")
+	}
+
+	persisted, err := store.GetTask(tk.ID)
+	if err != nil {
+		t.Fatalf("GetTask: %v", err)
+	}
+	if persisted.Agent.Type != "groq" {
+		t.Errorf("persisted Agent.Type: want %q, got %q", "groq", persisted.Agent.Type)
+	}
+	if persisted.Agent.Model != "llama-3.3-70b-versatile" {
+		t.Errorf("persisted Agent.Model: want %q, got %q", "llama-3.3-70b-versatile", persisted.Agent.Model)
+	}
+}
+
+// TestPool_Execute_NonRoleTask_Unaffected proves that a task with
+// Agent.Role == "" (every existing YAML/chatbot task shape) takes none of
+// the role-resolution branches in execute() — it dispatches exactly as it
+// did before this phase, using its explicitly-set Agent.Type/Model verbatim.
+func TestPool_Execute_NonRoleTask_Unaffected(t *testing.T) {
+	store := testStore(t)
+	runners := map[string]Runner{
+		"claude": &mockRunner{},
+	}
+	logger := slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelError}))
+	pool := NewPool(2, runners, store, logger)
+
+	tk := makeTask("non-role-task-1")
+	tk.Agent.Type = "claude"
+	tk.Agent.Model = "sonnet"
+	// Agent.Role intentionally left "" (zero value).
+	if err := store.CreateTask(tk); err != nil {
+		t.Fatalf("CreateTask: %v", err)
+	}
+
+	if err := pool.Submit(context.Background(), tk); err != nil {
+		t.Fatalf("Submit: %v", err)
+	}
+
+	select {
+	case result := <-pool.Results():
+		if result.Err != nil {
+			t.Fatalf("expected no error, got: %v", result.Err)
+		}
+		if result.Execution.Agent != "claude" {
+			t.Errorf("execution.Agent: want %q, got %q", "claude", result.Execution.Agent)
+		}
+		if result.Execution.EscalationRung != 0 {
+			t.Errorf("non-role task execution.EscalationRung should default to 0, got %d", result.Execution.EscalationRung)
+		}
+	case <-time.After(5 * time.Second):
+		t.Fatal("timed out waiting for result")
+	}
+
+	persisted, err := store.GetTask(tk.ID)
+	if err != nil {
+		t.Fatalf("GetTask: %v", err)
+	}
+	if persisted.Agent.Type != "claude" || persisted.Agent.Model != "sonnet" {
+		t.Errorf("non-role task's Agent.Type/Model should be unchanged: got %q/%q", persisted.Agent.Type, persisted.Agent.Model)
+	}
+}
+
+// TestPool_SelectRung_RoundRobin_SkipsRateLimited proves that repeated
+// selectRung calls on a round_robin tier rotate across candidates rather
+// than always returning candidate 0, and skip a candidate whose provider is
+// currently rate-limited.
+func TestPool_SelectRung_RoundRobin_SkipsRateLimited(t *testing.T) {
+	p := &Pool{
+		rateLimited:   make(map[string]time.Time),
+		roleTierIndex: make(map[string]int),
+	}
+	tier := role.Tier{
+		Candidates: []role.Rung{
+			{Provider: "local", Model: "m1"},
+			{Provider: "groq", Model: "m2"},
+			{Provider: "openrouter", Model: "m3"},
+		},
+		SelectionMode: "round_robin",
+	}
+
+	// With nothing rate-limited, repeated calls should rotate through all
+	// three candidates before repeating.
+	seen := map[string]int{}
+	for i := 0; i < 6; i++ {
+		r := p.selectRung("coder", 0, tier)
+		seen[r.Provider]++
+	}
+	for _, prov := range []string{"local", "groq", "openrouter"} {
+		if seen[prov] != 2 {
+			t.Errorf("expected provider %q to be picked exactly twice across 6 calls, got %d (seen=%v)", prov, seen[prov], seen)
+		}
+	}
+
+	// Now rate-limit "groq" and confirm it's skipped on subsequent picks.
+	p.mu.Lock()
+	p.rateLimited["groq"] = time.Now().Add(1 * time.Hour)
+	p.mu.Unlock()
+
+	for i := 0; i < 6; i++ {
+		r := p.selectRung("coder", 0, tier)
+		if r.Provider == "groq" {
+			t.Errorf("expected rate-limited provider %q to be skipped, got picked at iteration %d", "groq", i)
+		}
+	}
+}
+
+// TestPool_SelectRung_SingleMode_AlwaysFirstCandidate proves "single"
+// selection mode never rotates.
+func TestPool_SelectRung_SingleMode_AlwaysFirstCandidate(t *testing.T) {
+	p := &Pool{
+		rateLimited:   make(map[string]time.Time),
+		roleTierIndex: make(map[string]int),
+	}
+	tier := role.Tier{
+		Candidates: []role.Rung{
+			{Provider: "local", Model: "m1"},
+			{Provider: "groq", Model: "m2"},
+		},
+		SelectionMode: "single",
+	}
+	for i := 0; i < 4; i++ {
+		r := p.selectRung("coder", 0, tier)
+		if r.Provider != "local" {
+			t.Errorf("iteration %d: expected always \"local\" in single mode, got %q", i, r.Provider)
+		}
+	}
+}