tumwater 0.2.0 → 0.4.0

package/dist/src/failure/time-spend.js

@@ -1,13 +1,13 @@
-import { eventRole, eventUsage, tickSpanMs, tickStartMap } from "../events/event-read.js";
+import { eventRole, eventUsage, runSpanMs, runStartMap } from "../events/event-read.js";
 import { errorTextOrPlaceholder, normalizeClusterKey, poolTimeoutKey, sortedRoles, truncateExample } from "./failure-cluster.js";
-import { resolveQueuedResult, bucketMergeEvents } from "../history/history-data.js";
+import { resolveQueuedResult, bucketMergeEvents } from "../history/history-queued.js";
 import { nonNegativeNumber, stringList } from "../files/json-object.js";
 import { getOrCreate, groupBy, rankByCount } from "../collections.js";
 /** How the Outcome table's results collapse for costing:
- * "merged" made progress, "no_change" spent a tick and merged nothing, and every remaining
+ * "merged" made progress, "no_change" spent a run and merged nothing, and every remaining
  * result is "error-class" — it burned agent time without merge, whether the cause was a
  * hard failure or the review gate. Typed as a full Record so a result added to
- * src/tick/tick-outcome.ts and forgotten here is a compile error, like RESULT_ORDER in
+ * src/run/run-outcome.ts and forgotten here is a compile error, like RESULT_ORDER in
  * src/failure/failure-render.ts. */
 export const OUTCOME_CLASS = {
     changed: "merged",
@@ -35,7 +35,7 @@ const LOSS_TOP = 5;
 /** The raw results whose loss attributes to a cluster — an error, an abort, a quiet kill, or
  * a red-main skip, each carrying its own message on the run_end (main_red's is the
  * redMainMessage the error-clusters section already itemizes, BUGS.md 2026-10-07). A queued
- * tick's merge outcomes are owned by the joins below instead: review_error through its
+ * run's merge outcomes are owned by the joins below instead: review_error through its
  * matching `review_failed` message, review-rejected through its review reasons, and
  * merge_conflict/merge_blocked by the result itself (BUGS.md 2026-10-10). (A raw
  * `user_aborted` run_end is also error-class but is not in this set, so it stays out of the
@@ -45,8 +45,8 @@ const CLUSTERED_RESULTS = new Set(["error", "aborted", "quiet_killed", "main_red
  * other can occupy. Shared by the review-rejected and review_error cause joins, so the two
  * agree on which event belongs to the attempt (BUGS.md 2026-10-10: the window, not the pin's
  * sha, is the match, since every verification rebases its pin before the gate). */
-function newestAttemptEvent(eventsByLoop, role, attempt) {
-    return (eventsByLoop.get(role) ?? [])
+function newestAttemptEvent(eventsByRunner, role, attempt) {
+    return (eventsByRunner.get(role) ?? [])
         .filter((e) => e.ts >= attempt.pin.ts && e.ts <= attempt.outcome.ts)
         .at(-1);
 }
@@ -64,14 +64,14 @@ function pooledClusterCause(source) {
  * written since 2026-09-29 does), else the start→end pairing over `starts` — the same
  * fallback history-data.ts renders, so old events read their span the one way it can still be
  * known. 0 when neither source has the start (rotation cut it); the fold prices no time it
- * cannot attest but still counts the tick. */
-function tickDurationMs(ev, starts) {
+ * cannot attest but still counts the run. */
+function runDurationMs(ev, starts) {
     const own = nonNegativeNumber(ev.durationMs, null);
     if (own !== null)
         return own;
-    return tickSpanMs(ev, starts) ?? 0;
+    return runSpanMs(ev, starts) ?? 0;
 }
-/** Add one tick to a {runs, ms, costUsd} accumulator — the single home of the fold shared
+/** Add one run to a {runs, ms, costUsd} accumulator — the single home of the fold shared
  * by the time-and-spend table's outcome cells (SpendCell) and the loss-cause drafts
  * (LossDraft), so the two tallies cannot drift apart in what they count or price. The
  * caller passes one event's already-computed durationMs and usage, so folding an event
@@ -82,48 +82,48 @@ function tally(target, durationMs, usage) {
     target.costUsd += usage.costUsd;
 }
 /** Fold the window's run_ends into the time-and-spend table and the loss ranking. Pairing
- * runs over BOTH windows' events (the caller passes the whole read), so a tick that opened
+ * runs over BOTH windows' events (the caller passes the whole read), so a run that opened
  * in the preceding day and ended in the current one still gets its span. The merge-outcome
  * join runs over that same whole read too (BUGS.md 2026-09-30): a queued run_end resolves
  * through its own merge_queued pin to the later merge_done/merge_failed outcome for the same
- * loop+sha — history-data.ts's exact join — so an authoring tick whose merge was rejected
+ * role+sha — history-data.ts's exact join — so an authoring run whose merge was rejected
  * prices into the error-class cell its contract names instead of the merged cell its
  * transient queued result suggested. A leftover-recovery run resolves to the failed attempt it
  * re-queued (the history row's rule), so its near-zero span counts under that failure — a
  * review timeout's cluster, say — rather than adding a run to the change's final
  * review-rejected cause once per re-queue. A merge still in the pipeline, or an outcome event
  * matching no pin, keeps the queued→merged reading: the conservative fallback. */
-export function timeAndSpend(tickEvents, allEvents) {
-    const starts = tickStartMap(allEvents);
+export function timeAndSpend(runEvents, allEvents) {
+    const starts = runStartMap(allEvents);
     const emptyCell = () => ({ runs: 0, ms: 0, costUsd: 0 });
     const byRole = new Map();
     const losses = new Map();
-    // The merge evidence rides history-data.ts's bucketMergeEvents — the same buckets
+    // The merge evidence rides history-queued.ts's bucketMergeEvents — the same buckets
     // history's rows read — so the digest's join cannot drift from the rows' join.
-    const { mergeQueuedByLoop, outcomeByLoop } = bucketMergeEvents(allEvents);
-    const rejectedByLoop = groupBy(allEvents.filter((e) => e.type === "review_rejected"), (e) => e.source);
+    const { mergeQueuedByRunner, outcomeByRunner } = bucketMergeEvents(allEvents);
+    const rejectedByRunner = groupBy(allEvents.filter((e) => e.type === "review_rejected"), (e) => e.source);
     // A review_error merge kept its pin but left no message on its own merge_failed; the
-    // matching review_failed event for the same loop+sha carries it, so the span prices under
+    // matching review_failed event for the same role+sha carries it, so the span prices under
     // the same cluster key the digest's review-failure section already counts.
-    const reviewFailedByLoop = groupBy(allEvents.filter((e) => e.type === "review_failed"), (e) => e.source);
-    const deadlineKilledByLoop = groupBy(allEvents.filter((e) => e.type === "build_check" &&
+    const reviewFailedByRunner = groupBy(allEvents.filter((e) => e.type === "review_failed"), (e) => e.source);
+    const deadlineKilledByRunner = groupBy(allEvents.filter((e) => e.type === "build_check" &&
         e.status === "failed" &&
         (e.scope === "merge" || e.scope === "batch") &&
         typeof e.timeoutMs === "number"), (e) => e.source);
     // Queued run_ends resolve newest-first so each claims the newest pin at or before its end
-    // that no newer tick has claimed — resolveQueuedResult's exact claim rule, shared with the
-    // history rows. tickEvents is oldest-first, hence the backward walk.
+    // that no newer run has claimed — resolveQueuedResult's exact claim rule, shared with the
+    // history rows. runEvents is oldest-first, hence the backward walk.
     const claimTop = new Map();
     const resolved = new Map();
-    for (let i = tickEvents.length - 1; i >= 0; i--) {
-        const ev = tickEvents[i];
+    for (let i = runEvents.length - 1; i >= 0; i--) {
+        const ev = runEvents[i];
         if (ev.result !== "queued")
             continue;
-        const joined = resolveQueuedResult(ev, mergeQueuedByLoop, outcomeByLoop, claimTop, new Map(), null);
+        const joined = resolveQueuedResult(ev, mergeQueuedByRunner, outcomeByRunner, claimTop, new Map(), null);
         if (joined !== null)
             resolved.set(ev, joined);
     }
-    for (const ev of tickEvents) {
+    for (const ev of runEvents) {
         let cls = OUTCOME_CLASS[ev.result];
         if (cls === undefined)
             continue; // An unknown result is tallied in the Outcome table; costing it would need a class first.
@@ -138,7 +138,7 @@ export function timeAndSpend(tickEvents, allEvents) {
         }
         const role = eventRole(ev);
         const usage = eventUsage(ev);
-        const durationMs = tickDurationMs(ev, starts);
+        const durationMs = runDurationMs(ev, starts);
         const row = getOrCreate(byRole, role, () => ({
             merged: emptyCell(),
             no_change: emptyCell(),
@@ -155,9 +155,9 @@ export function timeAndSpend(tickEvents, allEvents) {
         if (ev.result === "refused") {
             // A refusal is a deliberate objection that blocks its entry, not quiet idleness — the
             // reason live in the event + lastSummary (src/verdict/refusal.ts). Rank it as its own
-            // per-role cause so the digest surfaces the objection instead of pricing the tick
+            // per-role cause so the digest surfaces the objection instead of pricing the run
             // exactly like a silently idle one; the branch sits BEFORE the no_change one because a
-            // refused tick is also no_change-class in the outcome table. The example rides the
+            // refused run is also no_change-class in the outcome table. The example rides the
             // refusal's summary the way a review-rejected cause rides its reason.
             key = `refused\u0000${role}`;
             kind = "refused";
@@ -169,8 +169,8 @@ export function timeAndSpend(tickEvents, allEvents) {
         }
         else if (CLUSTERED_RESULTS.has(String(ev.result))) {
             // A clustered result with no error text still owns its time: an abort's run_end never
-            // carries one (planTickStart clears s.lastError, tick-finalize logs error: undefined),
-            // and a malformed error tick can lose it too, so both take the same placeholder cause the
+            // carries one (planRunStart clears s.lastError, run-finalize logs error: undefined),
+            // and a malformed error run can lose it too, so both take the same placeholder cause the
             // error-clusters section already itemizes rather than dropping the span itemized nowhere.
             ({ key, example } = pooledClusterCause(ev.error));
         }
@@ -182,7 +182,7 @@ export function timeAndSpend(tickEvents, allEvents) {
             // `merge_queued` keeps the authored one — exact-sha equality names no reason for a rebased
             // rejection (BUGS.md 2026-10-10). The rejection for this attempt is the one inside the
             // claimed pin and its outcome, the window no other attempt can occupy.
-            const rej = newestAttemptEvent(rejectedByLoop, role, resolvedOutcome);
+            const rej = newestAttemptEvent(rejectedByRunner, role, resolvedOutcome);
             const reasons = stringList(rej?.reasons);
             example = reasons[0] !== undefined ? truncateExample(reasons[0]) : "";
         }
@@ -198,7 +198,7 @@ export function timeAndSpend(tickEvents, allEvents) {
             // keeps the authored one — exact-sha equality missed every rebased verification (BUGS.md
             // 2026-10-10). The review failure for this attempt is the one that falls inside the
             // claimed pin and its outcome, the window no other attempt can occupy.
-            const failed = newestAttemptEvent(reviewFailedByLoop, role, resolvedOutcome);
+            const failed = newestAttemptEvent(reviewFailedByRunner, role, resolvedOutcome);
             ({ key, example } = pooledClusterCause(failed?.message));
         }
         else if (ev.result === "queued" &&
@@ -214,7 +214,7 @@ export function timeAndSpend(tickEvents, allEvents) {
             example = errorTextOrPlaceholder(undefined);
             // A merge-scope check the harness killed at its own deadline is the team's load, not a
             // verdict on the change: split it into its own cause so the ranking names it.
-            const killed = newestAttemptEvent(deadlineKilledByLoop, role, resolvedOutcome);
+            const killed = newestAttemptEvent(deadlineKilledByRunner, role, resolvedOutcome);
             if (kind === "merge-blocked" && killed) {
                 key = `merge_blocked_deadline\u0000${role}`;
                 example = `${String(killed.scope)} build check killed at its ${Number(killed.timeoutMs) / 1000}s deadline (tumwater's own timeout, not a test failure)`;

package/dist/src/files/file-queue.js

@@ -44,6 +44,23 @@ export function queueFileStamp(name) {
     const m = /^(\d{13})-/.exec(name);
     return m ? Number(m[1]) : null;
 }
+/** The queue-file name one stamp below `stamps`' minimum — naming an entry to sort before
+ * every listed one, the "move to head" rename both queues share. With no parseable stamps it
+ * falls back to just before now (before every hand-placed name). Decrements while the computed
+ * name exists on disk, because a concurrent writer may have just taken the name we computed;
+ * the pid in queueFileName keeps two concurrent tops' names apart too. `ext` is the queue's own
+ * entry extension. The caller hands in its already-listed stamps (parsed with queueFileStamp),
+ * not a fresh scan, so the smallest stamp reflects the same read that picked the entry being
+ * moved. */
+export function lowestStampName(stamps, dir, ext) {
+    let stamp = (stamps.length > 0 ? Math.min(...stamps) : Date.now()) - 1;
+    let file = path.join(dir, queueFileName(stamp, 0, ext));
+    while (fs.existsSync(file)) {
+        stamp--;
+        file = path.join(dir, queueFileName(stamp, 0, ext));
+    }
+    return file;
+}
 /** Remove one queue entry's file, reporting whether it was there: true when removed, false
  * when it had already vanished (ENOENT). Any other error is rethrown. Both queues treat a
  * vanished file as a normal race with a concurrent dequeue/cancel, never as a failure. */

package/dist/src/files/files.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { errCode } from "../errno.js";
+import { DAY_MS } from "../text/datetime.js";
 /** Generic file operations under the harness's error policy — missing is no data, cleanup
  * must not throw, directories are created before writes: stat-or-missing for log readers,
  * PATH lookup for the pi-installation preflight, size-based rotation, recursive directory
@@ -22,6 +23,22 @@ export function statOrNull(file) {
         return null; // Missing (or vanished) — no data yet.
     }
 }
+/** Whether `file` exists and is a directory (a symlink is followed); false when it is missing
+ * or cannot be stat'd. */
+export function isDirectory(file) {
+    return statOrNull(file)?.isDirectory() === true;
+}
+/** Whether `file` is a regular file the process may execute (a symlink is followed); false
+ * when it is missing, a directory (which passes X_OK), or lacks the executable bit. */
+export function isExecutableFile(file) {
+    try {
+        fs.accessSync(file, fs.constants.X_OK);
+        return fs.statSync(file).isFile();
+    }
+    catch {
+        return false;
+    }
+}
 /** Whether a freshly stat'd file is still the same file at the same bytes as a prior
  * observation: matching dev/ino (a replaced inode is a different file even at the same size)
  * plus matching size and, when the caller tracks it, mtime. The one home of the freshness
@@ -36,6 +53,12 @@ export function sameStatIdentity(st, prev) {
         return false;
     return prev.mtimeMs === undefined || st.mtimeMs === prev.mtimeMs;
 }
+/** The identity fields sameStatIdentity compares, all zero when the file is missing (`null`):
+ * the "empty log" observation, so a log that has not been created yet reads as zero bytes of a
+ * file no real stat can match. */
+export function statIdentityOrZero(st) {
+    return { dev: st?.dev ?? 0, ino: st?.ino ?? 0, size: st?.size ?? 0, mtimeMs: st?.mtimeMs ?? 0 };
+}
 /** Open `file` for reading, or null when it vanished between a prior stat and this open — the
  * shared race-handling step for the incremental/tail log readers (forEachTailChunk,
  * terminateTornTail, readCompleteLines, readTranscriptTail), all of which treat a rotated-away
@@ -83,7 +106,7 @@ export function terminateTornTail(file, st) {
 /** Read a text file whole, or null when it does not exist (or cannot be read) — the harness's
  * "missing is no data" policy for the markdown and prompt text a render or prompt-building
  * path must never throw on: the backlog's PLANS/BUGS/QUESTIONS, the principles injected into
- * every tick prompt, the usage report's sources, and a queued prompt that vanished mid-
+ * every run prompt, the usage report's sources, and a queued prompt that vanished mid-
  * listing. The single home of that read-and-swallow step; callers pick their empty value
  * (`?? ""` when a blank default reads better than null). */
 export function readTextOrNull(file) {
@@ -148,29 +171,37 @@ export function envPath() {
 /** Locate an executable on PATH the same way spawn() would resolve it: a regular file
  * with the execute bit in some PATH directory. Returns its absolute path, or null when
  * missing (or not executable), so callers can fail fast with a clear message instead of
- * letting every tick die with "spawn <name> ENOENT". */
+ * letting every run die with "spawn <name> ENOENT". */
 export function findOnPath(name, pathEnv = envPath()) {
     for (const dir of pathEnv.split(path.delimiter)) {
         if (!dir)
             continue;
         const candidate = path.join(dir, name);
-        try {
-            fs.accessSync(candidate, fs.constants.X_OK); // Directories pass X_OK; require a file.
-            if (fs.statSync(candidate).isFile())
-                return candidate;
-        }
-        catch {
-            // Not in this directory; keep looking.
-        }
+        if (isExecutableFile(candidate))
+            return candidate;
     }
     return null;
 }
 /** Keep an append-only log bounded: over `maxBytes` it is renamed to `<file>.1`
- * (replacing any previous rotation) and a fresh file starts. Returns true if rotated. */
-export function rotateIfLarge(file, maxBytes) {
+ * (replacing any previous rotation) and a fresh file starts. Returns true if rotated.
+ * `keep` is how many archived generations to retain: over the size it drops `<file>.<keep>`,
+ * shifts `<file>.<k-1>` → `<file>.<k>` from oldest to newest (missing generations skipped),
+ * then moves the live file to `<file>.1`. With `keep` 1 it behaves as before, replacing the
+ * previous `.1`; role pi logs pass the default, the harness event log keeps five generations
+ * (EVENTS_KEEP). */
+export function rotateIfLarge(file, maxBytes, keep = 1) {
     try {
         if (fs.statSync(file).size <= maxBytes)
             return false;
+        if (keep >= 1) {
+            // Drop the oldest generation first so a shift down cannot collide with it.
+            fs.rmSync(file + "." + keep, { force: true });
+            for (let gen = keep - 1; gen >= 1; gen--) {
+                const from = file + "." + gen;
+                if (fs.existsSync(from))
+                    fs.renameSync(from, file + "." + (gen + 1));
+            }
+        }
         fs.renameSync(file, file + ".1");
         return true;
     }
@@ -217,13 +248,9 @@ export function walkUp(startDir, maxLevels, visit) {
  * cannot drift between them. (files.ts's own pruneOldFiles keeps its hand-rolled walk: it
  * removes emptied directories on the way back up, which this file-only visitor cannot do.) */
 export function walkFiles(dir, visit, skipDirs = new Set()) {
-    let entries;
-    try {
-        entries = fs.readdirSync(dir, { withFileTypes: true });
-    }
-    catch {
+    const entries = tryReadDirEntries(dir);
+    if (!entries)
         return; // Vanished or unreadable — skip this directory.
-    }
     for (const entry of entries) {
         const file = path.join(dir, entry.name);
         if (entry.isDirectory()) {
@@ -241,22 +268,44 @@ export function walkFiles(dir, visit, skipDirs = new Set()) {
  * with the same walk-and-swallow error policy, so it lives here once. (walkFiles above is the
  * recursive, file-only sibling.) */
 export function subdirectoryNames(dir, keep) {
-    let entries;
+    const entries = tryReadDirEntries(dir);
+    if (!entries)
+        return []; // Missing or unreadable — no data.
+    const names = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+    return keep ? names.filter(keep) : names;
+}
+/** The entry names directly under `dir`, in readdir order; `[]` when the directory is missing
+ * or unreadable. For the best-effort scans — a sweep, a count, an existence probe — where "no
+ * directory" and "nothing in it" are the same answer. A reader that must tell an unreadable
+ * directory from an empty one (listQueueFiles) keeps its own try/catch. */
+export function dirEntryNames(dir) {
     try {
-        entries = fs.readdirSync(dir, { withFileTypes: true });
+        return fs.readdirSync(dir);
     }
     catch {
-        return []; // Missing or unreadable — no data.
+        return [];
+    }
+}
+/** The `Dirent` list directly under `dir`, or null when the directory is missing or
+ * unreadable — the walk-and-swallow prelude walkFiles, subdirectoryNames, pruneOldFiles, and
+ * treeBytes all began by spelling out, so the "a vanished or unreadable directory is skipped,
+ * never an error" policy lives in one place. `dirEntryNames` above is the plain-name sibling
+ * for scans that need no file/directory distinction. build-stage.ts's pruneStaleStagings reads
+ * the staging root the same way, and exports it the way dirEntryNames is exported.) */
+export function tryReadDirEntries(dir) {
+    try {
+        return fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return null;
     }
-    const names = entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
-    return keep ? names.filter(keep) : names;
 }
 /** Write `data` — UTF-8 text or raw bytes — to `file` via a tmp file + rename, so a concurrent
  * reader of the same path sees either the old (absent) or the new content, never a partial
  * write: the prompt-inbox queue files (inbox.ts's enqueueRolePrompt) are written by one process
- * while dashboards poll, `--list` reads, and the loops dequeue in others, and a read that races
- * the write could run a tick on a truncated user request or flash one on the dashboard. The tmp
- * name carries the pid because several processes can write at once (CLI, TUI, GUI, a loop's
+ * while dashboards poll, `--list` reads, and the roles dequeue in others, and a read that races
+ * the write could start an agent run on a truncated user request or flash one on the dashboard.
+ * The tmp name carries the pid because several processes can write at once (CLI, TUI, GUI, a role's
  * re-queue); on failure the tmp is removed and the error rethrown, leaving the target untouched.
  * The harness's JSON writer (writeJsonAtomic in src/files/json-files.ts) and the config write-back
  * (writeBytesAtomic's caller, merge-git.ts's restoreConfigBytes) write through this, so the
@@ -304,6 +353,11 @@ export function removeQuiet(file) {
 export function removeTree(dir) {
     fs.rmSync(dir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
 }
+/** The epoch-ms instant `days` days before now: the age cutoff the retention prunes compare a
+ * file's mtime against (pruneOldFiles, pruneOldDirectory, and session-ledger.ts's two prunes). */
+export function daysAgoMs(days) {
+    return Date.now() - days * DAY_MS;
+}
 /** Delete regular files under `dir` (recursively) older than `days` days. Walks with a plain
  * per-directory readdir instead of {recursive: true} + entry.parentPath, so it stays within the
  * Node >= 20 floor declared in package.json — parentPath landed only in v20.12, and on earlier
@@ -324,16 +378,12 @@ export function removeTree(dir) {
 export function pruneOldFiles(dir, days) {
     if (!fs.existsSync(dir))
         return 0;
-    const cutoff = Date.now() - days * 24 * 3600 * 1000;
+    const cutoff = daysAgoMs(days);
     let pruned = 0;
     const walk = (d) => {
-        let entries;
-        try {
-            entries = fs.readdirSync(d, { withFileTypes: true });
-        }
-        catch {
+        const entries = tryReadDirEntries(d);
+        if (!entries)
             return; // Vanished (or unreadable) mid-scan; skip this directory.
-        }
         for (const entry of entries) {
             const file = path.join(d, entry.name);
             if (entry.isDirectory()) {
@@ -369,14 +419,14 @@ export function pruneOldFiles(dir, days) {
 }
 /** Remove `dir` entirely when the directory itself is older than `days` days (its own mtime,
  * not its children's). Worktree builds leave a gitignored `dist/` dir that `git clean -fd`
- * does not drop; this prunes it at the next tick, bounded by the same age rule. Returns true
+ * does not drop; this prunes it at the next run, bounded by the same age rule. Returns true
  * when the directory was removed. Mirrors pruneOldFiles' vanish-tolerant style. */
 export function pruneOldDirectory(dir, days) {
     if (!fs.existsSync(dir))
         return false;
     let pruned = false;
     try {
-        if (fs.statSync(dir).mtimeMs < Date.now() - days * 24 * 3600 * 1000) {
+        if (fs.statSync(dir).mtimeMs < daysAgoMs(days)) {
             removeTree(dir);
             pruned = true;
         }
@@ -386,3 +436,29 @@ export function pruneOldDirectory(dir, days) {
     }
     return pruned;
 }
+/** The total bytes under one directory tree, counted iteratively and skipping unreadable
+ * entries: a permission-denied subdirectory must not fail doctor. */
+export function treeBytes(dir) {
+    let total = 0;
+    const stack = [dir];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        const entries = tryReadDirEntries(current);
+        if (!entries)
+            continue;
+        for (const entry of entries) {
+            const full = path.join(current, entry.name);
+            if (entry.isDirectory())
+                stack.push(full);
+            else if (entry.isFile()) {
+                try {
+                    total += fs.statSync(full).size;
+                }
+                catch {
+                    // A file that vanished mid-walk contributes nothing.
+                }
+            }
+        }
+    }
+    return total;
+}

package/dist/src/files/json-files.js

@@ -8,14 +8,14 @@ import { parseJsonObject } from "./json-object.js";
  * is "no data", never an error) shared by every reader and writer of those files. */
 /** Read and parse a JSON *object* file, returning null when it does not exist, cannot be read
  * or parsed, or parses to a valid JSON value that is not a plain object (a scalar, `null`, or
- * an array). The harness's state/marker/info files (loop state, orchestrator info, landing
+ * an array). The harness's state/marker/info files (runner state, orchestrator info, landing
  * marker, reset/wake/abort markers, restart stamp, build stamp, claude account state) are all
  * objects written by other processes and may be missing or torn mid-write — readers treat that
  * as "no data" rather than an error, so a crash in one process can never take down the
  * observers polling them. A wrong-shaped file reads the same way: casting a scalar/array to `T`
  * would hand
- * callers a value that looks like data but is not (loadLoopState would spread a string's
- * characters into the loop's state, readOrchestratorInfo's `pid` would read undefined off an
+ * callers a value that looks like data but is not (loadRunnerState would spread a string's
+ * characters into the role's state, readOrchestratorInfo's `pid` would read undefined off an
  * array), so the object check is part of the no-data policy, not an extra one. */
 export function readJsonFile(file) {
     try {

package/dist/src/files/json-object.js

@@ -30,11 +30,11 @@ export function stringList(value) {
  * absent, not a number, or not finite (NaN/±Infinity poison arithmetic and comparisons: a
  * NaN costUsd makes every budget-cap comparison false, so the cap never trips) — the one
  * home of the "the field is the number or it is nothing" read. The call sites, by the
- * fallback each passes: event-read.ts's eventTick (tick → 0), eventUsage (tokens, costUsd →
- * 0), eventDayKey (ts → null), tickStartMap and tickSpanMs (both ts → null);
+ * fallback each passes: event-read.ts's eventRun (run → 0), eventUsage (tokens, costUsd →
+ * 0), eventDayKey (ts → null), runStartMap and runSpanMs (both ts → null);
  * event-format.ts's elapsed (ms → null), gigabytes (v → 0), minutes (ms → 0), and the
  * build_stale, slot_wait, restart, and permit_reserve renderers (aheadCommits, waitedMs,
- * abortedTicks, reserve → 0); phrases.ts's budgetPhrase (spentUsd, capUsd → 0); redeploy.ts's
+ * abortedRuns, reserve → 0); phrases.ts's budgetPhrase (spentUsd, capUsd → 0); redeploy.ts's
  * autoRestartRecord (lastAt → null); build/build-info.ts's readBuildInfo (builtAt → 0);
  * failure/failure-state-change.ts's model_fallback_ended (durationMs → 0) and build_stale
  * renderer (aheadCommits → 0); gates/maintenance-quota.ts's foldLine and seed (ev.ts → null);
@@ -54,13 +54,13 @@ export function finiteNumber(value, fallback) {
  * amount is as poisonous as NaN: it runs a spend total backwards and makes every `>= cap`
  * comparison false, so the daily budget's safety valve would never trip. The call sites, by
  * the fallback each passes: budget/budget.ts's spendNumber (dayCostUsd/usd → 0),
- * loop/loop-state.ts's healNumber (every numeric LoopState field → 0),
- * tick/tick-usage.ts's counter (each persisted usage count → 0), pi/pi-stream.ts's usageNumber
+ * runner/runner-state-load.ts's healNumber (every numeric RunnerState field → 0),
+ * run/run-usage.ts's counter (each persisted usage count → 0), pi/pi-stream.ts's usageNumber
  * (one wire usage number → 0), ui/progress-data.ts's message_end read (totalTokens → the
- * previous context, output and its peak floor → 0), time-spend.ts's tickDurationMs (an event's
+ * previous context, output and its peak floor → 0), time-spend.ts's runDurationMs (an event's
  * durationMs → null, the "no own duration" marker), pi-extension/context-budget.ts's
  * contextNote (usedTokens, usedWindow → null), pi-extension/context-shake.ts's percentOf
- * (tokens, contextWindow → null), merge/merge-queue.ts's isMergeEntry (tick, enqueuedAt,
+ * (tokens, contextWindow → null), merge/merge-queue.ts's isMergeEntry (run, enqueuedAt,
  * revisionRound → null), git/slots-state.ts's isSlotLease (since, pid → null); and
  * agent/claude/claude-stream.ts's canonicalUsage (each wire usage
  * number → 0) and its result/retry/rate-limit reads (api_error_status, attempt,
@@ -92,6 +92,27 @@ export function parseJsonObject(text) {
 export function objectOrEmpty(value) {
     return isJsonObject(value) ? value : {};
 }
+/** The entries of `value` that pass `guard`, as a fresh record; `{}` when `value` is not a JSON
+ * object. The one home of "keep the well-formed entries of an untrusted map, drop the foreign
+ * ones" (the image-probe and opencode-catalog caches, the per-pair daily spend map). Built with
+ * `Object.fromEntries`, so a `__proto__` key stays an own property. */
+export function validEntries(value, guard) {
+    if (!isJsonObject(value))
+        return {};
+    return Object.fromEntries(Object.entries(value).filter((kv) => guard(kv[1])));
+}
+/** Store one own property on `obj` under `key`. A plain `obj[key] = value` loses a key of
+ * `__proto__`: the assignment hits Object.prototype's setter and rewrites the map's prototype
+ * instead of adding an own entry, so the value vanishes from every reader and from the
+ * persisted JSON. Handling untrusted keys, or a model/flow name crossing an external boundary,
+ * means that case is real, so every site that stores under such a key defines the own property
+ * instead — the one home of the `enumerable/writable/configurable: true` descriptor, so the
+ * three flags cannot drift between sites. A named wrapper (`setWindow` on the account's
+ * windows) keeps its domain meaning across its call sites; callers keep `setOwn` where the
+ * key/value are generic, as the qa coverage ledger and budget.ts's per-pair spend do. */
+export function setOwn(obj, key, value) {
+    Object.defineProperty(obj, key, { value, enumerable: true, writable: true, configurable: true });
+}
 /** Assemble a stream translator's canonical usage block from the four already-validated non-
  * negative counts and the USD cost — the one home of the shape both the claude and opencode
  * translators (agent/claude/claude-stream.ts, agent/opencode/opencode-stream.ts) build, so the

package/dist/src/files/stat-cache.js

@@ -36,8 +36,8 @@ export function cachedByStat(cache, key, file, load, clone) {
  * reads it, and a null (no data) propagates through so a render path never throws on the file's
  * state. `parse` runs only on a cache miss and receives the file's text (never null); `clone`
  * hands each caller its own copy. The callers: backlog.ts's sectionEntries and
- * sectionCompletionDates, and backlog-structure.ts's strandedPlanEntriesFor,
- * actionableEntryRangesFor, and renderBacklogIndexBlock. */
+ * sectionCompletionDates, and backlog-structure.ts's strandedPlanEntriesFor and
+ * actionableEntryRangesFor, and backlog-index.ts's renderBacklogIndexBlock. */
 export function cachedTextByStat(cache, key, file, parse, clone) {
     return cachedByStat(cache, key, file, () => {
         const md = readTextOrNull(file); // Missing or unreadable — no data.

package/dist/src/files/tail.js

@@ -160,7 +160,7 @@ const MAX_TAILS = 64;
  *   from `fresh()`'s offset and folding every line into its fresh value;
  * - append-only growth since the last visit → fold only the newly complete lines in.
  * A torn trailing line is left unconsumed until its newline lands (the offset advances to
- * the last complete line). Shared by every observer that polls a log once per tick —
+ * the last complete line). Shared by every observer that polls a log once per run —
  * src/ui/progress-data.ts's live tail and transcript.ts's rendered entries. */
 export function withTail(tails, file, st, fresh, feed) {
     let tail = tails.get(file);

package/dist/src/gates/bootstrap-gates.js

@@ -1,8 +1,7 @@
-// vocabulary: plain
 /** New-project bootstrap (plans/work-ratio.md, "New-project bootstrap"; part 2/2): a fresh
  * project seeds `bootstrap.untilPlansDone` in tumwater.json (part 1/2), and this gate holds
- * every maintenance loop until that many plans have moved to PLANS.md's `## Done`. Only plan,
- * feature and director tick — plus bugfix while BUGS.md `## Open` is non-empty, since its
+ * every maintenance role until that many plans have moved to PLANS.md's `## Done`. Only plan,
+ * feature and director run — plus bugfix while BUGS.md `## Open` is non-empty, since its
  * latent-bug search is maintenance. The hold gives a young project a steady stream of plans and
  * code before hygiene roles start churning.
  *
@@ -28,7 +27,7 @@ import { writeJsonAtomic } from "../files/json-files.js";
 import { logEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
 import { errorMessage, stripTerminalControls } from "../text/text.js";
 import { BUGFIX_ROLE, DIRECTOR_ROLE } from "../roles/roles.js";
-import { baseRoleOf } from "../roles/loop-ids.js";
+import { baseRoleOf } from "../roles/runner-ids.js";
 /** The read-only bootstrap verdict: active while a positive `untilPlansDone` is configured and
  * the latch file is absent and fewer than that many plans are Done. No writes — the status
  * surfaces (src/status/status-data.ts) call this directly to show the same figure the
@@ -56,7 +55,7 @@ export function bootstrapHoldsRole(role, openBugsNow) {
 export function newBootstrapGateState() {
     return { active: false };
 }
-/** Step the gate by one orchestrator poll. Returns the loop ids held by bootstrap as of THIS
+/** Step the gate by one orchestrator poll. Returns the role ids held by bootstrap as of THIS
  * poll, for the scheduler's `bootstrapHeld` view. When the target has been reached, writes the
  * latch and logs `bootstrap_complete` once (the now-present latch suppresses later logs, and
  * survives an orchestrator restart that resets `state`). An unwritable repo does not abort the