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

diff --git a/internal/executor/groq_routing_test.go b/internal/executor/groq_routing_test.go
new file mode 100644
index 0000000..722bf95
--- /dev/null
+++ b/internal/executor/groq_routing_test.go
@@ -0,0 +1,98 @@
+package executor
+
+import (
+	"context"
+	"encoding/json"
+	"log/slog"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"sync/atomic"
+	"testing"
+
+	"github.com/thepeterstone/claudomator/internal/llm"
+	"github.com/thepeterstone/claudomator/internal/provider/openaicompat"
+)
+
+// TestPool_Submit_GroqAgentType_RoutesThroughOpenAICompatProvider is the
+// Part A wiring-level confirmation (verification item 5) that Groq — one of
+// the three providers that docs/api-keys-setup.md documented as "works once
+// configured" but was never actually registered by internal/cli/serve.go or
+// run.go before this phase — is a real, usable runner once wired up. Groq is
+// OpenAI-wire-compatible, so this reuses the existing Phase 1
+// internal/provider/openaicompat adapter (internal/llm.Client) exactly the
+// way internal/cli/cloudrunners.go's registerCloudRunners constructs it: no
+// new adapter package, purely config-driven construction pointed at Groq's
+// endpoint.
+func TestPool_Submit_GroqAgentType_RoutesThroughOpenAICompatProvider(t *testing.T) {
+	var calls int32
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		atomic.AddInt32(&calls, 1)
+		if r.URL.Path != "/chat/completions" {
+			t.Errorf("unexpected path %q", r.URL.Path)
+		}
+		if got := r.Header.Get("Authorization"); got != "Bearer test-groq-key" {
+			t.Errorf("wrong Authorization header: %q", got)
+		}
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"choices": []map[string]any{
+				{
+					"message":       map[string]any{"role": "assistant", "content": "## Summary\ndone"},
+					"finish_reason": "stop",
+				},
+			},
+			"model": "llama-3.3-70b-versatile",
+			"usage": map[string]any{"prompt_tokens": 10, "completion_tokens": 3},
+		})
+	}))
+	defer srv.Close()
+
+	// Mirrors registerCloudRunners' construction for groq/openrouter/openai:
+	// openaicompat.New(&llm.Client{...}) wrapped in a NativeRunner registered
+	// under the "groq" runner-map key, SandboxKind "docker" for the real
+	// wiring (irrelevant here since the task has no ProjectDir/sandbox use).
+	client := &llm.Client{
+		Endpoint: srv.URL,
+		Model:    "llama-3.3-70b-versatile",
+		APIKey:   "test-groq-key",
+	}
+	runners := map[string]Runner{
+		"groq": &NativeRunner{
+			Provider: openaicompat.New(client),
+			Logger:   slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelError})),
+			LogDir:   t.TempDir(),
+		},
+	}
+
+	store := testStore(t)
+	logger := slog.New(slog.NewTextHandler(os.Stderr, &slog.HandlerOptions{Level: slog.LevelError}))
+	pool := NewPool(2, runners, store, logger)
+
+	tk := makeTask("groq-routing-1")
+	tk.Agent.Type = "groq"
+	tk.Agent.Model = "llama-3.3-70b-versatile"
+	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)
+	}
+
+	result := <-pool.Results()
+	if result.Err != nil {
+		t.Fatalf("expected no error, got: %v", result.Err)
+	}
+	if got := atomic.LoadInt32(&calls); got != 1 {
+		t.Fatalf("expected exactly 1 call to the fake Groq server, got %d", got)
+	}
+	if result.Execution.Agent != "groq" {
+		t.Errorf("execution.Agent: want %q, got %q", "groq", result.Execution.Agent)
+	}
+	if result.Execution.TokensIn != 10 || result.Execution.TokensOut != 3 {
+		t.Errorf("tokens should come from the openaicompat provider's usage: got in=%d out=%d",
+			result.Execution.TokensIn, result.Execution.TokensOut)
+	}
+}