tumwater 0.1.2 → 0.2.0

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

@@ -1,17 +1,17 @@
 import { eventRole, eventUsage, tickSpanMs, tickStartMap } from "../events/event-read.js";
 import { errorTextOrPlaceholder, normalizeClusterKey, poolTimeoutKey, sortedRoles, truncateExample } from "./failure-cluster.js";
-import { resolveQueuedResult, bucketLandingEvents } from "../history/history-data.js";
+import { resolveQueuedResult, bucketMergeEvents } from "../history/history-data.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:
- * "landed" made progress, "no_change" spent a tick and landed nothing, and every remaining
- * result is "error-class" — it burned agent time without landing, whether the cause was a
+ * "merged" made progress, "no_change" spent a tick 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/failure/failure-render.ts. */
-const OUTCOME_CLASS = {
-    changed: "landed",
-    queued: "landed",
+export const OUTCOME_CLASS = {
+    changed: "merged",
+    queued: "merged",
     no_change: "no_change",
     refused: "no_change",
     skipped: "no_change",
@@ -28,29 +28,39 @@ const OUTCOME_CLASS = {
 /** A row's summed wall-clock span across its outcome classes — the sort key that puts the
  * burning role first, the way the usage report ranks its cost lines. */
 function sumMs(classes) {
-    return classes.landed.ms + classes.no_change.ms + classes.error.ms;
+    return classes.merged.ms + classes.no_change.ms + classes.error.ms;
 }
 /** The loss-cause cut, like ERROR_TOP above: the five most expensive causes by time. */
 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 tick_end (main_red's is the
+ * 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 landing outcomes are owned by the joins below instead: review_error through its
+ * tick'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` tick_end is also error-class but is not in this set, so it stays out of the
+ * `user_aborted` run_end is also error-class but is not in this set, so it stays out of the
  * ranking.) */
 const CLUSTERED_RESULTS = new Set(["error", "aborted", "quiet_killed", "main_red"]);
-/** The newest event for `role` inside a landing attempt's pin→outcome window — the attempt no
+/** The newest event for `role` inside a merge attempt's pin→outcome window — the attempt no
  * 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 vet rebases its pin before the gate). */
+ * sha, is the match, since every verification rebases its pin before the gate). */
 function newestAttemptEvent(eventsByLoop, role, attempt) {
     return (eventsByLoop.get(role) ?? [])
         .filter((e) => e.ts >= attempt.pin.ts && e.ts <= attempt.outcome.ts)
         .at(-1);
 }
-/** The time a `tick_end` attests: its own `durationMs` when it carries one (every event
+/** The pooled cluster key and truncated example a failure-message source's span prices under:
+ * the shared placeholder when the source carries no message, the pooled render
+ * (poolTimeoutKey(normalizeClusterKey)) of the message's cluster — so a review timeout pools
+ * into the same `timed out after <dur>` cause the error-cluster section counts — and the
+ * truncated example the loss-rank cell shows. One copy of the placeholder/pool/truncate chain
+ * so the error-cluster and review-failure causes cannot drift on it (BUGS.md 2026-10-10). */
+function pooledClusterCause(source) {
+    const text = errorTextOrPlaceholder(source);
+    return { key: poolTimeoutKey(normalizeClusterKey(text)), example: truncateExample(text) };
+}
+/** The time a `run_end` attests: its own `durationMs` when it carries one (every event
  * 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
@@ -61,43 +71,46 @@ function tickDurationMs(ev, starts) {
         return own;
     return tickSpanMs(ev, starts) ?? 0;
 }
-/** Add one tick to a {ticks, ms, costUsd} accumulator — the single home of the fold shared
+/** Add one tick 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
  * into both a cell and a draft parses the usage and pairs the span exactly once. */
 function tally(target, durationMs, usage) {
-    target.ticks++;
+    target.runs++;
     target.ms += durationMs;
     target.costUsd += usage.costUsd;
 }
-/** Fold the window's tick_ends into the time-and-spend table and the loss ranking. Pairing
+/** 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
- * in the preceding day and ended in the current one still gets its span. The landing-outcome
- * join runs over that same whole read too (BUGS.md 2026-09-30): a queued tick_end resolves
- * through its own land_queued pin to the later landed/land_failed outcome for the same
- * loop+sha — history-data.ts's exact join — so an authoring tick whose landing was rejected
- * prices into the error-class cell its contract names instead of the landed cell its
- * transient queued result suggested. A landing still in the pipeline, or an outcome event
- * matching no pin, keeps the queued→landed reading: the conservative fallback. */
+ * 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
+ * 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);
-    const emptyCell = () => ({ ticks: 0, ms: 0, costUsd: 0 });
+    const emptyCell = () => ({ runs: 0, ms: 0, costUsd: 0 });
     const byRole = new Map();
     const losses = new Map();
-    // The landing evidence rides history-data.ts's bucketLandingEvents — the same buckets
+    // The merge evidence rides history-data.ts's bucketMergeEvents — the same buckets
     // history's rows read — so the digest's join cannot drift from the rows' join.
-    const { landQueuedByLoop, outcomeByLoop } = bucketLandingEvents(allEvents);
-    const rejectedByLoop = groupBy(allEvents.filter((e) => e.type === "review_rejected"), (e) => e.loop);
-    // A review_error landing kept its pin but left no message on its own land_failed; the
+    const { mergeQueuedByLoop, outcomeByLoop } = bucketMergeEvents(allEvents);
+    const rejectedByLoop = 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
     // the same cluster key the digest's review-failure section already counts.
-    const reviewFailedByLoop = groupBy(allEvents.filter((e) => e.type === "review_failed"), (e) => e.loop);
+    const reviewFailedByLoop = groupBy(allEvents.filter((e) => e.type === "review_failed"), (e) => e.source);
     const deadlineKilledByLoop = groupBy(allEvents.filter((e) => e.type === "build_check" &&
         e.status === "failed" &&
-        (e.scope === "landing" || e.scope === "batch") &&
-        typeof e.timeoutMs === "number"), (e) => e.loop);
-    // Queued tick_ends resolve newest-first so each claims the newest pin at or before its end
+        (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.
     const claimTop = new Map();
@@ -106,7 +119,7 @@ export function timeAndSpend(tickEvents, allEvents) {
         const ev = tickEvents[i];
         if (ev.result !== "queued")
             continue;
-        const joined = resolveQueuedResult(ev, landQueuedByLoop, outcomeByLoop, claimTop, new Map(), null);
+        const joined = resolveQueuedResult(ev, mergeQueuedByLoop, outcomeByLoop, claimTop, new Map(), null);
         if (joined !== null)
             resolved.set(ev, joined);
     }
@@ -127,37 +140,46 @@ export function timeAndSpend(tickEvents, allEvents) {
         const usage = eventUsage(ev);
         const durationMs = tickDurationMs(ev, starts);
         const row = getOrCreate(byRole, role, () => ({
-            landed: emptyCell(),
+            merged: emptyCell(),
             no_change: emptyCell(),
             error: emptyCell(),
         }));
         tally(row[cls], durationMs, usage);
         // Loss causes: a clustered failure's cluster owns its time, a no_change's role does, and
-        // a landing-gate rejection prices its authoring span under a per-role cause of its own —
-        // unrepresentable as an error cluster, since the land_failed event carries no message;
-        // the example is the matching review_rejected's first reason, matched by landing attempt.
+        // a merge-gate rejection prices its authoring span under a per-role cause of its own —
+        // unrepresentable as an error cluster, since the merge_failed event carries no message;
+        // the example is the matching review_rejected's first reason, matched by merge attempt.
         let key = null;
         let kind = "error-cluster";
         let example = "";
-        if (cls === "no_change") {
+        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
+            // 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
+            // refusal's summary the way a review-rejected cause rides its reason.
+            key = `refused\u0000${role}`;
+            kind = "refused";
+            example = typeof ev.summary === "string" ? truncateExample(ev.summary) : "";
+        }
+        else if (cls === "no_change") {
             key = `no_change\u0000${role}`;
             kind = "no_change";
         }
         else if (CLUSTERED_RESULTS.has(String(ev.result))) {
-            // A clustered result with no error text still owns its time: an abort's tick_end never
+            // 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
             // error-clusters section already itemizes rather than dropping the span itemized nowhere.
-            const text = errorTextOrPlaceholder(ev.error);
-            key = poolTimeoutKey(normalizeClusterKey(text));
-            example = truncateExample(text);
+            ({ key, example } = pooledClusterCause(ev.error));
         }
         else if (ev.result === "queued" && resolvedOutcome?.result === "rejected") {
             key = `review-rejected\u0000${role}`;
             kind = "review-rejected";
-            // Match the landing ATTEMPT, not the pin's sha: every vet rebases its pin onto main
+            // Match the merge ATTEMPT, not the pin's sha: every verification rebases its pin onto main
             // before the gate (syncPinToMain), so `review_rejected.head` is the rebased commit while
-            // `land_queued` keeps the authored one — exact-sha equality names no reason for a rebased
+            // `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);
@@ -170,34 +192,32 @@ export function timeAndSpend(tickEvents, allEvents) {
             // message the review-failure section already clusters. Price the authoring span under
             // that cluster's key — a review timeout pools into the shared `timed out after <dur>`
             // cause via poolTimeoutKey — and fall back to the shared placeholder when no event is
-            // visible, so the span is itemized rather than hidden. The match keys on the landing
-            // ATTEMPT, not the pin's sha: every vet rebases its pin onto main before the gate
-            // (syncPinToMain), so `review_failed.head` is the rebased commit while `land_queued`
-            // keeps the authored one — exact-sha equality missed every rebased vet (BUGS.md
+            // visible, so the span is itemized rather than hidden. The match keys on the merge
+            // ATTEMPT, not the pin's sha: every verification rebases its pin onto main before the gate
+            // (syncPinToMain), so `review_failed.head` is the rebased commit while `merge_queued`
+            // 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 text = errorTextOrPlaceholder(failed?.message);
-            key = poolTimeoutKey(normalizeClusterKey(text));
-            example = truncateExample(text);
+            ({ key, example } = pooledClusterCause(failed?.message));
         }
         else if (ev.result === "queued" &&
             (resolvedOutcome?.result === "merge_conflict" || resolvedOutcome?.result === "merge_blocked")) {
-            // The landing failed to merge (a conflict, or a blocked fast-forward/rebase): this
-            // authoring span burned. The `land_failed` event carries no message — writeLandingOutcome
+            // The merge failed to merge (a conflict, or a blocked fast-forward/rebase): this
+            // authoring span burned. The `merge_failed` event carries no message — writeMergeOutcome
             // logs only result/commit/durationMs/usage — so the cause is named by its own result and
-            // takes the shared no-text placeholder, the same fallback a message-less aborted tick_end
+            // takes the shared no-text placeholder, the same fallback a message-less aborted run_end
             // uses, rather than dropping a span the error-class cell already priced (BUGS.md
             // 2026-10-10).
             key = `${resolvedOutcome.result}\u0000${role}`;
             kind = resolvedOutcome.result === "merge_conflict" ? "merge-conflict" : "merge-blocked";
             example = errorTextOrPlaceholder(undefined);
-            // A merge-scope check the harness killed at its own deadline is the fleet's load, not a
+            // 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);
             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 (the harness's own timeout, not a test failure)`;
+                example = `${String(killed.scope)} build check killed at its ${Number(killed.timeoutMs) / 1000}s deadline (tumwater's own timeout, not a test failure)`;
             }
         }
         if (key === null)
@@ -209,7 +229,7 @@ export function timeAndSpend(tickEvents, allEvents) {
                 roles: new Set(),
                 lastSeen: ev.ts,
                 example,
-                ticks: 0,
+                runs: 0,
                 ms: 0,
                 costUsd: 0,
             };
@@ -230,11 +250,11 @@ export function timeAndSpend(tickEvents, allEvents) {
         kind: d.kind,
         roles: sortedRoles(d.roles),
         example: d.example,
-        ticks: d.ticks,
+        runs: d.runs,
         ms: d.ms,
         costUsd: d.costUsd,
     }))
-        .sort((a, b) => b.ms - a.ms || b.ticks - a.ticks || a.example.localeCompare(b.example));
+        .sort((a, b) => b.ms - a.ms || b.runs - a.runs || a.example.localeCompare(b.example));
     const lossCauses = rankedLosses.slice(0, LOSS_TOP);
     return { timeSpend, lossCauses, lossCausesHidden: Math.max(0, rankedLosses.length - LOSS_TOP) };
 }

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

@@ -2,17 +2,29 @@ import fs from "node:fs";
 import path from "node:path";
 import { errCode } from "../errno.js";
 /** The directory-of-timestamped-files queue convention shared by the director's prompt inbox
- * (inbox.ts) and the durable land queue (landing-queue.ts): one file per entry, ordered by
+ * (inbox.ts) and the durable merge queue (merge-queue.ts): one file per entry, ordered by
  * filename across processes and listed by a directory read. Split out because both queues
  * would otherwise carry their own copy of the listing, naming, and ENOENT-tolerant removal
  * rules — exactly the parts that must not drift between the two. */
 /** Every entry file under `dir` whose name ends in `ext`, oldest first by filename sort. A
  * missing directory reads as an empty queue, like every reader in both queues. */
 export function listQueueFiles(dir, ext) {
-    if (!fs.existsSync(dir))
+    let entries;
+    try {
+        entries = fs.readdirSync(dir);
+    }
+    catch (err) {
+        // The "no queue here" cases — a directory removed between the caller's existence check
+        // and this read (ENOENT), or a regular file squatting at the path (ENOTDIR) — read the
+        // same empty list a missing directory does, per the contract. Any other error (EACCES:
+        // a real but unreadable directory) is a genuine failure the caller must see, never a
+        // silently empty queue that would hide queued work.
+        const code = errCode(err);
+        if (code !== "ENOENT" && code !== "ENOTDIR")
+            throw err;
         return [];
-    return fs
-        .readdirSync(dir)
+    }
+    return entries
         .filter((f) => f.endsWith(ext))
         .sort()
         .map((f) => path.join(dir, f));

package/dist/src/files/files.js

@@ -27,9 +27,9 @@ export function statOrNull(file) {
  * plus matching size and, when the caller tracks it, mtime. The one home of the freshness
  * check shared by files/stat-cache.ts's cachedByStat, events/events.ts's appended-shape memo
  * (`mtimeMs` omitted — it decides "our own append left this log clean" from identity and size
- * alone), report/report-data.ts's fold cache, gates/maintenance-quota.ts's window counter,
+ * alone), report/report-fold.ts's fold cache, gates/maintenance-quota.ts's window counter,
  * and failure/failure-data.ts's digest cache. Callers whose cached field is a byte offset
- * rather than a size (report-data, maintenance-quota) pass that offset as `size`, since a
+ * rather than a size (report-fold, maintenance-quota) pass that offset as `size`, since a
  * fully-folded log's offset equals its length. */
 export function sameStatIdentity(st, prev) {
     if (st.dev !== prev.dev || st.ino !== prev.ino || st.size !== prev.size)
@@ -130,6 +130,18 @@ export function unlinkAllMissingTolerant(files) {
 /** The PATH a binary lookup searches by default: the process PATH, or the empty string when
  * it is unset (findOnPath then finds no directories). The one home of the default so every
  * caller that exposes a `pathEnv` override falls back the same way. */
+/** Expand a `~` at the start of a directory against the home dir, for an env var that points
+ * at a subdirectory of home — e.g. `$PI_CODING_AGENT_DIR` (pi-models.ts's piAgentDir) and
+ * `$CLAUDE_CONFIG_DIR` (claude-backend.ts's claudeConfigDir), which share this exact rule. The
+ * empty case is the caller's job (each returns its own default subpath); this helper only maps
+ * the bare `~` → home and `~/x` → home/x, otherwise the literal dir. */
+export function expandHomeTilde(dir, homeDir) {
+    if (dir === "~")
+        return homeDir;
+    if (dir.startsWith("~/"))
+        return path.join(homeDir, dir.slice(2));
+    return dir;
+}
 export function envPath() {
     return process.env.PATH ?? "";
 }
@@ -247,7 +259,7 @@ export function subdirectoryNames(dir, keep) {
  * name carries the pid because several processes can write at once (CLI, TUI, GUI, a loop'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, landing-git.ts's restoreConfigBytes) write through this, so the
+ * (writeBytesAtomic's caller, merge-git.ts's restoreConfigBytes) write through this, so the
  * pid-tmp and no-torn-file contract lives in exactly one place. */
 function writeAtomic(file, data) {
     ensureParentDir(file);
@@ -266,8 +278,8 @@ export function writeTextAtomic(file, text) {
     writeAtomic(file, text);
 }
 /** Write raw `data` bytes to `file` — the byte entry point to writeAtomic's tmp+rename, for
- * writers that must preserve the source bytes exactly (landing-git.ts's restoreConfigBytes
- * writes back the live tumwater.json bytes a landing's merge deleted). */
+ * writers that must preserve the source bytes exactly (merge-git.ts's restoreConfigBytes
+ * writes back the live tumwater.json bytes the merge deleted). */
 export function writeBytesAtomic(file, data) {
     writeAtomic(file, data);
 }
@@ -302,7 +314,7 @@ export function removeTree(dir) {
  * A subdirectory that cannot be listed — without read permission, or removed by a concurrent
  * pass between the parent's readdir and this one — is skipped, the same vanish-tolerant policy
  * the per-file stat/delete below applies. This cleanup runs inside the orchestrator's poll loop
- * (RetentionPruner.poll), so a readdir throw escaping here would end the whole fleet; one
+ * (RetentionPruner.poll), so a readdir throw escaping here would end the whole team; one
  * unreadable session directory must cost at most its own contents' retention pass.
  *
  * After a subdirectory is walked, an empty one whose own mtime is past the cutoff is removed:

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

@@ -16,7 +16,7 @@ export function isJsonObject(value) {
  * when it is an array and [] otherwise — the one home of the "an event/record field is the
  * list or it is nothing" read every formatter applies (event-format.ts's review_rejected
  * reasons, dep_install packages, config_changed keys; src/failure/failure-state-change.ts's
- * config_changed keys; time-spend.ts's review-rejection reasons; fleet-state.ts's paused-roles
+ * config_changed keys; time-spend.ts's review-rejection reasons; team-state.ts's paused-roles
  * list). A torn or hand-edited line
  * never throws and never renders a placeholder: the field reads as absent, and the caller's
  * empty-list branch fires. Foreign entries inside an array are dropped for the same reason —
@@ -38,7 +38,7 @@ export function stringList(value) {
  * 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);
- * fleet/orchestrator-info.ts's isFiniteNumber (v → undefined); fleet/fleet-state.ts's
+ * team/orchestrator-info.ts's isFiniteNumber (v → undefined); team/team-state.ts's
  * standingMarker, pausedRoles, and standingRolesUntil (until → undefined);
  * operator/operator-requests.ts's consumeWakeRequest (notBeforeMs → undefined);
  * git/slots-state.ts's readSlotRecord (pinnedAt, lastReleasedAt → null); git/worktree-use.ts's
@@ -60,7 +60,7 @@ export function finiteNumber(value, fallback) {
  * previous context, output and its peak floor → 0), time-spend.ts's tickDurationMs (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), landing/landing-queue.ts's isLandingEntry (tick, enqueuedAt,
+ * (tokens, contextWindow → null), merge/merge-queue.ts's isMergeEntry (tick, 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,3 +92,18 @@ export function parseJsonObject(text) {
 export function objectOrEmpty(value) {
     return isJsonObject(value) ? value : {};
 }
+/** 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
+ * `totalTokens` sum and the `cost.total` envelope cannot drift between backends. The wire-
+ * specific field-name reads stay in each translator; this owns only the identical assembly. */
+export function canonicalUsageBlock(input, cacheRead, cacheWrite, output, costTotal) {
+    return {
+        input,
+        cacheRead,
+        cacheWrite,
+        output,
+        totalTokens: input + cacheRead + cacheWrite + output,
+        cost: { total: costTotal },
+    };
+}

package/dist/src/files/tail.js

@@ -17,7 +17,7 @@ import { piLogPath } from "../paths.js";
  * re-read next poll once its writer has written the newline instead of being parsed torn
  * or lost. The tail primitives here build on it (withTail, followFile); outside this
  * module it is called directly by src/ui/progress-data.ts, src/ui/transcript-tail.ts, and
- * the report fold in src/report/report-data.ts. */
+ * the report fold in src/report/report-fold.ts. */
 export function readCompleteLines(file, offset, size) {
     const len = size - offset;
     if (len <= 0)

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

@@ -1,3 +1,4 @@
+// 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,
@@ -13,7 +14,7 @@
  * may let a later poll retry. Removing `bootstrap` from config (live
  * reload) also ends it, without a latch. Both the latch write and the completion event are
  * best-effort, like every sibling gate: the poll runs inside the orchestrator's catch-less
- * loop, so an unwritable repo must degrade (the hold still lifts) rather than end the fleet.
+ * loop, so an unwritable repo must degrade (the hold still lifts) rather than end the team.
  *
  * Shape, like every gate in the family (src/gates/gate-polls.ts): the read-only verdict (and
  * the pure hold predicate) is separated from the edge-triggered bookkeeping so both the
@@ -24,7 +25,7 @@ import fs from "node:fs";
 import { donePlans, openBugs } from "../backlog/backlog.js";
 import { bootstrapLatchPath } from "../paths.js";
 import { writeJsonAtomic } from "../files/json-files.js";
-import { logEventBestEffort } from "../events/events.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";
@@ -76,10 +77,10 @@ export function pollBootstrapGate(root, state, runners, config, now) {
             catch (err) {
                 // A terminal boundary: the error can name a path carrying control characters. Sanitize
                 // like cli-output's say()/fail(), so the fallback line cannot drive the operator's shell.
-                process.stderr.write(`tumwater: harness: could not write bootstrap latch: ${stripTerminalControls(errorMessage(err))}\n`);
+                process.stderr.write(`tumwater: could not write bootstrap latch: ${stripTerminalControls(errorMessage(err))}\n`);
             }
             logEventBestEffort(root, {
-                loop: "harness",
+                source: TUMWATER_SOURCE,
                 type: "bootstrap_complete",
                 plansDone: status.plansDone,
                 untilPlansDone: status.untilPlansDone,