@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
1,527 lines • 68 kB
text/typescript
import { execFile, execFileSync } from "node:child_process";
import { closeSync, constants, existsSync, fstatSync, mkdirSync, mkdtempSync, openSync, readFileSync, readSync, readdirSync, rmSync, statSync, unlinkSync } from "node:fs";
import { homedir, tmpdir } from "node:os";
import { delimiter, join } from "node:path";
import { atomicWriteFile, getConfigDir } from "../config";
import { isSpawnableCodexCandidate } from "./exec-invocation";
import type { SpawnInvocation } from "../lib/win-exec";
import {
CodexExecTrustError,
validatedCodexExecTarget,
validatedCodexExecTargetAsync,
} from "./exec-boundary";
import { macCodexAppBundleFor, macCodexAppCommands } from "./mac-app-bundle";
import {
beginCodexCliSelectionParentWrite,
withCodexCliSelectionParentWriteAsync,
CodexCliSelectionMutationBusyError,
} from "./cli-update-selection-gate";
import { resolveCodexHomeDir } from "./home";
import { decodeOverlayState } from "./shim-state-file";
import { redactSecretString, redactUserPath } from "../lib/redact";
import { SUBPROCESS_KILL_GRACE_MS, waitForSubprocessExit } from "../lib/bounded-subprocess";
import { isPassiveRead } from "../lib/passive-read";
export type CodexRuntimeSource =
| "environment"
| "configured"
| "shim"
| "installed"
| "path"
| "fallback";
export type DeepReadonly<T> =
T extends (...args: never[]) => unknown ? T
: T extends readonly (infer U)[] ? readonly DeepReadonly<U>[]
: T extends object ? { readonly [K in keyof T]: DeepReadonly<T[K]> }
: T;
export interface ResolvedCodexRuntime {
readonly command: string;
readonly version: string | null;
readonly source: CodexRuntimeSource;
}
export interface RuntimeProbeFailure {
readonly command: string;
readonly source: CodexRuntimeSource;
readonly reason: string;
}
export interface EffortClampDiagnostic {
readonly runtimePath: string;
readonly runtimeVersion: string | null;
readonly removedEfforts: readonly string[];
readonly affectedModels: readonly string[];
}
/**
* True for the selection the resolver returns when no candidate ran: the bare `codex` fallback
* with no version. A probed candidate always carries the version it parsed, so a bare command
* that actually ran (a bare CODEX_CLI_PATH or shim, or the bare fallback itself) is not this
* sentinel. Deferred resolution (`probeVersion: false`) gives every candidate a null version and
* so cannot be told apart here; the bundled-catalog probe, `ocx connect` and `ocx status` all
* resolve with probing.
*/
export function codexRuntimeIsUnresolved(runtime: Pick<ResolvedCodexRuntime, "source" | "version">): boolean {
return runtime.source === "fallback" && runtime.version === null;
}
export interface ResolveCodexRuntimeResult {
readonly runtime: ResolvedCodexRuntime;
readonly failures: readonly RuntimeProbeFailure[];
readonly replacedConfigured?: Readonly<{ from: ResolvedCodexRuntime; reason: string }>;
/**
* Set when an unpinned, still-runnable persisted discovery is handed over to a
* strictly newer valid candidate. Distinct from replacedConfigured, which means
* the configured runtime became invalid; conflating "gone" with "superseded"
* would make the doctor output lie.
*/
readonly supersededDiscovered?: Readonly<{ from: ResolvedCodexRuntime; to: ResolvedCodexRuntime; reason: string }>;
readonly newerAvailable?: ResolvedCodexRuntime;
/** Set when the selected runtime could not be written to codex-runtime.json. */
readonly persistError?: string;
}
export type RuntimeExecFile = (
file: string,
args: string[],
options: {
encoding: "utf8";
stdio: ["ignore", "pipe", "ignore"];
timeout: number;
windowsHide: boolean;
shell?: boolean;
windowsVerbatimArguments?: boolean;
env?: NodeJS.ProcessEnv;
signal?: AbortSignal;
maxBuffer?: number;
},
) => string;
/** Async twin of RuntimeExecFile, used by resolveCodexRuntimeAsync; resolves with stdout. */
export type RuntimeExecFileAsync = (
...args: Parameters<RuntimeExecFile>
) => Promise<string>;
export interface ResolveCodexRuntimeDeps {
signal?: AbortSignal;
env?: NodeJS.ProcessEnv;
platform?: NodeJS.Platform;
configDir?: string;
execFileSync?: RuntimeExecFile;
/** Probe exec for resolveCodexRuntimeAsync. Injected impls bypass the process memo like execFileSync. */
execFile?: RuntimeExecFileAsync;
existsSync?: (path: string) => boolean;
readFileSync?: (path: string, encoding: "utf8") => string;
/** Bounded in-process macOS bundle identity reader; injected readers bypass the memo. */
readBundleIdentifier?: (infoPlistPath: string) => string | null;
/** macOS bundle publisher/filesystem trust check; injected checks bypass the memo. */
macBundleTrustReason?: (bundleRoot: string, binary: string) => string | null;
/** Async twin used by resolveCodexRuntimeAsync; injected checks bypass the memo. */
macBundleTrustReasonAsync?: (bundleRoot: string, binary: string, signal?: AbortSignal) => Promise<string | null>;
/** POSIX spawnability predicate at the exec boundary (regular file + X_OK). */
executable?: (path: string) => boolean;
/** Canonicalizer at the exec boundary; returns null when the path cannot be resolved. */
realpath?: (path: string) => string | null;
now?: () => number;
/**
* When false, stop after the first valid priority candidate (skip PATH-wide
* newerAvailable discovery). Use for hot UI/status paths.
*/
discoverAlternatives?: boolean;
/**
* When false, select a spawnable candidate without running `codex --version`.
* The prompt probe needs a command it can spawn, not a version, and paying
* ~1s of blocking exec per candidate on a UI path is what made it report an
* absent candidate instead of the Windows Codex App install (issue 4458).
*/
probeVersion?: boolean;
/**
* Directory listing used by Windows App-root discovery. Injected so tests can
* exercise the LOCALAPPDATA OpenAI/Codex/bin layout without a real Windows
* filesystem. Must be listed in resolveCacheKey's injection guard: an injected
* listing that leaked into the process memo would pin every later test in this
* file to a fake install.
*/
readdirSync?: (path: string) => string[];
/**
* Stat used to order Windows App version directories by mtime. Same injection
* contract as readdirSync: a test-supplied impl must not populate the process
* memo.
*/
statSync?: (path: string) => { mtimeMs: number; isDirectory(): boolean };
}
/**
* How a `codex-runtime.json` record got onto disk.
*
* "pinned" is an intentional operator selection (doctor --fix). "discovered" is
* automatic resolve-and-persist. Absent is the pre-field shape and is treated
* as discovered, not pinned: every such file was written by
* resolveAndPersistCodexRuntime, so reading it as a pin would leave issue 4204
* unfixed on exactly the installs that have it.
*/
export type CodexRuntimePinOrigin = "pinned" | "discovered";
export interface PersistedCodexRuntimeState {
readonly version: 1;
readonly command: string;
readonly source: CodexRuntimeSource;
readonly selectedVersion?: string | null;
readonly updatedAt: string;
readonly origin?: CodexRuntimePinOrigin;
}
const PERSIST_FILE = "codex-runtime.json";
const CLAMP_PERSIST_FILE = "codex-runtime-clamp.json";
/** Probe rejection for an absolute candidate whose file is gone. Matched when retiring a dead pin (#4035). */
const PATH_MISSING_REASON = "path does not exist";
/**
* Probe rejection when the selected command cannot even be spawned. Distinct
* from PATH_MISSING_REASON (the absolute path was gone before spawn) and from
* the generic `failed --version (...)` string (the binary ran and failed).
* Exported because the prompt probe classifies this as program-not-found, so a
* PATH fallback that is simply not installed must not look like an execution
* failure (issue 4458).
*/
export const CODEX_PROGRAM_NOT_FOUND_REASON = "program not found (ENOENT)";
function cloneAndDeepFreeze<T>(value: T): DeepReadonly<T> {
const clone = (current: unknown): unknown => {
if (Array.isArray(current)) return current.map(clone);
if (current && typeof current === "object") {
const out: Record<string, unknown> = {};
for (const [key, child] of Object.entries(current)) out[key] = clone(child);
return out;
}
return current;
};
const freeze = (current: unknown): unknown => {
if (!current || typeof current !== "object" || Object.isFrozen(current)) return current;
for (const child of Object.values(current)) freeze(child);
return Object.freeze(current);
};
return freeze(clone(value)) as DeepReadonly<T>;
}
function isCodexRuntimeSource(value: unknown): value is CodexRuntimeSource {
return value === "environment"
|| value === "configured"
|| value === "shim"
|| value === "installed"
|| value === "path"
|| value === "fallback";
}
function isCodexRuntimePinOrigin(value: unknown): value is CodexRuntimePinOrigin {
return value === "pinned" || value === "discovered";
}
export function codexRuntimeStatePath(configDir: string = getConfigDir()): string {
return join(configDir, PERSIST_FILE);
}
export function codexRuntimeClampStatePath(configDir: string = getConfigDir()): string {
return join(configDir, CLAMP_PERSIST_FILE);
}
interface PersistedClampState extends EffortClampDiagnostic {
version: 1;
updatedAt: string;
}
interface LoadedEffortClampDiagnostic {
runtimePath: string;
runtimeVersion: string | null;
removedEfforts: string[];
affectedModels: string[];
}
export function loadLastEffortClamp(
deps: ResolveCodexRuntimeDeps = {},
): LoadedEffortClampDiagnostic | null {
const configDir = deps.configDir ?? getConfigDir();
const read = deps.readFileSync ?? ((path, encoding) => readFileSync(path, encoding));
try {
const raw = JSON.parse(read(codexRuntimeClampStatePath(configDir), "utf8")) as PersistedClampState;
if (raw?.version !== 1 || !Array.isArray(raw.removedEfforts)) return null;
return {
runtimePath: typeof raw.runtimePath === "string" ? raw.runtimePath : "codex",
runtimeVersion: typeof raw.runtimeVersion === "string" ? raw.runtimeVersion : null,
removedEfforts: raw.removedEfforts.filter((item): item is string => typeof item === "string"),
affectedModels: Array.isArray(raw.affectedModels)
? raw.affectedModels.filter((item): item is string => typeof item === "string")
: [],
};
} catch {
return null;
}
}
/** Return whether a nonempty observation changed, so catalog notices share persistence's identity. */
export function persistEffortClamp(
diagnostic: EffortClampDiagnostic | null,
deps: ResolveCodexRuntimeDeps = {},
): boolean {
const configDir = deps.configDir ?? getConfigDir();
const path = codexRuntimeClampStatePath(configDir);
if (!diagnostic || diagnostic.removedEfforts.length === 0) {
try {
unlinkSync(path);
} catch {
/* absent is fine */
}
return false;
}
// This is an observation, not a heartbeat: rewriting updatedAt on every sync both churns disk
// and makes identical clamps look new after restart. Compare sets, not catalog enumeration order.
const previous = loadLastEffortClamp(deps);
const setKey = (values: readonly string[]) => JSON.stringify([...new Set(values)].sort());
if (previous && previous.runtimePath === diagnostic.runtimePath
&& previous.runtimeVersion === diagnostic.runtimeVersion
&& setKey(previous.removedEfforts) === setKey(diagnostic.removedEfforts)
&& setKey(previous.affectedModels) === setKey(diagnostic.affectedModels)) return false;
const payload: PersistedClampState = {
version: 1,
updatedAt: new Date((deps.now ?? Date.now)()).toISOString(),
runtimePath: diagnostic.runtimePath,
runtimeVersion: diagnostic.runtimeVersion,
removedEfforts: diagnostic.removedEfforts,
affectedModels: diagnostic.affectedModels,
};
mkdirSync(configDir, { recursive: true, mode: 0o700 });
atomicWriteFile(path, `${JSON.stringify(payload, null, 2)}\n`);
return true;
}
export function displayCodexRuntimePath(command: string): string {
if (command === "codex") return "codex";
return redactUserPath(command);
}
export function parseCodexVersionOutput(raw: string): string | null {
const text = String(raw || "").trim();
if (!text) return null;
const match = text.match(/\b(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)\b/);
return match?.[1] ?? null;
}
/** Compare dotted Codex versions. Returns negative if a < b. */
export function compareCodexVersions(a: string | null, b: string | null): number {
if (!a && !b) return 0;
if (!a) return -1;
if (!b) return 1;
const parse = (value: string) => {
const dash = value.indexOf("-");
const core = dash < 0 ? value : value.slice(0, dash);
const pre = dash < 0 ? "" : value.slice(dash + 1);
const parts = core.split(".").map(part => Number.parseInt(part, 10) || 0);
// SemVer prerelease identifiers are '.'-separated; keep hyphenated ids intact.
const preParts = pre
? pre.split(".").map(part => (/^\d+$/.test(part) ? Number.parseInt(part, 10) : part))
: [];
return { parts, preParts };
};
const left = parse(a);
const right = parse(b);
const len = Math.max(left.parts.length, right.parts.length);
for (let i = 0; i < len; i += 1) {
const diff = (left.parts[i] ?? 0) - (right.parts[i] ?? 0);
if (diff !== 0) return diff;
}
if (left.preParts.length === 0 && right.preParts.length > 0) return 1;
if (left.preParts.length > 0 && right.preParts.length === 0) return -1;
const preLen = Math.max(left.preParts.length, right.preParts.length);
for (let i = 0; i < preLen; i += 1) {
const lp = left.preParts[i];
const rp = right.preParts[i];
if (lp === undefined) return -1;
if (rp === undefined) return 1;
if (typeof lp === "number" && typeof rp === "number") {
if (lp !== rp) return lp - rp;
continue;
}
if (typeof lp === "number") return -1; // numeric < non-numeric (SemVer)
if (typeof rp === "number") return 1;
if (lp < rp) return -1;
if (lp > rp) return 1;
}
return 0;
}
/** Parse already-observed runtime-selection bytes without consulting the filesystem. */
export function parsePersistedCodexRuntime(
bytes: string | Uint8Array,
): DeepReadonly<PersistedCodexRuntimeState> | null {
try {
const text = typeof bytes === "string" ? bytes : Buffer.from(bytes).toString("utf8");
const raw = JSON.parse(text) as Partial<PersistedCodexRuntimeState>;
if (raw.version !== 1 || typeof raw.command !== "string" || !raw.command.trim()) return null;
if (!isCodexRuntimeSource(raw.source) || typeof raw.updatedAt !== "string") return null;
if (raw.selectedVersion !== undefined
&& raw.selectedVersion !== null
&& typeof raw.selectedVersion !== "string") return null;
// Absent origin is legal (pre-field files). A present value that is neither
// literal makes the whole record invalid, same as every other field.
if (raw.origin !== undefined && !isCodexRuntimePinOrigin(raw.origin)) return null;
return cloneAndDeepFreeze(raw as PersistedCodexRuntimeState);
} catch {
return null;
}
}
export function loadPersistedCodexRuntime(
deps: ResolveCodexRuntimeDeps = {},
): DeepReadonly<PersistedCodexRuntimeState> | null {
const configDir = deps.configDir ?? getConfigDir();
const read = deps.readFileSync ?? ((path, encoding) => readFileSync(path, encoding));
try {
return parsePersistedCodexRuntime(read(codexRuntimeStatePath(configDir), "utf8"));
} catch {
return null;
}
}
/**
* True only when the operator intentionally pinned this runtime.
*
* A record with no origin is NOT pinned: every such file predates this field
* and was written by resolveAndPersistCodexRuntime, which is auto-discovery.
* Reading a missing origin as an intentional pin would leave issue 4204
* unfixed on exactly the installs that have it — the still-runnable 0.135.0
* CLI that kept winning over a 0.153.4 Desktop runtime sitting right there.
*/
export function persistedCodexRuntimeIsPinned(
state: DeepReadonly<PersistedCodexRuntimeState> | null | undefined,
): boolean {
return state?.origin === "pinned";
}
/**
* Persist the selected Codex runtime.
*
* `origin` defaults to "pinned" ON PURPOSE: a direct call is a deliberate
* selection. src/cli/doctor.ts calls this from `doctor --fix`. The automatic
* discovery path is resolveAndPersistCodexRuntime, which passes "discovered"
* explicitly. Flipping the default would make doctor --fix look like an
* accident, and a later resolve would silently replace the operator's choice
* (issue 4204).
*/
export function persistCodexRuntime(
runtime: ResolvedCodexRuntime,
deps: ResolveCodexRuntimeDeps = {},
origin: CodexRuntimePinOrigin = "pinned",
): void {
// A cli-update worker holds the shared selection gate from its final process
// scan through its installer spawn; this write must not slip into that
// window, so a held gate is an immediate busy rather than a wait. Checked
// BEFORE the mkdir and the resolve-cache invalidation so a busy refusal
// changes nothing at all.
const selectionWrite = beginCodexCliSelectionParentWrite(deps.configDir);
if (!selectionWrite.entered) throw new CodexCliSelectionMutationBusyError();
try {
const configDir = deps.configDir ?? getConfigDir();
mkdirSync(configDir, { recursive: true, mode: 0o700 });
const payload: PersistedCodexRuntimeState = {
version: 1,
command: runtime.command,
source: runtime.source,
selectedVersion: runtime.version,
updatedAt: new Date((deps.now ?? Date.now)()).toISOString(),
origin,
};
// Invalidate process authority before the persisted replacement is visible.
clearCodexRuntimeResolveCache();
atomicWriteFile(codexRuntimeStatePath(configDir), `${JSON.stringify(payload, null, 2)}\n`);
} finally {
selectionWrite.exit();
}
}
/**
* Delete `codex-runtime.json`. Used to retire a pin whose path no longer exists, so a
* later resolve stops re-probing it (#4035).
*
* Invalidates the process resolve memo the same way `persistCodexRuntime` does: the memo
* folds the persisted `updatedAt` into its key, and a removed file has no stamp to fold.
*/
export function clearPersistedCodexRuntime(deps: ResolveCodexRuntimeDeps = {}): void {
// Same gate as persistCodexRuntime, checked before the cache invalidation
// and outside the swallowing catch: a busy refusal must stay an error, not
// become a silent "already removed".
const selectionWrite = beginCodexCliSelectionParentWrite(deps.configDir);
if (!selectionWrite.entered) throw new CodexCliSelectionMutationBusyError();
try {
const configDir = deps.configDir ?? getConfigDir();
clearCodexRuntimeResolveCache();
try {
unlinkSync(codexRuntimeStatePath(configDir));
} catch (error) {
// An already-missing file is the success case: the pin is gone, which is the point.
// Anything else means the pin SURVIVES and stays authoritative, so every later
// resolve re-probes the same dead path — #4035 unfixed, silently. Say so once.
const code = (error as NodeJS.ErrnoException | null)?.code;
if (code === "ENOENT") return;
console.warn(
`[opencodex] Could not remove the stale Codex runtime pin at ${displayCodexRuntimePath(codexRuntimeStatePath(configDir))}`
+ ` (${code ?? "unknown error"}). It will be re-probed until the file is removed.`,
);
}
} finally {
selectionWrite.exit();
}
}
export async function persistCodexRuntimeAsync(runtime: ResolvedCodexRuntime, deps: ResolveCodexRuntimeDeps = {},
origin: CodexRuntimePinOrigin = "pinned"): Promise<void> {
await withCodexCliSelectionParentWriteAsync(() => persistCodexRuntime(runtime, deps, origin), deps);
}
export async function clearPersistedCodexRuntimeAsync(deps: ResolveCodexRuntimeDeps = {}): Promise<void> {
await withCodexCliSelectionParentWriteAsync(() => clearPersistedCodexRuntime(deps), deps);
}
type VersionProbeResult = { ok: true; version: string | null; macAppBundle?: boolean } | { ok: false; reason: string };
/** Checks that need no exec; a non-null answer settles the candidate without running `--version`. */
function versionProbePrecheck(command: string, deps: ResolveCodexRuntimeDeps): VersionProbeResult | null {
const platform = deps.platform ?? process.platform;
if (command.includes("/") || command.includes("\\") || /^[A-Za-z]:/.test(command)) {
const exists = deps.existsSync ?? existsSync;
if (!exists(command)) return { ok: false, reason: PATH_MISSING_REASON };
if (!isSpawnableCodexCandidate(command, platform)) {
return { ok: false, reason: "not a spawnable Codex launcher on this platform" };
}
}
// The prompt probe needs a spawnable candidate, not a version. Running
// `codex --version` here is ~1s of blocking exec per candidate; on the
// dashboard probe that cost made Windows report Codex as missing even when
// the App install was sitting under LOCALAPPDATA/OpenAI/Codex/bin (issue 4458).
if (!macCodexAppIdentityMatches(command, deps)) {
return { ok: false, reason: "Codex app bundle identity mismatch or unavailable" };
}
if (deps.probeVersion === false) return { ok: true, version: null };
return null;
}
/** The sync and async probes differ only in which exec-boundary check builds this invocation. */
function codexExecBoundaryDeps(deps: ResolveCodexRuntimeDeps) {
return {
env: deps.env,
platform: deps.platform,
exists: deps.existsSync,
executable: deps.executable,
realpath: deps.realpath,
macBundleTrustReason: deps.macBundleTrustReason,
};
}
function versionProbeInvocation(deps: ResolveCodexRuntimeDeps, probeHome: string, invocation: SpawnInvocation) {
return {
file: invocation.file,
args: invocation.args,
options: {
encoding: "utf8" as const,
stdio: ["ignore", "pipe", "ignore"] as ["ignore", "pipe", "ignore"],
timeout: 8_000,
windowsHide: true,
env: { ...(deps.env ?? process.env), CODEX_HOME: probeHome },
...invocation.options,
},
};
}
function versionProbeOutput(output: string, macAppBundle: boolean): VersionProbeResult {
const version = parseCodexVersionOutput(output);
if (!version) return { ok: false, reason: "unrecognized --version output" };
return { ok: true, version, macAppBundle };
}
function versionProbeError(error: unknown, probeHome: string | undefined): VersionProbeResult {
if (!probeHome) return { ok: false, reason: "probe sandbox unavailable" };
if ((error as NodeJS.ErrnoException)?.code === "ENOENT") {
return { ok: false, reason: CODEX_PROGRAM_NOT_FOUND_REASON };
}
const message = error instanceof Error ? error.message : String(error);
const redacted = redactUserPath(redactSecretString(message)).slice(0, 160);
return { ok: false, reason: `failed --version (${redacted})` };
}
function removeProbeHome(probeHome: string | undefined): void {
if (!probeHome) return;
// Nested catch: a transient Windows EBUSY must never mask the probe result.
try { rmSync(probeHome, { recursive: true, force: true }); } catch { /* best effort */ }
}
function probeVersion(command: string, deps: ResolveCodexRuntimeDeps): VersionProbeResult {
const settled = versionProbePrecheck(command, deps);
if (settled) return settled;
const exec = deps.execFileSync ?? (execFileSync as unknown as RuntimeExecFile);
// Sandbox the probe's CODEX_HOME: a real Codex CLI creates state (tmp/, logs) under
// CODEX_HOME even for `--version`, and the probe inherits the caller's env — so a
// read-only `ocx status` would dirty the user's CODEX_HOME. Redirect it to a
// throwaway dir; if the sandbox cannot be created, skip the probe rather than
// probe with the inherited env (keeps probeVersion total: it never throws).
let probeHome: string | undefined;
try {
probeHome = mkdtempSync(join(tmpdir(), "ocx-codex-probe-"));
const target = validatedCodexExecTarget(command, ["--version"], codexExecBoundaryDeps(deps));
const { file, args, options } = versionProbeInvocation(deps, probeHome, target.invocation);
return versionProbeOutput(exec(file, args, options), target.macAppBundle);
} catch (error) {
if (error instanceof CodexExecTrustError) {
return { ok: false, reason: redactUserPath(redactSecretString(error.message)).slice(0, 160) };
}
return versionProbeError(error, probeHome);
} finally {
removeProbeHome(probeHome);
}
}
export const execCodexFileAsync: RuntimeExecFileAsync = (file, args, options) =>
new Promise((resolve, reject) => {
if (options.signal?.aborted) { reject(new Error("Codex subprocess aborted")); return; }
// execFile always pipes stdout/stderr; it takes no stdio option.
// Own abort/deadline termination; execFile's built-in observer can settle the
// callback while a SIGTERM-ignoring child is still alive.
const { stdio: _stdio, signal: _signal, timeout: _timeout, ...execOptions } = options;
let settled = false;
let timer: ReturnType<typeof setTimeout> | undefined;
let abort = () => {};
const finish = (error: Error | null, stdout = "") => {
if (settled) return;
settled = true;
clearTimeout(timer);
options.signal?.removeEventListener("abort", abort);
if (error) reject(error); else resolve(stdout);
};
const child = execFile(file, args, execOptions, (error, stdout) => {
if (error && child.exitCode === null && child.signalCode === null) stop(error);
else finish(error, String(stdout));
});
const exited = new Promise<number>(resolveExit => {
child.once("exit", code => resolveExit(code ?? 1));
// A kill error is not exit proof; only failed spawn has no child to reap.
child.once("error", () => { if (!child.pid) resolveExit(1); });
});
// A reaper owns actual exit independently of caller-facing promise settlement.
let stopping = false;
const stop = (error: Error) => {
if (stopping) return;
stopping = true;
try { child.kill(); } catch { /* exit/error observation still owns reaping */ }
child.stdout?.destroy();
child.stderr?.destroy();
void waitForSubprocessExit({ exited, kill: () => child.kill("SIGKILL") }, SUBPROCESS_KILL_GRACE_MS);
finish(error);
};
abort = () => stop(new Error("Codex subprocess aborted"));
options.signal?.addEventListener("abort", abort, { once: true });
if (options.timeout > 0) {
timer = setTimeout(() => stop(new Error("Codex subprocess deadline exceeded")), options.timeout);
timer.unref?.();
}
if (options.signal?.aborted) abort();
});
/** probeVersion with the same sandbox and outcomes, but the exec never holds the event loop. */
async function probeVersionAsync(command: string, deps: ResolveCodexRuntimeDeps): Promise<VersionProbeResult> {
const settled = versionProbePrecheck(command, deps);
if (settled) return settled;
const exec = deps.execFile ?? execCodexFileAsync;
let probeHome: string | undefined;
try {
probeHome = mkdtempSync(join(tmpdir(), "ocx-codex-probe-"));
const target = await validatedCodexExecTargetAsync(command, ["--version"], {
...codexExecBoundaryDeps(deps),
macBundleTrustReasonAsync: deps.macBundleTrustReasonAsync,
signal: deps.signal,
});
const { file, args, options } = versionProbeInvocation(deps, probeHome, target.invocation);
return versionProbeOutput(await exec(file, args, { ...options, signal: deps.signal }), target.macAppBundle);
} catch (error) {
if (error instanceof CodexExecTrustError) {
return { ok: false, reason: redactUserPath(redactSecretString(error.message)).slice(0, 160) };
}
return versionProbeError(error, probeHome);
} finally {
removeProbeHome(probeHome);
}
}
function shimCandidates(deps: ResolveCodexRuntimeDeps): string[] {
const configDir = deps.configDir ?? getConfigDir();
const read = deps.readFileSync ?? ((path, encoding) => readFileSync(path, encoding));
const platform = deps.platform ?? process.platform;
try {
const state = JSON.parse(read(join(configDir, "codex-shim.json"), "utf8")) as {
schema?: unknown;
mode?: unknown;
wrapperPath?: unknown;
originalPath?: unknown;
backupPath?: unknown;
wrappers?: Array<{ wrapperPath?: unknown; originalPath?: unknown; backupPath?: unknown }>;
};
const overlay = decodeOverlayState(state, configDir);
if ((state.schema !== undefined || state.mode !== undefined) && !overlay) return [];
const files = Array.isArray(state.wrappers) && state.wrappers.length > 0 ? state.wrappers : [state];
const out: string[] = overlay && isSpawnableCodexCandidate(overlay.launcherPath, platform)
? [overlay.launcherPath] : [];
for (const file of files) {
for (const value of [file.backupPath, file.originalPath, file.wrapperPath]) {
if (typeof value !== "string" || value.length === 0) continue;
if (!isSpawnableCodexCandidate(value, platform)) continue;
out.push(value);
}
}
return [...new Set(out)];
} catch {
return [];
}
}
function pathCandidates(deps: ResolveCodexRuntimeDeps): string[] {
const env = deps.env ?? process.env;
const platform = deps.platform ?? process.platform;
const out: string[] = [];
for (const dir of (env.PATH ?? "").split(delimiter).filter(Boolean)) {
if (platform === "win32") {
out.push(join(dir, "codex.exe"), join(dir, "codex.cmd"));
} else {
out.push(join(dir, "codex"));
}
}
return [...new Set(out)];
}
/**
* Bundle-identity eligibility only. This runs inside the exec-free precheck and
* inside deferred/passive enumeration, so it must never spawn: signature and
* ownership trust is enforced at the execution boundary (exec-boundary.ts)
* every time the selected command is actually run, not once at selection.
*/
function macCodexAppIdentityMatches(command: string, deps: ResolveCodexRuntimeDeps): boolean {
const bundle = macCodexAppBundleFor(command, deps);
if (!bundle) return true;
try {
return (deps.readBundleIdentifier ?? readBoundedBundleIdentifier)(`${bundle}/Contents/Info.plist`) === "com.openai.codex";
} catch { return false; }
}
/** XML plist subset only: no external entity expansion, subprocess, or unbounded read. */
function readBoundedBundleIdentifier(path: string): string | null {
let fd: number | undefined;
try {
fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK);
const st = fstatSync(fd);
const limit = 64 * 1024;
if (!st.isFile() || st.size > limit) return null;
const bytes = Buffer.alloc(limit + 1);
let size = 0;
while (size < bytes.length) {
const count = readSync(fd, bytes, size, bytes.length - size, null);
if (!count) break;
size += count;
}
if (size > limit) return null;
// XML 1.0 Char: tab, LF, CR, U+0020-D7FF, U+E000-FFFD, U+10000-10FFFF (no surrogates after fatal decoding).
const xmlChar = (code: number): boolean => code === 9 || code === 10 || code === 13
|| (code >= 0x20 && code <= 0xd7ff) || (code >= 0xe000 && code <= 0xfffd) || (code >= 0x10000 && code <= 0x10ffff);
const allXmlChars = (text: string): boolean => [...text].every(char => xmlChar(char.codePointAt(0)!));
const decoded = new TextDecoder("utf-8", { fatal: true }).decode(bytes.subarray(0, size));
// Every character is checked before anything is stripped, the prolog included.
if (!allXmlChars(decoded)) return null;
// Only a well-formed UTF-8 declaration and Apple's DOCTYPE are accepted, anchored in the prolog, in that order.
const declaration = /^<\?xml\s+version=(["'])1\.[0-9]\1(?:\s+encoding=(["'])utf-8\2)?(?:\s+standalone=(["'])(?:yes|no)\3)?\s*\?>/i;
if (decoded.startsWith("<?") && !declaration.test(decoded)) return null;
const xml = decoded
.replace(declaration, "")
.replace(/^\s*<!DOCTYPE plist PUBLIC "-\/\/Apple\/\/DTD PLIST 1\.0\/\/EN" "http:\/\/www\.apple\.com\/DTDs\/PropertyList-1\.0\.dtd">/, "");
type Node = { name: string; text: string; children: Node[] };
const root: Node = { name: "root", text: "", children: [] };
const stack = [root];
const tokens = xml.match(/<!--[\s\S]*?-->|<[^>]*>|[^<]+/g) ?? [];
if (tokens.join("") !== xml) return null;
for (const token of tokens) {
if (token.startsWith("<!--")) {
// A comment may not contain "--" or end in "-" (XML 1.0 §2.5).
if (/--|-$/.test(token.slice(4, -3))) return null;
continue;
}
const parent = stack[stack.length - 1]!;
if (!token.startsWith("<")) {
if (token.includes("]]>")) return null;
parent.text += token;
continue;
}
const close = /^<\/(\w+)\s*>$/.exec(token);
if (close) {
if (stack.length === 1 || parent.name !== close[1]) return null;
stack.pop();
continue;
}
const open = /^<(plist|dict|array|key|string|integer|real|date|data|true|false)(?:\s+version="1\.0")?\s*(\/?)>$/.exec(token);
if (!open || (token.includes("version=") && open[1] !== "plist")) return null;
const node: Node = { name: open[1]!, text: "", children: [] };
parent.children.push(node);
if (!open[2]) stack.push(node);
}
if (stack.length !== 1 || root.text.trim() || root.children.length !== 1) return null;
const plist = root.children[0]!;
if (plist.name !== "plist" || plist.text.trim() || plist.children.length !== 1) return null;
const dict = plist.children[0]!;
if (dict.name !== "dict" || dict.text.trim() || dict.children.length % 2) return null;
const decode = (text: string): string => text.replace(/&([^;]*);|&/g, (_match, entity: string | undefined) => {
const named: Record<string, string> = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'" };
if (entity && Object.hasOwn(named, entity)) return named[entity]!;
if (!entity || !/^#(?:[0-9]+|x[0-9a-fA-F]+)$/.test(entity)) throw new Error("invalid XML entity");
const value = entity.startsWith("#x") ? parseInt(entity.slice(2), 16) : Number(entity.slice(1));
if (!xmlChar(value)) throw new Error("invalid XML character");
return String.fromCodePoint(value);
});
// The identity only counts inside a document that is valid as a whole: every node, entity and
// literal character is checked, not just the CFBundleIdentifier pair.
const leafFormats: Record<string, RegExp> = {
integer: /^\s*[+-]?(?:\d+|0x[0-9a-fA-F]+)\s*$/,
real: /^\s*(?:[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?|[+-]?(?:nan|inf(?:inity)?))\s*$/i,
date: /^\s*\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z\s*$/,
data: /^[A-Za-z0-9+/=\s]*$/,
};
const validNode = (node: Node, inDict: "key" | "value" | null): boolean => {
if (!allXmlChars(node.text)) return false;
if (inDict === "key" && node.name !== "key") return false;
if (inDict !== "key" && node.name === "key") return false;
switch (node.name) {
case "dict":
return !node.text.trim() && node.children.length % 2 === 0
&& node.children.every((child, index) => validNode(child, index % 2 === 0 ? "key" : "value"));
case "array":
return !node.text.trim() && node.children.every(child => validNode(child, null));
case "key": case "string":
decode(node.text);
return node.children.length === 0;
case "true": case "false":
return node.children.length === 0 && !node.text.trim();
case "integer": case "real": case "date": case "data":
return node.children.length === 0 && leafFormats[node.name]!.test(decode(node.text));
default:
return false;
}
};
if (!validNode(dict, null)) return null;
let identifier: string | null = null;
let keys = 0;
for (let i = 0; i < dict.children.length; i += 2) {
const key = dict.children[i]!, value = dict.children[i + 1]!;
if (key.name !== "key" || key.children.length) return null;
if (decode(key.text) !== "CFBundleIdentifier") continue;
keys++;
if (value.name !== "string" || value.children.length) return null;
identifier = decode(value.text);
}
return keys === 1 ? identifier : null;
} catch { return null; }
finally { if (fd !== undefined) closeSync(fd); }
}
/**
* Codex installs that PATH does not necessarily expose.
*
* The Windows Codex App writes codex.exe under
* LOCALAPPDATA/OpenAI/Codex/bin/<changing-version>/, which never appears on
* the service process PATH. The prompt probe used to hardcode four POSIX
* paths and miss that layout, then report an absent candidate (issue 4458).
* POSIX keeps those four paths so an install that resolved before this source
* existed still resolves.
*/
function installedCodexCandidates(deps: ResolveCodexRuntimeDeps): string[] {
const platform = deps.platform ?? process.platform;
const env = deps.env ?? process.env;
const readDir = deps.readdirSync ?? ((path: string) => readdirSync(path));
const stat = deps.statSync ?? ((path: string) => statSync(path));
/** Version directories directly under root, newest first; unreadable roots yield nothing. */
const versionDirectories = (root: string): string[] => {
try {
const dirs: Array<{ name: string; directory: string; mtimeMs: number }> = [];
for (const name of readDir(root)) {
const directory = join(root, name);
try {
const st = stat(directory);
if (!st.isDirectory()) continue;
dirs.push({ name, directory, mtimeMs: st.mtimeMs });
} catch {
continue;
}
}
dirs.sort((a, b) => b.mtimeMs - a.mtimeMs || a.name.localeCompare(b.name));
return dirs.map(entry => entry.directory);
} catch {
return [];
}
};
if (platform === "win32") {
const localAppData = env.LOCALAPPDATA?.trim();
if (!localAppData) return [];
return versionDirectories(join(localAppData, "OpenAI", "Codex", "bin"))
.map(directory => join(directory, "codex.exe"));
}
const home = env.HOME?.trim() || env.USERPROFILE?.trim() || homedir();
const posix = [
join(home, ".codex", "packages", "standalone", "current", "bin", "codex"),
join(home, ".local", "bin", "codex"),
"/usr/local/bin/codex",
"/opt/homebrew/bin/codex",
];
if (platform === "darwin") {
const exists = deps.existsSync ?? existsSync;
return [...posix, ...macCodexAppCommands(deps).filter(command => exists(command) && macCodexAppIdentityMatches(command, deps))];
}
if (platform !== "linux") return posix;
// Windows Codex Desktop in WSL app-server mode ships its Linux binary under the
// effective Codex home as bin/wsl/<version-hash>/codex, and a Desktop update replaces
// that hash directory. The service PATH usually has no codex (issue 5635), so these
// rank after PATH and the ordinary locations and are re-enumerated on every resolve
// rather than trusted from a remembered hash.
let codexHome: string;
try {
codexHome = resolveCodexHomeDir({ env });
} catch {
return posix;
}
const desktopWsl = versionDirectories(join(codexHome, "bin", "wsl"))
.map(directory => join(directory, "codex"));
return [...posix, ...desktopWsl];
}
interface RankedCandidate {
command: string;
source: CodexRuntimeSource;
}
function sameRuntimeCommand(a: string, b: string): boolean {
return a.trim().toLowerCase() === b.trim().toLowerCase();
}
/**
* Rungs OpenCodex no longer lets the observed-runtime intersection remove, so a persisted
* diagnostic naming only these describes a policy that is gone rather than a live restriction.
* This is the single copy of the exemption: `catalog/effort.ts` imports it for the clamp
* predicate, and a leftover file written before the exemption must not keep warning about
* rungs the next sync will stop removing.
*/
export const UNCLAMPABLE_REASONING_EFFORTS: ReadonlySet<string> = new Set(["max", "ultra"]);
/** Removals that still describe a real restriction, ignoring rungs nothing clamps any more. */
export function liveRemovedEfforts(
diagnostic: EffortClampDiagnostic | null | undefined,
): readonly string[] {
if (!diagnostic) return [];
return diagnostic.removedEfforts.filter(effort => !UNCLAMPABLE_REASONING_EFFORTS.has(effort));
}
/**
* True when a persisted clamp diagnostic still applies to the currently selected runtime.
*
* Two ways a stored diagnostic stops describing reality:
*
* 1. Every rung it names is one nothing clamps any more, so the file is inert until the next
* sync unlinks it.
* 2. The binary at that path was upgraded in place. Windows updates Codex without moving the
* executable, so path equality alone kept a 0.135.0 observation "current" for a 0.154.0
* runtime whose own bundled catalog carried the rungs the diagnostic claimed were missing.
* A known version mismatch therefore wins over a path match; an unknown version on either
* side stays conservative, because absence of a version is not evidence of an upgrade.
*/
export function effortClampAppliesToRuntime(
diagnostic: EffortClampDiagnostic | null | undefined,
runtime: Pick<ResolvedCodexRuntime, "command" | "version">,
): boolean {
if (!diagnostic || liveRemovedEfforts(diagnostic).length === 0) return false;
if (sameRuntimeCommand(diagnostic.runtimePath, runtime.command)) {
if (diagnostic.runtimeVersion && runtime.version) {
return diagnostic.runtimeVersion === runtime.version;
}
return true;
}
return Boolean(
diagnostic.runtimeVersion
&& runtime.version
&& diagnostic.runtimeVersion === runtime.version,
);
}
const RESOLVE_CACHE_MS = 15_000;
interface ResolveCacheMemo {
readonly key: string;
readonly at: number;
readonly epoch: number;
readonly valueIdentity: string;
readonly value: DeepReadonly<ResolveCodexRuntimeResult>;
}
export type CodexRuntimeProcessCachePeek =
| Readonly<{
kind: "available";
epoch: number;
valueIdentity: string;
value: DeepReadonly<ResolveCodexRuntimeResult>;
}>
| Readonly<{ kind: "unavailable"; epoch: number }>;
let resolveCacheEpoch = 0;
let resolveCache: ResolveCacheMemo | null = null;
/**
* Memo for probeVersion === false resolves. Kept separate from resolveCache
* because peekCodexRuntimeProcessCache is read by convergence and the bundled
* catalog as "what runtime are we on". Publishing a null version there would
* be read as "unknown version" and become process authority (issue 4458).
*/
interface DeferredResolveCacheMemo {
readonly key: string;
readonly at: number;
readonly value: DeepReadonly<ResolveCodexRuntimeResult>;
}
let deferredResolveCache: DeferredResolveCacheMemo | null = null;
/**
* Bumped whenever persisted runtime state is replaced or process authority is cleared.
*
* Consumers that memoize anything derived from `codex-runtime.json` — entitlement's client
* version, for one — read this instead of a timestamp, so a runtime switch invalidates them at
* the moment of the write rather than after a delay window. Exposed because the alternative was
* a time-based guess that could answer under the previous version after the file had changed.
*/
export function codexRuntimeStateEpoch(): number {
return resolveCacheEpoch;
}
function publishResolveCache(key: string, at: number, value: ResolveCodexRuntimeResult): void {
const epoch = ++resolveCacheEpoch;
resolveCache = {
key,
at,
epoch,
valueIdentity: `runtime:${epoch}`,
value: cloneAndDeepFreeze(value),
};
}
function clearResolveCache(): void {
resolveCacheEpoch += 1;
resolveCache = null;
deferredResolveCache = null;
}
/** Clear process-local runtime authority without resolving a replacement. */
export function clearCodexRuntimeResolveCache(): void {
clearResolveCache();
}
/**
* Observe the successful process memo; never resolves or probes.
*
* An expired memo stays observable while an async refresh for the same inputs is in flight
* and nothing has invalidated it since. The sync resolver used to hold the event loop for the
* whole probe, so nothing could read in that window; with the refresh off the loop, dropping
* the memo there would send catalog gather to the persisted runtime (or none) and have
* convergence reject its process-local candidate every expiry. A published result or a clear
* still retires it; the deferred selection never enters this memo (#4458).
*/
export function peekCodexRuntimeProcessCache(): CodexRuntimeProcessCachePeek {
const memo = resolveCache;
const refreshing = memo !== null
&& asyncResolveInflight !== null
&& asyncResolveInflight.key === memo.key
&& asyncResolveInflight.epoch === resolveCacheEpoch
// An expired memo only stands in for a refresh of the same selection; an out-of-process
// runtime switch changes the key without bumping the epoch.
&& resolveCacheKey({}) === memo.key;
if (!memo || (Date.now() - memo.at >= RESOLVE_CACHE_MS && !refreshing)) {
return Object.freeze({ kind: "unavailable" as const, epoch: resolveCacheEpoch });
}
return Object.freeze({
kind: "available" as const,
epoch: memo.epoch,
valueIdentity: memo.valueIdentity,
value: cloneAndDeepFreeze(memo.value),
});
}
function persistedRuntimeCacheStamp(deps: ResolveCodexRuntimeDeps): string {
// Include on-disk selection so doctor --fix in another process busts this memo.
const configDir = deps.configDir ?? getConfigDir();
const read = deps.readFileSync ?? ((path, encoding) => readFileSync(path, encoding));
try {
return read(codexRuntimeStatePath(configDir), "utf8");
} catch {
return "";
}
}
function resolveCacheKey(deps: ResolveCodexRuntimeDeps): string | null {
// Only memoize uninjected process-env resolves (settings/status hot paths).
if (
deps.signal
|| deps.execFileSync
|| deps.execFile
|| deps.existsSync
|| deps.readFileSync
|| deps.readBundleIdentifier
|| deps.macBundleTrustReason
|| deps.macBundleTrustReasonAsync
|| deps.executable
|| deps.realpath
|| deps.readdirSync
|| deps.statSync
|| deps.configDir
|| deps.now
) {
return null;
}
return codexRuntimeSelectionIdentity(deps);
}
/** Exec-free input identity, including pin changes made by another process. */
export function codexRuntimeSelectionIdentity(deps: ResolveCodexRuntimeDeps = {}): string {
const env = deps.env ?? process.env;
return JSON.stringify({
configDir: deps.configDir ?? getConfigDir(),
cli: env.CODEX_CLI_PATH ?? "",
path: env.PATH ?? "",
platform: deps.platform ?? process.platform,
discover: deps.discoverAlternatives !== false,
probeVersion: deps.probeVersion !== false,
localAppData: env.LOCALAPPDATA?.trim() ?? "",
homeDir: env.HOME?.trim() ?? "",
userProfile: env.USERPROFILE?.trim() ?? "",
// Linux discovery enumerates <CODEX_HOME>/bin/wsl, so the home is part of the key.
codexHome: env.CODEX_HOME?.trim() ?? "",
home: process.env.OPENCODEX_HOME ?? "",
persisted: persistedRuntimeCacheStamp(deps),
});
}
/**
* Resolve the single Codex runtime OpenCodex should use for sync, clamp, and probes.
*/
export function resolveCodexRuntime(deps: ResolveCodexRuntimeDeps = {}): ResolveCodexRuntimeResult {
const cacheKey = resolveCacheKey(deps);
// A deferred selection has no validated version and must not publish into
// runtime authority. peekCodexRuntimeProcessCache would otherwise report
// "available" with version null, which catalog/convergence read as unknown.
if (deps.probeVersion === false) {
if (cacheKey
&& deferredResolveCache
&& deferredResolveCache.key === cacheKey
&& Date.now() - deferredResolveCache.at < RESOLVE_CACHE_MS) {
return cloneAndDeepFreeze(deferredResolveCache.value);
}
const deferred = resolveCodexRuntimeUncached(deps);
if (!cacheKey) return cloneAndDeepFreeze(deferred);
deferredResolveCache = {
key: cacheKey,
at: Date.now(),
value: cloneAndDeepFreeze(deferred),
};
return cloneAndDeepFreeze(deferredResolveCache.value);
}
if (cacheKey && resolveCache && resolveCache.key === cacheKey && Date.now() - resolveCache.at < RESOLVE_CACHE_MS) {
return cloneAndDeepFreeze(resolveCache.value);
}
const result = resolveCodexRuntimeUncached(deps);
if (cacheKey) {
publishResolveCache(cacheKey, Date.now(), result);
return cloneAndDeepFreeze(resolveCache!.value);
}
return cloneAndDeepFreeze(result);
}
interface AsyncRuntimeObservation {
readonly result: ResolveCodexRuntimeResult;
readonly inputs: string;
readonly epoch: number | null;
}
let asyncResolveInflight: { key: string; epoch: number; promise: Promise<AsyncRuntimeObservation> } | null = null;
/**
* resolveCodexRuntime for server request paths: same selection and process memo, but every
* `codex --version` runs through async exec. The sync resolver blocked the whole proxy for
* ~0.6s per memo expiry while the dashboard polled settings, stalling unrelated requests.
*/
export async function resolveCodexRuntimeAsync(
deps: ResolveCodexRuntimeDeps = {},
): Promise<ResolveCodexRuntimeResult> {
return cloneAndDeepFreeze((await resolveCodexRuntimeObservationAsync(deps)).result);
}
async function resolveCodexRuntimeObservationAsync(deps: ResolveCodexRuntimeDeps): Promise<AsyncRuntimeObservation> {
const inputs = codexRuntimeSelectionIdentity(deps);
const observed = (result: ResolveCodexRuntimeResult, epoch: number | null): AsyncRuntimeObservation => ({ result, inputs, epoch });
// A deferred selection never execs, so the sync path is already nonblocking.
if (deps.probeVersion === false) return observed(resolveCodexRuntime(deps), resolveCacheEpoch);
const cacheKey = resolveCacheKey({ ...deps, signal: undefined });
if (cacheKey && resolveCache && resolveCache.key === cacheKey && Date.now() - resolveCache.at < RESOLVE_CACHE_MS) {
return observed(cloneAndDeepFreeze(resolveCache.value), resolveCacheEpoch);
}
const startedEpoch = resolveCacheEpoch;
// A cancellable miss owns its probes; a warm memo remains usable without a new child.
if (!cacheKey || deps.signal) {
const result = await resolveCodexRuntimeUncachedAsync(deps);
const current = !deps.signal?.aborted && resolveCacheEpoch === startedEpoch
&& codexRuntimeSelectionIdentity(deps) === inputs;
if (current && cacheKey) publishResolveCache(cacheKey, Date.now(), result);
return observed(result, current ? resolveCacheEpoch : null);
}
if (asyncResolveInflight?.key === cacheKey && asyncResolveInflight.epoch === startedEpoch) {
return asyncResolveInflight.promise;
}
const promise = resolveCodexRuntimeUncachedAsync(deps).then(result => {
// A persist or clear while the probes ran makes this answer the previous selection's;
// publishing it would resurrect authority the write just revoked. Another process can also
// rewrite codex-runtime.json without touching this epoch, so the key is read again too.
if (resolveCacheEpoch === startedEpoch && resolveCacheKey(deps) === cacheKey) {
publishResolveCache(cacheKey, Date.now(), result);
return observed(result, resolveCacheEpoch);
}
return observed(result, null);
}).finally(() => {
if (asyncResolveInflight?.promise === promise) asyncResolveInflight = null;
});
asyncResolveInflight = { key: cacheKey, epoch: startedEpoch, promise };
return promise;
}
/**
* Stale-while-revalidate runtime read for hot UI paths; never waits on a probe.
*
* Returns the process memo when fresh, otherwise the last memo for the same inputs, and kicks
* resolveCodexRuntimeAsync to refresh it. With no memo yet (cold start, or right after a runtime
* switch cleared it) the answer is the exec-free deferred selection, so a version and
* newerAvailable appear once the first background refresh lands.
*/
export function getCodexRuntimeSnapshot(): ResolveCodexRuntimeResult {
const cacheKey = resolveCacheKey({});
const memo = resolveCache?.key === cacheKey ? resolveCache : null;
if (memo && Date.now() - memo.at < RESOLVE_CACHE_MS) return cloneAndDeepFreeze(memo.value);
// A passive read (a Remote Link Child's, #6959) starts no version probes on this machine.
if (!isPassiveRead()) resolveCodexRuntimeAsync().catch(() => { /* the next read retries */ });
if (memo) return cloneAndDeepFreeze(memo.value);
return resolveCodexRuntime({ discoverAlternatives: false, probeVersion: false });
}
/** Test-only: drop the short-lived process resolve cache. */
export function resetCodexRuntimeResolveCacheForTests(): void {
clearCodexRuntimeResolveCache();
}
/** Test-only owner mutation seam; input is cloned and frozen before publication. */
export function setCodexRuntimeResolveCacheForTests(
value: ResolveCodexRuntimeResult,
deps: ResolveCodexRuntimeDeps = {},
): void {
const key = resolveCacheKey(deps);
if (!key) throw new TypeError("Injected runtime dependencies cannot populate the process memo.");
publishResolveCache(key, Date.now(), value);
}
/**
* Candidate ranking and selection, written once for both drivers: each yield hands a candidate to
* the caller, which sends back its `--version` outcome. The sync driver keeps CLI behavior; the
* async one lets a server path resolve without blocking every other request on the probes.
*/
function* resolveCodexRuntimeSteps(
deps: ResolveCodexRuntimeDeps,
): Generator<RankedCandidate, ResolveCodexRuntimeResult, VersionProbeResult> {
const env = deps.env ?? process.env;
const failures: RuntimeProbeFailure[] = [];
const ordered: RankedCandidate[] = [];
const envPath = env.CODEX_CLI_PATH?.trim();
if (envPath) ordered.push({ command: envPath, source: "environment" });
const persisted = loadPersistedCodexRuntime(deps);
if (persisted?.command) {
ordered.push({ command: persisted.command, source: "configured" });
}
for (const command of shimCandidates(deps)) {
ordered.push({ command, source: "shim" });
}
for (const command of pathCandidates(deps)) {
ordered.push({ command, source: "path" });
}
const installed = installedCodexCandidates(deps);
// Order by the generated app commands only: an established install path that links into the
// app keeps its precedence, while identity and handover use the canonical classification.
const appCommands = new Set(macCodexAppCommands(deps));
const appCandidates = installed.filter(command => appCommands.has(command));
for (const command of installed.filter(command => !appCommands.has(command))) {
ordered.push({ command, source: "installed" });
}
ordered.push({ command: "codex", source: "fallback" });
for (const command of appCandidates) {
ordered.push({ command, source: "installed" });
}
const seen = new Set<string>();
const valid: ResolvedCodexRuntime[] = [];
const probedAppCommands = new Set<string>();
// A caller that declined PATH-wide discovery normally gets the first valid
// candidate and nothing else, which is right for a hot path and wrong for
// exactly one arrangement: an unpinned persisted selection sitting in front of
// a Codex App runtime that PATH never exposes.
//
// That arrangement is issue 4204. The catalog's bundled loader passes
// discoverAlternatives: false, so it stopped at a still-runnable codex-cli
// 0.135.0 and derived the reasoning ladder from it while the Desktop app was
// running 0.153.4 out of LOCALAPPDATA. Nothing downstream could notice,
// because the newer runtime was never probed.
//
// So the early stop keeps skipping PATH — which is the expensive part, 100+
// launcher probes on a dev machine — but still probes the `installed` roots,
// a bounded set with one entry per Codex App version directory. A pinned
// record skips even that: the operator's choice is not up for revision, and
// there is then nothing to compare it against.
const persistedIsUnpinned = Boolean(persisted?.command) && !persistedCodexRuntimeIsPinned(persisted);
for (const candidate of ordered) {
// Deferred resolution accepts the bare fallback without proving it exists; when a verified
// app CLI is present it must not preempt that app. Other platforms keep the old behaviour.
if (candidate.source === "fallback" && deps.probeVersion === false && appCandidates.length > 0) continue;
const key = candidate.command.toLowerCase();
if (seen.has(key)) continue;
seen.add(key);
if (
deps.discoverAlternatives === false
&& valid.length > 0
&& !(persistedIsUnpinned && candidate.source === "installed" && !macCodexAppBundleFor(candidate.command, deps))
) {
continue;
}
const probed: VersionProbeResult = yield candidate;
if (!probed.ok) {
failures.push({ command: candidate.command, source: candidate.source, reason: probed.reason });
continue;
}
valid.push({ command: candidate.command, version: probed.version, source: candidate.source });
// Keep the actual executed target's classification, including a bare PATH alias.
// Deferred candidates have no version and cannot trigger a version-based takeover.
if (probed.macAppBundle) probedAppCommands.add(candidate.command);
}
if (valid.length === 0) {
return {
runtime: { command: "codex", version: null, source: "fallback" },
failures,
};
}
// Prefer first valid in priority order (environment → configured → shim → path → installed → fallback).
let selected = valid[0]!;
let replacedConfigured: ResolveCodexRuntimeResult["replacedConfigured"];
let supersededDiscovered: ResolveCodexRuntimeResult["supersededDiscovered"];
const envValid = envPath
? valid.find(item => sameRuntimeCommand(item.command, envPath) && item.source === "environment")
: undefined;
if (envValid) selected = envValid;
if (persisted?.command) {
const configuredStillValid = valid.some(item => sameRuntimeCommand(item.command, persisted.command));
// Only emit replacement diagnostics when we actually searched alternatives or
// the preferred configured runtime was probed and rejected.
const configuredRejected = failures.some(item => sameRuntimeCommand(item.command, persisted.command));
if (!configuredStillValid && (configuredRejected || deps.discoverAlternatives !== false) && !envValid) {
replacedConfigured = {
from: {
command: persisted.command,
version: persisted.selectedVersion ?? null,
source: "configured",
},
reason: failures.find(item => sameRuntimeCommand(item.command, persisted.command))?.reason
?? "configured runtime is no longer valid",
};
// Keep priority-selected replacement (already in `selected`).
} else if (!envValid && configuredStillValid) {
// Stick to configured even when a later PATH entry is also valid.
selected = valid.find(item => sameRuntimeCommand(item.command, persisted.command)) ?? selected;
// An explicit pin is the user's decision and this change must never
// silently replace it — issue 4204 says so in as many words. Stick.
// An unpinned record (missing origin, or origin "discovered") may hand
// over to a strictly newer valid candidate. Unknown (null) versions on
// either side are not evidence of an upgrade: compareCodexVersions treats
// null as less-than, which would otherwise make any known alternative
// look newer than a deferred probe. probeVersion === false yields null
// everywhere, so the comparison cannot fire there; equal versions stick.
if (!persistedCodexRuntimeIsPinned(persisted)) {
const newerDiscovered = valid
.filter(item =>
!sameRuntimeCommand(item.command, selected.command)
&& !probedAppCommands.has(item.command)
&& typeof item.version === "string"
&& typeof selected.version === "string"
&& compareCodexVersions(item.version, selected.version) > 0)
.sort((a, b) => compareCodexVersions(b.version, a.version))[0];
if (newerDiscovered) {
supersededDiscovered = {
from: selected,
to: newerDiscovered,
reason: `discovered runtime ${selected.version} superseded by newer runtime ${newerDiscovered.version}`,
};
selected = newerDiscovered;
}
}
}
}
const newerAvailable = valid
.filter(item => !sameRuntimeCommand(item.command, selected.command))
.sort((a, b) => compareCodexVersions(b.version, a.version))[0];
const newer =
newerAvailable && compareCodexVersions(newerAvailable.version, selected.version) > 0
? newerAvailable
: undefined;
return {
runtime: selected,
failures,
replacedConfigured,
supersededDiscovered,
newerAvailable: newer,
};
}
function resolveCodexRuntimeUncached(deps: ResolveCodexRuntimeDeps = {}): ResolveCodexRuntimeResult {
const steps = resolveCodexRuntimeSteps(deps);
let step = steps.next();
while (!step.done) step = steps.next(probeVersion(step.value.command, deps));
return step.value;
}
async function resolveCodexRuntimeUncachedAsync(deps: ResolveCodexRuntimeDeps): Promise<ResolveCodexRuntimeResult> {
const steps = resolveCodexRuntimeSteps(deps);
let step = steps.next();
while (!step.done) {
if (deps.signal?.aborted) throw new Error("Codex runtime resolution aborted");
step = steps.next(await probeVersionAsync(step.value.command, deps));
}
return step.value;
}
/** Resolve and persist a successful selection (unless source is ephemeral fallback-only with no path). */
export function resolveAndPersistCodexRuntime(
deps: ResolveCodexRuntimeDeps = {},
): ResolveCodexRuntimeResult {
const result = resolveCodexRuntime(deps);
return persistResolvedCodexRuntime(result, deps);
}
/** Same selection/persistence as the CLI driver, with stale async results rejected. */
export async function resolveAndPersistCodexRuntimeAsync(
deps: ResolveCodexRuntimeDeps = {},
isCurrent: () => boolean = () => true,
): Promise<ResolveCodexRuntimeResult | null> {
if (deps.signal?.aborted) return null;
let observation: AsyncRuntimeObservation;
try { observation = await resolveCodexRuntimeObservationAsync(deps); }
catch (error) {
if (deps.signal?.aborted) return null;
throw error;
}
if (deps.signal?.aborted || !isCurrent() || observation.epoch === null || observation.epoch !== resolveCacheEpoch
|| observation.inputs !== codexRuntimeSelectionIdentity(deps)) return null;
if (deps.signal?.aborted) return null;
if (resolvedRuntimeMutation(observation.result, deps) === null) return cloneAndDeepFreeze(observation.result);
try {
return await withCodexCliSelectionParentWriteAsync(() => {
// Admission can await Windows ACL subprocesses. Re-prove all selection
// inputs after that await, in the same turn as the persisted mutation.
if (deps.signal?.aborted || !isCurrent() || observation.epoch !== resolveCacheEpoch
|| observation.inputs !== codexRuntimeSelectionIdentity(deps)) return null;
return cloneAndDeepFreeze(persistResolvedCodexRuntime(observation.result, deps));
}, deps);
} catch (error) {
if (deps.signal?.aborted) return null;
if (error instanceof CodexCliSelectionMutationBusyError) {
// A recovery denial also followed an await. Never return the obsolete
// selection as a usable result merely because no commit callback ran.
if (!isCurrent() || observation.epoch !== resolveCacheEpoch
|| observation.inputs !== codexRuntimeSelectionIdentity(deps)) return null;
if (observation.result.runtime.source !== "fallback") {
return cloneAndDeepFreeze({ ...observation.result, persistError: error.message });
}
}
throw error;
}
}
function resolvedRuntimeMutation(result: ResolveCodexRuntimeResult, deps: ResolveCodexRuntimeDeps): "persist" | "clear" | null {
const persisted = loadPersistedCodexRuntime(deps);
const unchanged = persisted !== null && persisted.command === result.runtime.command
&& persisted.source === result.runtime.source && (persisted.selectedVersion ?? null) === (result.runtime.version ?? null);
if (result.runtime.command && result.runtime.source !== "fallback" && !unchanged) return "persist";
if (result.runtime.source === "fallback" && persisted?.command && result.failures.some(failure =>
failure.command.trim() === persisted.command.trim() && failure.reason === PATH_MISSING_REASON)) return "clear";
return null;
}
function persistResolvedCodexRuntime(
result: ResolveCodexRuntimeResult,
deps: ResolveCodexRuntimeDeps,
): ResolveCodexRuntimeResult {
// Only WRITE when the selection actually changed. persistCodexRuntime() clears the
// in-process resolve memo and persistedRuntimeCacheStamp() folds `updatedAt` into the
// cache key, so an unconditional rewrite made every caller re-run the ~1s
// `codex --version` probe even when the resolved runtime was byte-identical.
const persistedRuntime = loadPersistedCodexRuntime(deps);
const selectionUnchanged = persistedRuntime !== null
&& persistedRuntime.command === result.runtime.command
&& persistedRuntime.source === result.runtime.source
&& (persistedRuntime.selectedVersion ?? null) === (result.runtime.version ?? null);
if (result.runtime.command && result.runtime.source !== "fallback" && !selectionUnchanged) {
try {
persistCodexRuntime(result.runtime, deps, "discovered");
} catch (error) {
const message = error instanceof Error ? error.message : String(error);
const persistError = redactUserPath(redactSecretString(message)).slice(0, 200);
console.warn(`[opencodex] Failed to persist Codex runtime selection: ${persistError}`);
return cloneAndDeepFreeze({ ...result, persistError });
}
}
// A pin whose path has vanished must be RETIRED, not merely skipped. A Codex App update
// replaces the hashed plugin directory the pin names, the probe rejects it with
// "path does not exist", nothing else resolves, and the selection degrades to `fallback` —
// which the write guard above declines. The dead entry then survived every later resolve
// and each one re-probed a path that cannot exist (#4035). Bound narrowly: only when the
// degraded result is `fallback`, only for the persisted command, and only for the
// path-does-not-exist rejection, so a present-but-unusable binary is left for the operator.
else if (result.runtime.source === "fallback" && persistedRuntime?.command) {
const pinVanished = result.failures.some(
// Exact comparison, not `sameRuntimeCommand`: that helper lowercases, and on a
// case-sensitive filesystem `/plugins/Codex` and `/plugins/codex` are different
// files. A missing lowercase path must not retire a live uppercase pin.
failure => failure.command.trim() === persistedRuntime.command.trim()
&& failure.reason === PATH_MISSING_REASON,
);
if (pinVanished) clearPersistedCodexRuntime(deps);
}
return result;
}
export function formatRuntimeLogLine(runtime: ResolvedCodexRuntime): string {
const path = displayCodexRuntimePath(runtime.command);
return `[opencodex] Codex runtime: ${path} (version=${runtime.version ?? "unknown"}, source=${runtime.source})`;
}
export function formatClampLogLines(diagnostic: EffortClampDiagnostic): string[] {
const efforts = diagnostic.removedEfforts.join(", ");
return [
`[opencodex] Removed unsupported reasoning efforts: ${efforts}`,
];
}