tumwater 0.2.0 → 0.3.0

package/dist/src/run/run-detail-render.js

@@ -0,0 +1,98 @@
+import { runCommitSha } from "./run-detail-data.js";
+import { formatEvent } from "../events/event-format.js";
+import { eventTypeLabel } from "../events/event-labels.js";
+import { roleLabel } from "../roles/role-labels.js";
+import { shortSpanPhrase } from "../text/phrases.js";
+import { shortSha } from "../text/format.js";
+import { piLogPath } from "../paths.js";
+import { readRunTranscript } from "../ui/transcript-run.js";
+import { gitTry } from "../git/git-run.js";
+/** The `git show --stat` summary or full `--patch` of a run's pinned commit. The sha is the
+ * authored commit the run pinned: a merge that rebased gives main a different sha with the
+ * same changes, so this describes what the run changed. */
+async function runCommitShow(root, sha, what) {
+    if (sha === null)
+        return "(no commit: this run sent nothing to merge)";
+    const out = await gitTry(root, "show", what, "--format=", sha);
+    if (out === null)
+        return `(commit ${shortSha(sha)} is not in this repository)`;
+    return out.trimEnd();
+}
+/** The pinned commit's stat text for a run, shared by `run --stat` and GET /api/run so both
+ * apply one rule for the sha and the "(no commit …)" / "(commit … is not in this repository)"
+ * texts. */
+export function runDetailStat(root, d) {
+    return runCommitShow(root, runCommitSha(d), "--stat");
+}
+/** The pinned commit's full patch for a run, for `history --patch`. Like runDetailStat it
+ * shows the commit the run pinned (runCommitSha), not the `merged as` sha, so the stat and
+ * the patch describe the same commit; the placeholder texts are the stat's. GET /api/run is its
+ * second caller (the dashboard's "Show patch" button). */
+export function runDetailPatch(root, d) {
+    return runCommitShow(root, runCommitSha(d), "--patch");
+}
+/** The human view of a RunDetail: one summary line — result (or the in-flight/unpaired
+ * marker), duration, usage, and the model the run started on when its `run_start` carried one
+ * (after the usage, before the pinned-commit sha), plus the pinned commit sha when the block's
+ * `merge_queued`/`merge_done` event carries one — then each event through formatEvent, the
+ * shared renderer `logs` and the
+ * TUI use, so the trail reads exactly like the feed it came from. A queued run whose merge
+ * has finished shows that verdict in the header and ends with the merge's outcome line; a
+ * leftover-recovery run's verdict is the failed attempt it re-queued (resolveQueuedResult),
+ * logged before the run began, so that outcome line leads the trail instead — the trail stays
+ * in time order. */
+export function renderRunDetail(d) {
+    const summary = [];
+    if (d.endTs === null)
+        summary.push(d.startTs === null ? "unpaired" : "in flight");
+    else
+        summary.push(d.result ? eventTypeLabel(d.result) : "?");
+    if (d.durationMs !== null)
+        summary.push(shortSpanPhrase(d.durationMs));
+    if (d.usage !== "")
+        summary.push(d.usage);
+    if (d.model !== null)
+        summary.push(d.model);
+    const sha = runCommitSha(d);
+    let header = `${roleLabel(d.role)} run #${d.run} — ${summary.join(" · ")}`;
+    if (sha !== null)
+        header += ` · commit ${shortSha(sha)}`;
+    if (d.mergedSha !== null && d.mergedSha !== sha)
+        header += ` · merged as ${shortSha(d.mergedSha)}`;
+    if (d.reverted !== null) {
+        header += ` · reverted ${shortSha(d.reverted.sha)}`;
+        if (d.reverted.kind === "main") {
+            if (d.reverted.failingTests[0] !== undefined)
+                header += ` (failing: ${d.reverted.failingTests[0]})`;
+        }
+        else {
+            header += ` (by operator)`; // vocabulary-ok: the deliberate-revert writer this header names
+        }
+    }
+    const trail = d.events.map(formatEvent);
+    if (d.merge !== null) {
+        const first = d.events[0];
+        if (first !== undefined && d.merge.ts < first.ts)
+            trail.unshift(formatEvent(d.merge));
+        else
+            trail.push(formatEvent(d.merge));
+    }
+    return [header, ...trail].join("\n");
+}
+/** The transcript block of `--transcript`: the rendered lines of the agent runs that started in the
+ * run's window, or `found: []` plus the `note` the text view prints in their place. The
+ * dashboard's `/api/run?transcript` serves the same text. */
+export function runTranscriptLines(root, role, runNumber, detail, opts = {}) {
+    if (detail.startTs === null) {
+        return { found: [], note: `(no transcript: run ${runNumber}'s start rotated out of the event log)` };
+    }
+    return {
+        found: readRunTranscript(piLogPath(root, role), detail.startTs, detail.endTs, {
+            includePrompts: opts.includePrompts,
+            grep: opts.grep?.toLowerCase(),
+        }),
+        note: opts.grep !== undefined
+            ? `(no transcript entries matching "${opts.grep}" in ${role} run ${runNumber})`
+            : `(no transcript for ${role} run ${runNumber}: rotated out of .tumwater/log/${role}.pi.jsonl, or the run started no agent)`,
+    };
+}

package/dist/src/run/run-detail.js

@@ -0,0 +1,168 @@
+/** Command half of `tumwater history <role> <n>` and its `--last` / `--stat` / `--patch` /
+ * `--transcript` forms: the read-only command body that resolves which run to open, validates
+ * it, and prints the rendered trail (or the not-found line). The payload is collected by
+ * run-detail-data.ts (runCommitSha / runMergedSha beside it) and rendered by
+ * run-detail-render.ts, so the CLI, the TUI's History drill-down, and the GUI's /api/run serve
+ * the same text. Read-only over the event log, stdout only. */
+import { fail, say, sayJson } from "../cli/cli-output.js";
+import { parseCountFlag } from "../cli/cli-args.js";
+import { knownRoleIdsCached } from "../config/config.js";
+import { HISTORY_MAX_RUNS, HISTORY_RESULT_FLAG_NAMES, historyClass, readRunRows, runRowsOnModels } from "../history/history-data.js";
+import { parseHistoryModelList, parseHistoryResultList } from "../history/history.js";
+import { readRunDetail } from "./run-detail-data.js";
+import { runDetailPatch, runDetailStat, renderRunDetail, runTranscriptLines } from "./run-detail-render.js";
+import { unknownRoleMessage } from "../roles/roles.js";
+import { canonicalRoleId } from "../roles/legacy-role-ids.js";
+/** The run command's synopsis, word for word what cli.ts's dispatcher gate and cmdRunDetail's own
+ * arity and unknown-role guards fail with — one string so the three sites cannot drift apart
+ * when the command's shape changes. */
+export const RUN_DETAIL_USAGE = "tumwater history <role> [<n>] [--last [--result <class>[,...]] [--model <selector>[,...]]] [--stat] [--patch] [--transcript [--prompt] [--grep <text>]] [--json]";
+/** The shared not-found frame both wordings complete — what the scan looked for, the role,
+ * and that the scanned window (not the world) is what came up empty. Exactly two consumers,
+ * the not-found wordings below (the numbered form's exported message and the --last form's
+ * exported sibling), so the trailing hedge cannot drift between them. */
+function runNotFoundPhrase(role, what) {
+    return `no ${what} for ${role} in the scanned window (the retained log may have rotated past it)`;
+}
+/** The not-found wording a missed run lookup owes its surface — `tumwater history <role> <n>`'s
+ * stdout line and the GUI /api/run endpoint's 404 JSON error, one template so the CLI's prose
+ * and the browser's error card cannot drift when the phrasing moves. Names the shape a user
+ * can act on: the run number, the role, and that the scanned window (not the world) is what
+ * came up empty. */
+export function runNotFoundMessage(role, runNumber) {
+    return runNotFoundPhrase(role, `run #${runNumber}`);
+}
+/** The not-found wording for `tumwater history <role> --last`, sibling of runNotFoundMessage —
+ * the same surfaces but naming what the last-form scan actually asked for: the newest
+ * completed run, not a number the user supplied. Two consumers: cmdRunDetail's stdout line and
+ * the GUI /api/run?last=1 404 error, so the CLI and the browser cannot word the miss apart. */
+export function runNotFoundLastMessage(role, classes = null, models = null) {
+    const flagNames = classes?.map((c) => HISTORY_RESULT_FLAG_NAMES[c]).join(",");
+    const what = `completed run${classes ? ` with result "${flagNames}"` : ""}${models ? ` on model "${models.join(",")}"` : ""}`;
+    return runNotFoundPhrase(role ?? "any role", what);
+}
+/** The newest completed run's row for a role (`null` for every role), or null when the scanned
+ * window holds none: the run `tumwater history <role> --last` opens, and bare `history --last`
+ * with no role. With neither filter it is readRunRows' newest row; with `classes` it is the
+ * newest row in those outcome classes, and with `models` the newest that started on one of those
+ * selectors. Also GET /api/run?last=1 with no role. */
+export function newestRunRow(root, role, classes, models) {
+    if (!classes && !models)
+        return readRunRows(root, 1, role)[0] ?? null;
+    const rows = models ? runRowsOnModels(readRunRows(root, HISTORY_MAX_RUNS, role), models) : readRunRows(root, HISTORY_MAX_RUNS, role);
+    return rows.find((r) => !classes || classes.includes(historyClass(r.result))) ?? null;
+}
+/** The newest completed run's number for a role, or null when the scanned window holds none:
+ * the run `history <role> <n>` resolves for `--last`; newestRunRow's number. */
+function newestRunNumber(root, role, classes, models) {
+    return newestRunRow(root, role, classes, models)?.run ?? null;
+}
+/** `tumwater history <role> [<n>] [--last [--result <class>[,...]]] [--stat] [--patch]
+ * [--transcript [--prompt] [--grep <text>]] [--json]`: print one completed
+ * run's full event trail. Read-only: stdout only, no state file created — a run the
+ * scan cannot find prints a not-found line and exits 0 (history's empty-output convention:
+ * an absent record is an answer, not a failure), and under --json it prints the JSON document
+ * `null` instead — the report --json precedent
+ * that every exit-0 output is parseable, never prose. `tumwater history <role> --last` resolves
+ * the role's newest completed run in the scanned window and prints its trail exactly as the
+ * numbered form would — the summary header and event rendering are shared, only the number's
+ * provenance differs (readRunRows' newest-first scan, not the user's argument). --last and
+ * a numeric <n> are rivals: exactly one positional under --last, exactly two without. With
+ * --last, `--result <class>[,...]` picks the newest run in the listed outcome classes instead
+ * (the listing's classes, scanning up to HISTORY_MAX_RUNS runs); it needs --last. `--model
+ * <selector>[,...]` with --last keeps only runs that started on a listed model (the listing's
+ * exact match) and composes with --result; it needs --last too. With --last and no role, the
+ * newest run of any role is opened (newestRunRow with a null role) and renders as its
+ * role's form. */
+export async function cmdRunDetail(root, positionals, json, { last = false, stat = false, patch = false, transcript = false, prompt = false, grep = null, result = null, model = null } = {}) {
+    // Positional arity by form: cli.ts has already peeled the flags off and gated them (only
+    // --json and --last are admitted), so anything left over that does not fit the chosen form
+    // is a mistake. The role is checked first, so a typo is named whatever the count; then
+    // --last takes exactly one positional (<role>) and the numeric path exactly two (<role> <n>).
+    const bare = last && positionals.length === 0;
+    let role = canonicalRoleId(positionals[0] ?? "");
+    // The role is validated like every role-targeting command's --role (knownRoleIdsCached: the
+    // built-ins plus user-defined roles, read through the never-throwing cached loader so a
+    // transiently broken tumwater.json cannot take a read-only view down), with the shared
+    // unknown-role wording plus the usage the positional command owes.
+    if (positionals.length >= 1) {
+        const ids = knownRoleIdsCached(root);
+        if (!ids.includes(role))
+            fail(`${unknownRoleMessage(role, ids)} (usage: ${RUN_DETAIL_USAGE})`);
+    }
+    const arity = last ? 1 : 2;
+    if (positionals.length !== arity && !bare) {
+        if (positionals.length === 1) {
+            fail(`history ${role} needs a run number or --last — \`tumwater history --role ${role}\` lists its runs (usage: ${RUN_DETAIL_USAGE})`);
+        }
+        if (positionals.length === 2 && last) {
+            fail(`history --last takes no run number (got "${positionals[1]}") (usage: ${RUN_DETAIL_USAGE})`);
+        }
+        fail(`usage: ${RUN_DETAIL_USAGE}`);
+    }
+    if (prompt && !transcript)
+        fail(`history --prompt needs --transcript (usage: ${RUN_DETAIL_USAGE})`);
+    if (grep !== null && !transcript)
+        fail(`history --grep needs --transcript on a one-run trail (usage: ${RUN_DETAIL_USAGE})`);
+    if (result !== null && !last)
+        fail(`history --result needs --last on a one-run trail (usage: ${RUN_DETAIL_USAGE})`);
+    if (model !== null && !last)
+        fail(`history --model needs --last on a one-run trail (usage: ${RUN_DETAIL_USAGE})`);
+    const classes = result !== null ? parseHistoryResultList(result) : null;
+    const models = model !== null ? parseHistoryModelList(model) : null;
+    // The run number: either the user's positive integer (the numbered path, through the
+    // shared count parser — a non-positive or non-numeric n fails naming the shape; there is
+    // no cap — the number selects, it does not size the scan) or the newest completed run's
+    // number, read from readRunRows' newest-first scan for the role. An empty scan is not
+    // found by construction, so the not-found path below takes it with the last-form wording.
+    let runNumber;
+    if (bare) {
+        // `history --last` with no role: the newest completed run of any role; its role is the row's.
+        const row = newestRunRow(root, null, classes, models);
+        if (row !== null)
+            role = row.role;
+        runNumber = row?.run ?? null;
+    }
+    else {
+        runNumber = last ? newestRunNumber(root, role, classes, models) : parseCountFlag("history <n>", positionals[1]);
+    }
+    const detail = runNumber === null ? null : readRunDetail(root, role, runNumber);
+    if (runNumber === null) {
+        // The --last scan came up empty: not found by construction, the last-form wording.
+        if (json)
+            sayJson(null);
+        else
+            say(runNotFoundLastMessage(bare ? null : role, classes, models));
+        return;
+    }
+    if (detail === null) {
+        // Not found stays exit 0 in both renderings, but --json still owes a parseable document in
+        // every exit-0 case (the report --json precedent, the invariant this command's own doc
+        // comment claims): `null` is the JSON answer for a single-record lookup that missed — the
+        // prose line would end a jq pipe mid-team-incident.
+        if (json)
+            sayJson(null);
+        else
+            say(runNotFoundMessage(role, runNumber));
+        return;
+    }
+    // --json swaps the renderer for the collector's own payload, exactly as history --json: a
+    // JSON document in every exit-0 case, never prose.
+    const footer = {};
+    if (stat)
+        footer.stat = await runDetailStat(root, detail);
+    if (patch)
+        footer.patch = await runDetailPatch(root, detail);
+    const transcriptLines = transcript
+        ? runTranscriptLines(root, role, runNumber, detail, { includePrompts: prompt, grep: grep ?? undefined })
+        : null;
+    if (json) {
+        sayJson({ ...detail, ...footer, ...(transcriptLines === null ? {} : { transcript: transcriptLines.found }) });
+    }
+    else {
+        const transcriptText = transcriptLines === null
+            ? []
+            : [transcriptLines.found.length > 0 ? transcriptLines.found.join("\n") : transcriptLines.note];
+        say([renderRunDetail(detail), ...Object.values(footer), ...transcriptText].join("\n\n"));
+    }
+}

package/dist/src/{tick/tick-finalize.js → run/run-finalize.js}

@@ -1,11 +1,11 @@
-import { hasOutstandingWork, saveLoopState } from "../loop/loop-state.js";
+import { hasOutstandingWork, saveRunnerStateBestEffort } from "../runner/runner-state.js";
 import { branchHead } from "../git/git.js";
 import { logEventBestEffort, usageFragment, warnEventBestEffort } from "../events/events.js";
-import { observeClaudeAccount } from "../agent/claude/claude-account.js";
-import { ERROR_STREAK_WARN, QUIET_KILL_RESUME_LIMIT, applyTickOutcome } from "./tick-apply.js";
-import { restoreMidTickWake } from "../scheduling/backoff.js";
+import { observeAccount } from "../agent/subscription-account.js";
+import { ERROR_STREAK_WARN, QUIET_KILL_RESUME_LIMIT, applyRunOutcome } from "./run-apply.js";
+import { restoreMidRunWake } from "../scheduling/backoff.js";
 import { consecutiveFailuresWarning } from "../text/phrases.js";
-/** The tick results that end an instance's claim: the tick found nothing to do, refused the
+/** The run results that end an instance's claim: the run found nothing to do, refused the
  * entry, was aborted by the user, or was skipped — none of them leaves work in flight. */
 const CLAIM_RELEASING = new Set([
     "no_change",
@@ -13,43 +13,43 @@ const CLAIM_RELEASING = new Set([
     "user_aborted",
     "skipped",
 ]);
-/** Fold a finished tick's outcome into the loop's state and the event feed — everything that
- * happens AFTER the pi run, extracted from LoopRunner.tick (src/loop/loop.ts) so the runner keeps
- * only tick lifecycle (worktree, sessions, abort) and this module owns the per-result
+/** Fold a finished run's outcome into the role's state and the event feed — everything that
+ * happens AFTER the pi run, extracted from RoleRunner.run (src/runner/runner.ts) so the runner
+ * keeps only run lifecycle (worktree, sessions, abort) and this module owns the per-result
  * bookkeeping policy. Order matters here and is pinned by behavior, not by a test seam: the
- * outcome's folds are applied to state before applyTickOutcome schedules the next run, the
+ * outcome's folds are applied to state before applyRunOutcome schedules the next run, the
  * main-head read happens while `running` is still true (a poll that runs in that window must not
- * double-wake the loop), and the warnings read the streaks exactly once per episode, after the
+ * double-wake the role), and the warnings read the streaks exactly once per episode, after the
  * schedule. */
-export async function finalizeTick(deps) {
-    const { root, role, mainBranch, config, state: s, usage, tick } = deps;
+export async function finalizeRun(deps) {
+    const { root, role, mainBranch, config, state: s, usage, runNumber } = deps;
     let { outcome } = deps;
-    // A re-queued leftover's merge failure is not the tick's own result, so it rides the
-    // outcome separately: applyTickOutcome feeds it into the error streak, and the warning
-    // below names it — even though runTick cleared `lastError` so it never latched onto
+    // A re-queued leftover's merge failure is not the run's own result, so it rides the
+    // outcome separately: applyRunOutcome feeds it into the error streak, and the warning
+    // below names it — even though runOnce cleared `lastError` so it never latched onto
     // `run_end` (BUGS.md 2026-09-21).
     if (deps.recoveryFailure !== undefined)
         outcome.recoveryFailure = deps.recoveryFailure;
-    // A main_red tick's cause is written for that result (src/baseline/main-red.ts), not a leftover
+    // A main_red run's cause is written for that result (src/baseline/main-red.ts), not a leftover
     // merge failure: fold it onto the state here so `run_end` logs it like every other
     // failure's and the digest can itemize what the Outcome table's main_red cells mean
-    // (BUGS.md 2026-09-28). runTick cleared `lastError` at its start, so nothing foreign
+    // (BUGS.md 2026-09-28). runOnce cleared `lastError` at its start, so nothing foreign
     // can precede this.
     if (outcome.error !== undefined)
         s.lastError = outcome.error;
-    // Read main's current head while this tick is still reserved (running=true): the
-    // applyTickOutcome below clears running, and a poll that runs between that clear and a later
-    // head update would see a stale lastMainHead and wake the loop again on the very move
-    // that triggered this tick — a duplicate wake event plus an extra tick for one world change.
+    // Read main's current head while this run is still reserved (running=true): the
+    // applyRunOutcome below clears running, and a poll that runs between that clear and a later
+    // head update would see a stale lastMainHead and wake the role again on the very move
+    // that triggered this run — a duplicate wake event plus an extra run for one world change.
     // branchHead reads the ref files first (microsecond-scale, like the orchestrator's per-poll
     // watch) and spawns `git rev-parse` only when they cannot resolve it; a null result keeps
     // the previous value rather than waking on "main moved" to nowhere.
     s.lastMainHead = (await branchHead(root, mainBranch)) ?? s.lastMainHead;
-    // Record the outcome on state and schedule the next run (see src/tick/tick-apply.ts for the
+    // Record the outcome on state and schedule the next run (see src/run/run-apply.ts for the
     // per-result policy: prompt retry, backoff, bounded cut-off resumes).
-    applyTickOutcome(s, config, role, outcome);
-    // A tick that ends without producing or keeping work releases this instance's backlog claim
-    // (plans/parallel-work-instances.md "Claims", part 4/7): the next tick may take a different
+    applyRunOutcome(s, config, role, outcome);
+    // A run that ends without producing or keeping work releases this instance's backlog claim
+    // (plans/parallel-work-instances.md "Claims", part 4/7): the next run may take a different
     // entry. Every other result — queued, changed, rejected with a revision, an error, an abort
     // that resumes — keeps the claim so the same instance retries it; an outstanding revision or
     // a pending resume also holds it, because the entry is still this instance's task.
@@ -60,79 +60,91 @@ export async function finalizeTick(deps) {
         s.claim = undefined;
         logEventBestEffort(root, { source: role, type: "claim", action: "released", title, reason: outcome.result });
     }
-    // A wake consumed while this tick ran stamped the shared state in place, but the outcome
+    // A wake consumed while this run ran stamped the shared state in place, but the outcome
     // schedule above overwrites it (lastRunEndedAt past wokenAt, nextRunAt a fresh gap or
     // backoff out), so a plain `tumwater wake --role` with an empty queue would silently wait
     // out the whole interval (BUGS.md 2026-09-25). Re-apply it here — exactly like a wake
-    // arriving one poll after the tick ended.
-    restoreMidTickWake(s);
-    saveLoopState(root, s);
-    // One warning per error episode (BUGS.md 2026-09-15: every loop failing identically
-    // looked like a quiet team). applyTickOutcome increments the streak on error-class
-    // outcomes, preserves it across a plain `queued` tick (the tick's merge resolves it),
+    // arriving one poll after the run ended.
+    restoreMidRunWake(s);
+    // A failed save warns and the run still ends: the in-memory state already holds the fold and
+    // the runner's next save writes it, while a throw here would skip run_end and the launch
+    // task's breaker fold.
+    saveRunnerStateBestEffort(root, s);
+    // One warning per error episode (BUGS.md 2026-09-15: every role failing identically
+    // looked like a quiet team). applyRunOutcome increments the streak on error-class
+    // outcomes, preserves it across a plain `queued` run (the run's merge resolves it),
     // and resets it on any other completed result — so warn only when THIS outcome incremented
     // the streak up to the threshold: a preserved streak already sitting at the bar must not
-    // re-warn on the queued tick's end. A rejection's crossing warns from the merge side
+    // re-warn on the queued run's end. A rejection's crossing warns from the merge side
     // instead (writeMergeOutcome, src/merge/merge-slot.ts), which is where rejections resolve.
     if ((outcome.result === "error" || outcome.recoveryFailure !== undefined) &&
         (s.consecutiveErrors ?? 0) === ERROR_STREAK_WARN) {
         warnEventBestEffort(root, role, consecutiveFailuresWarning(s.consecutiveErrors ?? 0, s.lastError ?? outcome.recoveryFailure ?? "unknown error"));
     }
-    // One warning per quiet-kill episode (BUGS.md 2026-09-18): a loop burning an hour per
-    // tick with no output must not look like a sleeping loop. applyTickOutcome grows the
+    // One warning per quiet-kill episode (BUGS.md 2026-09-18): a role burning an hour per
+    // run with no output must not look like a sleeping role. applyRunOutcome grows the
     // streak on each kill and resets it on any other result, so the crossing fires once;
     // the give-up (fresh session + backoff) follows on the next kill.
     if ((s.quietKillStreak ?? 0) === QUIET_KILL_RESUME_LIMIT) {
         warnEventBestEffort(root, role, `${s.quietKillStreak} consecutive stalls (no progress): ${s.lastError ?? "unknown hang"}`);
     }
-    // Per-tick usage: the event feed is where operators see
-    // spend — this tick's tokens and cost ride on run_end so a budget pause or a money-burning
-    // no_change/error/rejected/refused tick shows what it spent without diffing status-table
-    // snapshots. Both fields are per-tick windows (reset at tick start, folded in over every
-    // pi run of the tick); they ride on HarnessEvent's index signature like other payloads and
-    // are omitted when zero so skipped ticks render byte-identical to a pre-feature line.
-    // The tick's wall-clock span rides on run_end too: the
-    // failure digest prices a tick by its own durationMs first (src/failure/failure-data.ts
-    // tickDurationMs), so the field is ALWAYS present — a tick that ends within the same
-    // Date.now() millisecond it started (an instant early-abort error tick) or crosses a
+    // Per-run usage: the event feed is where operators see
+    // spend — this run's tokens and cost ride on run_end so a budget pause or a money-burning
+    // no_change/error/rejected/refused run shows what it spent without diffing status-table
+    // snapshots. Both fields are per-run windows (reset at run start, folded in over every
+    // pi run of the run); they ride on HarnessEvent's index signature like other payloads and
+    // are omitted when zero so skipped runs render byte-identical to a pre-feature line.
+    // The run's wall-clock span rides on run_end too: the
+    // failure digest prices a run by its own durationMs first (src/failure/failure-data.ts
+    // runDurationMs), so the field is ALWAYS present — a run that ends within the same
+    // Date.now() millisecond it started (an instant early-abort error run) or crosses a
     // backward clock step still attests its 0 ms, where the old omit-when-zero convention
     // dropped the field and broke the "every run_end carries a span" contract (BUGS.md
     // 2026-09-29). Unlike the usage fields, run_end's renderer never prints the span, so an
     // always-present 0 changes no rendered line.
-    const tickDurationMs = Math.max(0, Date.now() - deps.tickStartedAt);
-    // The account state (plans/agent-backends.md part 6a): fold this tick's billing answer and
-    // rate-window readings into .tumwater/state/claude-account.json for the sibling parts that
-    // throttle or display the subscription window. Best-effort — the file is a cache, and an
-    // unwritable state dir must not fail a tick whose real work is already done.
+    const runDurationMs = Math.max(0, Date.now() - deps.runStartedAt);
+    // The account state (plans/agent-backends.md part 6a): fold this run's billing answer and
+    // rate-window readings into the reporting backend's .tumwater/state/<backend>-account.json
+    // for the sibling parts that throttle or display the subscription window. Best-effort — the
+    // file is a cache, and an unwritable state dir must not fail a run whose real work is
+    // already done. A pi run never reports either, so in practice claude owns the file until a
+    // second subscription backend lands (plans/codex-backend.md).
     if (usage.billing !== undefined || usage.rateWindows !== undefined) {
         try {
-            observeClaudeAccount(root, { billing: usage.billing, rateWindows: usage.rateWindows });
+            observeAccount(root, usage.agent ?? "pi", {
+                billing: usage.billing,
+                rateWindows: usage.rateWindows,
+            });
         }
         catch {
-            // The next reporting run rewrites it; nothing this tick depends on is lost.
+            // The next reporting run rewrites it; nothing this run depends on is lost.
         }
     }
-    // The per-provider split of this tick's usage (plans: per-provider spend in the day
+    // The per-provider split of this run's usage (plans: per-provider spend in the day
     // report): a Record<provider, {costUsd, notionalCostUsd}> for the report's `Cost by
-    // provider` line. Omitted when empty like the prompt-token fields, so a tick whose runs
+    // provider` line. Omitted when empty like the prompt-token fields, so a run whose runs
     // carried no provider renders byte-identically to today.
     const providerCost = usage.serializeProviderCost();
     logEventBestEffort(root, {
         source: role,
         type: "run_end",
-        run: tick,
+        run: runNumber,
         result: outcome.result,
         summary: outcome.summary,
         error: s.lastError,
-        durationMs: tickDurationMs,
+        durationMs: runDurationMs,
         ...usageFragment(s.generatedTokens, usage.costUsd, usage.notionalCostUsd),
         ...(Object.keys(providerCost).length > 0 ? { providerCost } : {}),
-        // The billing answer the tick's runs reported, so the report can tell notional spend from
+        // The billing answer the run's runs reported, so the report can tell notional spend from
         // real spend without re-deriving it from the file (plans/agent-backends.md part 6a).
         ...(usage.billing !== undefined ? { billing: usage.billing } : {}),
-        // Per-tick prompt-token telemetry: how many prompt
-        // tokens the tick sent, how many were cache reads, and how many went out before its first
-        // edit. Omitted when zero like usageFragment's fields, so a tick that sent no prompt — and
+        // The backend that reported the billing/rate windows (plans/codex-backend.md part 3d/9):
+        // carried under the same condition the account file is written (observeAccount above), so
+        // the report folds a run's notional spend to the subscription backend whose runs made it.
+        ...(usage.billing !== undefined || usage.rateWindows !== undefined ? { agent: usage.agent } : {}),
+        // Per-run prompt-token telemetry: how many prompt
+        // tokens the run sent, how many were cache reads, and how many went out before its first
+        // edit. Omitted when zero like usageFragment's fields, so a run that sent no prompt — and
         // every run_end written by an older build — renders byte-identically.
         ...(usage.promptTokens > 0 ? { promptTokens: usage.promptTokens } : {}),
         ...(usage.cacheReadTokens > 0 ? { cacheReadTokens: usage.cacheReadTokens } : {}),

package/dist/src/{tick/tick-outcome.js → run/run-outcome.js}

@@ -1,14 +1,13 @@
-// vocabulary: plain
-/** What a finished tick or merge is (the TickResult/TickOutcome vocabulary), shared by the
+/** What a finished run or merge is (the RunResult/RunOutcome vocabulary), shared by the
  * runner that produces it, the dashboards that render it, and the state machine that applies
  * it. The application policy — which outcomes count which streaks, when a session resumes,
- * how the next run is scheduled — lives next door in tick-apply.ts; the clock arithmetic it
- * drives in backoff.ts. This module holds only the shared types. Split out of loop-state.ts —
- * the persisted state file's load/save — and later of the types.ts grab-bag, as LoopState and
+ * how the next run is scheduled — lives next door in run-apply.ts; the clock arithmetic it
+ * drives in backoff.ts. This module holds only the shared types. Split out of runner-state.ts —
+ * the persisted state file's load/save — and later of the types.ts grab-bag, as RunnerState and
  * HarnessEvent were before it. */
 export {};
 /** Record the review gate's verdict on a HEAD into `lastReview` — the field the author's next
- * tick prompt injects (tick-prompt.ts's buildRejectedReviewNote) and the same-head strike
+ * run prompt injects (run-prompt.ts's buildRejectedReviewNote) and the same-head strike
  * counter reads (review.ts's unreviewFailures). Mutates `s` in place; the timestamp is
  * stamped here so every call site shares one Date.now() read and the shape stays in one place
- * (loop-state.ts's lastReview). */
+ * (runner-state.ts's lastReview). */