@loucompanion/forge-bridge 0.1.3-dev.b6be5e7f9668 → 0.1.3-dev.ba293ccf876b

package/dist/session/provider-cli/provider-cli.process.js

@@ -0,0 +1,716 @@
+import { execFile, execFileSync, spawn } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import readline from "node:readline";
+import { promisify } from "node:util";
+import { resolveCursorAgentDirectLaunch } from "../../shared/cursor-agent/cursor-agent.launch.js";
+import { persistHostProcessSupervisorMetadata, resolveHostProcessSupervisedLaunch, terminateHostProcessTree, } from "../../shared/process/host-process-supervisor.js";
+import { buildWindowsLaunchCommand } from "../../shared/process/windows-launch.js";
+const execFileAsync = promisify(execFile);
+// Provider processes can emit many gigabytes over a long-running session. The
+// line handlers stream that output to Forge as it arrives; the completed result
+// only needs a bounded diagnostic tail for failure classification.
+export const PROVIDER_OUTPUT_CAPTURE_LIMIT_CHARS = 128 * 1024;
+const PROVIDER_TERMINAL_EXIT_GRACE_MS = 15_000;
+const allowedProviderParentEnvNames = [
+    "PATH",
+    "HOME",
+    "USERPROFILE",
+    "TMPDIR",
+    "TEMP",
+    "TMP",
+    "LANG"
+];
+const windowsAllowedProviderParentEnvNames = [
+    "SystemRoot",
+    "SystemDrive",
+    "ComSpec",
+    "PATHEXT",
+    "APPDATA",
+    "LOCALAPPDATA",
+    "USERNAME",
+    "USERDOMAIN",
+    "HOMEDRIVE",
+    "HOMEPATH",
+    "ProgramData",
+    "ProgramFiles",
+    "ProgramFiles(x86)",
+    "ProgramW6432",
+    "DOTNET_ROOT",
+    "DOTNET_ROOT(x86)",
+    "DOTNET_CLI_HOME",
+    "NUGET_PACKAGES",
+    "NUGET_HTTP_CACHE_PATH"
+];
+export function buildProviderChildEnvironment(requestEnv, options = {}) {
+    const parentEnv = options.parentEnv ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const env = {};
+    for (const [key, value] of Object.entries(parentEnv)) {
+        if (typeof value === "string" && isAllowedProviderParentEnv(key, platform)) {
+            env[key] = value;
+        }
+    }
+    if (requestEnv) {
+        for (const [key, value] of Object.entries(requestEnv)) {
+            const trimmedKey = key.trim();
+            if (trimmedKey.length > 0) {
+                env[trimmedKey] = value;
+            }
+        }
+    }
+    if (platform === "win32") {
+        normalizeWindowsDotNetEnvironment(env, parentEnv, options.homeDir ?? os.homedir());
+    }
+    normalizeProviderBuildEnvironment(env);
+    return env;
+}
+function normalizeProviderBuildEnvironment(env) {
+    // Provider sessions are long lived and commonly run many dotnet builds. Persistent
+    // MSBuild and Roslyn compiler servers otherwise survive individual commands and can
+    // retain more memory than the active Forge lane. Keep those caches process-scoped by
+    // default on every runner OS; an explicitly supplied request value still wins.
+    setCanonicalProviderBuildEnvironmentValue(env, "DOTNET_CLI_USE_MSBUILD_SERVER", "0");
+    setCanonicalProviderBuildEnvironmentValue(env, "MSBUILDDISABLENODEREUSE", "1");
+    setCanonicalProviderBuildEnvironmentValue(env, "UseSharedCompilation", "false");
+}
+function setCanonicalProviderBuildEnvironmentValue(env, name, value) {
+    // The dotnet CLI uses case-sensitive environment lookup on POSIX, while MSBuild
+    // property names are case-insensitive on every OS. Collapse request aliases to
+    // one canonical key so the explicit value wins without producing ambiguity.
+    const exact = env[name];
+    const alias = Object.entries(env).find(([key, candidate]) => key !== name
+        && key.toLowerCase() === name.toLowerCase()
+        && typeof candidate === "string"
+        && candidate.trim().length > 0)?.[1];
+    const resolved = typeof exact === "string" && exact.trim().length > 0
+        ? exact
+        : alias ?? value;
+    for (const key of Object.keys(env)) {
+        if (key !== name && key.toLowerCase() === name.toLowerCase()) {
+            delete env[key];
+        }
+    }
+    env[name] = resolved;
+}
+function isAllowedProviderParentEnv(key, platform = process.platform) {
+    return isAllowedProviderParentEnvName(key, allowedProviderParentEnvNames)
+        || key.toUpperCase().startsWith("LC_")
+        || (platform === "win32" && isAllowedProviderParentEnvName(key, windowsAllowedProviderParentEnvNames));
+}
+function isAllowedProviderParentEnvName(key, allowedNames) {
+    return allowedNames.some((allowed) => allowed.toLowerCase() === key.toLowerCase());
+}
+function normalizeWindowsDotNetEnvironment(env, parentEnv, homeDir) {
+    const systemRoot = readEnvironmentValue(env, "SystemRoot") ?? readEnvironmentValue(parentEnv, "SystemRoot") ?? "C:\\Windows";
+    const systemDrive = path.win32.parse(systemRoot).root.replace(/\\$/, "") || "C:";
+    setEnvironmentValueIfMissing(env, "SystemRoot", systemRoot);
+    setEnvironmentValueIfMissing(env, "SystemDrive", readEnvironmentValue(parentEnv, "SystemDrive") ?? systemDrive);
+    setEnvironmentValueIfMissing(env, "ComSpec", readEnvironmentValue(parentEnv, "ComSpec") ?? path.win32.join(systemRoot, "System32", "cmd.exe"));
+    setEnvironmentValueIfMissing(env, "PATHEXT", readEnvironmentValue(parentEnv, "PATHEXT") ?? ".COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.MSC;.CPL");
+    const userProfile = resolveWindowsUserProfile(env, parentEnv, homeDir);
+    if (userProfile) {
+        setEnvironmentValueIfMissing(env, "USERPROFILE", userProfile);
+        setEnvironmentValueIfMissing(env, "HOME", userProfile);
+        setEnvironmentValueIfMissing(env, "DOTNET_CLI_HOME", userProfile);
+        setEnvironmentValueIfMissing(env, "NUGET_PACKAGES", path.win32.join(userProfile, ".nuget", "packages"));
+        const parsed = path.win32.parse(userProfile);
+        if (parsed.root) {
+            setEnvironmentValueIfMissing(env, "HOMEDRIVE", parsed.root.replace(/\\$/, ""));
+            setEnvironmentValueIfMissing(env, "HOMEPATH", userProfile.slice(parsed.root.length - (parsed.root.endsWith("\\") ? 1 : 0)) || "\\");
+        }
+    }
+    const appData = readEnvironmentValue(env, "APPDATA")
+        ?? readEnvironmentValue(parentEnv, "APPDATA")
+        ?? (userProfile ? path.win32.join(userProfile, "AppData", "Roaming") : undefined);
+    const localAppData = readEnvironmentValue(env, "LOCALAPPDATA")
+        ?? readEnvironmentValue(parentEnv, "LOCALAPPDATA")
+        ?? (userProfile ? path.win32.join(userProfile, "AppData", "Local") : undefined);
+    if (appData) {
+        setEnvironmentValueIfMissing(env, "APPDATA", appData);
+    }
+    if (localAppData) {
+        setEnvironmentValueIfMissing(env, "LOCALAPPDATA", localAppData);
+        setEnvironmentValueIfMissing(env, "NUGET_HTTP_CACHE_PATH", path.win32.join(localAppData, "NuGet", "v3-cache"));
+    }
+    setEnvironmentValueIfMissing(env, "DOTNET_NOLOGO", "1");
+    setEnvironmentValueIfMissing(env, "DOTNET_CLI_TELEMETRY_OPTOUT", "1");
+    setEnvironmentValueIfMissing(env, "DOTNET_SKIP_FIRST_TIME_EXPERIENCE", "1");
+    setEnvironmentValueIfMissing(env, "NUGET_XMLDOC_MODE", "skip");
+}
+function resolveWindowsUserProfile(env, parentEnv, homeDir) {
+    const existing = readEnvironmentValue(env, "USERPROFILE") ?? readEnvironmentValue(parentEnv, "USERPROFILE");
+    if (existing) {
+        return existing;
+    }
+    const home = readEnvironmentValue(env, "HOME") ?? readEnvironmentValue(parentEnv, "HOME");
+    if (home && path.win32.isAbsolute(home)) {
+        return home;
+    }
+    const homeDrive = readEnvironmentValue(env, "HOMEDRIVE") ?? readEnvironmentValue(parentEnv, "HOMEDRIVE");
+    const homePath = readEnvironmentValue(env, "HOMEPATH") ?? readEnvironmentValue(parentEnv, "HOMEPATH");
+    if (homeDrive && homePath) {
+        return `${homeDrive}${homePath}`;
+    }
+    if (homeDir && path.win32.isAbsolute(homeDir)) {
+        return homeDir;
+    }
+    const systemDrive = readEnvironmentValue(env, "SystemDrive") ?? readEnvironmentValue(parentEnv, "SystemDrive") ?? "C:";
+    const username = readEnvironmentValue(env, "USERNAME") ?? readEnvironmentValue(parentEnv, "USERNAME");
+    return username ? path.win32.join(systemDrive, "Users", username) : undefined;
+}
+function readEnvironmentValue(env, name) {
+    const entry = Object.entries(env).find(([key]) => key.toLowerCase() === name.toLowerCase());
+    const value = entry?.[1];
+    return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+function setEnvironmentValueIfMissing(env, name, value) {
+    if (readEnvironmentValue(env, name)) {
+        return;
+    }
+    env[name] = value;
+}
+export class StreamingProviderProcessRunner {
+    terminalExitGraceMs;
+    constructor(terminalExitGraceMs = PROVIDER_TERMINAL_EXIT_GRACE_MS) {
+        this.terminalExitGraceMs = terminalExitGraceMs;
+    }
+    async run(request, handlers = {}, signal) {
+        const providerLaunch = await resolveProviderProcessLaunch(request.command, request.args);
+        const supervisedLaunch = resolveHostProcessSupervisedLaunch(request, providerLaunch.command, providerLaunch.args);
+        // An unsupervised Unix provider still gets a dedicated process group so a
+        // cancellation can stop descendants instead of only the CLI root.
+        const launch = supervisedLaunch ?? { ...providerLaunch, detached: process.platform !== "win32" };
+        return await new Promise((resolve, reject) => {
+            const rootCreatedAt = new Date().toISOString();
+            const child = spawn(launch.command, launch.args, {
+                cwd: request.cwd,
+                env: buildProviderChildEnvironment(request.env),
+                stdio: [request.stdin === undefined ? "ignore" : "pipe", "pipe", "pipe"],
+                windowsHide: true,
+                detached: launch.detached,
+            });
+            const memoryObserver = supervisedLaunch
+                ? new HostProcessTreeMemoryObserver(supervisedLaunch, child.pid ?? 0)
+                : null;
+            let termination = null;
+            const terminate = () => {
+                termination ??= terminateHostProcessTree(child, supervisedLaunch);
+                return termination;
+            };
+            const childStdout = child.stdout;
+            const childStderr = child.stderr;
+            if (!childStdout || !childStderr) {
+                const pipeError = new Error("Provider process stdout/stderr streams were not piped.");
+                void terminate().then(() => reject(pipeError), terminationError => reject(new AggregateError([pipeError, terminationError], "Provider launch failed and its process tree could not be proven stopped.")));
+                return;
+            }
+            const stdout = new BoundedOutputTail(PROVIDER_OUTPUT_CAPTURE_LIMIT_CHARS);
+            const stderr = new BoundedOutputTail(PROVIDER_OUTPUT_CAPTURE_LIMIT_CHARS);
+            let settled = false;
+            let closed = false;
+            let cancellationRequested = false;
+            let terminalTerminationStarted = false;
+            let terminalExitTimer = null;
+            let readiness = null;
+            const cleanup = () => {
+                if (terminalExitTimer) {
+                    clearTimeout(terminalExitTimer);
+                    terminalExitTimer = null;
+                }
+                signal?.removeEventListener("abort", abort);
+            };
+            const fail = (error) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                cleanup();
+                // Do not release the caller's reservation/worktree/port ownership until
+                // descendant termination has completed (or failed with explicit proof).
+                void terminate().then(() => reject(error), terminationError => reject(new AggregateError([error, terminationError], "Provider process failed and its process tree could not be proven stopped.")));
+            };
+            const abort = () => {
+                cancellationRequested = true;
+                // Cancellation is not a launch failure when the supervised tree can be
+                // proven stopped. Let the close handler settle the command after exact
+                // termination; only a failed termination proof rejects the run.
+                void terminate().catch(fail);
+            };
+            if (signal?.aborted) {
+                abort();
+            }
+            else {
+                signal?.addEventListener("abort", abort, { once: true });
+            }
+            child.on("error", fail);
+            child.once("spawn", () => {
+                readiness = (async () => {
+                    const providerReady = supervisedLaunch?.strategy === "windows_job_object"
+                        ? await waitForWindowsProviderReady(supervisedLaunch, signal, () => closed)
+                        : undefined;
+                    if (supervisedLaunch) {
+                        persistHostProcessSupervisorMetadata(supervisedLaunch, request, child.pid ?? 0, rootCreatedAt, providerReady);
+                    }
+                    await handlers.onStarted?.();
+                    if (supervisedLaunch?.strategy === "windows_job_object") {
+                        grantWindowsProviderStart(supervisedLaunch);
+                    }
+                })();
+                void readiness.catch(error => {
+                    if (!closed && !signal?.aborted)
+                        fail(error);
+                });
+            });
+            const writeProviderInput = () => {
+                if (request.stdin === undefined)
+                    return;
+                if (!child.stdin) {
+                    void terminate();
+                    fail(new Error("Provider process stdin stream was not piped."));
+                    return;
+                }
+                child.stdin.on("error", (error) => {
+                    void terminate();
+                    fail(error);
+                });
+                child.stdin.end(request.stdin, "utf8");
+            };
+            if (request.stdin !== undefined) {
+                if (supervisedLaunch?.strategy === "windows_job_object") {
+                    // The outer supervisor must receive stdin before it can launch the
+                    // inner provider. Its start-grant file prevents prompt delivery.
+                    writeProviderInput();
+                }
+                else {
+                    child.once("spawn", () => {
+                        void readiness?.then(writeProviderInput).catch(fail);
+                    });
+                }
+            }
+            const readers = [
+                readProcessLines(childStdout, (line) => {
+                    if (request.captureOutput !== false)
+                        stdout.appendLine(line);
+                    const handled = handlers.onStdoutLine?.(line);
+                    if (!terminalExitTimer && isProviderTerminalSuccess(line)) {
+                        terminalExitTimer = setTimeout(() => {
+                            if (closed || settled || cancellationRequested)
+                                return;
+                            terminalTerminationStarted = true;
+                            void terminate().catch(fail);
+                        }, this.terminalExitGraceMs);
+                        terminalExitTimer.unref?.();
+                    }
+                    return handled;
+                }),
+                readProcessLines(childStderr, (line) => {
+                    if (request.captureOutput !== false)
+                        stderr.appendLine(line);
+                    return handlers.onStderrLine?.(line);
+                })
+            ];
+            for (const reader of readers) {
+                void reader.catch(fail);
+            }
+            child.on("close", (code) => {
+                closed = true;
+                Promise.allSettled(readers).then(async (readerResults) => {
+                    await readiness?.catch(() => undefined);
+                    const rejected = readerResults.find((result) => result.status === "rejected");
+                    if (rejected?.status === "rejected") {
+                        fail(rejected.reason);
+                        return;
+                    }
+                    if (settled) {
+                        return;
+                    }
+                    try {
+                        memoryObserver?.sample();
+                        if (supervisedLaunch?.strategy === "unix_process_group" || !supervisedLaunch) {
+                            await terminate();
+                        }
+                        else if (termination) {
+                            await termination;
+                        }
+                    }
+                    catch (error) {
+                        fail(error);
+                        return;
+                    }
+                    settled = true;
+                    cleanup();
+                    const memory = memoryObserver?.complete();
+                    resolve({
+                        // A structured terminal-success event is the provider protocol's
+                        // authoritative completion signal. If the CLI stays resident after
+                        // that event, terminate the supervised tree after a short grace
+                        // period and preserve the successful handoff so the existing
+                        // artifact, commit, and publication gates can run.
+                        exitCode: terminalTerminationStarted && !cancellationRequested ? 0 : code ?? 1,
+                        stdout: stdout.toString(),
+                        stderr: stderr.toString(),
+                        ...(memory ?? {}),
+                    });
+                }).catch(fail);
+            });
+        });
+    }
+}
+function isProviderTerminalSuccess(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("{"))
+        return false;
+    try {
+        const event = JSON.parse(trimmed);
+        return event.type === "turn.completed"
+            || (event.type === "result" && event.subtype === "success" && event.is_error !== true);
+    }
+    catch {
+        return false;
+    }
+}
+class HostProcessTreeMemoryObserver {
+    launch;
+    processGroupId;
+    peakMemoryBytes = 0;
+    sampleCount = 0;
+    observedAt = null;
+    timer;
+    constructor(launch, processGroupId) {
+        this.launch = launch;
+        this.processGroupId = processGroupId;
+        if (launch.strategy === "unix_process_group" && processGroupId > 0) {
+            this.sample();
+            this.timer = setInterval(() => this.sample(), 1_000);
+            this.timer.unref?.();
+        }
+        else {
+            this.timer = null;
+        }
+    }
+    sample() {
+        if (this.launch.strategy !== "unix_process_group" || this.processGroupId <= 0)
+            return;
+        const bytes = processGroupResidentMemoryBytes(this.processGroupId);
+        if (bytes === null)
+            return;
+        this.sampleCount += 1;
+        this.peakMemoryBytes = Math.max(this.peakMemoryBytes, bytes);
+        this.observedAt = new Date().toISOString();
+    }
+    complete() {
+        if (this.timer)
+            clearInterval(this.timer);
+        if (this.launch.strategy === "windows_job_object") {
+            return readWindowsJobMemoryTelemetry(this.launch.memoryTelemetryPath);
+        }
+        if (this.peakMemoryBytes <= 0 || this.sampleCount <= 0 || !this.observedAt)
+            return undefined;
+        return {
+            peakMemoryBytes: this.peakMemoryBytes,
+            memorySampleCount: this.sampleCount,
+            memorySource: process.platform === "linux"
+                ? "linux_process_group_rss"
+                : "unix_process_group_rss",
+            memoryObservedAt: this.observedAt,
+        };
+    }
+}
+/** Returns aggregate resident bytes for the exact supervised Unix process group. */
+export function processGroupResidentMemoryBytes(processGroupId, platform = process.platform, procRoot = "/proc") {
+    if (!Number.isSafeInteger(processGroupId) || processGroupId <= 0)
+        return null;
+    if (platform === "linux") {
+        let totalKilobytes = 0;
+        let matched = 0;
+        try {
+            for (const entry of fs.readdirSync(procRoot, { withFileTypes: true })) {
+                if (!entry.isDirectory() || !/^\d+$/u.test(entry.name))
+                    continue;
+                try {
+                    const stat = fs.readFileSync(path.join(procRoot, entry.name, "stat"), "utf8");
+                    const close = stat.lastIndexOf(")");
+                    const fields = close >= 0 ? stat.slice(close + 2).trim().split(/\s+/u) : [];
+                    if (Number.parseInt(fields[2] ?? "", 10) !== processGroupId)
+                        continue;
+                    const status = fs.readFileSync(path.join(procRoot, entry.name, "status"), "utf8");
+                    const rss = /^VmRSS:\s+(\d+)\s+kB$/mu.exec(status);
+                    if (!rss)
+                        continue;
+                    totalKilobytes += Number.parseInt(rss[1], 10);
+                    matched += 1;
+                }
+                catch {
+                    // Processes can exit between the directory, stat, and status reads.
+                }
+            }
+            return matched > 0 ? totalKilobytes * 1024 : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    if (platform !== "win32") {
+        try {
+            const output = execFileSync("ps", ["-axo", "pgid=,rss="], {
+                encoding: "utf8",
+                timeout: 5_000,
+                stdio: ["ignore", "pipe", "ignore"],
+            });
+            let totalKilobytes = 0;
+            let matched = 0;
+            for (const line of output.split(/\r?\n/u)) {
+                const fields = line.trim().split(/\s+/u);
+                if (Number.parseInt(fields[0] ?? "", 10) !== processGroupId)
+                    continue;
+                const rss = Number.parseInt(fields[1] ?? "", 10);
+                if (!Number.isSafeInteger(rss) || rss < 0)
+                    continue;
+                totalKilobytes += rss;
+                matched += 1;
+            }
+            return matched > 0 ? totalKilobytes * 1024 : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    return null;
+}
+function readWindowsJobMemoryTelemetry(target) {
+    if (!target)
+        return undefined;
+    try {
+        const value = JSON.parse(fs.readFileSync(target, "utf8"));
+        const peakMemoryBytes = value.peakMemoryBytes;
+        const sampleCount = value.sampleCount;
+        const source = value.source;
+        const observedAt = value.observedAt;
+        if (!Number.isSafeInteger(peakMemoryBytes) || peakMemoryBytes <= 0
+            || !Number.isSafeInteger(sampleCount) || sampleCount <= 0
+            || typeof source !== "string" || source.length === 0
+            || typeof observedAt !== "string" || !Number.isFinite(Date.parse(observedAt))) {
+            return undefined;
+        }
+        return {
+            peakMemoryBytes: peakMemoryBytes,
+            memorySampleCount: sampleCount,
+            memorySource: source,
+            memoryObservedAt: observedAt,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+class BoundedOutputTail {
+    maxChars;
+    value = "";
+    constructor(maxChars) {
+        this.maxChars = maxChars;
+    }
+    appendLine(line) {
+        const chunk = `${line}\n`;
+        if (chunk.length >= this.maxChars) {
+            this.value = chunk.slice(-this.maxChars);
+            return;
+        }
+        const retainedPrefixChars = this.maxChars - chunk.length;
+        this.value = `${this.value.slice(-retainedPrefixChars)}${chunk}`;
+    }
+    toString() {
+        return this.value;
+    }
+}
+async function resolveProviderProcessLaunch(command, args) {
+    if (process.platform !== "win32") {
+        return { command, args };
+    }
+    const cursorDirect = await resolveCursorAgentDirectLaunch(command, args);
+    if (cursorDirect) {
+        return cursorDirect;
+    }
+    const resolved = await resolveWindowsCommand(command);
+    if (!resolved) {
+        return { command, args };
+    }
+    return resolveCodexNpmDirectLaunch(resolved, args)
+        ?? resolvePackageManagerDirectLaunch(resolved, args)
+        ?? buildWindowsLaunchCommand(resolved, args);
+}
+function grantWindowsProviderStart(launch) {
+    if (!launch.startGrantPath) {
+        throw new Error("host_process_supervisor_invalid: Windows provider start-grant path was not assigned.");
+    }
+    fs.writeFileSync(launch.startGrantPath, "granted\n", {
+        encoding: "utf8",
+        flag: "wx",
+        mode: 0o600,
+    });
+}
+async function waitForWindowsProviderReady(launch, signal, isClosed) {
+    const readyPath = launch.readyPath;
+    if (!readyPath) {
+        throw new Error("host_process_supervisor_invalid: Windows provider-ready path was not assigned.");
+    }
+    while (true) {
+        try {
+            const parsed = JSON.parse(await fs.promises.readFile(readyPath, "utf8"));
+            if (parsed.schemaVersion !== 1
+                || parsed.supervisorId !== launch.supervisorId
+                || !Number.isSafeInteger(parsed.rootPid)
+                || (parsed.rootPid ?? 0) <= 0
+                || typeof parsed.rootIdentity !== "string"
+                || !/^win32:\d+$/u.test(parsed.rootIdentity)
+                || !Number.isSafeInteger(parsed.providerPid)
+                || (parsed.providerPid ?? 0) <= 0
+                || typeof parsed.providerCreatedAt !== "string"
+                || Number.isNaN(Date.parse(parsed.providerCreatedAt))
+                || (parsed.providerIdentity !== undefined
+                    && (typeof parsed.providerIdentity !== "string" || !/^win32:\d+$/u.test(parsed.providerIdentity)))
+                || !Number.isSafeInteger(parsed.startAttempt)
+                || (parsed.startAttempt ?? 0) < 1) {
+                throw new Error("host_process_supervisor_invalid: provider-ready receipt was invalid.");
+            }
+            return parsed;
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        if (isClosed()) {
+            throw new Error("host_process_supervisor_start_failed: supervisor exited before the provider became ready.");
+        }
+        if (signal?.aborted) {
+            throw signal.reason instanceof Error ? signal.reason : new Error("Provider process launch was aborted.");
+        }
+        await new Promise(resolve => setTimeout(resolve, 25));
+    }
+}
+export function resolveCodexNpmDirectLaunch(commandPath, args) {
+    const extension = path.extname(commandPath).toLowerCase();
+    if ((extension !== ".cmd" && extension !== ".ps1")
+        || path.basename(commandPath, extension).toLowerCase() !== "codex") {
+        return null;
+    }
+    const entryPoint = path.join(path.dirname(commandPath), "node_modules", "@openai", "codex", "bin", "codex.js");
+    return fs.existsSync(entryPoint)
+        ? { command: process.execPath, args: [entryPoint, ...args] }
+        : null;
+}
+/**
+ * Avoids cmd.exe's nested-quote handling for package-manager shims. That
+ * quoting loses executable paths containing spaces after the command is
+ * wrapped by the Windows Job Object supervisor.
+ */
+export function resolvePackageManagerDirectLaunch(commandPath, args) {
+    const extension = path.extname(commandPath).toLowerCase();
+    if (extension !== ".cmd" && extension !== ".ps1")
+        return null;
+    const packageManager = path.basename(commandPath, extension).toLowerCase();
+    if (!["corepack", "npm", "npx", "pnpm", "pnpx", "yarn", "yarnpkg"].includes(packageManager))
+        return null;
+    const root = path.dirname(commandPath);
+    const candidates = [
+        path.join(root, "node_modules", "corepack", "dist", packageManager === "corepack" ? "corepack.js" : `${packageManager}.js`),
+        ...(packageManager === "npm" || packageManager === "npx"
+            ? [path.join(root, "node_modules", "npm", "bin", `${packageManager}-cli.js`)]
+            : []),
+        ...(packageManager === "pnpm" || packageManager === "pnpx"
+            ? [path.join(root, "node_modules", "pnpm", "bin", `${packageManager}.cjs`)]
+            : []),
+        ...(packageManager === "yarn" || packageManager === "yarnpkg"
+            ? [path.join(root, "node_modules", "yarn", "bin", "yarn.js")]
+            : []),
+    ];
+    const entryPoint = candidates.find(candidate => fs.existsSync(candidate));
+    if (!entryPoint)
+        return null;
+    const adjacentNode = path.join(root, "node.exe");
+    return {
+        command: fs.existsSync(adjacentNode) ? adjacentNode : process.execPath,
+        args: [entryPoint, ...args],
+    };
+}
+async function resolveWindowsCommand(command) {
+    if (path.isAbsolute(command)) {
+        return command;
+    }
+    const resolvedFromPath = resolveWindowsCommandFromPath(command);
+    if (resolvedFromPath) {
+        return resolvedFromPath;
+    }
+    try {
+        const result = await execFileAsync("where.exe", [command], { timeout: 2000 });
+        return chooseWindowsCommandCandidate(result.stdout.split(/\r?\n/));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolves Windows commands without spawning where.exe. Runtime launches can
+ * happen while the machine is under enough process pressure for where.exe to
+ * miss its timeout; returning the unresolved package-manager name in that case
+ * makes Node fall back to a shell shim that cannot survive Job Object wrapping.
+ */
+export function resolveWindowsCommandFromPath(command, pathValue = process.env.PATH ?? "", pathExtValue = process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD") {
+    if (!command || path.isAbsolute(command) || command.includes("/") || command.includes("\\")) {
+        return null;
+    }
+    const hasExtension = path.extname(command).length > 0;
+    const extensions = hasExtension
+        ? [""]
+        : [...new Set([
+                "",
+                ".exe",
+                ".ps1",
+                ".cmd",
+                ".bat",
+                ...pathExtValue.split(";").map(value => value.trim().toLowerCase()).filter(Boolean),
+            ])];
+    for (const rawDirectory of pathValue.split(path.delimiter)) {
+        const directory = rawDirectory.trim().replace(/^"|"$/gu, "");
+        if (!directory)
+            continue;
+        const candidates = [];
+        for (const extension of extensions) {
+            const candidate = path.join(directory, `${command}${extension}`);
+            if (fs.existsSync(candidate))
+                candidates.push(candidate);
+        }
+        const resolved = chooseWindowsCommandCandidate(candidates);
+        if (resolved)
+            return resolved;
+    }
+    return null;
+}
+export function chooseWindowsCommandCandidate(candidates) {
+    const normalized = candidates
+        .map((candidate) => candidate.trim())
+        .filter((candidate) => candidate.length > 0);
+    if (normalized.length === 0) {
+        return null;
+    }
+    const preferredExtensions = [".exe", ".ps1", ".cmd", ".bat", ""];
+    for (const extension of preferredExtensions) {
+        const candidate = normalized.find((entry) => path.extname(entry).toLowerCase() === extension);
+        if (candidate) {
+            return candidate;
+        }
+    }
+    return normalized[0];
+}
+async function readProcessLines(stream, onLine) {
+    const reader = readline.createInterface({ input: stream });
+    try {
+        for await (const line of reader) {
+            await onLine(line);
+        }
+    }
+    finally {
+        reader.close();
+    }
+}