catherd-cli 1.4.0 → 1.5.0

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

@@ -15,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";
 
@@ -23,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(
@@ -56,7 +68,7 @@ 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) =>
@@ -92,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),
@@ -103,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) =>
@@ -117,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

@@ -4,24 +4,91 @@ 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 { sessionKey, type HostContext } from "../../domain/host.ts";
-import { errorMessage } from "../../domain/errors.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. */
@@ -38,7 +105,7 @@ function logToolCalls(
     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 epoch = generation();
       const extra = args.at(-1) as { _meta?: Record<string, unknown> } | undefined;
@@ -102,16 +169,25 @@ export function buildServer(deps: Deps = defaultDeps(), observe?: ObserveSession
     return r;
   };
   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;
 }
 
 /** Connect immediately; initialized triggers recovery without delaying the handshake. */
 export async function startMcpServer(
-  o: { transport?: Transport; sync?: () => Promise<unknown>; deps?: Deps } = {},
+  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 = o.deps ?? defaultDeps();
   const observed = new Map<string, ReturnType<typeof startNotifier>>();
@@ -134,6 +210,8 @@ export async function startMcpServer(
   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 };
@@ -143,10 +221,17 @@ export async function startMcpServer(
     observed.clear();
     closed();
   };
-  server.server.onclose = invalidate;
+  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,
@@ -164,12 +249,18 @@ export async function startMcpServer(
     if (target) observed.set(sessionKey(target), active);
     void Promise.resolve()
       .then(() => {
-        if (epoch === generation) return (o.sync ?? (() => backgroundSync()))();
+        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;

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,
@@ -90,7 +91,7 @@ export function registerSetupTools(server: McpServer, deps: Deps): void {
     "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))),
@@ -100,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))),

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

@@ -0,0 +1,142 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import {
+  BaseRefSchema,
+  RELEASES,
+  WORKSPACE_LIMIT,
+  WorkspaceBudgetSchema,
+  WorkspaceIdSchema,
+} from "../../domain/workspace.ts";
+import { pauseWorkspace, resumeWorkspace } from "../../services/pause.ts";
+import type { Deps } from "../../services/ports.ts";
+import { setWorkspaceBudget, workspaceContract } from "../../services/workspace-admission.ts";
+import {
+  inspectWorkspace,
+  startWorkspace,
+  startWorkspaceChild,
+  workspaceStatus,
+} from "../../services/workspace-service.ts";
+import { handle } from "./result.ts";
+
+const id = WorkspaceIdSchema;
+const repos = z
+  .record(id, z.string().min(1))
+  .refine((r) => Object.keys(r).length <= WORKSPACE_LIMIT)
+  .optional();
+const aLines = z.array(z.string().min(1)).min(1).max(100);
+
+export function registerWorkspaceTools(server: McpServer, deps: Deps): void {
+  server.registerTool(
+    "workspace_inspect",
+    {
+      description:
+        "Resolve explicit workspace members from catherd.workspace.json or a supplied repo map. The root may be a plain directory. Reads only; never scans unrelated repositories.",
+      inputSchema: { root: z.string().min(1), repos },
+    },
+    (a) => handle(() => inspectWorkspace(a.root, a.repos)),
+  );
+  server.registerTool(
+    "workspace_start",
+    {
+      description:
+        "Snapshot a workspace's selected repositories, step dependency graph and optional shared budget (no cap unless given; raise it later with workspace_budget). A step releases its dependents when its milestone lands, or with release: 'merge' and base (e.g. origin/main) once its landed commit is an ancestor of that ref, checked when a dependent asks. Returns workspace.id and dir. Child single-repo runs are created later with workspace_child_start; no commits or pushes are performed.",
+      inputSchema: {
+        root: z.string().min(1),
+        title: z.string().min(1),
+        a_lines: aLines,
+        repos,
+        steps: z
+          .array(
+            // #43 finding 6: an unknown key (dependsOn for depends_on) is refused, never dropped
+            z.strictObject({
+              id,
+              repo: id,
+              title: z.string().min(1),
+              a_lines: aLines,
+              depends_on: z.array(id).max(WORKSPACE_LIMIT).optional(),
+              milestone: id.optional(),
+              release: z.enum(RELEASES).optional(),
+              base: BaseRefSchema.optional(),
+            }),
+          )
+          .min(1)
+          .max(WORKSPACE_LIMIT),
+        budget: WorkspaceBudgetSchema.optional(),
+      },
+    },
+    (a) =>
+      handle(() =>
+        startWorkspace(deps, {
+          root: a.root,
+          title: a.title,
+          aLines: a.a_lines,
+          repos: a.repos,
+          budget: a.budget,
+          steps: a.steps.map((s) => ({
+            id: s.id,
+            repo: s.repo,
+            title: s.title,
+            aLines: s.a_lines,
+            dependsOn: s.depends_on,
+            milestone: s.milestone,
+            release: s.release,
+            base: s.base,
+          })),
+        }),
+      ),
+  );
+  server.registerTool(
+    "workspace_contract",
+    {
+      description:
+        "Read or write the workspace's shared contract before any child run exists. Once a child is created the contract is frozen and copied into each child as workspace-contract.md.",
+      inputSchema: { workspace: z.string().min(1), content: z.string().optional() },
+    },
+    (a) => handle(() => workspaceContract(a)),
+  );
+  server.registerTool(
+    "workspace_child_start",
+    {
+      description:
+        "Create or return a step's single-repo run once its dependencies have landed their declared milestone, every dispatch of theirs is collected, and each 'merge' release's commit is in its base ref (fetch first; nothing is polled). Returns run, dir and the frozen contract path. Use the existing route, dispatch, verification and land tools on this child run.",
+      inputSchema: { workspace: z.string().min(1), step: id },
+    },
+    (a) => handle(() => startWorkspaceChild(deps, a)),
+  );
+  server.registerTool(
+    "workspace_pause",
+    {
+      description:
+        "Pause every child of a workspace on one blocker (a VPN, Docker down): admission refuses each dispatch and child start with E_ADMIT_PAUSED and the reason until workspace_resume. Running roles finish. status shows the pause first. Push the reason to the owner once.",
+      inputSchema: { workspace: z.string().min(1), reason: z.string().min(1) },
+    },
+    (a) => handle(() => pauseWorkspace(deps.now(), a)),
+  );
+  server.registerTool(
+    "workspace_resume",
+    {
+      description: "Lift a workspace's pause. Returns the pause it lifted, or null when none was in force.",
+      inputSchema: { workspace: z.string().min(1) },
+    },
+    (a) => handle(() => resumeWorkspace(deps.now(), a)),
+  );
+  const cap = z.number().finite().nonnegative().nullable().optional();
+  server.registerTool(
+    "workspace_budget",
+    {
+      description:
+        "Set or raise a workspace's shared budget: each of minutes, tokens and usd given as a number replaces that cap, null removes it, and one left out stays. A workspace has no cap unless one is set; its minutes count from its first child. Returns the budget, the spend and its status.",
+      inputSchema: { workspace: z.string().min(1), minutes: cap, tokens: cap, usd: cap },
+    },
+    (a) => handle(() => setWorkspaceBudget(deps, a)),
+  );
+  server.registerTool(
+    "workspace_status",
+    {
+      description:
+        "Read a workspace's step readiness, child run ids, landed milestones, aggregate spending and shared budget. Reads only; never starts children automatically.",
+      inputSchema: { workspace: z.string().min(1) },
+    },
+    (a) => handle(() => workspaceStatus(deps, a.workspace)),
+  );
+}

package/src/entry/pause-command.ts

@@ -0,0 +1,67 @@
+import { defineCommand } from "citty";
+import { CatherdError } from "../domain/errors.ts";
+import {
+  pauseLine,
+  pauseMachine,
+  pauseWorkspace,
+  resumeMachine,
+  resumeWorkspace,
+} from "../services/pause.ts";
+import { JSON_ARG, printJson, refuseInRole } from "./cli-kit.ts";
+
+/** Exactly one of --machine and --workspace: what a pause or resume covers. */
+function scope(args: { machine?: boolean; workspace?: string }, usage: string): "machine" | string {
+  if (args.machine === true && args.workspace === undefined) return "machine";
+  if (args.machine !== true && args.workspace) return args.workspace;
+  throw new CatherdError(
+    "E_INPUT_INVALID",
+    "name what to pause: --machine or --workspace <id>, one of them",
+    {
+      fix: usage,
+    },
+  );
+}
+
+const SCOPE_ARGS = {
+  machine: { type: "boolean", description: "every run on this machine" },
+  workspace: { type: "string", description: "every child of this workspace" },
+} as const;
+
+const PAUSE_USAGE = 'catherd pause --machine "the VPN takes the default route"';
+const RESUME_USAGE = "catherd resume --machine";
+
+/** Spec 1.5 "Group pause": one blocker, one pause, instead of a park per run and milestone. */
+export const pauseCommand = defineCommand({
+  meta: {
+    name: "pause",
+    description:
+      "Pause every run on this machine (--machine) or in a workspace: dispatches are refused until resume",
+  },
+  args: {
+    reason: { type: "positional", required: true, description: "why: what blocks the runs" },
+    ...SCOPE_ARGS,
+    ...JSON_ARG,
+  },
+  run({ args }) {
+    refuseInRole(process.env, "catherd pause");
+    const at = scope(args, PAUSE_USAGE);
+    const r =
+      at === "machine"
+        ? pauseMachine(Date.now(), args.reason)
+        : pauseWorkspace(Date.now(), { workspace: at, reason: args.reason });
+    if (args.json) return printJson(r);
+    console.log(pauseLine(r.pause));
+  },
+});
+
+export const resumeCommand = defineCommand({
+  meta: { name: "resume", description: "Lift a pause on this machine (--machine) or on a workspace" },
+  args: { ...SCOPE_ARGS, ...JSON_ARG },
+  run({ args }) {
+    refuseInRole(process.env, "catherd resume");
+    const at = scope(args, RESUME_USAGE);
+    const r = at === "machine" ? resumeMachine(Date.now()) : resumeWorkspace(Date.now(), { workspace: at });
+    if (args.json) return printJson(r);
+    console.log(r.resumed ? `resumed: ${pauseLine(r.resumed)}` : "nothing was paused");
+  },
+});