tumwater 0.2.0 → 0.3.0

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

@@ -1,13 +1,14 @@
-import { assertReportSinceMs, eventWindowCovers, readWindowEvents } from "../events/event-window.js";
+import { assertReportSinceMs, eventWindowCovers, readWindowEvents, sinceWindowTiming } from "../events/event-window.js";
 import { eventDayKey, eventRole } from "../events/event-read.js";
-import { baseRoleOf } from "../roles/loop-ids.js";
+import { baseRoleOf } from "../roles/runner-ids.js";
+import { scopeBases } from "../report/report-fold.js";
 import { timeAndSpend } from "./time-spend.js";
 import { dayAt, dayKey, dayWindow, formatDate } from "../text/datetime.js";
 import { describeStateChange, STATE_CHANGE_TOP, STATE_CHANGE_TYPES } from "./failure-state-change.js";
 import { clusterMessages, errorTextOrPlaceholder, truncateExample } from "./failure-cluster.js";
 import { addTo, getOrCreate, memoSetLru, rankByCount } from "../collections.js";
 import { firstReason } from "../text/phrases.js";
-import { sameStatIdentity, statOrNull } from "../files/files.js";
+import { sameStatIdentity, statIdentityOrZero, statOrNull } from "../files/files.js";
 import { nonNegativeNumber } from "../files/json-object.js";
 import { eventsLogPath } from "../paths.js";
 /** Caps that keep the digest bounded regardless of how bad the window was — the top-N
@@ -34,18 +35,18 @@ const MERGE_FAILURE_TOP = 10;
 const NO_MERGE_REASON = "no reason recorded";
 const MERGED_TOP = 10;
 const SUMMARY_MAX = 100;
-/** Keep only events that belong to one base role, so a scoped digest aggregates instances
- * (`feature-2`) into their group exactly as `report --role` and the per-role cap do. Loop
- * events match on their own loop id; the role-scoped harness transitions (a role pause, its
- * streak breaker, its cap, its fallback) log with loop "harness" and name the affected role
+/** Keep only events that belong to the scoped base roles, so a scoped digest aggregates instances
+ * (`feature-2`) into their group exactly as `report --role` and the per-role cap do. Role
+ * events match on their own role id; the role-scoped harness transitions (a role pause, its
+ * streak breaker, its cap, its fallback) log with source "harness" and name the affected role
  * in `role`, so those match on that field too — otherwise a scoped digest would drop exactly
- * the events that explain why the loop stopped. Applied to both partitions and the whole read,
+ * the events that explain why the role stopped. Applied to both partitions and the whole read,
  * so every section derived from them narrows. */
-function scopeToRole(events, base) {
-    return events.filter((ev) => baseRoleOf(eventRole(ev)) === base ||
+function scopeToRole(events, bases) {
+    return events.filter((ev) => bases.includes(baseRoleOf(eventRole(ev))) ||
         (STATE_CHANGE_TYPES.has(ev.type) &&
             typeof ev.role === "string" &&
-            baseRoleOf(ev.role) === base));
+            bases.includes(baseRoleOf(ev.role))));
 }
 /** Attach a section's window total (events the section owns, counted before any filter the
  * clustering applies — for rejections, the reasons-less ones too) to the clustered result. */
@@ -65,10 +66,10 @@ function messageSection(events, type, top, urgent) {
 }
 /** The merge-failure section: each blocked or conflicted `merge_failed` clusters on
  * (role, result, reason).
- * `merge_failed` carries no message, so the reason is the same role's nearest preceding
- * `warning` (a red merge check, a structure or fix-claim block) logged after that role's
- * previous merge outcome; with none, the placeholder. The total counts every blocked or
- * conflicted `merge_failed` in the window. */
+ * A `merge_failed` with a `reason` field uses it; an older one carries none, so the reason is
+ * the same role's nearest preceding `warning` (a red merge check, a structure or fix-claim
+ * block) logged after that role's previous merge outcome; with none, the placeholder. The
+ * total counts every blocked or conflicted `merge_failed` in the window. */
 function mergeFailureSection(events) {
     const ordered = [...events].sort((a, b) => a.ts - b.ts);
     const lastWarning = new Map();
@@ -91,7 +92,8 @@ function mergeFailureSection(events) {
                 continue;
             }
             total++;
-            const reason = lastWarning.get(role) ?? NO_MERGE_REASON;
+            const own = typeof ev.reason === "string" ? ev.reason.trim() : "";
+            const reason = own !== "" ? own : (lastWarning.get(role) ?? NO_MERGE_REASON);
             lastWarning.delete(role);
             messages.push({ message: `${result} — ${reason}`, role, ts: ev.ts, keyPrefix: `${role}\u0000` });
         }
@@ -102,8 +104,8 @@ function roleStats(events) {
     const byRole = new Map();
     const statsFor = (role) => getOrCreate(byRole, role, () => ({ runs: 0, errors: 0, quietKills: 0, rejections: 0 }));
     for (const ev of events) {
-        // Ticks are run_end events; a rejection is now recorded by the merge slot, AFTER the
-        // authoring tick has already ended `queued` (plans/merge-queue.md 3/5). review_rejected is
+        // Runs are run_end events; a rejection is now recorded by the merge slot, AFTER the
+        // authoring run has already ended `queued` (plans/merge-queue.md 3/5). review_rejected is
         // the one event every reject path logs exactly once (src/review/review.ts), so it — not a
         // run_end result no production path emits — is the rejection source.
         if (ev.type === "run_end") {
@@ -121,7 +123,7 @@ function roleStats(events) {
     return byRole;
 }
 /** Bounded memo of whole failure digests, keyed by root and day count. The dashboard's Failures
- * tab, the TUI's Ctrl+T pane, and every telemetry tick re-request the same digest, and the
+ * tab, the TUI's Ctrl+T pane, and every selfcheck run re-request the same digest, and the
  * collector re-reads and re-parses up to 2× the window's log bytes each time (~4 MB on this
  * repo's own log, growing toward the rotation cap). An unchanged log and window cost one stat
  * and return the prior result; any change — an append, a rotation, or a new local day —
@@ -131,10 +133,7 @@ const failureDigestCache = new Map();
 const FAILURE_DIGEST_CACHE_MAX = 8;
 /** The live log's identity, all zero when the file is missing (the empty-log case). */
 function digestStat(root) {
-    const st = statOrNull(eventsLogPath(root));
-    return st
-        ? { size: st.size, mtimeMs: st.mtimeMs, dev: st.dev, ino: st.ino }
-        : { size: 0, mtimeMs: 0, dev: 0, ino: 0 };
+    return statIdentityOrZero(statOrNull(eventsLogPath(root)));
 }
 /** Collect the digest over the last `days` local calendar days, reading a 2×-long window once
  * and partitioning it in memory so the delta against the preceding equal window costs no
@@ -144,10 +143,10 @@ export function collectFailureReport(root, days, role) {
     const now = new Date();
     const { from, to } = dayWindow(days, now);
     const priorFrom = formatDate(dayAt(days * 2 - 1, now));
-    const base = role === undefined ? undefined : baseRoleOf(role);
+    const bases = scopeBases(role);
     // The base role rides the key, so a scoped and a team digest of the same log cannot
     // collide in the memo.
-    const key = `${root}\u0000${days}\u0000${base ?? ""}`;
+    const key = `${root}\u0000${days}\u0000${bases?.join(",") ?? ""}`;
     const stat = digestStat(root);
     const cached = failureDigestCache.get(key);
     if (cached?.from === from &&
@@ -177,29 +176,30 @@ export function collectFailureReport(root, days, role) {
  * the window and the equal-length window immediately before it (the same current/prior split
  * the day collector builds, so the Deltas table compares like with like). The read starts at the
  * prior half's own day key, exactly as the day collector reads 2× its window; the cutoff instant
- * for coverage is the prior half's start, which a day key alone cannot prove. */
-export function collectFailureReportSince(root, sinceMs, role) {
+ * for coverage is the prior half's start, which a day key alone cannot prove. With `untilMs` the
+ * window is the bounded `[now - sinceMs, now - untilMs)`; the prior window then has that
+ * window's own length, `sinceMs - untilMs`. */
+export function collectFailureReportSince(root, sinceMs, role, untilMs) {
     assertReportSinceMs(sinceMs);
-    const now = Date.now();
-    const cutoff = now - sinceMs;
-    const priorFrom = cutoff - sinceMs;
+    const { now, cutoff, end, slice } = sinceWindowTiming(sinceMs, untilMs);
+    const length = sinceMs - (untilMs ?? 0);
+    const priorFrom = cutoff - length;
     const raw = readWindowEvents(root, dayKey(priorFrom));
     const current = [];
     const prior = [];
     for (const ev of raw.events) {
         if (typeof ev.ts !== "number")
             continue;
-        if (ev.ts >= cutoff && ev.ts <= now)
+        if (ev.ts >= cutoff && (untilMs === undefined ? ev.ts <= now : ev.ts < end))
             current.push(ev);
         else if (ev.ts >= priorFrom && ev.ts < cutoff)
             prior.push(ev);
     }
     return assembleFailureReport(current, prior, raw.events, eventWindowCovers(raw, priorFrom), raw.logState, {
-        days: Math.ceil(sinceMs / 86_400_000),
+        days: Math.ceil(length / 86_400_000),
         from: dayKey(cutoff),
-        to: dayKey(now),
-        sinceMs,
-        fromIso: new Date(cutoff).toISOString(),
+        to: dayKey(end),
+        ...slice,
     }, role);
 }
 /** Assemble the digest's sections from the two event partitions, the full read, and the
@@ -210,16 +210,16 @@ function assembleFailureReport(currentRaw, priorRaw, allEventsRaw, coversFullWin
     // Scope first when a role was named: every section below derives from these partitions, so
     // narrowing them at the source scopes outcomes, deltas, clusters, merges, and time/spend at
     // once. The unfiltered read's first event is kept for the retention line, so a scoped partial
-    // window still names when the log starts, not when the scoped role's own first tick does.
-    const base = role === undefined ? undefined : baseRoleOf(role);
-    const current = base === undefined ? currentRaw : scopeToRole(currentRaw, base);
-    const prior = base === undefined ? priorRaw : scopeToRole(priorRaw, base);
-    const allEvents = base === undefined ? allEventsRaw : scopeToRole(allEventsRaw, base);
+    // window still names when the log starts, not when the scoped role's own first run does.
+    const bases = scopeBases(role);
+    const current = bases === undefined ? currentRaw : scopeToRole(currentRaw, bases);
+    const prior = bases === undefined ? priorRaw : scopeToRole(priorRaw, bases);
+    const allEvents = bases === undefined ? allEventsRaw : scopeToRole(allEventsRaw, bases);
     const oldestRetained = allEventsRaw.length > 0 ? eventDayKey(allEventsRaw[0]) : null;
-    const tickEvents = current.filter((ev) => ev.type === "run_end");
+    const runEvents = current.filter((ev) => ev.type === "run_end");
     // Outcome table: one row per role, counts per result that occurred.
     const outcomeMap = new Map();
-    for (const ev of tickEvents) {
+    for (const ev of runEvents) {
         const role = eventRole(ev);
         const counts = getOrCreate(outcomeMap, role, () => ({}));
         const result = ev.result;
@@ -231,12 +231,12 @@ function assembleFailureReport(currentRaw, priorRaw, allEventsRaw, coversFullWin
     // (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 tick counts.
-    const { timeSpend, lossCauses, lossCausesHidden } = timeAndSpend(tickEvents, allEvents);
-    // Prompt-token telemetry: per role, the median prompt tokens a tick sent and how much of
+    // 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(tickEvents);
+    const promptStats = promptStatsFor(runEvents);
     // Deltas: current vs preceding window, per role.
     const curStats = roleStats(current);
     const prevStats = roleStats(prior);
@@ -260,8 +260,8 @@ 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 tick error: `state.lastError` is shared state the
-    // merge slot also writes, so a successful tick's `run_end` can carry a leftover merge failure's
+    // 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
@@ -271,7 +271,7 @@ function assembleFailureReport(currentRaw, priorRaw, allEventsRaw, coversFullWin
     // 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).
-    const errorEvents = tickEvents.filter((ev) => ev.result === "error" || ev.result === "main_red");
+    const errorEvents = runEvents.filter((ev) => ev.result === "error" || ev.result === "main_red");
     const errors = section(clusterMessages(errorEvents.map((ev) => ({
         message: errorTextOrPlaceholder(ev.error),
         role: eventRole(ev),
@@ -293,10 +293,10 @@ function assembleFailureReport(currentRaw, priorRaw, allEventsRaw, coversFullWin
     }), 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 tick ends
+    // 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 telemetry role can see a gate that keeps
-    // failing without misreading it as a tick error (BUGS.md 2026-09-21).
+    // `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
@@ -335,8 +335,8 @@ function assembleFailureReport(currentRaw, priorRaw, allEventsRaw, coversFullWin
     const windowComplete = coversFullWindow;
     return {
         ...window,
-        ...(base === undefined ? {} : { role: base }),
-        runs: tickEvents.length,
+        ...(bases === undefined ? {} : { role: bases.join(",") }),
+        runs: runEvents.length,
         hasEvents,
         emptyLog: !hasEvents && !coversFullWindow,
         logState,
@@ -365,9 +365,9 @@ function median(values) {
     const mid = Math.floor(sorted.length / 2);
     return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
 }
-/** Per-role prompt-token stats from the window's run_end events. Ticks without a
+/** Per-role prompt-token stats from the window's run_end events. Runs without a
  * `promptTokens` reading contribute nothing (and skip a role entirely), so the section only
- * appears once some tick ran on a build that records the field. Both reads go through
+ * appears once some run ran on a build that records the field. Both reads go through
  * nonNegativeNumber like every other event-log number: a torn or hand-edited line whose
  * `promptTokens` is `1e999` (JSON parses to Infinity) would otherwise land in the median and
  * the `preEditSum / promptSum` ratio as a non-finite value no report can render. */

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

@@ -1,14 +1,14 @@
 import { agree, plural } from "../text/phrases.js";
 import { shortSha, usd } from "../text/format.js";
-import { dayKey, dayLabel, formatTime, monthDay, reportWindow, sinceWindowLine } from "../text/datetime.js";
+import { boundedWindowLine, dayKey, dayLabel, formatTime, monthDay, reportWindow, sinceWindowLine } from "../text/datetime.js";
 import { durationLabel } from "../cli/cli-args.js";
 import { eventsRotationLabel } from "../events/events.js";
 import { eventTypeLabel } from "../events/event-labels.js";
 import { markdownTable } from "../text/markdown.js";
 /** A cluster's role list shows at most this many names before a "+N more" remainder. */
 const ROLES_SHOWN = 4;
-/** Every `TickResult`, mapped to its display/column rank. Typed as a `Record<TickResult, …>`,
- * so adding a result to src/tick/tick-outcome.ts and forgetting it here is a compile error — the
+/** Every `RunResult`, mapped to its display/column rank. Typed as a `Record<RunResult, …>`,
+ * so adding a result to src/run/run-outcome.ts and forgetting it here is a compile error — the
  * vocabulary is closed by the type checker, not by a comment. Order runs from "made progress"
  * through "did not" to the operator/shutdown outcomes. */
 const RESULT_ORDER = {
@@ -27,7 +27,7 @@ const RESULT_ORDER = {
     aborted: 12,
     user_aborted: 13,
 };
-/** The digest table's columns: every TickResult that at least one role logged in the window, ranked
+/** The digest table's columns: every RunResult that at least one role logged in the window, ranked
  * by RESULT_ORDER (ties alphabetical), so the table's shape follows the window's evidence instead
  * of the whole fixed vocabulary — a team with no errors gets no error column. */
 function columns(outcomes) {
@@ -41,13 +41,13 @@ function columns(outcomes) {
 /** A delta cell: `prev → cur`, with "—" on a side where the role had no runs (the "new role"
  * case for the preceding window), so an absence is never rendered as an infinite increase.
  * The displayed halves may be raw counts (stringified here) or pre-rendered rate strings —
- * the tick-count halves exist only to decide the "—", not to be printed. */
+ * the run-count halves exist only to decide the "—", not to be printed. */
 function deltaCell(prevRuns, prev, runs, cur) {
     return `${prevRuns === 0 ? "—" : prev} → ${runs === 0 ? "—" : cur}`;
 }
 /** The rejections column's cell. It cannot reuse deltaCell: a rejection is logged by the
  * merge slot, so its authoring run_end can fall in the other window — a role with a
- * rejection must show it even when its tick count is 0. Presence is judged on the rejection
+ * rejection must show it even when its run count is 0. Presence is judged on the rejection
  * count itself (the role is "absent" from the column only with neither runs nor rejections). */
 function rejectionCell(prevRuns, prevRejections, runs, rejections) {
     const prev = prevRuns === 0 && prevRejections === 0 ? "—" : String(prevRejections);
@@ -86,7 +86,7 @@ function rate(errors, runs) {
         return "—";
     return percent(errors, runs);
 }
-/** One time-and-spend cell: `x.x h · $y.yy`, or "—" when the role ended no tick on that
+/** One time-and-spend cell: `x.x h · $y.yy`, or "—" when the role ended no run on that
  * class — an absence is not a zero cost, for the same reason the Deltas cells say "—".
  * Hours carry one decimal: the digest prices agent-hours, and whole-hour rounding would
  * erase the difference between ten 200-ms errors and one 30-minute timeout. */
@@ -103,13 +103,13 @@ function hoursPhrase(ms) {
 }
 /** Render the digest as bounded Markdown. Byte bound: for a given team the tables grow only with
  * the number of configured roles (fixed by config), the RESULT_ORDER vocabulary (fixed by
- * src/tick/tick-outcome.ts), and the time-and-spend section's LOSS_TOP loss-cause lines (fixed by
+ * src/run/run-outcome.ts), and the time-and-spend section's LOSS_TOP loss-cause lines (fixed by
  * the cut), the merge-failure section's MERGE_FAILURE_TOP clusters (src/failure/failure-data.ts),
  * and every free string is capped — cluster examples at 120 chars (plus a `… (+N
  * chars)` cut marker when truncated, so a marked cut can never read as a complete message —
  * BUGS.md 2026-09-30), merged summaries at 100 under the same rule, a cluster's role list at 4
- * names plus a remainder count, and any loop id sliced to 32 chars (config validation already
- * refuses longer custom-loop ids, so the slice is a guard rather than the real bound). Cluster
+ * names plus a remainder count, and any role id sliced to 32 chars (config validation already
+ * refuses longer custom-role ids, so the slice is a guard rather than the real bound). Cluster
  * counts are capped at top-N, and the Team state changes section is capped at STATE_CHANGE_TOP
  * lines with each payload at STATE_CHANGE_MAX and each free field at STATE_CHANGE_FIELD_MAX; the
  * merged list at MERGED_TOP lines, each capped section closing with one remainder line when its cut
@@ -124,9 +124,12 @@ export function renderFailureMarkdown(data) {
     // The since shape prints the same sections as the day shape but labels its window as an
     // instant span (the wording renderSinceReportMarkdown uses); the day shape keeps its
     // day-window line. The empty branch follows the same split so neither claims the other's unit.
-    lines.push(data.sinceMs !== undefined
-        ? `${sinceWindowLine(durationLabel(data.sinceMs), data.fromIso)} · ${data.runs} runs`
-        : `${reportWindow(data.from, data.to, data.days, eventsRotationLabel())} · ${data.runs} runs`);
+    const bounded = data.sinceMs !== undefined && data.untilMs !== undefined && data.toIso !== undefined;
+    lines.push(bounded
+        ? `${boundedWindowLine(durationLabel(data.sinceMs), durationLabel(data.untilMs), data.fromIso, data.toIso)} · ${data.runs} runs`
+        : data.sinceMs !== undefined
+            ? `${sinceWindowLine(durationLabel(data.sinceMs), data.fromIso)} · ${data.runs} runs`
+            : `${reportWindow(data.from, data.to, data.days, eventsRotationLabel())} · ${data.runs} runs`);
     if (data.role !== undefined)
         lines.push(`role: ${data.role}`);
     if (data.logState === "unreadable")
@@ -134,9 +137,11 @@ export function renderFailureMarkdown(data) {
     else if (data.emptyLog)
         lines.push("no events retained");
     else if (!data.hasEvents) {
-        lines.push(data.sinceMs !== undefined
-            ? `no events in the last ${durationLabel(data.sinceMs)}`
-            : `no events in the last ${dayLabel(data.days)}`);
+        lines.push(bounded
+            ? `no events from ${durationLabel(data.sinceMs)} to ${durationLabel(data.untilMs)} ago`
+            : data.sinceMs !== undefined
+                ? `no events in the last ${durationLabel(data.sinceMs)}`
+                : `no events in the last ${dayLabel(data.days)}`);
     }
     else if (data.partial)
         lines.push(`partial: retained log starts ${data.oldestEventDate ?? "?"}`);
@@ -174,8 +179,9 @@ export function renderFailureMarkdown(data) {
     // 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
+    // no_change total — the quiet loss no cluster names, a review-rejected authoring span, a
+    // merge-conflict/merge-blocked authoring span, or a change the main watch reverted off
+    // main). Grows only with the role catalog
     // (fixed by config) and the LOSS_TOP cut, so the byte bound argued above holds.
     lines.push("");
     lines.push("## Time and spend by outcome");
@@ -204,7 +210,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 === "reverted"
+                                    ? `reverted off main on ${roleCell(c.roles[0] ?? "?")}${c.example ? ` — ${c.example}` : ""}`
+                                    : `${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
@@ -216,7 +224,7 @@ export function renderFailureMarkdown(data) {
         }
     }
     // Prompt-token telemetry: the per-role median prompt
-    // send and how much of the prompt budget goes out before a tick's first edit. Omitted
+    // 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.
     if (data.promptStats.length > 0) {
@@ -228,7 +236,7 @@ export function renderFailureMarkdown(data) {
         }
     }
     lines.push("");
-    lines.push(`## Deltas vs the preceding ${data.sinceMs !== undefined ? durationLabel(data.sinceMs) : dayLabel(data.days)}`);
+    lines.push(`## Deltas vs the preceding ${data.sinceMs !== undefined ? durationLabel(data.sinceMs - (data.untilMs ?? 0)) : dayLabel(data.days)}`);
     if (data.deltas.length === 0) {
         lines.push("_no runs in either window_");
     }
@@ -242,7 +250,7 @@ export function renderFailureMarkdown(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 tick, BUGS.md
+    // 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
     // by a title that reads as the error column alone.
     renderClusters(lines, "Top error clusters (red-main causes included)", data.errors, "run errors");
@@ -297,7 +305,7 @@ function roleList(roles) {
     const rest = roles.length - ROLES_SHOWN;
     return rest > 0 ? `${shown} +${rest} more` : shown;
 }
-/** Config validation caps custom-loop ids at 32 chars; this slice keeps the render's byte bound
+/** Config validation caps custom-role ids at 32 chars; this slice keeps the render's byte bound
  * true even for a hand-edited state file or a future catalog id. */
 function roleCell(role) {
     return role.slice(0, 32);

package/dist/src/failure/failure-state-change.js

@@ -1,4 +1,3 @@
-// vocabulary: plain
 /** Wording half of the failure digest's Team state changes section: which transition event types
  * the digest replays and the bounded one-liner describing each. Split out of failure-data.ts (the
  * same seam build/build-check-events.ts split from build/build-check.ts) so the per-event-type
@@ -7,15 +6,15 @@
  * sliced here, so the digest's byte bound holds for any event shape; the render adds the timestamp
  * and a roleCell-sliced role, so no unbounded field reaches the page. */
 import { truncateExample } from "./failure-cluster.js";
-import { cutSplitsSurrogatePair } from "../text/text.js";
+import { cutSplitsSurrogatePair, isNonBlankString } from "../text/text.js";
 import { finiteNumber, stringList } from "../files/json-object.js";
-import { ORCHESTRATOR_STOPPED, backendKindPhrase, budgetPhrase, teamPausePhrase, teamResumePhrase, holdPhrase, plural, rolePausePhrase, roleResumePhrase, rolesPhrase, shortSpanPhrase } from "../text/phrases.js";
+import { orchestratorStopPhrase, backendKindPhrase, budgetPhrase, teamPausePhrase, teamResumePhrase, holdPhrase, plural, rolePausePhrase, roleResumePhrase, rolesPhrase, shortSpanPhrase, PAUSE_EXPIRED_SUFFIX } from "../text/phrases.js";
 import { shortSha } from "../text/format.js";
-import { deferredReasonText } from "../events/event-format.js";
+import { deferredReasonText, untilClockSuffix } from "../events/event-format.js";
 /** The transition events the digest replays: the decisions the harness made about itself (the
  * cap/team gates and the team hold, the error-streak breaker's pause, the role's own daily
  * cap, model fallbacks, live-config edits, self-hosted redeploys, need-based deferrals,
- * orchestrator lifecycle). They are the evidence the telemetry role's load-bearing
+ * orchestrator lifecycle). They are the evidence the selfcheck role's load-bearing
  * rule asks it to judge — whether the harness's RESPONSE to a failure was wrong
  * (plans/telemetry-role.md) — so they sit beside the outcomes rather than being dropped. */
 export const STATE_CHANGE_TYPES = new Set([
@@ -101,20 +100,22 @@ export function describeStateChange(ev) {
             text = `budget resumed (${budgetPhrase(ev.spentUsd, ev.capUsd)} today)`;
             break;
         case "team_paused":
-            text = teamPausePhrase();
+            text = teamPausePhrase() + untilClockSuffix(ev.until);
+            if (isNonBlankString(ev.reason))
+                text += `: ${field(ev.reason)}`;
             break;
         case "team_resumed":
-            text = teamResumePhrase();
+            text = teamResumePhrase() + (ev.expired === true ? PAUSE_EXPIRED_SUFFIX : "");
             break;
         case "role_paused":
-            text = rolePausePhrase(field(ev.role ?? "?"));
+            text = rolePausePhrase(field(ev.role ?? "?")) + untilClockSuffix(ev.until);
             break;
         case "role_resumed":
-            text = roleResumePhrase(field(ev.role ?? "?"));
+            text = roleResumePhrase(field(ev.role ?? "?")) + (ev.expired === true ? PAUSE_EXPIRED_SUFFIX : "");
             break;
         case "role_streak_paused":
             // The error-streak breaker auto-paused the role; the digest names the depth so the
-            // operator can connect the pause to the failing ticks the clusters above show.
+            // operator can connect the pause to the failing runs the clusters above show.
             text = `role ${field(ev.role ?? "?")} paused — ${field(ev.streak ?? "?")} runs failed in a row`;
             break;
         case "role_cap_paused":
@@ -178,7 +179,11 @@ export function describeStateChange(ev) {
             break;
         }
         case "build_stale":
-            text = `update available (${plural(finiteNumber(ev.aheadCommits, 0), "commit")} behind) — restarts when idle`;
+            // The digest's 72-char line cap (§ STATE_CHANGE_MAX) cannot hold the full alert phrase
+            // "restarts after cooldown; work continues" beside the ahead-count prefix, so it says
+            // the same thing compactly: the restart waits while work continues (cooldown scope,
+            // PLANS.md 2026-10-23).
+            text = `update available (${plural(finiteNumber(ev.aheadCommits, 0), "commit")} behind) — restart waits; work continues`;
             break;
         case "restart_pending":
             text = `restart pending — main ${shortSha(ev.head)} green`;
@@ -199,7 +204,7 @@ export function describeStateChange(ev) {
             text = `tumwater started (pid ${field(ev.pid)}${ev.build ? `, build ${shortSha(ev.build)}` : ""})`;
             break;
         case "orchestrator_stop":
-            text = ORCHESTRATOR_STOPPED;
+            text = orchestratorStopPhrase(ev.cause);
             break;
         case "supervisor_exit":
             text = `tumwater down — restart ${field(ev.generation)} ${ev.signal ? `killed by ${field(ev.signal)}` : `exited ${field(ev.code)}`}${ev.reason ? `: ${field(ev.reason)}` : ""}`;