omp-conductor 0.18.1 → 0.19.0

package/src/spend-telemetry.ts

@@ -0,0 +1,117 @@
+/**
+ * Is the daily spend cap's own input still arriving? (#970)
+ *
+ * The cap compares `store.spendSince(project, startOfToday())` — a sum of the
+ * per-run `spendUsd` column — against its ceiling. When the harness stops
+ * reporting cost, that column reads 0.00 and the cap silently measures a
+ * fraction of reality. #46 named this once already: **$0.00 spend is not proof
+ * of no spend.**
+ *
+ * Measured on this fleet, counting only runs that actually did work:
+ *
+ * | day        | worked | reported $0.00 |
+ * |------------|--------|----------------|
+ * | 2026-08-15 |     53 |  3.8%          |
+ * | …          |        |  0–2.5%        |
+ * | 2026-08-20 |     15 |  0.0%          |
+ * | 2026-08-21 |     22 | 31.8%          |
+ * | 2026-08-22 |     12 | 75.0%          |
+ *
+ * Six days of ≤3.8% baseline, then 32%, then 75% — with #614 running 213 turns
+ * for $0.00.
+ *
+ * Two properties are load-bearing, and both were wrong in the predicate this
+ * replaces:
+ *
+ * - **Only runs that did work are judged.** A run killed before its first turn
+ *   records $0.00 honestly; 26 of this project's 48 zero-spend rows are exactly
+ *   that. Counting them inflates the ratio *and* lets a run of administrative
+ *   kills fire a telemetry finding that says nothing about telemetry.
+ * - **A ratio, not `every`.** The old check fired only when every sampled run
+ *   reported zero. Replayed over all 410 windows in this fleet's history it
+ *   would have fired 14 times while staying silent through 37 windows that had
+ *   lost a majority of their telemetry — so the common case, partial loss, was
+ *   the invisible one. On 2026-08-21, at 31.8% loss, every window that day
+ *   contained one metered run and the probe was silent all day.
+ *
+ * One judgement, two consumers: `doctor`'s finding and the `status` row. The
+ * cap's figure and the statement about whether that figure means anything must
+ * never come from two implementations that can disagree.
+ */
+
+/** One sampled run, reduced to what the judgement needs. */
+export interface SpendSample {
+  /** Turns taken. Zero means the run never worked, so its $0.00 is honest. */
+  turns: number;
+  spendUsd: number;
+}
+
+/**
+ * The share of *working* runs whose spend is missing at or above which this is
+ * reported.
+ *
+ * A majority, deliberately — the observed healthy baseline is 0–3.8%, not zero.
+ * A legitimately free or aborted-after-one-turn run happens, and a check that
+ * fires on one of them is a check that gets ignored, which is the failure the
+ * install-surface rows already name: a warning repeated every fifteen minutes
+ * trains an operator to ignore the row that matters.
+ */
+export const SPEND_MISSING_SHARE = 0.5;
+
+export type SpendTelemetryVerdict =
+  /** Enough working runs, and most of them metered. */
+  | { kind: "healthy"; worked: number; missing: number; totalUsd: number }
+  /** Not enough working runs to say anything — never a pass by default. */
+  | { kind: "insufficient"; worked: number; needed: number }
+  /** A majority of working runs reported nothing. */
+  | { kind: "partial"; worked: number; missing: number }
+  /** Every working run reported nothing — the same fact, stated louder. */
+  | { kind: "absent"; worked: number };
+
+/**
+ * Judge a newest-first sample.
+ *
+ * `limit` is how many *working* runs are wanted, not how many rows to read: the
+ * caller over-samples and this takes the first `limit` runs that did work, so a
+ * burst of 0-turn kills cannot push the real evidence out of the window.
+ */
+export function judgeSpendTelemetry(
+  samples: readonly SpendSample[],
+  limit: number,
+): SpendTelemetryVerdict {
+  const working = samples.filter((row) => row.turns > 0).slice(0, limit);
+  if (working.length < limit) {
+    return { kind: "insufficient", worked: working.length, needed: limit };
+  }
+  const missing = working.filter((row) => row.spendUsd === 0).length;
+  if (missing === working.length) return { kind: "absent", worked: working.length };
+  if (missing / working.length >= SPEND_MISSING_SHARE) {
+    return { kind: "partial", worked: working.length, missing };
+  }
+  return {
+    kind: "healthy",
+    worked: working.length,
+    missing,
+    totalUsd: working.reduce((sum, row) => sum + row.spendUsd, 0),
+  };
+}
+
+/** The operator-facing sentence, or undefined when there is nothing to say.
+ *  Shared so `doctor` and `status` cannot word the same fact differently. */
+export function spendTelemetryDetail(verdict: SpendTelemetryVerdict): string | undefined {
+  switch (verdict.kind) {
+    case "absent":
+      return (
+        `the last ${verdict.worked} completed runs that did any work all recorded $0.00 spend` +
+        " — the USD cap cannot fire on zeros, and $0.00 is not proof of no spend"
+      );
+    case "partial":
+      return (
+        `${verdict.missing} of the last ${verdict.worked} completed runs that did any work recorded ` +
+        "$0.00 spend — the USD cap is comparing a fraction of actual spend against its ceiling"
+      );
+    case "healthy":
+    case "insufficient":
+      return undefined;
+  }
+}

package/src/stats.ts

@@ -19,6 +19,7 @@
  * counted separately as **unmetered** and never averaged into a per-issue cost.
  */
 
+import { utcDay } from "./store.ts";
 import type { RunRecord } from "./types.ts";
 
 /** The bounded window a report answers over. Day keys are UTC (`YYYY-MM-DD`). */
@@ -181,6 +182,40 @@ function summarize(args: {
  * settled there. Rows within an issue must be ordered by `startedAt`, so the
  * first row of a chain is its first queue-label claim.
  */
+/** `7d` / `30d` / any positive whole-day duration. */
+const DURATION_FORM = /^(\d+)d$/;
+/** A bare UTC date: the window starts at 00:00:00Z that day. */
+const DATE_FORM = /^\d{4}-\d{2}-\d{2}$/;
+const DAY_MS = 86_400_000;
+
+/**
+ * `--since` (or `?since=`) to a full window, or `undefined` when it is not one.
+ *
+ * Here rather than in the CLI because the dashboard needs the identical parse
+ * (#297): two parsers would eventually disagree about what `30d` means, and the
+ * page's numbers are supposed to equal `stats --json` for the same window. The
+ * CLI turns `undefined` into its exit-2 message and the endpoint turns it into a
+ * 400 — neither silently defaults a typo'd window, because measuring the wrong
+ * week and saying nothing is the failure this shape prevents.
+ */
+export function parseStatsWindow(raw: string, now: number): StatsWindow | undefined {
+  const until = { untilEpochMs: now, untilDay: utcDay(now) };
+  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), ...until };
+    }
+    return undefined;
+  }
+  if (DATE_FORM.test(raw)) {
+    const sinceEpochMs = Date.parse(`${raw}T00:00:00Z`);
+    if (Number.isFinite(sinceEpochMs)) return { sinceEpochMs, sinceDay: raw, ...until };
+  }
+  return undefined;
+}
+
 export function computeStats(args: {
   project: string;
   window: StatsWindow;