tumwater 0.2.0 → 0.3.0

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

@@ -1,4 +1,3 @@
-// vocabulary: plain
 /** Event-log folding for the usage report: turn raw harness events (run_end/merged/…) into
  * per-day and whole-window `UsageFold` accumulators, memoizing the day-keyed read per
  * (root, fromKey) so a dashboard polling /api/report only folds appended lines instead of
@@ -7,19 +6,21 @@
  * --since and day windows present cannot drift apart; it lives here matching its own test
  * (test/report-fold-cache.test.ts). Zero incidental runtime dependencies: node built-ins and
  * the app's own modules only. */
-import { sameStatIdentity, statOrNull } from "../files/files.js";
+import { sameStatIdentity, statIdentityOrZero, statOrNull } from "../files/files.js";
 import { readWindowEvents } from "../events/event-window.js";
 import { eventDayKey, eventRole, eventUsage, parseEventLine } from "../events/event-read.js";
 import { readCompleteLines } from "../files/tail.js";
 import { eventsLogPath } from "../paths.js";
 import { isPassingFullCheck, isRedFullCheck } from "../build/build-check-events.js";
+import { isPassingMainCheck, isRedMain } from "../baseline/main-guardrails.js";
 import { addTo, memoSetLru } from "../collections.js";
+import { asList } from "../text/text.js";
 import { finiteNumber } from "../files/json-object.js";
 import { OUTCOME_CLASS } from "../failure/time-spend.js";
-import { baseRoleOf } from "../roles/loop-ids.js";
+import { baseRoleOf } from "../roles/runner-ids.js";
 import { commitTier } from "../roles/roles.js";
 /** Fold one event's `providerCost` map (`Record<provider, {costUsd, notionalCostUsd}>` — the
- * shape tick-finalize.ts's run_end and merge-slot.ts's merge_done/merge_failed emit) into the
+ * shape run-finalize.ts's run_end and merge-slot.ts's merge_done/merge_failed emit) into the
  * per-provider tallies, one addTo per provider per nonzero figure so zero stays absent. A
  * missing, foreign, or empty map folds nothing, so old logs render byte-identically. */
 function foldProviderCost(target, providerCost) {
@@ -37,28 +38,28 @@ function foldProviderCost(target, providerCost) {
             addTo(target.notionalByProvider, provider, notionalCostUsd);
     }
 }
-/** Push a provider- or workspace-slot wait's ms into the accumulator list a median reads,
- * when the event carried a positive wait: a wait is only event-logged at or above the 30 s
- * threshold, so a 0 ms wait (a probe seam) or a pre-waitedMs event adds nothing and the two
- * wait medians reflect real blocked admissions only. */
-function pushPositiveWaitedMs(list, ev) {
-    const waited = finiteNumber(ev.waitedMs, 0);
-    if (waited > 0)
-        list.push(waited);
+/** Push `ms` into the accumulator list a day median reads, when it is positive: the event
+ * fields that feed these medians are missing or 0 for the same event kinds (short runs, build
+ * pre-checks, precedent legacy events, probe-seam waits), and those contribute nothing — a
+ * median over only real durations/wait times. Every median list folds through here, so the
+ * "positive-only" rule cannot drift between fields. */
+function pushPositiveMs(list, ms) {
+    if (ms > 0)
+        list.push(ms);
 }
-/** Fold one event into a usage accumulator: run_end events add a tick (per role and, when
- * the target counts ticks, in total), their output tokens, and their cost — zero-cost ticks
+/** Fold one event into a usage accumulator: run_end events add a run (per role and, when
+ * the target counts runs, in total), their output tokens, and their cost — zero-cost runs
  * contribute nothing, so they leave no costByRole key, keeping the render's "$0 roles are
  * omitted" rule true on the aggregation itself, not just at display time; merged events add
  * a commit; merge_done/merge_failed events add a merge run and
- * accumulate their tokens/cost into the merge fields only — costByRole stays a ticks-only
+ * accumulate their tokens/cost into the merge fields only — costByRole stays a runs-only
  * breakdown, and the merge line is how the reviewer's share is named. Both collectors fold
  * through this one place, so the two windows' aggregation rules cannot drift apart. */
 export function foldUsageEvent(target, ev) {
     if (ev.type === "run_end") {
         const role = eventRole(ev);
         addTo(target.runsByRole, role, 1);
-        // Error-class ticks get their own parallel tally — the day report's ``Failed ticks by role``
+        // Error-class runs get their own parallel tally — the day report's ``Failed runs by role``
         // line — reusing the digest's OUTCOME_CLASS so "failed" cannot drift from the failure
         // report's meaning. Never subtracted from runsByRole; the two are independent counts.
         if (OUTCOME_CLASS[ev.result] === "error")
@@ -66,12 +67,13 @@ export function foldUsageEvent(target, ev) {
         // A refusal is its own deliberate outcome (src/verdict/refusal.ts), not error-class, so
         // it needs an explicit result check: the one per-role rejection-without-review count a
         // day report should surface beside rejections, revisions and falls. Never subtracted from
-        // runsByRole; a refused tick still counts as a run.
+        // runsByRole; a refused run still counts as a run.
         if (ev.result === "refused")
             addTo(target.refusalsByRole, role, 1);
         if (target.runs !== undefined)
             target.runs++;
         const { tokens, costUsd, notionalCostUsd } = eventUsage(ev);
+        pushPositiveMs(target.runDurationsMs, finiteNumber(ev.durationMs, 0));
         addTo(target.tokensByRole, role, tokens);
         target.tokensOut += tokens;
         target.costUsd += costUsd;
@@ -80,26 +82,48 @@ export function foldUsageEvent(target, ev) {
             addTo(target.costByRole, role, costUsd);
         if (notionalCostUsd !== 0)
             addTo(target.notionalByRole, role, notionalCostUsd);
-        // The tick's own runs' per-provider spend (tick-finalize.ts emits providerCost on run_end)
+        // The notional spend's backend (plans/codex-backend.md part 3d/9): the subscription seam
+        // whose runs made the run's API-equivalent cost, from the run_end's `agent` (run-finalize
+        // carries it when the run reported billing/rate windows) — falling back to "claude" when
+        // a legacy window event (no agent, subscription billing) attributed its spend, so the old
+        // default stays the report's only backend. A run with no backend and no subscription
+        // billing is unattributed and adds no key, so the render keeps its generic line for it.
+        const notionalBackend = typeof ev.agent === "string" && ev.agent !== ""
+            ? ev.agent
+            : ev.billing === "subscription"
+                ? "claude"
+                : undefined;
+        if (notionalBackend !== undefined && notionalCostUsd !== 0)
+            addTo(target.notionalByBackend, notionalBackend, notionalCostUsd);
+        // The agent runs' per-provider spend (run-finalize.ts emits providerCost on run_end)
         // — folded per provider beside the per-role maps, so a mixed team's `Cost by provider`
         // line names the expensive seam.
         foldProviderCost(target, ev.providerCost);
     }
     else if (ev.type === "review_rejected") {
-        // One rejection per event, on the day it happened, per loop. Zero-means-absent: a role
+        // One rejection per event, on the day it happened, per role. Zero-means-absent: a role
         // that never rejected stays absent, like costByRole.
         addTo(target.rejectionsByRole, eventRole(ev), 1);
+        // A rejection that carried a positive durationMs means a reviewer actually ran the gate
+        // and reached a verdict (post-merge rejections do; the build pre-check contributes no
+        // duration), so it joins the review-duration median beside approvals. durationMs: 0 and
+        // a duration-less event contribute nothing.
+        pushPositiveMs(target.reviewDurationsMs, finiteNumber(ev.durationMs, 0));
+    }
+    else if (ev.type === "review_verdict") {
+        // An approval that reached a verdict. Every reviewer run that reached a verdict, approval
+        // or rejection, is one entry in the review-duration median; review_failed stays out — it
+        // has no verdict. Mirrors the rejection branch above, on the same-day count.
+        pushPositiveMs(target.reviewDurationsMs, finiteNumber(ev.durationMs, 0));
     }
     else if (ev.type === "revision") {
-        // One rework round per event, on the day it happened, per loop. Zero-means-absent: a role
+        // One rework round per event, on the day it happened, per role. Zero-means-absent: a role
         // that never reworked a rejected change stays absent, like rejectionsByRole.
         addTo(target.revisionsByRole, eventRole(ev), 1);
     }
     else if (isPassingFullCheck(ev)) {
         // The merge slot's passing full-suite checks, for the day report's check-time median.
-        const durationMs = finiteNumber(ev.durationMs, 0);
-        if (durationMs > 0)
-            target.checkDurationsMs.push(durationMs);
+        pushPositiveMs(target.checkDurationsMs, finiteNumber(ev.durationMs, 0));
     }
     else if (isRedFullCheck(ev)) {
         // The merge slot's red full-suite checks, for the day report's red-check count.
@@ -114,7 +138,7 @@ export function foldUsageEvent(target, ev) {
         addTo(target.imageReroutesByRole, eventRole(ev), 1);
     }
     else if (ev.type === "run_deferred") {
-        // One deferral per event, a due maintenance tick that stood down. Bucket by the raw
+        // One deferral per event, a due maintenance run that stood down. Bucket by the raw
         // reason code ("backlog", "plans-full", else "no-work" for a missing/foreign/torn
         // reason — the same fallback deferredReasonText applies in the feed), so the collector
         // stays free of a presentation import and the render prints the code the event carried.
@@ -134,6 +158,15 @@ export function foldUsageEvent(target, ev) {
         else if (tier === "maintenance")
             target.maintenanceCommits++;
     }
+    else if (ev.type === "main_revert") {
+        // Which role's merged change the main watch took back off main, keyed by the culprit's
+        // `runner` — a revert is a merge outcome, so it counts under the role that merged the
+        // culprit, folded to base role like commitsByRole/mergedByRole (`feature-2` → `feature`).
+        // A revert with no `runner` (a hand-made or director commit) adds nothing — no
+        // `(unknown)` key — matching the zero-means-absent rule of the other role maps.
+        if (typeof ev.runner === "string" && ev.runner !== "")
+            addTo(target.revertsByRole, baseRoleOf(ev.runner), 1);
+    }
     else if (ev.type === "run_start") {
         // One tally per run start on a configured model: the same `model` field the CLI's
         // `run #N started on <model>` line prints, and the only event that carries a model
@@ -146,19 +179,24 @@ export function foldUsageEvent(target, ev) {
         // The day report's provider-slot wait median, mirroring the slot_wait push: a wait only
         // event-logged at or above the 30 s threshold counts, so a 0 ms wait (a probe seam) adds
         // nothing and the median reflects real blocked admissions only.
-        pushPositiveWaitedMs(target.providerWaitsMs, ev);
+        pushPositiveMs(target.providerWaitsMs, finiteNumber(ev.waitedMs, 0));
     }
     else if (ev.type === "slot_wait") {
         // The day report's workspace-slot wait median, mirroring the provider_wait push: a wait
         // only event-logged at or above the 30 s threshold counts, so a 0 ms wait (a probe seam)
         // or a pre-waitedMs event adds nothing.
-        pushPositiveWaitedMs(target.slotWaitsMs, ev);
+        pushPositiveMs(target.slotWaitsMs, finiteNumber(ev.waitedMs, 0));
+    }
+    else if (ev.type === "check_wait") {
+        // The day report's check-slot wait median, mirroring the slot_wait push: only waits logged
+        // at or above the 30 s threshold count, so a 0 ms or pre-waitedMs event adds nothing.
+        pushPositiveMs(target.checkWaitsMs, finiteNumber(ev.waitedMs, 0));
     }
     else if (ev.type === "merge_done" || ev.type === "merge_failed") {
         target.mergeRuns = (target.mergeRuns ?? 0) + 1;
         if (ev.type === "merge_failed")
             target.mergeFailed = (target.mergeFailed ?? 0) + 1;
-        // Attribute the outcome to the authoring role (writeMergeOutcome logs loop: entry.role)
+        // Attribute the outcome to the authoring role (writeMergeOutcome logs role: entry.role)
         // folded to base role, the same normalization the merged branch uses, so `feature-2`
         // aggregates into `feature`. A parallel tally beside the team run counts, never
         // subtracted from mergeRuns/mergeFailed.
@@ -166,13 +204,15 @@ export function foldUsageEvent(target, ev) {
         if (ev.type === "merge_done") {
             addTo(target.mergedByRole, role, 1);
             // Events logged before queuedMs existed carry none: skipped, not counted as zero.
-            const waited = finiteNumber(ev.queuedMs, 0);
-            if (waited > 0)
-                target.mergeWaitsMs.push(waited);
+            pushPositiveMs(target.mergeWaitsMs, finiteNumber(ev.queuedMs, 0));
+            // How long the merge slot itself held the change, from the verification's start to the
+            // outcome. Like mergeWaitsMs, only a landed merge feeds it, and a pre-durationMs event
+            // (or 0) contributes nothing.
+            pushPositiveMs(target.mergeDurationsMs, finiteNumber(ev.durationMs, 0));
         }
         else {
             addTo(target.mergeFailedByRole, role, 1);
-            // The event's result (writeMergeOutcome's TickResult) names WHY the merge bounced
+            // The event's result (writeMergeOutcome's RunResult) names WHY the merge bounced
             // off the gate — rejected/merge_conflict/merge_blocked/aborted. A legacy event with
             // no result folds under `unknown`, so the reason buckets always sum to mergeFailed.
             const reason = typeof ev.result === "string" && ev.result.length > 0 ? ev.result : "unknown";
@@ -184,6 +224,14 @@ export function foldUsageEvent(target, ev) {
         // A subscription merge's API-equivalent spend joins the notional line, never the
         // budgeted cost totals (plans/agent-backends.md part 6a).
         target.notionalCostUsd += notionalCostUsd;
+        // The merge's notional spend per backend (merge-slot.ts emits it on the event, keyed by
+        // each subscription run's agent) — folded beside the run-end per-backend map, so a codex
+        // merge's subscription spend names codex instead of falling back to the generic line.
+        for (const [backend, c] of Object.entries(ev.notionalByBackend ?? {})) {
+            const amt = finiteNumber(c, 0);
+            if (amt !== 0)
+                addTo(target.notionalByBackend, backend, amt);
+        }
         // The merge's per-provider spend (merge-slot.ts keys it to its reviewer seam), so a
         // merge's costs appear under the provider that ran the reviewer, matching the author
         // side's foldMergeUsage charge.
@@ -209,34 +257,58 @@ export function zeroCommitCounts() {
 export function zeroMergeCounts() {
     return { mergeRuns: 0, mergeTokens: 0, mergeCostUsd: 0 };
 }
-/** Sum a per-loop-id count/cost map over one base role: instance keys (`feature-2`) fold into
- * their base (`feature`), so a scoped report aggregates a whole role group exactly as the
- * per-role cap's group does. Ticks/tokens/cost are keyed by exact loop id while commits are
+/** The base roles a report scope names: undefined and an empty list mean no scope (the team
+ * report); otherwise each id folded through `baseRoleOf`, deduplicated in first-seen order, so
+ * `feature-2,feature` is one base. */
+export function scopeBases(role) {
+    if (role === undefined)
+        return undefined;
+    const ids = asList(role);
+    if (ids.length === 0)
+        return undefined;
+    const out = [];
+    for (const id of ids) {
+        const base = baseRoleOf(id);
+        if (!out.includes(base))
+            out.push(base);
+    }
+    return out;
+}
+/** Sum a per-role-id count/cost map over the scoped base roles: instance keys (`feature-2`)
+ * fold into their base (`feature`), so a scoped report aggregates a whole role group exactly
+ * as the per-role cap's group does. Runs/tokens/cost are keyed by exact role id while commits are
  * already base-role keyed; running every key through `baseRoleOf` reads both shapes the same
  * and returns 0 when nothing matches. */
-export function roleSum(record, role) {
+export function roleSum(record, bases) {
+    const list = asList(bases);
     let sum = 0;
     for (const [key, n] of Object.entries(record)) {
-        if (baseRoleOf(key) === role)
+        if (list.includes(baseRoleOf(key)))
             sum += n;
     }
     return sum;
 }
-/** Narrow a per-loop-id count/cost map to one base role, keyed by the base role; a role absent
- * from the map (no ticks, or no nonzero cost) yields an empty map, never a zero entry — the
- * same zero-means-absent rule the team render applies. Used by the role-scoped collectors so a
- * scoped series derives from the fold's per-role maps without inventing entries. */
-export function narrowToRole(record, role) {
-    const n = roleSum(record, role);
-    return n === 0 ? {} : { [role]: n };
+/** Narrow a per-role-id count/cost map to the scoped base roles, one entry per base keyed by
+ * that base; a role absent from the map (no runs, or no nonzero cost) yields no entry, never
+ * a zero one — the same zero-means-absent rule the team render applies. Used by the
+ * role-scoped collectors so a scoped series derives from the fold's per-role maps without
+ * inventing entries. */
+export function narrowToRole(record, bases) {
+    const out = {};
+    for (const base of asList(bases)) {
+        const n = roleSum(record, base);
+        if (n !== 0)
+            out[base] = n;
+    }
+    return out;
 }
-/** A per-loop map scoped to one base role for a report: the full map as-is when no scope is
- * set (a team report), else the same map narrowed to `base` — narrowToRole's zero-means-absent
+/** A per-role map scoped to the base roles of a report: the full map as-is when no scope is
+ * set (a team report), else the same map narrowed to `bases` — narrowToRole's zero-means-absent
  * rule, so a scoped report never invents a zero entry. The one home of the "keep everything,
  * or keep only the named base role" rule: the 13 per-role/pair fields of the `--since` report's
  * output all shape through it, so the scoping rule cannot drift between them. */
-export function scopedByRole(record, base) {
-    return base === undefined ? record : narrowToRole(record, base);
+export function scopedByRole(record, bases) {
+    return bases === undefined ? record : narrowToRole(record, bases);
 }
 function dayFoldFor(entry, dayKey) {
     let fold = entry.days.get(dayKey);
@@ -250,11 +322,16 @@ function dayFoldFor(entry, dayKey) {
             rejectionsByRole: {},
             revisionsByRole: {},
             refusalsByRole: {},
+            revertsByRole: {},
             checkDurationsMs: [],
             checkFailures: 0,
             mergeWaitsMs: [],
+            mergeDurationsMs: [],
+            runDurationsMs: [],
             providerWaitsMs: [],
             slotWaitsMs: [],
+            checkWaitsMs: [],
+            reviewDurationsMs: [],
             failedRunsByRole: {},
             fallbacksByRole: {},
             imageReroutesByRole: {},
@@ -267,6 +344,7 @@ function dayFoldFor(entry, dayKey) {
             mergeFailedByReason: {},
             costByProvider: {},
             notionalByProvider: {},
+            notionalByBackend: {},
             runsByModel: {},
             deferredByReason: {},
         };
@@ -286,6 +364,8 @@ function foldEventInto(entry, ev) {
         entry.hadEvents = true;
         entry.firstEventTs = typeof ev.ts === "number" ? ev.ts : undefined;
     }
+    if (isRedMain(ev) || isPassingMainCheck(ev))
+        entry.redEvents.push(ev);
     foldUsageEvent(dayFoldFor(entry, dayKey), ev);
 }
 /** Parse one appended log line and fold it; a torn or non-event line folds nothing. */
@@ -307,11 +387,7 @@ function foldLineInto(entry, line) {
  * carrying yesterday's proof forward. */
 export function foldWindowEvents(root, fromKey) {
     const key = `${root}\0${fromKey}`;
-    const liveStat = statOrNull(eventsLogPath(root));
-    const size = liveStat?.size ?? 0;
-    const mtimeMs = liveStat?.mtimeMs ?? 0;
-    const dev = liveStat?.dev ?? 0;
-    const ino = liveStat?.ino ?? 0;
+    const { size, mtimeMs, dev, ino } = statIdentityOrZero(statOrNull(eventsLogPath(root)));
     const cached = reportFoldCache.get(key);
     if (cached &&
         sameStatIdentity({ dev, ino, mtimeMs, size }, { dev: cached.dev, ino: cached.ino, mtimeMs: cached.mtimeMs, size: cached.offset })) {
@@ -345,6 +421,7 @@ export function foldWindowEvents(root, fromKey) {
         fileCovers: raw.coversFullWindow,
         hadEvents: false,
         days: new Map(),
+        redEvents: [],
     };
     for (const ev of raw.events)
         foldEventInto(entry, ev);

package/dist/src/report/report-main-red.js

@@ -0,0 +1,55 @@
+/** Main's red time per local calendar day: how long main had no passing full check, from the
+ * same `main_check` / `main_red_hold` event trail G1 uses (src/baseline/main-guardrails.ts).
+ * Pure and synchronous over an event list and a `[fromMs, toMs)` window, so the usage
+ * report's day and --since collectors both call it without reading the clock or the log
+ * again. This is main's own wall-clock red time, not any role's, so the report carries it
+ * only on the team scope. */
+import { dayKey } from "../text/datetime.js";
+import { isPassingMainCheck, isRedMain } from "../baseline/main-guardrails.js";
+/** Add a spell's ms, split across the local calendar days it spans, to `map` (a Map, so the
+ * caller keeps the day-key order the walk produced). */
+function addSpell(map, start, end) {
+    let cur = start;
+    while (cur < end) {
+        // The Date constructor's month/date fields cross the local midnight (and any DST shift
+        // at it) exactly as dayAt does, so an hour cannot leak into the next day.
+        const d = new Date(cur);
+        const nextMidnight = new Date(d.getFullYear(), d.getMonth(), d.getDate() + 1).getTime();
+        const segEnd = Math.min(end, nextMidnight);
+        const ms = segEnd - cur;
+        if (ms > 0)
+            map.set(dayKey(cur), (map.get(dayKey(cur)) ?? 0) + ms);
+        cur = segEnd;
+    }
+}
+/** Main's red wall-clock time per local calendar day (`YYYY-MM-DD` → ms), over the window
+ * `[fromMs, toMs)`. A red spell is G1's rule (isRedMain / isPassingMainCheck): it opens at a
+ * red event while none is open (a further red while open keeps the earliest start) and closes
+ * at the next passing full `main_check`; a spell still open at `toMs` runs to the window's
+ * end. Every spell is split across local calendar days (dayKey) with midnight arithmetic, so
+ * a DST shift cannot leak an hour into the next day; only nonzero daily entries are returned.
+ * A spell already open before `fromMs` is not counted, because its opener lies outside the
+ * window — the report measures main's own red time within the window it was asked for. */
+export function mainRedMinutesByDay(events, fromMs, toMs) {
+    const map = new Map();
+    const inWindow = events
+        .filter((e) => typeof e.ts === "number" && e.ts >= fromMs && e.ts < toMs)
+        .sort((a, b) => a.ts - b.ts);
+    let openStart;
+    for (const e of inWindow) {
+        const ts = e.ts;
+        if (isRedMain(e)) {
+            if (openStart === undefined)
+                openStart = ts;
+        }
+        else if (isPassingMainCheck(e)) {
+            if (openStart !== undefined) {
+                addSpell(map, openStart, ts);
+                openStart = undefined;
+            }
+        }
+    }
+    if (openStart !== undefined)
+        addSpell(map, openStart, toMs);
+    return map;
+}