tumwater 0.1.3 → 0.2.0

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

@@ -0,0 +1,116 @@
+// vocabulary: plain
+/** Words for the two code families the dashboards show: event types (the activity chips) and run
+ * result codes (the result cells). Pure, no I/O, so core modules and the UI may both import it. */
+/** The words for each event type. The `Record` type makes the compiler demand a label for every
+ * type in the union, so a new event type cannot ship without one; renaming a type renames its key
+ * here and leaves the label unchanged. A label is a lowercase phrase of a few words, never the
+ * code itself. */
+export const EVENT_TYPE_LABELS = {
+    run_start: "run started",
+    run_end: "run finished",
+    merge_queued: "waiting to merge",
+    merge_done: "merge finished",
+    merge_failed: "merge failed",
+    merged: "merged",
+    question_posted: "question posted",
+    entry_refused: "plan refused",
+    wake: "woke up",
+    run_deferred: "run deferred",
+    orchestrator_start: "tumwater started",
+    orchestrator_stop: "tumwater stopped",
+    prompt_enqueued: "message queued",
+    prompt_cancelled: "message cancelled",
+    prompt_edited: "message edited",
+    prompt_topped: "message moved to front",
+    prompt_taken: "message picked up",
+    counters_reset: "counters reset",
+    run_aborted: "run stopped by you",
+    resume: "run resumed",
+    review_start: "review started",
+    review_verdict: "review approved",
+    review_rejected: "review rejected",
+    review_failed: "review failed",
+    revision: "revision round",
+    conflict_handback: "sent back to resolve",
+    build_check: "check ran",
+    dep_install: "dependencies installed",
+    budget_warning: "budget warning",
+    budget_paused: "budget paused",
+    budget_fallback: "over-cap model",
+    budget_resumed: "budget resumed",
+    budget_handback: "returned to main model",
+    fallback_switched: "fallback switched",
+    team_paused: "team paused",
+    team_resumed: "team resumed",
+    state_migrated: "state migrated",
+    role_paused: "role paused",
+    role_resumed: "role resumed",
+    role_streak_paused: "repeated-failure pause",
+    role_cap_warning: "role budget warning",
+    role_cap_paused: "role budget paused",
+    role_cap_resumed: "role budget resumed",
+    main_red_hold: "main's check is failing",
+    maintenance_quota_hold: "waiting: maintenance allowance used",
+    maintenance_quota_resumed: "maintenance allowance reopened",
+    bootstrap_complete: "bootstrap complete",
+    quiet_hours_started: "quiet hours started",
+    quiet_hours_ended: "quiet hours ended",
+    disk_low: "waiting: low disk",
+    disk_ok: "disk space restored",
+    disk_reclaim: "disk space reclaimed",
+    claim: "entry claimed",
+    permit_reserve: "permits reserved",
+    slot_wait: "waited to start",
+    provider_wait: "waited for a provider slot",
+    rate_limit_hold: "waiting: provider limit",
+    rate_limit_resumed: "provider limit lifted",
+    claude_window_reserved: "claude usage window reserved",
+    claude_window_warning: "claude usage window warning",
+    claude_window_limited: "waiting: claude usage window",
+    claude_window_reset: "claude usage window reset",
+    max_concurrent_changed: "concurrency changed",
+    provider_concurrency_changed: "provider concurrency changed",
+    retention_changed: "retention changed",
+    config_changed: "settings changed",
+    model_changed: "model changed",
+    backend_binary: "backend checked",
+    model_fallback_started: "fallback model started",
+    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",
+    restart_refused: "update refused",
+    restart_blocked: "update blocked",
+    restart_forced: "update forced",
+    supervisor_exit: "tumwater exited",
+    warning: "warning",
+};
+/** The words for each run result code, shown in the result cells. */
+export const RUN_RESULT_LABELS = {
+    changed: "merged",
+    queued: "waiting to merge",
+    no_change: "no change",
+    skipped: "skipped",
+    refused: "refused",
+    rejected: "rejected in review",
+    review_error: "review failed",
+    merge_conflict: "merge conflict",
+    merge_blocked: "merge blocked",
+    error: "error",
+    aborted: "interrupted",
+    quiet_killed: "stalled, resumed",
+    user_aborted: "stopped by you",
+    main_red: "main's check is failing",
+};
+/** The words for an event type or run result code: its own-property label, else the code with
+ * underscores as spaces. The two code families are disjoint, so one lookup serves both. */
+export function eventTypeLabel(code) {
+    if (Object.hasOwn(EVENT_TYPE_LABELS, code))
+        return EVENT_TYPE_LABELS[code];
+    if (Object.hasOwn(RUN_RESULT_LABELS, code))
+        return RUN_RESULT_LABELS[code];
+    return code.replace(/_/g, " ");
+}

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

@@ -0,0 +1,140 @@
+import { TUMWATER_SOURCE } from "./events.js";
+import { canonicalRoleId } from "../roles/legacy-role-ids.js";
+/** Old event lines read under today's names. `.tumwater/log/events.jsonl` (and its rotated
+ * `events.jsonl.1`) outlive the build that wrote them, and a long-lived supervisor on an older
+ * build keeps writing old names, so every reader normalizes on read: `normalizeLegacyEvent` is
+ * applied by `parseEventLine` (which every file reader goes through) and by `logEvent` (so
+ * in-process subscribers see exactly what readers see). Its rewrites are permanent.
+ *
+ * Role ids (`dry`, `telemetry`) are deliberately NOT mapped here. The role-id rename aliases an
+ * event's `source` id through its own legacy-id table when it switches each id, so mapping them
+ * 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
+    // 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
+    // retired-name-ok:end
+    // retired-name-ok:start old event names
+    land_queued: "merge_queued", // vocabulary-ok: legacy event name read from old logs
+    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
+};
+/** 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",
+        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
+            }
+        },
+    },
+    {
+        // build_check.scope and conflict_handback.reason said "landing" for what is now "merge".
+        name: "landing-to-merge",
+        apply(ev) {
+            const e = ev;
+            if (e.type === "build_check" && e.scope === "landing")
+                e.scope = "merge"; // vocabulary-ok: legacy event value read from old logs
+            if (e.type === "conflict_handback" && e.reason === "landing")
+                e.reason = "merge"; // vocabulary-ok: legacy event value read from old logs
+        },
+    },
+    {
+        // slot_wait.purpose said "tick"/"vet" for what is now "run"/"verify".
+        name: "slot-purpose",
+        apply(ev) {
+            const e = ev;
+            if (e.type !== "slot_wait")
+                return;
+            if (e.purpose === "tick")
+                e.purpose = "run"; // vocabulary-ok: legacy event value read from old logs
+            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",
+        apply(ev) {
+            const e = ev;
+            if (e.type !== "restart")
+                return;
+            const renames = [
+                ["drainedMs", "finishedMs"], // vocabulary-ok: legacy field name read from old logs
+                ["abortedTicks", "abortedRuns"], // vocabulary-ok: legacy field name read from old logs
+                ["drainWindowMs", "finishWindowMs"], // vocabulary-ok: legacy field name read from old logs
+            ];
+            for (const [from, to] of renames) {
+                if (from in e && !(to in e)) {
+                    e[to] = e[from];
+                    delete e[from];
+                }
+            }
+        },
+    },
+    {
+        // The writer's id rode `loop`, with "harness" for tumwater's own events. A staged-claim
+        // `claim` line also carried a payload `source: "staged"`, which moves to `origin` first. A
+        // 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",
+        apply(ev) {
+            const e = ev;
+            if (typeof e.loop === "string") { // vocabulary-ok: legacy field name read from old logs
+                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
+            }
+            if (e.source === "harness")
+                e.source = TUMWATER_SOURCE; // vocabulary-ok: legacy event source read from old logs
+        },
+    },
+    {
+        // A retired role id on an old line reads as the role's current id. The table is empty
+        // until a switch part adds a row, so this changes nothing yet.
+        name: "legacy-role-ids",
+        apply(ev) {
+            const e = ev;
+            if (typeof e.source === "string")
+                e.source = canonicalRoleId(e.source);
+            if (typeof e.role === "string")
+                e.role = canonicalRoleId(e.role);
+        },
+    },
+];
+/** Today's name for an old event type name; any other string comes back unchanged. */
+export function canonicalEventType(name) {
+    return Object.prototype.hasOwnProperty.call(LEGACY_EVENT_TYPES, name) ? LEGACY_EVENT_TYPES[name] : name;
+}
+/** Rewrite a freshly parsed event line in place to today's names and return it. Never throws; a
+ * current line comes back untouched. */
+export function normalizeLegacyEvent(ev) {
+    if (typeof ev.type === "string") {
+        const next = canonicalEventType(ev.type);
+        if (next !== ev.type)
+            ev.type = next;
+    }
+    for (const rewrite of LEGACY_EVENT_REWRITES) {
+        try {
+            rewrite.apply(ev);
+        }
+        catch {
+            // A malformed field is left as written: normalizing must never lose the line.
+        }
+    }
+    return ev;
+}

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

@@ -3,6 +3,7 @@ import { finiteNumber, parseJsonObject } from "../files/json-object.js";
 import { eventsLogPath } from "../paths.js";
 import { cachedByStat } from "../files/stat-cache.js";
 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
@@ -20,10 +21,11 @@ import { readTailTextWithEnd } from "../files/tail.js";
  * object either: the log is one JSON object per line, so anything else is corrupt (or foreign)
  * and reads as no data — the same object check readJsonFile applies to the harness's state
  * files. Without it, `readEvents` pushes the truthy non-object into the feed and `formatEvent`
- * renders it as an `Invalid Date undefined` line. */
+ * renders it as an `Invalid Date undefined` line. An old line comes back under today's names
+ * (normalizeLegacyEvent, event-legacy.ts). */
 export function parseEventLine(line) {
     const parsed = parseJsonObject(line);
-    return parsed ? parsed : null;
+    return parsed ? normalizeLegacyEvent(parsed) : null;
 }
 /** The local calendar-day key ("YYYY-MM-DD") of an event's `ts`, or null when it carries no
  * numeric timestamp. The one day-bucketing rule the windowed reader (event-window.ts) and the
@@ -40,19 +42,19 @@ export function eventDayKey(ev) {
 /** The loop 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.loop === "string" && ev.loop !== "" ? ev.loop : "?";
+    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.ticks before logging its first tick — so 0 is visibly not
+ * 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
  * aheadCommits apply, kept finite so a JSON consumer never sees NaN's null stand-in. */
 export function eventTick(ev) {
-    return finiteNumber(ev.tick, 0);
+    return finiteNumber(ev.run, 0);
 }
-/** The usage numbers an event records (`tick_end`'s own run, `landed`'s landing slot):
+/** The usage numbers an event records (`run_end`'s own run, `merge_done`'s merge slot):
  * `tokens` and `costUsd` arrive `unknown` through the event's index signature, so they are
  * coerced to numbers here, with an absent, non-numeric, or non-finite value reading as 0 —
  * the one convention every usage consumer applies (the event feed's usage fragment,
@@ -66,27 +68,61 @@ export function eventUsage(ev) {
     const notionalCostUsd = finiteNumber(ev.notionalCostUsd, 0);
     return { tokens, costUsd, notionalCostUsd };
 }
-/** Pair the tick_start events of `events` by tick, keyed `${loop}#${tick}` → start epoch ms —
- * the one home of that pairing and its key format, shared by `tumwater history`'s rows
+/** Pair the run_start events of `events` by tick, keyed `${loop}#${tick}` → 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
+ * 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
+ * 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) {
+    const starts = new Map();
+    for (const e of events) {
+        const ts = finiteNumber(e.ts, null);
+        if (e.type === "run_start" && ts !== null)
+            starts.set(`${e.source}#${e.run}`, e);
+    }
+    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 tick_end whose start is not in `events` (log rotation cut it, or
+ * 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
- * end costs. A tick_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 value in the map is real epoch
- * ms and the span below cannot subtract from `undefined`. Lives in the read module, not in a
- * ui module, so core collectors can share it without a core→ui import. */
+ * 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) {
     const starts = new Map();
-    for (const e of events) {
-        const ts = finiteNumber(e.ts, null);
-        if (e.type === "tick_start" && ts !== null)
-            starts.set(`${e.loop}#${e.tick}`, ts);
-    }
+    for (const [key, e] of runStartMap(events))
+        starts.set(key, finiteNumber(e.ts, 0));
     return starts;
 }
-/** The start→end span of the `tick_end` event `ev` against `starts` (tickStartMap's pairing):
+/** The run_start pairing's model selectors: `${loop}#${tick}` → 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
+ * 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) {
+    const models = new Map();
+    for (const [key, e] of runStartMap(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
+ * 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) {
+    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
  * 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
@@ -97,12 +133,12 @@ export function tickStartMap(events) {
  * (`tickSpanMs(ev, starts) ?? 0`) folded that NaN straight into its agent-hour totals —
  * `NaN ?? 0` is still NaN. */
 export function tickSpanMs(ev, starts) {
-    const startTs = starts.get(`${ev.loop}#${ev.tick}`);
+    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);
 }
 /** The event-tail size readEvents falls back to when a caller omits `limit` — a working
- * handful of a busy fleet's recent activity, small enough that the per-poll tail read stays
+ * handful of a busy team's recent activity, small enough that the per-poll tail read stays
  * cheap. Exported so a caller that starts a scan at the default (status-polls.ts's
  * mainCheckForPoll ladder) grows from the same value instead of re-spelling the literal. */
 export const DEFAULT_EVENT_TAIL = 200;

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

@@ -1,4 +1,4 @@
-import { dayKey, humanSeconds } from "../text/datetime.js";
+import { dayAt, dayKey, humanSeconds } from "../text/datetime.js";
 import { eventDayKey, parseEventLine } from "./event-read.js";
 import { eventsArchivePath, eventsLogPath } from "../paths.js";
 import { statOrNull } from "../files/files.js";
@@ -23,16 +23,24 @@ export const LOGS_SINCE_MAX_MS = 7 * 24 * 60 * 60 * 1000;
  * 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;
+/** 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`
+ * 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})`;
+}
 /** Reject a trailing-window length outside the report bound before a collector reads the log.
  * The CLI's parseSinceFlag already rejects one, but both trailing-window collectors are also
  * called directly (tests, future callers), so the data layer enforces the bound too. A
  * non-finite length is refused here as well: NaN slips past both comparisons (`NaN <= 0` and
  * `NaN > MAX` are each false) and would reach the window arithmetic, so the guard tests
- * finiteness first — the same rule the persisted-state readers apply. One home for the message
- * keeps the usage report and the failure digest from drifting apart. */
+ * finiteness first — the same rule the persisted-state readers apply. The message comes from
+ * reportSinceMsg so the data layer and the dashboard share the bound's wording. */
 export function assertReportSinceMs(sinceMs) {
     if (!Number.isFinite(sinceMs) || sinceMs <= 0 || sinceMs > REPORT_SINCE_MAX_MS)
-        throw new Error(`sinceMs must be between 1 and ${humanSeconds(REPORT_SINCE_MAX_MS / 1000)} (got ${sinceMs})`);
+        throw new Error(reportSinceMsg(sinceMs));
 }
 /** The one-line note every windowed render prints when its read cannot prove the window was
  * fully covered (coversFullWindow false or eventWindowCovers false): the log's oldest retained
@@ -139,7 +147,7 @@ export function eventWindowCovers(w, cutoff) {
  * as the oldest complete line in hand predates the window — cost scales with the window's size,
  * not the file's. `coversFullWindow` records whether this file reaches back before the window
  * (see EventWindow's field doc), so the caller can tell "retention cut the window" from "the
- * fleet was idle": both leave the oldest returned event later than the window start, but only
+ * team was idle": both leave the oldest returned event later than the window start, but only
  * the former means data was lost. */
 function scanEventsFile(file, fromKey) {
     const st = statOrNull(file);
@@ -232,7 +240,7 @@ function scanFileReadState(file) {
 }
 /** 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
- * its land_queued pin before that cutoff, so its landing verdict must be joined from evidence
+ * 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
  * read's event list — the narrow scan reads a prefix of the wide scan's bytes and stops no
@@ -260,7 +268,7 @@ export function readEventsSinceJoined(root, sinceMs, joinBackslackMs) {
     // exactly ts < that midnight — so the checks below are numeric and the event list's
     // oldest-first order makes them one bounded pass instead of a day-key formatting per event.
     const cut = new Date(cutoff);
-    const narrowDayStartMs = new Date(cut.getFullYear(), cut.getMonth(), cut.getDate()).getTime();
+    const narrowDayStartMs = dayAt(0, cut).getTime();
     // One pass up the oldest-first list: the oldest numerically-timestamped event (any line
     // older than the narrow day proves the narrow scan would have early-stopped on it) and
     // the first event inside the narrow day (the narrow window's oldest retained event, for
@@ -298,3 +306,15 @@ export function readEventsSince(root, sinceMs) {
     const events = window.events.filter((e) => typeof e.ts === "number" && e.ts >= cutoff);
     return { cutoff, events, covered: eventWindowCovers(window, cutoff) };
 }
+/** 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`
+ * 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
+ * readEventsSince's filter, so the recheck never compares against a NaN. */
+export function eventsSince(root, sinceMs, now, keep = () => true) {
+    return readEventsSince(root, sinceMs).events.filter((ev) => keep(ev) && ev.ts >= now - sinceMs);
+}

package/dist/src/events/events.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import { eventsLogPath } from "../paths.js";
 import { ensureParentDir, rotateIfLarge, sameStatIdentity, statOrNull, terminateTornTail } from "../files/files.js";
+import { normalizeLegacyEvent } from "./event-legacy.js";
 import { errorMessage, stripTerminalControls } from "../text/text.js";
 const listeners = new Set();
 /** Get notified of every event logged in this process (e.g. to narrate `tumwater run`).
@@ -19,9 +20,12 @@ export const EVENTS_MAX_BYTES = 16 * 1024 * 1024;
 export function eventsRotationLabel() {
     return `rotated at ${EVENTS_MAX_BYTES / (1024 * 1024)} MB`;
 }
+;
+/** 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 tick_end,
- * landing-slot.ts's landed/land_failed): a zero-token, zero-cost run (a free model, an abort
+ * omit-when-zero convention the two usage-emitters apply (tick-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
  * fields absent rather than 0; readers (event-read.ts's eventUsage and the index-signature
@@ -32,7 +36,7 @@ export function usageFragment(tokens, costUsd, notionalCostUsd = 0) {
         ...(tokens > 0 ? { tokens } : {}),
         ...(costUsd > 0 ? { costUsd } : {}),
         // Subscription spend rides on the same fragment (plans/agent-backends.md part 6a): it is
-        // omitted when zero like the other fields, so an API-only fleet's lines are unchanged.
+        // omitted when zero like the other fields, so an API-only team's lines are unchanged.
         ...(notionalCostUsd > 0 ? { notionalCostUsd } : {}),
     };
 }
@@ -44,7 +48,7 @@ export function usageFragment(tokens, costUsd, notionalCostUsd = 0) {
  * so it runs only when the file's shape differs from what this process's last append left —
  * a steady stream of events costs one stat, not an fd cycle, per event. */
 export function logEvent(root, event) {
-    const full = { ts: Date.now(), ...event };
+    const full = normalizeLegacyEvent({ ts: Date.now(), ...event });
     const file = eventsLogPath(root);
     ensureParentDir(file);
     rotateIfLarge(file, EVENTS_MAX_BYTES);
@@ -54,10 +58,10 @@ export function logEvent(root, event) {
     return full;
 }
 /** Log a warning event: the harness's "something is off but the loop continues" signal. The
- * single home of the `{ loop, type: "warning", message }` shape every warn site constructs —
+ * single home of the `{ source, type: "warning", message }` shape every warn site constructs —
  * without it, each caller restates the event object and a field can drift between them. */
-export function warnEvent(root, loop, message) {
-    return logEvent(root, { loop, type: "warning", message });
+export function warnEvent(root, source, message) {
+    return logEvent(root, { source, type: "warning", message });
 }
 /** logEvent for a caller on a path that cannot handle a throw — the orchestrator's
  * catch-less poll loop and the gate family it runs every couple of seconds. An unwritable
@@ -71,7 +75,7 @@ export function logEventBestEffort(root, event) {
         // A terminal display boundary like cli-output's say()/fail(): the loop 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.loop}: could not log ${event.type} event: ${errorMessage(err)}`;
+        const detail = `${event.source}: could not log ${event.type} event: ${errorMessage(err)}`;
         process.stderr.write(`tumwater: ${stripTerminalControls(detail)}\n`);
     }
 }
@@ -81,26 +85,26 @@ export function logEventBestEffort(root, event) {
  * caller's message (a spawn failure, a rejected tick) 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, loop, message) {
+export function warnEventBestEffort(root, source, message) {
     try {
-        warnEvent(root, loop, 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:
         // sanitize exactly as say()/fail() do before the line reaches the operator's terminal.
-        const detail = `${loop}: ${message} (warning log unwritable: ${errorMessage(err)})`;
+        const detail = `${source}: ${message} (warning log unwritable: ${errorMessage(err)})`;
         process.stderr.write(`tumwater: ${stripTerminalControls(detail)}\n`);
     }
 }
 /** 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 fleet" policy has one home
+ * 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. */
 export function bestEffortEventLogger(root) {
     return {
         emit: (event) => logEventBestEffort(root, event),
-        warn: (message) => warnEventBestEffort(root, "harness", message),
+        warn: (message) => warnEventBestEffort(root, TUMWATER_SOURCE, message),
     };
 }
 /** The shape this process's last event append left a log in, per log path: while the file
@@ -127,7 +131,7 @@ function appendEventLine(file, line) {
             // The append writes UTF-8 BYTES, so the growth is Buffer.byteLength, not the string's
             // code-unit length: a multi-byte event line (an em dash in an agent's message is enough)
             // would otherwise leave the memo short of the file's real size, every later stat would
-            // miss it, and the memo would silently never hit on the fleet's actual traffic.
+            // miss it, and the memo would silently never hit on the team's actual traffic.
             size: st.size + (terminated ? 1 : 0) + Buffer.byteLength(line, "utf8"),
         });
     }