@openclaw/codex 2026.9.4 → 2026.9.6

package/dist/{transport-stdio-BGjHoYLr.js → .setup/transport-stdio-h2VHOskC.mjs}

@@ -1,9 +1,18 @@
-import { n as normalizeCodexAppServerArgs } from "./launch-args-RXQwn8zV.js";
+import { r as normalizeCodexAppServerArgs } from "./launch-args-DbFCehO7.mjs";
+import { i as resolveManagedCodexNativeCommand } from "./managed-binary-BnshlFag.mjs";
+import { i as recordCodexAppServerSpawnFailure, r as getCodexAppServerSpawnFailure } from "./spawn-error-CL3n6MAa.mjs";
 import { createHash, randomUUID } from "node:crypto";
+import { stripVTControlCharacters } from "node:util";
+import { embeddedAgentLog } from "openclaw/plugin-sdk/agent-harness-registration";
 import { z } from "zod";
 import { materializeWindowsSpawnProgram, resolveWindowsSpawnProgram } from "openclaw/plugin-sdk/windows-spawn";
+import { closeSync, constants, openSync, readSync } from "node:fs";
+import path from "node:path";
 import { readFile, readdir } from "node:fs/promises";
+import { resolveGlobalSingleton } from "openclaw/plugin-sdk/global-singleton";
 import { once } from "node:events";
+import { KeyedAsyncQueue } from "openclaw/plugin-sdk/keyed-async-queue";
+import { resolveStateDir } from "openclaw/plugin-sdk/state-paths";
 import { execFile, spawn } from "node:child_process";
 import { setImmediate } from "node:timers/promises";
 import { finished } from "node:stream/promises";
@@ -15,6 +24,32 @@ function isDeadProcessState(state) {
 const PROCESS_COLUMNS = "pid=,ppid=,pgid=,stat=,lstart=";
 const MAX_PROCESS_CONTAINMENT_MS$1 = 2e3;
 const PROCESS_INSPECTION_MAX_BYTES = 8388608;
+const PROCFS_COMMAND_PERMISSION_EXIT = 77;
+const PROCFS_COMMAND_READER = `
+const fs = require("node:fs");
+const [pid, maxBytes] = process.argv.slice(-2).map(Number);
+try {
+  const fd = fs.openSync("/proc/" + pid + "/cmdline", "r");
+  const buffer = Buffer.alloc(4096);
+  const chunks = [];
+  let bytes = 0;
+  try {
+    for (;;) {
+      const count = fs.readSync(fd, buffer, 0, Math.min(buffer.length, maxBytes - bytes + 1), null);
+      if (count === 0) break;
+      bytes += count;
+      if (bytes > maxBytes) throw new Error("Command byte limit exceeded");
+      chunks.push(Buffer.from(buffer.subarray(0, count)));
+    }
+  } finally {
+    fs.closeSync(fd);
+  }
+  process.stdout.end(Buffer.concat(chunks, bytes));
+} catch (error) {
+  process.exitCode = ["EACCES", "EPERM", "ERR_ACCESS_DENIED"].includes(error?.code)
+    ? ${PROCFS_COMMAND_PERMISSION_EXIT} : 1;
+}
+`;
 var ProcessInspectionError = class extends Error {
 	constructor(reason) {
 		const detail = {
@@ -56,17 +91,11 @@ async function readCodexAppServerProcessCommand(observed, deadline) {
 	if (process.platform === "linux") {
 		let pending = false;
 		do {
-			const remainingMs = deadline - Date.now();
-			if (remainingMs <= 0) throw new ProcessInspectionError("deadline");
-			let command;
-			try {
-				command = await readFile(`/proc/${observed.pid}/cmdline`, {
-					encoding: "utf8",
-					signal: AbortSignal.timeout(remainingMs)
-				});
-			} catch (error) {
-				throw inspectionFailure(error);
-			}
+			if (deadline - Date.now() <= 0) throw new ProcessInspectionError("deadline");
+			const command = await readProcessOutput({
+				kind: "procfs-command",
+				pid: observed.pid
+			}, deadline);
 			if (!command || pending) {
 				const current = await readCodexAppServerProcess(observed.pid, deadline);
 				if (!current || current.startedAt !== observed.startedAt || current.ppid !== observed.ppid || current.pgid !== observed.pgid || current.state.startsWith("Z")) throw new ProcessInspectionError("unavailable");
@@ -75,20 +104,26 @@ async function readCodexAppServerProcessCommand(observed, deadline) {
 			pending = command.length === 0;
 			if (pending) await setImmediate();
 		} while (pending);
-	} else output = (await readProcessOutput([
-		"-o",
-		"command=",
-		"-p",
-		String(observed.pid)
-	], deadline)).split("\n")[0]?.trim() ?? "";
+	} else output = (await readProcessOutput({
+		kind: "ps",
+		args: [
+			"-o",
+			"command=",
+			"-p",
+			String(observed.pid)
+		]
+	}, deadline)).split("\n")[0]?.trim() ?? "";
 	if (Date.now() >= deadline) throw new ProcessInspectionError("deadline");
 	if (!output) throw new ProcessInspectionError("unavailable");
 	return output;
 }
 async function readProcesses(args, deadline, selected = false) {
-	return parseProcesses(await readProcessOutput(args, deadline), selected);
+	return parseProcesses(await readProcessOutput({
+		kind: "ps",
+		args
+	}, deadline), selected);
 }
-async function readProcessOutput(args, deadline) {
+async function readProcessOutput(command, deadline) {
 	const remainingMs = deadline - Date.now();
 	if (remainingMs <= 0) throw new ProcessInspectionError("deadline");
 	return await new Promise((resolve, reject) => {
@@ -100,16 +135,24 @@ async function readProcessOutput(args, deadline) {
 			if (output instanceof ProcessInspectionError) reject(output);
 			else resolve(output);
 		};
-		const inspector = execFile("ps", args, {
+		const procfs = command.kind === "procfs-command";
+		const inspector = execFile(procfs ? process.execPath : "ps", procfs ? [
+			...process.versions.bun ? ["--no-env-file", "--config=/dev/null"] : [],
+			"-e",
+			PROCFS_COMMAND_READER,
+			String(command.pid),
+			String(PROCESS_INSPECTION_MAX_BYTES)
+		] : command.args, {
 			encoding: "utf8",
 			maxBuffer: PROCESS_INSPECTION_MAX_BYTES,
-			env: {
+			cwd: procfs ? "/" : void 0,
+			env: procfs ? {} : {
 				...process.env,
 				LC_ALL: "C",
 				TZ: "UTC"
 			}
 		}, (error, stdout) => {
-			settle(Date.now() >= deadline ? new ProcessInspectionError("deadline") : error ? inspectionFailure(error) : stdout);
+			settle(Date.now() >= deadline ? new ProcessInspectionError("deadline") : error ? procfs && error.code === PROCFS_COMMAND_PERMISSION_EXIT ? new ProcessInspectionError("permission") : inspectionFailure(error) : stdout);
 		});
 		const timer = setTimeout(() => {
 			settle(new ProcessInspectionError("deadline"));
@@ -154,6 +197,7 @@ function parseProcesses(output, selected) {
 	return rows;
 }
 async function readLinuxProcesses(selected, deadline) {
+	if (selected !== void 0) return readSelectedLinuxProcesses(selected, deadline);
 	const remainingMs = deadline - Date.now();
 	if (remainingMs <= 0) throw new ProcessInspectionError("deadline");
 	const options = {
@@ -161,9 +205,8 @@ async function readLinuxProcesses(selected, deadline) {
 		signal: AbortSignal.timeout(remainingMs)
 	};
 	try {
-		const bootId = (await readFile("/proc/sys/kernel/random/boot_id", options)).trim();
-		if (!/^[a-f0-9-]{36}$/.test(bootId)) throw new ProcessInspectionError("unavailable");
-		const pids = selected === void 0 ? await readdir("/proc") : selected.map(String);
+		const bootId = parseLinuxBootId(await readFile("/proc/sys/kernel/random/boot_id", options));
+		const pids = await readdir("/proc");
 		const rows = [];
 		let bytes = 0;
 		for (const entry of pids) {
@@ -176,23 +219,81 @@ async function readLinuxProcesses(selected, deadline) {
 			if (stat === void 0) continue;
 			bytes += stat.length;
 			if (bytes > PROCESS_INSPECTION_MAX_BYTES) throw new ProcessInspectionError("unavailable");
-			const commEnd = stat.lastIndexOf(")");
-			const fields = stat.slice(commEnd + 1).trim().split(/\s+/);
-			const ppid = Number(fields[1]);
-			const pgid = Number(fields[2]);
-			const startTicks = fields[19];
-			if (commEnd < 0 || ![ppid, pgid].every(Number.isSafeInteger) || selected !== void 0 && (pgid <= 0 || ppid < 0) || !/^\d+$/.test(startTicks ?? "")) throw new ProcessInspectionError("unavailable");
-			if (pgid > 0) {
-				const threads = Number(fields[17]);
-				if (!/^[1-9]\d*$/.test(fields[17] ?? "") || !Number.isSafeInteger(threads)) throw new ProcessInspectionError("unavailable");
-				rows.push({
-					pid: Number(entry),
-					ppid,
-					pgid,
-					state: `${fields[0]}${threads > 1 ? "l" : ""}`,
-					startedAt: `${bootId}:${startTicks}`
-				});
+			const row = parseLinuxProcess(stat, entry, bootId, false);
+			if (row) rows.push(row);
+		}
+		if (Date.now() >= deadline) throw new ProcessInspectionError("deadline");
+		return rows;
+	} catch (error) {
+		throw inspectionFailure(error);
+	}
+}
+function parseLinuxBootId(value) {
+	const bootId = value.trim();
+	if (!/^[a-f0-9-]{36}$/.test(bootId)) throw new ProcessInspectionError("unavailable");
+	return bootId;
+}
+function parseLinuxProcess(stat, entry, bootId, selected) {
+	const commEnd = stat.lastIndexOf(")");
+	const fields = stat.slice(commEnd + 1).trim().split(/\s+/);
+	const ppid = Number(fields[1]);
+	const pgid = Number(fields[2]);
+	const startTicks = fields[19];
+	if (commEnd < 0 || ![ppid, pgid].every(Number.isSafeInteger) || selected && (pgid <= 0 || ppid < 0) || !/^\d+$/.test(startTicks ?? "")) throw new ProcessInspectionError("unavailable");
+	if (pgid > 0) {
+		const threads = Number(fields[17]);
+		if (!/^[1-9]\d*$/.test(fields[17] ?? "") || !Number.isSafeInteger(threads)) throw new ProcessInspectionError("unavailable");
+		return {
+			pid: Number(entry),
+			ppid,
+			pgid,
+			state: `${fields[0]}${threads > 1 ? "l" : ""}`,
+			startedAt: `${bootId}:${startTicks}`
+		};
+	}
+}
+/** Known procfs identities must not queue behind unrelated libuv filesystem work. */
+function readSelectedProcFile(file, deadline, maxBytes = PROCESS_INSPECTION_MAX_BYTES) {
+	if (Date.now() >= deadline) throw new ProcessInspectionError("deadline");
+	const fd = openSync(file, constants.O_RDONLY | constants.O_NONBLOCK);
+	const chunks = [];
+	const buffer = Buffer.alloc(Math.min(4096, maxBytes + 1));
+	let bytes = 0;
+	try {
+		for (;;) {
+			if (Date.now() >= deadline) throw new ProcessInspectionError("deadline");
+			const count = readSync(fd, buffer, {
+				offset: 0,
+				length: Math.min(buffer.length, maxBytes - bytes + 1),
+				position: null
+			});
+			if (Date.now() >= deadline) throw new ProcessInspectionError("deadline");
+			if (count === 0) return Buffer.concat(chunks, bytes);
+			bytes += count;
+			if (bytes > maxBytes) throw new ProcessInspectionError("unavailable");
+			chunks.push(Buffer.from(buffer.subarray(0, count)));
+		}
+	} finally {
+		closeSync(fd);
+	}
+}
+function readSelectedLinuxProcesses(selected, deadline) {
+	try {
+		const bootId = parseLinuxBootId(readSelectedProcFile("/proc/sys/kernel/random/boot_id", deadline).toString("utf8"));
+		const rows = [];
+		let bytes = 0;
+		for (const entry of selected.map(String)) {
+			if (!/^\d+$/.test(entry)) continue;
+			let stat;
+			try {
+				stat = readSelectedProcFile(`/proc/${entry}/stat`, deadline, PROCESS_INSPECTION_MAX_BYTES - bytes);
+			} catch (error) {
+				if (error && typeof error === "object" && "code" in error && (error.code === "ENOENT" || error.code === "ESRCH")) continue;
+				throw error;
 			}
+			bytes += stat.length;
+			const row = parseLinuxProcess(stat.toString("utf8"), entry, bootId, true);
+			if (row) rows.push(row);
 		}
 		if (Date.now() >= deadline) throw new ProcessInspectionError("deadline");
 		return rows;
@@ -208,6 +309,8 @@ const MAX_PROCESS_QUIESCE_PASSES = 16;
 /** Discharges the registered root obligation, including an already-obsolete PID. */
 async function terminateCodexAppServerOrphan(expected) {
 	const deadline = Date.now() + MAX_PROCESS_CONTAINMENT_MS;
+	const initial = (await readCodexAppServerProcessSnapshot(deadline, [expected.pid])).find((row) => row.pid === expected.pid);
+	if (!initial || !hasSameIdentity(initial, expected) || isDeadProcessState(initial.state)) return true;
 	const result = await terminateCodexAppServerDescendants({
 		pid: expected.pid,
 		kill: (signal) => signalProcess(expected.pid, signal ?? "SIGTERM")
@@ -220,7 +323,7 @@ async function terminateCodexAppServerOrphan(expected) {
 			if (current && isSameLiveRoot(current, contained.root, true)) signalProcess(current.pgid === current.pid ? -current.pid : current.pid, "SIGKILL");
 		}
 		while (Date.now() < deadline) {
-			const snapshot = await readCodexAppServerProcessSnapshot(deadline).catch(() => void 0);
+			const snapshot = await readCodexAppServerProcessSnapshot(deadline, [expected.pid]).catch(() => void 0);
 			if (!snapshot?.some((row) => row.pid === process.pid)) return false;
 			const current = snapshot.find((row) => row.pid === expected.pid);
 			if (!current || !hasSameIdentity(current, expected) || isDeadProcessState(current.state)) {
@@ -437,21 +540,37 @@ const registrationSchema = z.object({
 	parent: processIdentity,
 	child: childIdentity
 }).strict();
+const registrationCleanup = /* @__PURE__ */ new WeakMap();
+const processReaper = resolveGlobalSingleton(Symbol.for("openclaw.codexAppServerProcessReaper"), () => new KeyedAsyncQueue());
+/** Join bookkeeping after the transport owner has observed physical exit. */
+async function waitForCodexAppServerProcessRegistrationCleanup(child) {
+	await registrationCleanup.get(child);
+}
 function fingerprintProcessCommand(command) {
 	return createHash("sha256").update(command).digest("hex");
 }
 async function openProcessRegistrationStore() {
-	const { createPluginStateSyncKeyedStore } = await import("openclaw/plugin-sdk/plugin-state-store-runtime");
-	return createPluginStateSyncKeyedStore("codex", {
+	const env = {
+		...process.env,
+		OPENCLAW_STATE_DIR: resolveStateDir()
+	};
+	const { createPluginStateKeyedStore } = await import("openclaw/plugin-sdk/plugin-state-store-runtime");
+	return createPluginStateKeyedStore("codex", {
 		namespace: "app-server-processes",
 		maxEntries: 512,
-		overflowPolicy: "reject-new"
+		overflowPolicy: "reject-new",
+		env
 	});
 }
 async function reapRegisteredCodexAppServerOrphans() {
 	const store = await openProcessRegistrationStore();
+	await processReaper.enqueue("orphans", () => sweepRegisteredCodexAppServerOrphans(store));
+	return store;
+}
+async function sweepRegisteredCodexAppServerOrphans(store) {
+	const entries = await store.entries();
 	const deadline = Date.now() + PROCESS_REGISTRATION_INSPECTION_MS;
-	for (const entry of store.entries()) {
+	for (const entry of entries) {
 		if (Date.now() >= deadline) throw new Error("Codex orphan cleanup exceeded its startup budget. Retry to finish cleanup.");
 		const registration = registrationSchema.parse(entry.value);
 		const snapshot = await readCodexAppServerProcessSnapshot(deadline, [registration.parent.pid, registration.child.pid]);
@@ -463,29 +582,34 @@ async function reapRegisteredCodexAppServerOrphans() {
 			try {
 				command = await readCodexAppServerProcessCommand(child, deadline);
 			} catch (error) {
-				if ((await readCodexAppServerProcessSnapshot(deadline, [registration.child.pid])).find((row) => row.pid === registration.child.pid)?.startedAt === registration.child.startedAt) throw error;
+				const current = (await readCodexAppServerProcessSnapshot(deadline, [registration.child.pid])).find((row) => row.pid === registration.child.pid);
+				if (current?.startedAt === registration.child.startedAt && !isDeadProcessState(current.state)) throw error;
 			}
 			if (command !== void 0 && fingerprintProcessCommand(command) !== registration.child.commandFingerprint) {
-				store.delete(entry.key);
+				await store.delete(entry.key);
 				continue;
 			}
 		}
 		if (!await terminateCodexAppServerOrphan(registration.child)) throw new Error(`Cannot reap registered Codex process ${registration.child.pid}. Stop it before retrying.`);
-		store.delete(entry.key);
+		await store.delete(entry.key);
 	}
 }
 function createCodexAppServerProcessReaperService() {
+	let pendingSweep;
 	return {
 		id: "codex-app-server-process-reaper",
 		start(ctx) {
 			if (process.platform === "win32") return;
-			(async () => {
+			pendingSweep = (async () => {
 				try {
 					await reapRegisteredCodexAppServerOrphans();
 				} catch (error) {
 					ctx.logger.warn(`Codex app-server orphan cleanup failed: ${String(error)}`);
 				}
 			})();
+		},
+		async stop() {
+			await pendingSweep;
 		}
 	};
 }
@@ -494,8 +618,7 @@ async function prepareCodexAppServerProcessRegistration() {
 	if (process.platform === "win32") return async (child) => {
 		await once(child, "spawn");
 	};
-	await reapRegisteredCodexAppServerOrphans();
-	const store = await openProcessRegistrationStore();
+	const store = await reapRegisteredCodexAppServerOrphans();
 	return async (child) => {
 		await once(child, "spawn");
 		if (!child.pid) throw new ProcessInspectionError("unavailable");
@@ -507,19 +630,61 @@ async function prepareCodexAppServerProcessRegistration() {
 		const command = await readCodexAppServerProcessCommand(spawned, deadline);
 		if (child.exitCode !== null || child.signalCode !== null) throw new Error("Cannot register the Codex child process command: the child exited during inspection. Retry.");
 		const key = randomUUID();
-		store.register(key, {
+		const value = {
 			parent: processIdentity.parse(parent),
 			child: childIdentity.parse({
 				...spawned,
 				commandFingerprint: fingerprintProcessCommand(command)
 			})
+		};
+		const exited = new Promise((resolve) => {
+			child.once("exit", () => resolve());
 		});
-		child.once("exit", () => {
+		const registered = store.register(key, value);
+		const cleanup = (async () => {
+			await exited;
+			await registered.catch(() => void 0);
 			try {
-				store.delete(key);
+				await store.delete(key);
 			} catch {}
-		});
+		})();
+		registrationCleanup.set(child, cleanup);
+		await registered;
+		if (child.exitCode !== null || child.signalCode !== null) {
+			await cleanup;
+			throw new Error("Cannot register the Codex child process: the child exited during registration. Retry.");
+		}
+	};
+}
+//#endregion
+//#region extensions/codex/src/app-server/managed-launcher-failure.ts
+/** The official npm launcher prints Node's native spawn error and exits before initialization. */
+function observeManagedCodexLauncherFailure(child, nativeCommand) {
+	let prefix = "";
+	let launchCode;
+	const startupFailure = { complete() {
+		child.stderr.off("data", onData);
+		child.off("exit", onExit);
+		prefix = "";
+	} };
+	const onData = (chunk) => {
+		if (launchCode || prefix.length >= 16384) return;
+		prefix = (prefix + stripVTControlCharacters(chunk.toString())).slice(0, 16384);
+		if (/\bError: spawn\b/u.test(prefix) && /syscall: ['"]spawn(?: [^'"\r\n]*)?['"]/u.test(prefix)) launchCode = /\bcode: ['"](ENOENT|EACCES|EBADARCH|Unknown system error -86)['"]/u.exec(prefix)?.[1];
+		else if (/Error: Missing optional dependency @openai\/codex-[\w-]+\. Reinstall Codex:/u.test(prefix)) launchCode = "ENOENT";
+	};
+	const onExit = (code) => {
+		startupFailure.complete();
+		if (code !== 1 || !launchCode) return;
+		const described = recordCodexAppServerSpawnFailure(Object.assign(/* @__PURE__ */ new Error(`spawn ${launchCode}`), {
+			code: launchCode,
+			syscall: "spawn"
+		}), nativeCommand, nativeCommand);
+		if (described instanceof Error) startupFailure.error = described;
 	};
+	child.stderr.on("data", onData);
+	child.once("exit", onExit);
+	Object.assign(child, { startupFailure });
 }
 //#endregion
 //#region extensions/codex/src/app-server/transport.ts
@@ -602,6 +767,7 @@ async function closeCodexAppServerTransportAndWait(child, options = {}) {
 	const closure = beginCodexAppServerTransportClose(child, options);
 	const containment = await closure.closing;
 	const settled = await waitForCodexAppServerTransportExit(child, options.exitTimeoutMs ?? 2e3, drained);
+	if (settled) await waitForCodexAppServerProcessRegistrationCleanup(child);
 	closure.naturalExit = containment === "natural" && settled;
 	if (options.drainStdio) {
 		child.stdout.destroy?.();
@@ -662,29 +828,29 @@ const RUNTIME_INJECTION_ENVIRONMENT_KEYS = /* @__PURE__ */ new Set([
 	"LD_PRELOAD"
 ]);
 const QA_PARENT_PID_ENV = "OPENCLAW_QA_PARENT_PID";
-const DEFAULT_SPAWN_RUNTIME = {
-	platform: process.platform,
-	env: process.env,
-	execPath: process.execPath
-};
 /** Resolves the concrete command/argv/shell settings used to spawn Codex app-server. */
-function resolveCodexAppServerSpawnInvocation(options, runtime = DEFAULT_SPAWN_RUNTIME) {
+function resolveCodexAppServerSpawnInvocation(options, env) {
 	if (options.commandSource === "managed") throw new Error("Managed Codex app-server start options must be resolved before spawn.");
 	const program = resolveWindowsSpawnProgram({
 		command: options.command,
-		platform: runtime.platform,
-		env: runtime.env,
-		execPath: runtime.execPath,
+		platform: process.platform,
+		env,
+		execPath: process.execPath,
 		packageName: "@openai/codex"
 	});
 	const args = normalizeCodexAppServerArgs(options.args);
 	const resolved = materializeWindowsSpawnProgram(program, args);
-	return {
-		command: resolved.command,
-		args: resolved.argv,
-		shell: resolved.shell,
-		windowsHide: resolved.windowsHide
+	if (options.commandSource === "resolved-managed" && resolved.resolution === "direct" && [
+		".cjs",
+		".js",
+		".mjs"
+	].includes(path.extname(resolved.command).toLowerCase())) return {
+		...resolved,
+		command: process.execPath,
+		argv: [resolved.command, ...resolved.argv],
+		resolution: "node-entrypoint"
 	};
+	return resolved;
 }
 /** Merges app-server environment overrides while honoring clearEnv and unsafe key filtering. */
 function resolveCodexAppServerSpawnEnv(options, baseEnv = process.env, platform = process.platform) {
@@ -724,26 +890,45 @@ function copySafeEnvironmentEntries(target, source) {
 /** Spawns the Codex app-server process and returns the shared transport interface. */
 async function createStdioTransport(options, baseEnv = process.env, assertCurrent, onSpawn) {
 	const env = resolveCodexAppServerSpawnEnv(options, baseEnv);
-	const invocation = resolveCodexAppServerSpawnInvocation(options, {
-		platform: process.platform,
-		env,
-		execPath: process.execPath
-	});
+	const invocation = resolveCodexAppServerSpawnInvocation(options, env);
+	const nativeCommand = options.commandSource === "resolved-managed" ? resolveManagedCodexNativeCommand(options.command, { pathExists: () => true }) : void 0;
+	const launchKey = JSON.stringify([
+		invocation.command,
+		options.cwd ?? process.cwd(),
+		nativeCommand ?? null,
+		path.isAbsolute(invocation.command) ? null : env.PATH ?? env.Path
+	]);
+	const previousFailure = getCodexAppServerSpawnFailure(launchKey) ?? (nativeCommand ? getCodexAppServerSpawnFailure(nativeCommand) : void 0);
+	if (previousFailure) throw previousFailure;
 	const register = await prepareCodexAppServerProcessRegistration();
 	assertCurrent?.();
-	const child = spawn(invocation.command, invocation.args, {
-		...options.cwd !== void 0 ? { cwd: options.cwd } : {},
-		env,
-		detached: resolveCodexAppServerDetachedMode(env),
-		shell: invocation.shell,
-		stdio: [
-			"pipe",
-			"pipe",
-			"pipe"
-		],
-		windowsHide: invocation.windowsHide
+	embeddedAgentLog.debug("Codex app-server spawn", {
+		command: invocation.command,
+		launcher: options.command,
+		...options.cwd ? { cwd: options.cwd } : {},
+		...nativeCommand ? { nativeCommand } : {},
+		platform: process.platform,
+		arch: process.arch
 	});
+	let child;
+	try {
+		child = spawn(invocation.command, invocation.argv, {
+			...options.cwd !== void 0 ? { cwd: options.cwd } : {},
+			env,
+			detached: resolveCodexAppServerDetachedMode(env),
+			shell: invocation.shell,
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			],
+			windowsHide: invocation.windowsHide
+		});
+	} catch (error) {
+		throw recordCodexAppServerSpawnFailure(error, invocation.command, launchKey);
+	}
 	try {
+		if (nativeCommand && invocation.resolution === "node-entrypoint") observeManagedCodexLauncherFailure(child, nativeCommand);
 		onSpawn?.(child);
 		await register(child);
 		assertCurrent?.();
@@ -751,8 +936,8 @@ async function createStdioTransport(options, baseEnv = process.env, assertCurren
 	} catch (error) {
 		await closeCodexAppServerTransportAndWait(child, { drainStdio: true });
 		assertCurrent?.();
-		throw error;
+		throw child.startupFailure?.error ?? recordCodexAppServerSpawnFailure(error, invocation.command, launchKey);
 	}
 }
 //#endregion
-export { hasCodexAppServerNaturalExit as a, closeCodexAppServerTransportAndWait as i, resolveCodexAppServerSpawnEnv as n, createCodexAppServerProcessReaperService as o, closeCodexAppServerTransport as r, createStdioTransport as t };
+export { closeCodexAppServerTransportAndWait as a, closeCodexAppServerTransport as i, resolveCodexAppServerSpawnEnv as n, hasCodexAppServerNaturalExit as o, resolveCodexAppServerSpawnInvocation as r, createCodexAppServerProcessReaperService as s, createStdioTransport as t };