@herbertgao/pi-extensions 2026.9.15 → 2026.9.17

package/node_modules/pi-lens/dist/clients/safe-spawn.js

@@ -22,6 +22,7 @@ import { incrementDegradationCount, recordDegradation, recordDegradationOnce, }
 import { logExtension } from "./extension-log.js";
 import { isFullyQualifiedWin32 } from "./path-utils.js";
 import { startSpawnUsageSampler } from "./resource-sampler.js";
+import { DEFAULT_MAX_OUTPUT_BYTES } from "./spawn-output-cap.js";
 import { compareOrdinal } from "./string-utils.js";
 /** Intent-level spawn failure. `cause` retains the original OS Error/errno. */
 export class SpawnFailureError extends Error {
@@ -479,7 +480,48 @@ function installLifetimeCleanup() {
         process.once(signal, () => {
             for (const pid of lifetimeState.pids)
                 killPidTreeSync(pid);
-            process.kill(process.pid, signal);
+            if (process.platform === "win32" && signal === "SIGHUP") {
+                // Windows emits SIGHUP when its console closes, but libuv cannot
+                // self-send it (process.kill(..., "SIGHUP") throws ENOSYS). The
+                // child cleanup above remains the required shutdown action; record
+                // the intentional decline synchronously and let the host exit cleanly.
+                recordDegradationOnce({
+                    kind: "safe-spawn-signal-reraise-unsupported",
+                    subject: `${process.platform}:${signal}`,
+                    reason: `${process.platform} ${signal}: self signal re-raise is unsupported by the Windows libuv signal capability`,
+                    metadata: {
+                        platform: process.platform,
+                        signal,
+                        reason: "unsupported",
+                    },
+                });
+                return;
+            }
+            try {
+                process.kill(process.pid, signal);
+            }
+            catch (error) {
+                // #3383: this runs inside a `process.once(signal)` handler, so a
+                // throw here is an uncaughtException DURING SHUTDOWN, not a
+                // rejection anyone can see. The one failure measured in the field
+                // (Windows SIGHUP ENOSYS) is declined in advance just above; this
+                // covers every other platform/signal/errno pair the OS can refuse —
+                // same ledger kind, `reason: "refused"` instead of "unsupported",
+                // because a reader of either row wants the same fact: the host
+                // exited without the signal's default disposition. The child
+                // cleanup above has already run either way.
+                recordDegradationOnce({
+                    kind: "safe-spawn-signal-reraise-unsupported",
+                    subject: `${process.platform}:${signal}`,
+                    reason: `${process.platform} ${signal}: self signal re-raise was refused (${error.code ?? error.message})`,
+                    metadata: {
+                        platform: process.platform,
+                        signal,
+                        reason: "refused",
+                        code: error.code ?? null,
+                    },
+                });
+            }
         });
     }
 }
@@ -1156,6 +1198,24 @@ export async function safeSpawnAsync(command, args, options) {
         let killed = false;
         let outputTruncated = false;
         let killedForOutputCap = false;
+        // #3375: bytes the child actually EMITTED (not what survived the cap) —
+        // the one number the field crash report could not supply, so the ledger
+        // row below can name how chatty the offending command really was.
+        let observedOutputBytes = 0;
+        // #3375: bytes RETAINED so far, kept incrementally. The cap check used to
+        // re-measure `Buffer.byteLength(stdout) + Buffer.byteLength(stderr)` on
+        // every chunk, which flattens both accumulated strings each time — O(n^2)
+        // in total output. Harmless while only 12 of 110 call sites passed a cap;
+        // with the cap now on by default it would tax every spawn (measured: a
+        // 32 MiB child resolved in 7944 ms before this counter, 469 ms after).
+        // Equal to the two byte lengths by construction: before
+        // truncation `stdout`/`stderr` are exactly the appended texts, and after
+        // it the branch that renders from the retained head/tail never reads it.
+        let retainedOutputBytes = 0;
+        // #3375: latched the first time a chunk handler throws. Later chunks
+        // return immediately, so the same fault cannot be re-entered and
+        // `refreshRetainedOutputs` can never overwrite the bytes already kept.
+        let outputHandlerFailed = false;
         let streamingMatch = false;
         // #1651 review: a single boolean the close/error handlers both check
         // AND set, so whichever one decides the outcome first wins outright —
@@ -1198,11 +1258,14 @@ export async function safeSpawnAsync(command, args, options) {
         // re-arm the grace timer on every chunk. `undefined` before exit / after
         // the wait settles, so the calls below are no-ops outside that window.
         let rearmIdleGrace;
-        const maxOutputBytes = options?.maxOutputBytes !== undefined &&
-            Number.isFinite(options.maxOutputBytes) &&
-            options.maxOutputBytes > 0
-            ? Math.floor(options.maxOutputBytes)
-            : undefined;
+        // #3375: never `undefined`. An omitted or unusable cap resolves to the
+        // module default instead of to unbounded retention, so `appendOutput`
+        // below has no arm that concatenates without a ceiling.
+        const callerCap = options?.maxOutputBytes;
+        const capFromCaller = callerCap !== undefined && Number.isFinite(callerCap) && callerCap > 0;
+        const maxOutputBytes = capFromCaller
+            ? Math.floor(callerCap)
+            : DEFAULT_MAX_OUTPUT_BYTES;
         const outputTruncationMarker = "\n...[output truncated]...\n";
         let retainedHead = [];
         let retainedTail = [];
@@ -1259,17 +1322,16 @@ export async function safeSpawnAsync(command, args, options) {
         };
         const appendOutput = (stream, current, chunk) => {
             const text = typeof chunk === "string" ? chunk : chunk.toString();
-            if (maxOutputBytes === undefined || outputTruncated) {
-                if (maxOutputBytes === undefined)
-                    return current + text;
+            if (outputTruncated) {
                 appendTail({ stream, text }, retainedTailLimit);
                 truncationStream = stream;
                 return renderOutput(stream);
             }
-            const used = Buffer.byteLength(stdout) + Buffer.byteLength(stderr);
             const bytes = Buffer.byteLength(text);
-            if (used + bytes <= maxOutputBytes)
+            if (retainedOutputBytes + bytes <= maxOutputBytes) {
+                retainedOutputBytes += bytes;
                 return current + text;
+            }
             outputTruncated = true;
             truncationStream = stream;
             const available = Math.max(0, maxOutputBytes - Buffer.byteLength(outputTruncationMarker));
@@ -1501,10 +1563,48 @@ export async function safeSpawnAsync(command, args, options) {
             usageSampler = { stop: () => null };
         }
         const resourceLabel = options?.resourceLabel ?? command;
+        let killFailed = false;
+        /** Send one signal. INVARIANT (#3375 r3 / M3384-2): every signal SEND in
+         *  `killTree` goes through this function. Exactly two `try`/`catch`
+         *  blocks remain in there and neither contains a bare send: the Windows
+         *  `await` guard around the taskkill child (its `catch` body sends only
+         *  through `trySend`), and the group LIVENESS PROBE, whose `catch`
+         *  computes a predicate rather than sending anything — the same shape as
+         *  the module-level `groupIsGone`. Returns false instead of throwing, and
+         *  records nothing itself: a refused signal is often ORDINARY (a negative-pid
+         *  ESRCH means the group already exited and the direct-child fallback
+         *  takes over), so only a send with no fallback left behind it pairs
+         *  with `noteKillFailure`. */
+        const trySend = (send) => {
+            try {
+                send();
+                return true;
+            }
+            catch {
+                return false;
+            }
+        };
+        /** Every signal for this teardown was refused, so the child may still be
+         *  running. One record per spawn — the reviewer's reproduction refused
+         *  two kills (the fault's and then the timeout's) and a row per attempt
+         *  would be a flood. A kind of its own rather than a field on
+         *  `spawn-output-cap-truncated`: this fires on the abort and timeout
+         *  teardowns too, which have nothing to do with an output cap. */
+        const noteKillFailure = (phase) => {
+            if (killFailed)
+                return;
+            killFailed = true;
+            incrementDegradationCount({
+                kind: "spawn-kill-failed",
+                subject: resourceLabel,
+                reason: `every signal available for the ${phase} teardown was refused; the child may still be running`,
+                metadata: { phase, pid: child.pid },
+            });
+        };
         // On Windows, shell:true means child.pid is cmd.exe — child.kill() only
         // kills the wrapper, leaving the actual subprocess (e.g. knip/npx) alive
         // as an orphan. Use taskkill /F /T to kill the full process tree instead.
-        const killTree = async () => {
+        const killTree = async (phase) => {
             if (isWindows && child.pid && child.pid > 0) {
                 const taskkill = `${process.env.SystemRoot ?? "C:\\Windows"}\\System32\\taskkill.exe`;
                 try {
@@ -1516,13 +1616,17 @@ export async function safeSpawnAsync(command, args, options) {
                         });
                         killer.once("close", () => done());
                         killer.once("error", () => {
-                            child.kill("SIGKILL");
+                            // E4: a throw HERE would leave the EventEmitter as an
+                            // uncaught exception, not a rejection.
+                            if (!trySend(() => child.kill("SIGKILL")))
+                                noteKillFailure(phase);
                             done();
                         });
                     });
                 }
                 catch {
-                    child.kill("SIGKILL");
+                    if (!trySend(() => child.kill("SIGKILL")))
+                        noteKillFailure(phase);
                 }
             }
             else if (posixProcessGroup && ownsChildPid) {
@@ -1530,11 +1634,18 @@ export async function safeSpawnAsync(command, args, options) {
                 // by the tool share its group, so one signal reaches the whole
                 // tree; a negative-pid ESRCH means it already exited.
                 const pgid = -child.pid;
-                try {
-                    process.kill(pgid, "SIGTERM");
-                }
-                catch {
-                    child.kill("SIGTERM");
+                // #3375 round 3 (M3384-2): through the one sink, like every other
+                // send. A second ad-hoc `try`/`catch` here would be a rival
+                // signal-safety mechanism inside the same teardown — the shape this
+                // change deleted four of — and a later edit to this branch would not
+                // inherit `trySend`'s total send or its failure accounting.
+                // `trySend` returning false here is ORDINARY, not a failure: #2026's
+                // negative-pid ESRCH means the group already exited, so the direct
+                // child below is the normal fallback and nothing is recorded. Only
+                // the last-resort send can fail the teardown.
+                if (!trySend(() => process.kill(pgid, "SIGTERM"))) {
+                    if (!trySend(() => child.kill("SIGTERM")))
+                        noteKillFailure(phase);
                 }
                 // #2027 round-1: gate the SIGKILL escalation on GROUP liveness,
                 // not direct-child death - a tool can exit instantly on SIGTERM
@@ -1543,38 +1654,49 @@ export async function safeSpawnAsync(command, args, options) {
                 // it is the only backstop for this group once finalize deletes
                 // the pid from lifetimeState.
                 escalationTimer = setTimeout(() => {
-                    let groupAlive = true;
-                    try {
-                        process.kill(pgid, 0);
-                    }
-                    catch {
-                        groupAlive = false;
-                    }
-                    if (!groupAlive)
-                        return;
-                    teardownEscalated = true;
-                    logLatency({
-                        type: "phase",
-                        phase: "spawn_group_kill_escalation",
-                        filePath: "",
-                        durationMs: 0,
-                        metadata: { pgid: child.pid },
+                    // The WHOLE body, not just the signal: this runs in a bare
+                    // timer callback, where any throw is an uncaught exception.
+                    const escalated = trySend(() => {
+                        let groupAlive = true;
+                        try {
+                            process.kill(pgid, 0);
+                        }
+                        catch {
+                            groupAlive = false;
+                        }
+                        if (!groupAlive)
+                            return;
+                        teardownEscalated = true;
+                        logLatency({
+                            type: "phase",
+                            phase: "spawn_group_kill_escalation",
+                            filePath: "",
+                            durationMs: 0,
+                            metadata: { pgid: child.pid },
+                        });
+                        // Through the sink too (#3375 r3 / M3384-2): one vocabulary
+                        // for every send in this function. A false here is ORDINARY
+                        // — the group raced its own exit — so it is deliberately not
+                        // escalated to `noteKillFailure`; the enclosing `trySend`
+                        // already guarantees nothing escapes this timer callback.
+                        trySend(() => process.kill(pgid, "SIGKILL"));
                     });
-                    try {
-                        process.kill(pgid, "SIGKILL");
-                    }
-                    catch {
-                        // Raced with group exit.
-                    }
+                    if (!escalated)
+                        noteKillFailure(phase);
                 }, 1000);
             }
             else {
-                child.kill("SIGTERM");
+                // E2/E3. This branch runs whenever `/proc` cannot prove pid
+                // ownership — every macOS host, and any Linux host with an
+                // unreadable `/proc` — so it is not a hypothetical path.
+                if (!trySend(() => child.kill("SIGTERM")))
+                    noteKillFailure(phase);
                 escalationTimer = setTimeout(() => {
-                    if (!closed) {
-                        teardownEscalated = true;
-                        child.kill("SIGKILL");
-                    }
+                    if (closed)
+                        return;
+                    teardownEscalated = true;
+                    if (!trySend(() => child.kill("SIGKILL")))
+                        noteKillFailure(phase);
                 }, 1000);
             }
         };
@@ -1583,7 +1705,7 @@ export async function safeSpawnAsync(command, args, options) {
             aborted = true;
             if (!killed && !child.killed) {
                 killed = true;
-                void killTree();
+                void killTree("abort");
             }
         };
         abortSignal?.addEventListener("abort", onAbort, { once: true });
@@ -1600,28 +1722,95 @@ export async function safeSpawnAsync(command, args, options) {
                 !child.killed) {
                 killedForOutputCap = true;
                 killed = true;
-                killPromise = killTree();
+                killPromise = killTree("output-cap");
+            }
+        };
+        // #3375: one bounded, counted ledger row per command label the moment the
+        // cap first bites - the crash report named no command, no byte count and
+        // no cap value, so nothing in it could identify the chatty producer.
+        // `incrementDegradationCount` keeps one latest-reason entry per subject
+        // with an exact tally and writes durable rows only at powers of two, so a
+        // tool that trips the cap on every dispatch cannot flood the sink.
+        const recordOutputCapTrip = () => {
+            incrementDegradationCount({
+                kind: "spawn-output-cap-truncated",
+                subject: resourceLabel,
+                reason: `retained output reached the ${maxOutputBytes}-byte ${capFromCaller ? "caller" : "default"} cap after ${observedOutputBytes} bytes; child ${killedForOutputCap ? "terminated" : "left running"}`,
+                metadata: {
+                    capBytes: maxOutputBytes,
+                    capSource: capFromCaller ? "caller" : "default",
+                    observedBytes: observedOutputBytes,
+                    killed: killedForOutputCap,
+                },
+            });
+        };
+        // #3375: the fault path for a chunk handler that threw. Every statement
+        // here is total by construction - plain assignments, a ledger call that
+        // swallows its own failures, and `killTree()`, which is `async` so a
+        // synchronous fault inside it becomes a rejected promise rather than a
+        // throw - because a throw raised HERE would escape the same way the
+        // original RangeError did.
+        const failOutputHandler = (stream, error) => {
+            outputHandlerFailed = true;
+            // Retention is over. The bytes already in `stdout`/`stderr` stay as
+            // the bounded output: nothing renders from the retained head/tail
+            // again, because the re-entry guard returns before that can happen.
+            // That is also why `truncationStream` is deliberately NOT set here —
+            // only `renderOutput` reads it, and nothing renders after a fault, so
+            // the assignment was mutation-inert (removing it reds nothing).
+            outputTruncated = true;
+            incrementDegradationCount({
+                kind: "spawn-output-handler-fault",
+                subject: resourceLabel,
+                reason: `${stream} chunk handling threw ${error.name} after ${observedOutputBytes} bytes; retention stopped and the child was terminated`,
+                metadata: {
+                    stream,
+                    error: error.name,
+                    capBytes: maxOutputBytes,
+                    observedBytes: observedOutputBytes,
+                },
+            });
+            if (!killed && !child.killed) {
+                killedForOutputCap = true;
+                killed = true;
+                killPromise = killTree("handler-fault");
             }
         };
         // Collect output
         child.stdout?.setEncoding("utf-8");
         child.stderr?.setEncoding("utf-8");
-        child.stdout?.on("data", (data) => {
-            matchStreamingChunk("stdout", data);
-            stdout = appendOutput("stdout", stdout, data);
-            if (outputTruncated)
-                refreshRetainedOutputs();
-            stopForOutputLimit();
-            rearmIdleGrace?.();
-        });
-        child.stderr?.on("data", (data) => {
-            matchStreamingChunk("stderr", data);
-            stderr = appendOutput("stderr", stderr, data);
-            if (outputTruncated)
-                refreshRetainedOutputs();
-            stopForOutputLimit();
-            rearmIdleGrace?.();
-        });
+        // #3375: a throw raised inside a stream `data` handler is delivered to
+        // the process, not to the caller awaiting this spawn - no `try`/`catch`
+        // around `await safeSpawnAsync(...)` can contain it, which is why a
+        // `RangeError: Invalid string length` from `appendOutput` terminated the
+        // Pi host on 2026-09-22. Every statement the handler runs lives inside
+        // this `try`, so ANY fault in the retention path (not just that one
+        // RangeError) becomes the bounded output-cap result the caller already
+        // knows how to read.
+        const onOutputChunk = (stream, data) => {
+            if (outputHandlerFailed)
+                return;
+            try {
+                observedOutputBytes += Buffer.byteLength(data);
+                const wasTruncated = outputTruncated;
+                matchStreamingChunk(stream, data);
+                if (stream === "stdout")
+                    stdout = appendOutput(stream, stdout, data);
+                else
+                    stderr = appendOutput(stream, stderr, data);
+                if (outputTruncated)
+                    refreshRetainedOutputs();
+                stopForOutputLimit();
+                if (!wasTruncated && outputTruncated)
+                    recordOutputCapTrip();
+                rearmIdleGrace?.();
+            }
+            catch (error) {
+                failOutputHandler(stream, toError(error));
+            }
+        };
+        child.stdout?.on("data", (data) => onOutputChunk("stdout", data));
+        child.stderr?.on("data", (data) => onOutputChunk("stderr", data));
         // #1673 review round 3 (F2): registered HERE, at spawn time, alongside
         // the other handlers above — not inside `waitForPipeIdle`. Real Node
         // emits `close` a fraction of a millisecond after `exit` (both fire in
@@ -1650,7 +1839,7 @@ export async function safeSpawnAsync(command, args, options) {
             if (!killed && !child.killed) {
                 killed = true;
                 teardownStartedAtMs = Date.now();
-                killPromise = killTree();
+                killPromise = killTree("timeout");
             }
         }, timeout);
         // #620: stop the poll and log peak/average CPU%+RSS for this invocation
@@ -1817,6 +2006,7 @@ export async function safeSpawnAsync(command, args, options) {
             const outputInfo = {
                 ...(outputTruncated ? { outputTruncated: true } : {}),
                 ...(killedForOutputCap ? { killedForOutputCap: true } : {}),
+                ...(killFailed ? { killFailed: true } : {}),
             };
             const streamingMatchInfo = streamingMatch ? { streamingMatch: true } : {};
             // #1816: surface the signal name as a field on every path where one
@@ -1960,6 +2150,7 @@ export async function safeSpawnAsync(command, args, options) {
                 spawnFailure,
                 ...(outputTruncated ? { outputTruncated: true } : {}),
                 ...(killedForOutputCap ? { killedForOutputCap: true } : {}),
+                ...(killFailed ? { killFailed: true } : {}),
                 ...(streamingMatch ? { streamingMatch: true } : {}),
                 resourceUsage,
             });

package/node_modules/pi-lens/dist/clients/spawn-output-cap.js

@@ -1,5 +1,7 @@
 /**
- * The one reading of `SpawnResult.outputTruncated` (#2100).
+ * The one reading of `SpawnResult.outputTruncated` (#2100), the one output-cap
+ * number (#3375), and the bounded accumulator the `data` handlers that never
+ * reach `safeSpawnAsync` use instead of `+=` (#3383).
  *
  * Its own module for the same reason `ledger-bounds.ts` is: `spawn-outcome.ts`
  * is on the shared runner path that dozens of test files reach with a bare
@@ -7,6 +9,87 @@
  * every one of those mocks have to re-export it. This module has no imports, so
  * nobody has to mock it.
  */
+/**
+ * The cap `safeSpawnAsync` applies when a caller passes no `maxOutputBytes`
+ * (#3375).
+ *
+ * Before this existed, an omitted cap meant NO cap: `appendOutput` fell
+ * through to `current + text` and grew one JS string until V8 refused the next
+ * concatenation with `RangeError: Invalid string length`. That throw is raised
+ * inside a stdout/stderr `data` handler, where the awaiting caller's
+ * `try`/`catch` cannot reach it, so it left the Pi host as an uncaught
+ * exception (field report: Pi 0.86.1, 2026-09-22).
+ *
+ * 32 MiB is chosen against the tree's own deliberate ceilings, not invented:
+ * the most generous explicit cap any caller asks for is 16 MiB
+ * (`MAX_GIT_STATUS_OUTPUT_BYTES` in `clients/shared-checkout-guard.ts` and
+ * `clients/opaque-mutation-scan.ts`, `MAX_LS_FILES_OUTPUT_BYTES` in
+ * `clients/git-tracked-ignore.ts` — a monorepo's whole tracked-file list), and
+ * the rest sit at 8 MiB or 64 KiB. Doubling that ceiling means no consumer
+ * whose legitimate volume is within the most generous allowance a maintainer
+ * has ever justified can be truncated by the DEFAULT, while the retained
+ * string stays 16x below V8's max string length (2^29-24 bytes of ASCII), so
+ * the concatenation that crashed the host is now unreachable rather than
+ * merely less likely. A caller that genuinely needs more passes its own
+ * `maxOutputBytes`; it always wins.
+ */
+export const DEFAULT_MAX_OUTPUT_BYTES = 32 * 1024 * 1024;
+/**
+ * The bound for a stream `data` handler that accumulates a string OUTSIDE
+ * `safeSpawnAsync` (#3383).
+ *
+ * #3375 capped the shared spawn seam, which covered 98 of 110 call sites; the
+ * class sweep for it found five accumulators that never reach that seam — a
+ * forked analyze worker (`clients/mcp/review.ts`), the unref'd one-shot
+ * collector (`clients/child-unref.ts`, which cannot import the seam at all: it
+ * is what `safe-spawn.ts` itself depends on) and two installer interpreter
+ * probes. Each grew one JS string per chunk with no ceiling, so each could
+ * reach the identical ending: V8 refusing the next concatenation with
+ * `RangeError: Invalid string length` INSIDE a `data` handler, which is an
+ * uncaught exception that terminated the Pi host on 2026-09-22.
+ *
+ * Retention is HEAD-ONLY and whole-chunk: the first chunk that would cross the
+ * bound is dropped entire, not byte-prefixed. `safeSpawnAsync`'s own
+ * `appendOutput` keeps a head, a marker and a tail because its callers parse
+ * tool output where the tail carries the summary; every caller here wants a
+ * prefix (a JSON document, a `ps` table, one path line) and a whole-chunk drop
+ * cannot split a multi-byte character.
+ *
+ * `maxBytes` defaults to {@link DEFAULT_MAX_OUTPUT_BYTES} so every bounded
+ * accumulator in the tree answers to ONE reviewed number. NO production caller
+ * passes it; it is a parameter so the retention arithmetic can be pinned at a
+ * readable size (`createBoundedOutputSink(10)`) instead of only at 32 MiB.
+ * There is deliberately no sanitizing of it either: nothing passes a value that
+ * would need it, so a `Number.isFinite` arm would be mutation-inert.
+ */
+export function createBoundedOutputSink(maxBytes = DEFAULT_MAX_OUTPUT_BYTES) {
+    let text = "";
+    let retained = 0;
+    let truncated = false;
+    let observed = 0;
+    return {
+        append(chunk) {
+            const part = typeof chunk === "string" ? chunk : chunk.toString();
+            const bytes = Buffer.byteLength(part);
+            observed += bytes;
+            if (retained + bytes <= maxBytes) {
+                retained += bytes;
+                text += part;
+                return;
+            }
+            truncated = true;
+        },
+        get text() {
+            return text;
+        },
+        get truncated() {
+            return truncated;
+        },
+        get observedBytes() {
+            return observed;
+        },
+    };
+}
 /**
  * True when `outputTruncated` is the OUTPUT CAP's own verdict about this run,
  * and not a detail of some other ending.