@bitkyc08/opencodex 2.55.0 → 2.57.0

package/src/codex/shim-probe.ts

@@ -0,0 +1,367 @@
+import { spawnSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import {
+  chmodSync,
+  existsSync,
+  lstatSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+} from "node:fs";
+import { join } from "node:path";
+import { CODEX_SHIM_REENTRY_EXIT_CODE, CODEX_SHIM_REENTRY_DIAGNOSTIC } from "./shim-templates";
+import type { ShimFileState } from "./shim-state-file";
+
+const CODEX_SHIM_INSTALL_PROBE_TIMEOUT_MS = 5_000;
+const CODEX_SHIM_INSTALL_PROBE_EXIT_TIMEOUT_MS = 1_000;
+
+const CODEX_SHIM_INSTALL_PROBE_SCRIPT = `
+const { spawn } = require("node:child_process");
+const { readFileSync, writeFileSync } = require("node:fs");
+const [markerPath, reentryPath, groupPath, stderrPath, launcherShellPath, wrapperPath, timeoutRaw, stderrLimitRaw, stderrDrainRaw, observationRaw] = process.argv.slice(1);
+const timeoutMs = Number.parseInt(timeoutRaw, 10);
+const stderrLimit = Number.parseInt(stderrLimitRaw, 10);
+const stderrDrainMs = Number.parseInt(stderrDrainRaw, 10);
+const observationMs = Number.parseInt(observationRaw, 10);
+const probeStartedAt = Date.now();
+const stderrChunks = [];
+let stderrBytes = 0;
+let launcher;
+let probeLease;
+let timer;
+let stderrDrainTimer;
+let observationTimer;
+let reentryPollTimer;
+let marker = "";
+let finished = false;
+
+function writeExclusive(path, value) {
+  writeFileSync(path, value, { flag: "wx", mode: 0o600 });
+}
+
+function appendStderr(value) {
+  if (stderrBytes >= stderrLimit) return;
+  const bytes = Buffer.from(value);
+  const retained = bytes.subarray(0, stderrLimit - stderrBytes);
+  stderrChunks.push(retained);
+  stderrBytes += retained.byteLength;
+}
+
+function groupAlive() {
+  if (!launcher || !launcher.pid) return false;
+  try {
+    process.kill(-launcher.pid, 0);
+    return true;
+  } catch (error) {
+    return error && error.code !== "ESRCH";
+  }
+}
+
+function killGroup() {
+  if (!launcher || !launcher.pid) return;
+  try { process.kill(-launcher.pid, "SIGKILL"); } catch (error) {
+    if (!error || error.code !== "ESRCH") appendStderr(String(error));
+  }
+}
+
+function setMarker(value) {
+  if (marker) return;
+  marker = value;
+  try { writeExclusive(markerPath, value + "\\n"); } catch (error) { appendStderr(String(error)); }
+}
+
+function reentryDetected() {
+  try { return readFileSync(reentryPath, "utf8").trim() === "recursive"; } catch { return false; }
+}
+
+function checkReentry() {
+  if (finished || !reentryDetected()) return;
+  setMarker("recursive");
+  killGroup();
+  finish(126);
+}
+
+function finish(status) {
+  if (finished) return;
+  finished = true;
+  if (timer) clearTimeout(timer);
+  if (stderrDrainTimer) clearTimeout(stderrDrainTimer);
+  if (observationTimer) clearTimeout(observationTimer);
+  if (reentryPollTimer) clearInterval(reentryPollTimer);
+  if (!marker && reentryDetected()) setMarker("recursive");
+  if (!marker && groupAlive()) {
+    setMarker("descendants");
+    killGroup();
+  }
+  try { writeExclusive(stderrPath, Buffer.concat(stderrChunks)); } catch { /* parent fails closed */ }
+  process.exit(marker === "timeout" ? 124 : marker === "descendants" ? 125 : marker === "recursive" ? 126 : status);
+}
+
+function finishAfterStderr(status) {
+  if (finished) return;
+  if (timer) {
+    clearTimeout(timer);
+    timer = undefined;
+  }
+  if (!launcher || !launcher.stderr || !probeLease) {
+    finish(status);
+    return;
+  }
+  let stderrEnded = launcher.stderr.readableEnded;
+  let leaseEnded = probeLease.readableEnded;
+  let observationElapsed = false;
+  const finishWhenReady = () => {
+    if (stderrEnded && leaseEnded && observationElapsed) finish(status);
+  };
+  launcher.stderr.once("end", () => {
+    stderrEnded = true;
+    finishWhenReady();
+  });
+  probeLease.once("end", () => {
+    leaseEnded = true;
+    finishWhenReady();
+  });
+  stderrDrainTimer = setTimeout(() => {
+    stderrEnded = true;
+    if (!marker && groupAlive()) {
+      setMarker("descendants");
+      killGroup();
+      finish(125);
+      return;
+    }
+    finishWhenReady();
+  }, stderrDrainMs);
+  const remainingObservationMs = Math.max(0, observationMs - (Date.now() - probeStartedAt));
+  observationTimer = setTimeout(() => {
+    observationElapsed = true;
+    if (!leaseEnded) {
+      setMarker(groupAlive() ? "descendants" : "timeout");
+      killGroup();
+      finish(marker === "descendants" ? 125 : 124);
+      return;
+    }
+    finishWhenReady();
+  }, remainingObservationMs);
+  finishWhenReady();
+}
+
+try {
+  launcher = spawn(launcherShellPath, [wrapperPath, "--version"], {
+    detached: true,
+    env: process.env,
+    stdio: ["ignore", "ignore", "pipe", "pipe"],
+  });
+  if (!launcher.pid) throw new Error("Codex shim probe launcher has no pid");
+  probeLease = launcher.stdio[3];
+  if (!probeLease) throw new Error("Codex shim probe launcher has no descendant lease pipe");
+  writeExclusive(groupPath, String(launcher.pid) + "\\n");
+  launcher.stderr.on("data", appendStderr);
+  reentryPollTimer = setInterval(checkReentry, 10);
+  launcher.once("error", error => {
+    appendStderr(String(error));
+    finishAfterStderr(127);
+  });
+  launcher.once("exit", code => finishAfterStderr(Number.isInteger(code) ? code : 127));
+  timer = setTimeout(() => {
+    setMarker("timeout");
+    killGroup();
+    finish(124);
+  }, timeoutMs);
+} catch (error) {
+  appendStderr(String(error));
+  killGroup();
+  finish(127);
+}
+`;
+const MAX_DIAGNOSTIC_VALUE_BYTES = 8 * 1024;
+
+type UnixShimProbeCleanupPhase = "marker" | "reentry" | "group" | "stderr" | "group-id" | "termination" | "spawn" | "exception";
+interface UnixShimProbeCleanup {
+  kind: "cleanup";
+  phase: UnixShimProbeCleanupPhase;
+  code: string;
+  status: number | null;
+  signal: string;
+}
+type UnixShimProbeResult = UnixShimProbeCleanup | "descendants" | "failed" | "recursive" | "timeout" | null;
+
+const SHIM_PROBE_ERROR_CODES = new Set([
+  "EACCES", "EAGAIN", "EBADF", "ECANCELED", "EINTR", "EIO", "EMFILE", "ENFILE",
+  "ENOENT", "ENOEXEC", "ENOMEM", "ENOSPC", "EPERM", "EPIPE", "ESRCH", "ETIMEDOUT", "ETXTBSY",
+]);
+const SHIM_PROBE_SIGNALS = new Set([
+  "SIGABRT", "SIGBUS", "SIGHUP", "SIGILL", "SIGINT", "SIGKILL", "SIGPIPE", "SIGQUIT",
+  "SIGSEGV", "SIGTERM", "SIGTRAP", "SIGXCPU", "SIGXFSZ",
+]);
+
+/** Diagnostics cross a CLI boundary: never stringify arbitrary errors or metadata. */
+function shimProbeCleanup(
+  phase: UnixShimProbeCleanupPhase, error?: unknown, status?: unknown, signal?: unknown,
+): UnixShimProbeCleanup {
+  let code = error === undefined ? "none" : "unknown";
+  if (error !== null && typeof error === "object") {
+    try {
+      const value = Object.getOwnPropertyDescriptor(error, "code")?.value;
+      if (typeof value === "string" && SHIM_PROBE_ERROR_CODES.has(value)) code = value;
+    } catch { /* hostile accessors/proxies cannot turn diagnostics into an exception */ }
+  }
+  return {
+    kind: "cleanup", phase, code,
+    status: typeof status === "number" && Number.isInteger(status) && status >= 0 && status <= 255 ? status : null,
+    signal: typeof signal === "string" && SHIM_PROBE_SIGNALS.has(signal) ? signal : "none",
+  };
+}
+
+let codexShimProbeHookForTests: (() => void) | null = null;
+let codexShimProbeShellForTests: string | null = null;
+
+let codexShimProbeObservationMs = CODEX_SHIM_INSTALL_PROBE_TIMEOUT_MS;
+
+/** Narrow deterministic seam for transaction rollback tests. */
+export function setCodexShimProbeHookForTests(hook: (() => void) | null): void {
+  codexShimProbeHookForTests = hook;
+}
+
+/** Selects a POSIX shell only for cross-shell probe regression tests. */
+export function setCodexShimProbeShellForTests(path: string | null): void {
+  codexShimProbeShellForTests = path;
+}
+
+/** Shortens the successful-launcher observation window only for focused tests. */
+export function setCodexShimProbeObservationMsForTests(value: number | null): void {
+  codexShimProbeObservationMs = value ?? CODEX_SHIM_INSTALL_PROBE_TIMEOUT_MS;
+}
+
+function readProbeMetadata(path: string, maxBytes: number): string | null {
+  try {
+    if (!existsSync(path)) return "";
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.size > maxBytes) return null;
+    return readFileSync(path, "utf8").trim();
+  } catch {
+    return null;
+  }
+}
+
+function probeUnixShimInstall(wrapperPath: string): UnixShimProbeResult {
+  if (process.platform === "win32") return null;
+  const probeDir = mkdtempSync(join(tmpdir(), "opencodex-shim-probe-"));
+  const markerPath = join(probeDir, "result");
+  const reentryPath = join(probeDir, "reentry");
+  const groupPath = join(probeDir, "group");
+  const stderrPath = join(probeDir, "stderr");
+  const env: NodeJS.ProcessEnv = {
+    ...process.env,
+    OCX_SHIM_BYPASS: "1",
+    OCX_SHIM_PROBE: "1",
+    OCX_SHIM_PROBE_REENTRY_PATH: reentryPath,
+  };
+  delete env.OCX_SHIM_ACTIVE_PID;
+  delete env.OCX_SHIM_ACTIVE_DEPTH;
+  delete env.OCX_SHIM_PROBE_ACTIVE;
+  let groupId = 0;
+  let probeStatus: unknown;
+  let probeSignal: unknown;
+  try {
+    chmodSync(probeDir, 0o700);
+    const result = spawnSync(process.execPath, [
+      "-e",
+      CODEX_SHIM_INSTALL_PROBE_SCRIPT,
+      markerPath,
+      reentryPath,
+      groupPath,
+      stderrPath,
+      codexShimProbeShellForTests ?? "/bin/sh",
+      wrapperPath,
+      String(CODEX_SHIM_INSTALL_PROBE_TIMEOUT_MS),
+      String(MAX_DIAGNOSTIC_VALUE_BYTES),
+      String(CODEX_SHIM_INSTALL_PROBE_EXIT_TIMEOUT_MS),
+      String(codexShimProbeObservationMs),
+    ], {
+      encoding: "utf8",
+      env,
+      timeout: CODEX_SHIM_INSTALL_PROBE_TIMEOUT_MS + CODEX_SHIM_INSTALL_PROBE_EXIT_TIMEOUT_MS,
+      killSignal: "SIGKILL",
+    });
+    probeStatus = result.status;
+    probeSignal = result.signal;
+    const timedOut = (result.error as NodeJS.ErrnoException | undefined)?.code === "ETIMEDOUT";
+    const marker = readProbeMetadata(markerPath, 64);
+    const reentryMarker = readProbeMetadata(reentryPath, 64);
+    const groupText = readProbeMetadata(groupPath, 64);
+    const launcherStderr = readProbeMetadata(stderrPath, MAX_DIAGNOSTIC_VALUE_BYTES);
+    groupId = groupText === null ? 0 : Number.parseInt(groupText, 10);
+    if (marker === null) return shimProbeCleanup("marker", result.error, probeStatus, probeSignal);
+    if (reentryMarker === null) return shimProbeCleanup("reentry", result.error, probeStatus, probeSignal);
+    if (groupText === null) return shimProbeCleanup("group", result.error, probeStatus, probeSignal);
+    if (launcherStderr === null) return shimProbeCleanup("stderr", result.error, probeStatus, probeSignal);
+    if (!Number.isInteger(groupId) || groupId <= 0) return shimProbeCleanup("group-id", result.error, probeStatus, probeSignal);
+    const groupSurvived = unixProcessGroupAlive(groupId);
+    if (timedOut || marker || reentryMarker || groupSurvived) {
+      try {
+        terminateUnixProcessGroup(groupId);
+      } catch (error) {
+        return shimProbeCleanup("termination", error, probeStatus, probeSignal);
+      }
+    }
+    if (result.error && !timedOut) return shimProbeCleanup("spawn", result.error, probeStatus, probeSignal);
+    if (timedOut || marker === "timeout") return "timeout";
+    if (marker === "recursive" || reentryMarker === "recursive") return "recursive";
+    if (reentryMarker !== "") return shimProbeCleanup("reentry", undefined, probeStatus, probeSignal);
+    if (marker === "descendants") return "descendants";
+    if (groupSurvived) return "descendants";
+    if (result.status === CODEX_SHIM_REENTRY_EXIT_CODE && launcherStderr.includes(CODEX_SHIM_REENTRY_DIAGNOSTIC)) {
+      return "recursive";
+    }
+    if (result.status !== 0) return "failed";
+    return null;
+  } catch (error) {
+    if (Number.isInteger(groupId) && groupId > 0) {
+      try { terminateUnixProcessGroup(groupId); } catch { /* cleanup classification below */ }
+    }
+    return shimProbeCleanup("exception", error, probeStatus, probeSignal);
+  } finally {
+    try { rmSync(probeDir, { recursive: true, force: true }); } catch { /* best-effort cleanup */ }
+  }
+}
+
+function probeUnixShimFiles(files: readonly ShimFileState[]): UnixShimProbeResult {
+  if (process.platform === "win32") return null;
+  codexShimProbeHookForTests?.();
+  return files
+    .filter(file => !file.preserveOnly)
+    .map(file => probeUnixShimInstall(file.wrapperPath))
+    .find(result => result !== null) ?? null;
+}
+
+function unixProcessGroupAlive(groupId: number): boolean {
+  try {
+    process.kill(-groupId, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code !== "ESRCH";
+  }
+}
+
+function terminateUnixProcessGroup(groupId: number): void {
+  let permissionError: unknown;
+  try {
+    process.kill(-groupId, "SIGKILL");
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "EPERM") permissionError = error;
+    else if (code !== "ESRCH") throw error;
+  }
+  // A concurrently exiting group can briefly reject a second signal. Only
+  // observed disappearance clears that uncertainty; never send another signal.
+  const deadline = Date.now() + CODEX_SHIM_INSTALL_PROBE_EXIT_TIMEOUT_MS;
+  while (Date.now() < deadline && unixProcessGroupAlive(groupId)) Bun.sleepSync(10);
+  if (unixProcessGroupAlive(groupId)) {
+    if (permissionError) throw permissionError;
+    throw new Error(`Codex shim install probe process group ${groupId} did not terminate`);
+  }
+}
+
+export { CODEX_SHIM_INSTALL_PROBE_TIMEOUT_MS, MAX_DIAGNOSTIC_VALUE_BYTES };
+export type { UnixShimProbeResult };
+export { probeUnixShimFiles };

package/src/codex/shim-restore-lock.ts

@@ -0,0 +1,169 @@
+import { randomUUID } from "node:crypto";
+import {
+  closeSync,
+  existsSync,
+  fstatSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readdirSync,
+  rmdirSync,
+  unlinkSync,
+  writeFileSync,
+  type Stats,
+} from "node:fs";
+import { join } from "node:path";
+import { getConfigDir } from "../config";
+import { isProcessAlive } from "../lib/process-control";
+import { sameFingerprint, stableShimPathProbe, type ShimPathFingerprint } from "./shim-fingerprint";
+import { fileErrorCode } from "./shim-state-file";
+
+const CODEX_SHIM_RESTORE_LOCK_STALE_MS = 30_000;
+
+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;
+}
+
+export { tryAcquireShimRestoreLock, reclaimStaleRestoreLock };

package/src/codex/shim-state-file.ts

@@ -0,0 +1,151 @@
+import {
+  closeSync,
+  existsSync,
+  fstatSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  readSync,
+  writeFileSync,
+  type Stats,
+} from "node:fs";
+import { join } from "node:path";
+import { getConfigDir } from "../config";
+import { recordOwnedConfigPath } from "../lib/config-ownership";
+
+export const CODEX_SHIM_STATE_MAX_BYTES = 1024 * 1024;
+
+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 ShimStateReadResult {
+  state: ShimState | null;
+  present: boolean;
+  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): { bytes: Buffer; content: string } | { warning: string } | null {
+  let lexicalBefore: Stats;
+  try {
+    lexicalBefore = lstatSync(path);
+    if (lexicalBefore.isSymbolicLink() || !lexicalBefore.isFile()) {
+      return { warning: `Codex shim state is not a direct regular file at ${path}; auto-restore skipped.` };
+    }
+  } catch (error) {
+    if (fileErrorCode(error) === "ENOENT") return null;
+    return { warning: `Codex shim state could not be inspected at ${path}.` };
+  }
+  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);
+    let lexicalAfter: Stats;
+    try {
+      lexicalAfter = lstatSync(path);
+    } catch {
+      return { warning: `Codex shim state changed while being read at ${path}; auto-restore skipped.` };
+    }
+    if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size
+      || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs
+      || lexicalBefore.dev !== before.dev || lexicalBefore.ino !== before.ino
+      || lexicalAfter.isSymbolicLink() || lexicalAfter.dev !== after.dev || lexicalAfter.ino !== after.ino) {
+      return { warning: `Codex shim state changed while being read at ${path}; auto-restore skipped.` };
+    }
+    return { bytes: buffer, content: buffer.toString("utf8") };
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function readStateResult(path = statePath()): ShimStateReadResult {
+  const bounded = readBoundedRegularFile(path, CODEX_SHIM_STATE_MAX_BYTES);
+  if (!bounded) return { state: null, present: false };
+  if ("warning" in bounded) return { state: null, present: true, warning: bounded.warning };
+  try {
+    const value = JSON.parse(bounded.content) as unknown;
+    if (!value || typeof value !== "object") return { state: null, present: true };
+    const state = value as Record<string, unknown>;
+    if (typeof state.platform !== "string") return { state: null, present: true };
+    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, present: true };
+    } else if (!validFile(state)) {
+      return { state: null, present: true };
+    }
+    return { state: state as unknown as ShimState, present: true };
+  } catch {
+    return { state: null, present: true };
+  }
+}
+
+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");
+}
+
+function stateFiles(state: ShimState): ShimFileState[] {
+  return state.wrappers?.length
+    ? state.wrappers
+    : [{ wrapperPath: state.wrapperPath, originalPath: state.originalPath, backupPath: state.backupPath }];
+}
+
+export type { ShimState, ShimFileState };
+export { fileErrorCode, readStateResult, readState, statePath, writeState, stateFiles };