@herbertgao/pi-extensions 2026.10.1 → 2026.10.2

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

@@ -1,2357 +0,0 @@
-/**
- * Safe cross-platform spawn utilities
- *
- * Provides both sync (deprecated) and async versions for gradual migration.
- *
- * Async version features:
- * - Non-blocking execution
- * - Proper process cleanup on timeout (no zombies)
- * - Batch execution with concurrency limits
- * - AbortSignal support for cancellation
- *
- * Migration guide:
- * - Change: safeSpawn(cmd, args, opts)
- * - To: await safeSpawnAsync(cmd, args, opts)
- */
-import { spawn, spawnSync, } from "node:child_process";
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { BoundedFifoMap, BoundedSet } from "./bounded-cache.js";
-import { logLatency } from "./latency-logger.js";
-import { incrementDegradationCount, recordDegradation, recordDegradationOnce, } from "./degradation-ledger.js";
-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 {
-    kind;
-    cause;
-    name = "SpawnFailureError";
-    constructor(kind, message, cause) {
-        super(message, { cause });
-        this.kind = kind;
-        this.cause = cause;
-    }
-}
-export function hasSpawnFailureKind(error, kind) {
-    return (error instanceof Error &&
-        "kind" in error &&
-        error.kind === kind);
-}
-/**
- * #2010: derive teardown evidence from observed timestamps.
- *
- * Pure by design so every branch is deterministically unit-testable,
- * including the natural-exit-at-budget-expiry race where the timeout
- * callback arms a kill against an already-dead child.
- *
- * - No recorded kill start (the guard saw the child already dying), no
- *   observed death at all, or death PREDATING the kill start: the child
- *   left on its own -> "exited", ms 0. Claiming a kill we cannot
- *   distinguish from a natural exit would be invented evidence.
- * - Death observed after the kill started: "escalate-kill" when the
- *   SIGKILL escalation fired, otherwise "killed-by-signal"; ms is the
- *   observed gap (floor 0 - clock jitter must never produce a negative).
- */
-export function resolveTeardownOutcome(input) {
-    // Another path (abort / output-limit) owns this death: emitting teardown
-    // evidence here would describe a kill this timeout didn't perform.
-    if (input.killStartedAtMs === undefined ||
-        input.deathObservedAtMs === undefined) {
-        return undefined;
-    }
-    // True natural-exit race: the child beat the budget-expired kill by a
-    // hair - death observed before (or exactly at) the kill start.
-    if (input.deathObservedAtMs <= input.killStartedAtMs) {
-        return { ms: 0, outcome: "exited" };
-    }
-    return {
-        ms: Math.max(0, input.deathObservedAtMs - input.killStartedAtMs),
-        outcome: input.escalated ? "escalate-kill" : "killed-by-signal",
-    };
-}
-function toError(error) {
-    return error instanceof Error ? error : new Error(String(error));
-}
-function errorCode(error) {
-    return error.code;
-}
-async function cwdIsUnresolvable(cwd) {
-    if (cwd === undefined)
-        return false;
-    try {
-        return !(await fs.promises.stat(cwd)).isDirectory();
-    }
-    catch {
-        return true;
-    }
-}
-function cwdIsUnresolvableSync(cwd) {
-    if (cwd === undefined)
-        return false;
-    try {
-        return !fs.statSync(cwd).isDirectory();
-    }
-    catch {
-        return true;
-    }
-}
-/**
- * Best-effort presence probe used ONLY to disambiguate ENOENT when the cwd is
- * ALSO unresolvable (#1340 review): a genuinely missing tool must classify as
- * tool-not-found even under a broken cwd, or auto-install can never repair it.
- * Absolute commands are probed directly (with PATHEXT variants on Windows);
- * bare names scan PATH. A relative-with-separator command under a broken cwd
- * is genuinely ambiguous -- we err toward cwd-unresolvable there, because
- * repairing the cwd is actionable while a reinstall loop (#1199) is not.
- */
-function commandProbablyPresent(command) {
-    const exts = process.platform === "win32"
-        ? [
-            "",
-            ...(process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD")
-                .split(";")
-                .filter(Boolean),
-        ]
-        : [""];
-    const existsWithExt = (base) => {
-        for (const ext of exts) {
-            try {
-                if (fs.existsSync(base + ext))
-                    return true;
-            }
-            catch {
-                // unreadable candidate -- keep probing
-            }
-        }
-        return false;
-    };
-    if (path.isAbsolute(command))
-        return existsWithExt(command);
-    if (command.includes("/") || command.includes("\\"))
-        return "ambiguous";
-    for (const dir of (process.env.PATH ?? "").split(path.delimiter)) {
-        if (dir && existsWithExt(path.join(dir, command)))
-            return true;
-    }
-    return false;
-}
-/**
- * Shared errno->bucket mapping. `cwdUnresolvable` is the only async-vs-sync
- * difference between the two public classifiers, so it arrives as a resolved
- * flag and everything else lives once (Sonar duplication finding, #1340).
- */
-function classifyWithCwdFlag(cause, options, cwdUnresolvable) {
-    const code = errorCode(cause);
-    let failure;
-    if (code === "ENOENT" &&
-        cwdUnresolvable &&
-        commandProbablyPresent(options.command) !== false) {
-        failure = new SpawnFailureError("cwd-unresolvable", `Cannot spawn ${options.command}: working directory is unresolvable (${options.cwd})`, cause);
-    }
-    else if (code === "ENOENT") {
-        failure = new SpawnFailureError("tool-not-found", `Cannot spawn ${options.command}: tool not found (${cause.message})`, cause);
-    }
-    else if (code === "EACCES" || code === "EPERM") {
-        failure = new SpawnFailureError("permission-denied", `Cannot spawn ${options.command}: permission denied`, cause);
-    }
-    else {
-        failure = new SpawnFailureError("spawn-failed", `Cannot spawn ${options.command}: ${cause.message}`, cause);
-    }
-    recordSpawnClassification(failure, options);
-    return failure;
-}
-const loggedSpawnClassifications = new Set();
-const SPAWN_CLASSIFICATION_LOG_CAP = 200;
-function recordSpawnClassification(failure, options) {
-    const pair = `${failure.kind}\0${options.command}`;
-    if (!loggedSpawnClassifications.has(pair)) {
-        if (loggedSpawnClassifications.size >= SPAWN_CLASSIFICATION_LOG_CAP) {
-            loggedSpawnClassifications.clear();
-        }
-        loggedSpawnClassifications.add(pair);
-        logExtension({
-            subsystem: "safe-spawn",
-            level: "debug",
-            message: "spawn failure classified",
-            metadata: {
-                kind: failure.kind,
-                command: options.command,
-                cwd: options.cwd,
-            },
-        });
-    }
-    if (failure.kind !== "tool-not-found") {
-        recordDegradation({
-            kind: "spawn-failure",
-            subject: options.command,
-            reason: `${failure.kind}${options.cwd ? ` in ${options.cwd}` : ""}`,
-        });
-    }
-}
-/** Classify a raw Node spawn error without discarding its errno-bearing Error. */
-export async function classifySpawnFailure(error, options) {
-    const cause = toError(error);
-    const needsCwdProbe = errorCode(cause) === "ENOENT";
-    const cwdUnresolvable = needsCwdProbe && (await cwdIsUnresolvable(options.cwd));
-    return classifyWithCwdFlag(cause, options, cwdUnresolvable);
-}
-function classifySpawnFailureSync(error, options) {
-    const cause = toError(error);
-    const needsCwdProbe = errorCode(cause) === "ENOENT";
-    const cwdUnresolvable = needsCwdProbe && cwdIsUnresolvableSync(options.cwd);
-    return classifyWithCwdFlag(cause, options, cwdUnresolvable);
-}
-// Vitest reloads modules inside a reused worker. Keep this registry on the
-// process so those module instances share one signal/exit listener set.
-const lifetimeStateKey = Symbol.for("pi-lens.safe-spawn.lifetime-state");
-const processWithLifetimeState = process;
-const lifetimeState = processWithLifetimeState[lifetimeStateKey] ??
-    (processWithLifetimeState[lifetimeStateKey] = {
-        pids: new Set(),
-        installed: false,
-    });
-/**
- * THE ownership predicate for every kill-by-raw-pid in this repo (#2042).
- *
- * A pid is signalable only when it is a LIVE DIRECT CHILD of this process.
- * `tests/clients/lsp/launch.test.ts` mocked `node:child_process` with a fake
- * child carrying the literal pid `2468`; `safeSpawnAsync` registered it in
- * `lifetimeState.pids`, the fake never emitted `close` so nothing removed it,
- * and at fork teardown `installLifetimeCleanup()` fired
- * `process.kill(-2468, "SIGKILL")`. On ~10 % of GitHub runners pid 2468 was
- * one of the job's own long-lived processes — that is the whole of #2042:
- * exit 137, no failing assertion, no kernel record, five weeks of "infra
- * kill" reruns. A `pid <= 0` guard would not have stopped it; 2468 is a
- * perfectly plausible pid. The defect is OWNERSHIP, not sign.
- *
- * Three guards fold into this one (net-count rule): `lsp/client.ts`'s
- * `pid <= 0`, `lsp/launch.ts`'s `handle.pid <= 0` plus its already-exited
- * recycled-pid check, and `killTree`'s `child.pid > 0` below. It closes
- * fabricated, stale and recycled pids together.
- *
- * NOT folded: `instance-reaper.ts#killPidTree`. Its pids come from OTHER
- * pi-lens instances' registries and from an OS scan of managed binaries with
- * confirmed-dead parents — deliberately NOT our children. Its `!isFinite ||
- * pid <= 0` guard is well-formedness on a different axis, and applying this
- * predicate there would turn the orphan reaper into a no-op.
- *
- * Platform behaviour, stated rather than implied:
- *  - Linux (the authoritative lane, and the one that lost five weeks):
- *    `/proc/<pid>/status` is the kernel's own answer. Missing entry = the pid
- *    does not exist, so there is nothing of ours to kill; `PPid` other than
- *    ours = someone else's process, which is recorded and never signalled.
- *  - Windows and macOS have no `/proc` (and neither does a Linux host with
- *    `/proc` unmounted — probed once, not assumed from `process.platform`),
- *    so ownership is unverifiable from a raw pid and the predicate keeps
- *    today's best-effort behaviour. The `handle` arm applies THERE and only
- *    there: it is the only ownership evidence Windows has, and it is what
- *    `killWindowsTree` already used. It must not gate the POSIX group kill,
- *    which legitimately runs after its leader has died (#3091 F1).
- */
-/**
- * Whether `/proc/<pid>/status` can actually be read here, probed ONCE against
- * this process's own entry (#3091 F4). `process.platform === "linux"` is not
- * the same question: a container or a hardened host can run Linux with no
- * `/proc` mounted, and there the per-pid read fails exactly the way a dead pid
- * does. Without this probe that silently refused every registration, so
- * `lifetimeState.pids` stayed empty and the host-exit tree kill stopped working
- * with no record anywhere.
- */
-const PROC_PPID_READABLE = (() => {
-    if (process.platform !== "linux")
-        return false;
-    try {
-        return /^PPid:\s*\d+$/m.test(fs.readFileSync("/proc/self/status", "utf8"));
-    }
-    catch {
-        return false;
-    }
-})();
-/**
- * Pids this process has PROVEN, from the kernel, to be its own live children.
- * FIFO-bounded (`BoundedFifoMap`, not a wholesale clear): a process that spawns
- * more than the cap drops its OLDEST verdicts, where a wholesale clear would
- * drop the one it is about to need.
- */
-export const VERIFIED_OWN_PID_CAP = 512;
-const verifiedOwnPids = new BoundedFifoMap(VERIFIED_OWN_PID_CAP);
-/**
- * Pids whose OWNERSHIP IS HELD for the lifetime of a long-lived resource —
- * today, the LSP children `clients/lsp/launch.ts` spawns with `nodeSpawn`
- * (#3091 F1-r2b).
- *
- * These deliberately do NOT live in `verifiedOwnPids`. Age is the wrong
- * retirement axis for a resource-scoped verdict: an LSP leader is verified once
- * at spawn and then sits untouched for the whole session, so in a FIFO that
- * every `safeSpawnAsync` writes to it is the OLDEST entry and therefore the
- * FIRST evicted — measured, 520 later verdicts were enough — and its group kill
- * at host exit is refused precisely because the server was long-lived enough to
- * matter. Retirement here is by RESOURCE STATE instead: `releaseOwnChildPid`
- * when the shutdown ladder is done with the pid, plus the confirmed-dead sweep
- * below for the paths that never reach a ladder (a server that crashes, or a
- * host killed mid-session).
- *
- * The bound that remains, stated rather than implied: at most
- * `HELD_OWN_PID_SWEEP_AT` entries — the confirmed-dead sweep below runs before
- * every insert, and `BoundedSet`'s own FIFO overflow is the last resort for the
- * case where every held group really is still alive. A crash-looping server cannot grow it without bound
- * because each sweep drops every pid whose process GROUP no longer exists,
- * which is exactly the condition under which the entry can never be needed
- * again.
- */
-const HELD_OWN_PID_SWEEP_AT = 256;
-const heldOwnPids = new BoundedSet(HELD_OWN_PID_SWEEP_AT);
-/** A process group that no longer exists can never need another signal. */
-function groupIsGone(pid) {
-    try {
-        process.kill(-pid, 0);
-        return false;
-    }
-    catch (error) {
-        return errorCode(error) === "ESRCH";
-    }
-}
-function sweepHeldOwnPids() {
-    if (heldOwnPids.size < HELD_OWN_PID_SWEEP_AT)
-        return;
-    // Deleting the current entry mid-iteration is well-defined for a Set, so
-    // no snapshot copy is needed.
-    for (const pid of heldOwnPids) {
-        if (groupIsGone(pid))
-            heldOwnPids.delete(pid);
-    }
-    // No hand-rolled "drop the oldest" block (#2442 / #3091 round 4): the
-    // last-resort eviction, for the case where every held group is still alive
-    // at the ceiling, is `BoundedSet.add`'s own FIFO overflow.
-}
-/**
- * Verify a pid at ADMISSION and hold the verdict for the resource's lifetime.
- *
- * This is AGENTS.md shape 50's own rule, which #3091 round 1 broke at the site
- * it was fixing: `isOwnLiveChild`'s three call sites were the `safeSpawnAsync`
- * registration, the Windows tree kill, and the SHUTDOWN group kill — so for an
- * LSP child, spawned with `nodeSpawn`, the first offer of verification was also
- * the last, and on the `processExiting` path the leader could already be dead
- * by then (`/proc` gone, nothing on record, signal refused, grandchildren
- * orphaned).
- */
-export function holdOwnChildPid(pid, site) {
-    const owned = isOwnLiveChild(pid, site);
-    if (!owned || !PROC_PPID_READABLE || typeof pid !== "number")
-        return owned;
-    // Exactly one home: the verification above filed the verdict in the
-    // age-bounded FIFO, and leaving a copy there would make BOTH the held set
-    // and its release mutation-inert — the FIFO copy would answer for them.
-    verifiedOwnPids.delete(pid);
-    sweepHeldOwnPids();
-    heldOwnPids.add(pid);
-    return true;
-}
-/**
- * Retire a held pid once nothing will signal it again — the end of the
- * shutdown ladder. Idempotent.
- */
-export function releaseOwnChildPid(pid) {
-    if (typeof pid === "number")
-        heldOwnPids.delete(pid);
-}
-/** Once per session: a Linux host whose `/proc` cannot answer the question. */
-function recordProcUnavailable(site) {
-    if (process.platform !== "linux")
-        return;
-    recordDegradationOnce({
-        kind: "kill-ownership-unverifiable",
-        subject: site,
-        reason: "/proc/self/status is unreadable on this Linux host; kill-by-pid ownership falls back to best-effort",
-    });
-}
-export function isOwnLiveChild(pid, site, handle) {
-    if (typeof pid !== "number" || !Number.isInteger(pid) || pid <= 0)
-        return false;
-    if (!PROC_PPID_READABLE) {
-        // No `/proc` to consult. A handle that has already reported exit is then
-        // the ONLY ownership evidence available, and it is exactly what
-        // `killWindowsTree` used before this predicate existed: a dead pid may
-        // have been recycled, and `taskkill /F /T` on a recycled pid destroys an
-        // unrelated tree. It overrides the memo below deliberately.
-        if (handle && (handle.exitCode != null || handle.signalCode != null))
-            return false;
-        recordProcUnavailable(site);
-        return true;
-    }
-    let status;
-    try {
-        status = fs.readFileSync(`/proc/${pid}/status`, "utf8");
-    }
-    catch {
-        // The pid does not exist. Not a degradation — a child that exited before
-        // the teardown signal is the ordinary case — but not automatically a
-        // refusal either: a POSIX process GROUP outlives its leader, and #2026's
-        // whole point is that the escalation must still reach a SIGTERM-hardy
-        // grandchild after the direct child has died. Ownership verified while
-        // the leader was alive is what answers that; a pid this process never
-        // owned is still refused.
-        return heldOwnPids.has(pid) || verifiedOwnPids.has(pid);
-    }
-    const parent = /^PPid:\s*(\d+)$/m.exec(status);
-    if (!parent)
-        return true;
-    if (Number(parent[1]) === process.pid) {
-        // Memoized only on a KERNEL-verified verdict, and only here: a pid we
-        // never proved was ours can never enter the memo, and a pid that is
-        // alive under a different parent is refused above regardless of what the
-        // memo holds — so a recycled pid cannot be signalled on the strength of
-        // its previous owner.
-        //
-        // Never for a pid already HELD, though: the shutdown ladder verifies a
-        // still-live leader on its way to the group signal, and filing that
-        // verdict in the FIFO too would put a held pid back in both stores —
-        // which outlives `releaseOwnChildPid` (the FIFO copy would keep
-        // answering for a pid this process has explicitly stopped claiming) and
-        // makes the held store's own tests unable to fail.
-        if (!heldOwnPids.has(pid))
-            verifiedOwnPids.set(pid, true);
-        return true;
-    }
-    // Alive AND someone else's: the dangerous case, and the only one worth a
-    // record. Subject is the SITE (a fixed, tiny set), never the pid, so the
-    // ledger stays bounded however often it fires.
-    incrementDegradationCount({
-        kind: "kill-foreign-pid-refused",
-        subject: site,
-        reason: `pid ${pid} has parent ${parent[1]}, not this process — signal refused`,
-    });
-    return false;
-}
-/**
- * Kill one registered pid's tree at host exit. Deliberately NOT re-checked
- * against `isOwnLiveChild` here: `lifetimeState.pids` has exactly one writer
- * (the registration below), that writer is now gated, and a second gate on
- * the same feeder would make BOTH mutation-inert — remove either one and the
- * other still blocks the kill, so neither would have a test that reds. The
- * gate lives where the pid enters, which is also where ownership is a fact
- * rather than a stale reading (#2042).
- */
-function killPidTreeSync(pid) {
-    if (process.platform === "win32") {
-        try {
-            const taskkill = `${process.env.SystemRoot ?? "C:\\Windows"}\\System32\\taskkill.exe`;
-            spawnSync(taskkill, ["/F", "/T", "/PID", String(pid)], {
-                shell: false,
-                windowsHide: true,
-                stdio: "ignore",
-            });
-        }
-        catch {
-            // Runs from process `exit`/signal handlers — a SYNCHRONOUS spawn throw
-            // (Windows `spawn UNKNOWN`/EINVAL, the pidusage bug class, #533) would
-            // become an uncaughtException during shutdown. Best-effort tree-kill:
-            // swallow it, mirroring the already-guarded POSIX branch below.
-        }
-        return;
-    }
-    try {
-        // #2026: negative pid = whole process group (POSIX children spawn
-        // detached), reaching grandchildren too. Any failure (ESRCH = already
-        // gone, EPERM = raced) falls through to the direct-child attempt.
-        try {
-            process.kill(-pid, "SIGKILL");
-        }
-        catch {
-            process.kill(pid, "SIGKILL");
-        }
-    }
-    catch {
-        // Child already exited.
-    }
-}
-function installLifetimeCleanup() {
-    if (lifetimeState.installed)
-        return;
-    lifetimeState.installed = true;
-    process.once("exit", () => {
-        for (const pid of lifetimeState.pids)
-            killPidTreeSync(pid);
-    });
-    for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
-        process.once(signal, () => {
-            for (const pid of lifetimeState.pids)
-                killPidTreeSync(pid);
-            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,
-                    },
-                });
-            }
-        });
-    }
-}
-// ============================================================================
-// AMBIENT TURN ABORT SIGNAL
-// ============================================================================
-/**
- * The current turn's abort signal, published by the lifecycle handlers from
- * pi's `ctx.signal`. Threading the signal explicitly through every
- * dispatch → runner → spawn call site would be invasive, so instead
- * `safeSpawnAsync` defaults to this ambient signal when a call doesn't pass its
- * own. The effect: pressing Esc mid-turn aborts in-flight linter / formatter /
- * type-checker child processes (process-tree kill on Windows) instead of letting
- * them run to their timeout.
- *
- * Each spawn captures the signal at call time (attaching its own abort listener),
- * so clearing this after a handler returns only affects *future* spawns — work
- * already in flight keeps the signal it started with.
- */
-let ambientAbortSignal;
-/** Publish (or clear, with `undefined`) the current turn's abort signal. */
-export function setAmbientAbortSignal(signal) {
-    ambientAbortSignal = signal;
-}
-/**
- * The current turn's abort signal, for in-process awaits that aren't child
- * spawns (e.g. an LSP JSON-RPC write that can backpressure on a wedged server).
- * Child spawns read the ambient signal internally; this getter lets the
- * interactive pipeline honor Escape on non-spawn LSP calls too.
- */
-export function getAmbientAbortSignal() {
-    return ambientAbortSignal;
-}
-// ============================================================================
-// INTERNAL HELPERS
-// ============================================================================
-/**
- * Escape a single argument for the Windows command interpreter.
- * The result is embedded in the `/c` command string below, so metacharacters
- * must remain inside a quoted argument rather than becoming command syntax.
- */
-function cmdEscapeArg(arg) {
-    if (!/[\s"&|<>^()]/.test(arg))
-        return arg;
-    return `"${arg.replace(/"/g, '""')}"`;
-}
-/**
- * Build the cmd.exe command string used for Windows wrapper spawning.
- *
- * The COMMAND must be escaped the same way as the args — escaping only the args
- * (the bug behind #214) means a tool whose resolved path contains a space (e.g.
- * `C:\Program Files\Go\bin\go.exe`) makes cmd.exe parse `C:\Program` as the
- * command and fail with "'C:\Program' is not recognized". `cmdEscapeArg` is a
- * no-op for space-free commands, so this is safe for the npm/.pi-lens tool paths
- * that already worked. The `chcp 65001` prefix forces the UTF-8 code page (so
- * tool output isn't mangled by the system code page) and, as a side benefit,
- * keeps the (possibly quoted) command off the front of the line, avoiding
- * cmd.exe's `/s` outer-quote-stripping quirk. #2023: chcp is invoked via its
- * absolute `%SystemRoot%\System32\chcp.com` path and chained with `&`, not
- * `&&` — a child environment whose PATH cannot resolve System32 used to fail
- * the bare `chcp` lookup, and `&&` then short-circuited EVERY .cmd/.bat spawn
- * into exit 1 with empty output. With the pin plus `&`, even a chcp failure
- * can never suppress the real command.
- */
-export function buildWindowsShellCommand(command, args) {
-    const chcp = `${process.env.SystemRoot ?? "C:\\Windows"}\\System32\\chcp.com`;
-    return `${chcp} 65001 >nul 2>&1 & ${[command, ...args].map(cmdEscapeArg).join(" ")}`;
-}
-/**
- * The extensions this resolver treats as executable suffixes on their own,
- * independent of PATHEXT: `.exe`/`.com` and `.cmd`/`.bat`. An explicit suffix
- * outside this set is not treated as a "known executable extension" unless
- * the caller's own PATHEXT says so (#1201).
- *
- * This is a RESOLUTION set, not a dispatch whitelist — do not read it as "the
- * only extensions this module can spawn". Dispatch in
- * `safeSpawnAsync`/`safeSpawn` below routes `.cmd`/`.bat` through the cmd.exe
- * wrapper and EVERYTHING ELSE to direct spawn, so a resolved path with any
- * other suffix (reachable only when the caller's own PATHEXT lists it) is
- * direct-spawned. That is deliberate and not a widening: CreateProcess does no
- * ShellExecute file-association lookup, the default Windows PATHEXT already
- * contains `.VBS`/`.JS`/`.WSF`/`.MSC`, and the set here is strictly narrower
- * than the pre-#1201 behavior. Only the doc claim was ever wrong.
- */
-const WINDOWS_DIRECT_RESOLVABLE_EXTS = new Set([
-    ".exe",
-    ".com",
-    ".cmd",
-    ".bat",
-]);
-/**
- * Merge a parent and child environment using Windows' case-insensitive variable
- * names. Node's JavaScript environment object can contain both `PATH` and
- * `Path`, even though Windows treats them as one variable. Removing an older
- * spelling before each assignment gives explicit child overrides precedence
- * over every ambient spelling and ensures the environment passed to spawn has
- * one unambiguous value.
- */
-export function mergeWindowsEnvironment(base, overrides) {
-    const entries = new Map();
-    const assign = (source) => {
-        if (!source)
-            return;
-        for (const [key, value] of Object.entries(source)) {
-            const folded = key.toLowerCase();
-            // Delete before setting so the last explicit spelling wins while the
-            // folded map remains O(n) instead of scanning the merged object for
-            // every environment entry.
-            entries.delete(folded);
-            if (value !== undefined)
-                entries.set(folded, { key, value });
-        }
-    };
-    assign(base);
-    assign(overrides);
-    const merged = {};
-    for (const { key, value } of entries.values())
-        merged[key] = value;
-    return merged;
-}
-function getWindowsEnvironmentValue(env, name) {
-    let value;
-    for (const [key, entry] of Object.entries(env)) {
-        if (key.toLowerCase() === name.toLowerCase())
-            value = entry;
-    }
-    return value;
-}
-function driveLetter(value) {
-    const match = /^([A-Za-z]):/.exec(value);
-    return match?.[1]?.toUpperCase();
-}
-function isDriveAbsolute(value, drive) {
-    return (value.length >= 3 &&
-        value[0]?.toUpperCase() === drive.toUpperCase() &&
-        value[1] === ":" &&
-        (value[2] === "\\" || value[2] === "/"));
-}
-/** `X:\...` or `X:/...` — a drive-absolute path, for any drive letter. */
-function isDriveAbsoluteAnyDrive(value) {
-    const drive = driveLetter(value);
-    return drive !== undefined && isDriveAbsolute(value, drive);
-}
-/** `\\server\share\...` — a UNC path. Two leading separators, not more. */
-function isUncWindowsPath(value) {
-    return ((value[0] === "\\" || value[0] === "/") &&
-        (value[1] === "\\" || value[1] === "/") &&
-        value[2] !== "\\" &&
-        value[2] !== "/");
-}
-/**
- * A path is "fully qualified" (self-contained, no ambient current-directory
- * lookup required) only when it is drive-absolute (`X:\...`) or UNC
- * (`\\server\share`). `path.win32.isAbsolute("\tools")` also returns `true`
- * for a *rooted* path — one relative to the current drive's root rather than
- * a specific drive — and treating that as fully qualified was the #1201
- * bug: it got statSync'd against the *host* drive while a different
- * `effectiveCwd`/`resolvedDrive` supplied the drive cmd.exe actually used to
- * execute it, so a different file could be validated than executed.
- */
-function isFullyQualifiedWindowsPath(value) {
-    return isFullyQualifiedWin32(value) && !isRootedWindowsPath(value);
-}
-/**
- * `\tools` or `/tools` — rooted at the current drive's root, but naming no
- * drive of its own (distinct from both `X:\tools` fully-qualified and
- * `X:tools` drive-relative-to-current-directory). Windows resolves this
- * against the root of whichever drive is "current", not the current
- * directory on that drive.
- */
-function isRootedWindowsPath(value) {
-    return ((value[0] === "\\" || value[0] === "/") &&
-        driveLetter(value) === undefined &&
-        !isUncWindowsPath(value));
-}
-/**
- * Resolve a rooted path (`\tools`) against the ROOT of `driveSource`'s drive
- * — not `driveSource` itself — matching Windows' own rooted-path semantics.
- *
- * When `driveSource` carries NO drive letter, this returns the normalized
- * value rather than `undefined` (#1201, recurring defect shape 2). A
- * drive-less "current drive" provenance means we are not on a drive-lettered
- * filesystem at all — a POSIX host, or a UNC `process.cwd()` such as
- * `\\server\share\...`, which Node permits on real Windows. In that namespace
- * a rooted path is already as qualified as any path can be, so there is
- * nothing to anchor and normalizing is the correct (and pre-#1201) answer.
- * Returning `undefined` instead used to collapse the whole resolution to
- * `null` without a single `statSync`, i.e. a false ENOENT — the exact failure
- * signature #1199 exists to remove. This function must therefore never fail
- * closed on the *shape* of a value that may not be a Windows path at all;
- * the filesystem probe downstream is what decides whether it exists.
- */
-function resolveRootedWindowsPath(value, driveSource) {
-    const drive = driveLetter(driveSource);
-    if (drive === undefined)
-        return path.win32.normalize(value);
-    return path.win32.normalize(path.win32.resolve(`${drive}:\\`, value));
-}
-/**
- * Return a validated Windows per-drive current directory. Windows exposes
- * these as environment entries such as `=D:`; unlike ordinary environment
- * variables they are not safe to synthesize from a drive letter. A malformed
- * or wrong-drive value is deliberately ignored so drive-relative resolution
- * fails closed instead of guessing a root.
- *
- * Node never surfaces `=X:` keys from the ambient `process.env` (verified:
- * `Object.keys(process.env).filter(k => k.startsWith("="))` is empty), so
- * this provenance is only ever available when a caller supplies it
- * explicitly in an `env` override — e.g. a test, or a future integration
- * that reads it from a lower-level Windows API. That's a real, if narrow,
- * use: keep this path rather than deleting it, but never synthesize a value
- * Node itself can't hand us.
- */
-function getValidatedPerDriveCwd(env, drive) {
-    const value = getWindowsEnvironmentValue(env, `=${drive}:`);
-    if (value === undefined || !isDriveAbsolute(value, drive))
-        return undefined;
-    return path.win32.normalize(value);
-}
-function resolveEffectiveWindowsCwd(cwd, env) {
-    if (cwd === undefined) {
-        // No caller-supplied cwd: `process.cwd()` IS the effective cwd already —
-        // the real, canonical filesystem cwd of THIS process, not a string that
-        // needs (re)classifying. On a POSIX CI host it naturally carries no
-        // drive letter; that's fine, it never needs one here. Only a
-        // CALLER-SUPPLIED cwd string goes through the fully-qualified/rooted/
-        // drive-relative classification below — running `process.cwd()`'s own
-        // value through `isRootedWindowsPath` was itself a #1201 regression: a
-        // drive-less POSIX path (e.g. Linux CI's real cwd) satisfies that
-        // predicate too (single leading separator, no drive letter), which then
-        // sent it to `resolveRootedWindowsPath` looking for a drive letter on
-        // `process.cwd()` that — being the very same drive-less string — could
-        // never supply one, resolving to `undefined` (recurring defect shape
-        // 2/7: `path.win32.resolve` falls back to `process.cwd()`, which
-        // supplies a drive on Windows and none on Linux).
-        return path.win32.normalize(process.cwd());
-    }
-    const requestedDrive = driveLetter(cwd);
-    if (requestedDrive !== undefined && !isDriveAbsoluteAnyDrive(cwd)) {
-        // `D:foo` — drive-relative to that drive's own current directory.
-        const base = getValidatedPerDriveCwd(env, requestedDrive);
-        return base === undefined
-            ? undefined
-            : path.win32.normalize(path.win32.resolve(base, cwd));
-    }
-    if (isFullyQualifiedWindowsPath(cwd))
-        return path.win32.normalize(cwd);
-    if (isRootedWindowsPath(cwd)) {
-        // `\tools` — rooted at the CURRENT drive's root.
-        //
-        // Note the deliberate asymmetry with `resolveWindowsPathEntry`, which
-        // anchors rooted PATH entries to `effectiveCwd`'s drive instead. Both
-        // use the SAME rule — "anchor to the best available "current drive"
-        // provenance at this point in the pipeline" — they just sit at
-        // different points. Here we are *computing* `effectiveCwd`, so it does
-        // not exist yet and the process's own cwd is the only provenance
-        // available (on real Windows it always carries a drive letter). By the
-        // time a PATH entry is resolved, `effectiveCwd` is known and is the
-        // strictly better answer, because it is the drive the child will
-        // actually run from — anchoring PATH entries to the host drive there
-        // would validate one file and execute another. Neither call can fail
-        // closed on a drive-less provenance; see `resolveRootedWindowsPath`.
-        return resolveRootedWindowsPath(cwd, process.cwd());
-    }
-    return path.win32.normalize(path.win32.resolve(process.cwd(), cwd));
-}
-function resolveDriveRelativeWindowsPath(value, effectiveCwd, env) {
-    const drive = driveLetter(value);
-    if (drive === undefined)
-        return undefined;
-    const cwdDrive = effectiveCwd === undefined ? undefined : driveLetter(effectiveCwd);
-    const base = cwdDrive?.toUpperCase() === drive
-        ? effectiveCwd
-        : getValidatedPerDriveCwd(env, drive);
-    if (base === undefined)
-        return undefined;
-    return path.win32.normalize(path.win32.resolve(base, value));
-}
-function resolveWindowsPathEntry(entry, effectiveCwd, env) {
-    if (driveLetter(entry) !== undefined && !isDriveAbsoluteAnyDrive(entry)) {
-        return resolveDriveRelativeWindowsPath(entry, effectiveCwd, env);
-    }
-    if (isFullyQualifiedWindowsPath(entry))
-        return path.win32.normalize(entry);
-    if (isRootedWindowsPath(entry)) {
-        // `\tools` — rooted at the effective child cwd's drive root, not the
-        // host process's drive (#1201: a rooted PATH entry must resolve on
-        // the SAME drive the child will actually run cmd.exe/the resolved
-        // binary from). See `resolveEffectiveWindowsCwd`'s rooted branch for
-        // why that function anchors to `process.cwd()` instead — same rule,
-        // different point in the pipeline. `undefined` here means the cwd
-        // itself was unprovable, which is a genuinely different condition
-        // from "the provenance carries no drive letter".
-        return effectiveCwd === undefined
-            ? undefined
-            : resolveRootedWindowsPath(entry, effectiveCwd);
-    }
-    if (effectiveCwd === undefined)
-        return undefined;
-    return path.win32.normalize(path.win32.resolve(effectiveCwd, entry));
-}
-/**
- * Cached PATH + PATHEXT resolution results. The effective child environment is
- * part of the key, not the ambient process environment: one caller's managed
- * bin directory must never poison another caller's resolution. The key also
- * carries the canonical child cwd and Windows `=X:` per-drive cwd entries,
- * because both affect relative PATH and drive-relative lookup. Session-lived
- * (matches this repo's other resolution caches, e.g.
- * `clients/workspace-topology.ts`'s `resetWorkspaceTopology`) — cleared via
- * `resetSafeSpawnWindowsCommandCache()`, wired into `handleSessionStart`. The
- * cache is also count-bounded with oldest-entry eviction because a long-lived
- * process can encounter unbounded cwd/environment combinations.
- */
-export const WINDOWS_COMMAND_CACHE_MAX_ENTRIES = 256;
-const WINDOWS_COMMAND_NEGATIVE_CACHE_TTL_MS = 1000;
-const windowsCommandCache = new BoundedFifoMap(WINDOWS_COMMAND_CACHE_MAX_ENTRIES);
-/** Reset after session replacement or a successful managed install. */
-export function resetSafeSpawnWindowsCommandCache() {
-    windowsCommandCache.clear();
-    loggedSpawnClassifications.clear();
-}
-function cacheWindowsCommandResult(key, resolved) {
-    // Resolution entries are session-scoped and cheap to recompute. The
-    // caller always deletes any stale entry for `key` before reaching here
-    // (see resolveWindowsCommandForEnvironment), so this can only grow the
-    // map; BoundedFifoMap evicts the oldest insertion first once the map
-    // exceeds capacity, so a long-lived process cannot retain every cwd /
-    // environment it has ever touched.
-    windowsCommandCache.set(key, { resolved, checkedAt: Date.now() });
-}
-function getPathExts(env) {
-    const raw = getWindowsEnvironmentValue(env, "PATHEXT") ?? ".COM;.EXE;.BAT;.CMD";
-    return raw
-        .split(";")
-        .map((ext) => ext.trim().toLowerCase())
-        .filter(Boolean);
-}
-function statIsFile(candidate) {
-    try {
-        return fs.statSync(candidate).isFile();
-    }
-    catch {
-        return false;
-    }
-}
-function resolveWindowsCommandUncached(command, effectiveCwd, env) {
-    const pathExts = getPathExts(env);
-    const existingExt = path.win32.extname(command).toLowerCase();
-    const hasExplicitExt = existingExt.length > 0;
-    // A suffix is "known executable" when it's one of the four extensions this
-    // resolver actually knows how to run (direct .exe/.com, or the
-    // cmd.exe-wrapped .cmd/.bat) OR it's explicitly listed in the caller's own
-    // PATHEXT. Anything else with a dot is NOT necessarily "an extension" — a
-    // versioned interpreter (`python3.11`, `node-v20.1`) has an `extname()` of
-    // `.11`/`.1` that is part of the basename, not a suffix to match exactly
-    // (#1201).
-    const isKnownExecutableExt = (ext) => WINDOWS_DIRECT_RESOLVABLE_EXTS.has(ext) || pathExts.includes(ext);
-    const tryBase = (base) => {
-        // Additive, not exclusive: an explicit, known-executable suffix is
-        // tried as an exact candidate FIRST (this also lets a caller ask for
-        // `foo.cmd` even when the current PATHEXT doesn't happen to list
-        // `.CMD`). Whenever the suffix ISN'T a PATHEXT entry — no extension at
-        // all, or a versioned/unknown one like `.11` — the PATHEXT-append loop
-        // ALSO runs against the full base, so `python3.11` still finds
-        // `python3.11.exe`. An unknown suffix (e.g. `foo.txt`) never gets an
-        // exact-match short-circuit: that would let an arbitrary
-        // non-executable file resolve as "spawnable" and reach the
-        // direct-spawn branch downstream.
-        if (hasExplicitExt &&
-            isKnownExecutableExt(existingExt) &&
-            statIsFile(base)) {
-            return { resolvedPath: base, ext: existingExt };
-        }
-        if (!hasExplicitExt || !pathExts.includes(existingExt)) {
-            for (const ext of pathExts) {
-                const candidate = base + ext;
-                if (statIsFile(candidate))
-                    return { resolvedPath: candidate, ext };
-            }
-        }
-        return null;
-    };
-    const hasPathSep = /[\\/]/.test(command);
-    // `D:tool.exe` is drive-relative on Windows, not a bare PATH command. It
-    // uses the effective cwd only when that cwd is on D:. For another drive we
-    // require an explicit, validated `=D:` provenance entry; otherwise this
-    // resolver fails closed rather than guessing `D:\\` or searching PATH.
-    const hasDrivePrefix = driveLetter(command) !== undefined;
-    if (hasPathSep || hasDrivePrefix || isFullyQualifiedWindowsPath(command)) {
-        let base;
-        if (isFullyQualifiedWindowsPath(command)) {
-            base = path.win32.normalize(command);
-        }
-        else if (hasDrivePrefix) {
-            base = resolveDriveRelativeWindowsPath(command, effectiveCwd, env);
-        }
-        else if (isRootedWindowsPath(command)) {
-            base =
-                effectiveCwd === undefined
-                    ? undefined
-                    : resolveRootedWindowsPath(command, effectiveCwd);
-        }
-        else if (effectiveCwd !== undefined) {
-            base = path.win32.normalize(path.win32.resolve(effectiveCwd, command));
-        }
-        return base === undefined ? null : tryBase(base);
-    }
-    // A bare command (no path separator) is a plain PATH search. Absolute PATH
-    // entries don't need `effectiveCwd` at all, so an unresolvable cwd must
-    // only skip the relative entries (handled per-entry in
-    // resolveWindowsPathEntry below), not abort the whole search (#1201: a bad
-    // cwd shouldn't make an otherwise-resolvable command look "not installed").
-    const pathValue = getWindowsEnvironmentValue(env, "PATH") ?? "";
-    const pathDirs = pathValue.split(path.win32.delimiter);
-    for (const dir of pathDirs) {
-        if (!dir)
-            continue;
-        const resolvedDir = resolveWindowsPathEntry(dir, effectiveCwd, env);
-        if (resolvedDir === undefined)
-            continue;
-        const found = tryBase(path.win32.join(resolvedDir, command));
-        if (found)
-            return found;
-    }
-    return null;
-}
-/**
- * Resolve a Windows command using the exact environment that will be passed to
- * the child. Exported as a small platform-independent test/diagnostic seam;
- * callers should pass a Windows-shaped environment and do not need to mutate
- * `process.env` to exercise resolution. Drive-relative commands (`D:tool.exe`)
- * use a same-drive effective cwd, or a validated absolute `=D:` entry for a
- * different drive; without that provenance they fail closed and never search
- * PATH. Relative PATH entries use the canonical effective child cwd.
- */
-export function resolveWindowsCommandForEnvironment(command, cwd, env) {
-    const effectiveCwd = resolveEffectiveWindowsCwd(cwd, env);
-    const pathValue = getWindowsEnvironmentValue(env, "PATH");
-    const pathExtValue = getWindowsEnvironmentValue(env, "PATHEXT");
-    const perDriveCwds = Object.entries(env)
-        .flatMap(([key, value]) => /^=[A-Za-z]:$/.test(key)
-        ? [[key.toLowerCase(), value]]
-        : [])
-        .sort(([left], [right]) => compareOrdinal(left, right));
-    // Keep presence separate from value: absent PATHEXT means the Windows
-    // default extension list, while PATHEXT="" means no implicit extensions.
-    // The per-drive snapshot is equally important: it is provenance for
-    // drive-relative commands and PATH entries, not ambient decoration.
-    const cacheKey = JSON.stringify([
-        "win32",
-        command,
-        pathValue === undefined ? ["absent"] : ["present", pathValue],
-        pathExtValue === undefined ? ["absent"] : ["present", pathExtValue],
-        effectiveCwd === undefined ? ["unresolved"] : ["resolved", effectiveCwd],
-        perDriveCwds,
-    ]);
-    const cached = windowsCommandCache.get(cacheKey);
-    if (cached) {
-        // Positive entries are revalidated on every hit so an executable deleted
-        // or replaced mid-session cannot remain spawnable through stale cache
-        // state. Negative entries are short-lived to discover external installs;
-        // pi-lens-managed installs also reset the cache immediately on success.
-        if (cached.resolved && statIsFile(cached.resolved.resolvedPath)) {
-            return cached.resolved;
-        }
-        if (!cached.resolved &&
-            Date.now() - cached.checkedAt <= WINDOWS_COMMAND_NEGATIVE_CACHE_TTL_MS) {
-            return null;
-        }
-        windowsCommandCache.delete(cacheKey);
-    }
-    const resolved = resolveWindowsCommandUncached(command, effectiveCwd, env);
-    cacheWindowsCommandResult(cacheKey, resolved);
-    return resolved;
-}
-/** Cached `where`-equivalent for the effective child environment. */
-function resolveWindowsCommand(command, cwd, env) {
-    return resolveWindowsCommandForEnvironment(command, cwd, env);
-}
-function getSpawnEnvironment(overrides) {
-    return process.platform === "win32"
-        ? mergeWindowsEnvironment(process.env, overrides)
-        : { ...process.env, ...overrides };
-}
-/**
- * Characters that make a cmd.exe `/c` command line unsound to build from
- * caller-tainted input: `%`/`!` expand even inside double quotes and cannot
- * be escaped on a `/c` line (only `%%` works, and only in batch files), `"`
- * can toggle cmd's quote-parsing state past the doubling convention, and
- * CR/LF let an argument masquerade as a second command. Reject rather than
- * attempt to escape these (#817) — silent stripping would just move the
- * unsoundness, not remove it.
- */
-const CMD_UNSAFE_CHARS = /["%!\r\n]/;
-/** First caller-tainted value (command or an arg) that can't be safely
- * passed through the .cmd/.bat cmd.exe wrapper, or `undefined` if all clear. */
-function findCmdUnsafeValue(command, args) {
-    if (CMD_UNSAFE_CHARS.test(command))
-        return command;
-    return args.find((arg) => CMD_UNSAFE_CHARS.test(arg));
-}
-function synthesizeEnoentError(command) {
-    // Shaped like Node's native `spawn <cmd> ENOENT` error (message/code/
-    // syscall/path) so the typed classifier retains the same diagnostic cause
-    // now that Windows resolution happens before spawn instead of inside cmd.exe.
-    const err = new Error(`spawn ${command} ENOENT`);
-    err.code = "ENOENT";
-    err.syscall = "spawn";
-    err.path = command;
-    return err;
-}
-/**
- * One-shot `chcp 65001` before the FIRST direct (.exe/.com) Windows spawn.
- *
- * Mechanism: `chcp` mutates the code page of the console the current process
- * is attached to, and that mutation persists for the console's lifetime —
- * it is not per-child-process state. The old cmd.exe-wrapper path re-ran
- * `chcp 65001 >nul 2>&1 &&` on every single spawn, which was always
- * redundant after the first call; memoizing here (module-level, once per
- * process) is a strict improvement, not a behavior change. Runs through a
- * tiny pinned cmd.exe spawn (same `%SystemRoot%\System32\cmd.exe` pin as
- * `killTree` below) with a static, hardcoded command string — no caller-
- * tainted data anywhere near it.
- */
-let utf8ConsoleCodePageApplied = false;
-function ensureUtf8ConsoleCodePageOnce() {
-    if (utf8ConsoleCodePageApplied)
-        return;
-    utf8ConsoleCodePageApplied = true;
-    try {
-        const cmdExe = `${process.env.SystemRoot ?? "C:\\Windows"}\\System32\\cmd.exe`;
-        spawnSync(cmdExe, ["/d", "/s", "/c", "chcp 65001 >nul 2>&1"], {
-            shell: false,
-            windowsHide: true,
-            // #1980 population sweep: a synchronous spawn with no timeout parks
-            // the event loop for as long as the child takes, and nothing here
-            // bounds that. `chcp` is normally instant, but this runs before the
-            // FIRST real spawn of the process, which is exactly when a cold or
-            // antivirus-throttled cmd.exe is slowest. Matches the 5s bound every
-            // other synchronous child-process site in this repo already carries.
-            timeout: 5000,
-        });
-    }
-    catch {
-        // Best-effort: worst case is non-ASCII tool output decoded incorrectly, not a
-        // spawn failure — never let this block the real spawn.
-    }
-}
-/**
- * Test-only seam: clear the one-shot `chcp` memoization.
- *
- * No test observes it today — the memoized work only runs inside a real
- * Windows direct spawn, so exercising it would mean a Windows-only test, and
- * the state it guards is a console code page, not behavior any assertion
- * depends on. This is kept purely so a future Windows-only test (or a second
- * caller of `ensureUtf8ConsoleCodePageOnce`) can reset process-lifetime state
- * without reaching into the module; it was dropped once as unrelated scope
- * creep in an earlier #1199 revision and restored on review. Do not read the
- * export as evidence of existing coverage (#1201).
- */
-export function resetUtf8ConsoleCodePageStateForTests() {
-    utf8ConsoleCodePageApplied = false;
-}
-// #1656: post-exit pipe-idle wait constants. Node's "close" event only fires
-// once every stdio fd referencing the child has been released — a
-// daemonized descendant that inherited our stdout/stderr pipe (the Windows
-// no-job-object case) can hold that fd open forever, hanging "close" even
-// though the child we spawned is long dead. A fixed post-exit deadline
-// avoids that hang but truncates a legitimately still-streaming child. The
-// idle-grace construction (adopted from pi's `waitForChildProcess`) does
-// neither: after "exit", wait for the pipes to go quiet — no data for
-// EXIT_PIPE_IDLE_GRACE_MS, re-armed on every chunk — so a quiet inherited
-// handle still releases after one grace window while an actively-writing
-// descendant keeps being read. EXIT_PIPE_IDLE_MAX_WAIT_MS caps the total
-// extra wait so a pathological, never-quiet descendant can't extend the
-// caller's overall budget unboundedly.
-const EXIT_PIPE_IDLE_GRACE_MS = 100;
-const EXIT_PIPE_IDLE_MAX_WAIT_MS = 2000;
-/**
- * #2968: how long past its own deadline this spawn's CPU/RSS sampler may keep
- * polling. Everything this function does to end a child after the deadline
- * fits inside it: `killTree`'s SIGTERM plus its 1000ms SIGKILL escalation (or
- * Windows' `taskkill /F /T`), then at most EXIT_PIPE_IDLE_MAX_WAIT_MS of
- * pipe-idle wait. A child still alive past deadline + this grace has outlived
- * every teardown available here, so polling it further only buys the Windows
- * process pile-up the report measured — and `stop()` still returns whatever
- * the sampler gathered before the cap.
- */
-const SPAWN_SAMPLER_TEARDOWN_GRACE_MS = 5_000;
-// ============================================================================
-// ASYNC VERSION (Recommended - Non-blocking)
-// ============================================================================
-/**
- * Async spawn with timeout and proper process cleanup.
- *
- * Unlike spawnSync, this:
- * - Doesn't block the event loop
- * - Kills the process on timeout (preventing zombies)
- * - Supports cancellation via AbortSignal
- *
- * ## Why this bound is NOT `bounded()` — the one documented exception (#2523)
- *
- * #2523 slice 2 folded every other "deadline AND abort signal" implementation
- * in the tree onto `clients/deadline-utils.ts#bounded`. This one stays, and it
- * is not a copy of the same idea:
- *
- * `bounded()` ABANDONS a promise — it stops waiting and lets the work run on
- * unobserved, which is safe precisely because everything it wraps is in-process
- * (a dynamic import, an LSP round trip, a `stat`). This function's work is a
- * CHILD PROCESS, and abandoning one leaks it. So its timer does not settle a
- * race at all: `timeoutId` sets `timedOut`, then runs `killTree()` — SIGTERM,
- * an escalation timer, SIGKILL, and on Windows a `taskkill /T` of the whole
- * tree — and the promise settles only when the child's own `close` arrives (or
- * the escalation gives up). The result it produces carries the teardown
- * EVIDENCE (`timeoutTeardown`, #2010): which signal killed it, whether the
- * tree actually died, how long it took. Replacing that with `bounded()` would
- * return `undefined` at the deadline and leave a live `vitest`/`gradle` behind
- * — the orphan class #2504 measured as 59 concurrent spawns starving a turn.
- *
- * The rule the exception preserves: a bound that can CANCEL its work must
- * cancel it. `bounded()` is for work that cannot be cancelled; this is not
- * that. Anything wrapping THIS function still gets `bounded()` around its own
- * await if it needs one.
- *
- * @example
- * const result = await safeSpawnAsync("npm", ["test"], { timeout: 30000 });
- * if (result.error) console.error("Failed:", result.error);
- */
-export async function safeSpawnAsync(command, args, options) {
-    const configuredTimeout = options?.timeout !== undefined &&
-        Number.isFinite(options.timeout) &&
-        options.timeout >= 0
-        ? options.timeout
-        : 30000;
-    const deadlineRemaining = options?.deadlineAt !== undefined && Number.isFinite(options.deadlineAt)
-        ? options.deadlineAt - Date.now()
-        : Number.POSITIVE_INFINITY;
-    const timeout = Math.max(0, Math.min(configuredTimeout, deadlineRemaining));
-    // Fall back to the current turn's ambient signal (set from ctx.signal) so an
-    // Esc/abort mid-turn cancels dispatches that didn't thread a signal of their
-    // own — unless the caller opts out (installs, which must run to completion).
-    const abortSignal = options?.signal ??
-        (options?.ignoreAmbientSignal ? undefined : ambientAbortSignal);
-    return new Promise((resolve) => {
-        // Check for early abort
-        if (abortSignal?.aborted) {
-            const cause = new Error("Spawn aborted before start");
-            resolve({
-                stdout: "",
-                stderr: "",
-                status: null,
-                error: cause,
-                failure: "aborted",
-                spawnFailure: new SpawnFailureError("killed", cause.message, cause),
-            });
-            return;
-        }
-        if (timeout <= 0) {
-            const cause = new Error(`Process timed out after ${timeout}ms`);
-            resolve({
-                stdout: "",
-                stderr: "",
-                status: null,
-                error: cause,
-                failure: "timeout",
-                spawnFailure: new SpawnFailureError("timeout", cause.message, cause),
-            });
-            return;
-        }
-        let stdout = "";
-        let stderr = "";
-        let timedOut = false;
-        let aborted = false;
-        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 —
-        // the DECISION itself is shape-based (see the `close` handler below),
-        // this flag only stops the loser from resolving a second time.
-        let resolved = false;
-        // The most recent 'error' Error, captured the instant the event fires
-        // regardless of whether that handler goes on to resolve. The `close`
-        // handler's shape-based branch (code === null || code < 0) reads this
-        // when it decides FIRST, so a genuinely informative ENOENT/EACCES/etc.
-        // Error is used when it happens to already be available, instead of
-        // always falling back to a generic synthesized one.
-        let pendingSpawnError;
-        // #1109: the non-Windows SIGTERM→SIGKILL escalation timer (armed in
-        // killTree below). Stored per-call (never shared) so the close/error
-        // handlers can clear it if the child exits before it fires — same
-        // uncleared-race-timeout class as the LSP client-wait leak (#1097):
-        // a ref'd 1s timer that outlives the child it was escalating against
-        // would keep a one-shot `pi --print` process alive for up to 1s.
-        let escalationTimer;
-        let teardownStartedAtMs;
-        let teardownEscalated = false;
-        // #2010: teardown evidence for the spawn's OWN timeout. The wall clock
-        // starts when the budget expires and the tree-kill is issued, and stops
-        // when the process tree is observed dead (`await killPromise` settles)
-        // - measured SEPARATELY from the budget itself, so a slow teardown is
-        // visible instead of silently inflating "how long the tool ran".
-        // `teardownEscalated` names whether SIGTERM sufficed or the SIGKILL
-        // escalation fired (POSIX; Windows taskkill /F is always forceful).
-        // #1114: `child.killed` is set by Node the moment `kill()` successfully
-        // SENDS a signal, not when the child actually dies — so gating the
-        // escalation on `!child.killed` right after a successful `SIGTERM` send
-        // is always false and the SIGKILL branch is unreachable. Track observed
-        // death via the close/error handlers instead (set synchronously, before
-        // any `await`, so a timer firing during the close handler's `await
-        // killPromise` still observes the flag correctly).
-        let closed = false;
-        // #1656: set only while the post-exit idle-pipe wait is active (see
-        // waitForPipeIdle below); the stdout/stderr "data" handlers call this to
-        // 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;
-        // #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 = [];
-        let retainedTailBytes = 0;
-        let retainedTailLimit = 0;
-        let truncationStream = "stderr";
-        const streamingMatcher = options?.matchWhileStreaming;
-        const streamingCarryBytes = streamingMatcher
-            ? Math.max(0, streamingMatcher.source.length - 1)
-            : 0;
-        const streamingCarry = {
-            stdout: "",
-            stderr: "",
-        };
-        const bytePrefix = (text, bytes) => Buffer.from(text).subarray(0, bytes).toString();
-        const byteSuffix = (text, bytes) => {
-            const buffer = Buffer.from(text);
-            return buffer.subarray(Math.max(0, buffer.byteLength - bytes)).toString();
-        };
-        const appendTail = (part, maxBytes) => {
-            if (maxBytes <= 0)
-                return;
-            retainedTail.push({ stream: part.stream, text: part.text });
-            retainedTailBytes += Buffer.byteLength(part.text);
-            while (retainedTailBytes > maxBytes && retainedTail.length > 0) {
-                const first = retainedTail[0];
-                const excess = retainedTailBytes - maxBytes;
-                const firstBytes = Buffer.byteLength(first.text);
-                if (firstBytes <= excess) {
-                    retainedTail.shift();
-                    retainedTailBytes -= firstBytes;
-                }
-                else {
-                    first.text = byteSuffix(first.text, firstBytes - excess);
-                    retainedTailBytes -= excess;
-                }
-            }
-        };
-        const renderOutput = (stream) => {
-            const head = retainedHead
-                .filter((part) => part.stream === stream)
-                .map((part) => part.text)
-                .join("");
-            const tail = retainedTail
-                .filter((part) => part.stream === stream)
-                .map((part) => part.text)
-                .join("");
-            const marker = stream === truncationStream ? outputTruncationMarker : "";
-            return head + marker + tail;
-        };
-        const refreshRetainedOutputs = () => {
-            stdout = renderOutput("stdout");
-            stderr = renderOutput("stderr");
-        };
-        const appendOutput = (stream, current, chunk) => {
-            const text = typeof chunk === "string" ? chunk : chunk.toString();
-            if (outputTruncated) {
-                appendTail({ stream, text }, retainedTailLimit);
-                truncationStream = stream;
-                return renderOutput(stream);
-            }
-            const bytes = Buffer.byteLength(text);
-            if (retainedOutputBytes + bytes <= maxOutputBytes) {
-                retainedOutputBytes += bytes;
-                return current + text;
-            }
-            outputTruncated = true;
-            truncationStream = stream;
-            const available = Math.max(0, maxOutputBytes - Buffer.byteLength(outputTruncationMarker));
-            const headBytes = Math.floor(available / 2);
-            const tailBytes = available - headBytes;
-            retainedTailLimit = tailBytes;
-            const parts = [
-                { stream: "stdout", text: stdout },
-                { stream: "stderr", text: stderr },
-                { stream, text },
-            ];
-            let headRemaining = headBytes;
-            for (const part of parts) {
-                if (headRemaining <= 0)
-                    break;
-                const kept = bytePrefix(part.text, headRemaining);
-                if (kept)
-                    retainedHead.push({ stream: part.stream, text: kept });
-                headRemaining -= Buffer.byteLength(kept);
-            }
-            let tailRemaining = tailBytes;
-            for (let index = parts.length - 1; index >= 0 && tailRemaining > 0; index--) {
-                const part = parts[index];
-                const kept = byteSuffix(part.text, tailRemaining);
-                if (kept) {
-                    retainedTail.unshift({ stream: part.stream, text: kept });
-                    tailRemaining -= Buffer.byteLength(kept);
-                }
-            }
-            retainedTailBytes = tailBytes - tailRemaining;
-            return renderOutput(stream);
-        };
-        const matchStreamingChunk = (stream, chunk) => {
-            if (streamingMatch || !streamingMatcher)
-                return;
-            const text = typeof chunk === "string" ? chunk : chunk.toString();
-            streamingMatcher.lastIndex = 0;
-            streamingMatch = streamingMatcher.test(streamingCarry[stream] + text);
-            if (streamingCarryBytes > 0) {
-                streamingCarry[stream] = Buffer.from(streamingCarry[stream] + text)
-                    .subarray(-streamingCarryBytes)
-                    .toString();
-            }
-        };
-        // Spawn the process (non-blocking). Keeping Node's `shell` option false
-        // is important on every path here: shell:true concatenates tainted
-        // arguments into a command line before spawning (CodeQL #17 / CWE-78).
-        //
-        // On Windows (#817): resolve `command` ourselves (PATH + PATHEXT walk,
-        // cached) instead of always routing through cmd.exe.
-        //   - .exe/.com  → spawn the resolved path directly, args stay a real
-        //     array, no shell involved at all (injection-proof).
-        //   - .cmd/.bat  → these are scripts cmd.exe must interpret (npm shims
-        //     are the common case), so keep the wrapper, but pin the
-        //     interpreter to %SystemRoot%\System32\cmd.exe (never trust
-        //     ComSpec — CodeQL #18) and VALIDATE args instead of trying to
-        //     escape them: reject anything containing `"`, `%`, `!`, or CR/LF
-        //     rather than spawn with an unsound escape.
-        //   - unresolvable → synthesize an ENOENT-shaped error instead of
-        //     letting cmd.exe report "not recognized" from inside a shell.
-        const isWindows = process.platform === "win32";
-        const spawnEnv = getSpawnEnvironment(options?.env);
-        // The cwd handed to the CHILD process doesn't need OUR validation —
-        // Windows resolves it natively, exactly as it did before #817 ever
-        // touched this file. A drive-relative cwd (`D:work`) without a
-        // validated `=D:` env entry can't be canonicalized by us (Node never
-        // surfaces `=X:` keys from the ambient environment — see
-        // `getValidatedPerDriveCwd`'s doc comment), but that is a gap in OUR
-        // provenance, not evidence the cwd itself is bad. Fall back to the raw
-        // value instead of failing the whole spawn before ever attempting it
-        // (#1201) — command resolution just below still fails closed for any
-        // relative PATH entry that would need this cwd to be canonical.
-        // No `?? process.cwd()` third arm: `resolveEffectiveWindowsCwd(undefined,
-        // env)` always returns a string, so the only way to reach `undefined`
-        // here is a DEFINED-but-unprovable `options.cwd`, which `?? options?.cwd`
-        // already covers. A `process.cwd()` arm would be unreachable, and it
-        // would read like a live silent-wrong-directory hazard (#1201).
-        const spawnCwd = isWindows
-            ? (resolveEffectiveWindowsCwd(options?.cwd, spawnEnv) ?? options?.cwd)
-            : options?.cwd;
-        let spawnCmd = command;
-        let spawnArgs = args;
-        let windowsVerbatimArguments = false;
-        let resolutionError;
-        if (isWindows) {
-            // Pass the ORIGINAL (unresolved) cwd here, not `spawnCwd` above — this
-            // seam intentionally fails closed on unprovable drive-relative
-            // provenance (matches `resolveWindowsCommandForEnvironment`'s
-            // documented contract and its dedicated test coverage), independent
-            // of the passthrough fallback the actual child cwd gets above.
-            const resolved = resolveWindowsCommand(command, options?.cwd, spawnEnv);
-            if (!resolved) {
-                resolutionError = synthesizeEnoentError(command);
-            }
-            else if (resolved.ext === ".cmd" || resolved.ext === ".bat") {
-                // Validate the RESOLVED path (what actually gets interpolated
-                // into the /c line via buildWindowsShellCommand below), not the
-                // caller's original `command` string — a resolved path
-                // containing `%`/`!` would otherwise reach the shell unvalidated.
-                const unsafeValue = findCmdUnsafeValue(resolved.resolvedPath, args);
-                if (unsafeValue !== undefined) {
-                    resolutionError = new Error(`Refusing to spawn "${resolved.resolvedPath}" via cmd.exe: ` +
-                        `${JSON.stringify(unsafeValue)} contains a character ("` +
-                        `, %, !, or CR/LF) that cannot be safely escaped on a ` +
-                        `cmd.exe /c command line (CWE-78, #817). Rename/quote the ` +
-                        "value or invoke the tool without going through cmd.exe.");
-                }
-                else {
-                    // Pin the interpreter — never trust ComSpec/COMSPEC (#18): an
-                    // env-controlled ComSpec could point anywhere.
-                    spawnCmd = `${process.env.SystemRoot ?? "C:\\Windows"}\\System32\\cmd.exe`;
-                    spawnArgs = [
-                        "/d",
-                        "/s",
-                        "/c",
-                        buildWindowsShellCommand(resolved.resolvedPath, args),
-                    ];
-                    // The `/c` payload is already quoted by buildWindowsShellCommand.
-                    // Prevent Node from escaping those quotes a second time when it
-                    // builds cmd.exe's Windows command line.
-                    windowsVerbatimArguments = true;
-                }
-            }
-            else {
-                // .exe / .com: direct spawn, no cmd.exe anywhere in the picture.
-                ensureUtf8ConsoleCodePageOnce();
-                spawnCmd = resolved.resolvedPath;
-                spawnArgs = args;
-            }
-        }
-        if (resolutionError) {
-            void classifySpawnFailure(resolutionError, {
-                command,
-                cwd: options?.cwd,
-            }).then((spawnFailure) => resolve({
-                stdout: "",
-                stderr: "",
-                status: null,
-                error: resolutionError,
-                failure: "spawn",
-                spawnFailure,
-            }));
-            return;
-        }
-        let child;
-        // #2026: on POSIX, run the child in its OWN process group (detached).
-        // killTree/killPidTreeSync then signal the whole GROUP (-pid), which
-        // makes grandchildren (npm -> node, sh -> sleep, etc.) die with their
-        // tool instead of surviving every timeout as orphans. Detachment stops
-        // direct terminal-signal delivery, so EVERY POSIX pid registers for
-        // lifetime cleanup - pi's signal/exit handlers forward the kill,
-        // preserving die-with-host semantics.
-        const posixProcessGroup = process.platform !== "win32";
-        try {
-            child = spawn(spawnCmd, spawnArgs, {
-                cwd: spawnCwd,
-                env: spawnEnv,
-                windowsHide: true,
-                shell: false,
-                windowsVerbatimArguments,
-                detached: posixProcessGroup,
-            });
-        }
-        catch (err) {
-            // A SYNCHRONOUS spawn throw (Windows `spawn UNKNOWN`/EINVAL — the
-            // pidusage bug class, #533) must NOT reject this Promise: every caller
-            // relies on safeSpawnAsync never rejecting (they inspect result.error),
-            // and many invoke it fire-and-forget in best-effort/background paths, so
-            // a rejection here could surface as an unhandledRejection that crashes
-            // the host. Resolve the failure gracefully instead — same contract as an
-            // asynchronously-emitted `'error'` event (handled below).
-            const cause = toError(err);
-            void classifySpawnFailure(cause, { command, cwd: options?.cwd }).then((spawnFailure) => resolve({
-                stdout: "",
-                stderr: "",
-                status: null,
-                error: cause,
-                failure: "spawn",
-                spawnFailure,
-            }));
-            return;
-        }
-        // Keep historical open stdin by default. An opted-in payload is written
-        // completely and followed by EOF; input: "" closes stdin immediately.
-        if (options?.input !== undefined) {
-            child.stdin?.on("error", () => { });
-            child.stdin?.end(options.input);
-        }
-        // #2042: ownership is a SPAWN-TIME fact — a real child is alive with
-        // `PPid == ours` the instant `spawn` returns, while a test double's
-        // invented pid never is. Resolve it once, here, and reuse the verdict:
-        // the group escalation below must still fire after the direct child
-        // dies (#2027: a SIGTERM-hardy grandchild keeps the group alive), so it
-        // cannot re-read `/proc` at kill time.
-        const ownsChildPid = isOwnLiveChild(child.pid, "safe-spawn-register");
-        if (ownsChildPid && (posixProcessGroup || options?.lifetimeCoupled)) {
-            // #2026: POSIX registers unconditionally - detached children no
-            // longer receive terminal signals directly, so the lifetime
-            // cleanup's signal forwarding IS their die-with-host path.
-            installLifetimeCleanup();
-            lifetimeState.pids.add(child.pid);
-        }
-        // #620: bracket this spawn's lifetime with a short-interval CPU/RSS poll
-        // (started right here, stopped in finalize() below) so transient
-        // analyzer children (jscpd, knip, madge, gitleaks, etc.) — which live too
-        // briefly for heartbeat-cadence sampling to reliably catch — still get a
-        // peak/average resource reading. `startSpawnUsageSampler` itself is
-        // best-effort/never-throws by design, but this call site wraps it anyway
-        // (belt and suspenders: the sampling seam must never be the reason a real
-        // spawn fails) with a no-op fallback sampler.
-        //
-        // #2968: the sampler's polling lifetime is bounded by THIS spawn's own
-        // deadline plus the teardown grace, not by the child's willingness to
-        // exit. `finalize`/the `error` handler still stop it on every settle
-        // path, but none of those paths exist for a child that never settles —
-        // a hung `.cmd` shim whose tree survives `taskkill /F /T` kept polling
-        // for 5-6 hours in the report.
-        let usageSampler;
-        try {
-            usageSampler = startSpawnUsageSampler(
-            // The poll CADENCE is the sampler's own policy (it owns the backoff
-            // too); the DEADLINE is this function's. Passing `undefined` rather
-            // than importing the cadence constant keeps this module's view of
-            // the sampler at one export, which is also what every existing
-            // `vi.mock` of it provides.
-            child.pid, undefined, timeout + SPAWN_SAMPLER_TEARDOWN_GRACE_MS);
-        }
-        catch {
-            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 (phase) => {
-            if (isWindows && child.pid && child.pid > 0) {
-                const taskkill = `${process.env.SystemRoot ?? "C:\\Windows"}\\System32\\taskkill.exe`;
-                try {
-                    await new Promise((done) => {
-                        const killer = spawn(taskkill, ["/F", "/T", "/PID", String(child.pid)], {
-                            shell: false,
-                            windowsHide: true,
-                            stdio: "ignore",
-                        });
-                        killer.once("close", () => done());
-                        killer.once("error", () => {
-                            // E4: a throw HERE would leave the EventEmitter as an
-                            // uncaught exception, not a rejection.
-                            if (!trySend(() => child.kill("SIGKILL")))
-                                noteKillFailure(phase);
-                            done();
-                        });
-                    });
-                }
-                catch {
-                    if (!trySend(() => child.kill("SIGKILL")))
-                        noteKillFailure(phase);
-                }
-            }
-            else if (posixProcessGroup && ownsChildPid) {
-                // #2026: signal the whole process group. Grandchildren spawned
-                // 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;
-                // #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
-                // while a SIGTERM-hardy grandchild keeps the group alive. The
-                // timer stays REF'D for group mode (max 1s tail after resolve):
-                // it is the only backstop for this group once finalize deletes
-                // the pid from lifetimeState.
-                escalationTimer = setTimeout(() => {
-                    // 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"));
-                    });
-                    if (!escalated)
-                        noteKillFailure(phase);
-                }, 1000);
-            }
-            else {
-                // 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)
-                        return;
-                    teardownEscalated = true;
-                    if (!trySend(() => child.kill("SIGKILL")))
-                        noteKillFailure(phase);
-                }, 1000);
-            }
-        };
-        // Handle abort signal
-        const onAbort = () => {
-            aborted = true;
-            if (!killed && !child.killed) {
-                killed = true;
-                void killTree("abort");
-            }
-        };
-        abortSignal?.addEventListener("abort", onAbort, { once: true });
-        // Output-cap kills are awaited by finalize() below, just like
-        // timeout/abort kills. An armed, unmatched streaming matcher is the one
-        // exception: retention remains bounded, but the caller's timeout is the
-        // bound while the child gets a chance to emit its rescue line.
-        let killPromise;
-        const stopForOutputLimit = () => {
-            const waitingForStreamingMatch = streamingMatcher !== undefined && !streamingMatch;
-            if (outputTruncated &&
-                !waitingForStreamingMatch &&
-                !killed &&
-                !child.killed) {
-                killedForOutputCap = true;
-                killed = true;
-                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");
-        // #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
-        // the same "process exit" turn, well before any microtask), so a
-        // listener attached inside `waitForPipeIdle` — which `finalize` only
-        // reaches after `await killPromise`, at least one microtask later — is
-        // always attaching to an event that has already happened. That's why
-        // the round-2 `child.on("close", finish)` placed inside
-        // `waitForPipeIdle` never actually caught a real spawn's `close` early:
-        // every real call still paid the full grace window. Capturing the
-        // boolean here, before any await, means `waitForPipeIdle` can check
-        // "did close already happen" synchronously the moment it runs.
-        let closeSeen = false;
-        // #2010: WHEN death was observed - the stop-clock for teardown evidence
-        // and the discriminator for its outcome. A close that predates the
-        // budget-expired kill means the child exited on its own ("exited"), no
-        // matter that the timer callback raced and armed a kill anyway.
-        let closedAtMs;
-        child.on("close", () => {
-            closeSeen = true;
-            closedAtMs ??= Date.now();
-        });
-        // Timeout handling - KILL the process, don't just abandon it
-        const timeoutId = setTimeout(() => {
-            timedOut = true;
-            if (!killed && !child.killed) {
-                killed = true;
-                teardownStartedAtMs = Date.now();
-                killPromise = killTree("timeout");
-            }
-        }, timeout);
-        // #620: stop the poll and log peak/average CPU%+RSS for this invocation
-        // into the existing per-runner latency.log phase entries — best-effort,
-        // wrapped so a logging hiccup can never affect the resolved SpawnResult.
-        const finishResourceUsage = () => {
-            const summary = usageSampler.stop();
-            if (!summary)
-                return undefined;
-            try {
-                logLatency({
-                    type: "phase",
-                    phase: "spawn_resource_usage",
-                    filePath: "",
-                    durationMs: 0,
-                    metadata: {
-                        command: resourceLabel,
-                        ...summary,
-                    },
-                });
-            }
-            catch {
-                // best-effort logging only
-            }
-            return summary;
-        };
-        // #1656: wait for stdout/stderr to fall idle after exit instead of
-        // waiting for Node's "close" event (see the constants' doc comment
-        // above). Resolves immediately if the child has no pipes to drain.
-        //
-        // These timers stay REF'D, matching `timeoutId`/`escalationTimer`
-        // elsewhere in this function: the caller's own settlement depends on
-        // them firing, so unref'ing would let a short-lived host process (a
-        // one-shot CLI whose only other in-flight work was this spawn) exit
-        // the event loop before `finish` ever runs — silently abandoning this
-        // promise instead of merely leaking a handle. Both paths to `finish`
-        // clear both timers, so nothing outlives settlement either way.
-        const waitForPipeIdle = () => {
-            if (!child.stdout && !child.stderr)
-                return Promise.resolve();
-            // #1673 review round 3 (F2): `close` fires a fraction of a
-            // millisecond after `exit` for a real Node child — well before
-            // `finalize`'s `await killPromise` ever yields, i.e. before this
-            // function is even called. By the time we get here, `closeSeen`
-            // (set by the listener registered at spawn time, above) already
-            // reflects reality for the overwhelming majority of real spawns:
-            // nothing is holding this child's stdio open, so don't pay out the
-            // 100ms grace window for a signal that already arrived.
-            if (closeSeen)
-                return Promise.resolve();
-            return new Promise((finishIdleWait) => {
-                let settled = false;
-                let graceTimer;
-                const capTimer = setTimeout(() => {
-                    finish();
-                }, EXIT_PIPE_IDLE_MAX_WAIT_MS);
-                const finish = () => {
-                    if (settled)
-                        return;
-                    settled = true;
-                    rearmIdleGrace = undefined;
-                    if (graceTimer)
-                        clearTimeout(graceTimer);
-                    clearTimeout(capTimer);
-                    // Optional chaining, not a bare call: `child` is a real Node
-                    // ChildProcess (always an EventEmitter, always has this) in
-                    // production, but several existing test doubles across the
-                    // suite fake stdio-bearing children as plain objects with only
-                    // the handful of methods (`on`, `kill`, ...) their scenario
-                    // needs — no `removeListener`. Skipping cleanup on those is
-                    // harmless (the fake is torn down with the test either way);
-                    // crashing here from inside a timer callback is not: it would
-                    // throw before `finishIdleWait()` runs, hanging every caller's
-                    // `safeSpawnAsync` promise (#1673 review round 2 caught this
-                    // live in tests/clients/installer/version-drift.test.ts).
-                    child.removeListener?.("close", finish);
-                    finishIdleWait();
-                };
-                // The `closeSeen` fast-path above catches the common case (close
-                // already happened by the time we get here). This listener is
-                // the fallback for the rare case where `close` genuinely lands
-                // DURING the wait — e.g. a child whose stdio takes a beat
-                // longer than usual to release, but still well under the grace
-                // window. `close` is a stronger signal than "no data for
-                // EXIT_PIPE_IDLE_GRACE_MS", so finishing on it here still beats
-                // waiting out the timer. The anti-hang property is untouched
-                // either way: a daemonized descendant holding the pipe open is
-                // EXACTLY the case where `close` never fires at all, so the
-                // grace/cap timers still bound that case as before.
-                child.on("close", finish);
-                rearmIdleGrace = () => {
-                    if (graceTimer)
-                        clearTimeout(graceTimer);
-                    graceTimer = setTimeout(finish, EXIT_PIPE_IDLE_GRACE_MS);
-                };
-                rearmIdleGrace();
-            });
-        };
-        // Process completion
-        //
-        // #1656 x #1651/#1670: finalize off BOTH `exit` and `close`, not just
-        // one — each covers a shape the other misses.
-        //   - `exit` is what unblocks the #1656 hang: a daemonized descendant
-        //     that inherited our stdout/stderr pipe can hold that fd open
-        //     forever, so `close` (which waits for every fd referencing the
-        //     child to release) never fires even though the child we spawned
-        //     is long dead. `exit` always fires once the child itself exits,
-        //     independent of who still holds its pipes.
-        //   - `close` is still wired because a child that never actually
-        //     launched (bad binary, EACCES, ...) gets NO `exit` event at all —
-        //     Node only emits `error` then `close(code<0, null)` for that
-        //     shape (#1651/#1670's shape guard below decides from exactly
-        //     this). `exit`-only would make that guard unreachable.
-        // Whichever fires first drives `finalize`; `settled` (distinct from
-        // `resolved`, which `finalize` itself owns) stops the second event
-        // from dispatching a redundant, concurrently-racing `finalize` call —
-        // double-invoking it would double-run `waitForPipeIdle` and
-        // `finishResourceUsage` against the same child.
-        let settled = false;
-        const onChildSettle = (code, signal) => {
-            if (settled || resolved)
-                return;
-            settled = true;
-            closed = true;
-            clearTimeout(timeoutId);
-            abortSignal?.removeEventListener("abort", onAbort);
-            if (child.pid)
-                lifetimeState.pids.delete(child.pid);
-            void finalize(code, signal);
-        };
-        const finalize = async (code, signal) => {
-            // Belt, not the decision: whichever path settles `resolved` FIRST
-            // wins. A healthy run's outcome must never be discarded by a late,
-            // unrelated 'error' (e.g. a post-exit kill() that itself failed
-            // with EPERM, #1651 review F4) — so this only bails when something
-            // else has ALREADY resolved, never on `error` merely having fired.
-            await killPromise;
-            if (resolved)
-                return;
-            // #1109: the child has exited - clear the non-Windows escalation
-            // timer so it doesn't linger as a ref'd handle. #2027 EXCEPTION:
-            // in POSIX group mode the timer is the liveness-gated SIGKILL
-            // backstop for SIGTERM-hardy grandchildren; it stays armed and
-            // self-cleans within 1s of firing (max 1s ref'd tail).
-            if (escalationTimer && !posixProcessGroup) {
-                clearTimeout(escalationTimer);
-            }
-            // #1673 review F1: latch the verdict as DECIDED here, before the
-            // idle-pipe wait — not after it. `code`/`signal`/`timedOut`/`aborted`
-            // are already fixed by this point (they don't change during the
-            // wait), so nothing below depends on staying unresolved across it.
-            // Leaving `resolved` false across the wait would reopen the exact
-            // race #1651 review F4 closed: a late, unrelated 'error' (e.g. a
-            // post-exit kill() failing with EPERM) landing inside the
-            // idle-grace window (bounded, but up to EXIT_PIPE_IDLE_MAX_WAIT_MS)
-            // would steal an already-decided healthy verdict. Pre-#1656 that
-            // race window was one microtask — the gap between `close` firing
-            // and `resolve()` being called synchronously in the same handler.
-            // This closes the window back down to that same shape instead of
-            // widening it to the whole wait.
-            resolved = true;
-            await waitForPipeIdle();
-            const resourceUsage = finishResourceUsage();
-            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
-            // exists, so callers can NAME it instead of scraping `error.message`.
-            const signalInfo = signal ? { signal } : {};
-            if (timedOut) {
-                const cause = new Error(`Process timed out after ${timeout}ms (killed with ${signal || "SIGTERM"})`);
-                // #2010: teardown evidence lives ONLY on the timeout path - it
-                // describes how long the tree took to die after the budget
-                // expired, and how it died ("exited" = the child beat the signal;
-                // "killed-by-signal" / "escalate-kill" = how WE ended it).
-                const timeoutTeardown = resolveTeardownOutcome({
-                    killStartedAtMs: teardownStartedAtMs,
-                    deathObservedAtMs: closedAtMs,
-                    escalated: teardownEscalated,
-                });
-                resolve({
-                    stdout,
-                    stderr,
-                    status: null,
-                    error: cause,
-                    failure: "timeout",
-                    ...signalInfo,
-                    ...(timeoutTeardown && { timeoutTeardown }),
-                    spawnFailure: new SpawnFailureError("timeout", cause.message, cause),
-                    ...outputInfo,
-                    ...streamingMatchInfo,
-                    resourceUsage,
-                });
-            }
-            else if (aborted) {
-                const cause = new Error("Spawn aborted");
-                resolve({
-                    stdout,
-                    stderr,
-                    status: null,
-                    error: cause,
-                    failure: "aborted",
-                    ...signalInfo,
-                    spawnFailure: new SpawnFailureError("killed", cause.message, cause),
-                    ...outputInfo,
-                    ...streamingMatchInfo,
-                    resourceUsage,
-                });
-            }
-            else if (signal) {
-                const cause = new Error(`Process killed by signal: ${signal}`);
-                resolve({
-                    stdout,
-                    stderr,
-                    status: null,
-                    error: cause,
-                    failure: "signal",
-                    ...signalInfo,
-                    spawnFailure: new SpawnFailureError("killed", cause.message, cause),
-                    ...outputInfo,
-                    ...streamingMatchInfo,
-                    resourceUsage,
-                });
-            }
-            else if (code === null || code < 0) {
-                // #1651 review F3: a real completed process never exits with a
-                // null or negative code (Node reports the negated libuv/errno for
-                // a child that never launched — e.g. ENOENT: -2 on Linux, -4058
-                // on Windows). This decides from that SHAPE alone, independent of
-                // whether/when 'error' has fired — Node's docs leave the
-                // 'error'/'close' ordering for a failed spawn unspecified, and a
-                // same-microtask re-check (the #1651 first-round fix) still loses
-                // if 'error' lands a tick later via setImmediate/nextTick.
-                // Reuse `pendingSpawnError` when 'error' already landed (a more
-                // informative Error — ENOENT vs EACCES vs other); otherwise
-                // synthesize an ENOENT-shaped one so a genuinely missing tool is
-                // never read as a clean, answered run.
-                const cause = pendingSpawnError ?? synthesizeEnoentError(command);
-                const spawnFailure = await classifySpawnFailure(cause, {
-                    command,
-                    cwd: options?.cwd,
-                });
-                resolve({
-                    stdout,
-                    stderr,
-                    status: code,
-                    error: cause,
-                    failure: "spawn",
-                    spawnFailure,
-                    ...outputInfo,
-                    ...streamingMatchInfo,
-                    resourceUsage,
-                });
-            }
-            else {
-                resolve({
-                    stdout,
-                    stderr,
-                    status: code,
-                    ...outputInfo,
-                    ...streamingMatchInfo,
-                    resourceUsage,
-                });
-            }
-        };
-        child.on("exit", onChildSettle);
-        child.on("close", onChildSettle);
-        child.on("error", (err) => {
-            // Capture unconditionally — even when `close` already resolved, this
-            // keeps the most recent Error available for anyone reading state
-            // mid-flight, and costs nothing (the assignment, not a resolve).
-            pendingSpawnError = err;
-            // A completed run's own verdict must never be downgraded by an
-            // unrelated LATE error (#1651 review F4 — e.g. a post-exit kill()
-            // failing with EPERM after `close(0, null)` already answered).
-            if (resolved)
-                return;
-            resolved = true;
-            closed = true;
-            clearTimeout(timeoutId);
-            abortSignal?.removeEventListener("abort", onAbort);
-            // #2027: group-mode timer stays armed as the grandchild backstop.
-            if (escalationTimer && !posixProcessGroup) {
-                clearTimeout(escalationTimer);
-            }
-            if (child.pid)
-                lifetimeState.pids.delete(child.pid);
-            const resourceUsage = finishResourceUsage();
-            let failure = "spawn";
-            if (aborted)
-                failure = "aborted";
-            else if (timedOut)
-                failure = "timeout";
-            const controlFailure = aborted
-                ? new SpawnFailureError("killed", err.message, err)
-                : timedOut
-                    ? new SpawnFailureError("timeout", err.message, err)
-                    : undefined;
-            const finish = (spawnFailure) => resolve({
-                stdout,
-                stderr,
-                status: null,
-                error: err,
-                failure,
-                spawnFailure,
-                ...(outputTruncated ? { outputTruncated: true } : {}),
-                ...(killedForOutputCap ? { killedForOutputCap: true } : {}),
-                ...(killFailed ? { killFailed: true } : {}),
-                ...(streamingMatch ? { streamingMatch: true } : {}),
-                resourceUsage,
-            });
-            if (controlFailure)
-                finish(controlFailure);
-            else {
-                void classifySpawnFailure(err, { command, cwd: options?.cwd }).then(finish);
-            }
-        });
-    });
-}
-/**
- * Run multiple commands concurrently with limited concurrency.
- *
- * This prevents resource contention when running many linters.
- * Uses async spawn with concurrency limiting built-in.
- *
- * @example
- * const results = await safeSpawnBatch([
- *   { command: "biome", args: ["check", "file.ts"] },
- *   { command: "ruff", args: ["check", "file.py"] },
- * ], 3); // Max 3 concurrent
- */
-export async function safeSpawnBatch(commands, concurrency = 3) {
-    const results = [];
-    // Process in batches to limit concurrent processes
-    for (let i = 0; i < commands.length; i += concurrency) {
-        const batch = commands.slice(i, i + concurrency);
-        const batchResults = await Promise.all(batch.map(({ command, args, options }) => safeSpawnAsync(command, args, options)));
-        results.push(...batchResults);
-    }
-    return results;
-}
-/**
- * Check if a command is available in PATH (async version)
- */
-export async function isCommandAvailableAsync(command) {
-    const finder = process.platform === "win32" ? "where" : "which";
-    const result = await safeSpawnAsync(finder, [command], { timeout: 5000 });
-    return result.status === 0 && !result.error;
-}
-/**
- * Find the full path to a command (async version)
- */
-export async function findCommandAsync(command) {
-    const finder = process.platform === "win32" ? "where" : "which";
-    const result = await safeSpawnAsync(finder, [command], { timeout: 5000 });
-    if (result.status !== 0 || result.error)
-        return null;
-    // Take first line (first match)
-    return result.stdout.trim().split("\n")[0] || null;
-}
-// ============================================================================
-// SYNC VERSION (Deprecated - Blocking, for backward compatibility)
-// ============================================================================
-/**
- * ⚠️ DEPRECATED: Use safeSpawnAsync instead.
- *
- * This blocks the entire Node.js event loop until the process exits.
- * If the process hangs, pi will freeze.
- *
- * Kept for backward compatibility during migration (today's only caller:
- * `test-runner-client.ts`'s synchronous pytest-on-PATH probe, called from a
- * sync detection path with many sync callers/tests — not a trivial async
- * migration, see #817 follow-up discussion).
- *
- * #817: the Windows branch used to build a `cmd.exe`/`shell:true` command
- * line from unvalidated caller input (CodeQL #17/#18/#19), same unsoundness
- * as the async version had. It now shares the exact same resolution/
- * validation seams as `safeSpawnAsync` — `resolveWindowsCommand` (cached
- * PATH+PATHEXT walk), direct `spawnSync(resolvedPath, args, { shell: false })`
- * for `.exe`/`.com`, the pinned-cmd.exe wrapper + `findCmdUnsafeValue`
- * rejection for `.cmd`/`.bat`, and a synthesized ENOENT when unresolvable.
- * No `shell: true` anywhere.
- */
-export function safeSpawn(command, args, options) {
-    const spawnEnv = getSpawnEnvironment(options?.env);
-    if (process.platform === "win32") {
-        // See the matching comment in safeSpawnAsync: the child's cwd doesn't
-        // need OUR validation (Windows resolves it natively), so an unprovable
-        // drive-relative cwd falls back to the raw value instead of failing the
-        // whole spawn before ever attempting it (#1201). Command resolution
-        // below intentionally still uses the ORIGINAL raw cwd and fails closed
-        // for PATH entries that would need it to be canonical.
-        // See safeSpawnAsync for why there is no `?? process.cwd()` third arm.
-        const spawnCwd = resolveEffectiveWindowsCwd(options?.cwd, spawnEnv) ?? options?.cwd;
-        const resolved = resolveWindowsCommand(command, options?.cwd, spawnEnv);
-        if (!resolved) {
-            const error = synthesizeEnoentError(command);
-            return {
-                stdout: "",
-                stderr: "",
-                status: null,
-                error,
-                failure: "spawn",
-                spawnFailure: classifySpawnFailureSync(error, {
-                    command,
-                    cwd: options?.cwd,
-                }),
-            };
-        }
-        let spawnCmd;
-        let spawnArgs;
-        let windowsVerbatimArguments = false;
-        if (resolved.ext === ".cmd" || resolved.ext === ".bat") {
-            // Validate the value that actually gets interpolated into the /c
-            // line — the RESOLVED path, not the caller's original (possibly
-            // extensionless) `command` string — plus every arg.
-            const unsafeValue = findCmdUnsafeValue(resolved.resolvedPath, args);
-            if (unsafeValue !== undefined) {
-                const error = new Error(`Refusing to spawn "${resolved.resolvedPath}" via cmd.exe: ` +
-                    `${JSON.stringify(unsafeValue)} contains a character ("` +
-                    `, %, !, or CR/LF) that cannot be safely escaped on a ` +
-                    `cmd.exe /c command line (CWE-78, #817). Rename/quote the ` +
-                    "value or invoke the tool without going through cmd.exe.");
-                return {
-                    stdout: "",
-                    stderr: "",
-                    status: null,
-                    error,
-                    failure: "spawn",
-                    spawnFailure: classifySpawnFailureSync(error, {
-                        command,
-                        cwd: options?.cwd,
-                    }),
-                };
-            }
-            spawnCmd = `${process.env.SystemRoot ?? "C:\\Windows"}\\System32\\cmd.exe`;
-            spawnArgs = [
-                "/d",
-                "/s",
-                "/c",
-                buildWindowsShellCommand(resolved.resolvedPath, args),
-            ];
-            windowsVerbatimArguments = true;
-        }
-        else {
-            ensureUtf8ConsoleCodePageOnce();
-            spawnCmd = resolved.resolvedPath;
-            spawnArgs = args;
-        }
-        const result = spawnSync(spawnCmd, spawnArgs, {
-            ...options,
-            cwd: spawnCwd,
-            env: spawnEnv,
-            encoding: "utf-8",
-            shell: false,
-            windowsHide: true,
-            windowsVerbatimArguments,
-        });
-        const spawnFailure = result.error
-            ? classifySpawnFailureSync(result.error, { command, cwd: options?.cwd })
-            : undefined;
-        return {
-            stdout: result.stdout?.toString() || "",
-            stderr: result.stderr?.toString() || "",
-            status: result.status,
-            error: result.error,
-            ...(spawnFailure ? { failure: "spawn", spawnFailure } : {}),
-        };
-    }
-    const result = spawnSync(command, args, {
-        ...options,
-        // Explicit override, not just the spread above: `options.env` alone
-        // would otherwise reach the child as a full replacement (no
-        // process.env merge, no PATH) instead of the merged environment the
-        // resolver/Windows branch above both use (#1201) — the module's
-        // "resolver and child receive the same merged environment" invariant
-        // must hold on every platform, not just Windows.
-        env: spawnEnv,
-        encoding: "utf-8",
-        shell: false,
-        windowsHide: true,
-    });
-    const spawnFailure = result.error
-        ? classifySpawnFailureSync(result.error, { command, cwd: options?.cwd })
-        : undefined;
-    return {
-        stdout: result.stdout?.toString() || "",
-        stderr: result.stderr?.toString() || "",
-        status: result.status,
-        error: result.error,
-        ...(spawnFailure ? { failure: "spawn", spawnFailure } : {}),
-    };
-}
-/**
- * Check if a command is available in PATH (sync version - deprecated)
- * @deprecated Use isCommandAvailableAsync
- */
-export function isCommandAvailable(command) {
-    const result = safeSpawn(process.platform === "win32" ? "where" : "which", [command], { timeout: 5000 });
-    return result.status === 0;
-}
-/**
- * Find the full path to a command (sync version - deprecated)
- * @deprecated Use findCommandAsync
- */
-export function findCommand(command) {
-    const finder = process.platform === "win32" ? "where" : "which";
-    const result = safeSpawn(finder, [command], { timeout: 5000 });
-    if (result.status !== 0)
-        return null;
-    return result.stdout.trim().split("\n")[0] || null;
-}