catherd-cli 1.0.0 → 1.1.0

package/README.md

@@ -17,8 +17,13 @@ of work, climbing a ladder only when a cheaper rung falls short.
   opencode 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.
-- **Guard rails for autopilot.** Quota failover to a rung on another quota, a preflight check before any
-  worker starts, per-repo knowledge carried between runs, and a run budget.
+- **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.
+- **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.
+- **Guard rails for autopilot.** Quota failover to a stand-in that clears the same bars, a preflight check
+  before any worker starts, per-repo knowledge carried between runs, and a run budget.
 
 ## Requirements
 
@@ -38,13 +43,18 @@ you have (`/catherd-setup` in Claude Code, or `catherd profile set roles.<role>.
 ## Install
 
 ```sh
-bunx catherd-cli init
+bun add -g catherd-cli
+catherd init
 ```
 
-The npm package is `catherd-cli`; the command it installs is `catherd`. `init` asks for the optional Jev key,
-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`; piped, it reads one answer per line once stdin closes: the Jev key, the profile, whether to replace it, each on its own line even when a question is skipped). Then add the plugin to Claude Code:
+The npm package is `catherd-cli`; the command it installs is `catherd`. `bunx catherd-cli init` works too: `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
+optional Jev key, 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`; piped, it reads one answer per line once stdin closes: the Jev key, the
+profile, whether to replace it, each on its own line even when a question is skipped). Then add the plugin to
+Claude Code:
 
 ```sh
 claude plugin marketplace add 47vigen/catherd
@@ -52,33 +62,35 @@ 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
-`bunx catherd-cli doctor`.
+`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.
 
 ## Use
 
 In Claude Code:
 
-- `/catherd <task>` runs a task on autopilot; `/catherd` alone resumes the latest run.
+- `/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`.
 - `/catherd-setup` tunes your profile in conversation: which models and efforts each role may
   use, cost or speed, isolation, budget and failover.
 
 In a terminal:
 
-| Command                                                                                   | What it does                                                                             |
-| ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
-| `catherd`                                                                                 | The dashboard: Status, Profiles and Runs (below)                                         |
-| `catherd init [--no-input] [--profile <p>]`                                               | First-run setup                                                                          |
-| `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`, `budget.usd 20`                       |
-| `catherd status [run]`, `catherd watch [--once] [--interval <s>]`                         | Where runs stand                                                                         |
-| `catherd runs list [--repo <path>]\|show <id> [--debug [--name <n>]]\|cancel <id> <name>` | Past runs; `--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 treat-like <rung> <like>`                                                | Scores an unscored rung as a scored one                                                  |
-| `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 [--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 treat-like <rung> <like>`                                                | Scores an unscored rung as a scored one                                                             |
+| `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)                  |
 
 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
@@ -103,16 +115,18 @@ Run data lives in `~/.local/share/catherd/`, config in `~/.config/catherd/` (bot
 | `CATHERD_CLAUDE_AGENTS_DIR` | Where catherd links its Claude agents (default: `$CLAUDE_CONFIG_DIR/agents`, else `~/.claude/agents`) |
 | `NO_COLOR`                  | Drops colour (the dashboard's and `--help`'s; piped `--help` has none either)                         |
 
-For development only: `CATHERD_STORY=1` opens the dashboard's storybook, `CATHERD_TICK_MS` sets how often a blocked
-`wait` reports progress (default 30000), and `CATHERD_LIVE=1` enables the live tests
-(CONTRIBUTING.md has the rest).
+For development only: `CATHERD_STORY=1` opens the dashboard's storybook, and `CATHERD_LIVE=1` enables the live
+tests (CONTRIBUTING.md has the rest).
 
 ### The dashboard
 
 `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** (live roles, climbs, routes, the budget, landed
-milestones; `p` pauses). `catherd watch` opens it on Runs.
+harness, budget, failover, timeouts and notify) and **3 Runs** (the Claude Code 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,
+`p` pauses). `catherd watch` opens it on Runs.
 
 - `ctrl+p` lists every command with its key and CLI twin; `?` lists the keys that work where you are.
 - `ctrl+x` is the leader: `ctrl+x 1`–`3` tabs, `ctrl+x n` new profile, `ctrl+x l` profiles, `ctrl+x u` and
@@ -131,7 +145,16 @@ milestones; `p` pauses). `catherd watch` opens it on Runs.
   (the palette shows each command by title; the ids are listed in
   [`src/entry/tui/commands.ts`](src/entry/tui/commands.ts)).
 
-## Upgrading from 0.x
+## Upgrading
+
+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
+session. `wait` is gone: results arrive as messages, `peek` shows a run, `result` reads a record. A profile saved
+by 1.0 keeps its failover map; `catherd profile validate` says what to change. The details are in
+[MIGRATION.md](MIGRATION.md).
+
+### From 0.x
 
 1.0 is a clean break: run `bunx catherd-cli init` once. It moves your 0.x `config.json`, `projects.json` and
 profiles into a `0.x-backup-<time>/` folder next to them (it never reads or deletes them), writes the 1.0
@@ -142,18 +165,19 @@ Code session. The details are in [MIGRATION.md](MIGRATION.md).
 
 ## Docs
 
-| Where                                                                                                                | What                                                                  |
-| -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
-| [MIGRATION.md](MIGRATION.md)                                                                                         | Upgrading 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/superpowers/specs/2026-09-25-catherd-1.0-design.md`](docs/superpowers/specs/2026-09-25-catherd-1.0-design.md) | The 1.0 design (binding)                                              |
-| [`docs/dev/`](docs/dev/)                                                                                             | Maintainer docs: live verification, manual tests, dependencies, ideas |
-| [`docs/dev/live-verification.md`](docs/dev/live-verification.md)                                                     | What CI cannot run: live tests, fixture capture, the Codex sandbox    |
-| [`docs/tui-frames.md`](docs/tui-frames.md)                                                                           | Every dashboard screen as text (generated, checked in CI)             |
-| [`docs/superpowers/`](docs/superpowers/), [`docs/research/`](docs/research/)                                         | How 1.0 was designed and built: plans, reviews, research              |
-| [`docs/archive/0.x/`](docs/archive/0.x/)                                                                             | The 0.x design and plans, for history                                 |
+| Where                                                                                              | What                                                                  |
+| -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| [MIGRATION.md](MIGRATION.md)                                                                       | Upgrading from 1.0 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-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 |
+| [`docs/dev/live-verification.md`](docs/dev/live-verification.md)                                   | What CI cannot run: live tests, fixture capture, the Codex sandbox    |
+| [`docs/tui-frames.md`](docs/tui-frames.md)                                                         | Every dashboard screen as text (generated, checked in CI)             |
+| [`docs/plans/`](docs/plans/), [`docs/handoff/`](docs/handoff/), [`docs/research/`](docs/research/) | How 1.0 was designed and built: plans, reviews, research              |
+| [`docs/archive/0.x/`](docs/archive/0.x/)                                                           | The 0.x design and plans, for history                                 |
 
 ## Contributing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "catherd-cli",
-  "version": "1.0.0",
+  "version": "1.1.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.0.0",
+  "version": "1.1.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/.mcp.json

@@ -1,8 +1,8 @@
 {
   "mcpServers": {
     "catherd": {
-      "command": "bunx",
-      "args": ["catherd-cli@1.0.0", "mcp"]
+      "command": "sh",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/bin/catherd-mcp"]
     }
   }
 }

package/plugin/bin/catherd-mcp

@@ -0,0 +1,30 @@
+#!/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.1.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
+  # CATHERD_USER_TMPDIR is only this launcher's own hand-off to the server below; never pass on a stray one
+  unset CATHERD_USER_TMPDIR
+  exec catherd mcp
+fi
+
+# else bunx, with its cache out of $TMPDIR: macOS cleans old files there and leaves bunx a broken package.
+# The server gets the user's own TMPDIR back from CATHERD_USER_TMPDIR (empty when it was unset).
+if [ -n "${XDG_CACHE_HOME:-}" ]; then
+  cache="$XDG_CACHE_HOME"
+elif [ -n "${HOME:-}" ]; then
+  cache="$HOME/.cache"
+else
+  echo "catherd-mcp: HOME and XDG_CACHE_HOME are both unset, so there is no cache folder for bunx; set HOME, or install catherd globally: bun add -g catherd-cli@$VERSION" >&2
+  exit 1
+fi
+CATHERD_USER_TMPDIR="${TMPDIR:-}"
+TMPDIR="$cache/catherd/bunx"
+if ! mkdir -p "$TMPDIR" 2>/dev/null; then
+  echo "catherd-mcp: cannot create $TMPDIR for bunx's cache; fix its permissions, or install catherd globally: bun add -g catherd-cli@$VERSION" >&2
+  exit 1
+fi
+export CATHERD_USER_TMPDIR TMPDIR
+exec bunx "catherd-cli@$VERSION" mcp

package/plugin/commands/catherd.md

@@ -7,4 +7,4 @@ Use the `catherd` skill for this, and follow it exactly.
 
 Task: $ARGUMENTS
 
-If the task is empty, resume: call `status()`, tell the user which run it names, and continue that run from its state.md.
+If the task is empty, resume: call `status()`, tell the user which run it names, call `peek(run)` once, and continue that run from its `Protocol next` step.