tumwater 0.2.0 → 0.3.0

package/dist/src/redeploy/redeploy-policy.js

@@ -1,6 +1,7 @@
+import { HOUR_MS, DAY_MS } from "../text/datetime.js";
 /** Self-redeploy for a self-hosting team (see build/build-info.ts for why): when main's build
  * inputs have moved past the running build, verify that main is green, compile it into a staging
- * dir, drain the team (no new ticks; in-flight ones finish or are aborted resumably after
+ * dir, drain the team (no new runs; in-flight ones finish or are aborted resumably after
  * RESTART_DRAIN_MAX_MS), swap the compiled tree into dist/, and ask the supervisor
  * (src/process/supervisor.ts) to respawn the harness onto it by exiting RESTART_EXIT_CODE. Every
  * step is non-blocking from the orchestrator's poll: the green check and the compile run in the
@@ -24,38 +25,42 @@
  * BuildStatus.restartBlocked, which the dashboards and doctor render — because a stale build that
  * is about to be replaced and one that never will be look identical otherwise (BUGS.md
  * 2026-09-08). A green, compiled build can still be unable to START here — the environment, not
- * the code, fails `tumwater run`'s startup gate — so that gate is asked before the team is held
+ * the code, fails `tumwater start`'s startup gate — so that gate is asked before the team is held
  * and again right before the swap, and a failure refuses the restart with a `restart_refused`
  * event instead of trading a running team for a child that exits on its first line (BUGS.md
- * 2026-09-23). Every tick a restart interrupts resumes on the new build through the same resume
+ * 2026-09-23). Every run a restart interrupts resumes on the new build through the same resume
  * machinery a Ctrl+C uses, so a restart loses no work. */
-/** The exit code a supervised `tumwater run` child uses to say "rebuilt; respawn me" —
+/** The exit code a supervised `tumwater start` child uses to say "rebuilt; respawn me" —
  * EX_TEMPFAIL, distinct from success (0), fail() (1) and a forced Ctrl+C (130). */
 export const RESTART_EXIT_CODE = 75;
-/** The COLD-START drain window: how long a pending restart waits for in-flight ROLE ticks before
- * aborting them (they resume on the new build) when the orchestrator has too few completed-tick
+/** The COLD-START drain window: how long a pending restart waits for in-flight ROLE runs before
+ * aborting them (they resume on the new build) when the orchestrator has too few completed-run
  * samples to derive one. Measured across the whole unbroken hold, not per head — see
- * Redeployer.drainSince. Director ticks are exempt: an in-flight human prompt extends the hold
+ * Redeployer.drainSince. Director runs are exempt: an in-flight human prompt extends the hold
  * without any cap (see poll).
  *
- * The live window tracks the team's real tick duration: the orchestrator passes the p75 of recent
- * completed work-bearing role ticks (InFlightCounts.roleTickP75Ms) and poll uses it in place of
+ * The live window tracks the team's real run duration: the orchestrator passes the p75 of recent
+ * completed work-bearing role runs (InFlightCounts.roleRunP75Ms) and poll uses it in place of
  * this constant once it has enough samples (BUGS.md 2026-09-18). The hand-set 30 minutes had not
  * been re-derived since an earlier backend; measured p50 was 46 min and p75 82 min, so the drain
- * timed out on 60% of ticks — paying the full idle cost of waiting plus the interruption cost of
+ * timed out on 60% of runs — paying the full idle cost of waiting plus the interruption cost of
  * not waiting. */
 export const RESTART_DRAIN_MAX_MS = 30 * 60_000;
 /** How often a COMPLETED auto-restart may land — at most once per this window (BUGS.md
  * 2026-09-11): under sustained main churn every stale head would otherwise drive a full
  * hold+drain+swap episode back to back, halting the team for a drain over and over. Bounds
- * frequency across episodes; RESTART_DRAIN_MAX_MS bounds the drain within one. */
-export const RESTART_COOLDOWN_MS = 12 * 60 * 60_000;
+ * frequency across episodes; RESTART_DRAIN_MAX_MS bounds the drain within one. Cut from twelve
+ * hours to four on 2026-10-20: the last eight drains took a median of about 7 min (2 s to
+ * 26 min) and only one aborted runs, so the longer wait cost more than the drains it prevented. */
+export const RESTART_COOLDOWN_MS = 4 * HOUR_MS;
+/** The cooldown in whole hours — the one home of that ms→h division, for the warning text. */
+export const RESTART_COOLDOWN_HOURS = RESTART_COOLDOWN_MS / HOUR_MS;
 /** The cooldown's urgency carve-out (BUGS.md 2026-09-30): when the RUNNING build's own commit
- * carries a red baseline verdict, the deferral is cut to this window instead of the full 12 h —
- * a red running build is not churn but the exact predicament the self-redeploy exists to end,
- * and the rate limit protects against storms, not against a team knowingly executing code its
- * own tree fails. Still a real delay, so consecutive reds cannot storm: one episode per this
- * window at most, each swap giving the team a chance to merge on green. */
+ * carries a red baseline verdict, the deferral is cut to this window instead of the ordinary
+ * cooldown — a red running build is not churn but the exact predicament the self-redeploy exists
+ * to end, and the rate limit protects against storms, not against a team knowingly executing
+ * code its own tree fails. Still a real delay, so consecutive reds cannot storm: one episode
+ * per this window at most, each swap giving the team a chance to merge on green. */
 export const RESTART_URGENT_COOLDOWN_MS = 15 * 60_000;
 /** The urgent carve-out in whole minutes — the one home of that ms→min division, beside the
  * constant it derives from, so the three redeployer.ts warnings that restate the length in
@@ -66,6 +71,6 @@ export const RESTART_URGENT_COOLDOWN_MIN = RESTART_URGENT_COOLDOWN_MS / 60_000;
  * different commit, so the aggregate — hours pinned on a stale build while every rebuild dies —
  * raised no alarm anywhere the operator reads. One warning at this age, then at most one per
  * STALE_ESCALATE_EVERY_MS for as long as the episode lasts. */
-export const STALE_ESCALATE_AFTER_MS = 6 * 60 * 60_000;
+export const STALE_ESCALATE_AFTER_MS = 6 * HOUR_MS;
 /** The sustained-pin warning's repeat cadence: daily, not per poll and not per head. */
-export const STALE_ESCALATE_EVERY_MS = 24 * 60 * 60_000;
+export const STALE_ESCALATE_EVERY_MS = DAY_MS;

package/dist/src/redeploy/redeploy-probes.js

@@ -31,7 +31,7 @@ export class PrewarmProbes {
     }
     /** Run the deferred head's green check, then its staged compile, once per SHA — the same
      * effects the episode itself runs, so their cost lands inside the dead window instead of
-     * stretching it; the 12 h rate limit keeps protecting against churn, and this keeps it from
+     * stretching it; the restart rate limit keeps protecting against churn, and this keeps it from
      * also idling away verification work a known-stale build owes. */
     prewarm(head, pending) {
         if (pending)

package/dist/src/redeploy/redeploy.js

@@ -1,4 +1,3 @@
-// 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";
@@ -15,7 +14,7 @@ import { Redeployer, bestEffortLog } from "./redeployer.js";
  * production RedeployDeps bound to one repo — the mirror worktree both the green check and the
  * compile run in, the baseline check that reads the live config per call, the staged compile,
  * and the dist swap — plus the completed-restart record's small state file and the
- * createRedeployer composition the run boot (cli/cli-run.ts) builds. */
+ * createRedeployer composition the run boot (cli/cli-start.ts) builds. */
 /** The production AutoRestartRecord: one JSON file under .tumwater/state/. A missing or torn
  * file reads as "no completed restart yet" — the same no-data policy as every other state
  * reader. */
@@ -78,7 +77,7 @@ export function redeployDeps(root, build, log, bootProblem) {
 /** The production Redeployer for `root`, or null when the running dist carries no build stamp
  * (compiled with a bare tsc): then provenance is unknown and there is nothing to compare. */
 export async function createRedeployer(root, log, 
-/** The successor's startup gate (RedeployDeps.bootProblem) — cli/cli-run.ts binds
+/** The successor's startup gate (RedeployDeps.bootProblem) — cli/cli-start.ts binds
  * runStartupProblem to the invocation's own flags, the ones the supervisor forwards to every
  * generation. */
 bootProblem) {

package/dist/src/redeploy/redeployer.js

@@ -2,7 +2,7 @@ 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";
-import { RESTART_COOLDOWN_MS, RESTART_DRAIN_MAX_MS, RESTART_URGENT_COOLDOWN_MIN, RESTART_URGENT_COOLDOWN_MS, STALE_ESCALATE_AFTER_MS, STALE_ESCALATE_EVERY_MS, } from "./redeploy-policy.js";
+import { RESTART_COOLDOWN_HOURS, RESTART_COOLDOWN_MS, RESTART_DRAIN_MAX_MS, RESTART_URGENT_COOLDOWN_MIN, RESTART_URGENT_COOLDOWN_MS, STALE_ESCALATE_AFTER_MS, STALE_ESCALATE_EVERY_MS, } from "./redeploy-policy.js";
 import { PrewarmProbes, track } from "./redeploy-probes.js";
 /** Wrap the event sink so an unwritable feed cannot throw out of the redeploy state machine.
  * `poll` runs inside the orchestrator's catch-less poll loop and `forceRestart` inside the
@@ -29,7 +29,7 @@ export function bestEffortLog(log) {
     };
 }
 /** The redeploy state machine — one per orchestrator process. `poll` is called every scheduler
- * cycle with main's current head and how many role/director ticks are in flight, and returns what
+ * cycle with main's current head and how many role/director runs are in flight, and returns what
  * to do; it never throws and never awaits anything slower than a git query. */
 export class Redeployer {
     build;
@@ -44,12 +44,12 @@ export class Redeployer {
     /** 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 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
+     * handed the same in-flight runs another 30 minutes every time main moved. On 2026-09-08 that
      * 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
+     * Nothing new starts during a hold, so the runs 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 team's observed p75 tick
+    /** The drain window captured when the current hold began: the team's observed p75 run
      * 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). */
@@ -106,7 +106,7 @@ export class Redeployer {
     cooldownWarnedUntil = null;
     /** The ordinary cooldown deadline whose urgent lapse has already warned: when the red-carved
      * deadline sits in the past, the deferred-branch warning above cannot fire, and the episode
-     * would otherwise start with no event naming why the announced 12 h deadline was abandoned
+     * would otherwise start with no event naming why the announced deadline was abandoned
      * (BUGS.md 2026-09-30). Keyed to the ordinary deadline — one warning per cooldown, the same
      * discipline as cooldownWarnedUntil. */
     urgentLapseWarnedFor = null;
@@ -147,7 +147,7 @@ export class Redeployer {
      * respect to this main, and poll is a no-op (see isSelfHosted). */
     selfHosted, deps, log, 
     /** Cold-start drain window (default RESTART_DRAIN_MAX_MS): the fallback poll uses until the
-     * orchestrator supplies enough observed tick durations; a test seam. */
+     * orchestrator supplies enough observed run durations; a test seam. */
     drainMaxMs = RESTART_DRAIN_MAX_MS, 
     /** The completed-auto-restart record (see AutoRestartRecord) — production reads it from its
      * state file at construction via autoRestartRecord(root), tests inject one. */
@@ -171,14 +171,14 @@ 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 team ticked on stale
+            // that gap is what let a blocked restart sit unnoticed while the team ran 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 team deliberately keeps ticking on the stale build
+            // Inside the post-restart cooldown the team deliberately keeps running 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 team on the stale build just as
@@ -203,7 +203,7 @@ export class Redeployer {
      * the next poll that reaches the cooldown check waives the deferral — it nulls the cooldown's
      * start, so the whole episode proceeds now and later polls of it stay un-deferred. It clears
      * ONLY the cooldown — a red main verdict, a failed compile, a swap error, or a boot refusal
-     * still blocks through the ordinary paths, and in-flight ticks still drain through the
+     * still blocks through the ordinary paths, and in-flight runs still drain through the
      * ordinary window. One `restart_forced` event records the operator's hand, so the feed shows
      * why an episode started mid-cooldown. */
     forceRestart() {
@@ -232,7 +232,7 @@ export class Redeployer {
         this.buildRedSha = this.build.sha;
         this.buildRed = track(this.deps.buildRed(this.build.sha));
     }
-    /** The deadline this deferral holds to: the ordinary 12 h rate limit, cut to the urgent
+    /** The deadline this deferral holds to: the ordinary cooldown, cut to the urgent
      * window when the RUNNING build's own commit carries a settled red verdict (BUGS.md
      * 2026-09-30). The verdict is whatever the background check has produced so far — an
      * unsettled or unknown verdict reads as not-red, so a cold cache leaves the ordinary
@@ -295,8 +295,8 @@ 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 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
+        // back to back. Inside the cooldown the team keeps running on the stale build exactly as when
+        // a restart is blocked — no pendingHead, no hold, no drain, no new-run 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
         // zero. This is re-evaluated on every poll rather than latched like blockedHead: once the
@@ -323,7 +323,7 @@ export class Redeployer {
                 this.warn(`auto-restart of ${shortSha(mainHead)} deferred — cooldown until ${new Date(cooldownUntil).toISOString()}` +
                     (urgent
                         ? ` (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)"));
+                        : ` (at most one completed restart per ${RESTART_COOLDOWN_HOURS} h)`));
             }
             this.probes.prewarm(mainHead, this.pendingHead !== null);
             return this.endDrain();
@@ -333,7 +333,7 @@ export class Redeployer {
         // The carve-out's second silence (BUGS.md 2026-09-30): a red verdict arriving after the
         // 15 min urgent window has passed cuts the deadline to a point already gone, so the
         // deferred-branch warning above never ran and the episode below started with no word of
-        // why the announced 12 h deadline was abandoned. urgent here means now is still inside the
+        // why the announced deadline was abandoned. urgent here means now is still inside the
         // ordinary cooldown and the running build is red — say why the episode starts early, once
         // per ordinary deadline.
         if (urgent && this.urgentLapseWarnedFor !== this.cooldownUntil()) {
@@ -356,7 +356,7 @@ export class Redeployer {
                 this.drainSince = now;
                 // Capture the window with the hold: the observed p75 when the orchestrator has it,
                 // otherwise the cold-start constant.
-                const p75 = inFlight.roleTickP75Ms;
+                const p75 = inFlight.roleRunP75Ms;
                 this.drainWindowMs = typeof p75 === "number" && p75 > 0 ? p75 : this.drainMaxMs;
             }
             // Adopt the cooldown's pre-warm (BUGS.md 2026-09-30): verdicts already in hand mean the
@@ -425,10 +425,10 @@ export class Redeployer {
             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
+        // The drain rule, split by who requested the work (BUGS.md 2026-09-08): a director run 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 team beyond what a single tick can do.
+        // time cap: no swap and no abort until it finishes. The per-run watchdogs already bound how
+        // long one run can take, so this cannot hang the team beyond what a single run can do.
         if (inFlight.directorInFlight > 0)
             return "hold";
         if (inFlight.roleInFlight > 0 && now - this.drainSince < this.drainWindowMs)
@@ -468,7 +468,7 @@ export class Redeployer {
         this.staleSince = null;
         this.lastEscalationAt = null;
         // 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
+        // directorInFlight === 0), so what gets aborted — and counted — are role runs only, and
         // only those holding a permit (see InFlightCounts). A director-extended hold reports
         // finishedMs past the window: correct and informative.
         this.log({

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

@@ -4,6 +4,7 @@ import { isSelfHosted, readBuildInfo } from "../build/build-info.js";
 import { RESTART_EXIT_CODE } from "./redeploy-policy.js";
 import { childEnv } from "../process/process.js";
 import { startParentDeathWatch } from "../process/supervisor.js";
+import { liveNodeBin } from "../process/node-bin.js";
 /** Auto-reload for the user-launched dashboards (`tumwater tui`, `tumwater gui`).
  *
  * Unlike the orchestrator — which the supervisor respawns onto a fresh build — a dashboard is
@@ -73,7 +74,7 @@ export function reexecSelf(spawnImpl = spawn) {
         stdio: "inherit",
         env: childEnv({ [DASHBOARD_CHILD_ENV]: String(process.pid) }),
     };
-    const startChild = () => spawnImpl(process.execPath, process.argv.slice(1), options);
+    const startChild = () => spawnImpl(liveNodeBin(), process.argv.slice(1), options);
     const supervise = () => {
         const child = startChild();
         child.on("exit", (code) => {