tumwater 0.1.2 → 0.2.0

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

@@ -1,10 +1,12 @@
-import { addTo, rankCountEntries } from "../collections.js";
+import { addTo, rankCountEntries, sortByValueDesc } from "../collections.js";
 import { compactTokens, usd } from "../text/format.js";
 import { durationLabel } from "../cli/cli-args.js";
 import { monthDay, reportWindow, sinceWindowLine } from "../text/datetime.js";
 import { eventsRotationLabel } from "../events/events.js";
 import { SPARSE_WINDOW_NOTE } from "../events/event-window.js";
+import { shortSpanPhrase } from "../text/phrases.js";
 import { markdownTable } from "../text/markdown.js";
+import { baseRoleOf } from "../roles/loop-ids.js";
 /** Bar width for one day: up to 20 blocks scaled to the window's max tokensOut —
  * round(20·v/max), min 1 when v > 0. */
 function barWidth(v, max) {
@@ -20,7 +22,7 @@ function rankedRoleMap(totals) {
     return rankCountEntries(Object.entries(totals));
 }
 /** Window totals per role: fold the per-day role maps (any `Record<string, number>` day field,
- * e.g. ticksByRole or costByRole) across the series, then rank through rankedRoleMap.
+ * e.g. runsByRole or costByRole) across the series, then rank through rankedRoleMap.
  * Callers filter/format the ranked pairs. */
 function rankedRoleTotals(series, pick) {
     const totals = {};
@@ -35,43 +37,72 @@ function rankedRoleTotals(series, pick) {
 function rankedRoleLine(label, pairs, fmt) {
     return `**${label}:** ${pairs.length === 0 ? "-" : pairs.map(([r, n]) => `${r} — ${fmt(n)}`).join(" · ")}`;
 }
+/** The per-day-median line of the team day report — "MMM D <span>" 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 merge check-time and merge-wait
+ * medians so their date+span cells and title line cannot drift; the planned provider-slot wait
+ * median is a third caller of the same rule. */
+function medianLine(series, title, pick) {
+    const cells = series.flatMap((d) => {
+        const v = pick(d);
+        return v === undefined ? [] : [`${monthDay(d.date)} ${shortSpanPhrase(v)}`];
+    });
+    return cells.length > 0 ? `**${title}:** ${cells.join(" · ")}` : undefined;
+}
+/** Push the `Cost by provider` and `Estimated by provider` lines of the per-provider spend
+ * breakdown (plans: per-provider spend), from the caller's already-ranked real- and notional-
+ * spend pairs. Role scoping is the caller's `role === undefined` gate — this helper only
+ * renders. Zero-means-absent: a provider with no spend prints no line, and both lanes format
+ * with usd so the day and --since windows cannot drift (the --since path ranks via rankedRoleMap,
+ * the day path via rankedRoleTotals). */
+function pushProviderCostLines(lines, rankCost, rankNotional) {
+    const providers = rankCost().filter(([, c]) => c > 0);
+    if (providers.length > 0)
+        lines.push(rankedRoleLine("Cost by provider", providers, usd));
+    const notionalProviders = rankNotional().filter(([, c]) => c > 0);
+    if (notionalProviders.length > 0)
+        lines.push(rankedRoleLine("Estimated by provider", notionalProviders, usd));
+}
 /** The "**Totals:** …" line both renders print — one home so field order, units, and the ·
  * separators cannot drift between the day report and the --since window. `tail` carries the
- * cells only one shape has: the day report's features/bugs counts (a sub-day window cannot
- * subdivide their day-granular dates, so the --since render passes nothing). */
+ * cells only one shape has: the day report's features/bugs counts and the filing counts
+ * (a sub-day window cannot subdivide their day-granular dates, so the --since render passes
+ * nothing). */
 function totalsLine(t, tail = "") {
-    return `**Totals:** ${compactTokens(t.tokensOut)} output tokens · ${t.ticks} ticks · ${t.commits} commits · ${usd(t.costUsd)}${tail}`;
+    return `**Totals:** ${compactTokens(t.tokensOut)} output tokens · ${t.runs} runs · ${t.commits} commits · ${usd(t.costUsd)}${tail}`;
 }
-/** The "of which landing runs …" line under a totals line — one home for the landing share's
- * wording. The caller decides when it prints: zero-means-absent, so a fleet with no landing
- * spend renders exactly as before (the budget charges the landing slot's runs too, so the
+/** The "of which merge runs …" line under a totals line — one home for the merge share's
+ * wording. The caller decides when it prints: zero-means-absent, so a team with no merge
+ * spend renders exactly as before (the budget charges the merge slot's runs too, so the
  * totals include them — this line says how much of the spend was reviewer + conflict
  * resolution work). */
-function landingShareLine(t) {
-    return `of which landing runs: ${t.landingRuns} runs · ${compactTokens(t.landingTokens)} tokens · ${usd(t.landingCostUsd)} (reviewer + conflict resolution)`;
+function mergeShareLine(t) {
+    const failed = (t.mergeFailed ?? 0) > 0 ? ` (${t.mergeFailed} failed)` : "";
+    return `of which merge runs: ${t.mergeRuns} runs${failed} · ${compactTokens(t.mergeTokens)} tokens · ${usd(t.mergeCostUsd)} (reviewer + conflict resolution)`;
 }
 /** The notional-spend line (plans/agent-backends.md part 6a): the API-equivalent cost of
  * claude.ai subscription runs folded into the window. Never part of the totals' costUsd,
  * because a subscription run is exempt from the daily dollar cap; the caller prints it only
- * when a subscription run actually folded in (zero means absent, like the landing line), so
- * an API-only fleet's report is unchanged. */
+ * when a subscription run actually folded in (zero means absent, like the merge line), so
+ * an API-only team's report is unchanged. */
 function notionalLine(t) {
-    return `claude subscription, API-equivalent: ${usd(t.notionalCostUsd ?? 0)} notional`;
+    return `claude subscription, API-equivalent: ${usd(t.notionalCostUsd ?? 0)} estimated`;
 }
-/** The scope note a `--role` report prints: landing runs belong to the landing slot and the
- * features-done/bugs-fixed tallies come from day-granular backlog-file dates, so neither can
- * be scoped to a role and both are omitted from the scoped totals. Shared by the day and
+/** The scope note a `--role` report prints: merge runs belong to the merge slot and the
+ * day-granular backlog tallies (features done / bugs fixed / plans added / bugs filed) come
+ * from day-granular backlog-file dates, so none can
+ * be scoped to a role and all are omitted from the scoped totals. Shared by the day and
  * --since renders so the two say the same thing. */
-const ROLE_SCOPE_NOTE = "role scope: landing runs and backlog tallies (features done / bugs fixed) are fleet-wide and omitted";
+const ROLE_SCOPE_NOTE = "role scope: merge runs and backlog tallies (features done / bugs fixed / plans added / bugs filed) are team-wide and omitted";
 /** The summary block both report shapes print, in the same order: the totals line (carrying
- * the caller's extra `tail` cells), the landing-share line and the notional line when each is
- * nonzero (zero means absent, so an API-only or landing-free window renders as before), and the
+ * the caller's extra `tail` cells), the merge-share line and the notional line when each is
+ * nonzero (zero means absent, so an API-only or merge-free window renders as before), and the
  * role-scope note when the report is scoped. One home so the day report and the --since window
  * cannot drift on the order, the omission predicates, or the scope note. */
 function pushReportSummary(lines, t, tail = "", scoped = false) {
     lines.push(totalsLine(t, tail));
-    if (t.landingRuns > 0)
-        lines.push(landingShareLine(t));
+    if (t.mergeRuns > 0)
+        lines.push(mergeShareLine(t));
     if ((t.notionalCostUsd ?? 0) > 0)
         lines.push(notionalLine(t));
     if (scoped)
@@ -90,15 +121,82 @@ export function renderSinceReportMarkdown(data) {
         lines.push(`role: ${data.role}`);
     lines.push("");
     const t = data.totals;
-    // Same totals voice as the day report, minus the features/bugs 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.
+    // 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("");
-    lines.push(rankedRoleLine("Ticks by role", rankedRoleMap(data.ticksByRole), String));
+    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.
+    lines.push(rankedRoleLine("Tokens by role", rankedRoleMap(data.tokensByRole).filter(([, n]) => n > 0), compactTokens));
     // Same breakdown for spend: ranked by spend desc then name asc, zero-spend roles omitted —
     // an all-zero window renders "-" like the ticks line.
     lines.push(rankedRoleLine("Cost by role", rankedRoleMap(data.costByRole).filter(([, c]) => c > 0), usd));
+    // 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.
+    if (data.role === undefined) {
+        pushProviderCostLines(lines, () => rankedRoleMap(data.costByProvider), () => rankedRoleMap(data.notionalByProvider));
+        // The same breakdown per MODEL (each run_start's agent-qualified selector — the model a
+        // team mixing providers, per-role overrides and fallbacks actually ran on), gated to the
+        // team report like the provider lines: a model is not a role, so a role-scoped window
+        // 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));
+    }
+    // The same breakdown for review friction: rejections per role from review_rejected events;
+    // a window with none renders "-" like the other lines.
+    lines.push(rankedRoleLine("Rejections by role", rankedRoleMap(data.rejectionsByRole).filter(([, r]) => r > 0), String));
+    lines.push(rankedRoleLine("Revisions by role", rankedRoleMap(data.revisionsByRole).filter(([, r]) => r > 0), String));
+    lines.push(rankedRoleLine("Refusals by role", rankedRoleMap(data.refusalsByRole).filter(([, r]) => r > 0), String));
+    // The same breakdown for outright failures: error-class run_ends per role under the
+    // digest's OUTCOME_CLASS — the ticks that burned agent time and merged nothing without
+    // going through review, which rejections/revisions would miss entirely. A window with
+    // none renders "-" like the other lines.
+    lines.push(rankedRoleLine("Failed runs by role", rankedRoleMap(data.failedRunsByRole).filter(([, n]) => n > 0), String));
+    lines.push(rankedRoleLine("Fallbacks by role", rankedRoleMap(data.fallbacksByRole).filter(([, n]) => n > 0), String));
+    lines.push(rankedRoleLine("Image reroutes by role", rankedRoleMap(data.imageReroutesByRole).filter(([, n]) => n > 0), String));
+    // Deferred maintenance ticks 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));
+    }
+    // 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));
+    // The merged-outcomes split by base role, mirroring the day render's line: which roles'
+    // changes reach main and which bounce off the gate (merge_failed). Gated to the team
+    // report — a role-scoped window omits merge (ROLE_SCOPE_NOTE), so the per-role
+    // attribution would contradict it. Zero-means-absent: the failures line prints only when
+    // 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));
+        // 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));
+    }
+    // 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) {
+        lines.push(rankedRoleLine("Estimated by role", rankedRoleMap(data.notionalByRole).filter(([, c]) => c > 0), usd));
+    }
     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 —
@@ -110,9 +208,47 @@ export function renderSinceReportMarkdown(data) {
     if (!data.coversFullWindow)
         lines.push(SPARSE_WINDOW_NOTE);
     else if (data.role === undefined)
-        lines.push("backlog tallies (features done / bugs fixed) need the day report (--days)");
+        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 loop 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
+ * 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-loop-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);
+    }
+    const mergeDone = [];
+    const idleCost = [];
+    for (const [role, c] of Object.entries(cost)) {
+        if (c <= 0)
+            continue;
+        const n = commits[role] ?? 0;
+        if (n > 0)
+            mergeDone.push([role, c / n, n]);
+        else
+            idleCost.push([role, c]);
+    }
+    sortByValueDesc(mergeDone);
+    return { mergeDone, idle: rankCountEntries(idleCost) };
+}
+/** One `**<label>:** …` line from costPerCommitPairs output; `-` when there is nothing. */
+function costPerCommitLine(label, pairs) {
+    const parts = [
+        ...pairs.mergeDone.map(([r, per, n]) => `${r} — ${usd(per)} (${n})`),
+        ...pairs.idle.map(([r, c]) => `${r} — ${usd(c)}, no commits`),
+    ];
+    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. */
@@ -125,33 +261,134 @@ export function renderReportMarkdown(data) {
         lines.push(`role: ${data.role}`);
     lines.push("");
     const t = data.totals;
-    // A role-scoped report drops the fleet-only features/bugs cells from the totals line — their
-    // dates carry no role — and states the omission through ROLE_SCOPE_NOTE below instead.
-    const tail = data.role === undefined ? ` · ${t.featuresDone} features done · ${t.bugsFixed} bugs fixed` : "";
+    // A role-scoped report drops the team-only features/bugs and filing cells from the totals
+    // line — their dates carry no role — and states the omission through ROLE_SCOPE_NOTE below.
+    const openedTail = (t.plansAdded ?? 0) + (t.bugsFiled ?? 0) > 0
+        ? ` · ${t.plansAdded ?? 0} plans added · ${t.bugsFiled ?? 0} bugs filed`
+        : "";
+    const tail = data.role === undefined
+        ? ` · ${t.featuresDone} features done · ${t.bugsFixed} bugs fixed${openedTail}`
+        : "";
     pushReportSummary(lines, t, tail, data.role !== undefined);
     lines.push("");
     const maxTokens = data.series.reduce((m, d) => Math.max(m, d.tokensOut), 0);
-    lines.push(...markdownTable(["day", "tokens out", "ticks", "commits", "cost"], data.series.map((d) => {
-        const ticks = Object.values(d.ticksByRole).reduce((a, b) => a + b, 0);
+    lines.push(...markdownTable(["day", "tokens out", "runs", "commits", "cost"], data.series.map((d) => {
+        const ticks = Object.values(d.runsByRole).reduce((a, b) => a + b, 0);
         const w = maxTokens > 0 ? barWidth(d.tokensOut, maxTokens) : 0;
         const bar = w > 0 ? ` ${"█".repeat(w)}` : ""; // Zero days carry no bar (and no stray space).
         return [monthDay(d.date), `${compactTokens(d.tokensOut)}${bar}`, String(ticks), String(d.commits), usd(d.costUsd)];
     }), ["left", "right", "right", "right", "right"]));
     lines.push("");
-    lines.push(rankedRoleLine("Ticks by role", rankedRoleTotals(data.series, (d) => d.ticksByRole), String));
+    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 ticks line. Zero-token roles are omitted; an
+    // all-zero window renders "-" like the ticks line.
+    lines.push(rankedRoleLine("Tokens by role", rankedRoleTotals(data.series, (d) => d.tokensByRole ?? {}).filter(([, n]) => n > 0), compactTokens));
     // 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 loop first, not the busiest one). Zero-spend roles are
     // omitted; an all-zero window renders "-" like the ticks line.
     lines.push(rankedRoleLine("Cost by role", rankedRoleTotals(data.series, (d) => d.costByRole).filter(([, c]) => c > 0), usd));
-    // Work ratio 4/4: the landed commits split by base role and by tier. The totals line's
+    // 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
+    // role-scoped report omits it (ROLE_SCOPE_NOTE covers the omission). Zero-means-absent: a
+    // window with no provider spend prints no line. Ranked and formatted exactly like Cost by
+    // role.
+    if (data.role === undefined) {
+        pushProviderCostLines(lines, () => rankedRoleTotals(data.series, (d) => d.costByProvider ?? {}), () => rankedRoleTotals(data.series, (d) => d.notionalByProvider ?? {}));
+        // The same breakdown per MODEL (each run_start's agent-qualified selector — the model a
+        // team mixing providers, per-role overrides and fallbacks actually ran on), gated to the
+        // team report like the provider lines: a model is not a role, so a role-scoped report
+        // 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));
+    }
+    // The same breakdown for review friction: window rejections per role from review_rejected
+    // events, ranked like the ticks line; a window with none renders "-".
+    lines.push(rankedRoleLine("Rejections by role", rankedRoleTotals(data.series, (d) => d.rejectionsByRole ?? {}).filter(([, r]) => r > 0), String));
+    lines.push(rankedRoleLine("Revisions by role", rankedRoleTotals(data.series, (d) => d.revisionsByRole ?? {}).filter(([, r]) => r > 0), String));
+    lines.push(rankedRoleLine("Refusals by role", rankedRoleTotals(data.series, (d) => d.refusalsByRole ?? {}).filter(([, r]) => r > 0), String));
+    // The same breakdown for outright failures: error-class run_ends per role under the
+    // digest's OUTCOME_CLASS — ticks that burned agent time and merged nothing without going
+    // through review, which rejections/revisions would miss entirely. Zero-means-absent, so a
+    // failure-free window renders no line and an all-zero window renders "-" like the others.
+    lines.push(rankedRoleLine("Failed runs by role", rankedRoleTotals(data.series, (d) => d.failedRunsByRole ?? {}).filter(([, n]) => n > 0), String));
+    lines.push(rankedRoleLine("Fallbacks by role", rankedRoleTotals(data.series, (d) => d.fallbacksByRole ?? {}).filter(([, n]) => n > 0), String));
+    lines.push(rankedRoleLine("Image reroutes by role", rankedRoleTotals(data.series, (d) => d.imageReroutesByRole ?? {}).filter(([, n]) => n > 0), String));
+    // Deferred maintenance ticks 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));
+    }
+    // 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));
+    // The merged-outcomes split by base role: which authoring roles' changes reach main through
+    // the merge slot, and — the new signal — which roles' changes bounce off the gate (a
+    // merge_failed: review rejection, under-cap review, a conflict, a blocked fast-forward, a
+    // shutdown abort). Gated to the team report — a role-scoped report omits merge runs
+    // (they are the merge slot's, per ROLE_SCOPE_NOTE), so the per-role attribution would
+    // contradict that stance. Zero-means-absent: a window with merges renders Merged by role;
+    // the failures line prints only when some role actually has one.
+    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));
+        // 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));
+        // 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).
+        const medians = medianLine(data.series, "Merge check median", (d) => d.checkMedianMs);
+        if (medians !== undefined)
+            lines.push(medians);
+        // Per-day count of red full-suite checks, beside the passing medians above; a day whose
+        // suite went red before passing shows here. Zero-absent: no line when no day fails.
+        const reds = data.series.flatMap((d) => d.checkFailures === undefined ? [] : [`${monthDay(d.date)} ×${d.checkFailures}`]);
+        if (reds.length > 0)
+            lines.push(`**Red merge checks:** ${reds.join(" · ")}`);
+        const waits = medianLine(data.series, "Merge wait median", (d) => d.mergeWaitMedianMs);
+        if (waits !== undefined)
+            lines.push(waits);
+        const providerWaits = medianLine(data.series, "Provider wait median", (d) => d.providerWaitMedianMs);
+        if (providerWaits !== undefined)
+            lines.push(providerWaits);
+        const slotWaits = medianLine(data.series, "Workspace wait median", (d) => d.slotWaitMedianMs);
+        if (slotWaits !== undefined)
+            lines.push(slotWaits);
+    }
+    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) {
+        const notionalOf = (d) => d.notionalByRole ?? {};
+        lines.push(rankedRoleLine("Estimated by role", rankedRoleTotals(data.series, notionalOf).filter(([, c]) => c > 0), usd));
+        lines.push(costPerCommitLine("Estimated per commit", costPerCommitPairs(data.series, notionalOf)));
+    }
     // Commits per backlog item is day-granular backlog data (features done + bugs fixed), so it
     // belongs only to the day report; zero items means the denominator is absent, not NaN.
     const items = t.featuresDone + t.bugsFixed;
     const perItem = items > 0 ? ` · ${(t.commits / items).toFixed(1)} commits per backlog item` : "";
     lines.push(`**Commits:** ${t.workCommits ?? 0} work / ${t.maintenanceCommits ?? 0} maintenance${perItem}`);
+    // Where the bugfix work was hardest to confirm: the window's fixed bugs tallied by their
+    // `Validation gap` tag, so the team can see where its own test infrastructure was weakest
+    // (recorded first, consumed now). Team-only (a tag has no role) and zero-means-absent: no
+    // line and no totals key for a role-scoped report or a window with no tagged fixed bug.
+    if (data.role === undefined && t.validationGapsByTag && Object.keys(t.validationGapsByTag).length > 0) {
+        lines.push(rankedRoleLine("Validation gaps", rankedRoleMap(t.validationGapsByTag), String));
+    }
     // The shared SPARSE_WINDOW_NOTE (one voice across the report's two windows and the other
     // windowed renders): covered is false only when events were aggregated from a log whose
     // oldest retained event lies inside the window, so the hedged sentence stays true whenever

package/dist/src/request-timeouts.js

@@ -1,6 +1,6 @@
 export function cappedRequestTimeouts(cfg, tickCapS, quietCapS) {
     return {
-        tickTimeoutSeconds: Math.min(cfg.tickTimeoutSeconds, tickCapS),
+        runTimeoutSeconds: Math.min(cfg.runTimeoutSeconds, tickCapS),
         quietTimeoutSeconds: cfg.quietTimeoutSeconds > 0 ? Math.min(cfg.quietTimeoutSeconds, quietCapS) : quietCapS,
     };
 }

package/dist/src/review/known-flakes.js

@@ -1,7 +1,8 @@
 /** The review gate's memory of its own flake warnings — split out of review-precheck.ts so the
  * "has this exact failure already passed on a re-run?" question lives on its own and can be
  * unit-tested over synthetic events. The gate re-runs a failed check once (BUGS.md 2026-09-23) and
- * logs `gate check failed then passed on retry — flaky: <headline>` when it passes; a later
+ * logs `gate check failed then passed on retry — flaky: <headline>` when it passes (the in-lock
+ * merge check's kept-pin retry logs the same with a `merge check` prefix); a later
  * repeat of that same headline is the flake firing again, not a verdict about whichever change
  * happened to hit it (BUGS.md 2026-10-06). The flake is matched by the shared failure-cluster
  * normalization so a duration, path, SHA, timestamp, or bare integer difference does not hide the
@@ -9,34 +10,53 @@
  * evidence of flakiness — it is exactly the attribution this memory exists to avoid making
  * twice. */
 import { readEventsSince } from "../events/event-window.js";
+import { increment } from "../collections.js";
 import { normalizeClusterKey } from "../failure/failure-cluster.js";
 /** How far back the gate looks for its own flake warnings. One local day: the example in
  * BUGS.md 2026-10-06 recorded a flake at 10:50 and rejected an unrelated change on the same
  * headline at 15:57, and a day is short enough that a retired flake stops excusing failures
- * while still covering a fleet's working span. */
-const KNOWN_FLAKE_WINDOW_MS = 24 * 60 * 60 * 1000;
+ * while still covering a team's working span. Exported so the doctor's `flaky checks` check
+ * and the gate share the one window and cannot drift. */
+export const KNOWN_FLAKE_WINDOW_MS = 24 * 60 * 60 * 1000;
 /** The exact prefix review-precheck.ts writes before a flake's failure headline. Exported so
  * the writer and reader cannot drift over the separator. */
 export const FLAKY_WARNING_PREFIX = "gate check failed then passed on retry — flaky: ";
-/** The normalized cluster keys of every flake warning in `events` at or after `now - windowMs`.
- * Pure over its inputs (no I/O, no clock) so the matching rules have their own unit tests.
- * Non-warning events, warnings whose message is not a string, and warnings older than the
- * window are ignored; a warning's headline is everything after the prefix. */
-export function flakeKeys(events, now, windowMs = KNOWN_FLAKE_WINDOW_MS) {
-    const cutoff = now - windowMs;
-    const keys = new Set();
+/** The prefix merge-check-failures.ts writes when an in-lock merge check that failed passes on
+ * its kept-pin retry — the merge-side twin of FLAKY_WARNING_PREFIX, read by the same consumers. */
+export const MERGE_FLAKY_WARNING_PREFIX = "merge check failed then passed on retry — flaky: ";
+/** The normalized cluster keys of every flake warning in `events` — the shared extraction
+ * both the gate's flakeKeys and the doctor's `flaky checks` check fold from the log, so the
+ * prefix slice-offset and original cluster normalization live once and cannot drift. Non-
+ * warning events and warnings whose message is not a string are ignored; `cutoffMs`, when
+ * given, also drops events timestamped strictly before it. Pure over its inputs (no I/O, no
+ * clock) so the matching rules have their own unit tests. */
+function flakeWarningKeys(events, cutoffMs) {
+    const keys = [];
     for (const e of events) {
         if (e.type !== "warning" || typeof e.message !== "string")
             continue;
-        if (typeof e.ts === "number" && e.ts < cutoff)
+        if (cutoffMs !== undefined && typeof e.ts === "number" && e.ts < cutoffMs)
             continue;
-        const at = e.message.indexOf(FLAKY_WARNING_PREFIX);
-        if (at < 0)
+        const message = e.message;
+        const prefix = [FLAKY_WARNING_PREFIX, MERGE_FLAKY_WARNING_PREFIX].find((p) => message.includes(p));
+        if (prefix === undefined)
             continue;
-        keys.add(normalizeClusterKey(e.message.slice(at + FLAKY_WARNING_PREFIX.length)));
+        keys.push(normalizeClusterKey(message.slice(message.indexOf(prefix) + prefix.length)));
     }
     return keys;
 }
+/** Each normalized flake headline in `events` with how often it was warned, most frequent first;
+ * ties keep first-seen order. No cutoff: callers pass an already-windowed read. Pure. */
+export function flakeCounts(events) {
+    const counts = new Map();
+    for (const key of flakeWarningKeys(events))
+        increment(counts, key);
+    return [...counts.entries()].sort((a, b) => b[1] - a[1]);
+}
+/** A Set of the flakeWarningKeys at or after `now - windowMs` of the gate's own window. */
+export function flakeKeys(events, now, windowMs = KNOWN_FLAKE_WINDOW_MS) {
+    return new Set(flakeWarningKeys(events, now - windowMs));
+}
 /** Whether `headline` matches a flake warning the gate logged within the last
  * KNOWN_FLAKE_WINDOW_MS, read from the live log and its one archived generation. */
 export function isKnownFlake(root, headline) {

package/dist/src/review/protected-edits.js

@@ -0,0 +1,33 @@
+// vocabulary: plain
+import path from "node:path";
+import { promptBlockOf } from "../brief/brief.js";
+import { readTextOrNull } from "../files/files.js";
+import { changeBaseRev, fileContentAt } from "../git/git.js";
+import { briefCandidates } from "../paths.js";
+import { baseRoleOf } from "../roles/loop-ids.js";
+/** The brief files that may carry the initial prompt block: the basenames of `briefCandidates`. */
+const BRIEF_FILES = briefCandidates("").map((p) => path.basename(p));
+/** The roles that may edit PRINCIPLES.md. */
+const PRINCIPLES_ROLES = new Set(["director", "steward"]);
+/** The deterministic gate/stage finding for a change that edits what the loop prompts forbid
+ * editing: the initial prompt block of a brief file (changed, removed, or the file deleted —
+ * a block that only moves passes), or PRINCIPLES.md from a role other than director or
+ * steward. undefined when neither happened. Reads the worktree and the change's merge-base
+ * like backlogStructureReason; a missing file reads as empty and never throws. */
+export async function protectedEditReason(wt, mainBranch, files, role) {
+    const briefs = BRIEF_FILES.filter((f) => files.includes(f));
+    if (briefs.length > 0) {
+        const baseRev = await changeBaseRev(wt, mainBranch);
+        for (const file of briefs) {
+            const base = promptBlockOf(await fileContentAt(wt, baseRev, file));
+            if (base === null)
+                continue;
+            const head = promptBlockOf(readTextOrNull(path.join(wt, file)) ?? "");
+            if (head !== base)
+                return `${file} changes the brief between the tumwater:prompt markers — only you edit it (tumwater brief); restore the block`;
+        }
+    }
+    if (files.includes("PRINCIPLES.md") && !PRINCIPLES_ROLES.has(baseRoleOf(role)))
+        return `PRINCIPLES.md is edited by the ${role} role — only the director and steward roles may edit it; record an objection in PLANS.md instead and revert the edit`;
+    return undefined;
+}

package/dist/src/review/review-followup.js

@@ -1,6 +1,6 @@
 import { agentSessionResumable } from "../agent/agent-backend.js";
-import { reviewRunConfig } from "../config/config-views.js";
-import { warnEventBestEffort } from "../events/events.js";
+import { reviewRunConfig, resolvedAgentConfig } from "../config/config-views.js";
+import { logEventBestEffort, warnEventBestEffort } from "../events/events.js";
 import { nativeLogPath, piLogPath } from "../paths.js";
 import { buildNoRerunPrompt, buildVerdictRequestPrompt } from "../prompt/gate-prompts.js";
 import { cappedRequestTimeouts } from "../request-timeouts.js";
@@ -17,8 +17,9 @@ async function runFollowupTurn(ctx, opts) {
     const cfg = reviewRunConfig(ctx.config);
     // The verdict/re-run follow-up continues the review session the gate just wrote. The
     // backend's own resumable rule keeps a newer line of another kind from being the session a
-    // pi continue would actually reach; claude resumes its recorded id.
-    if (!agentSessionResumable(dir, { kind: "gate", agent: cfg.agent ?? "pi" })) {
+    // pi continue would actually reach; claude resumes its recorded id (looked up under the
+    // team's config dir, so a team that set one continues under it).
+    if (!agentSessionResumable(dir, { kind: "gate", agent: cfg.agent ?? "pi" }, resolvedAgentConfig(ctx.config, "claude").configDir)) {
         return null;
     }
     return ctx.runGatePi({
@@ -39,6 +40,17 @@ async function runFollowupTurn(ctx, opts) {
         label: opts.label,
         signal: ctx.signal,
         onToolCallStalled: (message) => warnEventBestEffort(ctx.root, ctx.role, message),
+        // A gate run that read an image its model cannot see is logged, not killed (plans/
+        // image-input.md "Detecting a blind read") — same shape as the main review run in
+        // review.ts.
+        onBlindRead: (path, action) => logEventBestEffort(ctx.root, {
+            source: ctx.role,
+            type: "image_blind",
+            run: ctx.tick,
+            path,
+            model: cfg.model,
+            action,
+        }),
         ...(opts.onToolCallStart ? { onToolCallStart: opts.onToolCallStart } : {}),
     });
 }