tumwater 0.4.2 → 0.4.4

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

@@ -1,5 +1,5 @@
 import { extractRefusal, hasVerdictLine, isNegatedRefusal, isNothingToDo } from "../verdict/reply-contract.js";
-import { applyToolExecutionEvent, messageUpdateHasContent, piEventType, toolCallCommand, toolUpdateHasContent, } from "./pi-event-line.js";
+import { applyToolExecutionEvent, foldPendingReply, messageUpdateHasContent, piEventType, toolCallCommand, toolUpdateHasContent, } from "./pi-event-line.js";
 import { describeToolCall } from "../text/phrases.js";
 import { objectOrEmpty, nonNegativeNumber, parseJsonObject, isJsonObject } from "../files/json-object.js";
 import { backendKind, isBackendFailureKind, isPermanentConfigError, TRANSIENT_BACKEND } from "./pi-failure.js";
@@ -204,6 +204,10 @@ export class PiStreamParser {
      * empty-content update right after start, and a content-free keepalive must not mask a hang.
      * Feeds runPi's stall warning; entries clear at tool_execution_end. */
     openToolCalls = [];
+    /** The model request pi has sent and the provider has not yet answered (see PendingReply), or
+     * undefined. Feeds runPi's unanswered-request warning; stamped with this parser's clock, since
+     * it observes the request live. */
+    pendingReply = undefined;
     /** Read tool calls started but not yet ended, keyed by pi's toolCallId so concurrent reads
      * attribute their end to the right start (pi runs one message's tool calls concurrently, so
      * several can be open at once and end in completion order — the same rule
@@ -251,6 +255,17 @@ export class PiStreamParser {
      * treat a `rejected` window as the transient rate limit it is (with the resetsAt-derived
      * wait the translator attached). */
     applyRateLimit(event) {
+        const reading = this.readRateWindow(event);
+        this.upsertRateWindow(reading);
+        if (reading.status === "rejected") {
+            this.transientRateLimit = true;
+            this.setRetryAfterSeconds(event.retryAfterSeconds);
+        }
+    }
+    /** Build one `RateWindow` reading from a canonical `rate_limit` event: derive the `type`
+     * (falling back to `unknown` when pi names none), default the `status` to "" when absent,
+     * and copy through the four optional fields that the event carries. */
+    readRateWindow(event) {
         const type = typeof event.rateLimitType === "string" && event.rateLimitType ? event.rateLimitType : "unknown";
         const reading = { type, status: typeof event.status === "string" ? event.status : "" };
         if (typeof event.resetsAt === "number" && Number.isFinite(event.resetsAt))
@@ -261,9 +276,16 @@ export class PiStreamParser {
             reading.overageStatus = event.overageStatus;
         if (event.isUsingOverage === true)
             reading.isUsingOverage = true;
-        const existing = this.rateWindows.findIndex((w) => w.type === type);
+        return reading;
+    }
+    /** Insert one reading, keeping the newest per type: replace the window whose `type` matches
+     * and, when the reading is status-less (a non-binding window's utilization), carry the last
+     * known status of the window it replaces; note overage so a caller can see a rate limit hit
+     * even before it is rejected. */
+    upsertRateWindow(reading) {
+        const existing = this.rateWindows.findIndex((w) => w.type === reading.type);
         // A reading without a status (a non-binding window's utilization) keeps the last known one.
-        if (reading.status === "" && existing >= 0)
+        if (reading.status === "")
             reading.status = this.rateWindows[existing]?.status ?? "";
         if (existing >= 0)
             this.rateWindows[existing] = reading;
@@ -271,10 +293,6 @@ export class PiStreamParser {
             this.rateWindows.push(reading);
         if (reading.isUsingOverage === true)
             this.usedOverage = true;
-        if (reading.status === "rejected") {
-            this.transientRateLimit = true;
-            this.setRetryAfterSeconds(event.retryAfterSeconds);
-        }
     }
     /** Fold a provider Retry-After hint into `retryAfterSeconds`: ignore a non-number or
      * non-finite value, and clamp a negative or fractional one to whole seconds. */
@@ -355,6 +373,7 @@ export class PiStreamParser {
         if (event.type === "billing" && (event.billing === "subscription" || event.billing === "api"))
             this.billing = event.billing;
         this.countProgress(event);
+        this.pendingReply = foldPendingReply(this.pendingReply, event);
         this.applyToolExecution(event);
         if (event.type !== "message_end" || event.message?.role !== "assistant")
             return;
@@ -369,8 +388,10 @@ export class PiStreamParser {
     // 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)))
+            const hasContent = messageUpdateHasContent(parseJsonObject(line));
+            if (hasContent)
                 this.progressCount += 1;
+            this.pendingReply = foldPendingReply(this.pendingReply, { type: "message_update" }, { hasContent });
             return true;
         }
         return false;
@@ -494,6 +515,12 @@ export class PiStreamParser {
     }
     applyAssistantMessage(msg) {
         const text = messageText(msg);
+        this.applyAssistantReply(msg, text);
+        this.applyAssistantRefusal(text);
+        this.applyAssistantUsage(msg);
+        this.applyAssistantStop(msg);
+    }
+    applyAssistantReply(msg, text) {
         this.finalMessageContentless = !messageContent(msg).some((c) => c.type === "toolCall" ||
             (c.type === "text" && typeof c.text === "string" && Boolean(c.text.trim())));
         if (!this.finalMessageContentless)
@@ -502,6 +529,8 @@ export class PiStreamParser {
             this.finalText = text;
         if (isNothingToDo(text))
             this.declaredNothingToDo = true;
+    }
+    applyAssistantRefusal(text) {
         // The refusal comes only from an anchored `TUMWATER_REFUSED: <reason>` line: a bare
         // sentinel and a mid-sentence mention are not refusals, and a negating reason ("none",
         // "(n/a …)") clears one — BUGS.md 2026-09-23, four runs ended ordinary replies with
@@ -521,6 +550,8 @@ export class PiStreamParser {
         }
         if (hasVerdictLine(text))
             this.verdictText = text;
+    }
+    applyAssistantUsage(msg) {
         this.turns += 1;
         this.outputTokens += usageNumber(msg.usage?.output);
         const promptTokens = usageNumber(msg.usage?.input) + usageNumber(msg.usage?.cacheRead) + usageNumber(msg.usage?.cacheWrite);
@@ -536,6 +567,8 @@ export class PiStreamParser {
         }
         this.peakContextTokens = Math.max(this.peakContextTokens, usageNumber(msg.usage?.totalTokens));
         this.costUsd += usageNumber(msg.usage?.cost?.total);
+    }
+    applyAssistantStop(msg) {
         this.stopReason = msg.stopReason;
         if (msg.errorMessage)
             this.errorMessage = msg.errorMessage;

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

@@ -1,10 +1,11 @@
 /** The run's watchdog clocks, split out of pi.ts's runPi (2026-10-04, organize): the run
- * deadline and the quiet watchdog (quiet-kill plus the stalled-tool-call warning) — the
+ * deadline and the quiet watchdog (quiet-kill plus the stalled-tool-call and
+ * unanswered-model-request warnings) — the
  * timing policy of one pi run, which changes for different reasons than the spawn, stream,
- * and result-distillation wiring that drives it (src/agent/run-agent.ts keeps those). The
+ * and result-distillation wiring that drives it (src/agent/agent-run.ts keeps those). The
  * factory owns all the mutable state the two timers kept in runPi's closure (the progress
  * window, the zero-byte grace, the warned-call set) and exposes the flags the run's close
- * handler reads back; run-agent.ts feeds the parser live through the deps accessors, so no
+ * handler reads back; agent-run.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";
 /** The run-deadline clock: kills the process tree when it fires, after giving a
@@ -41,7 +42,9 @@ function startDeadlineWatch(state, deps) {
     // discard (BUGS.md 2026-10-26).
     const progressGraceMs = 250;
     let extended = false;
-    let graceArmed = false; // one grace per deadline, so a genuinely stalled run is never granted two
+    let graceArmed = false; // one grace for the whole run, so a genuinely stalled run is never granted two
+    // (see the deadline comment below: a run reaches this branch at most once, so per-run and
+    // per-deadline scope grant the same single short re-check)
     state.timeoutBudgetMs = deps.runTimeoutMs;
     const fireDeadline = () => {
         if (deps.extendOnProgress && !extended && deps.progressCount() > checkpointProgress) {
@@ -65,8 +68,13 @@ function startDeadlineWatch(state, deps) {
         // 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.
+        // keeps the discard path. The grace is one short beat, armed once for the whole run:
+        // graceArmed is a closure local of startDeadlineWatch, one per run, and the branch is
+        // reached at most once because a gate run's earlier base deadline is handled by its
+        // one-time extension (the block above) while an authoring run has a single deadline — so
+        // "once per run" and "once per deadline" grant the very same single re-check, and a
+        // progressing gate run is never left without one while a genuinely stalled run is never
+        // granted two.
         if (!graceArmed && deps.progressCount() > 0) {
             graceArmed = true;
             state.timeout = setTimeout(fireDeadline, progressGraceMs);
@@ -78,9 +86,13 @@ function startDeadlineWatch(state, deps) {
     };
     state.timeout = setTimeout(fireDeadline, deps.runTimeoutMs);
 }
+/** Whole minutes read cleaner in the feed; sub-minute thresholds stay in seconds. */
+function silenceLabel(ms) {
+    return ms < 60_000 ? `${Math.round(ms / 1000)}s` : `${Math.round(ms / 60_000)}m`;
+}
 /** 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). */
+ * stalled tool calls and unanswered model requests, on one interval against the wall clock
+ * (BUGS.md 2026-09-23, 2026-09-28, 2026-09-29, 2026-10-06, 2026-10-29). */
 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
@@ -147,21 +159,35 @@ function startQuietWatch(state, deps) {
                 const bufferedStallMs = bufferedCommandStallMs(deps.stallMs);
                 if (openMs >= bufferedStallMs) {
                     warnedStalledCalls.add(call.id);
-                    deps.onToolCallStalled?.(`tool call stalled: ${call.label} — no exit for ${Math.round(openMs / 60_000)}m`);
+                    deps.onStallWarning?.(`tool call stalled: ${call.label} — no exit for ${silenceLabel(openMs)}`);
                 }
                 continue;
             }
             const silentMs = Date.now() - call.lastActivityAt;
             if (silentMs >= deps.stallMs) {
                 warnedStalledCalls.add(call.id);
-                // Whole minutes read cleaner in the feed; sub-minute thresholds stay in seconds.
-                const silent = silentMs < 60_000
-                    ? `${Math.round(silentMs / 1000)}s`
-                    : `${Math.round(silentMs / 60_000)}m`;
-                deps.onToolCallStalled?.(`tool call stalled: ${call.label} — no output for ${silent}`);
+                deps.onStallWarning?.(`tool call stalled: ${call.label} — no output for ${silenceLabel(silentMs)}`);
             }
         }
     };
+    // The unanswered-request warning, the model-side twin of the stall warning: a provider can
+    // accept a request and never answer it (BUGS.md 2026-10-29: deepinfra's DeepSeek-V4.1-Flash
+    // sent plan only SSE keepalives, which pi never surfaces). pi then waits out its own idle
+    // timeout and retries, and each retry is progress to the quiet watchdog, so nothing else
+    // names the hang for hours. Like the stall warning it only warns: a slow local prefill can
+    // legitimately run this long, and pi's own timeout still owns each attempt. One warning per
+    // unanswered stretch, keyed by its start, not one per retry.
+    let warnedReplySince;
+    const warnUnansweredReply = () => {
+        const pending = deps.pendingReply?.();
+        if (!pending || pending.since === warnedReplySince)
+            return;
+        const waitedMs = Date.now() - pending.since;
+        if (waitedMs < deps.stallMs)
+            return;
+        warnedReplySince = pending.since;
+        deps.onStallWarning?.(`model request unanswered: ${pending.target || "model"} — no reply for ${silenceLabel(waitedMs)}`);
+    };
     const checkEveryMs = deps.quietMs > 0 ? deps.quietMs : deps.stallMs;
     state.quietCheck =
         checkEveryMs > 0
@@ -174,8 +200,10 @@ function startQuietWatch(state, deps) {
                     state.quietKilled = true;
                     deps.kill();
                 }
-                if (deps.stallMs > 0)
+                if (deps.stallMs > 0) {
                     warnStalledToolCalls();
+                    warnUnansweredReply();
+                }
             }, Math.min(Math.max(checkEveryMs / 2, 250), 30_000))
             : undefined;
 }

package/dist/src/pi/pi.js

@@ -1,9 +1,9 @@
-/** The pi-side facade over the backend-neutral agent runner (src/agent/run-agent.ts) and the
+/** The pi-side facade over the backend-neutral agent runner (src/agent/agent-run.ts) and the
  * pi adapter (src/pi/pi-backend.ts). `runPi` is a thin alias for `runAgent` so every existing
  * call site, fake, and test keeps importing the historical name; the stderr-match constants and
  * the run-kind/backend-failure types stay here for the same reason. The seam itself lives in
  * src/agent/agent-backend.ts, and `hasResumableSession` now lives beside the ledger it reads
  * (src/agent/session-ledger.ts) and is re-exported here so existing importers are unchanged. */
-export { runAgent, runPi } from "../agent/run-agent.js";
+export { runAgent, runPi } from "../agent/agent-run.js";
 export { MODEL_FALLBACK_CLONE, TRANSIENT_PI_CRASH } from "./pi-backend.js";
 export { hasResumableSession } from "../agent/session-ledger.js";

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

@@ -130,32 +130,22 @@ function isCandidate(msg, newerTokens, protectedTokens) {
         return false;
     return true;
 }
-/**
- * Plan a shake pass: the `context_edit` replacements that reclaim the most space from old
- * bulky tool results. Empty unless the run is at or above the first pass's percent, something
- * outside the newest protected slice is reclaimable, and the pass clears the reclaim floor
- * together — all three from `shakeLimits` for the usage's window. Deterministic and
- * filesystem-free except the injected
- * `writeFullOutput`, which is only called for a bash result pi has not already persisted.
- */
-export function shakePlan(messages, usage, writeFullOutput) {
-    const percent = percentOf(usage);
-    const limits = shakeLimits(usage.contextWindow);
-    if (percent === null || percent < limits.percent)
-        return EMPTY_PLAN;
-    // Tokens newer than each message, so a candidate is one the model has already moved past.
+/** Tokens newer than each message, so a candidate is one the model has already moved past. */
+function newerTokenCounts(messages) {
     const newerTokens = new Array(messages.length).fill(0);
     let running = 0;
     for (let i = messages.length - 1; i >= 0; i -= 1) {
         newerTokens[i] = running;
         running += estimateTokens(messages[i]?.text ?? "");
     }
-    const candidates = messages.filter((msg, i) => isCandidate(msg, newerTokens[i] ?? 0, limits.protectedTokens));
-    // The pointer is far shorter than the result it replaces, so the full text's tokens are a
-    // safe upper bound on the reclaim; bail before touching the writer when even that is short.
-    const upperBound = candidates.reduce((sum, msg) => sum + estimateTokens(msg.text), 0);
-    if (upperBound < limits.minReclaimTokens)
-        return EMPTY_PLAN;
+    return newerTokens;
+}
+/** The messages the model has already moved past and can reclaim space from. */
+function reclaimableCandidates(messages, newerTokens, protectedTokens) {
+    return messages.filter((msg, i) => isCandidate(msg, newerTokens[i] ?? 0, protectedTokens));
+}
+/** The edits that reclaim space from one candidate list, and how much they reclaim together. */
+function shakeEdits(candidates, writeFullOutput) {
     const edits = [];
     let reclaimedTokens = 0;
     for (const msg of candidates) {
@@ -171,6 +161,28 @@ export function shakePlan(messages, usage, writeFullOutput) {
         edits.push({ targetId: msg.entryId, toolName: msg.toolName, replacement, reclaimedTokens: reclaimed });
         reclaimedTokens += reclaimed;
     }
+    return { edits, reclaimedTokens };
+}
+/**
+ * Plan a shake pass: the `context_edit` replacements that reclaim the most space from old
+ * bulky tool results. Empty unless the run is at or above the first pass's percent, something
+ * outside the newest protected slice is reclaimable, and the pass clears the reclaim floor
+ * together — all three from `shakeLimits` for the usage's window. Deterministic and
+ * filesystem-free except the injected
+ * `writeFullOutput`, which is only called for a bash result pi has not already persisted.
+ */
+export function shakePlan(messages, usage, writeFullOutput) {
+    const percent = percentOf(usage);
+    const limits = shakeLimits(usage.contextWindow);
+    if (percent === null || percent < limits.percent)
+        return EMPTY_PLAN;
+    const candidates = reclaimableCandidates(messages, newerTokenCounts(messages), limits.protectedTokens);
+    // The pointer is far shorter than the result it replaces, so the full text's tokens are a
+    // safe upper bound on the reclaim; bail before touching the writer when even that is short.
+    const upperBound = candidates.reduce((sum, msg) => sum + estimateTokens(msg.text), 0);
+    if (upperBound < limits.minReclaimTokens)
+        return EMPTY_PLAN;
+    const { edits, reclaimedTokens } = shakeEdits(candidates, writeFullOutput);
     if (reclaimedTokens < limits.minReclaimTokens)
         return EMPTY_PLAN;
     return { edits, reclaimedTokens, elidedCount: edits.length };

package/dist/src/pi-extension/kill-guard.js

@@ -0,0 +1,69 @@
+/**
+ * Bundled pi extension: refuse a `bash` call that kills processes by pattern, next to the write
+ * guard (src/pi-extension/write-guard.ts). Loaded on every pi run via `-e <this file>` from
+ * src/pi/pi-args.ts.
+ *
+ * The run prompt already forbids pattern kills (KILL_BY_PID_RULE, src/prompt/prompt.ts): "Never
+ * kill processes by name or pattern; stop only a process you started, by its PID (`kill $!`)".
+ * But that rule is words, and BUGS.md 2026-10-28 records one agent answering a timed-out test run
+ * with `ps aux | grep test-runner | xargs kill` and a `for p in $(ps …) kill` loop, which reached
+ * every process-table row the pattern matched — the team's own in-flight checks included — and
+ * took them down mid-run. The process table is shared, so none of those kills is provably the
+ * runner's own; `kill $!` and the run's exit sweep are the sanctioned way to stop what it started.
+ *
+ * This is a tool-layer net beside the prompt rule, not a replacement for it. The same `tool_call`
+ * event pi fires for `edit`/`write` fires for `bash`; blocking a call when a handler returns
+ * `{ block: true, reason }` shows the model the reason as the tool's error. The detection is a
+ * heuristic for the common by-pattern shapes — `pkill`/`killall` as a command word, and `ps` or
+ * `pgrep` output fed into `kill` via `xargs` or a `$(ps|pgrep)` substitution — and fails open like
+ * the write guard does: a missed shape under load still leaves the prompt rule and the run's sweep,
+ * and an unexpected failure here lets the call through rather than stopping every bash command of
+ * the run (a broken guard cannot block the team's own checks).
+ */
+/** The refusal shown as the tool's error, naming the safe ways to stop a run's own process. */
+export const PATTERN_KILL_REFUSAL = "kill by pattern is refused: `pkill`/`killall` and `ps`/`pgrep` output fed into `kill` reach every " +
+    "process on the host the pattern matches, the team's own checks included. Stop only a process you " +
+    "started, by its PID: `kill $!` right after backgrounding it — the run's own processes are reaped " +
+    "when the run ends.";
+/** A `pkill` or `killall` spelled as a command word, skipping a line that only mentions them
+ * (built after `echo`/`grep`/`man` etc.). Preceded by a command boundary so `echo pkill x` and a
+ * quoted mention pass while `; pkill x` and `| killall x` are caught. */
+const DIRECT_PATTERN_KILL = /(?:^|[;&|(\n])\s*(?:pkill|killall)(?:\s|$)/;
+/** `ps` or `pgrep` that reads the process table. */
+const READ_PROCESS_TABLE = /\b(?:ps|pgrep)\b/;
+/** That table piped into `kill` through `xargs` (the incident's `ps … | … | xargs -r kill`). */
+const XARGS_KILL = /\bxargs\b[^\n;]*\bkill\b/;
+/** A `$(ps …)` / `$(pgrep …)` substitution that feeds ids to a `kill` (`kill -9 $(pgrep -f npm)`,
+ * a `for p in $(ps …)` loop whose body kills). */
+const TABLE_SUBSTITUTION = /\$\(\s*(?:ps|pgrep)\b/;
+/** The refusal for one `bash` command, or null to let it run. Exported for tests. */
+export function patternKillRefusal(command) {
+    if (typeof command !== "string" || command.trim() === "")
+        return null;
+    if (DIRECT_PATTERN_KILL.test(command))
+        return PATTERN_KILL_REFUSAL;
+    const feedsTable = READ_PROCESS_TABLE.test(command);
+    const feedsKill = XARGS_KILL.test(command) || (TABLE_SUBSTITUTION.test(command) && /\bkill\b/.test(command));
+    if (feedsTable && feedsKill)
+        return PATTERN_KILL_REFUSAL;
+    return null;
+}
+/** The refusal for one `tool_call` event, or undefined to let it run. Exported for tests. */
+export function guardKillToolCall(event) {
+    if (event.toolName !== "bash")
+        return undefined;
+    const input = event.input;
+    if (typeof input !== "object" || input === null)
+        return undefined;
+    try {
+        const reason = patternKillRefusal(input.command);
+        return reason === null ? undefined : { block: true, reason };
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The pi extension entry point. */
+export default function killGuard(pi) {
+    pi.on("tool_call", guardKillToolCall);
+}

package/dist/src/process/process-group.js

@@ -1,26 +1,7 @@
 import { spawn } from "node:child_process";
-import { captureCappedOutput, releaseChildHandles, signalTree, withoutLaunchServicesCheckIn } from "./process.js";
+import { captureCappedOutput, KILL_GRACE_MS, releaseChildHandles, signalTree, withoutLaunchServicesCheckIn, } from "./process.js";
+export { KILL_GRACE_MS };
 import { errCode } from "../errno.js";
-/** The detached process-group runner: runScriptGroup starts a command in its own process
- * group — exactly like pi — and settles exactly once, bounding a timed-out tree at its
- * deadline plus the SIGTERM → SIGKILL escalation grace. Split out of process.ts, whose other
- * residents (the exec helper, the liveness and process-table probes, the LaunchServices
- * preload) are generic child-process plumbing shared across the harness: this runner's two
- * runtime consumers both sit in the build boundary — the build check (build/build-check.ts)
- * and the lockfile install (build/dep-install.ts) — and its result carries the build check's
- * run record, so it lives beside that boundary instead of inside the shared module. The
- * signals it escalates with come from process.ts's signalTree; the children it starts carry
- * withoutLaunchServicesCheckIn's preload, so its npm trees check in with launchservicesd
- * neither on macOS nor anywhere else. */
-/** SIGTERM → SIGKILL escalation window once a run's timeout has FIRED: the whole process
- * group gets SIGTERM, and anything still alive this much later (a SIGTERM-trapping runner, a
- * wedged worker) is SIGKILLed — and the run settles then, whether or not the tree ever closed
- * its pipes, so a timed-out run is bounded at its deadline plus this grace. The default of
- * runBuildCheck's killGraceMs parameter (build/build-check.ts), which tests shrink — pinning that
- * the escalation is armed on timeout (never at spawn: a healthy run that merely outlasts the
- * grace period must run to completion), that a surviving grandchild is taken down before the
- * run settles, and that a tree the SIGTERM already took down does not wait out the grace. */
-export const KILL_GRACE_MS = 10_000;
 /** True while any process in the group led by `pid` still exists: a signal-0 probe of the
  * group, where EPERM still means a member exists. armGroupDeadline probes with it for both
  * detached-process-group runners (runScriptGroup and git-run's execGitBounded), whose
@@ -122,6 +103,13 @@ export function runScriptGroup(cmd, args, opts) {
             env: withoutLaunchServicesCheckIn(process.env),
         });
         let settled = false;
+        let aborted = false;
+        // Abort-stop timers, the mirror of armGroupDeadline's — armed only while an abort fires
+        // before settle (never at spawn), SIGTERM first then SIGKILL after killGraceMs for a
+        // survivor, settling as soon as the whole group is gone — cleared on finish, the caller's
+        // single settle path.
+        let abortPoll;
+        let abortKillTimer;
         // Captured output is capped at maxBuffer per stream (further chunks are dropped —
         // classification reads the tail, so a chatty script can neither wedge the check nor balloon
         // memory). The overflow is deliberately ignored here: truncated output still classifies.
@@ -134,11 +122,34 @@ export function runScriptGroup(cmd, args, opts) {
             killGraceMs: opts.killGraceMs,
             onTimedOut: () => finish({ signal: "SIGTERM" }),
         });
+        function stopForAbort() {
+            if (settled)
+                return;
+            aborted = true;
+            // The harness's own stop, signalled the way a timeout stops the tree: SIGTERM the whole
+            // group (grandchild included), then SIGKILL anything still alive after the grace. The
+            // run settles when the group is gone, so the caller never sees a live tree behind it.
+            signalTree(child, "SIGTERM");
+            abortPoll = setInterval(() => {
+                if (!groupAlive(child.pid))
+                    finish({ aborted: true });
+            }, GROUP_POLL_MS);
+            abortKillTimer = setTimeout(() => {
+                signalTree(child, "SIGKILL");
+                finish({ aborted: true });
+            }, opts.killGraceMs);
+        }
         function finish(result) {
             if (settled)
                 return;
             settled = true;
             deadline.dispose();
+            if (abortPoll)
+                clearInterval(abortPoll);
+            if (abortKillTimer)
+                clearTimeout(abortKillTimer);
+            if (opts.signal)
+                opts.signal.removeEventListener("abort", stopForAbort);
             const timedOut = deadline.fired();
             if (timedOut) {
                 // Nothing more is read once the deadline has fired: release the handles so a pipe
@@ -148,16 +159,30 @@ export function runScriptGroup(cmd, args, opts) {
             const run = { spawnedAt, settledAt: Date.now(), timeoutMs: opts.timeoutMs };
             if (timedOut)
                 run.deadlineLateMs = deadline.lateMs();
-            resolve({ ...result, timedOut, stdout: captured.stdout, stderr: captured.stderr, run });
+            resolve({ ...result, aborted, timedOut, stdout: captured.stdout, stderr: captured.stderr, run });
         }
+        // An abort signal stops the tree mid-check — the harness's own stop, so the outcome says
+        // the harness aborted it, distinct from a timeout and from an external killed signal. The
+        // listener is removed as soon as the run settles. An already-aborted signal is deliberately
+        // NOT acted on at spawn: the swap happens mid-run (a user abort or a shutdown fires while
+        // the check is running), and a signal already aborted before the check started is caught by
+        // the caller's `aborted` check when the run returns — a fast failing check under a
+        // pre-aborted signal still reaches its own verdict first (the pre-existing shutdown-test
+        // behavior).
+        if (opts.signal)
+            opts.signal.addEventListener("abort", stopForAbort, { once: true });
         child.on("error", (err) => {
-            // Before the deadline this is the spawn failing (npm missing from PATH). After it, it can
-            // only be a teardown signal that could not be delivered: the run is a timeout either way,
-            // settled by the group probe or the grace timer.
-            if (!deadline.fired())
+            // Before a stop this is the spawn failing (npm missing from PATH). After the deadline or
+            // an abort it can only be a teardown signal that could not be delivered — the stop's own
+            // group probe or grace timer settles the run.
+            if (!deadline.fired() && !aborted)
                 finish({ spawnError: err });
         });
         child.on("close", (code, signal) => {
+            // During an abort-stop the run settles on the whole group being gone (the probe or the
+            // grace timer), never on the leader's close alone. Otherwise the timeout rule stands.
+            if (aborted)
+                return;
             // Before the deadline the leader's close settles the run. After it, settle only once the
             // whole group is gone: something in the group may outlive the leader, and the poll
             // settles the run when it goes, or the grace timer SIGKILLs it and settles then.

package/dist/src/process/process.js

@@ -3,10 +3,10 @@ import { promisify } from "node:util";
 /** Child-process plumbing: the harness's one execFile helper (execFileAsync), the pid-liveness
  * probe every place that decides whether a recorded pid still belongs to a live process shares
  * (the merge lock's stale-holder check in lock.ts, the orchestrator-alive status in
- * team/orchestrator-info.ts), the group-signal helpers behind every teardown, the register/abort
- * race helper the spawns and merge's shutdown wiring share, and the child environment
- * that keeps the harness's Node processes out of LaunchServices on macOS. Reading the host's
- * process table and the per-run TUMWATER_RUN marks and sweep built on it live in
+ * team/team-orchestrator-info.ts), the group-signal helpers behind every teardown, the
+ * register/abort race helper the spawns and merge's shutdown wiring share, and the child
+ * environment that keeps the harness's Node processes out of LaunchServices on macOS. Reading the
+ * host's process table and the per-run TUMWATER_RUN marks and sweep built on it live in
  * process-table.ts, on top of the exec helper here. */
 const execFileRaw = promisify(execFile);
 /** The output ceiling every execFile the harness runs shares (git, tsc, the build check, the
@@ -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-spawn.ts), sleepInterruptible (run-timing.ts), and abortOnShutdown
+ * (src/agent/agent-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
@@ -88,10 +88,18 @@ export async function identityAlive(id) {
     const now = await pidIdentity(id.pid);
     return now !== null && now.start === id.start;
 }
+/** SIGTERM → SIGKILL escalation window: how long a SIGTERM is given to take a process tree
+ * down before whatever survived is SIGKILLed. The one value behind every harness escalation
+ * — terminateChild's group kill here, the run-marker sweep's orphan kill, and the detached
+ * process-group runner (whose own `KILL_GRACE_MS` re-exports it, process-group.ts) — so a
+ * team-wide teardown, an end-of-run sweep, and a timed-out build check all grant the same
+ * grace and the literal cannot drift between them. 10 s is enough for a well-behaved tree to
+ * exit on SIGTERM; a SIGTERM-trapping straggler is SIGKILLed after it. */
+export const KILL_GRACE_MS = 10_000;
 /** 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
- * tool-call grandchild — which a single-PID kill leaves orphaned to launchd — while the
+ * escalating to SIGKILL after KILL_GRACE_MS 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 tool-call grandchild — which a single-PID kill leaves orphaned to launchd — while the
  * harness's own group is never in the blast radius. Shared by the run-timeout,
  * quiet-watchdog, and harness-shutdown kills, and by the sweep every run gets once pi exits
  * (runPi's 'exit' handler), when the group holds only what pi's tool calls backgrounded.
@@ -106,14 +114,14 @@ export async function identityAlive(id) {
  * by it. */
 export function terminateChild(child) {
     if (signalTree(child, "SIGTERM"))
-        setTimeout(() => signalTree(child, "SIGKILL"), 10_000).unref();
+        setTimeout(() => signalTree(child, "SIGKILL"), KILL_GRACE_MS).unref();
 }
 /** Signal the child's whole process group, falling back to the child alone when the group is
  * already gone or the platform has no negative-PID kill (Windows). Returns whether the signal
  * reached a live process: false when nothing was left to receive it — ESRCH from a group that
  * died with its leader, the normal case once the child has exited. Never throws: a process
  * that died between the caller's decision and this call is the normal case. Shared by runPi's
- * teardown (src/agent/run-agent.ts) and the detached process-group runner (runScriptGroup,
+ * teardown (src/agent/agent-run.ts) and the detached process-group runner (runScriptGroup,
  * process-group.ts) — the same "signal the tree, not just the direct child" guarantee in one
  * home, this module. */
 export function signalTree(child, signal) {
@@ -186,8 +194,8 @@ export function captureCappedOutput(child, maxBuffer, onOverflow) {
 // ── Child environments ───────────────────────────────────────────────────────────────────
 /** The child-environment policy every spawn that hands a child the harness's environment shares:
  * start from `process.env` and apply `overrides` on top. The explicit spawn sites
- * (supervisor.ts, self-reload.ts, notify.ts, git-run.ts, doctor-model-checks.ts) all want exactly
- * this, so the spread lives here once instead of in each spawn's options. */
+ * (supervisor.ts, self-reload.ts, event-notify.ts, git-run.ts, doctor-model-checks.ts) all want
+ * exactly this, so the spread lives here once instead of in each spawn's options. */
 export function childEnv(overrides = {}) {
     return { ...process.env, ...overrides };
 }