@iislee/opencodex 2.11.0

package/src/codex/shim.ts

@@ -0,0 +1,1189 @@
+import { randomUUID } from "node:crypto";
+import { delimiter, dirname, extname, join, posix } from "node:path";
+import {
+  chmodSync,
+  closeSync,
+  existsSync,
+  fstatSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  readSync,
+  renameSync,
+  rmdirSync,
+  statSync,
+  type Stats,
+  unlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { getConfigDir } from "../config";
+import { durableBunPath } from "../lib/bun-runtime";
+import { isProcessAlive } from "../lib/process-control";
+import { serviceApiTokenFilePath } from "../lib/service-secrets";
+import { recordOwnedConfigPath } from "../lib/config-ownership";
+import { windowsEnvIndirectBatchValue } from "../lib/win-paths";
+import { isWslRuntime, wslAutomountRoot } from "./home";
+import { truncateRetainedUtf8 } from "../lib/admission";
+
+const SHIM_MARKER = "opencodex codex autostart shim";
+const CODEX_SHIM_PROBE_BYTES = 16 * 1024;
+export const CODEX_SHIM_REPLACEMENT_STABLE_MS = 100;
+export const CODEX_SHIM_STATE_MAX_BYTES = 1024 * 1024;
+const CODEX_SHIM_RESTORE_LOCK_STALE_MS = 30_000;
+const MAX_DIAGNOSTIC_VALUE_BYTES = 8 * 1024;
+let lastShimDiscoveryError: string | null = null;
+/** Last human-readable reason discovery returned null (exposed for doctor/tests). */
+export function lastCodexDiscoveryError(): string | null {
+  return lastShimDiscoveryError;
+}
+const CODEX_INTERNAL_COMMANDS = [
+  "app-server",
+  "archive",
+  "apply",
+  "cloud",
+  "completion",
+  "debug",
+  "delete",
+  "doctor",
+  "exec-server",
+  "features",
+  "fork",
+  "help",
+  "login",
+  "logout",
+  "mcp",
+  "plugin",
+  "sandbox",
+  "unarchive",
+  "update",
+];
+
+// Codex accepts global options before a subcommand. The shim must skip the value belonging to
+// these options before it decides which first positional token is the real subcommand. Keep this
+// list aligned with `codex --help`; `--option=value` and attached short forms stay one token.
+const CODEX_GLOBAL_OPTIONS_WITH_VALUE = [
+  "-c", "--config",
+  "--enable", "--disable",
+  "--remote", "--remote-auth-token-env",
+  "-i", "--image",
+  "-m", "--model",
+  "--local-provider",
+  "-p", "--profile",
+  "-s", "--sandbox",
+  "-C", "--cd",
+  "--add-dir",
+  "-a", "--ask-for-approval",
+];
+
+interface ShimState {
+  platform: NodeJS.Platform;
+  wrapperPath: string;
+  originalPath: string;
+  backupPath: string;
+  wrappers?: ShimFileState[];
+}
+
+interface ShimFileState {
+  wrapperPath: string;
+  originalPath: string;
+  backupPath: string;
+  realPath?: string;
+  preserveOnly?: boolean;
+}
+
+interface ShimPathFingerprint {
+  dev: number;
+  ino: number;
+  kind: "file" | "symlink";
+  mode: number;
+  size: number;
+  mtimeMs: number;
+  ctimeMs: number;
+  target?: Omit<ShimPathFingerprint, "target">;
+}
+
+interface StableShimPathProbe {
+  fingerprint: ShimPathFingerprint;
+  prefix: string;
+}
+
+interface InstallCodexShimInternalOptions {
+  expectedReplacements?: ReadonlyMap<string, ShimPathFingerprint>;
+  allowFreshInstall: boolean;
+  beforeGuardedRefresh?: (wrapperPath: string, index: number) => void;
+}
+
+export type CodexShimAutoRestoreResult =
+  | { status: "not-installed" | "healthy" | "disabled" }
+  | { status: "ineligible" | "deferred"; message?: string }
+  | { status: "restored"; message: string };
+
+function cliEntry(): { bun: string; cli: string } {
+  // Bundled Bun path (survives `ocx update`); all three shim builders
+  // (Unix / Windows cmd / Windows PowerShell) receive it via this entry.
+  // This module lives in src/codex/, the CLI entry in src/cli/index.ts.
+  return { bun: durableBunPath(), cli: join(import.meta.dir, "..", "cli", "index.ts") };
+}
+
+function commandNames(name: string): string[] {
+  if (process.platform !== "win32") return [name];
+  const exts = (process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD;.PS1").split(";").filter(Boolean);
+  return [name, ...exts.flatMap(ext => [`${name}${ext.toLowerCase()}`, `${name}${ext.toUpperCase()}`])];
+}
+
+function isShim(path: string): boolean {
+  try {
+    return readFileSync(path, "utf8").includes(SHIM_MARKER);
+  } catch {
+    return false;
+  }
+}
+
+function isHealthyShim(path: string, platform: NodeJS.Platform): boolean {
+  try {
+    const content = readFileSync(path, "utf8");
+    if (content.length < 180 || !content.includes(SHIM_MARKER) || !content.includes("ensure")) return false;
+    if (platform !== "win32" && (lstatSync(path).mode & 0o111) === 0) return false;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readShimProbePrefix(path: string): string {
+  const fd = openSync(path, "r");
+  try {
+    const buffer = Buffer.allocUnsafe(CODEX_SHIM_PROBE_BYTES);
+    const bytesRead = readSync(fd, buffer, 0, buffer.length, 0);
+    return buffer.toString("utf8", 0, bytesRead);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function statFingerprint(path: string, follow: boolean): Omit<ShimPathFingerprint, "target"> | null {
+  try {
+    const stat = follow ? statSync(path) : lstatSync(path);
+    if (follow ? !stat.isFile() : (!stat.isFile() && !stat.isSymbolicLink())) return null;
+    return {
+      dev: stat.dev,
+      ino: stat.ino,
+      kind: stat.isSymbolicLink() ? "symlink" : "file",
+      mode: stat.mode,
+      size: stat.size,
+      mtimeMs: stat.mtimeMs,
+      ctimeMs: stat.ctimeMs,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function sameFingerprint(
+  left: ShimPathFingerprint | Omit<ShimPathFingerprint, "target">,
+  right: ShimPathFingerprint | Omit<ShimPathFingerprint, "target">,
+): boolean {
+  return left.dev === right.dev
+    && left.ino === right.ino
+    && left.kind === right.kind
+    && left.mode === right.mode
+    && left.size === right.size
+    && left.mtimeMs === right.mtimeMs
+    && left.ctimeMs === right.ctimeMs
+    && (!("target" in left) || !("target" in right)
+      ? true
+      : left.target === undefined && right.target === undefined
+        ? true
+        : left.target !== undefined && right.target !== undefined
+          ? sameFingerprint(left.target, right.target)
+          : false);
+}
+
+function stableShimPathProbe(path: string): StableShimPathProbe | null {
+  const before = statFingerprint(path, false);
+  if (!before) return null;
+  const targetBefore = before.kind === "symlink" ? statFingerprint(path, true) : undefined;
+  if (before.kind === "symlink" && !targetBefore) return null;
+  let prefix: string;
+  try {
+    prefix = readShimProbePrefix(path);
+  } catch {
+    return null;
+  }
+  const targetAfter = before.kind === "symlink" ? statFingerprint(path, true) : undefined;
+  const after = statFingerprint(path, false);
+  if (!after || !sameFingerprint(before, after)) return null;
+  if (before.kind === "symlink") {
+    if (!targetBefore || !targetAfter || !sameFingerprint(targetBefore, targetAfter)) return null;
+  }
+  const fingerprint: ShimPathFingerprint = {
+    ...before,
+    ...(targetBefore ? { target: targetBefore } : {}),
+  };
+  const contentSize = fingerprint.target?.size ?? fingerprint.size;
+  return contentSize > 0 ? { fingerprint, prefix } : null;
+}
+
+function sameStableShimPathProbe(left: StableShimPathProbe, right: StableShimPathProbe): boolean {
+  return left.prefix === right.prefix && sameFingerprint(left.fingerprint, right.fingerprint);
+}
+
+function isHealthyShimProbe(probe: StableShimPathProbe, platform: NodeJS.Platform): boolean {
+  if (probe.prefix.length < 180 || !probe.prefix.includes(SHIM_MARKER) || !probe.prefix.includes("ensure")) return false;
+  const mode = probe.fingerprint.target?.mode ?? probe.fingerprint.mode;
+  return platform === "win32" || (mode & 0o111) !== 0;
+}
+
+function hasUsableBackingPath(file: ShimFileState): boolean {
+  return [existsSync(file.backupPath) ? file.backupPath : undefined, file.realPath]
+    .some(path => {
+      if (!path) return false;
+      const fingerprint = statFingerprint(path, true);
+      return fingerprint !== null && fingerprint.size > 0;
+    });
+}
+
+/**
+ * A PATH entry that reaches Windows through WSL drive interop
+ * (`<automount-root>/<drive>/...`; root defaults to /mnt, configurable via
+ * /etc/wsl.conf [automount] root).
+ */
+export function isWindowsInteropDir(dir: string, automountRoot = "/mnt"): boolean {
+  const root = automountRoot.replace(/\/+$/, "");
+  const escaped = root.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  return new RegExp(`^${escaped}/[a-z](/|$)`, "i").test(dir);
+}
+
+export type CodexPathScanDeps = {
+  pathValue?: string;
+  wsl?: boolean;
+  /** Treat PATH entries as POSIX paths (WSL context). Defaults to wsl || non-win32. */
+  posixPaths?: boolean;
+  automountRoot?: string;
+  exists?: (path: string) => boolean;
+  isShimFile?: (path: string) => boolean;
+  isDirectory?: (path: string) => boolean;
+};
+
+function realIsDirectory(path: string): boolean {
+  try {
+    return lstatSync(path).isDirectory();
+  } catch {
+    return true; // unreadable -> treat as unusable
+  }
+}
+
+export function findCodexOnPath(deps: CodexPathScanDeps = {}): string | null {
+  lastShimDiscoveryError = null;
+  const exists = deps.exists ?? existsSync;
+  const shimFile = deps.isShimFile ?? isShim;
+  const isDir = deps.isDirectory ?? realIsDirectory;
+  const wsl = deps.wsl ?? (process.platform === "linux" && isWslRuntime());
+  const usePosix = deps.posixPaths ?? (wsl || process.platform !== "win32");
+  const joinPath = usePosix ? posix.join : join;
+  const pathSep = usePosix ? ":" : delimiter;
+  const automountRoot = deps.automountRoot ?? (wsl ? wslAutomountRoot() : "/mnt");
+  // Windows npm prefixes ship codex.exe/codex.cmd next to the extensionless sh launcher.
+  const interopNames = ["codex", "codex.exe", "codex.cmd", "codex.ps1"];
+  let skippedInterop: string | null = null;
+
+  for (const dir of (deps.pathValue ?? process.env.PATH ?? "").split(pathSep).filter(Boolean)) {
+    if (wsl && isWindowsInteropDir(dir, automountRoot)) {
+      // A Windows-side codex reached through WSL PATH interop: a Unix shim written
+      // here would embed WSL-only paths and break every Windows-side invocation.
+      if (!skippedInterop) {
+        for (const name of interopNames) {
+          const path = joinPath(dir, name);
+          if (exists(path) && !shimFile(path) && !isDir(path)) { skippedInterop = path; break; }
+        }
+      }
+      continue;
+    }
+    // Interop dirs carry Windows launcher names even when the scan is not skipping them.
+    const names = isWindowsInteropDir(dir, automountRoot) ? interopNames : commandNames("codex");
+    for (const name of names) {
+      const path = joinPath(dir, name);
+      if (!exists(path) || shimFile(path)) continue;
+      if (!isDir(path)) return path;
+    }
+  }
+
+  if (skippedInterop) {
+    lastShimDiscoveryError = truncateRetainedUtf8(
+      `Found a Windows codex at ${skippedInterop} via WSL PATH interop, but no Linux-side codex. ` +
+      "Refusing to shim a Windows launcher from WSL (a WSL shim breaks Windows invocations). " +
+      "Install codex inside WSL (npm i -g @openai/codex), or run 'ocx ensure' from Windows to shim the Windows side.",
+      MAX_DIAGNOSTIC_VALUE_BYTES,
+    );
+  }
+  return null;
+}
+
+function findWindowsCodexTargets(): ShimFileState[] | null {
+  lastShimDiscoveryError = null;
+  for (const dir of (process.env.PATH ?? "").split(delimiter).filter(Boolean)) {
+    const exe = join(dir, "codex.exe");
+    if (existsSync(exe) && !isShim(exe)) {
+      try {
+        if (!lstatSync(exe).isDirectory()) {
+          lastShimDiscoveryError = truncateRetainedUtf8(
+            `Found codex.exe at ${exe}. Refusing to rename a real .exe because exact codex.exe invocations would break; ` +
+            "install a codex.cmd/codex.ps1 launcher or use `ocx service install` for autostart.",
+            MAX_DIAGNOSTIC_VALUE_BYTES,
+          );
+          return null;
+        }
+      } catch { /* keep scanning */ }
+    }
+
+    const cmd = join(dir, "codex.cmd");
+    const ps1 = join(dir, "codex.ps1");
+    // npm also installs an extensionless `codex` sh launcher for Git-Bash/MSYS shells;
+    // leaving it unshimmed means Git-Bash users silently get no autostart.
+    const gitBashLauncher = join(dir, "codex");
+    const targets: ShimFileState[] = [];
+    for (const path of [cmd, ps1, gitBashLauncher]) {
+      if (!existsSync(path) || isShim(path)) continue;
+      try {
+        if (!lstatSync(path).isDirectory()) {
+          targets.push({ wrapperPath: path, originalPath: path, backupPath: backupPathFor(path) });
+        }
+      } catch { /* keep scanning */ }
+    }
+    if (targets.length > 0) return targets;
+  }
+  return null;
+}
+
+function backupPathFor(path: string): string {
+  const ext = extname(path);
+  return ext ? `${path.slice(0, -ext.length)}.opencodex-real${ext}` : `${path}.opencodex-real`;
+}
+
+function shQuote(value: string): string {
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+
+export function buildUnixCodexShim(realCodexPath: string, bunPath: string, cliPath: string, tokenFile = serviceApiTokenFilePath()): string {
+  const internalCommands = CODEX_INTERNAL_COMMANDS.join("|");
+  const valueOptions = CODEX_GLOBAL_OPTIONS_WITH_VALUE.join("|");
+  return `#!/usr/bin/env sh
+# ${SHIM_MARKER}
+if [ -z "$OPENCODEX_API_AUTH_TOKEN" ] && [ -f ${shQuote(tokenFile)} ]; then
+  OPENCODEX_API_AUTH_TOKEN="$(cat ${shQuote(tokenFile)})"
+  export OPENCODEX_API_AUTH_TOKEN
+fi
+ocx_subcommand=""
+ocx_skip_next=0
+for ocx_arg in "$@"; do
+  if [ "$ocx_skip_next" -eq 1 ]; then
+    ocx_skip_next=0
+    continue
+  fi
+  case "$ocx_arg" in
+    --)
+      break
+      ;;
+    ${valueOptions})
+      ocx_skip_next=1
+      ;;
+    --help|-h|--version|-V)
+      ocx_subcommand="$ocx_arg"
+      break
+      ;;
+    -*)
+      ;;
+    *)
+      ocx_subcommand="$ocx_arg"
+      break
+      ;;
+  esac
+done
+case "$ocx_subcommand" in
+  ${internalCommands}|--help|-h|--version|-V)
+    ;;
+  *)
+    if [ -z "$OCX_SHIM_BYPASS" ]; then
+      ${shQuote(bunPath)} ${shQuote(cliPath)} ensure >/dev/null 2>&1 || true
+    fi
+    ;;
+esac
+exec ${shQuote(realCodexPath)} "$@"
+`;
+}
+
+function windowsBatchValue(value: string): string {
+  return value
+    .replace(/%/g, "%%")
+    .replace(/\^/g, "^^")
+    .replace(/"/g, "")
+    .replace(/[\r\n]/g, "");
+}
+
+function windowsBatchSet(name: string, value: string): string {
+  // Paths are rewritten to %USERPROFILE%-style env indirection: cmd.exe parses .cmd
+  // files in the OEM codepage, so a literal non-ASCII profile prefix (Korean/Chinese
+  // usernames) written as UTF-8 turns to mojibake. The env token expands natively in
+  // the right codepage at parse time; no `chcp` here — this shim runs in the USER's
+  // console and must not leak a codepage change into it.
+  return `set "${name}=${windowsEnvIndirectBatchValue(value, windowsBatchValue)}"`;
+}
+
+export function buildWindowsCodexShim(realCodexPath: string, bunPath: string, cliPath: string): string {
+  const internalCommandChecks = CODEX_INTERNAL_COMMANDS.map(command => `if /I "%~1"=="${command}" goto run_codex`).join("\r\n");
+  const valueOptionChecks = CODEX_GLOBAL_OPTIONS_WITH_VALUE.map(option => `if /I "%~1"=="${option}" goto skip_option_value`).join("\r\n");
+  return `@echo off\r
+rem ${SHIM_MARKER}\r
+${windowsBatchSet("OCX_REAL_CODEX", realCodexPath)}\r
+${windowsBatchSet("OCX_BUN", bunPath)}\r
+${windowsBatchSet("OCX_CLI", cliPath)}\r
+${windowsBatchSet("OCX_API_TOKEN_FILE", serviceApiTokenFilePath())}\r
+if "%OPENCODEX_API_AUTH_TOKEN%"=="" if exist "%OCX_API_TOKEN_FILE%" set /p OPENCODEX_API_AUTH_TOKEN=<"%OCX_API_TOKEN_FILE%"\r
+if not "%OCX_SHIM_BYPASS%"=="" goto run_codex\r
+goto scan_codex_args\r
+:scan_codex_args\r
+if "%~1"=="" goto ensure_ocx\r
+if "%~1"=="--" goto ensure_ocx\r
+${valueOptionChecks}\r
+${internalCommandChecks}\r
+if /I "%~1"=="--help" goto run_codex\r
+if /I "%~1"=="-h" goto run_codex\r
+if /I "%~1"=="--version" goto run_codex\r
+if /I "%~1"=="-V" goto run_codex\r
+set "OCX_SCAN_ARG=%~1"\r
+if "%OCX_SCAN_ARG:~0,1%"=="-" goto shift_codex_arg\r
+goto ensure_ocx\r
+:skip_option_value\r
+shift\r
+if "%~1"=="" goto ensure_ocx\r
+:shift_codex_arg\r
+shift\r
+goto scan_codex_args\r
+:ensure_ocx\r
+"%OCX_BUN%" "%OCX_CLI%" ensure >nul 2>nul\r
+:run_codex\r
+"%OCX_REAL_CODEX%" %*\r
+`;
+}
+
+function psString(value: string): string {
+  return `'${value.replace(/'/g, "''")}'`;
+}
+
+export function buildWindowsPowerShellCodexShim(realCodexPath: string, bunPath: string, cliPath: string): string {
+  const internalCommands = CODEX_INTERNAL_COMMANDS.map(command => psString(command)).join(", ");
+  const valueOptions = CODEX_GLOBAL_OPTIONS_WITH_VALUE.map(option => psString(option)).join(", ");
+  const tokenFile = serviceApiTokenFilePath();
+  return `#!/usr/bin/env pwsh
+# ${SHIM_MARKER}
+if (-not $env:OPENCODEX_API_AUTH_TOKEN -and (Test-Path -LiteralPath ${psString(tokenFile)})) {
+  $env:OPENCODEX_API_AUTH_TOKEN = (Get-Content -Raw -LiteralPath ${psString(tokenFile)}).Trim()
+}
+$internalCommands = @(${internalCommands})
+$valueOptions = @(${valueOptions})
+$subcommand = ""
+$skipNext = $false
+foreach ($argValue in $args) {
+  $argText = [string]$argValue
+  if ($skipNext) { $skipNext = $false; continue }
+  if ($argText -eq "--") { break }
+  if ($valueOptions -contains $argText) { $skipNext = $true; continue }
+  if (@("--help", "-h", "--version", "-V") -contains $argText) { $subcommand = $argText; break }
+  if ($argText.StartsWith("-")) { continue }
+  $subcommand = $argText
+  break
+}
+$skipEnsure = $env:OCX_SHIM_BYPASS -or $internalCommands -contains $subcommand -or @("--help", "-h", "--version", "-V") -contains $subcommand
+if (-not $skipEnsure) {
+  & ${psString(bunPath)} ${psString(cliPath)} ensure *> $null
+}
+& ${psString(realCodexPath)} @args
+exit $LASTEXITCODE
+`;
+}
+
+interface ShimStateReadResult {
+  state: ShimState | null;
+  warning?: string;
+}
+
+function fileErrorCode(error: unknown): string | undefined {
+  return error && typeof error === "object" && "code" in error
+    ? String((error as { code?: unknown }).code)
+    : undefined;
+}
+
+function readBoundedRegularFile(path: string, maxBytes: number): { content: string } | { warning: string } | null {
+  let fd: number;
+  try {
+    fd = openSync(path, "r");
+  } catch (error) {
+    if (fileErrorCode(error) === "ENOENT") return null;
+    return { warning: `Codex shim state could not be opened as a regular file at ${path}.` };
+  }
+  try {
+    const before = fstatSync(fd);
+    if (!before.isFile()) return { warning: `Codex shim state is not a regular file at ${path}; auto-restore skipped.` };
+    if (before.size > maxBytes) {
+      return { warning: `Codex shim state exceeds the 1 MiB startup limit at ${path}; auto-restore skipped.` };
+    }
+    const buffer = Buffer.allocUnsafe(before.size);
+    let offset = 0;
+    while (offset < buffer.length) {
+      const bytesRead = readSync(fd, buffer, offset, buffer.length - offset, offset);
+      if (bytesRead === 0) return { warning: `Codex shim state changed while being read at ${path}; auto-restore skipped.` };
+      offset += bytesRead;
+    }
+    const extra = Buffer.allocUnsafe(1);
+    if (readSync(fd, extra, 0, 1, offset) !== 0) {
+      return { warning: `Codex shim state exceeds the 1 MiB startup limit at ${path}; auto-restore skipped.` };
+    }
+    const after = fstatSync(fd);
+    if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size
+      || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs) {
+      return { warning: `Codex shim state changed while being read at ${path}; auto-restore skipped.` };
+    }
+    return { content: buffer.toString("utf8") };
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function readStateResult(): ShimStateReadResult {
+  const bounded = readBoundedRegularFile(statePath(), CODEX_SHIM_STATE_MAX_BYTES);
+  if (!bounded) return { state: null };
+  if ("warning" in bounded) return { state: null, warning: bounded.warning };
+  try {
+    const value = JSON.parse(bounded.content) as unknown;
+    if (!value || typeof value !== "object") return { state: null };
+    const state = value as Record<string, unknown>;
+    if (typeof state.platform !== "string") return { state: null };
+    const validFile = (item: unknown): item is ShimFileState => {
+      if (!item || typeof item !== "object") return false;
+      const file = item as Record<string, unknown>;
+      return typeof file.wrapperPath === "string"
+        && typeof file.originalPath === "string"
+        && typeof file.backupPath === "string"
+        && (file.realPath === undefined || typeof file.realPath === "string")
+        && (file.preserveOnly === undefined || typeof file.preserveOnly === "boolean");
+    };
+    if (state.wrappers !== undefined) {
+      if (!Array.isArray(state.wrappers) || state.wrappers.length === 0 || !state.wrappers.every(validFile)) return { state: null };
+    } else if (!validFile(state)) {
+      return { state: null };
+    }
+    return { state: state as unknown as ShimState };
+  } catch {
+    return { state: null };
+  }
+}
+
+function readState(): ShimState | null {
+  return readStateResult().state;
+}
+
+function statePath(): string {
+  return join(getConfigDir(), "codex-shim.json");
+}
+
+function writeState(state: ShimState): void {
+  const path = statePath();
+  recordOwnedConfigPath(getConfigDir(), path);
+  if (!existsSync(getConfigDir())) mkdirSync(getConfigDir(), { recursive: true });
+  writeFileSync(path, JSON.stringify(state, null, 2) + "\n", "utf8");
+}
+
+/** Git-Bash accepts `C:/...` but not backslashed paths inside sh scripts. */
+function gitBashPath(path: string): string {
+  return path.replace(/\\/g, "/");
+}
+
+function writeShim(wrapperPath: string, realCodexPath: string): void {
+  const { bun, cli } = cliEntry();
+  if (process.platform === "win32") {
+    const lower = wrapperPath.toLowerCase();
+    if (lower.endsWith(".ps1")) {
+      // UTF-8 BOM: Windows PowerShell 5.1 decodes BOM-less .ps1 files in the ANSI
+      // codepage, which mangles non-ASCII paths embedded in the shim.
+      writeFileSync(wrapperPath, `\uFEFF${buildWindowsPowerShellCodexShim(realCodexPath, bun, cli)}`, "utf8");
+    } else if (lower.endsWith(".cmd") || lower.endsWith(".bat")) {
+      writeFileSync(wrapperPath, buildWindowsCodexShim(realCodexPath, bun, cli), "utf8");
+    } else {
+      // Extensionless Git-Bash sh launcher: sh shim with forward-slash paths.
+      writeFileSync(
+        wrapperPath,
+        buildUnixCodexShim(gitBashPath(realCodexPath), gitBashPath(bun), gitBashPath(cli), gitBashPath(serviceApiTokenFilePath())),
+        "utf8",
+      );
+    }
+  } else {
+    writeFileSync(wrapperPath, buildUnixCodexShim(realCodexPath, bun, cli), "utf8");
+    chmodSync(wrapperPath, 0o755);
+  }
+}
+
+function stateFiles(state: ShimState): ShimFileState[] {
+  return state.wrappers?.length
+    ? state.wrappers
+    : [{ wrapperPath: state.wrapperPath, originalPath: state.originalPath, backupPath: state.backupPath }];
+}
+
+function primaryState(files: ShimFileState[]): ShimState {
+  const first = files[0];
+  return { platform: process.platform, ...first, wrappers: files };
+}
+
+function replaceOwnedBackup(sourcePath: string, backupPath: string): void {
+  const oldBackupPath = `${backupPath}.old-${process.pid}`;
+  if (existsSync(oldBackupPath)) unlinkSync(oldBackupPath);
+  if (existsSync(backupPath)) renameSync(backupPath, oldBackupPath);
+  try {
+    renameSync(sourcePath, backupPath);
+    if (existsSync(oldBackupPath)) unlinkSync(oldBackupPath);
+  } catch (error) {
+    if (!existsSync(backupPath) && existsSync(oldBackupPath)) renameSync(oldBackupPath, backupPath);
+    throw error;
+  }
+}
+
+function refreshShimFile(file: ShimFileState): boolean {
+  if (file.preserveOnly) {
+    if (existsSync(file.originalPath) && !isShim(file.originalPath)) {
+      replaceOwnedBackup(file.originalPath, file.backupPath);
+      return true;
+    }
+    return false;
+  }
+  if (existsSync(file.wrapperPath) && !isShim(file.wrapperPath)) {
+    if (file.wrapperPath !== file.originalPath) return false;
+    replaceOwnedBackup(file.wrapperPath, file.backupPath);
+    writeShim(file.wrapperPath, file.realPath ?? file.backupPath);
+    return true;
+  }
+  if (!existsSync(file.wrapperPath) && existsSync(file.backupPath)) {
+    writeShim(file.wrapperPath, file.realPath ?? file.backupPath);
+    return true;
+  }
+  if (file.originalPath !== file.wrapperPath && existsSync(file.originalPath) && existsSync(file.wrapperPath) && isShim(file.wrapperPath)) {
+    replaceOwnedBackup(file.originalPath, file.backupPath);
+    writeShim(file.wrapperPath, file.realPath ?? file.backupPath);
+    return true;
+  }
+  return false;
+}
+
+interface GuardedRefreshOperation {
+  file: ShimFileState;
+  expectedReplacement: ShimPathFingerprint;
+  sourcePath: string;
+}
+
+interface GuardedRefreshJournalEntry {
+  operation: GuardedRefreshOperation;
+  stagedOldBackupPath?: string;
+  replacementMovedToBackup: boolean;
+  wrapperWriteStarted: boolean;
+}
+
+let guardedRefreshTransactionId = 0;
+
+interface ShimRestoreLock {
+  release(): void;
+}
+
+interface ShimRestoreLockRecord {
+  version: 1;
+  token: string;
+  pid: number;
+  createdAt: number;
+}
+
+interface ShimRestoreLockSnapshot {
+  record: ShimRestoreLockRecord;
+  ownerPath: string;
+  lockIdentity: Pick<Stats, "dev" | "ino">;
+  fingerprint: ShimPathFingerprint;
+}
+
+function restoreLockPath(): string {
+  return join(getConfigDir(), "codex-shim.autorestore.lock");
+}
+
+function sameFileIdentity(left: Pick<Stats, "dev" | "ino">, right: Pick<Stats, "dev" | "ino">): boolean {
+  return left.dev === right.dev && left.ino === right.ino;
+}
+
+function readShimRestoreLockSnapshot(path: string): ShimRestoreLockSnapshot | null {
+  let lockIdentity: Stats;
+  let entries: string[];
+  try {
+    lockIdentity = lstatSync(path);
+    if (!lockIdentity.isDirectory()) return null;
+    entries = readdirSync(path);
+  } catch {
+    return null;
+  }
+  if (entries.length !== 1 || !entries[0].endsWith(".json")) return null;
+  const ownerPath = join(path, entries[0]);
+  const probe = stableShimPathProbe(ownerPath);
+  if (!probe || probe.fingerprint.kind !== "file" || probe.fingerprint.size > 4096) return null;
+  try {
+    const value = JSON.parse(probe.prefix) as Partial<ShimRestoreLockRecord>;
+    if (value.version !== 1 || typeof value.token !== "string" || value.token.length === 0
+      || typeof value.pid !== "number" || !Number.isSafeInteger(value.pid) || value.pid <= 0
+      || typeof value.createdAt !== "number" || !Number.isFinite(value.createdAt)) return null;
+    if (entries[0] !== `${value.token}.json`) return null;
+    const currentLockIdentity = lstatSync(path);
+    if (!currentLockIdentity.isDirectory() || !sameFileIdentity(lockIdentity, currentLockIdentity)) return null;
+    return {
+      record: value as ShimRestoreLockRecord,
+      ownerPath,
+      lockIdentity,
+      fingerprint: probe.fingerprint,
+    };
+  } catch {
+    return null;
+  }
+}
+
+function sameShimRestoreLock(left: ShimRestoreLockSnapshot, right: ShimRestoreLockSnapshot): boolean {
+  return left.record.token === right.record.token
+    && sameFileIdentity(left.lockIdentity, right.lockIdentity)
+    && sameFingerprint(left.fingerprint, right.fingerprint);
+}
+
+function reclaimStaleRestoreLock(path: string, beforeDelete?: () => void): boolean {
+  const observed = readShimRestoreLockSnapshot(path);
+  if (!observed) return false;
+  const createdAt = Math.max(observed.record.createdAt, observed.fingerprint.mtimeMs);
+  if (Date.now() - createdAt <= CODEX_SHIM_RESTORE_LOCK_STALE_MS) return false;
+  if (isProcessAlive(observed.record.pid)) return false;
+  const current = readShimRestoreLockSnapshot(path);
+  if (!current || !sameShimRestoreLock(observed, current)) return false;
+  beforeDelete?.();
+  try {
+    // The token is part of the owner filename. Even if the lock directory is
+    // replaced after the comparison, this unlink cannot target a successor's
+    // differently named owner record.
+    unlinkSync(observed.ownerPath);
+    rmdirSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function tryAcquireShimRestoreLock(beforeStaleDelete?: () => void): ShimRestoreLock | null {
+  const dir = getConfigDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const path = restoreLockPath();
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    let fd: number | null = null;
+    let identity: Stats | null = null;
+    let createdDirectory = false;
+    const record: ShimRestoreLockRecord = {
+      version: 1,
+      token: `${process.pid}-${Date.now()}-${randomUUID()}`,
+      pid: process.pid,
+      createdAt: Date.now(),
+    };
+    const ownerPath = join(path, `${record.token}.json`);
+    try {
+      mkdirSync(path, { mode: 0o700 });
+      createdDirectory = true;
+      fd = openSync(ownerPath, "wx", 0o600);
+      identity = fstatSync(fd);
+      writeFileSync(fd, `${JSON.stringify(record)}\n`, "utf8");
+      identity = fstatSync(fd);
+      let released = false;
+      return {
+        release(): void {
+          if (released) return;
+          released = true;
+          try { closeSync(fd!); } catch { /* stale recovery handles an uncertain lock */ }
+          try {
+            const current = readShimRestoreLockSnapshot(path);
+            if (identity && current && current.record.token === record.token
+              && sameFileIdentity(identity, current.fingerprint)) {
+              unlinkSync(ownerPath);
+              rmdirSync(path);
+            }
+          } catch { /* stale recovery handles release failures */ }
+        },
+      };
+    } catch (error) {
+      if (fd !== null) {
+        try { closeSync(fd); } catch { /* best-effort close before ownership cleanup */ }
+        try {
+          const current = readShimRestoreLockSnapshot(path);
+          if (identity && current && current.record.token === record.token
+            && sameFileIdentity(identity, current.fingerprint)) {
+            unlinkSync(ownerPath);
+            rmdirSync(path);
+          }
+        } catch { /* leave an uncertain lock for stale recovery */ }
+      } else if (createdDirectory) {
+        try { rmdirSync(path); } catch { /* another owner exists or cleanup is uncertain */ }
+      }
+      if (fileErrorCode(error) !== "EEXIST") throw error;
+      if (attempt === 0 && reclaimStaleRestoreLock(path, beforeStaleDelete)) continue;
+      return null;
+    }
+  }
+  return null;
+}
+
+function planGuardedRefreshTransaction(
+  files: readonly ShimFileState[],
+  expectedReplacements: ReadonlyMap<string, ShimPathFingerprint>,
+): GuardedRefreshOperation[] | null {
+  const operations: GuardedRefreshOperation[] = [];
+  const seen = new Set<string>();
+  for (const file of files) {
+    if (seen.has(file.wrapperPath)) return null;
+    seen.add(file.wrapperPath);
+    if (file.preserveOnly) {
+      if (!existsSync(file.backupPath) || existsSync(file.originalPath)) return null;
+      continue;
+    }
+    if (!hasUsableBackingPath(file)) return null;
+    const probe = stableShimPathProbe(file.wrapperPath);
+    if (!probe) return null;
+    const expectedReplacement = expectedReplacements.get(file.wrapperPath);
+    if (!expectedReplacement) {
+      if (!isHealthyShimProbe(probe, process.platform)) return null;
+      continue;
+    }
+    if (file.wrapperPath !== file.originalPath
+      || probe.prefix.includes(SHIM_MARKER)
+      || !sameFingerprint(probe.fingerprint, expectedReplacement)) return null;
+    operations.push({ file, expectedReplacement, sourcePath: file.wrapperPath });
+  }
+  if (operations.length !== expectedReplacements.size) return null;
+  return operations;
+}
+
+function rollbackGuardedRefresh(journal: readonly GuardedRefreshJournalEntry[]): Error[] {
+  const rollbackErrors: Error[] = [];
+  const attempt = (operation: () => void): void => {
+    try {
+      operation();
+    } catch (error) {
+      rollbackErrors.push(error instanceof Error ? error : new Error(String(error)));
+    }
+  };
+  for (const entry of [...journal].reverse()) {
+    attempt(() => {
+      if (entry.wrapperWriteStarted && existsSync(entry.operation.file.wrapperPath)) {
+        unlinkSync(entry.operation.file.wrapperPath);
+      }
+    });
+    attempt(() => {
+      if (entry.replacementMovedToBackup && existsSync(entry.operation.file.backupPath)) {
+        renameSync(entry.operation.file.backupPath, entry.operation.sourcePath);
+      }
+    });
+    attempt(() => {
+      if (entry.stagedOldBackupPath && existsSync(entry.stagedOldBackupPath)) {
+        renameSync(entry.stagedOldBackupPath, entry.operation.file.backupPath);
+      }
+    });
+  }
+  return rollbackErrors;
+}
+
+function applyGuardedRefreshTransaction(
+  operations: readonly GuardedRefreshOperation[],
+  beforeGuardedRefresh?: (wrapperPath: string, index: number) => void,
+  commitState?: () => void,
+): boolean {
+  const journal: GuardedRefreshJournalEntry[] = [];
+  let applyError: Error | null = null;
+  let fingerprintMismatch = false;
+  const transactionId = `${process.pid}-${++guardedRefreshTransactionId}`;
+
+  for (const [index, operation] of operations.entries()) {
+    beforeGuardedRefresh?.(operation.sourcePath, index);
+    const probe = stableShimPathProbe(operation.sourcePath);
+    if (!probe || !sameFingerprint(probe.fingerprint, operation.expectedReplacement)) {
+      fingerprintMismatch = true;
+      break;
+    }
+    const entry: GuardedRefreshJournalEntry = {
+      operation,
+      replacementMovedToBackup: false,
+      wrapperWriteStarted: false,
+    };
+    journal.push(entry);
+    try {
+      if (existsSync(operation.file.backupPath)) {
+        entry.stagedOldBackupPath = `${operation.file.backupPath}.autorestore-${transactionId}-${index}`;
+        if (existsSync(entry.stagedOldBackupPath)) unlinkSync(entry.stagedOldBackupPath);
+        renameSync(operation.file.backupPath, entry.stagedOldBackupPath);
+      }
+      renameSync(operation.sourcePath, operation.file.backupPath);
+      entry.replacementMovedToBackup = true;
+      entry.wrapperWriteStarted = true;
+      writeShim(operation.file.wrapperPath, operation.file.realPath ?? operation.file.backupPath);
+    } catch (error) {
+      applyError = error instanceof Error ? error : new Error(String(error));
+      break;
+    }
+  }
+
+  if (!fingerprintMismatch && !applyError && commitState) {
+    try {
+      commitState();
+    } catch (error) {
+      applyError = error instanceof Error ? error : new Error(String(error));
+    }
+  }
+
+  if (fingerprintMismatch || applyError) {
+    const rollbackErrors = rollbackGuardedRefresh(journal);
+    if (applyError || rollbackErrors.length > 0) {
+      throw new AggregateError(
+        [...(applyError ? [applyError] : []), ...rollbackErrors],
+        "Codex shim guarded refresh failed",
+      );
+    }
+    return false;
+  }
+
+  const cleanupErrors: Error[] = [];
+  for (const entry of journal) {
+    try {
+      if (entry.stagedOldBackupPath && existsSync(entry.stagedOldBackupPath)) unlinkSync(entry.stagedOldBackupPath);
+    } catch (error) {
+      cleanupErrors.push(error instanceof Error ? error : new Error(String(error)));
+    }
+  }
+  if (cleanupErrors.length > 0) throw new AggregateError(cleanupErrors, "Codex shim guarded refresh cleanup failed");
+  return true;
+}
+
+function installCodexShimInternal(options: InstallCodexShimInternalOptions): { installed: boolean; message: string } {
+  const existing = readState();
+  if (existing) {
+    const files = stateFiles(existing);
+    if (options.expectedReplacements) {
+      const operations = planGuardedRefreshTransaction(files, options.expectedReplacements);
+      if (!operations || operations.length === 0) {
+        return { installed: false, message: "Codex shim auto-restore deferred because tracked launchers changed." };
+      }
+      const originalStateBytes = readFileSync(statePath());
+      const commitState = (): void => {
+        try {
+          writeState(primaryState(files));
+        } catch (writeError) {
+          try {
+            writeFileSync(statePath(), originalStateBytes);
+          } catch (restoreError) {
+            throw new AggregateError(
+              [writeError, restoreError],
+              "Codex shim state commit and restoration failed",
+            );
+          }
+          throw writeError;
+        }
+      };
+      if (!applyGuardedRefreshTransaction(operations, options.beforeGuardedRefresh, commitState)) {
+        return { installed: false, message: "Codex shim auto-restore deferred because tracked launchers changed." };
+      }
+      return {
+        installed: true,
+        message: `Codex update detected. Backed up new launcher and refreshed shim at ${files.map(f => f.wrapperPath).join(", ")}.`,
+      };
+    }
+    let refreshed = false;
+    for (const file of files) refreshed = refreshShimFile(file) || refreshed;
+    const allInstalled = files.every(file => file.preserveOnly
+      ? existsSync(file.backupPath) && !existsSync(file.originalPath)
+      : existsSync(file.wrapperPath)
+        && (existsSync(file.backupPath) || (file.realPath ? existsSync(file.realPath) : false))
+        && isShim(file.wrapperPath));
+    if (refreshed || allInstalled) {
+      writeState(primaryState(files));
+      if (refreshed) {
+        return {
+          installed: true,
+          message: `Codex update detected. Backed up new launcher and refreshed shim at ${files.map(f => f.wrapperPath).join(", ")}.`,
+        };
+      }
+      return {
+        installed: false,
+        message: `Codex autostart shim already installed at ${files.map(f => f.wrapperPath).join(", ")}.`,
+      };
+    }
+  }
+
+  if (!options.allowFreshInstall) {
+    return { installed: false, message: "Codex shim auto-restore requires a valid prior installation." };
+  }
+
+  const targets: ShimFileState[] | null = process.platform === "win32"
+    ? findWindowsCodexTargets()
+    : (() => {
+      const originalPath = findCodexOnPath();
+      return originalPath ? [{ wrapperPath: originalPath, originalPath, backupPath: backupPathFor(originalPath) }] : null;
+    })();
+  if (!targets) return { installed: false, message: lastShimDiscoveryError ?? "Could not find a codex executable on PATH." };
+
+  for (const target of targets) {
+    if (existsSync(target.backupPath)) return { installed: false, message: `Refusing to overwrite existing backup: ${target.backupPath}` };
+  }
+  for (const target of targets) {
+    if (existsSync(target.originalPath)) renameSync(target.originalPath, target.backupPath);
+    if (!target.preserveOnly) writeShim(target.wrapperPath, target.realPath ?? target.backupPath);
+  }
+  writeState(primaryState(targets));
+  return {
+    installed: true,
+    message: `Codex autostart shim installed at ${targets.map(t => t.wrapperPath).join(", ")}. Original saved at ${targets.map(t => t.backupPath).join(", ")}.`,
+  };
+}
+
+export function installCodexShim(): { installed: boolean; message: string } {
+  return installCodexShimInternal({ allowFreshInstall: true });
+}
+
+export function autoRestoreCodexShim(options: {
+  enabled: () => boolean;
+  stabilitySleep?: (ms: number) => void;
+  /** Narrow deterministic seam used to hold the interprocess lock in tests. */
+  afterRestoreLockAcquired?: () => void;
+  /** Narrow deterministic seam for stale-lock compare-and-delete tests. */
+  beforeStaleRestoreLockDelete?: () => void;
+  /** Narrow deterministic race seam for the guarded transaction tests. */
+  beforeGuardedRefresh?: (wrapperPath: string, index: number) => void;
+}): CodexShimAutoRestoreResult {
+  const stateRead = readStateResult();
+  const state = stateRead.state;
+  if (!state) {
+    if (stateRead.warning) return { status: "ineligible", message: stateRead.warning };
+    return { status: existsSync(statePath()) ? "ineligible" : "not-installed" };
+  }
+  if (state.platform !== process.platform) return { status: "ineligible" };
+
+  const files = stateFiles(state);
+  const replacementProbes = new Map<string, StableShimPathProbe>();
+  const seen = new Set<string>();
+  let healthyCount = 0;
+  for (const file of files) {
+    if (seen.has(file.wrapperPath)) return { status: "ineligible" };
+    seen.add(file.wrapperPath);
+    if (file.preserveOnly) {
+      if (!existsSync(file.backupPath) || existsSync(file.originalPath)) return { status: "ineligible" };
+      continue;
+    }
+    if (!existsSync(file.wrapperPath) || !hasUsableBackingPath(file)) return { status: "ineligible" };
+    const probe = stableShimPathProbe(file.wrapperPath);
+    if (!probe) return { status: "deferred" };
+    if (probe.prefix.includes(SHIM_MARKER)) {
+      if (!isHealthyShimProbe(probe, state.platform)) return { status: "ineligible" };
+      healthyCount += 1;
+      continue;
+    }
+    replacementProbes.set(file.wrapperPath, probe);
+  }
+
+  if (replacementProbes.size === 0) return { status: "healthy" };
+  if (!options.enabled()) return { status: "disabled" };
+  if (files.length > 1 && healthyCount > 0) {
+    return {
+      status: "deferred",
+      message: "Codex shim auto-restore deferred because tracked launcher siblings are in a mixed shim/replacement state.",
+    };
+  }
+
+  const lock = tryAcquireShimRestoreLock(options.beforeStaleRestoreLockDelete);
+  if (!lock) return { status: "deferred" };
+  try {
+    options.afterRestoreLockAcquired?.();
+    (options.stabilitySleep ?? Bun.sleepSync)(CODEX_SHIM_REPLACEMENT_STABLE_MS);
+    const expectedReplacements = new Map<string, ShimPathFingerprint>();
+    for (const [path, firstProbe] of replacementProbes) {
+      const secondProbe = stableShimPathProbe(path);
+      if (!secondProbe || secondProbe.prefix.includes(SHIM_MARKER)
+        || !sameStableShimPathProbe(firstProbe, secondProbe)) return { status: "deferred" };
+      expectedReplacements.set(path, secondProbe.fingerprint);
+    }
+    const result = installCodexShimInternal({
+      allowFreshInstall: false,
+      expectedReplacements,
+      beforeGuardedRefresh: options.beforeGuardedRefresh,
+    });
+    return result.installed
+      ? { status: "restored", message: result.message }
+      : { status: "deferred" };
+  } finally {
+    lock.release();
+  }
+}
+
+export function uninstallCodexShim(): { removed: boolean; message: string } {
+  const state = readState();
+  if (!state) return { removed: false, message: "Codex autostart shim is not installed." };
+  const files = stateFiles(state);
+  for (const file of files) {
+    if (file.preserveOnly) continue;
+    if (existsSync(file.wrapperPath) && isShim(file.wrapperPath)) unlinkSync(file.wrapperPath);
+  }
+  for (const file of files) {
+    if (existsSync(file.backupPath) && !existsSync(file.originalPath)) renameSync(file.backupPath, file.originalPath);
+  }
+  if (existsSync(statePath())) unlinkSync(statePath());
+  return { removed: true, message: `Codex autostart shim removed. Restored ${files.map(f => f.originalPath).join(", ")}.` };
+}
+
+/** True if a Codex autostart shim is currently installed (state file present). */
+export function isCodexShimInstalled(): boolean {
+  return diagnoseCodexShim().installed;
+}
+
+export interface CodexShimDiagnostic {
+  installed: boolean;
+  healthy: boolean;
+  summary: string;
+}
+
+/** Structured, secret-free shim state for CLI/GUI lifecycle diagnostics. */
+export function diagnoseCodexShim(): CodexShimDiagnostic {
+  const state = readState();
+  if (!state) {
+    if (existsSync(statePath())) {
+      return {
+        installed: true,
+        healthy: false,
+        summary: `Codex autostart shim state is invalid or corrupt at ${statePath()}. Reinstall or remove the shim.`,
+      };
+    }
+    return {
+      installed: false,
+      healthy: false,
+      summary: "Codex autostart shim is not installed.",
+    };
+  }
+  const files = stateFiles(state);
+  const healthy = files.length > 0 && files.every(file => file.preserveOnly
+    ? existsSync(file.backupPath) && !existsSync(file.originalPath)
+    : existsSync(file.wrapperPath)
+      && (existsSync(file.backupPath) || (file.realPath ? existsSync(file.realPath) : false))
+      && isHealthyShim(file.wrapperPath, state.platform));
+  const summary = files.map(file => {
+    const wrapper = existsSync(file.wrapperPath)
+      ? isShim(file.wrapperPath)
+        ? "shim present"
+        : "present but not an opencodex shim"
+      : "missing";
+    const backup = existsSync(file.backupPath) ? "present" : "missing";
+    return `Codex autostart shim: wrapper ${wrapper} at ${file.wrapperPath}; original backup ${backup} at ${file.backupPath}.`;
+  }).join("\n");
+  return { installed: true, healthy, summary };
+}
+
+export function codexShimStatus(): string {
+  return diagnoseCodexShim().summary;
+}