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

diff --git a/internal/role/role.go b/internal/role/role.go
new file mode 100644
index 0000000..f65edba
--- /dev/null
+++ b/internal/role/role.go
@@ -0,0 +1,73 @@
+// Package role defines the per-role configuration shape (system prompt, tool
+// allowlist, sandbox kind, budget, and — the part actually driven this phase —
+// a multi-tier provider/model escalation ladder) used by the token-husbanding
+// harness. A RoleConfig is stored as a versioned row in storage's
+// role_configs table (see internal/storage/roleconfig.go); internal/executor
+// resolves tier 0 of a role's EscalationLadder for the initial dispatch of a
+// role-typed task, and internal/scheduler walks the ladder on failure
+// (retry-then-escalate).
+//
+// Not everything on RoleConfig is enforced yet. See the field doc comments
+// below and CLAUDE.md's Design Debt section for what's stored-but-not-wired,
+// matching how this codebase already documents task.Priority/RetryConfig.
+package role
+
+// RoleConfig is one version of a role's configuration.
+type RoleConfig struct {
+	// Role names the role this config applies to (e.g. "coder", "reviewer").
+	Role string `json:"role"`
+
+	// SystemPrompt is appended to Agent.SystemPromptAppend when a task
+	// dispatches through this role (internal/executor.Pool.execute()). Wired.
+	SystemPrompt string `json:"system_prompt,omitempty"`
+
+	// Tools, SandboxKind, and DefaultBudgetUSD are stored and round-tripped
+	// through the API/storage layer but are NOT YET enforced by the executor:
+	// guardrails/tool availability are still applied uniformly by
+	// NativeRunner (Phase 3) regardless of role, and SandboxKind here has no
+	// effect on which sandbox.Sandbox implementation a runner picks (that's
+	// still purely provider-driven, see NativeRunner.SandboxKind). A later
+	// phase should thread these through. DefaultBudgetUSD is read by
+	// internal/scheduler as the estimated cost passed to
+	// budget.Accountant.Allow() when considering an escalation, which is a
+	// narrow, specific use — not general per-role budget enforcement at
+	// dispatch time.
+	Tools            []string `json:"tools,omitempty"`
+	SandboxKind      string   `json:"sandbox_kind,omitempty"`
+	DefaultBudgetUSD float64  `json:"default_budget_usd,omitempty"`
+
+	// EscalationLadder is the ordered list of tiers a role-typed task climbs
+	// on repeated failure. Tier 0 is used for the initial dispatch.
+	EscalationLadder []Tier `json:"escalation_ladder,omitempty"`
+}
+
+// Tier is one rung-group in an escalation ladder: a set of candidate
+// (provider, model) rungs to choose among, plus how many attempts may be made
+// at this tier before the scheduler escalates to the next one.
+type Tier struct {
+	Candidates []Rung `json:"candidates"`
+	// SelectionMode is "round_robin" (default, when empty) or "single" (always
+	// use Candidates[0]).
+	SelectionMode string `json:"selection_mode,omitempty"`
+	// MaxRetries is the number of attempts allowed at this tier before the
+	// scheduler escalates to the next tier. 0 means "escalate immediately
+	// after the first failure at this tier" (no retries held here).
+	MaxRetries int `json:"max_retries"`
+}
+
+// Rung is a single (provider, model) pair. Provider must match a registered
+// executor runner key: "local", "anthropic", "google", "groq", "openrouter",
+// "openai".
+type Rung struct {
+	Provider string `json:"provider"`
+	Model    string `json:"model"`
+}
+
+// EffectiveSelectionMode returns t.SelectionMode, defaulting to
+// "round_robin" when unset.
+func (t Tier) EffectiveSelectionMode() string {
+	if t.SelectionMode == "" {
+		return "round_robin"
+	}
+	return t.SelectionMode
+}