@loucompanion/forge-bridge 0.1.3-dev.fbe15023cdfe → 0.1.4-dev.1ff37038366e

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

@@ -1,4 +1,5 @@
-import { execFile, spawn } from "node:child_process";
+import { execFile, execFileSync, spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
@@ -7,7 +8,138 @@ 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";
+import { assertHostDatabaseCapabilityBoundary } from "../../runtime/host-database-capability-boundary.js";
+import { ForgeFailureError } from "../session.types.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 maximumRecoverableCodexModelsCacheBytes = 16 * 1024 * 1024;
+/** Recovery must wrap the attempt coordinator, never its raw OS runner. Each
+ * relaunch needs a new fenced child generation and exclusive launch files. */
+export function recoveringProviderProcessRunner(inner) {
+    return new CodexResumeRecoveringProcessRunner(new CodexModelsCacheRecoveringProcessRunner(inner));
+}
+/**
+ * Codex Desktop and an independently installed Codex CLI can briefly disagree
+ * about the shared models-cache schema during a rolling upgrade. Recover only
+ * that exact failure by quarantining the bounded cache file and retrying once;
+ * auth, config, sessions, and every other CODEX_HOME entry remain untouched.
+ */
+export class CodexModelsCacheRecoveringProcessRunner {
+    inner;
+    constructor(inner) {
+        this.inner = inner;
+    }
+    async run(request, handlers, signal) {
+        const first = await this.inner.run(request, handlers, signal);
+        if (first.exitCode === 0
+            || signal?.aborted
+            || !isCodexCommand(request.command)
+            || !isCodexModelsCacheSchemaFailure(first)) {
+            return first;
+        }
+        const recovered = await quarantineIncompatibleCodexModelsCache(request.env).catch(() => false);
+        if (!recovered || signal?.aborted)
+            return first;
+        return await this.inner.run(request, handlers, signal);
+    }
+}
+/**
+ * Some Codex CLI builds can start new turns but cannot resume an older thread
+ * because the backing app does not implement the paginated thread lookup RPC.
+ * Preserve the prepared worktree and prompt, then retry once as a fresh turn.
+ */
+export class CodexResumeRecoveringProcessRunner {
+    inner;
+    constructor(inner) {
+        this.inner = inner;
+    }
+    async run(request, handlers, signal) {
+        const first = await this.inner.run(request, handlers, signal);
+        if (first.exitCode === 0
+            || signal?.aborted
+            || !isCodexCommand(request.command)
+            || !isRecoverableCodexResumeFailure(request.command, first)) {
+            return first;
+        }
+        const fallback = codexFreshTurnRequest(request);
+        return fallback ? await this.inner.run(fallback, handlers, signal) : first;
+    }
+}
+function isRecoverableCodexResumeFailure(command, result) {
+    const output = `${result.stderr}\n${result.stdout}`.toLowerCase();
+    return (output.includes("thread/resume failed")
+        && output.includes("paginated_threads is not supported yet"))
+        || isTransientCodexProviderNotFoundFailure(command, result);
+}
+/**
+ * Recognizes the exact nonzero Codex service response at the provider-process
+ * boundary. Provider stdout is deliberately excluded because it can contain
+ * arbitrary tool/command output and therefore cannot mint retry authority.
+ */
+export function isTransientCodexProviderNotFoundFailure(command, result) {
+    if (result.exitCode === 0 || !isCodexCommand(command))
+        return false;
+    return result.stderr
+        .split(/\r?\n/u)
+        .map(line => line.trim().toLowerCase())
+        .some(line => line === "not found: status code '404'"
+        || line === 'not found: status code "404"');
+}
+function codexFreshTurnRequest(request) {
+    const args = [...request.args];
+    const resumeIndex = args.indexOf("resume");
+    if (resumeIndex < 0 || args.length < 2)
+        return null;
+    // buildProviderCliCommand always places the thread id immediately before
+    // the prompt. Remove it before moving exec-level --cd back out of the
+    // resume subcommand shape.
+    args.splice(args.length - 2, 1);
+    args.splice(resumeIndex, 1);
+    const cdIndex = args.indexOf("--cd");
+    if (cdIndex >= 0 && cdIndex + 1 < args.length) {
+        const cd = args.splice(cdIndex, 2);
+        args.splice(args.length - 1, 0, ...cd);
+    }
+    return { ...request, args };
+}
+function isCodexCommand(command) {
+    return path.parse(command).name.toLowerCase() === "codex";
+}
+function isCodexModelsCacheSchemaFailure(result) {
+    const output = `${result.stderr}\n${result.stdout}`.toLowerCase();
+    return output.includes("base_instructions")
+        && output.includes("missing field")
+        && (output.includes("models_cache") || output.includes("models cache") || output.includes("model cache"));
+}
+async function quarantineIncompatibleCodexModelsCache(requestEnv) {
+    const configuredHome = readEnvironmentValue(requestEnv ?? {}, "CODEX_HOME")
+        ?? readEnvironmentValue(process.env, "CODEX_HOME")
+        ?? readEnvironmentValue(process.env, "FORGE_CODEX_HOME");
+    const codexHome = path.resolve(configuredHome ?? path.join(os.homedir(), ".codex"));
+    if (!path.isAbsolute(codexHome) || codexHome === path.parse(codexHome).root)
+        return false;
+    const cachePath = path.join(codexHome, "models_cache.json");
+    const cacheStat = await fs.promises.lstat(cachePath).catch(error => {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    });
+    if (!cacheStat
+        || !cacheStat.isFile()
+        || cacheStat.isSymbolicLink()
+        || cacheStat.nlink !== 1
+        || cacheStat.size <= 0
+        || cacheStat.size > maximumRecoverableCodexModelsCacheBytes) {
+        return false;
+    }
+    const quarantinePath = path.join(codexHome, `models_cache.forge-incompatible-${Date.now()}-${randomUUID()}.json`);
+    await fs.promises.rename(cachePath, quarantinePath);
+    return true;
+}
 const allowedProviderParentEnvNames = [
     "PATH",
     "HOME",
@@ -15,7 +147,8 @@ const allowedProviderParentEnvNames = [
     "TMPDIR",
     "TEMP",
     "TMP",
-    "LANG"
+    "LANG",
+    "CLAUDE_CONFIG_DIR"
 ];
 const windowsAllowedProviderParentEnvNames = [
     "SystemRoot",
@@ -36,7 +169,8 @@ const windowsAllowedProviderParentEnvNames = [
     "DOTNET_ROOT(x86)",
     "DOTNET_CLI_HOME",
     "NUGET_PACKAGES",
-    "NUGET_HTTP_CACHE_PATH"
+    "NUGET_HTTP_CACHE_PATH",
+    "CLAUDE_CODE_GIT_BASH_PATH"
 ];
 export function buildProviderChildEnvironment(requestEnv, options = {}) {
     const parentEnv = options.parentEnv ?? process.env;
@@ -58,8 +192,37 @@ export function buildProviderChildEnvironment(requestEnv, options = {}) {
     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_")
@@ -75,6 +238,17 @@ function normalizeWindowsDotNetEnvironment(env, parentEnv, homeDir) {
     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 resolvedSystemDrive = readEnvironmentValue(env, "SystemDrive") ?? systemDrive;
+    const defaultProgramFiles = path.win32.join(`${resolvedSystemDrive}\\`, "Program Files");
+    const defaultProgramFilesX86 = path.win32.join(`${resolvedSystemDrive}\\`, "Program Files (x86)");
+    const defaultProgramData = path.win32.join(`${resolvedSystemDrive}\\`, "ProgramData");
+    const programFiles = readEnvironmentValue(env, "ProgramFiles")
+        ?? readEnvironmentValue(parentEnv, "ProgramFiles")
+        ?? defaultProgramFiles;
+    setEnvironmentValueIfMissing(env, "ProgramFiles", programFiles);
+    setEnvironmentValueIfMissing(env, "ProgramW6432", readEnvironmentValue(parentEnv, "ProgramW6432") ?? defaultProgramFiles);
+    setEnvironmentValueIfMissing(env, "ProgramFiles(x86)", readEnvironmentValue(parentEnv, "ProgramFiles(x86)") ?? defaultProgramFilesX86);
+    setEnvironmentValueIfMissing(env, "ProgramData", readEnvironmentValue(parentEnv, "ProgramData") ?? defaultProgramData);
     const userProfile = resolveWindowsUserProfile(env, parentEnv, homeDir);
     if (userProfile) {
         setEnvironmentValueIfMissing(env, "USERPROFILE", userProfile);
@@ -138,10 +312,17 @@ function setEnvironmentValueIfMissing(env, name, value) {
     env[name] = value;
 }
 export class StreamingProviderProcessRunner {
+    terminalExitGraceMs;
+    constructor(terminalExitGraceMs = PROVIDER_TERMINAL_EXIT_GRACE_MS) {
+        this.terminalExitGraceMs = terminalExitGraceMs;
+    }
     async run(request, handlers = {}, signal) {
+        assertHostDatabaseCapabilityBoundary();
         const providerLaunch = await resolveProviderProcessLaunch(request.command, request.args);
         const supervisedLaunch = resolveHostProcessSupervisedLaunch(request, providerLaunch.command, providerLaunch.args);
-        const launch = supervisedLaunch ?? { ...providerLaunch, detached: false };
+        // 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, {
@@ -151,6 +332,9 @@ export class StreamingProviderProcessRunner {
                 windowsHide: true,
                 detached: launch.detached,
             });
+            const memoryObserver = supervisedLaunch
+                ? new HostProcessTreeMemoryObserver(supervisedLaunch, child.pid ?? 0)
+                : null;
             let termination = null;
             const terminate = () => {
                 termination ??= terminateHostProcessTree(child, supervisedLaunch);
@@ -159,16 +343,23 @@ export class StreamingProviderProcessRunner {
             const childStdout = child.stdout;
             const childStderr = child.stderr;
             if (!childStdout || !childStderr) {
-                void terminate();
-                reject(new Error("Provider process stdout/stderr streams were not piped."));
+                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;
             }
-            let stdout = "";
-            let stderr = "";
+            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) => {
@@ -177,10 +368,12 @@ export class StreamingProviderProcessRunner {
                 }
                 settled = true;
                 cleanup();
-                void terminate().catch(() => undefined);
-                reject(error);
+                // 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.
@@ -240,15 +433,28 @@ export class StreamingProviderProcessRunner {
             const readers = [
                 readProcessLines(childStdout, (line) => {
                     if (request.captureOutput !== false)
-                        stdout += `${line}\n`;
-                    return handlers.onStdoutLine?.(line);
+                        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 += `${line}\n`;
+                        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) => {
@@ -262,7 +468,8 @@ export class StreamingProviderProcessRunner {
                         return;
                     }
                     try {
-                        if (supervisedLaunch?.strategy === "unix_process_group") {
+                        memoryObserver?.sample();
+                        if (supervisedLaunch?.strategy === "unix_process_group" || !supervisedLaunch) {
                             await terminate();
                         }
                         else if (termination) {
@@ -275,16 +482,189 @@ export class StreamingProviderProcessRunner {
                     }
                     settled = true;
                     cleanup();
+                    const memory = memoryObserver?.complete();
                     resolve({
-                        exitCode: code ?? 1,
-                        stdout,
-                        stderr
+                        // 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 };
@@ -298,6 +678,7 @@ async function resolveProviderProcessLaunch(command, args) {
         return { command, args };
     }
     return resolveCodexNpmDirectLaunch(resolved, args)
+        ?? resolveClaudeNpmDirectLaunch(resolved, args)
         ?? resolvePackageManagerDirectLaunch(resolved, args)
         ?? buildWindowsLaunchCommand(resolved, args);
 }
@@ -342,7 +723,7 @@ async function waitForWindowsProviderReady(launch, signal, isClosed) {
                 throw error;
         }
         if (isClosed()) {
-            throw new Error("host_process_supervisor_start_failed: supervisor exited before the provider became ready.");
+            throw new ForgeFailureError("attempt_process_supervisor_start_failed", "host_process_supervisor_start_failed: supervisor exited before the provider became ready.", "bridge");
         }
         if (signal?.aborted) {
             throw signal.reason instanceof Error ? signal.reason : new Error("Provider process launch was aborted.");
@@ -361,6 +742,22 @@ export function resolveCodexNpmDirectLaunch(commandPath, args) {
         ? { command: process.execPath, args: [entryPoint, ...args] }
         : null;
 }
+/**
+ * npm installs of Claude Code (`npm i -g @anthropic-ai/claude-code`) put a `claude.cmd` shim on
+ * PATH; launch its cli.js directly for the same Job Object reasons as Codex. The native installer
+ * ships `claude.exe`, which is preferred by PATH resolution and needs no rewrite.
+ */
+export function resolveClaudeNpmDirectLaunch(commandPath, args) {
+    const extension = path.extname(commandPath).toLowerCase();
+    if ((extension !== ".cmd" && extension !== ".ps1")
+        || path.basename(commandPath, extension).toLowerCase() !== "claude") {
+        return null;
+    }
+    const entryPoint = path.join(path.dirname(commandPath), "node_modules", "@anthropic-ai", "claude-code", "cli.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
@@ -371,11 +768,11 @@ export function resolvePackageManagerDirectLaunch(commandPath, args) {
     if (extension !== ".cmd" && extension !== ".ps1")
         return null;
     const packageManager = path.basename(commandPath, extension).toLowerCase();
-    if (!["npm", "npx", "pnpm", "pnpx", "yarn", "yarnpkg"].includes(packageManager))
+    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}.js`),
+        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`)]
             : []),
@@ -432,18 +829,21 @@ export function resolveWindowsCommandFromPath(command, pathValue = process.env.P
                 ".bat",
                 ...pathExtValue.split(";").map(value => value.trim().toLowerCase()).filter(Boolean),
             ])];
-    const candidates = [];
     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 chooseWindowsCommandCandidate(candidates);
+    return null;
 }
 export function chooseWindowsCommandCandidate(candidates) {
     const normalized = candidates

package/dist/session/provider-cli/provider-cli.prompts.d.ts

@@ -24,6 +24,11 @@ export declare function buildProviderCliCommand(dispatch: RunOnceDispatchPacket,
     readonly imagePaths?: readonly string[];
     readonly runtimeEnvironment?: Readonly<Record<string, string>>;
 }): ProviderCliCommand;
+/**
+ * Returns the effort level to pass to the provider CLI, or null to keep Forge's provider default.
+ * Values the provider does not accept are dropped rather than failing the attempt; Forge validates on save.
+ */
+export declare function providerEffort(provider: string, effort: string | null | undefined): string | null;
 export declare function buildProviderCliPrompt(dispatch: RunOnceDispatchPacket, prompt: string, runtimeEnvironment?: Readonly<Record<string, string>>): string;
 export declare function codexSandboxModeForPlatform(platform?: NodeJS.Platform, executionMode?: string): "workspace-write" | "danger-full-access";
 export declare function buildArchitectPrompt(dispatch: RunOnceDispatchPacket): string;