catherd-cli 1.4.0 → 2.0.0-beta.20261022113309

package/src/entry/profile-command.ts

@@ -3,11 +3,11 @@ 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 { pairOf } from "../domain/catalog.ts";
 import { CatherdError } from "../domain/errors.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 type { Issue } from "../domain/profile-rules.ts";
 import { ROLES, type Role } from "../domain/roles.ts";
 import { gitToplevel } from "../infra/git.ts";
 import { loadCatalog } from "../services/catalog-service.ts";
@@ -34,28 +34,24 @@ import {
   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;
 
 export interface StandIn {
   from: string;
   to: string;
-  inferred: boolean;
-  via: string | null;
-  /** what the treat-like lends, as `profile show` says it */
+  /** `no Slopalytics index` when the stand-in is not indexed, so routing skips it */
   note: string | null;
 }
 
-/** Spec §7.2: each stand-in; `via` names the rung whose scores it borrows (spec 1.1 §11). */
+/** Spec §7.2: each stand-in, noting one that has no Slopalytics index. */
 export function standIns(p: Profile, c: Catalog): StandIn[] {
-  return Object.entries(p.failover).map(([from, to]) => {
-    try {
-      return { from, to, ...inferredScores(c, rungInfo(c, to)) };
-    } catch {
-      return { from, to, inferred: false, via: null, note: null };
-    }
-  });
+  return Object.entries(p.failover).map(([from, to]) => ({
+    from,
+    to,
+    note: pairOf(c, to) === null ? "no Slopalytics index" : null,
+  }));
 }
 
 const value = (v: unknown) => (v === null ? "none" : typeof v === "string" ? v : JSON.stringify(v));
@@ -82,6 +78,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) {
@@ -89,9 +89,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);
@@ -104,6 +102,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"}`,
   );
@@ -186,7 +194,7 @@ const show = defineCommand({
     const o = {
       active: name === here,
       enforcement: roleEnforcement(p),
-      standIns: standIns(p, loadCatalog({ timings: false })),
+      standIns: standIns(p, loadCatalog()),
     };
     if (args.json) return printJson({ profile: p, ...o });
     for (const l of formatProfile(p, { ...o, backends: runnableBackends() })) console.log(l);
@@ -206,6 +214,7 @@ const use = defineCommand({
     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", {
@@ -234,6 +243,7 @@ const create = defineCommand({
     from: { type: "string", description: "copy this profile instead of the default one" },
   },
   run({ args }) {
+    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}` : ""}`);
@@ -249,6 +259,7 @@ const copy = defineCommand({
     to: { type: "positional", required: true, description: "new profile name" },
   },
   run({ args }) {
+    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}`);
@@ -263,6 +274,7 @@ const rm = defineCommand({
     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}`);
   },
@@ -281,6 +293,7 @@ const set = defineCommand({
     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}"`, {
@@ -342,6 +355,7 @@ const validate = defineCommand({
       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`);
@@ -370,6 +384,7 @@ const resetDefaults = defineCommand({
     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",

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

@@ -0,0 +1,159 @@
+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 { DISPATCH_ID_ENV, activityReporter } from "../infra/lock-activity.ts";
+import { runMilestoneCheck } from "../services/milestone-check.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) 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,
+      }),
+    );
+  },
+});
+
+const runCheck = defineCommand({
+  meta: {
+    name: "run",
+    description: "Run the milestone's full check on the committed HEAD, detached (gate_run)",
+  },
+  args: {
+    run: GATE.run,
+    milestone: { type: "string", required: true, description: "the milestone you verify, like M1" },
+    command: GATE.command,
+    at: { type: "string", description: "a checkout of the run's base, to record the base's own failures" },
+    force: { type: "boolean", description: "run it again although a record of this HEAD exists" },
+  },
+  async run({ args }) {
+    assertRoleMay(scope(), args.run, "gate_run");
+    if (!ID_PATTERN.test(args.milestone))
+      throw new CatherdError("E_INPUT_INVALID", `bad milestone "${args.milestone}"`, {
+        fix: "pass --milestone M1",
+      });
+    // a shell tool call may be cut off; the check goes on, and this ticks the dispatch's activity while it waits
+    const reporter = activityReporter(process.env[DISPATCH_ID_ENV]);
+    try {
+      const r = await runMilestoneCheck(
+        {
+          run: args.run,
+          milestone: args.milestone,
+          command: args.command,
+          ...(args.at ? { at: args.at } : {}),
+          ...(args.force ? { force: true } : {}),
+        },
+        reporter ? { onWait: reporter.tick } : {},
+      );
+      printJson(r);
+      if (!r.running && r.missing.length > 0) process.exitCode = 1;
+    } finally {
+      reporter?.done();
+    }
+  },
+});
+
+export const gateCommand = defineCommand({
+  meta: {
+    name: "gate",
+    description: "A verifier's gate evidence: check an item, record a pass, run the check",
+  },
+  subCommands: { check, pass, run: runCheck },
+});

package/src/entry/runs-command.ts

@@ -4,6 +4,7 @@ import { assertId } from "../domain/ids.ts";
 import { knownQueueCapability, UNCHECKED_QUEUE } from "../infra/codex-queue.ts";
 import { listDispatches } from "../services/dispatches.ts";
 import { retryDelivery } from "../services/notifier.ts";
+import { pauseLine } from "../services/pause.ts";
 import { inspectDelivery } from "../services/run-debug.ts";
 import { terminalHost } from "./host-arg.ts";
 import { formatBudget } from "../domain/budget.ts";
@@ -13,10 +14,13 @@ import { redact } from "../infra/log.ts";
 import { cancel } from "../services/dispatch-service.ts";
 import { registerSavedSecrets } from "../services/jev-service.ts";
 import { runDebug } from "../services/run-debug.ts";
+import { cleanScratch } from "../services/scratch.ts";
+import { repin } from "../services/run-pin.ts";
+import { supersedeRun } from "../services/run-service.ts";
 import { findRun, listRuns, readRecords, type Run } from "../services/run-store.ts";
 import { groupRuns, type RunSession, type SessionGroup } from "../services/session-view.ts";
 import { type RunSummary, status, summarizeRun } from "../services/summary.ts";
-import { JSON_ARG, mark, printJson } from "./cli-kit.ts";
+import { JSON_ARG, mark, printJson, refuseInRole } from "./cli-kit.ts";
 import { defaultDeps } from "./deps.ts";
 
 const json = JSON_ARG;
@@ -40,6 +44,10 @@ export function formatRun(s: RunSummary, now: number = Date.now()): string[] {
   ];
   for (const q of s.questions) lines.push(`  ${mark("warn")} parked ${q.milestone}: ${q.question}`);
   for (const l of s.live) lines.push(`  live ${l.name}  ${l.rung}  ${l.state} ${l.secs}s`);
+  if (s.waiting)
+    lines.push(
+      `  ${s.waiting.stalled ? `${mark("warn")} stalled · ` : ""}waiting for orchestrator since ${s.waiting.since} · ${s.waiting.seconds}s · ${s.waiting.unread} unread result(s)`,
+    );
   lines.push(
     `  done ${t.runs} role run(s), ${t.ok} ok${t.notOk.length ? `; not ok: ${t.notOk.join(", ")}` : ""}`,
     `  tokens ${n(t.tokens.input)} in (${n(t.tokens.cached)} cached) · ${n(t.tokens.output)} out · $${t.costUsd.toFixed(2)}` +
@@ -56,7 +64,7 @@ export function formatRun(s: RunSummary, now: number = Date.now()): string[] {
   for (const m of s.milestones) lines.push(`  landed ${m}`);
   if (s.verifier)
     lines.push(
-      `  verifier step ${s.verifier.item}${s.verifier.carried ? " (carried over)" : ""} at ${s.verifier.at.slice(11, 16)}`,
+      `  verifier step ${s.verifier.item}${s.verifier.carried ? " (carried over)" : ""} at ${s.verifier.at.slice(11, 16)} · ${Math.floor(s.verifier.secs / 60)} min ago · ${s.verifier.open ? "open" : `closed (${s.verifier.closedBy})`}`,
     );
   for (const d of s.delivery)
     lines.push(
@@ -83,6 +91,8 @@ async function printStatus(runId: string | undefined, asJson: boolean, live = fa
       : null;
   const r = redact(status(defaultDeps(host), runId, queue));
   if (asJson) return printJson(r);
+  // spec 1.5 "Group pause": a pause comes first, before any run
+  for (const p of r.paused) console.log(`${mark("warn")} ${pauseLine(p)}`);
   if (r.runs.length === 0) console.log("no runs yet");
   // grouped by session, as the runs page is (spec §4); a run shows once, under the session that started it
   const byId = new Map(r.runs.map((s) => [s.id, s]));
@@ -105,7 +115,7 @@ async function printStatus(runId: string | undefined, asJson: boolean, live = fa
       for (const l of rest) console.log(l);
     }
   }
-  console.log(`host ${r.host.host}${r.host.conflict ? ` · conflict: ${r.host.conflict}` : ""}`);
+  console.log(`inspection host ${r.host.host}${r.host.conflict ? ` · conflict: ${r.host.conflict}` : ""}`);
   if (r.queue)
     console.log(
       r.queue.checked === false
@@ -115,11 +125,12 @@ async function printStatus(runId: string | undefined, asJson: boolean, live = fa
   for (const w of r.warnings) console.log(`${mark("warn")} ${w}`);
 }
 
-/** Spec §8 `catherd status [run] [--json]`: that run, else every run with a live role, else the newest. */
+/** `catherd status [run] [--json]`: that run, else the live runs, else the runs waiting for their orchestrator, else the newest. */
 export const statusCommand = defineCommand({
   meta: {
     name: "status",
-    description: "A run at a glance (default: runs with a live role, else the newest)",
+    description:
+      "A run at a glance (default: live runs, else runs waiting for their orchestrator, else the newest)",
   },
   args: { run: { type: "positional", required: false, description: "run id" }, ...json },
   run({ args }) {
@@ -138,36 +149,20 @@ export function redrawMs(interval: string | undefined): number {
   return Math.max(1, secs) * 1000;
 }
 
-/** Spec §8 `catherd watch [--once]`: the TUI's Runs tab on a terminal, else a plain redraw. */
+/** Spec §8 `catherd watch [--once]`: the live runs redrawn as text. */
 export const watchCommand = defineCommand({
   meta: {
     name: "watch",
-    description:
-      "The live runs: the dashboard's Runs tab on a terminal, else redrawn as text (--once: print once)",
+    description: "The live runs, redrawn as text (--once: print once); catherd panel shows them in a browser",
   },
   args: {
     once: { type: "boolean", description: "print one snapshot and exit" },
-    interval: { type: "string", description: "seconds between text redraws when piped (default 2)" },
-    plain: {
-      type: "boolean",
-      description: "the dashboard in ASCII without colour (NO_COLOR also drops colour)",
-    },
-    "reduced-motion": { type: "boolean", description: "the dashboard without animation" },
+    interval: { type: "string", description: "seconds between text redraws (default 2)" },
     ...json,
   },
   async run({ args }) {
     const every = redrawMs(args.interval);
     if (args.once || args.json) return printStatus(undefined, args.json === true);
-    // on a terminal, watch is the dashboard's Runs tab (plan 6 Ruling 10); piped output keeps the plain view
-    if (process.stdin.isTTY && process.stdout.isTTY) {
-      const { openTui } = await import("./tui/run.tsx");
-      const rawArgs = [
-        ...(args.plain ? ["--plain"] : []),
-        ...(args["reduced-motion"] ? ["--reduced-motion"] : []),
-      ];
-      process.exitCode = await openTui({ rawArgs, tab: "runs", tty: true });
-      return;
-    }
     for (;;) {
       if (process.stdout.isTTY) process.stdout.write("\x1b[2J\x1b[H");
       await printStatus(undefined, false, true);
@@ -200,6 +195,8 @@ const list = defineCommand({
         roleRuns: s.totals.runs,
         session: s.session,
         continuedIn: s.continuedIn,
+        waiting: s.waiting,
+        supersededBy: s.supersededBy ?? null,
       };
     };
     const groups = groupRuns(shown);
@@ -210,7 +207,7 @@ const list = defineCommand({
       for (const x of g.runs) {
         const r = row(x.run);
         console.log(
-          `  ${r.id}  ${r.live ? `${r.live} live` : "idle"}  ${r.roleRuns} role run(s)  ${r.title}  ${r.repo}${movedNote(x)}`,
+          `  ${r.id}  ${r.supersededBy ? `superseded by ${r.supersededBy}` : r.live ? `${r.live} live` : r.waiting ? `${r.waiting.stalled ? "stalled · " : ""}waiting for orchestrator ${r.waiting.seconds}s` : "idle"}  ${r.roleRuns} role run(s)  ${r.title}  ${r.repo}${movedNote(x)}`,
         );
       }
     }
@@ -278,12 +275,31 @@ const cancelCmd = defineCommand({
     name: { type: "positional", required: true, description: "the role's name, as status lists it" },
   },
   async run({ args }) {
+    refuseInRole(process.env, "catherd runs cancel");
     const r = await cancel(defaultDeps(), args.id, args.name);
     console.log(`${mark("ok")} ${r.record.name} ${r.record.status}`);
     for (const h of r.hints) console.log(`  ${h}`);
   },
 });
 
+const clean = defineCommand({
+  meta: {
+    name: "clean",
+    description:
+      "Remove the roles' scratch folders (their TMPDIR) of a run with no live role, or of every such run",
+  },
+  args: { id: { type: "positional", required: false, description: "run id (default: every run)" }, ...json },
+  run({ args }) {
+    refuseInRole(process.env, "catherd runs clean");
+    const r = cleanScratch({ run: args.id });
+    if (args.json) return printJson(r);
+    for (const x of r.removed)
+      console.log(`${mark("ok")} ${x.run}  scratch removed (${n(Math.round(x.bytes / 1024))} KB)`);
+    for (const x of r.kept) console.log(`${mark("skip")} ${x.run}  scratch kept: ${x.why}`);
+    if (!r.removed.length && !r.kept.length) console.log("no scratch to remove");
+  },
+});
+
 const retryPush = defineCommand({
   meta: {
     name: "retry-push",
@@ -300,6 +316,7 @@ const retryPush = defineCommand({
     ...json,
   },
   async run({ args }) {
+    refuseInRole(process.env, "catherd runs retry-push");
     if (args["acknowledge-possible-duplicate"] !== true)
       throw new CatherdError("E_INPUT_INVALID", "Retry requires --acknowledge-possible-duplicate");
     assertId("role name", args.name);
@@ -328,9 +345,46 @@ const retryPush = defineCommand({
   },
 });
 
+const supersede = defineCommand({
+  meta: {
+    name: "supersede",
+    description: "Close a run with a pointer to the run that took it over; status hides it",
+  },
+  args: {
+    id: { type: "positional", required: true, description: "the run to close" },
+    by: { type: "string", required: true, description: "the run that took it over" },
+    ...json,
+  },
+  async run({ args }) {
+    refuseInRole(process.env, "catherd runs supersede");
+    const r = await supersedeRun(defaultDeps(), { run: args.id, by: args.by });
+    if (args.json) return printJson(r);
+    console.log(`${mark("ok")} ${r.run} superseded by ${r.by}`);
+    for (const h of r.hints ?? []) console.log(`  ${h}`);
+  },
+});
+
+const pin = defineCommand({
+  meta: {
+    name: "pin",
+    description: "Re-pin a run to the profile, access and isolation its repo runs on now",
+  },
+  args: { id: { type: "positional", required: true, description: "run id" }, ...json },
+  async run({ args }) {
+    refuseInRole(process.env, "catherd runs pin");
+    const r = await repin(defaultDeps(), { run: args.id });
+    if (args.json) return printJson(r);
+    console.log(`${mark("ok")} ${args.id} pinned to ${r.pin.profile}`);
+    for (const c of r.changed) console.log(`  was: ${c}`);
+  },
+});
+
 /** Spec §8 `catherd runs list|show [--debug]|cancel`; a bare `catherd runs` lists them, as `status` needs no run. */
 export const runsCommand = defineCommand({
-  meta: { name: "runs", description: "Runs: list them (the default), show one, cancel a live role" },
-  subCommands: { list, show, cancel: cancelCmd, "retry-push": retryPush },
+  meta: {
+    name: "runs",
+    description: "Runs: list them (the default), show one, cancel a live role, supersede or re-pin one",
+  },
+  subCommands: { list, show, cancel: cancelCmd, clean, "retry-push": retryPush, supersede, pin },
   default: "list",
 });