tumwater 0.2.0 → 0.3.0

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

@@ -11,10 +11,10 @@ import { canonicalRoleId } from "../roles/legacy-role-ids.js";
  * here would show `dedupe` while the role is still `dry`. */
 /** An old event type name → today's name. */
 const LEGACY_EVENT_TYPES = {
-    tick_start: "run_start", // vocabulary-ok: legacy event name read from old logs
-    tick_end: "run_end", // vocabulary-ok: legacy event name read from old logs
-    tick_deferred: "run_deferred", // vocabulary-ok: legacy event name read from old logs
-    tick_aborted: "run_aborted", // vocabulary-ok: legacy event name read from old logs
+    tick_start: "run_start", // vocabulary-ok: legacy event name read from old logs // retired-name-ok: legacy name
+    tick_end: "run_end", // vocabulary-ok: legacy event name read from old logs // retired-name-ok: legacy name
+    tick_deferred: "run_deferred", // vocabulary-ok: legacy event name read from old logs // retired-name-ok: legacy name
+    tick_aborted: "run_aborted", // vocabulary-ok: legacy event name read from old logs // retired-name-ok: legacy name
     // retired-name-ok:start old event names
     fleet_paused: "team_paused", // vocabulary-ok: legacy event name read from old logs
     fleet_resumed: "team_resumed", // vocabulary-ok: legacy event name read from old logs
@@ -24,23 +24,29 @@ const LEGACY_EVENT_TYPES = {
     landed: "merge_done", // vocabulary-ok: legacy event name read from old logs
     land_failed: "merge_failed", // vocabulary-ok: legacy event name read from old logs
     // retired-name-ok:end
+    // retired-name-ok:start old subscription-window event names
+    claude_window_reserved: "subscription_window_reserved", // vocabulary-ok: legacy event name read from old logs
+    claude_window_warning: "subscription_window_warning", // vocabulary-ok: legacy event name read from old logs
+    claude_window_limited: "subscription_window_limited", // vocabulary-ok: legacy event name read from old logs
+    claude_window_reset: "subscription_window_reset", // vocabulary-ok: legacy event name read from old logs
+    // retired-name-ok:end
 };
 /** 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.
-        name: "tick-to-run",
+        name: "tick-to-run", // retired-name-ok: legacy name
         apply(ev) {
             const e = ev;
-            if ("tick" in e && !("run" in e)) { // vocabulary-ok: legacy field name read from old logs
-                e.run = e.tick; // vocabulary-ok: legacy field name read from old logs
-                delete e.tick; // vocabulary-ok: legacy field name read from old logs
+            if ("tick" in e && !("run" in e)) { // vocabulary-ok: legacy field name read from old logs // retired-name-ok: legacy field
+                e.run = e.tick; // vocabulary-ok: legacy field name read from old logs // retired-name-ok: legacy field
+                delete e.tick; // vocabulary-ok: legacy field name read from old logs // retired-name-ok: legacy field
             }
         },
     },
     {
         // build_check.scope and conflict_handback.reason said "landing" for what is now "merge".
-        name: "landing-to-merge",
+        name: "merge-scope-value",
         apply(ev) {
             const e = ev;
             if (e.type === "build_check" && e.scope === "landing")
@@ -57,14 +63,14 @@ const LEGACY_EVENT_REWRITES = [
             if (e.type !== "slot_wait")
                 return;
             if (e.purpose === "tick")
-                e.purpose = "run"; // vocabulary-ok: legacy event value read from old logs
+                e.purpose = "run"; // vocabulary-ok: legacy event value read from old logs // retired-name-ok: legacy name
             if (e.purpose === "vet")
                 e.purpose = "verify"; // vocabulary-ok: legacy event value read from old logs
         },
     },
     {
         // The restart event's drain fields became finish fields.
-        name: "restart-drain-to-finish",
+        name: "restart-finish-fields",
         apply(ev) {
             const e = ev;
             if (e.type !== "restart")
@@ -88,16 +94,16 @@ const LEGACY_EVENT_REWRITES = [
         // call site that still passes `source: "harness"` (the warn helpers' callers) maps too.
         // Kept permanently though no TypeScript type accepts `loop` any more: old logs and a
         // still-running old supervisor keep writing it, so the read path and logEvent need this.
-        name: "loop-to-source",
+        name: "writer-id-to-source",
         apply(ev) {
             const e = ev;
-            if (typeof e.loop === "string") { // vocabulary-ok: legacy field name read from old logs
+            if (typeof e.loop === "string") { // vocabulary-ok: legacy field name read from old logs // retired-name-ok: legacy field, read permanently
                 if (e.type === "claim" && e.source === "staged" && !("origin" in e)) {
                     e.origin = e.source;
                     delete e.source;
                 }
-                e.source = e.loop; // vocabulary-ok: legacy field name read from old logs
-                delete e.loop; // vocabulary-ok: legacy field name read from old logs
+                e.source = e.loop; // vocabulary-ok: legacy field name read from old logs // retired-name-ok: legacy field, read permanently
+                delete e.loop; // vocabulary-ok: legacy field name read from old logs // retired-name-ok: legacy field, read permanently
             }
             if (e.source === "harness")
                 e.source = TUMWATER_SOURCE; // vocabulary-ok: legacy event source read from old logs
@@ -115,6 +121,24 @@ const LEGACY_EVENT_REWRITES = [
                 e.role = canonicalRoleId(e.role);
         },
     },
+    {
+        // The four subscription-window events now name their backend (plans/codex-backend.md part
+        // 2b/9). The old claude_window_* names map (above) to subscription_window_* with no
+        // backend, so a line written before the rename gets `backend: "claude"` here; a current
+        // line written with its own backend is left alone. Kept permanently: a still-running old
+        // supervisor and old rotated logs keep writing the old names without a backend.
+        name: "subscription-window-backend",
+        apply(ev) {
+            const e = ev;
+            if (e.type === "subscription_window_reserved" ||
+                e.type === "subscription_window_warning" ||
+                e.type === "subscription_window_limited" ||
+                e.type === "subscription_window_reset") {
+                if (typeof e.backend !== "string")
+                    e.backend = "claude";
+            }
+        },
+    },
 ];
 /** Today's name for an old event type name; any other string comes back unchanged. */
 export function canonicalEventType(name) {

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

@@ -6,7 +6,7 @@ import { readTailTextWithEnd } from "../files/tail.js";
 import { normalizeLegacyEvent } from "./event-legacy.js";
 /** The READ side of the event feed: everything that consumes events.jsonl after the fact —
  * parseEventLine's skip-without-failing rule, the per-event query conventions (eventDayKey,
- * eventRole, eventUsage, tickStartMap/tickSpanMs) the reports and history share, and the
+ * eventRole, eventUsage, runStartMap/runSpanMs) the reports and history share, and the
  * stat-cached backwards tail scan readEvents is built on. The WRITE side — logEvent/warnEvent,
  * the append path with its torn-tail repair, rotation, and the subscriber list — and the
  * HarnessEvent shape itself live beside it in events.ts; the split keeps the append path's
@@ -31,7 +31,7 @@ export function parseEventLine(line) {
  * numeric timestamp. The one day-bucketing rule the windowed reader (event-window.ts) and the
  * usage/failure reports all apply, so they agree on what counts as one day. A `ts` that is
  * present but not finite is as unusable as an absent one and reads null too (the same
- * finiteness check eventTick/eventUsage/tickStartMap/tickSpanMs apply): bare
+ * finiteness check eventRun/eventUsage/runStartMap/runSpanMs apply): bare
  * `typeof Infinity === "number"` let a JSON `1e999` through to dayKey, whose
  * `new Date(Infinity)` rendered the bucket key "NaN-NaN-NaN" and filed the event under a day
  * no window can name. */
@@ -39,19 +39,19 @@ export function eventDayKey(ev) {
     const ts = finiteNumber(ev.ts, null);
     return ts === null ? null : dayKey(ts);
 }
-/** The loop id an event is filed under, or "?" when absent or empty — the guard the usage
+/** The role id an event is filed under, or "?" when absent or empty — the guard the usage
  * report and the failure digest both apply when grouping by role. */
 export function eventRole(ev) {
     return typeof ev.source === "string" && ev.source !== "" ? ev.source : "?";
 }
-/** The tick number an event names, or 0 when it is absent or non-finite. The one guard every
- * display surface applies to the loosened `tick` field: an event log is read without a shape
- * filter, so a torn or hand-edited line can carry no tick (String(undefined) printed "#undefined"
- * in the feed) or a non-numeric one (String(Number(…)) printed "#NaN" in history). Ticks are
- * 1-based — the loop increments state.runs before logging its first tick — so 0 is visibly not
- * a real tick, the same corrupt-value-reads-as-0 rule gigabytes and the failure digest's
+/** The run number an event names, or 0 when it is absent or non-finite. The one guard every
+ * display surface applies to the loosened `run` field: an event log is read without a shape
+ * filter, so a torn or hand-edited line can carry no run (String(undefined) printed "#undefined"
+ * in the feed) or a non-numeric one (String(Number(…)) printed "#NaN" in history). Runs are
+ * 1-based — the role increments state.runs before logging its first run — so 0 is visibly not
+ * a real run, the same corrupt-value-reads-as-0 rule gigabytes and the failure digest's
  * aheadCommits apply, kept finite so a JSON consumer never sees NaN's null stand-in. */
-export function eventTick(ev) {
+export function eventRun(ev) {
     return finiteNumber(ev.run, 0);
 }
 /** The usage numbers an event records (`run_end`'s own run, `merge_done`'s merge slot):
@@ -68,15 +68,15 @@ export function eventUsage(ev) {
     const notionalCostUsd = finiteNumber(ev.notionalCostUsd, 0);
     return { tokens, costUsd, notionalCostUsd };
 }
-/** Pair the run_start events of `events` by tick, keyed `${loop}#${tick}` → the start event
+/** Pair the run_start events of `events` by run, keyed `${role}#${run}` → the start event
  * itself — the one home of that pairing and its key format, shared by the timestamps
- * (tickStartMap), the models (tickStartModelMap), and the tick drill-down's duration
- * (tick-detail-data.ts uses tickSpanMs' key). A run_start whose `ts` is not a finite number is
+ * (runStartMap), the models (runStartModelMap), and the run drill-down's duration
+ * (run-detail-data.ts uses runSpanMs' key). A run_start whose `ts` is not a finite number is
  * as unusable as an absent one and adds no entry either (the same "a torn or hand-edited line
- * carries no usable timestamp" policy eventTick/eventUsage apply to their fields), so every
+ * carries no usable timestamp" policy eventRun/eventUsage apply to their fields), so every
  * entry is a real start the projections below can trust. Private: external consumers read one
  * of the projections, not this raw pairing. */
-function runStartMap(events) {
+function runStartEvents(events) {
     const starts = new Map();
     for (const e of events) {
         const ts = finiteNumber(e.ts, null);
@@ -85,54 +85,54 @@ function runStartMap(events) {
     }
     return starts;
 }
-/** The run_start pairing's start epoch ms: `${loop}#${tick}` → start epoch ms, the projection
- * of runStartMap onto each event's `ts` — shared by `tumwater history`'s row spans
- * (history-data.ts), the failure digest's time-and-spend fold (time-spend.ts), and the tick
- * drill-down's duration (tick-detail-data.ts), so those consumers cannot drift into different
- * notions of a tick's span. A run_end whose start is not in `events` (log rotation cut it, or
- * the tick was skipped before any start logged) has no entry; callers decide what an unpaired
+/** The run_start pairing's start epoch ms: `${role}#${run}` → start epoch ms, the projection
+ * of runStartEvents onto each event's `ts` — shared by `tumwater history`'s row spans
+ * (history-data.ts), the failure digest's time-and-spend fold (time-spend.ts), and the run
+ * drill-down's duration (run-detail-data.ts), so those consumers cannot drift into different
+ * notions of a run's span. A run_end whose start is not in `events` (log rotation cut it, or
+ * the run was skipped before any start logged) has no entry; callers decide what an unpaired
  * end costs. Lives in the read module, not in a ui module, so core collectors can share it
  * without a core→ui import. */
-export function tickStartMap(events) {
+export function runStartMap(events) {
     const starts = new Map();
-    for (const [key, e] of runStartMap(events))
+    for (const [key, e] of runStartEvents(events))
         starts.set(key, finiteNumber(e.ts, 0));
     return starts;
 }
-/** The run_start pairing's model selectors: `${loop}#${tick}` → the run's model when its
+/** The run_start pairing's model selectors: `${role}#${run}` → the run's model when its
  * run_start carries a non-empty string `model` (the agent-qualified selector string — a
  * per-role override, a fallback, or the primary — that the status rows carry; see
- * config-views.ts's agentQualifiedSelector). A run_start with no `model`, or an empty or
+ * config-views.ts's backendQualifiedSelector). A run_start with no `model`, or an empty or
  * non-string one, adds no entry, so `tumwater history`'s model cell renders empty for a start
  * that named none — exactly the empty-usage convention applied to cells. The finite-`ts`
- * guard rides runStartMap, the one home of the pairing. */
-export function tickStartModelMap(events) {
+ * guard rides runStartEvents, the one home of the pairing. */
+export function runStartModelMap(events) {
     const models = new Map();
-    for (const [key, e] of runStartMap(events)) {
+    for (const [key, e] of runStartEvents(events)) {
         if (typeof e.model === "string" && e.model !== "")
             models.set(key, e.model);
     }
     return models;
 }
-/** The model of the run_end event `ev` against `models` (tickStartModelMap's pairing): the
- * `${loop}#${tick}` lookup, in one place beside the map it indexes, so the key format and the
- * "no model is null" rule are spelled once — the model twin of tickSpanMs. null when the
+/** The model of the run_end event `ev` against `models` (runStartModelMap's pairing): the
+ * `${role}#${run}` lookup, in one place beside the map it indexes, so the key format and the
+ * "no model is null" rule are spelled once — the model twin of runSpanMs. null when the
  * start is missing (rotation cut it) or carried no model; callers decide what an empty model
  * costs — history renders it as an empty cell. */
-export function tickStartModel(ev, models) {
+export function runStartModel(ev, models) {
     return models.get(`${ev.source}#${ev.run}`) ?? null;
 }
-/** The start→end span of the `run_end` event `ev` against `starts` (tickStartMap's pairing):
- * the `${loop}#${tick}` lookup and the clamp to non-negative, in one place beside the map
+/** The start→end span of the `run_end` event `ev` against `starts` (runStartMap's pairing):
+ * the `${role}#${run}` lookup and the clamp to non-negative, in one place beside the map
  * they index, so the key format and the span rule are spelled once. null when the start is
  * missing (rotation cut it) or when `ev.ts` is not a finite number (a torn or hand-edited end
  * line can carry no usable timestamp); callers decide what an unpaired end costs — the failure
- * digest prices it as 0, history renders it as "—", tick detail omits the duration. The end's
- * guard is the same finiteness check eventTick/eventUsage apply to their fields: without it,
- * `Math.max(0, undefined - start)` was NaN, and the failure digest's `tickDurationMs`
- * (`tickSpanMs(ev, starts) ?? 0`) folded that NaN straight into its agent-hour totals —
+ * digest prices it as 0, history renders it as "—", run detail omits the duration. The end's
+ * guard is the same finiteness check eventRun/eventUsage apply to their fields: without it,
+ * `Math.max(0, undefined - start)` was NaN, and the failure digest's `runDurationMs`
+ * (`runSpanMs(ev, starts) ?? 0`) folded that NaN straight into its agent-hour totals —
  * `NaN ?? 0` is still NaN. */
-export function tickSpanMs(ev, starts) {
+export function runSpanMs(ev, starts) {
     const startTs = starts.get(`${ev.source}#${ev.run}`);
     const endTs = finiteNumber(ev.ts, null);
     return startTs === undefined || endTs === null ? null : Math.max(0, endTs - startTs);

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

@@ -0,0 +1,16 @@
+/** The one ordering the prose `tumwater logs --count` tally and the TUI Activity pane's
+ * tally line share: count each present event type, most-frequent first with ties in
+ * type-name order, one `[type, count]` pair per present type. Hoisting the sort here keeps
+ * `sayTally` and the pane from drifting on which types win or how ties break. The dashboard
+ * feed's tally chips keep their own copy because they run in a browser where harness modules
+ * cannot be imported (the `reportRoleOrder` exception
+ * src/ui/gui/gui-client-report-chart.ts documents). */
+import { increment, sortByValueDesc } from "../collections.js";
+/** Tally the distinct types present, most-frequent first with ties in type-name order.
+ * `[]` in, `[]` out. */
+export function eventTypeTally(events) {
+    const counts = new Map();
+    for (const e of events)
+        increment(counts, e.type);
+    return sortByValueDesc([...counts.entries()]);
+}

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

@@ -1,5 +1,6 @@
-import { dayAt, dayKey, humanSeconds } from "../text/datetime.js";
+import { dayAt, dayKey, humanSeconds, DAY_MS } from "../text/datetime.js";
 import { eventDayKey, parseEventLine } from "./event-read.js";
+import { EVENTS_KEEP } from "./events.js";
 import { eventsArchivePath, eventsLogPath } from "../paths.js";
 import { statOrNull } from "../files/files.js";
 import { readTailTextWithEnd } from "../files/tail.js";
@@ -17,16 +18,16 @@ export const REPORT_MAX_DAYS = 90;
  * signal, and the log rotates at 16 MB (EVENTS_MAX_BYTES in events.ts) anyway, so a huge window
  * mostly reads rotated-away nothing. Lives here so the CLI's flag validation and its window
  * read share one bound. */
-export const LOGS_SINCE_MAX_MS = 7 * 24 * 60 * 60 * 1000;
+export const LOGS_SINCE_MAX_MS = 7 * DAY_MS;
 /** The `tumwater report --since <duration>` window's cap: 7 days. The same bound as the logs
  * view above, for the same rationale — a longer window only re-reads more log without adding
  * signal, and the log rotates at 16 MB (EVENTS_MAX_BYTES in events.ts) anyway. Lives here so
  * the CLI's flag validation and the collector's window read share one bound. */
-export const REPORT_SINCE_MAX_MS = 7 * 24 * 60 * 60 * 1000;
+export const REPORT_SINCE_MAX_MS = 7 * DAY_MS;
 /** Why a trailing-window length is refused, as the rejection text naming the out-of-range
  * value (`sinceMs must be between 1 and 7d (got 604800000)`). The single home of the report
  * window's bound wording, shared by the data-layer guard (assertReportSinceMs) and the
- * dashboard's ?sinceMs= 400 (gui-endpoints.ts) so the two cannot drift apart; the `--since`
+ * dashboard's ?sinceMs= 400 (gui-report-endpoints.ts) so the two cannot drift apart; the `--since`
  * CLI flag uses parseSinceFlag's own distinct wording. */
 export function reportSinceMsg(sinceMs) {
     return `sinceMs must be between 1 and ${humanSeconds(REPORT_SINCE_MAX_MS / 1000)} (got ${sinceMs})`;
@@ -198,32 +199,42 @@ function scanEventsFile(file, fromKey) {
     const end = trailing !== "" && parseEventLine(trailing) !== null ? coveredEnd + Buffer.byteLength(trailing) : coveredEnd;
     return { events, coversFullWindow, end, logState: classifyLogFile(text, st) };
 }
-/** Events whose local day is on or after `fromKey`, read from the live log and — when the live
- * log alone does not cover the window — its one archived generation (events.jsonl.1, written by
- * rotation). Each file is scanned with bounded I/O (scanEventsFile) and the archive's in-window
- * events are strictly older than the live file's, so prepending them keeps the oldest-first
- * ordering every consumer assumes; the concatenation needs no dedup because rotation moves the
- * whole file, so the two files share no lines. `coversFullWindow` is true when either file's
- * oldest retained event predates the window, which keeps the rotation note honest in both
- * directions: it vanishes once the archive completes the window and still appears when even the
- * archive starts inside it. A window the live file provably covers never touches the archive,
+/** Events whose local day is on or after `fromKey`, read from the live log and, when the
+ * live log alone does not cover the window, its archived generations (events.jsonl.1 …
+ * `.EVENTS_KEEP`, each written by rotation — the newest archive `.1` first, then `.2` …
+ * `.5` only while the window is not yet covered, per G4). Each file is scanned with bounded
+ * I/O (scanEventsFile) and every archive's in-window events are strictly older than the live
+ * file's, so prepending them oldest-archive-first keeps the oldest-first ordering every
+ * consumer assumes; the concatenation needs no dedup because rotation moves whole files, so
+ * the files share no lines. `coversFullWindow` is true when any read file's oldest retained
+ * event predates the window, which keeps the rotation note honest in both directions: it
+ * vanishes once an archive completes the window and still appears when even the newest
+ * archive starts inside it. A window the live file provably covers never touches an archive,
  * and a missing or empty archive (the normal case) reads as nothing, so the no-rotation
  * behavior is unchanged. */
 export function readWindowEvents(root, fromKey) {
     const live = scanEventsFile(eventsLogPath(root), fromKey);
     if (live.coversFullWindow)
         return { events: live.events, coversFullWindow: true, liveEnd: live.end, logState: live.logState };
-    const archive = scanEventsFile(eventsArchivePath(root), fromKey);
-    return {
-        events: [...archive.events, ...live.events],
-        coversFullWindow: archive.coversFullWindow || live.coversFullWindow,
-        liveEnd: live.end,
-        logState: combineLogState(live.logState, archive.logState),
-    };
+    const archived = [];
+    let covered = live.coversFullWindow;
+    for (let gen = 1; gen <= EVENTS_KEEP && !covered; gen++) {
+        const archive = scanEventsFile(eventsArchivePath(root, gen), fromKey);
+        archived.push(archive);
+        covered = archive.coversFullWindow;
+    }
+    const events = [];
+    for (let i = archived.length - 1; i >= 0; i--)
+        events.push(...archived[i].events);
+    events.push(...live.events);
+    let logState = live.logState;
+    for (const a of archived)
+        logState = combineLogState(logState, a.logState);
+    return { events, coversFullWindow: covered, liveEnd: live.end, logState };
 }
 /** The event feed's read outcome for a one-shot caller that needs no window — `doctor`'s
  * event-log pre-flight. Reads the live log and its archive whole and classifies each; the
- * combine rule matches readWindowEvents, so the doctor check and the telemetry digest agree on
+ * combine rule matches readWindowEvents, so the doctor check and the selfcheck digest agree on
  * what "unreadable" means. */
 export function eventLogState(root) {
     return combineLogState(scanFileReadState(eventsLogPath(root)), scanFileReadState(eventsArchivePath(root)));
@@ -239,7 +250,7 @@ function scanFileReadState(file) {
     return classifyLogFile(text, st);
 }
 /** The duration-shaped windowed read whose consumer needs a SECOND view of the same window
- * with a wider cutoff (history's tick-row join: a queued tick spanning the rows' cutoff logged
+ * with a wider cutoff (history's run-row join: a queued run spanning the rows' cutoff logged
  * its merge_queued pin before that cutoff, so its merge verdict must be joined from evidence
  * up to `joinBackslackMs` older). One backwards scan serves both: the wide read's day key never
  * sits after the narrow one's, so every `ts >= cutoff` event it holds is exactly the narrow
@@ -309,8 +320,9 @@ export function readEventsSince(root, sinceMs) {
 /** The "recent events of a kind" read every doctor wait/failure check shares: events since the
  * trailing `sinceMs` window, kept only when they clear `now − sinceMs` (the caller's seam for the
  * window's far edge) and pass `keep`. One home of the read-and-recheck shape the slot/provider
- * wait checks (doctor-checks.ts), the notify-failure check, and the queued-merge wait check each
- * spelled beside readEventsSince's cutoff — the kind + recency rule cannot drift per caller. `keep`
+ * wait checks (doctor-contention-checks.ts), the notify-failure check, and the queued-merge
+ * wait check each spelled beside readEventsSince's cutoff — the kind + recency rule cannot drift
+ * per caller. `keep`
  * defaults to every event, so the ts-only reader passes nothing; `now` is explicit so every call in
  * one window derives from the same instant (readEventsSince's own cutoff still uses the real
  * clock, so this recheck is what a test seam can pin). `ts` is already number-typed by
@@ -318,3 +330,27 @@ export function readEventsSince(root, sinceMs) {
 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
+ * `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
+ * `now` for the open-ended case), and both stamp the same fromIso/toIso identity fields into
+ * their JSON, so the timing math and the ISO stamping live here rather than drifting per
+ * collector. `slice` is exactly the identity object each embeds: sinceMs and fromIso always,
+ * plus untilMs and toIso only when the window is bounded. */
+export function sinceWindowTiming(sinceMs, untilMs) {
+    const now = Date.now();
+    const cutoff = now - sinceMs;
+    const end = untilMs === undefined ? now : now - untilMs;
+    return {
+        now,
+        cutoff,
+        end,
+        slice: {
+            sinceMs,
+            fromIso: new Date(cutoff).toISOString(),
+            ...(untilMs === undefined ? {} : { untilMs, toIso: new Date(end).toISOString() }),
+        },
+    };
+}

package/dist/src/events/events.js

@@ -14,17 +14,22 @@ export function subscribeEvents(listener) {
  * harness event log is small per event, so a fixed cap keeps logEvent config-free. Exported
  * because the report headers name the threshold — a fact only this module owns. */
 export const EVENTS_MAX_BYTES = 16 * 1024 * 1024;
+/** How many rotated event-log generations rotateIfLarge retains (plans/fast-merge.md
+ * "Guardrails" G4): at most 96 MB with the live file, about six weeks at the series' daily
+ * rate, so a by-hand audit of the team still sees months. A constant, not a config key, like
+ * EVENTS_MAX_BYTES. */
+export const EVENTS_KEEP = 5;
 /** The rotation phrase the report headers render — `eventsRotationLabel()` rather than a
- * hardcoded "rotated at 16 MB" copy, so changing EVENTS_MAX_BYTES updates the header with it
- * instead of leaving every report claiming a size the log no longer rotates at. */
+ * hardcoded "rotated at 16 MB" copy, so changing EVENTS_MAX_BYTES or EVENTS_KEEP updates the
+ * header with it instead of leaving every report claiming a rotation the log no longer does. */
 export function eventsRotationLabel() {
-    return `rotated at ${EVENTS_MAX_BYTES / (1024 * 1024)} MB`;
+    return `rotated at ${EVENTS_MAX_BYTES / (1024 * 1024)} MB, ${EVENTS_KEEP} kept`;
 }
 ;
 /** The `source` of events tumwater writes about itself rather than on a role's behalf. */
 export const TUMWATER_SOURCE = "tumwater";
 /** The usage fields an event carries, as a fragment with both omitted when zero — the
- * omit-when-zero convention the two usage-emitters apply (tick-finalize.ts's run_end,
+ * omit-when-zero convention the two usage-emitters apply (run-finalize.ts's run_end,
  * merge-slot.ts's merge_done/merge_failed): a zero-token, zero-cost run (a free model, an abort
  * before any tokens) renders without usage, so event-format's usage fragment and
  * `tumwater history` show nothing rather than "$0.00". Spreading the fragment keeps the
@@ -51,7 +56,7 @@ export function logEvent(root, event) {
     const full = normalizeLegacyEvent({ ts: Date.now(), ...event });
     const file = eventsLogPath(root);
     ensureParentDir(file);
-    rotateIfLarge(file, EVENTS_MAX_BYTES);
+    rotateIfLarge(file, EVENTS_MAX_BYTES, EVENTS_KEEP);
     appendEventLine(file, JSON.stringify(full) + "\n");
     for (const listener of listeners)
         listener(full);
@@ -72,7 +77,7 @@ export function logEventBestEffort(root, event) {
         logEvent(root, event);
     }
     catch (err) {
-        // A terminal display boundary like cli-output's say()/fail(): the loop id, event type, and
+        // A terminal display boundary like cli-output's say()/fail(): the role id, event type, and
         // error text can carry model- or subprocess-supplied bytes, and stderr is a terminal. Strip
         // the control characters the same way so a fallback line cannot drive the operator's shell.
         const detail = `${event.source}: could not log ${event.type} event: ${errorMessage(err)}`;
@@ -80,9 +85,9 @@ export function logEventBestEffort(root, event) {
     }
 }
 /** warnEvent's twin of logEventBestEffort: the "something is off but the loop continues"
- * warning must not be the thing that ends the loop it warns about. The fallback keeps the
+ * warning must not be the thing that ends the role it warns about. The fallback keeps the
  * warning's own text on stderr — when the feed is the failure, this line is the only place the
- * caller's message (a spawn failure, a rejected tick) survives to be read. The single home of
+ * caller's message (a spawn failure, a rejected run) survives to be read. The single home of
  * the try-warn → message-bearing-stderr-fallback shape, so the notify hook and the launch pass
  * do not each carry a copy of it. */
 export function warnEventBestEffort(root, source, message) {
@@ -90,17 +95,29 @@ export function warnEventBestEffort(root, source, message) {
         warnEvent(root, source, message);
     }
     catch (err) {
-        // The warning's own text is very often model-supplied (a stalled tool call's label, a tick's
-        // lastError) and the loop id can be a custom one, so this fallback is a terminal boundary:
+        // The warning's own text is very often model-supplied (a stalled tool call's label, a run's
+        // lastError) and the role id can be a custom one, so this fallback is a terminal boundary:
         // sanitize exactly as say()/fail() do before the line reaches the operator's terminal.
         const detail = `${source}: ${message} (warning log unwritable: ${errorMessage(err)})`;
         process.stderr.write(`tumwater: ${stripTerminalControls(detail)}\n`);
     }
 }
+/** Run a best-effort bookkeeping step: when `step` throws, warn "could not <what>: <error>" under
+ * `source` and return false, so the caller keeps going (or returns early on false). */
+export function tryOrWarn(root, source, what, step) {
+    try {
+        step();
+        return true;
+    }
+    catch (err) {
+        warnEventBestEffort(root, source, `could not ${what}: ${errorMessage(err)}`);
+        return false;
+    }
+}
 /** The `{ emit, warn }` pair for a caller on a catch-less path (the orchestrator's poll loop
  * and the live config reload it drives): both route through logEventBestEffort and
  * warnEventBestEffort, so the "an unwritable feed must not end the team" policy has one home
- * and the harness-loop warning shorthand cannot drift from warnEvent's event shape. */
+ * and the harness-level warning shorthand cannot drift from warnEvent's event shape. */
 export function bestEffortEventLogger(root) {
     return {
         emit: (event) => logEventBestEffort(root, event),
@@ -140,11 +157,11 @@ function appendEventLine(file, line) {
     }
 }
 // The READ side of this feed — parseEventLine, the per-event query conventions
-// (eventDayKey/eventRole/eventUsage, tickStartMap/tickSpanMs), and the stat-cached tail
+// (eventDayKey/eventRole/eventUsage, runStartMap/runSpanMs), and the stat-cached tail
 // reader (readEvents/readEventsTailWithEnd) — lives in event-read.ts, so the append path's
 // fs machinery and stat-memo cache stay apart from the read path's parse-and-scan machinery
 // and its own stat-keyed cache. Human-facing formatting of events lives in event-format.ts;
 // the windowed reader in event-window.ts; both beside this module because each is used by
 // both display surfaces (src/ui/) and core consumers (the `run` banner's live stream,
-// cli/cli-run.ts), and src/ui/ is imported only by itself and the CLI command layer that
+// cli/cli-start.ts), and src/ui/ is imported only by itself and the CLI command layer that
 // drives it (cli.ts and the src/ command bodies — DEVELOPMENT.md Layout).

package/dist/src/events/notify.js

@@ -14,7 +14,7 @@ import { childEnv } from "../process/process.js";
  * role-cap-gates.ts and disk-gate.ts, src/baseline/main-red.ts, src/team/team-polls.ts,
  * merge-slot.ts, merge-questions.ts,
  * src/redeploy/redeployer.ts). `supervisor_exit` is logged by the supervisor after the
- * orchestrator is gone, so src/cli/cli-run.ts pages it directly with notifyTeamDown; events
+ * orchestrator is gone, so src/cli/cli-start.ts pages it directly with notifyTeamDown; events
  * appended by
  * operator CLI commands go straight to the file and are out of scope by design.
  *
@@ -24,14 +24,14 @@ import { childEnv } from "../process/process.js";
  * (the exact line `tumwater logs` renders, via formatEvent). */
 export const NOTIFY_EVENT_TYPES = [
     "budget_warning", // daily spend crossed 80% of the cap, gate still open — time to raise it or fix the fallback before the page below
-    "role_cap_warning", // one role's own daily spend crossed 80% of its cap, still ticking — time to raise it before the page below
-    "budget_paused", // spend cap hit with no usable free fallback — role loops are stopped
-    "claude_window_warning", // the claude.ai subscription window first reported allowed_warning — subscription claude seams still tick; the heads-up before the hold below
-    "claude_window_limited", // a rejected subscription window holds every subscription claude seam until it resets — the subscription team's binding stop
+    "role_cap_warning", // one role's own daily spend crossed 80% of its cap, still running — time to raise it before the page below
+    "budget_paused", // spend cap hit with no usable free fallback — roles are stopped
+    "subscription_window_warning", // the subscription window first reported allowed_warning — subscription seams still run; the heads-up before the hold below
+    "subscription_window_limited", // a rejected subscription window holds every subscription seam until it resets — the subscription team's binding stop
     "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 ticks
+    "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 loop is held until a fix lands
+    "main_red_hold", // main's own check is red — every code role is held until a fix lands
     "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

@@ -1,7 +1,7 @@
 /** The cluster-key rules shared by everything that groups failure messages into causes: the
  * failure digest's collection (failure-data.ts) and the error-storm reducer
  * (src/team/error-storm.ts) both count by these keys, so the normalization, the two
- * tick-timeout shapes and their pooling, and the grouping engine live here rather than
+ * 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";
@@ -76,34 +76,34 @@ export function normalizeClusterKey(message) {
         .replace(/(?<!exited\s)\b\d+\b/g, "<n>");
     return normalized.trim().slice(0, EXAMPLE_MAX);
 }
-/** normalizeClusterKey's rendering of the two tick-timeout errors src/agent/run-agent.ts emits —
+/** normalizeClusterKey's rendering of the two run-timeout errors src/agent/run-agent.ts emits —
  * the plain kill and the still-making-progress variant (session and worktree edits preserved
  * for resume, BUGS.md 2026-09-29). Both are one cause pointing at one knob (runTimeoutSeconds),
  * so every consumer that counts by cluster key pools them under the plain one. */
-export const TICK_TIMEOUT_KEY = "timed out after <dur>";
-const TICK_TIMEOUT_PROGRESSING_KEY = "timed out after <dur> while still making progress — session and worktree edits preserved for resume";
+export const RUN_TIMEOUT_KEY = "timed out after <dur>";
+const RUN_TIMEOUT_PROGRESSING_KEY = "timed out after <dur> while still making progress — session and worktree edits preserved for resume";
 // The review run's rewording of the same cause (BUGS.md 2026-09-30): the reviewer never
 // resumes, so its timeout names what actually happens — the commit is kept, the next
 // attempt re-reviews from scratch. Same cause, same knob (review.timeoutSeconds), one row.
-const TICK_TIMEOUT_PROGRESSING_REVIEW_KEY = "timed out after <dur> while still making progress — the commit is kept; the next attempt reviews it from scratch";
+const RUN_TIMEOUT_PROGRESSING_REVIEW_KEY = "timed out after <dur> while still making progress — the commit is kept; the next attempt reviews it from scratch";
 // The review run's wording when a resumable session remains:
 // the next attempt continues this review instead of re-reviewing. Continuing the timed-out
 // session is a different cause from a from-scratch re-review, so this wording is its own
-// cluster rather than joining the pooled plain tick-timeout row. Exported for its unit tests
-// (like TICK_TIMEOUT_KEY), so a display or digest test can pin the mapping by name.
-export const TICK_TIMEOUT_PROGRESSING_REVIEW_RESUME_KEY = "timed out after <dur> while still making progress — the commit is kept; the next attempt continues this review";
+// cluster rather than joining the pooled plain run-timeout row. Exported for its unit tests
+// (like RUN_TIMEOUT_KEY), so a display or digest test can pin the mapping by name.
+export const RUN_TIMEOUT_PROGRESSING_REVIEW_RESUME_KEY = "timed out after <dur> while still making progress — the commit is kept; the next attempt continues this review";
 /** The known progressing-timeout wordings and the key each pools under. The two review
  * wordings name one cause on one knob (review.timeoutSeconds): a still-making-progress kill
- * pools into the plain tick-timeout row (a mixed team of plain and progressing kills is one
+ * pools into the plain run-timeout row (a mixed team of plain and progressing kills is one
  * cause's agent-hours, not two half-size rows the top-N cut can drop — the same pooling the
  * error-storm reducer applies, src/team/error-storm.ts), and a resumed review's wording maps
  * to itself, because continuing the timed-out session is a different cause from a from-scratch
  * re-review. Enumerated so a future wording edit lands in
  * this table rather than silently changing which row its timeouts count under. */
 const TIMEOUT_POOL = new Map([
-    [TICK_TIMEOUT_PROGRESSING_KEY, TICK_TIMEOUT_KEY],
-    [TICK_TIMEOUT_PROGRESSING_REVIEW_KEY, TICK_TIMEOUT_KEY],
-    [TICK_TIMEOUT_PROGRESSING_REVIEW_RESUME_KEY, TICK_TIMEOUT_PROGRESSING_REVIEW_RESUME_KEY],
+    [RUN_TIMEOUT_PROGRESSING_KEY, RUN_TIMEOUT_KEY],
+    [RUN_TIMEOUT_PROGRESSING_REVIEW_KEY, RUN_TIMEOUT_KEY],
+    [RUN_TIMEOUT_PROGRESSING_REVIEW_RESUME_KEY, RUN_TIMEOUT_PROGRESSING_REVIEW_RESUME_KEY],
 ]);
 /** The cluster key a normalized error clusters under: the pooled wordings above map to their
  * row, and every other cause stands as normalizeClusterKey rendered it. */