tumwater 0.4.0 → 0.4.2

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

@@ -38,6 +38,21 @@ function rankedRoleTotals(series, pick) {
 function rankedRoleLine(label, pairs, fmt) {
     return `**${label}:** ${pairs.length === 0 ? "-" : pairs.map(([r, n]) => `${r} — ${fmt(n)}`).join(" · ")}`;
 }
+/** The "**Prompt tokens by role:**" line — each role's prompt-token total and, when its
+ * backend reported a cache read, the share of it served from cache (`12000 (80% cached)`)
+ * — with zero-total roles omitted (the same zero-means-absent rule the sibling lines apply)
+ * and "-" when no role sent a prompt. `prompt` arrives already ranked (prompt desc then
+ * name asc). The one home of the share format, so the day and `--since` lines cannot drift. */
+function promptTokensLine(prompt, cache) {
+    const cacheByRole = new Map(cache);
+    const cells = prompt
+        .filter(([, n]) => n > 0)
+        .map(([role, n]) => {
+        const c = cacheByRole.get(role) ?? 0;
+        return `${role} — ${compactTokens(n)}${c > 0 ? ` (${Math.round((100 * c) / n)}% cached)` : ""}`;
+    });
+    return `**Prompt tokens by role:** ${cells.length === 0 ? "-" : cells.join(" · ")}`;
+}
 /** Push one "**Label:** …" ranked-role line, dropping roles with a non-positive value (zero
  * count/spend) before rendering, so an all-zero window still renders "-" exactly like the
  * unfiltered lines. fmt formats each role's number (default String for count lines; pass
@@ -46,6 +61,18 @@ function rankedRoleLine(label, pairs, fmt) {
 function pushRankedRoleLine(lines, label, pairs, fmt = String) {
     lines.push(rankedRoleLine(label, pairs.filter(([, n]) => n > 0), fmt));
 }
+/** Push a "**Label:** …" ranked-role line only when some role carries a positive value — the
+ * zero-means-absent idiom: a window or day with no evidence prints no line at all, unlike
+ * pushRankedRoleLine's always-printed "-", because "no model ran" is an absence, not a zero
+ * (the same reason pushProviderCostLines and pushDayCameoLine stay silent when empty). fmt
+ * formats each role's number (default String for count lines). Shared by the since and day
+ * renders so the filter-and-if-present guard cannot drift between them — a field that flipped
+ * one render to always-print would show an absent "-" line in one report but not the other. */
+function pushPresentRankedLine(lines, label, pairs, fmt = String) {
+    const present = pairs.filter(([, n]) => n > 0);
+    if (present.length > 0)
+        lines.push(rankedRoleLine(label, present, fmt));
+}
 /** The per-day cameo line of the team day report — "MMM D <cell>" cells for each day that
  * carries a value, joined under a bold title, or undefined when no day has one (zero means
  * absent). The one home of that cameo rendering, shared by the per-day medians, the red-check
@@ -159,6 +186,20 @@ function pushReportSummary(lines, t, tail = "", scoped = false) {
  * collector's captured cutoff, so the printed window matches the aggregated one). */
 export function renderSinceReportMarkdown(data) {
     const lines = [];
+    pushSinceWindowHeader(lines, data);
+    pushSinceSummary(lines, data);
+    pushSinceRoleLines(lines, data);
+    pushSinceProviderModelLines(lines, data);
+    pushSinceMainRedLines(lines, data);
+    pushSinceFrictionLines(lines, data);
+    pushSinceDeferralLines(lines, data);
+    pushSinceCommitLines(lines, data);
+    pushSinceCostLines(lines, data);
+    pushSinceCoverageLines(lines, data);
+    return lines.join("\n");
+}
+/** The window header: the title, the bounded-or-since window line and the role scope line. */
+function pushSinceWindowHeader(lines, data) {
     lines.push("# tumwater usage report");
     lines.push("");
     lines.push(data.untilMs !== undefined && data.toIso !== undefined
@@ -167,21 +208,36 @@ export function renderSinceReportMarkdown(data) {
     if (data.role !== undefined)
         lines.push(`role: ${data.role}`);
     lines.push("");
+}
+/** The shared totals voice (minus features/bugs/filing cells, stated at the tail), gated
+ * to the team report like the day sibling's. */
+function pushSinceSummary(lines, data) {
     const t = data.totals;
     // Same totals voice as the day report, minus the features/bugs and filing cells: those tallies
     // come from day-granular backlog-file dates that cannot subdivide a sub-day window, so the
     // final line below states the omission instead of showing a day-rounded number.
     pushReportSummary(lines, t, "", data.role !== undefined);
     lines.push("");
+}
+/** Runs / tokens / prompt-tokens / cost breakdowns by role. */
+function pushSinceRoleLines(lines, data) {
     lines.push(rankedRoleLine("Runs by role", rankedRoleMap(data.runsByRole), String));
     // Same breakdown for token spend: ranked by tokens desc then name asc, zero-token roles
     // omitted — an all-zero window renders "-" like the other lines. Output tokens are the
     // resource the budget charges, so this is the line an operator reads to find which role's
     // prompt loop burned the window's tokens.
     pushRankedRoleLine(lines, "Tokens by role", rankedRoleMap(data.tokensByRole), compactTokens);
+    // The prompt side of the same breakdown, straight after the output-token line: how many
+    // prompt tokens each role sent and the share of them its backend served from cache — the
+    // input side of the bill an operator cannot see from Tokens by role. Zero-prompt roles are
+    // omitted, and an all-zero window renders "-" like the sibling lines.
+    lines.push(promptTokensLine(rankedRoleMap(data.promptTokensByRole ?? {}), rankedRoleMap(data.cacheReadTokensByRole ?? {})));
     // Same breakdown for spend: ranked by spend desc then name asc, zero-spend roles omitted —
     // an all-zero window renders "-" like the runs line.
     pushRankedRoleLine(lines, "Cost by role", rankedRoleMap(data.costByRole), usd);
+}
+/** The provider cost lines and the per-model line, gated to the team report. */
+function pushSinceProviderModelLines(lines, data) {
     // The same breakdown per PROVIDER (plans: per-provider spend), gated to the team report
     // like its day sibling. SinceReport.costByProvider is always present (empty when none), so
     // the zero-means-absent gate prints no line for a window with no provider spend.
@@ -193,15 +249,29 @@ export function renderSinceReportMarkdown(data) {
         // omits it. SinceReport.runsByModel is always present, so a window with no modelled
         // start prints no line (keeping a model-less day's output unchanged), exactly as the
         // provider lines stay absent when no provider spent.
-        const modelPairs = rankedRoleMap(data.runsByModel).filter(([, n]) => n > 0);
-        if (modelPairs.length > 0)
-            lines.push(rankedRoleLine("Runs by model", modelPairs, String));
+        pushPresentRankedLine(lines, "Runs by model", rankedRoleMap(data.runsByModel));
     }
+}
+/** Main's red time and the test/merge culprits behind it, gated like the day sibling. */
+function pushSinceMainRedLines(lines, data) {
     // Main's red wall-clock over the window (main's own, not any role's — a role-scoped
     // collector carries 0, so this never prints for a scoped window). Zero-absent: no line for
     // a window main was never red.
     if (data.mainRedMs > 0)
         lines.push(`**Main red:** ${durationLabel(data.mainRedMs)}`);
+    // The same "what kept main red" detail named by failing test — which tests main's own red
+    // checks named over the window. Team-only like main's red time, so a role-scoped window
+    // omits it; zero-absent: no line when the window's red checks named no test.
+    if (data.role === undefined) {
+        pushPresentRankedLine(lines, "Main red by test", rankedRoleMap(data.mainRedByTest ?? {}));
+        // The same "what kept main red" detail named by merge — the landed merges the watch's
+        // own main_culprit events blamed, mirroring the failing-test line right above. Team-only
+        // like main's red time and zero-absent: no line when the window blamed no merge.
+        pushPresentRankedLine(lines, "Main red by merge", rankedRoleMap(data.mainRedByCulprit ?? {}));
+    }
+}
+/** The review-friction and failed-run breakdowns by role. */
+function pushSinceFrictionLines(lines, data) {
     // The same breakdown for review friction: rejections per role from review_rejected events;
     // a window with none renders "-" like the other lines. The post-merge line is the
     // afterMerge: true subset — rejections that reached an already-merged commit.
@@ -215,16 +285,19 @@ export function renderSinceReportMarkdown(data) {
     // none renders "-" like the other lines.
     pushRankedRoleLine(lines, "Failed runs by role", rankedRoleMap(data.failedRunsByRole));
     pushRankedRoleLine(lines, "Fallbacks by role", rankedRoleMap(data.fallbacksByRole));
-    pushRankedRoleLine(lines, "Image reroutes by role", rankedRoleMap(data.imageReroutesByRole));
+}
+/** Deferred maintenance runs by reason code, gated to the team report. */
+function pushSinceDeferralLines(lines, data) {
     // Deferred maintenance runs per reason code, the --since twin of the day render's line:
     // how many due maintenance runs stood down and why (backlog / no-work / plans-full).
     // Gated to the team report — a reason is not a role, so a role-scoped window omits it.
     // Zero-means-absent: a window with no deferral prints no line.
     if (data.role === undefined) {
-        const deferred = rankedRoleMap(data.deferredByReason ?? {}).filter(([, n]) => n > 0);
-        if (deferred.length > 0)
-            lines.push(rankedRoleLine("Deferred runs by reason", deferred, String));
+        pushPresentRankedLine(lines, "Deferred runs by reason", rankedRoleMap(data.deferredByReason ?? {}));
     }
+}
+/** Commits by role and the merged/merge-failure split, gated to the team report. */
+function pushSinceCommitLines(lines, data) {
     // The merged-commits split by base role, matching the day render's unfiltered line: the
     // window's totals.commits carries the count; this line says which role's commits it was.
     lines.push(rankedRoleLine("Commits by role", rankedRoleMap(data.commitsByRole), String));
@@ -235,22 +308,32 @@ export function renderSinceReportMarkdown(data) {
     // some role has one; a merge-free window renders `-` like the other lines.
     if (data.role === undefined) {
         lines.push(rankedRoleLine("Merged by role", rankedRoleMap(data.mergedByRole), String));
-        const mergeFailures = rankedRoleMap(data.mergeFailedByRole).filter(([, n]) => n > 0);
-        if (mergeFailures.length > 0)
-            lines.push(rankedRoleLine("Merge failures by role", mergeFailures, String));
+        pushPresentRankedLine(lines, "Merge failures by role", rankedRoleMap(data.mergeFailedByRole));
         // WHY the window's merges failed, from each merge_failed's result code — the day
         // report's reason twin of the role line above, so an operator can tell a review
         // rejection (fix the change) from a conflict/block (rebase) from a shutdown abort
         // (capacity). Ranked the same way (count desc then code asc), reason-free only.
-        const mergeFailureReasons = rankedRoleMap(data.mergeFailedByReason ?? {}).filter(([, n]) => n > 0);
-        if (mergeFailureReasons.length > 0)
-            lines.push(rankedRoleLine("Merge failures by reason", mergeFailureReasons, String));
+        pushPresentRankedLine(lines, "Merge failures by reason", rankedRoleMap(data.mergeFailedByReason ?? {}));
     }
+}
+/** Cost/estimated per commit and the notional Estimated by role lines. */
+function pushSinceCostLines(lines, data) {
+    // Spend per merged commit, the --since twin of the day render's `Cost per commit:` line:
+    // costByRole is keyed by role id (instances not folded, so `feature-2` joins `feature`),
+    // commitsByRole is already base-role keyed. Prints for a spend-free window as `-` and for a
+    // role-scoped window from its scoped maps, matching the day render.
+    lines.push(costPerCommitLine("Cost per commit", costPerCommitPairsFrom(foldBaseRoles(data.costByRole), data.commitsByRole)));
     // Subscription spend is notional: its own line, only when the window has any — the same
     // conditional/filtered `usd` form the day render's "Estimated by role" uses.
     if (data.notionalByRole !== undefined) {
         pushRankedRoleLine(lines, "Estimated by role", rankedRoleMap(data.notionalByRole), usd);
+        // The day render's `Estimated per commit:` twin, after `Estimated by role`, from the same
+        // notionalByRole source folded to base roles and the base-keyed commitsByRole.
+        lines.push(costPerCommitLine("Estimated per commit", costPerCommitPairsFrom(foldBaseRoles(data.notionalByRole), data.commitsByRole)));
     }
+}
+/** The trailing blank and the exactly-one coverage/backlog-omission note. */
+function pushSinceCoverageLines(lines, data) {
     lines.push("");
     // Exactly one final line, chosen by the collector's coverage proof: either a hedged note
     // that stays true whenever it prints (the oldest retained event lies inside the window —
@@ -263,24 +346,22 @@ export function renderSinceReportMarkdown(data) {
         lines.push(SPARSE_WINDOW_NOTE);
     else if (data.role === undefined)
         lines.push("backlog tallies (features done / bugs fixed / plans added / bugs filed) need the day report (--days)");
-    return lines.join("\n");
 }
-/** Cost per merged commit by base role. Spend comes from costByRole (keyed by role id, folded to
- * its base role so `feature-2` joins `feature`), commits from commitsByRole (already base-role
- * keyed). `merged` is [role, cost per commit, commits] for roles with both, ranked by cost per
+/** Fold every key of a per-role-id map through its base role, so `feature-2` joins `feature`.
+ * The same fold the day caller does per day, applied to an already-aggregated window map. */
+function foldBaseRoles(map) {
+    const folded = {};
+    for (const [id, c] of Object.entries(map))
+        addTo(folded, baseRoleOf(id), c);
+    return folded;
+}
+/** Rank one cost map against a base-keyed commits map into cost-per-commit output: the shared
+ * core of the day and --since cost-per-commit lines. `cost` is expected base-role keyed (the
+ * day caller folds per day, the --since caller via `foldBaseRoles`); commits are base-role
+ * keyed. `merged` is [role, cost per commit, commits] for roles with both, ranked by cost per
  * commit desc then name asc; `idle` is roles that spent and merged nothing, ranked by spend.
- * Merge spend (the reviewer's) and notional subscription spend stay out by default, matching
- * `**Cost by role:**` (`pick` selects another per-role-id spend map, e.g. notionalByRole); a
- * role with commits but no spend in the picked map appears in neither list. */
-function costPerCommitPairs(series, pick = (d) => d.costByRole) {
-    const cost = {};
-    const commits = {};
-    for (const d of series) {
-        for (const [id, c] of Object.entries(pick(d)))
-            addTo(cost, baseRoleOf(id), c);
-        for (const [role, n] of Object.entries(d.commitsByRole ?? {}))
-            addTo(commits, role, n);
-    }
+ * A role with commits but no spend appears in neither list. */
+function costPerCommitPairsFrom(cost, commits) {
     const mergeDone = [];
     const idleCost = [];
     for (const [role, c] of Object.entries(cost)) {
@@ -295,6 +376,22 @@ function costPerCommitPairs(series, pick = (d) => d.costByRole) {
     sortByValueDesc(mergeDone);
     return { mergeDone, idle: rankCountEntries(idleCost) };
 }
+/** The day caller of the cost-per-commit core: fold each day's role-id-keyed spend map through
+ * its base role (so `feature-2` joins `feature`) and aggregate the base-keyed commitsByRole,
+ * then hand both to `costPerCommitPairsFrom`. `pick` selects the per-role-id spend map; merge
+ * spend (the reviewer's) and notional subscription spend stay out by default, matching
+ * `**Cost by role:**`. */
+function costPerCommitPairs(series, pick = (d) => d.costByRole) {
+    const cost = {};
+    const commits = {};
+    for (const d of series) {
+        for (const [id, c] of Object.entries(pick(d)))
+            addTo(cost, baseRoleOf(id), c);
+        for (const [role, n] of Object.entries(d.commitsByRole ?? {}))
+            addTo(commits, role, n);
+    }
+    return costPerCommitPairsFrom(cost, commits);
+}
 /** One `**<label>:** …` line from costPerCommitPairs output; `-` when there is nothing. */
 function costPerCommitLine(label, pairs) {
     const parts = [
@@ -303,11 +400,8 @@ function costPerCommitLine(label, pairs) {
     ];
     return `**${label}:** ${parts.length === 0 ? "-" : parts.join(" · ")}`;
 }
-/** Render a report as Markdown — the pinned shape the CLI prints and the TUI usage pane
- * (report 3/3) reuses; the GUI tab (report 2/3) renders its own SVG charts from the same
- * ReportData instead. Pure function of ReportData: no I/O, no clock reads. */
-export function renderReportMarkdown(data) {
-    const lines = [];
+/** The title, window line, optional role line, then the report summary line. */
+function pushReportHeader(lines, data) {
     lines.push("# tumwater usage report");
     lines.push("");
     lines.push(reportWindow(data.from, data.to, data.days, eventsRotationLabel()));
@@ -325,6 +419,9 @@ export function renderReportMarkdown(data) {
         : "";
     pushReportSummary(lines, t, tail, data.role !== undefined);
     lines.push("");
+}
+/** The day-by-day window table (day, tokens out, runs, commits, cost) and its blank line. */
+function pushReportSeriesTable(lines, data) {
     const maxTokens = data.series.reduce((m, d) => Math.max(m, d.tokensOut), 0);
     lines.push(...markdownTable(["day", "tokens out", "runs", "commits", "cost"], data.series.map((d) => {
         const runs = Object.values(d.runsByRole).reduce((a, b) => a + b, 0);
@@ -333,16 +430,26 @@ export function renderReportMarkdown(data) {
         return [monthDay(d.date), `${compactTokens(d.tokensOut)}${bar}`, String(runs), String(d.commits), usd(d.costUsd)];
     }), ["left", "right", "right", "right", "right"]));
     lines.push("");
+}
+/** The per-role runs/tokens/prompt/cost breakdown lines. */
+function pushReportRoleLines(lines, data) {
     lines.push(rankedRoleLine("Runs by role", rankedRoleTotals(data.series, (d) => d.runsByRole), String));
     // The same breakdown for output tokens (the resource the budget charges): window totals per
     // role from tokensByRole, ranked like the runs line. Zero-token roles are omitted; an
     // all-zero window renders "-" like the runs line.
     pushRankedRoleLine(lines, "Tokens by role", rankedRoleTotals(data.series, (d) => d.tokensByRole ?? {}), compactTokens);
+    // The input side of that same bill, straight after the output-token line: each role's prompt
+    // totals and, when some run reported a cache read, the share of them served from cache — so
+    // the same report that says who burned output tokens also says whose prompts are cached.
+    lines.push(promptTokensLine(rankedRoleTotals(data.series, (d) => d.promptTokensByRole ?? {}), rankedRoleTotals(data.series, (d) => d.cacheReadTokensByRole ?? {})));
     // The same breakdown for spend: window totals per role from costByRole, ranked by spend
     // desc then name asc — spend is what the operator acts on (an operator tuning per-role
     // intervals wants the burning role first, not the busiest one). Zero-spend roles are
     // omitted; an all-zero window renders "-" like the runs line.
     pushRankedRoleLine(lines, "Cost by role", rankedRoleTotals(data.series, (d) => d.costByRole), usd);
+}
+/** The team-only per-provider and per-model breakdown lines. */
+function pushReportProviderLines(lines, data) {
     // The same breakdown per PROVIDER (plans: per-provider spend): which seam of a mixed team
     // spent what, straight from the events' providerCost maps (run_end's own runs and the
     // merge's reviewer seam). Gated to the team report — a provider is not a role, so a
@@ -357,10 +464,11 @@ export function renderReportMarkdown(data) {
         // omits it (ROLE_SCOPE_NOTE covers the omission), and a window with no modelled start
         // prints no line (keeping a model-less day's output unchanged), exactly as the provider
         // lines stay absent when no provider spent. Ranked and formatted like Cost by role.
-        const modelPairs = rankedRoleTotals(data.series, (d) => d.runsByModel ?? {}).filter(([, n]) => n > 0);
-        if (modelPairs.length > 0)
-            lines.push(rankedRoleLine("Runs by model", modelPairs, String));
+        pushPresentRankedLine(lines, "Runs by model", rankedRoleTotals(data.series, (d) => d.runsByModel ?? {}));
     }
+}
+/** The per-role review-friction and outright-failure lines. */
+function pushReportFrictionLines(lines, data) {
     // The same breakdown for review friction: window rejections per role from review_rejected
     // events, ranked like the runs line; a window with none renders "-". The post-merge line
     // is the afterMerge: true subset — rejections that reached an already-merged commit.
@@ -374,17 +482,20 @@ export function renderReportMarkdown(data) {
     // failure-free window renders no line and an all-zero window renders "-" like the others.
     pushRankedRoleLine(lines, "Failed runs by role", rankedRoleTotals(data.series, (d) => d.failedRunsByRole ?? {}));
     pushRankedRoleLine(lines, "Fallbacks by role", rankedRoleTotals(data.series, (d) => d.fallbacksByRole ?? {}));
-    pushRankedRoleLine(lines, "Image reroutes by role", rankedRoleTotals(data.series, (d) => d.imageReroutesByRole ?? {}));
+}
+/** The team-only deferred-runs-by-reason line. */
+function pushReportDeferralLines(lines, data) {
     // Deferred maintenance runs per reason code — how many due maintenance runs stood down
     // and why, so an idle day reads as backlog-open / no-work / plans-full rather than blank,
     // the per-role breakdown of the deferred maintenances. Gated to the team report — a
     // reason is not a role (ROLE_SCOPE_NOTE covers the omission). Zero-means-absent: a window
     // with no deferral prints no line, so a deferral-free day's output is unchanged.
     if (data.role === undefined) {
-        const deferred = rankedRoleTotals(data.series, (d) => d.deferredByReason ?? {}).filter(([, n]) => n > 0);
-        if (deferred.length > 0)
-            lines.push(rankedRoleLine("Deferred runs by reason", deferred, String));
+        pushPresentRankedLine(lines, "Deferred runs by reason", rankedRoleTotals(data.series, (d) => d.deferredByReason ?? {}));
     }
+}
+/** The Commits-by-role line plus the team-only merge/main-red/cameo block. */
+function pushReportMergeLines(lines, data) {
     // Work ratio 4/4: the merged commits split by base role and by tier. The totals line's
     // `commits` carries the count; these lines say who made it and how much of it was work.
     lines.push(rankedRoleLine("Commits by role", rankedRoleTotals(data.series, (d) => d.commitsByRole ?? {}), String));
@@ -398,14 +509,10 @@ export function renderReportMarkdown(data) {
     if (data.role === undefined) {
         const mergeDone = rankedRoleTotals(data.series, (d) => d.mergedByRole ?? {});
         lines.push(rankedRoleLine("Merged by role", mergeDone, String));
-        const mergeFailures = rankedRoleTotals(data.series, (d) => d.mergeFailedByRole ?? {}).filter(([, n]) => n > 0);
-        if (mergeFailures.length > 0)
-            lines.push(rankedRoleLine("Merge failures by role", mergeFailures, String));
+        pushPresentRankedLine(lines, "Merge failures by role", rankedRoleTotals(data.series, (d) => d.mergeFailedByRole ?? {}));
         // The --since reason twin, folded across the series the same way; a reason-free window
         // prints no line, so its output is byte-for-byte unchanged.
-        const mergeFailureReasons = rankedRoleTotals(data.series, (d) => d.mergeFailedByReason ?? {}).filter(([, n]) => n > 0);
-        if (mergeFailureReasons.length > 0)
-            lines.push(rankedRoleLine("Merge failures by reason", mergeFailureReasons, String));
+        pushPresentRankedLine(lines, "Merge failures by reason", rankedRoleTotals(data.series, (d) => d.mergeFailedByReason ?? {}));
         // Per-day median passing check time, so a suite slowing over days shows; days without a
         // check are left out, and no line prints when no day has one (zero means absent).
         pushDayCameoLine(lines, data.series, "Merge check median", (d) => d.checkMedianMs);
@@ -413,9 +520,17 @@ export function renderReportMarkdown(data) {
         // suite went red before passing shows here. Zero-absent: no line when no day fails.
         pushDayCameoLine(lines, data.series, "Red merge checks", (d) => d.checkFailures, (n) => `×${n}`);
         // Per-day main red wall-clock, beside the red-check counts above: how long each day main
-        // had no passing full check (the span every code role was held). Team-only (main's own
+        // had its own check red (the span main had no passing full check). Team-only (main's own
         // red time, not any role's) and zero-absent: no line when no day was red.
         pushDayCameoLine(lines, data.series, "Main red", (d) => d.mainRedMs, durationLabel);
+        // The day twin of the --since window's totals line: the same tests ranked across the
+        // series' per-day main-red maps (Main red by test). Zero-absent: no line when no day
+        // named a failing test.
+        pushPresentRankedLine(lines, "Main red by test", rankedRoleTotals(data.series, (d) => d.mainRedByTest ?? {}));
+        // The day twin of the --since window's merges line: the same culprits ranked across the
+        // series' per-day main-red maps (Main red by merge). Zero-absent: no line when no day
+        // blamed a merge.
+        pushPresentRankedLine(lines, "Main red by merge", rankedRoleTotals(data.series, (d) => d.mainRedByCulprit ?? {}));
         pushDayCameoLine(lines, data.series, "Merge wait median", (d) => d.mergeWaitMedianMs);
         // How long the merge slot itself held each change it landed, beside the merge-wait median:
         // the queue backlog (merge wait minus slot time) apart from the slot's own review/check/
@@ -429,6 +544,10 @@ export function renderReportMarkdown(data) {
         pushDayCameoLine(lines, data.series, "Workspace wait median", (d) => d.slotWaitMedianMs);
         pushDayCameoLine(lines, data.series, "Check wait median", (d) => d.checkWaitMedianMs);
     }
+}
+/** Cost/commits tail: cost per commit, notional block, lag, validation gaps, sparse note. */
+function pushReportTail(lines, data) {
+    const t = data.totals;
     lines.push(costPerCommitLine("Cost per commit", costPerCommitPairs(data.series)));
     // Subscription spend is notional: its own two lines, only when the window has any.
     if ((t.notionalCostUsd ?? 0) > 0) {
@@ -466,5 +585,19 @@ export function renderReportMarkdown(data) {
     // it prints — an empty or fully covered log never claims a history it cannot see.
     if (!data.coversFullWindow)
         lines.push("", SPARSE_WINDOW_NOTE);
+}
+/** Render a report as Markdown — the pinned shape the CLI prints and the TUI usage pane
+ * (report 3/3) reuses; the GUI tab (report 2/3) renders its own SVG charts from the same
+ * ReportData instead. Pure function of ReportData: no I/O, no clock reads. */
+export function renderReportMarkdown(data) {
+    const lines = [];
+    pushReportHeader(lines, data);
+    pushReportSeriesTable(lines, data);
+    pushReportRoleLines(lines, data);
+    pushReportProviderLines(lines, data);
+    pushReportFrictionLines(lines, data);
+    pushReportDeferralLines(lines, data);
+    pushReportMergeLines(lines, data);
+    pushReportTail(lines, data);
     return lines.join("\n");
 }

package/dist/src/report/report-since-data.js

@@ -0,0 +1,218 @@
+/** The trailing-window half of the usage report's collection: read the harness's event log
+ * over the `sinceMs` window and distill it into a `SinceReport` — run/token/commit/cost
+ * totals plus features-done/cost maps and main-red tallies. Split out of
+ * src/report/report-data.ts (which keeps the per-day `ReportData` series collector) so each
+ * window collector owns its own helpers and its own shape: the day collector's zero-filled
+ * series and backlog-file reads have no place in a window totals view, and the two change
+ * for different reasons. The event-log folding both collectors share lives in
+ * src/report/report-usage-fold.ts (foldUsageEvent) and src/report/report-fold.ts (the windowed
+ * cache and scope helpers), the shapes they produce in src/report/report-types.ts, and the
+ * Markdown rendering in src/report/report-render.ts. */
+import { assertReportSinceMs, eventWindowCovers, readWindowEvents, sinceWindowTiming } from "../events/event-window.js";
+import { dayKey } from "../text/datetime.js";
+import { addTo } from "../collections.js";
+import { nonemptyObj, roleSum, scopeBases, scopedByRole, zeroCommitCounts, zeroMergeCounts, } from "./report-fold.js";
+import { foldUsageEvent } from "./report-usage-fold.js";
+import { mainRedCulpritsByDay, mainRedFailingTestsByDay, mainRedMinutesByDay } from "./report-main-red.js";
+/** Aggregate team usage over the trailing `sinceMs` window ending now (or `untilMs` ago, which
+ * drops events at or after that end; `coversFullWindow` still judges the far edge
+ * only), from the event log only (run_end/merged — see SinceReport for why the backlog files
+ * are not read). Kept a
+ * separate function rather than a `collectReport` variant flag: the day collector's
+ * zero-filled series and backlog-file reads have no place in a window totals view. */
+export function collectReportSince(root, sinceMs, role, untilMs) {
+    assertReportSinceMs(sinceMs);
+    const { now, cutoff, end, slice } = sinceWindowTiming(sinceMs, untilMs);
+    const { raw, acc } = foldSinceWindow(root, cutoff, now, end, untilMs);
+    // The empty-window branch of the shared proof matters here: with no retained events nothing
+    // can have rotated away, and printing a rotation note over a fresh install would claim a
+    // history that never existed. When neither proof holds, the oldest retained event lies inside
+    // the window and the render notes the possible truncation.
+    const coversFullWindow = eventWindowCovers(raw, cutoff);
+    // Role scope: every map and total below derives from the fold's per-role maps for the named
+    // base roles alone — merge usage (the merge slot's, not the role's) and the team-only
+    // fields stay out, so a scoped --since report sums exactly the same events the scoped day
+    // report would. The scope is the base roles, so instances (`feature-2`) aggregate into their
+    // group as the cap does.
+    const bases = scopeBases(role);
+    return {
+        ...slice,
+        ...(bases === undefined ? {} : { role: bases.join(",") }),
+        totals: sinceScopedTotals(acc, bases),
+        ...sinceRoleMaps(acc, bases),
+        // Main's red time is main's own (G1's rule), not any role's, so a role-scoped window
+        // carries 0 — the type's always-present default for the team-only field.
+        mainRedMs: bases === undefined
+            ? [...mainRedMinutesByDay(raw.events, cutoff, end).values()].reduce((a, b) => a + b, 0)
+            : 0,
+        ...nonemptyObj("mainRedByTest", sinceMainRedByTest(raw, cutoff, end, bases)),
+        ...nonemptyObj("mainRedByCulprit", sinceMainRedByCulprit(raw, cutoff, end, bases)),
+        coversFullWindow,
+    };
+}
+/** The window's event read and fold, one function so the read happens exactly once per window
+ * and every downstream builder — the coverage proof and the main-red by-test/by-culprit maps
+ * — consumes the same `raw`. `raw` is the one day-keyed log read the whole report is built on
+ * (its `events` feed both the `acc` fold below and the red maps), so its retention-backed
+ * coverage and its event set cannot disagree across the builders. */
+function foldSinceWindow(root, cutoff, now, end, untilMs) {
+    // The window key is the cutoff's local calendar day, from the shared dayKey helper
+    // eventDayKey buckets events with, so the read's day keys cannot disagree with the ts
+    // filter below; the day-keyed read may include earlier hours of that day, which the ts
+    // filter removes (over-read is at most one day's events). Future-dated events are dropped
+    // here too, matching collectReport (its day map only holds the window's days).
+    const fromKey = dayKey(cutoff);
+    const raw = readWindowEvents(root, fromKey);
+    const acc = {
+        runs: 0,
+        runsByRole: {},
+        rejectionsByRole: {},
+        postMergeRejectionsByRole: {},
+        revisionsByRole: {},
+        refusalsByRole: {},
+        checkDurationsMs: [],
+        checkFailures: 0,
+        mergeWaitsMs: [],
+        mergeDurationsMs: [],
+        runDurationsMs: [],
+        providerWaitsMs: [],
+        slotWaitsMs: [],
+        checkWaitsMs: [],
+        reviewDurationsMs: [],
+        failedRunsByRole: {},
+        fallbacksByRole: {},
+        tokensByRole: {},
+        promptTokensByRole: {},
+        cacheReadTokensByRole: {},
+        costByRole: {},
+        tokensOut: 0,
+        ...zeroCommitCounts(),
+        costUsd: 0,
+        notionalCostUsd: 0,
+        notionalByRole: {},
+        ...zeroMergeCounts(),
+        mergedByRole: {},
+        mergeFailedByRole: {},
+        mergeFailedByReason: {},
+        costByProvider: {},
+        notionalByProvider: {},
+        notionalByBackend: {},
+        runsByModel: {},
+        deferredByReason: {},
+    };
+    for (const ev of raw.events) {
+        if (typeof ev.ts !== "number" || ev.ts < cutoff || ev.ts > now || (untilMs !== undefined && ev.ts >= end))
+            continue;
+        foldUsageEvent(acc, ev);
+    }
+    return { raw, acc };
+}
+/** The window's `totals` group under both scope rules, named so the team-vs-role branch reads
+ * as one function instead of a ternary buried in the return: the team figure sums the merge-slot
+ * fields in (the merge slot's dash tokens/cost are the same team spend the budget charges), while
+ * the role branch sums just the base roles through `roleSum` and zeroes the merge counts — a
+ * role's merge usage is the merge slot's, not the role's. */
+function sinceScopedTotals(acc, bases) {
+    return bases === undefined
+        ? {
+            tokensOut: acc.tokensOut + (acc.mergeTokens ?? 0),
+            runs: acc.runs ?? 0,
+            commits: acc.commits,
+            costUsd: acc.costUsd + (acc.mergeCostUsd ?? 0),
+            ...(acc.notionalCostUsd > 0 ? { notionalCostUsd: acc.notionalCostUsd } : {}),
+            ...nonemptyObj("notionalByBackend", acc.notionalByBackend),
+            mergeRuns: acc.mergeRuns ?? 0,
+            mergeTokens: acc.mergeTokens ?? 0,
+            mergeCostUsd: acc.mergeCostUsd ?? 0,
+            ...((acc.mergeFailed ?? 0) > 0 ? { mergeFailed: acc.mergeFailed } : {}),
+        }
+        : (() => {
+            // The role's own notional spend, from its run_end events; the merge slot's
+            // notional is team-wide and stays out like its cost.
+            const notional = roleSum(acc.notionalByRole, bases);
+            return {
+                tokensOut: roleSum(acc.tokensByRole, bases),
+                runs: roleSum(acc.runsByRole, bases),
+                commits: roleSum(acc.commitsByRole, bases),
+                costUsd: roleSum(acc.costByRole, bases),
+                ...(notional > 0 ? { notionalCostUsd: notional } : {}),
+                ...zeroMergeCounts(),
+            };
+        })();
+}
+/** Flatten a per-day main-red record map (day → label → count) into one flat label→count map,
+ * the shared body of sinceMainRedByTest and sinceMainRedByCulprit. Main's red state is main's
+ * own, not any role's, so a role-scoped window carries none — the empty map `nonemptyObj` then
+ * omits from the JSON, keeping a red-free --since byte-identical to today. */
+function flattenMainRedByDay(perDay, bases) {
+    if (bases !== undefined)
+        return {};
+    const flat = {};
+    for (const record of perDay.values()) {
+        for (const [label, n] of Object.entries(record))
+            addTo(flat, label, n);
+    }
+    return flat;
+}
+/** Main's red failing tests over the window, flattened across the per-day records of the same
+ * red `main_check` events the red time uses (G1's rule) into one map. Main's failing tests are
+ * main's own, not any role's, so a role-scoped window carries none (see flattenMainRedByDay). */
+function sinceMainRedByTest(raw, cutoff, end, bases) {
+    return flattenMainRedByDay(mainRedFailingTestsByDay(raw.events, cutoff, end), bases);
+}
+/** Main's red culprits over the window, flattened across the per-day records of the same red
+ * `main_culprit` events the live `mainred` alert's `red.culprit` reads (the historical twin)
+ * into one map. Main's own blame, not any role's, so a role-scoped window carries none (see
+ * flattenMainRedByDay). */
+function sinceMainRedByCulprit(raw, cutoff, end, bases) {
+    return flattenMainRedByDay(mainRedCulpritsByDay(raw.events, cutoff, end), bases);
+}
+/** The `SinceReport` return's role-scoped map group — every field a reader names when asking
+ * "which fields are team-only?": each `scopedByRole` call applies the base-role scope (the
+ * rule `collectReportSince`'s `bases` comment spells), so a role-scoped window shows exactly
+ * the maps the scoped day report would, and the team-only fields (providers, backends, models,
+ * deferred reasons) carry full maps for the team or empty maps for a scoped role. */
+function sinceRoleMaps(acc, bases) {
+    // The --since render/JSON's Notional by role line is conditional on the window's own
+    // notional spend, scoped to base when a role is given — the same conditional the day
+    // collector applies to ReportDay.notionalByRole (line ~573), so a role-scoped window
+    // whose role spent no notional carries no notionalByRole instead of an empty map.
+    const notionalByRole = scopedByRole(acc.notionalByRole, bases);
+    // Deferred runs are bucketed by a reason code (not a role), so a role-scoped window
+    // carries no entries — the same team-only rule runsByModel follows. Only set when the
+    // window actually deferred (zero means absent), so a deferral-free --since JSON omits it.
+    const deferred = scopedByRole(acc.deferredByReason, bases);
+    return {
+        runsByRole: scopedByRole(acc.runsByRole, bases),
+        costByRole: scopedByRole(acc.costByRole, bases),
+        rejectionsByRole: scopedByRole(acc.rejectionsByRole, bases),
+        postMergeRejectionsByRole: scopedByRole(acc.postMergeRejectionsByRole, bases),
+        revisionsByRole: scopedByRole(acc.revisionsByRole, bases),
+        refusalsByRole: scopedByRole(acc.refusalsByRole, bases),
+        failedRunsByRole: scopedByRole(acc.failedRunsByRole, bases),
+        fallbacksByRole: scopedByRole(acc.fallbacksByRole, bases),
+        tokensByRole: scopedByRole(acc.tokensByRole, bases),
+        ...nonemptyObj("promptTokensByRole", scopedByRole(acc.promptTokensByRole, bases)),
+        ...nonemptyObj("cacheReadTokensByRole", scopedByRole(acc.cacheReadTokensByRole, bases)),
+        commitsByRole: scopedByRole(acc.commitsByRole, bases),
+        mergedByRole: scopedByRole(acc.mergedByRole, bases),
+        mergeFailedByRole: scopedByRole(acc.mergeFailedByRole, bases),
+        // A result code is not a role, so a role-scoped window carries an empty map (a code
+        // never baseRoleOf to the role) — the render gates the reason line to the team report.
+        mergeFailedByReason: scopedByRole(acc.mergeFailedByReason, bases),
+        ...nonemptyObj("notionalByRole", notionalByRole),
+        // Provider spend is a team attribution (a provider is not a role), so a role-scoped
+        // window carries empty maps — providers never baseRoleOf to the role — and the render
+        // gates the provider lines to the team report anyway. Always present, empty when none.
+        costByProvider: scopedByRole(acc.costByProvider, bases),
+        notionalByProvider: scopedByRole(acc.notionalByProvider, bases),
+        // Backend spend is a team attribution (a backend is not a role), so a role-scoped window
+        // omits it — the same absent-when-empty rule the day collector applies.
+        ...nonemptyObj("notionalByBackend", scopedByRole(acc.notionalByBackend, bases)),
+        // Model attribution is team-only (a model is not a role, so no model folds to the
+        // scoped role), the same full-map-for-team / empty-for-scoped rule costByProvider
+        // follows. Always present so the render can gate on the window's own events.
+        runsByModel: scopedByRole(acc.runsByModel, bases),
+        ...nonemptyObj("deferredByReason", deferred),
+    };
+}