catherd-cli 1.3.0 → 1.5.0

package/README.md

@@ -6,19 +6,18 @@
  (")(")
 ```
 
-Autopilot builds from your own Claude Code session. Claude plans and verifies, Codex, opencode, Cursor, Grok Build,
-Antigravity or headless Claude Code workers write the code, and [Jev](https://typesafe.ai) picks the model and effort for each piece
+Autopilot builds from your own Claude Code or native Codex session. Your profile routes the architect, verifier and workers to their backends; Codex, opencode, Cursor, Grok Build,
+Antigravity or headless Claude Code processes write the code, and [Jev](https://typesafe.ai) picks the model and effort for each piece
 of work, climbing a ladder only when a cheaper rung falls short.
 
 - **Your harness, as you set it up.** Every role runs in its vendor's own CLI with your config,
   hooks, skills and `AGENTS.md`. Isolation is an opt-in toggle per profile and harness, for when
   you'd rather save the tokens your customizations cost.
-- **Claude roles stay native.** `claude:` rungs run as ordinary Claude Code subagents; Codex,
+- **Claude roles stay native on Claude Code.** `claude:` rungs require that host and run as ordinary Claude Code subagents; Codex,
   opencode, Cursor, Grok Build, Antigravity and headless `claude-code:` rungs run through catherd's MCP server.
 - **Survives restarts.** Workers are detached processes writing straight to disk, so a dropped
   MCP server never loses a run.
-- **Results come to you.** Roles run side by side while you keep talking to Claude; each one that finishes
-  arrives in the session as a message, like a native subagent's notice, and `peek` shows how a run stands.
+- **Results come to you.** Roles run side by side while you keep talking. Claude Code uses its peer inbox; Codex uses queued next input through its existing native server. A busy Codex conversation processes it after the active turn. Queue acceptance and result collection are separate; `peek` shows how a run stands.
 - **A protocol the tools enforce.** Every lane is routed, every brief ends with the reply contract, and a
   milestone lands only after a reviewer and a verifier passed it. Workers can run their own checks (network,
   loopback, Docker, the lock dir); an owner question parks one milestone, not the run.
@@ -28,7 +27,7 @@ of work, climbing a ladder only when a cheaper rung falls short.
 ## Requirements
 
 - [Bun](https://bun.sh) ≥ 1.4
-- [Claude Code](https://claude.com/claude-code) (desktop app or CLI)
+- An orchestration host: [Claude Code](https://claude.com/claude-code), or native [Codex](https://github.com/openai/codex) CLI/Desktop with plugin support and the existing native queue endpoint (installed CLI 0.159.2 verified for packaging; queue support is feature-detected)
 - At least one worker backend, logged in:
   - [Codex CLI](https://github.com/openai/codex) 0.157.0 or newer
   - [opencode](https://opencode.ai) **v2**, 2.0.16 or newer: `curl -fsSL https://opencode.ai/v2/install | bash`
@@ -47,7 +46,7 @@ of work, climbing a ladder only when a cheaper rung falls short.
 
 `catherd doctor` checks each backend's version and login and prints the fix for anything missing. The default
 profile runs its workers on Codex; without Codex, doctor's fix also names how to move those roles to a backend
-you have (`/catherd-setup` in Claude Code, or `catherd profile set roles.<role>.rungs <rung>`).
+you have (`/catherd-setup`, or `catherd profile set roles.<role>.rungs <rung> --host <codex|claude-code>`). Codex-only setup does not require or configure Claude; enabled selected roles and reachable failover decide optional dependencies. Doctor sends nothing by default; `--test-push` is an explicit smoke send from a validated host session (`--thread <uuid>` names the Codex thread from a shell; inside a session, the `test_push` tool does the same).
 
 ### Cursor
 
@@ -93,7 +92,9 @@ grok keeps a session on the access it started with, so catherd refuses to resume
 An Antigravity rung names the model `agy models` lists, without an effort suffix; the effort is agy's `--effort`
 (`low`, `medium`, `high` or `max`), and `#default` passes none: `antigravity:gemini-3.8-flash#low`. No profile uses
 Antigravity until you put a rung on it. catherd never runs `agy -p` while agy is signed out, since agy would open a
-browser and wait; `catherd doctor` says so, with the fix. A Google login draws on your plan's quota (doctor shows
+browser and wait; `catherd doctor` says so, with the fix. A sign-in check that passed is kept for 10 minutes, so
+after you sign agy out, restart the catherd MCP server (or wait those minutes) before the next Antigravity dispatch.
+A Google login draws on your plan's quota (doctor shows
 what is left); `GEMINI_API_KEY` bills the Gemini API project. Gemini rungs fail over between Antigravity and Cursor
 when either runs out, unless your profile names another stand-in.
 
@@ -111,14 +112,21 @@ route is the one meant for automation; check the terms before you rely on a plan
 
 ## Install
 
+catherd runs from Claude Code or, since 1.4, from native Codex; one global `catherd` and one plugin version serve both. To check a packaged build before you rely on it, follow the [local packaged acceptance procedure](docs/dev/live-verification.md#14-native-codex-packaging-and-completion-acceptance); a matching version alone does not prove that the feature core ran.
+
+### Claude Code
+
 ```sh
 bun add -g catherd-cli
-catherd init
+catherd init --host claude-code
 ```
 
-The npm package is `catherd-cli`; the command it installs is `catherd`. `bunx catherd-cli init` works too: `init`
+The npm package is `catherd-cli`; the command it installs is `catherd`. `bunx catherd-cli init --host claude-code`
+works too (a terminal with no host evidence cannot pick the architect/verifier defaults, so name the host): `init`
 installs the global command at its own version (`--no-global` skips it) and says `installing catherd…` before
-it does, though the first `bunx` resolve itself prints nothing for up to half a minute. `init` asks for the
+it does, though the first `bunx` resolve itself prints nothing for up to half a minute: bunx fetches about a
+hundred packages before catherd's first line, TypeScript among them (a peer dependency of OpenTUI's native
+layer, which Bun installs), so `bun add -g catherd-cli` first is the quicker start. `init` asks for the
 optional Jev key and the optional Artificial Analysis key, syncs the public model sources, writes the default
 profile and links its Claude agents, lists your backends' models, and ends with a readiness report (`--no-input`
 asks nothing and keeps what exists; `--profile <name>` sets up and activates that profile instead of `default`;
@@ -132,41 +140,84 @@ claude plugin install catherd@catherd
 ```
 
 Start a new Claude Code session so the plugin, its MCP server and the agent files load, then check with
-`catherd doctor`. Run it once from inside that session too (ask Claude to run `catherd doctor`): its `push` row
-then checks that finished roles can reach the session.
+`catherd doctor --host claude-code`. From inside that session, explicit `catherd doctor --test-push` sends a labeled smoke notice; inspect actual processing separately from transport acceptance.
+
+### Native Codex
+
+```sh
+bun add -g catherd-cli
+catherd init --host codex
+codex plugin marketplace add 47vigen/catherd
+codex plugin add catherd@catherd
+codex mcp list --json
+```
+
+Restart the Codex host to load the installed shared skills and server. Native CLI accepts `owner/repo[@ref]` and a local marketplace path. The supported marketplace uses `.claude-plugin/marketplace.json` with its plugin subdirectory; the native manifest is `plugin/.codex-plugin/plugin.json`, with `skills: "./skills/"` and `mcpServers: "./.mcp-codex.json"`. Installed native resolution supplies `command: "sh"`, `args: ["./bin/catherd-mcp"]`, `cwd: <installed plugin root>` and `CATHERD_ORCHESTRATION_HOST=codex`. No Claude root macro or synthetic session ID belongs in that declaration. The shared launcher/core remains versioned together with both manifests.
+
+Pass the actual project `repo` to repository-aware MCP profile/setup/catalog calls, because the server cwd is the plugin root. `run_start(repo, ...)` already requires it. Terminal `init` and `doctor` accept `--host codex|claude-code|auto`; selecting a terminal host chooses setup checks without inventing a conversation owner.
 
 ## Use
 
-In Claude Code:
+In either supported host, use the installed shared skills through that host's skill invocation and tool discovery:
 
 - `/catherd <task>` runs a task on autopilot; `/catherd` alone resumes the latest run. While it runs, keep
-  talking: each finished role arrives as a message from catherd, and "how is it going?" gets a `peek`.
+  talking: completion arrives through the host's transport, and "how is it going?" gets a `peek`.
 - `/catherd-setup` tunes your profile in conversation: which models and efforts each role may
   use, cost or speed, isolation, budget and failover.
 
+`route` chooses the backend for every role. Native `claude:` uses Claude Code's `Agent` and `record_agent_run` only on Claude Code; process backends, including Codex architect/verifier, use `dispatch` followed by `result`. Omitted Codex architect/verifier choices are exactly `codex:gpt-6.1-sol#high` / `codex:gpt-6.1-sol#low`; omitted Claude choices retain their existing native defaults. Verify that exact model ID against native catalog discovery and validation; if spelling differs, resolve the mismatch explicitly with the owner, never silently normalize or substitute, and retain high/low efforts. Explicit ladders and materialized profiles are preserved, without silently converting `claude:` to `claude-code:`. To opt into host defaults, review and save the narrow reset:
+
+```sh
+catherd profile reset-host-defaults <profile> --host codex --preview --json > /tmp/catherd-host-defaults-review.json
+# Review the diff, effective defaults, errors and warnings.
+catherd profile reset-host-defaults <profile> --host codex --expect /tmp/catherd-host-defaults-review.json --json
+```
+
+It removes only architect/verifier `rungs` and `defaultRung`; every other setting stays intact. Run profile CLI commands from the project directory and choose the actual profile name. Use `--host claude-code` for Claude defaults.
+
+Completion never uses `await_results` or model polling. Codex sends through `codex queue --remote unix://` to the validated original thread: idle wake and ordered busy follow-up are the native semantics, without Claude's urgent tool-round priority. A receipt proves queue acceptance, not observed generation or collection; unloaded/interrupted hosts may retain input. Only `result` collects the actual stored record. Explicit `peek(run)` adopts the run for the current host/session; `status` and `result` do not. Unknown/conflicting identity never owns or pushes.
+
+When a role ends, its own supervisor also queues the notice to a Codex owner's thread, under the same receipt as the server's push, so a thread whose MCP server Codex has stopped still hears, and nothing arrives twice. Run a Codex coordinator inside `tmux` (or `screen`): Codex stops a thread's MCP servers once no client is attached, and the queued input waits for the next attach. Every catherd message names the role's `thread:`; resume it with `dispatch(…, thread: "latest")` under the same name.
+
+Roles get catherd's tools too. Headless Codex and Claude Code roles get a `catherd_role` MCP server, isolated or not, without any change to your config; roles on other backends run `catherd run-file read|write <run> <path>` and `catherd gate check|pass <run> …` from their shell, bound to their own run and to their role's tools: every role may read run files, only the architect and researcher write them, and only the verifier runs `gate check|pass` (anything else is `E_ROLE_SCOPE`). The coordinator tools (`dispatch`, `result`, `land`, `climb`, `peek` of another role, `run_start`, `park`, `answer`, `cancel`, `set_next`, `profile_set`, `test_push`, `run_pin`, `lane_set`, `owns_add`, `record_agent_run` and the workspace writers) are the orchestrator's: a role's process gets `E_ROLE_SCOPE` for them, so a role can never take the run over.
+
+Recover unread work with `peek` and `result`. Accepted or ambiguous attempts are not automatically resent. When ambiguity needs a deliberate retry, run from the current owner's validated host session:
+
+```sh
+catherd runs retry-push <run> <name> --event '<exact event ID from peek/status>' --acknowledge-possible-duplicate
+```
+
+This acknowledges possible duplicate native input; an accepted receipt still suppresses a repeat for that owner/event. Without a supported history reconciliation API, retain ambiguity until an explicit decision. Notices preserve all event IDs, including coalesced events; repeated input means idempotent reads, never another dispatch or landing. Stored records and independent reviewer/verifier gates are authoritative. Profile notification moments use an available host facility, without inventing a Codex notification tool or scheduled wake.
+
 In a terminal:
 
-| Command                                                                                   | What it does                                                                                        |
-| ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
-| `catherd`                                                                                 | The dashboard: Status, Profiles and Runs (below)                                                    |
-| `catherd init [--no-input] [--no-global] [--profile <p>]`                                 | First-run setup; installs the global `catherd` at its own version unless `--no-global`              |
-| `catherd doctor [--json]`                                                                 | Readiness report, one row per check with its fix; exits 3 when not ready                            |
-| `catherd profile list\|show\|use [--repo]\|new [--from <p>]\|copy\|rm\|diff\|validate`    | Profiles; `use --repo` binds one to the repo you are in                                             |
-| `catherd profile use --repo --clear`                                                      | Unbinds the repo you are in; it runs on the active profile again                                    |
-| `catherd profile set <path> <value> [--profile <p>]`                                      | One field, e.g. `roles.verifier.access read-only`, `roles.worker.network false`, `budget.usd 20`    |
-| `catherd status [run]`, `catherd watch [--once] [--interval <s>]`                         | Where runs stand, grouped by the Claude Code session that drove them                                |
-| `catherd runs list [--repo <path>]\|show <id> [--debug [--name <n>]]\|cancel <id> <name>` | Past runs, by session; `--debug` adds exit.json and the stderr and event tails, `--name` one role's |
-| `catherd catalog refresh\|list [--backend <b>] [--role <r>] [--text <t>] [--scored]`      | The models catherd can place, filtered                                                              |
-| `catherd catalog sync [--force] [--unmatched]`                                            | Fetches the public model facts and scores now (below); `--unmatched` lists ids no model matched     |
-| `catherd catalog treat-like <rung> <like>`                                                | Scores an unscored rung as a scored one                                                             |
-| `catherd catalog treat-like --suggest <rung>\|--clear <rung>\|--reset`                    | The three nearest stand-ins for a rung; removes one or every mapping of yours                       |
-| `catherd knowledge show\|add "<line>"\|path [--repo <path>]`                              | The repo's knowledge.md, which new runs read; `add` appends a fact of yours, marked "by hand"       |
-| `catherd lock [--slots N] -- <cmd>`                                                       | Runs a heavy command behind the machine-wide semaphore, in its own session (no /dev/tty)            |
-| `catherd mcp`                                                                             | The MCP server on stdio; the plugin starts it, you never need to                                    |
-| `catherd capture-fixtures [--backend <b>] [--out <dir>]`                                  | Contributors: records sanitized test fixtures from real runs (see CONTRIBUTING.md)                  |
+| Command                                                                                                                                                                | What it does                                                                                                                                           |
+| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `catherd`                                                                                                                                                              | The dashboard: Status, Profiles and Runs (below)                                                                                                       |
+| `catherd init [--host codex\|claude-code\|auto] [--no-input] [--no-global] [--profile <p>]`                                                                            | First-run setup; installs the global `catherd` at its own version unless `--no-global`                                                                 |
+| `catherd doctor [--host codex\|claude-code\|auto] [--test-push [--thread <uuid>]] [--docker] [--json]`                                                                 | Readiness and capability report; no send unless explicit smoke; `--docker` probes a compose network and the Docker disk; exits 3 when not ready        |
+| `catherd profile list\|show\|use [--repo]\|new [--from <p>]\|copy\|rm\|diff\|validate`                                                                                 | Profiles; `use --repo` binds one to the repo you are in                                                                                                |
+| `catherd profile use --repo --clear`                                                                                                                                   | Unbinds the repo you are in; it runs on the active profile again                                                                                       |
+| `catherd profile set <path> <value> [--profile <p>]`                                                                                                                   | One field, e.g. `roles.verifier.access read-only`, `roles.worker.network false`, `budget.usd 20`                                                       |
+| `catherd status [run]`, `catherd watch [--once] [--interval <s>]`                                                                                                      | Where runs stand, grouped by host and session; read-only ownership                                                                                     |
+| `catherd runs list [--repo <path>]\|show <id> [--debug [--name <n>]]\|cancel <id> <name>`                                                                              | Past runs, by session; `--debug` adds exit.json and the stderr and event tails, `--name` one role's                                                    |
+| `catherd runs clean [<id>]`                                                                                                                                            | Removes the roles' scratch folders (each role's `$TMPDIR`) of runs with no live role                                                                   |
+| `catherd catalog refresh\|list [--backend <b>] [--role <r>] [--text <t>] [--scored]`                                                                                   | The models catherd can place, filtered                                                                                                                 |
+| `catherd catalog sync [--force] [--unmatched]`                                                                                                                         | Fetches the public model facts and scores now (below); `--unmatched` lists ids no model matched                                                        |
+| `catherd catalog treat-like <rung> <like>`                                                                                                                             | Scores an unscored rung as a scored one                                                                                                                |
+| `catherd catalog treat-like --suggest <rung>\|--clear <rung>\|--reset`                                                                                                 | The three nearest stand-ins for a rung; removes one or every mapping of yours                                                                          |
+| `catherd knowledge show\|add "<line>"\|path [--repo <path>]`                                                                                                           | The repo's knowledge.md, keyed by its git origin (its toplevel when it has none), which new runs read; `add` appends a fact of yours, marked "by hand" |
+| `catherd knowledge env set NAME=value\|NAME --from VAR`, `env rm NAME`, `env list`                                                                                     | The repo's gate environment, which the verifier and preflight run with; a secret by reference only                                                     |
+| `catherd runs supersede <id> --by <id>`, `catherd runs pin <id>`                                                                                                       | Closes a run with a pointer to the one that took over; re-pins a run to the repo's profile now                                                         |
+| `catherd pause --machine\|--workspace <id> "<reason>"`, `catherd resume --machine\|--workspace <id>`                                                                   | Pauses every run on the machine (or in a workspace) on one blocker; dispatch is refused until resume                                                   |
+| `catherd lock [--slots N] [--role verifier [--run <id>]] -- <cmd>`                                                                                                     | Runs a heavy command behind the machine-wide semaphore, in its own session (no /dev/tty); `--role verifier` keeps two runs' verifiers apart            |
+| `catherd run-file read\|write <run> <path>`                                                                                                                            | A run's plan, lanes and notes (`write` reads stdin); in a role, its own run only                                                                       |
+| `catherd gate check <run> [--item <i> --command <c> --paths <p,…>] [--milestone <M>]`, `catherd gate pass <run> --item <i> --command <c> --paths <p,…> --evidence <e>` | A verifier's gate evidence, as `gate_check`/`gate_pass`; in a role, its own run only                                                                   |
+| `catherd mcp`                                                                                                                                                          | The MCP server on stdio; the plugin starts it, you never need to                                                                                       |
+| `catherd capture-fixtures [--backend <b>] [--out <dir>]`                                                                                                               | Contributors: records sanitized test fixtures from real runs (see CONTRIBUTING.md)                                                                     |
 
 A profile command without a profile name (`show`, `set`, `diff`, `validate`), like the MCP profile tools, acts
-on the profile the repo you are in runs on: the one bound to it, else the active one. Run them as
+on the profile the repo you are in runs on: the one bound to it, else the active one. Pass `repo` explicitly to MCP tools; profile CLI commands accept `--host` for effective defaults. Run them as
 `bunx catherd-cli <command>` when catherd is not installed globally. Every read command takes `--json`; a bare `catherd runs` is `catherd runs list`. Exit codes: 0 ok, 1 error, 2 usage, 3 not ready, 130 interrupted; an error prints
 `error E_CODE: message` and a `fix:` line. `--verbose` (or `CATHERD_LOG=debug`) logs more to
 `~/.local/share/catherd/logs/`, kept for 7 days with secrets redacted. The dashboard takes `--plain` (ASCII, no colour)
@@ -174,7 +225,7 @@ and `--reduced-motion`; `doctor` and `init` take `--plain` for ASCII glyphs too.
 
 Model facts and scores also come from public sources: models.dev, OpenRouter, LiteLLM, Arena (LMArena), Vectara's
 hallucination leaderboard and Epoch AI, plus Artificial Analysis when you give `catherd init` a free key. The MCP
-server syncs them in the background when a Claude Code session starts (each source at most every 12 hours, never
+server syncs them in the background when a host session starts (each source at most every 12 hours, never
 delaying the session), `init` syncs them, and `catherd catalog sync` (or the `catalog_sync` tool) does it on demand.
 Each answer is kept in `~/.local/share/catherd/sources/`; a source that fails keeps its last good answer, and with no
 network and no sync at all catherd routes on the scores it ships. Those are the keyless sources' values, refreshed
@@ -185,15 +236,59 @@ A lane's kind and difficulty pick a bar: a threshold on each dimension it spans
 `honesty`, `agentic`, `frontend`; `steer` is shown but has no default bar), and the lane starts on the cheapest
 rung that clears them all. A rung with no value on a dimension takes its nearest stand-in's as `inferred`, and
 `profile validate` and `doctor` list it as a "stand-in to confirm": confirm or replace it with `catherd catalog
-treat-like --suggest <rung>`, then `treat-like <rung> <like>`. `route` says, for the rung it picks, each threshold,
-the value used, its confidence and source, and catherd's own runs on it ("12 lanes, 2 climbed, 1 partial"), which
-it shows but never routes on. A bar of your own goes in `~/.config/catherd/catalog.override.json`, per dimension
+treat-like --suggest <rung>`, then `treat-like <rung> <like>`. A ladder holds only rungs at least as strong as its
+start, and rungs of equal scores on two quotas start on the one the run has used least. `route` returns the rung,
+its ladder and a one-line why (a lane's declared `Kind:`/`Difficulty:` wins over Jev, and the why says when Jev
+disagreed, when no rung clears the bar, or when a tie decided); the run's `routes.jsonl` keeps every role's
+decision with, for the rung it picks, each threshold, the value used, its confidence and source, and catherd's own
+runs on it ("12 lanes, 2 climbed, 1 partial"), which it shows but never routes on. A bar of your own goes in `~/.config/catherd/catalog.override.json`, per dimension
 (`"bars": { "ui": { "hard": { "frontend": 1700, "honesty": null } } }`: a number sets a threshold, `null` removes
 the default's).
 
 Run data lives in `~/.local/share/catherd/`, config in `~/.config/catherd/` (both follow
 `XDG_*`).
 
+### Coordinating several repositories
+
+A workspace can be a plain directory containing independent Git repositories. Declare its members explicitly
+in `catherd.workspace.json`; catherd does not scan neighboring folders:
+
+```json
+{
+  "schema": 1,
+  "repos": { "api": "./api", "web": "./web" }
+}
+```
+
+Run `catherd workspace inspect /path/to/workspace --json` to check the resolved members. Through MCP,
+`workspace_start` takes `root`, `title`, `a_lines`, and `steps`: each step has `id`, a member `repo`, `title`,
+`a_lines`, optional `depends_on` step ids, and the `milestone` that releases its dependents (default `M1`).
+A step with `release: "merge"` and a `base` ref (`origin/main`) releases them only once its landed commit is
+an ancestor of that ref (`git merge-base --is-ancestor`), checked when a dependent asks; fetch first, nothing
+is polled.
+An explicit `repos` map can replace the manifest. Only members used by the steps enter the run snapshot.
+Steps reusing one member must be ordered by dependencies. A final verification step can reuse a member
+after both parallel producer steps land; unordered steps in the same repository are refused.
+
+Write the shared interface or coordination agreement with `workspace_contract(workspace, content)` before
+starting children; the first child freezes it, and every child receives `workspace-contract.md`.
+`workspace_child_start(workspace, step)` creates a single-repo run only when its prerequisites have landed.
+Use the existing route, dispatch, verification and land workflow with that child's run id. Each member keeps
+its own profile, knowledge and repository rules; workers write within their own repository.
+
+`workspace_status(workspace)` and `catherd workspace status <id> --json` show the shared view and spending.
+The optional workspace `budget` (`minutes`, `tokens`, `usd`; no cap unless given, minutes from the first
+child) stops new admissions when aggregate observed spending reaches its cap, alongside each child's budget;
+`workspace_budget(workspace, …)` raises it. Running workers may overshoot; native subagent usage is reported
+after execution. Dependency readiness requires a recorded landing and finalized dispatches, not just a
+finished worker. Landing a step's completion milestone and dispatch admission share the parent lock; other
+milestones land freely, and a landed step admits a post-land fix. `workspace_pause(workspace, reason)` stops
+every child's admission on one blocker until `workspace_resume`. Workspaces support at most 100 repositories
+and 100 steps. A run folder without a readable `meta.json` is skipped and named in `workspace_status`; with a
+cap set, unreadable or negative usage evidence blocks admission until repaired. Stored status remains available after a checkout disappears, while child
+recovery and admission require the captured Git root. catherd never automatically commits, pushes,
+rolls back repositories or starts the next child.
+
 ### Environment variables
 
 | Variable                      | What it does                                                                                                |
@@ -219,7 +314,7 @@ tests (CONTRIBUTING.md has the rest).
 
 `catherd` opens three tabs: **1 Status** (every check with its fix; `y` copies the fix, `r` checks again),
 **2 Profiles** (one tree per profile: roles with their access, default rung, models and efforts, then routing,
-harness, budget, failover, timeouts and notify) and **3 Runs** (the Claude Code sessions that drove your runs, newest
+harness, budget, failover, timeouts and notify) and **3 Runs** (the host sessions that drove your runs, newest
 first; a session opens on its runs, their milestones and every role with its rung, status, time and last event, live
 ones first; a milestone opens on its digest (what landed, lanes and climbs, reviewer and verifier, tokens); a role
 opens on its brief, reply and record; the open screen redraws as run files change; `esc` goes back,
@@ -244,6 +339,12 @@ opens on its brief, reply and record; the open screen redraws as run files chang
 
 ## Upgrading
 
+From 1.4: `bun add -g catherd-cli@latest && catherd doctor`, update the plugin and start a new session; `doctor`
+names the Claude agent links to refresh. There is still no `wait` tool (it never shipped and is gone): end the
+turn, and on Codex run the coordinator inside `tmux`. A role calling a coordinator tool now gets `E_ROLE_SCOPE`,
+knowledge is keyed by the git origin, and `route` returns seven keys with the rest in `routes.jsonl`.
+[MIGRATION.md](MIGRATION.md), "From 1.4 to 1.5", has the rest.
+
 From 1.0: install 1.1 and run its `init` (`bun add -g catherd-cli@latest && catherd init`, or
 `bunx catherd-cli@latest init`; 1.0's own `catherd init` does not upgrade), update the plugin
 (`claude plugin marketplace update catherd && claude plugin update catherd@catherd`) and start a new Claude Code
@@ -264,10 +365,11 @@ Code session. The details are in [MIGRATION.md](MIGRATION.md).
 
 | Where                                                                                              | What                                                                  |
 | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
-| [MIGRATION.md](MIGRATION.md)                                                                       | Upgrading from 1.0 and from 0.x                                       |
+| [MIGRATION.md](MIGRATION.md)                                                                       | Upgrading from each release to the next, and from 0.x                 |
 | [CHANGELOG.md](CHANGELOG.md)                                                                       | Releases                                                              |
 | [CONTRIBUTING.md](CONTRIBUTING.md)                                                                 | Development setup, the checks, commits, changesets, live tests        |
 | [SECURITY.md](SECURITY.md)                                                                         | Reporting a vulnerability; what catherd stores and how                |
+| [`docs/specs/2026-10-02-catherd-1.5-design.md`](docs/specs/2026-10-02-catherd-1.5-design.md)       | The 1.5 design (binding where it differs from the earlier ones)       |
 | [`docs/specs/2026-09-28-catherd-1.1-design.md`](docs/specs/2026-09-28-catherd-1.1-design.md)       | The 1.1 design (binding; builds on 1.0's)                             |
 | [`docs/specs/2026-09-25-catherd-1.0-design.md`](docs/specs/2026-09-25-catherd-1.0-design.md)       | The 1.0 design                                                        |
 | [`docs/dev/`](docs/dev/)                                                                           | Maintainer docs: live verification, manual tests, dependencies, ideas |
@@ -278,8 +380,8 @@ Code session. The details are in [MIGRATION.md](MIGRATION.md).
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md). CI runs the checks on Linux and macOS, on Bun 1.4.0 and the latest Bun;
-what CI cannot run is in [`docs/dev/live-verification.md`](docs/dev/live-verification.md). Report security issues
+See [CONTRIBUTING.md](CONTRIBUTING.md). CI runs the checks on every pull request on Linux and macOS, with Bun 1.4.0 and the latest Bun (the full matrix nightly);
+live verification is in [`docs/dev/live-verification.md`](docs/dev/live-verification.md). Report security issues
 privately, as [SECURITY.md](SECURITY.md) describes. Everyone taking part follows the
 [Code of Conduct](CODE_OF_CONDUCT.md).
 

package/catalog/ATTRIBUTION.md

@@ -1,7 +1,8 @@
 # Attribution for the shipped catalog data
 
 `catalog/scores.json` carries model scores from public sources. Each value names its source (`source`), the page
-it came from (`url`), its date and its confidence. The weekly `catalog-refresh` workflow rebuilds the values that
+it came from (`url`), its date and its confidence. `catalog/models.json` carries each model's release date
+(`releaseDate`) from models.dev. The weekly `catalog-refresh` workflow rebuilds the values that
 come from the keyless sources below; the hand-typed values (no `source`) cite their own vendor or benchmark page in
 their `url`.
 
@@ -20,6 +21,12 @@ their `url`.
 - License: CC BY 4.0; external tables keep their own license
 - Attribution: Epoch AI, 'Capabilities & benchmarking'. Published online at epoch.ai. Retrieved from 'https://epoch.ai/benchmarks' (CC BY 4.0)
 
+### models.dev
+
+- Data: https://models.dev/api.json, the release dates in `catalog/models.json`
+- License: MIT License
+- Attribution: models.dev (MIT License), https://github.com/sst/models.dev
+
 ### Vectara hallucination leaderboard
 
 - Data: the README table of https://github.com/vectara/hallucination-leaderboard
@@ -28,9 +35,10 @@ their `url`.
 
 ## Sources read at run time only
 
-catherd reads these on the user's machine and ships none of their data: models.dev (MIT License,
-https://models.dev), the OpenRouter API (https://openrouter.ai) and LiteLLM's
-`model_prices_and_context_window.json` (MIT License, https://github.com/BerriAI/litellm).
+catherd reads these on the user's machine and ships none of their data: the OpenRouter API
+(https://openrouter.ai) and LiteLLM's `model_prices_and_context_window.json` (MIT License,
+https://github.com/BerriAI/litellm). models.dev's prices, capabilities and efforts are read at run time too;
+only its release dates ship (above).
 
 Artificial Analysis (https://artificialanalysis.ai) is read only with the user's own key, and its values are never
 shipped.

package/catalog/models.json

@@ -45,6 +45,7 @@
     {
       "id": "gpt-6.1-sol",
       "name": "GPT-6.1 Sol",
+      "predecessor": "gpt-6-sol",
       "vendor": "openai",
       "releaseDate": "2026-09-29",
       "capabilities": { "toolUse": true, "imageIn": true, "reasoning": true },
@@ -63,6 +64,7 @@
     {
       "id": "gpt-6-sol",
       "name": "GPT-6 Sol",
+      "predecessor": "gpt-5.6-sol",
       "vendor": "openai",
       "releaseDate": "2026-09-22",
       "capabilities": { "toolUse": true, "imageIn": true, "reasoning": true },
@@ -88,6 +90,7 @@
     {
       "id": "gpt-6-luna",
       "name": "GPT-6 Luna",
+      "predecessor": "gpt-5.6-luna",
       "vendor": "openai",
       "releaseDate": "2026-09-22",
       "capabilities": { "toolUse": true, "imageIn": true, "reasoning": true },
@@ -239,6 +242,7 @@
     {
       "id": "claude-sonnet-5-5",
       "name": "Claude Sonnet 5.5",
+      "predecessor": "claude-sonnet-5",
       "vendor": "anthropic",
       "releaseDate": "2026-09-28",
       "capabilities": { "toolUse": true, "imageIn": true, "reasoning": true },
@@ -292,6 +296,7 @@
     {
       "id": "grok-4-7",
       "name": "Grok 4.7",
+      "predecessor": "grok-4-6",
       "vendor": "xai",
       "releaseDate": "2026-09-21",
       "capabilities": { "toolUse": true, "imageIn": true, "reasoning": true },
@@ -308,6 +313,7 @@
     {
       "id": "grok-4-6",
       "name": "Grok 4.6",
+      "predecessor": "grok-4-5",
       "vendor": "xai",
       "releaseDate": "2026-08-12",
       "capabilities": { "toolUse": true, "imageIn": true, "reasoning": true },
@@ -356,6 +362,7 @@
     {
       "id": "gemini-3-8-flash",
       "name": "Gemini 3.8 Flash",
+      "predecessor": "gemini-3-7-flash",
       "vendor": "google",
       "releaseDate": "2026-09-02",
       "capabilities": { "toolUse": true, "imageIn": true, "reasoning": true },
@@ -368,6 +375,7 @@
     {
       "id": "gemini-3-7-flash",
       "name": "Gemini 3.7 Flash",
+      "predecessor": "gemini-3-6-flash",
       "vendor": "google",
       "releaseDate": "2026-08-13",
       "capabilities": { "toolUse": true, "imageIn": true, "reasoning": true },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "catherd-cli",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Herds coding agents: autopilot builds from your own Claude Code session.",
   "keywords": [
     "autopilot",

package/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "catherd",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Herds coding agents: Claude plans and verifies, Codex, opencode or headless Claude Code workers write the code, and Jev picks the model and effort for each piece.",
   "author": {
     "name": "47vigen",

package/plugin/.codex-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "catherd",
+  "version": "1.5.0",
+  "description": "Shared catherd orchestration, profiles and durable role results through the versioned MCP core.",
+  "author": { "name": "47vigen", "url": "https://github.com/47vigen" },
+  "homepage": "https://github.com/47vigen/catherd",
+  "repository": "https://github.com/47vigen/catherd",
+  "license": "MIT",
+  "skills": "./skills/",
+  "mcpServers": "./.mcp-codex.json"
+}

package/plugin/.mcp-codex.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "catherd": {
+      "command": "sh",
+      "args": ["./bin/catherd-mcp"],
+      "cwd": ".",
+      "env": { "CATHERD_ORCHESTRATION_HOST": "codex" }
+    }
+  }
+}

package/plugin/bin/catherd-mcp

@@ -1,7 +1,7 @@
 #!/bin/sh
 # catherd's MCP launcher (spec 1.1 §12): the plugin's .mcp.json runs it. The release stamps VERSION
 # (scripts/stamp-plugin-version.mjs), so the plugin always starts the server it was released with.
-VERSION="1.3.0"
+VERSION="1.5.0"
 
 # a global catherd at this version (catherd init installs one): start it, no resolve at all
 if command -v catherd >/dev/null 2>&1 && [ "$(catherd --version 2>/dev/null)" = "$VERSION" ]; then