@bitkyc08/opencodex 2.76.0 → 2.78.0-preview.20261005

package/src/codex/shim-path-resolution.ts

@@ -0,0 +1,145 @@
+import { accessSync, closeSync, constants, existsSync, fstatSync, lstatSync, openSync, readSync, realpathSync, statSync } from "node:fs";
+import { posix, win32 } from "node:path";
+import { isWslRuntime, wslAutomountRoot } from "./home";
+import { SHIM_MARKER } from "./shim-templates";
+
+/**
+ * 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;
+  realpath?: (path: string) => string;
+  executableEligible?: (path: string) => boolean;
+};
+
+export type CodexPathCandidate = {
+  path: string;
+  isShim: boolean;
+};
+
+export function realIsDirectory(path: string): boolean {
+  try {
+    return lstatSync(path).isDirectory();
+  } catch {
+    return true; // unreadable -> treat as unusable
+  }
+}
+
+const SHIM_HEADER_MAX_BYTES = 16 * 1024;
+
+/** Shared POSIX eligibility, following launcher symlinks without opening special files. */
+export function isExecutableCodexCandidate(path: string): boolean {
+  try {
+    if (process.platform !== "win32") accessSync(path, constants.X_OK);
+    return statSync(path).isFile();
+  } catch { return false; }
+}
+
+export function inspectShimFile(path: string): boolean | null {
+  let fd: number | undefined;
+  try {
+    if (process.platform !== "win32") {
+      try { accessSync(path, constants.X_OK); } catch { return null; }
+    }
+    // Follow npm launcher symlinks, but never read a known special file.
+    if (!statSync(path).isFile()) return null;
+    const flags = constants.O_RDONLY | (process.platform === "win32" ? 0 : constants.O_NONBLOCK);
+    fd = openSync(path, flags);
+    // The entry can change after stat; a replacement FIFO must not block open or read.
+    if (!fstatSync(fd).isFile()) return null;
+    const header = Buffer.allocUnsafe(SHIM_HEADER_MAX_BYTES);
+    let total = 0;
+    while (total < header.length) {
+      const count = readSync(fd, header, total, header.length - total, total);
+      if (count === 0) break;
+      total += count;
+    }
+    return header.subarray(0, total).toString("utf8").includes(SHIM_MARKER);
+  } catch {
+    // An unreadable command still shadows later PATH entries; do not claim they are active.
+    return false;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+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()}`])];
+}
+
+/** The shell-local bin directory that fnm creates for one interactive shell. */
+export function isFnmMultishellPath(path: string, posixPaths: boolean): boolean {
+  const normalized = (posixPaths
+    ? posix.normalize(path)
+    : win32.normalize(path).replace(/\\/g, "/")).toLowerCase();
+  return /(?:^|\/)fnm_multishells?(?:\/|$)/.test(normalized);
+}
+
+/** Find the command the shell would actually use, including an OpenCodex shim. */
+export function findFirstCodexOnPath(deps: CodexPathScanDeps = {}): CodexPathCandidate | null {
+  const exists = deps.exists ?? existsSync;
+  const shimFile = deps.isShimFile ?? inspectShimFile;
+  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 : win32.join;
+  const pathSep = usePosix ? ":" : win32.delimiter;
+  const automountRoot = deps.automountRoot ?? (wsl ? wslAutomountRoot() : "/mnt");
+  const interopNames = ["codex", "codex.exe", "codex.cmd", "codex.ps1"];
+
+  for (const dir of (deps.pathValue ?? process.env.PATH ?? "").split(pathSep).filter(Boolean)) {
+    if (wsl && isWindowsInteropDir(dir, automountRoot)) continue;
+    const names = isWindowsInteropDir(dir, automountRoot) ? interopNames : commandNames("codex");
+    for (const name of names) {
+      const path = joinPath(dir, name);
+      if (!exists(path) || isDir(path)) continue;
+      const isShim = shimFile(path);
+      if (isShim !== null) return { path, isShim };
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve a Codex command discovered through fnm's temporary PATH entry.
+ *
+ * A temporary path is safe to use only when its physical target is outside the
+ * temporary tree. Returning null is deliberate: callers must not wrap the
+ * shell-local path or silently choose a lower-priority Codex installation.
+ */
+export function resolveStableFnmCodexPath(
+  path: string,
+  posixPaths: boolean,
+  realpath: ((path: string) => string) | undefined = realpathSync.native,
+): string | null {
+  if (!isFnmMultishellPath(path, posixPaths)) return path;
+  try {
+    // fnm normally links the temporary directory to the durable installation,
+    // while npm may link the command file again into its package internals.
+    // Resolve only the directory so the command basename remains the stable
+    // installation entry that the installer is allowed to replace.
+    const pathTools = posixPaths ? posix : win32;
+    const resolvedParent = realpath(pathTools.dirname(path));
+    if (!resolvedParent || isFnmMultishellPath(resolvedParent, posixPaths) || !pathTools.isAbsolute(resolvedParent)) return null;
+    return pathTools.join(resolvedParent, pathTools.basename(path));
+  } catch {
+    return null;
+  }
+}

package/src/codex/shim-probe.ts

@@ -246,7 +246,7 @@ function readProbeMetadata(path: string, maxBytes: number): string | null {
   }
 }
 
-function probeUnixShimInstall(wrapperPath: string): UnixShimProbeResult {
+function probeUnixShimInstall(wrapperPath: string, childEnv?: NodeJS.ProcessEnv): UnixShimProbeResult {
   if (process.platform === "win32") return null;
   const probeDir = mkdtempSync(join(tmpdir(), "opencodex-shim-probe-"));
   const markerPath = join(probeDir, "result");
@@ -255,6 +255,7 @@ function probeUnixShimInstall(wrapperPath: string): UnixShimProbeResult {
   const stderrPath = join(probeDir, "stderr");
   const env: NodeJS.ProcessEnv = {
     ...process.env,
+    ...childEnv,
     BUN_BE_BUN: "1",
     OCX_SHIM_BYPASS: "1",
     OCX_SHIM_PROBE: "1",
@@ -329,12 +330,12 @@ function probeUnixShimInstall(wrapperPath: string): UnixShimProbeResult {
   }
 }
 
-function probeUnixShimFiles(files: readonly ShimFileState[]): UnixShimProbeResult {
+function probeUnixShimFiles(files: readonly ShimFileState[], childEnv?: NodeJS.ProcessEnv): UnixShimProbeResult {
   if (process.platform === "win32") return null;
   codexShimProbeHookForTests?.();
   return files
     .filter(file => !file.preserveOnly)
-    .map(file => probeUnixShimInstall(file.wrapperPath))
+    .map(file => probeUnixShimInstall(file.wrapperPath, childEnv))
     .find(result => result !== null) ?? null;
 }
 

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

@@ -1,21 +1,31 @@
 import {
   closeSync,
+  constants,
   existsSync,
   fstatSync,
   lstatSync,
   mkdirSync,
   openSync,
   readSync,
+  renameSync,
+  unlinkSync,
   writeFileSync,
   type Stats,
 } from "node:fs";
-import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { dirname, isAbsolute, join, resolve } from "node:path";
 import { getConfigDir } from "../config";
 import { recordOwnedConfigPath } from "../lib/config-ownership";
 
 export const CODEX_SHIM_STATE_MAX_BYTES = 1024 * 1024;
 
 interface ShimState {
+  schema?: 2;
+  mode?: "path-overlay";
+  launcherPath?: string;
+  wrapperIdentity?: OverlayIdentity;
+  envIdentity?: OverlayIdentity;
+  transactionId?: string;
   platform: NodeJS.Platform;
   wrapperPath: string;
   originalPath: string;
@@ -23,6 +33,51 @@ interface ShimState {
   wrappers?: ShimFileState[];
 }
 
+export interface OverlayIdentity { dev: number; ino: number }
+export interface OverlayState {
+  schema: 2;
+  mode: "path-overlay";
+  platform: NodeJS.Platform;
+  wrapperPath: string;
+  launcherPath: string;
+  // Older schema-2 records remain readable, but absent identities confer no mutation authority.
+  wrapperIdentity?: OverlayIdentity;
+  envIdentity?: OverlayIdentity;
+  transactionId?: string;
+}
+
+export function decodeOverlayState(value: unknown, configDir: string): OverlayState | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const state = value as Record<string, unknown>;
+  const platforms = ["aix", "darwin", "freebsd", "linux", "openbsd", "sunos", "android", "netbsd", "haiku", "cygwin"];
+  const validPath = (path: unknown): path is string => typeof path === "string" && isAbsolute(path) && !/[\x00-\x1f\x7f]/.test(path);
+  if (state.schema !== 2 || state.mode !== "path-overlay" || !platforms.includes(String(state.platform))
+    || !validPath(configDir) || !validPath(state.wrapperPath) || !validPath(state.launcherPath)
+    || state.wrapperPath !== join(resolve(configDir), "bin", "codex")
+    || dirname(state.wrapperPath).includes(":") || resolve(state.launcherPath) === state.wrapperPath) return null;
+  for (const field of ["originalPath", "backupPath", "realPath"]) {
+    if (state[field] !== undefined && state[field] !== state.launcherPath) return null;
+  }
+  if (state.preserveOnly !== undefined && state.preserveOnly !== false) return null;
+  if (state.wrappers !== undefined) {
+    if (!Array.isArray(state.wrappers) || state.wrappers.length !== 1) return null;
+    const file = state.wrappers[0];
+    if (!file || typeof file !== "object" || file.wrapperPath !== state.wrapperPath
+      || file.originalPath !== state.launcherPath || file.backupPath !== state.launcherPath
+      || (file.realPath !== undefined && file.realPath !== state.launcherPath) || file.preserveOnly) return null;
+  }
+  for (const key of ["wrapperIdentity", "envIdentity"]) {
+    const id = state[key] as Partial<OverlayIdentity> | undefined;
+    if (id !== undefined && (!id || !Number.isSafeInteger(id.dev) || !Number.isSafeInteger(id.ino))) return null;
+  }
+  if (state.transactionId !== undefined && (typeof state.transactionId !== "string" || !/^[a-f0-9-]{36}$/.test(state.transactionId))) return null;
+  return state as unknown as OverlayState;
+}
+
+export function readOverlayState(configDir = getConfigDir()): OverlayState | null {
+  return decodeOverlayState(readStateResult(join(configDir, "codex-shim.json")).state, configDir);
+}
+
 interface ShimFileState {
   wrapperPath: string;
   originalPath: string;
@@ -43,7 +98,7 @@ function fileErrorCode(error: unknown): string | undefined {
     : undefined;
 }
 
-function readBoundedRegularFile(path: string, maxBytes: number): { bytes: Buffer; content: string } | { warning: string } | null {
+function readBoundedRegularFile(path: string, maxBytes: number): { bytes: Buffer; content: string; stat: Stats } | { warning: string } | null {
   let lexicalBefore: Stats;
   try {
     lexicalBefore = lstatSync(path);
@@ -56,7 +111,7 @@ function readBoundedRegularFile(path: string, maxBytes: number): { bytes: Buffer
   }
   let fd: number;
   try {
-    fd = openSync(path, "r");
+    fd = openSync(path, process.platform === "win32" ? "r" : constants.O_RDONLY | constants.O_NONBLOCK);
   } catch (error) {
     if (fileErrorCode(error) === "ENOENT") return null;
     return { warning: `Codex shim state could not be opened as a regular file at ${path}.` };
@@ -87,11 +142,16 @@ function readBoundedRegularFile(path: string, maxBytes: number): { bytes: Buffer
     }
     if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size
       || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs
+      || before.mode !== after.mode || before.uid !== after.uid
       || lexicalBefore.dev !== before.dev || lexicalBefore.ino !== before.ino
-      || lexicalAfter.isSymbolicLink() || lexicalAfter.dev !== after.dev || lexicalAfter.ino !== after.ino) {
+      || lexicalBefore.mode !== before.mode || lexicalBefore.uid !== before.uid
+      || lexicalBefore.size !== before.size || lexicalBefore.mtimeMs !== before.mtimeMs || lexicalBefore.ctimeMs !== before.ctimeMs
+      || !lexicalAfter.isFile() || lexicalAfter.isSymbolicLink() || lexicalAfter.dev !== after.dev || lexicalAfter.ino !== after.ino
+      || lexicalAfter.mode !== after.mode || lexicalAfter.uid !== after.uid
+      || lexicalAfter.size !== after.size || lexicalAfter.mtimeMs !== after.mtimeMs || lexicalAfter.ctimeMs !== after.ctimeMs) {
       return { warning: `Codex shim state changed while being read at ${path}; auto-restore skipped.` };
     }
-    return { bytes: buffer, content: buffer.toString("utf8") };
+    return { bytes: buffer, content: buffer.toString("utf8"), stat: after };
   } finally {
     closeSync(fd);
   }
@@ -105,6 +165,15 @@ function readStateResult(path = statePath()): ShimStateReadResult {
     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 (state.mode !== undefined || state.schema !== undefined) {
+      // Legacy records stay readable; private overlay authority requires safe ownership.
+      // Non-writable mode drift is readable for opt-in repair, never a healthy installation.
+      if (process.platform !== "win32" && (bounded.stat.uid !== process.getuid?.() || (bounded.stat.mode & 0o022))) {
+        return { state: null, present: true, warning: "Private Codex shim state is not owned by the current user or is group/world writable; preserving artifacts. Remove the private files manually before reinstalling." };
+      }
+      const overlay = decodeOverlayState(value, dirname(path));
+      return { state: overlay ? { ...overlay, originalPath: overlay.launcherPath, backupPath: overlay.launcherPath } : null, present: true };
+    }
     if (typeof state.platform !== "string") return { state: null, present: true };
     const validFile = (item: unknown): item is ShimFileState => {
       if (!item || typeof item !== "object") return false;
@@ -134,18 +203,35 @@ function statePath(): string {
   return join(getConfigDir(), "codex-shim.json");
 }
 
-function writeState(state: ShimState): void {
+function writeState(state: ShimState | OverlayState): void {
   const path = statePath();
   recordOwnedConfigPath(getConfigDir(), path);
   if (!existsSync(getConfigDir())) mkdirSync(getConfigDir(), { recursive: true });
+  if (state.mode === "path-overlay") {
+    if (!decodeOverlayState(state, getConfigDir()) || !state.wrapperIdentity || !state.envIdentity) {
+      throw new Error("Invalid Codex overlay state: recorded ownership identities are required");
+    }
+    const staged = `${path}.${randomUUID()}.tmp`;
+    try {
+      writeFileSync(staged, JSON.stringify(state, null, 2) + "\n", { flag: "wx", mode: 0o600 });
+      renameSync(staged, path);
+    } finally {
+      try { unlinkSync(staged); } catch { /* committed or absent */ }
+    }
+    return;
+  }
   writeFileSync(path, JSON.stringify(state, null, 2) + "\n", "utf8");
 }
 
 function stateFiles(state: ShimState): ShimFileState[] {
+  if (state.mode === "path-overlay" && state.launcherPath) return [{
+    wrapperPath: state.wrapperPath, originalPath: state.launcherPath,
+    backupPath: state.launcherPath, realPath: state.launcherPath,
+  }];
   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 };
+export { readBoundedRegularFile, fileErrorCode, readStateResult, readState, statePath, writeState, stateFiles };

package/src/codex/shim.ts

@@ -8,7 +8,7 @@ import {
   unlinkSync,
   writeFileSync,
 } from "node:fs";
-import { basename, delimiter, dirname, extname, join, posix } from "node:path";
+import { basename, delimiter, dirname, extname, join, posix, win32 } from "node:path";
 import { durableBunRuntime } from "../lib/bun-runtime";
 import type { BunRuntimeSource } from "../lib/bun-runtime";
 import { serviceApiTokenFilePath } from "../lib/service-secrets";
@@ -53,14 +53,28 @@ import {
   type UnixShimProbeResult,
 } from "./shim-probe";
 import { tryAcquireShimRestoreLock } from "./shim-restore-lock";
+import {
+  isWindowsInteropDir,
+  isExecutableCodexCandidate,
+  inspectShimFile,
+  realIsDirectory,
+  resolveStableFnmCodexPath,
+  type CodexPathScanDeps,
+} from "./shim-path-resolution";
 
 export { buildUnixCodexShim, buildWindowsCodexShim, buildWindowsPowerShellCodexShim } from "./shim-templates";
 export { isVersionManagerOwnedCodexPath } from "./shim-fingerprint";
 export { CODEX_SHIM_STATE_MAX_BYTES } from "./shim-state-file";
 export { setCodexShimProbeHookForTests, setCodexShimProbeShellForTests, setCodexShimProbeObservationMsForTests } from "./shim-probe";
 export type { CodexShimBackingForCommand } from "./shim-inspect";
+export type { CodexPathScanDeps } from "./shim-path-resolution";
+export { isWindowsInteropDir } from "./shim-path-resolution";
 export { isLocalAbsoluteInspectionPath, inspectCodexShimBackingForCommand } from "./shim-inspect";
 
+import { isShim, diagnoseCodexShim } from "./shim-diagnostics";
+import { installUnixOverlay, autoRestoreUnixOverlay, uninstallUnixCodexShim, overlayPaths } from "./shim-overlay";
+export { diagnoseCodexShim, codexShimStatus, type CodexShimDiagnostic } from "./shim-diagnostics";
+
 export const CODEX_SHIM_REPLACEMENT_STABLE_MS = 100;
 
 let lastShimDiscoveryError: string | null = null;
@@ -75,6 +89,17 @@ interface InstallCodexShimInternalOptions {
   beforeGuardedRefresh?: (wrapperPath: string, index: number) => void;
 }
 
+function discoveredCodexPath(path: string, posixPaths: boolean, realpath?: (path: string) => string): string | null {
+  const resolved = resolveStableFnmCodexPath(path, posixPaths, realpath);
+  if (resolved !== null) return resolved;
+  lastShimDiscoveryError = truncateRetainedUtf8(
+    `Found codex at ${path} inside fnm's temporary multishell path, but it did not resolve to a durable Node installation. `
+    + "Refusing to install a shim; retry after fnm selects a stable installation.",
+    MAX_DIAGNOSTIC_VALUE_BYTES,
+  );
+  return null;
+}
+
 export type CodexShimAutoRestoreResult =
   | { status: "not-installed" | "healthy" | "disabled" }
   | { status: "ineligible" | "deferred"; message?: string }
@@ -95,65 +120,18 @@ function commandNames(name: string): string[] {
   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" && !content.includes(UNIX_SHIM_REVISION_MARKER)) return false;
-    if (platform !== "win32" && (lstatSync(path).mode & 0o111) === 0) return false;
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * 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 shimFile = deps.isShimFile ?? (process.platform === "win32" ? isShim : (path: string) => inspectShimFile(path) !== false);
   const isDir = deps.isDirectory ?? realIsDirectory;
+  const eligible = deps.executableEligible ?? (deps.exists ? () => true : isExecutableCodexCandidate);
   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;
+  // The injected path flavour governs join and separator alike; host-native `join` and
+  // `delimiter` made a Windows-flavoured scan split `C:\...` on a Linux host.
+  const joinPath = usePosix ? posix.join : win32.join;
+  const pathSep = usePosix ? ":" : win32.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"];
@@ -175,8 +153,14 @@ export function findCodexOnPath(deps: CodexPathScanDeps = {}): string | null {
     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 (!exists(path)) continue;
+      if (usePosix && (path === overlayPaths().wrapper || !eligible(path))) continue;
+      if (shimFile(path)) continue;
+      if (!isDir(path)) {
+        const resolved = discoveredCodexPath(path, usePosix, deps.realpath);
+        if (resolved !== null) return resolved;
+        return null;
+      }
     }
   }
 
@@ -195,11 +179,13 @@ 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)) {
+    const stableExe = existsSync(exe) && !isShim(exe) ? discoveredCodexPath(exe, false) : exe;
+    if (stableExe === null) return null;
+    if (existsSync(stableExe) && !isShim(stableExe)) {
       try {
-        if (!lstatSync(exe).isDirectory()) {
+        if (!lstatSync(stableExe).isDirectory()) {
           lastShimDiscoveryError = truncateRetainedUtf8(
-            `Found codex.exe at ${exe}. Refusing to rename a real .exe because exact codex.exe invocations would break; ` +
+            `Found codex.exe at ${stableExe}. 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,
           );
@@ -216,9 +202,12 @@ function findWindowsCodexTargets(): ShimFileState[] | null {
     const targets: ShimFileState[] = [];
     for (const path of [cmd, ps1, gitBashLauncher]) {
       if (!existsSync(path) || isShim(path)) continue;
+      const stablePath = discoveredCodexPath(path, false);
+      if (stablePath === null) return null;
+      if (!existsSync(stablePath) || isShim(stablePath)) continue;
       try {
-        if (!lstatSync(path).isDirectory()) {
-          targets.push({ wrapperPath: path, originalPath: path, backupPath: backupPathFor(path) });
+        if (!lstatSync(stablePath).isDirectory()) {
+          targets.push({ wrapperPath: stablePath, originalPath: stablePath, backupPath: backupPathFor(stablePath) });
         }
       } catch { /* keep scanning */ }
     }
@@ -1072,7 +1061,8 @@ function installCodexShimInternal(options: InstallCodexShimInternalOptions): { i
   };
 }
 
-export function installCodexShim(): { installed: boolean; message: string } {
+export function installCodexShim(): { installed: boolean; message: string; refused?: boolean; runnable?: boolean } {
+  if (process.platform !== "win32") return installUnixOverlay(findCodexOnPath);
   return installCodexShimInternal({ allowFreshInstall: true });
 }
 
@@ -1086,6 +1076,7 @@ export function autoRestoreCodexShim(options: {
   /** Narrow deterministic race seam for the guarded transaction tests. */
   beforeGuardedRefresh?: (wrapperPath: string, index: number) => void;
 }): CodexShimAutoRestoreResult {
+  if (process.platform !== "win32") return autoRestoreUnixOverlay(options);
   const stateRead = readStateResult();
   const state = stateRead.state;
   if (!state) {
@@ -1181,6 +1172,7 @@ export function autoRestoreCodexShim(options: {
 }
 
 export function uninstallCodexShim(): { removed: boolean; message: string } {
+  if (process.platform !== "win32") return uninstallUnixCodexShim();
   const state = readState();
   if (!state) return { removed: false, message: "Codex autostart shim is not installed." };
   const files = stateFiles(state);
@@ -1199,48 +1191,3 @@ export function uninstallCodexShim(): { removed: boolean; message: string } {
 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;
-}

package/src/codex/subagent-model-fallback.ts

@@ -1,3 +1,4 @@
+import { codexAccountUsesCreditsAfterLimit } from "./account-credit-use";
 /**
  * Quota-aware subagent model fallback (issue #374).
  *
@@ -233,7 +234,7 @@ export function isNativeModelQuotaExhausted(
   // Subagent fallback reads the same score, so a stale terminal reading would push
   // subagents off a native model whose window has already reset. Thread the caller's clock
   // rather than letting the scorer read wall time - the two would silently diverge.
-  const usage = computeCodexUsageScore(quota, getPoolAccountPlan(config, resolvedAccountId), now);
+  const usage = computeCodexUsageScore(quota, getPoolAccountPlan(config, resolvedAccountId), now, codexAccountUsesCreditsAfterLimit(config, resolvedAccountId));
   if (usage >= CODEX_UNKNOWN_USAGE_SCORE) return false;
   return usage >= quotaThreshold(config, resolvedAccountId);
 }