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, 10 insertions, 5 deletions

diff --git a/docs/api-keys-setup.md b/docs/api-keys-setup.md
index 1a9daf9..83c98e1 100644
--- a/docs/api-keys-setup.md
+++ b/docs/api-keys-setup.md
@@ -6,9 +6,9 @@ Providers, in escalation-ladder order (cheapest/free first):
 
 | Provider | Status | Cost | Wire format |
 |---|---|---|---|
-| Groq | to add (works once configured — Phase 1's `openaicompat` adapter, no dedicated phase needed) | free tier (real, no card required historically) | OpenAI-compatible |
-| OpenRouter | to add (same as Groq) | free tier (rate-limited) + pay-as-you-go | OpenAI-compatible |
-| OpenAI | to add (same as Groq) | prepaid credit, no ongoing free tier | OpenAI-compatible (native) |
+| Groq | **wired up (Phase 5)** — `agent.type: "groq"` works as soon as a key is in `config.toml` (Phase 1's `openaicompat` adapter, no dedicated adapter package needed) | free tier (real, no card required historically) | OpenAI-compatible |
+| OpenRouter | **wired up (Phase 5)** — `agent.type: "openrouter"` works as soon as a key is in `config.toml` (same adapter as Groq) | free tier (rate-limited) + pay-as-you-go | OpenAI-compatible |
+| OpenAI | **wired up (Phase 5)** — `agent.type: "openai"` works as soon as a key is in `config.toml` (same adapter as Groq) | prepaid credit, no ongoing free tier | OpenAI-compatible (native) |
 | Google (Gemini) | **wired up (Phase 4)** — `agent.type: "google"` works as soon as a key is in `config.toml` | paid (already have account) | native (Gemini API) |
 | Anthropic (Claude) | **wired up (Phase 2)** — `agent.type: "anthropic"` works as soon as a key is in `config.toml` | paid (already have account) | native (Messages API) |
 
@@ -60,6 +60,7 @@ Free tier, no credit card required to start. Good first escalation rung above lo
 3. Copy the key immediately — Groq only shows it once (`gsk_...`).
 4. Rate limits (free tier, vary per model): roughly 30 requests/minute, 6K–70K tokens/minute, 1K–14.4K requests/day, 100K–500K tokens/day depending on the specific model. Check `console.groq.com/settings/limits` for your account's current numbers per model — this varies enough by model that it's worth checking directly rather than trusting a fixed table here.
 5. Put the key in `config.toml` under `[providers.groq]` as shown above. `endpoint` is Groq's OpenAI-compatible base: `https://api.groq.com/openai/v1`.
+6. As soon as the key is set, `claudomator serve`/`run` registers `agent.type: "groq"` as a usable runner — no restart-time flag needed beyond having the key present. To turn it off without removing the key, set `[runners] groq = false`.
 
 ---
 
@@ -72,6 +73,7 @@ Aggregates many providers/models behind one key, including models with a `:free`
 3. Free-tier limits: **without any credit purchase**, 50 free-model requests/day total across all `:free`-suffixed models. **With $10+ in purchased credits**, that jumps to 1000 requests/day (a one-time credit purchase, not a subscription) — worth doing once your usage grows past the bare free tier, since it's a 20x limit increase for a fixed cost, not a recurring charge.
 4. Pick a free model when configuring the harness — model IDs ending in `:free` (e.g. `meta-llama/llama-3.3-70b-instruct:free`) don't draw down credits. Browse current free models at `openrouter.ai/models?max_price=0`.
 5. `endpoint` is `https://openrouter.ai/api/v1`.
+6. As soon as the key is set, `claudomator serve`/`run` registers `agent.type: "openrouter"` as a usable runner. To turn it off without removing the key, set `[runners] openrouter = false`.
 
 ---
 
@@ -84,6 +86,7 @@ No meaningful ongoing free tier at this point — expect to prepay. Included in
 3. **Dashboard → API keys** (`platform.openai.com/api-keys`) → **Create new secret key**. Name it, copy it (`sk-...`) — shown once.
 4. Consider setting a spend limit under **Billing → Limits** so a runaway harness escalation can't produce a surprise bill — this matters more here than for Groq/OpenRouter's free tiers.
 5. `endpoint` is `https://api.openai.com/v1`.
+6. As soon as the key is set, `claudomator serve`/`run` registers `agent.type: "openai"` as a usable runner. To turn it off without removing the key, set `[runners] openai = false`.
 
 ---
 
@@ -119,7 +122,7 @@ Same situation as Gemini: `credentials/claude/` holds the `claude` CLI's OAuth s
 
 ## Sanity-checking a key works
 
-Once phase 1/2/4 of the harness redesign land (native `Provider` adapters), the quickest check is submitting a trivial role-typed task pinned to a single rung, e.g. via the CLI:
+All five providers are wired up as of Phase 5 (`internal/cli/cloudrunners.go`). The quickest check is submitting a trivial task pinned to a single provider directly (bypassing role-based escalation), e.g. via the CLI:
 
 ```bash
 ./claudomator run - <<'EOF'
@@ -131,4 +134,6 @@ agent:
 EOF
 ```
 
-and checking `GET /api/budget` afterward to confirm the provider's spend/usage was recorded. Until then, you can at minimum confirm the key itself is valid with a raw `curl` against the provider's chat-completions endpoint using the docs above.
+and checking `GET /api/budget` afterward to confirm the provider's spend/usage was recorded. You can also confirm the key itself is valid directly with a raw `curl` against the provider's chat-completions endpoint using the docs above.
+
+To exercise a provider through the escalation ladder instead of pinning `agent.type` directly, create a role via `POST /api/roles/{role}/versions` with an `escalation_ladder` naming the provider, activate it with `POST /api/roles/{role}/activate?version=1`, and submit a task with `agent.role` set instead of `agent.type`/`agent.model` — see `CLAUDE.md`'s "Role-based dispatch & escalation" section.