tumwater 0.2.0 → 0.4.0

package/dist/src/text/datetime.js

@@ -1,7 +1,6 @@
-// vocabulary: plain
 /** Local date/time formatting and calendar-day arithmetic — the zero-padded clock and
  * calendar parts, local-midnight day math, and the report-window header every display and
- * report surface (transcript run separators, the status table's last-tick cell, daily-budget
+ * report surface (transcript run separators, the status table's last-run cell, daily-budget
  * day stamps, the usage report's and failure digest's per-day buckets and headers) render
  * through, so what counts as one day and how a timestamp prints cannot drift per consumer.
  * Split out of text.ts — which keeps the one-line text shaping — because calendar
@@ -9,14 +8,28 @@
  * string cutting, with its own tests. Presentation only: depends on node built-ins alone. */
 import { plural } from "./phrases.js";
 import { EVENTS_LOG_BASENAME } from "../paths.js";
+/** Milliseconds in an hour — the shared unit for this repo's window and timeout
+ * constants (reclaim's idle threshold, the doctor's merge/stale-pin/wait checks, the
+ * claim/review/queue expiry, the scheduling defer cap, redeploy's cooldowns, the
+ * provider-hold window), so no two of them can spell the hour multiplier differently
+ * (`60 * 60 * 1000` vs `60 * 60_000` vs `3600_000`). Day-sized spans use `DAY_MS`
+ * (or `N * DAY_MS`) below. */
+export const HOUR_MS = 60 * 60 * 1000;
+/** Milliseconds in a day — the sibling of `HOUR_MS`: the shared day unit for the
+ * day-sized retention and lookback constants (the opencode-catalog and image-probe TTLs,
+ * the doctor's stale-pin/merge/prompt/wait checks, the known-flake and selfcheck
+ * windows, the dashboard-history since bound, the retention prune, the claude-window
+ * lookback) so one day cannot mean slightly different spans per consumer. */
+export const DAY_MS = 24 * HOUR_MS;
 /** Zero-pad an integer to two digits — the clock and calendar components every local-time
  * display in the harness renders through (transcript run separators, the status table's last-
- * tick cell, the daily-budget day stamp), so zero-padding cannot drift per consumer. */
+ * run cell, the daily-budget day stamp), so zero-padding cannot drift per consumer. */
 export function pad2(n) {
     return String(n).padStart(2, "0");
 }
 /** The local wall-clock `HH:MM` of an instant, the hours/minutes-only shape the burn-rate
- * forecast, the window badge, and the role view's fallback line share. */
+ * forecast, the window badge, the role view's fallback line, and the failure digest's
+ * transition stamps (failure-render.ts's stateChangeStamp) share. */
 export function clockHm(ms) {
     const d = new Date(ms);
     return `${pad2(d.getHours())}:${pad2(d.getMinutes())}`;
@@ -25,7 +38,7 @@ export function clockHm(ms) {
  * clamps at zero (an age never goes negative when the clock skews), `secondsUntil` clamps at
  * zero the same way for the future direction (a countdown never reads negative once its
  * deadline has passed). The one home of the clamp + rounding behind every elapsed age and
- * countdown — status-render.ts's lastTickCell and nextRunCell, the queued-prompt age and
+ * countdown — status-render.ts's lastRunCell and nextRunCell, the queued-prompt age and
  * deliver-in suffix, the team pause's auto-resume countdown, and status-model.ts's sleeping
  * phase label (which re-floors at 1s) all render through. The GUI page's browser
  * script keeps its own one-line twins (gui-client.ts's ageSec and its inline countdown
@@ -39,12 +52,6 @@ export function secondsSince(sinceMs, now) {
 export function secondsUntil(atMs, now) {
     return Math.max(0, Math.round((atMs - now) / 1000));
 }
-/** Whole elapsed seconds since an epoch-ms instant, clamped at zero and rounded to the
- * nearest second — the age rule status-render.ts's lastTickCell ages its `HH:MM:SS · Ns ago`
- * stamp through (secondsSince against the real clock). */
-export function elapsedSeconds(sinceMs) {
-    return secondsSince(sinceMs, Date.now());
-}
 /** Calendar date as `YYYY-MM-DD` in local time — shared by the transcript run separators,
  * the daily-budget day stamp (todayStamp), and the usage report's per-day buckets, which must
  * all agree on what counts as one day. */
@@ -52,13 +59,23 @@ export function formatDate(d) {
     return `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}`;
 }
 /** Wall-clock time as zero-padded `HH:MM:SS` in local time — the clock half formatTimestamp
- * builds, and the direct rendering of the status table's last-tick cell (status-render.ts's
- * lastTickCell), doctor-checks's probe-at stamp, failure-render's state-change stamp, and
+ * builds, and the direct rendering of the status table's last-run cell (status-render.ts's
+ * lastRunCell), doctor-project-checks's probe-at stamp, and
  * operator-intent's pause/deadline wording, so a local time of day reads the same shape at
  * every surface. */
 export function formatTime(d) {
     return `${pad2(d.getHours())}:${pad2(d.getMinutes())}:${pad2(d.getSeconds())}`;
 }
+/** Epoch ms as a local `HH:MM:SS` wall-clock string — the epoch-ms form of formatTime, the
+ * dayKey-to-formatDate sibling. It shares the clock-instant rendering every event renderer's
+ * pause/reset/resume suffix needs (event-format.ts's pauseSuffix and windowResetPhrase,
+ * failure-state-change.ts's team/role pause untils, doctor-model-checks.ts's probe time), so no
+ * site re-derives `formatTime(new Date(ms))`. A non-finite or absent `ms` renders the same NaN
+ * clock formatTime's Date would — callers guard with finiteNumber first, exactly as they did
+ * before. */
+export function formatClock(ms) {
+    return formatTime(new Date(ms));
+}
 /** Epoch ms as a local calendar-day key (`YYYY-MM-DD`) — the epoch-ms form of formatDate:
  * the day-bucketing rule the event log's day key (eventDayKey), the windowed readers' window
  * keys, the daily-budget stamp, and the failure digest's cluster dates all render through, so
@@ -89,7 +106,7 @@ export function monthDay(dayKey) {
  * the transcript's run separators, the history table's time cell, and the review-gate prompt's
  * rejection context, so a timestamp reads identically at every surface. A non-finite `ms` (a
  * corrupt event `ts`, a Date.parse of a malformed ISO match) renders as the em dash — the same
- * "no value" marker the history table uses for a tick with no reported duration, so a corrupt
+ * "no value" marker the history table uses for a run with no reported duration, so a corrupt
  * stamp reads as unknowable instead of printing `new Date(NaN)`'s `NaN-NaN-NaN NaN:NaN:NaN`
  * through every surface that renders events or rows. */
 export function formatTimestamp(ms) {
@@ -144,8 +161,33 @@ export function humanSeconds(s) {
 export function humanUntil(atMs, now) {
     return humanSeconds(secondsUntil(atMs, now));
 }
-/** The shared "when may this loop next act" phrase — the `next run` cell (status-render.ts's
- * nextRunCell) and the `Next tick` line (role-render.ts's scheduleLine) render their schedule
+/** `humanUntil`'s past-direction twin: how long since an epoch-ms instant, as `NS ago` —
+ * the past-direction phrase five renderers each built as `{humanSeconds(secondsSince(...))} ago`
+ * (status-render.ts's ago against the real clock, role-render.ts's last-run and
+ * merge-queue-render.ts's enqueue ages, inbox.ts's queued-age suffix, and doctor-notify.ts's
+ * latest-failed-page age, which had inlined the clamp itself), so the clamp, the rounding,
+ * and the " ago" wording cannot drift per consumer. Lives here beside the other time
+ * phrasing so core modules (which may not import src/ui) share the same form. */
+export function humanAgo(sinceMs, now) {
+    return `${humanSeconds(secondsSince(sinceMs, now))} ago`;
+}
+/** A compact age clamped at zero and floored to whole units — `12m`, `4h`, `6d` — the bare
+ * (no `ago`) parenthetical the `qa` coverage block and the `feedback` "previously filed" block
+ * render for each ledger entry, which each defined as their own local `formatAge`. Kept
+ * distinct from humanSeconds on purpose: this floors (a sub-minute age reads `0m`, never
+ * `Ns`) and skips the seconds bucket, so the two units/rounding rules cannot drift per
+ * consumer. Lives here beside the other time phrasing. */
+export function formatAge(ms) {
+    const minutes = Math.max(0, Math.floor(ms / 60_000));
+    if (minutes < 60)
+        return `${minutes}m`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours}h`;
+    return `${Math.floor(hours / 24)}d`;
+}
+/** The shared "when may this role next act" phrase — the `next run` cell (status-render.ts's
+ * nextRunCell) and the `Next run` line (role-render.ts's scheduleLine) render their schedule
  * through it, so the two surfaces cannot drift on the backoff prefix or the humanSeconds
  * bucketing. `remainSeconds` is the seconds until the next run (non-positive = due); `backoff`
  * adds the `backoff ` prefix the wake action clears; `dueWord` names the due case and `withIn`
@@ -166,7 +208,7 @@ export function dayLabel(days) {
     return plural(days, "day");
 }
 /** The report header both renderers print: the window's day-key bounds, its length in days
- * (singular at 1), and the event log it was read from. The failure digest appends its own tick
+ * (singular at 1), and the event log it was read from. The failure digest appends its own run
  * count. The rotation phrase is a required argument — eventsRotationLabel() supplies it from
  * events.ts's EVENTS_MAX_BYTES, so this header cannot keep claiming "16 MB" after the actual
  * threshold moves (this module stays presentation-only, owning no log facts of its own). The
@@ -180,7 +222,12 @@ export function reportWindow(from, to, days, rotation) {
  * with the window's start instant in local time. `duration` is the window length already phrased
  * by cli-args.ts's durationLabel (this helper supplies the leading `last `) — taken as a
  * string so this presentation-only module avoids importing the CLI layer; the failure digest
- * appends its own tick count. One home so the two reports' window wording cannot drift. */
+ * appends its own run count. One home so the two reports' window wording cannot drift. */
 export function sinceWindowLine(duration, fromIso) {
     return `window: last ${duration} (since ${formatTimestamp(new Date(fromIso).getTime())})`;
 }
+/** The bounded sibling of `sinceWindowLine`: the window line for a `--since`/`--until` span that
+ * ends before now. */
+export function boundedWindowLine(since, until, fromIso, toIso) {
+    return `window: ${since} to ${until} ago (since ${formatTimestamp(new Date(fromIso).getTime())}, until ${formatTimestamp(new Date(toIso).getTime())})`;
+}

package/dist/src/text/format.js

@@ -6,20 +6,31 @@ import { textOr } from "./text.js";
  * (wording fragments). Presentation only: depends on node built-ins alone, so any layer
  * (harness or observer) can import it — and each format lives in exactly one place so the
  * abbreviation length, decimal width, and compaction thresholds cannot drift per consumer. */
+/** Append a section note to a running prompt, separated from what precedes it by a blank line.
+ * The run and authoring-run prompt assemblers (run-prompt.ts, runner-run.ts) build a prompt by
+ * stacking nameless sections — assignment, held-entry, conflict-discard, conflict-handback and
+ * cut-off notes appended this way. The rejected-review and revision notes deliberately LEAD the
+ * run instead (prependPromptNote, plans/reviewer-as-role.md part 4/4) so the author cannot miss
+ * them. This is the single append so the `\n\n` section separator stays in one place. The note
+ * is appended unconditionally, exactly as the call sites appended the literal, so behavior is
+ * unchanged for any note. */
+export function appendPromptNote(prompt, note) {
+    return `${prompt}\n\n${note}`;
+}
+/** Prepend a section note to a running prompt, separated from what follows by a blank line — the
+ * mirror of appendPromptNote, used where a note must LEAD the charter rather than trail it: the
+ * rejected-review note (run-prompt.ts) and the revision note (runner-run.ts) of
+ * plans/reviewer-as-role.md part 4/4, which the author must not miss. This is the single prepend
+ * so the `\n\n` section separator stays in one place, the same way appendPromptNote owns the
+ * append side. */
+export function prependPromptNote(prompt, note) {
+    return `${note}\n\n${prompt}`;
+}
 /** Compact token count for tight table cells and commit trailers — bare integers below
  * 10,000, one-decimal k at and above 10,000, one-decimal M at and above 1,000,000. The single
  * home of the token display format shared by the status table's gen/peak-ctx columns and the
  * commit trailer's ctx field — pinned here so those surfaces cannot drift even though they
  * live in different modules. */
-/** Append a section note to a running prompt, separated from what precedes it by a blank line.
- * The tick and authoring-tick prompt assemblers (tick-prompt.ts, loop-tick.ts) build a prompt by
- * stacking nameless sections — assignment, held-entry, rejected-review, conflict-discard,
- * conflict-handback, revision and cut-off notes — each appended the same way. This is the single
- * append so the `\n\n` section separator stays in one place. The note is appended unconditionally,
- * exactly as the call sites appended the literal, so behavior is unchanged for any note. */
-export function appendPromptNote(prompt, note) {
-    return `${prompt}\n\n${note}`;
-}
 export function compactTokens(n) {
     if (n >= 1_000_000)
         return `${(n / 1_000_000).toFixed(1)}M`;
@@ -58,10 +69,36 @@ export function usdCap(n) {
 /** A disk size in GB for display: one decimal and the unit (`12.3 GB`) — the single home of
  * the disk-size format shared by the event feed's disk lines (event-format.ts), the status
  * header's disk badge (badges.ts's `diskBadge`), the team's low-disk alert (team-alerts.ts),
- * the doctor's disk check detail (doctor-checks.ts), and `tumwater reclaim`'s freed-size line
- * (operator-commands.ts), so the decimal width and unit cannot drift per consumer. A caller
+ * the doctor's disk check detail (doctor-project-checks.ts), and `tumwater reclaim`'s
+ * freed-size line (operator-commands.ts), so the decimal width and unit cannot drift per
+ * consumer. A caller
  * reading the value from an untrusted event field applies event-format.ts's `gigabytes`
  * wrapper (finiteNumber's corrupt-field rule) over this. */
 export function formatGB(n) {
     return `${n.toFixed(1)} GB`;
 }
+/** A byte count for display, picking the largest of the B/KB/MB/GB tiers so the unit keeps the
+ * number small (`2.0 KB`, `1.5 MB`) — one decimal everywhere. The single home of the tiered
+ * byte format shared by the doctor's claude transcript size (doctor-checks.ts's `formatBytes`)
+ * and the opencode db/spill sizes (doctor-model-checks.ts's `opencodeBytes`), so the tiers and
+ * decimal width cannot drift per consumer. Distinct from `formatGB` above, which always renders
+ * a disk size in GB regardless of magnitude. The GUI's file-size label still formats from its
+ * own inline JS in gui-client-composer.ts: a separate runtime that cannot import TypeScript. */
+export function formatBytes(n) {
+    if (n >= 1024 ** 3)
+        return `${(n / 1024 ** 3).toFixed(1)} GB`;
+    if (n >= 1024 ** 2)
+        return `${(n / 1024 ** 2).toFixed(1)} MB`;
+    if (n >= 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    return `${n} B`;
+}
+/** A token-count context window with its unit, thousands-separated (`128,000-token window`) —
+ * the single home of this format shared by the doctor's codex and opencode model checks
+ * (doctor-codex-checks.ts, doctor-opencode-checks.ts), each of which renders a cataloged
+ * model's window this way, so the separator and the "-token window" unit cannot drift per
+ * consumer. The separating comma is the caller's to add when the label follows a price
+ * (opencode's `, ${tokenWindowLabel(…)}`). */
+export function tokenWindowLabel(n) {
+    return `${n.toLocaleString("en-US")}-token window`;
+}

package/dist/src/text/markdown.js

@@ -18,13 +18,16 @@ export function markdownTable(header, rows, align = []) {
         ...rows.map((cells) => `| ${cells.join(" | ")} |`),
     ];
 }
-/** `items` as a `1. …` ordered list, one line each, joined with newlines — the single home of
+/** `items` as a `1. …` ordered list, one line each, joined with newlines — the home of
  * the `map((item, i) => `${i + 1}. ${item}`).join("\n")` step, shared by the review prompt's
  * prior objections, its stage-fix findings, and the rejected/revision notes
- * (prompt/gate-prompts.ts) and `tumwater questions`' open-question list
- * (backlog/question-answer.ts), so the numbering shape cannot drift between the surfaces that
- * read a numbered list. `empty` is returned verbatim when `items` is empty (the reasons
- * sites pass `(no reasons recorded)`; the others keep the default empty string). */
+ * (prompt/gate-notes.ts), `tumwater questions`' open-question list
+ * (backlog/question-answer.ts) and `tumwater wake --list`'s wake lines
+ * (operator/operator-intent.ts `renderWakeList`), so the numbering shape cannot drift between
+ * those surfaces (the TUI queued-prompt rows and the merge queue rows number their own
+ * lines). `empty` is returned verbatim when `items` is empty
+ * (the reasons sites
+ * pass `(no reasons recorded)`; the others keep the default empty string). */
 export function numberedList(items, empty = "") {
     return items.length > 0 ? items.map((item, i) => `${i + 1}. ${item}`).join("\n") : empty;
 }

package/dist/src/text/phrases.js

@@ -1,4 +1,3 @@
-// vocabulary: plain
 import path from "node:path";
 import { finiteNumber, isJsonObject, stringList } from "../files/json-object.js";
 import { squash } from "./text.js";
@@ -8,38 +7,40 @@ import { shortSha, usd } from "./format.js";
  * of $y", main's red-tip naming, a tool call's one-line label, the plural helper) shared by the
  * event feed (event-format.ts), the failure digest (src/failure/failure-render.ts and
  * src/failure/failure-state-change.ts), the status surfaces (ui/), and the CLI messages
- * (operator/operator-commands.ts, cli/cli-run.ts), so their phrasing cannot drift per consumer.
+ * (operator/operator-commands.ts, cli/cli-start-summary.ts), so their phrasing
+ * cannot drift per consumer.
  * Pure presentation: every phrase composes the shared formats format.ts pins (shortSha, usd,
  * squash) into words. Pure value formats — the token a number or hash renders as (compactTokens,
  * shortSha, usd, usdCap) — stay in format.ts; this module is where those tokens become words. */
 const NO_REASONS_GIVEN = "no reasons given";
-/** The reason an over-long prompt or config field carries: the text rides into a tick's
- * prefill, so a longer value bloats every tick's context. The single home of that tail,
+/** The reason an over-long prompt or config field carries: the text rides into a run's
+ * prefill, so a longer value bloats every run's context. The single home of that tail,
  * shared by init's seed check (init/init.ts) and config-validation's customRoles task and
  * roles-instructions caps (config/config-validation.ts), so the three cannot drift on the
  * wording. inbox-submit's promptLengthProblem renders a role-scoped variant ("it rides into
- * the <role> tick's prefill") and keeps its own wording. */
+ * the <role> run's prefill") and keeps its own wording. */
 export const PREFILL_REASON = "it rides into every run's prefill";
 /** The reason a review rejection leads with — its first listed reason, or `no reasons given`
  * when the list is empty or its first entry is not a string. One home so the fallback cannot
  * drift across the four surfaces that show just that first reason: the review gate's returned
  * detail (review.ts), the event feed's one-line reject (event-format.ts), the failure digest's
- * rejection clusters (failure-data.ts), and the error a loop's next tick records (tick-apply.ts).
+ * rejection clusters (failure-data.ts), and the error a role's next run records (run-apply.ts).
  * Sites that render the whole reason list, or intentionally omit the fallback (time-spend.ts's
  * first-reason example, review.ts's rejection event `reason`), keep their own handling. */
 export function firstReason(reasons) {
     const first = reasons?.[0];
     return typeof first === "string" ? first : NO_REASONS_GIVEN;
 }
-/** A count and its noun as one phrase (`plural(3, "tick")` → `3 ticks`) — the single home of
- * the singular/plural selection the CLI's once summary (cli/cli-run.ts), the day window's day label
+/** A count and its noun as one phrase (`plural(3, "run")` → `3 runs`) — the single home of the
+ * singular/plural selection the CLI's once summary (cli/cli-start-summary.ts), the
+ * day window's day label
  * (datetime.ts), the failure digest's loss-cause lines (src/failure/failure-render.ts), and the
  * team alerts' banner titles (ui/team-alerts.ts, whose local copy this replaces), and the
  * build_stale lines' "N commit(s) ahead" (event-format.ts, src/failure/failure-state-change.ts —
  * the singular/plural wording their tests pin, once "N commit(s)" with the old literal, now "N
  * commits"/"1 commit"), and the stage self-check and dropped-attachment notes
- * (src/tick/tick-stage.ts, inbox/inbox-attachments.ts) all rendered inline before. `many` accepts a
- * whole replacement form (`plural(n, "loop is", "loops are")`) so verb-agreement titles share the
+ * (src/run/run-stage.ts, inbox/inbox-attachments.ts) all rendered inline before. `many` accepts a
+ * whole replacement form (`plural(n, "role is", "roles are")`) so verb-agreement titles share the
  * helper; the plural-by-`s` default covers regular nouns. (The GUI keeps its own JS copy in
  * gui-client.ts: a separate runtime that cannot import TypeScript.) */
 export function plural(n, one, many = `${one}s`) {
@@ -86,16 +87,16 @@ export function mainRedNotMine(sha) {
 export function pauseReasonSuffix(reason) {
     return reason ? ` — "${reason}"` : "";
 }
-/** The harness warning a loop crossing the error-streak threshold raises — `3 consecutive
- * tick failures: <reason>` — shared by the tick-side crossing (tick-finalize.ts, an error or
+/** The harness warning a role crossing the error-streak threshold raises — `3 consecutive
+ * run failures: <reason>` — shared by the run-side crossing (run-finalize.ts, an error or
  * recovery failure) and the merge-side crossing a review rejection resolves
  * (merge-slot.ts), the two sites that build the message, so the operator-facing wording
  * their tests pin cannot drift between them. */
 export function consecutiveFailuresWarning(count, reason) {
     return `${count} runs failed in a row: ${reason}`;
 }
-/** The base line for an operator team pause — `team paused — role loops stop starting new
- * ticks` — built here so the event feed (event-format.ts, which appends its own `(director
+/** The base line for an operator team pause — `team paused — roles stop starting new
+ * runs` — built here so the event feed (event-format.ts, which appends its own `(director
  * keeps running)` consequence) and the failure digest's Team state changes lines
  * (src/failure/failure-state-change.ts, which keeps the short form) cannot drift on the base
  * wording. `tumwater pause`'s confirmation (operator/operator-commands.ts) interleaves its
@@ -112,6 +113,10 @@ export function teamPausePhrase() {
 export function teamResumePhrase() {
     return "team resumed — roles run again";
 }
+/** Appended to a resume line whose `expired: true` event says the pause's deadline lifted it
+ * rather than `tumwater resume` — read by the event feed (event-format.ts) and the failure
+ * digest (src/failure/failure-state-change.ts). */
+export const PAUSE_EXPIRED_SUFFIX = " (its timed pause ran out)";
 /** The base line for a per-role pause — `role <id> paused — it starts no new runs` —
  * shared by the event feed (event-format.ts, which appends `(the rest of the team keeps running)`)
  * and the failure digest's Team state changes lines (src/failure/failure-state-change.ts, which
@@ -129,7 +134,25 @@ export function roleResumePhrase(role) {
 }
 /** The line for an orchestrator shutdown — the event feed (event-format.ts) and the failure
  * digest's Team state changes lines (src/failure/failure-state-change.ts) both render it. */
-export const ORCHESTRATOR_STOPPED = "tumwater stopped";
+const ORCHESTRATOR_STOPPED = "tumwater stopped";
+/** The orchestrator shutdown line with its `cause` (restart, once, signal, error): the event feed
+ * (event-format.ts) and the failure digest (src/failure/failure-state-change.ts) both render it.
+ * A missing or unknown cause — every event logged before the field existed — renders the bare
+ * ORCHESTRATOR_STOPPED. */
+export function orchestratorStopPhrase(cause) {
+    switch (cause) {
+        case "restart":
+            return `${ORCHESTRATOR_STOPPED} to restart onto the new build`;
+        case "once":
+            return `${ORCHESTRATOR_STOPPED} — the --once round settled`;
+        case "signal":
+            return `${ORCHESTRATOR_STOPPED} on a stop signal`;
+        case "error":
+            return `${ORCHESTRATOR_STOPPED} — its polling failed`;
+        default:
+            return ORCHESTRATOR_STOPPED;
+    }
+}
 /** A HarnessEvent's loosely typed `roles` list as a `A, B, C` phrase — the single home of the
  * array coercion and join, shared by the event feed (event-format.ts: counters_reset's scope,
  * budget_handback's handed-back list, the rate_limit_hold line) and the failure digest's state-
@@ -197,17 +220,30 @@ export function backendKindPhrase(kind) {
             return "backend failure";
     }
 }
+const LEADING_CD = /^\s*cd\s+(?:"[^"]*"|'[^']*'|\S+)\s*(?:&&|;)\s*/;
+function withoutLeadingCd(command) {
+    let rest = command;
+    while (LEADING_CD.test(rest))
+        rest = rest.replace(LEADING_CD, "");
+    return rest.trim() ? rest : command;
+}
 /** One-line description of a tool call from its name and args — shared by live progress data
  * collection (LiveProgress.lastTool), transcript rendering, and the harness's stalled-tool-call
  * warning (src/pi/pi-stream.ts builds the label src/pi/pi-watchdogs.ts renders). Path-like keys
- * reduce to the file name; the other candidate keys are shown verbatim. */
+ * reduce to the file name; the other candidate keys are shown verbatim. A leading `cd <dir> &&`
+ * is dropped from a command, because the run's cwd is implied and the path would use up the
+ * 32-character budget. */
 export function describeToolCall(toolName, args) {
     let detail = "";
     if (isJsonObject(args)) {
         const candidate = args.path ?? args.file_path ?? args.command ?? args.cmd ?? args.pattern ?? args.url;
         if (typeof candidate === "string") {
             detail =
-                candidate === args.path || candidate === args.file_path ? path.basename(candidate) : candidate;
+                candidate === args.path || candidate === args.file_path
+                    ? path.basename(candidate)
+                    : candidate === args.command || candidate === args.cmd
+                        ? withoutLeadingCd(candidate)
+                        : candidate;
         }
     }
     detail = squash(detail, 32);
@@ -218,12 +254,13 @@ export function describeToolCall(toolName, args) {
 /** The ` (+N more)` remainder suffix a capped list appends when `count` entries were omitted —
  * empty when none were, so the item fits an already-built line either way. The single home of that
  * parenthesized remainder, shared by the reviewer suite-rerun warning (review/suite-rerun.ts) and
- * the stage self-check's missing-path and lost-final-newline findings (tick/stage-check.ts), so the
- * three cannot drift on the spacing or the parenthesized form. The other remainder phrasings keep
- * their own wording: the failure digest's bare `+N more` role list and its `_+N more …_` lines
- * (failure/failure-render.ts), doctor's `and N more` (doctor/doctor-orphans.ts), the TUI alert
- * pointer (ui/tui/tui-frame.ts), and the review-reject reasons, whose extra clause sits inside the
- * parentheses (events/event-format.ts). */
+ * the stage self-check's missing-path and lost-final-newline findings (run/stage-path-checks.ts
+ * and run/stage-prose-checks.ts),
+ * so the three cannot drift on the spacing or the parenthesized form. The other remainder
+ * phrasings keep their own wording: the failure digest's bare `+N more` role list and its `_+N
+ * more …_` lines (failure/failure-render.ts), doctor's `and N more` (doctor/doctor-orphans.ts),
+ * the TUI alert pointer (ui/tui/tui-frame.ts), and the review-reject reasons, whose extra clause
+ * sits inside the parentheses (events/event-format.ts). */
 export function moreSuffix(count) {
     return count > 0 ? ` (+${count} more)` : "";
 }

package/dist/src/text/suggest.js

@@ -55,7 +55,7 @@ export function didYouMean(suggestion) {
  * `input` against `candidates`, the empty string when nothing is close enough to suggest. The
  * unknown-X error sites (roles.ts's unknownRoleMessage, config-write.ts's
  * unknownConfigKeyError and its role-field error, config-field-checks.ts's checkKnownKeys,
- * checkKnownRoleId and its thinking-level problem, config-validation.ts's backend problem,
+ * checkKnownRoleId and its thinking-level problem, config-validation-agents.ts's backend problem,
  * gui/gui-args.ts's rejectBadRole, init-templates.ts's
  * unknownTemplateError) render the hint
  * through this one composition so the two-step pairing cannot drift; callers still print the

package/dist/src/text/text.js

@@ -1,5 +1,5 @@
 /** Shared text-shaping helpers for human-facing one-line text — the observability layer's
- * display labels (live progress, transcripts), tick commit subjects and body fields, and
+ * display labels (live progress, transcripts), run commit subjects and body fields, and
  * build-check reason lines: whitespace collapsing, ellipsis truncation, and plain-decimal
  * integer parsing. (Number, money, and hash formats — compactTokens, shortSha, usd, usdCap —
  * live in format.ts; local date/time formatting and calendar-day arithmetic live in
@@ -34,7 +34,7 @@ export function stripTerminalControls(s) {
  * The one home of the "a torn or hand-edited field reads as a visible placeholder, never
  * String(undefined)'s literal 'undefined'" coercion the event feed's free-text fields and
  * shortSha apply. Numbers stay admitted because events legitimately carry numeric fields
- * (a tick number, a pid) that a display line renders as text. */
+ * (a run number, a pid) that a display line renders as text. */
 export function textOr(value, fallback = "?") {
     if (typeof value === "string")
         return value;
@@ -49,6 +49,28 @@ export function textOr(value, fallback = "?") {
 export function errorMessage(err) {
     return err instanceof Error ? err.message : String(err);
 }
+/** The first line of `errorMessage(err)`, trimmed: the one-line form a status reason carries
+ * when git's multi-line stderr would swamp it. Used by the fast-forward and archive-commit
+ * failure reasons. */
+export function errorFirstLine(err) {
+    return errorMessage(err).trim().split("\n")[0];
+}
+/** `s` with every regex metacharacter escaped, so it can be dropped into a `RegExp` and match
+ * only its literal text — the one spelling of the standard `replace(/[.*+?^${}()|[\]\\]/g,
+ * "\\$&")` escape, previously repeated at every site that turned an untrusted string (a
+ * provider id, a series/held-tag prefix, a role-note token, a config fragment) into a
+ * word-bounded or anchored match. Careful callers build `new RegExp(escapeRegExp(s))` and then
+ * append the boundaries (`\\b`, `^`, `)`) they want on top; this helper escapes only, never
+ * anchors, so the caller keeps control of the surrounding pattern. The presentation-only
+ * contract is inherited from the module: node built-ins alone, so any layer can import it. */
+export function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** The first line of `body` that begins with `prefix` once trimmed, trimmed; undefined when no
+ * line does. Used by the backlog's hold-note text and the answered-question preview. */
+export function firstTrimmedLineStartingWith(body, prefix) {
+    return body.split("\n").map((l) => l.trim()).find((l) => l.startsWith(prefix));
+}
 /** The error message's " (got …)" value suffix, spelled one way everywhere: JSON.stringify for
  * the value's debug form, wrapped in the established parenthetical. The human-facing
  * validation errors that echo back a rejected value with this suffix — the CLI flag
@@ -57,12 +79,11 @@ export function errorMessage(err) {
  * this one helper, so the "got" wording and its quoting cannot drift between surfaces.
  * (Deliberately different suffixes: config-field-checks's show() truncates long config values
  * before the parenthetical, and cli/cli-args.ts's duration cap renders the value through
- * durationLabel — neither fits a plain stringify.) Undefined values are the
- * caller's call: append the suffix only for a value that is actually present (see
- * gui/gui-args's string/boolean validators), since ` (got undefined)` would name a field the
- * request simply did not carry. */
+ * durationLabel — neither fits a plain stringify.) A missing value
+ * (undefined) appends nothing, since ` (got undefined)` would name a field the request never
+ * carried; null still prints ` (got null)`, a value the request did carry. */
 export function gotSuffix(v) {
-    return ` (got ${JSON.stringify(v)})`;
+    return v === undefined ? "" : ` (got ${JSON.stringify(v)})`;
 }
 /** Is `v` a string with non-whitespace content — the "field carries something usable" guard every
  * structural read of an unknown-typed JSON field applies (a blank or whitespace-only string reads
@@ -70,7 +91,7 @@ export function gotSuffix(v) {
  * narrows `v` to `string` for the code that consumes it — the one spelling shared by
  * build/build-check-detect.ts's check-script/command/cwd/gateCommand reads, config validation's
  * thinking-level check and model-field guards (tier-map values, the legacy model/ fallback selector
- * and its legacy provider, exempt paths, custom-loop tasks), pi-event-line.ts's tool-result content
+ * and its legacy provider, exempt paths, custom-role tasks), pi-event-line.ts's tool-result content
  * test, quiet-hours.ts's per-role window lookup, and inbox-attachments.ts's image-name check, so
  * the blank-means-unset rule cannot drift per call site. Callers where a bare empty string means
  * unset rather than blank text (notify.ts, version.ts, inbox-cancel.ts) keep their own `=== ""`
@@ -79,6 +100,27 @@ export function gotSuffix(v) {
 export function isNonBlankString(v) {
     return typeof v === "string" && v.trim() !== "";
 }
+/** Split a comma list into its trimmed, non-empty pieces, in order — the one spelling of the
+ * split-trim-drop-blanks step shared by the `--role` list flags (cli-args.ts and
+ * operator-commands.ts), `logs --type`, the history `--result` and `--model` filters, and the
+ * GUI's `role` and `model` query parameters. Deduplication and the no-piece-left error stay
+ * with each caller. */
+export function splitCommaList(raw) {
+    return raw.split(",").map((p) => p.trim()).filter((p) => p !== "");
+}
+/** splitCommaList with repeated pieces dropped (first occurrence kept) — the `--model` history
+ * filter and the GUI's `role` and `model` query parameters, each of which treats a repeat as
+ * the same selector. */
+export function splitCommaListUnique(raw) {
+    return [...new Set(splitCommaList(raw))];
+}
+/** A value or list of `T` as a list: a bare `T` is one item, an array stays itself. The
+ * single home of the string-or-list normalization (a `--role` selector is either one id or a
+ * comma-split list): report-fold.ts's scopeBases/roleSum/narrowToRole and history-data.ts's
+ * role filter each spelled the `typeof x === "string" ? [x] : x` wrap by hand before. */
+export function asList(value) {
+    return typeof value === "string" ? [value] : value;
+}
 /** Drop the blank lines at the start of `lines`, in place — the one home of the
  * leading-blank trim loop shared by the backlog writer's section-content rebuild and
  * `questions answer`'s tail slice (the lines after the moved answer). Blank means
@@ -112,6 +154,20 @@ function isLowSurrogate(code) {
 export function cutSplitsSurrogatePair(s, i) {
     return i > 0 && i < s.length && isHighSurrogate(s.charCodeAt(i - 1)) && isLowSurrogate(s.charCodeAt(i));
 }
+/** Join the first `max` of `items` with `sep`, then `<sep>+N more` when others were left out. */
+export function joinWithMore(items, max, sep = ", ") {
+    const shown = items.slice(0, max).join(sep);
+    return items.length > max ? `${shown}${sep}+${items.length - max} more` : shown;
+}
+/** Join the non-empty entries of `parts` with `sep`, dropping empty strings and nullish or
+ * falsy entries — the shape of a message assembled from optional fragments (a doctor verdict
+ * line, a commit body, a provider/model token, an error note). Each call site previously
+ * wrote `[a, ...b].filter(Boolean).join(sep)` by hand; feeding a fragment that is unset (an
+ * `undefined`/`false` from a guard) is fine, no `cond ? x : ""` placeholder needed. Returns
+ * the empty string when nothing is non-empty. */
+export function joinParts(parts, sep = "; ") {
+    return parts.filter((p) => Boolean(p)).join(sep);
+}
 /** Shorten `s` to at most `max` characters: unchanged when it fits, otherwise cut to
  * `max - 1`, drop any trailing space the cut may have left behind, and append an ellipsis.
  * The result is never longer than `max`. A cut that would split a surrogate pair (an astral
@@ -140,8 +196,8 @@ export function squash(s, max) {
 /** Text capped for injection into a prompt: past `max` characters it is cut and given a visible
  * `…[<label> truncated at <max> chars]` note naming what was capped and how much survived, so
  * the loss is never silent. The single home of that marker format — the PRINCIPLES.md cap
- * (principles.ts's readPrinciples), the initial-prompt backstop (brief.ts's extractPrompt), and
- * the role-notebook read (tick-prompt.ts) all render through it, so the defensive caps cannot
+ * (principles.ts's readPrinciples), the brief text backstop (brief.ts's extractPrompt), and
+ * the role-notes read (run-prompt.ts) all render through it, so the defensive caps cannot
  * drift apart in wording. A plain slice at `max` (not truncate's ellipsis-and-trim cut): the
  * marker carries the ellipsis, and the cut boundary must stay a stable, predictable prefix of
  * the original text. A cut that would split a surrogate pair (an astral character such as
@@ -189,11 +245,20 @@ export function parseNonNegativeInt(raw) {
 }
 /** The shared over-long-text message: `<subject> is <n> chars — shorten it to at most <max>`,
  * with `tail` naming where the text rides once accepted. The one home of that phrasing, used
- * by init's seed check (init.ts, "the initial prompt … every tick's prefill"), inbox-submit's
- * promptLengthProblem ("the prompt … the <role> tick's prefill"), and config-validation's
- * customRoles task and roles instructions caps (both "every tick's prefill"), so the four
+ * by init's seed check (init.ts, "the brief text … every run's prefill"), inbox-submit's
+ * promptLengthProblem ("the prompt … the <role> run's prefill"), and config-validation's
+ * customRoles task and roles instructions caps (both "every run's prefill"), so the four
  * too-long messages cannot drift apart in shape. Callers keep their own subject, cap, and
  * tail; this owns only the sentence around them. */
 export function tooLongMessage(subject, n, max, tail) {
     return `${subject} is ${n} chars — shorten it to at most ${max}: ${tail}`;
 }
+/** Each distinct path-shaped token in `text`, in first-appearance order: at least one slash and
+ * a final `.<ext>` segment. Scanned inside the text (not whitespace-split) so surrounding
+ * backticks, brackets, and sentence punctuation fall away with the match. Shared by the staging
+ * self-check's added-nonexistent-path finding (run/stage-path-checks.ts) and run-prompt's
+ * role-note missing-path scan (run/run-prompt.ts), so the two agree on what reads as a path. */
+export function pathTokens(text) {
+    const tokenRe = /[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)+\.[A-Za-z0-9]+/g;
+    return [...new Set([...text.matchAll(tokenRe)].map((m) => m[0]))];
+}