pi-lens 4.3.0 → 4.4.0

package/dist/clients/lsp/launch.js

@@ -1,746 +0,0 @@
-/**
- * LSP Process Launch Utilities
- *
- * Handles spawning LSP servers via various methods:
- * - Direct binary execution (using absolute paths on Windows)
- * - Node.js scripts (npx/bun)
- * - Package manager execution
- */
-import { execFileSync, spawn as nodeSpawn, } from "node:child_process";
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-import { isTestMode } from "../env-utils.js";
-import { getGlobalPiLensDir } from "../file-utils.js";
-import { getGlobalPiLensLogDir } from "../probe-home-state.js";
-import { isFullyQualified } from "../path-utils.js";
-import { findGlobalBinary } from "../package-manager.js";
-import { redactSecrets } from "../redact/secrets.js";
-import { classifySpawnFailure, holdOwnChildPid, isOwnLiveChild, SpawnFailureError, } from "../safe-spawn.js";
-import { getRubyVersionDirNamesAsync } from "./ruby-drive-dirs.js";
-const isWindows = process.platform === "win32";
-/**
- * Whether a resolved command must be spawned through a shell on Windows.
- * `.cmd`/`.bat` are scripts cmd.exe must interpret; extensionless or spaced-path
- * commands also go through the shell so cmd resolves/quotes them.
- */
-function computeNeedsShell(resolvedCommand) {
-    return (isWindows &&
-        (resolvedCommand.includes(" ") ||
-            /\.(cmd|bat)$/i.test(resolvedCommand) ||
-            !/\.(exe|cmd|bat)$/i.test(resolvedCommand)));
-}
-const DEFAULT_STARTUP_FAILURE_WINDOW_MS = 50;
-const WINDOWS_NAV_STARTUP_FAILURE_WINDOW_MS = 500;
-const SESSIONSTART_LOG_DIR = getGlobalPiLensLogDir();
-const SESSIONSTART_LOG = path.join(SESSIONSTART_LOG_DIR, "sessionstart.log");
-const PI_LENS_BIN_DIR = path.join(getGlobalPiLensDir(), "bin");
-const PI_LENS_TOOLS_BIN_DIR = path.join(getGlobalPiLensDir(), "tools", "node_modules", ".bin");
-function logSessionStart(msg) {
-    if (isTestMode()) {
-        return;
-    }
-    // Crash-adjacent: keep this write synchronous so a hard launch failure
-    // cannot discard the final diagnostic from an async logger queue.
-    const line = redactSecrets(`[${new Date().toISOString()}] ${msg}\n`);
-    try {
-        fs.mkdirSync(SESSIONSTART_LOG_DIR, { recursive: true });
-        fs.appendFileSync(SESSIONSTART_LOG, line);
-    }
-    catch { }
-}
-function compactLogValue(value, max = 280) {
-    const normalized = value.replace(/\s+/g, " ").trim();
-    if (!normalized)
-        return "";
-    return normalized.length > max
-        ? `${normalized.slice(0, max)}...`
-        : normalized;
-}
-function delimiterForPlatform(platform) {
-    return platform === "win32" ? ";" : ":";
-}
-function splitPathEntries(value, delimiter) {
-    if (!value)
-        return [];
-    return value
-        .split(delimiter)
-        .map((entry) => entry.trim())
-        .filter((entry) => entry.length > 0);
-}
-/**
- * Dedupe key for one PATH entry, under `platform`'s rules.
- *
- * #1193 P3: the body used the HOST-DEFAULT `path.normalize` inside a branch
- * already committed to `platform` (AGENTS.md defect shape 2), so on the ubuntu
- * lane the win32 arm lowercased without folding separators or dot segments and
- * `C:\Tools` / `C:/Tools` / `C:\x\..\Tools` were three keys for one directory.
- * Each arm now parses with its own `path` flavor. That is the whole fix: a
- * `toPosix` call on the win32 arm would be INERT — `win32.normalize` already
- * answers backslashes for either input separator (measured: adding it left
- * every case green) — and the POSIX arm must NOT fold separators at all,
- * because a backslash is a legal POSIX filename character and `/opt/a\b` and
- * `/opt/a/b` are two directories there.
- *
- * Ephemeral by construction: the key exists only inside one
- * `combinePathValuesForPlatform` call's `seen` set — the ORIGINAL entry string
- * is what survives into the joined PATH — so it never reaches a persisted or
- * cross-process record and `normalizeEphemeralMapKey`'s `process.platform` read
- * would defeat the explicit-`platform` seam these arms exist for.
- */
-function normalizePathEntry(entry, platform) {
-    if (platform !== "win32")
-        return path.posix.normalize(entry);
-    return path.win32.normalize(entry).toLowerCase();
-}
-export function combinePathValuesForPlatform(values, platform = process.platform) {
-    const unique = [];
-    const seen = new Set();
-    const delimiter = delimiterForPlatform(platform);
-    for (const value of values) {
-        for (const entry of splitPathEntries(value, delimiter)) {
-            const key = normalizePathEntry(entry, platform);
-            if (seen.has(key))
-                continue;
-            seen.add(key);
-            unique.push(entry);
-        }
-    }
-    return unique.join(delimiter);
-}
-function resolvePathValue(env) {
-    return combinePathValuesForPlatform([env.PATH, env.Path, env.path]);
-}
-/**
- * Run an `execFileSync` probe with the #2095 stderr guard applied, returning
- * `""` on any failure. Exported as a small test seam: production always calls
- * it with the fixed `powershell.exe` command/args below, but a test can pass
- * a command guaranteed to fail with real stderr output (no real Windows or
- * powershell.exe required) to prove the guard is actually reached and not
- * vacuous.
- */
-export function runStderrGuardedProbe(command, args) {
-    try {
-        const { execFileSync } = require("node:child_process");
-        const out = execFileSync(command, args, {
-            timeout: 3000,
-            encoding: "utf8",
-            // #2095 sibling: execFileSync inherits stderr to the parent by
-            // default (only stdout is captured into `out`), so a failed
-            // powershell.exe launch would print raw diagnostics into the pi
-            // TUI even though the surrounding catch already returns "" (read as
-            // "unknown" PATH by every caller). Pipe stderr instead of inheriting it.
-            stdio: ["ignore", "pipe", "ignore"],
-        });
-        return out.trim();
-    }
-    catch {
-        return "";
-    }
-}
-/** Read live system+user PATH from Windows registry (bypasses stale process.env.PATH). */
-function readWindowsRegistryPath() {
-    return runStderrGuardedProbe("powershell.exe", [
-        "-NoProfile",
-        "-NonInteractive",
-        "-Command",
-        "[System.Environment]::GetEnvironmentVariable('Path','Machine') + ';' + [System.Environment]::GetEnvironmentVariable('Path','User')",
-    ]);
-}
-let _liveWindowsPath = null;
-function getLiveWindowsPath() {
-    if (_liveWindowsPath === null) {
-        _liveWindowsPath = readWindowsRegistryPath();
-    }
-    return _liveWindowsPath;
-}
-async function buildAugmentedPath(basePath) {
-    const candidates = [];
-    const nodeDir = path.dirname(process.execPath);
-    if (nodeDir) {
-        candidates.push(nodeDir);
-    }
-    if (isWindows) {
-        const home = os.homedir();
-        const driveRoot = path.parse(home).root; // e.g. "C:\"
-        candidates.push(path.join(home, ".cargo", "bin"));
-        candidates.push(path.join(home, "go", "bin"));
-        candidates.push(path.join(home, ".dotnet", "tools"));
-        candidates.push(PI_LENS_BIN_DIR);
-        candidates.push(PI_LENS_TOOLS_BIN_DIR);
-        candidates.push(path.join(driveRoot, "Program Files", "Go", "bin"));
-        candidates.push(path.join(driveRoot, "Go", "bin"));
-        // Ruby installer drops versioned dirs (e.g. Ruby34-x64) on the drive root.
-        // Read off the event loop and memoized once per process (#1137): a
-        // synchronous drive-root enumeration on every LSP spawn blocked the loop
-        // for the whole stall on a slow cloud/network-backed drive root.
-        for (const entry of await getRubyVersionDirNamesAsync(driveRoot)) {
-            candidates.push(path.join(driveRoot, entry, "bin"));
-        }
-    }
-    // On Windows, merge the live registry PATH so newly installed tools are visible
-    // even if the pi agent process started before they were installed.
-    const effectiveBase = isWindows
-        ? combinePathValuesForPlatform([basePath, getLiveWindowsPath()])
-        : basePath;
-    const existing = new Set();
-    for (const entry of splitPathEntries(effectiveBase, path.delimiter)) {
-        if (!entry)
-            continue;
-        existing.add(normalizePathEntry(entry, process.platform));
-    }
-    const toAppend = [];
-    for (const candidate of candidates) {
-        if (!candidate || !fs.existsSync(candidate))
-            continue;
-        const normalized = normalizePathEntry(candidate, process.platform);
-        if (existing.has(normalized))
-            continue;
-        toAppend.push(candidate);
-        existing.add(normalized);
-    }
-    if (toAppend.length === 0)
-        return basePath ?? "";
-    if (!basePath)
-        return toAppend.join(path.delimiter);
-    return `${basePath}${path.delimiter}${toAppend.join(path.delimiter)}`;
-}
-/**
- * Validate that a .cmd shim's target JS/script exists before attempting to
- * spawn it. npm-generated .cmd files reference the actual script via a path
- * like `"%~dp0\..\yaml-language-server\bin\yaml-language-server"`. If that
- * target is missing the shim will exit immediately with code 1 after a 500ms
- * startup window — pre-checking avoids the delay.
- * Returns true if the shim is valid (or we can't determine), false if the
- * target is definitively missing.
- */
-export function isCmdShimValid(cmdPath) {
-    try {
-        const content = fs.readFileSync(cmdPath, "utf-8");
-        // npm cmd shim pattern: "%~dp0\..\<relpath>" or "%~dp0/<relpath>"
-        // The `-` ends the char class, where it is a literal and needs no escape.
-        // oxfmt formats this repository (#1844) and rewrites no regex literal, so
-        // this line needs no suppression; the directive oxfmt honors, if one is
-        // ever needed here, is `// prettier-ignore`.
-        const match = content.match(/"%~dp0[/\\]\.\.[/\\]((?:[\w./@-]|\\)+\.(?:mjs|cjs|js))"/i);
-        if (!match)
-            return true; // non-npm shim — let it through
-        const relPath = match[1].replace(/[/\\]/g, path.sep);
-        const target = path.resolve(path.dirname(cmdPath), "..", relPath);
-        return fs.existsSync(target);
-    }
-    catch {
-        return true; // can't read — be permissive
-    }
-}
-/**
- * On Windows, npm creates .ps1 wrappers that hang indefinitely when PowerShell
- * execution policy is Restricted or AllSigned. Bypass by preferring the .cmd
- * sibling (runs under cmd.exe, no execution policy) or falling back to direct
- * Node.js execution of the JS entry point extracted from the PS1 script.
- * Returns undefined if no safe bypass is found.
- */
-function bypassPs1OnWindows(ps1Path, args) {
-    // 1. Prefer the .cmd sibling — cmd.exe handles it without execution policy issues
-    const cmdPath = `${ps1Path.slice(0, -4)}.cmd`;
-    if (fs.existsSync(cmdPath)) {
-        return { command: cmdPath, args, needsShell: true };
-    }
-    // 2. Parse the .ps1 to find the JS entry point and invoke via node directly.
-    // npm-generated PS1 pattern: "$basedir/../<package>/bin/cli.js"
-    try {
-        const content = fs.readFileSync(ps1Path, "utf-8");
-        // Same char class as isCmdShimValid above, and the same note: the trailing
-        // `-` is a literal, and oxfmt leaves regex literals alone.
-        const match = content.match(/"\$basedir[/\\]\.\.[/\\]((?:[\w./@-]|\\)+\.(?:mjs|cjs|js))"/i);
-        if (match) {
-            const relPath = match[1].replace(/[/\\]/g, path.sep);
-            const jsPath = path.resolve(path.dirname(ps1Path), "..", relPath);
-            if (fs.existsSync(jsPath)) {
-                return {
-                    command: process.execPath,
-                    args: [jsPath, ...args],
-                    needsShell: false,
-                };
-            }
-        }
-    }
-    catch {
-        // Can't read PS1 — no bypass available
-    }
-    return undefined;
-}
-function findBinaryOnPath(command, env) {
-    try {
-        const result = execFileSync(isWindows ? "where" : "which", [command], {
-            encoding: "utf-8",
-            stdio: ["ignore", "pipe", "ignore"],
-            env,
-            // #1980 population sweep: this was the one synchronous
-            // child-process site in the repo with no bound at all. It runs on
-            // the LSP server spawn path, so an unresponsive `where`/`which` — a
-            // stale network PATH entry is the classic cause — parked the event
-            // loop with no ceiling, and read as ordinary compute in
-            // `loop_block`. 5s matches `isCommandAvailable`/`findCommand` in
-            // clients/safe-spawn.ts, which run these same two binaries.
-            timeout: 5000,
-        })
-            .split(/\r?\n/)
-            .map((line) => line.trim())
-            .filter(Boolean);
-        for (const candidate of result) {
-            if (fs.existsSync(candidate)) {
-                return candidate;
-            }
-        }
-    }
-    catch {
-        // ignore lookup failures
-    }
-    return undefined;
-}
-/**
- * Try to spawn a process, throwing immediately if it fails
- */
-function trySpawn(command, args, cwd, env, needsShell) {
-    let proc;
-    if (needsShell) {
-        // Build a cmd.exe-safe command string: wrap in double quotes, escape internal
-        // quotes by doubling them, and escape cmd metacharacters (& | < > ^ ( ) !) with ^
-        const escapeCmdArg = (s) => {
-            // Escape cmd.exe metacharacters first, then wrap in quotes if needed
-            const escaped = s.replace(/([&|<>^()!])/g, "^$1");
-            return /[\s"]/.test(escaped)
-                ? `"${escaped.replace(/"/g, '""')}"`
-                : escaped;
-        };
-        // shell:true justified: Windows .cmd/.bat LSP binaries (e.g. typescript-language-server.cmd)
-        // cannot be spawned via execFile — cmd.exe must interpret the script wrapper.
-        const shellCommand = `"${command}" ${args.map(escapeCmdArg).join(" ")}`;
-        // #2015 class-sweep exemption: this is a LONG-LIVED language-server launch,
-        // not a bounded probe - killing it on a timeout would be wrong, and its
-        // lifetime is owned by the LSP lifecycle, not the spawner. Exempt from the
-        // verifyToolBinary/probe tree-kill migration.
-        proc = nodeSpawn(shellCommand, [], {
-            cwd,
-            env,
-            stdio: ["pipe", "pipe", "pipe"],
-            detached: !isWindows,
-            windowsHide: true,
-            shell: true,
-        });
-    }
-    else {
-        // Use normal spawn without shell
-        proc = nodeSpawn(command, args, {
-            cwd,
-            env,
-            stdio: ["pipe", "pipe", "pipe"],
-            detached: !isWindows,
-            windowsHide: isWindows,
-        });
-    }
-    if (!proc.stdin || !proc.stdout || !proc.stderr) {
-        throw new Error(`Failed to spawn LSP server: ${command}`);
-    }
-    // Check if process exited immediately (spawn failure - synchronous check)
-    if (proc.exitCode !== null || proc.killed) {
-        throw new Error(`LSP server ${command} exited immediately (code: ${proc.exitCode}). ` +
-            `The binary may be missing or corrupted.`);
-    }
-    // #3091 F1-r2: take ownership HERE, while the child is provably alive. LSP
-    // servers are the one long-lived child pi-lens spawns outside
-    // `safeSpawnAsync`, so without this their first offer of verification is
-    // `stopLSP`'s group kill — by which time, on the `processExiting` path, the
-    // leader can already be dead, `/proc` is gone, and the group signal that
-    // reaps surviving grandchildren (#2026) is refused. The verdict is released
-    // by `killProcessTree` when the shutdown ladder is done with the pid.
-    holdOwnChildPid(proc.pid, "lsp-spawn");
-    return proc;
-}
-/**
- * Attach error handler to a spawned process to prevent ENOENT crashes
- * This catches "command not found" errors and other spawn failures
- * Returns a promise that rejects if an immediate error occurs
- */
-function unrefLspProcessHandles(proc) {
-    try {
-        proc.unref();
-    }
-    catch {
-        // best-effort
-    }
-    for (const stream of [proc.stdin, proc.stdout, proc.stderr]) {
-        try {
-            stream?.unref?.();
-        }
-        catch {
-            // best-effort
-        }
-    }
-}
-function _attachErrorHandler(proc, context, logContext, rejectOnImmediateError) {
-    let stderrPreview = "";
-    let closeLogged = false;
-    const onStderr = (chunk) => {
-        if (stderrPreview.length >= 4000)
-            return;
-        stderrPreview += chunk.toString();
-    };
-    proc.stderr?.on("data", onStderr);
-    proc.on("error", (err) => {
-        if (logContext) {
-            logSessionStart("lsp process " +
-                context +
-                ": spawn-error command=" +
-                logContext.command +
-                " args=" +
-                JSON.stringify(logContext.args) +
-                " cwd=" +
-                logContext.cwd +
-                " pid=" +
-                (logContext.pid ?? 0) +
-                " error=" +
-                err.message +
-                (stderrPreview ? " stderr=" + compactLogValue(stderrPreview) : ""));
-        }
-        // Preserve intent at the boundary instead of leaking a raw errno check.
-        if (rejectOnImmediateError && logContext) {
-            void classifySpawnFailure(err, {
-                command: logContext.command,
-                cwd: logContext.cwd,
-            }).then(rejectOnImmediateError);
-        }
-    });
-    proc.on("close", (code, signal) => {
-        if (closeLogged)
-            return;
-        closeLogged = true;
-        proc.stderr?.off("data", onStderr);
-        if (code !== 0 && code !== null) {
-            if (logContext) {
-                logSessionStart("lsp process " +
-                    context +
-                    ": closed code=" +
-                    code +
-                    (signal ? " signal=" + signal : "") +
-                    " command=" +
-                    logContext.command +
-                    " args=" +
-                    JSON.stringify(logContext.args) +
-                    " cwd=" +
-                    logContext.cwd +
-                    " pid=" +
-                    (logContext.pid ?? 0) +
-                    (stderrPreview ? " stderr=" + compactLogValue(stderrPreview) : ""));
-            }
-        }
-        else if (signal && logContext) {
-            logSessionStart("lsp process " +
-                context +
-                ": closed signal=" +
-                signal +
-                " command=" +
-                logContext.command +
-                " args=" +
-                JSON.stringify(logContext.args) +
-                " cwd=" +
-                logContext.cwd +
-                " pid=" +
-                (logContext.pid ?? 0) +
-                (stderrPreview ? " stderr=" + compactLogValue(stderrPreview) : ""));
-        }
-    });
-}
-/**
- * Spawn an LSP server process
- *
- * Key fixes for Windows:
- * - Uses absolute paths (relative paths fail in shell mode)
- * - Uses shell: true for .cmd files
- * - Uses windowsHide to prevent console window popup
- * - Detects immediate spawn failures (ENOENT) before returning
- *
- * @param command - Command to run (e.g., "typescript-language-server")
- * @param args - Arguments (e.g., ["--stdio"])
- * @param options - Spawn options including cwd, env
- * @returns LSPProcess handle
- */
-export async function launchLSP(command, args = [], options = {}) {
-    const cwd = String(options.cwd ?? process.cwd());
-    const mergedEnv = { ...process.env, ...options.env };
-    const augmentedPath = await buildAugmentedPath(resolvePathValue(mergedEnv));
-    const env = {
-        ...mergedEnv,
-        PATH: augmentedPath,
-        ...(isWindows ? { Path: augmentedPath } : {}),
-    };
-    // Resolve command path
-    // - If already absolute, use as-is
-    // - If it's a simple command (no path separators), let system find it via PATH
-    // - Otherwise, resolve relative to cwd
-    const isRelativePath = !isFullyQualified(command) &&
-        (command.includes(path.sep) || command.includes("/"));
-    const explicitCommand = isRelativePath ? path.resolve(cwd, command) : command;
-    const resolvedCommand = !isFullyQualified(command) &&
-        !command.includes(path.sep) &&
-        !command.includes("/")
-        ? (findBinaryOnPath(command, env) ?? explicitCommand)
-        : explicitCommand;
-    // Compute needsShell based on command
-    // On Windows, shell: true is needed for .cmd/.bat files and extensionless binaries
-    // .exe files can be spawned directly, but .cmd/.bat require shell interpretation
-    let needsShell = computeNeedsShell(resolvedCommand);
-    // Try to spawn the process
-    // If command not found, try npm global as fallback (handles PATH caching after install)
-    let spawnCommand = resolvedCommand;
-    // First, try to find in npm global if it's a simple command name
-    if (!isFullyQualified(command) &&
-        !command.includes(path.sep) &&
-        !command.includes("/")) {
-        const globalBinPath = await findGlobalBinary(command);
-        if (globalBinPath) {
-            spawnCommand = globalBinPath;
-            // Recompute needsShell for the resolved global path
-            needsShell = computeNeedsShell(spawnCommand);
-        }
-    }
-    // Pre-validate .cmd shims: if the underlying script is missing the shim will
-    // exit with code 1 after a 500ms wait. Catching this early avoids the delay.
-    if (isWindows &&
-        /\.(cmd|bat)$/i.test(spawnCommand) &&
-        !isCmdShimValid(spawnCommand)) {
-        logSessionStart(`lsp cmd-shim-invalid: ${spawnCommand} target missing — skipping candidate`);
-        const cause = Object.assign(new Error(`LSP .cmd shim target not found: ${spawnCommand}`), { code: "ENOENT" });
-        throw await classifySpawnFailure(cause, { command, cwd });
-    }
-    // P0 FIX: Never spawn .ps1 wrappers on Windows — they hang when PowerShell
-    // execution policy is Restricted/AllSigned. Prefer .cmd or direct node.
-    if (isWindows && /\.ps1$/i.test(spawnCommand)) {
-        const bypass = bypassPs1OnWindows(spawnCommand, args);
-        if (bypass) {
-            logSessionStart(`lsp ps1-bypass: ${spawnCommand} → ${bypass.command} shell=${bypass.needsShell}`);
-            spawnCommand = bypass.command;
-            args = bypass.args;
-            needsShell = bypass.needsShell;
-        }
-        else {
-            logSessionStart(`lsp ps1-bypass: no .cmd or JS entry found for ${spawnCommand}, spawn may hang`);
-        }
-    }
-    let proc;
-    try {
-        proc = trySpawn(spawnCommand, args, cwd, env, needsShell);
-    }
-    catch (err) {
-        // If spawn failed with simple command, try npm global
-        if (!isFullyQualified(command) &&
-            !command.includes(path.sep) &&
-            !command.includes("/")) {
-            const globalBinPath = await findGlobalBinary(command);
-            if (globalBinPath && globalBinPath !== spawnCommand) {
-                // Recompute needsShell for the resolved global path
-                const needsShellGlobal = computeNeedsShell(globalBinPath);
-                proc = trySpawn(globalBinPath, args, cwd, env, needsShellGlobal);
-            }
-            else {
-                throw await classifySpawnFailure(err, { command, cwd });
-            }
-        }
-        else {
-            throw await classifySpawnFailure(err, { command, cwd });
-        }
-    }
-    if (!proc.stdin || !proc.stdout || !proc.stderr) {
-        throw new Error(`Failed to spawn LSP server: ${command}`);
-    }
-    // Check if process exited immediately (spawn failure - synchronous check)
-    if (proc.exitCode !== null || proc.killed) {
-        throw new Error(`LSP server ${command} exited immediately (code: ${proc.exitCode}). ` +
-            `The binary may be missing or corrupted.`);
-    }
-    logSessionStart(`lsp launch: command=${command} resolved=${spawnCommand} args=${JSON.stringify(args)} cwd=${cwd} shell=${needsShell ? "true" : "false"} pid=${proc.pid ?? 0}`);
-    const formatStartupStderr = (stderr) => {
-        const normalized = compactLogValue(stderr);
-        if (!normalized)
-            return "";
-        return ` stderr=${normalized}`;
-    };
-    let startupStderr = "";
-    const onStartupStderr = (chunk) => {
-        if (startupStderr.length >= 4000)
-            return;
-        startupStderr += chunk.toString();
-    };
-    proc.stderr?.on("data", onStartupStderr);
-    // For Windows and certain spawn failures, the error is async (ENOENT)
-    // We need to wait a small tick to catch immediate spawn failures
-    try {
-        await new Promise((resolve, reject) => {
-            let settled = false;
-            // Attach error handler that can reject for immediate errors
-            proc.on("error", (err) => {
-                if (!settled) {
-                    settled = true;
-                    void classifySpawnFailure(err, { command, cwd }).then((failure) => {
-                        const detail = formatStartupStderr(startupStderr);
-                        reject(detail
-                            ? new SpawnFailureError(failure.kind, `${failure.message}${detail}`, failure.cause)
-                            : failure);
-                    });
-                }
-            });
-            // Also listen for immediate exit
-            proc.on("exit", (code) => {
-                if (!settled && code !== null) {
-                    settled = true;
-                    // On Windows, .cmd shims fail with code 1 when the underlying binary isn't installed
-                    // This is different from ENOENT - the shim exists but can't find the binary
-                    const isWindowsCmd = isWindows && command.endsWith(".cmd");
-                    const errorMsg = isWindowsCmd && code === 1
-                        ? `npm .cmd shim failed (underlying binary not installed). Run 'npm install' in this project or use a global installation.`
-                        : `The binary may be missing or corrupted.`;
-                    reject(new Error(`LSP server ${command} exited immediately with code ${code}. ${errorMsg}${formatStartupStderr(startupStderr)}`));
-                }
-            });
-            const startupFailureWindowMs = (() => {
-                if (options?.startupFailureWindowMs) {
-                    return options.startupFailureWindowMs;
-                }
-                if (isWindows && needsShell) {
-                    return WINDOWS_NAV_STARTUP_FAILURE_WINDOW_MS;
-                }
-                return DEFAULT_STARTUP_FAILURE_WINDOW_MS;
-            })();
-            // Give shell-backed Windows launches a slightly longer window because
-            // npm/cmd shims can fail asynchronously after the initial spawn succeeds.
-            setTimeout(() => {
-                if (!settled) {
-                    settled = true;
-                    resolve();
-                }
-            }, startupFailureWindowMs);
-        });
-    }
-    finally {
-        proc.stderr?.off("data", onStartupStderr);
-    }
-    // Re-attach the permanent error handler now that we've passed the danger zone
-    _attachErrorHandler(proc, command, {
-        command: spawnCommand,
-        args,
-        cwd,
-        pid: proc.pid ?? 0,
-    });
-    unrefLspProcessHandles(proc);
-    return {
-        process: proc,
-        stdin: proc.stdin,
-        stdout: proc.stdout,
-        stderr: proc.stderr,
-        pid: proc.pid ?? 0,
-        command: spawnCommand,
-        args,
-    };
-}
-/**
- * Spawn via Node.js directly
- */
-export async function launchViaNode(scriptPath, args = [], options = {}) {
-    return launchLSP(process.execPath, [scriptPath, ...args], options);
-}
-/**
- * Spawn via Python module
- */
-export async function launchViaPython(moduleName, args = [], options = {}) {
-    // On Windows, prefer 'py' launcher, fall back to 'python'
-    const pythonCmd = process.platform === "win32" ? "py" : "python3";
-    return launchLSP(pythonCmd, ["-m", moduleName, ...args], options);
-}
-/**
- * Stop an LSP process gracefully
- */
-export async function stopLSP(handle) {
-    if (handle.process.exitCode !== null || handle.process.signalCode !== null) {
-        return;
-    }
-    return new Promise((resolve) => {
-        let settled = false;
-        let forceTimeout;
-        let giveUpTimeout;
-        const done = () => {
-            if (settled)
-                return;
-            settled = true;
-            if (forceTimeout)
-                clearTimeout(forceTimeout);
-            if (giveUpTimeout)
-                clearTimeout(giveUpTimeout);
-            handle.process.off("exit", done);
-            handle.process.off("error", done);
-            resolve();
-        };
-        handle.process.once("exit", done);
-        handle.process.once("error", done);
-        const killWindowsTree = () => {
-            if (!isWindows)
-                return false;
-            // If our child has already exited, its PID is dead and the OS may have
-            // RECYCLED it to an unrelated process. `taskkill /F /T` on a recycled PID
-            // force-kills that process AND its whole tree — in the test suite this
-            // occasionally nuked a vitest worker fork ("Worker exited unexpectedly",
-            // no fatal dump, e.g. via the "stopLSP after the process already exited"
-            // path); in production it could kill an unrelated user process. Never
-            // tree-kill a PID we no longer own — fall back to handle.process.kill(),
-            // which on Windows signals via the retained process HANDLE (not the raw
-            // PID), so it's a safe no-op on an already-exited child.
-            //
-            // #2042 folded the sign check and this exited check into the one
-            // ownership predicate every kill-by-raw-pid now shares; the handle
-            // arm below IS this paragraph, and on Windows it is the only
-            // ownership evidence available (there is no /proc to read).
-            if (!isOwnLiveChild(handle.pid, "lsp-stop-windows-tree", handle.process))
-                return false;
-            try {
-                // Absolute path avoids PATH-resolution substitution on Windows.
-                const taskkill = `${process.env.SystemRoot ?? "C:\\Windows"}\\System32\\taskkill.exe`;
-                const killer = nodeSpawn(taskkill, ["/F", "/T", "/PID", String(handle.pid)], {
-                    shell: false,
-                    windowsHide: true,
-                });
-                killer.once("error", done);
-                return true;
-            }
-            catch {
-                return false;
-            }
-        };
-        try {
-            // On Windows, kill the tree first; killing the direct child can orphan
-            // grandchildren (e.g. tsserver.js behind a cmd/npm shim).
-            if (!killWindowsTree()) {
-                handle.process.kill("SIGTERM");
-            }
-        }
-        catch {
-            done();
-            return;
-        }
-        forceTimeout = setTimeout(() => {
-            if (settled)
-                return;
-            try {
-                if (!killWindowsTree()) {
-                    handle.process.kill("SIGKILL");
-                }
-            }
-            catch {
-                done();
-                return;
-            }
-            // If the process had already exited before listeners were attached, no
-            // exit event will arrive. Resolve rather than hanging test cleanup forever.
-            giveUpTimeout = setTimeout(done, 500);
-        }, 5000);
-    });
-}