ultimate-pi 0.18.0 → 0.19.0

package/.pi/lib/harness-lens/clients/lsp/launch.ts

@@ -0,0 +1,939 @@
+/**
+ * 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 {
+	type ChildProcess,
+	execFileSync,
+	execSync,
+	spawn as nodeSpawn,
+	type SpawnOptions,
+} from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export interface LSPProcess {
+	process: ChildProcess;
+	stdin: NodeJS.WritableStream;
+	stdout: NodeJS.ReadableStream;
+	stderr: NodeJS.ReadableStream;
+	pid: number;
+}
+
+const isWindows = process.platform === "win32";
+const DEFAULT_STARTUP_FAILURE_WINDOW_MS = 50;
+const WINDOWS_NAV_STARTUP_FAILURE_WINDOW_MS = 500;
+const SESSIONSTART_LOG_DIR = path.join(
+	process.cwd(),
+	".pi",
+	"harness",
+	".lens",
+);
+const SESSIONSTART_LOG = path.join(SESSIONSTART_LOG_DIR, "sessionstart.log");
+const PI_LENS_BIN_DIR = path.join(
+	process.cwd(),
+	".pi",
+	"harness",
+	".lens",
+	"bin",
+);
+const PI_LENS_TOOLS_BIN_DIR = path.join(
+	process.cwd(),
+	".pi",
+	"harness",
+	".lens",
+	"tools",
+	"node_modules",
+	".bin",
+);
+
+function logSessionStart(msg: string): void {
+	if (
+		process.env.PI_LENS_TEST_MODE === "1" ||
+		(process.env.VITEST && process.env.PI_LENS_TEST_MODE !== "0")
+	) {
+		return;
+	}
+	const line = `[${new Date().toISOString()}] ${msg}\n`;
+	try {
+		fs.mkdirSync(SESSIONSTART_LOG_DIR, { recursive: true });
+		fs.appendFileSync(SESSIONSTART_LOG, line);
+	} catch {}
+}
+
+function compactLogValue(value: string, max = 280): string {
+	const normalized = value.replace(/\s+/g, " ").trim();
+	if (!normalized) return "";
+	return normalized.length > max
+		? `${normalized.slice(0, max)}...`
+		: normalized;
+}
+
+function delimiterForPlatform(platform: NodeJS.Platform): string {
+	return platform === "win32" ? ";" : ":";
+}
+
+function splitPathEntries(
+	value: string | undefined,
+	delimiter: string,
+): string[] {
+	if (!value) return [];
+	return value
+		.split(delimiter)
+		.map((entry) => entry.trim())
+		.filter((entry) => entry.length > 0);
+}
+
+function normalizePathEntry(entry: string, platform: NodeJS.Platform): string {
+	const normalized = path.normalize(entry);
+	return platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+
+export function combinePathValuesForPlatform(
+	values: Array<string | undefined>,
+	platform: NodeJS.Platform = process.platform,
+): string {
+	const unique: string[] = [];
+	const seen = new Set<string>();
+	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: NodeJS.ProcessEnv): string {
+	return combinePathValuesForPlatform([env.PATH, env.Path, env.path]);
+}
+
+/** Read live system+user PATH from Windows registry (bypasses stale process.env.PATH). */
+function readWindowsRegistryPath(): string {
+	try {
+		const { execFileSync } =
+			require("node:child_process") as typeof import("node:child_process");
+		const out = execFileSync(
+			"powershell.exe",
+			[
+				"-NoProfile",
+				"-NonInteractive",
+				"-Command",
+				"[System.Environment]::GetEnvironmentVariable('Path','Machine') + ';' + [System.Environment]::GetEnvironmentVariable('Path','User')",
+			],
+			{ timeout: 3000, encoding: "utf8" },
+		);
+		return out.trim();
+	} catch {
+		return "";
+	}
+}
+
+let _liveWindowsPath: string | null = null;
+function getLiveWindowsPath(): string {
+	if (_liveWindowsPath === null) {
+		_liveWindowsPath = readWindowsRegistryPath();
+	}
+	return _liveWindowsPath;
+}
+
+function buildAugmentedPath(basePath?: string): string {
+	const candidates: string[] = [];
+	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 — scan dynamically
+		try {
+			for (const entry of fs.readdirSync(driveRoot)) {
+				if (/^ruby\d/i.test(entry)) {
+					candidates.push(path.join(driveRoot, entry, "bin"));
+				}
+			}
+		} catch {
+			// drive root not readable — skip
+		}
+	}
+
+	// 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<string>();
+	for (const entry of splitPathEntries(effectiveBase, path.delimiter)) {
+		if (!entry) continue;
+		existing.add(normalizePathEntry(entry, process.platform));
+	}
+
+	const toAppend: string[] = [];
+	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)}`;
+}
+
+/**
+ * Find binary in npm global directory
+ * Works around PATH caching issue after npm install -g
+ */
+function _findBinaryInNpmGlobal(command: string): string | undefined {
+	try {
+		// Get npm global prefix
+		const prefix = execSync("npm prefix -g", { encoding: "utf-8" }).trim();
+
+		// On Windows, binaries are directly in the prefix dir
+		// On Unix, they're in prefix/bin
+		const binDir = isWindows ? prefix : path.join(prefix, "bin");
+
+		// Check for Windows variants
+		const candidates = isWindows
+			? [
+					path.join(binDir, `${command}.cmd`),
+					path.join(binDir, `${command}.exe`),
+					path.join(binDir, command),
+				]
+			: [path.join(binDir, command)];
+
+		for (const candidate of candidates) {
+			if (fs.existsSync(candidate)) {
+				return candidate;
+			}
+		}
+		return undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * 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: string): boolean {
+	try {
+		const content = fs.readFileSync(cmdPath, "utf-8");
+		// npm cmd shim pattern: "%~dp0\..\<relpath>" or "%~dp0/<relpath>"
+		// biome-ignore format: regex char-class \- must stay escaped — formatter strips it
+		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: string,
+	args: string[],
+): { command: string; args: string[]; needsShell: boolean } | undefined {
+	// 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");
+		// biome-ignore format: regex char-class \- must stay escaped — formatter strips it
+		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: string,
+	env: NodeJS.ProcessEnv,
+): string | undefined {
+	try {
+		const result = execFileSync(isWindows ? "where" : "which", [command], {
+			encoding: "utf-8",
+			stdio: ["ignore", "pipe", "ignore"],
+			env,
+		})
+			.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: string,
+	args: string[],
+	cwd: string,
+	env: NodeJS.ProcessEnv,
+	needsShell: boolean,
+): ChildProcess {
+	let proc: ChildProcess;
+
+	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: string): string => {
+			// 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(" ")}`;
+		proc = nodeSpawn(shellCommand, [], {
+			cwd,
+			env,
+			stdio: ["pipe", "pipe", "pipe"],
+			detached: false,
+			windowsHide: true,
+			shell: true,
+		});
+	} else {
+		// Use normal spawn without shell
+		proc = nodeSpawn(command, args, {
+			cwd,
+			env,
+			stdio: ["pipe", "pipe", "pipe"],
+			detached: false,
+			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.`,
+		);
+	}
+
+	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 _attachErrorHandler(
+	proc: ChildProcess,
+	context: string,
+	logContext?: {
+		command: string;
+		args: string[];
+		cwd: string;
+		pid?: number;
+	},
+	rejectOnImmediateError?: (err: Error) => void,
+): void {
+	let stderrPreview = "";
+	let closeLogged = false;
+	const onStderr = (chunk: Buffer | string): void => {
+		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) : ""),
+			);
+		}
+
+		// If we have a reject function and this is an immediate spawn error, reject
+		if (
+			rejectOnImmediateError &&
+			(err as NodeJS.ErrnoException).code === "ENOENT"
+		) {
+			rejectOnImmediateError(err);
+		}
+	});
+
+	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
+ */
+function isSimpleCommand(command: string): boolean {
+	return (
+		!path.isAbsolute(command) &&
+		!command.includes(path.sep) &&
+		!command.includes("/")
+	);
+}
+
+function usesShellOnWindows(commandPath: string): boolean {
+	if (!isWindows) return false;
+	return (
+		commandPath.includes(" ") ||
+		/\.(cmd|bat)$/i.test(commandPath) ||
+		!/\.(exe|cmd|bat)$/i.test(commandPath)
+	);
+}
+
+function createLaunchContext(
+	command: string,
+	options: SpawnOptions & { startupFailureWindowMs?: number },
+): {
+	cwd: string;
+	env: NodeJS.ProcessEnv;
+	resolvedCommand: string;
+	isSimple: boolean;
+} {
+	const cwd = String(options.cwd ?? process.cwd());
+	const mergedEnv = { ...process.env, ...options.env };
+	const augmentedPath = buildAugmentedPath(resolvePathValue(mergedEnv));
+	const env: NodeJS.ProcessEnv = {
+		...mergedEnv,
+		PATH: augmentedPath,
+		...(isWindows ? { Path: augmentedPath } : {}),
+	};
+	const simple = isSimpleCommand(command);
+	const isRelativePath =
+		!path.isAbsolute(command) &&
+		(command.includes(path.sep) || command.includes("/"));
+	const explicitCommand = isRelativePath ? path.resolve(cwd, command) : command;
+	const resolvedCommand = simple
+		? (findBinaryOnPath(command, env) ?? explicitCommand)
+		: explicitCommand;
+	return { cwd, env, resolvedCommand, isSimple: simple };
+}
+
+function withNpmGlobalCandidate(command: string, spawnCommand: string): string {
+	if (!isSimpleCommand(command)) return spawnCommand;
+	return _findBinaryInNpmGlobal(command) ?? spawnCommand;
+}
+
+function prevalidateWindowsShim(spawnCommand: string): void {
+	if (!isWindows || !/\.(cmd|bat)$/i.test(spawnCommand)) return;
+	if (isCmdShimValid(spawnCommand)) return;
+	logSessionStart(
+		`lsp cmd-shim-invalid: ${spawnCommand} target missing — skipping candidate`,
+	);
+	throw new Error(
+		`LSP .cmd shim target not found: ${spawnCommand}. The npm package may not be installed.`,
+	);
+}
+
+function applyWindowsPs1Bypass(
+	spawnCommand: string,
+	args: string[],
+	needsShell: boolean,
+): { spawnCommand: string; args: string[]; needsShell: boolean } {
+	if (!isWindows || !/\.ps1$/i.test(spawnCommand)) {
+		return { spawnCommand, args, needsShell };
+	}
+	const bypass = bypassPs1OnWindows(spawnCommand, args);
+	if (!bypass) {
+		logSessionStart(
+			`lsp ps1-bypass: no .cmd or JS entry found for ${spawnCommand}, spawn may hang`,
+		);
+		return { spawnCommand, args, needsShell };
+	}
+	logSessionStart(
+		`lsp ps1-bypass: ${spawnCommand} → ${bypass.command} shell=${bypass.needsShell}`,
+	);
+	return {
+		spawnCommand: bypass.command,
+		args: bypass.args,
+		needsShell: bypass.needsShell,
+	};
+}
+
+function spawnLspWithFallback(
+	command: string,
+	spawnCommand: string,
+	args: string[],
+	cwd: string,
+	env: NodeJS.ProcessEnv,
+	needsShell: boolean,
+): { proc: ChildProcess; spawnCommand: string; needsShell: boolean } {
+	try {
+		const proc = trySpawn(spawnCommand, args, cwd, env, needsShell);
+		return { proc, spawnCommand, needsShell };
+	} catch (err) {
+		if (!isSimpleCommand(command)) throw err;
+		const npmGlobalPath = _findBinaryInNpmGlobal(command);
+		if (!npmGlobalPath || npmGlobalPath === spawnCommand) throw err;
+		const needsShellGlobal = usesShellOnWindows(npmGlobalPath);
+		const proc = trySpawn(npmGlobalPath, args, cwd, env, needsShellGlobal);
+		return {
+			proc,
+			spawnCommand: npmGlobalPath,
+			needsShell: needsShellGlobal,
+		};
+	}
+}
+
+function ensureHealthyProcess(proc: ChildProcess, command: string): void {
+	if (!proc.stdin || !proc.stdout || !proc.stderr) {
+		throw new Error(`Failed to spawn LSP server: ${command}`);
+	}
+	if (proc.exitCode !== null || proc.killed) {
+		throw new Error(
+			`LSP server ${command} exited immediately (code: ${proc.exitCode}). ` +
+				`The binary may be missing or corrupted.`,
+		);
+	}
+}
+
+function formatStartupStderr(stderr: string): string {
+	const normalized = compactLogValue(stderr);
+	if (!normalized) return "";
+	return ` stderr=${normalized}`;
+}
+
+function startupFailureWindow(
+	options: SpawnOptions & { startupFailureWindowMs?: number },
+	needsShell: boolean,
+): number {
+	if (options?.startupFailureWindowMs) return options.startupFailureWindowMs;
+	if (isWindows && needsShell) return WINDOWS_NAV_STARTUP_FAILURE_WINDOW_MS;
+	return DEFAULT_STARTUP_FAILURE_WINDOW_MS;
+}
+
+async function waitForImmediateStartupFailures(
+	proc: ChildProcess,
+	command: string,
+	options: SpawnOptions & { startupFailureWindowMs?: number },
+	needsShell: boolean,
+): Promise<void> {
+	let startupStderr = "";
+	const onStartupStderr = (chunk: Buffer | string): void => {
+		if (startupStderr.length >= 4000) return;
+		startupStderr += chunk.toString();
+	};
+	proc.stderr?.on("data", onStartupStderr);
+	try {
+		await new Promise<void>((resolve, reject) => {
+			let settled = false;
+			const fail = (error: Error) => {
+				if (settled) return;
+				settled = true;
+				reject(error);
+			};
+			const pass = () => {
+				if (settled) return;
+				settled = true;
+				resolve();
+			};
+
+			proc.on("error", (err: Error & { code?: string }) => {
+				if (err.code !== "ENOENT" && err.code !== "EINVAL") return;
+				fail(
+					new Error(
+						`LSP server binary not found: ${command}. Install it or check your PATH.${formatStartupStderr(startupStderr)}`,
+					),
+				);
+			});
+
+			proc.on("exit", (code: number | null) => {
+				if (code === null) return;
+				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.";
+				fail(
+					new Error(
+						`LSP server ${command} exited immediately with code ${code}. ${errorMsg}${formatStartupStderr(startupStderr)}`,
+					),
+				);
+			});
+
+			setTimeout(pass, startupFailureWindow(options, needsShell));
+		});
+	} finally {
+		proc.stderr?.off("data", onStartupStderr);
+	}
+}
+
+export async function launchLSP(
+	command: string,
+	args: string[] = [],
+	options: SpawnOptions & {
+		startupFailureWindowMs?: number;
+	} = {},
+): Promise<LSPProcess> {
+	const context = createLaunchContext(command, options);
+	let spawnCommand = withNpmGlobalCandidate(command, context.resolvedCommand);
+	let needsShell = usesShellOnWindows(spawnCommand);
+	prevalidateWindowsShim(spawnCommand);
+	const bypassed = applyWindowsPs1Bypass(spawnCommand, args, needsShell);
+	spawnCommand = bypassed.spawnCommand;
+	args = bypassed.args;
+	needsShell = bypassed.needsShell;
+
+	const spawned = spawnLspWithFallback(
+		command,
+		spawnCommand,
+		args,
+		context.cwd,
+		context.env,
+		needsShell,
+	);
+	const proc = spawned.proc;
+	spawnCommand = spawned.spawnCommand;
+	needsShell = spawned.needsShell;
+
+	ensureHealthyProcess(proc, command);
+	logSessionStart(
+		`lsp launch: command=${command} resolved=${spawnCommand} args=${JSON.stringify(args)} cwd=${context.cwd} shell=${needsShell ? "true" : "false"} pid=${proc.pid ?? 0}`,
+	);
+	await waitForImmediateStartupFailures(proc, command, options, needsShell);
+
+	_attachErrorHandler(proc, command, {
+		command: spawnCommand,
+		args,
+		cwd: context.cwd,
+		pid: proc.pid ?? 0,
+	});
+
+	return {
+		process: proc,
+		stdin: proc.stdin as NodeJS.WritableStream,
+		stdout: proc.stdout as NodeJS.ReadableStream,
+		stderr: proc.stderr as NodeJS.ReadableStream,
+		pid: proc.pid ?? 0,
+	};
+}
+
+/**
+ * Spawn via package manager (npx/bun)
+ */
+export async function launchViaPackageManager(
+	packageName: string,
+	args: string[] = [],
+	options: SpawnOptions = {},
+): Promise<LSPProcess> {
+	// Prefer bun if available, fall back to npx (use .cmd on Windows)
+	const isWin = process.platform === "win32";
+
+	if (process.env.BUN_INSTALL) {
+		return launchLSP(
+			isWin ? "bun.exe" : "bun",
+			["x", packageName, ...args],
+			options,
+		);
+	}
+
+	// shell:true justified: npx on Windows is npx.cmd — requires shell to execute.
+	if (isWin) {
+		const argsStr = args.map((a) => (a.includes(" ") ? `"${a}"` : a)).join(" ");
+		// --no prevents silent download of uncached packages
+		const shellCommand = `npx --no ${packageName}${argsStr ? ` ${argsStr}` : ""}`;
+
+		const cwd = String(options.cwd ?? process.cwd());
+		const mergedEnv = { ...process.env, ...options.env };
+		const augmentedPath = buildAugmentedPath(resolvePathValue(mergedEnv));
+		const env: NodeJS.ProcessEnv = {
+			...mergedEnv,
+			PATH: augmentedPath,
+			...(isWindows ? { Path: augmentedPath } : {}),
+		};
+
+		const proc = nodeSpawn(shellCommand, [], {
+			cwd,
+			env,
+			stdio: ["pipe", "pipe", "pipe"],
+			detached: false,
+			windowsHide: true,
+			shell: true,
+		});
+
+		if (!proc.stdin || !proc.stdout || !proc.stderr) {
+			throw new Error(`Failed to spawn package manager for: ${packageName}`);
+		}
+
+		// Check for immediate spawn failure on Windows
+		await new Promise<void>((resolve, reject) => {
+			let settled = false;
+
+			proc.on("error", (err: Error & { code?: string }) => {
+				if (!settled && (err.code === "ENOENT" || err.code === "EINVAL")) {
+					settled = true;
+					reject(
+						new Error(
+							`Package manager not found for: ${packageName}. ` +
+								`Install Node.js or check your PATH.`,
+						),
+					);
+				}
+			});
+
+			proc.on("exit", (code: number | null) => {
+				if (!settled && code !== null) {
+					settled = true;
+					reject(
+						new Error(
+							`Package manager exited immediately for: ${packageName} (code: ${code})`,
+						),
+					);
+				}
+			});
+
+			setTimeout(() => {
+				if (!settled) {
+					settled = true;
+					resolve();
+				}
+			}, 50);
+		});
+
+		// Attach permanent error handler
+		_attachErrorHandler(proc, packageName);
+
+		return {
+			process: proc,
+			stdin: proc.stdin,
+			stdout: proc.stdout,
+			stderr: proc.stderr,
+			pid: proc.pid ?? 0,
+		};
+	}
+
+	// --no prevents silent download of uncached packages; user must have
+	// already installed the LSP server via the interactive-install flow.
+	return launchLSP("npx", ["--no", packageName, ...args], options);
+}
+
+/**
+ * Spawn via Node.js directly
+ */
+export async function launchViaNode(
+	scriptPath: string,
+	args: string[] = [],
+	options: SpawnOptions = {},
+): Promise<LSPProcess> {
+	return launchLSP(process.execPath, [scriptPath, ...args], options);
+}
+
+/**
+ * Spawn via Python module
+ */
+export async function launchViaPython(
+	moduleName: string,
+	args: string[] = [],
+	options: SpawnOptions = {},
+): Promise<LSPProcess> {
+	// 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: LSPProcess): Promise<void> {
+	if (handle.process.exitCode !== null || handle.process.signalCode !== null) {
+		return;
+	}
+
+	return new Promise((resolve) => {
+		let settled = false;
+		let forceTimeout: ReturnType<typeof setTimeout> | undefined;
+		let giveUpTimeout: ReturnType<typeof setTimeout> | undefined;
+
+		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 = (): boolean => {
+			if (!isWindows || handle.pid <= 0) 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);
+	});
+}