tumwater 0.4.0 → 0.4.2

package/dist/src/pi/pi-stream.js

@@ -334,18 +334,8 @@ export class PiStreamParser {
             this.buffer = this.buffer.slice(start);
     }
     feedLine(line) {
-        // Streaming deltas are ~72% of log bytes in observed runs. pi's JSON protocol strips the
-        // cumulative message snapshot from them, so the delta event is all they carry — and a
-        // content-free one (a zombie stream's keepalive, or the pre-strip shape) proves nothing:
-        // it must not reset the hang watchdog. A content-bearing delta is real generation, and
-        // counting it is what keeps a long thinking block on a slow model from being quiet-killed
-        // as hung (BUGS.md 2026-10-17) — the same content rule tool_execution_update gets below.
-        // Nothing else in this parser acts on the type, so the line is done either way.
-        if (piEventType(line) === "message_update") {
-            if (messageUpdateHasContent(parseJsonObject(line)))
-                this.progressCount += 1;
+        if (this.applyMessageUpdate(line))
             return;
-        }
         // pi's stream is one JSON object per line: a torn, non-JSON, or valid-JSON-scalar line is
         // noise, not an event — parseJsonObject reads it as no data (the same policy parseEventLine
         // applies to the harness event log and parsePiEventLine applies to pi's log lines) instead
@@ -355,6 +345,37 @@ export class PiStreamParser {
         if (!parsed)
             return; // Non-JSON noise on stdout; ignore.
         const event = parsed;
+        this.applyErrorTexts(event);
+        this.applyRunCost(event);
+        this.applyRunUsage(event);
+        // A canonical rate_limit event carries an account-window reading: collect the newest per
+        // type, note any overage, and treat a rejected window as the transient rate limit it is.
+        if (event.type === "rate_limit")
+            this.applyRateLimit(event);
+        if (event.type === "billing" && (event.billing === "subscription" || event.billing === "api"))
+            this.billing = event.billing;
+        this.countProgress(event);
+        this.applyToolExecution(event);
+        if (event.type !== "message_end" || event.message?.role !== "assistant")
+            return;
+        this.applyAssistantMessage(event.message);
+    }
+    // Streaming deltas are ~72% of log bytes in observed runs. pi's JSON protocol strips the
+    // cumulative message snapshot from them, so the delta event is all they carry — and a
+    // content-free one (a zombie stream's keepalive, or the pre-strip shape) proves nothing:
+    // it must not reset the hang watchdog. A content-bearing delta is real generation, and
+    // counting it is what keeps a long thinking block on a slow model from being quiet-killed
+    // as hung (BUGS.md 2026-10-17) — the same content rule tool_execution_update gets below.
+    // Nothing else in this parser acts on the type, so the line is done either way.
+    applyMessageUpdate(line) {
+        if (piEventType(line) === "message_update") {
+            if (messageUpdateHasContent(parseJsonObject(line)))
+                this.progressCount += 1;
+            return true;
+        }
+        return false;
+    }
+    applyErrorTexts(event) {
         // A translator-classified error (claude's `tumwaterKind`) is trusted before the text
         // regexes: the backend read schemas, not prose, and its signal wins.
         if (typeof event.tumwaterKind === "string" && event.tumwaterKind) {
@@ -389,19 +410,23 @@ export class PiStreamParser {
                 }
             }
         }
-        // A canonical run_cost is the run's authoritative cost and REPLACES the per-message sum
-        // (claude's split-block messages report cost.total 0; the final result carries the real
-        // number). A backend that emits none keeps the summed per-message figure (pi).
+    }
+    // A canonical run_cost is the run's authoritative cost and REPLACES the per-message sum
+    // (claude's split-block messages report cost.total 0; the final result carries the real
+    // number). A backend that emits none keeps the summed per-message figure (pi).
+    applyRunCost(event) {
         if (event.type === "run_cost")
             this.costUsd = usageNumber(event.total);
-        // Likewise a run_usage replaces the summed per-message token figures (claude's per-message
-        // usage is the stream-start snapshot, about 8x low). OpenCode's export drives a run_usage
-        // that carries the run's whole token split — input, output, cacheRead, cacheWrite — and
-        // replaces all four summed fields, the way run_cost replaces the cost sum; a stream without
-        // one keeps its summed figures. A run_usage bearing only outputTokens (claude) keeps the
-        // historical behavior of replacing just the output sum. The split's sum is a cumulative RUN
-        // total, not a single request, so it never touches peakContextTokens (a per-request peak
-        // the stream keeps computing); the export carries no total and none is invented here.
+    }
+    // Likewise a run_usage replaces the summed per-message token figures (claude's per-message
+    // usage is the stream-start snapshot, about 8x low). OpenCode's export drives a run_usage
+    // that carries the run's whole token split — input, output, cacheRead, cacheWrite — and
+    // replaces all four summed fields, the way run_cost replaces the cost sum; a stream without
+    // one keeps its summed figures. A run_usage bearing only outputTokens (claude) keeps the
+    // historical behavior of replacing just the output sum. The split's sum is a cumulative RUN
+    // total, not a single request, so it never touches peakContextTokens (a per-request peak
+    // the stream keeps computing); the export carries no total and none is invented here.
+    applyRunUsage(event) {
         if (event.type === "run_usage") {
             if (event.input !== undefined || event.cacheRead !== undefined || event.cacheWrite !== undefined) {
                 const input = usageNumber(event.input);
@@ -416,26 +441,24 @@ export class PiStreamParser {
                 this.outputTokens = usageNumber(event.outputTokens);
             }
         }
-        // A canonical rate_limit event carries an account-window reading: collect the newest per
-        // type, note any overage, and treat a rejected window as the transient rate limit it is.
-        if (event.type === "rate_limit")
-            this.applyRateLimit(event);
-        if (event.type === "billing" && (event.billing === "subscription" || event.billing === "api"))
-            this.billing = event.billing;
-        // Every structured event (turn/tool/message boundaries, retries, session) is real
-        // progress, and so is a content-bearing update — but a content-free one never is: bash
-        // emits an empty tool_execution_update right after start, and a zombie stream's keepalive
-        // updates must not reset the hang watchdog any more than a content-free message delta
-        // would (message_update deltas are counted above, before this point, by the same rule).
+    }
+    // Every structured event (turn/tool/message boundaries, retries, session) is real
+    // progress, and so is a content-bearing update — but a content-free one never is: bash
+    // emits an empty tool_execution_update right after start, and a zombie stream's keepalive
+    // updates must not reset the hang watchdog any more than a content-free message delta
+    // would (message_update deltas are counted above, before this point, by the same rule).
+    countProgress(event) {
         if (!(event.type === "tool_execution_update" && !toolUpdateHasContent(event.partialResult)))
             this.progressCount += 1;
         if (event.type === "compaction_start")
             this.compacted = true;
-        // Open-tool-call tracking for the stall warning: a call that sits open and silent is
-        // surfaced by name while the quiet watchdog still counts down. The start/update/end state
-        // machine lives in applyToolExecutionEvent, shared with the dashboards' live flag
-        // (src/ui/progress-data.ts); only the label is surface-specific — the warning names the
-        // command even when pi omits a toolName, where progress falls back to "tool".
+    }
+    // Open-tool-call tracking for the stall warning: a call that sits open and silent is
+    // surfaced by name while the quiet watchdog still counts down. The start/update/end state
+    // machine lives in applyToolExecutionEvent, shared with the dashboards' live flag
+    // (src/ui/progress-data.ts); only the label is surface-specific — the warning names the
+    // command even when pi omits a toolName, where progress falls back to "tool".
+    applyToolExecution(event) {
         if (event.type === "tool_execution_start" ||
             event.type === "tool_execution_update" ||
             event.type === "tool_execution_end") {
@@ -468,9 +491,8 @@ export class PiStreamParser {
                 }
             }
         }
-        if (event.type !== "message_end" || event.message?.role !== "assistant")
-            return;
-        const msg = event.message;
+    }
+    applyAssistantMessage(msg) {
         const text = messageText(msg);
         this.finalMessageContentless = !messageContent(msg).some((c) => c.type === "toolCall" ||
             (c.type === "text" && typeof c.text === "string" && Boolean(c.text.trim())));

package/dist/src/pi/pi-watchdogs.js

@@ -7,18 +7,10 @@
  * handler reads back; run-agent.ts feeds the parser live through the deps accessors, so no
  * notification path is needed when events land. */
 import { bufferedCommandStallMs, callBuffersOutput } from "./command-shape.js";
-/** Start one pi run's two watchdog clocks: the run deadline (kills the process tree when it
- * fires, recording whether the run was still progressing) and the quiet/stall interval
- * (quiet-kills a run that stopped making progress and warns on stalled tool calls). Returns
- * the live flags the run's close handler reads and the note/stop calls its data handlers and
- * settle path make. */
-export function startPiWatchdogs(deps) {
-    let lastProgressAt = Date.now();
-    let lastProgressCount = 0;
-    let sawOutput = false;
-    let timedOut = false;
-    let timedOutProgressing = false;
-    let quietKilled = false;
+/** The run-deadline clock: kills the process tree when it fires, after giving a
+ * progressing gate run one extension, and records whether the run was still progressing
+ * (BUGS.md 2026-09-29, 2026-10-09, 2026-10-07). */
+function startDeadlineWatch(state, deps) {
     // A gate run earns one deadline extension while it is still making progress, so a large
     // diff's review can finish instead of timing out mid-verification and being re-read from
     // scratch on the next attempt (BUGS.md 2026-10-07). "Still making progress" means a
@@ -37,26 +29,28 @@ export function startPiWatchdogs(deps) {
     // checkpoint covers the extension test and the kill's classification, so the two cannot
     // disagree, and re-arming it for the extended deadline keeps the bar at `progressWindowMs`
     // before whichever deadline finally fires.
-    let checkpoint;
     const armCheckpoint = (deadlineMs) => {
-        clearTimeout(checkpoint);
-        checkpoint = setTimeout(() => {
+        clearTimeout(state.checkpoint);
+        state.checkpoint = setTimeout(() => {
             checkpointProgress = deps.progressCount();
         }, Math.max(0, deadlineMs - progressWindowMs));
     };
     armCheckpoint(deps.runTimeoutMs);
+    // One short beat the deadline gives a run that has begun producing progress but whose
+    // count was flat at fire time: time for a drain-delayed run's output to land before the
+    // discard (BUGS.md 2026-10-26).
+    const progressGraceMs = 250;
     let extended = false;
-    let timeoutBudgetMs = deps.runTimeoutMs;
-    let timeout;
+    let graceArmed = false; // one grace per deadline, so a genuinely stalled run is never granted two
+    state.timeoutBudgetMs = deps.runTimeoutMs;
     const fireDeadline = () => {
         if (deps.extendOnProgress && !extended && deps.progressCount() > checkpointProgress) {
             extended = true;
-            timeoutBudgetMs = deps.runTimeoutMs * 2;
+            state.timeoutBudgetMs = deps.runTimeoutMs * 2;
             armCheckpoint(deps.runTimeoutMs); // the extended deadline gets its own progress window
-            timeout = setTimeout(fireDeadline, deps.runTimeoutMs); // one more slice; the next firing is final
+            state.timeout = setTimeout(fireDeadline, deps.runTimeoutMs); // one more slice; the next firing is final
             return;
         }
-        timedOut = true;
         // A deadline that fires on a run still making progress killed a slow run, not a hung
         // one: "recent progress" is progress since the checkpoint `progressWindowMs` before this
         // deadline — the same window the extension test uses, so the kill's classification
@@ -64,10 +58,30 @@ export function startPiWatchdogs(deps) {
         // budget (BUGS.md 2026-09-29, 2026-10-09). A run with no progress event at all — never
         // emitted a byte, or bytes without one structured event — keeps today's discard path: it
         // has not demonstrably begun.
-        timedOutProgressing = deps.progressCount() > 0 && deps.progressCount() > checkpointProgress;
+        //
+        // The checkpoint comparison can mis-classify a run that IS still emitting: the checkpoint
+        // and this deadline can fire in the same drain (a firing timers phase precedes the poll
+        // phase that delivers stdout), so on a main-thread stall both read the same already-final
+        // count and a progressing run looks stalled (BUGS.md 2026-10-26). A run that has begun
+        // producing structured progress therefore gets ONE short grace to drain queued output and
+        // re-prove itself; only a run still flat after the grace — or one that never progressed —
+        // keeps the discard path. The grace is one-shot, so a genuinely stalled run is not
+        // granted a second chance.
+        if (!graceArmed && deps.progressCount() > 0) {
+            graceArmed = true;
+            state.timeout = setTimeout(fireDeadline, progressGraceMs);
+            return;
+        }
+        state.timedOut = true;
+        state.timedOutProgressing = deps.progressCount() > 0 && deps.progressCount() > checkpointProgress;
         deps.kill();
     };
-    timeout = setTimeout(fireDeadline, deps.runTimeoutMs);
+    state.timeout = setTimeout(fireDeadline, deps.runTimeoutMs);
+}
+/** The quiet/stall clock: quiet-kills a run that stopped making progress and warns on
+ * stalled tool calls, on one interval against the wall clock (BUGS.md 2026-09-23,
+ * 2026-09-28, 2026-09-29, 2026-10-06). */
+function startQuietWatch(state, deps) {
     // Quiet watchdog: a healthy run makes PROGRESS continuously even when slow — messages
     // start and end, turns and tool calls complete. Prolonged lack of progress means a hung
     // tool (an interactive command waiting for input) or a zombie stream (a dead generation
@@ -100,7 +114,7 @@ export function startPiWatchdogs(deps) {
     // begun; bytes without progress keep the doubled window (the zombie-stream case), and
     // once real progress has landed quietTimeoutSeconds applies unchanged.
     const zeroByteSilenceMs = Math.max(deps.quietMs * 2, 30 * 60_000);
-    const allowedSilenceMs = () => deps.progressCount() > 0 ? deps.quietMs : sawOutput ? deps.quietMs * 2 : zeroByteSilenceMs;
+    const allowedSilenceMs = () => deps.progressCount() > 0 ? deps.quietMs : state.sawOutput ? deps.quietMs * 2 : zeroByteSilenceMs;
     // The stall warning's threshold (distinct from the kill above): one hung tool call is
     // surfaced by name even while sibling calls keep streaming, so total silence is not
     // required. One warning per stalled call — the interval keeps firing until the kill or
@@ -149,48 +163,69 @@ export function startPiWatchdogs(deps) {
         }
     };
     const checkEveryMs = deps.quietMs > 0 ? deps.quietMs : deps.stallMs;
-    const quietCheck = checkEveryMs > 0
-        ? setInterval(() => {
-            if (deps.progressCount() > lastProgressCount) {
-                lastProgressCount = deps.progressCount();
-                lastProgressAt = Date.now();
-            }
-            else if (deps.quietMs > 0 && Date.now() - lastProgressAt > allowedSilenceMs()) {
-                quietKilled = true;
-                deps.kill();
-            }
-            if (deps.stallMs > 0)
-                warnStalledToolCalls();
-        }, Math.min(Math.max(checkEveryMs / 2, 250), 30_000))
-        : undefined;
+    state.quietCheck =
+        checkEveryMs > 0
+            ? setInterval(() => {
+                if (deps.progressCount() > state.lastProgressCount) {
+                    state.lastProgressCount = deps.progressCount();
+                    state.lastProgressAt = Date.now();
+                }
+                else if (deps.quietMs > 0 && Date.now() - state.lastProgressAt > allowedSilenceMs()) {
+                    state.quietKilled = true;
+                    deps.kill();
+                }
+                if (deps.stallMs > 0)
+                    warnStalledToolCalls();
+            }, Math.min(Math.max(checkEveryMs / 2, 250), 30_000))
+            : undefined;
+}
+/** Start one pi run's two watchdog clocks: the run deadline (kills the process tree when it
+ * fires, recording whether the run was still progressing) and the quiet/stall interval
+ * (quiet-kills a run that stopped making progress and warns on stalled tool calls). Returns
+ * the live flags the run's close handler reads and the note/stop calls its data handlers and
+ * settle path make. */
+export function startPiWatchdogs(deps) {
+    const state = {
+        lastProgressAt: Date.now(),
+        lastProgressCount: 0,
+        sawOutput: false,
+        timedOut: false,
+        timedOutProgressing: false,
+        quietKilled: false,
+        timeoutBudgetMs: deps.runTimeoutMs,
+    };
+    // Each watchdog owns its own timer and the rule it enforces: the deadline/extension rule
+    // and the quiet/stall rule are each found by name here, and `stop` clears all three below.
+    startDeadlineWatch(state, deps);
+    startQuietWatch(state, deps);
     return {
         get timedOut() {
-            return timedOut;
+            return state.timedOut;
         },
         get timeoutBudgetMs() {
-            return timeoutBudgetMs;
+            return state.timeoutBudgetMs;
         },
         get timedOutProgressing() {
-            return timedOutProgressing;
+            return state.timedOutProgressing;
         },
         get quietKilled() {
-            return quietKilled;
+            return state.quietKilled;
         },
         get sawOutput() {
-            return sawOutput;
+            return state.sawOutput;
         },
         noteByte() {
-            sawOutput = true; // any byte ends the starting phase, progress or not
+            state.sawOutput = true; // any byte ends the starting phase, progress or not
         },
         noteStderr() {
-            sawOutput = true;
-            lastProgressAt = Date.now();
+            state.sawOutput = true;
+            state.lastProgressAt = Date.now();
         },
         stop() {
-            clearTimeout(timeout);
-            clearTimeout(checkpoint);
-            if (quietCheck)
-                clearInterval(quietCheck);
+            clearTimeout(state.timeout);
+            clearTimeout(state.checkpoint);
+            if (state.quietCheck)
+                clearInterval(state.quietCheck);
         },
     };
 }

package/dist/src/pi-extension/context-shake.js

@@ -179,43 +179,67 @@ export function shakePlan(messages, usage, writeFullOutput) {
 export function shakeNote(elidedCount, reclaimedTokens) {
     return `[tumwater: elided ${elidedCount} old tool results (~${compactTokens(reclaimedTokens)} tokens); each pointer says where the full text is]`;
 }
+/** Records the tool-call parts of an assistant message by id, so a later tool result can find
+ * its matching call. */
+function recordToolCalls(msg, calls) {
+    if (msg.role !== "assistant" || !Array.isArray(msg.content))
+        return;
+    for (const part of msg.content) {
+        if (part?.type === "toolCall" && typeof part.id === "string")
+            calls.set(part.id, part);
+    }
+}
+/** Resolves the read-input pointer (file:range) from a matching tool call, when it was a read. */
+function readInputFor(call) {
+    if (call?.name === "read") {
+        return {
+            path: call.arguments?.path,
+            offset: call.arguments?.offset,
+            limit: call.arguments?.limit,
+        };
+    }
+    return undefined;
+}
+/** Copies a tool result's fields (toolName, toolCallId, isError, fullOutputPath, readInput) onto
+ * the message from the recorded calls. */
+function applyToolResultFields(message, msg, calls) {
+    if (msg.role === "toolResult") {
+        if (msg.toolName)
+            message.toolName = msg.toolName;
+        if (msg.toolCallId)
+            message.toolCallId = msg.toolCallId;
+        if (msg.isError !== undefined)
+            message.isError = msg.isError;
+        if (msg.details?.fullOutputPath)
+            message.fullOutputPath = msg.details.fullOutputPath;
+        const call = msg.toolCallId ? calls.get(msg.toolCallId) : undefined;
+        const readInput = readInputFor(call);
+        if (readInput)
+            message.readInput = readInput;
+    }
+}
+/** Assembles one message's fields (text, entry id, role, then its tool-result fields). */
+function buildShakeMessage(msg, entryId, calls) {
+    const message = { text: textOf(msg) };
+    if (entryId)
+        message.entryId = entryId;
+    if (msg.role)
+        message.role = msg.role;
+    applyToolResultFields(message, msg, calls);
+    return message;
+}
 /** Flatten a turn_end event's projected context into the ordered messages the planner reads,
- * mapping each assistant tool call's input onto the tool result it produced. */
+ * mapping each assistant tool call's input onto the tool result it produced. The per-job work
+ * lives in the named helpers `recordToolCalls`, `readInputFor`, `applyToolResultFields` and
+ * `buildShakeMessage`; this function is their composition. */
 export function shakeMessages(event) {
     const calls = new Map();
     const out = [];
     for (const entry of event.context?.contextEntries ?? []) {
+        const entryId = entry.sourceEntry?.id;
         for (const msg of entry.messages ?? []) {
-            if (msg.role === "assistant" && Array.isArray(msg.content)) {
-                for (const part of msg.content) {
-                    if (part?.type === "toolCall" && typeof part.id === "string")
-                        calls.set(part.id, part);
-                }
-            }
-            const message = { text: textOf(msg) };
-            if (entry.sourceEntry?.id)
-                message.entryId = entry.sourceEntry.id;
-            if (msg.role)
-                message.role = msg.role;
-            if (msg.role === "toolResult") {
-                if (msg.toolName)
-                    message.toolName = msg.toolName;
-                if (msg.toolCallId)
-                    message.toolCallId = msg.toolCallId;
-                if (msg.isError !== undefined)
-                    message.isError = msg.isError;
-                if (msg.details?.fullOutputPath)
-                    message.fullOutputPath = msg.details.fullOutputPath;
-                const call = msg.toolCallId ? calls.get(msg.toolCallId) : undefined;
-                if (call?.name === "read") {
-                    message.readInput = {
-                        path: call.arguments?.path,
-                        offset: call.arguments?.offset,
-                        limit: call.arguments?.limit,
-                    };
-                }
-            }
-            out.push(message);
+            recordToolCalls(msg, calls);
+            out.push(buildShakeMessage(msg, entryId, calls));
         }
     }
     return out;

package/dist/src/pi-extension/full-output.js

@@ -11,10 +11,9 @@
  * side effects it must not grow. pi itself loads the bundled extensions, so this stays
  * dependency-free beyond node built-ins and the path helper.
  */
-import fs from "node:fs";
 import path from "node:path";
 import { toolOutputDir } from "../paths.js";
-import { isDirectory, walkUp, writeTextAtomic } from "../files/files.js";
+import { ensureDir, isDirectory, walkUp, writeTextAtomic } from "../files/files.js";
 /** Walk up from `startDir` looking for a `.tumwater/` directory — the harness root. Worktrees
  * under it (`.tumwater/worktrees/<role>`, merger, gate alike) reach it three levels up
  * (`../../..`, the repo checkout that owns `.tumwater/`); a harness root carries it directly.
@@ -41,7 +40,7 @@ export function writeFullOutput(text, toolCallId, startDir = process.cwd()) {
         return null;
     try {
         const dir = toolOutputDir(root);
-        fs.mkdirSync(dir, { recursive: true });
+        ensureDir(dir);
         const id = typeof toolCallId === "string" && toolCallId
             ? toolCallId.replace(/[^\w-]/g, "_")
             : `result-${Date.now()}`;

package/dist/src/process/process.js

@@ -24,7 +24,7 @@ export function execFileAsync(file, args, options = {}) {
  * added after the abort event never fires, so `addEventListener` alone would leave the caller
  * waiting on a shutdown that has come and gone. A missing signal (no shutdown wiring)
  * registers nothing. Shared by spawnSupervised (supervisor.ts), runPi's child spawn
- * (src/agent/run-agent.ts), sleepInterruptible (run-timing.ts), and abortOnShutdown
+ * (src/agent/run-spawn.ts), sleepInterruptible (run-timing.ts), and abortOnShutdown
  * (merge-pipeline.ts).
  *
  * Returns a disposer that detaches `fn`. A `{ once: true }` listener detaches itself when the
@@ -65,6 +65,29 @@ export function pidAlive(pid) {
         return false;
     }
 }
+/** The identity of the live process on `pid`, or null when no process of ours answers for it —
+ * a non-positive or non-integer pid, a reaped pid, or a pid the probe cannot read (a foreign
+ * process `ps` will not disclose, or a host whose ps lacks `lstart`). Null reads as "not
+ * alive" to `identityAlive`, so the reap checks' bounded poll reports only a genuine hang. */
+export async function pidIdentity(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return null;
+    try {
+        const { stdout } = await execFileAsync("ps", ["-o", "lstart=", "-p", String(pid)]);
+        const start = stdout.trim();
+        return start.length > 0 ? { pid, start } : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** True when the process instance `id` names is still alive: the pid answers and the OS still
+ * reports the same start time. A reaped pid (no answer), a pid reused by a different process
+ * (a different start), or null reads as not alive. */
+export async function identityAlive(id) {
+    const now = await pidIdentity(id.pid);
+    return now !== null && now.start === id.start;
+}
 /** Terminate a detached child and everything it started: SIGTERM to the process group now,
  * escalating to SIGKILL after 10 s if any of it is still alive. The child is spawned detached
  * (its own process group leader — runPi does this for pi), so a negative PID reaches every

package/dist/src/process/run-marker.js

@@ -4,7 +4,7 @@
  * probe's runMarkers check and doctor's orphan judgment), and the sweep that SIGTERMs
  * this run's leftovers whatever process group they ended up in. Split out of
  * process-table.ts — which keeps the doctor-facing probe interface and the ps/lsof/top
- * parsing it is made of — because this half serves src/agent/run-agent.ts's run stamping and
+ * parsing it is made of — because this half serves src/agent/run-spawn.ts's run stamping and
  * the exit sweep, and shares none of the probe's table-parsing concerns; the probe reads marks
  * through the same parsers exported here. */
 import crypto from "node:crypto";
@@ -43,7 +43,7 @@ export function runMarkerEnv(base, marker) {
  * check-in preload removed (`withoutLaunchServicesCheckIn`) and this run's marker appended
  * (`runMarkerEnv`). All three adapters (pi, claude, opencode) layer their own settings on
  * top, so the composition lives here rather than being re-derived in each. `binDir`, when
- * given, is prepended to PATH — run-agent passes the notes shim dir (notesShimDir) so every
+ * given, is prepended to PATH — run-spawn passes the notes shim dir (notesShimDir) so every
  * run finds the `tumwater-notes` command first (plans/notes-command.md "Reaching it from a
  * run"). */
 export function backendBaseEnv(marker, base = process.env, binDir) {

package/dist/src/process/supervisor.js

@@ -3,6 +3,7 @@ import { TUMWATER_SOURCE } from "../events/events.js";
 import { RESTART_EXIT_CODE } from "../redeploy/redeploy-policy.js";
 import { childEnv, runOnAbort } from "./process.js";
 import { liveNodeBin } from "./node-bin.js";
+import { parsePositiveInt } from "../text/text.js";
 /** The respawn loop behind `tumwater start`. The command runs as two processes: this supervisor
  * (the one the operator started, holding the terminal) and a child that runs the orchestrator.
  * When the child rebuilt dist/ onto a newer main (src/redeploy/redeployer.ts) it exits
@@ -49,9 +50,22 @@ function intervalPoll(intervalMs) {
  * disarms the watch (a no-op once it fired or was already stopped). */
 export function startParentDeathWatch(onGone, opts = {}) {
     const ppid = opts.ppid ?? (() => process.ppid);
-    const original = opts.expectedPpid ?? ppid();
+    const expectedGiven = opts.expectedPpid !== undefined;
+    const original = expectedGiven ? opts.expectedPpid : ppid();
     let cancel;
     let fired = false;
+    // No expectation was handed down, so the baseline is the watch's own first read. A first
+    // read of 1 (PID 1 — launchd/init, never a real parent) means the process was already
+    // reparented before the watch armed: the shell that started it exited before this child's
+    // first ppid read, the detached-`&` leak. There is no distinct parent left to watch, so
+    // the child is already orphaned — fire immediately instead of pinning the baseline to 1,
+    // where the watch could never observe a change. This is the same route the follow
+    // commands' parent-death rule closes: a follow that cannot see a distinct parent ends now.
+    if (!expectedGiven && original === 1) {
+        fired = true;
+        onGone();
+        return () => { };
+    }
     // Release the poll at most once: a fired watch, or an explicit stop, must leave nothing armed.
     const release = () => {
         const stopPoll = cancel;
@@ -59,6 +73,9 @@ export function startParentDeathWatch(onGone, opts = {}) {
         stopPoll?.();
     };
     const check = () => {
+        // When an expectation was handed down, the first read may legitimately equal it even
+        // when the parent is already gone (the expected pid is compared, not the first read);
+        // otherwise the baseline IS the first read, so only a later change fires the watch.
         if (fired || ppid() === original)
             return;
         fired = true;
@@ -78,11 +95,13 @@ export function startParentDeathWatch(onGone, opts = {}) {
     };
 }
 /** The supervisor pid a supervised child was handed, or undefined when the mark is absent or
- * names no process (a number that is not an integer, or 1 — launchd/init, never a supervisor):
- * the watch's own first read stands instead. */
+ * names no process (a hex/exponent/whitespace spelling, or 1 — launchd/init, never a supervisor):
+ * the watch's own first read stands instead. The mark is written as String(process.pid) (plain
+ * decimal), so it is read by the shared plain-decimal rule, not Number()'s silent coercion. */
 export function expectedSupervisorPid(env = process.env) {
-    const pid = Number(env[SUPERVISOR_PID_ENV]);
-    return Number.isInteger(pid) && pid > 1 ? pid : undefined;
+    const mark = env[SUPERVISOR_PID_ENV];
+    const pid = mark === undefined ? null : parsePositiveInt(mark);
+    return pid !== null && pid > 1 ? pid : undefined;
 }
 /** Respawns within this window count toward the crash-loop guard. */
 export const RESPAWN_WINDOW_MS = 60_000;