tumwater 0.4.0 → 0.4.2

package/dist/src/events/event-labels.js

@@ -84,7 +84,6 @@ export const EVENT_TYPE_LABELS = {
     model_fallback_ended: "fallback model ended",
     opencode_free_model_billed: "free model billed",
     image_blind: "image not seen",
-    image_reroute: "image sent to another model",
     build_stale: "update available",
     restart_pending: "update waits for idle",
     restart: "restarted onto update",

package/dist/src/events/event-legacy.js

@@ -34,7 +34,7 @@ const LEGACY_EVENT_TYPES = {
 /** The ordered field rewrites; later parts of the series append here, and they run in order. */
 const LEGACY_EVENT_REWRITES = [
     {
-        // The run number rode `tick` on run_start, run_end, prompt_taken, image_blind, image_reroute.
+        // The run number rode `tick` on run_start, run_end, prompt_taken, image_blind.
         name: "tick-to-run", // retired-name-ok: legacy name
         apply(ev) {
             const e = ev;

package/dist/src/events/event-window.js

@@ -349,7 +349,7 @@ export function eventsSince(root, sinceMs, now, keep = () => true) {
     return readEventsSince(root, sinceMs).events.filter((ev) => keep(ev) && ev.ts >= now - sinceMs);
 }
 /** The `--since` / `?sinceMs=` trailing window's bounds and identity slice, shared by the two
- * trailing-window collectors (`collectReportSince` in report-data.ts and
+ * trailing-window collectors (`collectReportSince` in report-since-data.ts and
  * `collectFailureReportSince` in failure-data.ts): an open-ended window (cutoff = now − sinceMs,
  * end = now) when `untilMs` is absent, else the bounded [now − sinceMs, now − untilMs). Both
  * collectors budget events with the same open/closed comparisons against `cutoff`/`end` (and

package/dist/src/events/events.js

@@ -58,8 +58,21 @@ export function logEvent(root, event) {
     ensureParentDir(file);
     rotateIfLarge(file, EVENTS_MAX_BYTES, EVENTS_KEEP);
     appendEventLine(file, JSON.stringify(full) + "\n");
-    for (const listener of listeners)
-        listener(full);
+    // The event is committed to the log before dispatch, so a subscriber's own failure must not
+    // make the write look like it failed to the caller, starve the other subscribers of this or
+    // any later event, or crash an unwrapped writer (the orchestrator's poll-loop warn site)
+    // for one listener's bug. Each listener is isolated: its throw is surfaced loudly on stderr
+    // (a terminal boundary, so the text is sanitized) and the dispatch moves on. The set is
+    // snapshotted so a listener that unsubscribes itself mid-dispatch cannot skip or double-run
+    // a sibling.
+    for (const listener of [...listeners]) {
+        try {
+            listener(full);
+        }
+        catch (err) {
+            process.stderr.write(`tumwater: event subscriber failed: ${stripTerminalControls(errorMessage(err))}\n`);
+        }
+    }
     return full;
 }
 /** Log a warning event: the harness's "something is off but the loop continues" signal. The

package/dist/src/events/notify.js

@@ -31,7 +31,7 @@ export const NOTIFY_EVENT_TYPES = [
     "role_streak_paused", // the error-streak circuit breaker auto-paused a role
     "role_cap_paused", // the role's own daily cost cap is reached — it stops starting runs
     "disk_low", // free space on the worktrees volume dropped below diskHoldGB — new work is held
-    "main_red_hold", // main's own check is red — every code role is held until a fix lands
+    "main_red_hold", // main's own check is red — roles keep authoring; the merge-side main_red pin queues a kept change until main moves past it, and the ci healer is handed the failing tests
     "merge_failed", // the merge slot finished without merging a change
     "restart_blocked", // the self-redeploy for main is blocked and latched — the team is stuck behind it
     "question_posted", // a merge posted a new QUESTIONS.md ## Open entry — only a human can answer it

package/dist/src/failure/failure-cluster.js

@@ -4,7 +4,7 @@
  * run-timeout shapes and their pooling, and the grouping engine live here rather than
  * inside either consumer. Pure string
  * and grouping logic — no event reads, no clock. */
-import { rankByCount } from "../collections.js";
+import { rankByCount, topAndHidden } from "../collections.js";
 import { cutSplitsSurrogatePair } from "../text/text.js";
 /** The verbatim example's trim bound, shared by the normalized key and each cluster's example.
  * The digest's other caps (top-N counts, summary width) live beside their consumers in
@@ -146,8 +146,9 @@ export function clusterMessages(messages, top, urgent) {
     // Clusters whose example is `urgent` rank ahead of every other, whatever their count, so a
     // once-per-window singleton survives the cut past recurring noise.
     const sorted = rankByCount(drafts.values(), (d) => d.count + (urgent?.(d.example) ? Number.MAX_SAFE_INTEGER / 2 : 0), (d) => d.key);
+    const { visible, hidden } = topAndHidden(sorted, top);
     return {
-        clusters: sorted.slice(0, top).map((d) => ({
+        clusters: visible.map((d) => ({
             key: d.key,
             count: d.count,
             roles: sortedRoles(d.roles),
@@ -155,6 +156,6 @@ export function clusterMessages(messages, top, urgent) {
             lastSeen: d.lastSeen,
             example: d.example,
         })),
-        hiddenClusters: Math.max(0, sorted.length - top),
+        hiddenClusters: hidden,
     };
 }

package/dist/src/failure/failure-data.js

@@ -217,7 +217,66 @@ function assembleFailureReport(currentRaw, priorRaw, allEventsRaw, coversFullWin
     const allEvents = bases === undefined ? allEventsRaw : scopeToRole(allEventsRaw, bases);
     const oldestRetained = allEventsRaw.length > 0 ? eventDayKey(allEventsRaw[0]) : null;
     const runEvents = current.filter((ev) => ev.type === "run_end");
-    // Outcome table: one row per role, counts per result that occurred.
+    const outcomes = outcomeRows(runEvents);
+    // Time and spend: the same runs priced by wall-clock span and cost, per role × outcome
+    // class, plus the loss ranking that weighs causes by agent-hours rather than run counts.
+    const { timeSpend, lossCauses, lossCausesHidden } = timeAndSpend(runEvents, allEvents);
+    // Prompt-token telemetry: per role, the median prompt tokens a run sent and how much of
+    // the prompt budget went out before the first edit. Only runs carrying the field count, so
+    // a pre-feature log leaves the section off entirely.
+    const promptStats = promptStatsFor(runEvents);
+    const deltas = deltaRows(current, prior);
+    const errors = errorSection(runEvents);
+    const warnings = warningSection(current);
+    const { rejections, postMergeRejections } = rejectionSection(current);
+    const mergeFailures = mergeFailureSection(current);
+    const reviewFailures = reviewFailureSection(current);
+    const { merged, mergedTotal } = mergedCommits(current);
+    const { stateChanges, stateChangesTotal } = stateChangeRows(current);
+    // Judged on the two partitions, not the whole read: the since collector reads from priorFrom's
+    // local day key, which can reach events earlier that day but before priorFrom — outside both
+    // windows. Counting those as "events" would suppress the empty-window line with a window that
+    // in fact held none. The day collector's read is exactly current ∪ prior (whole local days), so
+    // this changes nothing there.
+    const hasEvents = current.length > 0 || prior.length > 0;
+    const oldestEventDate = hasEvents ? oldestRetained : null;
+    // Complete only when the reader proves the whole read window (priorFrom..to) is covered:
+    // coversFullWindow fires when the oldest retained line predates priorFrom, so both the delta
+    // baseline and the current window reach their starts. Every retained event's day is >= priorFrom
+    // (the reader filters on it), so an event-side comparison can never strengthen that proof — the
+    // former `oldestEventDate < from` arm declared the digest complete while the prior half was still
+    // truncated, leaving the delta table to present a skewed baseline as a real trend. Only a proven
+    // window can be trusted as idle rather than truncated by rotation.
+    const windowComplete = coversFullWindow;
+    return {
+        ...window,
+        ...(bases === undefined ? {} : { role: bases.join(",") }),
+        runs: runEvents.length,
+        hasEvents,
+        emptyLog: !hasEvents && !coversFullWindow,
+        logState,
+        partial: hasEvents && !windowComplete,
+        oldestEventDate,
+        outcomes,
+        deltas,
+        timeSpend,
+        lossCauses,
+        lossCausesHidden,
+        promptStats,
+        errors,
+        warnings,
+        reviewFailures,
+        rejections,
+        postMergeRejections,
+        mergeFailures,
+        merged,
+        mergedTotal,
+        stateChanges,
+        stateChangesTotal,
+    };
+}
+/** Outcome table: one row per role, counts per result that occurred. */
+function outcomeRows(runEvents) {
     const outcomeMap = new Map();
     for (const ev of runEvents) {
         const role = eventRole(ev);
@@ -229,19 +288,14 @@ function assembleFailureReport(currentRaw, priorRaw, allEventsRaw, coversFullWin
     // sort-ascending-then-reverse idiom accidentally flipped equal-total ties into
     // reverse-alphabetical order; equal-total roles now follow the stated deterministic rule
     // (pinned by the tie test in test/failure-render.test.ts).
-    const outcomes = rankByCount([...outcomeMap.entries()].map(([role, counts]) => ({ role, counts })), (row) => total(row.counts), (row) => row.role);
-    // Time and spend: the same runs priced by wall-clock span and cost, per role × outcome
-    // class, plus the loss ranking that weighs causes by agent-hours rather than run counts.
-    const { timeSpend, lossCauses, lossCausesHidden } = timeAndSpend(runEvents, allEvents);
-    // Prompt-token telemetry: per role, the median prompt tokens a run sent and how much of
-    // the prompt budget went out before the first edit. Only runs carrying the field count, so
-    // a pre-feature log leaves the section off entirely.
-    const promptStats = promptStatsFor(runEvents);
-    // Deltas: current vs preceding window, per role.
+    return rankByCount([...outcomeMap.entries()].map(([role, counts]) => ({ role, counts })), (row) => total(row.counts), (row) => row.role);
+}
+/** Deltas: current vs preceding window, per role, ordered by runs descending. */
+function deltaRows(current, prior) {
     const curStats = roleStats(current);
     const prevStats = roleStats(prior);
     const roles = [...new Set([...curStats.keys(), ...prevStats.keys()])];
-    const deltas = roles
+    return roles
         .map((role) => {
         const c = curStats.get(role) ?? { runs: 0, errors: 0, quietKills: 0, rejections: 0 };
         const p = prevStats.get(role) ?? { runs: 0, errors: 0, quietKills: 0, rejections: 0 };
@@ -260,51 +314,65 @@ function assembleFailureReport(currentRaw, priorRaw, allEventsRaw, coversFullWin
         .sort((a, b) => b.runs - a.runs ||
         b.prevRuns - a.prevRuns ||
         a.role.localeCompare(b.role));
-    // Only runs that ENDED as errors carry a run error: `state.lastError` is shared state the
-    // merge slot also writes, so a successful run's `run_end` can carry a leftover merge failure's
-    // text (BUGS.md 2026-09-21). `main_red` joins them because its cause is written for that result
-    // — the baseline gate's own text (src/baseline/main-red.ts), never a leftover — so the
-    // section itemizes the outcome that blocks every merge instead of leaving it a bare count
-    // (BUGS.md 2026-09-28). The total therefore equals the Outcome table's error column PLUS its
-    // main_red cells; the render's section title says so, and merge failures still surface below.
-    // The selection predicate is the Outcome table's own — raw `error`/`main_red` results, no
-    // error-text test — so a malformed run_end that skipped the text can never be counted above
-    // but itemized nowhere: those events cluster under a placeholder cause, keeping the section's
-    // total equal to the tables it cross-checks against (BUGS.md 2026-09-30).
+}
+/** Only runs that ENDED as errors carry a run error: `state.lastError` is shared state the
+ * merge slot also writes, so a successful run's `run_end` can carry a leftover merge failure's
+ * text (BUGS.md 2026-09-21). `main_red` joins them because its cause is written for that result
+ * — the baseline gate's own text (src/baseline/main-red.ts), never a leftover — so the
+ * section itemizes the outcome that blocks every merge instead of leaving it a bare count
+ * (BUGS.md 2026-09-28). The total therefore equals the Outcome table's error column PLUS its
+ * main_red cells; the render's section title says so, and merge failures still surface below.
+ * The selection predicate is the Outcome table's own — raw `error`/`main_red` results, no
+ * error-text test — so a malformed run_end that skipped the text can never be counted above
+ * but itemized nowhere: those events cluster under a placeholder cause, keeping the section's
+ * total equal to the tables it cross-checks against (BUGS.md 2026-09-30). */
+function errorSection(runEvents) {
     const errorEvents = runEvents.filter((ev) => ev.result === "error" || ev.result === "main_red");
-    const errors = section(clusterMessages(errorEvents.map((ev) => ({
+    return section(clusterMessages(errorEvents.map((ev) => ({
         message: errorTextOrPlaceholder(ev.error),
         role: eventRole(ev),
         ts: ev.ts,
     })), ERROR_TOP), errorEvents.length);
-    const warnings = messageSection(current.map((ev) => ev.type === "warning" && typeof ev.message === "string"
+}
+/** Warnings cluster on the merged, often-reworded message; the re-input rewording pools the
+ * pre-07b2664a wording with its current form so a window spanning the change counts one cause. */
+function warningSection(current) {
+    return messageSection(current.map((ev) => ev.type === "warning" && typeof ev.message === "string"
         ? { ...ev, message: ev.message.replace(OLD_MERGE_CHECK_WORDING, "merge check failed (kept for one retry)") }
         : ev), "warning", WARNING_TOP, (m) => URGENT_WARNING.test(m));
-    // Rejections cluster on (role, reasons[0]) — the field the event feed renders — so two
-    // different rejection reasons from the same role stay separate rows, and an already-landed
-    // one (ev.afterMerge === true) splits apart from a same-reason pre-merge one so the row names
-    // the post-merge class whose rejection stands recorded on main. The section's total counts
-    // every `review_rejected` in the window, reasons or not, so it equals the Deltas column and
-    // the render's remainder line cross-checks against it.
+}
+/** Rejections cluster on (role, reasons[0]) — the field the event feed renders — so two
+ * different rejection reasons from the same role stay separate rows, and an already-landed
+ * one (ev.afterMerge === true) splits apart from a same-reason pre-merge one so the row names
+ * the post-merge class whose rejection stands recorded on main. The section's total counts
+ * every `review_rejected` in the window, reasons or not, so it equals the Deltas column and
+ * the render's remainder line cross-checks against it. The post-merge count rides along. */
+function rejectionSection(current) {
     const rejectedEvents = current.filter((ev) => ev.type === "review_rejected");
     const postMergeRejections = rejectedEvents.filter((ev) => ev.afterMerge === true).length;
-    const rejections = section(clusterMessages(rejectedEvents
-        .filter((ev) => Array.isArray(ev.reasons))
-        .map((ev) => {
-        const reasons = ev.reasons;
-        const message = ev.afterMerge === true ? `post-merge rejection: ${firstReason(reasons)}` : firstReason(reasons);
-        return { message, role: eventRole(ev), ts: ev.ts, keyPrefix: `${eventRole(ev)}\u0000` };
-    }), REJECTION_TOP), rejectedEvents.length);
-    const mergeFailures = mergeFailureSection(current);
-    // Merge review failures: a reviewer that could not return a parseable verdict (a dead
-    // backend, a transport error) fails closed and keeps the commit, but its authoring run ends
-    // `queued`/`no_change` — so the failure lives on the `review_failed` event, never on
-    // `run_end.error`. Clustered on their own so the selfcheck role can see a gate that keeps
-    // failing without misreading it as a run error (BUGS.md 2026-09-21).
-    const reviewFailures = messageSection(current, "review_failed", REVIEW_FAILURE_TOP);
-    // The newest MERGED_TOP merges, newest first. The pre-slice count rides along, as it does for
-    // the state changes below, so the render can name what the cut left out — a busy window must
-    // not read as a MERGED_TOP-merge day (BUGS.md 2026-09-23).
+    return {
+        rejections: section(clusterMessages(rejectedEvents
+            .filter((ev) => Array.isArray(ev.reasons))
+            .map((ev) => {
+            const reasons = ev.reasons;
+            const message = ev.afterMerge === true ? `post-merge rejection: ${firstReason(reasons)}` : firstReason(reasons);
+            return { message, role: eventRole(ev), ts: ev.ts, keyPrefix: `${eventRole(ev)}\u0000` };
+        }), REJECTION_TOP), rejectedEvents.length),
+        postMergeRejections,
+    };
+}
+/** Merge review failures: a reviewer that could not return a parseable verdict (a dead
+ * backend, a transport error) fails closed and keeps the commit, but its authoring run ends
+ * `queued`/`no_change` — so the failure lives on the `review_failed` event, never on
+ * `run_end.error`. Clustered on their own so the selfcheck role can see a gate that keeps
+ * failing without misreading it as a run error (BUGS.md 2026-09-21). */
+function reviewFailureSection(current) {
+    return messageSection(current, "review_failed", REVIEW_FAILURE_TOP);
+}
+/** The newest MERGED_TOP merges, newest first. The pre-slice count rides along, as it does for
+ * the state changes below, so the render can name what the cut left out — a busy window must
+ * not read as a MERGED_TOP-merge day (BUGS.md 2026-09-23). */
+function mergedCommits(current) {
     const allMerged = current
         .filter((ev) => ev.type === "merged")
         .map((ev) => ({
@@ -313,56 +381,17 @@ function assembleFailureReport(currentRaw, priorRaw, allEventsRaw, coversFullWin
         summary: typeof ev.summary === "string" ? truncateExample(ev.summary, SUMMARY_MAX) : "",
     }))
         .sort((a, b) => b.ts - a.ts);
-    const merged = allMerged.slice(0, MERGED_TOP);
-    // The harness's own decisions, newest STATE_CHANGE_TOP kept in chronological order. The
-    // description is bounded at collection so render stays a pure function of this data. The
-    // pre-slice count rides along so the render can say when it is showing a cut, not all of them.
+    return { merged: allMerged.slice(0, MERGED_TOP), mergedTotal: allMerged.length };
+}
+/** The harness's own decisions, newest STATE_CHANGE_TOP kept in chronological order. The
+ * description is bounded at collection so render stays a pure function of this data. The
+ * pre-slice count rides along so the render can say when it is showing a cut, not all of them. */
+function stateChangeRows(current) {
     const allStateChanges = current
         .filter((ev) => STATE_CHANGE_TYPES.has(ev.type))
         .map((ev) => ({ ts: ev.ts, role: eventRole(ev), description: describeStateChange(ev) }))
         .sort((a, b) => a.ts - b.ts);
-    const stateChanges = allStateChanges.slice(-STATE_CHANGE_TOP);
-    // Judged on the two partitions, not the whole read: the since collector reads from priorFrom's
-    // local day key, which can reach events earlier that day but before priorFrom — outside both
-    // windows. Counting those as "events" would suppress the empty-window line with a window that
-    // in fact held none. The day collector's read is exactly current ∪ prior (whole local days), so
-    // this changes nothing there.
-    const hasEvents = current.length > 0 || prior.length > 0;
-    const oldestEventDate = hasEvents ? oldestRetained : null;
-    // Complete only when the reader proves the whole read window (priorFrom..to) is covered:
-    // coversFullWindow fires when the oldest retained line predates priorFrom, so both the delta
-    // baseline and the current window reach their starts. Every retained event's day is >= priorFrom
-    // (the reader filters on it), so an event-side comparison can never strengthen that proof — the
-    // former `oldestEventDate < from` arm declared the digest complete while the prior half was still
-    // truncated, leaving the delta table to present a skewed baseline as a real trend. Only a proven
-    // window can be trusted as idle rather than truncated by rotation.
-    const windowComplete = coversFullWindow;
-    return {
-        ...window,
-        ...(bases === undefined ? {} : { role: bases.join(",") }),
-        runs: runEvents.length,
-        hasEvents,
-        emptyLog: !hasEvents && !coversFullWindow,
-        logState,
-        partial: hasEvents && !windowComplete,
-        oldestEventDate,
-        outcomes,
-        deltas,
-        timeSpend,
-        lossCauses,
-        lossCausesHidden,
-        promptStats,
-        errors,
-        warnings,
-        reviewFailures,
-        rejections,
-        postMergeRejections,
-        mergeFailures,
-        merged,
-        mergedTotal: allMerged.length,
-        stateChanges,
-        stateChangesTotal: allStateChanges.length,
-    };
+    return { stateChanges: allStateChanges.slice(-STATE_CHANGE_TOP), stateChangesTotal: allStateChanges.length };
 }
 /** Median of a non-empty numeric list (the mean of the two middles for an even count). */
 function median(values) {
@@ -384,12 +413,14 @@ function promptStatsFor(runs) {
         if (prompt === 0 && preEdit === 0)
             continue;
         const role = eventRole(ev);
-        const acc = getOrCreate(byRole, role, () => ({ prompts: [], promptSum: 0, preEditSum: 0 }));
+        const acc = getOrCreate(byRole, role, () => ({ prompts: [], promptSum: 0, preEditSum: 0, cacheReadSum: 0 }));
         if (prompt > 0) {
             acc.prompts.push(prompt);
             acc.promptSum += prompt;
         }
         acc.preEditSum += preEdit;
+        const cacheRead = nonNegativeNumber(ev.cacheReadTokens, 0);
+        acc.cacheReadSum += cacheRead;
     }
     return [...byRole.entries()]
         .filter(([, acc]) => acc.promptSum > 0)
@@ -398,6 +429,7 @@ function promptStatsFor(runs) {
         runs: acc.prompts.length,
         medianPromptTokens: median(acc.prompts),
         preEditShare: acc.preEditSum / acc.promptSum,
+        ...(acc.cacheReadSum > 0 ? { cacheReadShare: acc.cacheReadSum / acc.promptSum } : {}),
     }))
         .sort((a, b) => a.role.localeCompare(b.role));
 }

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

@@ -119,6 +119,19 @@ function hoursPhrase(ms) {
  * I/O, no clock reads. */
 export function renderFailureMarkdown(data) {
     const lines = [];
+    pushDigestHeader(lines, data);
+    pushStateChanges(lines, data);
+    pushOutcomeTable(lines, data);
+    pushTimeAndSpend(lines, data);
+    pushPromptStats(lines, data);
+    pushDeltas(lines, data);
+    pushClusterSections(lines, data);
+    pushMergedSection(lines, data);
+    return lines.join("\n");
+}
+/** The digest's title, blank line, window line (bounded/since/day) and log-state lines. Owns the
+ * local `bounded` const the empty branch reads, so the since-vs-day split stays in one place. */
+function pushDigestHeader(lines, data) {
     lines.push("# tumwater failure digest");
     lines.push("");
     // The since shape prints the same sections as the day shape but labels its window as an
@@ -145,10 +158,12 @@ export function renderFailureMarkdown(data) {
     }
     else if (data.partial)
         lines.push(`partial: retained log starts ${data.oldestEventDate ?? "?"}`);
-    // The causal frame before the counts: what the team DID in the window, so the reader can ask
-    // whether the harness's response was right. Omitted entirely when the window held none. When
-    // the newest-N cap cut the window's transitions, the remainder is named — a quiet window (no
-    // line) and a truncated one must not look the same.
+}
+/** The causal frame before the counts: what the team DID in the window, so the reader can ask
+ * whether the harness's response was right. Omitted entirely when the window held none. When
+ * the newest-N cap cut the window's transitions, the remainder is named — a quiet window (no
+ * line) and a truncated one must not look the same. */
+function pushStateChanges(lines, data) {
     if (data.stateChanges.length > 0) {
         lines.push("");
         // A scoped digest retitles the section: its transitions are the named role's, so the
@@ -161,6 +176,10 @@ export function renderFailureMarkdown(data) {
         if (hidden > 0)
             lines.push(`+${hidden} older transitions hidden`);
     }
+}
+/** The outcome table: the column set derived from the window's evidence, then the role × result
+ * table, or its placeholder when no run finished. */
+function pushOutcomeTable(lines, data) {
     const cols = columns(data.outcomes);
     lines.push("");
     lines.push("## Outcome by role");
@@ -176,12 +195,16 @@ export function renderFailureMarkdown(data) {
             ...cols.map((c) => String(row.counts[c] ?? 0)),
         ]), ["left", ...cols.map(() => "right")]));
     }
-    // The same runs priced by what they cost, so a 30-minute timeout outranks ten 200-ms
-    // errors that the Outcome table above weighs equally. Two parts: the role × class table of
-    // hours and dollars, then the top loss causes by time (an error cluster, a role's
-    // no_change total — the quiet loss no cluster names, a review-rejected authoring span, or a
-    // merge-conflict/merge-blocked authoring span). Grows only with the role catalog
-    // (fixed by config) and the LOSS_TOP cut, so the byte bound argued above holds.
+}
+/** The same runs priced by what they cost, so a 30-minute timeout outranks ten 200-ms
+ * errors that the Outcome table above weighs equally. Two parts: the role × class table of
+ * hours and dollars, then the top loss causes by time (an error cluster, a role's
+ * no_change total — the quiet loss no cluster names, a review-rejected authoring span, a
+ * merge-conflict/merge-blocked authoring span, or a context cut-off (a run truncated at
+ * its model's ceiling, a cost of length the harness resumes rather than quiet idleness).
+ * Grows only with the role catalog (fixed by config) and the LOSS_TOP cut, so the byte
+ * bound argued above holds. */
+function pushTimeAndSpend(lines, data) {
     lines.push("");
     lines.push("## Time and spend by outcome");
     if (data.timeSpend.length === 0) {
@@ -209,7 +232,9 @@ export function renderFailureMarkdown(data) {
                             ? `refused on ${roleCell(c.roles[0] ?? "?")}${c.example ? ` — ${c.example}` : ""}`
                             : c.kind === "merge-conflict" || c.kind === "merge-blocked"
                                 ? `${c.kind} authoring on ${roleCell(c.roles[0] ?? "?")}${c.example ? ` — ${c.example}` : ""}`
-                                : `${c.example} (${roleList(c.roles)})`;
+                                : c.kind === "cutoff"
+                                    ? `context cut-off on ${roleCell(c.roles[0] ?? "?")}`
+                                    : `${c.example} (${roleList(c.roles)})`;
                 lines.push(`- ${hoursPhrase(c.ms)} · ${usd(c.costUsd)} — ${plural(c.runs, "run")}: ${cause}`);
             }
             // Mark the top-5 cut the way the cluster sections mark theirs: a capped ranking that
@@ -220,18 +245,28 @@ export function renderFailureMarkdown(data) {
             }
         }
     }
-    // Prompt-token telemetry: the per-role median prompt
-    // send and how much of the prompt budget goes out before a run's first edit. Omitted
-    // entirely when no run_end in the window carries the fields, so old logs and their golden
-    // digests render unchanged.
+}
+/** Prompt-token telemetry: the per-role median prompt
+ * send and how much of the prompt budget goes out before a run's first edit, plus each
+ * role's cache-read share of its prompt bill when some run reported cache reads. Omitted
+ * entirely when no run_end in the window carries the fields, so old logs and their golden
+ * digests render unchanged. */
+function pushPromptStats(lines, data) {
     if (data.promptStats.length > 0) {
         lines.push("");
         lines.push("## Prompt tokens by role");
         for (const row of data.promptStats) {
             const share = percent(row.preEditShare, 1);
-            lines.push(`- ${roleCell(row.role)}: median ${row.medianPromptTokens} prompt tokens/run · ${share} before first edit`);
+            let line = `- ${roleCell(row.role)}: median ${row.medianPromptTokens} prompt tokens/run · ${share} before first edit`;
+            if (row.cacheReadShare !== undefined) {
+                line += ` · ${percent(row.cacheReadShare, 1)} cache reads`;
+            }
+            lines.push(line);
         }
     }
+}
+/** The deltas table: this window's runs/rates vs the preceding one, or its placeholder. */
+function pushDeltas(lines, data) {
     lines.push("");
     lines.push(`## Deltas vs the preceding ${data.sinceMs !== undefined ? durationLabel(data.sinceMs - (data.untilMs ?? 0)) : dayLabel(data.days)}`);
     if (data.deltas.length === 0) {
@@ -246,6 +281,10 @@ export function renderFailureMarkdown(data) {
             rejectionCell(d.prevRuns, d.prevRejections, d.runs, d.rejections),
         ])));
     }
+}
+/** The five cluster sections in their current order, plus the post-merge-rejection line between
+ * the review/rejection clusters and the merge-failure section. */
+function pushClusterSections(lines, data) {
     // The title restates the section's contract: its total now covers the Outcome table's error
     // column AND its main_red cells (the baseline gate's own cause rides the run, BUGS.md
     // 2026-09-28), so an operator cross-checking counts against the tables above is not misled
@@ -258,6 +297,9 @@ export function renderFailureMarkdown(data) {
         lines.push(`_${plural(data.postMergeRejections, "post-merge rejection", "post-merge rejections")} — the commit already reached main, so it stays there with the reviewer's recorded reasons (never re-reviewed — Forward, never back)_`);
     }
     renderClusters(lines, "Merge failures", data.mergeFailures, "merge failures");
+}
+/** The merged list, with its remainder line when the newest-N cut dropped anything. */
+function pushMergedSection(lines, data) {
     lines.push("");
     lines.push("## Merged in the window");
     if (data.merged.length === 0) {
@@ -272,7 +314,6 @@ export function renderFailureMarkdown(data) {
         if (hidden > 0)
             lines.push(`+${hidden} older merges not listed`);
     }
-    return lines.join("\n");
 }
 /** Push one "Top … clusters" section: each cluster as a `**N×** roles · first → last —
  * example` line (the collector supplies the order and the top-N cut), or a single `no <noun> in the