omp-conductor 0.16.0 → 0.16.2

package/src/cli.ts

@@ -9,8 +9,7 @@
  */
 import { userInfo } from "node:os";
 import { loadConfig } from "./config.ts";
-import { AMEND_AREA_IDS } from "./setup.ts";
-import type { ProjectConfig } from "./types.ts";
+import { COMMAND_MANIFEST, renderUsage } from "./command-manifest.ts";
 import { armCommand } from "./commands/arm.ts";
 import { boardCommand } from "./commands/board.ts";
 import { briefUpgradeCommand } from "./commands/brief-upgrade.ts";
@@ -53,276 +52,7 @@ import {
   type CommandHandler,
 } from "./commands/context.ts";
 
-const USAGE = `omp-conductor — dispatch ready issues to omp coding sessions
-
-usage:
-  omp-conductor setup [area] [--no-ai] [--project NAME]
-  omp-conductor start [--port N] [--project NAME]
-  omp-conductor --version
-  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 restore-db [SNAPSHOT]
-  omp-conductor ledger [--issue N] [--limit N] [--project NAME]
-  omp-conductor hold [--keep-ticks] [--project NAME | --all]
-  omp-conductor arm [--project NAME | --all]
-  omp-conductor disarm [--project NAME | --all]
-  omp-conductor tail <issue> [--project NAME]
-  omp-conductor extend <issue> --turns N [--project NAME]
-  omp-conductor worker pause <issue> [--project NAME]
-  omp-conductor worker resume <issue> [--project NAME]
-  omp-conductor worker stop <issue> --reason TEXT [--project NAME]
-  omp-conductor unblock <issue> [--force] [--no-requeue] [--project NAME]
-  omp-conductor unfreeze <repo> [--reason TEXT] [--project NAME]
-  omp-conductor verb <conductor_*> [--project NAME] [--arg k=v ...]
-  omp-conductor daemon [--once] [--port N] [--project NAME]
-  omp-conductor resume [--project NAME | --all]
-  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|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 watch add --note TEXT [--blocks TEXT] [--resolves-when COND] [--project NAME]
-  omp-conductor watch 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
-           staged host files behind one confirm. Bare is a full run — or, when
-           the project already exists, a chooser of which area to amend. Naming
-           an area positionally skips that chooser and amends only that area:
-           ${AMEND_AREA_IDS.join(", ")}.
-  upgrade  update the Bun-global CLI, omp plugin, Herdr recovery plugin, and
-           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: 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
-           other herdr session. resume clears the pin.
-  restart  drain the fleet by default: pause new claims, wait until live workers
-           reach 0/N (bounded by --timeout SECONDS, default 1800), restart keeping
-           the running daemon's port and project unless a flag overrides them,
-           then restore the prior dispatch state. --now skips the drain and
-           restarts immediately, orphaning any live runs (old behavior). A drain
-           that hits --timeout restarts nothing and leaves dispatch paused. On boot
-           the new process salvages dirty live worktrees before orphaning those
-           rows — see README "Deploying a new package onto a busy fleet". Goes
-           through systemctl when the unit owns the live pid; a failed
-           installed unit is reset and restarted through systemd, never
-           replaced by an unmanaged daemon.
-  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.
-  restore-db
-           put conductor.db back to a restorable snapshot, replacing the live
-           file and dropping stale -wal/-shm sidecars. Refuses while a daemon
-           is live — restoring under a running daemon is a corruption path.
-           The default source is the newest snapshot in the configured db
-           backup directory; an explicit snapshot path overrides it.
-  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
-           except through those verbs, so this is the record of what they tried
-           as well as what they did. --issue narrows it to one issue's run.
-  hold     soft stop: pause claiming AND disarm ticks. Daemon and pane stay up.
-           This is "stop the conductor overnight" without killing processes.
-           Use --all to target every configured project.
-  arm      proof-gated: send a Telegram challenge and write the arm marker only
-           after your reply appears as a user turn in the orchestrator transcript.
-           Never auto-armed by resume/hold. Use --all for every project.
-  disarm   remove the arm marker so ticks skip. Processes untouched. Use --all
-           to target every configured project.
-  tail     follow the newest run for <issue>: the worker's assistant text and
-           the tools it calls, printed as they land. Workers are sessions inside
-           the daemon rather than terminals, so this is the only way to watch
-           one live. Runs until Ctrl-C, or until the run has finished and its
-           transcript has stopped growing.
-  extend   raise a live run's turn ceiling, or set a bounded one-shot ceiling
-           after a failed, killed, orphaned or blocked run. Refuses values outside
-           configured bounds.
-  worker   cooperatively pause one live worker at harness idle, then resume the
-           same session with a continuation prompt. Its wall clock is frozen
-           while parked. Distinct from fleet-level pause/resume.
-  unblock  clear <issue>'s blocked and failed labels so the next tick can claim
-           it again — the supported way back for an escalation you answered,
-           and why the brief's "never hand-edit a state label" rule can stay
-           absolute. Run history is kept; answered blocks consume the separate
-           operational-continuation budget, not failed implementation attempts.
-           Refuses when the newest attempt's work could not be committed and
-           its worktree is the only copy: re-claiming removes that tree. Use
-           --force once you have recovered it or accepted the loss. Restores
-           the project queue label by default so the issue is actually
-           dispatchable; --no-requeue clears state labels only (the "about to
-           close it" case).
-  verb     run one conductor_* verb as the orchestrator, from the CLI: the same
-           checks and the same ledger rows a session's call would get. This is
-           how an external orchestrator merges, labels, releases or reads PR
-           state without a raw gh call that skips every gate. Arguments are
-           strings, one per --arg (e.g. --arg prUrl=https://x --arg headSha=y).
-           A refusal exits 3. See conductor_pr_merge/conductor_label/
-           conductor_release/conductor_pr_update_branch in the brief.
-  event    persist one ordinary material outcome without sending it. Category
-           is a short lowercase slug; summary and evidence name what happened
-           and where it can be verified. --occurred-at defaults to now.
-  report   hand a rendered report to the daemon's durable outbox. The report is
-           persisted before anything is sent, delivered by the daemon with
-           bounded retries, and shown by status until it lands. Delivery is
-           at-least-once: a crash mid-send is retried and the retry says it may
-           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. 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. 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
-           carries what is still owed. \`--resolves-when\` attaches a condition the
-           daemon checks for you (pr-merged:<url>, issue-closed:<n>,
-           npm-version:<pkg>@<version>); a met one is flagged in that digest.
-           Unanswered rows expire after seven days rather than accumulating.
-             decision open --question TEXT [--blocks TEXT] [--resolves-when COND]
-             decision resolve <id> --answer TEXT
-             decision withdraw <id> [--reason TEXT]
-             decision list
-  watch    set a condition or carry note for the orchestrator itself, with no
-           human in the loop — the same no-sleep surface \`decision open
-           --resolves-when\` used to serve, given its own verb so it never renders
-           as a question put to the operator. \`--resolves-when\` attaches a
-           condition the daemon checks for you; a met watch wakes the next tick
-           with its note, exactly as a met question does, but it is listed under
-           its own heading and never under "Open operator decisions", and it has
-           no seven-day expiry. \`watch list\` shows open watches.
-             watch add --note TEXT [--blocks TEXT] [--resolves-when COND]
-             watch 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
-           loop; recording one never edits policy by itself.
-  daemon   run the dispatch loop in the foreground; --once runs a single tick
-           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 [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
-           you, install and enable the reindex timer as root, then seed one
-           indexing run and verify it. --no-seed enables without seeding;
-           --print changes nothing. Exits 1 when no repo has graphProject.
-  brief-upgrade
-           inspect the brief overlay (package floor + POLICY.md). Reports by
-           default. --migrate lifts a bannered ORCHESTRATOR.md owned half into
-           POLICY.md and recomposes. --retrofit proposes inserting the YOURS TO
-           EDIT banner before the first Releases/Project context/Reporting/
-           Amendments heading (#20); --retrofit --apply writes it. --apply only
-           ever confirms one of those two — the legacy single-file merge was
-           removed in 0.4.3. --file checks a brief that is not where the wizard
-           would have put it.
-  help     print this text (also --help, -h).
-  --version
-           print the installed omp-conductor package version (also -V, version).
-
-Pause is a flag file under the state directory, so it applies to the selected
-project (or every configured project with --all) and survives a daemon restart.
-Hold also removes the arm marker the heartbeat reads, so both brains go quiet
-without killing processes. A running daemon is tracked by a pidfile under
-$OMP_CONDUCTOR_RUNTIME_DIR (default
-~/.omp/run/daemons/omp-conductor), written whether it was started in the
-background or in the foreground, and probed for liveness on every read — a
-stale one never blocks a start.
-
-Stop the conductor:
-  hold              no claims, no tick sends (inspectable)
-  stop              hold + stop dispatch daemon
-  stop --pane       stop + pin conductor-pane recovery off
-  resume && arm     clear pause and any pane pin, then prove inbound Telegram`;
+const USAGE = renderUsage(COMMAND_MANIFEST);
 
 /** Applies both `--port 9000` and `--port=9000`; returns undefined when absent. */
 function flag(argv: string[], name: string): string | undefined {
@@ -413,46 +143,10 @@ function issueArg(verb: string, raw: string | undefined): number {
   return issue;
 }
 
-
-const argv = process.argv.slice(2);
-const cmd = argv[0];
-/**
- * Parsed once, because nearly every verb takes it and a per-case
- * `projectFlag` is a line each of them can forget. Named `projectFlag`
- * rather than `project` because many cases bind their own resolved
- * `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[] {
-  // 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"));
-}
-
 /**
  * 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.
+ * the same code an unknown verb uses.
  */
 const REMOVED: Record<string, string> = {
   halt: '"halt" is now "stop" — see help',
@@ -461,79 +155,114 @@ const REMOVED: Record<string, string> = {
   "graph-setup": '"graph-setup" is now "setup graph" — see help',
 };
 
-/**
- * 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),
-  unfreeze: () => unfreezeCommand(ctx),
-  verb: () => verbCommand(ctx),
-  event: () => eventCommand(ctx),
-  report: () => reportCommand(ctx),
-  message: () => messageCommand(ctx),
-  decision: () => decisionCommand(ctx),
-  watch: () => watchCommand(ctx),
-  intake: () => intakeCommand(ctx),
-  friction: () => frictionCommand(ctx),
-  "restore-db": () => restoreDbCommand(ctx),
-  resume: () => resumeCommand(ctx),
-  "brief-upgrade": () => briefUpgradeCommand(ctx),
-  help: () => helpCommand(USAGE),
-  "--help": () => helpCommand(USAGE),
-  "-h": () => helpCommand(USAGE),
-};
+/** The registration table used by dispatch and the manifest drift test. */
+export function commandHandlers(ctx: CommandContext): Record<string, CommandHandler> {
+  return {
+    "--version": () => versionCommand(),
+    "-V": () => versionCommand(),
+    version: () => versionCommand(),
+    complete: async () =>
+      (await import("./commands/complete.ts")).completeCommand(ctx.argv.slice(1)),
+    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),
+    unfreeze: () => unfreezeCommand(ctx),
+    verb: () => verbCommand(ctx),
+    event: () => eventCommand(ctx),
+    report: () => reportCommand(ctx),
+    message: () => messageCommand(ctx),
+    decision: () => decisionCommand(ctx),
+    watch: () => watchCommand(ctx),
+    intake: () => intakeCommand(ctx),
+    friction: () => frictionCommand(ctx),
+    "restore-db": () => restoreDbCommand(ctx),
+    resume: () => resumeCommand(ctx),
+    "brief-upgrade": () => briefUpgradeCommand(ctx),
+    help: () => helpCommand(USAGE),
+    "--help": () => helpCommand(USAGE),
+    "-h": () => helpCommand(USAGE),
+  };
+}
 
-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);
+export async function runCli(argv: string[] = process.argv.slice(2)): Promise<void> {
+  const cmd = argv[0];
+  // Completion runs on every TAB press. Answer before config, daemon, or
+  // project-context construction so a shell request stays cheap and fail-empty.
+  if (cmd === "complete") {
+    try {
+      const requestDelimiter = argv.indexOf("--", 1);
+      const ownArgs = argv.slice(1, requestDelimiter === -1 ? undefined : requestDelimiter);
+      const ownProjectFlag = flag(ownArgs, "project");
+      if (COMMAND_SCOPES[cmd] === "none" && ownProjectFlag !== undefined) {
+        process.stderr.write(
+          `omp-conductor: ${cmd} does not take a project — it needs no --project\n`,
+        );
+        process.exit(2);
+      }
+      (await import("./commands/complete.ts")).completeCommand(argv.slice(1));
+      return;
+    } catch (err) {
+      process.stderr.write(`omp-conductor: ${err instanceof Error ? err.message : String(err)}\n`);
+      process.exit(1);
+    }
   }
-  // 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);
+  const projectFlag = flag(argv, "project");
+
+  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: () =>
+      resolveProjectsByScope(loadConfig(), "fleet", projectFlag, argv.includes("--all")),
+  };
+  const commands = commandHandlers(ctx);
+
+  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.
+    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) {
+    process.stderr.write(`omp-conductor: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
   }
-  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.
-  process.stderr.write(`omp-conductor: ${err instanceof Error ? err.message : String(err)}\n`);
-  process.exit(1);
 }
+
+if (import.meta.main) await runCli();