tumwater 0.4.2 → 0.4.3

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

@@ -3,7 +3,7 @@ import path from "node:path";
 import { enabledRoleIds, loadConfigSafe } from "../config/config.js";
 import { configForRole, resolverConfig, resolvedBackendConfig, reviewConfig } from "../config/config-views.js";
 import { fallbackPair } from "../config/config-fallbacks.js";
-import { seamAgent } from "../config/model-selector.js";
+import { seamAgent } from "../config/config-model-selector.js";
 import { cachedByStat } from "../files/stat-cache.js";
 import { isJsonObject } from "../files/json-object.js";
 import { readJsonFile } from "../files/json-files.js";
@@ -107,40 +107,54 @@ export function seamContextWindow(seam, projectRoot, modelsPath = piModelsPath()
     const backend = seamAgent(seam);
     switch (backend) {
         case "pi":
-            let { provider, model } = seam;
-            if (!provider || !model) {
-                const piDefault = readPiDefaultModel(piSettingsPath(modelsPath), projectRoot);
-                provider = piDefault?.provider;
-                model = piDefault?.model;
-            }
-            return declaredWindow(resolveModelDef(readPiProviders(modelsPath), provider, model)?.contextWindow);
+            return piSeamContextWindow(seam, projectRoot, modelsPath);
         case "opencode":
-            // The models.dev cache (readOpencodeCache, an empty cache when the file is missing) holds
-            // the window part 6a/7 parsed from `limit.context`, keyed by the gateway-qualified id the
-            // run actually invokes (opencodeModelKey) — the same key and entry the free-ness check
-            // prices by, so a seam's window never disagrees with the model it runs.
-            if (seam.model === undefined)
-                return null;
-            return declaredWindow(readOpencodeCache(projectRoot).models[opencodeModelKey(seam.model)]?.context);
+            return opencodeSeamContextWindow(seam, projectRoot);
         case "codex":
-            // The model catalog (codex-catalog.ts) holds the window part 8/9 parsed from
-            // `context_window × effective_context_window_percent / 100`, read from the team's codex
-            // home (backends.codex.configDir) at this project root — the same home the runs use. An
-            // unknown model, an absent home or a missing catalog reads null (declaredWindow's safe
-            // answer for an unknown window).
-            if (seam.model === undefined)
-                return null;
-            {
-                const { config } = loadConfigSafe(projectRoot);
-                const home = codexHome(resolvedBackendConfig(config ?? {}, "codex"));
-                if (home === undefined)
-                    return null;
-                return declaredWindow(readCodexCatalog(home).get(seam.model)?.contextWindow);
-            }
+            return codexSeamContextWindow(seam, projectRoot);
         default:
             return null;
     }
 }
+/** The window a pi seam declares, or null when it cannot be known: reads the pair's
+ * `contextWindow` from pi's models.json, running on pi's saved default
+ * (readPiDefaultModel) when the seam names no provider/model — exactly the model pi will
+ * start on. An unresolvable pair or a missing/unusable window reads null. */
+function piSeamContextWindow(seam, projectRoot, modelsPath) {
+    let { provider, model } = seam;
+    if (!provider || !model) {
+        const piDefault = readPiDefaultModel(piSettingsPath(modelsPath), projectRoot);
+        provider = piDefault?.provider;
+        model = piDefault?.model;
+    }
+    return declaredWindow(resolveModelDef(readPiProviders(modelsPath), provider, model)?.contextWindow);
+}
+/** The window an opencode seam declares, or null when it cannot be known. The models.dev cache
+ * (readOpencodeCache, an empty cache when the file is missing) holds the window part 6a/7
+ * parsed from `limit.context`, keyed by the gateway-qualified id the run actually invokes
+ * (opencodeModelKey) — the same key and entry the free-ness check prices by, so a seam's
+ * window never disagrees with the model it runs. A missing cache, an unknown model or an
+ * unusable `context` reads null. */
+function opencodeSeamContextWindow(seam, projectRoot) {
+    if (seam.model === undefined)
+        return null;
+    return declaredWindow(readOpencodeCache(projectRoot).models[opencodeModelKey(seam.model)]?.context);
+}
+/** The window a codex seam declares, or null when it cannot be known. The model catalog
+ * (codex-catalog.ts) holds the window part 8/9 parsed from
+ * `context_window × effective_context_window_percent / 100`, read from the team's codex home
+ * (backends.codex.configDir) at this project root — the same home the runs use. An unknown
+ * model, an absent home or a missing catalog reads null (declaredWindow's safe answer for an
+ * unknown window). */
+function codexSeamContextWindow(seam, projectRoot) {
+    if (seam.model === undefined)
+        return null;
+    const { config } = loadConfigSafe(projectRoot);
+    const home = codexHome(resolvedBackendConfig(config ?? {}, "codex"));
+    if (home === undefined)
+        return null;
+    return declaredWindow(readCodexCatalog(home).get(seam.model)?.contextWindow);
+}
 /** The resolved primary seam's declared context window for a role — `configForRole` resolves
  * the role's seam (the view the role page, status table/drawer and run history all print), then
  * `seamContextWindow` names the window that seam declares, or null when it cannot be known. The

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

@@ -50,37 +50,60 @@ export function readPiDefaultModel(settingsPath, projectRoot) {
     return cachedByStat(settingsCache, settingsPath, // Keyed by path so distinct roots and test files never collide.
     settingsPath, () => readPiDefaultModelUncached(settingsPath, projectRoot), (defaultModel) => ({ ...defaultModel }));
 }
-function readPiDefaultModelUncached(settingsPath, projectRoot) {
-    // readJsonFile is the shared "missing or torn reads as no data" policy for a JSON object
-    // file; the nested shapes get the same isJsonObject guard.
-    const doc = readJsonFile(settingsPath);
-    if (!doc)
-        return null;
+/** The saved default pair, or null when either half is missing or empty — pi uses a saved
+ * default only as a pair. */
+function savedDefaultPair(doc) {
     const { defaultProvider, defaultModel } = doc;
     if (typeof defaultProvider !== "string" || defaultProvider === "")
         return null;
     if (typeof defaultModel !== "string" || defaultModel === "")
         return null;
-    if (Array.isArray(doc.enabledModels) && doc.enabledModels.length > 0)
-        return null;
+    return { provider: defaultProvider, model: defaultModel };
+}
+/** Whether pi starts on the first scoped model instead of the saved default — a pattern
+ * tumwater does not resolve, so the reader shows nothing. */
+function startsWithScopedModels(doc) {
+    return Array.isArray(doc.enabledModels) && doc.enabledModels.length > 0;
+}
+/** Whether the project's own `.pi/settings.json` names any default key, which makes pi's final
+ * choice depend on whether it trusts the project — unknowable to tumwater, so show nothing. */
+function projectOverridesSavedDefault(projectRoot) {
     // A project-local override that names any default key means pi's final choice depends on
     // whether it trusts the project — unknowable to tumwater, so show nothing.
     const proj = readJsonFile(path.join(projectRoot, ".pi", "settings.json"));
-    if (proj) {
-        for (const key of DEFAULT_KEYS) {
-            if (proj[key] !== undefined)
-                return null;
-        }
+    if (!proj)
+        return false;
+    for (const key of DEFAULT_KEYS) {
+        if (proj[key] !== undefined)
+            return true;
     }
-    const key = `${defaultProvider}/${defaultModel}`;
+    return false;
+}
+/** pi's thinking for the pair: `modelThinkingLevels[key]` first, else `defaultThinkingLevel`. */
+function savedThinkingLevel(doc, key) {
     const levels = doc.modelThinkingLevels;
     const level = isJsonObject(levels) ? levels[key] : undefined;
-    let thinking;
     if (typeof level === "string")
-        thinking = level;
-    else if (typeof doc.defaultThinkingLevel === "string")
-        thinking = doc.defaultThinkingLevel;
+        return level;
+    if (typeof doc.defaultThinkingLevel === "string")
+        return doc.defaultThinkingLevel;
+    return undefined;
+}
+function readPiDefaultModelUncached(settingsPath, projectRoot) {
+    // readJsonFile is the shared "missing or torn reads as no data" policy for a JSON object
+    // file; the nested shapes get the same isJsonObject guard.
+    const doc = readJsonFile(settingsPath);
+    if (!doc)
+        return null;
+    const pair = savedDefaultPair(doc);
+    if (!pair)
+        return null;
+    if (startsWithScopedModels(doc))
+        return null;
+    if (projectOverridesSavedDefault(projectRoot))
+        return null;
+    const thinking = savedThinkingLevel(doc, `${pair.provider}/${pair.model}`);
     return thinking !== undefined
-        ? { provider: defaultProvider, model: defaultModel, thinking }
-        : { provider: defaultProvider, model: defaultModel };
+        ? { provider: pair.provider, model: pair.model, thinking }
+        : { provider: pair.provider, model: pair.model };
 }

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

@@ -251,6 +251,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 +272,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 +289,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. */
@@ -494,6 +508,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 +522,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 +543,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 +560,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,10 @@
 /** 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
  * 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 +41,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 +67,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);

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

@@ -122,6 +122,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 +141,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 +178,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
@@ -113,7 +113,7 @@ export function terminateChild(child) {
  * 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 +186,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 };
 }