tumwater 0.2.0 → 0.4.0

package/dist/src/report/report-render.js

@@ -1,12 +1,13 @@
 import { addTo, rankCountEntries, sortByValueDesc } from "../collections.js";
 import { compactTokens, usd } from "../text/format.js";
 import { durationLabel } from "../cli/cli-args.js";
-import { monthDay, reportWindow, sinceWindowLine } from "../text/datetime.js";
+import { boundedWindowLine, monthDay, reportWindow, sinceWindowLine } from "../text/datetime.js";
 import { eventsRotationLabel } from "../events/events.js";
 import { SPARSE_WINDOW_NOTE } from "../events/event-window.js";
 import { shortSpanPhrase } from "../text/phrases.js";
 import { markdownTable } from "../text/markdown.js";
-import { baseRoleOf } from "../roles/loop-ids.js";
+import { baseRoleOf } from "../roles/runner-ids.js";
+import { backendDisplayName } from "../agent/backend-traits.js";
 /** Bar width for one day: up to 20 blocks scaled to the window's max tokensOut —
  * round(20·v/max), min 1 when v > 0. */
 function barWidth(v, max) {
@@ -37,18 +38,37 @@ function rankedRoleTotals(series, pick) {
 function rankedRoleLine(label, pairs, fmt) {
     return `**${label}:** ${pairs.length === 0 ? "-" : pairs.map(([r, n]) => `${r} — ${fmt(n)}`).join(" · ")}`;
 }
-/** The per-day-median line of the team day report — "MMM D <span>" cells for each day that
+/** Push one "**Label:** …" ranked-role line, dropping roles with a non-positive value (zero
+ * count/spend) before rendering, so an all-zero window still renders "-" exactly like the
+ * unfiltered lines. fmt formats each role's number (default String for count lines; pass
+ * usd/compactTokens for spend/token lines). All the "X by role" lines share this filter-rule
+ * home so the zero-means-render-dash guard cannot drift between the --since and day renders. */
+function pushRankedRoleLine(lines, label, pairs, fmt = String) {
+    lines.push(rankedRoleLine(label, pairs.filter(([, n]) => n > 0), fmt));
+}
+/** The per-day cameo line of the team day report — "MMM D <cell>" cells for each day that
  * carries a value, joined under a bold title, or undefined when no day has one (zero means
- * absent). The one home of that cameo rendering, shared by the merge check-time and merge-wait
- * medians so their date+span cells and title line cannot drift; the planned provider-slot wait
- * median is a third caller of the same rule. */
-function medianLine(series, title, pick) {
+ * absent). The one home of that cameo rendering, shared by the per-day medians, the red-check
+ * count and the main-red wall-clock lines so their date+cell shape and title line cannot drift.
+ * Each caller supplies its own cell formatter (shortSpanPhrase for the medians, `×n` for the
+ * red-check count, durationLabel for the main-red span). */
+function dayCameoLine(series, title, pick, fmt = shortSpanPhrase) {
     const cells = series.flatMap((d) => {
         const v = pick(d);
-        return v === undefined ? [] : [`${monthDay(d.date)} ${shortSpanPhrase(v)}`];
+        return v === undefined ? [] : [`${monthDay(d.date)} ${fmt(v)}`];
     });
     return cells.length > 0 ? `**${title}:** ${cells.join(" · ")}` : undefined;
 }
+/** Push a day-cameo line onto `lines` only when some day carries a value — the “compute a
+ * cameo line, push it when present” boilerplate every per-day cell repeats. Renders via
+ * dayCameoLine (the one cameo shape), so the date+cell shape and title line cannot drift.
+ * Zero-means-absent: a day whose field is undefined renders no cell, and a series with no such
+ * day pushes no line. */
+function pushDayCameoLine(lines, series, title, pick, fmt = shortSpanPhrase) {
+    const line = dayCameoLine(series, title, pick, fmt);
+    if (line !== undefined)
+        lines.push(line);
+}
 /** Push the `Cost by provider` and `Estimated by provider` lines of the per-provider spend
  * breakdown (plans: per-provider spend), from the caller's already-ranked real- and notional-
  * spend pairs. Role scoping is the caller's `role === undefined` gate — this helper only
@@ -80,13 +100,38 @@ function mergeShareLine(t) {
     const failed = (t.mergeFailed ?? 0) > 0 ? ` (${t.mergeFailed} failed)` : "";
     return `of which merge runs: ${t.mergeRuns} runs${failed} · ${compactTokens(t.mergeTokens)} tokens · ${usd(t.mergeCostUsd)} (reviewer + conflict resolution)`;
 }
-/** The notional-spend line (plans/agent-backends.md part 6a): the API-equivalent cost of
- * claude.ai subscription runs folded into the window. Never part of the totals' costUsd,
- * because a subscription run is exempt from the daily dollar cap; the caller prints it only
- * when a subscription run actually folded in (zero means absent, like the merge line), so
- * an API-only team's report is unchanged. */
-function notionalLine(t) {
-    return `claude subscription, API-equivalent: ${usd(t.notionalCostUsd ?? 0)} estimated`;
+/** A float-robust "the per-backend notional sums account for the window's total" check: the two
+ * numbers fold in different orders (per-event vs per-backend-then-summed), so their float traces
+ * need not coincide exactly even when every subscription event is attributed — the gap lands
+ * around machine epsilon. A small relative slack absorbs that reordering noise, while a genuinely
+ * partial map (an unattributed subscription merge, or a legacy event with no agent) is off by a
+ * real, much larger amount and must fall back to the generic line. */
+function notionalSumsCoverTotal(summed, total) {
+    return Math.abs(summed - total) <= 1e-9 * Math.max(1, Math.abs(total));
+}
+/** The notional-spend line(s) (plans/agent-backends.md part 6a, codex-backend.md part 3d/9):
+ * the API-equivalent cost of subscription runs folded into the window. Never part of the
+ * totals' costUsd, because a subscription run is exempt from the daily dollar cap; the caller
+ * prints it only when a subscription run actually folded in (zero means absent, like the merge
+ * line), so an API-only team's report is unchanged. When the window's notional spend fully
+ * decomposes into backends, one labeled line names each backend — including a single non-claude
+ * backend (a codex-only window), so a codex team's line never reads "claude". A claude-only
+ * account, an old-log window, or unattributed merge spend keeps one generic lowercase "claude
+ * subscription" line — byte-identical to the pre-codex render. */
+function notionalLines(t) {
+    const total = t.notionalCostUsd ?? 0;
+    const byBackend = t.notionalByBackend ?? {};
+    const backends = Object.entries(byBackend).filter(([, c]) => c > 0);
+    const summed = backends.reduce((n, [, c]) => n + c, 0);
+    // A single fully-attributed claude account collapses to the generic line (its true or
+    // fallback backend is claude, and the capitalization keeps old/byte-identical output);
+    // every other fully-attributed window — multi-backend, or a single codex/other backend —
+    // names each backend on its own line.
+    const singleClaude = backends.length === 1 && backends[0]?.[0] === "claude";
+    if (notionalSumsCoverTotal(summed, total) && !singleClaude) {
+        return backends.map(([backend, c]) => `${backendDisplayName(backend)} subscription, API-equivalent: ${usd(c)} estimated`);
+    }
+    return [`claude subscription, API-equivalent: ${usd(total)} estimated`];
 }
 /** The scope note a `--role` report prints: merge runs belong to the merge slot and the
  * day-granular backlog tallies (features done / bugs fixed / plans added / bugs filed) come
@@ -104,7 +149,7 @@ function pushReportSummary(lines, t, tail = "", scoped = false) {
     if (t.mergeRuns > 0)
         lines.push(mergeShareLine(t));
     if ((t.notionalCostUsd ?? 0) > 0)
-        lines.push(notionalLine(t));
+        lines.push(...notionalLines(t));
     if (scoped)
         lines.push(ROLE_SCOPE_NOTE);
 }
@@ -116,7 +161,9 @@ export function renderSinceReportMarkdown(data) {
     const lines = [];
     lines.push("# tumwater usage report");
     lines.push("");
-    lines.push(sinceWindowLine(durationLabel(data.sinceMs), data.fromIso));
+    lines.push(data.untilMs !== undefined && data.toIso !== undefined
+        ? boundedWindowLine(durationLabel(data.sinceMs), durationLabel(data.untilMs), data.fromIso, data.toIso)
+        : sinceWindowLine(durationLabel(data.sinceMs), data.fromIso));
     if (data.role !== undefined)
         lines.push(`role: ${data.role}`);
     lines.push("");
@@ -131,10 +178,10 @@ export function renderSinceReportMarkdown(data) {
     // omitted — an all-zero window renders "-" like the other lines. Output tokens are the
     // resource the budget charges, so this is the line an operator reads to find which role's
     // prompt loop burned the window's tokens.
-    lines.push(rankedRoleLine("Tokens by role", rankedRoleMap(data.tokensByRole).filter(([, n]) => n > 0), compactTokens));
+    pushRankedRoleLine(lines, "Tokens by role", rankedRoleMap(data.tokensByRole), compactTokens);
     // Same breakdown for spend: ranked by spend desc then name asc, zero-spend roles omitted —
-    // an all-zero window renders "-" like the ticks line.
-    lines.push(rankedRoleLine("Cost by role", rankedRoleMap(data.costByRole).filter(([, c]) => c > 0), usd));
+    // an all-zero window renders "-" like the runs line.
+    pushRankedRoleLine(lines, "Cost by role", rankedRoleMap(data.costByRole), usd);
     // The same breakdown per PROVIDER (plans: per-provider spend), gated to the team report
     // like its day sibling. SinceReport.costByProvider is always present (empty when none), so
     // the zero-means-absent gate prints no line for a window with no provider spend.
@@ -150,19 +197,26 @@ export function renderSinceReportMarkdown(data) {
         if (modelPairs.length > 0)
             lines.push(rankedRoleLine("Runs by model", modelPairs, String));
     }
+    // Main's red wall-clock over the window (main's own, not any role's — a role-scoped
+    // collector carries 0, so this never prints for a scoped window). Zero-absent: no line for
+    // a window main was never red.
+    if (data.mainRedMs > 0)
+        lines.push(`**Main red:** ${durationLabel(data.mainRedMs)}`);
     // The same breakdown for review friction: rejections per role from review_rejected events;
-    // a window with none renders "-" like the other lines.
-    lines.push(rankedRoleLine("Rejections by role", rankedRoleMap(data.rejectionsByRole).filter(([, r]) => r > 0), String));
-    lines.push(rankedRoleLine("Revisions by role", rankedRoleMap(data.revisionsByRole).filter(([, r]) => r > 0), String));
-    lines.push(rankedRoleLine("Refusals by role", rankedRoleMap(data.refusalsByRole).filter(([, r]) => r > 0), String));
+    // a window with none renders "-" like the other lines. The post-merge line is the
+    // afterMerge: true subset — rejections that reached an already-merged commit.
+    pushRankedRoleLine(lines, "Rejections by role", rankedRoleMap(data.rejectionsByRole));
+    pushRankedRoleLine(lines, "Post-merge rejections by role", rankedRoleMap(data.postMergeRejectionsByRole));
+    pushRankedRoleLine(lines, "Revisions by role", rankedRoleMap(data.revisionsByRole));
+    pushRankedRoleLine(lines, "Refusals by role", rankedRoleMap(data.refusalsByRole));
     // The same breakdown for outright failures: error-class run_ends per role under the
-    // digest's OUTCOME_CLASS — the ticks that burned agent time and merged nothing without
+    // digest's OUTCOME_CLASS — the runs that burned agent time and merged nothing without
     // going through review, which rejections/revisions would miss entirely. A window with
     // none renders "-" like the other lines.
-    lines.push(rankedRoleLine("Failed runs by role", rankedRoleMap(data.failedRunsByRole).filter(([, n]) => n > 0), String));
-    lines.push(rankedRoleLine("Fallbacks by role", rankedRoleMap(data.fallbacksByRole).filter(([, n]) => n > 0), String));
-    lines.push(rankedRoleLine("Image reroutes by role", rankedRoleMap(data.imageReroutesByRole).filter(([, n]) => n > 0), String));
-    // Deferred maintenance ticks per reason code, the --since twin of the day render's line:
+    pushRankedRoleLine(lines, "Failed runs by role", rankedRoleMap(data.failedRunsByRole));
+    pushRankedRoleLine(lines, "Fallbacks by role", rankedRoleMap(data.fallbacksByRole));
+    pushRankedRoleLine(lines, "Image reroutes by role", rankedRoleMap(data.imageReroutesByRole));
+    // Deferred maintenance runs per reason code, the --since twin of the day render's line:
     // how many due maintenance runs stood down and why (backlog / no-work / plans-full).
     // Gated to the team report — a reason is not a role, so a role-scoped window omits it.
     // Zero-means-absent: a window with no deferral prints no line.
@@ -195,7 +249,7 @@ export function renderSinceReportMarkdown(data) {
     // Subscription spend is notional: its own line, only when the window has any — the same
     // conditional/filtered `usd` form the day render's "Estimated by role" uses.
     if (data.notionalByRole !== undefined) {
-        lines.push(rankedRoleLine("Estimated by role", rankedRoleMap(data.notionalByRole).filter(([, c]) => c > 0), usd));
+        pushRankedRoleLine(lines, "Estimated by role", rankedRoleMap(data.notionalByRole), usd);
     }
     lines.push("");
     // Exactly one final line, chosen by the collector's coverage proof: either a hedged note
@@ -211,12 +265,12 @@ export function renderSinceReportMarkdown(data) {
         lines.push("backlog tallies (features done / bugs fixed / plans added / bugs filed) need the day report (--days)");
     return lines.join("\n");
 }
-/** Cost per merged commit by base role. Spend comes from costByRole (keyed by loop id, folded to
+/** Cost per merged commit by base role. Spend comes from costByRole (keyed by role id, folded to
  * its base role so `feature-2` joins `feature`), commits from commitsByRole (already base-role
  * keyed). `merged` is [role, cost per commit, commits] for roles with both, ranked by cost per
  * commit desc then name asc; `idle` is roles that spent and merged nothing, ranked by spend.
  * Merge spend (the reviewer's) and notional subscription spend stay out by default, matching
- * `**Cost by role:**` (`pick` selects another per-loop-id spend map, e.g. notionalByRole); a
+ * `**Cost by role:**` (`pick` selects another per-role-id spend map, e.g. notionalByRole); a
  * role with commits but no spend in the picked map appears in neither list. */
 function costPerCommitPairs(series, pick = (d) => d.costByRole) {
     const cost = {};
@@ -273,22 +327,22 @@ export function renderReportMarkdown(data) {
     lines.push("");
     const maxTokens = data.series.reduce((m, d) => Math.max(m, d.tokensOut), 0);
     lines.push(...markdownTable(["day", "tokens out", "runs", "commits", "cost"], data.series.map((d) => {
-        const ticks = Object.values(d.runsByRole).reduce((a, b) => a + b, 0);
+        const runs = Object.values(d.runsByRole).reduce((a, b) => a + b, 0);
         const w = maxTokens > 0 ? barWidth(d.tokensOut, maxTokens) : 0;
         const bar = w > 0 ? ` ${"█".repeat(w)}` : ""; // Zero days carry no bar (and no stray space).
-        return [monthDay(d.date), `${compactTokens(d.tokensOut)}${bar}`, String(ticks), String(d.commits), usd(d.costUsd)];
+        return [monthDay(d.date), `${compactTokens(d.tokensOut)}${bar}`, String(runs), String(d.commits), usd(d.costUsd)];
     }), ["left", "right", "right", "right", "right"]));
     lines.push("");
     lines.push(rankedRoleLine("Runs by role", rankedRoleTotals(data.series, (d) => d.runsByRole), String));
     // The same breakdown for output tokens (the resource the budget charges): window totals per
-    // role from tokensByRole, ranked like the ticks line. Zero-token roles are omitted; an
-    // all-zero window renders "-" like the ticks line.
-    lines.push(rankedRoleLine("Tokens by role", rankedRoleTotals(data.series, (d) => d.tokensByRole ?? {}).filter(([, n]) => n > 0), compactTokens));
+    // role from tokensByRole, ranked like the runs line. Zero-token roles are omitted; an
+    // all-zero window renders "-" like the runs line.
+    pushRankedRoleLine(lines, "Tokens by role", rankedRoleTotals(data.series, (d) => d.tokensByRole ?? {}), compactTokens);
     // The same breakdown for spend: window totals per role from costByRole, ranked by spend
     // desc then name asc — spend is what the operator acts on (an operator tuning per-role
-    // intervals wants the burning loop first, not the busiest one). Zero-spend roles are
-    // omitted; an all-zero window renders "-" like the ticks line.
-    lines.push(rankedRoleLine("Cost by role", rankedRoleTotals(data.series, (d) => d.costByRole).filter(([, c]) => c > 0), usd));
+    // intervals wants the burning role first, not the busiest one). Zero-spend roles are
+    // omitted; an all-zero window renders "-" like the runs line.
+    pushRankedRoleLine(lines, "Cost by role", rankedRoleTotals(data.series, (d) => d.costByRole), usd);
     // The same breakdown per PROVIDER (plans: per-provider spend): which seam of a mixed team
     // spent what, straight from the events' providerCost maps (run_end's own runs and the
     // merge's reviewer seam). Gated to the team report — a provider is not a role, so a
@@ -308,18 +362,20 @@ export function renderReportMarkdown(data) {
             lines.push(rankedRoleLine("Runs by model", modelPairs, String));
     }
     // The same breakdown for review friction: window rejections per role from review_rejected
-    // events, ranked like the ticks line; a window with none renders "-".
-    lines.push(rankedRoleLine("Rejections by role", rankedRoleTotals(data.series, (d) => d.rejectionsByRole ?? {}).filter(([, r]) => r > 0), String));
-    lines.push(rankedRoleLine("Revisions by role", rankedRoleTotals(data.series, (d) => d.revisionsByRole ?? {}).filter(([, r]) => r > 0), String));
-    lines.push(rankedRoleLine("Refusals by role", rankedRoleTotals(data.series, (d) => d.refusalsByRole ?? {}).filter(([, r]) => r > 0), String));
+    // events, ranked like the runs line; a window with none renders "-". The post-merge line
+    // is the afterMerge: true subset — rejections that reached an already-merged commit.
+    pushRankedRoleLine(lines, "Rejections by role", rankedRoleTotals(data.series, (d) => d.rejectionsByRole ?? {}));
+    pushRankedRoleLine(lines, "Post-merge rejections by role", rankedRoleTotals(data.series, (d) => d.postMergeRejectionsByRole ?? {}));
+    pushRankedRoleLine(lines, "Revisions by role", rankedRoleTotals(data.series, (d) => d.revisionsByRole ?? {}));
+    pushRankedRoleLine(lines, "Refusals by role", rankedRoleTotals(data.series, (d) => d.refusalsByRole ?? {}));
     // The same breakdown for outright failures: error-class run_ends per role under the
-    // digest's OUTCOME_CLASS — ticks that burned agent time and merged nothing without going
+    // digest's OUTCOME_CLASS — runs that burned agent time and merged nothing without going
     // through review, which rejections/revisions would miss entirely. Zero-means-absent, so a
     // failure-free window renders no line and an all-zero window renders "-" like the others.
-    lines.push(rankedRoleLine("Failed runs by role", rankedRoleTotals(data.series, (d) => d.failedRunsByRole ?? {}).filter(([, n]) => n > 0), String));
-    lines.push(rankedRoleLine("Fallbacks by role", rankedRoleTotals(data.series, (d) => d.fallbacksByRole ?? {}).filter(([, n]) => n > 0), String));
-    lines.push(rankedRoleLine("Image reroutes by role", rankedRoleTotals(data.series, (d) => d.imageReroutesByRole ?? {}).filter(([, n]) => n > 0), String));
-    // Deferred maintenance ticks per reason code — how many due maintenance runs stood down
+    pushRankedRoleLine(lines, "Failed runs by role", rankedRoleTotals(data.series, (d) => d.failedRunsByRole ?? {}));
+    pushRankedRoleLine(lines, "Fallbacks by role", rankedRoleTotals(data.series, (d) => d.fallbacksByRole ?? {}));
+    pushRankedRoleLine(lines, "Image reroutes by role", rankedRoleTotals(data.series, (d) => d.imageReroutesByRole ?? {}));
+    // Deferred maintenance runs per reason code — how many due maintenance runs stood down
     // and why, so an idle day reads as backlog-open / no-work / plans-full rather than blank,
     // the per-role breakdown of the deferred maintenances. Gated to the team report — a
     // reason is not a role (ROLE_SCOPE_NOTE covers the omission). Zero-means-absent: a window
@@ -352,29 +408,32 @@ export function renderReportMarkdown(data) {
             lines.push(rankedRoleLine("Merge failures by reason", mergeFailureReasons, String));
         // Per-day median passing check time, so a suite slowing over days shows; days without a
         // check are left out, and no line prints when no day has one (zero means absent).
-        const medians = medianLine(data.series, "Merge check median", (d) => d.checkMedianMs);
-        if (medians !== undefined)
-            lines.push(medians);
+        pushDayCameoLine(lines, data.series, "Merge check median", (d) => d.checkMedianMs);
         // Per-day count of red full-suite checks, beside the passing medians above; a day whose
         // suite went red before passing shows here. Zero-absent: no line when no day fails.
-        const reds = data.series.flatMap((d) => d.checkFailures === undefined ? [] : [`${monthDay(d.date)} ×${d.checkFailures}`]);
-        if (reds.length > 0)
-            lines.push(`**Red merge checks:** ${reds.join(" · ")}`);
-        const waits = medianLine(data.series, "Merge wait median", (d) => d.mergeWaitMedianMs);
-        if (waits !== undefined)
-            lines.push(waits);
-        const providerWaits = medianLine(data.series, "Provider wait median", (d) => d.providerWaitMedianMs);
-        if (providerWaits !== undefined)
-            lines.push(providerWaits);
-        const slotWaits = medianLine(data.series, "Workspace wait median", (d) => d.slotWaitMedianMs);
-        if (slotWaits !== undefined)
-            lines.push(slotWaits);
+        pushDayCameoLine(lines, data.series, "Red merge checks", (d) => d.checkFailures, (n) => `×${n}`);
+        // Per-day main red wall-clock, beside the red-check counts above: how long each day main
+        // had no passing full check (the span every code role was held). Team-only (main's own
+        // red time, not any role's) and zero-absent: no line when no day was red.
+        pushDayCameoLine(lines, data.series, "Main red", (d) => d.mainRedMs, durationLabel);
+        pushDayCameoLine(lines, data.series, "Merge wait median", (d) => d.mergeWaitMedianMs);
+        // How long the merge slot itself held each change it landed, beside the merge-wait median:
+        // the queue backlog (merge wait minus slot time) apart from the slot's own review/check/
+        // rebase/merge work. Team-only (the slot is the team's), omitted when no day carries one.
+        pushDayCameoLine(lines, data.series, "Merge slot median", (d) => d.mergeSlotMedianMs);
+        pushDayCameoLine(lines, data.series, "Run duration median", (d) => d.runMedianMs);
+        // How long the review gate ran per day — how long the reviewer's verdict run(s) took —
+        // beside the run/merge-wait medians; pushDayCameoLine omits the line when no day carries one.
+        pushDayCameoLine(lines, data.series, "Review duration median", (d) => d.reviewMedianMs);
+        pushDayCameoLine(lines, data.series, "Provider wait median", (d) => d.providerWaitMedianMs);
+        pushDayCameoLine(lines, data.series, "Workspace wait median", (d) => d.slotWaitMedianMs);
+        pushDayCameoLine(lines, data.series, "Check wait median", (d) => d.checkWaitMedianMs);
     }
     lines.push(costPerCommitLine("Cost per commit", costPerCommitPairs(data.series)));
     // Subscription spend is notional: its own two lines, only when the window has any.
     if ((t.notionalCostUsd ?? 0) > 0) {
         const notionalOf = (d) => d.notionalByRole ?? {};
-        lines.push(rankedRoleLine("Estimated by role", rankedRoleTotals(data.series, notionalOf).filter(([, c]) => c > 0), usd));
+        pushRankedRoleLine(lines, "Estimated by role", rankedRoleTotals(data.series, notionalOf), usd);
         lines.push(costPerCommitLine("Estimated per commit", costPerCommitPairs(data.series, notionalOf)));
     }
     // Commits per backlog item is day-granular backlog data (features done + bugs fixed), so it
@@ -382,6 +441,18 @@ export function renderReportMarkdown(data) {
     const items = t.featuresDone + t.bugsFixed;
     const perItem = items > 0 ? ` · ${(t.commits / items).toFixed(1)} commits per backlog item` : "";
     lines.push(`**Commits:** ${t.workCommits ?? 0} work / ${t.maintenanceCommits ?? 0} maintenance${perItem}`);
+    // How long each finished plan or bug waited from filing to done, per completion day — the
+    // median backlog age at which the day's items closed. Team-only (a lag has no role) and
+    // zero-means-absent: no line when no day carries one. Values are whole days from
+    // daysBetween, so a plain `${n}d` is exact where medianLine's shortSpanPhrase would print
+    // minutes.
+    if (data.role === undefined) {
+        const lags = data.series.flatMap((d) => d.backlogLagMedianDays === undefined
+            ? []
+            : [`${monthDay(d.date)} ${d.backlogLagMedianDays}d`]);
+        if (lags.length > 0)
+            lines.push(`**Backlog lag median:** ${lags.join(" · ")}`);
+    }
     // Where the bugfix work was hardest to confirm: the window's fixed bugs tallied by their
     // `Validation gap` tag, so the team can see where its own test infrastructure was weakest
     // (recorded first, consumed now). Team-only (a tag has no role) and zero-means-absent: no

package/dist/src/report/report-types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/report/report.js

@@ -6,28 +6,38 @@ import { collectReport, collectReportSince } from "./report-data.js";
 import { collectFailureReport, collectFailureReportSince } from "../failure/failure-data.js";
 import { renderFailureMarkdown } from "../failure/failure-render.js";
 import { renderReportMarkdown, renderSinceReportMarkdown } from "./report-render.js";
-import { say, sayJson, sayJsonOrRender } from "../cli/cli-output.js";
-import { failRivalShapes, flagValue, parseCountFlag, parseRoleScope, parseSinceFlag } from "../cli/cli-args.js";
+import { fail, say, sayJson, sayJsonOrRender } from "../cli/cli-output.js";
+import { followView } from "../cli/follow-view.js";
+import { failRivalShapes, failUntilShorterThanSince, flagValue, parseCountFlag, parseRoleListScope, parseSinceFlag } from "../cli/cli-args.js";
+import { hasFollowFlag } from "../cli/cli-flag-specs.js";
 import { REPORT_DEFAULT_DAYS, REPORT_MAX_DAYS, REPORT_SINCE_MAX_MS } from "../events/event-window.js";
-/** `tumwater report [--days <n>] [--failures] [--since <duration>]`: parse the flags and
+/** `tumwater report [--days <n>] [--failures] [--since <duration>]
+ * [--until <duration>]`: parse the flags and
  * print. Unknown-args rejection and the no-ready-repo-gate decision stay in cli.ts's case,
  * like every other command's. */
-export async function cmdReport(root, args) {
+export async function cmdReport(root, args, seams = {}) {
     // --since is handled before the day-shape reads: it is a rival shape (totals over a
     // trailing window vs a series over whole days), not a modifier of either.
     const ms = parseSinceFlag(args, "report --since", REPORT_SINCE_MAX_MS);
+    const untilMs = parseSinceFlag(args, "report --until", REPORT_SINCE_MAX_MS, "--until");
+    failUntilShorterThanSince("report", untilMs, ms);
     // --role scopes both report shapes: the usage report (day and --since) and the failure
-    // digest, whose day and --since collectors take the same optional base role.
-    const role = parseRoleScope(root, args);
+    // digest, whose day and --since collectors take the same optional list of base roles.
+    const role = parseRoleListScope(root, args);
+    const follow = hasFollowFlag(args);
+    if (follow && args.includes("--json"))
+        fail("report --json prints one document; -f/--follow repaints a live view — drop one of them");
     if (ms !== null) {
         // --days is still a rival shape: it counts whole local days, while --since totals a trailing
         // window. --failures is not a rival anymore — the digest has a windowed-since collector that
         // reuses the day digest's own sections, so `report --failures --since <d>` dispatches it
-        // through the existing --json / render choice.
+        // through the existing --json / render choice; --until bounds its window's end.
+        if (follow)
+            failRivalShapes("report --since", "-f/--follow", 'follow means "from now on"; --since shows a bounded past window');
         if (args.includes("--days"))
             failRivalShapes("report --since", "--days", "--days counts whole local days; --since totals a trailing window");
         if (args.includes("--failures")) {
-            const digest = collectFailureReportSince(root, ms, role ?? undefined);
+            const digest = collectFailureReportSince(root, ms, role ?? undefined, untilMs ?? undefined);
             if (args.includes("--json"))
                 sayJson(digest);
             else
@@ -36,7 +46,7 @@ export async function cmdReport(root, args) {
         }
         // --json swaps the renderer for the collector's own payload, exactly as status --json
         // does: bounds and cap checks above are shared, only the printing differs.
-        const since = collectReportSince(root, ms, role ?? undefined);
+        const since = collectReportSince(root, ms, role ?? undefined, untilMs ?? undefined);
         sayJsonOrRender(args, since, renderSinceReportMarkdown);
         return;
     }
@@ -54,6 +64,10 @@ export async function cmdReport(root, args) {
     // report --json and doctor --json precedent: the time-and-spend fold gave the digest a
     // stable data shape, so the machine-readable form is the data itself, not a re-parse of the
     // Markdown (the old "clustered narrative with no agreed shape" refusal is retired).
+    if (follow) {
+        await followView(() => args.includes("--failures") ? renderFailureMarkdown(collectFailureReport(root, days, role ?? undefined)) : renderReportMarkdown(collectReport(root, days, role ?? undefined)), seams);
+        return;
+    }
     if (args.includes("--failures") && args.includes("--json")) {
         sayJson(collectFailureReport(root, days, role ?? undefined));
         return;

package/dist/src/request-timeouts.js

@@ -1,6 +1,6 @@
-export function cappedRequestTimeouts(cfg, tickCapS, quietCapS) {
+export function cappedRequestTimeouts(cfg, runCapS, quietCapS) {
     return {
-        runTimeoutSeconds: Math.min(cfg.runTimeoutSeconds, tickCapS),
+        runTimeoutSeconds: Math.min(cfg.runTimeoutSeconds, runCapS),
         quietTimeoutSeconds: cfg.quietTimeoutSeconds > 0 ? Math.min(cfg.quietTimeoutSeconds, quietCapS) : quietCapS,
     };
 }

package/dist/src/review/diff-rules.js

@@ -0,0 +1,53 @@
+/** The review gate's five deterministic diff rules, in the gate's own order and scope — the one
+ * call site both the gate (review.ts) and the main watch (main-watch.ts) use, so a finding reads
+ * the same on a changed tree and on main's tip. `baseRev` is a commit or branch name the async
+ * rules resolve with changeBaseRev (merge-base of HEAD and it), so the watch passes a commit
+ * while the gate passes the main branch. Runs conflictMarkerReason, then protectedEditReason,
+ * then secretLeakReason, then — only for an exempt (md-only) diff — falseFixReason, then
+ * backlogStructureReason for every diff, short-circuiting on the first finding exactly as the
+ * original gate did: a later rule never runs once an earlier one already rejects. Returns a
+ * one-reason array when a rule fires (the reason the gate rejects on and the watch reports) and
+ * `[]` when nothing is wrong. An empty `role` (the watch cannot name the tip's merging role) is
+ * no basis for calling a PRINCIPLES.md edit unauthorized, so the role-dependent half of the
+ * protected-edit rule is skipped — but its role-independent half, the brief-block rule
+ * (briefEditReason), still runs, so a brief edit on an unattributed head is still reported; the
+ * gate always passes a known role, so its rejections are unchanged.
+ *
+ * This module lives apart from review-precheck.ts so the main watch can share the rules without a
+ * runtime import cycle: review-precheck.ts imports src/baseline/main-watch.ts
+ * (onlyKnownMainFailures), so a main-watch -> review-precheck import edge would make the two
+ * modules mutually depend on each other at runtime (docs/code-metrics.md records "no runtime
+ * import cycles"). diff-rules.ts's own imports (merge-git, protected-edits, secret-leaks,
+ * fix-claim, backlog-structure) import nothing from main-watch or review-precheck, so it is a
+ * cycle-free home both consumers can import. */
+import { conflictMarkerReason } from "../merge/merge-git.js";
+import { briefEditReason, protectedEditReason } from "./protected-edits.js";
+import { secretLeakReason } from "./secret-leaks.js";
+import { falseFixReason } from "../verdict/fix-claim.js";
+import { backlogStructureReason } from "../backlog/backlog-structure.js";
+export async function diffRuleReasons(wt, baseRev, files, role, exempt) {
+    const marker = conflictMarkerReason(wt, files);
+    if (marker !== undefined)
+        return [marker];
+    // The brief-block rule is role-independent — its edit is forbidden for every role alike — so it
+    // runs even when the watch cannot name the tip's merging role (role === ""). Only the
+    // PRINCIPLES.md half of protectedEditReason needs a known role to condemn an edit.
+    const briefReason = await briefEditReason(wt, baseRev, files);
+    if (briefReason !== undefined)
+        return [briefReason];
+    const protectedReason = role === "" ? undefined : await protectedEditReason(wt, baseRev, files, role);
+    if (protectedReason !== undefined)
+        return [protectedReason];
+    const secretReason = await secretLeakReason(wt, baseRev, files);
+    if (secretReason !== undefined)
+        return [secretReason];
+    if (exempt) {
+        const falseFix = await falseFixReason(wt, baseRev, files);
+        if (falseFix)
+            return [falseFix];
+    }
+    const structure = await backlogStructureReason(wt, baseRev, files);
+    if (structure)
+        return [structure];
+    return [];
+}

package/dist/src/review/known-flakes.js

@@ -9,15 +9,24 @@
  * repeat. Only the gate's positive flake record is trusted: a check-failure rejection is not
  * evidence of flakiness — it is exactly the attribution this memory exists to avoid making
  * twice. */
+import { DAY_MS } from "../text/datetime.js";
+import { TUMWATER_SOURCE, tryOrWarn } from "../events/events.js";
 import { readEventsSince } from "../events/event-window.js";
 import { increment } from "../collections.js";
 import { normalizeClusterKey } from "../failure/failure-cluster.js";
+import { FAILING_TESTS_MAX } from "../build/build-check-report.js";
+import { readJsonFile, writeJsonAtomic } from "../files/json-files.js";
+import { isJsonObject } from "../files/json-object.js";
+import { parseEntryDetails } from "../backlog/backlog-md.js";
+import { readTextOrNull } from "../files/files.js";
+import { quarantinePath } from "../paths.js";
+import path from "node:path";
 /** How far back the gate looks for its own flake warnings. One local day: the example in
  * BUGS.md 2026-10-06 recorded a flake at 10:50 and rejected an unrelated change on the same
  * headline at 15:57, and a day is short enough that a retired flake stops excusing failures
  * while still covering a team's working span. Exported so the doctor's `flaky checks` check
  * and the gate share the one window and cannot drift. */
-export const KNOWN_FLAKE_WINDOW_MS = 24 * 60 * 60 * 1000;
+export const KNOWN_FLAKE_WINDOW_MS = DAY_MS;
 /** The exact prefix review-precheck.ts writes before a flake's failure headline. Exported so
  * the writer and reader cannot drift over the separator. */
 export const FLAKY_WARNING_PREFIX = "gate check failed then passed on retry — flaky: ";
@@ -53,6 +62,18 @@ export function flakeCounts(events) {
         increment(counts, key);
     return [...counts.entries()].sort((a, b) => b[1] - a[1]);
 }
+/** The bar at which a normalized check counts as flapping: one warning in the window is a
+ * routine one-off the gate's single re-run already absorbed, while two means the check flapped
+ * again and pays that re-run on every merge it touches — the one threshold the doctor's `flaky
+ * checks` row and the always-on flapped-checks alert share, folded through
+ * repeatedFlakeCounts. */
+const FLAKE_REPEAT_WARN = 2;
+/** The normalized checks in `events` that flapped at least FLAKE_REPEAT_WARN times, most
+ * frequent first — the filter flakeCounts feeds both the doctor and the status alert, so the
+ * threshold lives in the one home. Pure. */
+export function repeatedFlakeCounts(events) {
+    return flakeCounts(events).filter(([, n]) => n >= FLAKE_REPEAT_WARN);
+}
 /** A Set of the flakeWarningKeys at or after `now - windowMs` of the gate's own window. */
 export function flakeKeys(events, now, windowMs = KNOWN_FLAKE_WINDOW_MS) {
     return new Set(flakeWarningKeys(events, now - windowMs));
@@ -63,3 +84,93 @@ export function isKnownFlake(root, headline) {
     const { events } = readEventsSince(root, KNOWN_FLAKE_WINDOW_MS);
     return flakeKeys(events, Date.now()).has(normalizeClusterKey(headline));
 }
+/** How many quarantined tests are kept; the oldest by lastSeen fall off. */
+export const QUARANTINE_MAX = 100;
+/** The quarantine list, a malformed file or entry reading as no data. */
+export function loadQuarantine(root) {
+    const stored = readJsonFile(quarantinePath(root));
+    const out = [];
+    for (const e of Array.isArray(stored?.tests) ? stored.tests : []) {
+        if (!isJsonObject(e) || typeof e.test !== "string")
+            continue;
+        const num = (v) => (typeof v === "number" ? v : 0);
+        out.push({
+            test: e.test,
+            firstSeen: num(e.firstSeen),
+            lastSeen: num(e.lastSeen),
+            count: num(e.count) || 1,
+            bug: typeof e.bug === "string" ? e.bug : "",
+            ...(typeof e.tail === "string" ? { tail: e.tail } : {}),
+        });
+    }
+    return out;
+}
+function saveQuarantine(root, entries) {
+    const kept = [...entries].sort((a, b) => b.lastSeen - a.lastSeen).slice(0, QUARANTINE_MAX);
+    writeJsonAtomic(quarantinePath(root), { tests: kept });
+}
+/** The quarantined test names. */
+export function quarantinedTests(root) {
+    return loadQuarantine(root).map((e) => e.test);
+}
+/** The failing tests when every one is quarantined; null when none is named, any is outside the
+ * list, or the list may have been cut short (FAILING_TESTS_MAX). */
+export function onlyQuarantined(root, failingTests) {
+    if (!failingTests || failingTests.length === 0 || failingTests.length >= FAILING_TESTS_MAX)
+        return null;
+    const known = new Set(quarantinedTests(root));
+    return failingTests.every((t) => known.has(t)) ? [...failingTests] : null;
+}
+/** Quarantine each test of a check that failed and then passed on the same tree. A test already
+ * listed counts another flake; `tail` is kept for the BUGS.md entry of a new one. Returns the
+ * newly quarantined tests. Nothing is recorded for an empty or possibly truncated list. A failed
+ * write warns and returns no tests: the callers run this after a re-run passed, so a lost record
+ * must not fail that check. */
+export function quarantineTests(root, tests, tail) {
+    if (!tests || tests.length === 0 || tests.length >= FAILING_TESTS_MAX)
+        return [];
+    const entries = loadQuarantine(root);
+    const now = Date.now();
+    const added = [];
+    for (const test of new Set(tests)) {
+        const have = entries.find((e) => e.test === test);
+        if (have) {
+            have.lastSeen = now;
+            have.count += 1;
+        }
+        else {
+            const text = typeof tail === "string" ? tail : (tail ?? []).join("\n");
+            entries.push({ test, firstSeen: now, lastSeen: now, count: 1, bug: "", ...(text ? { tail: text } : {}) });
+            added.push(test);
+        }
+    }
+    if (!tryOrWarn(root, TUMWATER_SOURCE, "write quarantine.json", () => saveQuarantine(root, entries)))
+        return [];
+    return added;
+}
+/** Record the BUGS.md heading filed for each of `tests`, dropping their kept output. */
+export function markQuarantineFiled(root, bugs) {
+    const entries = loadQuarantine(root);
+    for (const e of entries) {
+        const bug = bugs.get(e.test);
+        if (bug === undefined)
+            continue;
+        e.bug = bug;
+        delete e.tail;
+    }
+    saveQuarantine(root, entries);
+}
+/** Release the quarantined tests whose filed BUGS.md entry is no longer under `## Open`; a later
+ * flake of one puts it back. Returns the released tests. A missing BUGS.md releases nothing. */
+export function releaseQuarantine(root) {
+    const entries = loadQuarantine(root);
+    const md = readTextOrNull(path.join(root, "BUGS.md"));
+    if (md === null || entries.length === 0)
+        return [];
+    const open = new Set(parseEntryDetails(md, "Open").map((e) => e.title));
+    const released = entries.filter((e) => e.bug !== "" && !open.has(e.bug));
+    if (released.length === 0)
+        return [];
+    saveQuarantine(root, entries.filter((e) => !released.includes(e)));
+    return released.map((e) => e.test);
+}