omp-conductor 0.15.10 → 0.15.12

package/src/cli.ts

@@ -1,101 +1,54 @@
 #!/usr/bin/env bun
 /**
  * Standalone entry point — the only operator surface after #309. Everything here
- * is argument handling and printing: the loop, the caps and the state live in
+ * is argument handling, the shared usage text, and the registration table that
+ * dispatches each verb to its own module in ./commands/<verb>.ts; the per-verb
+ * bodies moved there by the module split (#462), so a new operator subcommand
+ * is one file plus one table line. The loop, the caps and the state live in
  * ./daemon.ts and the background process lifecycle in ./lifecycle.ts.
  */
-import { randomUUID } from "node:crypto";
-import { closeSync, openSync, readFileSync, readSync, statSync } from "node:fs";
 import { userInfo } from "node:os";
-import { dirname, join } from "node:path";
-import { boardJson, boardSnapshotOnce, runBoard } from "./board.ts";
+import { loadConfig } from "./config.ts";
+import { AMEND_AREA_IDS } from "./setup.ts";
+import type { ProjectConfig } from "./types.ts";
+import { armCommand } from "./commands/arm.ts";
+import { boardCommand } from "./commands/board.ts";
+import { briefUpgradeCommand } from "./commands/brief-upgrade.ts";
+import { daemonCommand } from "./commands/daemon.ts";
+import { dashboardCommand } from "./commands/dashboard.ts";
+import { decisionCommand } from "./commands/decision.ts";
+import { disarmCommand } from "./commands/disarm.ts";
+import { doctorCommand } from "./commands/doctor.ts";
+import { eventCommand } from "./commands/event.ts";
+import { extendCommand } from "./commands/extend.ts";
+import { frictionCommand } from "./commands/friction.ts";
+import { helpCommand } from "./commands/help.ts";
+import { holdCommand } from "./commands/hold.ts";
+import { intakeCommand } from "./commands/intake.ts";
+import { ledgerCommand } from "./commands/ledger.ts";
+import { messageCommand } from "./commands/message.ts";
+import { reportCommand } from "./commands/report.ts";
+import { restartCommand } from "./commands/restart.ts";
+import { resumeCommand } from "./commands/resume.ts";
+import { setupCommand } from "./commands/setup.ts";
+import { startCommand } from "./commands/start.ts";
+import { statsCommand } from "./commands/stats.ts";
+import { statusCommand } from "./commands/status.ts";
+import { stopCommand } from "./commands/stop.ts";
+import { tailCommand } from "./commands/tail.ts";
+import { unblockCommand } from "./commands/unblock.ts";
+import { upgradeInstallCommand } from "./commands/upgrade-install.ts";
+import { upgradeRollbackCommand } from "./commands/upgrade-rollback.ts";
+import { upgradeCommand } from "./commands/upgrade.ts";
+import { verbCommand } from "./commands/verb.ts";
+import { versionCommand } from "./commands/version.ts";
+import { workerCommand } from "./commands/worker.ts";
 import {
-  applyRetrofit,
-  formatBriefReport,
-  formatMigrateResult,
-  formatRetrofitProposal,
-  formatRetrofitRefusal,
-  inspectBriefLayout,
-  migrateToPolicy,
-  missingSections,
-  proposeRetrofit,
-  repairPolicyBannerCrumbs,
-} from "./brief-upgrade.ts";
-import { interruptDisposition } from "./availability.ts";
-import { findProject, loadConfig, resolveCaps, stateDir } from "./config.ts";
-import { CONDITION_FORMS, parseCondition } from "./decisions.ts";
-import { isPaused, pausedAt, runDaemon, setPaused } from "./daemon.ts";
-import {
-  armTicks,
-  clearPaneHaltIfResolvable,
-  disarmTicks,
-  hold,
-  pinPaneHalt,
-  releaseHold,
-  renderStatus,
-  startHerdrFleet,
-  stopConductorPane,
-  telegramStateDir,
-} from "./fleet.ts";
-import { formatGraphSetup, graphRepos, writeGraphSetup, type GraphSetupWrite } from "./graph.ts";
-import { readBaseChain } from "./gitops.ts";
-import {
-  clearRecord,
-  DEFAULT_PORT,
-  livingDaemon,
-  restartDaemon,
-  startDaemon,
-  stopDaemon,
-  writeRecord,
-  type RestartResult,
-} from "./lifecycle.ts";
-import { STALL_MARKER_FILE } from "./orchestrator-tick.ts";
-import {
-  deliverOperatorMessage,
-  digestDedupeKey,
-  type OperatorMessageOutcome,
-} from "./reports.ts";
-import { digestDue } from "./digest-schedule.ts";
-import {
-  AMEND_AREA_IDS,
-  briefPathForProject,
-  policyPathForProject,
-  renderBriefForProject,
-  renderFloorForProject,
-  shippedBriefTemplate,
-  type AmendAreaId,
-} from "./setup.ts";
-import { runGraphInstall, runHostInstall } from "./setup-install.ts";
-import { DEFAULT_PROBES, NO_PROBES, setup } from "./setup-wizard.ts";
-import { terminalUi } from "./wizard-ui.ts";
-import { dbPath, LIVE_STATES, openStore } from "./store.ts";
-import { formatTranscriptLine } from "./transcript.ts";
-import { formatVerbLedgerEntry } from "./verbs/ledger.ts";
-import { makeTracker } from "./tracker/github.ts";
-import { githubVerbActions } from "./verbs/actions.ts";
-import { handleVerbCall, type VerbChannel } from "./verbs/server.ts";
-import { REPORT_KINDS, DEFAULT_REPORT_POLICY, VERB_NAMES } from "./types.ts";
-import type { ProjectConfig, ReportKind } from "./types.ts";
-import { formatUnblock, unblockIssue } from "./unblock.ts";
-import { DEFAULT_DEPS, drainAndRestart, upgradeConductor, type UpgradeDeps } from "./upgrade.ts";
-
-const FRICTION_FEEDBACK_KINDS = {
-  "escalation-digest": "feedback:escalation-should-digest",
-  "report-noise": "feedback:report-noise",
-  "report-surprise": "feedback:report-surprise",
-} as const;
-
-type FrictionFeedbackName = keyof typeof FRICTION_FEEDBACK_KINDS;
-
-function packageVersion(): string {
-  const parsed = JSON.parse(readFileSync(join(import.meta.dir, "..", "package.json"), "utf8")) as {
-    version?: unknown;
-  };
-  if (typeof parsed.version !== "string" || parsed.version.length === 0) {
-    throw new Error("installed package.json has no version");
-  }
-  return parsed.version;
-}
+  COMMAND_SCOPES,
+  resolveProjectsByScope,
+  type CommandContext,
+  type CommandHandler,
+} from "./commands/context.ts";
 
 const USAGE = `omp-conductor — dispatch ready issues to omp coding sessions
 
@@ -106,8 +59,13 @@ usage:
   omp-conductor stop [--pane] [--project NAME | --all]
   omp-conductor restart [--now] [--timeout SECONDS] [--port N] [--project NAME]
   omp-conductor upgrade [--to VERSION] [--project NAME]
+  omp-conductor upgrade-install --to VERSION [--project NAME]
+  omp-conductor upgrade-rollback
   omp-conductor board [--project NAME] [--json]
+  omp-conductor dashboard [--port N] [--host ADDR]
   omp-conductor status [--project NAME]
+  omp-conductor stats [--since 7d|30d|YYYY-MM-DD] [--project NAME] [--json]
+  omp-conductor doctor [--project NAME] [--json] [--probe-telegram]
   omp-conductor ledger [--issue N] [--limit N] [--project NAME]
   omp-conductor hold [--keep-ticks] [--project NAME | --all]
   omp-conductor arm [--project NAME | --all]
@@ -124,12 +82,16 @@ usage:
   omp-conductor brief-upgrade [--migrate|--retrofit] [--apply] [--file PATH] [--project NAME]
   omp-conductor friction <escalation-digest|report-noise|report-surprise> --detail TEXT [--issue N] [--project NAME]
   omp-conductor event record --category NAME --summary TEXT --evidence REF [--occurred-at ISO] [--project NAME]
-  omp-conductor report --text TEXT [--kind material|digest] [--events IDS] [--notices IDS] [--project NAME]
-  omp-conductor message --text TEXT [--project NAME]
+  omp-conductor report --text TEXT [--kind material|digest|tier2|decision-needed|fleet-stopped|confirmed-failure] [--events IDS] [--notices IDS] [--project NAME]
+  omp-conductor message --text TEXT [--category CATEGORY] [--blocks TEXT] [--project NAME]
   omp-conductor decision open --question TEXT [--blocks TEXT] [--resolves-when COND] [--project NAME]
   omp-conductor decision resolve <id> --answer TEXT [--project NAME]
   omp-conductor decision withdraw <id> [--reason TEXT] [--project NAME]
   omp-conductor decision list [--project NAME]
+  omp-conductor intake "<text>" [--project NAME]
+  omp-conductor intake list [--project NAME]
+  omp-conductor intake dismiss <id> [--project NAME]
+  omp-conductor intake groomed <id> --issue <url> [--project NAME]
   omp-conductor help
 
   setup    interview, then write config.json, the labels, the briefs and the
@@ -141,13 +103,23 @@ usage:
            brief as one pinned release. Pauses only new claims, drains live
            workers, reloads, verifies twice, and restores the prior dispatch
            state. Run it from a shell outside the target Herdr session.
+  upgrade-install
+           the detached executor half of the fleet-installs-itself request:
+           the same transaction, journaled per surface, leaving verification
+           and dispatch restore to the first tick after the restart. Run by
+           the transient unit, never by hand in a Herdr session.
+  upgrade-rollback
+           the detached rollback unit: restore every surface the failed
+           upgrade-install touched, from the durable pre-install snapshot in
+           the upgrade journal, and report through the durable outbox.
   start    start the installed herdr-fleet.service when present, then run the
            dispatch loop in the background and wait until it answers GET
            /healthz on :8787 (override with --port). Refuses if one is running.
   stop     stop the conductor: pause claiming, disarm ticks, then stop the
-           dispatch daemon (systemctl-aware, so Restart=on-failure cannot bring
-           it back). Pane stays up unless --pane is passed. To bounce the daemon
-           without stopping the fleet, use restart.
+           dispatch daemon (systemctl-aware: an explicit stop is recorded by
+           systemd, so Restart=always does not undo it). Pane stays up unless
+           --pane is passed. To bounce the daemon without stopping the fleet,
+           use restart.
   stop --pane
            also stop the conductor agent's pane and pin herdr-conductor recovery
            off for that agent only — it does NOT stop herdr-fleet.service or any
@@ -166,11 +138,34 @@ usage:
   status   layered fleet report: dispatch (running|paused|stopped), ticks and
            next due time, pane, herdr, Telegram bot/API health, daemon, caps
            and active runs.
+  stats    what the fleet accomplished and at what cost, read wholly from the
+           local store: issues merged, merge rate, queue-to-merge lead time
+           (median/p90), attempts per merged issue, metered spend per merged
+           issue, the failure-class breakdown of what did not merge, and
+           tracked gh calls over the window. Continuation chains collapse into
+           one journey; $0.00 runs are reported as unmetered, never averaged in
+           as free. --json prints the stable {project, window, ghCalls, empty,
+           total, repos} shape.
+  doctor   read-only deployment health, one finding per past failure mode:
+           gh auth/scopes, exact-case configured labels, systemd unit drift
+           and runtime-dir ownership, config + backup freshness, sqlite
+           integrity, spend telemetry, reporting timezones, Telegram health.
+           The only write anywhere is the self-identified probe message that
+           --probe-telegram sends through the report transport. Exit code 0
+           only when nothing failed; --json prints the stable CI shape. Run
+           it after install and after every upgrade.
   board    open the live keyboard-driven fleet board. It renders queue holds,
            every run lifecycle stage, recent merges, spend and health; Enter
            follows a selected transcript without leaving the board. --json (or
            a non-interactive stdin/stdout) prints a one-shot JSON snapshot of
            the same lanes instead.
+  dashboard
+           serve the fleet dashboard in a browser: the UI shell and GET
+           /api/projects, bearer-authenticated with the token minted 0600 at
+           <state>/dashboard-token on first start. Binds 127.0.0.1:8788 by
+           default; a non-loopback --host still starts but prints a warning
+           naming the token file. A separate process — never a route on the
+           daemon port.
   ledger   every conductor-verb call and how the daemon decided it: the verb,
            the arguments, allow or refuse, the named refusal reason, and the
            resulting sha. Sessions cannot push, open, merge, label or release
@@ -223,15 +218,25 @@ usage:
            be a repeat. --kind digest is accepted at most once per local day,
            decided from the ledger rather than from what you remember sending.
            A digest associates the comma-separated --events and --notices rows
-           atomically; omitted rows stay owed.
+           atomically; omitted rows stay owed. The other --kind values (tier2,
+           decision-needed, fleet-stopped, confirmed-failure) declare the
+           report's interrupt category: the reporting policy decides between
+           sending now and holding, exactly as for a daemon escalation. An
+           identical retry is refused only while the earlier handoff is still
+           undelivered, and admitted again once it lands (#453).
   message  deliver one direct Telegram message to this project's own chat and
            forum topic, resolved from config rather than from whichever chat
            last wrote to the session. This is how a locally injected tick
            answers or asks something directly: telegram_send keeps the active
            topic only while it names no chat, and a tick has no active topic to
-           keep. Text beginning "QUESTION:" carries the decision category; the
-           operator's availability policy still decides between sending now and
-           holding a notice, exactly as it does for an autonomous tick.
+           keep. A question — text beginning "QUESTION:", or a --category that
+           is not material — records an open decision row before delivery
+           (parked on silence: still pending in every tick until answered or
+           the seven-day expiry, so no one has to remember a separate
+           \`decision open\`), and --category carries the escalation category
+           directly instead of a text prefix. The operator's availability
+           policy still decides between sending now and holding a notice,
+           exactly as it does for an autonomous tick.
   decision record, list and close the questions you have put to your operator.
            A question that lives only in a session's context is lost to the next
            compaction, so \`decision open\` writes it down and every tick's prompt
@@ -243,6 +248,12 @@ usage:
              decision resolve <id> --answer TEXT
              decision withdraw <id> [--reason TEXT]
              decision list
+  intake   keep a raw idea durably before it becomes anything: record it now
+           with \`omp-conductor intake "<text>"\`, list what is still pending,
+           dismiss what turned out to be nothing. Backed by the sqlite store,
+           not a session, so ideas survive restarts; the orchestrator grooms
+           one into an issue as its #300 duty and records that provenance with
+           \`omp-conductor intake groomed <id> --issue <url>\`.
   friction record a bounded observation the daemon cannot classify itself:
            an escalation that belonged in a digest, or a tick report that was
            noise/surprising. Repeated observations feed the existing Learning
@@ -251,8 +262,11 @@ usage:
            and exits. This is what \`start\` launches.
   resume   clear pause and any pane-recovery pin. Does NOT re-arm: run arm after
            an inbound Telegram proof to bring ticks back. Use --all for every project.
-  setup host
+  setup host [NAME]
            re-stage the systemd unit and run the install behind one confirm.
+           The units are host-global; NAME (or --project NAME) says which
+           project's per-project tail (tick config, brief link) to write, and
+           is required on a host with several configured projects.
   setup graph
            set up the code-graph indexes workers query instead of grepping, end
            to end: check prerequisites, clone any missing index-only clone as
@@ -287,7 +301,7 @@ Stop the conductor:
   stop --pane       stop + pin conductor-pane recovery off
   resume && arm     clear pause and any pane pin, then prove inbound Telegram`;
 
-/** Accepts both `--port 9000` and `--port=9000`; returns undefined when absent. */
+/** Applies both `--port 9000` and `--port=9000`; returns undefined when absent. */
 function flag(argv: string[], name: string): string | undefined {
   const i = argv.indexOf(`--${name}`);
   if (i >= 0) return argv[i + 1];
@@ -305,9 +319,19 @@ function digestIdsFlag(argv: string[], name: "events" | "notices"): string[] {
     return [];
   }
   const ids = [...new Set(raw.split(",").map((id) => id.trim()).filter((id) => id.length > 0))];
+  // The three shapes the runtime actually mints as ledger row ids: 12-hex
+  // material event ids, UUID held-notice ids (quiet-hours material holds,
+  // operator messages), and 64-hex sha256 held-notice ids (escalate and the
+  // orchestrator tick). Anything else is a typo; refusing it is what keeps a
+  // mistyped id from silently claiming nothing.
   if (
     ids.length === 0 ||
-    ids.some((id) => !/^(?:[0-9a-f]{12}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/.test(id))
+    ids.some(
+      (id) =>
+        !/^(?:[0-9a-f]{12}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|[0-9a-f]{64})$/.test(
+          id,
+        ),
+    )
   ) {
     process.stderr.write(`omp-conductor: report --${name} needs comma-separated ledger row ids\n`);
     process.exit(2);
@@ -352,53 +376,6 @@ function humanDuration(ms: number): string {
   return `${Math.floor(h / 24)}d ${String(h % 24).padStart(2, "0")}h`;
 }
 
-
-/**
- * The orchestrator half, and the one thing `status` has ever known about the
- * supervising session: the stall marker its heartbeat writes when its own
- * prompts stop being consumed (see {@link STALL_MARKER_FILE}).
- *
- * The marker is written in the *session's* cwd, which this process has no way
- * to discover — so this reads the state directory, on the reference deploy's
- * convention that the orchestrator session runs from exactly there. That makes
- * the reading one-directional: a line printed here is proof of a wedge, and no
- * line is proof of nothing at all. On a fleet whose session lives elsewhere the
- * check is simply inert, which is why it never prints a reassuring "healthy".
- */
-function stallLine(): string | undefined {
-  let raw: string;
-  try {
-    raw = readFileSync(join(stateDir(), STALL_MARKER_FILE), "utf8").trim();
-  } catch {
-    return undefined;
-  }
-  // "<ISO timestamp> <one-line diagnosis>". A file truncated by something else
-  // still gets reported: that the marker exists at all is the news.
-  const cut = raw.indexOf(" ");
-  const since = cut < 0 ? raw : raw.slice(0, cut);
-  const diagnosis = cut < 0 ? "" : ` — ${raw.slice(cut + 1)}`;
-  return `orchestrator   STALLED since ${since === "" ? "an unrecorded time" : since}${diagnosis}`;
-}
-
-/**
- * `DaemonRecord.logFile` for a daemon nobody spawned. The field is required and
- * `status` prints it, so it has to say something true: a foreground daemon
- * opened no log of its own — whoever started it owns its stdout, be that
- * systemd's journal, a terminal, or a pane.
- */
-const FOREGROUND_LOG = "<inherited stdout — started in the foreground>";
-
-/** How often `tail` re-stats the transcript it is following. */
-const TAIL_POLL_MS = 1_000;
-
-/**
- * How long the transcript must stay unchanged, after its run has left the live
- * states, before `tail` calls it over. The state flips from the daemon's thread
- * while the harness may still be flushing its last message, so exiting on the
- * state alone truncates the ending an operator ran this command to watch.
- */
-const TAIL_QUIET_MS = 5_000;
-
 /**
  * The `<issue>` positional, for the two verbs that take one. Exits 2 rather
  * than following run #NaN or clearing the labels of issue #0; `verb` is named
@@ -414,86 +391,6 @@ function issueArg(verb: string, raw: string | undefined): number {
 }
 
 
-/**
- * Follow one run's transcript the way `tail -f` follows a log.
- *
- * Reads from byte zero rather than from the end: attaching to a worker that is
- * already ten turns in and then showing nothing until turn eleven is not
- * watching the run. Polls `stat` instead of taking a file watcher because the
- * transcript is a plain append-only file that may sit on a filesystem where
- * change events are a polite fiction, and one stat a second costs nothing.
- *
- * SIGINT is deliberately left to its default, which is immediate exit. Nothing
- * here is buffered, and a handler could only add a poll interval of latency to
- * every Ctrl-C.
- */
-async function tailRun(project: string, issue: number): Promise<void> {
-  // Read-only in practice: the store is opened WAL with a busy timeout, so this
-  // never contends with the daemon writing the same rows.
-  const store = openStore(dbPath());
-  try {
-    const run = store.latestRun(project, issue);
-    if (run === undefined) throw new Error(`no run recorded for #${issue}`);
-    const path = run.sessionFile;
-    // Claimed but not yet started, or an attempt whose session never opened one.
-    if (path === undefined) throw new Error(`no transcript yet (state: ${run.state})`);
-
-    const fd = openSync(path, "r");
-    try {
-      let offset = 0;
-      let pending = Buffer.alloc(0);
-      let lastChange = Date.now();
-
-      for (;;) {
-        let size = offset;
-        try {
-          size = statSync(path).size;
-        } catch {
-          // A transcript that vanishes mid-follow is not worth crashing over.
-          // The run's own state, below, is what decides when this command ends.
-        }
-        // Shorter than what we have already read means truncated or replaced;
-        // resuming from the old offset would read the middle of another file.
-        if (size < offset) {
-          offset = 0;
-          pending = Buffer.alloc(0);
-        }
-        if (size > offset) {
-          const chunk = Buffer.allocUnsafe(size - offset);
-          const read = readSync(fd, chunk, 0, chunk.length, offset);
-          offset += read;
-          // Split on newlines as bytes, not as text: a UTF-8 sequence straddling
-          // a read boundary would be mangled by decoding each chunk on its own.
-          pending = Buffer.concat([pending, chunk.subarray(0, read)]);
-          for (;;) {
-            const nl = pending.indexOf(0x0a);
-            if (nl < 0) break;
-            const rendered = formatTranscriptLine(pending.subarray(0, nl).toString("utf8"));
-            pending = pending.subarray(nl + 1);
-            if (rendered !== undefined) process.stdout.write(`${rendered}\n`);
-          }
-          if (read > 0) lastChange = Date.now();
-        }
-
-        // Re-read this exact run every poll — not `latestRun`, which would jump
-        // to a retry started meanwhile and report its state against the wrong
-        // transcript. The daemon writes the row from another process, so looking
-        // is the only way to notice the run finished.
-        const state = store.getRun(run.id)?.state ?? run.state;
-        if (!LIVE_STATES.includes(state) && Date.now() - lastChange >= TAIL_QUIET_MS) {
-          process.stdout.write(`run ended: ${state}\n`);
-          return;
-        }
-        await new Promise<void>((resolve) => setTimeout(resolve, TAIL_POLL_MS));
-      }
-    } finally {
-      closeSync(fd);
-    }
-  } finally {
-    store.close();
-  }
-}
-
 const argv = process.argv.slice(2);
 const cmd = argv[0];
 /**
@@ -503,1189 +400,111 @@ const cmd = argv[0];
  * `ProjectConfig` under that name.
  */
 const projectFlag = flag(argv, "project");
+/**
+ * The parsed essentials every command receives. Argument parsing lives above
+ * (and behind) this object; a command module reads what it needs and never
+ * imports this entry point, so no verb depends on another's edits here beyond
+ * the table line that names it.
+ */
+const ctx: CommandContext = {
+  argv,
+  projectFlag,
+  flag: (name) => flag(argv, name),
+  portFlag: () => portFlag(argv),
+  turnsFlag: () => turnsFlag(argv),
+  digestIdsFlag: (name) => digestIdsFlag(argv, name),
+  issueArg: (verb, raw) => issueArg(verb, raw),
+  targetProjects: () => targetProjects(),
+};
 
 function targetProjects(): ProjectConfig[] {
-  const cfg = loadConfig();
-  if (argv.includes("--all")) return cfg.projects;
-  if (projectFlag === undefined && cfg.projects.length > 1) {
-    throw new Error(
-      `config has ${cfg.projects.length} projects; use --project NAME or --all`,
-    );
-  }
-  return [findProject(cfg, projectFlag)];
+  // The fleet resolution, delegated to the scope machinery (#514) so the
+  // arm/disarm/hold/resume/stop "every project, or the named one" shape is
+  // the same code the classification describes it as.
+  return resolveProjectsByScope(loadConfig(), "fleet", projectFlag, argv.includes("--all"));
 }
 
-try {
-  switch (cmd) {
-    case "--version":
-    case "-V":
-    case "version":
-      process.stdout.write(`${packageVersion()}\n`);
-      break;
-    case "setup": {
-      const sub = argv[1];
-      const positional = sub !== undefined && !sub.startsWith("--") ? sub : undefined;
-      // The terminal surface owns stdin for whichever path runs, and is released
-      // in a finally: a throw with readline still attached leaves the operator's
-      // shell without an echo.
-      const ui = terminalUi();
-      try {
-        // `host` and `graph` are install subcommands, checked BEFORE the amend
-        // areas. They are not areas — routing them through the area validation
-        // is how `setup host` came to exit 2 as an "unknown setup area".
-        if (positional === "host" || positional === "graph") {
-          const cfg = loadConfig();
-          const project = findProject(cfg, projectFlag);
-          const outcome =
-            positional === "host"
-              ? await runHostInstall(project, resolveCaps(project, cfg.defaults), telegramStateDir(), ui)
-              : await runGraphInstall(project, ui, {
-                  noSeed: argv.includes("--no-seed"),
-                  print: argv.includes("--print"),
-                });
-          // `staged` is a success on a host that has no systemd: the files are
-          // real, only the enable step is impossible.
-          if (outcome.kind === "refused" || outcome.kind === "failed") process.exit(1);
-          break;
-        }
-        let area: AmendAreaId | undefined;
-        if (positional !== undefined) {
-          if (!(AMEND_AREA_IDS as readonly string[]).includes(positional)) {
-            process.stderr.write(
-              `omp-conductor: unknown setup argument "${positional}" — ` +
-                `install subcommands are host, graph; amend areas are ${AMEND_AREA_IDS.join(", ")}\n`,
-            );
-            process.exit(2);
-          }
-          area = positional as AmendAreaId;
-        }
-        // `--no-ai` is the interview with its reading half removed: every question
-        // is still asked, nothing is proposed. For a host with no omp peer, a
-        // private repo no probe can clone, or an operator who would rather type the
-        // gates than review a model's reading of their CI.
-        await setup(ui, projectFlag, area, argv.includes("--no-ai") ? NO_PROBES : DEFAULT_PROBES);
-      } finally {
-        ui.close();
-      }
-      break;
-    }
-    case "upgrade": {
-      const result = await upgradeConductor({
-        version: flag(argv, "to"),
-        project: projectFlag,
-      });
-      process.stdout.write(
-        `${result.alreadyCurrent ? "already current" : "upgrade complete"}:\n` +
-          `  Bun-global CLI     omp-conductor@${result.version}\n` +
-          `  omp plugin         omp-conductor@${result.version}\n` +
-          `  Herdr plugin       herdr-conductor@${result.gitHead}\n` +
-          `  orchestrator brief managed ORCHESTRATOR.md floor current; POLICY.md preserved\n` +
-          `  dispatch           ${result.dispatch}${result.alreadyCurrent ? "" : " restored"}\n`,
-      );
-      break;
-    }
-    case "daemon": {
-      // Until now only `lifecycle.startDaemon()` — the spawn path — wrote the
-      // pidfile, which left a daemon started in the foreground (which is how
-      // systemd runs it) invisible twice over: `omp-conductor status` reported
-      // no daemon at all, and a `daemon --once` drill run beside it saw
-      // `livingDaemon() === undefined`, concluded nothing else was dispatching,
-      // and reconciled the live daemon's in-flight runs as orphans. Writing the
-      // record here closes both holes.
-      const once = argv.includes("--once");
-      const port = portFlag(argv);
-      const project = projectFlag;
-
-      // `--once` registers nothing, on purpose. It is precisely the single-tick
-      // drill the orphan guard exists to protect, so a drill that announced
-      // itself as the daemon would be the process that misleads the next reader
-      // — and would clear the real daemon's record on its way out.
-      if (once) {
-        await runDaemon({ once, port, project });
-        break;
-      }
-
-      const running = livingDaemon();
-      if (running !== undefined && running.pid !== process.pid) {
-        process.stderr.write(`omp-conductor: another daemon is alive (pid ${running.pid}); stop it first\n`);
-        process.exit(1);
-      }
-
-      // A living record that already names this pid was written by the `start`
-      // that spawned us, and it knows the log file our stdout is really going
-      // to. Replacing it with a guess would be a downgrade.
-      if (running === undefined) {
-        writeRecord({
-          pid: process.pid,
-          port: port ?? DEFAULT_PORT,
-          startedAt: Date.now(),
-          logFile: FOREGROUND_LOG,
-          ...(project === undefined ? {} : { project }),
-        });
-      }
-
-      try {
-        await runDaemon({ once, port, project });
-      } finally {
-        // The record names a pid that is about to stop existing. Leaving it
-        // behind makes the next reader probe a ghost before believing us.
-        clearRecord();
-      }
-      break;
-    }
-
-    case "start": {
-      const project = projectFlag;
-      const herdr = startHerdrFleet(project);
-      const rec = await startDaemon({ port: portFlag(argv), project });
-      process.stdout.write(
-        `started — pid ${rec.pid}, /healthz on :${rec.port}` +
-          `${rec.project === undefined ? "" : `, project ${rec.project}`}\n` +
-          `herdr ${herdr.kind === "active" ? `active (${herdr.unit})${herdr.recoveryReleased ? "; recovery pin cleared" : ""}` : `unmanaged (${herdr.reason})`}\n` +
-          `log ${rec.logFile}\n`,
-      );
-      break;
-    }
-
-    // `stop` absorbs the old `halt`: one word for "stop the conductor", instead of
-    // an operator holding in their head that `halt` was `hold` plus stopping the
-    // daemon while `stop` killed only the process. Bouncing the daemon is
-    // `restart`, which is what the removed kill-only `stop` was reached for.
-    case "stop": {
-      const withPane = argv.includes("--pane");
-      const targets = targetProjects().map((project) => {
-        // `stop` takes the fleet down, so it always disarms — `--keep-ticks` is a
-        // `hold` affordance. Assert the invariant instead of printing a path that
-        // might not exist.
-        const held = hold(project.name, "halt");
-        if (held.disarmed === undefined) throw new Error("stop must disarm ticks");
-        return {
-          project,
-          hold: { ...held, disarmed: held.disarmed },
-          pin: withPane ? pinPaneHalt(project.name).path : undefined,
-        };
-      });
-      const stop = await stopDaemon();
-      const stopLine =
-        stop.kind === "not-running"
-          ? "daemon was not running"
-          : `daemon stopped — pid ${stop.pid}${stop.via === "systemctl" ? " (via systemctl)" : ""}`;
-      for (const target of targets) {
-        if (target.pin !== undefined) {
-          const pane = await stopConductorPane(target.project.name);
-          process.stdout.write(
-            `stopped — claiming paused; ticks disarmed at ${target.hold.disarmed.path}\n` +
-              `${stopLine}\n` +
-              `pane recovery pinned at ${target.pin}\n` +
-              `pane stop: ${pane.stopped} — ${pane.detail}\n` +
-              `  (conductor agent "${pane.agentName}" only — herdr-fleet.service was NOT stopped;\n` +
-              `   resume clears the pin when you want recovery again)\n`,
-          );
-        } else {
-          process.stdout.write(
-            `stopped — claiming paused; ticks disarmed at ${target.hold.disarmed.path}\n` +
-              `${stopLine}\n` +
-              `pane left running (pass --pane to stop the conductor agent and pin recovery)\n`,
-          );
-        }
-      }
-      break;
-    }
-
-    case "restart": {
-      if (argv.includes("--now")) {
-        // Inherit the running daemon's port and project: a restart that quietly
-        // moved to the default port would leave every existing health check
-        // pointing at nothing. When the unit owns the live pid, restartDaemon
-        // goes through systemctl so the replacement stays supervised; a failed
-        // installed unit is reset and started through systemd the same way and
-        // is never replaced by an unmanaged daemon. Success is only reported
-        // after the manager is proven to own the reported pid.
-        const { previous, record, via } = await restartDaemon({
-          port: portFlag(argv),
-          project: projectFlag,
-        });
-        if (previous !== undefined) {
-          process.stdout.write(
-            `stopped — pid ${previous.pid}${via === "systemctl" ? " (via systemctl)" : ""}\n`,
-          );
-        }
-        process.stdout.write(
-          `started — pid ${record.pid}, /healthz on :${record.port}` +
-            `${record.project === undefined ? "" : `, project ${record.project}`}` +
-            `${via === "systemctl" ? " (via systemctl)" : ""}\nlog ${record.logFile}\n`,
-        );
-        break;
-      }
-
-      // Default: drain the fleet before restarting — pause new claims, wait for
-      // live workers to reach 0/N (bounded by --timeout), restart, then restore
-      // the prior dispatch state. A timed-out drain restarts nothing and leaves
-      // dispatch paused, so it is safe to run while the daemon is wedged.
-      const timeoutRaw = flag(argv, "timeout");
-      const timeoutSeconds =
-        timeoutRaw === undefined ? 1800 : Number.parseInt(timeoutRaw, 10);
-      const timeoutMs = (Number.isNaN(timeoutSeconds) ? 1800 : timeoutSeconds) * 1000;
-      let result!: RestartResult;
-      const deps: UpgradeDeps = {
-        ...DEFAULT_DEPS,
-        setPaused: (v, project) =>
-          setPaused(v, { source: "restart", reason: "restart, draining" }, project),
-        restartDaemon: async () => {
-          result = await restartDaemon({
-            port: portFlag(argv),
-            project: projectFlag,
-          });
-        },
-      };
-      try {
-        await drainAndRestart(deps, { project: projectFlag, timeoutMs });
-      } catch (err) {
-        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
-        process.exit(1);
-      }
-      if (result.previous !== undefined) {
-        process.stdout.write(
-          `stopped — pid ${result.previous.pid}${result.via === "systemctl" ? " (via systemctl)" : ""}\n`,
-        );
-      }
-      process.stdout.write(
-        `started — pid ${result.record.pid}, /healthz on :${result.record.port}` +
-          `${result.record.project === undefined ? "" : `, project ${result.record.project}`}` +
-          `${result.via === "systemctl" ? " (via systemctl)" : ""}\nlog ${result.record.logFile}\n`,
-      );
-      break;
-    }
-
-    case "status": {
-      const project = projectFlag;
-      const text = await renderStatus(project);
-      const stalled = stallLine();
-      process.stdout.write(`${text}${stalled === undefined ? "\n" : `\n\n${stalled}\n`}`);
-      break;
-    }
-
-    /**
-     * The action ledger: mediated conductor verbs plus durable per-issue budget
-     * changes. Its own command as well as a block in `status`, because the two
-     * questions are different sizes. `status` answers "what is pending or being
-     * refused now"; this answers "what did run 3 actually try, and what budget
-     * did the operator assign", which needs history rather than only live state.
-     */
-    case "ledger": {
-      const cfg = loadConfig();
-      const p = findProject(cfg, projectFlag);
-      const issueFlag = flag(argv, "issue");
-      const issue = issueFlag === undefined ? undefined : issueArg("ledger", issueFlag);
-      const limitFlag = flag(argv, "limit");
-      const limit = limitFlag === undefined ? 50 : Number.parseInt(limitFlag, 10);
-      if (!Number.isSafeInteger(limit) || limit < 1) {
-        process.stderr.write(`omp-conductor: ledger --limit needs a positive integer, got "${limitFlag ?? ""}"\n`);
-        process.exitCode = 1;
-        break;
-      }
-      // Read-only, WAL, same as `tail`: this never contends with the daemon
-      // writing the rows it is printing.
-      const store = openStore(dbPath());
-      try {
-        const entries = store.verbLedger(p.name, {
-          ...(issue === undefined ? {} : { issue }),
-          limit,
-        });
-        const overrides = store.turnOverrideLedger(p.name, {
-          ...(issue === undefined ? {} : { issue }),
-          limit,
-        });
-        if (entries.length === 0 && overrides.length === 0) {
-          process.stdout.write(
-            `no conductor actions recorded for ${p.name}` +
-              `${issue === undefined ? "" : ` on #${String(issue)}`}\n`,
-          );
-          break;
-        }
-        const blocks: string[] = [];
-        if (entries.length > 0) {
-          const refused = entries.filter((e) => e.decision === "refused").length;
-          blocks.push(
-            `${p.name} — ${entries.length} verb call(s), ${refused} refused (newest first)\n` +
-              entries.flatMap(formatVerbLedgerEntry).join("\n"),
-          );
-        }
-        if (overrides.length > 0) {
-          blocks.push(
-            `${p.name} — ${overrides.length} turn override(s) (newest first)\n` +
-              overrides
-                .map(
-                  (entry) =>
-                    `  ${new Date(entry.setAt).toISOString()}  #${entry.issue}  ` +
-                    `${entry.maxTurns} turns`,
-                )
-                .join("\n"),
-          );
-        }
-        process.stdout.write(`${blocks.join("\n\n")}\n`);
-      } finally {
-        store.close();
-      }
-      break;
-    }
-
-    case "board": {
-      const project = projectFlag;
-      // Headless one-shot mode: `--json` asks for it explicitly, and a
-      // non-interactive stdin or stdout (pipe, redirect, cron, script) cannot
-      // host the key-driven board anyway. The TTY throw inside runBoard stays
-      // as a backstop for direct callers.
-      if (argv.includes("--json") || !process.stdout.isTTY || !process.stdin.isTTY) {
-        process.stdout.write(`${boardJson(await boardSnapshotOnce(project))}\n`);
-        break;
-      }
-      await runBoard(project);
-      break;
-    }
-
-    case "hold": {
-      const keepTicks = argv.includes("--keep-ticks");
-      for (const project of targetProjects()) {
-        const r = hold(project.name, "hold", keepTicks ? { keepTicks: true } : {});
-        process.stdout.write(
-          `held — claiming paused` +
-            `${r.wasPaused ? " (already paused)" : ""}` +
-            (r.disarmed === undefined
-              ? "; ticks left armed — resume restores the fleet with no new arm challenge"
-              : `; ticks disarmed at ${r.disarmed.path}` +
-                `${r.disarmed.wasArmed ? "" : " (was already disarmed)"}`) +
-            `\ndaemon and pane left running; stop to stop the daemon too\n`,
-        );
-      }
-      break;
-    }
-
-    // Removed verbs keep a case rather than falling through to usage: an operator
-    // who typed the old word gets the new one, not a wall of help text. Exit 2 is
-    // the same code an unknown verb uses.
-    case "halt":
-      process.stderr.write('omp-conductor: "halt" is now "stop" — see help\n');
-      process.exit(2);
-      break;
-
-    case "pause":
-      process.stderr.write(
-        'omp-conductor: "pause" is gone — "hold" pauses claiming AND disarms ticks; see help\n',
-      );
-      process.exit(2);
-      break;
-
-    case "release-pane":
-      process.stderr.write('omp-conductor: "release-pane" is now part of "resume" — see help\n');
-      process.exit(2);
-      break;
-
-    case "graph-setup":
-      process.stderr.write('omp-conductor: "graph-setup" is now "setup graph" — see help\n');
-      process.exit(2);
-      break;
-
-    case "arm": {
-      for (const project of targetProjects()) {
-        process.stdout.write("arm: sending inbound Telegram challenge…\n");
-        const r = await armTicks(project.name);
-        process.stdout.write(
-          `ARMED — inbound round-trip proved with owner ${r.owner}; ticks are now live.\n` +
-            `marker ${r.path}${r.alreadyArmed ? " (replaced previous marker)" : ""}\n`,
-        );
-      }
-      break;
-    }
-
-    case "disarm": {
-      for (const project of targetProjects()) {
-        const r = disarmTicks(project.name);
-        process.stdout.write(
-          `disarmed — ticks will be skipped` +
-            `${r.wasArmed ? "" : " (was already disarmed)"}\n` +
-            `marker ${r.path}\n`,
-        );
-      }
-      break;
-    }
-
-    case "tail": {
-      const issue = issueArg("tail", argv[1]);
-      await tailRun(findProject(loadConfig(), projectFlag).name, issue);
-      break;
-    }
-
-    case "extend": {
-      const issue = issueArg("extend", argv[1]);
-      const maxTurns = turnsFlag(argv);
-      const project = findProject(loadConfig(), projectFlag);
-      const daemon = livingDaemon();
-      if (daemon === undefined) throw new Error("daemon is not running");
-      if (daemon.project !== undefined && daemon.project !== project.name) {
-        throw new Error(
-          `daemon serves project "${daemon.project}", not requested project "${project.name}"`,
-        );
-      }
-      const response = await fetch(
-        `http://127.0.0.1:${daemon.port}/runs/${issue}/turn-limit`,
-        {
-          method: "PUT",
-          headers: { "content-type": "application/json" },
-          body: JSON.stringify({ project: project.name, maxTurns }),
-        },
-      );
-      const payload = (await response.json()) as {
-        error?: unknown;
-        kind?: unknown;
-        runId?: unknown;
-        maxTurns?: unknown;
-        issue?: unknown;
-        nextAttemptMaxTurns?: unknown;
-        baseMaxTurns?: unknown;
-      };
-      if (!response.ok) {
-        throw new Error(
-          typeof payload.error === "string" ? payload.error : `daemon returned HTTP ${response.status}`,
-        );
-      }
-      if (
-        payload.kind === "next-attempt" &&
-        payload.issue === issue &&
-        typeof payload.nextAttemptMaxTurns === "number" &&
-        typeof payload.baseMaxTurns === "number"
-      ) {
-        process.stdout.write(
-          `#${issue} next attempt turn ceiling set to ${payload.nextAttemptMaxTurns} ` +
-            `(project base ${payload.baseMaxTurns})\n`,
-        );
-        break;
-      }
-      if (typeof payload.runId !== "string" || typeof payload.maxTurns !== "number") {
-        throw new Error("daemon returned an invalid turn-extension response");
-      }
-      process.stdout.write(
-        `#${issue} turn ceiling extended to ${payload.maxTurns} (run ${payload.runId})\n`,
-      );
-      break;
-    }
-
-    case "worker": {
-      const sub = argv[1];
-      if (sub !== "pause" && sub !== "resume" && sub !== "stop") {
-        process.stderr.write(
-          "omp-conductor: worker needs pause, resume, or stop, then an issue number\n",
-        );
-        process.exit(2);
-      }
-      const issue = issueArg("worker", argv[2]);
-      const rawReason = sub === "stop" ? flag(argv, "reason") : undefined;
-      const reason = rawReason?.trim().replace(/\s+/g, " ");
-      if (sub === "stop" && (reason === undefined || reason === "" || reason.length > 500)) {
-        process.stderr.write(
-          "omp-conductor: worker stop needs --reason with 1-500 characters\n",
-        );
-        process.exit(2);
-      }
-      const project = findProject(loadConfig(), projectFlag);
-      const daemon = livingDaemon();
-      if (daemon === undefined) throw new Error("daemon is not running");
-      if (daemon.project !== undefined && daemon.project !== project.name) {
-        throw new Error(
-          `daemon serves project "${daemon.project}", not requested project "${project.name}"`,
-        );
-      }
-      const response = await fetch(
-        `http://127.0.0.1:${daemon.port}/runs/${issue}/${sub}`,
-        {
-          method: "PUT",
-          headers: { "content-type": "application/json" },
-          body: JSON.stringify({
-            project: project.name,
-            ...(reason === undefined ? {} : { reason }),
-          }),
-        },
-      );
-      const payload = (await response.json()) as {
-        error?: unknown;
-        runId?: unknown;
-        phase?: unknown;
-        outcome?: unknown;
-        state?: unknown;
-        reason?: unknown;
-        salvageSha?: unknown;
-        salvageError?: unknown;
-        worktree?: unknown;
-      };
-      if (!response.ok) {
-        throw new Error(
-          typeof payload.error === "string" ? payload.error : `daemon returned HTTP ${response.status}`,
-        );
-      }
-      if (sub === "stop") {
-        if (
-          typeof payload.runId !== "string" ||
-          typeof payload.state !== "string" ||
-          (payload.outcome !== "stopped" && payload.outcome !== "already-terminal")
-        ) {
-          throw new Error("daemon returned an invalid worker-stop response");
-        }
-        if (payload.outcome === "already-terminal") {
-          process.stdout.write(
-            `#${issue} worker already terminal: ${payload.state} (run ${payload.runId})\n`,
-          );
-          break;
-        }
-        if (typeof payload.reason !== "string") {
-          throw new Error("daemon returned an invalid worker-stop response");
-        }
-        process.stdout.write(
-          `#${issue} worker stopped (run ${payload.runId}): ${payload.reason}\n`,
-        );
-        if (typeof payload.salvageSha === "string") {
-          process.stdout.write(`work preserved: ${payload.salvageSha}\n`);
-        }
-        if (typeof payload.salvageError === "string") {
-          process.stdout.write(
-            `WIP SALVAGE FAILED: ${payload.salvageError}\n` +
-            `worktree kept: ${typeof payload.worktree === "string" ? payload.worktree : "(path unavailable)"}\n`,
-          );
-        }
-        break;
-      }
-      if (typeof payload.runId !== "string" || typeof payload.phase !== "string") {
-        throw new Error("daemon returned an invalid worker-control response");
-      }
-      process.stdout.write(`#${issue} worker ${payload.phase} (run ${payload.runId})\n`);
-      break;
-    }
-
-    case "unblock": {
-      const issue = issueArg("unblock", argv[1]);
-      const cfg = loadConfig();
-      const project = findProject(cfg, projectFlag);
-      const store = openStore(dbPath());
-      try {
-        const outcome = await unblockIssue(project, makeTracker(project), store, issue, {
-          force: argv.includes("--force"),
-          requeue: !argv.includes("--no-requeue"),
-        });
-        process.stdout.write(`${formatUnblock(issue, outcome, project, resolveCaps(project, cfg.defaults))}\n`);
-        // A refusal must not read as success to a script or a board keypress.
-        if (outcome.refused !== undefined) process.exitCode = 3;
-      } finally {
-        store.close();
-      }
-      break;
-    }
-
-    /**
-     * The external-orchestrator half of the verbs (#167): run any
-     * `conductor_*` verb from the CLI, through the daemon's own checks and
-     * ledger. An orchestrator that merges, labels or releases through this
-     * gets exactly the same refusals a session would and writes the same
-     * ledger rows — the raw `gh pr merge` a session reaches for instead is
-     * invisible to both.
-     *
-     * Worker-only verbs (conductor_push, conductor_pr_create) refuse with
-     * `role-not-allowed` — correct, and deliberately not special-cased here.
-     *
-     * Accepted limitation: the daemon's in-process one-merge-per-project slot
-     * does not span the daemon and a concurrent CLI merge. The execution-time
-     * head re-read (`--match-head-commit` in prMergeVerb) is the cross-process
-     * guard, so a CLI merge races a daemon merge exactly as two daemon merges
-     * would.
-     */
-    case "verb": {
-      const name = argv[1];
-      if (name === undefined || !VERB_NAMES.some((n) => n === name)) {
-        process.stderr.write(
-          `omp-conductor: unknown verb "${name ?? ""}". Known verbs: ${VERB_NAMES.join(", ")}\n`,
-        );
-        process.exit(2);
-      }
-      const cfg = loadConfig();
-      const project = findProject(cfg, projectFlag);
-      const args: Record<string, string> = {};
-      for (let i = 2; i < argv.length; i++) {
-        const token = argv[i];
-        if (token === "--arg") {
-          const pair = argv[i + 1];
-          if (pair === undefined || !pair.includes("=")) {
-            process.stderr.write(`omp-conductor: verb --arg needs k=v, got "${pair ?? ""}"\n`);
-            process.exit(2);
-          }
-          const eq = pair.indexOf("=");
-          args[pair.slice(0, eq)] = pair.slice(eq + 1);
-          i++;
-        } else if (token === "--project" || token?.startsWith("--project=") === true) {
-          // Consumed by `projectFlag` above; both spellings skip here.
-          if (token === "--project") i++;
-        } else {
-          process.stderr.write(
-            `omp-conductor: verb: unexpected argument "${token ?? ""}" (pass verb arguments as --arg k=v)\n`,
-          );
-          process.exit(2);
-        }
-      }
-      const store = openStore(dbPath());
-      try {
-        const channel: VerbChannel = {
-          kind: "orchestrator",
-          path: "cli",
-          project: project.name,
-          role: "orchestrator",
-        };
-        const reply = await handleVerbCall(
-          {
-            project: () => findProject(loadConfig(), project.name),
-            store,
-            tracker: makeTracker(project),
-            actions: githubVerbActions(project),
-            fleetStop: () =>
-              isPaused(project.name)
-                ? "claiming is paused for this fleet (omp-conductor hold or stop)"
-                : undefined,
-            pausedAt: () => pausedAt(project.name),
-            log: (m) => process.stderr.write(`${m}\n`),
-            now: () => Date.now(),
-            chain: { readBaseChain },
-          },
-          channel,
-          { verb: name, args },
-        );
-        process.stdout.write(`${reply.text}\n`);
-        // A refusal must not read as success to a script calling this.
-        if (!reply.ok) process.exitCode = 3;
-      } finally {
-        store.close();
-      }
-      break;
-    }
-
-    case "event": {
-      if (argv[1] !== "record") {
-        process.stderr.write("omp-conductor: event needs the record subcommand\n");
-        process.exit(2);
-      }
-      const category = flag(argv, "category");
-      const summary = flag(argv, "summary")?.replace(/\s+/g, " ").trim();
-      const evidence = flag(argv, "evidence")?.replace(/\s+/g, " ").trim();
-      if (
-        category === undefined ||
-        !/^[a-z0-9][a-z0-9-]{0,31}$/.test(category) ||
-        summary === undefined ||
-        summary.length === 0 ||
-        summary.length > 240 ||
-        summary.startsWith("--") ||
-        evidence === undefined ||
-        evidence.length === 0 ||
-        evidence.length > 500 ||
-        evidence.startsWith("--")
-      ) {
-        process.stderr.write(
-          "omp-conductor: event record needs --category with a lowercase slug, --summary (1-240 chars), and --evidence (1-500 chars)\n",
-        );
-        process.exit(2);
-      }
-      const rawOccurredAt = flag(argv, "occurred-at");
-      const recordedAt = Date.now();
-      const occurredAt = rawOccurredAt === undefined ? recordedAt : Date.parse(rawOccurredAt);
-      if (!Number.isFinite(occurredAt)) {
-        process.stderr.write("omp-conductor: event record --occurred-at needs an ISO timestamp\n");
-        process.exit(2);
-      }
-      const project = findProject(loadConfig(), projectFlag);
-      const store = openStore(dbPath());
-      try {
-        const event = store.recordMaterialEvent({
-          project: project.name,
-          category,
-          summary,
-          evidence,
-          occurredAt,
-          recordedAt,
-        });
-        process.stdout.write(
-          `event ${event.id} recorded for ${project.name} (${event.category}, ${new Date(event.occurredAt).toISOString()}) — nothing sent\n`,
-        );
-      } finally {
-        store.close();
-      }
-      break;
-    }
-
-    /**
-     * The handover point. Authorship stays with the model; from here the daemon
-     * owns delivery, so "I sent the report" stops being a claim the model makes
-     * about a tool call it may never have run and becomes a row anyone can read
-     * back out of the store (#123).
-     */
-    case "report": {
-      const rawText = flag(argv, "text");
-      const body = rawText?.trim();
-      if (body === undefined || body.length === 0 || rawText?.startsWith("--") === true) {
-        process.stderr.write("omp-conductor: report needs --text with the rendered report\n");
-        process.exit(2);
-      }
-      const rawKind = flag(argv, "kind") ?? "material";
-      // Fail closed on an unknown kind rather than defaulting to `material`: a
-      // typo'd `--kind diggest` that silently became a material report would
-      // bypass the daily-digest guard, which is the one thing the kind is for.
-      if (!(REPORT_KINDS as readonly string[]).includes(rawKind)) {
-        process.stderr.write(
-          `omp-conductor: report --kind must be one of: ${REPORT_KINDS.join(", ")}\n`,
-        );
-        process.exit(2);
-      }
-      const kind = rawKind as ReportKind;
-      if (kind !== "digest" && (argv.includes("--events") || argv.includes("--notices"))) {
-        process.stderr.write(
-          "omp-conductor: report --events and --notices are valid only with --kind digest\n",
-        );
-        process.exit(2);
-      }
-      const project = findProject(loadConfig(), projectFlag);
-      const store = openStore(dbPath());
-      try {
-        const at = Date.now();
-        // #229: the policy decides what may interrupt the phone. A kind the
-        // policy defers is refused here rather than silently turning into a
-        // page, or a digest going out off-schedule.
-        const policy = project.reporting;
-        const digestPolicy = policy?.digest ?? { cadence: "per-tick" };
-        if (kind === "digest") {
-          if (digestPolicy.cadence === "none") {
-            process.stderr.write(`omp-conductor: report: digest cadence is "none" for this project\n`);
-            process.exit(2);
-          }
-          if (digestPolicy.cadence === "daily" && digestPolicy.at !== undefined) {
-            const lastKey = store.lastDigestDedupeKey(project.name);
-            const lastDay = lastKey === undefined ? undefined : lastKey.slice("digest:".length);
-            if (!digestDue(policy ?? DEFAULT_REPORT_POLICY, lastDay, at)) {
-              process.stderr.write(
-                `omp-conductor: report: the daily digest is not due until ${digestPolicy.at}` +
-                  `${digestPolicy.timezone === undefined ? "" : ` ${digestPolicy.timezone}`}\n`,
-              );
-              process.exit(2);
-            }
-          }
-        }
-        if (kind === "material") {
-          const disposition = interruptDisposition(policy, "material", at);
-          if (disposition === "digest") {
-            process.stderr.write(
-              "omp-conductor: report: material updates are digest-only under this reporting policy; fold this into the next digest (--kind digest)\n",
-            );
-            process.exit(2);
-          }
-          if (disposition === "availability") {
-            const noticeId = randomUUID();
-            store.addHeldNotice({
-              id: noticeId,
-              project: project.name,
-              category: "material",
-              summary: body.split("\n", 1)[0]!.slice(0, 240),
-              detail: body,
-              createdAt: at,
-              releaseOnAvailable: true,
-            });
-            process.stdout.write(
-              `held notice ${noticeId} queued for ${project.name} (material; quiet hours)\n` +
-                "the daemon will include it in the next digest or working-hours catch-up\n",
-            );
-            break;
-          }
-        }
-        const draft = {
-          project: project.name,
-          kind,
-          body,
-          // Only a daily digest is at-most-once. Per-tick digests and material
-          // reports describe new outcomes each time, so they carry no daily key.
-          ...(kind === "digest" && digestPolicy.cadence === "daily"
-            ? { dedupeKey: digestDedupeKey(at, digestPolicy.timezone) }
-            : {}),
-          at,
-        };
-        const { report, deduped } =
-          kind === "digest"
-            ? store.enqueueDigestReport(
-                draft,
-                digestIdsFlag(argv, "events"),
-                digestIdsFlag(argv, "notices"),
-              )
-            : store.enqueueReport(draft);
-        process.stdout.write(
-          deduped
-            ? `today's digest was already handed over as report ${report.id} (${report.state}) — nothing queued\n` +
-                "the ledger decides this, not your memory of the last tick; newly named rows remain owed for a later digest\n"
-            : `report ${report.id} queued for ${project.name} (${kind})\n` +
-                "the daemon owns delivery from here; omp-conductor status shows it until it lands\n",
-        );
-      } finally {
-        store.close();
-      }
-      break;
-    }
-
-    /**
-     * One direct message to the operator, on the project's own Telegram target.
-     *
-     * `telegram_send` inherits the chat of the last inbound message, and its
-     * `thread_id` defaults to the active topic *only* while `chat_id` is
-     * omitted — so a locally injected tick, which has no inbound message to
-     * inherit from, had no way to reach a project's forum topic and its answers
-     * landed in the main chat (#366). This resolves chat and topic from the
-     * project config instead of from session memory, and applies the same
-     * availability decision the autonomous tick gate applies, so the CLI is not
-     * a way around the operator's own interrupt policy.
-     */
-    case "message": {
-      const rawText = flag(argv, "text");
-      const body = rawText?.trim();
-      if (body === undefined || body.length === 0 || rawText?.startsWith("--") === true) {
-        process.stderr.write("omp-conductor: message needs --text with the message to deliver\n");
-        process.exit(2);
-      }
-      const project = findProject(loadConfig(), projectFlag);
-      const store = openStore(dbPath());
-      let outcome: OperatorMessageOutcome;
-      try {
-        outcome = await deliverOperatorMessage(project, body, {
-          store,
-          at: Date.now(),
-          noticeId: randomUUID(),
-        });
-      } catch (err) {
-        process.stderr.write(
-          `omp-conductor: message: ${err instanceof Error ? err.message : String(err)}\n`,
-        );
-        process.exit(2);
-      } finally {
-        store.close();
-      }
-      process.stdout.write(
-        outcome.kind === "sent"
-          ? // Not "into the topic": a stale topic degrades to the flat chat with
-            // its own warning on stderr, and this line must not contradict it.
-            `message delivered to ${project.name}'s configured Telegram target (${outcome.category})\n`
-          : `held notice ${outcome.noticeId} queued for ${project.name} (${outcome.category}; ` +
-              `${outcome.reason === "availability" ? "outside the availability window" : "a digest-only category"})\n` +
-              "nothing was sent; the daemon releases it with the next digest or working-hours catch-up\n",
-      );
-      break;
-    }
-
-    case "decision": {
-      const sub = argv[1];
-      const project = findProject(loadConfig(), projectFlag);
-      const store = openStore(dbPath());
-      try {
-        if (sub === "open") {
-          const question = flag(argv, "question")?.trim();
-          if (question === undefined || question.length === 0 || question.startsWith("--")) {
-            process.stderr.write(
-              "omp-conductor: decision open needs --question with the question you sent\n",
-            );
-            process.exit(2);
-          }
-          const condition = flag(argv, "resolves-when")?.trim();
-          if (condition !== undefined && parseCondition(condition) === undefined) {
-            process.stderr.write(
-              `omp-conductor: --resolves-when must be one of:\n${CONDITION_FORMS.map((f) => `  ${f}`).join("\n")}\n`,
-            );
-            process.exit(2);
-          }
-          const blocks = flag(argv, "blocks")?.trim();
-          const decision = store.createDecision({
-            project: project.name,
-            question,
-            ...(blocks === undefined || blocks.length === 0 ? {} : { blocks }),
-            ...(condition === undefined ? {} : { condition }),
-            at: Date.now(),
-          });
-          process.stdout.write(
-            `decision ${decision.id} recorded — resolve with: omp-conductor decision resolve ${decision.id} --answer "..."\n`,
-          );
-          break;
-        }
-
-        if (sub === "resolve" || sub === "withdraw") {
-          const id = argv[2];
-          if (id === undefined || id.startsWith("--")) {
-            process.stderr.write(`omp-conductor: decision ${sub} needs the decision id\n`);
-            process.exit(2);
-          }
-          const answered = sub === "resolve";
-          const text = answered ? flag(argv, "answer")?.trim() : flag(argv, "reason")?.trim();
-          if (answered && (text === undefined || text.length === 0)) {
-            process.stderr.write("omp-conductor: decision resolve needs --answer with what was decided\n");
-            process.exit(2);
-          }
-          const ok = store.resolveDecision(
-            id,
-            answered ? "answered" : "withdrawn",
-            text === undefined || text.length === 0 ? "withdrawn" : text,
-            Date.now(),
-          );
-          if (!ok) {
-            // A decision that is not open is a different mistake from an id that
-            // never existed, and the operator can only act on one of them.
-            process.stderr.write(
-              `omp-conductor: no open decision ${id} for ${project.name} — it was answered, withdrawn or expired, or the id is wrong\n`,
-            );
-            process.exit(1);
-          }
-          process.stdout.write(`decision ${id} ${answered ? "answered" : "withdrawn"}\n`);
-          break;
-        }
-
-        if (sub === "list" || sub === undefined) {
-          const open = store.openDecisions(project.name);
-          if (open.length === 0) {
-            process.stdout.write("no open decisions\n");
-            break;
-          }
-          const now = Date.now();
-          for (const d of open) {
-            const condition =
-              d.condition === undefined ? "-" : d.conditionMetAt === undefined ? "pending" : "met";
-            const hours = Math.max(0, Math.round((now - d.askedAt) / 3_600_000));
-            process.stdout.write(
-              `${d.id}  ${hours}h  blocks:${d.blocks ?? "-"}  condition:${condition}  ${d.question}\n`,
-            );
-          }
-          break;
-        }
-
-        process.stderr.write(
-          `omp-conductor: unknown decision subcommand "${sub}" — expected open, resolve, withdraw or list\n`,
-        );
-        process.exit(2);
-      } finally {
-        store.close();
-      }
-      break;
-    }
-
-    case "friction": {
-      const name = argv[1] as FrictionFeedbackName | undefined;
-      if (name === undefined || !Object.hasOwn(FRICTION_FEEDBACK_KINDS, name)) {
-        process.stderr.write(
-          "omp-conductor: friction needs one of: escalation-digest, report-noise, report-surprise\n",
-        );
-        process.exit(2);
-      }
-      const rawDetail = flag(argv, "detail");
-      const detail = rawDetail?.replace(/\s+/g, " ").trim();
-      if (
-        detail === undefined ||
-        detail.length === 0 ||
-        detail.length > 160 ||
-        rawDetail?.startsWith("--") === true
-      ) {
-        process.stderr.write("omp-conductor: friction needs --detail with 1-160 characters\n");
-        process.exit(2);
-      }
-      const issueText = flag(argv, "issue");
-      const issue = issueText === undefined ? undefined : issueArg("friction --issue", issueText);
-      const project = findProject(loadConfig(), projectFlag);
-      const store = openStore(dbPath());
-      try {
-        store.recordFriction(project.name, {
-          kind: FRICTION_FEEDBACK_KINDS[name],
-          occurrences: 1,
-          ...(issue === undefined ? {} : { issue }),
-          sample: detail,
-          at: Date.now(),
-        });
-      } finally {
-        store.close();
-      }
-      process.stdout.write(`friction recorded for ${project.name}: ${name} — ${detail}\n`);
-      break;
-    }
-
-    case "resume": {
-      for (const project of targetProjects()) {
-        releaseHold(project.name);
-        const pin = clearPaneHaltIfResolvable(project.name);
-        process.stdout.write(
-          "resumed — claiming allowed on the next tick\n" +
-            (pin.wasHalted
-              ? `pane recovery pin cleared — ${pin.path}\n`
-              : "no pane recovery pin to clear\n") +
-            "ticks stay disarmed — run `omp-conductor arm`\n",
-        );
-      }
-      break;
-    }
-
-    case "brief-upgrade": {
-      const override = flag(argv, "file");
-      let project: ProjectConfig | undefined;
-      let path: string;
-      if (override === undefined) {
-        project = findProject(loadConfig(), projectFlag);
-        path = briefPathForProject(project);
-      } else {
-        path = override;
-        try {
-          project = findProject(loadConfig(), projectFlag);
-        } catch {
-          project = undefined;
-        }
-      }
-
-      const workspaceRoot = project?.workspaceRoot ?? dirname(path);
-      const rendered =
-        project === undefined ? shippedBriefTemplate() : renderBriefForProject(project);
-      const floor = project === undefined ? shippedBriefTemplate() : renderFloorForProject(project);
-      const layout = inspectBriefLayout(workspaceRoot, rendered);
-
-      if (argv.includes("--retrofit")) {
-        let live: string;
-        try {
-          live = readFileSync(path, "utf8");
-        } catch {
-          process.stderr.write(`omp-conductor: no brief at ${path}.\n`);
-          process.exit(1);
-        }
-        const result = proposeRetrofit(live);
-        if (result.kind === "no-cut") {
-          process.stdout.write(
-            `brief ${path}\n\nNo Releases / Project context / Reporting / Amendments heading found — cannot classify a cut.\n`,
-          );
-          process.exit(1);
-        }
-        if (result.kind === "interleaved") {
-          process.stdout.write(`${formatRetrofitRefusal(path, result)}\n`);
-          process.exit(1);
-        }
-        process.stdout.write(`${formatRetrofitProposal(path, result.proposal)}\n`);
-        if (argv.includes("--apply")) {
-          const backup = applyRetrofit(path, result.proposal);
-          process.stdout.write(`\napplied retrofit — previous brief kept at ${backup}\n`);
-        }
-        break;
-      }
-
-      if (argv.includes("--migrate")) {
-        if (layout.kind === "overlay") {
-          if (!argv.includes("--apply")) {
-            process.stdout.write(
-              `${formatBriefReport(path, layout, [])}\n\n` +
-                "POLICY.md already present. --migrate --apply will strip any leading\n" +
-                "banner-comment crumbs from POLICY.md and recompose ORCHESTRATOR.md.\n",
-            );
-            break;
-          }
-          if (project === undefined) {
-            process.stderr.write(
-              "omp-conductor: repairing an overlay needs --project (or a config) so the floor renders.\n",
-            );
-            process.exit(1);
-          }
-          const repaired = repairPolicyBannerCrumbs({
-            orchestratorPath: layout.orchestratorPath,
-            policyPath: layout.policyPath,
-            floor: renderFloorForProject(project),
-          });
-          if (repaired === undefined) {
-            process.stdout.write(
-              `${formatBriefReport(path, layout, [])}\n\nrecomposed ORCHESTRATOR.md — POLICY.md needed no crumb strip.\n`,
-            );
-          } else {
-            process.stdout.write(`${formatMigrateResult(repaired)}\n`);
-          }
-          break;
-        }
-        if (layout.kind === "missing") {
-          process.stderr.write(`omp-conductor: no brief at ${path} to migrate.\n`);
-          process.exit(1);
-        }
-        if (layout.kind === "legacy-handwritten") {
-          process.stdout.write(`${formatBriefReport(path, layout, layout.missing)}\n`);
-          process.exit(1);
-        }
-        if (project === undefined && /\{\{[A-Za-z0-9_]+\}\}/.test(floor)) {
-          process.stderr.write(
-            "omp-conductor: --migrate needs --project (or a config) so the floor renders without {{PLACEHOLDER}}s.\n",
-          );
-          process.exit(1);
-        }
-        if (!argv.includes("--apply")) {
-          process.stdout.write(
-            [
-              `migrate ${layout.orchestratorPath}`,
-              "",
-              "Would write POLICY.md from the owned half below YOURS TO EDIT,",
-              "then recompose ORCHESTRATOR.md from the package floor + that policy.",
-              "",
-              "Apply:  omp-conductor brief-upgrade --migrate --apply",
-            ].join("\n") + "\n",
-          );
-          break;
-        }
-        const policyPath = project ? policyPathForProject(project) : join(workspaceRoot, "POLICY.md");
-        const result = migrateToPolicy({
-          orchestratorPath: layout.orchestratorPath,
-          policyPath,
-          floor: project ? renderFloorForProject(project) : floor,
-          owned: layout.owned,
-        });
-        process.stdout.write(`${formatMigrateResult(result)}\n`);
-        break;
-      }
-
-      // No `--migrate` / `--retrofit`: report the layout and what to run. The
-      // legacy single-file merge that used to live here is gone (#131) — a bare
-      // `--apply` now says so rather than silently doing nothing.
-      if (argv.includes("--apply")) {
-        process.stderr.write(
-          "brief-upgrade: the legacy single-file merge was removed in 0.4.3 — use --migrate --apply (bannered) or --retrofit --apply (hand-written)\n",
-        );
-        process.exit(2);
-      }
-
-      let missing: string[] = [];
-      if (layout.kind !== "overlay" && layout.kind !== "missing") {
-        let live: string;
-        try {
-          live = readFileSync(path, "utf8");
-        } catch {
-          process.stderr.write(
-            `omp-conductor: no brief at ${path}` +
-              `${override === undefined ? " — run `omp-conductor setup brief` and say yes to writing ORCHESTRATOR.md." : "."}\n`,
-          );
-          process.exit(1);
-        }
-        missing = missingSections(live, rendered);
-      }
-
-      process.stdout.write(`${formatBriefReport(path, layout, missing)}\n`);
-      if (layout.kind !== "overlay" && project === undefined) {
-        process.stdout.write(
-          "\nnote: no conductor config resolved on this host, so the template's\n" +
-            "{{PLACEHOLDER}} coordinates are unsubstituted. Section names are unaffected.\n",
-        );
-      }
-      break;
-    }
+/**
+ * Removed verbs keep an entry rather than falling through to usage: an operator
+ * who typed the old word gets the new one, not a wall of help text. Exit 2 is
+ * the same code an unknown verb uses. Each is a two-line pointer with its own
+ * fixed text and nothing to grow, so they stay as entries here instead of a
+ * file per alias — the #462 acceptance carve-out for two-line cases.
+ */
+const REMOVED: Record<string, string> = {
+  halt: '"halt" is now "stop" — see help',
+  pause: '"pause" is gone — "hold" pauses claiming AND disarms ticks; see help',
+  "release-pane": '"release-pane" is now part of "resume" — see help',
+  "graph-setup": '"graph-setup" is now "setup graph" — see help',
+};
 
-    case "help":
-    case "--help":
-    case "-h":
-      process.stdout.write(`${USAGE}\n`);
-      break;
+/**
+ * The registration table — verb → handler. Adding an operator subcommand is one
+ * module in ./commands/ plus one line here; nothing else about dispatch
+ * changes. Version and help are tiny enough that their handlers are single
+ * statements, but they still ride the table so every surface is nameable.
+ */
+const COMMANDS: Record<string, CommandHandler> = {
+  "--version": () => versionCommand(),
+  "-V": () => versionCommand(),
+  version: () => versionCommand(),
+  setup: () => setupCommand(ctx),
+  upgrade: () => upgradeCommand(ctx),
+  "upgrade-install": () => upgradeInstallCommand(ctx),
+  "upgrade-rollback": () => upgradeRollbackCommand(ctx),
+  daemon: () => daemonCommand(ctx),
+  start: () => startCommand(ctx),
+  stop: () => stopCommand(ctx),
+  restart: () => restartCommand(ctx),
+  status: () => statusCommand(ctx),
+  stats: () => statsCommand(ctx),
+  doctor: () => doctorCommand(ctx),
+  ledger: () => ledgerCommand(ctx),
+  board: () => boardCommand(ctx),
+  dashboard: () => dashboardCommand(ctx),
+  hold: () => holdCommand(ctx),
+  arm: () => armCommand(ctx),
+  disarm: () => disarmCommand(ctx),
+  tail: () => tailCommand(ctx),
+  extend: () => extendCommand(ctx),
+  worker: () => workerCommand(ctx),
+  unblock: () => unblockCommand(ctx),
+  verb: () => verbCommand(ctx),
+  event: () => eventCommand(ctx),
+  report: () => reportCommand(ctx),
+  message: () => messageCommand(ctx),
+  decision: () => decisionCommand(ctx),
+  intake: () => intakeCommand(ctx),
+  friction: () => frictionCommand(ctx),
+  resume: () => resumeCommand(ctx),
+  "brief-upgrade": () => briefUpgradeCommand(ctx),
+  help: () => helpCommand(USAGE),
+  "--help": () => helpCommand(USAGE),
+  "-h": () => helpCommand(USAGE),
+};
 
-    default:
-      process.stderr.write(
-        `${cmd === undefined ? "omp-conductor: no subcommand" : `omp-conductor: unknown subcommand "${cmd}"`}\n\n${USAGE}\n`,
-      );
-      process.exit(2);
+try {
+  const removed = cmd === undefined ? undefined : REMOVED[cmd];
+  if (removed !== undefined) {
+    process.stderr.write(`omp-conductor: ${removed}\n`);
+    process.exit(2);
+  }
+  const handler = cmd === undefined ? undefined : COMMANDS[cmd];
+  if (handler === undefined) {
+    process.stderr.write(
+      `${cmd === undefined ? "omp-conductor: no subcommand" : `omp-conductor: unknown subcommand "${cmd}"`}\n\n${USAGE}\n`,
+    );
+    process.exit(2);
+  }
+  // A "none"-scope verb does no per-project work, so --project cannot change
+  // what it does: refuse it with a reason instead of silently ignoring it
+  // (#514). Host-scoped verbs keep the flag because each one has a documented
+  // per-project tail (or already refuses to narrow, #389).
+  if (COMMAND_SCOPES[cmd ?? ""] === "none" && projectFlag !== undefined) {
+    process.stderr.write(`omp-conductor: ${cmd} does not take a project — it needs no --project\n`);
+    process.exit(2);
   }
+  await handler(ctx);
 } catch (err) {
   // Config, lifecycle and `gh` errors are written to be read by a human, so
   // surface the message rather than a stack.