@bitkyc08/opencodex 2.81.0 → 2.83.0

package/src/codex/routing/selection.ts

@@ -19,6 +19,7 @@ import { codexPlanKey } from "../plan";
 import { MAIN_CODEX_ACCOUNT_ID, getMainAccountPlan } from "../main-account";
 import type { OcxConfig } from "../../types";
 import { CODEX_FAILURE_WINDOW_MS, computeCodexUsageScore } from "./cooldown-math";
+import { failureWindowSteersNewThreads } from "./failure-window";
 import {
   codexPoolKeyForScope,
   dropSpentCredentialFailure,
@@ -211,6 +212,7 @@ export function getEligiblePoolAccounts(
       && (!skipFailoverReadyCandidates || !shouldFailover(config, account.id, now)))
     .filter(account => getCodexQuotaHealthSnapshot(account.id, quotaScope, now) === null)
     .filter(account => !isCodexAccountSoftAvoided(account.id, now))
+    .filter(account => !failureWindowSteersNewThreads(config, account.id, now))
     .filter(account => !isCodexQuotaAvoided(account.id, quotaScope, now))
     .filter(account => !isCodexPoolRefreshCooling(account.id, now))
     .filter(account => isCodexAccountUsable(config, account.id, selectionOptions))
@@ -222,6 +224,7 @@ export function getEligiblePoolAccounts(
     && !isCodexAccountPaused(config, MAIN_CODEX_ACCOUNT_ID)
     && getCodexQuotaHealthSnapshot(MAIN_CODEX_ACCOUNT_ID, quotaScope, now) === null
     && !isCodexAccountSoftAvoided(MAIN_CODEX_ACCOUNT_ID, now)
+    && !failureWindowSteersNewThreads(config, MAIN_CODEX_ACCOUNT_ID, now)
     // The main login is not in `config.codexAccounts`, so it never passes through the
     // filters above and this is the only place an avoidance window can exclude it. Without
     // this the window a refusal announced applies to the pool but not to the account that
@@ -863,7 +866,7 @@ export function applyFailureFailover(
   selectionOptions?: CodexAccountUsabilityOptions,
   commitSharedSelection = true,
 ): string {
-  if (!shouldFailover(config, active, now)) return active;
+  if (!shouldFailover(config, active, now) && !failureWindowSteersNewThreads(config, active, now)) return active;
   const best = pickAlternateCodexAccount(config, active, now, quotaScope, selectionOptions);
   if (best) {
     // The scope still routes away from the failing account — that is this request's

package/src/codex/routing.ts

@@ -19,6 +19,13 @@ import type { OcxConfig } from "../types";
 import { captureConfigGeneration, type GenerationContext } from "../lib/state-store-sweeper";
 import { recordUpstreamHostFailure } from "./upstream-host-health";
 import type { CodexThreadLineage } from "./lineage";
+import {
+  failureWindowSteersNewThreads,
+  forgetCodexFailureWindow,
+  forgetCodexFailureWindows,
+  noteCodexFailureWindowSample,
+  settleCodexSuccessStreak,
+} from "./routing/failure-window";
 
 import { isCodexPoolRefreshCooling } from "./pool-refresh-backoff";
 import {
@@ -238,6 +245,7 @@ export function clearCodexUpstreamHealth(): void {
   clearAllManualPreferences();
   clearIdleWindowSteering();
   clearUpstreamHealthState();
+  forgetCodexFailureWindows();
   forgetRuntimeActiveCodexAccount();
   // The reconcile watermark is part of this state, not something that outlives it. Keeping
   // it across a full reset is incoherent: there is no health left to protect, yet
@@ -249,6 +257,7 @@ export function clearCodexUpstreamHealth(): void {
 
 export function clearCodexUpstreamHealthForAccount(accountId: string): void {
   deleteAllHealthForAccount(accountId);
+  forgetCodexFailureWindow(accountId);
   // Deletion is the third operator exit, next to pause and exclusion, and it is the one
   // with no reconcile path behind it: once the account is gone nothing can succeed on it,
   // so an unspent preference naming it would suppress the automatic cursor for every other
@@ -829,7 +838,7 @@ export function previewCodexAccountForRequest(
       active = pickLowerUsageAccount(config, active, usage, now, quotaScope, selectionOptions);
     }
   }
-  if (shouldFailover(config, active, now)) {
+  if (shouldFailover(config, active, now) || failureWindowSteersNewThreads(config, active, now)) {
     const best = pickLowestUsageCodexAccount(config, active, now, quotaScope, selectionOptions);
     if (best) active = best;
   }
@@ -1296,6 +1305,7 @@ export function recordCodexUpstreamOutcome(
    */
   dropSpentCredentialFailure(accountId);
   if (outcomeClass === "success") {
+    noteCodexFailureWindowSample(config, accountId, false, now);
     // The operator's one-shot is spent by a dispatch that actually worked, and only by that.
     // A failed lookup leaves it unspent so the intent survives the failure.
     consumeManualPreference(accountId, codexPoolKeyForScope(quotaScope));
@@ -1336,22 +1346,7 @@ export function recordCodexUpstreamOutcome(
     // Non-owners keep every hard-cooldown field, including someone else's live lease.
     const base = ownsProbeLease(current, meta) ? withProbeLeaseReleased(current!, now) : current;
     const preserved = preservedCooldownFields(base);
-    const failoverEnabled = (config.upstreamFailoverThreshold ?? 3) > 0;
-    if (failoverEnabled && current && current.consecutiveFailures >= 2) {
-      const consecutiveSuccesses = (current.consecutiveSuccesses ?? 0) + 1;
-      if (consecutiveSuccesses < 2) {
-        setAccountHealth(accountId, {
-          ...base!,
-          ...preserved,
-          consecutiveSuccesses,
-        });
-        return;
-      }
-    }
-    // Level 1 clears immediately; escalated accounts need two consecutive healthy terminals.
-    // Hard quota cooldown intentionally survives either recovery path.
-    if (cooldownUntil) setAccountHealth(accountId, { consecutiveFailures: 0, ...preserved });
-    else deleteAccountHealth(accountId);
+    settleCodexSuccessStreak(config, accountId, current, base, preserved, cooldownUntil);
     return;
   }
   if (outcomeClass === "caller") {
@@ -1560,6 +1555,7 @@ export function recordCodexUpstreamOutcome(
   // A transient failure concludes an owning probe; an unrelated 5xx must not
   // consume someone else's live lease or drop hard-cooldown bookkeeping (#433).
   const transientBase = ownsProbeLease(current, meta) ? withProbeLeaseReleased(current!, now) : current;
+  noteCodexFailureWindowSample(config, accountId, true, now);
   const stale = current?.lastFailureAt ? now - current.lastFailureAt > CODEX_FAILURE_WINDOW_MS : false;
   const hardCooldownUntil = getCodexAccountCooldownUntil(accountId, now) ?? undefined;
   // Soft avoid + affinity clears are part of failover. When threshold is 0, leave

package/src/codex/runtime.ts

@@ -7,6 +7,7 @@ import { codexExecInvocation, isSpawnableCodexCandidate } from "./exec-invocatio
 import { resolveCodexHomeDir } from "./home";
 import { decodeOverlayState } from "./shim-state-file";
 import { redactSecretString, redactUserPath } from "../lib/redact";
+import { SUBPROCESS_KILL_GRACE_MS, waitForSubprocessExit } from "../lib/bounded-subprocess";
 
 export type CodexRuntimeSource =
   | "environment"
@@ -68,6 +69,8 @@ export type RuntimeExecFile = (
     shell?: boolean;
     windowsVerbatimArguments?: boolean;
     env?: NodeJS.ProcessEnv;
+    signal?: AbortSignal;
+    maxBuffer?: number;
   },
 ) => string;
 
@@ -77,6 +80,7 @@ export type RuntimeExecFileAsync = (
 ) => Promise<string>;
 
 export interface ResolveCodexRuntimeDeps {
+  signal?: AbortSignal;
   env?: NodeJS.ProcessEnv;
   platform?: NodeJS.Platform;
   configDir?: string;
@@ -487,23 +491,62 @@ function probeVersion(command: string, deps: ResolveCodexRuntimeDeps): VersionPr
   }
 }
 
-const defaultExecFileAsync: RuntimeExecFileAsync = (file, args, options) =>
+export const execCodexFileAsync: RuntimeExecFileAsync = (file, args, options) =>
   new Promise((resolve, reject) => {
+    if (options.signal?.aborted) { reject(new Error("Codex subprocess aborted")); return; }
     // execFile always pipes stdout/stderr; it takes no stdio option.
-    const { stdio: _stdio, ...execOptions } = options;
-    execFile(file, args, execOptions, (error, stdout) => (error ? reject(error) : resolve(String(stdout))));
+    // Own abort/deadline termination; execFile's built-in observer can settle the
+    // callback while a SIGTERM-ignoring child is still alive.
+    const { stdio: _stdio, signal: _signal, timeout: _timeout, ...execOptions } = options;
+    let settled = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let abort = () => {};
+    const finish = (error: Error | null, stdout = "") => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      options.signal?.removeEventListener("abort", abort);
+      if (error) reject(error); else resolve(stdout);
+    };
+    const child = execFile(file, args, execOptions, (error, stdout) => {
+      if (error && child.exitCode === null && child.signalCode === null) stop(error);
+      else finish(error, String(stdout));
+    });
+    const exited = new Promise<number>(resolveExit => {
+      child.once("exit", code => resolveExit(code ?? 1));
+      // A kill error is not exit proof; only failed spawn has no child to reap.
+      child.once("error", () => { if (!child.pid) resolveExit(1); });
+    });
+    // A reaper owns actual exit independently of caller-facing promise settlement.
+    let stopping = false;
+    const stop = (error: Error) => {
+      if (stopping) return;
+      stopping = true;
+      try { child.kill(); } catch { /* exit/error observation still owns reaping */ }
+      child.stdout?.destroy();
+      child.stderr?.destroy();
+      void waitForSubprocessExit({ exited, kill: () => child.kill("SIGKILL") }, SUBPROCESS_KILL_GRACE_MS);
+      finish(error);
+    };
+    abort = () => stop(new Error("Codex subprocess aborted"));
+    options.signal?.addEventListener("abort", abort, { once: true });
+    if (options.timeout > 0) {
+      timer = setTimeout(() => stop(new Error("Codex subprocess deadline exceeded")), options.timeout);
+      timer.unref?.();
+    }
+    if (options.signal?.aborted) abort();
   });
 
 /** probeVersion with the same sandbox and outcomes, but the exec never holds the event loop. */
 async function probeVersionAsync(command: string, deps: ResolveCodexRuntimeDeps): Promise<VersionProbeResult> {
   const settled = versionProbePrecheck(command, deps);
   if (settled) return settled;
-  const exec = deps.execFile ?? defaultExecFileAsync;
+  const exec = deps.execFile ?? execCodexFileAsync;
   let probeHome: string | undefined;
   try {
     probeHome = mkdtempSync(join(tmpdir(), "ocx-codex-probe-"));
     const { file, args, options } = versionProbeInvocation(command, deps, probeHome);
-    return versionProbeOutput(await exec(file, args, options));
+    return versionProbeOutput(await exec(file, args, { ...options, signal: deps.signal }));
   } catch (error) {
     return versionProbeError(error, probeHome);
   } finally {
@@ -782,9 +825,7 @@ function persistedRuntimeCacheStamp(deps: ResolveCodexRuntimeDeps): string {
   const configDir = deps.configDir ?? getConfigDir();
   const read = deps.readFileSync ?? ((path, encoding) => readFileSync(path, encoding));
   try {
-    const raw = parsePersistedCodexRuntime(read(codexRuntimeStatePath(configDir), "utf8"));
-    if (!raw) return "";
-    return `${raw.command}|${raw.selectedVersion ?? ""}|${raw.updatedAt ?? ""}`;
+    return read(codexRuntimeStatePath(configDir), "utf8");
   } catch {
     return "";
   }
@@ -793,7 +834,8 @@ function persistedRuntimeCacheStamp(deps: ResolveCodexRuntimeDeps): string {
 function resolveCacheKey(deps: ResolveCodexRuntimeDeps): string | null {
   // Only memoize uninjected process-env resolves (settings/status hot paths).
   if (
-    deps.execFileSync
+    deps.signal
+    || deps.execFileSync
     || deps.execFile
     || deps.existsSync
     || deps.readFileSync
@@ -804,8 +846,14 @@ function resolveCacheKey(deps: ResolveCodexRuntimeDeps): string | null {
   ) {
     return null;
   }
+  return codexRuntimeSelectionIdentity(deps);
+}
+
+/** Exec-free input identity, including pin changes made by another process. */
+export function codexRuntimeSelectionIdentity(deps: ResolveCodexRuntimeDeps = {}): string {
   const env = deps.env ?? process.env;
   return JSON.stringify({
+    configDir: deps.configDir ?? getConfigDir(),
     cli: env.CODEX_CLI_PATH ?? "",
     path: env.PATH ?? "",
     platform: deps.platform ?? process.platform,
@@ -859,7 +907,12 @@ export function resolveCodexRuntime(deps: ResolveCodexRuntimeDeps = {}): Resolve
   return cloneAndDeepFreeze(result);
 }
 
-let asyncResolveInflight: { key: string; epoch: number; promise: Promise<ResolveCodexRuntimeResult> } | null = null;
+interface AsyncRuntimeObservation {
+  readonly result: ResolveCodexRuntimeResult;
+  readonly inputs: string;
+  readonly epoch: number | null;
+}
+let asyncResolveInflight: { key: string; epoch: number; promise: Promise<AsyncRuntimeObservation> } | null = null;
 
 /**
  * resolveCodexRuntime for server request paths: same selection and process memo, but every
@@ -869,16 +922,29 @@ let asyncResolveInflight: { key: string; epoch: number; promise: Promise<Resolve
 export async function resolveCodexRuntimeAsync(
   deps: ResolveCodexRuntimeDeps = {},
 ): Promise<ResolveCodexRuntimeResult> {
+  return cloneAndDeepFreeze((await resolveCodexRuntimeObservationAsync(deps)).result);
+}
+
+async function resolveCodexRuntimeObservationAsync(deps: ResolveCodexRuntimeDeps): Promise<AsyncRuntimeObservation> {
+  const inputs = codexRuntimeSelectionIdentity(deps);
+  const observed = (result: ResolveCodexRuntimeResult, epoch: number | null): AsyncRuntimeObservation => ({ result, inputs, epoch });
   // A deferred selection never execs, so the sync path is already nonblocking.
-  if (deps.probeVersion === false) return resolveCodexRuntime(deps);
-  const cacheKey = resolveCacheKey(deps);
+  if (deps.probeVersion === false) return observed(resolveCodexRuntime(deps), resolveCacheEpoch);
+  const cacheKey = resolveCacheKey({ ...deps, signal: undefined });
   if (cacheKey && resolveCache && resolveCache.key === cacheKey && Date.now() - resolveCache.at < RESOLVE_CACHE_MS) {
-    return cloneAndDeepFreeze(resolveCache.value);
+    return observed(cloneAndDeepFreeze(resolveCache.value), resolveCacheEpoch);
   }
-  if (!cacheKey) return cloneAndDeepFreeze(await resolveCodexRuntimeUncachedAsync(deps));
   const startedEpoch = resolveCacheEpoch;
+  // A cancellable miss owns its probes; a warm memo remains usable without a new child.
+  if (!cacheKey || deps.signal) {
+    const result = await resolveCodexRuntimeUncachedAsync(deps);
+    const current = !deps.signal?.aborted && resolveCacheEpoch === startedEpoch
+      && codexRuntimeSelectionIdentity(deps) === inputs;
+    if (current && cacheKey) publishResolveCache(cacheKey, Date.now(), result);
+    return observed(result, current ? resolveCacheEpoch : null);
+  }
   if (asyncResolveInflight?.key === cacheKey && asyncResolveInflight.epoch === startedEpoch) {
-    return cloneAndDeepFreeze(await asyncResolveInflight.promise);
+    return asyncResolveInflight.promise;
   }
   const promise = resolveCodexRuntimeUncachedAsync(deps).then(result => {
     // A persist or clear while the probes ran makes this answer the previous selection's;
@@ -886,13 +952,14 @@ export async function resolveCodexRuntimeAsync(
     // rewrite codex-runtime.json without touching this epoch, so the key is read again too.
     if (resolveCacheEpoch === startedEpoch && resolveCacheKey(deps) === cacheKey) {
       publishResolveCache(cacheKey, Date.now(), result);
+      return observed(result, resolveCacheEpoch);
     }
-    return result;
+    return observed(result, null);
   }).finally(() => {
     if (asyncResolveInflight?.promise === promise) asyncResolveInflight = null;
   });
   asyncResolveInflight = { key: cacheKey, epoch: startedEpoch, promise };
-  return cloneAndDeepFreeze(await promise);
+  return promise;
 }
 
 /**
@@ -1087,7 +1154,10 @@ function resolveCodexRuntimeUncached(deps: ResolveCodexRuntimeDeps = {}): Resolv
 async function resolveCodexRuntimeUncachedAsync(deps: ResolveCodexRuntimeDeps): Promise<ResolveCodexRuntimeResult> {
   const steps = resolveCodexRuntimeSteps(deps);
   let step = steps.next();
-  while (!step.done) step = steps.next(await probeVersionAsync(step.value.command, deps));
+  while (!step.done) {
+    if (deps.signal?.aborted) throw new Error("Codex runtime resolution aborted");
+    step = steps.next(await probeVersionAsync(step.value.command, deps));
+  }
   return step.value;
 }
 
@@ -1096,6 +1166,24 @@ export function resolveAndPersistCodexRuntime(
   deps: ResolveCodexRuntimeDeps = {},
 ): ResolveCodexRuntimeResult {
   const result = resolveCodexRuntime(deps);
+  return persistResolvedCodexRuntime(result, deps);
+}
+
+/** Same selection/persistence as the CLI driver, with stale async results rejected. */
+export async function resolveAndPersistCodexRuntimeAsync(
+  deps: ResolveCodexRuntimeDeps = {},
+  isCurrent: () => boolean = () => true,
+): Promise<ResolveCodexRuntimeResult | null> {
+  const observation = await resolveCodexRuntimeObservationAsync(deps);
+  if (!isCurrent() || observation.epoch === null || observation.epoch !== resolveCacheEpoch
+    || observation.inputs !== codexRuntimeSelectionIdentity(deps)) return null;
+  return cloneAndDeepFreeze(persistResolvedCodexRuntime(observation.result, deps));
+}
+
+function persistResolvedCodexRuntime(
+  result: ResolveCodexRuntimeResult,
+  deps: ResolveCodexRuntimeDeps,
+): ResolveCodexRuntimeResult {
   // Only WRITE when the selection actually changed. persistCodexRuntime() clears the
   // in-process resolve memo and persistedRuntimeCacheStamp() folds `updatedAt` into the
   // cache key, so an unconditional rewrite made every caller re-run the ~1s

package/src/codex/shim.ts

@@ -9,7 +9,9 @@ import {
   writeFileSync,
 } from "node:fs";
 import { basename, delimiter, dirname, extname, join, posix, win32 } from "node:path";
-import { durableBunRuntime } from "../lib/bun-runtime";
+import { durableBunRuntime, type DurableBunRuntime } from "../lib/bun-runtime";
+import { assertSelectedRuntimeWritable, RuntimePreflightError, type RuntimePreflightDeps } from "../lib/bun-runtime-preflight";
+import { getConfigDir } from "../config";
 import type { BunRuntimeSource } from "../lib/bun-runtime";
 import { serviceApiTokenFilePath } from "../lib/service-secrets";
 import { isWslRuntime, wslAutomountRoot } from "./home";
@@ -83,7 +85,9 @@ export function lastCodexDiscoveryError(): string | null {
   return lastShimDiscoveryError;
 }
 
-interface InstallCodexShimInternalOptions {
+interface InstallCodexShimInternalOptions extends RuntimePreflightDeps {
+  runtime?: DurableBunRuntime;
+  runtimeAdmitted?: boolean;
   expectedReplacements?: ReadonlyMap<string, ShimPathFingerprint>;
   allowFreshInstall: boolean;
   beforeGuardedRefresh?: (wrapperPath: string, index: number) => void;
@@ -105,12 +109,11 @@ export type CodexShimAutoRestoreResult =
   | { status: "ineligible" | "deferred"; message?: string }
   | { status: "restored"; message: string };
 
-function cliEntry(): { bun: string; bunRuntimeSource: BunRuntimeSource; cli: string } {
+function cliEntry(runtime: DurableBunRuntime = durableBunRuntime()): { bun: string; bunRuntimeSource: BunRuntimeSource; 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.
   // Path and provenance resolve together so the marker always describes this binary.
-  const runtime = durableBunRuntime();
   return { bun: runtime.path, bunRuntimeSource: runtime.source, cli: join(import.meta.dir, "..", "cli", "index.ts") };
 }
 
@@ -345,8 +348,8 @@ function rollbackFreshShimInstall(journal: readonly FreshShimInstallJournalEntry
  * updater's wrapper can carry them, and a replacement landing between the write
  * and the observation is otherwise indistinguishable from our own file.
  */
-function writeShim(wrapperPath: string, realCodexPath: string): { dev: number; ino: number } | undefined {
-  const { bun, bunRuntimeSource, cli } = cliEntry();
+function writeShim(wrapperPath: string, realCodexPath: string, runtime?: DurableBunRuntime): { dev: number; ino: number } | undefined {
+  const { bun, bunRuntimeSource, cli } = cliEntry(runtime);
   if (process.platform === "win32") {
     const lower = wrapperPath.toLowerCase();
     if (lower.endsWith(".ps1")) {
@@ -458,7 +461,7 @@ function replaceOwnedBackup(sourcePath: string, backupPath: string): void {
   }
 }
 
-function refreshShimFile(file: ShimFileState): boolean {
+function refreshShimFile(file: ShimFileState, runtime: DurableBunRuntime): boolean {
   if (file.preserveOnly) {
     if (existsSync(file.originalPath) && !isShim(file.originalPath)) {
       replaceOwnedBackup(file.originalPath, file.backupPath);
@@ -474,10 +477,10 @@ function refreshShimFile(file: ShimFileState): boolean {
       file,
       expectedReplacement: replacement.fingerprint,
       sourcePath: file.wrapperPath,
-    }]);
+    }], undefined, undefined, runtime);
   }
   if (!existsSync(file.wrapperPath) && existsSync(file.backupPath)) {
-    writeShim(file.wrapperPath, file.realPath ?? file.backupPath);
+    writeShim(file.wrapperPath, file.realPath ?? file.backupPath, runtime);
     const writtenWrapper = stableShimPathProbe(file.wrapperPath);
     if (!writtenWrapper || !writtenWrapper.prefix.includes(SHIM_MARKER)) {
       return false;
@@ -503,7 +506,7 @@ function refreshShimFile(file: ShimFileState): boolean {
   }
   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);
+    writeShim(file.wrapperPath, file.realPath ?? file.backupPath, runtime);
     return true;
   }
   return false;
@@ -610,6 +613,7 @@ function applyGuardedRefreshTransaction(
   operations: readonly GuardedRefreshOperation[],
   beforeGuardedRefresh?: (wrapperPath: string, index: number) => void,
   commitState?: () => void,
+  runtime?: DurableBunRuntime,
 ): boolean {
   const journal: GuardedRefreshJournalEntry[] = [];
   let applyError: Error | null = null;
@@ -643,7 +647,7 @@ function applyGuardedRefreshTransaction(
       if (!movedReplacement) throw new Error("Codex shim guarded refresh could not fingerprint the staged launcher");
       entry.movedReplacementFingerprint = movedReplacement.fingerprint;
       entry.wrapperWriteStarted = true;
-      const writtenInode = writeShim(operation.file.wrapperPath, operation.file.realPath ?? operation.file.backupPath);
+      const writtenInode = writeShim(operation.file.wrapperPath, operation.file.realPath ?? operation.file.backupPath, runtime);
       // Claim our own partial write before the hook can fail (see fresh install).
       entry.writtenWrapperFingerprint = ownedWrapperFingerprint(operation.file.wrapperPath, writtenInode);
       codexShimGuardedWriteHookForTests?.();
@@ -747,7 +751,7 @@ type ObsoleteUnixShimRefreshResult =
   | { installed: true; message: string }
   | { installed: false; deferred: boolean; message: string };
 
-function refreshObsoleteUnixShims(files: readonly ShimFileState[]): ObsoleteUnixShimRefreshResult {
+function refreshObsoleteUnixShims(files: readonly ShimFileState[], runtime?: DurableBunRuntime): ObsoleteUnixShimRefreshResult {
   if (process.platform === "win32") {
     return { installed: false, deferred: false, message: "Codex autostart shim is already current." };
   }
@@ -786,7 +790,7 @@ function refreshObsoleteUnixShims(files: readonly ShimFileState[]): ObsoleteUnix
         throw new Error("Codex autostart shim upgrade could not fingerprint the staged wrapper");
       }
       entry.wrapperWriteStarted = true;
-      const writtenInode = writeShim(file.wrapperPath, file.realPath ?? file.backupPath);
+      const writtenInode = writeShim(file.wrapperPath, file.realPath ?? file.backupPath, runtime);
       const writtenWrapper = stableShimPathProbe(file.wrapperPath);
       if (!writtenWrapper || !isCurrentUnixShimProbe(writtenWrapper)) {
         throw new Error("Codex autostart shim upgrade could not fingerprint the regenerated wrapper");
@@ -876,6 +880,19 @@ function refreshObsoleteUnixShims(files: readonly ShimFileState[]): ObsoleteUnix
 
 function installCodexShimInternal(options: InstallCodexShimInternalOptions): { installed: boolean; message: string } {
   const existing = readState();
+  const filesBefore = existing ? stateFiles(existing) : [];
+  if (filesBefore.length > 0 && filesBefore.every(file => {
+    if (file.preserveOnly) return existsSync(file.backupPath) && !existsSync(file.originalPath);
+    const probe = stableShimPathProbe(file.wrapperPath);
+    return hasUsableBackingPath(file) && probe !== null && isHealthyShimProbe(probe, process.platform);
+  })) {
+    return { installed: false, message: "Codex autostart shim is already installed." };
+  }
+  const runtime = options.runtime ?? Object.freeze({ ...(options.selectRuntime ?? durableBunRuntime)() });
+  if (!options.runtimeAdmitted) {
+    const configDir = (options.configDir ?? getConfigDir)();
+    (options.assertRuntimeWritable ?? assertSelectedRuntimeWritable)(runtime, configDir, { rootWasAbsent: !existsSync(configDir) });
+  }
   if (existing) {
     const files = stateFiles(existing);
     if (!options.expectedReplacements && process.platform !== "win32") {
@@ -907,7 +924,7 @@ function installCodexShimInternal(options: InstallCodexShimInternalOptions): { i
           throw writeError;
         }
       };
-      if (!applyGuardedRefreshTransaction(operations, options.beforeGuardedRefresh, commitState)) {
+      if (!applyGuardedRefreshTransaction(operations, options.beforeGuardedRefresh, commitState, runtime)) {
         return { installed: false, message: "Codex shim auto-restore deferred because tracked launchers changed." };
       }
       return {
@@ -916,7 +933,7 @@ function installCodexShimInternal(options: InstallCodexShimInternalOptions): { i
       };
     }
     let refreshed = false;
-    for (const file of files) refreshed = refreshShimFile(file) || refreshed;
+    for (const file of files) refreshed = refreshShimFile(file, runtime) || refreshed;
     const allInstalled = files.every(file => file.preserveOnly
       ? existsSync(file.backupPath) && !existsSync(file.originalPath)
       : existsSync(file.wrapperPath)
@@ -988,7 +1005,7 @@ function installCodexShimInternal(options: InstallCodexShimInternalOptions): { i
       }
       if (!target.preserveOnly) {
         entry.wrapperWriteStarted = true;
-        const writtenInode = writeShim(target.wrapperPath, target.realPath ?? target.backupPath);
+        const writtenInode = writeShim(target.wrapperPath, target.realPath ?? target.backupPath, runtime);
         entry.writtenWrapperInode = writtenInode;
         codexShimFreshWriteHookForTests?.();
         if (process.platform !== "win32") {
@@ -1061,12 +1078,12 @@ function installCodexShimInternal(options: InstallCodexShimInternalOptions): { i
   };
 }
 
-export function installCodexShim(): { installed: boolean; message: string; refused?: boolean; runnable?: boolean } {
+export function installCodexShim(deps: RuntimePreflightDeps = {}): { installed: boolean; message: string; refused?: boolean; runnable?: boolean } {
   if (process.platform !== "win32") return installUnixOverlay(findCodexOnPath);
-  return installCodexShimInternal({ allowFreshInstall: true });
+  return installCodexShimInternal({ ...deps, allowFreshInstall: true });
 }
 
-export function autoRestoreCodexShim(options: {
+export function autoRestoreCodexShim(options: RuntimePreflightDeps & {
   enabled: () => boolean;
   stabilitySleep?: (ms: number) => void;
   /** Narrow deterministic seam used to hold the interprocess lock in tests. */
@@ -1133,6 +1150,14 @@ export function autoRestoreCodexShim(options: {
     };
   }
 
+  const runtime = Object.freeze({ ...(options.selectRuntime ?? durableBunRuntime)() });
+  try {
+    const configDir = (options.configDir ?? getConfigDir)();
+    (options.assertRuntimeWritable ?? assertSelectedRuntimeWritable)(runtime, configDir, { rootWasAbsent: !existsSync(configDir) });
+  } catch (error) {
+    if (error instanceof RuntimePreflightError) return { status: "deferred", message: error.message };
+    throw error;
+  }
   const lock = tryAcquireShimRestoreLock(options.beforeStaleRestoreLockDelete);
   if (!lock) return { status: "deferred" };
   try {
@@ -1159,6 +1184,7 @@ export function autoRestoreCodexShim(options: {
       expectedReplacements.set(path, secondProbe.fingerprint);
     }
     const result = installCodexShimInternal({
+      runtime, runtimeAdmitted: true,
       allowFreshInstall: false,
       expectedReplacements,
       beforeGuardedRefresh: options.beforeGuardedRefresh,