coordinator: docs + allium spec lockstep catch-up

Following CLAUDE.md #5 ("docs and specs stay in lockstep with code"),
catching up QUICKSTART, README, and the allium spec for today's
rapid-fire changes that drifted them.

QUICKSTART:
- 6f rewritten: api_token_ceiling is now a panic brake (500M default),
  not a budget. Real cost control is wall-hours + cost-anomaly
  tripwire + auto-pause on streak. Mentions --token-ceiling CLI flag.
- Step 8: `-u` unbuffered flag added to launch command; CLI flag
  examples (--token-ceiling, --wall-hours-ceiling) shown.
- New §8a "Autopilot behaviors" — summarizes phase pivot, cost anomaly
  tripwire, cooperative pause (.coordinator/pause), and sdk-errors
  capture. Things the user doesn't need to trigger but should know
  exist.

README:
- Model-routing table rewritten for the proposer-implementer split.
  Proposer (Opus) authors detailed implementation_plan; Implementer
  (Sonnet when plan present) executes mechanically with max_turns=25
  and Task tool blocked. Reviewers see plan + diff, hack_detector has
  a plan_fidelity advisory check.
- Added a prose block explaining WHY the split: iter 16 Opus-as-
  implementer reached for Task, spawned 17-min sub-agent, crashed
  with $291 burned. Moving design into proposer + Sonnet-executes
  makes it mechanical, bounded, ~5× cheaper.

allium spec (via allium:tend subagent):
- Config: plateau_pivot_lookback, max_pivots_before_halt, all
  cost_anomaly_* fields, api_token_ceiling 500M with panic-brake
  prose, CLI flag override semantics.
- Candidate.implementation_plan; Budget.consecutive_cost_anomalies;
  Db.pivot_banned_families + pivot_count fields.
- New rules: AutopilotPivotOnPhasePlateau, CheckCostAnomalyAt
  IterationEnd, WaitWhilePaused.
- Modified rule guidance: UnanimousReviewRequired (plan passthrough),
  ProposeCandidatesWhenQueueDry (plan requirement + pivot_clause),
  DiversityBanStuckFamilies (persistent-ban union), PhaseExitOnPlateau
  (superseded note + hard-halt path retained).
- New CoordinatorConsole guarantees: TaskToolBlockedForImplementer,
  ProposerImplementerSplit, DurableTokenLogging, SdkErrorsCaptured,
  LiveBudgetCeilingsFromDb, CooperativePause.
- allium check: 0 errors, 28 pre-existing warnings.

All 102 coordinator tests pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: ellataira

tasks/coordinator/QUICKSTART.md

@@ -233,13 +233,15 @@ PYTHONPATH=tasks python -m coordinator.seed_candidates
 # different from the baseline-measured version.
 PYTHONPATH=tasks python -m coordinator.import_validations
 
-# 6f. Before the real run, set a hard API-token ceiling. Edit
-# tasks/coordinator/config.py:
+# 6f. Token ceiling is now a PANIC BRAKE, not a budget. Default is
+# 500M tokens (≈ $2.5k-7.5k Opus list price) — deliberately set very
+# high so a 72h run finishes without nagging halts. Actual cost control
+# is wall-hours + per-iter cost-anomaly tripwire + autopilot pause on
+# consecutive-anomaly streak (see §Autopilot behaviors below).
 #
-#    api_token_ceiling: int | None = 20_000_000   # ≈ $50-200 of Opus
-#
-# Prevents a runaway edge case from burning $1-5k of API spend.
-# Leave None while smoke-testing.
+# To tighten the ceiling for a specific cost-bounded run, pass
+# --token-ceiling N to the driver CLI. Same for wall hours:
+# --wall-hours-ceiling H. Both persist to db.budget on first save.
 ```
 
 If `eval-results/` doesn't exist on this driver workspace yet, pull it
@@ -284,13 +286,62 @@ Expected flow:
 ## 8. Launch the forever loop
 
 ```bash
-PYTHONPATH=tasks python -m coordinator.driver --forever 2>&1 | tee -a .coordinator/driver.log
+PYTHONPATH=tasks python -u -m coordinator.driver --forever 2>&1 | tee -a .coordinator/driver.log
+```
+
+`-u` is important — unbuffered Python output so `tail -f driver.log` updates live.
+
+Optional CLI overrides (both persist to `db.budget` so you don't need to re-pass on restart):
+
+```bash
+# Tighten the panic-brake for a bounded run
+PYTHONPATH=tasks python -u -m coordinator.driver --forever \
+    --token-ceiling 50000000 \
+    --wall-hours-ceiling 48 \
+    2>&1 | tee -a .coordinator/driver.log
 ```
 
 Detach from tmux with `Ctrl-b d`. The loop keeps running.
 
 ---
 
+## 8a. Autopilot behaviors (you don't need to do anything for these)
+
+Three autonomous reactions the coordinator takes without user input:
+
+**Phase plateau → pivot.** After `plateau_patience` (5) consecutive
+non-improving iterations, the driver auto-bans every `approach_family`
+from the last 5 iters into `db.pivot_banned_families` (persistent),
+resets the plateau counter, fires a `phase_pivot` PR comment, and
+keeps running. The proposer's next call sees a "this is a pivot"
+block in its prompt and generates structurally-different candidates.
+Only hard-halts (requires_ack) after `max_pivots_before_halt` (4)
+pivots without any ship — "structurally un-improvable."
+
+**Per-iter cost anomaly tripwire.** At iteration end, driver compares
+this iter's token cost to the rolling mean of the last 5. If
+`this_cost > 2× rolling_mean` OR `this_tokens > 10M`, a `cost_anomaly`
+PR comment fires with the triggers enumerated. After 3 consecutive
+anomalous iters, driver writes `.coordinator/pause` to cooperatively
+halt at the next iter boundary — user must `rm .coordinator/pause`
+to resume. Nothing in flight is wasted (iter finishes normally first).
+
+**Cooperative pause.** Touch `.coordinator/pause` at any time to stop
+the loop at the next iter boundary. Safer than Ctrl-C (doesn't lose
+mid-iter implementation work). Remove the file to resume. Used by the
+auto-pause above; also usable manually for "let me look at recent
+comments before you spend more money."
+
+**SDK error capture.** When an SDK call crashes (claude CLI subprocess
+exits non-zero, which unfortunately surfaces as bare "exit code 1"
+through the SDK), the driver dumps full context to
+`.coordinator/sdk-errors/<ts>-<purpose>.txt`: exception repr, cause
+chain, traceback, plus enrichment (token-log stats for the iter, last
+N SDK message types, git state at crash, SDK versions). Referenced
+in the `iter_impl_failed` PR comment.
+
+---
+
 ## 9. Watch it
 
 From the driver workspace (or by sshing in from your laptop):

tasks/coordinator/README.md

@@ -413,15 +413,21 @@ experiment for audit.
 
 ## Model routing
 
-Deep-thinking SDK calls use Opus; lightweight summaries use Sonnet.
+Design/judgment work uses Opus; mechanical execution uses Sonnet.
 Tune in `config.py`:
 
 | Role | Model | Task |
 |---|---|---|
-| Implementation agent | `model_deep` (Opus) | writing code for a candidate |
-| Review personas | `model_deep` (Opus) | judging approve/reject |
-| Proposer | `model_deep` (Opus) | brainstorming new candidates from history |
-| Inbox interpreter | `model_light` (Sonnet) | summarizing a user message |
+| **Proposer** | `model_deep` (Opus) | Brainstorm novel directions AND author a detailed `implementation_plan` per candidate (30-80 lines: exact files, interface contract, numbered algorithm steps, data shapes, test plan, perf). Opus does the design work. |
+| **Implementation agent** | `model_light` (Sonnet) when a plan is present | Execute the plan mechanically. `max_turns=25`. No design discretion. Task tool hard-blocked via PreToolUse hook. Falls back to Opus if the candidate has no plan (rare). |
+| Review personas (×3) | `model_deep` (Opus) | Judge approve/reject. See both the diff AND the plan; `plan_fidelity` check flags deviations. A net-positive deviation ships; a net-negative one doesn't. |
+| Inbox interpreter | `model_light` (Sonnet) | Distill a user PR comment into (interpretation, planned_change). |
+
+Why this split: Opus-as-implementer reached for the Task tool on big
+candidates, spawning sub-agents that crashed after 17 minutes and
+burned $291 per iter (iter 16 matrix-profile). Moving design into the
+proposer + executing with Sonnet + plan makes implementations
+mechanical, bounded, and ~5× cheaper.
 
 Set `CONFIG.model_deep` / `CONFIG.model_light` to an empty string to fall
 back to the SDK default.