tumwater 0.3.0 → 0.4.1

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

@@ -38,6 +38,21 @@ function rankedRoleTotals(series, pick) {
 function rankedRoleLine(label, pairs, fmt) {
     return `**${label}:** ${pairs.length === 0 ? "-" : pairs.map(([r, n]) => `${r} — ${fmt(n)}`).join(" · ")}`;
 }
+/** The "**Prompt tokens by role:**" line — each role's prompt-token total and, when its
+ * backend reported a cache read, the share of it served from cache (`12000 (80% cached)`)
+ * — with zero-total roles omitted (the same zero-means-absent rule the sibling lines apply)
+ * and "-" when no role sent a prompt. `prompt` arrives already ranked (prompt desc then
+ * name asc). The one home of the share format, so the day and `--since` lines cannot drift. */
+function promptTokensLine(prompt, cache) {
+    const cacheByRole = new Map(cache);
+    const cells = prompt
+        .filter(([, n]) => n > 0)
+        .map(([role, n]) => {
+        const c = cacheByRole.get(role) ?? 0;
+        return `${role} — ${compactTokens(n)}${c > 0 ? ` (${Math.round((100 * c) / n)}% cached)` : ""}`;
+    });
+    return `**Prompt tokens by role:** ${cells.length === 0 ? "-" : cells.join(" · ")}`;
+}
 /** 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
@@ -179,6 +194,11 @@ export function renderSinceReportMarkdown(data) {
     // resource the budget charges, so this is the line an operator reads to find which role's
     // prompt loop burned the window's tokens.
     pushRankedRoleLine(lines, "Tokens by role", rankedRoleMap(data.tokensByRole), compactTokens);
+    // The prompt side of the same breakdown, straight after the output-token line: how many
+    // prompt tokens each role sent and the share of them its backend served from cache — the
+    // input side of the bill an operator cannot see from Tokens by role. Zero-prompt roles are
+    // omitted, and an all-zero window renders "-" like the sibling lines.
+    lines.push(promptTokensLine(rankedRoleMap(data.promptTokensByRole ?? {}), rankedRoleMap(data.cacheReadTokensByRole ?? {})));
     // Same breakdown for spend: ranked by spend desc then name asc, zero-spend roles omitted —
     // an all-zero window renders "-" like the runs line.
     pushRankedRoleLine(lines, "Cost by role", rankedRoleMap(data.costByRole), usd);
@@ -202,12 +222,27 @@ export function renderSinceReportMarkdown(data) {
     // a window main was never red.
     if (data.mainRedMs > 0)
         lines.push(`**Main red:** ${durationLabel(data.mainRedMs)}`);
+    // The same "what kept main red" detail named by failing test — which tests main's own red
+    // checks named over the window. Team-only like main's red time, so a role-scoped window
+    // omits it; zero-absent: no line when the window's red checks named no test.
+    if (data.role === undefined) {
+        const mainRedByTest = rankedRoleMap(data.mainRedByTest ?? {}).filter(([, n]) => n > 0);
+        if (mainRedByTest.length > 0)
+            lines.push(rankedRoleLine("Main red by test", mainRedByTest, String));
+        // The same "what kept main red" detail named by merge — the landed merges the watch's
+        // own main_culprit events blamed, mirroring the failing-test line right above. Team-only
+        // like main's red time and zero-absent: no line when the window blamed no merge.
+        const mainRedByCulprit = rankedRoleMap(data.mainRedByCulprit ?? {}).filter(([, n]) => n > 0);
+        if (mainRedByCulprit.length > 0)
+            lines.push(rankedRoleLine("Main red by merge", mainRedByCulprit, String));
+    }
     // The same breakdown for review friction: rejections per role from review_rejected events;
-    // a window with none renders "-" like the other lines.
+    // 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));
-    pushRankedRoleLine(lines, "Reverts by role", rankedRoleMap(data.revertsByRole));
     // The same breakdown for outright failures: error-class run_ends per role under the
     // 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
@@ -245,10 +280,18 @@ export function renderSinceReportMarkdown(data) {
         if (mergeFailureReasons.length > 0)
             lines.push(rankedRoleLine("Merge failures by reason", mergeFailureReasons, String));
     }
+    // Spend per merged commit, the --since twin of the day render's `Cost per commit:` line:
+    // costByRole is keyed by role id (instances not folded, so `feature-2` joins `feature`),
+    // commitsByRole is already base-role keyed. Prints for a spend-free window as `-` and for a
+    // role-scoped window from its scoped maps, matching the day render.
+    lines.push(costPerCommitLine("Cost per commit", costPerCommitPairsFrom(foldBaseRoles(data.costByRole), data.commitsByRole)));
     // 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) {
         pushRankedRoleLine(lines, "Estimated by role", rankedRoleMap(data.notionalByRole), usd);
+        // The day render's `Estimated per commit:` twin, after `Estimated by role`, from the same
+        // notionalByRole source folded to base roles and the base-keyed commitsByRole.
+        lines.push(costPerCommitLine("Estimated per commit", costPerCommitPairsFrom(foldBaseRoles(data.notionalByRole), data.commitsByRole)));
     }
     lines.push("");
     // Exactly one final line, chosen by the collector's coverage proof: either a hedged note
@@ -264,22 +307,21 @@ 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 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
+/** Fold every key of a per-role-id map through its base role, so `feature-2` joins `feature`.
+ * The same fold the day caller does per day, applied to an already-aggregated window map. */
+function foldBaseRoles(map) {
+    const folded = {};
+    for (const [id, c] of Object.entries(map))
+        addTo(folded, baseRoleOf(id), c);
+    return folded;
+}
+/** Rank one cost map against a base-keyed commits map into cost-per-commit output: the shared
+ * core of the day and --since cost-per-commit lines. `cost` is expected base-role keyed (the
+ * day caller folds per day, the --since caller via `foldBaseRoles`); commits are 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-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 = {};
-    const commits = {};
-    for (const d of series) {
-        for (const [id, c] of Object.entries(pick(d)))
-            addTo(cost, baseRoleOf(id), c);
-        for (const [role, n] of Object.entries(d.commitsByRole ?? {}))
-            addTo(commits, role, n);
-    }
+ * A role with commits but no spend appears in neither list. */
+function costPerCommitPairsFrom(cost, commits) {
     const mergeDone = [];
     const idleCost = [];
     for (const [role, c] of Object.entries(cost)) {
@@ -294,6 +336,22 @@ function costPerCommitPairs(series, pick = (d) => d.costByRole) {
     sortByValueDesc(mergeDone);
     return { mergeDone, idle: rankCountEntries(idleCost) };
 }
+/** The day caller of the cost-per-commit core: fold each day's role-id-keyed spend map through
+ * its base role (so `feature-2` joins `feature`) and aggregate the base-keyed commitsByRole,
+ * then hand both to `costPerCommitPairsFrom`. `pick` selects the per-role-id spend map; merge
+ * spend (the reviewer's) and notional subscription spend stay out by default, matching
+ * `**Cost by role:**`. */
+function costPerCommitPairs(series, pick = (d) => d.costByRole) {
+    const cost = {};
+    const commits = {};
+    for (const d of series) {
+        for (const [id, c] of Object.entries(pick(d)))
+            addTo(cost, baseRoleOf(id), c);
+        for (const [role, n] of Object.entries(d.commitsByRole ?? {}))
+            addTo(commits, role, n);
+    }
+    return costPerCommitPairsFrom(cost, commits);
+}
 /** One `**<label>:** …` line from costPerCommitPairs output; `-` when there is nothing. */
 function costPerCommitLine(label, pairs) {
     const parts = [
@@ -302,11 +360,8 @@ function costPerCommitLine(label, pairs) {
     ];
     return `**${label}:** ${parts.length === 0 ? "-" : parts.join(" · ")}`;
 }
-/** Render a report as Markdown — the pinned shape the CLI prints and the TUI usage pane
- * (report 3/3) reuses; the GUI tab (report 2/3) renders its own SVG charts from the same
- * ReportData instead. Pure function of ReportData: no I/O, no clock reads. */
-export function renderReportMarkdown(data) {
-    const lines = [];
+/** The title, window line, optional role line, then the report summary line. */
+function pushReportHeader(lines, data) {
     lines.push("# tumwater usage report");
     lines.push("");
     lines.push(reportWindow(data.from, data.to, data.days, eventsRotationLabel()));
@@ -324,6 +379,9 @@ export function renderReportMarkdown(data) {
         : "";
     pushReportSummary(lines, t, tail, data.role !== undefined);
     lines.push("");
+}
+/** The day-by-day window table (day, tokens out, runs, commits, cost) and its blank line. */
+function pushReportSeriesTable(lines, data) {
     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 runs = Object.values(d.runsByRole).reduce((a, b) => a + b, 0);
@@ -332,16 +390,26 @@ export function renderReportMarkdown(data) {
         return [monthDay(d.date), `${compactTokens(d.tokensOut)}${bar}`, String(runs), String(d.commits), usd(d.costUsd)];
     }), ["left", "right", "right", "right", "right"]));
     lines.push("");
+}
+/** The per-role runs/tokens/prompt/cost breakdown lines. */
+function pushReportRoleLines(lines, data) {
     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 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 input side of that same bill, straight after the output-token line: each role's prompt
+    // totals and, when some run reported a cache read, the share of them served from cache — so
+    // the same report that says who burned output tokens also says whose prompts are cached.
+    lines.push(promptTokensLine(rankedRoleTotals(data.series, (d) => d.promptTokensByRole ?? {}), rankedRoleTotals(data.series, (d) => d.cacheReadTokensByRole ?? {})));
     // 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 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 team-only per-provider and per-model breakdown lines. */
+function pushReportProviderLines(lines, data) {
     // 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
@@ -360,12 +428,16 @@ export function renderReportMarkdown(data) {
         if (modelPairs.length > 0)
             lines.push(rankedRoleLine("Runs by model", modelPairs, String));
     }
+}
+/** The per-role review-friction and outright-failure lines. */
+function pushReportFrictionLines(lines, data) {
     // The same breakdown for review friction: window rejections per role from review_rejected
-    // events, ranked like the runs line; a window with none renders "-".
+    // 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 ?? {}));
-    pushRankedRoleLine(lines, "Reverts by role", rankedRoleTotals(data.series, (d) => d.revertsByRole ?? {}));
     // The same breakdown for outright failures: error-class run_ends per role under the
     // 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
@@ -373,6 +445,9 @@ export function renderReportMarkdown(data) {
     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 ?? {}));
+}
+/** The team-only deferred-runs-by-reason line. */
+function pushReportDeferralLines(lines, data) {
     // 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
@@ -383,6 +458,9 @@ export function renderReportMarkdown(data) {
         if (deferred.length > 0)
             lines.push(rankedRoleLine("Deferred runs by reason", deferred, String));
     }
+}
+/** The Commits-by-role line plus the team-only merge/main-red/cameo block. */
+function pushReportMergeLines(lines, data) {
     // Work ratio 4/4: the merged commits split by base role and by tier. The totals line's
     // `commits` carries the count; these lines say who made it and how much of it was work.
     lines.push(rankedRoleLine("Commits by role", rankedRoleTotals(data.series, (d) => d.commitsByRole ?? {}), String));
@@ -411,9 +489,21 @@ export function renderReportMarkdown(data) {
         // suite went red before passing shows here. Zero-absent: no line when no day fails.
         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
+        // had its own check red (the span main had no passing full check). 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);
+        // The day twin of the --since window's totals line: the same tests ranked across the
+        // series' per-day main-red maps (Main red by test). Zero-absent: no line when no day
+        // named a failing test.
+        const mainRedByTest = rankedRoleTotals(data.series, (d) => d.mainRedByTest ?? {}).filter(([, n]) => n > 0);
+        if (mainRedByTest.length > 0)
+            lines.push(rankedRoleLine("Main red by test", mainRedByTest, String));
+        // The day twin of the --since window's merges line: the same culprits ranked across the
+        // series' per-day main-red maps (Main red by merge). Zero-absent: no line when no day
+        // blamed a merge.
+        const mainRedByCulprit = rankedRoleTotals(data.series, (d) => d.mainRedByCulprit ?? {}).filter(([, n]) => n > 0);
+        if (mainRedByCulprit.length > 0)
+            lines.push(rankedRoleLine("Main red by merge", mainRedByCulprit, String));
         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/
@@ -427,6 +517,10 @@ export function renderReportMarkdown(data) {
         pushDayCameoLine(lines, data.series, "Workspace wait median", (d) => d.slotWaitMedianMs);
         pushDayCameoLine(lines, data.series, "Check wait median", (d) => d.checkWaitMedianMs);
     }
+}
+/** Cost/commits tail: cost per commit, notional block, lag, validation gaps, sparse note. */
+function pushReportTail(lines, data) {
+    const t = data.totals;
     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) {
@@ -464,5 +558,19 @@ export function renderReportMarkdown(data) {
     // it prints — an empty or fully covered log never claims a history it cannot see.
     if (!data.coversFullWindow)
         lines.push("", SPARSE_WINDOW_NOTE);
+}
+/** Render a report as Markdown — the pinned shape the CLI prints and the TUI usage pane
+ * (report 3/3) reuses; the GUI tab (report 2/3) renders its own SVG charts from the same
+ * ReportData instead. Pure function of ReportData: no I/O, no clock reads. */
+export function renderReportMarkdown(data) {
+    const lines = [];
+    pushReportHeader(lines, data);
+    pushReportSeriesTable(lines, data);
+    pushReportRoleLines(lines, data);
+    pushReportProviderLines(lines, data);
+    pushReportFrictionLines(lines, data);
+    pushReportDeferralLines(lines, data);
+    pushReportMergeLines(lines, data);
+    pushReportTail(lines, data);
     return lines.join("\n");
 }

package/dist/src/report/report.js

@@ -8,7 +8,7 @@ import { renderFailureMarkdown } from "../failure/failure-render.js";
 import { renderReportMarkdown, renderSinceReportMarkdown } from "./report-render.js";
 import { fail, say, sayJson, sayJsonOrRender } from "../cli/cli-output.js";
 import { followView } from "../cli/follow-view.js";
-import { durationLabel, failRivalShapes, flagValue, parseCountFlag, parseRoleListScope, parseSinceFlag } from "../cli/cli-args.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>]
@@ -20,10 +20,7 @@ export async function cmdReport(root, args, seams = {}) {
     // 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");
-    if (untilMs !== null && ms === null)
-        fail("report --until requires --since");
-    if (untilMs !== null && ms !== null && untilMs >= ms)
-        fail(`report --until (${durationLabel(untilMs)}) must be shorter than --since (${durationLabel(ms)})`);
+    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 list of base roles.
     const role = parseRoleListScope(root, args);

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

@@ -10,7 +10,7 @@
  * 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 { TUMWATER_SOURCE, tryOrWarn, warnEventBestEffort } from "../events/events.js";
 import { readEventsSince } from "../events/event-window.js";
 import { increment } from "../collections.js";
 import { normalizeClusterKey } from "../failure/failure-cluster.js";
@@ -62,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));
@@ -136,6 +148,25 @@ export function quarantineTests(root, tests, tail) {
         return [];
     return added;
 }
+/** Remove the one quarantined test named `test` at the operator's request — the manual twin
+ * of releaseQuarantine's automatic release, and `tumwater quarantine --release <n>` its only
+ * caller (which resolves the position the list prints down to the exact test first). Returns
+ * whether the entry was present and the write succeeded, so the caller can answer a concurrent
+ * removal: `false` with no warning and no write for a name not quarantined, or when a write
+ * faulted (the quarantineTests write contract: a failed write warns and changes nothing). Logs
+ * one `warning` under TUMWATER_SOURCE so the alert and the doctor's `flaky checks` row stop
+ * excusing the name. */
+export function releaseQuarantinedTest(root, test) {
+    const entries = loadQuarantine(root);
+    const have = entries.some((e) => e.test === test);
+    if (!have)
+        return false;
+    const removed = entries.filter((e) => e.test !== test);
+    if (!tryOrWarn(root, TUMWATER_SOURCE, "write quarantine.json", () => saveQuarantine(root, removed)))
+        return false;
+    warnEventBestEffort(root, TUMWATER_SOURCE, `${test} released from the flake quarantine at the user's request — the gate no longer excuses its failures`);
+    return true;
+}
 /** Record the BUGS.md heading filed for each of `tests`, dropping their kept output. */
 export function markQuarantineFiled(root, bugs) {
     const entries = loadQuarantine(root);

package/dist/src/review/post-merge-review-accept.js

@@ -0,0 +1,51 @@
+/** The operator's deliberate acceptance of a pending post-merge review without running it
+ * (src/cli/cli-review-commands.ts `tumwater reviews --accept <n>`), split out of the CLI so
+ * the review queue stays a pure reader/editor and this module owns the destructive half —
+ * removing an unattempted entry on purpose. It is the sibling of `tumwater queue --cancel
+ * <n>` (src/merge/merge-cancel.ts): the queue's no-third-path gap that the at-risk alert's
+ * shared sentence names ("…or accept the commit unreviewed deliberately"). It reads the same
+ * FIFO list `readPostReviews` numbers 1..N and settles the entry by its commit, so the removed
+ * entry is the very one the printed position named. */
+import { readPostReviews, settlePostReview } from "./post-merge-review.js";
+import { warnEventBestEffort } from "../events/events.js";
+import { shortSha } from "../text/format.js";
+/** Remove one readable entry the operator accepts unreviewed: refuse it (writing nothing) when
+ * it carries `fixed` — the repair already merged, so accepting it unreviewed is meaningless
+ * and the false "accepted unreviewed" warning would mislead — otherwise settle it with no
+ * verdict (`settlePostReview`; its failed write already warns and never throws, INV-BT2),
+ * log one `warning` under the entry's role, and return the `accepted` outcome naming what was
+ * retired. A rejected entry waits on nothing, so it is accepted like any other pending entry.
+ * The single removal both `acceptPostReview` (by position) and `acceptPostReviewBySha`
+ * (by sha) share, so the CLI and the dashboard's post-review-accept cannot drift on what
+ * accepting means. */
+function removeAcceptedEntry(root, entry) {
+    if (entry.fixed !== undefined)
+        return { status: "settled", commit: entry.commit };
+    settlePostReview(root, entry.commit, null);
+    const message = `post-merge review of ${shortSha(entry.commit)} accepted unreviewed at the operator's request — the commit stays on main unreviewed`; // vocabulary-ok: the accepted-unreviewed wording those reasons it is the operator's choice
+    warnEventBestEffort(root, entry.role, message);
+    return { status: "accepted", role: entry.role, commit: entry.commit, summary: entry.summary };
+}
+/** Retire the Nth pending post-merge review — 1-based, as `tumwater reviews` numbers it —
+ * accepting the commit unreviewed at the operator's request. `position` is resolved against
+ * `readPostReviews` (the same readable FIFO list the command renders), so the position matches
+ * the line `tumwater reviews` printed. An out-of-range position writes nothing and returns the
+ * current readable depth; otherwise it runs the same `removeAcceptedEntry` the sha variant
+ * shares, so the two never drift on what accepting means (see `removeAcceptedEntry` for the
+ * removal, the fixed-guard, the warning, and the never-throws guarantee). */
+export function acceptPostReview(root, position) {
+    const entries = readPostReviews(root);
+    if (position < 1 || position > entries.length)
+        return { status: "out-of-range", depth: entries.length };
+    return removeAcceptedEntry(root, entries[position - 1]);
+}
+/** Remove the pending post-merge review whose entry's commit is `sha` (the browser twin of
+ * `tumwater reviews --accept <n>`, resolving by commit because the dashboard rows carry one).
+ * A commit that matches none is `{ status: "gone" }` and changes nothing; otherwise it runs the
+ * same `removeAcceptedEntry` the position variant shares. */
+export function acceptPostReviewBySha(root, sha) {
+    const entry = readPostReviews(root).find((e) => e.commit.toLowerCase() === sha.toLowerCase());
+    if (!entry)
+        return { status: "gone" };
+    return removeAcceptedEntry(root, entry);
+}

package/dist/src/review/post-merge-review-render.js

@@ -0,0 +1,112 @@
+/** The renderer behind `tumwater reviews` — the operator-facing text for the post-merge review
+ * queue (.tumwater/state/post-review.json): one line per well-formed entry in the given order,
+ * plus a `post-merge review queue (N):` header. Pure function of the entry list — the optional
+ * `now` is the only clock input, and when it is a number and an entry carries `enqueuedAt` the
+ * line names the wait since the entry was first queued, exactly as the merge queue names its
+ * age — so a test can pin its output exactly. The `merge queue empty` convention
+ * (src/merge/merge-queue-render.ts) is reused for the empty case. */
+import { roleLabel } from "../roles/role-labels.js";
+import { shortSha } from "../text/format.js";
+import { squash } from "../text/text.js";
+import { filterKeepPositions } from "../collections.js";
+import { plural } from "../text/phrases.js";
+import { humanAgo } from "../text/datetime.js";
+/** The one state every observer surface narrows on: `fixed` when the repair already merged
+ * (the terminal Forward-never-back 1a/6 record — naming both shas, it is not pending anything),
+ * `rejected` when the reviewer turned the commit back (empty `rejected` array still counts),
+ * `failing` when the review runs keep ending without a verdict (`failures` positive), else
+ * `waiting`. The precedence matches what postReviewStatusLabel already printed — an entry can
+ * never be both — so the status label and `tumwater reviews --status` share this one definition
+ * and cannot drift. */
+export function postReviewState(entry) {
+    if (entry.fixed !== undefined)
+        return "fixed";
+    if (entry.rejected !== undefined)
+        return "rejected";
+    if (typeof entry.failures === "number" && entry.failures > 0)
+        return "failing";
+    return "waiting";
+}
+/** The states `tumwater reviews --status` accepts, in the order the filter's error message
+ * lists them (the terminal `fixed` last). `postReviewState` is the definition; this only names
+ * the vocabulary. */
+export const POST_REVIEW_STATES = ["waiting", "failing", "rejected", "fixed"];
+/** The bracketed status suffix one post-merge review entry carries on every observer surface
+ * (`tumwater reviews`, the dashboard's Post-merge reviews card, and the TUI Pending pane's
+ * review block): the reviewer's recorded rejected reasons when `rejected` is set; else the
+ * number of verdict-less review runs when `failures` is positive, naming the
+ * last failure's reason beside the count when `lastFailure` is a non-empty string; else `""`.
+ * Reasons are squashed to 60 as `tumwater reviews` has always printed them, and the failure
+ * detail to 80. Branches on `postReviewState` so the label and the `--status` filter share one
+ * state definition; extracted so the
+ * CLI, the dashboard and the TUI share one status wording and cannot drift. */
+export function postReviewStatusLabel(entry) {
+    switch (postReviewState(entry)) {
+        case "fixed":
+            return `[fixed — the repair ${shortSha(entry.fixed)} already merged on main]`;
+        case "rejected":
+            return `[rejected — ${entry.rejected.map((r) => squash(r, 60)).join("; ")}]`;
+        case "failing": {
+            const failures = entry.failures; // postReviewState only says "failing" when failures > 0
+            if (typeof entry.lastFailure === "string" && entry.lastFailure.length > 0) {
+                return `[${plural(failures, "failed review run")} — last: ${squash(entry.lastFailure, 80)}]`;
+            }
+            return `[${plural(failures, "failed review run")}]`;
+        }
+        default:
+            return "";
+    }
+}
+/** Narrows a whole post-merge review list to the entries `keep` accepts, and returns
+ * the `scope` renderPostReviews takes: the kept roles, each kept entry's 1-based place in the
+ * whole list, and the whole list's entry count — plus, when a status filter is active, the
+ * `filter` text the header and no-match line print. The filtering-and-positioning step is the
+ * shared `filterKeepPositions` (src/collections.ts) that `scopeMergeQueue` (src/merge/
+ * merge-queue-render.ts) also uses, so `tumwater reviews --role` keeps the same whole-queue
+ * positions `--accept <n>` still addresses. */
+export function scopePostReviews(entries, roles, keep, filter) {
+    const { kept, positions } = filterKeepPositions(entries, keep);
+    return {
+        entries: kept,
+        scope: { roles, positions, total: entries.length, ...(filter !== undefined ? { filter } : {}) },
+    };
+}
+/** The text `tumwater reviews` prints. A totally empty queue renders `post-merge review queue
+ * empty`; otherwise a header and one line per entry — position, role, short commit, and, when
+ * `now` and the entry's `enqueuedAt` are both numbers, the wait since the commit was queued
+ * (`<age> ago`, between the short commit and the summary) — then the squashed summary and the
+ * status suffix from `postReviewStatusLabel`, appended as `" · " + label` only when it is
+ * non-empty. Without a `now`, or for an entry with no `enqueuedAt`, the line is byte-identical
+ * to before, so an older `post-review.json` and every existing renderer test read unchanged.
+ * With the optional `scope` (`reviews --role`/`--status`: `entries` already holds only the kept
+ * entries', `positions` their 1-based places in the whole queue, `total` the whole queue's
+ * entry count, and `filter` the `--role`/`--status` filter text when one is active) each line
+ * keeps its whole-queue number and the header reads
+ * `post-merge review queue (<kept> of <total>, <filter>):`, where `<filter>` is `scope.filter`
+ * when set else `--role <ids>`. A scope that keeps nothing of a non-empty queue prints
+ * `no post-merge reviews matching <filter> (post-merge review queue holds <total>)` when a
+ * filter is set, else `no post-merge reviews for <ids> (…)`. Without `scope` and `now` the
+ * output is byte-identical to before. */
+export function renderPostReviews(entries, scope, now) {
+    const total = scope ? scope.total : entries.length;
+    if (total === 0)
+        return "post-merge review queue empty";
+    if (scope && entries.length === 0) {
+        const reason = scope.filter !== undefined ? `matching ${scope.filter}` : `for ${scope.roles.join(",")}`;
+        return `no post-merge reviews ${reason} (post-merge review queue holds ${total})`;
+    }
+    const lines = [
+        scope
+            ? `post-merge review queue (${entries.length} of ${total}, ${scope.filter ?? `--role ${scope.roles.join(",")}`}):`
+            : `post-merge review queue (${plural(total, "entry", "entries")}):`,
+    ];
+    entries.forEach((entry, i) => {
+        const label = postReviewStatusLabel(entry);
+        const suffix = label === "" ? "" : ` · ${label}`;
+        const age = typeof now === "number" && typeof entry.enqueuedAt === "number"
+            ? ` · ${humanAgo(entry.enqueuedAt, now)}`
+            : "";
+        lines.push(`  ${scope ? scope.positions[i] : i + 1}. ${roleLabel(entry.role)} ${shortSha(entry.commit)}${age} · ${squash(entry.summary, 80)}${suffix}`);
+    });
+    return lines.join("\n");
+}