catherd-cli 1.3.0 → 1.5.0

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");
+  },
+});

package/src/entry/profile-command.ts

@@ -1,9 +1,12 @@
+import { readFileSync } from "node:fs";
+import { HOST_ARG, terminalHost } from "./host-arg.ts";
 import { assertProfileName } from "../domain/profile.ts";
 import { defineCommand } from "citty";
 import type { Catalog } from "../domain/catalog.ts";
 import { rungInfo } from "../domain/catalog.ts";
 import { CatherdError } from "../domain/errors.ts";
-import { type Change, patchAt, type Profile } from "../domain/profile.ts";
+import type { OrchestrationHost } from "../domain/host.ts";
+import { ProfileDocSchema, type Change, patchAt, type Profile } from "../domain/profile.ts";
 import { inferredScores, type Issue } from "../domain/profile-rules.ts";
 import { ROLES, type Role } from "../domain/roles.ts";
 import { gitToplevel } from "../infra/git.ts";
@@ -15,6 +18,7 @@ import {
   deleteProfile,
   diffNamed,
   patchProfile,
+  resetHostDefaults,
   unbind,
 } from "../services/profile-service.ts";
 import {
@@ -24,12 +28,13 @@ import {
   listProfiles,
   profileExists,
   readProjects,
+  readProfileDoc,
   requireProfile,
   roleEnforcement,
   runnableBackends,
   validateNamed,
 } from "../services/profile-store.ts";
-import { EXIT, JSON_ARG, mark, printJson } from "./cli-kit.ts";
+import { EXIT, JSON_ARG, mark, printJson, refuseInRole } from "./cli-kit.ts";
 
 const json = JSON_ARG;
 
@@ -77,6 +82,10 @@ export function formatProfile(
     `objective ${p.objective} · jev ${p.jev.use} · heavy slots ${p.lock.heavy} · notify ${p.notify.join(", ") || "none"}`,
     "roles",
   ];
+  const accessOf = (role: Role) =>
+    `${p.roles[role].access}${p.roles[role].network === false ? " (no network)" : ""}, ${o.enforcement[role]}`;
+  // the ladders start in one column, however long the longest access text ("(no network)" included)
+  const accessWidth = Math.max(27, ...ROLES.filter((r) => p.roles[r].enabled).map((r) => accessOf(r).length));
   for (const role of ROLES) {
     const rc = p.roles[role];
     if (!rc.enabled) {
@@ -84,9 +93,7 @@ export function formatProfile(
       continue;
     }
     const ladder = rc.rungs.map((r) => (r === rc.defaultRung ? `${r} (default)` : r)).join(" → ");
-    lines.push(
-      `  ${role.padEnd(width)}  ${`${rc.access}${rc.network === false ? " (no network)" : ""}, ${o.enforcement[role]}`.padEnd(27)}  ${ladder || "no rungs"}`,
-    );
+    lines.push(`  ${role.padEnd(width)}  ${accessOf(role).padEnd(accessWidth)}  ${ladder || "no rungs"}`);
   }
   // only what catherd can run today: a backend without an adapter has nothing to bill or isolate
   const runs = ([key]: [string, unknown]) => keyRunnable(key, o.backends);
@@ -99,6 +106,16 @@ export function formatProfile(
   const budget = Object.entries(p.budget).map(([k, v]) => (k === "usd" ? `$${v}` : `${v} ${k}`));
   lines.push(`budget ${budget.join(" · ") || "no cap"}`);
   lines.push(`timeouts idle ${p.timeouts.idleMin} min · wall ${p.timeouts.wallMin} min`);
+  // plan 23: a role's own timeouts, under the profile's
+  for (const role of ROLES) {
+    const t = p.roles[role].timeouts;
+    if (!t) continue;
+    const parts = [
+      ...(t.idleMin !== undefined ? [`idle ${t.idleMin} min`] : []),
+      ...(t.wallMin !== undefined ? [`wall ${t.wallMin} min`] : []),
+    ];
+    lines.push(`  ${role} ${parts.join(" · ")}`);
+  }
   lines.push(
     `preflight ${p.preflight.confirm ? "shows its commands and asks first" : "runs the checks without asking"}`,
   );
@@ -139,7 +156,10 @@ const list = defineCommand({
     name: "list",
     description: "Every profile, the one this repo runs on (*), and the repos bound to each",
   },
-  args: json,
+  args: {
+    ...HOST_ARG,
+    ...json,
+  },
   async run({ args }) {
     const active = await activeHere();
     const bindings = Object.entries(readProjects().bindings);
@@ -161,11 +181,20 @@ const show = defineCommand({
     name: "show",
     description: "A profile with every default filled in (without a name: the one this repo runs on)",
   },
-  args: { name: { type: "positional", required: false, description: "profile name" }, ...json },
+  args: {
+    ...HOST_ARG,
+    name: { type: "positional", required: false, description: "profile name" },
+    raw: { type: "boolean", description: "stored document without effective defaults" },
+    ...json,
+  },
   async run({ args }) {
     const here = await activeHere();
     const name = args.name === undefined ? here : requireProfile(args.name);
-    const p = getProfile(name);
+    if (args.raw)
+      return args.json
+        ? printJson(readProfileDoc(name))
+        : console.log(JSON.stringify(readProfileDoc(name), null, 2));
+    const p = getProfile(name, terminalHost(args.host).host);
     const o = {
       active: name === here,
       enforcement: roleEnforcement(p),
@@ -183,17 +212,19 @@ const use = defineCommand({
       "Make a profile active, bind it to this repo with --repo, or unbind this repo with --repo --clear",
   },
   args: {
+    ...HOST_ARG,
     name: { type: "positional", required: false, description: "profile name" },
     repo: { type: "boolean", description: "bind it to the git repo you are in, instead of making it active" },
     clear: { type: "boolean", description: "with --repo and no name: unbind the git repo you are in" },
   },
   async run({ args }) {
+    refuseInRole(process.env, "catherd profile use");
     if (args.clear) {
       if (!args.repo || args.name !== undefined)
         throw new CatherdError("E_INPUT_INVALID", "--clear goes with --repo and no profile name", {
           fix: "catherd profile use --repo --clear, inside the repo to unbind",
         });
-      const r = unbind(await repoHere());
+      const r = unbind(await repoHere(), terminalHost(args.host).host);
       console.log(`${mark("ok")} ${r.repo} is unbound`);
       printSynced(r);
       return;
@@ -202,7 +233,7 @@ const use = defineCommand({
       throw new CatherdError("E_INPUT_INVALID", "which profile? name one", {
         fix: "catherd profile use <name> [--repo], or catherd profile use --repo --clear",
       });
-    const r = activate(args.name, args.repo ? await repoHere() : null);
+    const r = activate(args.name, args.repo ? await repoHere() : null, terminalHost(args.host).host);
     console.log(`${mark("ok")} ${r.active} ${r.repo ? `is bound to ${r.repo}` : "is active"}`);
     printSynced(r);
   },
@@ -211,11 +242,13 @@ const use = defineCommand({
 const create = defineCommand({
   meta: { name: "new", description: "A new profile from the default one, or from --from <profile>" },
   args: {
+    ...HOST_ARG,
     name: { type: "positional", required: true, description: "new profile name" },
     from: { type: "string", description: "copy this profile instead of the default one" },
   },
   run({ args }) {
-    const r = createProfile(args.name, args.from);
+    refuseInRole(process.env, "catherd profile new");
+    const r = createProfile(args.name, args.from, terminalHost(args.host).host);
     if (!r.saved) throw refused(r.errors);
     console.log(`${mark("ok")} created ${args.name}${args.from ? ` from ${args.from}` : ""}`);
     printIssues([], r.warnings);
@@ -225,11 +258,13 @@ const create = defineCommand({
 const copy = defineCommand({
   meta: { name: "copy", description: "Copy a profile under a new name" },
   args: {
+    ...HOST_ARG,
     from: { type: "positional", required: true, description: "profile to copy" },
     to: { type: "positional", required: true, description: "new profile name" },
   },
   run({ args }) {
-    const r = createProfile(args.to, args.from);
+    refuseInRole(process.env, "catherd profile copy");
+    const r = createProfile(args.to, args.from, terminalHost(args.host).host);
     if (!r.saved) throw refused(r.errors);
     console.log(`${mark("ok")} copied ${args.from} to ${args.to}`);
     printIssues([], r.warnings);
@@ -238,8 +273,12 @@ const copy = defineCommand({
 
 const rm = defineCommand({
   meta: { name: "rm", description: "Delete a profile and its agent files (never the active or a bound one)" },
-  args: { name: { type: "positional", required: true, description: "profile name" } },
+  args: {
+    ...HOST_ARG,
+    name: { type: "positional", required: true, description: "profile name" },
+  },
   run({ args }) {
+    refuseInRole(process.env, "catherd profile rm");
     deleteProfile(args.name);
     console.log(`${mark("ok")} deleted ${args.name}`);
   },
@@ -252,17 +291,21 @@ const set = defineCommand({
       "Set one field: e.g. roles.worker.access read-only, budget.usd 20, failover.<rung> <rung>, roles.worker.rungs a,b; null removes",
   },
   args: {
+    ...HOST_ARG,
     path: { type: "positional", required: true, description: "dotted path, e.g. roles.verifier.access" },
     value: { type: "positional", required: true, description: "JSON, or a plain word; null removes the key" },
     profile: { type: "string", description: "the profile to change (default: the one this repo runs on)" },
   },
   async run({ args }) {
+    refuseInRole(process.env, "catherd profile set");
     // the CLI never creates a profile by setting a field of it: a typo would start a new one
     if (args.profile !== undefined && !profileExists(assertProfileName(args.profile)))
       throw new CatherdError("E_INPUT_INVALID", `no profile named "${args.profile}"`, {
         fix: `catherd profile new ${args.profile}`,
       });
-    const r = patchProfile(args.profile ?? (await activeHere()), patchAt(args.path, args.value));
+    const r = patchProfile(args.profile ?? (await activeHere()), patchAt(args.path, args.value), {
+      host: terminalHost(args.host).host,
+    });
     if (!r.saved) throw refused(r.errors);
     if (r.diff.length === 0) console.log("no change");
     for (const c of r.diff) console.log(`${mark("ok")} ${formatChange(c)}`);
@@ -282,6 +325,7 @@ const diff = defineCommand({
     description: "What differs between two profiles (the second defaults to the one this repo runs on)",
   },
   args: {
+    ...HOST_ARG,
     a: { type: "positional", required: true, description: "profile" },
     b: { type: "positional", required: false, description: "profile (default: the one this repo runs on)" },
     ...json,
@@ -290,6 +334,7 @@ const diff = defineCommand({
     const changes = diffNamed(
       args.b === undefined ? await activeHere() : requireProfile(args.b),
       requireProfile(args.a),
+      terminalHost(args.host).host,
     );
     if (args.json) return printJson(changes);
     if (changes.length === 0) console.log("no differences");
@@ -300,6 +345,7 @@ const diff = defineCommand({
 const validate = defineCommand({
   meta: { name: "validate", description: "Errors that block a save, and warnings that do not" },
   args: {
+    ...HOST_ARG,
     name: {
       type: "positional",
       required: false,
@@ -309,7 +355,12 @@ const validate = defineCommand({
   },
   async run({ args }) {
     const repo = await gitToplevel(process.cwd());
-    const v = validateNamed(args.name === undefined ? activeName(repo) : requireProfile(args.name), repo);
+    const v = validateNamed(
+      args.name === undefined ? activeName(repo) : requireProfile(args.name),
+      repo,
+      terminalHost(args.host).host,
+      { reach: true },
+    );
     if (args.json) printJson({ valid: v.errors.length === 0, ...v });
     else if (v.errors.length === 0 && v.warnings.length === 0) console.log(`${mark("ok")} valid`);
     else printIssues(v.errors, v.warnings);
@@ -317,8 +368,72 @@ const validate = defineCommand({
   },
 });
 
+const HOSTS: readonly OrchestrationHost[] = ["claude-code", "codex", "unknown"];
+
+const resetDefaults = defineCommand({
+  meta: {
+    name: "reset-host-defaults",
+    description: "Review and explicitly reset only architect/verifier host defaults",
+  },
+  args: {
+    ...HOST_ARG,
+    ...JSON_ARG,
+    name: { type: "positional", required: false },
+    preview: { type: "boolean" },
+    expect: { type: "string", description: "reviewed preview JSON file" },
+  },
+  async run({ args }) {
+    const name = args.name === undefined ? await activeHere() : requireProfile(args.name);
+    const host = terminalHost(args.host).host;
+    let r;
+    if (args.preview) r = resetHostDefaults(name, host, { preview: true });
+    else {
+      refuseInRole(process.env, "catherd profile reset-host-defaults");
+      if (!args.expect)
+        throw new CatherdError(
+          "E_INPUT_INVALID",
+          "saving host defaults requires --expect <reviewed-preview.json>",
+          { fix: "run reset-host-defaults --preview --json and review the output first" },
+        );
+      let expected, reviewed;
+      try {
+        const raw = JSON.parse(readFileSync(args.expect, "utf8")) as Record<string, unknown> | null;
+        expected = ProfileDocSchema.parse(raw?.expect);
+        const { profile, host: previewed } = raw ?? {};
+        if (typeof profile !== "string" || !HOSTS.includes(previewed as OrchestrationHost))
+          throw new Error("unbound preview");
+        reviewed = { profile, host: previewed as OrchestrationHost };
+      } catch {
+        throw new CatherdError("E_INPUT_INVALID", "invalid reviewed preview file", {
+          fix: "pass the JSON output of reset-host-defaults --preview --json",
+        });
+      }
+      r = resetHostDefaults(name, host, { preview: false, expect: expected, reviewed });
+    }
+    if (args.json) printJson(r);
+    else {
+      for (const c of r.diff) console.log(formatChange(c));
+      printIssues(r.errors, r.warnings);
+      printSynced(r);
+    }
+    if (r.errors.length) process.exitCode = EXIT.error;
+  },
+});
+
 /** Spec §8: `catherd profile list|show|use [--repo [--clear]]|new|copy|rm|set <path> <value>|diff|validate`. */
 export const profileCommand = defineCommand({
   meta: { name: "profile", description: "Profiles: which models each role runs, and how" },
-  subCommands: { list, show, use, new: create, copy, rm, set, diff, validate },
+  args: HOST_ARG,
+  subCommands: {
+    "reset-host-defaults": resetDefaults,
+    list,
+    show,
+    use,
+    new: create,
+    copy,
+    rm,
+    set,
+    diff,
+    validate,
+  },
 });

package/src/entry/role-cli-command.ts

@@ -0,0 +1,115 @@
+import { defineCommand } from "citty";
+import { CatherdError } from "../domain/errors.ts";
+import { ID_PATTERN } from "../domain/ids.ts";
+import { roleScopeFromEnv } from "../domain/role-scope.ts";
+import { gateCheckOrList, gatePass } from "../services/gate-service.ts";
+import { assertRoleMay } from "../services/role-access.ts";
+import { readRunFile, writeRunFile } from "../services/run-service.ts";
+import { printJson } from "./cli-kit.ts";
+import { defaultDeps } from "./deps.ts";
+
+/**
+ * Spec 1.5 plan 21: the role server's operations as commands any role can run from its shell, on a backend
+ * whose harness has no role server (opencode, Cursor, Grok Build, agy) or when no MCP tool is listed. In a role
+ * (CATHERD_ROLE, or its scratch TMPDIR) they are bound to its own run and its role's operations.
+ */
+const scope = () => roleScopeFromEnv(process.env);
+
+const RUN_PATH = {
+  run: { type: "positional", required: true, description: "the run id" },
+  path: { type: "positional", required: true, description: "a path relative to the run folder" },
+} as const;
+
+const read = defineCommand({
+  meta: { name: "read", description: "Print a file of the run folder (read_run_file)" },
+  args: RUN_PATH,
+  run({ args }) {
+    assertRoleMay(scope(), args.run, "read_run_file");
+    const text = readRunFile({ run: args.run, path: args.path });
+    process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
+  },
+});
+
+const write = defineCommand({
+  meta: { name: "write", description: "Write stdin to a file of the run folder (write_run_file)" },
+  args: RUN_PATH,
+  async run({ args }) {
+    assertRoleMay(scope(), args.run, "write_run_file");
+    const content = await Bun.stdin.text();
+    printJson(writeRunFile({ run: args.run, path: args.path, content }));
+  },
+});
+
+export const runFileCommand = defineCommand({
+  meta: { name: "run-file", description: "Read or write a run's plan, lanes, dossier and notes" },
+  subCommands: { read, write },
+});
+
+const GATE = {
+  run: { type: "positional", required: true, description: "the run id" },
+  item: { type: "string", required: true, description: "the gate item's name" },
+  command: { type: "string", required: true, description: "the command that checks it" },
+  paths: { type: "string", required: true, description: "the repo paths it depends on, comma-separated" },
+} as const;
+
+const pathsOf = (s: string): string[] => {
+  const paths = s
+    .split(",")
+    .map((p) => p.trim())
+    .filter(Boolean);
+  if (!paths.length)
+    throw new CatherdError("E_INPUT_INVALID", "--paths names no path", {
+      fix: "pass --paths src,package.json",
+    });
+  return paths;
+};
+
+const check = defineCommand({
+  meta: { name: "check", description: "Whether a gate item passed on unchanged content (gate_check)" },
+  // plan 23: with only the run and --milestone, it lists the milestone's recorded items (as gate_check does)
+  args: {
+    run: GATE.run,
+    item: { ...GATE.item, required: false },
+    command: { ...GATE.command, required: false },
+    paths: { ...GATE.paths, required: false },
+    milestone: { type: "string", description: "the milestone you verify, like M1" },
+  },
+  async run({ args }) {
+    assertRoleMay(scope(), args.run, "gate_check");
+    if (args.milestone !== undefined && !ID_PATTERN.test(args.milestone))
+      throw new CatherdError("E_INPUT_INVALID", `bad milestone "${args.milestone}"`, {
+        fix: "pass --milestone M1",
+      });
+    printJson(
+      await gateCheckOrList(defaultDeps(), {
+        run: args.run,
+        item: args.item,
+        command: args.command,
+        paths: args.paths === undefined ? undefined : pathsOf(args.paths),
+        ...(args.milestone ? { milestone: args.milestone } : {}),
+      }),
+    );
+  },
+});
+
+const pass = defineCommand({
+  meta: { name: "pass", description: "Record a passed gate item with its evidence (gate_pass)" },
+  args: { ...GATE, evidence: { type: "string", required: true, description: "what showed it passed" } },
+  async run({ args }) {
+    assertRoleMay(scope(), args.run, "gate_pass");
+    printJson(
+      await gatePass(defaultDeps(), {
+        run: args.run,
+        item: args.item,
+        command: args.command,
+        paths: pathsOf(args.paths),
+        evidence: args.evidence,
+      }),
+    );
+  },
+});
+
+export const gateCommand = defineCommand({
+  meta: { name: "gate", description: "A verifier's gate evidence: check an item, record a pass" },
+  subCommands: { check, pass },
+});