tumwater 0.4.0 → 0.4.2

package/dist/src/report/report-usage-fold.js

@@ -0,0 +1,288 @@
+/** The single-event folding core of the usage report: fold one harness event into a
+ * `UsageFold` accumulator (`foldUsageEvent`), with one named helper per event family
+ * (run_end, review_rejected, merge_done/merge_failed, …). This is the pure per-event rule,
+ * shared by the since-window collector and the per-day window fold — the latter lives in
+ * src/report/report-fold.ts, which reads and memoizes the event log (`foldWindowEvents`)
+ * and delegates each parsed event here, so the two windows' aggregation rules cannot drift
+ * apart. Zero incidental runtime dependencies: node built-ins and the app's own modules
+ * only. */
+import { addTo } from "../collections.js";
+import { isPassingFullCheck, isRedFullCheck } from "../build/build-check-events.js";
+import { eventRole, eventUsage } from "../events/event-read.js";
+import { finiteNumber, nonNegativeNumber } from "../files/json-object.js";
+import { OUTCOME_CLASS } from "../failure/time-spend.js";
+import { commitTier } from "../roles/roles.js";
+import { baseRoleOf } from "../roles/runner-ids.js";
+/** Fold one event's `providerCost` map (`Record<provider, {costUsd, notionalCostUsd}>` — the
+ * shape run-finalize.ts's run_end and merge-slot.ts's merge_done/merge_failed emit) into the
+ * per-provider tallies, one addTo per provider per nonzero figure so zero stays absent. A
+ * missing, foreign, or empty map folds nothing, so old logs render byte-identically. */
+function foldProviderCost(target, providerCost) {
+    if (typeof providerCost !== "object" || providerCost === null)
+        return;
+    for (const [provider, c] of Object.entries(providerCost)) {
+        if (typeof c !== "object" || c === null)
+            continue;
+        const entry = c;
+        const costUsd = finiteNumber(entry.costUsd, 0);
+        const notionalCostUsd = finiteNumber(entry.notionalCostUsd, 0);
+        if (costUsd !== 0)
+            addTo(target.costByProvider, provider, costUsd);
+        if (notionalCostUsd !== 0)
+            addTo(target.notionalByProvider, provider, notionalCostUsd);
+    }
+}
+/** Push `ms` into the accumulator list a day median reads, when it is positive: the event
+ * fields that feed these medians are missing or 0 for the same event kinds (short runs, build
+ * pre-checks, precedent legacy events, probe-seam waits), and those contribute nothing — a
+ * median over only real durations/wait times. Every median list folds through here, so the
+ * "positive-only" rule cannot drift between fields. */
+function pushPositiveMs(list, ms) {
+    if (ms > 0)
+        list.push(ms);
+}
+/** Fold a run_end into the accumulator: a run (per role and, when the target counts runs, in
+ * total), its output/prompt/cache tokens, its cost, and its notional backend share. */
+function foldRunEnd(target, ev) {
+    const role = eventRole(ev);
+    addTo(target.runsByRole, role, 1);
+    // Error-class runs get their own parallel tally — the day report's ``Failed runs by role``
+    // line — reusing the digest's OUTCOME_CLASS so "failed" cannot drift from the failure
+    // report's meaning. Never subtracted from runsByRole; the two are independent counts.
+    if (OUTCOME_CLASS[ev.result] === "error")
+        addTo(target.failedRunsByRole, role, 1);
+    // A refusal is its own deliberate outcome (src/verdict/refusal.ts), not error-class, so
+    // it needs an explicit result check: the one per-role rejection-without-review count a
+    // day report should surface beside rejections, revisions and falls. Never subtracted from
+    // runsByRole; a refused run still counts as a run.
+    if (ev.result === "refused")
+        addTo(target.refusalsByRole, role, 1);
+    if (target.runs !== undefined)
+        target.runs++;
+    const { tokens, costUsd, notionalCostUsd } = eventUsage(ev);
+    pushPositiveMs(target.runDurationsMs, finiteNumber(ev.durationMs, 0));
+    addTo(target.tokensByRole, role, tokens);
+    // The prompt side of the same run's bill: how many prompt tokens each role sent and how
+    // much of that its backend served from cache (run-finalize.ts rides both on run_end, each
+    // omitted when zero). Zero-means-absent like tokensByRole. The finite guard is the failure
+    // digest's promptStatsFor rule, and the Math.min clamp keeps a torn log's cache share from
+    // ever exceeding the prompt total — together they pin a rendered share to <= 100% and keep
+    // a non-finite reading (1e999 → Infinity) out of the maps as absent, not NaN.
+    const prompt = nonNegativeNumber(ev.promptTokens, 0);
+    const cacheRead = Math.min(nonNegativeNumber(ev.cacheReadTokens, 0), prompt);
+    if (prompt > 0)
+        addTo(target.promptTokensByRole, role, prompt);
+    if (cacheRead > 0)
+        addTo(target.cacheReadTokensByRole, role, cacheRead);
+    target.tokensOut += tokens;
+    target.costUsd += costUsd;
+    target.notionalCostUsd += notionalCostUsd;
+    if (costUsd !== 0)
+        addTo(target.costByRole, role, costUsd);
+    if (notionalCostUsd !== 0)
+        addTo(target.notionalByRole, role, notionalCostUsd);
+    // The notional spend's backend (plans/codex-backend.md part 3d/9): the subscription seam
+    // whose runs made the run's API-equivalent cost, from the run_end's `agent` (run-finalize
+    // carries it when the run reported billing/rate windows) — falling back to "claude" when
+    // a legacy window event (no agent, subscription billing) attributed its spend, so the old
+    // default stays the report's only backend. A run with no backend and no subscription
+    // billing is unattributed and adds no key, so the render keeps its generic line for it.
+    const notionalBackend = typeof ev.agent === "string" && ev.agent !== ""
+        ? ev.agent
+        : ev.billing === "subscription"
+            ? "claude"
+            : undefined;
+    if (notionalBackend !== undefined && notionalCostUsd !== 0)
+        addTo(target.notionalByBackend, notionalBackend, notionalCostUsd);
+    // The agent runs' per-provider spend (run-finalize.ts emits providerCost on run_end)
+    // — folded per provider beside the per-role maps, so a mixed team's `Cost by provider`
+    // line names the expensive seam.
+    foldProviderCost(target, ev.providerCost);
+}
+/** Fold a review_rejected: one rejection per event, on the day it happened, per role, with
+ * the post-merge subset and a review-duration entry when the rejection carried one. */
+function foldReviewRejected(target, ev) {
+    // One rejection per event, on the day it happened, per role. Zero-means-absent: a role
+    // that never rejected stays absent, like costByRole.
+    addTo(target.rejectionsByRole, eventRole(ev), 1);
+    // A rejection that carried afterMerge: true is a post-merge one — the commit had already
+    // landed, so the reviewer's turn-back reaches the revert path off main. Kept as its own
+    // subset of rejectionsByRole because it is a different, costlier kind of rejection.
+    if (ev.afterMerge === true)
+        addTo(target.postMergeRejectionsByRole, eventRole(ev), 1);
+    // A rejection that carried a positive durationMs means a reviewer actually ran the gate
+    // and reached a verdict (post-merge rejections do; the build pre-check contributes no
+    // duration), so it joins the review-duration median beside approvals. durationMs: 0 and
+    // a duration-less event contribute nothing.
+    pushPositiveMs(target.reviewDurationsMs, finiteNumber(ev.durationMs, 0));
+}
+/** Fold a review_verdict approval into the review-duration median. */
+function foldReviewVerdict(target, ev) {
+    // An approval that reached a verdict. Every reviewer run that reached a verdict, approval
+    // or rejection, is one entry in the review-duration median; review_failed stays out — it
+    // has no verdict. Mirrors the rejection branch above, on the same-day count.
+    pushPositiveMs(target.reviewDurationsMs, finiteNumber(ev.durationMs, 0));
+}
+/** Fold a revision: one rework round per event, on the day it happened, per role. */
+function foldRevision(target, ev) {
+    // One rework round per event, on the day it happened, per role. Zero-means-absent: a role
+    // that never reworked a rejected change stays absent, like rejectionsByRole.
+    addTo(target.revisionsByRole, eventRole(ev), 1);
+}
+/** Fold a passing full-suite check into the day report's check-time median. */
+function foldPassingCheck(target, ev) {
+    // The merge slot's passing full-suite checks, for the day report's check-time median.
+    pushPositiveMs(target.checkDurationsMs, finiteNumber(ev.durationMs, 0));
+}
+/** Fold a red full-suite check into the day report's red-check count. */
+function foldRedCheck(target, _ev) {
+    // The merge slot's red full-suite checks, for the day report's red-check count.
+    target.checkFailures++;
+}
+/** Fold a model_fallback_started: one episode per start event, per role. */
+function foldFallbackStarted(target, ev) {
+    // One episode per start event; durations are not summed (an episode can span the window edge).
+    addTo(target.fallbacksByRole, eventRole(ev), 1);
+}
+/** Fold a run_deferred: one deferral per event, bucketed by the raw reason code (team-only). */
+function foldDeferred(target, ev) {
+    // One deferral per event, a due maintenance run that stood down. Bucket by the raw
+    // reason code ("backlog", "plans-full", else "no-work" for a missing/foreign/torn
+    // reason — the same fallback deferredReasonText applies in the feed), so the collector
+    // stays free of a presentation import and the render prints the code the event carried.
+    // Team-only: a reason is not a role.
+    const reason = ev.reason === "backlog" || ev.reason === "plans-full" ? ev.reason : "no-work";
+    addTo(target.deferredByReason, reason, 1);
+}
+/** Fold a merged commit: one commit split by base role and tier (Work ratio 4/4). */
+function foldMerged(target, ev) {
+    target.commits++;
+    // Work ratio 4/4: split merged commits by base role and by tier. Instance suffixes fold
+    // into their role (`feature-2` counts as feature) so the split does not fragment.
+    const role = baseRoleOf(eventRole(ev));
+    addTo(target.commitsByRole, role, 1);
+    const tier = commitTier(role);
+    if (tier === "work")
+        target.workCommits++;
+    else if (tier === "maintenance")
+        target.maintenanceCommits++;
+}
+/** Fold a run_start: one tally per run start on a configured model. */
+function foldRunStarted(target, ev) {
+    // One tally per run start on a configured model: the same `model` field the CLI's
+    // `run #N started on <model>` line prints, and the only event that carries a model
+    // (run_end has none), so a run that started with no configured model contributes no key.
+    const model = typeof ev.model === "string" && ev.model.length > 0 ? ev.model : null;
+    if (model !== null)
+        addTo(target.runsByModel, model, 1);
+}
+/** Fold a provider_wait into the provider-slot wait median. */
+function foldProviderWait(target, ev) {
+    // The day report's provider-slot wait median, mirroring the slot_wait push: a wait only
+    // event-logged at or above the 30 s threshold counts, so a 0 ms wait (a probe seam) adds
+    // nothing and the median reflects real blocked admissions only.
+    pushPositiveMs(target.providerWaitsMs, finiteNumber(ev.waitedMs, 0));
+}
+/** Fold a slot_wait into the workspace-slot wait median. */
+function foldSlotWait(target, ev) {
+    // The day report's workspace-slot wait median, mirroring the provider_wait push: a wait
+    // only event-logged at or above the 30 s threshold counts, so a 0 ms wait (a probe seam)
+    // or a pre-waitedMs event adds nothing.
+    pushPositiveMs(target.slotWaitsMs, finiteNumber(ev.waitedMs, 0));
+}
+/** Fold a check_wait into the check-slot wait median. */
+function foldCheckWait(target, ev) {
+    // The day report's check-slot wait median, mirroring the slot_wait push: only waits logged
+    // at or above the 30 s threshold count, so a 0 ms or pre-waitedMs event adds nothing.
+    pushPositiveMs(target.checkWaitsMs, finiteNumber(ev.waitedMs, 0));
+}
+/** Fold a merge_done/merge_failed outcome: its run count, its accumulation into the merge
+ * fields only (costByRole stays a runs-only breakdown), and its notional/provider shares. */
+function foldMergeOutcome(target, ev) {
+    target.mergeRuns = (target.mergeRuns ?? 0) + 1;
+    if (ev.type === "merge_failed")
+        target.mergeFailed = (target.mergeFailed ?? 0) + 1;
+    // Attribute the outcome to the authoring role (writeMergeOutcome logs role: entry.role)
+    // folded to base role, the same normalization the merged branch uses, so `feature-2`
+    // aggregates into `feature`. A parallel tally beside the team run counts, never
+    // subtracted from mergeRuns/mergeFailed.
+    const role = baseRoleOf(eventRole(ev));
+    if (ev.type === "merge_done") {
+        addTo(target.mergedByRole, role, 1);
+        // Events logged before queuedMs existed carry none: skipped, not counted as zero.
+        pushPositiveMs(target.mergeWaitsMs, finiteNumber(ev.queuedMs, 0));
+        // How long the merge slot itself held the change, from the verification's start to the
+        // outcome. Like mergeWaitsMs, only a landed merge feeds it, and a pre-durationMs event
+        // (or 0) contributes nothing.
+        pushPositiveMs(target.mergeDurationsMs, finiteNumber(ev.durationMs, 0));
+    }
+    else {
+        addTo(target.mergeFailedByRole, role, 1);
+        // The event's result (writeMergeOutcome's RunResult) names WHY the merge bounced
+        // off the gate — rejected/merge_conflict/merge_blocked/aborted. A legacy event with
+        // no result folds under `unknown`, so the reason buckets always sum to mergeFailed.
+        const reason = typeof ev.result === "string" && ev.result.length > 0 ? ev.result : "unknown";
+        addTo(target.mergeFailedByReason, reason, 1);
+    }
+    const { tokens, costUsd, notionalCostUsd } = eventUsage(ev);
+    target.mergeTokens = (target.mergeTokens ?? 0) + tokens;
+    target.mergeCostUsd = (target.mergeCostUsd ?? 0) + costUsd;
+    // A subscription merge's API-equivalent spend joins the notional line, never the
+    // budgeted cost totals (plans/agent-backends.md part 6a).
+    target.notionalCostUsd += notionalCostUsd;
+    // The merge's notional spend per backend (merge-slot.ts emits it on the event, keyed by
+    // each subscription run's agent) — folded beside the run-end per-backend map, so a codex
+    // merge's subscription spend names codex instead of falling back to the generic line.
+    for (const [backend, c] of Object.entries(ev.notionalByBackend ?? {})) {
+        const amt = finiteNumber(c, 0);
+        if (amt !== 0)
+            addTo(target.notionalByBackend, backend, amt);
+    }
+    // The merge's per-provider spend (merge-slot.ts keys it to its reviewer seam), so a
+    // merge's costs appear under the provider that ran the reviewer, matching the author
+    // side's foldMergeUsage charge.
+    foldProviderCost(target, ev.providerCost);
+}
+/** Fold one event into a usage accumulator by dispatching to a per-family builder —
+ * foldRunEnd, foldReviewRejected, foldReviewVerdict, foldRevision, foldPassingCheck,
+ * foldRedCheck, foldFallbackStarted, foldDeferred, foldMerged,
+ * foldRunStarted, foldProviderWait, foldSlotWait, foldCheckWait or foldMergeOutcome — each
+ * named for the family it folds, so how a family folds is found by name. The dispatch holds
+ * no accumulation of its own. All behavior lives in the builders: run_end events add a run
+ * (per role and, when the target counts runs, in total), their output tokens, and their
+ * cost — zero-cost runs contribute nothing, so they leave no costByRole key, keeping the
+ * render's "$0 roles are omitted" rule true on the aggregation itself, not just at display
+ * time; merged events add a commit; merge_done/merge_failed events add a merge run and
+ * accumulate their tokens/cost into the merge fields only — costByRole stays a runs-only
+ * breakdown, and the merge line is how the reviewer's share is named. Both collectors fold
+ * through this one place, so the two windows' aggregation rules cannot drift apart. */
+export function foldUsageEvent(target, ev) {
+    if (ev.type === "run_end")
+        foldRunEnd(target, ev);
+    else if (ev.type === "review_rejected")
+        foldReviewRejected(target, ev);
+    else if (ev.type === "review_verdict")
+        foldReviewVerdict(target, ev);
+    else if (ev.type === "revision")
+        foldRevision(target, ev);
+    else if (isPassingFullCheck(ev))
+        foldPassingCheck(target, ev);
+    else if (isRedFullCheck(ev))
+        foldRedCheck(target, ev);
+    else if (ev.type === "model_fallback_started")
+        foldFallbackStarted(target, ev);
+    else if (ev.type === "run_deferred")
+        foldDeferred(target, ev);
+    else if (ev.type === "merged")
+        foldMerged(target, ev);
+    else if (ev.type === "run_start")
+        foldRunStarted(target, ev);
+    else if (ev.type === "provider_wait")
+        foldProviderWait(target, ev);
+    else if (ev.type === "slot_wait")
+        foldSlotWait(target, ev);
+    else if (ev.type === "check_wait")
+        foldCheckWait(target, ev);
+    else if (ev.type === "merge_done" || ev.type === "merge_failed")
+        foldMergeOutcome(target, ev);
+}

package/dist/src/report/report.js

@@ -2,7 +2,8 @@
  * src/report/report-data.ts / src/failure/failure-data.ts, and print. The Markdown renderers
  * live in the pure-render modules they pair with: src/report/report-render.ts and
  * src/failure/failure-render.ts. */
-import { collectReport, collectReportSince } from "./report-data.js";
+import { collectReport } from "./report-data.js";
+import { collectReportSince } from "./report-since-data.js";
 import { collectFailureReport, collectFailureReportSince } from "../failure/failure-data.js";
 import { renderFailureMarkdown } from "../failure/failure-render.js";
 import { renderReportMarkdown, renderSinceReportMarkdown } from "./report-render.js";

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";
@@ -65,11 +65,11 @@ export function flakeCounts(events) {
 /** 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
+ * checks` row reads, 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
+ * frequent first — the filter flakeCounts feeds the doctor's `flaky checks` row, so the
  * threshold lives in the one home. Pure. */
 export function repeatedFlakeCounts(events) {
     return flakeCounts(events).filter(([, n]) => n >= FLAKE_REPEAT_WARN);
@@ -148,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 doctor's `flaky checks` row stops
+ * 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

@@ -2,8 +2,9 @@
  * (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
+ * <n>` (src/merge/merge-cancel.ts): the queue's no-third-path gap that the doctor's at-risk
+ * post-review row'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";

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

@@ -1,4 +1,5 @@
 import { readJsonFile, writeJsonAtomic } from "../files/json-files.js";
+import { compareCodeUnits } from "../collections.js";
 import { postReviewPath, postReviewWorktreePath, nativeLogPath, piLogPath, reviewRunSessionDir, reviewFixRef } from "../paths.js";
 import { reviewedAfterMerge, reviewRunConfig } from "../config/config-views.js";
 import { logEventBestEffort, TUMWATER_SOURCE, tryOrWarn } from "../events/events.js";
@@ -19,20 +20,21 @@ import { fixLine } from "../verdict/reply-contract.js";
 import { parseVerdict } from "./review-verdict.js";
 /** A commit's review is dropped, with a warning, after this many runs with no verdict. */
 export const POST_REVIEW_FAILURE_LIMIT = 3;
-/** The bar a day's post-merge rejections must reach before the `post-merge-churn` amber alert
- * (src/ui/team-alerts.ts) fires: one post-merge rejection is the tiering's ordinary cost, two in
- * a day is a role whose already-landed changes keep being turned back — the reviewer-fix signal
- * for an operator to narrow `review.afterMerge` or raise the authoring bar. */
+/** The bar a day's post-merge rejections must reach before the doctor's `post-merge churn` row
+ * fires: one post-merge rejection is the tiering's ordinary cost,
+ * two in a day is a role whose already-landed changes keep being turned back — the
+ * reviewer-fix signal for an operator to narrow `review.afterMerge` or raise the
+ * authoring bar. */
 export const POST_MERGE_REJECT_WARN = 2;
 /** How far back the post-merge-churn rule looks — one day, the 24 h event-window convention
- * every event-reading alert uses (PRIMARY_OVERWRITE_WINDOW_MS sorts beside it). */
+ * every event-reading doctor row uses. */
 export const POST_MERGE_REJECT_WINDOW_MS = 24 * 60 * 60_000;
 /** Group the `afterMerge: true` `review_rejected` events of `events` by base role — the same
  * `e.type === "review_rejected" && e.afterMerge === true` test the report fold
- * (src/report/report-fold.ts `postMergeRejectionsByRole`) applies, so the churn alert and the
+ * (src/report/report-fold.ts `postMergeRejectionsByRole`) applies, so the churn row and the
  * report cannot disagree on which rejections are post-merge. The key is the event's base role
  * (`baseRoleOf(eventRole(ev))`), not the raw source: an event's `source` is the runner id
- * (`bugfix-2`), and both the alert's remedy ("narrow `review.afterMerge`") and the scoped
+ * (`bugfix-2`), and both the row's remedy ("narrow `review.afterMerge`") and the scoped
  * report are keyed by base role, so one base role's churn must read as one row. Pre-merge
  * rejections and other event types contribute nothing. */
 export function postMergeRejectionCounts(events) {
@@ -45,10 +47,10 @@ export function postMergeRejectionCounts(events) {
     }
     return [...byRole.entries()]
         .map(([role, count]) => ({ role, count }))
-        .sort((a, b) => b.count - a.count || (a.role < b.role ? -1 : a.role > b.role ? 1 : 0));
+        .sort((a, b) => b.count - a.count || compareCodeUnits(a.role, b.role));
 }
-/** The one home of the trigger and selection the `post-merge-churn` alert (src/ui/team-alerts.ts)
- * and the doctor's `post-merge churn` row (src/doctor/doctor-project-checks.ts) share: whether
+/** The one home of the trigger and selection the doctor's `post-merge churn` row
+ * (src/doctor/doctor-project-checks.ts) reads: whether
  * the trailing `POST_MERGE_REJECT_WINDOW_MS` holds at least `POST_MERGE_REJECT_WARN` post-merge
  * `review_rejected` events, and, when it does, which roles and how many each. null when the
  * window holds fewer than the bar, or none — so the two surfaces cannot disagree on when churn
@@ -195,9 +197,9 @@ export async function reviewMergedCommit(root, config, entry, runGatePi, signal)
                 logEventBestEffort(root, { source: role, type: "review_verdict", head: commit, reason: verdict.reasons[0], durationMs, afterMerge: true });
             }
             // A rejecting review whose reply carries a FIX: line and whose worktree holds an edit
-            // survives as one fix commit on the review ref, kept for merge-post-review.ts to land on
-            // main through the ordinary change path. A clean worktree or a reply with no FIX line keeps
-            // today's outcomes and deletes the ref.
+            // survives as one fix commit on the review ref, kept for
+            // merge-post-review-drain.ts to land on main through the ordinary change path. A clean
+            // worktree or a reply with no FIX line keeps today's outcomes and deletes the ref.
             const paths = pi.ok && !pi.aborted ? fixLine(pi.verdictText ?? "") : null;
             if (paths && verdict.verdict === "reject" && (await gitTry(wt, "status", "--porcelain"))?.trim().length) {
                 // The self-fix chain's round is one past the reviewed commit's `Revision:` trailer; at
@@ -221,7 +223,7 @@ export async function reviewMergedCommit(root, config, entry, runGatePi, signal)
                 }
                 const fix = await commitReviewerFix(wt, commit, verdict.reasons, nextRound);
                 // Advance the review-fix ref from C to the new fix commit, so the repair is reachable and
-                // the merge-post-review landing (which checks the fix out by this sha) finds it.
+                // the merge-post-review-drain landing (which checks the fix out by this sha) finds it.
                 await setRef(root, fixRef, fix);
                 return { kind: "fixed", fix, reasons: verdict.reasons };
             }

package/dist/src/review/quarantine-render.js

@@ -6,6 +6,7 @@
  * so an operator can see which tests the gate is excusing and why. Pure over its inputs
  * (no I/O, no clock): every branch has its own unit tests. */
 import { plural } from "../text/phrases.js";
+import { compareCodeUnits } from "../collections.js";
 import { squash } from "../text/text.js";
 import { humanAgo } from "../text/datetime.js";
 import { quarantineWarning } from "../baseline/main-guardrails.js";
@@ -14,7 +15,7 @@ import { quarantineWarning } from "../baseline/main-guardrails.js";
  * through with `""` staying `""`. */
 export function quarantineRows(entries) {
     return [...entries]
-        .sort((a, b) => a.firstSeen - b.firstSeen || (a.test < b.test ? -1 : a.test > b.test ? 1 : 0))
+        .sort((a, b) => a.firstSeen - b.firstSeen || compareCodeUnits(a.test, b.test))
         .map((e, i) => ({
         position: i + 1,
         test: e.test,
@@ -43,12 +44,13 @@ export function renderQuarantine(rows, now) {
     }
     return lines.join("\n");
 }
-/** The Markdown section the Failures surfaces (the dashboard's Failures view and the TUI's
- * Failures pane) append below the failure digest — the read twin of the amber quarantine
- * alert, whose `See failures` action lands there. It reads the same `quarantineRows` rule as
- * `tumwater quarantine` (and shares its `quarantineWarning` phrase when one fires), so the CLI
- * and the always-on surfaces cannot disagree. Empty for an empty list, so a window with a
- * digest but a clean quarantine adds nothing. Pure over its inputs (no I/O, no clock). */
+/** The Markdown section the TUI's Failures pane appends below the failure digest — no longer
+ * reachable from the dashboard, whose Failures view paints the structured { warning, rows }
+ * card (quarantineViewRows) with a Release button per row instead. It reads the same
+ * `quarantineRows` rule as `tumwater quarantine` (and shares its `quarantineWarning` phrase
+ * when one fires), so the CLI and the TUI cannot disagree. Empty for an empty list, so a
+ * window with a digest but a clean quarantine adds nothing. Pure over its inputs (no I/O, no
+ * clock). */
 export function renderQuarantineSection(rows, now) {
     if (rows.length === 0)
         return "";
@@ -56,10 +58,26 @@ export function renderQuarantineSection(rows, now) {
     const warning = quarantineWarning(rows, now);
     if (warning !== null)
         lines.push(warning, "");
-    for (const r of rows) {
-        const filed = r.bug ? `filed: ${squash(r.bug, 80)}` : "not filed";
-        lines.push(`- ${squash(r.test, 80)} — first seen ${humanAgo(r.firstSeen, now)}, ` +
-            `last seen ${humanAgo(r.lastSeen, now)}, ${plural(r.count, "flake")} — ${filed}`);
+    for (const r of quarantineViewRows(rows, now)) {
+        // The test name is NOT squashed: the Failures Ctrl+X release editor matches the exact
+        // path the list shows (releaseQuarantinedTest(session.root, test)), so truncating here
+        // would make a title over the bound impossible to release. `tumwater quarantine` keeps
+        // its own numbered squash because --release <n> never needs the full name.
+        lines.push(`- ${r.test} — ${r.detail}`);
     }
     return lines.join("\n");
 }
+/** Build the structured rows for the dashboard's quarantine card: `quarantineViewRows` over the
+ * sorted `rows`, each `detail` the exact per-row text `renderQuarantineSection` prints after the
+ * test. */
+export function quarantineViewRows(rows, now) {
+    return rows.map((r) => {
+        const filed = r.bug ? `filed: ${squash(r.bug, 80)}` : "not filed";
+        return {
+            position: r.position,
+            test: r.test,
+            detail: `first seen ${humanAgo(r.firstSeen, now)}, ` +
+                `last seen ${humanAgo(r.lastSeen, now)}, ${plural(r.count, "flake")} — ${filed}`,
+        };
+    });
+}

package/dist/src/review/review-precheck.js

@@ -146,7 +146,8 @@ export async function gateBuildPrecheck(ctx, state, head, reject) {
             if (main.status === "red") {
                 // Main fails too: not this change's failure. Leave the commit (and with it the pin) and
                 // do not advance the discard counter — the transport-failure rule (BUGS.md 2026-09-20):
-                // nothing judged this diff. main-red.ts's gate and the bugfix handoff own the repair,
+                // nothing judged this diff. main-red.ts's healer hand-off (`mainRedHealNote`) and the
+                // bugfix handoff own the repair,
                 // and the orchestrator poll (requeueMainRedPin) re-queues the kept pin once main's head
                 // moves; leftover recovery holds it until then.
                 const detail = mainRedNotMine(main.sha);

package/dist/src/roles/role-catalog.js

@@ -4,7 +4,7 @@
  * in roles.ts. Pure catalog data — the shared instruction fragments role prompts embed live in
  * role-guidance.ts (import-only downward, so prompt assembly depends on both without a cycle).
  * roles.ts re-exports ROLES and Role, so every existing importer keeps its import path. */
-import { backlogMoveGuidance, CONVERGENCE_HOLD_MARKER, DECOMPOSITION_GUIDANCE, HELD_TAG_PREFIX, NEEDS_REPLAN_NOTE, NEEDS_REVIEW_NOTE, PLAN_QUEUE_GUIDANCE, PLAN_SIZING, PRIOR_HELD_PREFIX, searchGuidance, VALIDATION_GAP_GUIDANCE, VALIDATION_GAP_QUERY, VALIDATION_GAP_TALLY, WAITING_FOR_FAILURE_NOTE, WAITING_FOR_FAILURE_PREFIX, } from "./role-guidance.js";
+import { backlogMoveGuidance, CHECK_DECLARATION_MARKER, CONVERGENCE_HOLD_MARKER, DECOMPOSITION_GUIDANCE, NEEDS_REVIEW_NOTE, PLAN_QUEUE_GUIDANCE, PLAN_SIZING, searchGuidance, VALIDATION_GAP_GUIDANCE, VALIDATION_GAP_QUERY, VALIDATION_GAP_TALLY, } from "./role-guidance.js";
 import { roleCommitGrep } from "./legacy-role-ids.js";
 import { NOTHING_TO_DO } from "../verdict/reply-contract.js";
 /** The trailer the readme role's commits carry and its `git log --grep` reads back; git parses
@@ -24,25 +24,25 @@ export const ROLES = [
         tier: "default",
         title: "feature implementer",
         find: `Implement the SINGLE most valuable planned feature in PLANS.md that is not yet implemented.
+   A \`<no-check>\` block in your prompt names the \`## Planned\` entry marked ${CHECK_DECLARATION_MARKER}
+   — that project-check declaration outranks every other planned entry: implement it so a merge
+   makes it live (the doctor's \`check\` row ok, \`tumwater status --json\` with no \`noDeclaredCheck\`),
+   then mark it done. Do not chase an in-run re-read: while unmerged both still reflect the
+   pre-declaration state, so the merge confirms it.
+
    1. The prompt's <backlog-index> block lists PLANS.md's \`## Planned\` entries with each
       entry's line range; read the one you pick by that range.
    2. Pick one entry under \`## Planned\`, preferring ones marked ready or with a written plan.
       Skip entries the index block marks \`[blocked: …]\` — \`[blocked: requires …]\` (a
-      prerequisite has not merged), \`[blocked: refused]\`, \`[blocked: needs review]\` or
-      \`[blocked: needs replan]\`. Skip plans whose entry carries a Refused note, and skip
-      entries already carrying a **Needs review …** note or a ${NEEDS_REPLAN_NOTE}. If PLANS.md
+      prerequisite has not merged), \`[blocked: refused]\`, \`[blocked: needs review]\`.
+      Skip plans whose entry carries a Refused note, and skip
+      entries already carrying a **Needs review …** note. If PLANS.md
       is empty or everything is done, there is nothing to do.
    3. Read only the chosen entry's line range and the code it names.
    4. A plan too large to finish in this run is not split by you: append the note
       ${NEEDS_REVIEW_NOTE}
       under its heading, skip it, and implement the next available plan that fits. You may mark
-      several oversized entries while scanning, but land exactly one plan. The held tag you write
-      — \`${HELD_TAG_PREFIX}<N>)\` on a Needs-review note, \`${HELD_TAG_PREFIX}<H>)\` on a
-      Needs-replan note — is ONE past the count already on the entry: read your own or an earlier
-      mark's \`${HELD_TAG_PREFIX}N)\` tag, else the \`${PRIOR_HELD_PREFIX}<N>**\` line a lift left
-      behind, else start at 1 — never reset it while the same plan ping-pongs, so three holds
-      without a merge reach \`${HELD_TAG_PREFIX}3)\`. A plan that merged and left \`## Planned\`
-      carries no marker — the convergence backstop starts fresh there.
+      several oversized entries while scanning, but land exactly one plan.
    5. Implement it completely: code, tests, and any docs. The reviewer checks your diff against
       the entry's files-touched list and acceptance criteria, so land everything the entry
       promises, or update the entry to say what changed and why. When a plan's anchors no longer
@@ -64,8 +64,8 @@ than forcing it.`,
       latent-bug hunt at the end instead.
    2. Reproduce it if possible: a failing test or a scratch script. When it cannot be reproduced
       and this run made its failure message name the cause next time (or found it already does),
-      record a Progress note, write ${WAITING_FOR_FAILURE_NOTE} as its own line under the
-      heading, and end the run. Do not keep investigating without new evidence.
+      record a Progress note, write a **Needs review <YYYY-MM-DD> by bugfix: <what the next failure's message
+      will show>** note as its own line under the heading, and end the run. Do not keep investigating without new evidence.
    3. Fix it, and add a regression test that fails without the fix — run that test to watch it
       fail before the fix and pass after.
    4. Mark it fixed in BUGS.md — ${backlogMoveGuidance("BUGS.md", "## Open", "## Fixed", "BUGS-FIXED.md", "fixed")}
@@ -92,10 +92,17 @@ within that budget, there is nothing to do.`,
         find: `Write ONE concrete plan for what this project needs next. Do not implement it.
    1. Check what is already waiting: the prompt's <backlog-index> block lists PLANS.md's
       \`## Planned\` entries with each entry's line range.
+      - A \`<no-check>\` block in your prompt (this project declares no check and no declaration
+        plan waits) is this run's task over adding another plan: write the declaration entry it
+        names, headed \`### Declare the project's deterministic check\` and marked on its own line
+        with ${CHECK_DECLARATION_MARKER}, before anything else — the eligible-plan stop below
+        yields to it within an admitted run (a full plan backlog can still defer the plan role
+        before this prompt is built). A Needs-review lift and an assigned claim still
+        come first.
       - A plan carrying a ${NEEDS_REVIEW_NOTE} note outranks adding another plan: split it into
         independently mergeable sub-plans that cross-reference each other (per PLAN_SIZING below,
         each with its own acceptance criteria), then remove the note. That split is this run's task.
-      - A BUGS.md \`## Open\` entry carrying a ${NEEDS_REVIEW_NOTE} or ${NEEDS_REPLAN_NOTE} note
+      - A BUGS.md \`## Open\` entry carrying a ${NEEDS_REVIEW_NOTE} note
         (the feature or bugfix role parked it as too large for one run) also outranks adding another
         plan: resolve it in the same run by splitting it into independently fixable sub-bugs (each
         its own BUGS.md heading) then removing the note, or by lifting the note when the work does
@@ -106,19 +113,13 @@ within that budget, there is nothing to do.`,
         the quoted objections and the code they name and rewrite the plan so an implementation
         following it would answer each — correcting the approach or the anchors, tightening the
         acceptance criteria, or splitting it per PLAN_SIZING — then remove the note.
-      - A plan carrying a ${NEEDS_REPLAN_NOTE} note also outranks adding another plan: read the
-        quoted objections and the code they name, then rewrite the plan so an implementation
-        following it would answer them — correcting the approach or the anchors, tightening the
-        acceptance criteria, splitting it per PLAN_SIZING, or refusing it with the objection
-        recorded when it should not be done — and remove both the note and the quoted objections.
-      - When you lift a Needs-review or Needs-replan note (a split or a rewrite) and the change
-        has NOT merged, keep the held count instead of letting it reset: remove any existing
-        \`**Previously held N**\` line on the surviving parent and every child part the split
-        produces, then write \`${PRIOR_HELD_PREFIX}<N>**\` at the lifted note's count on the
-        parent and copy it to each child, so exactly one marker survives and heldCount reads the
-        lifted count everywhere — a merged parent (one whose plan left \`## Planned\`) leaves no
-        marker, and a note with no \`(held N)\` tag (the automatic convergence hold) is lifted
-        without writing a \`**Previously held 0**\` marker.
+      - A plan carrying a **Needs review …** note that quotes the reviewer's surviving objections
+        (a final-round rejection — \`rejected after <N> review rounds\`) also outranks adding another
+        plan: read the quoted objections and the code they name, then rewrite the plan so an
+        implementation following it would answer them — correcting the approach or the anchors,
+        tightening the acceptance criteria, splitting it per PLAN_SIZING, or refusing it with the
+        objection recorded when it should not be done — and remove both the note and the quoted
+        objections.
       - Otherwise, when PLANS.md \`## Planned\` already holds one more eligible plan than there
         are feature instances (one waiting per instance, plus one for the next planner run),
         end with ${NOTHING_TO_DO} — feature has work, and a waiting plan is refined by the
@@ -418,8 +419,8 @@ own response failing, so it is fileable as it stands under rule 1.
       outranks one that burned seconds — cite its cost when it is the reason you file.
    4. Before filing, check BUGS.md's ## Open section and \`git log ${roleCommitGrep("selfcheck")}\`
       for an entry that already names this cluster — no duplicate filings. When that Open entry
-      carries a ${WAITING_FOR_FAILURE_PREFIX}…** note and the cluster failed again after the
-      note's date, add the new occurrence under the entry (time, merged commit, failure message)
+      carries a **Needs review …** note naming what would make the failure show itself and the cluster
+      failed again after the note's date, add the new occurrence under the entry (time, merged commit, failure message)
       and delete the note line, instead of filing a duplicate.
    5. File it: cite the cluster's normalized key plus the correlated \`merged\` commit in the
       entry, so the bugfix role can reproduce it.