omp-conductor 0.15.9 → 0.15.11

package/src/setup.ts

@@ -29,8 +29,10 @@ import {
   POLICY_BRIEF_NAME,
   composeOrchestrator,
   policyPathForRoot,
+  readSharedPolicy,
   refreshComposedBrief,
   renderBriefTemplate,
+  sharedPolicyPath,
 } from "./brief-upgrade.ts";
 import {
   clonePolicy,
@@ -55,6 +57,7 @@ import {
   WEEKDAYS,
   type BaseFreshness,
   type BehindBaseAction,
+  type AuthorityHolder,
   type Caps,
   type ConductorConfig,
   type DigestCadence,
@@ -411,6 +414,31 @@ export const MERGE_DUTY: { readonly [K in ProjectConfig["authority"]["merge"]]:
     "  one is a hard boundary, not a preference.",
 };
 
+/**
+ * The Promotion paragraph, worded from `authority.promotion`.
+ *
+ * The queue label is a sign-off: adding it to an issue lets a worker claim it
+ * and starts spend. POLICY.md must state who may do that — never a blank the
+ * floor defers into — and an unstated owner reads operator-only, because a
+ * gate nobody claimed must not resolve to the session that wants to use it.
+ *
+ * The paragraph refers to "the queue label" rather than naming it: the label
+ * itself is rendered into the section heading from config, and a second copy
+ * here would be a label that can disagree with the one the daemon reads.
+ */
+export const PROMOTION_DUTIES: { readonly [K in AuthorityHolder]: string } = {
+  human:
+    "**Default: the operator promotes.** Adding the queue label to an issue is promotion, and\n" +
+    "promotion is the operator's: the orchestrator grooms, routes and proposes, but the label\n" +
+    "goes on only when the operator puts it there — it is the sign-off that starts spend. To\n" +
+    "delegate, re-run `omp-conductor setup` or replace this paragraph with one naming the\n" +
+    "orchestrator as promoter.",
+  orchestrator:
+    "**Delegated in setup: the orchestrator promotes.** Adding the queue label to an issue is\n" +
+    "promotion, and the orchestrator may do it after grooming the issue, one at a time. The\n" +
+    "operator can take it back by editing this paragraph.",
+};
+
 export { ORCHESTRATOR_BRIEF_NAME, POLICY_BRIEF_NAME };
 
 /** Shipped floor template — duties, tiers, hard boundaries, Learning loop. */
@@ -427,12 +455,14 @@ const POLICY_TEMPLATE_PATH = join(import.meta.dir, "briefs", "policy.md");
 const REQUIRED_SCOPES = ["repo", "project"] as const;
 
 /** GitHub's own palette, so the tracker reads at a glance: green means queued,
- *  blue means moving, amber means waiting on you, red means it gave up. */
+ *  blue means moving, amber means waiting on you, red means it gave up, and
+ *  purple is routing — the operator's input, the one label the loop never writes. */
 const LABEL_COLOURS = {
   queue: "0e8a16",
   inProgress: "1d76db",
   blocked: "fbca04",
   failed: "b60205",
+  routing: "6f42c1",
 } as const;
 
 interface GhResult {
@@ -514,11 +544,18 @@ export async function checkTokenScopes(): Promise<ScopeCheck> {
 }
 
 /**
- * The four labels the loop reads and writes, and which already exist. Read-only:
- * this is what the operator is shown before being asked to consent to creation.
+ * Every label setup wants on the tracker, before existence is known: the queue
+ * and state labels the loop reads and writes, plus one routing label per routed
+ * repo. Pure — the prefix and the repo keys are already answered at this point
+ * in the interview — which is what lets a test pin the whole set without `gh`.
+ *
+ * Routing labels are provisioned, never applied: `route()` requires exactly one
+ * `<prefix><repo>` label per issue and treats zero or two as unroutable, so a
+ * tracker without them can queue nothing. Creating them queues nothing either —
+ * applying one, with the queue label, stays the operator's sign-off.
  */
-export async function planLabels(trackerRepo: string, a: SetupAnswers): Promise<LabelPlan[]> {
-  const wanted: Omit<LabelPlan, "exists">[] = [
+export function wantedLabels(a: SetupAnswers): Omit<LabelPlan, "exists">[] {
+  return [
     {
       name: a.queueLabel,
       colour: LABEL_COLOURS.queue,
@@ -539,13 +576,28 @@ export async function planLabels(trackerRepo: string, a: SetupAnswers): Promise<
       colour: LABEL_COLOURS.failed,
       description: "The conductor gave up on this issue after its retry budget",
     },
+    ...a.targetRepos.map((r) => ({
+      name: `${a.routingLabelPrefix}${r.name}`,
+      colour: LABEL_COLOURS.routing,
+      description: `Routes this issue to the ${r.name} checkout`,
+    })),
   ];
+}
 
-  const existing = await listLabelNames(trackerRepo);
-
-  // GitHub label names are unique case-insensitively, so an operator who answers
-  // "Ready-For-Agent" against an existing "ready-for-agent" must not be told a
-  // creation is pending that would then fail.
+/**
+ * Turns wanted labels into the plan the operator is shown, deduped
+ * case-insensitively and marked against what already exists.
+ *
+ * GitHub label names are unique case-insensitively, so an operator who answers
+ * "Ready-For-Agent" against an existing "ready-for-agent" must not be told a
+ * creation is pending that would then fail — and a multi-repo project whose
+ * names case-fold onto each other or onto a lifecycle label wants one creation,
+ * not two.
+ */
+export function planAgainstLabels(
+  wanted: readonly Omit<LabelPlan, "exists">[],
+  existing: ReadonlySet<string>,
+): LabelPlan[] {
   const seen = new Set<string>();
   const plan: LabelPlan[] = [];
   for (const w of wanted) {
@@ -557,6 +609,18 @@ export async function planLabels(trackerRepo: string, a: SetupAnswers): Promise<
   return plan;
 }
 
+/**
+ * The labels a tracker needs, and which already exist. Read-only: this is what
+ * the operator is shown before being asked to consent to creation.
+ *
+ * The queue and state labels are the ones the loop reads and writes; the
+ * routing labels (one per repo) are the operator's input that makes an issue
+ * routable, and setup provisions them only so there is something to apply.
+ */
+export async function planLabels(trackerRepo: string, a: SetupAnswers): Promise<LabelPlan[]> {
+  return planAgainstLabels(wantedLabels(a), await listLabelNames(trackerRepo));
+}
+
 /** Lower-cased label names currently on the repo. Throws rather than guessing:
  *  a repo whose labels cannot be listed cannot be serviced either. */
 async function listLabelNames(trackerRepo: string): Promise<Set<string>> {
@@ -1023,6 +1087,7 @@ function briefVarsForProject(p: ProjectConfig): Record<string, string> {
     QUEUE_LABEL: p.queueLabel,
     RELEASES_DEFAULT: RELEASES_DEFAULTS[`${p.authority.merge}/${p.authority.release}`],
     MERGE_DUTY: MERGE_DUTY[p.authority.merge],
+    PROMOTION_DUTY: PROMOTION_DUTIES[p.authority.promotion ?? DEFAULT_AUTHORITY.promotion],
     POLICY_SOURCE: policySourceLine(p),
   };
 }
@@ -1073,14 +1138,19 @@ export function renderPolicyForProject(p: ProjectConfig): string {
 }
 
 /**
- * Composed session brief: rendered floor + POLICY scaffold (or a caller's policy).
+ * Composed session brief: rendered floor + shared policy (when present) +
+ * POLICY scaffold (or a caller's policy).
  *
  * Setup writes the policy half to `POLICY.md` and this compose to
- * `ORCHESTRATOR.md`. Later ticks recompose from the live POLICY.md so package
- * floor updates apply without brief-upgrade.
+ * `ORCHESTRATOR.md`. Later ticks recompose from the live POLICY.md and the live
+ * host-wide shared policy, so package floor updates apply without brief-upgrade.
  */
 export function renderBriefForProject(p: ProjectConfig, policyText?: string): string {
-  return composeOrchestrator(renderFloorForProject(p), policyText ?? renderPolicyForProject(p));
+  return composeOrchestrator(
+    renderFloorForProject(p),
+    policyText ?? renderPolicyForProject(p),
+    readSharedPolicy(),
+  );
 }
 
 /** Wizard-time path, via the project the answers describe. */
@@ -1094,7 +1164,7 @@ export function renderOrchestratorBrief(a: SetupAnswers, prose: ProbedProse = {}
   // would write" and "what setup writes" cannot diverge — the preview an operator
   // consents to is the file they get.
   const project = buildProject(a);
-  return composeOrchestrator(renderFloorForProject(project), renderPolicy(a, prose));
+  return composeOrchestrator(renderFloorForProject(project), renderPolicy(a, prose), readSharedPolicy());
 }
 
 /** `POLICY.md` for these answers: the project's own template plus the interview. */
@@ -1149,7 +1219,7 @@ export function writeOrchestratorBrief(a: SetupAnswers, prose: ProbedProse = {})
   mkdirSync(dirname(orchestratorPath), { recursive: true });
   const policy = renderPolicy(a, prose);
   writeFileSync(policyPath, policy);
-  writeFileSync(orchestratorPath, composeOrchestrator(renderFloorForProject(project), policy));
+  writeFileSync(orchestratorPath, composeOrchestrator(renderFloorForProject(project), policy, readSharedPolicy()));
   return orchestratorPath;
 }
 
@@ -1246,7 +1316,8 @@ function releaseLines(j: OperatorJudgment): string[] {
 }
 
 /**
- * Recompose `ORCHESTRATOR.md` from the package floor + live `POLICY.md`.
+ * Recompose `ORCHESTRATOR.md` from the package floor + host-wide shared policy
+ * (when present) + live `POLICY.md`.
  *
  * Returns false when POLICY.md is missing (caller should migrate or set up).
  */
@@ -1255,6 +1326,7 @@ export function refreshComposedBriefForProject(p: ProjectConfig): boolean {
     policyPath: policyPathForProject(p),
     orchestratorPath: briefPathForProject(p),
     floor: renderFloorForProject(p),
+    sharedPolicyPath: sharedPolicyPath(),
   });
 }
 
@@ -1355,6 +1427,15 @@ function describeAvailabilityDays(days: readonly Weekday[]): string {
     : days.join(",");
 }
 
+/**
+ * The caps table's key column. Wide enough that the longest cap key,
+ * `maxConcurrentWorkersPerRepo`, cannot fuse with its value — the very defect
+ * that made #448's consent screen read `maxConcurrentWorkersPerRepo1` while
+ * the daemon ran 3. Exported so tests pin the rendered table against the same
+ * column the renderer uses.
+ */
+export const CAPS_PLAN_KEY_PAD = 28;
+
 /**
  * Everything that would change, as plain text, with no side effects at all.
  *
@@ -1368,11 +1449,15 @@ export function summarisePlan(
   scopes: ScopeCheck,
   labels: LabelPlan[],
   tg: TelegramPresence,
+  defaults: Caps = DEFAULT_CAPS,
 ): string {
   const project = buildProject(a);
-  // Caps are shown against the shipped baseline: the summary describes what
-  // these answers mean on their own, before any hand-edited global block.
-  const effective = resolveCaps(project, DEFAULT_CAPS);
+  // Caps are resolved against the caller's defaults — the loaded config's
+  // global block on a re-run, the shipped baseline on a first run, where the
+  // two are the same object. That is the exact baseline the daemon resolves
+  // against, so the consent screen and runtime cannot disagree (#372/#448).
+  // The shipped baseline itself is never labelled "effective".
+  const effective = resolveCaps(project, defaults);
   const states = Object.values(a.stateLabels).join(", ");
 
   const lines: string[] = [];
@@ -1441,10 +1526,10 @@ export function summarisePlan(
   lines.push("", "caps (effective)");
   for (const [key, value] of Object.entries(effective)) {
     const answered = Object.hasOwn(project.caps, key) ? "  (answered)" : "";
-    lines.push(`  ${key.padEnd(22)}${String(value)}${answered}`);
+    lines.push(`  ${key.padEnd(CAPS_PLAN_KEY_PAD)}${String(value)}${answered}`);
   }
   if (a.workerModel !== undefined && a.workerModel.trim().length > 0) {
-    lines.push(`  ${"worker model".padEnd(22)}${a.workerModel.trim()}  (answered)`);
+    lines.push(`  ${"worker model".padEnd(CAPS_PLAN_KEY_PAD)}${a.workerModel.trim()}  (answered)`);
   }
 
   lines.push("", "escalation");
@@ -1482,7 +1567,7 @@ export function summarisePlan(
   const granted = RELEASE_SHAPES.filter((shape) => a.releaseGrants[shape] === "orchestrator");
   lines.push(
     "",
-    `authority      merge=${a.authority.merge}  release=${a.authority.release}`,
+    `authority      merge=${a.authority.merge}  release=${a.authority.release}  promotion=${a.authority.promotion ?? DEFAULT_AUTHORITY.promotion}`,
     `tool gate      ${
       granted.length === 0
         ? "every release/deploy shape blocked for workers and the orchestrator"
@@ -1602,13 +1687,16 @@ export type AmendAreaId = (typeof AMEND_AREA_IDS)[number];
  * `describe` is the reason the pick-list is worth anything — an operator picking
  * blind from eight nouns cannot tell which one holds the setting they came to
  * change, so every row carries its own current value. It reads only the config,
- * so the whole menu can be rendered and reviewed without a terminal.
+ * so the whole menu can be rendered and reviewed without a terminal. The caps
+ * row resolves inherited values against the defaults the caller is amending —
+ * the loaded config's global block on a re-run — so the menu and the daemon
+ * agree on what a project actually runs (#448).
  */
 export const AMEND_AREAS: {
   readonly [K in AmendAreaId]: {
     readonly name: string;
     readonly asks: string;
-    readonly describe: (p: ProjectConfig) => string;
+    readonly describe: (p: ProjectConfig, defaults?: Caps) => string;
   };
 } = {
   tracker: {
@@ -1636,8 +1724,8 @@ export const AMEND_AREAS: {
     // an area no menu offers is a setting only a full re-interview can reach.
     name: "caps & worker model",
     asks: "concurrency, spend, turn base and extension ceiling, wall clock, failed attempts, continuations — then the worker model",
-    describe: (p) => {
-      const c = resolveCaps(p, DEFAULT_CAPS);
+    describe: (p, defaults = DEFAULT_CAPS) => {
+      const c = resolveCaps(p, defaults);
       const answered = Object.keys(p.caps).length > 0;
       const spend =
         c.dailySpendUsd === null ? "no spend cap" : `$${c.dailySpendUsd}/day`;
@@ -1664,7 +1752,7 @@ export const AMEND_AREAS: {
   },
   authority: {
     name: "authority",
-    asks: "who lands green PRs, who cuts releases, then one question per release/deploy shape",
+    asks: "who lands green PRs, who cuts releases, who promotes, then one question per release/deploy shape",
     describe: (p) => {
       const grants = resolveReleaseGrants(p);
       const granted = RELEASE_SHAPES.filter((shape) => grants[shape] === "orchestrator");
@@ -1673,7 +1761,8 @@ export const AMEND_AREAS: {
       // set that mutates a running environment and the one #122 cost us. The full
       // table is in `status` and in the amend summary.
       return (
-        `merge=${p.authority.merge}, release=${p.authority.release}, tools: ` +
+        `merge=${p.authority.merge}, release=${p.authority.release}, ` +
+        `promote=${p.authority.promotion ?? DEFAULT_AUTHORITY.promotion}, tools: ` +
         `${granted.length === 0 ? "all blocked" : `${granted.length}/${RELEASE_SHAPES.length} granted`}` +
         `, deploy=${grants.deploy}`
       );
@@ -1742,10 +1831,10 @@ const AMEND_LABEL_MAX = 96;
  * its own text alone — and it is the value, not the noun, that tells them
  * whether this is the row they came for.
  */
-export function amendChoices(p: ProjectConfig): { id: AmendAreaId; label: string; description: string }[] {
+export function amendChoices(p: ProjectConfig, defaults: Caps = DEFAULT_CAPS): { id: AmendAreaId; label: string; description: string }[] {
   return AMEND_AREA_IDS.map((id) => {
     const area = AMEND_AREAS[id];
-    const current = area.describe(p);
+    const current = area.describe(p, defaults);
     return {
       id,
       label: `${area.name} — ${current.length > AMEND_LABEL_MAX ? `${current.slice(0, AMEND_LABEL_MAX - 1).trimEnd()}…` : current}`,
@@ -1762,11 +1851,18 @@ export function amendChoices(p: ProjectConfig): { id: AmendAreaId; label: string
  * mutation it authorises — creating labels, writing the config, replacing a
  * brief — and a delta alone names none of them. What this adds is the sentence
  * the operator is actually looking for: one area changed, everything else came
- * back off disk.
+ * back off disk. Inherited caps on both sides of the "was"/"now" compare
+ * against the same `defaults`, so a changed per-repo limit reads as a change
+ * and a carried value reads as no change (#448).
  */
-export function summariseAmend(area: AmendAreaId, before: ProjectConfig, a: SetupAnswers): string {
+export function summariseAmend(
+  area: AmendAreaId,
+  before: ProjectConfig,
+  a: SetupAnswers,
+  defaults: Caps = DEFAULT_CAPS,
+): string {
   const it = AMEND_AREAS[area];
-  const was = it.describe(before);
+  const was = it.describe(before, defaults);
   // The brief is a decision, not a config key, so its "after" is what the wizard
   // is about to do rather than what a rebuilt project would say.
   const now =
@@ -1774,7 +1870,7 @@ export function summariseAmend(area: AmendAreaId, before: ProjectConfig, a: Setu
       ? a.writeOrchestratorBrief
         ? `would ${existsSync(orchestratorBriefPath(a)) ? "OVERWRITE" : "write"} ${orchestratorBriefPath(a)}`
         : "not written — left exactly as it is"
-      : it.describe(buildProject(a));
+      : it.describe(buildProject(a), defaults);
 
   const others = AMEND_AREA_IDS.filter((o) => o !== area).map((o) => AMEND_AREAS[o].name);
   const lines = [`amending       ${it.name}  —  project ${before.name}`];

package/src/stats.ts

@@ -0,0 +1,331 @@
+/**
+ * `stats` — what the fleet accomplished and at what cost, over a window
+ * (#282, legibility 5/5).
+ *
+ * Pure by construction: every fact arrives as injected run rows, a window and
+ * a gh-call count, so the aggregation is testable without a daemon or a store
+ * (the same seam split `doctor` uses). The CLI command in ./commands/stats.ts
+ * supplies the rows through read-only store queries, then renders the same
+ * numbers the --json shape carries.
+ *
+ * The unit of outcome is the **issue journey**, never the run row: an issue
+ * that took six attempts is one merged outcome with six runs and one lead
+ * time. Counting rows would make a stranded issue look like productive
+ * throughput, which is the exact misreading this surface exists to prevent.
+ *
+ * Spend semantics follow the store's own convention (README Limitations, and
+ * the doctor `spend-telemetry` finding): a run whose `spendUsd` reads 0.00
+ * means harness telemetry was absent, not that the run was free. Such runs are
+ * counted separately as **unmetered** and never averaged into a per-issue cost.
+ */
+
+import type { RunRecord } from "./types.ts";
+
+/** The bounded window a report answers over. Day keys are UTC (`YYYY-MM-DD`). */
+export interface StatsWindow {
+  sinceDay: string;
+  untilDay: string;
+  sinceEpochMs: number;
+  untilEpochMs: number;
+}
+
+/** One aggregate, per repo and for the whole selection. */
+export interface RepoStats {
+  /** The repo name; `"(all)"` on the totals row. */
+  repo: string;
+  /** Distinct issues whose PR merged and settled inside the window. */
+  merged: number;
+  /** `merged` plus issues whose terminal state inside the window did not merge. */
+  settled: number;
+  /** `merged / settled`; `null` when nothing settled (never a fake 0). */
+  mergeRate: number | null;
+  /** Mean attempts per merged issue, over the whole continuation chain. */
+  runsPerMerged: number | null;
+  /** First queue-label claim → merge settlement, over merged issues, in ms. */
+  leadTimeMedianMs: number | null;
+  leadTimeP90Ms: number | null;
+  /** Metered (spendUsd > 0) spend across merged chains, rounded to cents. */
+  spendUsd: number;
+  /** `spendUsd / merged issues with ≥1 metered run`; null when none. */
+  spendPerMerged: number | null;
+  /** Runs examined with `spendUsd === 0` — telemetry absent, not free. */
+  unmeteredRuns: number;
+  /** Merged issues whose whole chain metered nothing — cost unknown, not $0. */
+  unmeteredMerged: number;
+  /** Terminal non-merged runs in the window, bucketed by failure class. */
+  failureClasses: Record<string, number>;
+}
+
+/** The stable report shape `--json` prints; the human renderer reads it too. */
+export interface StatsReport {
+  project: string;
+  window: StatsWindow;
+  /** Tracked GitHub API calls over the window's UTC days (#198). */
+  ghCalls: number;
+  /**
+   * True when nothing settled in the window: a fresh store or an idle fleet.
+   * A consumer must render this as "no measurements", never as zero outcomes.
+   */
+  empty: boolean;
+  /** The whole selection (`--project NAME`, or the sole configured project). */
+  total: RepoStats;
+  /** Per-repo aggregates of the same shape, busiest (by merges) first. */
+  repos: RepoStats[];
+}
+
+/** Terminal non-merged run states — everything the failure histogram counts. */
+const FAILED_STATES: ReadonlySet<RunRecord["state"]> = new Set([
+  "failed",
+  "blocked",
+  "killed",
+  "orphaned",
+  "stopped",
+]);
+
+/** Runs with no classified failure fall into this explicit bucket. */
+export const UNCLASSIFIED = "unclassified";
+
+/** The timestamp a run is placed on the window timeline. Mirrors the store's
+ *  `COALESCE(endedAt, startedAt)` convention everywhere else in this package. */
+const WINDOW_KEY = (run: RunRecord): number => run.endedAt ?? run.startedAt;
+
+/** One issue's settled outcome, reduced from its full attempt chain. */
+interface IssueOutcome {
+  repo: string;
+  merged: boolean;
+  /** Attempts in the whole chain (continuations collapse into one journey). */
+  attempts: number;
+  /** First claim → merge settlement, in ms. Present iff `merged`. */
+  leadTimeMs?: number;
+  /** Sum of metered (spendUsd > 0) spend across the chain, in USD. */
+  meteredSpend: number;
+  /** Runs in the chain whose spend actually metered. */
+  meteredRuns: number;
+}
+
+function median(sorted: readonly number[]): number {
+  if (sorted.length === 0) return Number.NaN;
+  const lo = sorted[Math.floor((sorted.length - 1) / 2)]!;
+  const hi = sorted[Math.ceil((sorted.length - 1) / 2)]!;
+  return (lo + hi) / 2;
+}
+
+/** Nearest-rank p90: at least 90% of the samples are at or below the result. */
+function p90(sorted: readonly number[]): number {
+  if (sorted.length === 0) return Number.NaN;
+  return sorted[Math.min(sorted.length - 1, Math.ceil(0.9 * sorted.length) - 1)]!;
+}
+
+function cents(usd: number): number {
+  return Math.round(usd * 100) / 100;
+}
+
+function emptyRepo(repo: string): RepoStats {
+  return {
+    repo,
+    merged: 0,
+    settled: 0,
+    mergeRate: null,
+    runsPerMerged: null,
+    leadTimeMedianMs: null,
+    leadTimeP90Ms: null,
+    spendUsd: 0,
+    spendPerMerged: null,
+    unmeteredRuns: 0,
+    unmeteredMerged: 0,
+    failureClasses: {},
+  };
+}
+
+/**
+ * Aggregate one repo's settled issues and failure runs into {@link RepoStats}.
+ * Lead times and per-issue cost are reported only where a merged issue exists;
+ * `null` is "not measured", never a zero that could read as a measurement.
+ */
+function summarize(args: {
+  repo: string;
+  outcomes: readonly IssueOutcome[];
+  failureRuns: readonly { repo: string; cls: string }[];
+  unmeteredRuns: number;
+}): RepoStats {
+  const out = emptyRepo(args.repo);
+  const merged = args.outcomes.filter((o) => o.merged);
+  const leadTimes = merged
+    .map((o) => o.leadTimeMs!)
+    .sort((a, b) => a - b);
+  const meteredMerged = merged.filter((o) => o.meteredRuns > 0);
+  const meteredSpend = merged.reduce((sum, o) => sum + o.meteredSpend, 0);
+
+  out.merged = merged.length;
+  out.settled = args.outcomes.length;
+  out.mergeRate = args.outcomes.length === 0 ? null : merged.length / args.outcomes.length;
+  if (merged.length > 0) {
+    out.runsPerMerged = merged.reduce((sum, o) => sum + o.attempts, 0) / merged.length;
+    out.leadTimeMedianMs = Math.round(median(leadTimes));
+    out.leadTimeP90Ms = Math.round(p90(leadTimes));
+  }
+  out.spendUsd = cents(meteredSpend);
+  out.spendPerMerged = meteredMerged.length === 0 ? null : cents(meteredSpend / meteredMerged.length);
+  out.unmeteredMerged = merged.filter((o) => o.meteredRuns === 0).length;
+  out.unmeteredRuns = args.unmeteredRuns;
+  for (const run of args.failureRuns) {
+    out.failureClasses[run.cls] = (out.failureClasses[run.cls] ?? 0) + 1;
+  }
+  return out;
+}
+
+/**
+ * Compute the report from store rows. `runs` is whatever the store's
+ * stats-window query returned for the project: rows settling at or after
+ * `window.sinceEpochMs`, plus the full chain of every issue whose merge
+ * settled there. Rows within an issue must be ordered by `startedAt`, so the
+ * first row of a chain is its first queue-label claim.
+ */
+export function computeStats(args: {
+  project: string;
+  window: StatsWindow;
+  ghCalls: number;
+  runs: readonly RunRecord[];
+}): StatsReport {
+  const chains = new Map<number, RunRecord[]>();
+  for (const run of args.runs) {
+    const chain = chains.get(run.issue);
+    if (chain === undefined) chains.set(run.issue, [run]);
+    else chain.push(run);
+  }
+
+  const outcomes: IssueOutcome[] = [];
+  const byRepo = new Map<string, IssueOutcome[]>();
+  const failureRuns: { repo: string; cls: string }[] = [];
+  let unmeteredRuns = 0;
+  const unmeteredByRepo = new Map<string, number>();
+
+  for (const chain of chains.values()) {
+    // One issue merges once; if a weird history ever carried two merged rows,
+    // the newest settlement wins.
+    let merged: RunRecord | undefined;
+    for (const run of chain) {
+      if (
+        run.state === "merged" &&
+        (merged === undefined || WINDOW_KEY(run) > WINDOW_KEY(merged))
+      ) {
+        merged = run;
+      }
+    }
+
+    const terminatedInWindow = chain.some(
+      (run) => FAILED_STATES.has(run.state) && WINDOW_KEY(run) >= args.window.sinceEpochMs,
+    );
+    // A chain appears in the result for two reasons: its merge settled in the
+    // window, or an individual run ended there. Without a merged row and
+    // without a terminal row in the window it is still in flight — news, not
+    // an outcome.
+    if (merged === undefined && !terminatedInWindow) continue;
+
+    for (const run of chain) {
+      if (run.spendUsd === 0) {
+        unmeteredRuns += 1;
+        unmeteredByRepo.set(run.repo, (unmeteredByRepo.get(run.repo) ?? 0) + 1);
+      }
+      if (merged === undefined && FAILED_STATES.has(run.state) && WINDOW_KEY(run) >= args.window.sinceEpochMs) {
+        failureRuns.push({ repo: run.repo, cls: run.failureClass ?? UNCLASSIFIED });
+      }
+    }
+
+    const claimAt = chain[0]!.startedAt;
+    const mergedAt = merged === undefined ? undefined : WINDOW_KEY(merged);
+    const repo =
+      merged?.repo ??
+      chain.find((r) => FAILED_STATES.has(r.state) && WINDOW_KEY(r) >= args.window.sinceEpochMs)!.repo;
+    const outcome: IssueOutcome = {
+      repo,
+      merged: merged !== undefined,
+      attempts: chain.length,
+      leadTimeMs: mergedAt === undefined ? undefined : Math.max(0, mergedAt - claimAt),
+      meteredSpend: chain.reduce((sum, run) => sum + (run.spendUsd > 0 ? run.spendUsd : 0), 0),
+      meteredRuns: chain.filter((run) => run.spendUsd > 0).length,
+    };
+    outcomes.push(outcome);
+    const bucket = byRepo.get(repo);
+    if (bucket === undefined) byRepo.set(repo, [outcome]);
+    else bucket.push(outcome);
+  }
+
+  const repos = [...byRepo.entries()]
+    .map(([repo, list]) =>
+      summarize({
+        repo,
+        outcomes: list,
+        failureRuns: failureRuns.filter((r) => r.repo === repo),
+        unmeteredRuns: unmeteredByRepo.get(repo) ?? 0,
+      }),
+    )
+    .sort((a, b) => b.merged - a.merged || b.settled - a.settled || a.repo.localeCompare(b.repo));
+
+  return {
+    project: args.project,
+    window: args.window,
+    ghCalls: args.ghCalls,
+    empty: outcomes.length === 0,
+    total: summarize({ repo: "(all)", outcomes, failureRuns, unmeteredRuns }),
+    repos,
+  };
+}
+
+/** `N` and its unit, for a count line that must not print "0" as a measure. */
+function countLine(n: number, noun: string, plural: string): string {
+  return `${n} ${n === 1 ? noun : plural}`;
+}
+
+function humanDuration(ms: number): string {
+  const s = Math.max(0, Math.round(ms / 1000));
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m ${String(s % 60).padStart(2, "0")}s`;
+  const h = Math.floor(m / 60);
+  if (h < 24) return `${h}h ${String(m % 60).padStart(2, "0")}m`;
+  return `${Math.floor(h / 24)}d ${String(h % 24).padStart(2, "0")}h`;
+}
+
+function renderRepo(repo: RepoStats, indent: string): string {
+  const lines: string[] = [];
+  const leadTimeMedian = repo.leadTimeMedianMs;
+  const leadTimeP90 = repo.leadTimeP90Ms;
+  const lead =
+    leadTimeMedian === null || leadTimeP90 === null
+      ? "—"
+      : `median ${humanDuration(leadTimeMedian)} · p90 ${humanDuration(leadTimeP90)}`;
+  const cost =
+    repo.spendPerMerged === null
+      ? `$${repo.spendUsd.toFixed(2)} metered on merged work (no metered merge to divide by)`
+      : `$${repo.spendUsd.toFixed(2)} metered ($${repo.spendPerMerged.toFixed(2)}/merged)`;
+  const unmetered: string[] = [];
+  if (repo.unmeteredRuns > 0) unmetered.push(`${countLine(repo.unmeteredRuns, "run", "runs")} unmetered`);
+  if (repo.unmeteredMerged > 0) unmetered.push(`${countLine(repo.unmeteredMerged, "merged issue", "merged issues")} never metered`);
+  const rates = repo.mergeRate === null ? "nothing settled" : `${(repo.mergeRate * 100).toFixed(1)}% of ${repo.settled} settled`;
+  const attempts = repo.runsPerMerged === null ? "—" : `${repo.runsPerMerged.toFixed(2)} per merged issue`;
+  lines.push(`${indent}${repo.repo}  merged ${repo.merged} (${rates})`);
+  lines.push(`${indent}  lead       ${lead} (first claim → merge)`);
+  lines.push(`${indent}  attempts   ${attempts}`);
+  lines.push(`${indent}  cost       ${cost}${unmetered.length === 0 ? "" : ` · ${unmetered.join(" · ")}`}`);
+  const classes = Object.entries(repo.failureClasses).sort((a, b) => b[1] - a[1]);
+  if (classes.length > 0) {
+    lines.push(`${indent}  failures   ${classes.map(([cls, n]) => `${cls}: ${n}`).join(" · ")}`);
+  }
+  return lines.join("\n");
+}
+
+/** Render the human form of the same {@link StatsReport} `--json` prints. */
+export function renderStatsHuman(report: StatsReport): string {
+  const w = report.window;
+  const header = `${report.project} — outcomes ${w.sinceDay} → ${w.untilDay}`;
+  if (report.empty) {
+    return `${header}\n  nothing settled in the window — no runs recorded, so there are no measurements to report yet (a fresh store or an idle fleet).\n`;
+  }
+  const lines = [header, renderRepo(report.total, "  "), `  gh api     ${report.ghCalls} tracked ${report.ghCalls === 1 ? "call" : "calls"} in the window`];
+  if (report.repos.length > 0) {
+    lines.push("  per repo:");
+    for (const repo of report.repos) lines.push(renderRepo(repo, "    "));
+  }
+  return `${lines.join("\n")}\n`;
+}