tumwater 0.1.2 → 0.2.0

package/dist/src/build/build-check-scoped.js

@@ -1,37 +1,35 @@
 import { BUILD_CHECK_TIMEOUT_MS, detectBuildCheck, gateCommandOf, } from "./build-check-detect.js";
 import { runBuildCheck, checkScriptName, checkTimeoutMs, } from "./build-check.js";
 import { logEventBestEffort, warnEventBestEffort } from "../events/events.js";
-import { MERGE_SCOPES, SCOPE_WORDS, buildCheckEvent, buildCheckSkipWarning, owesCleanRetry, installFailedPhrase, killedPhrase, loadedHostPhrase, timedOutPhrase, DEADLINE_LATE_TOLERANCE_MS, SLEEP_SPAN_TOLERANCE_MS, sleptPhrase, starvedDeadlineMs, UNVERIFIED_TREE, } from "./build-check-events.js";
+import { MERGE_SCOPES, SCOPE_WORDS, buildCheckEvent, buildCheckSkipWarning, runWithCleanRetry, installFailedPhrase, killedPhrase, loadedHostPhrase, timedOutPhrase, DEADLINE_LATE_TOLERANCE_MS, SLEEP_SPAN_TOLERANCE_MS, sleptPhrase, starvedDeadlineMs, UNVERIFIED_TREE, } from "./build-check-events.js";
 import { CHECK_TIER, withCheckPermit } from "../concurrency/check-permit.js";
 import { sampleHostLoad, sampleSleepClock } from "./host-sleep.js";
 import { npmInstall } from "./dep-install.js";
-/** Run the project's declared check for a named scope — the detect → run → build_check
- * event → skip-warning sequence the review gate's pre-check (scope "gate"), the landing
- * path's in-lock re-check (scope "landing"), and the batch lander's one check over the whole
- * stacked tree (scope "batch") previously each ran inline, kept in one place so
- * the event's shape and the skip warning cannot drift between them. Split out of
- * build-check.ts — which keeps the check's execution and outcome classification
- * (runBuildCheck, BuildCheckOutcome) — because orchestration is its own concern: the permit,
- * the event emission, the verdict-less retry, the merge-scope unverified remapping, and the
- * skip warning. Every run is an event with its cost: the deterministic checks are where the
- * fleet's compute goes after the authoring run, and "how long does npm test take per merge"
- * must be answerable from the feed, not by timing it by hand. Returns null when no check is
+/** Run the project's declared check for a named scope — the detect → run → build_check event →
+ * skip-warning sequence the review gate's pre-check (scope "gate"), the merge path's in-lock
+ * re-check (scope "merge"), and the batch merger's one check over the whole stacked tree (scope
+ * "batch") previously each ran inline, kept in one place so the event's shape and the skip warning
+ * cannot drift between them. Split out of build-check.ts — which keeps the check's execution and
+ * outcome classification (runBuildCheck, BuildCheckOutcome) — because orchestration is its own
+ * concern: the permit, the event emission, the verdict-less retry, the merge-scope unverified
+ * remapping, and the skip warning. Every run is an event with its cost: the deterministic checks
+ * are where the team's compute goes after the authoring run, and "how long does npm test take per
+ * merge" must be answerable from the feed, not by timing it by hand. Returns null when no check is
  * declared (nothing to run — the caller passes, exactly as before this split), otherwise the
- * declared check plus its classified outcome. A "skipped" outcome also logs its standard
- * warning here (wording keyed on the scope, the timeout as actually set — and, when its
- * deadline fired late, as actually enforced); "failed" and "passed" are the caller's to
- * decide (deterministic reject vs. verifiedHead / baseline seeding). A timeout or signal kill
- * at a merge scope is remapped to a deterministic "failed" — the tree is unverified, so it
- * must not land. A check killed by a signal the harness did not send is retried once at any
- * scope — the first run's death says nothing about the tree (it is another run's `pkill`), so
- * one verdict from a clean attempt is owed before the skip is honored; a timeout whose deadline
- * demonstrably fired late (the harness's own host-sleep evidence) earns that same one retry at
- * any scope, and a failed run the host slept through does too; each attempt is priced
- * as its own build_check event, carrying when the check itself ran (buildCheckRunFields).
- * A configured `check.gateCommand` replaces the command at scope "gate" only (same cwd and
- * timeout); the landing and batch scopes — and the red-main baseline, which detects on its
- * own — keep running check.command. `permitWait` hears about a wait for the check permit (the
- * landing cell's "waiting for a check slot"). Never throws. */
+ * declared check plus its classified outcome. A "skipped" outcome also logs its standard warning
+ * here (wording keyed on the scope, the timeout as actually set — and, when its deadline fired
+ * late, as actually enforced); "failed" and "passed" are the caller's to decide (deterministic
+ * reject vs. verifiedHead / baseline seeding). A timeout or signal kill at a merge scope is
+ * remapped to a deterministic "failed" — the tree is unverified, so it must not merge. A check
+ * killed by a signal the harness did not send is retried once at any scope — the first run's death
+ * says nothing about the tree (it is another run's `pkill`), so one verdict from a clean attempt is
+ * owed before the skip is honored; a timeout whose deadline demonstrably fired late (the harness's
+ * own host-sleep evidence) earns that same one retry at any scope, and a failed run the host slept
+ * through does too; each attempt is priced as its own build_check event, carrying when the check
+ * itself ran (buildCheckRunFields). A configured `check.gateCommand` replaces the command at scope
+ * "gate" only (same cwd and timeout); the merge and batch scopes — and the red-main baseline, which
+ * detects on its own — keep running check.command. `permitWait` hears about a wait for the check
+ * permit (the merge cell's "waiting for a check slot"). Never throws. */
 export async function runScopedBuildCheck(root, role, scope, wt, config, timeoutMs = BUILD_CHECK_TIMEOUT_MS, sampleSleep = sampleSleepClock, install = npmInstall, permitWait, sampleLoad = sampleHostLoad) {
     const gateCommand = scope === "gate" ? gateCommandOf(config) : undefined;
     const check = detectBuildCheck(wt, gateCommand === undefined ? config : { check: { ...config?.check, command: gateCommand } });
@@ -41,7 +39,7 @@ export async function runScopedBuildCheck(root, role, scope, wt, config, timeout
     // caller's bound. Effective here so the reason text and the skip warning agree with what
     // runBuildCheck enforced.
     // A merge scope under a starved host gets a longer deadline (starvedDeadlineMs): the check
-    // runs as long as the fleet's load stretches it, and a kill at the unstretched bound would
+    // runs as long as the team's load stretches it, and a kill at the unstretched bound would
     // only measure the load (BUGS.md 2026-10-12). The load sampled here is also what the
     // unverified reason names.
     const load = sampleLoad();
@@ -53,42 +51,33 @@ export async function runScopedBuildCheck(root, role, scope, wt, config, timeout
     // holds); durationMs prices the run itself, not the wait for a permit.
     let durationMs = 0;
     const raw = await withCheckPermit(config, MERGE_SCOPES.has(scope) ? CHECK_TIER.merge : CHECK_TIER.other, async () => {
-        const startedAt = Date.now();
-        const first = await runBuildCheck(wt, runCheck, timeoutMs, undefined, sampleSleep, install);
-        durationMs = Date.now() - startedAt;
-        // A check the harness did not stop itself says nothing about the tree — its death is
-        // another run's doing. A timeout whose deadline demonstrably fired late is the same
-        // weather: the harness's own evidence (run.deadlineLateMs, the measurement BUGS.md
-        // 2026-09-21 added) says the deadline passed while the host slept or the harness
-        // stalled, so the check ran seconds and was killed at a wake — it made no verdict about
-        // the tree and was not a slow suite. At every scope it owes one retry from a clean
-        // attempt; the second attempt's outcome stands. The verdict-less first attempt is priced
-        // as its own event (the feed must answer how long a check took), then the final event
-        // below records the retry's classified outcome.
-        if (!owesCleanRetry(first))
-            return first;
-        logEventBestEffort(root, buildCheckEvent(role, scope, first, durationMs));
-        const retryStart = Date.now();
-        const retry = await runBuildCheck(wt, runCheck, timeoutMs, undefined, sampleSleep, install);
-        durationMs = Date.now() - retryStart;
-        return retry;
+        // One permit covers both attempts (the killed-check retry re-runs under the permit it
+        // holds); durationMs prices the run itself, not the wait for a permit. A check the
+        // harness did not stop itself says nothing about the tree; a timeout whose deadline
+        // demonstrably fired late, and a failed run the host slept through, are the same weather
+        // — at every scope each owes one retry from a clean attempt, and the second attempt's
+        // outcome stands (runWithCleanRetry). The verdict-less first attempt is priced as its own
+        // event (the feed must answer how long a check took), then the final event below records
+        // the retry's classified outcome.
+        const { outcome, durationMs: d } = await runWithCleanRetry(() => runBuildCheck(wt, runCheck, timeoutMs, undefined, sampleSleep, install), (first, dur) => logEventBestEffort(root, buildCheckEvent(role, scope, first, dur)));
+        durationMs = d;
+        return outcome;
     }, permitWait);
-    // A signal kill at a merge scope, or a timeout whose deadline fired on time (real slowness,
-    // a genuinely hung or oversized suite), made no verdict about the tree — and this is the
-    // check whose whole job is to catch a semantic conflict before it lands, so it rejects
-    // deterministically — the author keeps its commit and retries. A timeout whose deadline
-    // fired late has already had its retry above: the lateness is the harness's own evidence the
-    // host slept, so a second verdict-less attempt is recorded as unverified rather than read
-    // again as weather (BUGS.md 2026-09-28). no-npm and a broken toolchain still say nothing
-    // about the tree, and the gate scope still proceeds to the model reviewer, which the landing
-    // path's own check backs up.
-    // A retry that ALSO slept made no clean verdict either: it is recorded as unverified — not
+    // A signal kill at a merge scope, or a timeout whose deadline fired on time (real slowness, a
+    // genuinely hung or oversized suite), made no verdict about the tree — and this is the check
+    // whose whole job is to catch a semantic conflict before it merges, so it rejects
+    // deterministically — the author keeps its commit and retries. A timeout whose deadline fired
+    // late has already had its retry above: the lateness is the harness's own evidence the host
+    // slept, so a second verdict-less attempt is recorded as unverified rather than read again as
+    // weather (BUGS.md 2026-09-28). no-npm and a broken toolchain still say nothing about the tree,
+    // and the gate scope still proceeds to the model reviewer, which the merge path's own check backs
+    // up. A retry that ALSO slept made no clean verdict either: it is recorded as unverified — not
     // attributed to the change, not cached as a red baseline — rather than read as a second
-    // deterministic failure (BUGS.md 2026-09-30). A retry that passed stands: the tree went
-    // green under the project's own check, even if the host napped through parts of it.
+    // deterministic failure (BUGS.md 2026-09-30). A retry that passed stands: the tree went green
+    // under the project's own check, even if the host napped through parts of it.
     const sleepFailed = raw.status === "failed" && (raw.run?.sleptMs ?? 0) > SLEEP_SPAN_TOLERANCE_MS;
-    // A failed dependency install is the same at a merge scope: nothing ran against the tree as
-    // its lockfile pins it, so it must not land (BUGS.md 2026-10-01).
+    // A failed dependency install is the same at a merge scope: nothing ran against the tree as its
+    // lockfile pins it, so it must not merge (BUGS.md 2026-10-01).
     const unverifiedSkip = MERGE_SCOPES.has(scope) &&
         (((raw.status === "skipped" &&
             (raw.skipReason === "timeout" || raw.skipReason === "killed" || raw.skipReason === "install")) ||
@@ -101,7 +90,7 @@ export async function runScopedBuildCheck(root, role, scope, wt, config, timeout
                 ? sleptPhrase(SCOPE_WORDS[scope].label, raw.run.sleptMs, UNVERIFIED_TREE)
                 : `${SCOPE_WORDS[scope].label} ${timedOutPhrase(effectiveMs, raw.run)}; ${UNVERIFIED_TREE}${
                 // An on-time kill (the late-deadline wording already names its own cause) names the
-                // starved host when the load average says the fleet was the check's competition.
+                // starved host when the load average says the team was the check's competition.
                 (raw.run?.deadlineLateMs ?? 0) > DEADLINE_LATE_TOLERANCE_MS ? "" : loadedHostPhrase(load)}`;
     const outcome = unverifiedSkip
         ? {

package/dist/src/build/build-check.js

@@ -41,10 +41,11 @@ const TOOLCHAIN_ERROR_PATTERNS = [
 function toolchainErrorInOutput(output) {
     return TOOLCHAIN_ERROR_PATTERNS.some((p) => p.test(output));
 }
-/** The timeout a check actually runs under: `check.timeoutSeconds` when configured (detectBuildCheck
- * carries it as timeoutMs on both kinds), else a configured command's built-in 300 s and an npm
- * check's caller-given bound. One resolution so the run, the event, and the skip warning cannot
- * disagree.
+/** The timeout a check actually runs under: `check.timeoutSeconds` when configured
+ * (detectBuildCheck carries it as timeoutMs on both kinds), else a configured command's
+ * built-in 300 s and an npm check's caller-given bound. One resolution so the run, the event,
+ * and the skip warning
+ * cannot disagree.
  *
  * checkTimeoutMs and checkScriptName are both shared with build-check-scoped.ts's
  * runScopedBuildCheck, whose reason text and event must agree with what runBuildCheck
@@ -81,16 +82,16 @@ export async function runBuildCheck(wt, check, timeoutMs = BUILD_CHECK_TIMEOUT_M
     if ((await probeToolchain()) === "broken") {
         return { status: "skipped", script, skipReason: "toolchain" };
     }
-    // A tree whose lockfile pins direct dependencies the walk-up does not resolve (a change that
-    // adds or bumps one — node_modules is gitignored, so the worktree resolves through a root
-    // install that predates it) is installed first, into the tree itself: without it the check
-    // fails TS2307 on a correct change and rejects it before any reviewer sees it (BUGS.md
-    // 2026-10-01). An npm check only — a configured command owns its own environment. A failed
-    // install made no verdict about the tree; runScopedBuildCheck treats it as unverified at the
-    // merge scopes, so an uninstallable tree never lands. Never answer a missing dependency by
-    // skipping instead (classifying a `Cannot find module` failure as environmental): that was
-    // tried and reverted twice on 2026-10-01 by the user's decision — see BUGS.md's "Do not
-    // reintroduce a missing-install skip" note for why it switches the gate off fleet-wide.
+    // A tree whose lockfile pins direct dependencies the walk-up does not resolve (a change that adds
+    // or bumps one — node_modules is gitignored, so the worktree resolves through a root install that
+    // predates it) is installed first, into the tree itself: without it the check fails TS2307 on a
+    // correct change and rejects it before any reviewer sees it (BUGS.md 2026-10-01). An npm check
+    // only — a configured command owns its own environment. A failed install made no verdict about
+    // the tree; runScopedBuildCheck treats it as unverified at the merge scopes, so an uninstallable
+    // tree never merges. Never answer a missing dependency by skipping instead (classifying a `Cannot
+    // find module` failure as environmental): that was tried and reverted twice on 2026-10-01 by the
+    // user's decision — see BUGS.md's "Do not reintroduce a missing-install skip" note for why it
+    // switches the gate off team-wide.
     let installed;
     if (check.kind === "npm") {
         const r = await syncInstall(wt, install);

package/dist/src/build/build-info.js

@@ -1,3 +1,4 @@
+// vocabulary: plain
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { gitTry } from "../git/git-run.js";
@@ -40,7 +41,7 @@ export async function stampBuild(root, dist, sha) {
     const info = { sha: head, builtAt: Date.now(), root: path.resolve(root) };
     // Atomic: a process killed mid-write (a redeploy swap, a timeout-killed `npm test`) would
     // otherwise leave a torn stamp, and readBuildInfo reads that as no provenance at all —
-    // createRedeployer then returns null and the fleet never self-redeploys onto newer main,
+    // createRedeployer then returns null and the team never self-redeploys onto newer main,
     // the exact blind spot the stamp exists to close.
     writeJsonAtomic(buildInfoPath(dist), info);
     return info;

package/dist/src/build/build-stage.js

@@ -1,3 +1,4 @@
+// vocabulary: plain
 import fs from "node:fs";
 import path from "node:path";
 import { distDir, stampBuild } from "./build-info.js";
@@ -6,7 +7,7 @@ import { resolveFromNodeModules } from "./build-check-detect.js";
 import { ensureDir, removeTree } from "../files/files.js";
 import { stagingDir, stagingRootDir } from "../paths.js";
 import { execFileAsync } from "../process/process.js";
-import { warnEvent, warnEventBestEffort } from "../events/events.js";
+import { warnEvent, warnEventBestEffort, TUMWATER_SOURCE } from "../events/events.js";
 import { errorMessage } from "../text/text.js";
 import { shortSha } from "../text/format.js";
 /** Producing and swapping the compiled tree behind a self-redeploy (redeploy.ts): compile a
@@ -16,14 +17,14 @@ import { shortSha } from "../text/format.js";
  * reads without the staging and rename detail. Split out of redeploy.ts for that reason. */
 /** Hard cap on one compile of the harness; tsc on this codebase takes well under a minute. */
 const COMPILE_TIMEOUT_MS = 5 * 60_000;
-/** How old a superseded staged build may get before a later compile deletes it. A completed
- * compile stays consumable for one episode's tail — the drain hold is capped at
- * RESTART_DRAIN_MAX_MS (30 min) — so anything older than this grace cannot be swapped by any
- * live episode and is pure disk: a fleet whose restarts stay blocked (red main, a failing boot
- * gate) recompiles every new head it lands, and without a prune each landed commit left a full
- * staged tree behind until the NEXT successful swap cleaned them all up — ~750 MB across one
- * busy day (observed 2026-09-30: 128 staged builds, none swapped). A successful swap already
- * wipes every staging; this bounds the accumulation between swaps. */
+/** How old a superseded staged build may get before a later compile deletes it. A completed compile
+ * stays consumable for one episode's tail — the drain hold is capped at RESTART_DRAIN_MAX_MS (30
+ * min) — so anything older than this grace cannot be swapped by any live episode and is pure disk:
+ * a team whose restarts stay blocked (red main, a failing boot gate) recompiles every new head it
+ * merges, and without a prune each merged commit left a full staged tree behind until the NEXT
+ * successful swap cleaned them all up — ~750 MB across one busy day (observed 2026-09-30: 128
+ * staged builds, none swapped). A successful swap already wipes every staging; this bounds the
+ * accumulation between swaps. */
 export const STAGED_PRUNE_AFTER_MS = 45 * 60_000;
 /** Delete staged builds other than `keep` that no live episode can still swap: directories
  * named for a head (40-hex SHA) whose mtime is older than STAGED_PRUNE_AFTER_MS. Everything
@@ -79,7 +80,7 @@ function rejectedCompile(detail) {
  * ancestor node_modules, and the mirror lives under <root>/.tumwater/. The compiler itself is
  * found the same way (resolveFromNodeModules): a checkout that never ran `npm install` — every
  * tumwater worktree — still has the install of an ancestor to borrow, and demanding a local one
- * is what left the fleet unable to rebuild itself on 2026-09-08 (BUGS.md). Never throws. */
+ * is what left the team unable to rebuild itself on 2026-09-08 (BUGS.md). Never throws. */
 export async function compileStaged(root, mirrorWt, mainHead, timeoutMs = COMPILE_TIMEOUT_MS, 
 /** Test seam: the node binary the primary spawn runs tsc under. Production always uses
  * process.execPath; a test injects a stale path to reproduce an interpreter an upgrade
@@ -109,7 +110,7 @@ execPath = process.execPath) {
         // 2026-09-29) into a diagnosis instead of a mystery.
         const missing = missingSpawnInputs(execPath, mirrorWt, tsc);
         // The one spawn failure a retry can beat: the running build's own node binary vanished
-        // under it (an upgrade while the fleet stays up leaves process.execPath naming a file that
+        // under it (an upgrade while the team stays up leaves process.execPath naming a file that
         // no longer exists, while every PATH-resolved spawn — git, npm, pi — keeps working). tsc's
         // own shebang resolves a live node through PATH at spawn time, so run it directly.
         if (fs.existsSync(execPath) || !fs.existsSync(mirrorWt))
@@ -128,13 +129,13 @@ execPath = process.execPath) {
     const stamped = await stampBuild(root, staged, mainHead);
     if (stamped)
         pruneStaleStagings(root, staged); // Superseded stagings die with the new build's success.
-    return stamped ? { ok: true, detail: "" } : { ok: false, detail: "could not stamp the compiled build" };
+    return stamped ? { ok: true, detail: "" } : { ok: false, detail: "could not stamp the compiled update" };
 }
 /** Classify one failed compile spawn into its terminal CompileResult, or null when the error
  * carries no exit at all — a spawn failure the caller still has to diagnose. Shared by the
  * primary and shebang-fallback spawns so the two classification ladders cannot drift: a
  * numeric exit code is the one shape that is a verdict about the tree (tsc ran and chose it),
- * so latching anything else as a verdict pins the fleet on the stale build even after the
+ * so latching anything else as a verdict pins the team on the stale build even after the
  * environment recovers (BUGS.md 2026-09-28), and misclassifying a real exit as a rejection
  * makes the redeployer drop a genuinely failing head and re-attempt it forever instead of
  * blocking on it (review objection 2026-09-29). A timeout (killed) and a death by signal are
@@ -173,7 +174,7 @@ function missingSpawnInputs(execPath, cwd, tsc) {
 export function swapDist(root, dist, mainHead) {
     const staged = stagingDir(root, mainHead);
     if (!fs.existsSync(staged))
-        throw new Error(`no staged build for ${shortSha(mainHead)}`);
+        throw new Error(`no staged update for ${shortSha(mainHead)}`);
     const prev = path.join(stagingRootDir(root), "dist.prev");
     removeTree(prev);
     const hadDist = fs.existsSync(dist);
@@ -190,21 +191,21 @@ export function swapDist(root, dist, mainHead) {
             catch (restoreErr) {
                 // A restore failure leaves dist/ MISSING — the operator must hear that plus where
                 // the old build sits, not just the raw ENOENT/ENOSPC of whichever rename lost.
-                throw new Error(`could not restore the previous dist after a failed build swap for ${shortSha(mainHead)}` +
-                    `: ${errorMessage(err)}; dist is missing and the old build is preserved at ${prev}` +
+                throw new Error(`could not restore the previous dist after a failed update swap for ${shortSha(mainHead)}` +
+                    `: ${errorMessage(err)}; dist is missing and the old update is preserved at ${prev}` +
                     ` (restore failed: ${errorMessage(restoreErr)})`);
             }
         }
         // The raw error alone ("ENOTDIR", "EACCES") never says which move failed or which
         // staged build was lost: name the head and the dist path the swap was serving.
-        throw new Error(`could not move the staged build for ${shortSha(mainHead)} into ${dist}: ${errorMessage(err)}`);
+        throw new Error(`could not move the staged update for ${shortSha(mainHead)} into ${dist}: ${errorMessage(err)}`);
     }
     // The swap is committed: the rename above put the new build at dist/. Everything below is
     // cleanup of superseded trees — the old build stepped aside at dist.prev, and the stagings
     // of heads that moved on before their own swap. It is dead weight a later swap or compile
     // collects, so a removal that fails (a directory surviving removeTree's retries, an
     // unreadable staging root) must not be reported as a failed swap: the redeployer would
-    // block the restart while dist/ already holds the new build, leaving the fleet running the
+    // block the restart while dist/ already holds the new build, leaving the team running the
     // old code under a misleading `restart BLOCKED: swapping the new build into place failed`.
     // Warn and continue, the same best-effort policy pruneStaleStagings applies so pruning
     // never fails the work it follows.
@@ -244,10 +245,10 @@ export function recoverInterruptedSwap(root, dist) {
 export function repairInterruptedSwap(root, dist = distDir()) {
     try {
         if (recoverInterruptedSwap(root, dist))
-            warnEventBestEffort(root, "harness", "an interrupted build swap left dist/ missing — restored it from .tumwater/build/dist.prev");
+            warnEventBestEffort(root, TUMWATER_SOURCE, "an interrupted update swap left dist/ missing — restored it from .tumwater/build/dist.prev");
     }
     catch (err) {
-        warnEventBestEffort(root, "harness", `dist/ is missing after an interrupted build swap and could not be restored from .tumwater/build/dist.prev: ${errorMessage(err)}`);
+        warnEventBestEffort(root, TUMWATER_SOURCE, `dist/ is missing after an interrupted update swap and could not be restored from .tumwater/build/dist.prev: ${errorMessage(err)}`);
     }
 }
 /** Remove one post-swap leftover tree, warning instead of throwing: the swap is already
@@ -257,7 +258,7 @@ function removeSupersededQuiet(root, dir) {
         removeTree(dir);
     }
     catch (err) {
-        warnCleanup(root, `could not remove superseded build tree ${dir}: ${errorMessage(err)}`);
+        warnCleanup(root, `could not remove superseded update tree ${dir}: ${errorMessage(err)}`);
     }
 }
 /** Best-effort sweep of the staging root after a successful swap: every directory left there
@@ -282,7 +283,7 @@ function sweepSupersededStagings(root) {
  * event log is unwritable too, the new dist/ is already in place and stays the outcome. */
 function warnCleanup(root, message) {
     try {
-        warnEvent(root, "harness", message);
+        warnEvent(root, TUMWATER_SOURCE, message);
     }
     catch {
         // Cleanup must not throw; the swap already succeeded.

package/dist/src/build/dep-install.js

@@ -1,3 +1,4 @@
+// vocabulary: plain
 import path from "node:path";
 import { resolveFromNodeModules } from "./build-check-detect.js";
 import { readJsonFile } from "../files/json-files.js";
@@ -6,14 +7,14 @@ import { KILL_GRACE_MS, runScriptGroup } from "../process/process-group.js";
 import { logEventBestEffort, warnEventBestEffort } from "../events/events.js";
 import { errorMessage } from "../text/text.js";
 /** Keeping a tree's install in step with its lockfile (BUGS.md 2026-10-01). node_modules is
- * gitignored, so a tumwater worktree has none of its own: its toolchain and every import
- * resolve by walking UP to the root checkout's install (detectBuildCheck,
- * resolveFromNodeModules). That install predates any dependency a change adds, and no loop ever
- * ran `npm install` — so a legitimate dependency-adding change failed its gate check with
- * TS2307 every time, and had it landed, every tree after it would have resolved against a root
- * install missing the package. Two callers close both halves: runBuildCheck installs into the
- * checked tree when its lockfile's direct dependencies are not what the walk-up resolves, and
- * the landing path re-syncs the root checkout after a fast-forward moves main's lockfile. */
+ * gitignored, so a tumwater worktree has none of its own: its toolchain and every import resolve by
+ * walking UP to the root checkout's install (detectBuildCheck, resolveFromNodeModules). That
+ * install predates any dependency a change adds, and no loop ever ran `npm install` — so a
+ * legitimate dependency-adding change failed its gate check with TS2307 every time, and had it
+ * merged, every tree after it would have resolved against a root install missing the package. Two
+ * callers close both halves: runBuildCheck installs into the checked tree when its lockfile's
+ * direct dependencies are not what the walk-up resolves, and the merge path re-syncs the root
+ * checkout after a fast-forward moves main's lockfile. */
 /** Hard cap on one install run — a registry fetch of a handful of packages takes seconds; the
  * cap only bounds a hung network. Same bound as the check itself. */
 const DEP_INSTALL_TIMEOUT_MS = 300_000;
@@ -53,7 +54,7 @@ function installedVersion(dir, name) {
 /** The production installer: `npm install` in `dir` from its own lockfile, run as a process
  * group under the timeout. `--no-save` keeps package.json and package-lock.json byte-identical,
  * so neither a worktree nor the root checkout goes dirty. Not `npm ci`: ci deletes node_modules
- * first, and at the root that is the install every in-flight check of a live fleet resolves
+ * first, and at the root that is the install every in-flight check of a live team resolves
  * through. `--ignore-scripts` runs no package's (or the project's own) lifecycle scripts inside
  * the harness. */
 export const npmInstall = async (dir, timeoutMs) => {
@@ -91,22 +92,22 @@ export async function syncInstall(dir, install = npmInstall, timeoutMs = DEP_INS
     return { packages, ok: true, durationMs };
 }
 /** Re-sync the root checkout's install after a fast-forward moved main's lockfile (BUGS.md
- * 2026-10-01). Every fleet worktree, the redeploy compile, and the running harness resolve
- * through `root/node_modules`, so a landed dependency the root never installed would leave each
- * of them resolving against the old tree. Called under the merge lock right after the ff, so
- * the next landing's in-lock check already sees it. A `dep_install` event prices a run; a
- * failure also warns, and is retried by the next landing's call (the drift is still there) —
- * meanwhile each check installs into its own tree, so nothing is rejected for it. No drift (the
- * common case — the landing did not touch dependencies) spawns nothing and logs nothing. */
+ * 2026-10-01). Every team worktree, the redeploy compile, and the running harness resolve through
+ * `root/node_modules`, so a merged dependency the root never installed would leave each of them
+ * resolving against the old tree. Called under the merge lock right after the ff, so the next
+ * merge's in-lock check already sees it. A `dep_install` event prices a run; a failure also warns,
+ * and is retried by the next merge's call (the drift is still there) — meanwhile each check
+ * installs into its own tree, so nothing is rejected for it. No drift (the common case — the merge
+ * did not touch dependencies) spawns nothing and logs nothing. */
 export async function syncRootInstall(root, role, install = npmInstall) {
     const r = await syncInstall(root, install);
     if (!r)
         return;
-    // Best-effort: the root install already ran and the ff that prompted it already moved main,
-    // so an unwritable feed must not reject the landing that awaited this (landing-merge.ts's
-    // tryMerge, landing-stack.ts's ffStackToMain).
+    // Best-effort: the root install already ran and the ff that prompted it already moved main, so an
+    // unwritable feed must not reject the merge that awaited this (merge-to-main.ts's tryMerge,
+    // merge-stack.ts's ffStackToMain).
     logEventBestEffort(root, {
-        loop: role,
+        source: role,
         type: "dep_install",
         packages: r.packages,
         status: r.ok ? "passed" : "failed",
@@ -114,5 +115,5 @@ export async function syncRootInstall(root, role, install = npmInstall) {
         ...(r.detail ? { error: r.detail } : {}),
     });
     if (!r.ok)
-        warnEventBestEffort(root, role, `the root install did not pick up main's dependencies (${r.packages.join(", ")})${r.detail ? `: ${r.detail}` : ""}; checks install into their own trees until a later landing re-syncs it`);
+        warnEventBestEffort(root, role, `the root install did not pick up main's dependencies (${r.packages.join(", ")})${r.detail ? `: ${r.detail}` : ""}; checks install into their own trees until a later merge re-syncs it`);
 }

package/dist/src/build/host-sleep.js

@@ -1,5 +1,5 @@
 /** Measured host sleep inside a time window — the evidence that lets the harness tell "the
- * build failed" from "the host was asleep while the build ran". The fleet's host is a laptop
+ * build failed" from "the host was asleep while the build ran". The team's host is a laptop
  * in clamshell maintenance sleep (BUGS.md 2026-09-21 logged 569 sleeps over three days), and
  * a sleep shorter than a check's remaining deadline but longer than a test's own wall-clock
  * wait expires that wait at the next wake: the suite exits nonzero INSIDE the deadline, so

package/dist/src/change/change-data.js

@@ -1,13 +1,13 @@
 /** The collector behind `tumwater diff --role <id>`: what change a loop holds between its commit
- * and its merge. The committed half is the loop branch's unlanded work (commits ahead of the
- * fleet's main branch, with the patch); the uncommitted half is the loop worktree's dirty state.
+ * and its merge. The committed half is the loop branch's unmerged work (commits ahead of the
+ * team's main branch, with the patch); the uncommitted half is the loop worktree's dirty state.
  * Everything is read-only git plumbing already used elsewhere — this module only wires the pieces
- * into one operator view, degrading like `report` does when the fleet (or just this role's
+ * into one operator view, degrading like `report` does when the team (or just this role's
  * worktree) does not exist yet. Lives beside the other collectors (src/report/report-data.ts,
  * history-data.ts, status/status-data.ts); the terminal rendering of these views is
  * change-render.ts's half. */
 import { knownRoleIdsCached, loadConfigSafe } from "../config/config.js";
-import { aheadOfMain, branchExists, currentBranch, targetBranch } from "../git/git.js";
+import { aheadOfMain, branchExists, countCommitsInRange, currentBranch, targetBranch } from "../git/git.js";
 import { gitTry } from "../git/git-run.js";
 import { aheadOfMainDiff, changedFiles } from "../git/git-diff.js";
 import { branchName } from "../paths.js";
@@ -17,14 +17,14 @@ import { roleWorktreeDir } from "../git/slots-state.js";
  * order — disabled roles included, since a loop stopped mid-flight still holds its branch).
  * Each entry goes through collectRoleChange, which keeps the absent/no-base degradation
  * logic single-homed and only computes the patch git-diffs for roles actually holding work
- * (both are "" when a role holds nothing); the fleet view then drops the patch fields. */
-export async function collectFleetChanges(root) {
+ * (both are "" when a role holds nothing); the team view then drops the patch fields. */
+export async function collectTeamChanges(root) {
     const roles = await Promise.all(knownRoleIdsCached(root).map(async (role) => {
         const view = await collectRoleChange(root, role);
-        const { diff: _diff, uncommittedDiff: _uncommittedDiff, ...fleet } = view;
-        return fleet;
+        const { diff: _diff, uncommittedDiff: _uncommittedDiff, ...team } = view;
+        return team;
     }));
-    // mainBranch is fleet-wide: collectRoleChange resolves it once per role through the same
+    // mainBranch is team-wide: collectRoleChange resolves it once per role through the same
     // targetBranch call, so the first entry's value is every entry's value.
     return { mainBranch: roles[0]?.mainBranch ?? "main", roles };
 }
@@ -32,9 +32,9 @@ export async function collectFleetChanges(root) {
  * half of the view can print unbounded text. */
 const DIFF_MAX_BYTES = 200_000;
 /** Collect the change the role's loop holds: both halves of the view, or a degraded state
- * when the worktree or the base branch is missing. Never throws on a degraded fleet — a
+ * when the worktree or the base branch is missing. Never throws on a degraded team — a
  * query about a loop that has not run yet must answer, not fail (report's rationale). */
-export async function collectRoleChange(root, role) {
+export async function collectRoleChange(root, role, opts = {}) {
     const branch = branchName(role);
     const { config } = loadConfigSafe(root);
     const mainBranch = targetBranch(config?.baseBranch, await currentBranch(root));
@@ -43,6 +43,7 @@ export async function collectRoleChange(root, role) {
         branch,
         mainBranch,
         ahead: 0,
+        behind: 0,
         commits: [],
         diff: "",
         dirtyFiles: [],
@@ -58,11 +59,21 @@ export async function collectRoleChange(root, role) {
     if (wt === null || !(await isUsableWorktree(wt)))
         return { ...empty, state: "absent" };
     const ahead = await aheadOfMain(wt, mainBranch);
+    const behind = await countCommitsInRange(wt, `HEAD..${mainBranch}`);
     const commits = parseOnelineLog(await gitTry(wt, "log", "--oneline", `${mainBranch}..HEAD`));
-    const diff = ahead === 0 ? "" : await aheadOfMainDiff(wt, mainBranch);
+    // Under opts.stat both halves hold the uncapped `git diff --stat` summary (one line per file).
+    const diff = ahead === 0
+        ? ""
+        : opts.stat
+            ? ((await gitTry(wt, "diff", "--stat", `${mainBranch}...HEAD`)) ?? "")
+            : await aheadOfMainDiff(wt, mainBranch);
     const dirtyFiles = await changedFiles(wt);
-    const uncommittedDiff = dirtyFiles.length === 0 ? "" : await cappedWorkingDiff(wt);
-    return { ...empty, state: "ready", ahead, commits, diff, dirtyFiles, uncommittedDiff };
+    const uncommittedDiff = dirtyFiles.length === 0
+        ? ""
+        : opts.stat
+            ? ((await gitTry(wt, "diff", "--stat", "HEAD")) ?? "")
+            : await cappedWorkingDiff(wt);
+    return { ...empty, state: "ready", ahead, behind, commits, diff, dirtyFiles, uncommittedDiff };
 }
 /** Parse `git log --oneline` output into {sha, subject} pairs — sha up to the first space,
  * the rest of the line the subject. Blank trailing lines (runGit's trimEnd makes them

package/dist/src/change/change-render.js

@@ -1,28 +1,29 @@
 /** The renderer behind `tumwater diff` — the operator-facing text for the change views the
  * collector (change-data.ts, beside src/report/report-data.ts and history-data.ts) gathers: one
- * role's pending work (`--role <id>`) and the fleet-wide roster (no --role). Pure function of the
+ * role's pending work (`--role <id>`) and the team-wide roster (no --role). Pure function of the
  * collected view — no I/O, no clock reads. */
 import { plural } from "../text/phrases.js";
 /** The work-summary phrase both change views open their work lines with — `N commits ahead
- * of <main>` plus `, M uncommitted file(s)` when the worktree is dirty (both halves through
- * plural, so the singular/plural wording the tests pin cannot drift between the fleet roster
- * and the per-role header). Exactly two call sites: renderFleetChange's per-role line and
- * renderRoleChange's header line. */
-function workSummary(ahead, mainBranch, dirtyFiles) {
+ * of <main>` plus `, K commits behind` when the branch lags main, plus `, M uncommitted
+ * file(s)` when the worktree is dirty (each count through plural, so the singular/plural
+ * wording the tests pin cannot drift between the team roster and the per-role header).
+ * Exactly two call sites: renderTeamChange's per-role line and renderRoleChange's header line. */
+function workSummary(ahead, behind, mainBranch, dirtyFiles) {
     return (`${plural(ahead, "commit")} ahead of ${mainBranch}` +
+        (behind > 0 ? `, ${plural(behind, "commit")} behind` : "") +
         (dirtyFiles.length > 0 ? `, ${plural(dirtyFiles.length, "uncommitted file")}` : ""));
 }
 /** Render the roster as the operator-facing text `tumwater diff` (no --role) prints: one
  * line per role that holds pending work, in roster order; roles with no worktree and roles
  * holding nothing are skipped. Every entry no-base means the baseline itself is gone — the
- * per-role view's line says so, fleet-wide, exit 0 like every other degraded case. */
-export function renderFleetChange(view) {
+ * per-role view's line says so, team-wide, exit 0 like every other degraded case. */
+export function renderTeamChange(view) {
     if (view.roles.length > 0 && view.roles.every((r) => r.state === "no-base")) {
         return `main branch ${view.mainBranch} does not exist`;
     }
     const lines = view.roles
         .filter((r) => r.state !== "no-base" && (r.ahead > 0 || r.dirtyFiles.length > 0))
-        .map((r) => `${r.role}: ${workSummary(r.ahead, view.mainBranch, r.dirtyFiles)}`);
+        .map((r) => `${r.role}: ${workSummary(r.ahead, r.behind, view.mainBranch, r.dirtyFiles)}`);
     return lines.length > 0 ? lines.join("\n") : "no pending changes";
 }
 /** Render the view as the operator-facing text `tumwater diff --role <id>` prints. */
@@ -34,7 +35,7 @@ export function renderRoleChange(view) {
     if (view.ahead === 0 && view.dirtyFiles.length === 0)
         return `no pending change for ${view.role}`;
     const lines = [
-        `${view.role}: ${view.branch}, ${workSummary(view.ahead, view.mainBranch, view.dirtyFiles)}`,
+        `${view.role}: ${view.branch}, ${workSummary(view.ahead, view.behind, view.mainBranch, view.dirtyFiles)}`,
     ];
     for (const c of view.commits)
         lines.push(`${c.sha} ${c.subject}`);