catherd-cli 1.0.0 → 1.1.1

package/src/domain/profile-rules.ts

@@ -1,5 +1,4 @@
 import {
-  billingKeyOf,
   type Catalog,
   capableFor,
   effortOffered,
@@ -8,12 +7,22 @@ import {
   rungInfo,
   scoresOf,
 } from "./catalog.ts";
-import { type Rung, tryParseRung } from "./ids.ts";
+import {
+  catalogRungs,
+  claudeBilled,
+  downgradeDims,
+  ladderDropDims,
+  quotaOf,
+  rankStandIns,
+} from "./failover.ts";
+import { tryParseRung } from "./ids.ts";
 import { DIFFICULTIES, KINDS } from "./lane.ts";
 import { type Profile, type ProfileDoc, unknownValues } from "./profile.ts";
 import { DEFAULT_ACCESS, ROLES, type Role } from "./roles.ts";
 import { candidates, clearsBar, type RoutingProfile } from "./select.ts";
 
+export { quotaOf };
+
 /** One finding of `validate`: where in the profile, what is wrong, and the action that fixes it. */
 export interface Issue {
   path: string;
@@ -35,12 +44,6 @@ export const routingProfileOf = (p: Profile, role: Role): RoutingProfile => ({
   role: p.roles[role],
 });
 
-/**
- * Spec §7.1 and §4.5: a stand-in on the same quota would be out of quota too. The billing key names the
- * quota, except that the native `claude` path and headless `claude-code` both draw on the Claude plan.
- */
-export const quotaOf = (r: Rung): string => (billingKeyOf(r) === "claude" ? "claude-code" : billingKeyOf(r));
-
 /** Whether a rung's scores are catherd's guess: borrowed through a treat-like, or only `inferred` ones. */
 export function inferredScores(c: Catalog, info: RungInfo): { inferred: boolean; via: string | null } {
   const s = scoresOf(c, info.canonical);
@@ -54,7 +57,8 @@ export function inferredScores(c: Catalog, info: RungInfo): { inferred: boolean;
  * treat-like; a failover stand-in unscored or on the same quota; a rung whose backend catherd cannot run
  * (`backends` lists those it can, `claude` included). Everything else worth knowing is a warning: an access
  * mode other than the role's default, an effort or model the last listing does not offer, a stand-in
- * that never runs. With the stored `doc` `p` came from, a value this catherd does not know is also a
+ * that never runs, and (spec 1.1 §11) a stand-in that downgrades its rung, one that spends Claude quota
+ * while another plan could stand in, and a ladder that goes down. With the stored `doc` `p` came from, a value this catherd does not know is also a
  * warning, one that says how the value is read.
  */
 export function validateProfile(
@@ -131,6 +135,16 @@ export function validateProfile(
       if (!scoresOf(c, info.canonical))
         errors.push({ path: `${at}.rungs`, message: `${rung} is unscored`, fix: TREAT_LIKE_FIX(rung) });
     }
+    rc.rungs.forEach((rung, i) => {
+      const prev = rc.rungs[i - 1];
+      const down = prev === undefined ? [] : ladderDropDims(c, prev, rung);
+      if (down.length)
+        warnings.push({
+          path: `${at}.rungs`,
+          message: `the ladder goes down at ${rung}: it scores below ${prev} on ${down.join(", ")}`,
+          fix: `order ${at}.rungs weakest first`,
+        });
+    });
     if (rc.defaultRung !== undefined && !rc.rungs.includes(rc.defaultRung))
       errors.push({
         path: `${at}.defaultRung`,
@@ -169,6 +183,11 @@ export function validateProfile(
   }
 
   const ladders = new Set(ROLES.filter((r) => p.roles[r].enabled).flatMap((r) => p.roles[r].rungs));
+  // the stand-ins catherd could run here, for the fixes below
+  const pool = catalogRungs(c).filter((x) => {
+    const r = tryParseRung(x);
+    return r !== null && backends.includes(r.backend);
+  });
   for (const [from, to] of Object.entries(p.failover)) {
     const at = `failover.${from}`;
     const a = tryParseRung(from);
@@ -193,6 +212,21 @@ export function validateProfile(
         message: `stand-in ${to} draws on the same quota as ${from}, which is out when ${from} hits its limit`,
         fix: "name a stand-in on another backend or plan",
       });
+    const ranked = rankStandIns(c, p.billing, from, pool);
+    const down = downgradeDims(c, from, to);
+    if (down.length)
+      warnings.push({
+        path: at,
+        message: `downgrade: ${to} stands in for ${from}, scoring below it on ${down.join(", ")}`,
+        fix: `catherd profile set failover.${from} ${ranked[0] ?? "null"}`,
+      });
+    const other = ranked.find((x) => !claudeBilled(x));
+    if (claudeBilled(to) && other)
+      warnings.push({
+        path: at,
+        message: `stand-in ${to} spends Claude quota, while ${other} could stand in on another plan`,
+        fix: `catherd profile set failover.${from} ${other}`,
+      });
     if (b.backend === "claude")
       warnings.push({
         path: at,

package/src/domain/profile.ts

@@ -43,6 +43,7 @@ const RoleDocSchema = z.looseObject({
   access: z.string().optional(),
   rungs: z.array(z.string()).optional(),
   defaultRung: z.string().optional(),
+  network: z.boolean().optional(),
 });
 
 export const ProfileDocSchema = z.looseObject({
@@ -113,6 +114,8 @@ export type RoleConfig = {
   /** in ladder order, each `backend:model#effort`; `claude:` runs as a native subagent, `claude-code:` headless */
   rungs: string[];
   defaultRung?: string;
+  /** spec §5: false drops a workspace-write role's network, loopback and Docker grants; absent means granted */
+  network?: false;
 };
 
 /** A profile with every default filled in: what the run engine, the CLI and the agent files read. */
@@ -155,15 +158,15 @@ export const BUILTIN_ROLES: Record<Role, RoleConfig> = {
 };
 
 /**
- * Spec §7.2: each Codex rung fails over to the best-matching OpenCode Go model. Go serves GPT-6 Luna
- * itself; for Sol it has no GPT model, so Kimi K3 stands in through a shipped treat-like (scores.json),
- * which `profile show` marks inferred.
+ * Spec 1.1 §11: each shipped worker rung fails over to the best stand-in the shipped catalog offers
+ * (`rankStandIns` over `catalogRungs`, pinned by test/domain/failover.test.ts): on another quota, paid
+ * from a plan, and no downgrade on the dims the rung's bars use. Go serves GPT-6 Luna itself; Kimi K3
+ * borrows Sol medium's scores (a shipped treat-like). Sol high and xhigh have no such stand-in on the
+ * owner's plans, so they have none: a limit on them pauses the lane instead of dropping it a tier.
  */
 export const DEFAULT_FAILOVER: Record<string, string> = {
   [LUNA_HIGH]: "opencode:opencode-go/gpt-6-luna#high",
   [SOL("medium")]: "opencode:opencode-go/kimi-k3#max",
-  [SOL("high")]: "opencode:opencode-go/kimi-k3#max",
-  [SOL("xhigh")]: "opencode:opencode-go/kimi-k3#max",
 };
 
 /** The five billing keys spec §7.1 writes out; cursor and grok arrive with their backends. */
@@ -210,6 +213,7 @@ export function resolveProfile(doc: ProfileDoc, name: string): Profile {
             : STORED_FALLBACK.access,
       rungs: [...(d?.rungs ?? b.rungs)],
       ...(defaultRung ? { defaultRung } : {}),
+      ...(d?.network === false ? { network: false as const } : {}),
     };
   }
   const harness: Profile["harness"] = {};
@@ -247,13 +251,15 @@ export function agentName(profile: string, role: Role, rung: string): string {
 }
 
 // Patches: what profile_set and `catherd profile set` accept. Strict at every level, so a misspelt key is
-// refused with E_INPUT_INVALID instead of dropped (plan-2 review m9). `null` removes a map entry.
+// refused with E_INPUT_INVALID instead of dropped (plan-2 review m9). `null` removes a map entry or a nullable
+// field (a role's `network` among them: absent means granted).
 const RolePatchSchema = z
   .strictObject({
     enabled: z.boolean(),
     access: z.enum(ACCESS),
     rungs: z.array(RungSchema),
     defaultRung: RungSchema.nullable(),
+    network: z.boolean().nullable(),
   })
   .partial();
 

package/src/domain/record.ts

@@ -71,6 +71,8 @@ export const RunRecordSchema = z.looseObject({
   images: z.array(z.string()),
   error: z.object({ code: z.string(), message: z.string() }).nullable(),
   replyPath: z.string(),
+  /** the Claude Code session that dispatched it, copied from admit.json (spec §3.3); absent before 1.1 */
+  sessionId: z.string().optional(),
 });
 export type RunRecord = z.infer<typeof RunRecordSchema>;
 

package/src/domain/role-prompts.ts

@@ -53,7 +53,11 @@ const architect = [
 const verifier = [
   "You verify work you did not write. You get the acceptance lines, the check command and how to run the thing. You do not get the author's account of it, and you should not look for one.",
   "",
-  "1. Run the check command once. Report its exit code and the failing lines.",
+  "1. Run the check command once. Report its exit code and the failing lines. When the check has several gate items (suites, lint, builds, a boot check):",
+  "   - Before each item, call the catherd MCP tool gate_check (mcp__plugin_catherd_catherd__gate_check) with the run id, the milestone you verify (M1, as your brief names it), the item, its command and the repo paths it depends on. When it answers carried: true, do not run the item: report it as carried over from its commit. It also tells the orchestrator which step you are on.",
+  "   - After an item passes, call gate_pass (mcp__plugin_catherd_catherd__gate_pass) with the same item, command and paths, and the evidence.",
+  "   - Run independent items side by side, each heavy one wrapped in catherd lock, which queues them within the machine's slots.",
+  "   - Build each commit's images once, and reuse them for the boot check and the acceptance suite.",
   "2. Exercise every acceptance line through the real entry point: the CLI, the HTTP route, the page. Read source only to find that entry point. When a line needs data or files, build them in a temporary directory outside the project.",
   "3. Read the diff (git diff plus untracked files) for bugs the acceptance lines miss: wrong edge behavior, dead code, leftovers.",
   "",
@@ -62,6 +66,7 @@ const verifier = [
   "Return, in this order:",
   "- VERDICT: PASS or VERDICT: FAIL on the first line.",
   "- One line per acceptance line: A<n> PASS|FAIL, the command you ran and the decisive output.",
+  "- One line per gate item: PASS|FAIL, or carried over from <commit>.",
   "- Bugs outside the acceptance lines: file:line, what happens, the input that triggers it.",
   "- What you could not check, and why.",
 ].join("\n");
@@ -134,6 +139,33 @@ const BODIES: Record<Role, (version: string) => string> = {
   researcher: () => researcher,
 };
 
+const STATUS_LINE =
+  "The last line of your reply is: STATUS: complete|partial|blocked|refused — <one line why>";
+
+/**
+ * Spec 1.1 §6: the reply contract `dispatch` appends to every brief it writes, the tail of the role's
+ * prompt: reply length and the STATUS line. The architect and the verifier keep their own reply shapes.
+ */
+const CONTRACTS: Record<Role, string> = {
+  architect: `Reply briefly: the milestones, each with its lanes as Mx.Ly — one line — owned files, and the full-check command. ${STATUS_LINE}`,
+  verifier: `The first line of your reply is VERDICT: PASS or VERDICT: FAIL. ${STATUS_LINE}`,
+  worker: REPLY,
+  reviewer: REPLY,
+  "ui-reviewer": REPLY,
+  artist: REPLY,
+  writer: REPLY,
+  researcher: `For a single question, reply in at most 15 lines. ${STATUS_LINE}`,
+};
+
+export const replyContract = (role: Role): string => CONTRACTS[role];
+
+/** `brief` with the role's reply contract as its last paragraph, once: a brief that already ends with it is kept. */
+export function withReplyContract(role: Role, brief: string): string {
+  const contract = CONTRACTS[role];
+  const body = brief.trimEnd();
+  return body.endsWith(contract) ? `${body}\n` : `${body}\n\n${contract}\n`;
+}
+
 /** The role's prompt; the worker's names the catherd version whose `lock` it must use. */
 export const rolePrompt = (role: Role, version: string): string => BODIES[role](version);
 

package/src/domain/state.ts

@@ -1,3 +1,15 @@
+const PARKED = /^parked: [^;]*; /;
+
+/**
+ * Spec 1.1 §8: `next` with the parked milestones in front of it, once ("parked: M2 waits on the owner;
+ * <next>"), whoever wrote the step: a milestone stays parked in state.md until it is answered.
+ */
+export function withParked(next: string, parked: string[]): string {
+  const base = next.replace(PARKED, "");
+  if (parked.length === 0) return base;
+  return `parked: ${parked.join(", ")} ${parked.length > 1 ? "wait" : "waits"} on the owner; ${base}`;
+}
+
 export interface StateView {
   title: string;
   head: string;
@@ -5,9 +17,11 @@ export interface StateView {
   running: { name: string; rung: string; thread: string | null; since: string; brief: string }[];
   lastCheck: string | null;
   next: string;
+  /** spec 1.1 §10: the protocol's next step, derived from the run's files; always the last line */
+  protocol: string;
 }
 
-/** state.md: enough for a fresh session to resume from alone; the next step is always the last line. */
+/** state.md: enough for a fresh session to resume from alone; the protocol's next step is always the last line. */
 export function renderState(s: StateView): string {
   const waiting = s.running.map((r) => r.name);
   return [
@@ -27,7 +41,9 @@ export function renderState(s: StateView): string {
     "",
     `Last check: ${s.lastCheck ?? "none"}`,
     "",
-    `Next: ${waiting.length ? `wait for ${waiting.join(", ")}; then ${s.next}` : s.next}`,
+    // 1.1: no tool waits; each running role's record arrives as a catherd message
+    `Next: ${waiting.length ? `running ${waiting.join(", ")} (results arrive as catherd messages; peek to check); then ${s.next}` : s.next}`,
+    `Protocol next: ${s.protocol}`,
     "",
   ].join("\n");
 }

package/src/entry/deps.ts

@@ -1,3 +1,4 @@
+import { readSessionEnv } from "../infra/claude-session.ts";
 import { VERSION } from "../infra/version.ts";
 import type { Deps } from "../services/ports.ts";
 import { profileService } from "../services/profile-service.ts";
@@ -10,7 +11,7 @@ export function defaultDeps(): Deps {
     routing: routingService(),
     version: VERSION,
     pollMs: 250,
-    tickMs: Number(process.env.CATHERD_TICK_MS) || 30_000,
+    session: readSessionEnv(process.env),
     now: Date.now,
   };
 }

package/src/entry/doctor-command.ts

@@ -1,6 +1,7 @@
 import { defineCommand } from "citty";
 import { VERSION } from "../infra/version.ts";
 import { type DoctorReport, doctor } from "../services/doctor.ts";
+import { probePush } from "../services/doctor-push.ts";
 import type { Check } from "../services/doctor-checks.ts";
 import { EXIT, JSON_ARG, mark, printJson } from "./cli-kit.ts";
 import { mcpHandshake } from "./mcp/handshake.ts";
@@ -37,7 +38,12 @@ export const doctorCommand = defineCommand({
     plain: { type: "boolean", description: "ASCII glyphs (NO_COLOR drops only colour)" },
   },
   async run({ args }) {
-    const r = await doctor({ bunVersion: Bun.version, version: VERSION, handshake: () => mcpHandshake() });
+    const r = await doctor({
+      bunVersion: Bun.version,
+      version: VERSION,
+      handshake: () => mcpHandshake(),
+      push: () => probePush(),
+    });
     if (args.json) printJson(r);
     else for (const l of formatReport(r, args.plain === true)) console.log(l);
     process.exitCode = r.ready ? EXIT.ok : EXIT.notReady;

package/src/entry/glyphs.ts

@@ -7,6 +7,7 @@ const GLYPHS = {
   warn: ["!", "!"],
   fail: ["✗", "x"],
   skip: ["-", "-"],
+  info: ["i", "i"],
   live: ["●", "*"],
   waiting: ["◌", "."],
   on: ["[x]", "[x]"],
@@ -30,4 +31,4 @@ export const GLYPH_NAMES = Object.keys(GLYPHS) as Glyph[];
 export const glyph = (g: Glyph, plain: boolean): string => GLYPHS[g][plain ? 1 : 0];
 
 /** The words state always travels with (spec §9.3: green/amber/red only for state, always with a word). */
-export type State = "ok" | "warn" | "fail" | "skip";
+export type State = "ok" | "warn" | "fail" | "skip" | "info";

package/src/entry/init-command.ts

@@ -5,6 +5,8 @@ import { configDir } from "../infra/paths.ts";
 import { VERSION } from "../infra/version.ts";
 import { doctor } from "../services/doctor.ts";
 import { jevKey, saveJevKey, testJevKey } from "../services/jev-service.ts";
+import { reinstallCommand } from "../services/doctor-checks.ts";
+import { ensureGlobal, type GlobalInstallDeps, realGlobalInstall } from "../services/global-install.ts";
 import { hasProfileFile, type InitResult, initSetup, moveLegacy } from "../services/setup.ts";
 import { formatRefreshed } from "./catalog-command.ts";
 import { mark as markOf } from "./cli-kit.ts";
@@ -63,6 +65,38 @@ export async function jevStep(
   }
 }
 
+/**
+ * Spec 1.1 §12: installs the global CLI at this version (the plugin's launcher then needs no bunx), and
+ * says "installing catherd…" before the resolve. It never stops `init`: a failure is a `!` line and its fix.
+ */
+export async function globalStep(
+  version: string,
+  o: { skip: boolean; deps?: GlobalInstallDeps; plain?: boolean },
+): Promise<void> {
+  const mark = (state: State) => markOf(state, o.plain === true);
+  if (o.skip)
+    return console.log(`- catherd: not installed globally (--no-global); the plugin starts it with bunx`);
+  const r = await ensureGlobal(version, o.deps ?? realGlobalInstall, () =>
+    console.log(`installing catherd… (${reinstallCommand(version)})`),
+  );
+  if (r.state === "current") return console.log(`${mark("ok")} catherd ${version} is installed globally`);
+  if (r.state === "installed")
+    return console.log(
+      `${mark("ok")} catherd ${version} installed globally; the plugin starts it without bunx`,
+    );
+  if (r.state === "shadowed") {
+    const found = r.onPath === null ? "no catherd is on PATH" : `the catherd first on PATH is ${r.onPath}`;
+    console.log(
+      `${mark("warn")} catherd ${version} installed globally, but ${found}, so the plugin starts it with bunx`,
+    );
+    return console.log(
+      `    fix: put bun's global bin folder (bun pm bin -g) first on PATH, then run catherd init again`,
+    );
+  }
+  console.log(`${mark("warn")} could not install catherd globally: ${r.reason}`);
+  console.log(`    fix: ${reinstallCommand(version)}`);
+}
+
 /** What happened to the profile: written, kept, or (when the defaults do not validate here) why not. */
 export function profileLines(r: InitResult, plain = false): string[] {
   const mark = (state: State) => markOf(state, plain);
@@ -90,11 +124,16 @@ export const initCommand = defineCommand({
   meta: {
     name: "init",
     description:
-      "First run: the Jev key, the default profile, its agents, and a readiness report. Piped, it reads the answers from stdin one per line, a line per question even when this machine skips it (the Jev key, the profile, whether to replace it), and waits for stdin to close; --no-input asks nothing",
+      "First run: the global catherd command, the Jev key, the default profile, its agents, and a readiness report. Piped, it reads the answers from stdin one per line, a line per question even when this machine skips it (the Jev key, the profile, whether to replace it), and waits for stdin to close; --no-input asks nothing",
   },
   args: {
     // citty reads --no-input as input: false, whatever the flag is named; naming it no-input shows it as is
     "no-input": { type: "boolean", description: "ask nothing: keep what exists, else write the defaults" },
+    // read as global: false, like no-input above
+    "no-global": {
+      type: "boolean",
+      description: "do not install the global catherd command (bun add -g catherd-cli@<this version>)",
+    },
     profile: { type: "string", description: "the profile to set up and make active (default: default)" },
     plain: { type: "boolean", description: "ASCII glyphs (NO_COLOR drops only colour)" },
   },
@@ -107,6 +146,7 @@ export const initCommand = defineCommand({
     try {
       if (process.stdout.isTTY) for (const line of welcomeLines(VERSION)) console.log(line);
       console.log(`catherd ${VERSION}: setting up in ${configDir()}`);
+      await globalStep(VERSION, { skip: (args as { global?: boolean }).global === false, plain });
       await jevStep(ask, {}, plain);
       if (args.profile !== undefined) ask?.skip?.();
       const name = assertProfileName(

package/src/entry/mcp/command.ts

@@ -1,7 +1,11 @@
 import { defineCommand } from "citty";
+import { restoreTmpdir } from "../../infra/env.ts";
 import { startMcpServer } from "./server.ts";
 
 export const mcpCommand = defineCommand({
   meta: { name: "mcp", description: "Run the catherd MCP server over stdio" },
-  run: () => startMcpServer(),
+  run: () => {
+    restoreTmpdir(process.env);
+    return startMcpServer();
+  },
 });

package/src/entry/mcp/dispatch-tools.ts

@@ -2,37 +2,17 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { ID_PATTERN } from "../../domain/ids.ts";
 import { ROLES } from "../../domain/roles.ts";
-import { cancel, dispatch, type Progress, wait } from "../../services/dispatch-service.ts";
+import { cancel, dispatch } from "../../services/dispatch-service.ts";
+import { peek } from "../../services/peek.ts";
 import type { Deps } from "../../services/ports.ts";
 import { handle } from "./result.ts";
 
-type Notify = (n: {
-  method: "notifications/progress";
-  params: { progressToken: string | number; progress: number; message: string };
-}) => Promise<void>;
-
-/** Progress notifications that can never fail a wait: the client may be gone (audit C8). */
-export function progressTo(token: string | number | undefined, send: Notify): Progress | undefined {
-  if (token === undefined) return undefined;
-  let n = 0;
-  return (message) => {
-    try {
-      send({
-        method: "notifications/progress",
-        params: { progressToken: token, progress: ++n, message },
-      }).catch(() => {}); // the client is gone: progress is best effort
-    } catch {
-      // the transport is closed
-    }
-  };
-}
-
 export function registerDispatchTools(server: McpServer, deps: Deps): void {
   server.registerTool(
     "dispatch",
     {
       description:
-        "Start one role on a process backend (codex, claude-code, opencode) and return at launch, in about a second, with { dispatched: { name, role, rung, dispatchId, admittedAt }, hints }; the role runs on, and wait(run) collects its record. Dispatch every independent role one after another, then call wait. The brief is the text itself. With lane, the lane file's Owns: paths guard against overlapping lanes. thread resumes that role's thread for its own fix round. Refused with a structured error (E_ADMIT_*, E_RUN_BUDGET, E_BACKEND_*) before anything starts. Call it from the main thread.",
+        "Start one role on a process backend (codex, claude-code, opencode) and return at launch, in about a second, with { dispatched: { name, role, rung, dispatchId, admittedAt }, hints }; the role runs on. When it finishes, catherd sends this session a <cross-session-message from-name=\"catherd\"> naming the run, the role and its status, and result(run, name) reads the record. Dispatch every independent role one after another, then end your turn. The brief is the text itself; dispatch appends the role's reply contract (reply length and the STATUS line), so do not write it. With lane, the lane file's Owns: paths guard against overlapping lanes, and a lane not yet routed is routed first (a rung off its routed ladder starts at the routed rung, with a hint). thread resumes that role's thread for its own fix round. Refused with a structured error (E_ADMIT_*, E_RUN_BUDGET, E_BACKEND_*) before anything starts. Call it from the main thread.",
       inputSchema: {
         run: z.string(),
         role: z.enum(ROLES),
@@ -48,35 +28,25 @@ export function registerDispatchTools(server: McpServer, deps: Deps): void {
   );
 
   server.registerTool(
-    "wait",
+    "peek",
     {
       description:
-        "Block until at least one of the run's uncollected dispatches has finished (only those in names, when given; every one of them with all: true), reporting progress meanwhile, and return { records, started, running, hints }. records holds each finished role's { record, hints }, in the order they finished, each returned by one wait only; a role that hit a usage limit has its failover stand-in launched, listed in started. running names every uncollected role this call did not return, still running or already finished, stand-ins included: act on the records, then wait again while running is not empty. Returns at once, with a hint, when nothing is uncollected. Call it from the main thread.",
+        "A look at the runs, without waiting: with run, that run (and this session becomes its owner); without, every run this session owns, else the newest. Per run, first the open owner questions, which are the owner's questions: push them to the owner, relay the owner's answer with answer(run, milestone, answer), and go on with the work that does not depend on them. Then each live role with its rung, seconds since it started and its last event (the last command, file edit or message line); every finished record not yet read, as the first line of catherd's message; the latest native Claude run; the run's next step; protocol, the milestone loop's next step and its six-line checklist; and verifier, the verifier's latest gate step. name narrows it to one role. It never marks a record read: result(run, name) does. Call it when the user asks how it is going, when a decision needs the other roles' state, or once after run_start on a resumed run; never in a loop.",
       inputSchema: {
-        run: z.string(),
-        names: z.array(z.string().regex(ID_PATTERN)).optional(),
-        all: z.boolean().optional(),
+        run: z.string().optional(),
+        name: z.string().regex(ID_PATTERN).optional(),
       },
     },
-    (a, extra) =>
-      handle(() =>
-        wait(
-          deps,
-          a,
-          progressTo(extra._meta?.progressToken, (n) => extra.sendNotification(n)),
-          // a wait its caller cancelled collects nothing: the record would go to no one
-          extra.signal,
-        ),
-      ),
+    (a) => handle(() => peek(deps, a)),
   );
 
   server.registerTool(
     "cancel",
     {
       description:
-        "Stop a live dispatch (interrupt, then SIGTERM, then SIGKILL) and return its record, marked cancelled, and hints.",
+        "Stop a live dispatch (interrupt, then SIGTERM, then SIGKILL) and return its record, marked cancelled and read, and hints.",
       inputSchema: { run: z.string(), name: z.string().regex(ID_PATTERN) },
     },
-    (a) => handle(() => cancel(deps, a.run, a.name)),
+    (a) => handle(() => cancel(deps, a.run, a.name, { read: true })),
   );
 }

package/src/entry/mcp/handshake.ts

@@ -6,27 +6,37 @@ import { scrubSecrets } from "../../infra/env.ts";
 import { VERSION } from "../../infra/version.ts";
 import type { Handshake } from "../../services/doctor.ts";
 
-const CLI = fileURLToPath(new URL("../../cli.ts", import.meta.url));
-const TIMEOUT_MS = 20_000;
+/** The plugin's MCP launcher, shipped in the package beside src/ (spec 1.1 §12). */
+export const LAUNCHER = fileURLToPath(new URL("../../../plugin/bin/catherd-mcp", import.meta.url));
+/** A cold `bunx catherd-cli@<version>` resolve took about 30 s in the 1.0.0 fresh install. */
+const TIMEOUT_MS = 60_000;
+const STDERR_TAIL = 4_000;
 
 /** The env the doctor's MCP server starts with: catherd's own secrets scrubbed, as for every process it starts. */
 export const handshakeEnv = (
   base: Record<string, string | undefined> = process.env,
 ): Record<string, string> => scrubSecrets(base);
 
-/** Spec §10.3: starts `catherd mcp` over stdio, as Claude Code would, and asks it for tools/list. */
-export async function mcpHandshake(): Promise<Handshake> {
+/**
+ * Spec §10.3 and 1.1 §12: starts the MCP server the way the plugin does, `sh <launcher>` over stdio, and
+ * asks it for tools/list. What it writes to stderr comes back too, so doctor can say what broke.
+ */
+export async function mcpHandshake(o: { launcher?: string } = {}): Promise<Handshake> {
   const client = new Client({ name: "catherd-doctor", version: VERSION });
   const transport = new StdioClientTransport({
-    command: process.execPath,
-    args: [CLI, "mcp"],
+    command: "sh",
+    args: [o.launcher ?? LAUNCHER],
     env: handshakeEnv(),
-    stderr: "ignore",
+    stderr: "pipe",
+  });
+  let stderr = "";
+  transport.stderr?.on("data", (b: Buffer) => {
+    stderr = (stderr + b.toString()).slice(-STDERR_TAIL);
   });
   let timer: ReturnType<typeof setTimeout> | undefined;
   const late = new Promise<Handshake>((resolve) => {
     timer = setTimeout(
-      () => resolve({ ok: false, tools: [], error: `no answer within ${TIMEOUT_MS / 1000} s` }),
+      () => resolve({ ok: false, tools: [], error: `no answer within ${TIMEOUT_MS / 1000} s`, stderr }),
       TIMEOUT_MS,
     );
   });
@@ -40,7 +50,7 @@ export async function mcpHandshake(): Promise<Handshake> {
       late,
     ]);
   } catch (e) {
-    return { ok: false, tools: [], error: errorMessage(e) };
+    return { ok: false, tools: [], error: errorMessage(e), stderr };
   } finally {
     clearTimeout(timer);
     await client.close().catch(() => {}); // the answer (or the failure) is already in hand

package/src/entry/mcp/lane-tools.ts

@@ -3,7 +3,7 @@ import { z } from "zod";
 import { ID_PATTERN } from "../../domain/ids.ts";
 import { ROLES } from "../../domain/roles.ts";
 import { CLIMB_REASONS } from "../../domain/route.ts";
-import { ask, climb, land, route } from "../../services/lane-service.ts";
+import { ask, climb, LAND_SKIPS, land, route } from "../../services/lane-service.ts";
 import type { Deps } from "../../services/ports.ts";
 import { preflight } from "../../services/preflight.ts";
 import { handle } from "./result.ts";
@@ -13,7 +13,7 @@ export function registerLaneTools(server: McpServer, deps: Deps): void {
     "route",
     {
       description:
-        "The rung for a lane (from Jev, else the lane file's Kind/Difficulty lines, else the profile default) or, without a lane file, a role's default rung, with the ladder above it. Rungs are backend:model#effort; a claude: rung comes with the agent to run it as.",
+        "The rung for a lane (from Jev, else the lane file's Kind/Difficulty lines, else the profile default) or, without a lane file, a role's default rung, with the ladder above it. Rungs are backend:model#effort; a claude: rung comes with the agent to run it as. A lane whose Kind: or Difficulty: the catalog does not know is refused with E_LANE_INVALID.",
       inputSchema: {
         run: z.string(),
         lane_file: z.string().optional(),
@@ -27,7 +27,7 @@ export function registerLaneTools(server: McpServer, deps: Deps): void {
     "preflight",
     {
       description:
-        "Run each lane's fast check once, on the base tree, behind the heavy-command lock, with a 120 s timeout. Each lane is pass, fails-as-expected, skipped (it checks a file the lane creates) or cannot-start; only cannot-start blocks. When the profile asks for confirmation, the first call returns the commands to show the user; call again with confirmed: true.",
+        "Run each lane's fast check once, on the base tree, behind the heavy-command lock, with a 120 s timeout. Each lane is pass, fails-as-expected, skipped (it checks a file the lane creates) or cannot-start; only cannot-start blocks. When the profile asks for confirmation, the first call returns the commands to show the user; call again with confirmed: true. Refused with E_LANE_INVALID, running nothing, while any lane's Kind: or Difficulty: is not one the catalog knows.",
       inputSchema: { run: z.string(), confirmed: z.boolean().optional() },
     },
     (a) => handle(() => preflight(deps, { run: a.run, confirmed: a.confirmed })),
@@ -37,7 +37,7 @@ export function registerLaneTools(server: McpServer, deps: Deps): void {
     "climb",
     {
       description:
-        "Move a routed lane one rung up its ladder and record why. Returns the next rung, or top: true, and any hints. Dispatch the lane again at that rung on a fresh thread. Pass env: true when the environment caused it (a missing service, a broken tool, a usage limit), not the rung.",
+        "Move a routed lane one rung up its ladder and record why. Returns the next rung, or top: true, and any hints. Dispatch the lane again at that rung on a fresh thread. Pass env: true when the environment caused it (a missing service, a broken tool, a usage limit), not the rung. Refused with E_CLIMB_DESIGN when the evidence is a design question (Jev's finding answer is design, or a blocked climb's evidence is about lane ownership): send it to the architect instead.",
       inputSchema: {
         run: z.string(),
         lane: z.string().regex(ID_PATTERN),
@@ -67,15 +67,16 @@ export function registerLaneTools(server: McpServer, deps: Deps): void {
     "land",
     {
       description:
-        "Record a landed milestone after you commit it: its five-column ledger row (with the minutes it took) and state.md's last check and next step, with any hints. learned, when given, goes to this repo's knowledge.md.",
+        "Record a landed milestone after you commit it: its five-column ledger row (with the minutes it took) and state.md's last check and next step, with any hints. learned, when given, goes to this repo's knowledge.md. Returns digest: the milestone's digest (R/digests/<milestone>.md: A-lines, commit, lanes with rungs and climbs, reviewer findings, the verifier's verdict with carried items, minutes and tokens), for the milestone push to link. Refused with E_LAND_GATE unless, since the milestone's lanes started, a reviewer named reviewer-<milestone> ended ok (a dispatch, or a Claude subagent recorded with record_agent_run, role reviewer) and a verifier verdict naming the milestone was recorded ok (record_agent_run, role verifier; a headless verifier's reply opening VERDICT: PASS). A skip over an empty commit range is refused: commit first. skip: docs-only lands a milestone whose commit range changed only docs; skip: no-code one that changed no source file (put the evidence, e.g. a green pipeline, in evidence).",
       inputSchema: {
         run: z.string(),
-        milestone: z.string().min(1),
+        milestone: z.string().regex(ID_PATTERN),
         what: z.string().min(1),
         commit: z.string().regex(/^[0-9a-f]{7,40}$/),
         evidence: z.string().min(1),
         next: z.string().min(1),
         learned: z.string().min(1).optional(),
+        skip: z.enum(LAND_SKIPS).optional(),
       },
     },
     (a) => handle(() => land(deps, a)),