catherd-cli 0.2.1 → 1.1.0

package/src/entry/lock-command.ts

@@ -0,0 +1,123 @@
+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 { killGroup } from "../infra/proc.ts";
+import { profileFor } from "../services/profile-store.ts";
+import { printError } from "./cli-kit.ts";
+
+/**
+ * --slots, then CATHERD_LOCK_SLOTS, then the profile's lock.heavy, then half the cores. `warn` hears why
+ * the profile could not say, so the fallback is never silent (plan-2 review m10).
+ */
+export function resolveSlots(
+  flag: string | undefined,
+  profile: () => number | "cpus/2",
+  warn: (message: string) => void = () => {},
+): number {
+  const raw = flag ?? process.env.CATHERD_LOCK_SLOTS;
+  if (raw) {
+    if (raw === "cpus/2") return heavySlots("cpus/2");
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 1)
+      throw new CatherdError("E_INPUT_INVALID", `slots must be a number ≥ 1 or cpus/2, not "${raw}"`, {
+        fix: "catherd lock --slots 2 -- <command>",
+      });
+    return heavySlots(n);
+  }
+  try {
+    return heavySlots(profile());
+  } catch (e) {
+    const slots = heavySlots("cpus/2");
+    warn(`catherd lock: no profile to read lock.heavy from (${(e as Error).message}); using ${slots} slots`);
+    return slots;
+  }
+}
+
+/** How long a second Ctrl-C has to follow the first to kill the command outright. */
+export const DOUBLE_INTERRUPT_MS = 2_000;
+
+/**
+ * Runs `argv` in its own process group and forwards SIGINT, SIGTERM and SIGHUP to the whole group once:
+ * 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> {
+  const child = Bun.spawn(argv, {
+    stdin: "inherit",
+    stdout: "inherit",
+    stderr: "inherit",
+    env: scrubSecrets(process.env),
+    detached: true,
+  });
+  let lastInt = 0;
+  const handlers: [NodeJS.Signals, () => void][] = [
+    [
+      "SIGINT",
+      () => {
+        const now = Date.now();
+        killGroup(child.pid, now - lastInt < DOUBLE_INTERRUPT_MS ? "SIGKILL" : "SIGINT");
+        lastInt = now;
+      },
+    ],
+    ["SIGTERM", () => killGroup(child.pid, "SIGTERM")],
+    ["SIGHUP", () => killGroup(child.pid, "SIGHUP")],
+  ];
+  for (const [sig, h] of handlers) process.on(sig, h);
+  // The command's own session is out of reach of a signal to catherd's group, and a SIGKILL (a
+  // supervisor's escalation) cannot be forwarded: the watchdog reads EOF when catherd dies, however it
+  // dies, and kills the command's group then.
+  const watchdog = Bun.spawn(
+    ["sh", "-c", 'read _ || kill -s KILL -- "-$1" 2>/dev/null', "sh", String(child.pid)],
+    {
+      stdin: "pipe",
+      stdout: "ignore",
+      stderr: "ignore",
+      detached: true,
+    },
+  );
+  try {
+    return await child.exited;
+  } finally {
+    watchdog.kill("SIGKILL");
+    for (const [sig, h] of handlers) process.off(sig, h);
+  }
+}
+
+/** 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 lockCommand = defineCommand({
+  meta: {
+    name: "lock",
+    description:
+      "Run a heavy command behind the machine-wide semaphore, in its own process group and session: it gets no /dev/tty and no job control",
+  },
+  args: {
+    slots: {
+      type: "string",
+      description: "Slots (default: CATHERD_LOCK_SLOTS, else the profile's lock.heavy, else half the cores)",
+    },
+  },
+  async run({ args, rawArgs }) {
+    const sep = rawArgs.indexOf("--");
+    const argv = sep < 0 ? [] : rawArgs.slice(sep + 1);
+    if (argv.length === 0) {
+      printError(
+        new CatherdError("E_INPUT_INVALID", "no command to run", {
+          fix: LOCK_USAGE,
+        }),
+      );
+      process.exitCode = 2;
+      return;
+    }
+    const repo = await gitToplevel(process.cwd());
+    const slots = resolveSlots(
+      args.slots,
+      () => profileFor(repo).lock.heavy,
+      (m) => console.error(m),
+    );
+    process.exitCode = await withHeavySlot(slots, () => runForwarding(argv));
+  },
+});

package/src/{mcp/commands.ts → 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

@@ -0,0 +1,52 @@
+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 } from "../../services/dispatch-service.ts";
+import { peek } from "../../services/peek.ts";
+import type { Deps } from "../../services/ports.ts";
+import { handle } from "./result.ts";
+
+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. 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),
+        name: z.string().regex(ID_PATTERN),
+        brief: z.string().min(1),
+        rung: z.string().min(3),
+        thread: z.string().optional(),
+        lane: z.string().regex(ID_PATTERN).optional(),
+        next: z.string().optional(),
+      },
+    },
+    (a) => handle(() => dispatch(deps, a)),
+  );
+
+  server.registerTool(
+    "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.",
+      inputSchema: {
+        run: z.string().optional(),
+        name: z.string().regex(ID_PATTERN).optional(),
+      },
+    },
+    (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 read, and hints.",
+      inputSchema: { run: z.string(), name: z.string().regex(ID_PATTERN) },
+    },
+    (a) => handle(() => cancel(deps, a.run, a.name, { read: true })),
+  );
+}

package/src/entry/mcp/handshake.ts

@@ -0,0 +1,58 @@
+import { fileURLToPath } from "node:url";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { errorMessage } from "../../domain/errors.ts";
+import { scrubSecrets } from "../../infra/env.ts";
+import { VERSION } from "../../infra/version.ts";
+import type { Handshake } from "../../services/doctor.ts";
+
+/** 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 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: "sh",
+    args: [o.launcher ?? LAUNCHER],
+    env: handshakeEnv(),
+    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`, stderr }),
+      TIMEOUT_MS,
+    );
+  });
+  try {
+    return await Promise.race([
+      (async (): Promise<Handshake> => {
+        await client.connect(transport);
+        const r = await client.listTools();
+        return { ok: true, tools: r.tools.map((t) => t.name) };
+      })(),
+      late,
+    ]);
+  } catch (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

@@ -0,0 +1,84 @@
+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 { CLIMB_REASONS } from "../../domain/route.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";
+
+export function registerLaneTools(server: McpServer, deps: Deps): void {
+  server.registerTool(
+    "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. 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(),
+        role: z.enum(ROLES).default("worker"),
+      },
+    },
+    (a) => handle(() => route(deps, { run: a.run, laneFile: a.lane_file, role: a.role })),
+  );
+
+  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() },
+    },
+    (a) => handle(() => preflight(deps, { run: a.run, confirmed: a.confirmed })),
+  );
+
+  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.",
+      inputSchema: {
+        run: z.string(),
+        lane: z.string().regex(ID_PATTERN),
+        reason: z.enum(CLIMB_REASONS),
+        evidence: z.string().optional(),
+        env: z.boolean().optional(),
+      },
+    },
+    (a) => handle(() => climb(deps, a)),
+  );
+
+  server.registerTool(
+    "ask",
+    {
+      description:
+        "Ask Jev one fixed question. finding: state { lane_file, finding } → design | code | unclear. same-defect: state { before, after } → yes | no. Falls back to the default when Jev is unsure or absent. Keep the state short, in English, and free of secrets.",
+      inputSchema: {
+        run: z.string(),
+        question: z.enum(["finding", "same-defect"]),
+        state: z.record(z.string(), z.string()),
+      },
+    },
+    (a) => handle(() => ask(deps, a)),
+  );
+
+  server.registerTool(
+    "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).",
+      inputSchema: {
+        run: z.string(),
+        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)),
+  );
+}

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

@@ -0,0 +1,57 @@
+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 { answer, park } from "../../services/questions.ts";
+import type { Deps } from "../../services/ports.ts";
+import { handle } from "./result.ts";
+
+// Spec 1.1 §7 and §8: the tools the enforced protocol adds.
+export function registerProtocolTools(server: McpServer, deps: Deps): void {
+  const gate = {
+    run: z.string(),
+    item: z.string().min(1),
+    command: z.string().min(1),
+    paths: z.array(z.string().min(1)).min(1),
+  };
+
+  server.registerTool(
+    "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() },
+    },
+    (a) => handle(() => gateCheck(deps, a)),
+  );
+
+  server.registerTool(
+    "gate_pass",
+    {
+      description:
+        "The verifier, after a gate item passed: records the command, the content hash of paths and the commit, with the evidence (a log path or the decisive line), so a later gate_check on unchanged content carries it over.",
+      inputSchema: { ...gate, evidence: z.string().min(1) },
+    },
+    (a) => handle(() => gatePass(deps, a)),
+  );
+
+  server.registerTool(
+    "park",
+    {
+      description:
+        "An owner question only the user can answer: parks the milestone (land refuses it until answered) and puts it in front of state.md's next step, instead of stopping the run. Returns the parked milestones and hints: push the full question to the user with PushNotification, and go on with the milestones and runs that do not depend on it.",
+      inputSchema: { run: z.string(), milestone: z.string().regex(ID_PATTERN), question: z.string().min(1) },
+    },
+    (a) => handle(() => park(deps, a)),
+  );
+
+  server.registerTool(
+    "answer",
+    {
+      description:
+        "The owner answered a parked milestone's question in this session: records the answer and unparks the milestone. status, peek and run_start list the questions still open.",
+      inputSchema: { run: z.string(), milestone: z.string().regex(ID_PATTERN), answer: z.string().min(1) },
+    },
+    (a) => handle(() => answer(deps, a)),
+  );
+}

package/src/entry/mcp/result.ts

@@ -0,0 +1,51 @@
+import { type CallToolResult, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+import { CatherdError, errorMessage, isCatherdError } from "../../domain/errors.ts";
+
+/** A service's value as a tool result; its `hints`, when it has any, pass through as they are. */
+const ok = (v: unknown): CallToolResult => ({
+  content: [{ type: "text", text: typeof v === "string" ? v : JSON.stringify(v, null, 2) }],
+});
+
+/** Spec §4.8, §10.1: every failure is a structured tool error `{ code, message, fix }`. */
+function fail(e: unknown): CallToolResult {
+  const err = isCatherdError(e)
+    ? { fix: "", ...e.toJSON() }
+    : {
+        code: "E_IO_UNEXPECTED",
+        message: errorMessage(e),
+        fix: "this is a catherd bug: report it with the message",
+      };
+  return { isError: true, content: [{ type: "text", text: JSON.stringify(err) }], structuredContent: err };
+}
+
+/** Runs one service call and turns its value, or its error, into a tool result. */
+export async function handle(f: () => unknown): Promise<CallToolResult> {
+  try {
+    return ok(await f());
+  } catch (e) {
+    return fail(e);
+  }
+}
+
+const UNKNOWN_TOOL = /Tool (\S+) (?:not found|disabled)$/;
+
+/** The tool an SDK error message names ("Tool x not found", "… arguments for tool x: …"), else null. */
+export const toolOf = (message: string): string | null =>
+  (UNKNOWN_TOOL.exec(message) ?? /for tool (\S+?):/.exec(message))?.[1] ?? null;
+
+/**
+ * The SDK's own tool errors, raised before `handle` runs, in catherd's shape (spec §4.8): a call to a tool
+ * this server does not have, or input a tool's schema rejects, is E_INPUT_INVALID; anything else is
+ * unexpected.
+ */
+export function sdkToolError(message: string): CallToolResult {
+  if (!message.startsWith(`MCP error ${ErrorCode.InvalidParams}:`)) return fail(new Error(message));
+  const unknown = UNKNOWN_TOOL.exec(message)?.[1];
+  return fail(
+    new CatherdError("E_INPUT_INVALID", message, {
+      fix: unknown
+        ? `call a tool this server lists (tools/list); a skill that needs ${unknown} needs a newer catherd: claude plugin update catherd@catherd`
+        : "correct the argument the message names, then call again",
+    }),
+  );
+}

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

@@ -0,0 +1,145 @@
+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 { redact } from "../../infra/log.ts";
+import { registerSavedSecrets } from "../../services/jev-service.ts";
+import type { Deps } from "../../services/ports.ts";
+import {
+  readKnowledge,
+  readRunFile,
+  recordAgentRun,
+  result,
+  setNext,
+  startRun,
+  writeRunFile,
+} from "../../services/run-service.ts";
+import { runsSummary, status } from "../../services/summary.ts";
+import { handle } from "./result.ts";
+
+export function registerRunTools(server: McpServer, deps: Deps): void {
+  server.registerTool(
+    "run_start",
+    {
+      description:
+        "Start a catherd run for a git repository: creates its run folder (outside the repo) and state.md. Returns the run id, the folder, protocol (the next step of the milestone loop and its six-line checklist), and hints when state.md could not be written yet.",
+      inputSchema: {
+        repo: z.string().min(1),
+        title: z.string().min(1),
+        a_lines: z.array(z.string().min(1)).min(1),
+      },
+    },
+    (a) => handle(() => startRun(deps, { repo: a.repo, title: a.title, aLines: a.a_lines })),
+  );
+
+  server.registerTool(
+    "write_run_file",
+    {
+      description:
+        "Write a file in the run folder: plan.md, lanes/Mx.Ly.md, a dossier or notes. The path is relative to the run folder; catherd's own files are refused.",
+      inputSchema: { run: z.string(), path: z.string().min(1), content: z.string() },
+    },
+    (a) => handle(() => writeRunFile(a)),
+  );
+
+  server.registerTool(
+    "read_run_file",
+    {
+      description: "Read a file in the run folder, by a path relative to it.",
+      inputSchema: { run: z.string(), path: z.string().min(1) },
+    },
+    (a) => handle(() => readRunFile(a)),
+  );
+
+  server.registerTool(
+    "status",
+    {
+      description:
+        "catherd's version, and one screen per run: the state.md tail, live roles, totals, reported Claude subagents, Jev fallbacks, per backend how many dispatches ran native and isolated, budget and landed milestones. Without a run: every run with live roles, else the newest. Reads only.",
+      inputSchema: { run: z.string().optional() },
+    },
+    (a) =>
+      handle(() => {
+        registerSavedSecrets();
+        return redact(status(deps, a.run));
+      }),
+  );
+
+  server.registerTool(
+    "result",
+    {
+      description:
+        "A role's latest dispatch: its state, its record once finished, its capped reply, and hints (climb, violation, failed, limit and failover lines). Reading a finished record marks it read: catherd's messages announce records, and this is how you read one.",
+      inputSchema: { run: z.string(), name: z.string().regex(ID_PATTERN) },
+    },
+    (a) => handle(() => result(deps, a)),
+  );
+
+  server.registerTool(
+    "set_next",
+    {
+      description:
+        "Record the run's next step, the last line of state.md: when pausing, or when the plan changes. dispatch, climb and land write state.md themselves. Returns { state } (state.md's text), and hints ['state.md not refreshed: …'] with state null when git fails (the step is still recorded).",
+      inputSchema: { run: z.string(), next: z.string().min(1) },
+    },
+    (a) => handle(() => setNext(a)),
+  );
+
+  server.registerTool(
+    "record_agent_run",
+    {
+      description:
+        "After every native Claude subagent (Agent tool) of a run, record what the Agent result reported: total_tokens and duration_ms. The budget counts it. Pass lane (e.g. M1.L1) when the subagent worked a lane, so its time counts toward that lane's kind in the catalog timings. status says how the subagent's work ended: for a verifier it is the verdict, so pass status: \"failed\" when its verdict is FAIL; only a PASS is recorded ok.",
+      inputSchema: {
+        run: z.string(),
+        name: z.string().regex(ID_PATTERN),
+        role: z.enum(ROLES),
+        rung: z.string().min(3),
+        total_tokens: z.number().int().nonnegative(),
+        duration_ms: z.number().nonnegative().optional(),
+        cost_usd: z.number().nonnegative().optional(),
+        status: z.enum(["ok", "failed", "cancelled"]).default("ok"),
+        lane: z.string().regex(ID_PATTERN).optional(),
+      },
+    },
+    (a) =>
+      handle(() =>
+        recordAgentRun(deps, {
+          lane: a.lane,
+          run: a.run,
+          name: a.name,
+          role: a.role,
+          rung: a.rung,
+          totalTokens: a.total_tokens,
+          durationMs: a.duration_ms,
+          costUsd: a.cost_usd,
+          status: a.status,
+        }),
+      ),
+  );
+
+  server.registerTool(
+    "read_knowledge",
+    {
+      description:
+        "What past runs of this repo learned, one line per landed milestone that said something. Read it before an architect plans a new run.",
+      inputSchema: { repo: z.string().min(1) },
+    },
+    (a) => handle(() => readKnowledge(a.repo)),
+  );
+
+  server.registerTool(
+    "runs_summary",
+    {
+      description:
+        "Per role and rung over past runs: runs, ok, refusals, climbs from that rung, seconds and tokens; reported Claude subagent runs; and what the user's harness customizations cost per run (median first-turn input, native against isolated; with a run, over that run's repo; null below 3 runs a side or when native is not dearer; none for Codex, which reports no per-request input). Reads only.",
+      inputSchema: {
+        run: z.string().optional(),
+        repo: z.string().optional(),
+        role: z.enum(ROLES).optional(),
+        since_days: z.number().positive().optional(),
+      },
+    },
+    (a) => handle(() => runsSummary({ run: a.run, repo: a.repo, role: a.role, sinceDays: a.since_days })),
+  );
+}