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}`,
  ];
}
