tumwater 0.1.2 → 0.2.0

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

@@ -1,7 +1,10 @@
+// vocabulary: plain
 /** Shared instruction fragments role prompts and prompt assembly embed verbatim. Pure
- * data: this module imports nothing, so prompt assembly can depend on it without a cycle.
+ * data: this module imports only the dependency-free legacy-role-ids, so prompt assembly
+ * can depend on it without a cycle.
  * Split from roles.ts, whose catalog (now role-catalog.ts) find texts embed these fragments
  * while prompt.ts embeds them too — the wording is one concern, the catalog another. */
+import { roleCommitGrep } from "./legacy-role-ids.js";
 /** Shared guidance for any loop about to record a plan or bug: split independent parts
  * into their own entries. Defined once so the director and role prompts cannot drift.
  * Lives here (not in prompt.ts) because two role `find` texts embed it — keeping this
@@ -9,7 +12,7 @@
  * and the catalog → here. */
 export const DECOMPOSITION_GUIDANCE = `Before recording a plan or bug, check whether it decomposes
 into independent subparts (separate features, or separate bugs). If it does, record each part as
-its own PLANS.md/BUGS.md entry that cross-references its siblings, so loops can pick them up
+its own PLANS.md/BUGS.md entry that cross-references its siblings, so roles can pick them up
 independently; if the parts are not truly independent, keep a single entry.`;
 /** Shared instruction for closing a backlog entry (the feature loop moving a plan to Done,
  * the bugfix loop moving a bug to Fixed). Written against the observed failure (PLANS.md
@@ -17,9 +20,11 @@ independently; if the parts are not truly independent, keep a single entry.`;
  * commits left PLANS.md with two `## Done` headings — so the wording names the file's EXISTING
  * resolved heading, forbids touching `## ` structure, and gives the verifiable invariant
  * (the same headings before and after). Lettered sub-steps, because the callers embed it as one
- * numbered step of their task. Takes the file and section names so the feature and bugfix texts
- * cannot drift apart; lives here with the other shared fragments. */
-export function backlogMoveGuidance(file, openSection, resolvedSection) {
+ * numbered step of their task. The pasted entry does not stay there: tumwater moves it to the top
+ * of `archive` when the change commits (plans/backlog-archive.md), which the last line says so no
+ * run opens the archive to do it by hand. Takes the file, section and archive names so the feature
+ * and bugfix texts cannot drift apart; lives here with the other shared fragments. */
+export function backlogMoveGuidance(file, openSection, resolvedSection, archive) {
     return `move the entry, step by step:
       a. cut the entry out of \`${openSection}\`;
       b. add the closing date to its \`### \` heading;
@@ -27,8 +32,12 @@ export function backlogMoveGuidance(file, openSection, resolvedSection) {
       d. if it was the last entry under \`${openSection}\`, leave a \`_None yet._\` placeholder
          there.
       Never add, remove, or rename a \`## \` heading: \`grep -n '^## ' ${file}\` must list the
-      same headings before and after the edit.`;
+      same headings before and after the edit. When your change commits, tumwater moves the
+      pasted entry to the top of ${archive}; do not open or edit ${archive} yourself.`;
 }
+/** The heading clause requiredParts parses, spelled as the parser reads it. Interpolated because
+ * a comment inside the template would become prompt text. */
+const REQUIRES_PART_FORM = "requires part N/M landed"; // vocabulary-ok: requiredParts parses this heading syntax
 /** Shared sizing rule for anyone writing a plan (the plan role and the director): the feature
  * loop is one mid-sized local model working alone in one run, and the review gate rejects a
  * change that lands less than its entry promises — so a plan must fit that run. Oversized plans
@@ -38,13 +47,17 @@ export function backlogMoveGuidance(file, openSection, resolvedSection) {
  * and its own fast-forward deleted the config. */
 export const PLAN_SIZING = `Size every plan to ONE implementation run by a mid-sized model working
 alone: a handful of files, at most a few hundred lines of change including tests, and no design
-question left open for the implementer. Anything larger is split into independently landable
-sub-plans that cross-reference each other, each with its own acceptance criteria. Anchor plans on
+question left open for the implementer. Anything larger is split into independently mergeable
+sub-plans that cross-reference each other, each with its own acceptance criteria. A sub-plan that
+depends on a sibling spells that dependency as ${REQUIRES_PART_FORM}, in quotes, in its
+heading's trailing parenthetical; it is the only form the claim allocator reads, so a dependency
+worded any other way (such as blocked by part 1/2, after part 1/2, or follows part 1/2) does not
+hold the part until its prerequisite leaves ## Planned. Anchor plans on
 file paths and symbol names — functions, types, constants, test names — never on line numbers or
-ranges, because line anchors go stale with every landing. When the project is the harness running
-the fleet, every commit lands under the build that predates it, so a
-change to how landings behave and any step that depends on it are separate sub-plans, the second
-landing only once the first is the running build.`;
+ranges, because line anchors go stale with every merge. When tumwater is building itself,
+every commit merges under the build that predates it, so a
+change to how merges behave and any step that depends on it are separate sub-plans, the second
+merge only once the first is the running build.`;
 /** The closed vocabulary for the validation-gap trace (plans/repair-traces.md): what made a bug
  * hard to *confirm*, which is the only evidence of where this project's test infrastructure is
  * weakest. Closed on purpose so the traces aggregate, and `none` is a written value rather than an
@@ -71,17 +84,28 @@ made the bug hard to CONFIRM — not to fix — as one line, \`**Validation gap:
    - real-run-needed — no offline path covered it; a real bounded run was required
    - no-observability — the failure left no trace
    - slow-check — the only verification was slow enough to shape the fix
-   - unclear-invariant — had to reconstruct what the code was supposed to guarantee first
+   - unclear-invariant — had to reconstruct what the code was supposed to guarantee first; record the reconstructed invariant in docs/invariants.md in the same commit so a later bug in that area does not reconstruct it again
 When nothing fits exactly, use the closest tag and say so in the sentence — never invent a
 tag. \`none\` is written, never omitted, so a tally has an honest denominator.`;
-/** The one query that tallies validation-gap tags across BUGS.md, counting both the verbatim
- * \`**Validation gap:**\` line bugfix writes and the steward's compressed \`gap: <tag>\` suffix.
+/** The one query that tallies validation-gap tags across BUGS.md and BUGS-FIXED.md (where fixed
+ * bugs are archived), counting both the verbatim \`**Validation gap:**\` line bugfix writes and
+ * the \`gap: <tag>\` suffix of the one-line records the steward used to compress older entries to.
  * Split from VALIDATION_GAP_GUIDANCE so only the steward — the one role that aggregates the
  * tags — carries it; a bugfix run writes one line and never needs the tally. */
-export const VALIDATION_GAP_TALLY = `One query counts both the verbatim line and the compressed
-\`gap: <tag>\` suffix: \`grep -oE 'gap:[*]{0,2} ?[a-z-]+' BUGS.md | sed -E 's/^gap:[*]{0,2} ?//' | sort | uniq -c\`.`;
+export const VALIDATION_GAP_TALLY = `One query counts both the verbatim line and the older compressed
+\`gap: <tag>\` suffix across BUGS.md and its archive: \`grep -sohE 'gap:[*]{0,2} ?[a-z-]+' BUGS.md BUGS-FIXED.md | sed -E 's/^gap:[*]{0,2} ?//' | sort | uniq -c\`.`;
+/** The one query a *consumer* of the validation-gap traces — a role like coverage that picks its
+ * next target from the record of what made past bugs hard to confirm — runs to pull the
+ * recent, still-full-body entries. Split from VALIDATION_GAP_TALLY (the steward's aggregate
+ * count) because this one lists the *entries*, newest-first: \`head\` not \`tail\`, since
+ * \`## Fixed\` is newest-first, so the recent full-body entries sit at the top, for a role to
+ * read each hit's free text. It reads BUGS.md's own section first, then BUGS-FIXED.md, where
+ * fixed bugs are archived (plans/backlog-archive.md); \`-s\` keeps a missing archive quiet, and
+ * each hit names its file and line. Built from the closed vocabulary (minus \`none\`, which
+ * names nothing to build) so it cannot drift. */
+export const VALIDATION_GAP_QUERY = `grep -snE '\\*\\*Validation gap:\\*\\* (${VALIDATION_GAP_TAGS.filter((t) => t !== "none").join("|")})' BUGS.md BUGS-FIXED.md | head -20`;
 /** The literal prefix every Needs-review note starts with. Exported so a reader that only has
- * to recognize one (the backlog index's ` [needs review]` mark) can match on it instead of
+ * to recognize one (the backlog index's ` [blocked: needs review]` mark) can match on it instead of
  * parsing the date or the wording out of the full template — the same split as
  * NEEDS_REPLAN_PREFIX. */
 export const NEEDS_REVIEW_PREFIX = `**Needs review `;
@@ -91,22 +115,31 @@ export const NEEDS_REVIEW_PREFIX = `**Needs review `;
  * clause cannot drift. */
 export const NEEDS_REVIEW_NOTE = `${NEEDS_REVIEW_PREFIX}<YYYY-MM-DD> by feature: too large for one run**`;
 /** The literal prefix every Needs-replan note starts with. Exported so a reader that only has to
- * recognize one (the backlog index's ` [needs replan]` mark) can match on it instead of parsing
- * the date or the round count out of the full template. */
+ * recognize one (the backlog index's ` [blocked: needs replan]` mark) can match on it instead of
+ * parsing the date or the round count out of the full template. */
 export const NEEDS_REPLAN_PREFIX = `**Needs replan `;
 /** The markdown note the feature loop appends under a plan whose change was rejected after its
  * final revision round, carrying the reviewer's objections back to the strong-tier plan loop
  * instead of letting feature re-author the same plan. Same convention as NEEDS_REVIEW_NOTE: a
  * note a later fresh tick reads, with no code parsing it. */
 export const NEEDS_REPLAN_NOTE = `${NEEDS_REPLAN_PREFIX}<YYYY-MM-DD> by feature: rejected after <N> review rounds**`;
-/** How a role with no backlog (organize, clean, dry, perf, security, robustness, improve) finds its
- * one task, as numbered steps. Written against the observed failure: with nothing to point at, a
- * local model reads the codebase file by file — thirty whole-file reads, ~300 KB of tool output
- * — and then either fills its window or declares nothing-to-do (improve: 41 of 44 ticks in the
- * first week of September landed nothing). Cheap signals shortlist candidates; a decision deadline
- * ends the search; the harness's own commit subjects (`tumwater(<role>): …`) are the only
- * cross-tick memory of what the role did lately, so the text names them. Takes the role id so the
- * git command is literal, not a placeholder the model has to fill in. */
+/** The literal prefix every Waiting-for-the-next-failure note starts with. Exported so a reader
+ * that only has to recognize one (the backlog index's ` [blocked: waiting for the next failure]`
+ * mark) can match on it instead of parsing the date or the wording out of the full template. */
+export const WAITING_FOR_FAILURE_PREFIX = `**Waiting for the next failure `;
+/** The markdown note the bugfix loop writes under an open bug it cannot reproduce once it has made
+ * the failure explain itself, so bugfix stops spending runs without new evidence. Same convention
+ * as NEEDS_REPLAN_NOTE: a note a later fresh tick reads. It lifts when whoever records the next
+ * occurrence deletes the line, or by `tumwater bug --release <n>`. */
+export const WAITING_FOR_FAILURE_NOTE = `${WAITING_FOR_FAILURE_PREFIX}<YYYY-MM-DD> by bugfix: <what the next failure's message will show>**`;
+/** How a role with no backlog (organize, clean, dedupe, perf, security, robustness, improve) finds
+ * its one task, as numbered steps. Written against the observed failure: with nothing to point
+ * at, a local model reads the codebase file by file — thirty whole-file reads, ~300 KB of tool
+ * output — and then either fills its window or declares nothing-to-do (improve: 41 of 44 ticks in
+ * the first week of September landed nothing). Cheap signals shortlist candidates; a decision
+ * deadline ends the search; the harness's own commit subjects (`tumwater(<role>): …`) are the
+ * only cross-tick memory of what the role did lately, so the text names them. Takes the role id
+ * so the git command is literal, not a placeholder the model has to fill in. */
 export function searchGuidance(roleId) {
     return `How to search — do not read the codebase file by file: a whole-tree survey costs most of
 the run and rarely finds anything a targeted look would not.
@@ -114,10 +147,10 @@ the run and rarely finds anything a targeted look would not.
       the expensive unit: \`git log --stat -15\` (recent churn is where problems accumulate),
       \`wc -l\` over the source files (size outliers), and \`grep -rn\` for the specific pattern
       you are after.
-   2. Skip what your own role handled lately: \`git log --oneline -15 --grep="tumwater(${roleId})"\`
-      lists it — the harness's commit subjects say what each loop did.
+   2. Skip what your own role handled lately: \`git log --oneline -15 ${roleCommitGrep(roleId)}\`
+      lists it — tumwater's commit subjects say what each role did.
    3. Vary the slice you look at across runs (a different directory, module, or recency window)
-      so successive ticks do not all converge on the same files.
+      so successive runs do not all converge on the same files.
    4. Shortlist at most five candidate files and inspect them with \`grep -n\` and ranged reads;
       open a file whole only when it is under ~300 lines.
    5. Decide within ~15 tool calls, in a handful of turns: if no candidate clearly clears the bar

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

@@ -0,0 +1,10 @@
+// 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. */
+export function roleLabel(runnerId) {
+    const base = baseRoleOf(runnerId);
+    return base === runnerId ? runnerId : `${base} #${instanceIndex(runnerId)}`;
+}

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

@@ -1,6 +1,11 @@
-import { agree } from "../text/phrases.js";
-import { formatTimestamp } from "../text/datetime.js";
+// vocabulary: plain
+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 { claudeWindowLabel } from "../agent/claude/claude-account.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
  * 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
@@ -32,15 +37,21 @@ function fencedOrNone(label, text, noneNote = "none") {
  * `renderRoleMarkdown` splices these at the same position, so the extracted function and the
  * full document cannot drift. */
 export function inspectMarkdownLines(p) {
+    const running = chainStepLine(p);
+    return [...(running ? [running, ""] : []), ...inspectBodyLines(p)];
+}
+/** The notebook, prompt and disclosure blocks alone — what renderRoleMarkdown splices after
+ * its own Team lines, which already carry the fallback-step bullet. */
+function inspectBodyLines(p) {
     const lines = [];
-    lines.push(...fencedOrNone("Notebook", p.note, "none yet — the role's own earlier ticks write it, and the director has none"));
-    lines.push(...fencedOrNone("Next tick prompt", p.nextPrompt, "nothing to run this tick"));
+    lines.push(...fencedOrNone("Notes", p.notes, "none yet — the role's own earlier runs write them, and the director has none"));
+    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
     // 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() !== "") {
         const more = p.inboxCount - 1;
-        lines.push(`_(the Next tick prompt embeds the oldest queued prompt — one is consumed per tick; ${more} more ${agree(more, "waits", "wait")})_`);
+        lines.push(`_(the next run's prompt embeds the oldest inbox message — one is taken per run; ${more} more ${agree(more, "waits", "wait")})_`);
     }
     return lines;
 }
@@ -53,49 +64,214 @@ function modelPair(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.agent !== "pi" ? p.agent : "pi"} default`;
+    return `${p.backend !== "pi" ? p.backend : "pi"} default`;
 }
 /** 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.
  * A non-pi backend is named as the selector's provider namespace (`claude/claude-sonnet-5-5`),
  * matching the string the events and status rows carry; a pi seam is unchanged. */
 function modelLine(p) {
+    // pi's own saved default (part 2/2): the formatted selector already carries its thinking
+    // 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})`;
     const pair = modelPair(p.provider, p.model);
     const thinking = p.thinking ? ` (thinking: ${p.thinking})` : "";
     if (!pair)
         return `${agentDefault(p)}${thinking}`;
-    const agent = p.agent !== "pi" ? `${p.agent}/` : "";
+    const agent = p.backend !== "pi" ? `${p.backend}/` : "";
     return `${agent}${pair}${thinking}`;
 }
-/** Render one loop's inspection payload as Markdown. */
-export function renderRoleMarkdown(p) {
+/** A fallback pair as one readable token, agent-qualified exactly like modelLine — a non-pi
+ * backend (its `agent`, or a provider that names one, `claude`) is named as the selector's
+ * namespace; a pi pair keeps `provider/model`; neither half present falls back to the
+ * 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);
+    if (fb.model !== undefined) {
+        if (agentBackend !== undefined)
+            return `${agentBackend}/${fb.model}`;
+        return fb.provider !== undefined ? `${fb.provider}/${fb.model}` : fb.model;
+    }
+    if (fb.provider !== undefined)
+        return fb.provider;
+    return agentDefault;
+}
+/** Why a tier moved down its fallback chain, as the role view words it. */
+function chainReasonPhrase(reason, windowType) {
+    switch (reason) {
+        case "window":
+            return `${windowType !== undefined ? claudeWindowLabel(windowType) : "Claude"} window used up`;
+        case "reserve":
+            return "window reserve reached";
+        case "cap":
+            return "daily cap reached";
+        case "step-cap":
+            return "previous step's cap reached";
+        case "overage":
+            return "extra usage refused";
+        case "demoted":
+            return "previous step demoted";
+    }
+}
+/** The `Running on fallback <step> of <of> (<why>, resets HH:MM)` bullet, or null when the
+ * role's tier is on its primary. */
+function chainStepLine(p) {
+    const c = p.chainStep;
+    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})`;
+}
+/** 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
+ * 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
+ * appended when the event carried one. Unset halves are dropped, never printed as a literal
+ * `undefined`. */
+function recentOutcomeLine(o) {
+    let line = `${formatTimestamp(o.ts)} · ${o.result}`;
+    if (o.durationMs !== undefined)
+        line += ` · ${shortSpanPhrase(o.durationMs)}`;
+    if (o.summary)
+        line += ` — ${o.summary}`;
+    return line;
+}
+/** One quiet-hours bullet: the window, whose it is, and whether it holds the loop 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
+ * `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`;
+ * 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
+ * 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.
+    const suffix = yieldMultiplierSuffix(p.yieldMultiplier);
+    let next;
+    if (p.nextRunAt <= 0) {
+        next = "not scheduled yet";
+    }
+    else {
+        const remain = secondsUntil(p.nextRunAt, 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)`
+        : "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())
+ * 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}`, ""];
-    lines.push(`- Loop: "${p.id}" (${p.title})${p.custom ? " — user-defined loop" : ""}`);
+    lines.push(`- ${p.custom ? "Custom role" : "Role"}: "${p.id}" (${p.title})`);
     const state = [p.enabled ? "enabled" : "disabled", p.paused ? "paused" : "not paused"].join(", ");
     lines.push(`- State: ${state}`);
-    lines.push(`- Scheduling tier: ${p.tier} (${p.tier === 0 ? "work" : "maintenance/observer"})`);
+    lines.push(`- Priority: ${p.tier === 0 ? "work" : "maintenance or observer"}`);
     lines.push(`- Model: ${modelLine(p)} (${p.modelTier} tier)`);
+    // Context window: the resolved primary seam's declared window (the one `- Next run:`
+    // previews, not the fallback — a run on the model fallback may use a different window, the
+    // fallback's own documented state). `unknown` when it cannot be known (a non-pi seam, an
+    // 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
+    // `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>`
+    // explains the team alert without running doctor. Unknown (null) renders `unknown` rather
+    // than guessing.
+    const images = p.imageInput === true
+        ? "yes"
+        : p.imageInput === false
+            ? p.imageReroute
+                ? `no — reruns on ${p.imageReroute}`
+                : "no"
+            : "unknown";
+    lines.push(`- Images: ${images}`);
     // 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 = modelPair(p.modelFallback.provider, p.modelFallback.model) || agentDefault(p);
+        const pair = fallbackPairLabel(p.modelFallback, agentDefault(p));
         lines.push(`- Model fallback: ${pair} — on fallback since ${formatTimestamp(p.modelFallback.since)} (primary failing: ${p.modelFallback.reason})`);
     }
     if (p.fallback) {
-        const pair = modelPair(p.fallback.provider, p.fallback.model) || agentDefault(p);
-        lines.push(`- Budget fallback: ${pair} (${p.fallbackFree ? "free" : "priced"})`);
+        const pair = fallbackPairLabel(p.fallback, agentDefault(p));
+        lines.push(`- Over-cap model: ${pair} (${p.fallbackFree ? "free" : "priced"})`);
     }
+    const running = chainStepLine(p);
+    if (running)
+        lines.push(running);
     // 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)` : "";
         lines.push(`- Billing: ${p.billing === "api" ? "API" : p.billing}${window}`);
     }
-    lines.push(`- Min tick interval: ${p.minTickIntervalSeconds}s`);
-    lines.push(`- Queued prompts: ${p.inboxCount}`);
+    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,
+    // 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`
+    // goldens are byte-identical.
+    if (p.usage) {
+        let spend = `- Spend: ${usd(p.usage.costUsd)} · ${compactTokens(p.usage.tokens)} tokens`;
+        if (p.usage.notionalCostUsd !== 0)
+            spend += ` · ${usd(p.usage.notionalCostUsd)} notional`;
+        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.
+    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"})`;
+        if (dc.roleIds.length > 1)
+            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
+    // 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.
+    if (p.recentOutcomes && p.recentOutcomes.length > 0) {
+        lines.push("", "## Recent runs", "");
+        for (const o of p.recentOutcomes)
+            lines.push(`- ${recentOutcomeLine(o)}`);
+    }
     lines.push("");
     lines.push(...fencedOrNone("Instructions override", p.instructions));
-    lines.push(...fencedOrNone("Find text", p.find, "none — the director is driven by its queued prompts, not a find text"));
-    lines.push(...inspectMarkdownLines(p));
+    lines.push(...fencedOrNone("Find text", p.find, "none — the director is driven by its inbox, not by instructions"));
+    lines.push(...inspectBodyLines(p));
     return lines.join("\n").trimEnd();
 }