omp-conductor 0.15.10 → 0.15.12

package/src/commands/report.ts

@@ -0,0 +1,206 @@
+/**
+ * `report` — hand a rendered report to the daemon's durable outbox; the daemon owns delivery with bounded retries.
+ *
+ * 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 { randomUUID } from "node:crypto";
+import { interruptDisposition } from "../availability.ts";
+import { findProject, loadConfig } from "../config.ts";
+import { digestDue } from "../digest-schedule.ts";
+import { dbPath, openStore } from "../store.ts";
+import { digestDedupeKey } from "../reports.ts";
+import {
+  DEFAULT_REPORT_POLICY,
+  INTERRUPT_CATEGORIES,
+  REPORT_KINDS,
+  SESSION_ROLE_ENV,
+  type InterruptCategory,
+  type ReportKind,
+} from "../types.ts";
+
+export async function reportCommand(ctx: CommandContext): Promise<void> {
+const rawText = ctx.flag("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 = ctx.flag("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" && (ctx.argv.includes("--events") || ctx.argv.includes("--notices"))) {
+  process.stderr.write(
+    "omp-conductor: report --events and --notices are valid only with --kind digest\n",
+  );
+  process.exit(2);
+}
+// Escalation tiers are not a worker session's to claim, like every other
+// privileged surface (#508). The daemon stamps the session role on spawned
+// sessions; a value outside the closed vocabulary is refused, never assumed.
+// A bare CLI run (operator's shell) has the env absent and stays the
+// orchestrator surface, so this refuses precisely the worker who would
+// otherwise page the operator from inside a worktree.
+const sessionRole = process.env[SESSION_ROLE_ENV];
+if (
+  sessionRole === "worker" &&
+  INTERRUPT_CATEGORIES.some((category) => category !== "material" && category === kind)
+) {
+  process.stderr.write(
+    `omp-conductor: report: escalation tier is not a worker session's to claim; ` +
+      `only the operator or orchestrator may hand off a ${kind} report\n`,
+  );
+  process.exit(3);
+}
+const project = findProject(loadConfig(), ctx.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);
+      }
+    }
+  }
+  // Every non-digest kind is an interrupt category, and the caller's kind
+  // IS the category: admission runs the shared interruptDisposition with
+  // that category, so a `fleet-stopped` report under scope=escalations is
+  // admitted while `material` stays digest-only under that same policy.
+  if (kind !== "digest") {
+    const category: InterruptCategory = kind;
+    const disposition = interruptDisposition(policy, category, at);
+    if (disposition === "digest") {
+      // Name the flags that would have worked rather than only the digest:
+      // the categories this policy actually pages are how a handoff like a
+      // tier-2 install notice gets through, and there is no other spelling to
+      // guess at (#508).
+      const interruptable = INTERRUPT_CATEGORIES.filter(
+        (candidate) => interruptDisposition(policy, candidate, at) === "interrupt",
+      );
+      const flags =
+        interruptable.length > 0
+          ? `hand it off as a category this policy pages (--kind ${interruptable.join("|")}) or fold it ` +
+            "into the next digest (--kind digest)"
+          : "fold it into the next digest (--kind digest)";
+      process.stderr.write(
+        `omp-conductor: report: ${category} updates are digest-only under this reporting policy; ${flags}\n`,
+      );
+      process.exit(2);
+    }
+    // One escalation handoff per event while the first has not landed.
+    // Material reports describe one ordinary outcome each time, so they
+    // keep their historical no-dedup behaviour. The escalation categories
+    // refuse an identical retry only while the earlier handoff is still
+    // owed — an outbox report awaiting delivery or a held notice not yet
+    // digested (#453). The notifications ledger cannot decide this: its
+    // rows are permanent, so a same-text recurrence would be refused
+    // forever once the first occurrence was marked; a delivered handoff
+    // means the identical text is a new event, not a double-send.
+    if (category !== "material") {
+      if (store.hasOpenEscalationHandoff(project.name, category, body)) {
+        process.stderr.write(
+          `omp-conductor: report: an identical ${category} handoff for ${project.name} is still queued undelivered ` +
+            "— this retry was refused so the operator is not paged twice; nothing new was queued, " +
+            "check `omp-conductor status` for what is still awaiting delivery\n",
+        );
+        process.exit(2);
+      }
+      if (disposition === "availability") {
+        const noticeId = randomUUID();
+        store.addHeldNotice({
+          id: noticeId,
+          project: project.name,
+          category,
+          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} (${category}; quiet hours)\n` +
+            "the daemon will include it in the next digest or working-hours catch-up\n",
+        );
+        return;
+      }
+      const { report } = store.enqueueReport({ project: project.name, kind, body, at });
+      process.stdout.write(
+        `report ${report.id} queued for ${project.name} (${kind})\n` +
+          "the daemon owns delivery from here; omp-conductor status shows it until it lands\n",
+      );
+      return;
+    }
+    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",
+      );
+      return;
+    }
+  }
+  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,
+          ctx.digestIdsFlag("events"),
+          ctx.digestIdsFlag("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();
+}
+}

package/src/commands/restart.ts

@@ -0,0 +1,76 @@
+/**
+ * `restart` — drain the fleet by default, then restart keeping the running daemon's port and project unless a flag overrides them.
+ *
+ * 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 { setPaused } from "../daemon.ts";
+import { restartDaemon, type RestartResult } from "../lifecycle.ts";
+import { DEFAULT_DEPS, drainAndRestart, type UpgradeDeps } from "../upgrade.ts";
+
+export async function restartCommand(ctx: CommandContext): Promise<void> {
+if (ctx.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: ctx.portFlag(),
+    project: ctx.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`,
+  );
+  return;
+}
+
+// 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 = ctx.flag("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: ctx.portFlag(),
+      project: ctx.projectFlag,
+    });
+  },
+};
+try {
+  await drainAndRestart(deps, { project: ctx.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`,
+);
+}

package/src/commands/resume.ts

@@ -0,0 +1,58 @@
+/**
+ * `resume` — clear pause and any pane-recovery pin. Does NOT re-arm.
+ *
+ * A running daemon is woken over its loopback control port so the resumed
+ * project is dispatched on a pass that starts immediately instead of after
+ * the five-minute tick (#380); when no daemon is alive there is nothing to
+ * wake and the output says so rather than implying an immediate pass happened.
+ *
+ * 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 { armState, clearPaneHaltIfResolvable, releaseHold } from "../fleet.ts";
+import { livingDaemon } from "../lifecycle.ts";
+
+/** Wakes a running daemon, returning the human line that states what happened.
+ *  State-only clients (no live daemon) get an honest fallback rather than an
+ *  error: the hold is already cleared and the next pass or daemon start
+ *  claims without this poke. */
+async function wakeDaemon(projectName: string): Promise<string> {
+  const daemon = livingDaemon();
+  if (daemon === undefined) {
+    return "daemon not running — claiming starts when the daemon next starts or ticks";
+  }
+  let response: Response;
+  try {
+    response = await fetch(`http://127.0.0.1:${daemon.port}/wake`, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ project: projectName }),
+    });
+  } catch {
+    return "daemon wake failed — daemon unreachable; the next scheduled pass will claim";
+  }
+  if (!response.ok) {
+    return `daemon wake failed (HTTP ${response.status}); the next scheduled pass will claim`;
+  }
+  return "daemon dispatch loop woken — claiming starts on an immediate pass";
+}
+
+export async function resumeCommand(ctx: CommandContext): Promise<void> {
+for (const project of ctx.targetProjects()) {
+  releaseHold(project.name);
+  const pin = clearPaneHaltIfResolvable(project.name);
+  const arm = armState(project.name);
+  process.stdout.write(
+    `resumed — claiming allowed — ${await wakeDaemon(project.name)}\n` +
+      (pin.wasHalted
+        ? `pane recovery pin cleared — ${pin.path}\n`
+        : "no pane recovery pin to clear\n") +
+      (arm.armed
+        ? `ticks remain armed — marker ${arm.path}\n`
+        : "ticks stay disarmed — run `omp-conductor arm`\n"),
+  );
+}
+}

package/src/commands/setup.ts

@@ -0,0 +1,143 @@
+/**
+ * `setup` — interview, then write config.json, the labels, the briefs and the * staged host files behind one confirm.
+ *
+ * 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, resolveCaps } from "../config.ts";
+import { AMEND_AREA_IDS, type AmendAreaId } from "../setup.ts";
+import { runGraphInstall, runHostInstall, type InstallOutcome } from "../setup-install.ts";
+import { DEFAULT_PROBES, NO_PROBES, setup } from "../setup-wizard.ts";
+import { telegramStateDir } from "../fleet.ts";
+import { terminalUi } from "../wizard-ui.ts";
+import type { ConductorConfig, ProjectConfig } from "../types.ts";
+
+/**
+ * The setup verb's own usage, printed for `setup --help` / `setup -h` before
+ * any UI, config read, probe or area parsing. Areas come from `AMEND_AREA_IDS`
+ * rather than a second copy, so an added amend area appears both here and in
+ * the shared `USAGE` with no third spelling to keep in sync.
+ */
+const SETUP_USAGE = `omp-conductor setup — interview, then write config.json, the labels, the briefs
+and the staged host files behind one confirm.
+
+usage:
+  omp-conductor setup [area] [--no-ai] [--project NAME]
+  omp-conductor setup host [NAME] [--project NAME]
+  omp-conductor setup graph [--no-seed] [--print] [--project NAME]
+
+  Bare setup runs the full interview — or, when the project already exists,
+  asks which area to amend. Naming an area positionally skips that chooser and
+  amends only that area. \`setup host\` and \`setup graph\` are install
+  subcommands, not areas: the NAME (or --project NAME) says which project to
+  install for.
+
+amend areas:
+  ${AMEND_AREA_IDS.join(", ")}
+
+flags:
+  --project NAME   the project to configure or amend (or NAME positionally
+                   for \`setup host\`)
+  --no-ai          ask every question, propose nothing (no AI repo reads)`;
+
+/**
+ * Resolve the project an install subcommand (`setup host`, `setup graph`)
+ * installs for — the flag, or the positional form an operator naturally
+ * types on a multi-project host (`setup host conductor`). The pair may not
+ * disagree, and an unknown name fails loudly as "Unknown project …" rather
+ * than being silently ignored (#514).
+ */
+export function setupInstallProject(
+  cfg: ConductorConfig,
+  projectFlag: string | undefined,
+  positionalName: string | undefined,
+): ProjectConfig {
+  if (projectFlag !== undefined && positionalName !== undefined && projectFlag !== positionalName) {
+    throw new Error(
+      `setup names two different projects (--project ${projectFlag} and ${positionalName}) — pass one`,
+    );
+  }
+  return findProject(cfg, projectFlag ?? positionalName);
+}
+
+export async function setupCommand(ctx: CommandContext): Promise<void> {
+// Help first, and only in the first trailing position: a help request
+// must never open a UI, read config, probe GitHub or pause dispatch.
+// `setup bogus --help` still rejects `bogus` as an unknown area, and
+// `setup caps --help` still names `caps` as the governing argument.
+if (ctx.argv[1] === "--help" || ctx.argv[1] === "-h") {
+  process.stdout.write(`${SETUP_USAGE}\n`);
+  return;
+}
+const sub = ctx.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();
+    // `setup host <name>`: the project an operator would naturally type.
+    // The positional only ever names a project; anything else that does not
+    // look like a flag is refused by findProject below rather than being
+    // quietly ignored.
+    const positionalName =
+      positional === "host" && ctx.argv[2] !== undefined && !ctx.argv[2].startsWith("--")
+        ? ctx.argv[2]
+        : undefined;
+    let outcome: InstallOutcome;
+    if (positional === "host") {
+      // No `--project` and no positional → a host-global install (#530): the
+      // units are host-global, so a multi-project host installs them with no
+      // name and skips the per-project tail (tick config, brief link) with a
+      // named note; a name resolves and wires the tail.
+      const project =
+        ctx.projectFlag === undefined && positionalName === undefined
+          ? undefined
+          : setupInstallProject(cfg, ctx.projectFlag, positionalName);
+      outcome = await runHostInstall(
+        project,
+        project === undefined ? cfg.defaults : resolveCaps(project, cfg.defaults),
+        telegramStateDir(),
+        ui,
+      );
+    } else {
+      // `setup graph` is inherently per-project repositories; there is no
+      // host-global graph to install, so a project must resolve.
+      outcome = await runGraphInstall(findProject(cfg, ctx.projectFlag), ui, {
+        noSeed: ctx.argv.includes("--no-seed"),
+        print: ctx.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);
+    return;
+  }
+  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, ctx.projectFlag, area, ctx.argv.includes("--no-ai") ? NO_PROBES : DEFAULT_PROBES);
+} finally {
+  ui.close();
+}
+}

package/src/commands/start.ts

@@ -0,0 +1,23 @@
+/**
+ * `start` — start the installed herdr-fleet.service when present, then run the dispatch loop in the background and wait for /healthz.
+ *
+ * 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 { startHerdrFleet } from "../fleet.ts";
+import { startDaemon } from "../lifecycle.ts";
+
+export async function startCommand(ctx: CommandContext): Promise<void> {
+const project = ctx.projectFlag;
+const herdr = startHerdrFleet(project);
+const rec = await startDaemon({ port: ctx.portFlag(), 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`,
+);
+}

package/src/commands/stats.ts

@@ -0,0 +1,131 @@
+/**
+ * `stats` — what the fleet accomplished and at what cost over a window (#282,
+ * legibility 5/5).
+ *
+ * The aggregation lives in ../stats.ts, pure over injected store rows; this
+ * module only parses the flags, reads the local store read-only, and renders
+ * the same report the --json shape carries. Nothing here touches GitHub or any
+ * other network surface: the window, runs, spend and gh-call counts all come
+ * from SQLite on this host.
+ */
+
+import type { CommandContext } from "./context.ts";
+import { findProject, loadConfig } from "../config.ts";
+import { dbPath, openStore, utcDay } from "../store.ts";
+import { computeStats, renderStatsHuman, type StatsWindow } from "../stats.ts";
+
+const DAY_MS = 24 * 60 * 60 * 1_000;
+const DATE_FORM = /^\d{4}-\d{2}-\d{2}$/;
+const DURATION_FORM = /^(\d{1,3})d$/;
+
+const STATS_USAGE = `omp-conductor stats — what the fleet accomplished and at what cost.
+
+usage:
+  omp-conductor stats [--since 7d|30d|YYYY-MM-DD] [--project NAME] [--json]
+
+Reads only the local store — zero GitHub calls. Over a bounded window it
+reports, per repo and in total: issues merged, issues settled (merged or
+terminally failed/blocked), merge rate, queue-to-merge lead time (median and
+p90, from the first claim of the issue's continuation chain to the tick's
+merge settlement), attempts per merged issue, metered spend per merged issue,
+the failure-class breakdown of everything that did not merge, and the tracked
+GitHub API calls consumed over the window's days.
+
+Continuation chains collapse into one journey: an issue that took six attempts
+is one merged outcome with six runs and one lead time. Runs whose spend reads
+$0.00 — harness telemetry absent (README Limitations) — are counted separately
+as unmetered and never averaged into cost as if they were free.
+
+flags:
+  --since 7d | 30d | YYYY-MM-DD   window start (default 7d)
+  --json                          print the stable report shape {project,
+                                  window, ghCalls, empty, total, repos} — keys
+                                  never move, so a consumer can rely on it
+  --project NAME                  the project to report (required only when
+                                  the config has more than one)
+
+When nothing settled in the window the report says so explicitly ("empty:
+true" in --json) rather than printing zeros that could read as measurements.`;
+
+/** `--since` to a window. The bare date form means from 00:00:00Z of that day;
+ *  the duration form (`7d`) is now minus whole days. Anything else exits 2,
+ *  because silently defaulting a typo'd window would measure the wrong week. */
+function sinceWindow(raw: string, now: number): Pick<StatsWindow, "sinceDay" | "sinceEpochMs"> {
+  const duration = DURATION_FORM.exec(raw);
+  if (duration !== null) {
+    const days = Number(duration[1]);
+    if (days >= 1) {
+      const sinceEpochMs = now - days * DAY_MS;
+      return { sinceEpochMs, sinceDay: utcDay(sinceEpochMs) };
+    }
+  }
+  if (DATE_FORM.test(raw)) {
+    const sinceEpochMs = Date.parse(`${raw}T00:00:00Z`);
+    if (Number.isFinite(sinceEpochMs)) {
+      return { sinceEpochMs, sinceDay: raw };
+    }
+  }
+  process.stderr.write(
+    `omp-conductor: stats --since needs 7d, 30d or YYYY-MM-DD, got "${raw}"\n`,
+  );
+  process.exit(2);
+}
+
+export async function statsCommand(ctx: CommandContext): Promise<void> {
+  // Help first: parsing stops before any config read or store open.
+  if (ctx.argv[1] === "--help" || ctx.argv[1] === "-h") {
+    process.stdout.write(`${STATS_USAGE}\n`);
+    return;
+  }
+  // Every remaining token after the verb is accounted for: the flag presence
+  // markers plus the two value flags cli.ts already parsed.
+  const STATS_FLAGS: Record<string, true> = {
+    "--json": true,
+    "--since": true,
+    "--project": true,
+  };
+  for (let i = 1; i < ctx.argv.length; i++) {
+    const token = ctx.argv[i];
+    if (token === undefined) continue;
+    // `--since 7d` and `--since=7d` are both legal — cli.ts's flag helper
+    // accepts the prefixed form, so the scan must too.
+    if (
+      STATS_FLAGS[token] !== true &&
+      !token.startsWith("--since=") &&
+      !token.startsWith("--project=")
+    ) {
+      process.stderr.write(`omp-conductor: stats: unexpected argument "${token}"\n`);
+      process.exit(2);
+    }
+    if (token === "--since" || token === "--project") i += 1;
+  }
+
+  const project = findProject(loadConfig(), ctx.projectFlag);
+  const now = Date.now();
+  const rawSince = ctx.flag("since");
+  if (rawSince === undefined && ctx.argv.includes("--since")) {
+    process.stderr.write(`omp-conductor: stats --since needs 7d, 30d or YYYY-MM-DD\n`);
+    process.exit(2);
+  }
+  const window: StatsWindow = {
+    ...sinceWindow(rawSince ?? "7d", now),
+    untilEpochMs: now,
+    untilDay: utcDay(now),
+  };
+  const store = openStore(dbPath());
+  try {
+    const report = computeStats({
+      project: project.name,
+      window,
+      ghCalls: store.ghCallsBetween(window.sinceDay, window.untilDay),
+      runs: store.statsRuns(project.name, window.sinceEpochMs),
+    });
+    process.stdout.write(
+      ctx.argv.includes("--json")
+        ? `${JSON.stringify(report, null, 2)}\n`
+        : renderStatsHuman(report),
+    );
+  } finally {
+    store.close();
+  }
+}