catherd-cli 1.3.0 → 1.5.0

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,116 @@
+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 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)),
+    );
+  }
+  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());
+}

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

@@ -2,6 +2,7 @@ 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 { knownQueueCapability } from "../../infra/codex-queue.ts";
 import { redact } from "../../infra/log.ts";
 import { registerSavedSecrets } from "../../services/jev-service.ts";
 import type { Deps } from "../../services/ports.ts";
@@ -14,6 +15,7 @@ import {
   startRun,
   writeRunFile,
 } from "../../services/run-service.ts";
+import { repin } from "../../services/run-pin.ts";
 import { runsSummary, status } from "../../services/summary.ts";
 import { handle } from "./result.ts";
 
@@ -22,14 +24,25 @@ export function registerRunTools(server: McpServer, deps: Deps): void {
     "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.",
+        "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. from: the run this one takes over (a planning run handed to the execution run in a worktree): it is closed with a pointer here, and status hides it.",
       inputSchema: {
         repo: z.string().min(1),
         title: z.string().min(1),
         a_lines: z.array(z.string().min(1)).min(1),
+        from: z.string().regex(ID_PATTERN).optional(),
       },
     },
-    (a) => handle(() => startRun(deps, { repo: a.repo, title: a.title, aLines: a.a_lines })),
+    (a) => handle(() => startRun(deps, { repo: a.repo, title: a.title, aLines: a.a_lines, from: a.from })),
+  );
+
+  server.registerTool(
+    "run_pin",
+    {
+      description:
+        "Re-pin a run to what its repo runs on now: the profile, each role's access and each backend's isolation. run_start pins them; while they differ, dispatch keeps the pinned values and status and state.md say what changed. Only on the owner's word. Returns the new pin and what it changed. Orchestrator only.",
+      inputSchema: { run: z.string().regex(ID_PATTERN) },
+    },
+    (a) => handle(() => repin(deps, a)),
   );
 
   server.registerTool(
@@ -55,13 +68,15 @@ export function registerRunTools(server: McpServer, deps: Deps): void {
     "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.",
+        "catherd's version, and one screen per run: the state.md tail, live roles, unread results waiting for the orchestrator, 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 or unread completions waiting for its orchestrator, else the newest. Reads only.",
       inputSchema: { run: z.string().optional() },
     },
     (a) =>
-      handle(() => {
+      handle(async () => {
         registerSavedSecrets();
-        return redact(status(deps, a.run));
+        const queue =
+          deps.host.host === "codex" && !deps.host.conflict ? knownQueueCapability(process.env) : null;
+        return redact(status(deps, a.run, queue));
       }),
   );
 
@@ -89,7 +104,7 @@ export function registerRunTools(server: McpServer, deps: Deps): void {
     "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.",
+        '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. For a verifier, pass verdict: the first line of its reply; a VERDICT: BLOCKED: environment — <probe> (status "failed") is then a blocker to surface to the owner, not a fix round. Pass reply_status, the STATUS word its reply ends with: a reviewer that stopped partial is not the milestone review.',
       inputSchema: {
         run: z.string(),
         name: z.string().regex(ID_PATTERN),
@@ -100,6 +115,8 @@ export function registerRunTools(server: McpServer, deps: Deps): void {
         cost_usd: z.number().nonnegative().optional(),
         status: z.enum(["ok", "failed", "cancelled"]).default("ok"),
         lane: z.string().regex(ID_PATTERN).optional(),
+        verdict: z.string().min(1).optional(),
+        reply_status: z.enum(["complete", "partial", "blocked", "refused", "flaky"]).optional(),
       },
     },
     (a) =>
@@ -114,6 +131,8 @@ export function registerRunTools(server: McpServer, deps: Deps): void {
           durationMs: a.duration_ms,
           costUsd: a.cost_usd,
           status: a.status,
+          verdict: a.verdict,
+          replyStatus: a.reply_status,
         }),
       ),
   );

package/src/entry/mcp/server.ts

@@ -1,34 +1,134 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 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 type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import { errorMessage } from "../../domain/errors.ts";
+import { sessionKey, type HostContext } from "../../domain/host.ts";
+import { type CatherdError, errorMessage, isCatherdError } from "../../domain/errors.ts";
+import {
+  isCoordinatorTool,
+  refusedForRole,
+  type RoleScope,
+  roleScopeError,
+} from "../../domain/role-scope.ts";
+import { takeBootLock } from "../../infra/boot-lock.ts";
+import { resolveHost } from "../../infra/host-context.ts";
 import { log } from "../../infra/log.ts";
+import { assertRoleMay } from "../../services/role-access.ts";
+import { currentSession } from "../../services/sessions.ts";
 import { startNotifier } from "../../services/notifier.ts";
 import type { Deps } from "../../services/ports.ts";
-import { reconcileAll } from "../../services/reconcile.ts";
+import { adoptOwned, reconcileAll } from "../../services/reconcile.ts";
 import { backgroundSync } from "../../services/source-sync.ts";
 import { defaultDeps } from "../deps.ts";
 import { registerDispatchTools } from "./dispatch-tools.ts";
 import { registerLaneTools } from "./lane-tools.ts";
 import { registerProtocolTools } from "./protocol-tools.ts";
-import { sdkToolError, toolOf } from "./result.ts";
+import { registerPushTools } from "./push-tools.ts";
+import { handle, sdkToolError, toolOf } from "./result.ts";
 import { registerRunTools } from "./run-tools.ts";
 import { registerSetupTools } from "./setup-tools.ts";
+import { registerWorkspaceTools } from "./workspace-tools.ts";
+
+type ObserveSession = (context: Deps) => (() => void) | undefined;
+
+/** Spec 1.5 plan 21: a coordinator tool's description says, first, that only the orchestrator calls it. */
+function orchestratorOnly(name: string, config: unknown): unknown {
+  const c = config as { description?: string };
+  return isCoordinatorTool(name) && c.description
+    ? { ...c, description: `Orchestrator only (a role process gets E_ROLE_SCOPE). ${c.description}` }
+    : config;
+}
+
+type RequestHandler = (
+  request: { params?: { name?: unknown; arguments?: unknown } },
+  extra: unknown,
+) => unknown;
+
+/** The role server's tools that act on a run: in a role they are bound as their CLI forms are (assertRoleMay). */
+const RUN_BOUND_TOOLS = new Set(["read_run_file", "write_run_file", "gate_check", "gate_pass"]);
+
+/**
+ * Why a role process may not make this call on the full server, else null (plan 21 review, finding 3): a
+ * coordinator tool; `record_agent_run`, which could fabricate a verifier's ok; or a run-bound tool on another
+ * run or outside its role's tool set, as `catherd run-file` and `catherd gate` refuse it.
+ */
+function roleRefusal(name: string, args: unknown, role: RoleScope): CatherdError | null {
+  if (refusedForRole(name, args, role) || name === "record_agent_run") return roleScopeError(name, role);
+  if (!RUN_BOUND_TOOLS.has(name)) return null;
+  const run = (args as { run?: unknown } | undefined)?.run;
+  try {
+    assertRoleMay(role, typeof run === "string" ? run : "", name);
+    return null;
+  } catch (e) {
+    if (isCatherdError(e)) return e;
+    throw e;
+  }
+}
+
+/**
+ * Spec 1.5 plan 21: in a role's process (`deps.role`) a coordinator tool call is refused with E_ROLE_SCOPE
+ * before anything else, its input check included, so a role learns at once that the tool is not its own. The
+ * SDK keeps its request handlers in a private map; test/entry/role-scope-mcp.test.ts fails if it moves.
+ */
+function refuseCoordinatorTools(server: McpServer, deps: Deps): void {
+  const handlers = (server.server as unknown as { _requestHandlers: Map<string, RequestHandler> })
+    ._requestHandlers;
+  const callTool = handlers.get("tools/call");
+  if (!callTool) return;
+  handlers.set("tools/call", async (request, extra) => {
+    const role = deps.role;
+    const name = String(request.params?.name ?? "");
+    const refusal = role ? roleRefusal(name, request.params?.arguments, role) : null;
+    if (!refusal) return callTool(request, extra);
+    const r = await handle(() => {
+      throw refusal;
+    });
+    log("warn", "tool", { tool: name, ok: false, code: "E_ROLE_SCOPE" });
+    return r;
+  });
+}
 
 type Handler = (...args: unknown[]) => CallToolResult | Promise<CallToolResult>;
 
 /** Spec §10.2: every tool call is logged with its duration and outcome (the error code), never its input. */
-function logToolCalls(server: McpServer): void {
+function logToolCalls(
+  server: McpServer,
+  deps: Deps,
+  scope: AsyncLocalStorage<Deps>,
+  generation: () => number,
+  observe?: ObserveSession,
+): void {
   const register = server.registerTool.bind(server) as unknown as (
     n: string,
     c: unknown,
     h: Handler,
   ) => unknown;
   (server as unknown as { registerTool: typeof register }).registerTool = (name, config, handler) =>
-    register(name, config, async (...args: unknown[]) => {
+    register(name, orchestratorOnly(name, config), async (...args: unknown[]) => {
       const started = Date.now();
-      const r = await handler(...args);
+      const epoch = generation();
+      const extra = args.at(-1) as { _meta?: Record<string, unknown> } | undefined;
+      let host = deps.host;
+      if (host.host === "codex" && !host.conflict && extra?._meta && "threadId" in extra._meta) {
+        const threadId = extra._meta.threadId;
+        host =
+          typeof threadId === "string"
+            ? resolveHost({
+                clientName: "codex-mcp-client",
+                env: { CODEX_THREAD_ID: threadId, CODEX_SESSION_ID: host.session?.sessionId },
+              })
+            : { host: "unknown", session: null, conflict: "Codex _meta.threadId must be a UUID string" };
+      }
+      const context: Deps = {
+        ...deps,
+        get host(): HostContext {
+          return epoch === generation() ? host : { host: "unknown", session: null, conflict: null };
+        },
+      };
+      const after = observe?.(context);
+      const r = await scope.run(context, () => handler(...args));
+      after?.();
       const code = r.isError ? (r.structuredContent as { code?: string } | undefined)?.code : undefined;
       log(r.isError ? "warn" : "info", "tool", {
         tool: name,
@@ -40,9 +140,25 @@ function logToolCalls(server: McpServer): void {
     });
 }
 
-export function buildServer(deps: Deps = defaultDeps()): McpServer {
+export function buildServer(deps: Deps = defaultDeps(), observe?: ObserveSession): McpServer {
   const server = new McpServer({ name: "catherd", version: deps.version });
-  logToolCalls(server);
+  const scope = new AsyncLocalStorage<Deps>();
+  const scoped: Deps = new Proxy(deps, {
+    get: (target, key) => (key === "profiles" ? profiles : Reflect.get(scope.getStore() ?? target, key)),
+  });
+  const profiles = deps.profiles.withHost?.(() => scoped.host) ?? deps.profiles;
+  let generation = 0;
+  const invalidate = () => {
+    generation++;
+    deps.host = { host: "unknown", session: null, conflict: null };
+  };
+  logToolCalls(server, deps, scope, () => generation, observe);
+  deps.host = { host: "unknown", session: null, conflict: null };
+  server.server.oninitialized = () => {
+    invalidate();
+    deps.host = resolveHost({ clientName: server.server.getClientVersion()?.name, env: process.env });
+  };
+  server.server.onclose = invalidate;
   // The SDK validates input before a tool's `handle` runs and reports a failure through this (private)
   // method as plain text; test/entry/mcp.test.ts fails loudly if an SDK upgrade renames it. The wrapper
   // above never sees such a call, so it is logged here (spec §10.2: every call), by the tool it names.
@@ -52,47 +168,111 @@ export function buildServer(deps: Deps = defaultDeps()): McpServer {
     log("warn", "tool", { tool: toolOf(message), ok: false, code });
     return r;
   };
-  registerRunTools(server, deps);
-  registerLaneTools(server, deps);
-  registerDispatchTools(server, deps);
-  registerSetupTools(server, deps);
-  registerProtocolTools(server, deps);
+  registerRunTools(server, scoped);
+  registerWorkspaceTools(server, scoped);
+  registerLaneTools(server, scoped);
+  registerDispatchTools(server, scoped);
+  registerSetupTools(server, scoped);
+  registerProtocolTools(server, scoped);
+  registerPushTools(server, scoped);
+  refuseCoordinatorTools(server, deps);
   return server;
 }
 
-/**
- * Spec §4.7: connect first, so the client never waits on a scan; then reconcile every run. Spec §3.4: the notifier
- * starts before reconcile, so what reconcile settles is announced, and scans for the rest once it is done. Spec
- * 1.2 §3.2: the source sync starts once connected and is never awaited, so neither the handshake nor a tool call
- * waits on the network. Tests pass their own transport and sync.
- */
+/** Connect immediately; initialized triggers recovery without delaying the handshake. */
 export async function startMcpServer(
-  o: { transport?: Transport; sync?: () => Promise<unknown> } = {},
+  o: {
+    transport?: Transport;
+    sync?: () => Promise<unknown>;
+    deps?: Deps;
+    /** plan 22: the boot lock (tests replace it); null while another live server holds it */
+    bootLock?: () => (() => void) | null;
+  } = {},
 ): Promise<void> {
-  const deps = defaultDeps();
-  // which of the session's variables this server got (never their values): the live check of spec §3.9
-  log("info", "session", {
-    sessionId: Boolean(deps.session?.sessionId),
-    hostSessionId: Boolean(deps.session?.hostSessionId),
-    socket: Boolean(deps.session?.socketPath),
-    token: Boolean(deps.session?.token),
+  const deps = o.deps ?? defaultDeps();
+  const observed = new Map<string, ReturnType<typeof startNotifier>>();
+  const server = buildServer(deps, (context) => {
+    const target = currentSession(context);
+    if (!target) return;
+    const key = sessionKey(target);
+    let active = observed.get(key);
+    if (!active) {
+      active = startNotifier(context);
+      observed.set(key, active);
+    }
+    const n = active;
+    return () => {
+      if (observed.get(key) === n) void n.scan();
+    };
   });
-  const notifier = startNotifier(deps);
-  await buildServer(deps).connect(o.transport ?? new StdioServerTransport());
-  const sync = o.sync ?? (() => backgroundSync());
-  void Promise.resolve()
-    .then(sync)
-    .catch((e: unknown) => log("debug", "sources", { error: errorMessage(e) }));
-  try {
-    const r = await reconcileAll(deps);
-    const shown = r.warnings.length;
-    for (const w of r.warnings) console.error(`catherd: ${w}`);
-    void r.done.then(() => {
-      for (const w of r.warnings.slice(shown)) console.error(`catherd: ${w}`);
+  const initialized = server.server.oninitialized!;
+  const closed = server.server.onclose!;
+  let generation = 0;
+  let notifier: ReturnType<typeof startNotifier> | undefined;
+  let recovery: Deps | undefined;
+  // plan 22: taken at the first initialize, held until this server closes; null: another server leads the boot
+  let boot: (() => void) | null | undefined;
+  const invalidate = () => {
+    generation++;
+    if (recovery) recovery.host = { host: "unknown", session: null, conflict: null };
+    notifier?.stop();
+    notifier = undefined;
+    for (const n of observed.values()) n.stop();
+    observed.clear();
+    closed();
+  };
+  server.server.onclose = () => {
+    invalidate();
+    boot?.();
+    boot = undefined;
+  };
+  server.server.oninitialized = () => {
+    invalidate();
+    initialized();
+    boot ??= (o.bootLock ?? takeBootLock)();
+    const lead = boot !== null;
+    if (!lead) log("info", "boot", { skipped: "another catherd server runs the boot sync and reconcile" });
+    log("info", "session", {
+      host: deps.host.host,
+      conflict: deps.host.conflict,
+      sessionId: Boolean(deps.session?.sessionId),
+      hostSessionId: Boolean(deps.session?.hostSessionId),
+      socket: Boolean(deps.session?.socketPath),
+      token: Boolean(deps.session?.token),
     });
-  } catch (e) {
-    console.error(`catherd: reconcile failed: ${errorMessage(e)}`);
-  }
-  // whatever finished unread while no server ran, or finished under another server (spec §3.4)
-  void notifier.scan();
+    const epoch = generation;
+    recovery = { ...deps };
+    const context = recovery;
+    notifier = startNotifier(context);
+    const active = notifier;
+    const target = currentSession(context);
+    if (target) observed.set(sessionKey(target), active);
+    void Promise.resolve()
+      .then(() => {
+        if (lead && epoch === generation) return (o.sync ?? (() => backgroundSync()))();
+      })
+      .catch((e: unknown) => log("debug", "sources", { error: errorMessage(e) }));
+    void (async () => {
+      try {
+        if (epoch !== generation) return;
+        // the leading server reconciles every run; this one still watches the live roles of the runs its own
+        // session owns (a coordinator's server restarted mid-run) and tells its session what it owns
+        if (!lead) {
+          adoptOwned(context);
+          return void active.scan();
+        }
+        const r = await reconcileAll(context);
+        if (epoch !== generation) return;
+        const shown = r.warnings.length;
+        for (const w of r.warnings) console.error(`catherd: ${w}`);
+        void r.done.then(() => {
+          if (epoch === generation) for (const w of r.warnings.slice(shown)) console.error(`catherd: ${w}`);
+        });
+        if (epoch === generation) void active.scan();
+      } catch (e) {
+        console.error(`catherd: reconcile failed: ${errorMessage(e)}`);
+      }
+    })();
+  };
+  await server.connect(o.transport ?? new StdioServerTransport());
 }

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

@@ -59,7 +59,8 @@ export function registerSetupTools(server: McpServer, deps: Deps): void {
     },
     (a) =>
       handle(async () => {
-        const r = await (deps.sync ?? ((o) => syncSources(o)))({ force: a.force });
+        // (1.2 minor) a sync already running (the boot sync) answers busy at once, never a 120 s wait
+        const r = await (deps.sync ?? ((o) => syncSources(o)))({ force: a.force, wait: false });
         return {
           newlyScored: r.newlyScored,
           standInsNoLongerNeeded: r.noLongerNeeded,
@@ -76,16 +77,21 @@ export function registerSetupTools(server: McpServer, deps: Deps): void {
     {
       description:
         "A profile (without a name: the profile this repo runs on, i.e. the one bound to `repo`, default this server's directory, else the active one) as the run engine reads it, with every default filled in: per role its access mode, rungs and default rung, and whether its backend enforces the access (enforcement); billing, jev, harness isolation, failover, budget, timeouts, preflight, lock and notify. Also `active` (the global active profile), `here` (the profile this repo runs on) and every name.",
-      inputSchema: { name: PROFILE, repo: REPO },
+      inputSchema: { name: PROFILE, repo: REPO, raw: z.boolean().optional() },
     },
-    (a) => handle(async () => deps.profiles.get(a.name, await toplevel(a.repo))),
+    (a) =>
+      handle(async () =>
+        a.raw && deps.profiles.raw
+          ? deps.profiles.raw(a.name, await toplevel(a.repo))
+          : deps.profiles.get(a.name, await toplevel(a.repo)),
+      ),
   );
 
   server.registerTool(
     "profile_validate",
     {
       description:
-        "Check a profile (without a name: the profile this repo runs on, as in profile_get). errors block a save: the worker disabled, an enabled role with no usable rung, an unscored rung without a 'treat like', a failover stand-in unscored or on the same quota, a backend catherd cannot run. warnings do not: an access mode other than the role's default, a model the backend's listing lacks, a stand-in that never runs. Each has a path, a message and often a fix.",
+        "Check a profile (without a name: the profile this repo runs on, as in profile_get). errors block a save: the worker disabled, an enabled role with no usable rung, an unscored rung without a 'treat like', a failover stand-in unscored or on the same quota, a backend catherd cannot run. warnings do not: an access mode other than the role's default, a model the backend's listing lacks, a stand-in that never runs, a quota none of whose rungs ever starts a lane, and every kind and difficulty no worker rung clears. Each has a path, a message and often a fix.",
       inputSchema: { name: PROFILE, repo: REPO },
     },
     (a) => handle(async () => deps.profiles.validate(a.name, await toplevel(a.repo))),
@@ -95,7 +101,7 @@ export function registerSetupTools(server: McpServer, deps: Deps): void {
     "profile_set",
     {
       description:
-        "Apply a patch to a profile (without a name: the profile this repo runs on, as in profile_get; a new name starts from the default profile): objective, jev.use, billing, roles (enabled, access, network, rungs, defaultRung), harness isolation per backend, failover, budget, timeouts, preflight.confirm, lock.heavy and notify. Lists replace, maps merge, and null removes a key. An unknown key is refused. It validates first and writes nothing when invalid, unless the patch repairs an invalid profile: it fixes at least one of its errors and adds none, and then it saves with `errors` listing those still open. A save rewrites the agent files and relinks them. Returns saved, the errors and warnings, the diff, and newSessionNeededFor: the agents that apply from the next Claude Code session.",
+        "Apply a patch to a profile (without a name: the profile this repo runs on, as in profile_get; a new name starts from the default profile): objective, jev.use, billing, roles (enabled, access, network, rungs, defaultRung, timeouts: a role's own idleMin and wallMin over the profile's), harness isolation per backend, failover, budget, timeouts, preflight.confirm, lock.heavy and notify. Lists replace, maps merge, and null removes a key. An unknown key is refused. It validates first and writes nothing when invalid, unless the patch repairs an invalid profile: it fixes at least one of its errors and adds none, and then it saves with `errors` listing those still open. A save rewrites the agent files and relinks them. Returns saved, the errors and warnings, the diff, and newSessionNeededFor: the agents that apply from the next Claude Code session.",
       inputSchema: { name: PROFILE, repo: REPO, patch: ProfilePatchSchema },
     },
     (a) => handle(async () => deps.profiles.set(a.name, a.patch, await toplevel(a.repo))),