import { execFile, execFileSync } from "node:child_process";
import { existsSync, mkdirSync, mkdtempSync, readFileSync, 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 { codexExecInvocation, isSpawnableCodexCandidate } from "./exec-invocation";
import { resolveCodexHomeDir } from "./home";
import { redactSecretString, redactUserPath } from "../lib/redact";

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[];
}

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;
  },
) => string;

/** Async twin of RuntimeExecFile, used by resolveCodexRuntimeAsync; resolves with stdout. */
export type RuntimeExecFileAsync = (
  ...args: Parameters<RuntimeExecFile>
) => Promise<string>;

export interface ResolveCodexRuntimeDeps {
  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;
  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;
  }
}

export function persistEffortClamp(
  diagnostic: EffortClampDiagnostic | null,
  deps: ResolveCodexRuntimeDeps = {},
): void {
  const configDir = deps.configDir ?? getConfigDir();
  const path = codexRuntimeClampStatePath(configDir);
  if (!diagnostic || diagnostic.removedEfforts.length === 0) {
    try {
      unlinkSync(path);
    } catch {
      /* absent is fine */
    }
    return;
  }
  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`);
}

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 {
  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`);
}

/**
 * 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 {
  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.`,
    );
  }
}

type VersionProbeResult = { ok: true; version: string | null } | { 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 (deps.probeVersion === false) return { ok: true, version: null };
  return null;
}

function versionProbeInvocation(command: string, deps: ResolveCodexRuntimeDeps, probeHome: string) {
  const invocation = codexExecInvocation(command, ["--version"], deps.platform ?? process.platform, {
    env: deps.env,
    exists: deps.existsSync,
  });
  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): VersionProbeResult {
  const version = parseCodexVersionOutput(output);
  if (!version) return { ok: false, reason: "unrecognized --version output" };
  return { ok: true, version };
}

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 { file, args, options } = versionProbeInvocation(command, deps, probeHome);
    return versionProbeOutput(exec(file, args, options));
  } catch (error) {
    return versionProbeError(error, probeHome);
  } finally {
    removeProbeHome(probeHome);
  }
}

const defaultExecFileAsync: RuntimeExecFileAsync = (file, args, options) =>
  new Promise((resolve, reject) => {
    // execFile always pipes stdout/stderr; it takes no stdio option.
    const { stdio: _stdio, ...execOptions } = options;
    execFile(file, args, execOptions, (error, stdout) => (error ? reject(error) : resolve(String(stdout))));
  });

/** 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 ?? defaultExecFileAsync;
  let probeHome: string | undefined;
  try {
    probeHome = mkdtempSync(join(tmpdir(), "ocx-codex-probe-"));
    const { file, args, options } = versionProbeInvocation(command, deps, probeHome);
    return versionProbeOutput(await exec(file, args, options));
  } catch (error) {
    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 {
      wrapperPath?: unknown;
      originalPath?: unknown;
      backupPath?: unknown;
      wrappers?: Array<{ wrapperPath?: unknown; originalPath?: unknown; backupPath?: unknown }>;
    };
    const files = Array.isArray(state.wrappers) && state.wrappers.length > 0 ? state.wrappers : [state];
    const out: string[] = [];
    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)];
}

/**
 * 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 !== "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 {
    const raw = parsePersistedCodexRuntime(read(codexRuntimeStatePath(configDir), "utf8"));
    if (!raw) return "";
    return `${raw.command}|${raw.selectedVersion ?? ""}|${raw.updatedAt ?? ""}`;
  } catch {
    return "";
  }
}

function resolveCacheKey(deps: ResolveCodexRuntimeDeps): string | null {
  // Only memoize uninjected process-env resolves (settings/status hot paths).
  if (
    deps.execFileSync
    || deps.execFile
    || deps.existsSync
    || deps.readFileSync
    || deps.readdirSync
    || deps.statSync
    || deps.configDir
    || deps.now
  ) {
    return null;
  }
  const env = deps.env ?? process.env;
  return JSON.stringify({
    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);
}

let asyncResolveInflight: { key: string; epoch: number; promise: Promise<ResolveCodexRuntimeResult> } | 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> {
  // A deferred selection never execs, so the sync path is already nonblocking.
  if (deps.probeVersion === false) return resolveCodexRuntime(deps);
  const cacheKey = resolveCacheKey(deps);
  if (cacheKey && resolveCache && resolveCache.key === cacheKey && Date.now() - resolveCache.at < RESOLVE_CACHE_MS) {
    return cloneAndDeepFreeze(resolveCache.value);
  }
  if (!cacheKey) return cloneAndDeepFreeze(await resolveCodexRuntimeUncachedAsync(deps));
  const startedEpoch = resolveCacheEpoch;
  if (asyncResolveInflight?.key === cacheKey && asyncResolveInflight.epoch === startedEpoch) {
    return cloneAndDeepFreeze(await 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 result;
  }).finally(() => {
    if (asyncResolveInflight?.promise === promise) asyncResolveInflight = null;
  });
  asyncResolveInflight = { key: cacheKey, epoch: startedEpoch, promise };
  return cloneAndDeepFreeze(await 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);
  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" });
  }
  for (const command of installedCodexCandidates(deps)) {
    ordered.push({ command, source: "installed" });
  }
  ordered.push({ command: "codex", source: "fallback" });

  const seen = new Set<string>();
  const valid: ResolvedCodexRuntime[] = [];
  // 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) {
    const key = candidate.command.toLowerCase();
    if (seen.has(key)) continue;
    seen.add(key);
    if (
      deps.discoverAlternatives === false
      && valid.length > 0
      && !(persistedIsUnpinned && candidate.source === "installed")
    ) {
      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 });
  }

  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)
            && 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) 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);
  // 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}`,
    "[opencodex] Run ocx doctor for diagnosis and recovery.",
  ];
}
