@herbertgao/pi-extensions 2026.8.4 → 2026.8.6

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

@@ -17,7 +17,153 @@ import { spawn, spawnSync, } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { logLatency } from "./latency-logger.js";
+import { recordDegradation } from "./degradation-ledger.js";
+import { logExtension } from "./extension-log.js";
+import { isFullyQualifiedWin32 } from "./path-utils.js";
 import { startSpawnUsageSampler } from "./resource-sampler.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);
+}
+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");
@@ -128,19 +274,271 @@ export function buildWindowsShellCommand(command, args) {
     return `chcp 65001 >nul 2>&1 && ${[command, ...args].map(cmdEscapeArg).join(" ")}`;
 }
 /**
- * Cached PATH + PATHEXT resolution results, keyed by
- * `${command}\0${PATH}\0${cwd}` so a changed PATH or cwd never hits a stale
- * entry. Session-lived (matches this repo's other resolution caches, e.g.
+ * 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`.
+ * `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.
  */
+const WINDOWS_COMMAND_CACHE_MAX_ENTRIES = 256;
+const WINDOWS_COMMAND_NEGATIVE_CACHE_TTL_MS = 1000;
 const windowsCommandCache = new Map();
-/** Reset hook for session start — see `clients/runtime-session.ts`. */
+/** Reset after session replacement or a successful managed install. */
 export function resetSafeSpawnWindowsCommandCache() {
     windowsCommandCache.clear();
+    loggedSpawnClassifications.clear();
 }
-function getPathExts() {
-    const raw = process.env.PATHEXT || ".COM;.EXE;.BAT;.CMD";
+function cacheWindowsCommandResult(key, resolved) {
+    if (windowsCommandCache.size >= WINDOWS_COMMAND_CACHE_MAX_ENTRIES) {
+        // Resolution entries are session-scoped and cheap to recompute. Evict the
+        // oldest insertion first so a long-lived process cannot retain every cwd /
+        // environment it has ever touched.
+        const oldest = windowsCommandCache.keys().next().value;
+        if (oldest !== undefined)
+            windowsCommandCache.delete(oldest);
+    }
+    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())
@@ -154,48 +552,145 @@ function statIsFile(candidate) {
         return false;
     }
 }
-function resolveWindowsCommandUncached(command, cwd) {
-    const pathExts = getPathExts();
-    const existingExt = path.extname(command).toLowerCase();
-    const hasKnownExt = pathExts.includes(existingExt);
+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) => {
-        if (hasKnownExt) {
-            return statIsFile(base) ? { resolvedPath: base, ext: existingExt } : null;
+        // 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 };
         }
-        for (const ext of pathExts) {
-            const candidate = base + ext;
-            if (statIsFile(candidate))
-                return { resolvedPath: candidate, ext };
+        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);
-    if (hasPathSep || path.isAbsolute(command)) {
-        const base = path.isAbsolute(command)
-            ? command
-            : path.resolve(cwd ?? process.cwd(), command);
-        return tryBase(base);
+    // `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);
     }
-    const pathDirs = (process.env.PATH ?? process.env.Path ?? "").split(";");
+    // 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 found = tryBase(path.join(dir, command));
+        const resolvedDir = resolveWindowsPathEntry(dir, effectiveCwd, env);
+        if (resolvedDir === undefined)
+            continue;
+        const found = tryBase(path.win32.join(resolvedDir, command));
         if (found)
             return found;
     }
     return null;
 }
-/** Cached `where`-equivalent: resolve `command` to a real file via PATH + PATHEXT. */
-function resolveWindowsCommand(command, cwd) {
-    const cacheKey = `${command}\0${process.env.PATH ?? process.env.Path ?? ""}\0${cwd ?? ""}`;
-    if (windowsCommandCache.has(cacheKey)) {
-        return windowsCommandCache.get(cacheKey) ?? 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]) => left.localeCompare(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, cwd);
-    windowsCommandCache.set(cacheKey, resolved);
+    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
@@ -215,10 +710,8 @@ function findCmdUnsafeValue(command, args) {
 }
 function synthesizeEnoentError(command) {
     // Shaped like Node's native `spawn <cmd> ENOENT` error (message/code/
-    // syscall/path) so existing `err.message.includes("ENOENT")` /
-    // `err.code === "ENOENT"` call sites (e.g. sg-runner.ts, lsp/launch.ts)
-    // keep working now that Windows resolution happens before spawn instead
-    // of inside cmd.exe.
+    // 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";
@@ -251,11 +744,22 @@ function ensureUtf8ConsoleCodePageOnce() {
         });
     }
     catch {
-        // Best-effort: worst case is non-ASCII tool output mis-decoded, not a
+        // Best-effort: worst case is non-ASCII tool output decoded incorrectly, not a
         // spawn failure — never let this block the real spawn.
     }
 }
-/** Test-only: allow tests to force the chcp one-shot to run again. */
+/**
+ * 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;
 }
@@ -275,7 +779,15 @@ export function resetUtf8ConsoleCodePageStateForTests() {
  * if (result.error) console.error("Failed:", result.error);
  */
 export async function safeSpawnAsync(command, args, options) {
-    const timeout = options?.timeout ?? 30000;
+    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).
@@ -284,18 +796,72 @@ export async function safeSpawnAsync(command, args, options) {
     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: new Error("Spawn aborted before start"),
+                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 spawnErrored = false;
+        // #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;
+        // #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;
+        const maxOutputBytes = options?.maxOutputBytes !== undefined &&
+            Number.isFinite(options.maxOutputBytes) &&
+            options.maxOutputBytes > 0
+            ? Math.floor(options.maxOutputBytes)
+            : undefined;
+        const appendOutput = (current, chunk) => {
+            const text = typeof chunk === "string" ? chunk : chunk.toString();
+            if (maxOutputBytes === undefined)
+                return current + text;
+            const used = Buffer.byteLength(stdout) + Buffer.byteLength(stderr);
+            const remaining = maxOutputBytes - used;
+            if (remaining <= 0) {
+                outputTruncated = true;
+                return current;
+            }
+            const bytes = Buffer.byteLength(text);
+            if (bytes <= remaining)
+                return current + text;
+            outputTruncated = true;
+            return current + Buffer.from(text).subarray(0, remaining).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).
@@ -313,12 +879,36 @@ export async function safeSpawnAsync(command, args, options) {
         //   - 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) {
-            const resolved = resolveWindowsCommand(command, options?.cwd);
+            // 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);
             }
@@ -359,14 +949,24 @@ export async function safeSpawnAsync(command, args, options) {
             }
         }
         if (resolutionError) {
-            resolve({ stdout: "", stderr: "", status: null, error: resolutionError });
+            void classifySpawnFailure(resolutionError, {
+                command,
+                cwd: options?.cwd,
+            }).then((spawnFailure) => resolve({
+                stdout: "",
+                stderr: "",
+                status: null,
+                error: resolutionError,
+                failure: "spawn",
+                spawnFailure,
+            }));
             return;
         }
         let child;
         try {
             child = spawn(spawnCmd, spawnArgs, {
-                cwd: options?.cwd,
-                env: { ...process.env, ...options?.env },
+                cwd: spawnCwd,
+                env: spawnEnv,
                 windowsHide: true,
                 shell: false,
                 windowsVerbatimArguments,
@@ -380,12 +980,15 @@ export async function safeSpawnAsync(command, args, options) {
             // 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).
-            resolve({
+            const cause = toError(err);
+            void classifySpawnFailure(cause, { command, cwd: options?.cwd }).then((spawnFailure) => resolve({
                 stdout: "",
                 stderr: "",
                 status: null,
-                error: err instanceof Error ? err : new Error(String(err)),
-            });
+                error: cause,
+                failure: "spawn",
+                spawnFailure,
+            }));
             return;
         }
         if (options?.lifetimeCoupled && child.pid) {
@@ -434,27 +1037,43 @@ export async function safeSpawnAsync(command, args, options) {
             }
             else {
                 child.kill("SIGTERM");
-                setTimeout(() => {
-                    if (!child.killed)
+                escalationTimer = setTimeout(() => {
+                    if (!closed)
                         child.kill("SIGKILL");
                 }, 1000);
             }
         };
         // Handle abort signal
         const onAbort = () => {
+            aborted = true;
             if (!killed && !child.killed) {
                 killed = true;
                 void killTree();
             }
         };
         abortSignal?.addEventListener("abort", onAbort, { once: true });
+        // Output-cap kills are awaited by the close handler below, just like
+        // timeout/abort kills. This keeps a noisy CLI from continuing in the
+        // background after its retained output has been bounded.
+        let killPromise;
+        const stopForOutputLimit = () => {
+            if (outputTruncated && !killed && !child.killed) {
+                killed = true;
+                killPromise = killTree();
+            }
+        };
         // Collect output
         child.stdout?.setEncoding("utf-8");
         child.stderr?.setEncoding("utf-8");
-        child.stdout?.on("data", (data) => (stdout += data));
-        child.stderr?.on("data", (data) => (stderr += data));
+        child.stdout?.on("data", (data) => {
+            stdout = appendOutput(stdout, data);
+            stopForOutputLimit();
+        });
+        child.stderr?.on("data", (data) => {
+            stderr = appendOutput(stderr, data);
+            stopForOutputLimit();
+        });
         // Timeout handling - KILL the process, don't just abandon it
-        let killPromise;
         const timeoutId = setTimeout(() => {
             timedOut = true;
             if (!killed && !child.killed) {
@@ -488,41 +1107,99 @@ export async function safeSpawnAsync(command, args, options) {
         };
         // Process completion
         child.on("close", async (code, signal) => {
+            if (spawnErrored)
+                return;
+            closed = true;
             clearTimeout(timeoutId);
             abortSignal?.removeEventListener("abort", onAbort);
             if (child.pid)
                 lifetimeState.pids.delete(child.pid);
             await killPromise;
+            // #1109: the child has exited — if killTree armed the non-Windows
+            // SIGTERM→SIGKILL escalation timer and it hasn't fired yet, clear it
+            // so it doesn't linger as a ref'd handle after this promise resolves.
+            if (escalationTimer)
+                clearTimeout(escalationTimer);
             const resourceUsage = finishResourceUsage();
+            const outputInfo = outputTruncated ? { outputTruncated: true } : {};
             if (timedOut) {
+                const cause = new Error(`Process timed out after ${timeout}ms (killed with ${signal || "SIGTERM"})`);
                 resolve({
                     stdout,
                     stderr,
                     status: null,
-                    error: new Error(`Process timed out after ${timeout}ms (killed with ${signal || "SIGTERM"})`),
+                    error: cause,
+                    failure: "timeout",
+                    spawnFailure: new SpawnFailureError("timeout", cause.message, cause),
+                    ...outputInfo,
+                    resourceUsage,
+                });
+            }
+            else if (aborted) {
+                const cause = new Error("Spawn aborted");
+                resolve({
+                    stdout,
+                    stderr,
+                    status: null,
+                    error: cause,
+                    failure: "aborted",
+                    spawnFailure: new SpawnFailureError("killed", cause.message, cause),
+                    ...outputInfo,
                     resourceUsage,
                 });
             }
             else if (signal) {
+                const cause = new Error(`Process killed by signal: ${signal}`);
                 resolve({
                     stdout,
                     stderr,
                     status: null,
-                    error: new Error(`Process killed by signal: ${signal}`),
+                    error: cause,
+                    failure: "signal",
+                    spawnFailure: new SpawnFailureError("killed", cause.message, cause),
+                    ...outputInfo,
                     resourceUsage,
                 });
             }
             else {
-                resolve({ stdout, stderr, status: code, resourceUsage });
+                resolve({ stdout, stderr, status: code, ...outputInfo, resourceUsage });
             }
         });
         child.on("error", (err) => {
+            spawnErrored = true;
+            closed = true;
             clearTimeout(timeoutId);
             abortSignal?.removeEventListener("abort", onAbort);
+            if (escalationTimer)
+                clearTimeout(escalationTimer);
             if (child.pid)
                 lifetimeState.pids.delete(child.pid);
             const resourceUsage = finishResourceUsage();
-            resolve({ stdout, stderr, status: null, error: err, resourceUsage });
+            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 } : {}),
+                resourceUsage,
+            });
+            if (controlFailure)
+                finish(controlFailure);
+            else {
+                void classifySpawnFailure(err, { command, cwd: options?.cwd }).then(finish);
+            }
         });
     });
 }
@@ -591,14 +1268,29 @@ export async function findCommandAsync(command) {
  * No `shell: true` anywhere.
  */
 export function safeSpawn(command, args, options) {
+    const spawnEnv = getSpawnEnvironment(options?.env);
     if (process.platform === "win32") {
-        const resolved = resolveWindowsCommand(command, options?.cwd);
+        // 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: synthesizeEnoentError(command),
+                error,
+                failure: "spawn",
+                spawnFailure: classifySpawnFailureSync(error, {
+                    command,
+                    cwd: options?.cwd,
+                }),
             };
         }
         let spawnCmd;
@@ -610,15 +1302,21 @@ export function safeSpawn(command, args, options) {
             // 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: 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."),
+                    error,
+                    failure: "spawn",
+                    spawnFailure: classifySpawnFailureSync(error, {
+                        command,
+                        cwd: options?.cwd,
+                    }),
                 };
             }
             spawnCmd = `${process.env.SystemRoot ?? "C:\\Windows"}\\System32\\cmd.exe`;
@@ -637,29 +1335,46 @@ export function safeSpawn(command, args, options) {
         }
         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 } : {}),
     };
 }
 /**