omp-conductor 0.15.9 → 0.15.11

package/src/commands/arm.ts

@@ -0,0 +1,21 @@
+/**
+ * `arm` — proof-gated: send a Telegram challenge and write the arm marker only after the reply appears in the orchestrator transcript.
+ *
+ * Moved out of cli.ts's switch by the per-verb module split (#462);
+ * only the case wrapper, the injected `ctx` lookups and the imports
+ * changed from the original bodies.
+ */
+
+import type { CommandContext } from "./context.ts";
+import { armTicks } from "../fleet.ts";
+
+export async function armCommand(ctx: CommandContext): Promise<void> {
+for (const project of ctx.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`,
+  );
+}
+}

package/src/commands/board.ts

@@ -0,0 +1,23 @@
+/**
+ * `board` — the live keyboard-driven fleet board, or a one-shot --json snapshot of the same lanes.
+ *
+ * Moved out of cli.ts's switch by the per-verb module split (#462);
+ * only the case wrapper, the injected `ctx` lookups and the imports
+ * changed from the original bodies.
+ */
+
+import type { CommandContext } from "./context.ts";
+import { boardJson, boardSnapshotOnce, runBoard } from "../board.ts";
+
+export async function boardCommand(ctx: CommandContext): Promise<void> {
+const project = ctx.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 (ctx.argv.includes("--json") || !process.stdout.isTTY || !process.stdin.isTTY) {
+  process.stdout.write(`${boardJson(await boardSnapshotOnce(project))}\n`);
+  return;
+}
+await runBoard(project);
+}

package/src/commands/brief-upgrade.ts

@@ -0,0 +1,186 @@
+/**
+ * `briefUpgrade` — inspect the brief overlay (package floor + POLICY.md) and run the `--migrate` / `--retrofit` paths.
+ *
+ * Moved out of cli.ts's switch by the per-verb module split (#462);
+ * only the case wrapper, the injected `ctx` lookups and the imports
+ * changed from the original bodies.
+ */
+
+import type { CommandContext } from "./context.ts";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import {
+  applyRetrofit,
+  formatBriefReport,
+  formatMigrateResult,
+  formatRetrofitProposal,
+  formatRetrofitRefusal,
+  inspectBriefLayout,
+  migrateToPolicy,
+  missingSections,
+  proposeRetrofit,
+  repairPolicyBannerCrumbs,
+  sharedPolicyPath,
+} from "../brief-upgrade.ts";
+import { findProject, loadConfig } from "../config.ts";
+import {
+  briefPathForProject,
+  policyPathForProject,
+  renderBriefForProject,
+  renderFloorForProject,
+  shippedBriefTemplate,
+} from "../setup.ts";
+import type { ProjectConfig } from "../types.ts";
+
+export async function briefUpgradeCommand(ctx: CommandContext): Promise<void> {
+const override = ctx.flag("file");
+let project: ProjectConfig | undefined;
+let path: string;
+if (override === undefined) {
+  project = findProject(loadConfig(), ctx.projectFlag);
+  path = briefPathForProject(project);
+} else {
+  path = override;
+  try {
+    project = findProject(loadConfig(), ctx.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);
+  // Host-wide shared policy, reported as a layer when present (#363).
+  const sharedBrief = existsSync(sharedPolicyPath()) ? sharedPolicyPath() : undefined;
+
+if (ctx.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 (ctx.argv.includes("--apply")) {
+    const backup = applyRetrofit(path, result.proposal);
+    process.stdout.write(`\napplied retrofit — previous brief kept at ${backup}\n`);
+  }
+  return;
+}
+
+if (ctx.argv.includes("--migrate")) {
+  if (layout.kind === "overlay") {
+    if (!ctx.argv.includes("--apply")) {
+      process.stdout.write(
+        `${formatBriefReport(path, layout, [], sharedBrief)}\n\n` +
+          "POLICY.md already present. --migrate --apply will strip any leading\n" +
+          "banner-comment crumbs from POLICY.md and recompose ORCHESTRATOR.md.\n",
+      );
+      return;
+    }
+    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, [], sharedBrief)}\n\nrecomposed ORCHESTRATOR.md — POLICY.md needed no crumb strip.\n`,
+      );
+    } else {
+      process.stdout.write(`${formatMigrateResult(repaired)}\n`);
+    }
+    return;
+  }
+  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, sharedBrief)}\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 (!ctx.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",
+    );
+    return;
+  }
+  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`);
+  return;
+}
+
+// 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 (ctx.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, sharedBrief)}\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",
+  );
+}
+}

package/src/commands/context.ts

@@ -0,0 +1,49 @@
+import type { ProjectConfig } from "../types.ts";
+
+/**
+ * What a command handler may read about the invocation it was dispatched for.
+ *
+ * Argument parsing stays in cli.ts — the flag helpers, the shared usage text
+ * and the registration table — and each handler receives the parsed essentials
+ * plus the lookups it needs through this object. A command module therefore
+ * never imports the entry point back: no import cycle, and no module-level
+ * mutable state for one verb to change under another.
+ */
+export interface CommandContext {
+  /** The full argv including the verb at index 0, read once per process. */
+  argv: string[];
+  /**
+   * The `--project` value, parsed once because nearly every verb takes it.
+   * Named `projectFlag` rather than `project` because many handlers bind their
+   * own resolved `ProjectConfig` under that name.
+   */
+  projectFlag: string | undefined;
+  /** Applies both `--flag VALUE` and `--flag=VALUE`; undefined when absent. */
+  flag(name: string): string | undefined;
+  /**
+   * `--port` for the daemon-bound verbs. Exits 2 rather than defaulting,
+   * because silently ignoring a typo'd port would leave the operator probing
+   * an endpoint the daemon is not on.
+   */
+  portFlag(): number | undefined;
+  /** Required positive integer for `extend`; no partial parses such as `180x`. */
+  turnsFlag(): number;
+  /**
+   * `report`'s comma-separated `--events` / `--notices` ledger row ids, in the
+   * three shapes the runtime actually mints. Exits 2 on anything else.
+   */
+  digestIdsFlag(name: "events" | "notices"): string[];
+  /**
+   * The `<issue>` positional, for the verbs that take one. Exits 2 rather
+   * than proceeding with run #NaN; `verb` is named in the message.
+   */
+  issueArg(verb: string, raw: string | undefined): number;
+  /**
+   * The projects a fleet-level verb targets: `--all`, `--project NAME`, or the
+   * sole configured project (throwing when the choice would be ambiguous).
+   */
+  targetProjects(): ProjectConfig[];
+}
+
+/** One operator subcommand: what the registration table maps a verb to. */
+export type CommandHandler = (ctx: CommandContext) => Promise<void> | void;

package/src/commands/daemon.ts

@@ -0,0 +1,71 @@
+/**
+ * `daemon` — run the dispatch loop in the foreground; --once runs a single tick and exits. This is what `start` launches.
+ *
+ * Moved out of cli.ts's switch by the per-verb module split (#462);
+ * only the case wrapper, the injected `ctx` lookups and the imports
+ * changed from the original bodies.
+ */
+
+import type { CommandContext } from "./context.ts";
+import { runDaemon } from "../daemon.ts";
+import { clearRecord, DEFAULT_PORT, livingDaemon, writeRecord } from "../lifecycle.ts";
+
+/**
+ * `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>";
+
+export async function daemonCommand(ctx: CommandContext): Promise<void> {
+// 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 = ctx.argv.includes("--once");
+const port = ctx.portFlag();
+const project = ctx.projectFlag;
+
+// A drill is still a dispatcher: it settles rows, projects labels,
+// admits, and launches workers, so it holds the same exclusive daemon/
+// state ownership as the long-running dispatcher for the whole tick
+// (#431). `runDaemon` acquires that ownership up front (the one choke
+// point every once tick passes through) and refuses — having done no
+// mutation — while another live daemon owns the project; the thrown
+// refusal surfaces as `omp-conductor: another daemon is alive (pid N)…`.
+if (once) {
+  await runDaemon({ once, port, project });
+  return;
+}
+
+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();
+}
+}

package/src/commands/dashboard.ts

@@ -0,0 +1,74 @@
+/**
+ * `dashboard` — serve the fleet dashboard in a browser (epic #292, slice 1/5):
+ * the UI shell plus one bearer-authenticated read endpoint, `/api/projects`,
+ * from a dedicated `Bun.serve` process — never a route on the daemon port,
+ * whose unauthenticated loopback surface stays exactly as
+ * `verbs/server.test.ts` pins it.
+ *
+ * Argument parsing follows `stats.ts`'s template: every token after the verb
+ * is accounted for, and an unexpected one exits 2 rather than being silently
+ * ignored.
+ */
+
+import type { CommandContext } from "./context.ts";
+import { DASHBOARD_HOST, startDashboard } from "../dashboard/server.ts";
+
+const DASHBOARD_USAGE = `omp-conductor dashboard — serve the fleet dashboard in your browser.
+
+usage:
+  omp-conductor dashboard [--port N] [--host ADDR]
+
+Serves the dashboard UI and GET /api/projects from a dedicated process —
+separate from the daemon, which it only ever reads. /api/projects answers with
+every configured project annotated with its daemon state (the same
+livingDaemon + /healthz classification status and board use), the daemon's
+port, and the raw /healthz body when it answers. Every /api request must carry
+Authorization: Bearer <token>; anything else is a bare 401. The token is
+minted mode 0600 at <stateDir()>/dashboard-token on first start (the
+$OMP_CONDUCTOR_HOME state directory, next to config.json) and reused
+afterwards; the page asks for it once and keeps it in localStorage. Static
+assets are served without auth.
+
+Binds 127.0.0.1:8788 by default. A non-loopback --host (say, a tailnet IP)
+still starts, but prints a one-line warning naming the token file: the token
+is then the only thing between anyone who can reach that address and the
+project list. Ctrl-C stops the server.
+
+flags:
+  --port PORT listen port (default 8788)
+  --host ADDR bind address (default 127.0.0.1)`;
+
+export async function dashboardCommand(ctx: CommandContext): Promise<void> {
+  // Help first: parsing stops before any config read, token mint or socket.
+  if (ctx.argv[1] === "--help" || ctx.argv[1] === "-h") {
+    process.stdout.write(`${DASHBOARD_USAGE}\n`);
+    return;
+  }
+  // Every remaining token after the verb is accounted for: the two value
+  // flags cli.ts already parsed (--port via portFlag, --host via flag).
+  for (let i = 1; i < ctx.argv.length; i++) {
+    const token = ctx.argv[i];
+    if (token === undefined) continue;
+    if (
+      token !== "--port" &&
+      token !== "--host" &&
+      !token.startsWith("--port=") &&
+      !token.startsWith("--host=")
+    ) {
+      process.stderr.write(`omp-conductor: dashboard: unexpected argument "${token}"\n`);
+      process.exit(2);
+    }
+    if (token === "--port" || token === "--host") i += 1;
+  }
+  const host = ctx.flag("host");
+  if (host === undefined && ctx.argv.includes("--host")) {
+    process.stderr.write(`omp-conductor: dashboard --host needs an address\n`);
+    process.exit(2);
+  }
+  if (host !== undefined && host.length === 0) {
+    process.stderr.write(`omp-conductor: dashboard --host needs an address\n`);
+    process.exit(2);
+  }
+
+  await startDashboard({ port: ctx.portFlag(), host: host ?? DASHBOARD_HOST });
+}

package/src/commands/decision.ts

@@ -0,0 +1,103 @@
+/**
+ * `decision` — record, list and close the questions put to the operator.
+ *
+ * Moved out of cli.ts's switch by the per-verb module split (#462);
+ * only the case wrapper, the injected `ctx` lookups and the imports
+ * changed from the original bodies.
+ */
+
+import type { CommandContext } from "./context.ts";
+import { findProject, loadConfig } from "../config.ts";
+import { CONDITION_FORMS, parseCondition } from "../decisions.ts";
+import { dbPath, openStore } from "../store.ts";
+
+export async function decisionCommand(ctx: CommandContext): Promise<void> {
+const sub = ctx.argv[1];
+const project = findProject(loadConfig(), ctx.projectFlag);
+const store = openStore(dbPath());
+try {
+  if (sub === "open") {
+    const question = ctx.flag("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 = ctx.flag("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 = ctx.flag("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`,
+    );
+    return;
+  }
+
+  if (sub === "resolve" || sub === "withdraw") {
+    const id = ctx.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 ? ctx.flag("answer")?.trim() : ctx.flag("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`);
+    return;
+  }
+
+  if (sub === "list" || sub === undefined) {
+    const open = store.openDecisions(project.name);
+    if (open.length === 0) {
+      process.stdout.write("no open decisions\n");
+      return;
+    }
+    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`,
+      );
+    }
+    return;
+  }
+
+  process.stderr.write(
+    `omp-conductor: unknown decision subcommand "${sub}" — expected open, resolve, withdraw or list\n`,
+  );
+  process.exit(2);
+} finally {
+  store.close();
+}
+}

package/src/commands/disarm.ts

@@ -0,0 +1,21 @@
+/**
+ * `disarm` — remove the arm marker so ticks skip. Processes untouched.
+ *
+ * Moved out of cli.ts's switch by the per-verb module split (#462);
+ * only the case wrapper, the injected `ctx` lookups and the imports
+ * changed from the original bodies.
+ */
+
+import type { CommandContext } from "./context.ts";
+import { disarmTicks } from "../fleet.ts";
+
+export async function disarmCommand(ctx: CommandContext): Promise<void> {
+for (const project of ctx.targetProjects()) {
+  const r = disarmTicks(project.name);
+  process.stdout.write(
+    `disarmed — ticks will be skipped` +
+      `${r.wasArmed ? "" : " (was already disarmed)"}\n` +
+      `marker ${r.path}\n`,
+  );
+}
+}

package/src/commands/doctor.ts

@@ -0,0 +1,98 @@
+/**
+ * `doctor` — read-only deployment health, one finding per past failure mode
+ * (#287, legibility 1/5).
+ *
+ * The probe logic lives in ../doctor.ts with every I/O seam injectable; this
+ * module only parses the doctor's own flags, renders the findings the runner
+ * produced (the same findings `--json` emits), and derives the exit code:
+ * nonzero iff the report contains a failing finding.
+ */
+
+import type { CommandContext } from "./context.ts";
+import { runDoctor, type DoctorReport, type FindingStatus } from "../doctor.ts";
+
+const DOCTOR_USAGE = `omp-conductor doctor — check the deployment faults that have already cost
+debugging sessions, mechanically and read-only.
+
+usage:
+  omp-conductor doctor [--project NAME] [--json] [--probe-telegram]
+
+Checks, each one the mechanical version of a past production incident:
+  gh auth         token alive and scopes cover every configured repo (a token
+                  that expired under a live daemon failed every tracker call
+                  silently)
+  labels          every configured routing/state label exists with exact case
+                  — label matching is case-sensitive and a mismatch fails
+                  silently (README Limitations)
+  systemd unit    the installed units vs the staged render (User=, environment,
+                  working directory, exec, restart/success status) and the
+                  ownership/modes of the unit and runtime dirs (the worker
+                  die-at-turn-0 class)
+  config          config.json validates, and its pre-write backup exists and
+                  is fresh
+  store           PRAGMA integrity_check
+  spend telemetry every completed run recording $0.00 means the USD cap cannot
+                  fire — $0.00 is not proof of no spend
+  timezone        reporting timezones are known IANA zones
+  telegram        bot health, and one self-identified probe message
+
+flags:
+  --json                 print the stable report shape {project, checkedAt,
+                         status, findings:[{id,status,summary,fix?}]} — the CI
+                         contract
+  --probe-telegram       the ONE opt-in side effect: send one self-identified
+                         test message through the report transport
+  --project NAME         the project to check (required only when the config
+                         has more than one)
+
+Exit code is 0 only when nothing failed; warnings do not fail the run.`;
+
+const LABEL_BY_STATUS: Record<FindingStatus, string> = { pass: "PASS", warn: "WARN", fail: "FAIL" };
+
+/** Renders the same findings `--json` emits, so the two cannot disagree. */
+export function renderDoctorReport(report: DoctorReport): string {
+  const width = Math.max(...report.findings.map((f) => f.id.length).concat(0), 8);
+  const lines = [
+    `omp-conductor doctor — ${report.project}`,
+    `status: ${report.status.toUpperCase()} (${report.findings.filter((f) => f.status === "fail").length} failed · ${report.findings.filter((f) => f.status === "warn").length} warnings) · checked ${report.checkedAt}`,
+    "",
+  ];
+  for (const f of report.findings) {
+    const pad = " ".repeat(Math.max(0, width - f.id.length));
+    lines.push(`  ${LABEL_BY_STATUS[f.status].padEnd(5)}  ${f.id}${pad}  ${f.summary}`);
+    if (f.fix !== undefined) lines.push(`        ${" ".repeat(width)}  fix: ${f.fix}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+export async function doctorCommand(ctx: CommandContext): Promise<void> {
+  // Help first: parsing stops before any probe, config read, or side effect.
+  if (ctx.argv[1] === "--help" || ctx.argv[1] === "-h") {
+    process.stdout.write(`${DOCTOR_USAGE}\n`);
+    return;
+  }
+  // Every remaining token after the verb is accounted for: the two flag
+  // presence markers and the `--project NAME` pair cli.ts already parsed.
+  const DOCTOR_FLAGS: Record<string, true> = {
+    "--json": true,
+    "--probe-telegram": true,
+    "--project": true,
+  };
+  for (let i = 1; i < ctx.argv.length; i++) {
+    const token = ctx.argv[i];
+    if (token === undefined) continue;
+    if (DOCTOR_FLAGS[token] !== true) {
+      process.stderr.write(`omp-conductor: doctor: unexpected argument "${token}"\n`);
+      process.exit(2);
+    }
+    if (token === "--project") i += 1;
+  }
+
+  const report = await runDoctor(ctx.projectFlag, {
+    probeTelegram: ctx.argv.includes("--probe-telegram"),
+  });
+  if (ctx.argv.includes("--json")) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+  else process.stdout.write(renderDoctorReport(report));
+  // The one contract CI reads: nonzero iff something failed. Warnings pass.
+  if (report.status === "fail") process.exitCode = 1;
+}