omp-conductor 0.19.7 → 0.20.0

package/src/daemon/views.ts

@@ -0,0 +1,751 @@
+/**
+ * Read-only projections: everything that answers "what is the fleet doing"
+ * without changing it.
+ *
+ * `StatusSnapshot` is the whole reason this is one module. It is the single
+ * shape the CLI, the dashboard, the board and `/healthz` all render, and it is
+ * built here from the store rather than assembled per caller — three renderers
+ * projecting three nearly-identical shapes is how a status display starts
+ * disagreeing with itself. The `format*` helpers beside it are the shared
+ * fragments those renderers reach for.
+ *
+ * The rule that keeps the boundary honest: nothing here writes. A projection
+ * that also reconciled would make every caller of a display a caller of a
+ * mutation — which is why the historical-infra backfill lives in
+ * `settle-pass.ts` and only its results are read from here.
+ *
+ * `prepareConductor` is the one exception, and a deliberate one: it is setup's
+ * "create the store and hold dispatch" barrier, and it lives beside the snapshot
+ * because holding and then reading back the held state is one operator gesture.
+ */
+import { startOfToday } from "../admission.ts";
+import { availabilityState, type AvailabilityState } from "../availability.ts";
+import { configPath, findProject, loadConfig, resolveCaps, resolveReleaseGrants, resolveReview, stateDir } from "../config.ts";
+import { digestScheduleState, type DigestScheduleState } from "../digest-schedule.ts";
+import { SPEND_SAMPLE_ROWS, SPEND_SAMPLE_RUNS } from "../doctor.ts";
+import type { CodeGraphHealth } from "../graph-health.ts";
+import { isPaused, pauseProvenance, setPaused } from "../pause.ts";
+import { branchName, route } from "../routing.ts";
+import { judgeSpendTelemetry, type SpendTelemetryVerdict } from "../spend-telemetry.ts";
+import { dbPath, openStore, utcDay } from "../store.ts";
+import { makeTracker, type RateLimitStatus } from "../tracker/github.ts";
+import { DEFAULT_REPORT_POLICY, RELEASE_SHAPES, type BaseFreeze, type BaseHealth, type Caps, type DigestBacklog, type DispatchSummary, type HandoffWithdrawal, type InstallSurfaceObservation, type InterruptCategory, type OrchestratorIncident, type ProjectConfig, type ReportRecord, type ReportScope, type ReportingPolicy, type ResolvedGrants, type ReviewAdjudicationRecord, type ReviewCorrectionRound, type ReviewHeadBlocker, type ReviewPolicy, type RunRecord, type Store, type TurnOverride, type VerbLedgerEntry } from "../types.ts";
+import { readUpgradeJournal } from "../upgrade-journal.ts";
+import { upgradeRecoveryStatus, type UpgradeRecoveryStatus } from "../upgrade-verify.ts";
+import type { PlanUsageStatus } from "../usage.ts";
+import { STATUS_LEDGER_SCAN } from "../verbs/ledger.ts";
+import type { WorkerPausePhase } from "../worker.ts";
+import { UNROUTABLE_TEXT, type WorkerControlRegistry } from "./deps.ts";
+import { readDrain } from "./drain.ts";
+
+export interface DaemonHealthSnapshot {
+  ok: boolean;
+  paused: boolean;
+  activeRuns: number;
+  project: string;
+  /** One-shot issue ceilings waiting for the next claim. */
+  turnOverrides: TurnOverride[];
+  dispatch?: DispatchSummary;
+  codeGraph?: CodeGraphHealth;
+  /** Live workers in a non-running pause phase; absent/empty = nothing paused.
+   *  `source`/`pausedAtMs` carry the pause provenance when one was recorded (#997). */
+  workers?: { issue: number; runId: string; phase: WorkerPausePhase; source?: string; pausedAtMs?: number }[];
+  /**
+   * The live orchestrator surface, attested by the running daemon (#832):
+   * which mode this project's fleet is in, and — when the daemon hosts the
+   * orchestrator session itself — the extension version that session *loaded*
+   * and the transcript it resumed. This is the read the upgrade's
+   * session-reload verification checks: a restarted daemon whose orchestrator
+   * child came up on the installed release answers `loaded` equal to that
+   * release; one that never reloaded answers an older version; one that
+   * failed to start answers `mode: "failed"`. `external` means the pane owns
+   * the session and the daemon cannot attest it from here.
+   */
+  orchestrator?: {
+    mode: "embedded" | "external" | "failed";
+    loaded?: string;
+    sessionFile?: string;
+    alive?: boolean;
+  };
+}
+
+export interface DaemonHealth {
+  ok: boolean;
+  /** Resident set of this daemon; workers are in-process omp sessions. */
+  rssBytes: number;
+  projects: DaemonHealthSnapshot[];
+}
+
+export function daemonHealthSnapshot(
+  store: Store,
+  project: string,
+  paused = isPaused(project),
+  codeGraph?: CodeGraphHealth,
+  workerControls?: WorkerControlRegistry,
+  orchestrator?: DaemonHealthSnapshot["orchestrator"],
+): DaemonHealthSnapshot {
+  const dispatch = store.latestDispatch(project);
+  return {
+    ok: true,
+    paused,
+    activeRuns: store.activeRuns(project).length,
+    turnOverrides: store.listTurnOverrides(project),
+    project,
+    ...(dispatch === undefined ? {} : { dispatch }),
+    ...(codeGraph?.configured === true ? { codeGraph } : {}),
+    ...(workerControls === undefined ? {} : { workers: workerControls.snapshot(project) }),
+    ...(orchestrator === undefined ? {} : { orchestrator }),
+  };
+}
+
+export function daemonHealth(
+  projects: DaemonHealthSnapshot[],
+  rssBytes = process.memoryUsage().rss,
+): DaemonHealth {
+  return { ok: projects.every((project) => project.ok), rssBytes, projects };
+}
+
+/**
+ * The effective reporting surface, derived from the configured policy — never
+ * from the legacy preset name alone: an explicit policy without the
+ * `scopePreset` back-annotation must present the same truth from `interruptOn`
+ * and the digest cadence (#633).
+ */
+export interface ReportingSummary {
+  /** The legacy preset this policy came from, when the config back-annotates one. */
+  scopePreset?: ReportScope;
+  /** Categories allowed to interrupt the operator's phone. */
+  interruptOn: InterruptCategory[];
+  /** Where non-interrupting outcomes accumulate: the effective digest config. */
+  digest: ReportingPolicy["digest"];
+}
+
+/**
+ * The effective reporting summary. The loader always materialises the policy,
+ * so `undefined` means the default (`DEFAULT_REPORT_POLICY`); the preset name
+ * is carried only when the policy actually back-annotates one, so a rendered
+ * status names the preset without ever letting a stale or absent preset
+ * misstate what the policy does (#633).
+ */
+export function reportingSummary(policy: ReportingPolicy | undefined): ReportingSummary {
+  const effective = policy ?? DEFAULT_REPORT_POLICY;
+  return {
+    ...(effective.scopePreset === undefined ? {} : { scopePreset: effective.scopePreset }),
+    interruptOn: [...effective.interruptOn],
+    digest: { ...effective.digest },
+  };
+}
+
+/**
+ * The active drain as structured status exposes it: the creation instant, the
+ * absolute deadline, the purpose, and the live-run count the drain is waiting
+ * to reach zero. Only present on the snapshot while the record is fresh.
+ */
+export interface DrainStatus {
+  /** Epoch-ms instant the drain intent was recorded. */
+  since: number;
+  /** Absolute epoch-ms deadline — admission resumes automatically after it. */
+  expiresAt: number;
+  /** Purpose recorded at creation. */
+  reason?: string;
+  /** Runs still in the active set (live workers plus pushed-state PRs) — the
+   *  count a drain waits to reach zero, matching the `runs-settled` release
+   *  gate (#776 review #2). */
+  remainingRuns: number;
+}
+
+export interface StatusSnapshot {
+  project: string;
+  configPath: string;
+  stateDir: string;
+  paused: boolean;
+  /**
+   * Why the fleet is paused, when whatever paused it said. Rendered beside
+   * `(PAUSED)` so a pause an operator did not issue names itself instead of
+   * reading like a mistake (#220).
+   */
+  pauseReason?: string;
+  /** Unresolved host-wide upgrade recovery, rendered identically for every project. */
+  upgradeRecovery?: UpgradeRecoveryStatus;
+  /**
+   * The project's active self-expiring drain (#484): present only while a
+   * fresh, valid drain record exists. Paused and drained are deliberately two
+   * fields — a drain is bounded and self-clearing where a pause is not, and
+   * the structured surface has to tell them apart without reading the pass
+   * history. Human CLI wording over it is a later #484 child.
+   */
+  drain?: DrainStatus;
+  /** Mechanical operator availability at the moment this snapshot was read. */
+  availability?: AvailabilityState;
+  /** Next digest opportunity under the same predicate that gates submission. */
+  digestSchedule?: DigestScheduleState;
+  /**
+   * The effective reporting policy: what interrupts, where everything else
+   * goes, and the legacy preset name when one is back-annotated. On the
+   * snapshot so the human `status`, the dashboard API and the CLI all read
+   * the same truth about the reporting surface without opening config — a
+   * routine outcome that reads as "Telegram is broken" unless the policy says
+   * it is digest-only (#633).
+   */
+  reporting?: ReportingSummary;
+  caps: Caps;
+  /**
+   * The effective per-shape release grants. On the snapshot rather than re-read
+   * by each renderer because #122 began with a grant nobody had looked at in
+   * weeks: `status` names them so a stale one is visible without opening either
+   * the config or the brief.
+   */
+  releaseGrants: ResolvedGrants;
+  /**
+   * The effective review policy (#678). On the snapshot for the reason
+   * `releaseGrants` is: the orchestrator's Duty 1 has to act on it every
+   * tick, and a stale level or ceiling sitting only in a config file nobody
+   * opens is exactly the drift this field exists to surface. The loader always
+   * materialises it, so this is never absent on a real daemon.
+   */
+  review: ReviewPolicy;
+  /** Occupied issues: live workers plus green PRs awaiting a human merge. Both
+   *  lifecycle kinds, told apart by {@link StatusSnapshot.leasedRunIds}. */
+  activeRuns: RunRecord[];
+  /**
+   * The subset of {@link StatusSnapshot.activeRuns} holding an **active
+   * mutation lease** (#898): a live worker, or a dispatched unsettled review
+   * revision. Everything else in `activeRuns` is a worker-free preserved
+   * artifact — durable work awaiting review, merge or recovery, with nothing
+   * writing to it.
+   *
+   * Carried as ids rather than a second run list so the two renderings cannot
+   * disagree about the rows themselves, and derived from `Store.leasedRuns` —
+   * the same query admission's file-lane gate and `conductor_pr_recover` read,
+   * so what status calls a lease is exactly what those two enforce (#899,
+   * #925). A plain array so the dashboard's JSON round-trip preserves it.
+   */
+  leasedRunIds?: readonly string[];
+  /**
+   * The review-ceiling adjudications an operator needs to see (#874): every
+   * non-terminal one, plus the terminal one for each active run's PR head — so a
+   * cleared or rejected verdict stays visible for exactly as long as the PR it
+   * decided is still in flight, and disappears with it rather than accumulating.
+   *
+   * Keyed by nothing: the records carry their own `prUrl` and `headSha`, which is
+   * how the renderer matches them to a run without inventing a second identity
+   * for a PR.
+   */
+  reviewAdjudications?: readonly ReviewAdjudicationRecord[];
+  /**
+   * runId → live review-revision round, for runs whose revision worker is
+   * currently dispatched (#692). Derived from the durable `review_revisions`
+   * rows, so the rendered `review-revision N` state rests on the same facts
+   * the restart recovery reads — never on a label or a guess. A plain object
+   * (not a Map) so the dashboard's JSON round-trip of the snapshot preserves
+   * it byte for byte.
+   */
+  /**
+   * The live review round per run: its number AND the instant it was dispatched
+   * (#802). The instant is what makes the line honest — a resumed session's
+   * `turns` and `startedAt` are cumulative over the whole attempt, so without a
+   * phase boundary a fresh revision reads as though it had been running for
+   * hours.
+   */
+  reviewRounds?: Readonly<Record<string, { round: number; dispatchedAt: number }>>;
+  /**
+   * runId → the durable review evidence blocking a merge of the run's
+   * pushed-green PR at its exact recorded head (#888). Derived from the same
+   * `review_revisions` rows `conductor_pr_merge` refuses on, so status can
+   * never present a green PR as merge-ready while the privileged verb will
+   * refuse it. An absent entry means nothing blocks that run's head.
+   */
+  mergeBlockers?: Readonly<Record<string, ReviewHeadBlocker>>;
+  /**
+   * runId → every review-correction round recorded for that run, ascending by
+   * round, carrying #1045's durable launch provenance (#1048).
+   *
+   * Separate from {@link StatusSnapshot.reviewRounds} and
+   * {@link StatusSnapshot.mergeBlockers} on purpose: those two answer "what
+   * state does this run render as" and "what stands between this head and a
+   * merge", and both are deliberately narrow (one live round; one blocking
+   * round). This is the round *history* an operator reads to answer the #1035
+   * question — did conductor resume the diagnosed transcript or open a fresh
+   * correction, and under which model — so it includes settled rounds, which
+   * neither of the other two can see once they stop blocking anything.
+   *
+   * Every provenance field is copied off the row and never derived from the
+   * current config: rendering today's `workerModel` for a round dispatched
+   * under yesterday's is the exact silent fake #1048 names. A pre-#1045 row
+   * therefore projects with no provenance at all, which the renderer prints as
+   * an explicit unknown.
+   */
+  reviewCorrections?: Readonly<Record<string, readonly ReviewCorrectionRound[]>>;
+  /** Newest attempts holding a preserved WIP tip, or a tree that is still the
+   *  only copy of work the daemon could not save. */
+  salvagedRuns: RunRecord[];
+  /** Retained trees whose object store could not be made sound, so the daemon
+   *  refused to fetch into them and their commits cannot be verified against
+   *  any remote (#737). Distinguished from ordinary retention on purpose —
+   *  quarantine is "potentially stranded work", not routine housekeeping. */
+  quarantinedRuns: RunRecord[];
+  /** One-shot issue ceilings waiting for the next claim. */
+  turnOverrides: TurnOverride[];
+  /** Reports the operator has not provably received: pending, in-flight with an
+   *  unknown outcome, or written off. An empty list is the only honest way to
+   *  say "everything authored this cycle actually went out" (#123). */
+  openReports: ReportRecord[];
+  /** Recent successful report/notice withdrawals, newest first. */
+  handoffWithdrawals?: HandoffWithdrawal[];
+  /** Ordinary outcomes and deferred escalations not yet associated with an
+   * accepted digest report. */
+  digestBacklog: DigestBacklog;
+  /**
+   * The most recent conductor-verb calls and how the daemon decided them
+   * (#126). On `status` rather than only behind `omp-conductor ledger` because
+   * a refused merge is news: it means a session tried to do something the
+   * config does not let it, and an operator who has to know to go looking is an
+   * operator who finds out from the tracker instead.
+   */
+  /** Current live-head push-workflow verdict per recently merged repository. */
+  baseHealth: BaseHealth[];
+  /** Per-repo base-red merge freezes, active first (#283). */
+  freezes: BaseFreeze[];
+  verbLedger: VerbLedgerEntry[];
+  /** Runs backed by a worker process — the number capacity compares against. */
+  liveWorkers: number;
+  runsToday: number;
+  spendTodayUsd: number;
+  /** The install identities the last dispatch pass recorded (#919). Absent
+   *  means no pass has looked yet, which the renderer says out loud rather
+   *  than presenting as agreement. */
+  installSurfaces?: InstallSurfaceObservation;
+  /** What live runs have reserved out of today's budget but not yet spent
+   *  (#851). Optional so a caller that built a snapshot before reservations
+   *  existed renders no figure rather than a fabricated zero. */
+  reservedSpendUsd?: number;
+  /**
+   * Whether the figure above is built on runs that actually reported cost
+   * (#970). Absent when the caller did not judge it; the renderer then says
+   * nothing rather than implying the telemetry is sound.
+   */
+  spendTelemetry?: SpendTelemetryVerdict;
+  dispatch?: DispatchSummary;
+  /**
+   * Latest plan-allowance verdict, when the caller read one. Optional because
+   * this snapshot is built synchronously off the store while the provider read
+   * is I/O: a renderer that did not do that work must say "not read" rather
+   * than print a percentage nobody measured (#110).
+   */
+  planUsage?: PlanUsageStatus;
+  /**
+   * The GitHub API rate-limit budget, when the caller read one. Optional for
+   * the same reason as `planUsage` — the read is I/O and the snapshot is
+   * synchronous — and a broken `gh` must cost one status row, not the report
+   * (#188).
+   */
+  github?: RateLimitStatus;
+  /**
+   * Observed GitHub rate-limit refusals within the last five minutes, and the
+   * daemon's tracked per-source `gh` call counts for the UTC day. Unlike
+   * `github`, which a caller polls, these are written by the tracker's hooks —
+   * the polled budget sat beside what actually happened (#198).
+   */
+  ghRefusals?: { count: number; latestAt?: number };
+  ghCallsToday?: readonly { source: string; calls: number }[];
+  /**
+   * Label-projection ops still owed to the tracker (#201). Present only while
+   * one is pending: GitHub has not yet converged on what the store decided —
+   * a refused or deferred label write is exactly the state an operator should
+   * see rather than a silent gap.
+   */
+  labelOps?: { pending: number; oldestAgeMs: number };
+  /**
+   * The orchestrator-down incident, when the embedded orchestrator is down:
+   * mode, since-moment and the tier-1 escalations diverted to issue comments
+   * so far. Absent when the orchestrator is healthy (or external), so recovery
+   * drops the degrade row from `status` (#288).
+   */
+  orchestratorDown?: OrchestratorIncident;
+}
+
+/** Builds a status reading from an already-open store. Long-lived operator
+ * surfaces use this path so a one-second refresh does not repeatedly open and
+ * initialise SQLite connections. */
+export function statusSnapshotFromStore(
+  p: ProjectConfig,
+  caps: Caps,
+  store: Store,
+  planUsage?: PlanUsageStatus,
+): StatusSnapshot {
+  const now = Date.now();
+  const lastDigestKey = store.lastDigestDedupeKey(p.name);
+  const lastDigestDay =
+    lastDigestKey === undefined ? undefined : lastDigestKey.slice("digest:".length);
+  const since = startOfToday();
+  const dispatch = store.latestDispatch(p.name);
+  const labelOpsPending = store.countPendingLabelOps(p.name);
+  const oldestLabelOpAt = store.oldestPendingLabelOpAt(p.name);
+  // Read once: `status` renders the degrade row off this while it is down.
+  const orchestratorDown = store.orchestratorIncident(p.name);
+  // The journal is the authoritative recovery lifecycle. Render unresolved
+  // recovery even when an operator/project pause currently wins provenance,
+  // or before the verifier has re-created a missing global fence.
+  const pause = pauseProvenance(p.name);
+  const reason = pause?.reason;
+  const upgradeRecovery = upgradeRecoveryStatus(readUpgradeJournal(stateDir()), stateDir());
+  // Same cost discipline as the pause read: the drain record is a file read,
+  // and the active-drain view is only built when one is actually fresh. The
+  // read is observational — it never mutates the record — so a status read
+  // cannot consume a malformed marker the next dispatch pass still has to fail
+  // closed on; the dispatch consume owns cleanup (#776 review #2).
+  const drain = readDrain(p.name);
+  // The live run list feeds the worker-capacity row; the drain's
+  // remaining-runs count waits on the ACTIVE set (live workers plus
+  // pushed-state PRs), the same population the `runs-settled` release gate
+  // reads, so the two can never disagree about when a batch is finished
+  // (#776 review #2).
+  const live = store.liveRuns(p.name);
+  const active = store.activeRuns(p.name);
+  // Which of those active rows something is actually writing through (#898).
+  // The same query admission's file-lane gate and `conductor_pr_recover` read,
+  // so status cannot call a row a lease that those two treat as released, or
+  // vice versa (#899, #925).
+  const leasedRunIds = store.leasedRuns(p.name).map((r) => r.id);
+  // Adjudications worth rendering (#874): the open ones always, plus a terminal
+  // verdict for a head an active run is still sitting on. Bounded by the active
+  // set rather than by a history window, so a fleet with a thousand settled
+  // adjudications renders the handful that still describe live work.
+  const openAdjudications = store.openReviewAdjudications(p.name);
+  const adjudicationIds = new Set(openAdjudications.map((a) => a.id));
+  const reviewAdjudications = [...openAdjudications];
+  for (const r of active) {
+    if (r.prUrl === undefined || r.headSha === undefined) continue;
+    const decided = store.reviewAdjudicationForHead(p.name, r.prUrl, r.headSha);
+    if (decided !== undefined && !adjudicationIds.has(decided.id)) {
+      adjudicationIds.add(decided.id);
+      reviewAdjudications.push(decided);
+    }
+  }
+  // The live review-revision rounds, read from the same durable rows the
+  // restart recovery uses: a run whose revision is dispatched is read as
+  // `review-revision N` while its worker is live (#692).
+  const reviewRounds: Record<string, { round: number; dispatchedAt: number }> = {};
+  for (const revision of store.unsettledReviewRevisions(p.name)) {
+    if (revision.dispatchedAt !== undefined) {
+      reviewRounds[revision.runId] = { round: revision.round, dispatchedAt: revision.dispatchedAt };
+    }
+  }
+  // The exact-head merge blockers (#888), read from the same durable rows the
+  // merge verb consults: a pushed-green run whose PR stands at a head carrying
+  // unresolved review evidence — a round queued there, crashed mid-review
+  // there, or settled `failed` there.
+  const mergeBlockers: Record<string, ReviewHeadBlocker> = {};
+  for (const r of active) {
+    if (r.prUrl === undefined || r.headSha === undefined) continue;
+    const blocker = store.mergeBlockingReviews(p.name, r.prUrl, r.headSha)[0];
+    if (blocker !== undefined) {
+      mergeBlockers[r.id] = {
+        round: blocker.round,
+        state:
+          blocker.settledAt !== undefined ? "failed" : blocker.dispatchedAt !== undefined ? "crashed" : "pending",
+      };
+    }
+  }
+  // The review-correction round history per active run, with #1045's durable
+  // launch provenance (#1048). Read from the rows keyed by the run's own PR and
+  // then narrowed to the run: a continuation that inherited the PR must not
+  // show its predecessor's rounds as its own. Bounded by the active set for the
+  // same reason the adjudication projection is — a fleet with a thousand
+  // settled rounds renders the handful that still describe live work.
+  //
+  // Every provenance value is copied off the row verbatim, and an absent column
+  // stays absent: the renderer prints "unknown" for a pre-#1045 round, which is
+  // the truth, where filling it from `project.workerModel` would be an
+  // invention (#1048's named silent fake).
+  const reviewCorrections: Record<string, ReviewCorrectionRound[]> = {};
+  for (const r of active) {
+    if (r.prUrl === undefined) continue;
+    const rounds = store
+      .reviewRevisionsForPr(p.name, r.prUrl)
+      .filter((revision) => revision.runId === r.id)
+      .sort((a, b) => a.round - b.round)
+      .map((revision) => ({
+        round: revision.round,
+        state:
+          revision.settledAt !== undefined
+            ? ("settled" as const)
+            : revision.dispatchedAt !== undefined
+              ? ("dispatched" as const)
+              : ("pending" as const),
+        ...(revision.outcome === undefined ? {} : { outcome: revision.outcome }),
+        ...(revision.dispatchedAt === undefined ? {} : { dispatchedAt: revision.dispatchedAt }),
+        ...(revision.launchMode === undefined ? {} : { launchMode: revision.launchMode }),
+        ...(revision.requestedModel === undefined ? {} : { requestedModel: revision.requestedModel }),
+        ...(revision.resolvedModel === undefined ? {} : { resolvedModel: revision.resolvedModel }),
+        ...(revision.originSessionRef === undefined ? {} : { originSessionRef: revision.originSessionRef }),
+        ...(revision.correctionSessionRef === undefined
+          ? {}
+          : { correctionSessionRef: revision.correctionSessionRef }),
+      }));
+    if (rounds.length > 0) reviewCorrections[r.id] = rounds;
+  }
+  return {
+    project: p.name,
+    configPath: configPath(),
+    stateDir: stateDir(),
+    paused: isPaused(p.name),
+    ...(reason === undefined ? {} : { pauseReason: reason }),
+    ...(upgradeRecovery === undefined ? {} : { upgradeRecovery }),
+    ...(drain.kind === "active"
+      ? {
+          drain: {
+            since: Date.parse(drain.drain.createdAt),
+            expiresAt: Date.parse(drain.drain.expiresAt),
+            ...(drain.drain.reason === undefined ? {} : { reason: drain.drain.reason }),
+            remainingRuns: active.length,
+          } satisfies DrainStatus,
+        }
+      : {}),
+    availability: availabilityState(p.reporting, now),
+    digestSchedule: digestScheduleState(p.reporting ?? DEFAULT_REPORT_POLICY, lastDigestDay, now),
+    reporting: reportingSummary(p.reporting ?? DEFAULT_REPORT_POLICY),
+    caps,
+    releaseGrants: resolveReleaseGrants(p),
+    review: resolveReview(p),
+    activeRuns: active,
+    leasedRunIds,
+    reviewAdjudications,
+    reviewRounds,
+    reviewCorrections,
+    salvagedRuns: store.salvagedRuns(p.name),
+    quarantinedRuns: store.quarantinedRuns(p.name),
+    turnOverrides: store.listTurnOverrides(p.name),
+    openReports: store.openReports(p.name),
+    handoffWithdrawals: store.handoffWithdrawals(p.name),
+    digestBacklog: store.digestBacklog(p.name),
+    verbLedger: store.verbLedger(p.name, { limit: STATUS_LEDGER_SCAN }),
+    liveWorkers: live.length,
+    runsToday: store.runsStartedSince(p.name, since),
+    spendTodayUsd: store.spendSince(p.name, since),
+    reservedSpendUsd: store.reservedSpendUsd(p.name),
+    // Judged from the store on the same read as the figure above (#970), so the
+    // row that qualifies the spend number cannot disagree with it, and nothing
+    // is probed at render time.
+    spendTelemetry: judgeSpendTelemetry(
+      store.recentSpendSamples?.(p.name, SPEND_SAMPLE_ROWS) ?? [],
+      SPEND_SAMPLE_RUNS,
+      {
+        // Config and an already-read status only — this snapshot probes nothing
+        // at render time, which is the property the figure above depends on
+        // (#970). The declaration alone is enough to know a dollar cap cannot
+        // fire; the window name rides along when a configured plan cap has
+        // already resolved one, and `doctor` (which may probe) reads it live.
+        declaredSubscription: (p.requireOauthProviders ?? []).length > 0,
+        ...(planUsage?.window === undefined
+          ? {}
+          : {
+              allowanceWindow:
+                planUsage.window.label === undefined
+                  ? planUsage.window.id
+                  : `${planUsage.window.id} (${planUsage.window.label})`,
+            }),
+      },
+    ),
+    // Read, never probed: the recorded row is the whole point (#919).
+    ...(() => {
+      const observed = store.installSurfaces();
+      return observed === undefined ? {} : { installSurfaces: observed };
+    })(),
+    ...(dispatch === undefined ? {} : { dispatch }),
+    ...(planUsage === undefined ? {} : { planUsage }),
+    // Written by the tracker's hooks rather than polled, so the renderer does
+    // not re-read GitHub to know it is being refused (#198).
+    ghRefusals: store.ghRefusalsSince?.(now - 5 * 60_000),
+    ghCallsToday: store.ghCallsToday?.(utcDay()),
+    ...(labelOpsPending === 0 || oldestLabelOpAt === undefined
+      ? {}
+      : { labelOps: { pending: labelOpsPending, oldestAgeMs: now - oldestLabelOpAt } }),
+    baseHealth: store.baseHealth(p.name),
+    freezes: store.freezes(p.name),
+    mergeBlockers,
+    ...(orchestratorDown === undefined ? {} : { orchestratorDown }),
+  };
+}
+
+/** Opens and closes its own store handle so one-shot CLI and plugin readers can
+ * read status while a daemon in another process is writing (the store runs in
+ * WAL mode for exactly this). */
+export function statusSnapshot(project?: string): StatusSnapshot {
+  const cfg = loadConfig();
+  const p = findProject(cfg, project);
+  const store = openStore(dbPath());
+  try {
+    return statusSnapshotFromStore(p, resolveCaps(p, cfg.defaults), store);
+  } finally {
+    store.close();
+  }
+}
+
+export function formatDispatchSummary(summary?: DispatchSummary): string {
+  if (summary === undefined) return "last dispatch  (none recorded)";
+  const lines = [
+    `last dispatch  ${new Date(summary.completedAt).toISOString()}${summary.degraded ? "  DEGRADED" : ""}`,
+  ];
+  if (summary.paused === true) {
+    // A held pass never routed the queue: printing zero candidates here would
+    // read as "the queue was empty". Say what the pass was and attribute what
+    // it did instead (#497).
+    lines.push(`  pass          held — nothing admitted`);
+  } else {
+    lines.push(
+      `  candidates    ${summary.ready} ready / ${summary.claimed ?? 0} in flight / ${summary.routed} spare`,
+      `  admitted      ${summary.admitted}`,
+    );
+    // The operator's park label, counted from the same eligibility read the
+    // claim gate uses (#507): "0 claimable, 12 parked" and "0 claimable,
+    // nothing to do" demand opposite orchestrator responses and must not
+    // render alike. Omitted at zero so an empty queue stays the old shape.
+    const parked = summary.parked ?? 0;
+    if (parked > 0) {
+      lines.push(`  parked        ${parked} — operator-held, never claimed`);
+    }
+    if (summary.holds.length === 0) {
+      lines.push("  held          0");
+    } else {
+      lines.push("  held");
+      for (const hold of summary.holds) {
+        const sample =
+          hold.issues.length === 0
+            ? ""
+            : ` (#${hold.issues.join(", #")}${hold.count > hold.issues.length ? ", …" : ""})`;
+        lines.push(`    ${hold.reason}  ${hold.count}${sample}`);
+        // A `file-lane` hold groups several issues, each blocked by a different
+        // file and holder; the grouped line says how many, this says which.
+        //
+        // Deduplicated for display only, never in the record: a fleet-wide hold
+        // (`credential-class`, #852) gives every held candidate the *same*
+        // sentence, and printing one reason five times reads as five problems.
+        // The persisted details stay index-aligned with `issues` — a reader that
+        // needs "which issue got which detail" still has it.
+        const details = [...new Set(hold.details ?? [])];
+        if (details.length > 0) {
+          lines.push(`      ${details.join(" | ")}`);
+        }
+      }
+    }
+  }
+  if ((summary.settled ?? 0) > 0) lines.push(`  settled       ${summary.settled}`);
+  return lines.join("\n");
+}
+
+/**
+ * The grant table, named shape by shape.
+ *
+ * One renderer for both status surfaces (this one and the fleet view), because
+ * #122 began with a POLICY grant that no longer matched anyone's intent and went
+ * unnoticed: a stale grant has to be visible from `status` alone, and two
+ * renderers would eventually show it in only one of them.
+ */
+export function formatReleaseGrants(grants: ResolvedGrants): string[] {
+  const granted = RELEASE_SHAPES.filter((shape) => grants[shape] === "orchestrator");
+  return [
+    granted.length === 0
+      ? "release   no shape granted — every release/deploy tool call is blocked"
+      : `release   granted to the orchestrator: ${granted.join(", ")}`,
+    ...RELEASE_SHAPES.map((shape) => `  ${shape.padEnd(19)}${grants[shape]}`),
+  ];
+}
+
+export function formatBaseHealth(rows: readonly BaseHealth[]): string[] {
+  return rows.map((row) => {
+    const head = row.headSha.slice(0, 8);
+    if (row.verdict === "green") {
+      return `base ${row.repo}/${row.branch}  green (${row.runsCount} run(s)) at ${head}`;
+    }
+    if (row.verdict === "red") {
+      return `base ${row.repo}/${row.branch}  RED — ${row.detail ?? `workflow failed at ${head}`}`;
+    }
+    if (row.verdict === "pending") {
+      return `base ${row.repo}/${row.branch}  pending (${row.runsCount} run(s)) at ${head}`;
+    }
+    return (
+      `base ${row.repo}/${row.branch}  unknown — ` +
+      (row.detail ?? `no push-triggered workflow run for ${head}`)
+    );
+  });
+}
+
+/**
+ * The active base-red freezes as status lines — merges refused until the base
+ * is green again or the operator overrides. Active freezes only: a cleared
+ * freeze is history the ledger and digest already told an operator about.
+ */
+export function formatFreezes(freezes: readonly BaseFreeze[]): string[] {
+  const active = freezes.filter((f) => f.clearedAt === undefined);
+  if (active.length === 0) return [];
+  return [
+    "frozen repos  (merges refused until base green)",
+    ...active.map(
+      (f) =>
+        `  ${f.repo}  base red at ${f.culpritSha.slice(0, 8)}` +
+        (f.detail === undefined ? "" : `  ${f.detail}`) +
+        `  — override: omp-conductor unfreeze ${f.repo}`,
+    ),
+  ];
+}
+
+
+export interface QueuePreview {
+  project: string;
+  configPath: string;
+  queueDescription: string;
+  paused: boolean;
+  ready: { number: number; title: string; repo: string; branch: string }[];
+  unroutable: { number: number; title: string; reason: string; labels: string[] }[];
+}
+
+/**
+ * Exactly what the next tick would pick up, computed without touching a single
+ * label, run row or worktree. This is what makes `omp-conductor setup` honest: the
+ * dry run is the same routing code the loop uses, not a description of it.
+ */
+export async function previewProject(
+  p: ProjectConfig,
+  path: string = configPath(),
+): Promise<QueuePreview> {
+  const { routed, unroutable } = route(await makeTracker(p).listReady(), p);
+  const states = Object.values(p.stateLabels).join(", ");
+  return {
+    project: p.name,
+    configPath: path,
+    queueDescription:
+      `open issues in ${p.tracker.repo} labelled "${p.queueLabel}", ` +
+      `minus anything already labelled ${states}, ` +
+      `routed by one "${p.routing.labelPrefix}<repo>" label`,
+    paused: isPaused(p.name),
+    ready: routed.map((r) => ({
+      number: r.issue.number,
+      title: r.issue.title,
+      repo: r.repo.name,
+      branch: branchName(r.issue),
+    })),
+    unroutable: unroutable.map((u) => ({
+      number: u.issue.number,
+      title: u.issue.title,
+      reason: UNROUTABLE_TEXT[u.reason],
+      labels: u.labels,
+    })),
+  };
+}
+
+export async function previewQueue(project?: string): Promise<QueuePreview> {
+  const cfg = loadConfig();
+  return previewProject(findProject(cfg, project));
+}
+
+/**
+ * Creates the state store and holds dispatch while setup verifies the host.
+ *
+ * Setup calls this immediately after consent. Every later setup error therefore
+ * leaves the fleet paused instead of exposing a partially written runtime.
+ */
+export function prepareConductor(project?: string): void {
+  openStore(dbPath()).close();
+  setPaused(true, { source: "setup" }, project);
+}