tumwater 0.2.0 → 0.4.0

package/dist/src/roles/role-labels.js

@@ -1,10 +1,12 @@
-// vocabulary: plain
 /** How a role's id shows up in words: an instance id as `feature #2`. Pure, no I/O, so core
  * modules and the UI may both import it. */
-import { baseRoleOf, instanceIndex } from "./loop-ids.js";
-/** An instance id as `feature #2`; any other id (a bare role, `director`, a custom role,
- * `feature-1`) unchanged. */
+import { baseRoleOf, instanceIndex } from "./runner-ids.js";
+/** The shared display labels that differ from a role's id (the shared table every surface that
+ * shows a role label reads through roleLabel, and the dashboard client's hand-kept copy). ci
+ * renders as "CI"; every other id — a bare role, a custom role, an instance — renders as its id. */
+export const ROLE_LABELS = { ci: "CI" };
 export function roleLabel(runnerId) {
     const base = baseRoleOf(runnerId);
-    return base === runnerId ? runnerId : `${base} #${instanceIndex(runnerId)}`;
+    const label = Object.prototype.hasOwnProperty.call(ROLE_LABELS, base) ? ROLE_LABELS[base] : base;
+    return base === runnerId ? label : `${label} #${instanceIndex(runnerId)}`;
 }

package/dist/src/roles/role-render.js

@@ -1,12 +1,13 @@
-// vocabulary: plain
+import { joinParts } from "../text/text.js";
 import { agree, shortSpanPhrase } from "../text/phrases.js";
 import { compactTokens, usd } from "../text/format.js";
-import { clockHm, formatTimestamp, humanSeconds, nextRunPhrase, secondsSince, secondsUntil } from "../text/datetime.js";
+import { clockHm, formatAge, formatTimestamp, humanAgo, nextRunPhrase, secondsUntil } from "../text/datetime.js";
 import { claudeWindowLabel } from "../agent/claude/claude-account.js";
+import { windowLabel } from "../agent/subscription-account.js";
+import { backendDefaultLabel, backendDisplayName } from "../agent/backend-traits.js";
 import { yieldMultiplierSuffix } from "../scheduling/backoff.js";
 import { quietWindowEnd } from "../scheduling/quiet-hours.js";
-import { isAgentId } from "../config/model-selector.js";
-/** The terminal's view of one loop — what `tumwater role <id>` prints, rendered as Markdown
+/** The terminal's view of one role — what `tumwater role <id>` prints, rendered as Markdown
  * from the payload role-view.ts's rolePayload collects (the same document `--json` prints).
  * Like backlog-render.ts, the renderer owns no collection of its own: the CLI's --json and
  * human branches share one collection through sayJsonOrRender's thunk, so the two surfaces
@@ -15,7 +16,7 @@ import { isAgentId } from "../config/model-selector.js";
  * prose-and-shell markdown the operator may copy verbatim — with the fence grown past any
  * backtick run the text itself contains, so a prompt that quotes a fence still round-trips.
  * Unset things render as explicit `_(none)_` lines rather than disappearing, so an
- * un-overridden loop reads as fully defaulted, not as a truncated report. */
+ * un-overridden role reads as fully defaulted, not as a truncated report. */
 /** A code fence one longer than any backtick run in the fenced text, so the block always
  * closes where the text itself would have ended it. */
 function fenceFor(text) {
@@ -31,22 +32,50 @@ function fencedOrNone(label, text, noneNote = "none") {
     const fence = fenceFor(text);
     return [`## ${label}`, "", fence, text.replace(/\n+$/, ""), fence, ""];
 }
-/** The Notebook and Next tick prompt blocks and the "more waits" disclosure, as Markdown
- * lines — the read-only inspection the TUI's notebook view and `tumwater role <id>` share,
- * so the terminal and the CLI show one loop's notebook and assembled prompt identically.
+/** The Notes and Next run prompt blocks and the "more waits" disclosure, as Markdown
+ * lines — the read-only inspection the TUI's notes view and `tumwater role <id>` share,
+ * so the terminal and the CLI show one role's notes and assembled prompt identically.
  * `renderRoleMarkdown` splices these at the same position, so the extracted function and the
  * full document cannot drift. */
-export function inspectMarkdownLines(p) {
+export function inspectMarkdownLines(p, now = Date.now()) {
     const running = chainStepLine(p);
-    return [...(running ? [running, ""] : []), ...inspectBodyLines(p)];
+    return [...(running ? [running, ""] : []), ...inspectBodyLines(p, now)];
 }
-/** The notebook, prompt and disclosure blocks alone — what renderRoleMarkdown splices after
+/** The notes, prompt and disclosure blocks alone — what renderRoleMarkdown splices after
  * its own Team lines, which already carry the fallback-step bullet. */
-function inspectBodyLines(p) {
+function inspectBodyLines(p, now) {
     const lines = [];
     lines.push(...fencedOrNone("Notes", p.notes, "none yet — the role's own earlier runs write them, and the director has none"));
+    // The operator twin of the `<role-notes>` prompt block's save age: name when the note was
+    // last saved, so a note from five minutes ago and one from five days ago read differently.
+    // Present only when there is a note (noteSavedAt is null with none), so a note-less role's
+    // render is byte-identical to today's.
+    if (p.noteSavedAt !== null) {
+        lines.push(`_Last saved ${formatTimestamp(p.noteSavedAt)} (${humanAgo(p.noteSavedAt, now)}) — a snapshot of the past; verify its claims against the code._`);
+    }
+    // The qa observer's flow-coverage ledger (role-view.ts's flowCoverage, qa-coverage.ts's
+    // coverageRows): each flow's last exercise and result, in the same order and wording family
+    // as the prompt block (never-exercised first, then stalest-first), without the prompt's
+    // intro sentence — the operator twin of the ledger that is otherwise the observer's only
+    // memory. Present only for qa, so every other role's render stays byte-identical.
+    if (p.flowCoverage) {
+        lines.push("## Flow coverage", "");
+        for (const row of p.flowCoverage) {
+            if (row.lastRunAt === null) {
+                lines.push(`- ${row.flow}: never exercised`);
+            }
+            else {
+                const age = formatAge(now - row.lastRunAt);
+                const status = row.result === "bug"
+                    ? `bug filed (BUGS.md: "${row.summary ?? "see BUGS.md"}")`
+                    : "passed";
+                lines.push(`- ${row.flow}: ${age} ago, ${status}`);
+            }
+        }
+        lines.push("");
+    }
     lines.push(...fencedOrNone("Next run's prompt", p.nextPrompt, "nothing to do this run"));
-    // tick-prompt.ts dequeues exactly one queued prompt per tick, so with more than one
+    // run-prompt.ts dequeues exactly one queued prompt per run, so with more than one
     // waiting the block above shows only the oldest — say so, so the count line and the
     // block never read as a contradiction (the 2026-10-04 BUGS.md entry under ## Fixed).
     if (p.inboxCount > 1 && p.nextPrompt !== null && p.nextPrompt.trim() !== "") {
@@ -59,12 +88,13 @@ function inspectBodyLines(p) {
  * `model` alone when only the model is (the join simply drops unset halves) — shared by the
  * main line and the budget-fallback line, so the two render the same wiring the same way. */
 function modelPair(provider, model) {
-    return [provider, model].filter(Boolean).join("/");
+    return joinParts([provider, model], "/");
 }
 /** The backend's own-default label when no model resolves: `<agent> default` — pi's
- * historical `pi default` for the pi backend, `claude default` for claude (part 4f/7). */
-function agentDefault(p) {
-    return `${p.backend !== "pi" ? p.backend : "pi"} default`;
+ * historical `pi default` for the pi backend, `claude default` for claude (part 4f/7),
+ * shared with the status rows through `backendDefaultLabel`. */
+function backendDefault(p) {
+    return backendDefaultLabel(p.backend);
 }
 /** The provider/model wiring as one readable token: `provider/model` when both resolve,
  * `model` alone when only the model is named, and the backend-default note when neither is.
@@ -75,11 +105,11 @@ function modelLine(p) {
     // level (piDefault is formatted with the effective thinking winning), so the separate
     // ` (thinking: …)` suffix is dropped for this case only.
     if (p.piDefault)
-        return `${agentDefault(p)} (${p.piDefault})`;
+        return `${backendDefault(p)} (${p.piDefault})`;
     const pair = modelPair(p.provider, p.model);
     const thinking = p.thinking ? ` (thinking: ${p.thinking})` : "";
     if (!pair)
-        return `${agentDefault(p)}${thinking}`;
+        return `${backendDefault(p)}${thinking}`;
     const agent = p.backend !== "pi" ? `${p.backend}/` : "";
     return `${agent}${pair}${thinking}`;
 }
@@ -89,9 +119,8 @@ function modelLine(p) {
  * backend-default label. One home for the Model fallback and Budget fallback lines, so a
  * claude fallback reads `claude/claude-sonnet-5-5`, not a bare id (PLANS.md "Mixed claude +
  * pi fleets, part 3/4" gap 7). */
-function fallbackPairLabel(fb, agentDefault) {
-    const agentBackend = (fb.backend !== undefined && fb.backend !== "pi" ? fb.backend : undefined) ??
-        (fb.provider !== undefined && isAgentId(fb.provider) ? fb.provider : undefined);
+function fallbackPairLabel(fb, backendDefault) {
+    const agentBackend = fb.backend !== undefined && fb.backend !== "pi" ? fb.backend : undefined;
     if (fb.model !== undefined) {
         if (agentBackend !== undefined)
             return `${agentBackend}/${fb.model}`;
@@ -99,12 +128,27 @@ function fallbackPairLabel(fb, agentDefault) {
     }
     if (fb.provider !== undefined)
         return fb.provider;
-    return agentDefault;
+    return backendDefault;
 }
-/** Why a tier moved down its fallback chain, as the role view words it. */
-function chainReasonPhrase(reason, windowType) {
+/** The backend-and-window label the role view shows for a non-claude backend's window:
+ * `backendDisplayName(billingBackend)` beside `windowLabel(windowType)` — "Codex 7d" for a
+ * codex subscription (plans/codex-backend.md part 3c/9), so a reader knows whose window it
+ * is. Claude keeps today's bare window type ("5h") so its role view stays byte-identical. */
+function billingWindowLabel(billingBackend, windowType) {
+    const type = windowType !== undefined ? windowLabel(windowType) : "";
+    const backend = billingBackend !== undefined && billingBackend !== "claude" ? backendDisplayName(billingBackend) : "";
+    return [backend, type].filter(Boolean).join(" ");
+}
+/** Why a tier moved down its fallback chain, as the role view words it. The window phrase
+ * names the backend in play ("Codex 7d window used up") when a non-claude backend moved the
+ * role; claude keeps today's wording byte-identical, and an unknown backend falls back to
+ * today's hardcoded "Claude". */
+function chainReasonPhrase(reason, billingBackend, windowType) {
     switch (reason) {
         case "window":
+            if (billingBackend !== undefined && billingBackend !== "claude") {
+                return `${billingWindowLabel(billingBackend, windowType)} window used up`;
+            }
             return `${windowType !== undefined ? claudeWindowLabel(windowType) : "Claude"} window used up`;
         case "reserve":
             return "window reserve reached";
@@ -125,10 +169,10 @@ function chainStepLine(p) {
     if (!c)
         return null;
     const resets = c.returnsAt !== undefined ? `, resets ${clockHm(c.returnsAt)}` : "";
-    return `- Running on fallback ${c.step} of ${c.of} (${chainReasonPhrase(c.reason, p.billingWindow)}${resets})`;
+    return `- Running on fallback ${c.step} of ${c.of} (${chainReasonPhrase(c.reason, p.billingBackend, p.billingWindow)}${resets})`;
 }
-/** One recent tick outcome as a Markdown bullet line — `<time> · <result> · <span> —
- * <summary>` — so `tumwater role <id>` and the TUI notebook view read a loop's discrete
+/** One recent run outcome as a Markdown bullet line — `<time> · <result> · <span> —
+ * <summary>` — so `tumwater role <id>` and the TUI notes view read a role's discrete
  * outcomes at a glance. `time` is the same local `YYYY-MM-DD HH:MM:SS` stamp the model-
  * fallback `since` prints (formatTimestamp); `span` is the same short-duration phrasing
  * shortSpanPhrase renders for holdPhrase and the event feed's countdowns; the summary is
@@ -142,29 +186,29 @@ function recentOutcomeLine(o) {
         line += ` — ${o.summary}`;
     return line;
 }
-/** One quiet-hours bullet: the window, whose it is, and whether it holds the loop now — with
+/** One quiet-hours bullet: the window, whose it is, and whether it holds the role now — with
  * the same `quiet until <end>` text the status table uses. */
 function quietHoursLine(w) {
     const whose = w.scope === "role" ? "own window" : "team window";
     const state = w.inWindow ? `holding now — quiet until ${quietWindowEnd(w.window)}` : "not holding now";
     return `- Quiet hours: ${w.window} (${whose}; ${state})`;
 }
-/** The loop's schedule as Markdown bullet lines — `Next tick`, `Last tick`, then one
+/** The role's schedule as Markdown bullet lines — `Next run`, `Last run`, then one
  * `Quiet hours` line per governing window (none when the payload carries no windows) — in the
  * same words and wording family as the team surface's `next run` cell (status-render.ts's
- * nextRunCell), so the role view and the status table cannot drift on when a loop acts next:
- * a never-scheduled loop (nextRunAt 0) reads `not scheduled yet`; a due loop reads `due now`;
+ * nextRunCell), so the role view and the status table cannot drift on when a role acts next:
+ * a never-scheduled role (nextRunAt 0) reads `not scheduled yet`; a due role reads `due now`;
  * a future one reads `in <Ns>` through humanSeconds, prefixed `backoff ` while backoffSeconds
  * > 0 (the wake row-action clears exactly that) — the shared nextRunPhrase, so the role view
  * and the status `next run` cell cannot drift on the backoff prefix or the humanSeconds
- * bucketing. `Last tick` reuses formatTimestamp and the same `humanSeconds … ago` phrasing the
- * status `last tick` cell ages with, or `never` for a loop that has not ticked. `now` is
+ * bucketing. `Last run` reuses formatTimestamp and the same `humanSeconds … ago` phrasing the
+ * status `last run` cell ages with, or `never` for a role that has not run. `now` is
  * injected (default Date.now()) so the renderer stays a pure function of the payload and the
  * test can pin a fixed clock. */
 function scheduleLine(p, now) {
     // The yield multiplier rides the line as `×N` exactly like nextRunCell/fmtNextRun: a quiet
-    // yield-scaled loop's effective gap is longer than nextRunAt's countdown shows (isEligible
-    // gates on the multiplier too), so the Schedule must not understate when the loop acts next.
+    // yield-scaled role's effective gap is longer than nextRunAt's countdown shows (isEligible
+    // gates on the multiplier too), so the Schedule must not understate when the role acts next.
     const suffix = yieldMultiplierSuffix(p.yieldMultiplier);
     let next;
     if (p.nextRunAt <= 0) {
@@ -175,11 +219,11 @@ function scheduleLine(p, now) {
         next = nextRunPhrase(remain, p.backoffSeconds > 0, "due now", true) + suffix;
     }
     const last = p.lastRunEndedAt !== undefined
-        ? `${formatTimestamp(p.lastRunEndedAt)} (${humanSeconds(secondsSince(p.lastRunEndedAt, now))} ago)`
+        ? `${formatTimestamp(p.lastRunEndedAt)} (${humanAgo(p.lastRunEndedAt, now)})`
         : "never";
     return [`- Next run: ${next}`, `- Last run: ${last}`, ...(p.quietHours ?? []).map(quietHoursLine)];
 }
-/** Render one loop's inspection payload as Markdown. `now` is injected (default Date.now())
+/** Render one role's inspection payload as Markdown. `now` is injected (default Date.now())
  * so the schedule lines stay a pure function of the payload — the test pins a fixed clock. */
 export function renderRoleMarkdown(p, now = Date.now()) {
     const lines = [`# tumwater role: ${p.id}`, ""];
@@ -194,15 +238,15 @@ export function renderRoleMarkdown(p, now = Date.now()) {
     // unresolvable pair, a model with no declared window).
     lines.push(`- Context window: ${p.contextWindow === null ? "unknown" : `${compactTokens(p.contextWindow)} tokens`}`);
     // Per-provider concurrency cap (plans/provider-concurrency.md §8): name the key whose cap
-    // bounds the role's concurrent ticks, plus the cap itself. Present only while
+    // bounds the role's concurrent runs, plus the cap itself. Present only while
     // `maxConcurrentPerProvider` maps this seam's key — a cap-less default team has no
     // resolvable key entry, so its role view renders no new line and stays byte-identical.
     if (p.providerKey !== undefined && p.providerCap !== undefined) {
         lines.push(`- Provider: ${p.providerKey} (cap ${p.providerCap})`);
     }
-    // Image input (plans/image-input.md "Surfaces", part 5/5): whether this loop's own model
-    // reads images, and — when it cannot — where a tick that reads an image reroutes. Not just
-    // `yes`/`no`: a text-only loop that falls back names the target, so `tumwater role <id>`
+    // Image input (plans/image-input.md "Surfaces", part 5/5): whether this role's own model
+    // reads images, and — when it cannot — where a run that reads an image reroutes. Not just
+    // `yes`/`no`: a text-only role that falls back names the target, so `tumwater role <id>`
     // explains the team alert without running doctor. Unknown (null) renders `unknown` rather
     // than guessing.
     const images = p.imageInput === true
@@ -213,14 +257,20 @@ export function renderRoleMarkdown(p, now = Date.now()) {
                 : "no"
             : "unknown";
     lines.push(`- Images: ${images}`);
+    // Whether the review gate reviews this role's commits after they merge (role-view.ts's
+    // reviewedAfterMerge). Present only while review.enabled is on and review.afterMerge lists
+    // the role's base id — a pre-merge-reviewed role or a gate-off config omits the line.
+    if (p.reviewedAfterMerge) {
+        lines.push(`- Review: after merge (a rejected change stays on main with the reviewer's recorded reasons)`);
+    }
     // Model failure fallback, part 2/2: name the off-model pair, when the episode began, and
     // the provider-class failure that tripped it, so `tumwater role <id>` explains the state.
     if (p.modelFallback) {
-        const pair = fallbackPairLabel(p.modelFallback, agentDefault(p));
+        const pair = fallbackPairLabel(p.modelFallback, backendDefault(p));
         lines.push(`- Model fallback: ${pair} — on fallback since ${formatTimestamp(p.modelFallback.since)} (primary failing: ${p.modelFallback.reason})`);
     }
     if (p.fallback) {
-        const pair = fallbackPairLabel(p.fallback, agentDefault(p));
+        const pair = fallbackPairLabel(p.fallback, backendDefault(p));
         lines.push(`- Over-cap model: ${pair} (${p.fallbackFree ? "free" : "priced"})`);
     }
     const running = chainStepLine(p);
@@ -229,17 +279,19 @@ export function renderRoleMarkdown(p, now = Date.now()) {
     // The claude seam's billing (plans/agent-backends.md §7/§8, PLANS.md part 6d/7): absent on
     // a pi seam, so its role view is byte-identical to before.
     if (p.billing) {
-        const window = p.billing === "subscription" && p.billingWindow ? ` (${claudeWindowLabel(p.billingWindow)} window)` : "";
+        const window = p.billing === "subscription" && p.billingWindow
+            ? ` (${billingWindowLabel(p.billingBackend, p.billingWindow)} window)`
+            : "";
         lines.push(`- Billing: ${p.billing === "api" ? "API" : p.billing}${window}`);
     }
     lines.push(`- Min run interval: ${p.minRunIntervalSeconds}s`);
     if (p.instances !== undefined)
         lines.push(`- Instances: ${p.instances}`);
     lines.push(`- Inbox: ${p.inboxCount}`);
-    // The loop's own spend over its retained event window (role-view.ts's usage, summed from the
-    // same run_end events recentOutcomes reads): how much the loop burned on tokens and cost,
+    // The role's own spend over its retained event window (role-view.ts's usage, summed from the
+    // same run_end events recentOutcomes reads): how much the role burned on tokens and cost,
     // with a notional suffix only when a claude-subscription seam burned non-zero notional spend
-    // (plans/agent-backends.md part 6a). Absent for a never-costly loop, so old `tumwater role`
+    // (plans/agent-backends.md part 6a). Absent for a never-costly role, so old `tumwater role`
     // goldens are byte-identical.
     if (p.usage) {
         let spend = `- Spend: ${usd(p.usage.costUsd)} · ${compactTokens(p.usage.tokens)} tokens`;
@@ -248,7 +300,7 @@ export function renderRoleMarkdown(p, now = Date.now()) {
         lines.push(spend);
     }
     // The per-role daily cap (role-view.ts's dailyCap): today's spend against the cap and whether
-    // it holds the loop now. Absent without a cap, so old goldens are unchanged.
+    // it holds the role now. Absent without a cap, so old goldens are unchanged.
     if (p.dailyCap) {
         const dc = p.dailyCap;
         let cap = `- Daily cap: ${usd(dc.spentUsd)} of ${usd(dc.capUsd)} spent today (${dc.over ? "holding now — no new runs until local midnight" : "not holding"})`;
@@ -256,14 +308,14 @@ export function renderRoleMarkdown(p, now = Date.now()) {
             cap += ` · shared by ${dc.roleIds.join(", ")}`;
         lines.push(cap);
     }
-    // The loop's schedule (role-view.ts's nextRunAt/backoffSeconds/lastRunEndedAt, read from
-    // the same persisted state): when it may tick again, and when it last did — the one
-    // place the team's `next run`/`last tick` vocabulary was absent. Rendered from the
+    // The role's schedule (role-view.ts's nextRunAt/backoffSeconds/lastRunEndedAt, read from
+    // the same persisted state): when it may run again, and when it last did — the one
+    // place the team's `next run`/`last run` vocabulary was absent. Rendered from the
     // injected `now`, so the lines stay a pure function of the payload.
     lines.push(...scheduleLine(p, now));
-    // The loop's recent tick outcomes (role-view.ts's recentOutcomes, read from the event log):
-    // one line per outcome so `tumwater role <id>` shows what the loop has been DOING, not just
-    // what it is. Absent (never ticked) renders nothing new, so old goldens are byte-identical.
+    // The role's recent run outcomes (role-view.ts's recentOutcomes, read from the event log):
+    // one line per outcome so `tumwater role <id>` shows what the role has been DOING, not just
+    // what it is. Absent (never run) renders nothing new, so old goldens are byte-identical.
     if (p.recentOutcomes && p.recentOutcomes.length > 0) {
         lines.push("", "## Recent runs", "");
         for (const o of p.recentOutcomes)
@@ -272,6 +324,6 @@ export function renderRoleMarkdown(p, now = Date.now()) {
     lines.push("");
     lines.push(...fencedOrNone("Instructions override", p.instructions));
     lines.push(...fencedOrNone("Find text", p.find, "none — the director is driven by its inbox, not by instructions"));
-    lines.push(...inspectBodyLines(p));
+    lines.push(...inspectBodyLines(p, now));
     return lines.join("\n").trimEnd();
 }