catherd-cli 0.2.1 → 1.0.0

package/plugin/skills/catherd/SKILL.md

@@ -23,32 +23,47 @@ Your job:
 
 The catherd server keeps `state.md` true: it rewrites it on every dispatch, climb and landing.
 
+**Your first call is `status()`.** Its `version` must be the one this plugin pins, `catherd-cli@1.0.0`. If it differs, stop and tell the user to restart Claude Code so the plugin and its server match.
+
 **You never edit product files.** Every line of code, tests or docs comes from a role, including a one-line fix.
 
 **You run in the user's own session, on purpose.** The main thread is the user's own model in Claude Code, with their plugins, hooks and memory beside it: the environment they decide in every day. Never propose a stripped launcher or a headless relay to save tokens.
 
-**Each role runs in its vendor's own harness with the user's customizations — never isolate it.** Codex and opencode roles keep the user's config, hooks, MCP servers, skills and `AGENTS.md`. The one exception is the user's own choice, the profile's `harness.<name>.isolated`, and `dispatch` applies it for you.
+**Each role runs in its vendor's own harness with the user's customizations — never isolate it.** Codex roles keep the user's config, hooks, MCP servers, skills and `AGENTS.md`. The one exception is the user's own choice, the profile's `harness.<name>.isolated`, and `dispatch` applies it for you.
 
 ## Tools
 
 The catherd MCP tools ship with this plugin. They appear as `mcp__plugin_catherd_catherd__<name>`. If they are deferred, load them all with one ToolSearch call at the start, together with `PushNotification`.
 
-| Tool                                                             | Use                                                                                                                                                                           |
-| ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `run_start(repo, title, a_lines)`                                | Once per project. Returns `run`, the id every other call takes, and `dir`, the run folder `R`                                                                                 |
-| `route(run, lane_file?, role?)`                                  | A lane's rung, decided by Jev from its lane file; or, without a lane file, a role's rung from the profile. Returns `rung`, `ladder`, `backend`, and `agent` for a Claude rung |
-| `preflight(run)`                                                 | Runs each lane's fast check once, on the base tree, behind the machine-wide lock. Call it once every lane file exists, before dispatching any of them                         |
-| `dispatch(run, role, name, brief, rung, thread?, lane?, next?)`  | Runs one Codex or opencode role and returns its `record` and `hints`                                                                                                          |
-| `climb(run, lane, reason, evidence?)`                            | The lane's next rung, or `top: true`                                                                                                                                          |
-| `ask(run, question, state)`                                      | Jev's `finding` or `same-defect` answer                                                                                                                                       |
-| `land(run, milestone, what, commit, evidence, next, learned?)`   | A landed milestone's ledger row, and `state.md`. `learned` appends to this repo's `knowledge.md`                                                                              |
-| `read_knowledge(repo)`                                           | What past runs of this repo learned. The dossier brief reads it                                                                                                               |
-| `write_run_file(run, path, content)`, `read_run_file(run, path)` | Files in `R`. Never your own Write or Read tools there: `R` is outside the repo                                                                                               |
-| `result(run, name)`                                              | A role's capped reply and its record                                                                                                                                          |
-| `status(run?)`                                                   | One screen: the `state.md` tail, live roles with their age, totals, Jev fallbacks, the harness cost, the run's budget spend                                                   |
-| `set_next(run, next)`                                            | The next step, when you pause or the plan changes                                                                                                                             |
-| `runs_summary(filter)`                                           | Time, tokens, refusals and climbs per role and rung, and the harness cost, for the report                                                                                     |
-| `profile_get()`                                                  | The active profile: enabled roles, and the moments to push                                                                                                                    |
+| Tool                                                                                             | Use                                                                                                                                                                 |
+| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `status(run?)`                                                                                   | First, and whenever the user asks where it stands: `version`, then per run the `state.md` tail, live roles, totals, Claude subagents, budget, milestones            |
+| `run_start(repo, title, a_lines)`                                                                | Once per project. Returns `run`, the id every other call takes, and `dir`, the run folder `R`                                                                       |
+| `route(run, lane_file?, role?)`                                                                  | A lane's rung (from Jev, else the lane file's `Kind:`/`Difficulty:`, else the profile), or a role's rung. Returns `rung`, `ladder`, `backend`, `agent`              |
+| `preflight(run, confirmed?)`                                                                     | Each lane's fast check once, before any lane runs. Outcomes below                                                                                                   |
+| `dispatch(run, role, name, brief, rung, thread?, lane?, next?)`                                  | Starts one process role (Codex, claude-code or opencode) and returns at launch, in about a second, with `dispatched`; `wait` collects its record                    |
+| `wait(run, names?, all?)`                                                                        | Blocks until a role finishes (every one with `all: true`); returns `records` (each role's `record` and `hints`), `started`, and `running`: what is still to collect |
+| `cancel(run, name)`                                                                              | Stops a live role and returns its record, `cancelled`, and `hints`                                                                                                  |
+| `record_agent_run(run, name, role, rung, total_tokens, duration_ms?, cost_usd?, status?, lane?)` | After every Claude subagent: what its Agent result reported. The budget counts it; `lane` counts its time toward that lane's kind                                   |
+| `climb(run, lane, reason, evidence?, env?)`                                                      | The lane's next rung, with its `backend` and `agent`, or `top: true`. `env: true` when the environment, not the rung, caused it                                     |
+| `ask(run, question, state)`                                                                      | Jev's `finding` or `same-defect` answer                                                                                                                             |
+| `land(run, milestone, what, commit, evidence, next, learned?)`                                   | A landed milestone's ledger row, with the minutes it took, and `state.md`. `learned` appends to this repo's `knowledge.md`                                          |
+| `read_knowledge(repo)`                                                                           | What past runs of this repo learned. The dossier brief reads it                                                                                                     |
+| `write_run_file(run, path, content)`, `read_run_file(run, path)`                                 | Files in `R`. Never your own Write or Read tools there: `R` is outside the repo                                                                                     |
+| `result(run, name)`                                                                              | A role's latest reply, capped, and its record                                                                                                                       |
+| `set_next(run, next)`                                                                            | The next step, when you pause or the plan changes. Returns `state` and, when git fails, `hints`                                                                     |
+| `runs_summary(run?, repo?, role?, since_days?)`                                                  | Time, tokens, refusals and climbs per role and rung, the Claude subagent runs, and the harness cost, for the report                                                 |
+| `profile_get(repo?)`                                                                             | The profile this repo runs on: each role's access, rungs and enforcement, failover, budget, timeouts, and the moments to push                                       |
+
+**A tool returns `hints` when it has any:** one line each, on what to do next. Read them before you move on.
+
+**Every error is `{ code, message, fix }`.** Read the code, act on the fix, and never retry the same call blindly:
+
+- `E_ADMIT_OVERLAP`: the lane shares an owned path with a running lane. Dispatch it when that one returns.
+- `E_ADMIT_DUPLICATE`: that role name is already running. Wait for it, or `cancel` it.
+- `E_ADMIT_RUNG`: the rung is not on that role's ladder, it is a `claude:` rung, or the profile turns the role off. Use the rung `route` returned; run a `claude:` rung as its agent; skip a role that is off.
+- `E_RUN_BUDGET`: the run's budget is spent (a soft cap: roles already running finish). Pause, report and push.
+- `E_BACKEND_MISSING`, `E_BACKEND_NOT_LOGGED_IN`, `E_BACKEND_TOO_OLD`: tell the user the `fix`, word for word, then pause.
 
 ## Roles
 
@@ -63,27 +78,29 @@ The catherd MCP tools ship with this plugin. They appear as `mcp__plugin_catherd
 | writer      | `dispatch(run, "writer", "writer-<m>", brief, rung)`                            | README, docs, changelog, MR body                        |
 | researcher  | `dispatch(run, "researcher", "researcher-<n>", brief, rung)`                    | The dossier, or one factual question about the code     |
 
-- **Every rung comes from `route`,** never from you. The table shows the usual backend; the profile decides. When `route` returns `backend: "claude"`, run that role with `Agent(subagent_type: <agent>)`, with the brief and the run id as its prompt; otherwise `dispatch` it. `dispatch` refuses a Claude rung and names the agent.
+- **Every rung comes from `route`,** never from you. A rung names its backend: `backend:model#effort`, like `codex:gpt-6-sol#high` or `claude:claude-opus-5-5#high`. The table shows the usual backend; the profile decides. When `route` returns `backend: "claude"`, run that role with `Agent(subagent_type: <agent>)`, with the brief and the run id as its prompt; otherwise `dispatch` it. `dispatch` refuses a Claude rung and names the agent.
+- **After every Claude subagent returns,** call `record_agent_run(run, name, role, rung, total_tokens, duration_ms, lane)` with the numbers its Agent result reports (`lane` when it worked one). Claude runs cost the budget too, and catherd cannot see them otherwise.
 - **A role the profile disables** (`profile_get`; every role but the worker can be off) is skipped, and the report says so.
-- **Sandbox:** catherd sets it per role. Worker, artist and writer write in the repo only; reviewer, researcher and architect read; verifier and UI reviewer get full access for Docker, a browser, gate logs and screenshots.
+- **Access:** catherd sets it per role. Worker, artist and writer write in the repo only; reviewer, researcher and architect read; verifier and UI reviewer get full access for Docker, a browser, gate logs and screenshots.
+- **A read-only role on claude-code or opencode has no shell** (no `git diff`, no `ls`), so its brief must list the files to read.
 - **Cheap rungs hide broken tools.** The lowest Track A rung stays silent about a broken tool about a third of the time, so every lane on it is checked by your fast check, not by its own word.
 - **Claude agents:**
   - catherd generates them from the profile, and Claude Code registers them at session start.
   - Pass no `model` to those Agent calls. Never let `Plan`, `general-purpose` or `Explore` stand in.
   - `Agent type … not found` means the profile changed after this session started: tell the user to open a new session.
   - If the model needs a newer Claude Code, stop and tell the user to upgrade Claude Code. Never pass a `model` to get past it.
-- **The record:** `R/roles/<name>.out` is the latest reply; earlier rounds are kept as `<name>.r<k>.*`. `R/runs.jsonl` holds one record per run (role, rung, status, thread, seconds, tokens). It is the token and time record: never keep your own.
+- **The record:** each dispatch has its own folder, `R/roles/<name>/<dispatchId>/` (brief, reply, events, stderr); `result(run, name)` reads the latest. `R/runs.jsonl` holds one record per dispatch (role, rung, status, thread, seconds, tokens, the owned files it changed and any it should not have). `R/agents.jsonl` holds the Claude subagent runs you reported. Together they are the token and time record: never keep your own.
 
 ## Effort: the ladder, decided by Jev
 
 A lane starts on the lowest rung that can do it, and climbs one rung when it shows it cannot. The ladders come from the profile and the catalog. With the default profile:
 
-| Track | Lanes                                                                         | Rungs, low to high                                                            |
-| ----- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
-| A     | `copy` or `build`: an existing pattern, a clear fast check                    | `gpt-6-luna#high` → `gpt-6-sol#medium` → `gpt-6-sol#high` → `gpt-6-sol#xhigh` |
-| B     | `logic` or `hard`, or `terminal` work: state, concurrency, ops, unclear cause | `gpt-6-sol#medium` → `gpt-6-sol#high` → `gpt-6-sol#xhigh`                     |
+| Track | Lanes                                                                         | Rungs, low to high                                                                                    |
+| ----- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| A     | `copy` or `build`: an existing pattern, a clear fast check                    | `codex:gpt-6-luna#high` → `codex:gpt-6-sol#medium` → `codex:gpt-6-sol#high` → `codex:gpt-6-sol#xhigh` |
+| B     | `logic` or `hard`, or `terminal` work: state, concurrency, ops, unclear cause | `codex:gpt-6-sol#medium` → `codex:gpt-6-sol#high` → `codex:gpt-6-sol#xhigh`                           |
 
-**Jev picks the start.** Jev (TypeSafe) is a decision model: it answers a fixed question with calibrated confidence in about three seconds, for a fraction of a cent. On low confidence, or with no Jev, the tools return the profile's default (`source: "default"`), so the run never waits on it. Every call is logged to `R/jev.jsonl`.
+**Jev picks the start, when the user has it.** Jev (TypeSafe) is a decision model: it answers a fixed set of questions about the lane with calibrated probabilities, usually in well under a second, for a fraction of a cent; `route` gives up on it after 25 s. It is optional. When its probabilities do not settle the track, or with no Jev key, `route` uses the lane file's `Kind:` and `Difficulty:` lines (`source: "lane"`), else the profile's default (`source: "default"`), so the run never waits on it. When Jev is sure of the kind but not the difficulty, `route` keeps Jev's kind and takes the difficulty from the lane's `Difficulty:` line, else the role's default (`source: "jev-kind"`). Every Jev call is logged to `R/jev.jsonl`, without the lane's text.
 
 | When                                          | Call                                                                          | On the answer                               |
 | --------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------- |
@@ -91,16 +108,18 @@ A lane starts on the lowest rung that can do it, and climbs one rung when it sho
 | A review finding that may be the plan's fault | `ask(run, "finding", { lane_file: "lanes/Mx.Ly.md", finding: "<the line>" })` | `design` → the architect. Else → the worker |
 | A finding back after its fix round            | `ask(run, "same-defect", { before: "<old line>", after: "<new line>" })`      | `yes` → climb one rung                      |
 
-**Climb one rung** with `climb(run, lane, reason, evidence)`, then dispatch the lane at the new rung on a fresh thread whose brief is the lane file plus the path of the failing evidence, when:
+**Climb one rung** with `climb(run, lane, reason, evidence)` (add `env: true` when a missing service, a broken tool or a usage limit caused it, not the rung), then dispatch the lane at the new rung on a fresh thread whose brief is the lane file plus the path of the failing evidence, when:
 
 - your fast check fails twice on that lane (`check-failed-twice`);
 - the lane gets a BLOCKER (`blocker`), or Jev calls a returning finding the same defect (`same-defect`);
-- the reply says `STATUS: refused` or `blocked`, or the run exits 0 while the lane's owned files are unchanged: that is a refusal, whatever the reply says (`refused`, `blocked`, `unchanged`). `dispatch` flags each of these in its `hints` as `climb: <reason>`.
+- the reply says `STATUS: refused` or `blocked`, or the run exits 0 while the lane's owned files are unchanged: that is a refusal, whatever the reply says (`refused`, `blocked`, `unchanged`). `wait` flags each of these in the record's `hints` as `climb: <reason>`.
+
+A usage limit is not a climb. When the profile names a stand-in for that rung, `wait` has already started the role on it, on a fresh thread: the limited record's first hint says `limit: … failed over to <rung>`, the stand-in is in `started` and its name stays in `running`, and a later `wait` returns its record. With no stand-in, the hint is `limit: …` and the run is paused.
 
 A failure on the top rung (`top: true`) goes to the architect when Jev calls it design, else to the report as open.
 
 - Jev decides which model does the work. It never decides that the work is done: only a check, the reviewer or the verifier does.
-- `R/routes.jsonl` records each lane's rung and every climb with its reason.
+- `R/routes.jsonl` records each lane's rung and every climb with its reason; `R/outcomes.jsonl` gets one row per lane when its milestone lands or it fails its top rung; a lane written again (landed after failing its top rung, or re-landed) keeps its rows, and the last row per lane wins.
 - Never put a secret or a key into an `ask` state. Keep the state short and in English.
 
 ## Threads
@@ -115,7 +134,7 @@ A resumed thread replays its whole history on every tool call. In the first real
 
 Your context is re-read on every turn, and it is the run's most expensive token. In the first real run you were 68% of the Claude spend: 269 turns at about 220k tokens each.
 
-- **One message per transition.** Independent tool calls (a `land`, the next lanes' dispatches, a `route`) go in the same message.
+- **One message per transition.** Independent tool calls (a `land`, the next lanes' dispatches, a `route`) go in the same message. They run one after another, and each `dispatch` returns in about a second; the `wait` comes after them.
 - **Read little, and read it narrowly.**
   - From the architect, read its short reply. The plan lives in `plan.md` and the lane files; read a section with `read_run_file` only when a decision needs it.
   - From a role, read its record and its capped reply.
@@ -125,7 +144,14 @@ Your context is re-read on every turn, and it is the run's most expensive token.
 
 ## Waiting
 
-Call `dispatch` from your main thread, never from a subagent: a subagent's MCP call never backgrounds, so it would hold that subagent for the whole run. Launch every independent role in the same message. Each dispatch backgrounds by itself after two minutes, and its result arrives as a notification that wakes you. Then end your turn with one status line. Never `sleep` and never poll.
+Call `dispatch` and `wait` from your main thread only, never from a subagent: a subagent's MCP call never backgrounds, so a `wait` there would hold that subagent for the whole run.
+
+- **Dispatch every independent role one after another.** Each `dispatch` returns in about a second, once its role has started, so they all run side by side.
+- **Then call `wait(run)`.** It returns once one of them finishes, and its result wakes you. After two minutes Claude Code backgrounds it: end your turn with one status line, and its notification wakes you.
+- **Act on each record it returns,** dispatch what follows, and call `wait(run)` again while its `running` is not empty. `running` names every role whose record no `wait` has returned yet, still running or already finished; each record comes back once.
+- **A single role is `dispatch`, then `wait`.**
+
+Never `sleep` and never poll.
 
 **When the user asks where it stands,** call `status(run)` once and answer from it.
 
@@ -145,43 +171,56 @@ Nothing else pushes: a phone that buzzes for progress teaches the user to ignore
 - **`lanes/Mx.Ly.md`:** one file per lane, the only plan a worker reads. Its second line, `Owns: <paths>`, is what `dispatch` uses to refuse a lane that shares a file with a running one, and to spot a refusal.
 - **`ledger.md`:** one row per landed piece, appended by `land`. Never rewritten.
 - **`state.md`:** rewritten by the server at every dispatch, climb and landing, so a fresh session resumes from it alone: HEAD, the dirty files and their owners, each running role with its brief, thread and rung, the last check, and the next step on the last line.
-- **`runs.jsonl`, `jev.jsonl`, `routes.jsonl`, `harness.jsonl`:** the record.
-- **`roles/`** (briefs and replies) and **`shots/`** (screenshots).
-- **`<data>/<repo-slug>/knowledge.md`** (one level up, per repo, not per run): what past runs learned. `land`'s `learned` appends to it; `read_knowledge` reads it.
+- **`runs.jsonl`, `agents.jsonl`, `jev.jsonl`, `routes.jsonl`, `outcomes.jsonl`, `harness.jsonl`:** the record.
+- **`roles/<name>/<dispatchId>/`** (each dispatch's brief, reply, events and stderr) and **`shots/`** (screenshots).
+- **The repo's `knowledge.md`** (beside the runs, per repo, not per run): what past runs learned. `land`'s `learned` appends to it; `read_knowledge` reads it.
+
+**Pause** (on the user's word, a usage limit, or `E_RUN_BUDGET`): dispatch nothing new, `cancel(run, name)` each live role the user wants stopped, and bring down only this run's stack. Leave the tree as it is, call `set_next(run, "paused: <why>; resume with <step>")`, then stop. On a usage limit, `wait` has already written the pause.
 
-**Pause** (on the user's word, or a usage limit): dispatch nothing new, and bring down only this run's stack. Leave the tree as it is, call `set_next(run, "paused: <why>; resume with <step>")`, then stop. On a usage limit, `dispatch` has already written the pause.
+**Cancel** a role with `cancel(run, name)` when the user asks, or when a role is plainly stuck on work you no longer need. It returns the role's record, `cancelled`, and no later `wait` returns it again; a `wait` already in flight may return it too, and `cancel` then says so in its `hints`.
 
-**Resume:** `status()` names the run, and `status(run)` shows it. Check HEAD and the dirty files against its `state.md`. Continue each role on its own thread with `dispatch(…, thread, brief: "<where it stopped>")`.
+**Resume:** `status()` names the run, and `status(run)` shows it. Check HEAD and the dirty files against its `state.md`. Before dispatching anything, call `wait(run)`, again while its `running` is not empty, to collect the roles the last session left running or unread (`dispatch` refuses a name that is still running). Continue each role on its own thread with `dispatch(…, thread, brief: "<where it stopped>")`.
 
 ## The sequence
 
 **Once per project:**
 
 1. **A-lines.** Write the request as numbered, observable lines `A1…An`. Ask the user every open product question now; after this point, run without them. Then `run_start(repo, title, a_lines)`.
+   - **Plan in hand:** when the request names a plan the user already has, keep it as an A-line, `plan: <path>[, <path>…]`. The run then skips the dossier, and the architect translates that plan instead of designing one (step 3).
 2. **Dossier.** One researcher, `researcher-dossier`, maps the code the A-lines touch. Its brief asks for, with `file:line` everywhere:
    - what past runs of this repo learned (`read_knowledge(repo)`), so it maps only what changed since then;
    - the files and folders involved, one line each on what they hold;
    - the existing patterns the work should copy, by path;
    - the build, test and run commands, with how long the full suite takes;
+   - the lint and type-check commands, and how to scope each to one package;
    - the symbols the change will call or alter, with their signatures;
    - the repo's rules (`CLAUDE.md`, `AGENTS.md`, conventions) that bind this work;
    - risks: shared files, generated code, slow or flaky tests.
 
-   It may run to 200 lines; the 15-line cap does not apply to it. Its reply is `R/roles/researcher-dossier.out`. A Claude researcher writes it to `R/dossier.md` with `write_run_file` instead.
+   It may run to 200 lines; the 15-line cap does not apply to it. Its reply is `result(run, "researcher-dossier")`, at the record's `replyPath`. A Claude researcher writes it to `R/dossier.md` with `write_run_file` instead.
 
-3. **Architect,** once, with the A-lines, the run id and the dossier's path. It reads the dossier first, writes `plan.md` and every `lanes/Mx.Ly.md` itself with `write_run_file`, and replies with a short list of milestones and lanes. Each lane names its owned files and its **fast check** (targeted tests, seconds to a minute or two); each milestone names its **full check** (the whole suite).
+3. **Architect,** once, with the A-lines, the run id and the dossier's path. It reads the dossier first, writes `plan.md` and every `lanes/Mx.Ly.md` itself with `write_run_file`, and replies with a short list of milestones and lanes. Each lane names its owned files and its **fast check**: its targeted tests plus the linter, and the type check when the repo has one, scoped to the lane's owned packages (seconds to a minute or two). Each milestone names its **full check** (the whole suite).
    - A full check slower than about five minutes is a problem to solve, not to live with. The architect makes speeding it up (parallel tests, a shared fixture) an early lane.
-   - **No dossier and no architect** for a polish or fix run (a list of known defects or tweaks to code that exists) or a single mechanical task. You write the lane files yourself with `write_run_file`, straight from the A-lines: one lane per cluster of defects that share files, with owned files found by `grep -n`, and the three header lines the architect writes (`# Mx.Ly — …`, `Owns: …`, `Fast check: …`).
-4. **Route and preflight.** `route(run, "lanes/Mx.Ly.md")` for every lane, all in one message. Then, once every lane file exists, `preflight(run)` once, before dispatching any lane: a lane whose fast check cannot even start blocks the run with its output until fixed.
+   - Every lane file starts with these lines: `# Mx.Ly — <title>`, `Owns: <paths>` (repo-relative, a trailing `/` for a folder, never a glob), `Fast check: <command>`, `Kind: repo_code|terminal|ui|prose|research` and `Difficulty: copy|build|logic|hard`.
+   - **Plan in hand** (a `plan:` A-line): no dossier. Brief the architect with the A-lines, the run id and the plan's paths, to translate, not design: each plan task becomes lanes (`Owns:`, `Fast check:`, `Kind:`, `Difficulty:`), each MR or phase a milestone with its full check. It copies the plan's decisions into `plan.md` and the lane files, redesigns only what the plan leaves undecided, and stays the target for `design` findings.
+   - **No dossier and no architect** for a polish or fix run (a list of known defects or tweaks to code that exists) or a single mechanical task. You write the lane files yourself with `write_run_file`, straight from the A-lines: one lane per cluster of defects that share files, with owned files found by `grep -n`, and the same header lines.
+4. **Route and preflight.** `route(run, "lanes/Mx.Ly.md")` for every lane, one call per lane; each may wait up to 25 s on Jev. Then, once every lane file exists, `preflight(run)` once, before dispatching any lane. Each lane comes back as one of:
+   - `pass`: the check already passes on the base tree;
+   - `fails-as-expected`: it runs and fails, because the lane has not been done yet;
+   - `skipped`: it checks a file the lane creates;
+   - `cannot-start`: it could not even run (a missing command, exit 126 or 127, a 120 s timeout, or no `Fast check:` line). Only this blocks: fix that lane's check, or ask the architect to, and run `preflight` again.
+
+   When it returns `needsConfirmation: true`, the profile wants the user to see the commands first: show them the `commands`, and on their yes call `preflight(run, confirmed: true)`.
 
 **Per milestone:**
 
-5. **Lanes.** Launch every lane of the milestone in one message, each at its rung: workers, the artist, and a researcher if needed. A worker's brief points at its lane file, and `dispatch` gets its `lane`. A worker runs its own fast check until it passes.
+5. **Lanes.** Dispatch every lane of the milestone, one after another, each at its rung, then `wait(run)`: workers, the artist, and a researcher if needed. A worker's brief points at its lane file, and `dispatch` gets its `lane`. A worker runs its own fast check until it passes.
    - When a worker returns, check its STATUS line, its `changedOwned` and its `hints`, then run its fast check yourself once. A fail goes back to the same thread with the failing output's path; a second fail climbs a rung.
+   - A `violation: <paths>` hint means the role wrote outside its lane. Send those paths to the reviewer with the milestone; a lane that needs them gets an `Owns:` delta from the architect.
 6. **writer,** when the milestone changes docs. It starts once the workers are done.
 7. **reviewer,** once, over the whole milestone diff on a frozen tree.
    - **UI pass,** when the milestone touched a screen. List the changed files (`git diff --name-only <milestone base>`), map them to the screens that render them, and brief the UI reviewer on those screens only. You start the app first.
-8. **One fix round.** Send each lane's findings, verbatim, to its own worker thread, at its rung. A BLOCKER climbs a rung instead, on a fresh thread. All lanes go at once. Then resume the same reviewer thread, and it re-checks only the BLOCKER and BUG lines.
+8. **One fix round.** Send each lane's findings, verbatim, to its own worker thread, at its rung. A BLOCKER climbs a rung instead, on a fresh thread. Dispatch every lane's fix, then `wait`. Then resume the same reviewer thread, and it re-checks only the BLOCKER and BUG lines.
    - Before routing a finding that questions the plan, `ask(run, "finding", …)`. `design` goes to the architect (`SendMessage` to the same agent), and its delta rewrites the lane files.
    - A finding that comes back: `ask(run, "same-defect", …)`. `yes` gets one climb and one re-check of that line. Anything still open goes to the report, not into another round.
 9. **verifier,** with the milestone's A-lines and the **full check**, on a frozen tree. A full check that starts while a role still edits proves nothing, and it has to run again. Never give it a worker's reply.
@@ -206,8 +245,8 @@ Then report to the user, in their language, and push if `notify` has `finish`:
 - the verdict per milestone;
 - the commits;
 - one line per role run, with its rung;
-- the time and token sums per backend and per rung, and the climbs with their reasons (`runs_summary({ run })`), the Claude subagent runs, and the Jev decisions with how many fell back (`status(run)`);
-- the harness line from `runs_summary`: what the user's Codex and opencode customizations cost per run, so they can judge the isolation toggle (`/catherd-setup` offers it);
+- the time and token sums per backend and per rung, and the climbs with their reasons (`runs_summary({ run })`), the Claude subagent runs you reported (say they are reported, not measured), and the Jev decisions with how many fell back (`status(run)`);
+- the harness line from `runs_summary`: what the user's claude-code and opencode customizations cost per run, so they can judge the isolation toggle (`/catherd-setup` offers it). Codex reports no per-request input, so it has no harness figure: say so instead of offering one;
 - the run's budget spend (`status(run)`), if the profile set one;
 - what was left open, and why.
 
@@ -215,15 +254,15 @@ Roles never commit. You commit, following the repo's rules.
 
 ## Brief for a role
 
-The brief is the `brief` text you pass to `dispatch` (catherd writes it to `R/roles/<name>.md`, or `<name>.fix.md` for a fix), or the prompt of a Claude role's Agent call, with the run id. It has these parts, in order:
+The brief is the `brief` text you pass to `dispatch` (catherd writes it to the dispatch's own `brief.md` and hands it to the CLI on stdin), or the prompt of a Claude role's Agent call, with the run id. It has these parts, in order:
 
 1. The role and the goal, in one line.
 2. The A-lines this run must meet.
 3. The files it owns, and the files it must not touch. If the repo has a `CLAUDE.md`, add "Read CLAUDE.md first": Codex loads only `AGENTS.md`.
 4. For a worker:
    - "Read `<R>/lanes/Mx.Ly.md`": decisions, signatures, data shapes;
-   - its fast check, to run until it passes;
-   - "Run the full suite only if this brief says so", and "Wrap any full build or full test suite in `bunx catherd-cli@0.2.1 lock -- <command>`": other lanes share the machine.
+   - its fast check (targeted tests, lint and type check), to run until it passes;
+   - "Run the full suite only if this brief says so", and "Wrap any full build or full test suite in `bunx catherd-cli@1.0.0 lock -- <command>`": other lanes share the machine.
 5. For a reviewer: the A-lines and the changed files, with new files read in full. It reports every finding as `BLOCKER|BUG|NIT file:line — problem — fix`, covering:
    - unmet A-lines and edge cases;
    - code or abstractions nobody needs;
@@ -255,16 +294,18 @@ The brief is the `brief` text you pass to `dispatch` (catherd writes it to `R/ro
 
 ## Reading results
 
-- Read the record `dispatch` returns, its `hints`, and the reply (`result(run, name)`), nothing else. Read `roles/<name>.jsonl` or `.err` with `read_run_file` only when `status` is `failed`. Never read a diff or a log yourself: that is the reviewer's and verifier's job, and your context is the run's most expensive token.
+- Read each record `wait` returns, its `hints`, and the reply (`result(run, name)`), nothing else. Read the stderr the `failed: read <path>` hint names, with `read_run_file`, only when `status` is `failed`. Never read a diff or a log yourself: that is the reviewer's and verifier's job, and your context is the run's most expensive token.
 - Exit 0 means the model finished, not that it is right. The STATUS line is the role's claim; `changedOwned` and your fast check are the facts.
 - `failed` comes only from a real turn failure or an exit with no reply; a reconnect mid-run does not count. Read the reply before you retry.
-- `cli-too-old`: tell the user the upgrade command in the record's `error`. `limit`: a usage limit is the user's to fix: pause, report and push that turn.
+- `cli-too-old`: tell the user the upgrade command its `cli-too-old:` hint names. `limit` with no stand-in: a usage limit is the user's to fix: pause, report and push that turn. `timeout`: the role went quiet for the profile's idle minutes, or ran past its wall minutes; resume its thread once with where it stopped, then climb.
+- `thread-heavy`: that thread is spent; its next piece starts fresh.
 
 ## Red flags
 
 | You notice                                                                                                                          | Do instead                                                                                                             |
 | ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| A lane waits on another lane that shares none of its files                                                                          | Launch it now, in the same message                                                                                     |
+| A lane waits on another lane that shares none of its files                                                                          | Dispatch it now, beside the others, then `wait`                                                                        |
+| A role dispatched, then waited on, before the next independent one is dispatched                                                    | Dispatch every independent role first, then one `wait(run)`                                                            |
 | A worker or fix loop runs the full suite to check one change                                                                        | Its fast check. The full check is the verifier's, once per milestone                                                   |
 | A reviewer or verifier runs after each lane                                                                                         | Once per milestone, over the whole milestone                                                                           |
 | A third review round                                                                                                                | One fix round, one climb for a returning defect, one re-check. The rest goes to the report                             |
@@ -275,9 +316,14 @@ The brief is the `brief` text you pass to `dispatch` (catherd writes it to `R/ro
 | A new bug, cleanup, re-run or climb sent with `thread`                                                                              | A fresh thread. Resume only for that piece's own findings at the same rung                                             |
 | One transition spread over several turns (a land, routes, dispatches)                                                               | One message, with every independent call in it                                                                         |
 | A plan, log or test file read whole into your context                                                                               | `read_run_file` for the one section, or `grep -n` then those lines. Or name the path in a brief                        |
-| You copy the architect's plan into `plan.md` yourself                                                                               | The architect writes `plan.md` and the lane files                                                                      |
+| You copy the architect's plan into `plan.md` yourself                                                                               | The architect writes `plan.md` and the lane files. With a plan in hand, it copies the user's plan into them            |
+| A dossier, or an architect designing afresh, with a plan in hand                                                                    | No dossier. Brief the architect to translate the plan, and to design only what it leaves undecided                     |
 | A dossier or an architect for a polish or fix run                                                                                   | Write the lane files from the A-lines yourself                                                                         |
 | A lane file without an `Owns:` line                                                                                                 | Add it: `dispatch` refuses the lane without one                                                                        |
+| A Claude subagent returned and you moved on                                                                                         | `record_agent_run` with its `total_tokens` and `duration_ms` first                                                     |
+| A rung written as `model#effort`                                                                                                    | `backend:model#effort`, exactly as `route` returned it                                                                 |
+| `dispatch` retried after an `E_*` error without doing what its `fix` says                                                           | Do the `fix`, or pause and tell the user                                                                               |
+| A `cannot-start` preflight lane dispatched anyway                                                                                   | Fix its fast check first, and run `preflight` again                                                                    |
 | You pick a rung by feel                                                                                                             | `route`. Its default covers the case where Jev is unsure or down                                                       |
 | Jev's answer taken as proof a lane is done                                                                                          | Jev picks who works. Checks, the reviewer and the verifier decide done                                                 |
 | A reply from the lowest Track A rung trusted without your fast check                                                                | Run it. Cheap rungs hide broken tools                                                                                  |
@@ -293,7 +339,7 @@ The brief is the `brief` text you pass to `dispatch` (catherd writes it to `R/ro
 | A push for progress that is not a landed milestone, the finish or a block                                                           | No push. `status(run)` answers when the user asks                                                                      |
 | Your own decision changes behavior that already exists and no A-line asked for it (e.g. re-numbering `list` to match a new command) | Pick the option that keeps existing behavior, and fit the new code to it                                               |
 | `Agent(subagent_type: "Plan", model: "opus")` for the architect                                                                     | The `agent` that `route(run, role: "architect")` returned, with no model                                               |
-| `dispatch` called from a subagent                                                                                                   | The main thread. A subagent's MCP call never backgrounds                                                               |
+| `dispatch` or `wait` called from a subagent                                                                                         | The main thread. A subagent's MCP call never backgrounds                                                               |
 | `codex exec` or `opencode run` called by hand                                                                                       | Always `dispatch`: it records the run, keeps `state.md` true and guards the lanes                                      |
 | You isolate a role's harness yourself, or tell a role to ignore the user's config                                                   | Never. Only the profile's `harness.<name>.isolated`, which the user sets                                               |
 | The architect's plan contains function bodies                                                                                       | Ask for decisions and signatures. The worker writes the code                                                           |

package/plugin/skills/catherd-setup/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: catherd-setup
-description: Use when the user wants to tune catherd — which models and efforts each role may use, cost versus speed, which subscriptions to lean on, harness isolation — /catherd-setup, "set up catherd", "tune my catherd profile". Not for running a task; that is the catherd skill.
+description: Use when the user wants to tune catherd — which models and efforts each role may use, how much each role may touch, cost versus speed, which subscriptions to lean on, failover, budget, harness isolation — /catherd-setup, "set up catherd", "tune my catherd profile". Not for running a task; that is the catherd skill.
 ---
 
 # catherd setup
 
-You tune the user's catherd profile in conversation. A profile says, per role, which models and efforts it may run on; whether routing favours cost or speed; whether each vendor harness runs with the user's customizations or isolated; how many heavy commands run at once; and when to push.
+You tune the user's catherd profile in conversation. A profile says, per role, which rungs it may run on (`backend:model#effort`, in ladder order) and what it may touch (its access mode); whether routing favours cost or speed; how each backend is billed; whether Jev picks the rung; which rung stands in when a backend hits its usage limit; the run budget and timeouts; whether each vendor harness runs with the user's customizations or isolated; how many heavy commands run at once; and when to push.
 
-**You never edit a file by hand.** `profile_set` is the only writer, so this conversation and the TUI (`bunx catherd-cli`) cannot drift apart.
+**You never edit a file by hand.** `profile_set` is the only writer, so this conversation, the `catherd profile` commands and the TUI cannot drift apart.
 
 ## Rules
 
@@ -21,45 +21,55 @@ You tune the user's catherd profile in conversation. A profile says, per role, w
 Ask these, one at a time, each with its recommended answer:
 
 1. **Their order of speed, cost and quality.** Recommend cost first, the default `objective`: catherd climbs a rung when a cheap one cannot do the work, so the lanes that need speed get it anyway, and the reviewer and the verifier hold quality either way.
-2. **The subscriptions they hold:** a ChatGPT plan (Codex), a Claude plan, OpenRouter or other opencode credit. Recommend leaning on subscriptions before metered spend, and on Claude last among the workers, since it spends the same quota as this conversation.
+2. **The subscriptions they hold:** a ChatGPT plan (Codex), a Claude plan, OpenCode Go, Zen credit or API keys. They set `billing` per key (`codex`, `claude`, `claude-code`, `opencode-go`, `opencode`): `chatgpt-plan`, `claude-plan`, `subscription` or `metered`. Recommend leaning on subscriptions before metered spend, and on Claude last among the workers, since it spends the same quota as this conversation.
 3. **The kind of work they orchestrate:** front-end screens, back-end services, terminal and ops work, docs. Recommend from their own runs when `runs_summary` has any.
 
 ## 2. Read the facts before proposing
 
 In one message, call:
 
-- `catalog_query({ role: "<role>" })` for each role you will discuss: what their installed backends can run, with capabilities and scores. A model whose `installed` is false is not offered;
-- `runs_summary({})`: how each rung has done on their own runs (runs, refusals, climbs, time) and the harness cost line;
-- `profile_get()`: where they stand now.
+- `catalog_query({ role: "<role>" })` for each role you will discuss: the models that can fill it, their scored rungs, any "treat like", each rung's cost under their billing, and whether their backend's last listing offers it (`listed: false` means their account does not);
+- `runs_summary({})`: how each rung has done on their own runs (runs, refusals, climbs, time) and the harness cost line, for claude-code and opencode only: Codex reports no per-request input, so it has no harness figure;
+- `profile_get({ repo })`: where they stand now, with each role's `access` and `enforcement`. Pass the user's repo: without a name, the profile tools act on the profile this repo runs on (the one bound to it, else the active one), which `here` names; `active` is the global active profile.
 
 ## 3. Propose one decision at a time
 
 Go through these in order, and skip any the user does not care about:
 
-1. `objective`;
-2. the worker's ladder: its enabled models and efforts, and its `defaultRung`;
-3. the reviewer and the UI reviewer;
-4. the architect and the verifier, which spend Claude quota;
-5. the writer, the researcher and the artist;
-6. harness isolation, per harness (below);
-7. `lock.heavy` and `notify`.
+1. `objective`, and `jev.use` (`auto` asks Jev when a key exists; `off` routes on each lane's `Kind:` and `Difficulty:` lines);
+2. `billing`, from step 1;
+3. the worker's `rungs` and its `defaultRung`;
+4. the reviewer and the UI reviewer;
+5. the architect and the verifier, which spend Claude quota. A `claude:` rung runs as a native subagent in this session; a `claude-code:` rung runs headless through `dispatch`. Recommend native for these two;
+6. the writer, the researcher and the artist;
+7. each role's `access` (below);
+8. `failover` (below);
+9. `budget`, `timeouts` and `preflight.confirm`;
+10. harness isolation, per harness (below);
+11. `lock.heavy` and `notify`.
 
 Each proposal has three parts: the change, a worked example from their facts, and the tradeoff in their terms. For instance: "Luna high on build lanes: about 5 min slower than Sol medium, no Claude quota, climbs on 1 in 5 of your runs so far."
 
-- Offer only the models `catalog_query` lists as capable for the role.
-- An unscored model can be enabled only once it has a "treat like <scored model#effort>". That lives in the catalog override, which the TUI edits: send the user to `bunx catherd-cli` for it, then come back.
+- Offer only the rungs `catalog_query` lists as capable for the role, written `backend:model#effort`.
+- An unscored model can be enabled only once it has a "treat like <scored rung>". There is no tool for that: give the user the command to run in a terminal, `catherd catalog treat-like <rung> <scored rung>`, then come back and propose again.
 
-**Harness isolation.** For each harness they use (`codex`, `opencode`), offer `harness.<name>.isolated` with its harness line from `runs_summary` and this tradeoff: "native keeps your hooks, skills and AGENTS.md; isolated saves ~N tokens per run, but the role loses them." Recommend native. When they have no isolated runs yet, the number is the median first-turn input of their native runs: say that isolation would save some part of it, not all of it. When there are no runs at all, say there is no number yet, and recommend native until there is.
+**Access.** Each role runs `read-only`, `workspace-write` or `full`. The defaults: architect, reviewer and researcher `read-only`; worker, writer and artist `workspace-write`; verifier and UI reviewer `full`. `profile_get` says per role whether its backend holds it to that mode (`enforced`: Codex's sandbox) or only asks (`advisory`: claude-code, opencode and native subagents, where the model can still reach past it). Recommend the defaults; when the user wants a role tighter or looser, say what it can no longer do (a read-only reviewer on claude-code or opencode has no shell, so it cannot run `git diff`) and that `profile_validate` will warn about it.
+
+**Failover.** `failover` maps a rung to its stand-in when that rung's backend hits a usage limit. A stand-in must be scored and on another quota (Go and Zen bill apart; native `claude` and `claude-code` share the Claude plan). The default profile fails each Codex rung over to OpenCode Go, marked inferred: Go's GPT-6 Luna for Luna, and Kimi K3, treated like Sol medium, for Sol. Say so, and offer to change it when they have no Go subscription. `null` removes an entry.
+
+**Budget and timeouts.** `budget` (`minutes`, `tokens`, `usd`) is a soft cap: from 80 % routing starts at the cheapest rung that clears the bar, and at 100 % no new role starts. `timeouts.idleMin` (15) stops a role that has gone quiet, `timeouts.wallMin` (90) one that runs too long. `preflight.confirm: true` makes `preflight` show its commands for the user to approve first.
+
+**Harness isolation.** For each harness they use (`codex`, `claude-code`, `opencode`), offer `harness.<name>.isolated` with its harness line from `runs_summary` (Codex has none: it reports no per-request input, so say there is no figure for it instead of offering one) and this tradeoff: "native keeps your hooks, skills and AGENTS.md; isolated saves ~N tokens per run, but the role loses them." Recommend native. When they have no isolated runs yet, the number is the median first-turn input of their native runs: say that isolation would save some part of it, not all of it. When there are no runs at all, say there is no number yet, and recommend native until there is.
 
 ## 4. Write it
 
-- Call `profile_set({ patch })` with only what changed; pass `name` only to edit a profile other than the active one. It validates before it writes:
-  - `saved: false` comes with `errors`. Explain each in their terms, fix the patch, and propose again.
-  - `saved: true` comes with the `diff`. Read it back to the user, one line per change.
-- Then call `profile_validate()`. It checks that every enabled role has a capable model, that the worker's ladder is non-empty for every kind, and that no unscored model is enabled without its "treat like".
+- Call `profile_set({ repo, patch })` with only what changed; pass `name` only to edit a profile other than the one this repo runs on (a name that does not exist yet starts a new profile from the default one). Lists (`rungs`, `notify`) replace, maps (`billing`, `failover`, `budget`) merge, and `null` removes a key. A key it does not know is refused with `E_INPUT_INVALID`. It validates before it writes:
+  - `saved: false` comes with `errors`, each with a `path`, a `message` and often a `fix`. Explain each in their terms, fix the patch, and propose again.
+  - `saved: true` comes with the `diff` (`path`, `before`, `after`) and any `warnings`. Read the diff back to the user, one line per change, and each warning with it.
+- Then call `profile_validate({ repo })`. `errors` block a save: the worker disabled, an enabled role with no usable rung, an unscored rung without a "treat like", a failover stand-in unscored or on the same quota, a backend catherd cannot run. `warnings` do not: an access mode other than the role's default, a model the backend's listing lacks, a stand-in that never runs.
 
 ## 5. Say what applies when
 
-- Codex and opencode changes, isolation included, apply at the next dispatch, even in a run already under way.
-- A Claude agent listed in `new_session_needed_for` applies from the next Claude Code session: Claude Code registers agent files when a session starts. Other Claude changes apply now.
-- Editing a profile that is not the active one writes its agent files but links none; they apply once it becomes active.
+- Codex, claude-code and opencode changes, access and isolation included, apply at the next dispatch, even in a run already under way.
+- An agent listed in `newSessionNeededFor` applies from the next Claude Code session: Claude Code reads agent files when a session starts. Other Claude changes apply now.
+- Editing a profile that is not the active one writes its agent files but links none; they apply once it becomes active (`catherd profile use <name>`), or in a repo it is bound to (`catherd profile use <name> --repo`).

package/src/adapters/all.ts

@@ -0,0 +1,8 @@
+import { claudeCodeAdapter } from "./claude-code/index.ts";
+import { codexAdapter } from "./codex/index.ts";
+import { opencodeAdapter } from "./opencode/index.ts";
+import { registerAdapter } from "./registry.ts";
+
+registerAdapter(codexAdapter);
+registerAdapter(claudeCodeAdapter);
+registerAdapter(opencodeAdapter);