tumwater 0.1.2 → 0.2.0

package/dist/src/redeploy/redeploy.js

@@ -1,4 +1,6 @@
+// vocabulary: plain
 import { buildStaleness, distDir, isSelfHosted, readBuildInfo } from "../build/build-info.js";
+import { TUMWATER_SOURCE } from "../events/events.js";
 import { baselineCheckEventLogger } from "../build/build-check-events.js";
 import { liveConfig } from "../config/config.js";
 import { cachedBaselineVerdict, checkMainBaseline, mainIsGreen } from "../baseline/main-baseline.js";
@@ -46,24 +48,24 @@ export function redeployDeps(root, build, log, bootProblem) {
         mainGreen: async (mainHead) => 
         // The live config per call (a mid-run edit applies to the next green check like it
         // does everywhere else); a broken file degrades to defaults — no declared check.
-        mainIsGreen(await mirror(mainHead), liveConfig(root), baselineCheckEventLogger("harness", safeLog)),
+        mainIsGreen(await mirror(mainHead), liveConfig(root), baselineCheckEventLogger(TUMWATER_SOURCE, safeLog)),
         compile: async (mainHead) => compileStaged(root, await mirror(mainHead), mainHead),
         swap: (mainHead) => swapDist(root, dist, mainHead),
         bootProblem,
         // The urgency carve-out's verdict (BUGS.md 2026-09-30): a cached verdict answers free;
         // otherwise the baseline check runs on the running build's own SHA, in a dedicated witness
         // worktree — never the mirror, which the green check and compile serve at main's heads —
-        // and lands in the same fleet-shared cache every later consult reads. A fresh red is
+        // and lands in the same team-shared cache every later consult reads. A fresh red is
         // provisional (BUGS.md 2026-09-30): the gate's flake rule applies here too, so one
         // immediate re-run must confirm it before the carve-out may cut the cooldown on it — a
-        // green on the re-run promotes the SHA fleet-wide, and a skipped re-run leaves the verdict
+        // green on the re-run promotes the SHA team-wide, and a skipped re-run leaves the verdict
         // unsettled (null), which the policy reads as not-red.
         buildRed: async (buildSha) => {
             const cached = cachedBaselineVerdict(buildSha);
             if (cached !== undefined)
                 return cached === "red";
             const witness = await ensureDetachedWorktree(root, witnessWorktreePath(root), buildSha);
-            const onRun = baselineCheckEventLogger("harness", safeLog);
+            const onRun = baselineCheckEventLogger(TUMWATER_SOURCE, safeLog);
             const baseline = await checkMainBaseline(witness, liveConfig(root), onRun);
             if (baseline.baseline?.status !== "red") {
                 return baseline.baseline ? false : null;

package/dist/src/redeploy/redeployer.js

@@ -1,3 +1,4 @@
+import { TUMWATER_SOURCE } from "../events/events.js";
 import { errorMessage, stripTerminalControls } from "../text/text.js";
 import { shortSha } from "../text/format.js";
 import { mainRedPhrase } from "../text/phrases.js";
@@ -7,7 +8,7 @@ import { PrewarmProbes, track } from "./redeploy-probes.js";
  * `poll` runs inside the orchestrator's catch-less poll loop and `forceRestart` inside the
  * restart-marker consumer's, so a `logEvent` throw (ENOSPC, EACCES, the path replaced by a
  * directory) on the first build_stale/restart_refused/restart_blocked transition would end the
- * fleet, and for a forced restart leave its marker unacknowledged — the same "logging must not
+ * team, and for a forced restart leave its marker unacknowledged — the same "logging must not
  * throw" policy the orchestrator poll body's `emit` and the abort-request consumer apply. The
  * redeploy wiring (redeploy.ts's redeployDeps) wraps its sink with this too: the green and
  * witness checks call that sink from inside checkMainBaseline's run hook, whose throw would
@@ -23,7 +24,7 @@ export function bestEffortLog(log) {
         catch (err) {
             // A terminal boundary: the error text can carry 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 record ${event.type} event: ${stripTerminalControls(errorMessage(err))}\n`);
+            process.stderr.write(`tumwater: could not record ${event.type} event: ${stripTerminalControls(errorMessage(err))}\n`);
         }
     };
 }
@@ -40,15 +41,15 @@ export class Redeployer {
     staleness = null;
     /** The head a restart is pending for. */
     pendingHead = null;
-    /** When the fleet's current unbroken hold began — 0 when it is not being held. The drain
+    /** When the team's current unbroken hold began — 0 when it is not being held. The drain
      * deadline is measured from here and NOT from when the current head became pending: a busy
-     * self-hosting fleet merges while it drains, and giving each new head its own full window
+     * self-hosting team merges while it drains, and giving each new head its own full window
      * handed the same in-flight ticks another 30 minutes every time main moved. On 2026-09-08 that
-     * held the fleet for 38 minutes under a 30-minute cap and reported the last 30 (BUGS.md).
+     * held the team for 38 minutes under a 30-minute cap and reported the last 30 (BUGS.md).
      * Nothing new starts during a hold, so the ticks a drain waits on can only be the ones it
      * began with — one window is all they are owed. */
     drainSince = 0;
-    /** The drain window captured when the current hold began: the fleet's observed p75 tick
+    /** The drain window captured when the current hold began: the team's observed p75 tick
      * duration when the orchestrator has enough samples, else the cold-start RESTART_DRAIN_MAX_MS.
      * Captured once per unbroken hold so a sample change mid-episode cannot move a deadline that
      * is already running (see drainSince). */
@@ -82,7 +83,7 @@ export class Redeployer {
     forcedRestart = false;
     /** When the current unbroken stale episode began (epoch ms), or null while the build is fresh.
      * Deliberately head-independent: main moving under a stale build CONTINUES the episode rather
-     * than restarting the clock, because the fleet's predicament — running code main has left
+     * than restarting the clock, because the team's predicament — running code main has left
      * behind — is the same whatever the head, and a per-head clock is exactly what let the
      * 2026-09-29 pin produce 109 warnings without ever saying the pin was the story. In-memory,
      * per process: a completed restart (and the process exit that follows it) is a new world. */
@@ -97,7 +98,7 @@ export class Redeployer {
     lastEscalationAt = null;
     /** The cooldown deadline the current episode's deferral was last warned about — one warning
      * per distinct deadline, not one per poll and not one per head: the cooldown condition is
-     * head-independent, so a landing mid-cooldown adds no new information (BUGS.md 2026-09-19).
+     * head-independent, so a merge mid-cooldown adds no new information (BUGS.md 2026-09-19).
      * Keyed to the deadline rather than a bare flag so an urgency onset mid-episode — the running
      * build's red verdict arriving after the ordinary warning (BUGS.md 2026-09-30) — is a real
      * transition and warns once more with the earlier deadline. Cleared when the deadline lapses,
@@ -119,7 +120,7 @@ export class Redeployer {
     buildRedSha = null;
     /** Pre-warm during a cooldown (BUGS.md 2026-09-30): the head whose restart the cooldown defers
      * still gets its green check and staged compile — once per SHA — so the lapse reaches the
-     * swap directly instead of paying green-check + compile + drain from zero while the fleet sits on
+     * swap directly instead of paying green-check + compile + drain from zero while the team sits on
      * a build it already knows is stale. The check and compile are the same side-effect-free effects
      * the episode itself runs (mirror worktree, staging dir under .tumwater/build); what the episode
      * adopts is decided by the adopt helpers, not by the pre-warm. The probes themselves live in
@@ -136,7 +137,7 @@ export class Redeployer {
      * blockedHead: the gate is asked again on every poll, so repairing the environment lets the
      * same head proceed without main moving. Also the dedupe key — one `restart_refused` per
      * distinct reason, not one per poll, and head-independent like the cooldown warning: a
-     * landing mid-refusal adds no new information. */
+     * merge mid-refusal adds no new information. */
     refusedReason = null;
     /** The live autoRestart flag as last seen by poll — status() publishes the cooldown reason only
      * while it is on (off means no restart will ever be attempted, so a deadline would mislead). */
@@ -170,26 +171,26 @@ export class Redeployer {
             s.checkedHead = this.lastHead;
             // Why a stale build is still the one running. Staleness alone cannot say: a restart that
             // is minutes away and one that was refused hours ago look identical, and on 2026-09-08
-            // that gap is what let a blocked restart sit unnoticed while the fleet ticked on stale
+            // that gap is what let a blocked restart sit unnoticed while the team ticked on stale
             // code (BUGS.md). Mutually exclusive by construction — block() clears the pending head,
             // and an episode cannot start inside the cooldown, so no two branches can hold at once.
             if (this.pendingHead === this.lastHead)
                 s.restartPending = true;
             else if (this.blockedHead === this.lastHead && this.blockedReason)
                 s.restartBlocked = this.blockedReason;
-            // Inside the post-restart cooldown the fleet deliberately keeps ticking on the stale build
+            // Inside the post-restart cooldown the team deliberately keeps ticking on the stale build
             // — say so with a deadline, through the same channel as a refused restart
             // (BUGS.md 2026-09-11).
-            // Past it, a startup gate that keeps failing holds the fleet on the stale build just as
+            // Past it, a startup gate that keeps failing holds the team on the stale build just as
             // surely, and says why the same way (BUGS.md 2026-09-23).
             else if (s.stale && this.autoRestartOn) {
                 const { until, urgent } = this.effectiveCooldownUntil(now);
                 if (now < until)
                     s.restartBlocked =
                         `cooldown until ${new Date(until).toISOString()}` +
-                            (urgent ? ` (the running build's own commit is red — cut to ${RESTART_URGENT_COOLDOWN_MIN} min)` : "");
+                            (urgent ? ` (the running version's own commit fails its check — cut to ${RESTART_URGENT_COOLDOWN_MIN} min)` : "");
                 else if (this.refusedReason !== null)
-                    s.restartBlocked = `the new build could not start: ${this.refusedReason}`;
+                    s.restartBlocked = `the update could not start: ${this.refusedReason}`;
             }
         }
         return s;
@@ -207,7 +208,7 @@ export class Redeployer {
      * why an episode started mid-cooldown. */
     forceRestart() {
         this.forcedRestart = true;
-        this.log({ loop: "harness", type: "restart_forced", build: this.build.sha });
+        this.log({ source: TUMWATER_SOURCE, type: "restart_forced", build: this.build.sha });
     }
     /** Read and clear the forced flag — one-shot: the poll that consumes it acts on it. */
     consumeForcedRestart() {
@@ -218,7 +219,7 @@ export class Redeployer {
     }
     /** Start the RUNNING build's own baseline check in the background when the cooldown is
      * deferring a restart and this process has no verdict for the build SHA yet (BUGS.md
-     * 2026-09-30). This is the cold-cache recovery the fleet-shared cache cannot give by itself:
+     * 2026-09-30). This is the cold-cache recovery the team-shared cache cannot give by itself:
      * checkMainBaseline only ever runs at main's tip, so a stale build's SHA gains an entry no
      * other way. The witness check costs at most one suite run per process per build SHA — the
      * cache answers every later consult — and its result can only shorten the wait safely: a
@@ -260,7 +261,7 @@ export class Redeployer {
             const stale = this.staleness?.stale ?? false;
             if (stale && !wasStale) {
                 this.log({
-                    loop: "harness",
+                    source: TUMWATER_SOURCE,
                     type: "build_stale",
                     build: this.build.sha,
                     head: mainHead,
@@ -294,7 +295,7 @@ export class Redeployer {
             return this.endDrain();
         // Completed auto-restarts are rate-limited to one per RESTART_COOLDOWN_MS (BUGS.md 2026-09-11):
         // under sustained churn every stale head would otherwise drive a full hold+drain+swap episode
-        // back to back. Inside the cooldown the fleet keeps ticking on the stale build exactly as when
+        // back to back. Inside the cooldown the team keeps ticking on the stale build exactly as when
         // a restart is blocked — no pendingHead, no hold, no drain, no new-tick block — but the
         // deferred head's green check and staged compile still run (prewarm, BUGS.md 2026-09-30), so
         // the lapse reaches the swap directly instead of paying green-check + compile + drain from
@@ -321,7 +322,7 @@ export class Redeployer {
                 this.cooldownWarnedUntil = cooldownUntil;
                 this.warn(`auto-restart of ${shortSha(mainHead)} deferred — cooldown until ${new Date(cooldownUntil).toISOString()}` +
                     (urgent
-                        ? ` (the running build ${shortSha(this.build.sha)} is red — the cooldown is cut to ${RESTART_URGENT_COOLDOWN_MIN} min)`
+                        ? ` (the running version ${shortSha(this.build.sha)} fails its check — the cooldown is cut to ${RESTART_URGENT_COOLDOWN_MIN} min)`
                         : " (at most one completed restart per 12 h)"));
             }
             this.probes.prewarm(mainHead, this.pendingHead !== null);
@@ -337,7 +338,7 @@ export class Redeployer {
         // per ordinary deadline.
         if (urgent && this.urgentLapseWarnedFor !== this.cooldownUntil()) {
             this.urgentLapseWarnedFor = this.cooldownUntil();
-            this.warn(`auto-restart of ${shortSha(mainHead)} proceeding early — the running build ${shortSha(this.build.sha)} is red, ` +
+            this.warn(`auto-restart of ${shortSha(mainHead)} proceeding early — the running version ${shortSha(this.build.sha)} fails its check, ` +
                 `the cooldown was cut to ${RESTART_URGENT_COOLDOWN_MIN} min and that deadline has already passed`);
         }
         if (this.pendingHead === null) {
@@ -349,7 +350,7 @@ export class Redeployer {
                 return this.refuse(mainHead, problem, now);
             this.refusedReason = null;
             this.pendingHead = mainHead;
-            // Only when the fleet was not already being held: a superseded head hands its drain over
+            // Only when the team was not already being held: a superseded head hands its drain over
             // to the new one rather than starting a fresh window (see drainSince).
             if (!this.drainSince) {
                 this.drainSince = now;
@@ -362,6 +363,10 @@ export class Redeployer {
             // lapse reaches the swap directly instead of paying green-check + compile from zero.
             this.green = this.probes.adoptGreen(mainHead);
             this.compiled = this.probes.adoptCompile(mainHead);
+            // An adopted compile skips the `!this.compiled` branch below, the only other place the
+            // hold is announced, so say it here or the episode logs nothing until `restart`.
+            if (this.compiled)
+                this.logRestartPending(mainHead);
             return "hold";
         }
         if (!this.green?.done)
@@ -369,7 +374,7 @@ export class Redeployer {
         // A REJECTED check is not a verdict: it could not run (git broke inside the mirror worktree,
         // or the check itself threw), so it says nothing about the tree. Drop the pending head — no
         // blockedHead, no latched "main is red" — warn once per episode, and let the next poll
-        // re-run the check on the same head; a fleet whose toolchain recovers redeploys itself
+        // re-run the check on the same head; a team whose toolchain recovers redeploys itself
         // without main ever moving (BUGS.md 2026-09-16). A red VERDICT below still blocks.
         if (this.green.error) {
             this.noteFailure(now);
@@ -387,19 +392,7 @@ export class Redeployer {
         }
         if (!this.compiled) {
             this.compiled = this.probes.adoptCompile(mainHead) ?? track(this.deps.compile(mainHead));
-            // Once per head, not once per episode: a rejected compile drops the episode and the next
-            // poll starts a fresh one, and a state stream that re-enters "compiling" it never left
-            // is noise on top of the missing terminal event (BUGS.md 2026-09-28).
-            if (this.pendingLoggedHead !== mainHead) {
-                this.pendingLoggedHead = mainHead;
-                this.log({
-                    loop: "harness",
-                    type: "restart_pending",
-                    build: this.build.sha,
-                    head: mainHead,
-                    aheadCommits: this.staleness.aheadCommits,
-                });
-            }
+            this.logRestartPending(mainHead);
             return "hold";
         }
         if (!this.compiled.done)
@@ -422,26 +415,26 @@ export class Redeployer {
                 if (this.compileFailedHead !== mainHead) {
                     this.compileFailedHead = mainHead;
                     this.warn(c === undefined
-                        ? `rebuild of ${shortSha(mainHead)} could not run: ${detail} — retrying on the next poll`
-                        : `could not start the rebuild of ${shortSha(mainHead)}: ${detail} — retrying on the next poll`);
+                        ? `the update to ${shortSha(mainHead)} could not be built: ${detail} — retrying on the next poll`
+                        : `the update could not start: ${detail} — retrying on the next poll`);
                 }
                 this.clearPending();
                 return this.endDrain();
             }
-            const reason = `rebuild of ${shortSha(mainHead)} failed`;
-            this.block(mainHead, reason, `${reason} — staying on build ${shortSha(this.build.sha)}: ${detail}`);
+            const reason = `the update to ${shortSha(mainHead)} failed to build`;
+            this.block(mainHead, reason, `${reason} — staying on version ${shortSha(this.build.sha)}: ${detail}`);
             return this.endDrain();
         }
         // The drain rule, split by who requested the work (BUGS.md 2026-09-08): a director tick is
         // an explicit human prompt and outranks the redeploy — while one is in flight the hold has no
         // time cap: no swap and no abort until it finishes. The per-tick watchdogs already bound how
-        // long one run can take, so this cannot hang the fleet beyond what a single tick can do.
+        // long one run can take, so this cannot hang the team beyond what a single tick can do.
         if (inFlight.directorInFlight > 0)
             return "hold";
         if (inFlight.roleInFlight > 0 && now - this.drainSince < this.drainWindowMs)
             return "hold";
         // Ask the startup gate once more, right before the point of no return: the environment can
-        // change during a long drain — a landing already in flight when the hold began can still
+        // change during a long drain — a merge already in flight when the hold began can still
         // delete tumwater.json (the 2026-09-22 incident's own cause). Refused, the episode is
         // dropped rather than latched, so the next poll starts over at the gate above: nothing is
         // held while it keeps failing, and a fixed environment gets a full episode with its own drain.
@@ -455,7 +448,7 @@ export class Redeployer {
         }
         catch (err) {
             this.noteFailure(now);
-            const reason = "swapping the new build into place failed";
+            const reason = "swapping the update into place failed";
             this.block(mainHead, reason, `${reason}: ${errorMessage(err)}`);
             return this.endDrain();
         }
@@ -477,27 +470,42 @@ export class Redeployer {
         // The director is guaranteed finished by here (poll only reaches the swap with
         // directorInFlight === 0), so what gets aborted — and counted — are role ticks only, and
         // only those holding a permit (see InFlightCounts). A director-extended hold reports
-        // drainedMs past the window: correct and informative.
+        // finishedMs past the window: correct and informative.
         this.log({
-            loop: "harness",
+            source: TUMWATER_SOURCE,
             type: "restart",
             from: this.build.sha,
             to: mainHead,
-            drainedMs: now - this.drainSince,
-            abortedTicks: inFlight.roleInFlight,
-            drainWindowMs: this.drainWindowMs,
+            finishedMs: now - this.drainSince,
+            abortedRuns: inFlight.roleInFlight,
+            finishWindowMs: this.drainWindowMs,
         });
         // The state stream left "compiling"; a later episode for this same head is a new transition.
         this.pendingLoggedHead = null;
         return "restart";
     }
-    /** Nothing is being waited for any more — the fleet schedules normally again, so whatever
+    /** Nothing is being waited for any more — the team schedules normally again, so whatever
      * drain was running is over and the next one starts its clock from scratch. Every path out of
      * poll that is not a `hold` goes through here. */
     endDrain() {
         this.drainSince = 0;
         return "none";
     }
+    // Once per head, not once per episode: a rejected compile drops the episode and the next
+    // poll starts a fresh one, and a state stream that re-enters "compiling" it never left
+    // is noise on top of the missing terminal event (BUGS.md 2026-09-28).
+    logRestartPending(mainHead) {
+        if (this.pendingLoggedHead === mainHead)
+            return;
+        this.pendingLoggedHead = mainHead;
+        this.log({
+            source: TUMWATER_SOURCE,
+            type: "restart_pending",
+            build: this.build.sha,
+            head: mainHead,
+            aheadCommits: this.staleness?.aheadCommits ?? 0,
+        });
+    }
     /** deps.bootProblem, fail-closed: a gate that throws cannot vouch for the successor, so its
      * error is the refusal's reason (and, like any refusal, it is asked again next poll). */
     async bootProblem() {
@@ -514,7 +522,7 @@ export class Redeployer {
         this.noteFailure(now);
         if (reason !== this.refusedReason) {
             this.refusedReason = reason;
-            this.log({ loop: "harness", type: "restart_refused", from: this.build.sha, to: head, reason });
+            this.log({ source: TUMWATER_SOURCE, type: "restart_refused", from: this.build.sha, to: head, reason });
         }
         // The state stream left "compiling" via the refusal event; a later episode for the same
         // head — the gate re-asked after the environment was repaired — is a new transition.
@@ -532,12 +540,12 @@ export class Redeployer {
         this.blockedHead = head;
         this.blockedReason = reason;
         this.clearPending();
-        // A typed transition, not only a warning: the digest's Fleet state changes section replays
+        // A typed transition, not only a warning: the digest's Team state changes section replays
         // the decisions, and a stream that entered "compiling" must leave it when the compile dies
         // — its two other endings (restart, restart_refused) each have an event, so the third does
         // too (BUGS.md 2026-09-28). Logged before the warning, so the warning is never the state
         // stream's only trace of the episode's end.
-        this.log({ loop: "harness", type: "restart_blocked", from: this.build.sha, to: head, reason });
+        this.log({ source: TUMWATER_SOURCE, type: "restart_blocked", from: this.build.sha, to: head, reason });
         this.warn(message);
     }
     /** A restart attempt just failed — record when, so sustained staleness WITH failures can
@@ -551,7 +559,7 @@ export class Redeployer {
     /** The sustained-pin warning (BUGS.md 2026-09-29): once the build has stayed stale past
      * STALE_ESCALATE_AFTER_MS and a restart attempt has failed within this same stale episode,
      * say the aggregate out loud — at most once per STALE_ESCALATE_EVERY_MS while it lasts.
-     * Healthy churn never feeds it: a landing restart clears the episode, and a cooldown
+     * Healthy churn never feeds it: a merge restart clears the episode, and a cooldown
      * deferral or red main produces no failed attempt, so no warning. */
     escalateIfSustained(now) {
         const since = this.staleSince;
@@ -563,10 +571,10 @@ export class Redeployer {
             return;
         this.lastEscalationAt = now;
         const hours = Math.max(1, Math.round((now - since) / 3_600_000));
-        this.warn(`build ${shortSha(this.build.sha)} has stayed stale for ~${hours} h (${this.staleness?.aheadCommits ?? 0} commits behind main) while rebuild attempts keep failing — the sustained pin itself is the problem, not any one head`);
+        this.warn(`an update has waited ~${hours} h to install (running ${shortSha(this.build.sha)}, ${this.staleness?.aheadCommits ?? 0} commits behind main) while update attempts keep failing — the stuck version itself is the problem, not any one commit`);
     }
     /** Log one warning event for the harness loop — the shape the class's warn sites share. */
     warn(message) {
-        this.log({ loop: "harness", type: "warning", message });
+        this.log({ source: TUMWATER_SOURCE, type: "warning", message });
     }
 }

package/dist/src/redeploy/self-reload.js

@@ -8,7 +8,7 @@ import { startParentDeathWatch } from "../process/supervisor.js";
  *
  * Unlike the orchestrator — which the supervisor respawns onto a fresh build — a dashboard is
  * started by hand and, without this, keeps serving its startup code until the operator
- * restarts it. When the fleet redeploys itself (redeploy.ts swaps `dist/`) the TUI keeps
+ * restarts it. When the team redeploys itself (redeploy.ts swaps `dist/`) the TUI keeps
  * rendering old modules and the GUI keeps serving old page JS. This module watches for a
  * newer compiled tree on disk and hands itself to a fresh copy of the same command (a supervised
  * respawn, not a nested wrapper), so both surfaces come back on the new code within a poll.