catherd-cli 1.4.0 → 2.0.0-beta.20261022113309

package/src/entry/init-command.ts

@@ -6,20 +6,17 @@ import { errorMessage, isCatherdError } from "../domain/errors.ts";
 import { configDir } from "../infra/paths.ts";
 import { VERSION } from "../infra/version.ts";
 import { doctor } from "../services/doctor.ts";
-import { testAaKey } from "../infra/sources/artificial-analysis.ts";
-import { aaKey, saveAaKey } from "../services/credentials.ts";
+import { type IndexStatus, refreshIndex } from "../services/catalog-service.ts";
 import { jevKey, saveJevKey, testJevKey } from "../services/jev-service.ts";
-import { type SyncReport, syncSources } from "../services/source-sync.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 { activeName } from "../services/profile-store.ts";
-import { formatRefreshed, syncLines } from "./catalog-command.ts";
-import { mark as markOf } from "./cli-kit.ts";
+import { formatRefreshed } from "./catalog-command.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";
-import { mascot } from "./tui/theme.ts";
+import { mascot, type State } from "./glyphs.ts";
 import { type Prompter, prompter } from "./prompt.ts";
 
 /** What `init` prints last (spec §9.1): the plugin install commands, to paste into a terminal. */
@@ -30,7 +27,7 @@ export const PLUGIN_STEPS = [
   "Then start a new Claude Code session, so it loads the plugin and the catherd agents.",
 ];
 
-/** Spec §9.3: the full mascot greets `init` (and the TUI's empty states), nowhere else. */
+/** Spec §9.3: the full mascot greets `init` nowhere else. */
 export function welcomeLines(version: string): string[] {
   const [ears, face, paws] = mascot("good");
   return [ears, `${face}  catherd ${version}`, `${paws}  herds your coding agents`, ""];
@@ -72,68 +69,22 @@ export async function jevStep(
 }
 
 /**
- * Spec 1.2 §9: the Artificial Analysis key step, after Jev's. ARTIFICIAL_ANALYSIS_API_KEY wins, else the saved
- * key, else a prompt (Enter skips). A typed key is tested with one request: a 200 saves it, a 401 does not,
- * and a key that cannot be checked (no network) is not saved either. It never stops `init`.
- */
-export async function aaStep(
-  ask: Prompter | null,
-  d: {
-    testAaKey?: (key: string) => Promise<{ result: "ok" | "refused" | "unchecked"; error?: string }>;
-    saveAaKey?: (key: string) => void;
-  } = {},
-  plain = false,
-): Promise<void> {
-  const mark = (state: State) => markOf(state, plain);
-  if (process.env.ARTIFICIAL_ANALYSIS_API_KEY?.trim()) {
-    ask?.skip?.();
-    return console.log(`${mark("ok")} Artificial Analysis: using ARTIFICIAL_ANALYSIS_API_KEY`);
-  }
-  if (aaKey()) {
-    ask?.skip?.();
-    return console.log(`${mark("ok")} Artificial Analysis: using the saved key`);
-  }
-  const key = ask ? await ask.secret("Artificial Analysis API key (optional; Enter skips): ") : "";
-  if (!key)
-    return console.log(
-      "- Artificial Analysis: no key; scores come from the keyless sources (add one later with catherd init)",
-    );
-  const t = await (d.testAaKey ?? testAaKey)(key).catch((e: unknown) => ({
-    result: "unchecked" as const,
-    error: errorMessage(e),
-  }));
-  if (t.result === "refused")
-    return console.log(`${mark("warn")} Artificial Analysis: the key was refused (401), so it was not saved`);
-  if (t.result === "unchecked")
-    return console.log(
-      `${mark("warn")} Artificial Analysis: the key could not be checked (${t.error ?? "no answer"}), so it was not saved; run catherd init again to retry`,
-    );
-  try {
-    (d.saveAaKey ?? saveAaKey)(key);
-    console.log(`${mark("ok")} Artificial Analysis: the key answers; saved with mode 600`);
-  } catch (e) {
-    console.log(
-      `${mark("warn")} Artificial Analysis: could not save the key: ${errorMessage(e).split("\n").join(" ")}`,
-    );
-    if (isCatherdError(e) && e.fix) console.log(`    fix: ${e.fix}`);
-  }
-}
-
-/**
- * Spec 1.2 §9: `init` syncs the public sources in the foreground, after the keys. It never stops `init`;
+ * `init` refreshes the Slopalytics index in the foreground, after the Jev key. It never stops `init`;
  * CATHERD_NO_SYNC=1 skips it.
  */
-export async function syncStep(o: { plain?: boolean; sync?: () => Promise<SyncReport> } = {}): Promise<void> {
+export async function syncStep(
+  o: { plain?: boolean; sync?: () => Promise<IndexStatus> } = {},
+): Promise<void> {
   const plain = o.plain === true;
   if (process.env.CATHERD_NO_SYNC === "1")
-    return console.log("- sources: not synced (CATHERD_NO_SYNC=1); catherd catalog sync fetches them");
-  console.log("syncing the public model sources…");
-  try {
-    for (const l of syncLines(await (o.sync ?? (() => syncSources()))(), plain)) console.log(l);
-  } catch (e) {
-    console.log(`${markOf("warn", plain)} sources: ${errorMessage(e).split("\n").join(" ")}`);
-    console.log("    fix: catherd catalog sync");
-  }
+    return console.log("- catalog: not fetched (CATHERD_NO_SYNC=1); catherd catalog sync fetches it");
+  console.log("fetching the Slopalytics index…");
+  const s = await (o.sync ?? (() => refreshIndex({ auto: true })))().catch(
+    (e: unknown) => ({ error: errorMessage(e), pairs: 0 }) as Pick<IndexStatus, "error" | "pairs">,
+  );
+  if (s.error === null) return console.log(`${markOf("ok", plain)} Slopalytics: ${s.pairs} pairs indexed`);
+  console.log(`${markOf("warn", plain)} Slopalytics: ${s.error.split("\n").join(" ")}`);
+  console.log("    fix: catherd catalog sync");
 }
 
 /**
@@ -190,12 +141,12 @@ export function profileLines(r: InitResult, plain = false): string[] {
   return out;
 }
 
-/** Spec §8 `catherd init [--no-input]`: first-run setup without the TUI (plan 6 adds the TUI wizard). */
+/** Spec §8 `catherd init [--no-input]`: first-run setup without the panel. */
 export const initCommand = defineCommand({
   meta: {
     name: "init",
     description:
-      "First run: the global catherd command, the Jev key, the Artificial Analysis key, a sync of the public model sources, 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 Artificial Analysis 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, a fetch of the Slopalytics model index, 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: {
     ...HOST_ARG,
@@ -213,6 +164,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();
@@ -223,7 +175,6 @@ export const initCommand = defineCommand({
       console.log(`catherd ${VERSION}: setting up in ${configDir()}`);
       await globalStep(VERSION, { skip: (args as { global?: boolean }).global === false, plain });
       await jevStep(ask, {}, plain);
-      await aaStep(ask, {}, plain);
       await syncStep({ plain });
       const repo = await gitToplevel(process.cwd());
       // 0.x files go first, so a legacy profile about to be moved aside is never asked about

package/src/entry/knowledge-command.ts

@@ -1,7 +1,17 @@
 import { resolve } from "node:path";
 import { defineCommand } from "citty";
-import { addKnowledge, knowledgeLines, knowledgePath, readKnowledge } from "../services/run-service.ts";
-import { JSON_ARG, printJson } from "./cli-kit.ts";
+import { CatherdError } from "../domain/errors.ts";
+import { gateEnvLines, readGateEnv, removeGateEnv, setGateEnv } from "../services/gate-env.ts";
+import { ROLES, type Role } from "../domain/roles.ts";
+import {
+  addKnowledge,
+  knowledgeLines,
+  knowledgePath,
+  readKnowledge,
+  removeKnowledge,
+  standingRules,
+} from "../services/run-service.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 = {
@@ -11,8 +21,26 @@ const repoOf = (repo: string | undefined): string => resolve(repo ?? process.cwd
 
 const show = defineCommand({
   meta: { name: "show", description: "Print what catherd knows about the repo (its knowledge.md)" },
-  args: { ...REPO_ARG, ...JSON_ARG },
+  args: {
+    ...REPO_ARG,
+    role: { type: "string", description: "only the rules that reach this role" },
+    ...JSON_ARG,
+  },
   async run({ args }) {
+    if (args.role !== undefined) {
+      if (!(ROLES as readonly string[]).includes(args.role))
+        throw new CatherdError("E_INPUT_INVALID", `"${args.role}" is not a role`, {
+          fix: `pass one of ${ROLES.join(", ")}`,
+        });
+      const rules = await standingRules(repoOf(args.repo), args.role as Role);
+      if (args.json) {
+        const at = await knowledgePath(repoOf(args.repo));
+        return printJson({ ...at, role: args.role, rules });
+      }
+      const out = rules || "catherd: no knowledge recorded yet for this repo";
+      process.stdout.write(`${out}\n`);
+      return;
+    }
     if (args.json) return printJson(await knowledgeLines(repoOf(args.repo)));
     const text = await readKnowledge(repoOf(args.repo));
     process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
@@ -29,10 +57,26 @@ const add = defineCommand({
     ...REPO_ARG,
   },
   async run({ args }) {
+    refuseInRole(process.env, "catherd knowledge add");
     console.log(await addKnowledge(repoOf(args.repo), args.line));
   },
 });
 
+const rm = defineCommand({
+  meta: {
+    name: "rm",
+    description: "Remove the one line of the repo's knowledge.md that contains the text",
+  },
+  args: {
+    text: { type: "positional", required: true, description: "text of the one line to remove" },
+    ...REPO_ARG,
+  },
+  async run({ args }) {
+    refuseInRole(process.env, "catherd knowledge rm");
+    console.log(await removeKnowledge(repoOf(args.repo), args.text));
+  },
+});
+
 const path = defineCommand({
   meta: { name: "path", description: "Print the path of the repo's knowledge.md (it may not exist yet)" },
   args: { ...REPO_ARG, ...JSON_ARG },
@@ -43,8 +87,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, rm or path, and its gate environment (env)",
+  },
+  subCommands: { show, add, rm, 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, LOCK_HELD_ENV, 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,52 @@ 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}`;
+}
+
+export { LOCK_HELD_ENV };
 
 export const lockCommand = defineCommand({
   meta: {
@@ -102,6 +152,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 +174,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 = (_slot: number, tmp: string) =>
+      runForwarding(argv, {
+        extraEnv: { [LOCK_HELD_ENV]: "1", TMPDIR: tmp, GOTMPDIR: tmp },
+        ...(activity ? { onOutput: activity.tick } : {}),
+      });
+    const role = args.role;
     const repo = await gitToplevel(process.cwd());
     const slots = resolveSlots(
       args.slots,
@@ -123,6 +207,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, tmpBase: process.env.TMPDIR }),
+            waiting,
+          )
+        : await withHeavySlot(slots, run, { ...waiting, tmpBase: process.env.TMPDIR });
+    } finally {
+      activity?.done();
+    }
   },
 });

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/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;
+}

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

@@ -0,0 +1,134 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import { z } from "zod";
+import { ID_PATTERN } from "../../domain/ids.ts";
+import { ROLE_MCP_SERVER, type RoleMcpContext, roleMcpTools } from "../../domain/role-tools.ts";
+import { log } from "../../infra/log.ts";
+import { gateCheckOrList, gatePass } from "../../services/gate-service.ts";
+import { runMilestoneCheck } from "../../services/milestone-check.ts";
+import type { Deps } from "../../services/ports.ts";
+import { readKnowledge, readRunFile, writeRunFile } from "../../services/run-service.ts";
+import { findRun } from "../../services/run-store.ts";
+import { defaultDeps } from "../deps.ts";
+import { handle, sdkToolError, toolOf } from "./result.ts";
+
+/** A role can reach only its run artifacts and, for a verifier, that run's gate evidence. */
+export function buildRoleServer(context: RoleMcpContext, deps: Deps = defaultDeps()): McpServer {
+  const run = findRun(context.run);
+  const server = new McpServer({ name: ROLE_MCP_SERVER, version: deps.version });
+  const tools = new Set(roleMcpTools(context.role));
+  const boundRun = z.literal(run.id);
+  const runFile = { run: boundRun, path: z.string().min(1) };
+  const call = async (tool: string, f: () => unknown) => {
+    const started = Date.now();
+    const result = await handle(f);
+    log(result.isError ? "warn" : "info", "tool", {
+      tool,
+      ms: Date.now() - started,
+      ok: !result.isError,
+      code: result.isError ? (result.structuredContent as { code?: string } | undefined)?.code : undefined,
+    });
+    return result;
+  };
+  (server as unknown as { createToolError: typeof sdkToolError }).createToolError = (message) => {
+    const result = sdkToolError(message);
+    log("warn", "tool", {
+      tool: toolOf(message),
+      ok: false,
+      code: (result.structuredContent as { code?: string } | undefined)?.code,
+    });
+    return result;
+  };
+
+  server.registerTool(
+    "read_run_file",
+    {
+      description: "Read an artifact from this role's run folder, using a run-relative path.",
+      inputSchema: runFile,
+      annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+    (a) => call("read_run_file", () => readRunFile(a)),
+  );
+  server.registerTool(
+    "read_knowledge",
+    {
+      description:
+        "Read what past runs learned about this role's repository. Takes no argument: it reads the run's own repository.",
+      // #42 finding 4: `.`, the pwd or /tmp vs /private/tmp never matched a literal; any repo given is ignored
+      inputSchema: { repo: z.string().optional() },
+      annotations: { readOnlyHint: true, openWorldHint: false },
+    },
+    () => call("read_knowledge", () => readKnowledge(run.meta.repo)),
+  );
+  if (tools.has("write_run_file"))
+    server.registerTool(
+      "write_run_file",
+      {
+        description: "Write a plan, lane, dossier or note in this run; catherd's own files are protected.",
+        inputSchema: { ...runFile, content: z.string() },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+      },
+      (a) => call("write_run_file", () => writeRunFile(a)),
+    );
+  if (tools.has("gate_check")) {
+    const gate = {
+      run: boundRun,
+      item: z.string().min(1),
+      command: z.string().min(1),
+      paths: z.array(z.string().min(1)).min(1),
+    };
+    server.registerTool(
+      "gate_check",
+      {
+        description:
+          "Check whether this run's gate item passed on unchanged content; records the current step. With only run and milestone, lists the items already checked for that milestone in this run, each with its command and whether it passed: reuse those names and re-check the failed ones first.",
+        inputSchema: {
+          run: boundRun,
+          item: gate.item.optional(),
+          command: gate.command.optional(),
+          paths: gate.paths.optional(),
+          milestone: z.string().regex(ID_PATTERN).optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+      },
+      (a) => call("gate_check", () => gateCheckOrList(deps, a)),
+    );
+    server.registerTool(
+      "gate_pass",
+      {
+        description: "Record this run's passed gate item with the evidence, command and content hash.",
+        inputSchema: { ...gate, evidence: z.string().min(1) },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+      },
+      (a) => call("gate_pass", () => gatePass(deps, a)),
+    );
+  }
+  if (tools.has("gate_run"))
+    server.registerTool(
+      "gate_run",
+      {
+        description:
+          "The verifier's full check of a milestone, run by catherd on the committed HEAD in a detached worker under the verifier lock and a heavy slot: { running: false, record (exit, failing lines, log, secrets, rerunOf), missing, audit } once done; land reads that record. The same run, milestone, command and HEAD answers the recorded result (force: true runs it again). Refused while tracked files are uncommitted. Past 10 minutes it answers { running: true }: call it again to wait for the same run. at: a checkout of the run's base you prepared, to record the base's own failures, which then do not block.",
+        inputSchema: {
+          run: boundRun,
+          milestone: z.string().regex(ID_PATTERN),
+          command: z.string().min(1),
+          at: z.string().min(1).optional(),
+          force: z.boolean().optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+      },
+      (a) => call("gate_run", () => runMilestoneCheck(a)),
+    );
+  return server;
+}
+
+/** Role servers have no orchestrator ownership, notifier, reconciliation or background catalog sync. */
+export async function startRoleMcpServer(
+  context: RoleMcpContext,
+  o: { deps?: Deps; transport?: Transport } = {},
+): Promise<void> {
+  const server = buildRoleServer(context, o.deps);
+  await server.connect(o.transport ?? new StdioServerTransport());
+}