catherd-cli 1.4.0 → 1.5.0

package/src/entry/doctor-command.ts

@@ -1,11 +1,13 @@
 import { gitToplevel } from "../infra/git.ts";
-import { HOST_ARG, terminalHost } from "./host-arg.ts";
+import { CatherdError } from "../domain/errors.ts";
+import { HOST_ARG, terminalHost, withThread } from "./host-arg.ts";
 import { defineCommand } from "citty";
 import { VERSION } from "../infra/version.ts";
 import { type DoctorReport, doctor } from "../services/doctor.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";
+import { probeRoleServer } from "../infra/role-mcp.ts";
 
 /**
  * One row per check: `✓ ready  Bun — 1.4.2`, then the full fix on its own line; a fix of several lines
@@ -42,16 +44,32 @@ export const doctorCommand = defineCommand({
       description:
         "send one labeled smoke to the validated original session (receipt does not prove processing)",
     },
+    thread: {
+      type: "string",
+      description:
+        "with --test-push: the Codex thread to send the smoke to (Codex does not export it to the commands it runs)",
+    },
+    docker: {
+      type: "boolean",
+      description:
+        "also probe Docker as a gate sees it: two compose services reaching each other by name, and the free disk (pulls busybox)",
+    },
     plain: { type: "boolean", description: "ASCII glyphs (NO_COLOR drops only colour)" },
   },
   async run({ args }) {
+    if (args.thread !== undefined && args["test-push"] !== true)
+      throw new CatherdError("E_INPUT_INVALID", "--thread only names where --test-push sends its smoke", {
+        fix: `catherd doctor --test-push --thread ${args.thread}`,
+      });
     const r = await doctor({
-      host: terminalHost(args.host),
+      host: withThread(terminalHost(args.host), args.thread),
       repo: await gitToplevel(process.cwd()),
       bunVersion: Bun.version,
       version: VERSION,
       handshake: () => mcpHandshake(),
+      roleServerStart: () => probeRoleServer(),
       testPush: args["test-push"] === true,
+      docker: args.docker === true,
     });
     if (args.json) printJson(r);
     else for (const l of formatReport(r, args.plain === true)) console.log(l);

package/src/entry/host-arg.ts

@@ -10,6 +10,34 @@ export const HOST_ARG = {
   },
 };
 
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Plan 22, `doctor --test-push --thread <uuid>`: Codex does not export its thread id to the commands it runs, so a
+ * shell names the thread the smoke goes to. It makes the host that Codex thread; a Claude Code session refuses it.
+ */
+export function withThread(host: HostContext, thread: string | undefined): HostContext {
+  if (thread === undefined) return host;
+  if (!UUID.test(thread))
+    throw new CatherdError("E_INPUT_INVALID", `--thread ${thread} is not a Codex thread id`, {
+      fix: "pass the thread's UUID, as the first line of a catherd message names it (thread: <uuid>)",
+    });
+  if (host.host === "claude-code")
+    throw new CatherdError(
+      "E_INPUT_INVALID",
+      "--thread names a Codex thread, and this is a Claude Code session",
+      {
+        fix: "run catherd doctor --test-push without --thread from Claude Code",
+      },
+    );
+  const sessionId = thread.toLowerCase();
+  return {
+    host: "codex",
+    session: { host: "codex", sessionId, hostSessionId: null, name: null },
+    conflict: null,
+  };
+}
+
 export function terminalHost(value: string | undefined, env = process.env): HostContext {
   if (value === undefined || value === "auto") return resolveHost({ env });
   if (value !== "codex" && value !== "claude-code")

package/src/entry/init-command.ts

@@ -15,7 +15,7 @@ import { ensureGlobal, type GlobalInstallDeps, realGlobalInstall } from "../serv
 import { hasProfileFile, type InitResult, initSetup, moveLegacy } from "../services/setup.ts";
 import { activeName } from "../services/profile-store.ts";
 import { formatRefreshed, syncLines } from "./catalog-command.ts";
-import { mark as markOf } from "./cli-kit.ts";
+import { mark as markOf, refuseInRole } from "./cli-kit.ts";
 import { formatReport } from "./doctor-command.ts";
 import { mcpHandshake } from "./mcp/handshake.ts";
 import type { State } from "./glyphs.ts";
@@ -213,6 +213,7 @@ export const initCommand = defineCommand({
     plain: { type: "boolean", description: "ASCII glyphs (NO_COLOR drops only colour)" },
   },
   async run({ args }) {
+    refuseInRole(process.env, "catherd init");
     // a bad --profile is refused before any question is asked
     if (args.profile !== undefined) assertProfileName(args.profile);
     const ask = (args as { input?: boolean }).input === false ? null : await prompter();

package/src/entry/knowledge-command.ts

@@ -1,7 +1,9 @@
 import { resolve } from "node:path";
 import { defineCommand } from "citty";
+import { CatherdError } from "../domain/errors.ts";
+import { gateEnvLines, readGateEnv, removeGateEnv, setGateEnv } from "../services/gate-env.ts";
 import { addKnowledge, knowledgeLines, knowledgePath, readKnowledge } from "../services/run-service.ts";
-import { JSON_ARG, printJson } from "./cli-kit.ts";
+import { JSON_ARG, printJson, refuseInRole } from "./cli-kit.ts";
 
 /** `--repo`, else the repository the command runs in, as run_start and read_knowledge resolve it. */
 const REPO_ARG = {
@@ -29,6 +31,7 @@ const add = defineCommand({
     ...REPO_ARG,
   },
   async run({ args }) {
+    refuseInRole(process.env, "catherd knowledge add");
     console.log(await addKnowledge(repoOf(args.repo), args.line));
   },
 });
@@ -43,8 +46,80 @@ const path = defineCommand({
   },
 });
 
+/** `NAME=value` as name and value; null when it has no `=`. */
+function assignment(raw: string): { name: string; value: string } | null {
+  const eq = raw.indexOf("=");
+  return eq > 0 ? { name: raw.slice(0, eq), value: raw.slice(eq + 1) } : null;
+}
+
+const envSet = defineCommand({
+  meta: {
+    name: "set",
+    description:
+      "Set one variable of the repo's gate environment, which the verifier and preflight run with: NAME=value, or NAME --from ENV_VAR for a secret (stored by reference, read when a role starts)",
+  },
+  args: {
+    variable: { type: "positional", required: true, description: "NAME=value, or NAME with --from" },
+    from: { type: "string", description: "the env var that holds the secret value" },
+    ...REPO_ARG,
+    ...JSON_ARG,
+  },
+  async run({ args }) {
+    refuseInRole(process.env, "catherd knowledge env set");
+    const set = assignment(args.variable);
+    if (args.from !== undefined && set)
+      throw new CatherdError("E_INPUT_INVALID", "pass NAME=value or NAME --from ENV_VAR, not both", {
+        fix: "catherd knowledge env set DOCKER_HOST=unix:///var/run/docker.sock",
+      });
+    if (args.from === undefined && !set)
+      throw new CatherdError("E_INPUT_INVALID", `"${args.variable}" has no value`, {
+        fix: "catherd knowledge env set NAME=value, or catherd knowledge env set NAME --from ENV_VAR",
+      });
+    const r = set
+      ? await setGateEnv(repoOf(args.repo), set.name, { value: set.value })
+      : await setGateEnv(repoOf(args.repo), args.variable, { from: args.from as string });
+    if (args.json) return printJson(r);
+    for (const line of gateEnvLines(r.vars)) console.log(line);
+  },
+});
+
+const envRm = defineCommand({
+  meta: { name: "rm", description: "Remove one variable from the repo's gate environment" },
+  args: { name: { type: "positional", required: true }, ...REPO_ARG, ...JSON_ARG },
+  async run({ args }) {
+    refuseInRole(process.env, "catherd knowledge env rm");
+    const r = await removeGateEnv(repoOf(args.repo), args.name);
+    if (args.json) return printJson(r);
+    for (const line of gateEnvLines(r.vars)) console.log(line);
+  },
+});
+
+const envList = defineCommand({
+  meta: { name: "list", description: "Print the repo's gate environment (a secret shows as $ENV_VAR)" },
+  args: { ...REPO_ARG, ...JSON_ARG },
+  async run({ args }) {
+    const at = await knowledgePath(repoOf(args.repo));
+    const vars = await readGateEnv(at.repo);
+    if (args.json) return printJson({ repo: at.repo, vars });
+    const lines = gateEnvLines(vars);
+    console.log(lines.length ? lines.join("\n") : "catherd: no gate environment set for this repo");
+  },
+});
+
+/** Plan 23: the repo's gate environment, beside its knowledge.md. */
+const env = defineCommand({
+  meta: {
+    name: "env",
+    description: "The repo's gate environment, which the verifier and preflight run with: set, rm or list",
+  },
+  subCommands: { set: envSet, rm: envRm, list: envList },
+});
+
 /** What past runs of a repo learned, which the read_knowledge tool gives every new run (spec §4.7). */
 export const knowledgeCommand = defineCommand({
-  meta: { name: "knowledge", description: "What catherd knows about a repo: show, add or path" },
-  subCommands: { show, add, path },
+  meta: {
+    name: "knowledge",
+    description: "What catherd knows about a repo: show, add or path, and its gate environment (env)",
+  },
+  subCommands: { show, add, path, env },
 });

package/src/entry/lock-command.ts

@@ -3,7 +3,8 @@ import { defineCommand } from "citty";
 import { CatherdError } from "../domain/errors.ts";
 import { scrubSecrets } from "../infra/env.ts";
 import { gitToplevel } from "../infra/git.ts";
-import { heavySlots, withHeavySlot } from "../infra/heavy-lock.ts";
+import { heavySlots, withHeavySlot, withRoleLock } from "../infra/heavy-lock.ts";
+import { activityReporter, DISPATCH_ID_ENV } from "../infra/lock-activity.ts";
 import { killGroup } from "../infra/proc.ts";
 import { activeName, readProfileDoc } from "../services/profile-store.ts";
 import { printError } from "./cli-kit.ts";
@@ -44,14 +45,26 @@ export const DOUBLE_INTERRUPT_MS = 2_000;
  * a terminal's Ctrl-C reaches catherd only, so the command sees it exactly once, and so does every
  * process it started. A second Ctrl-C within 2 s kills the group. Resolves to the command's exit code.
  */
-export async function runForwarding(argv: string[]): Promise<number> {
+export async function runForwarding(
+  argv: string[],
+  o: { onOutput?: () => void; extraEnv?: Record<string, string> } = {},
+): Promise<number> {
+  // plan 23: inside a dispatch the output passes through catherd, which notes when the command last wrote
+  const piped = o.onOutput !== undefined;
   const child = Bun.spawn(argv, {
     stdin: "inherit",
-    stdout: "inherit",
-    stderr: "inherit",
-    env: scrubSecrets(process.env),
+    stdout: piped ? "pipe" : "inherit",
+    stderr: piped ? "pipe" : "inherit",
+    env: { ...scrubSecrets(process.env), ...o.extraEnv },
     detached: true,
   });
+  const pumps =
+    piped && o.onOutput
+      ? [
+          pump(child.stdout as ReadableStream<Uint8Array>, process.stdout, o.onOutput),
+          pump(child.stderr as ReadableStream<Uint8Array>, process.stderr, o.onOutput),
+        ]
+      : [];
   let lastInt = 0;
   const handlers: [NodeJS.Signals, () => void][] = [
     [
@@ -80,15 +93,53 @@ export async function runForwarding(argv: string[]): Promise<number> {
     },
   );
   try {
-    return await child.exited;
+    const code = await child.exited;
+    // a process the command left behind may hold the pipes open: what it wrote by then is passed on
+    await Promise.race([Promise.all(pumps), Bun.sleep(PIPE_DRAIN_MS)]);
+    return code;
   } finally {
     watchdog.kill("SIGKILL");
     for (const [sig, h] of handlers) process.off(sig, h);
   }
 }
 
+/** How long the pipes may stay open after the command exits. */
+const PIPE_DRAIN_MS = 500;
+
+/** Copies a piped stream to `out`, calling `tick` for each chunk; a broken pipe ends the copy. */
+async function pump(
+  stream: ReadableStream<Uint8Array>,
+  out: NodeJS.WriteStream,
+  tick: () => void,
+): Promise<void> {
+  try {
+    for await (const chunk of stream) {
+      out.write(chunk);
+      tick();
+    }
+  } catch {
+    // the command's end closes the pipe
+  }
+}
+
 /** Spec §8: what `--help` and the usage error show; the command runs after `--`. */
-export const LOCK_USAGE = "catherd lock [--slots N] -- <command> [args...]";
+export const LOCK_USAGE = "catherd lock [--slots N] [--role verifier [--run <run>]] -- <command> [args...]";
+
+/** The roles that take a machine-wide role lock besides their slot (spec 1.5 "Cross-run verifier contention"). */
+export const ROLE_LOCKS = ["verifier"] as const;
+
+/**
+ * Whose a role lock is: `--run`, else the run in `CATHERD_ROLE` (`<run>/<role-name>`, which the supervisor
+ * sets in every role's env), else this process alone. Commands of one run share the lock.
+ */
+export function roleLockOwnerOf(run: string | undefined, env: NodeJS.ProcessEnv): string {
+  if (run) return `run:${run}`;
+  const fromRole = env.CATHERD_ROLE?.split("/")[0];
+  return fromRole ? `run:${fromRole}` : `process:${process.pid}`;
+}
+
+/** Set in a locked command's env: a `catherd lock` inside it runs at once, holding nothing more. */
+export const LOCK_HELD_ENV = "CATHERD_LOCK_HELD";
 
 export const lockCommand = defineCommand({
   meta: {
@@ -102,6 +153,15 @@ export const lockCommand = defineCommand({
       type: "string",
       description: "Slots (default: CATHERD_LOCK_SLOTS, else the profile's lock.heavy, else half the cores)",
     },
+    role: {
+      type: "string",
+      description:
+        "verifier: also hold the machine-wide verifier lock, shared by one run's commands, so two runs' verifiers never overlap",
+    },
+    run: {
+      type: "string",
+      description: "with --role: the run whose commands share it (default: CATHERD_ROLE's)",
+    },
   },
   async run({ args, rawArgs }) {
     const sep = rawArgs.indexOf("--");
@@ -115,6 +175,31 @@ export const lockCommand = defineCommand({
       process.exitCode = 2;
       return;
     }
+    if (args.role !== undefined && !(ROLE_LOCKS as readonly string[]).includes(args.role)) {
+      printError(
+        new CatherdError("E_INPUT_INVALID", `no role lock "${args.role}"`, {
+          fix: "catherd lock --role verifier -- <command>",
+        }),
+      );
+      process.exitCode = 2;
+      return;
+    }
+    // already inside a locked command: run at once, so a nested lock never waits on its own parent's slot
+    if (process.env[LOCK_HELD_ENV] === "1") {
+      process.exitCode = await runForwarding(argv);
+      return;
+    }
+    // plan 23: a role's lock reports its output, so the role's wall timeout counts from its last line; it
+    // reports while it waits for the role lock or a slot too, so a gate queued behind another run's is not
+    // killed before its first command
+    const activity = activityReporter(process.env[DISPATCH_ID_ENV]);
+    const waiting = activity ? { onWait: activity.tick } : {};
+    const run = () =>
+      runForwarding(argv, {
+        extraEnv: { [LOCK_HELD_ENV]: "1" },
+        ...(activity ? { onOutput: activity.tick } : {}),
+      });
+    const role = args.role;
     const repo = await gitToplevel(process.cwd());
     const slots = resolveSlots(
       args.slots,
@@ -123,6 +208,17 @@ export const lockCommand = defineCommand({
       () => readProfileDoc(activeName(repo)).lock?.heavy ?? "cpus/2",
       (m) => console.error(m),
     );
-    process.exitCode = await withHeavySlot(slots, () => runForwarding(argv));
+    try {
+      process.exitCode = role
+        ? await withRoleLock(
+            role,
+            roleLockOwnerOf(args.run, process.env),
+            () => withHeavySlot(slots, run, waiting),
+            waiting,
+          )
+        : await withHeavySlot(slots, run, waiting);
+    } finally {
+      activity?.done();
+    }
   },
 });

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

@@ -12,13 +12,13 @@ export function registerDispatchTools(server: McpServer, deps: Deps): void {
     "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. 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.",
+        "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, a lane not yet routed is routed first (a rung off its routed ladder starts at the routed rung, with a hint), and rung may be left out: the lane runs at its current rung (its route, or the rung its last climb gave). Without lane, rung is required (route(run, role) gives it), and the choice is recorded in routes.jsonl. thread resumes that role's thread for its own fix round: the thread its catherd message names, or \"latest\" for the name's last thread; a thread the name never ran on in this run is refused (E_ADMIT_THREAD). 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),
         name: z.string().regex(ID_PATTERN),
         brief: z.string().min(1),
-        rung: z.string().min(3),
+        rung: z.string().min(3).optional(),
         thread: z.string().optional(),
         lane: z.string().regex(ID_PATTERN).optional(),
         next: z.string().optional(),
@@ -31,7 +31,7 @@ export function registerDispatchTools(server: McpServer, deps: Deps): void {
     "peek",
     {
       description:
-        "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.",
+        "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. actionable is false, with its reason, when nothing is yours to do (only roles are live on the step, or the owner's answer comes first): end the turn with no tool call, and the next catherd message wakes you.",
       inputSchema: {
         run: z.string().optional(),
         name: z.string().regex(ID_PATTERN).optional(),

package/src/entry/mcp/handshake.ts

@@ -12,11 +12,15 @@ export const LAUNCHER = fileURLToPath(new URL("../../../plugin/bin/catherd-mcp",
 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. */
+/**
+ * The env the doctor's MCP server starts with: catherd's own secrets scrubbed, as for every process it starts,
+ * and no boot sync (1.2 minor): the server lives for one tools/list, so a sync there spends fetches (AA's
+ * included) and records nothing.
+ */
 export const handshakeEnv = (
   base: Record<string, string | undefined> = process.env,
 ): Record<string, string> => {
-  return scrubSecrets(base);
+  return { ...scrubSecrets(base), CATHERD_NO_SYNC: "1" };
 };
 
 /**

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

@@ -2,8 +2,10 @@ 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 { CatherdError } from "../../domain/errors.ts";
 import { CLIMB_REASONS } from "../../domain/route.ts";
-import { ask, climb, LAND_SKIPS, land, route } from "../../services/lane-service.ts";
+import { LANE_FIELDS, type LaneField, laneSet, ownsAdd } from "../../services/lane-edit.ts";
+import { ask, climb, LAND_SKIPS, land, route, routeLanes } from "../../services/lane-service.ts";
 import type { Deps } from "../../services/ports.ts";
 import { preflight } from "../../services/preflight.ts";
 import { handle } from "./result.ts";
@@ -13,31 +15,76 @@ 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. `provenance` says why: each threshold of the lane's bar with the value used against it, that value's confidence, source and date (`inferred: true` when a treat-like or a stand-in lent it), the rung's speed and cost facts, and catherd's own run evidence for it (shown, never used to route). A lane whose Kind: or Difficulty: the catalog does not know is refused with E_LANE_INVALID.",
+        "The rung for a lane (from the lane file's Kind/Difficulty lines when it declares both, else Jev, else the profile default), or with lanes (several lane files) for each of them in one call, Jev asked about all at once ({ routes: [...] }, in order), or, without a lane file, a role's default rung, with the ladder above it: only rungs at least as strong as the start. Rungs are backend:model#effort; a claude: rung comes with the agent to run it as. Returns rung, ladder, backend, agent and why: one line naming the decision, where Jev disagreed with the lane's header, when no rung clears the bar (and the closest), and when a tie between quotas decided. Every decision, with its provenance (each threshold, the value used, its source and date, the rung's cost and run evidence), is written to the run's routes.jsonl. 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(),
+        lanes: z.array(z.string()).min(1).optional(),
         role: z.enum(ROLES).default("worker"),
       },
     },
-    (a) => handle(() => route(deps, { run: a.run, laneFile: a.lane_file, role: a.role })),
+    (a) =>
+      handle(async () => {
+        if (a.lanes && a.lane_file !== undefined)
+          throw new CatherdError("E_INPUT_INVALID", "route takes lane_file or lanes, not both", {
+            fix: "pass every lane file in lanes",
+          });
+        return a.lanes
+          ? { routes: await routeLanes(deps, { run: a.run, laneFiles: a.lanes, role: a.role }) }
+          : route(deps, { run: a.run, laneFile: a.lane_file, role: a.role });
+      }),
+  );
+
+  const lane = z.string().regex(ID_PATTERN);
+  server.registerTool(
+    "lane_set",
+    {
+      description:
+        "Set one header line of a lane file (owns, fast_check, kind, difficulty, after, allow), validated as write_run_file validates a lane: an unknown Kind or Difficulty, an Owns path outside the repo, or a malformed After:/Allow: is refused with E_LANE_INVALID, and an Owns that a running lane holds with E_ADMIT_OVERLAP. after names lanes that must finish first; allow lists path or path:line hits the lane's absence check may report. Returns the line and the header as it now reads. Orchestrator only.",
+      inputSchema: {
+        run: z.string(),
+        lane,
+        field: z.enum(Object.keys(LANE_FIELDS) as [LaneField, ...LaneField[]]),
+        value: z.string(),
+      },
+    },
+    (a) => handle(() => laneSet(deps, a)),
+  );
+
+  server.registerTool(
+    "owns_add",
+    {
+      description:
+        "Grow a lane's Owns mid-lane, with why (kept in the lane file): a running lane that owns one of the paths refuses it with E_ADMIT_OVERLAP; another lane file that lists one comes back as a hint. A dispatch of the lane still running is held to the new list when it finishes, so its edits there are not violations. Orchestrator only.",
+      inputSchema: {
+        run: z.string(),
+        lane,
+        paths: z.array(z.string().min(1)).min(1).max(100),
+        why: z.string().min(1),
+      },
+    },
+    (a) => handle(() => ownsAdd(deps, a)),
   );
 
   server.registerTool(
     "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. 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() },
+        "Run each lane's fast check once, on the base tree, behind the heavy-command lock, with a 120 s timeout, in the user's login environment plus the repo's gate environment (catherd knowledge env). By default only the lanes of milestones not landed yet; milestone names one. Each lane is pass, fails-as-expected, skipped (it checks a file the lane creates, or a pnpm filter that matches no package yet), cannot-start (a missing command, a timeout, or an environment error: no Docker, DNS, a denied permission; its note says which) or lock-busy (no heavy slot came free within 60 s: run it again); only cannot-start blocks. warnings names each lane whose fast check runs no linter while the repo has one. 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(),
+        milestone: z.string().regex(ID_PATTERN).optional(),
+      },
     },
-    (a) => handle(() => preflight(deps, { run: a.run, confirmed: a.confirmed })),
+    (a) => handle(() => preflight(deps, { run: a.run, confirmed: a.confirmed, milestone: a.milestone })),
   );
 
   server.registerTool(
     "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. 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.",
+        "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. Refused with E_CLIMB_ENV when the lane's last reply named the environment on an ENV: line: fix the environment or park the milestone.",
       inputSchema: {
         run: z.string(),
         lane: z.string().regex(ID_PATTERN),
@@ -67,7 +114,7 @@ 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. 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).",
+        "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, the commits, lanes with rungs and climbs, the reviewer's BLOCKER and BUG lines, the owner questions still open, the verifier's verdict with carried items, minutes and tokens), and digestPath, its full path, 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 was recorded ok under exactly verifier-<milestone> (record_agent_run, role verifier; a headless verifier's reply opening VERDICT: PASS; verifier-M1-pre does not count). minutes leave out the time the milestone was parked and any machine or workspace pause. 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().regex(ID_PATTERN),

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

@@ -1,7 +1,7 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { ID_PATTERN } from "../../domain/ids.ts";
-import { gateCheck, gatePass } from "../../services/gate-service.ts";
+import { gateCheckOrList, gatePass } from "../../services/gate-service.ts";
 import { answer, park } from "../../services/questions.ts";
 import type { Deps } from "../../services/ports.ts";
 import { handle } from "./result.ts";
@@ -19,10 +19,16 @@ export function registerProtocolTools(server: McpServer, deps: Deps): void {
     "gate_check",
     {
       description:
-        "The verifier, before running a gate item: { carried: true, passedAt, commit } when this repo already has a pass of the same command on the same content of paths (repo-relative; . for the whole repo: HEAD plus uncommitted not-ignored changes; a git-ignored input such as .env or a build output is hashed only when named as a path), so it reports the item as carried over from that commit instead of running it; else { carried: false }, and it runs the item. Either way the call is recorded as the verifier's current step, which status and peek show. Pass milestone (the M the verifier checks) so the milestone's digest lists only its own carried items.",
-      inputSchema: { ...gate, milestone: z.string().regex(ID_PATTERN).optional() },
+        "The verifier, before running a gate item: { carried: true, passedAt, commit } when this repo already has a pass of the same command on the same content of paths (repo-relative; . for the whole repo: the tracked files plus uncommitted not-ignored changes; the repo's lockfiles always count, so never name node_modules; a git-ignored input such as .env or a build output is hashed only when named as a path, and as absent while it is not built), so it reports the item as carried over from that commit instead of running it; else { carried: false }, and it runs the item. Either way the call is recorded as the verifier's current step, which status and peek show. Pass milestone (the M the verifier checks): the milestone's digest then lists only its own carried items, and the answer adds recorded, the items already checked for that milestone in this run, each with its command and whether it passed. Call it first with only run and milestone to get that list without checking anything: reuse those item names, and re-check the failed ones first.",
+      inputSchema: {
+        run: z.string(),
+        item: gate.item.optional(),
+        command: gate.command.optional(),
+        paths: gate.paths.optional(),
+        milestone: z.string().regex(ID_PATTERN).optional(),
+      },
     },
-    (a) => handle(() => gateCheck(deps, a)),
+    (a) => handle(() => gateCheckOrList(deps, a)),
   );
 
   server.registerTool(

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

@@ -0,0 +1,16 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { probePush } from "../../services/doctor-push.ts";
+import type { Deps } from "../../services/ports.ts";
+import { handle } from "./result.ts";
+
+export function registerPushTools(server: McpServer, deps: Deps): void {
+  server.registerTool(
+    "test_push",
+    {
+      description:
+        "Send this session one labeled smoke message through catherd's push (Claude Code's peer inbox, or the native Codex queue for this thread) and return the receipt: { outcome, enqueue, processing, msgId, detail }. A receipt proves the host accepted it, never that the model read it. For a check from inside a session, where a shell cannot name the Codex thread; catherd doctor --test-push --thread <uuid> is the shell's form.",
+      inputSchema: {},
+    },
+    () => handle(() => probePush(deps.host, process.env)),
+  );
+}

package/src/entry/mcp/role-bin.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import { errorMessage } from "../../domain/errors.ts";
+import { ROLES } from "../../domain/roles.ts";
+import { restoreTmpdir } from "../../infra/env.ts";
+import { startRoleMcpServer } from "./role-server.ts";
+
+if (process.argv[2] === "--probe") {
+  // doctor's start probe: the server's module graph is loaded by now (spec 1.5 plan 21)
+  console.log("ready");
+  process.exit(0);
+}
+
+try {
+  const [role, run] = z.tuple([z.enum(ROLES), z.string().min(1)]).parse(process.argv.slice(2));
+  restoreTmpdir(process.env);
+  await startRoleMcpServer({ role, run });
+} catch (e) {
+  console.error(`catherd role MCP: ${errorMessage(e)}`);
+  process.exitCode = 1;
+}