@bitkyc08/opencodex 2.59.0 → 2.61.0-preview.20260922

package/src/codex/observed-model-denials.ts

@@ -48,8 +48,55 @@ const OBSERVED_DENIAL_TTL_MS = 6 * 60 * 60_000;
 /** Bounded like the roster cache: pool size times flagship count, with room to spare. */
 const OBSERVED_DENIAL_MAX_ENTRIES = 512;
 
-/** `accountId\u0000modelId` -> expiry. Insertion order is the eviction order. */
-const observedDenials = new Map<string, number>();
+/**
+ * One entry of refusal evidence.
+ *
+ * `generation` is the credential generation the refusal was observed under (#4952). Evidence
+ * is about a CREDENTIAL, not an account id: reauthenticating the same internal account can
+ * swap the subscription underneath it, so a refusal from the previous credential says nothing
+ * about the replacement. Carrying the generation lets a reader ignore superseded evidence and
+ * lets a late reply from an older generation be refused rather than applied.
+ *
+ * It is OPTIONAL because not every account that can be refused has one. A `main-pool` context
+ * — the stored main login taking part in rotation — carries a real `accountId` and a
+ * `writerGeneration`, but no pool credential generation, because its credential lives in
+ * `auth.json` rather than the pool store. Dropping its evidence would have silently reverted
+ * #4906 for that account: the pool would re-send the same model to the login that just refused
+ * it, on every request, forever. An entry without a generation is account-scoped, and the
+ * generation fences below simply do not apply to it. This is the same rule the quota writer
+ * already uses in `core-codex-account.ts`, where an absent credential generation skips the
+ * liveness check instead of discarding the write.
+ */
+interface ObservedDenial {
+  expiresAt: number;
+  generation?: number;
+}
+
+/** `accountId\u0000modelId` -> entry. Insertion order is the eviction order. */
+const observedDenials = new Map<string, ObservedDenial>();
+
+/** Whether `generation` is still the account's live credential. */
+type GenerationLiveCheck = (accountId: string, generation: number) => boolean;
+
+/**
+ * Opens one liveness check.
+ *
+ * A FACTORY rather than a bare predicate because the production implementation reads the
+ * credential store, and a lookup can ask about several accounts. Loading once per lookup and
+ * closing over that snapshot is the shape `loadCodexAccountRecordSnapshot` exists for; a bare
+ * predicate would reload and reparse the whole store per row, on the request path.
+ *
+ * Injected rather than imported at module scope so this stays a leaf module: `account-store`
+ * reads the credential file, and a unit test of this map should not have to stand one up.
+ */
+type GenerationLiveCheckFactory = () => GenerationLiveCheck;
+
+let beginGenerationLiveCheck: GenerationLiveCheckFactory = () => () => true;
+
+/** Wire the liveness predicate. Called once at startup; tests substitute their own. */
+export function setObservedDenialGenerationCheck(begin: GenerationLiveCheckFactory): void {
+  beginGenerationLiveCheck = begin;
+}
 
 function denialKey(accountId: string, modelId: string): string {
   return `${accountId}\u0000${modelId}`;
@@ -72,12 +119,24 @@ function modelIdOfDenialKey(key: string): string {
 export function recordObservedCodexModelDenial(
   accountId: string,
   modelId: string,
+  generation: number | undefined,
   now = Date.now(),
 ): void {
+  // A refusal dispatched under generation G can arrive after G+1 has been saved. Reject it
+  // BEFORE touching the map at all, not merely when this key already holds newer evidence:
+  // with no entry for this key the stale row would otherwise be inserted, and at the entry
+  // bound it would evict a valid row that nothing can restore (#4952).
+  if (generation !== undefined && !beginGenerationLiveCheck()(accountId, generation)) return;
   const key = denialKey(accountId, modelId);
+  const existing = observedDenials.get(key);
+  // Second fence, for the window where the replacement credential has been dispatched but the
+  // store read above still answers live. Both sides must name a generation to be comparable;
+  // an account-scoped entry is not older or newer than a credential-scoped one.
+  if (existing !== undefined && existing.generation !== undefined && generation !== undefined
+    && existing.generation > generation) return;
   // Delete before set so the refreshed entry moves to the back of the eviction order.
   observedDenials.delete(key);
-  observedDenials.set(key, now + OBSERVED_DENIAL_TTL_MS);
+  observedDenials.set(key, { expiresAt: now + OBSERVED_DENIAL_TTL_MS, generation });
   while (observedDenials.size > OBSERVED_DENIAL_MAX_ENTRIES) {
     const oldest = observedDenials.keys().next();
     if (oldest.done) break;
@@ -91,8 +150,20 @@ export function recordObservedCodexModelDenial(
  * A success is newer and stronger evidence than the refusal that preceded it: whatever the
  * entitlement was when upstream refused, it is not that now.
  */
-export function clearObservedCodexModelDenial(accountId: string, modelId: string): void {
-  observedDenials.delete(denialKey(accountId, modelId));
+export function clearObservedCodexModelDenial(
+  accountId: string,
+  modelId: string,
+  generation: number | undefined,
+): void {
+  const key = denialKey(accountId, modelId);
+  const existing = observedDenials.get(key);
+  if (!existing) return;
+  // The mirror of the write fence: a success dispatched under G arriving after G+1 was
+  // refused must not clear the replacement's evidence (#4952). Equal generations clear,
+  // because that is the ordinary "this account just served this model" case.
+  if (existing.generation !== undefined && generation !== undefined
+    && existing.generation > generation) return;
+  observedDenials.delete(key);
 }
 
 /**
@@ -119,19 +190,41 @@ export function forgetObservedCodexModelDenialsForAccount(accountId: string | nu
 export function observedDeniedCodexAccountIdsForModel(
   modelId: string | undefined,
   now = Date.now(),
+  options: { excludeAccountIds?: ReadonlySet<string> } = {},
 ): ReadonlySet<string> | undefined {
   if (!modelId) return undefined;
   const denied = new Set<string>();
-  for (const [key, expiresAt] of [...observedDenials]) {
-    if (expiresAt <= now) {
+  // Opened lazily and at most once: a lookup that matches no credential-scoped row must not
+  // read the credential store at all.
+  let isLive: GenerationLiveCheck | undefined;
+  for (const [key, entry] of [...observedDenials]) {
+    if (entry.expiresAt <= now) {
       observedDenials.delete(key);
       continue;
     }
-    if (modelIdOfDenialKey(key) === modelId) denied.add(accountIdOfDenialKey(key));
+    // Model and the caller's exclusion fence FIRST. The issue asks for identity validation
+    // after the exclusion read, and an excluded account — a draining profile switch, or a
+    // request-owned credential — must produce no credential-store read on its behalf.
+    if (modelIdOfDenialKey(key) !== modelId) continue;
+    const accountId = accountIdOfDenialKey(key);
+    if (options.excludeAccountIds?.has(accountId)) continue;
+    if (entry.generation !== undefined) {
+      isLive ??= beginGenerationLiveCheck();
+      // Superseded evidence stops denying the replacement. It is SKIPPED, not deleted: the
+      // predicate cannot tell "this account reauthenticated" from "the credential store could
+      // not be read", and deleting on the second would throw away valid evidence that a
+      // transient read failure was never entitled to touch. Skipping already delivers the
+      // routing outcome the issue asks for, on every read, without depending on the
+      // conditional account-wide forget that cannot run when no roster was ever cached.
+      // Superseded rows still leave by TTL, by eviction, and by the account-wide forget.
+      if (!isLive(accountId, entry.generation)) continue;
+    }
+    denied.add(accountId);
   }
   return denied.size > 0 ? denied : undefined;
 }
 
 export function resetObservedCodexModelDenialsForTests(): void {
   observedDenials.clear();
+  beginGenerationLiveCheck = () => () => true;
 }

package/src/codex/prompt-text-probe.ts

@@ -75,7 +75,7 @@ const UNMAPPED_LAYER_IDS = [
   // The Rust source names a <git_attribution> marker pair, but a world-state section is
   // DIFF-rendered: it emits nothing on a turn where its state has not changed. Live
   // `codex debug prompt-input` (codex-cli 0.145.0, 32978 bytes) showed no such block and
-  // no attribution text. Listing the id here reports "not exposed" honestly instead of
+  // no attribution text. Listing the id here reports "unmapped" honestly instead of
   // claiming a tag this extractor has never actually matched - the same mistake the
   // header above records for permissions.
   "git-attribution",
@@ -85,7 +85,7 @@ export interface LayerText {
   /** Rendered text, when this layer produced a section on the probed turn. */
   text: string | null;
   /** Why the text is absent, when it is. */
-  reason: "ok" | "empty-source" | "not-rendered" | "not-exposed" | "unavailable";
+  reason: "ok" | "empty-source" | "not-rendered" | "not-exposed" | "unmapped" | "unavailable";
   bytes: number;
   /**
    * `expanded` is text Codex sends as written. `template` is a catalog
@@ -103,7 +103,7 @@ export interface LayerText {
 
 /**
  * Why the base prompt is or is not readable, at the granularity a reader can act
- * on. `LayerText.reason` has five coarse values and cannot express any of this,
+ * on. `LayerText.reason` has six coarse values and cannot express any of this,
  * which is why the detailed answer travels on its own record.
  */
 export type BasePromptReason =
@@ -374,7 +374,7 @@ function readBasePrompt(codexHome: string): BasePromptText {
 /**
  * Project the base prompt onto the legacy `base-instructions` layer slot.
  *
- * The slot is lossy by construction - five coarse reasons, no renderer that reads
+ * The slot is lossy by construction - six coarse reasons, no renderer that reads
  * `representation` - so it carries only what it can carry honestly: published text
  * when the source is text Codex sends, and otherwise no text at all. A template is
  * deliberately NOT `ok` here, because the dialog labels every `ok` layer "Text
@@ -944,9 +944,12 @@ export async function probePromptText(
 
   // Layers whose rendered tag we have not confirmed against live output. Leaving
   // them absent made the GUI fall through to "unavailable", which claims the probe
-  // failed when it succeeded. Saying we have no mapping is the smaller claim.
+  // failed when it succeeded. Keep this distinct from the base prompt's
+  // "not-exposed", which is confirmed to travel outside the printable message
+  // list - reusing it showed a base-prompt-specific explanation for unrelated
+  // layers.
   for (const id of UNMAPPED_LAYER_IDS) {
-    layers[id] ??= { text: null, reason: "not-exposed", bytes: 0 };
+    layers[id] ??= { text: null, reason: "unmapped", bytes: 0 };
   }
   return { ok: true, codexHome, layers, base, ...(reportedRuntime ? { runtime: reportedRuntime } : {}) };
 }

package/src/codex/routing/health-store.ts

@@ -350,6 +350,45 @@ export function deleteAccountHealth(accountId: string): void {
   upstreamHealth.delete(accountId);
 }
 
+export function carriesQuotaRefusal(health: CodexUpstreamHealth | undefined): boolean {
+  return health?.lastFailureStatus === 429 || health?.lastFailureStatus === 402;
+}
+
+/**
+ * Has this account refused a request on quota without serving one since?
+ *
+ * Thread affinity is a prompt-cache optimization and every rule around it is a preference:
+ * `autoSwitchThreshold` is a hint that an account is getting busy, and `pool.cacheAffinity`
+ * deliberately raises that bar further. A refusal is not a preference, and once the account has
+ * told THIS thread it cannot serve, the binding has nothing left to optimize.
+ *
+ * The distinction matters because the cooldown a 429 writes is deliberately short. A reset
+ * announcement is advisory — plan quota routinely frees up before the advertised instant — so
+ * {@link CODEX_MAX_RESET_DERIVED_COOLDOWN_MS} caps it at 15 minutes. The five-hour window that
+ * announcement describes is not capped, so an account whose burst window is spent looks
+ * selectable again long before it is. For an unbound request that is correct: going back to find
+ * out is how the pool learns the window moved. For a BOUND thread it is a loop with no exit —
+ * the cooldown lapses, the account still scores lowest on the only window this proxy has a
+ * reading for (its weekly bar, untouched by a burst limit), the thread rebinds, and earns the
+ * identical 429. Cleared affinity does not help: the next request re-derives the same choice.
+ * From the Codex side that reads exactly as reported — a new session rotates normally while an
+ * existing one is locked to an exhausted account until the proxy is restarted, because a restart
+ * is the only thing that drops the binding and the stale health together.
+ *
+ * `lastFailureStatus` is the right evidence because of when it ends: {@link preservedCooldownFields}
+ * strips it from every recovery write, so it survives exactly until the account actually serves a
+ * request again. Nothing here blocks that — selection is untouched, so unbound traffic still probes
+ * the account and the first success releases every thread this refused.
+ *
+ * Scope follows where the refusal was recorded. An account-wide throttle lands in
+ * `upstreamHealth` and releases every lane; a reset-derived refusal lands against one native
+ * quota group, so a spent Spark window still cannot displace the same thread's Terra binding.
+ */
+export function hasUnrecoveredCodexQuotaRefusal(accountId: string, quotaScope?: CodexQuotaScope): boolean {
+  if (carriesQuotaRefusal(getAccountHealth(accountId))) return true;
+  return quotaScope !== undefined && carriesQuotaRefusal(scopedHealthFor(accountId, quotaScope));
+}
+
 export function listScopedHealthEntries(accountId: string): Array<[CodexQuotaScope, CodexUpstreamHealth]> {
   return [...(quotaScopedHealth.get(accountId) ?? [])];
 }

package/src/codex/routing/selection.ts

@@ -22,6 +22,7 @@ import {
   dropSpentCredentialFailure,
   getAccountHealth,
   getCodexQuotaHealthSnapshot,
+  hasUnrecoveredCodexQuotaRefusal,
   isCodexAccountSoftAvoided,
   isCodexQuotaAvoided,
   isIndependentCodexQuotaScope,
@@ -276,6 +277,40 @@ export function isCacheAffinityEnabled(config: OcxConfig): boolean {
   return config.pool?.cacheAffinity !== false;
 }
 
+/**
+ * Whether quota may retire shared state while cache affinity is active.
+ *
+ * A threshold crossing is a hint that an account is getting busy, not evidence it cannot
+ * serve — the same bar {@link mayRebindAffinityForQuota} applies to a live binding. Shared
+ * state held across a model detour gets that exhaustion boundary for the same reason: the
+ * detour is request-scoped, so retiring the binding over a hint pays a cold prefix for
+ * nothing. New/unbound selection still reads {@link hasCodexQuotaHeadroom}; only
+ * preservation of an existing shared selection or thread binding qualifies here. Like the
+ * live-binding rule, the configured threshold plays no role once retention applies: a
+ * genuinely exhausted (>=100%) account releases even with threshold switching disabled,
+ * while the fallback above keeps a disabled threshold's "never drained on quota alone".
+ */
+export function hasCodexSharedStateQuotaHeadroom(
+  config: OcxConfig,
+  accountId: string,
+  quotaScope: CodexQuotaScope | undefined,
+  selectionOptions?: CodexAccountUsabilityOptions,
+  now: number = Date.now(),
+): boolean {
+  if (
+    !isCacheAffinityEnabled(config)
+    || accountPoolStrategyForScope(config, quotaScope) !== "quota"
+  ) {
+    return hasCodexQuotaHeadroom(config, accountId, selectionOptions, now);
+  }
+  const usage = computeCodexUsageScore(
+    getAccountQuota(accountId),
+    getPoolAccountPlanForSelection(config, accountId, selectionOptions),
+    now,
+  );
+  return isUnknownUsage(usage) || usage < 100;
+}
+
 /** Earliest future shared short/weekly reset; missing evidence and ties use usage order. */
 export function pickResetFirstCodexAccount(
   config: OcxConfig,
@@ -726,7 +761,8 @@ export function isHealthySharedCodexSelection(
   selectionOptions: CodexAccountUsabilityOptions | undefined,
 ): boolean {
   return isCodexAccountSelectable(config, accountId, now, quotaScope, selectionOptions)
-    && hasCodexQuotaHeadroom(config, accountId, selectionOptions, now)
+    && hasCodexSharedStateQuotaHeadroom(config, accountId, quotaScope, selectionOptions, now)
+    && !hasUnrecoveredCodexQuotaRefusal(accountId, quotaScope)
     && !shouldFailover(config, accountId, now);
 }
 

package/src/codex/routing.ts

@@ -1,5 +1,6 @@
 import { saveConfigPreservingClaudeCode } from "../config";
-import { isCodexAccountGenerationLive } from "./account-store";
+import { isCodexAccountGenerationLive, registerCodexRefreshGenerationHandoff } from "./account-store";
+import { handOffThreadAffinityGeneration } from "./routing/thread-affinity";
 import { codexAccountLogLabel } from "./account-label";
 import { isCodexAccountPaused } from "./account-pause";
 import { clearCodexAccountPin, pinnedCodexAccountId } from "./account-priority";
@@ -27,6 +28,7 @@ import {
   type CodexUpstreamOutcomeMeta,
 } from "./routing/cooldown-math";
 import {
+  carriesQuotaRefusal,
   codexPoolKeyForScope,
   codexQuotaScopeForModel,
   deleteAccountHealth,
@@ -37,6 +39,7 @@ import {
   getCodexAccountCooldownUntil,
   getCodexAccountSoftAvoidUntil,
   getCodexQuotaHealthSnapshot,
+  hasUnrecoveredCodexQuotaRefusal,
   isCodexAccountSoftAvoided,
   isCodexQuotaAvoided,
   isHealthAccountAdmissible,
@@ -92,6 +95,7 @@ import {
   getEligiblePoolAccounts,
   getPoolAccountPlanForSelection,
   hasCodexQuotaHeadroom,
+  hasCodexSharedStateQuotaHeadroom,
   isCodexAccountPlanExcluded,
   isCodexAccountSelectable,
   isHealthySharedCodexSelection,
@@ -205,6 +209,11 @@ export {
 } from "./routing/active-account";
 export { codexAccountPinDrainReason } from "./routing/pin-drain";
 export type { CodexPinDrainReason } from "./routing/pin-drain";
+
+// A shared refresh can outlive the request that opened it. Register the affinity
+// handoff with the flight so a detached G -> G+1 commit cannot strand bindings at G.
+registerCodexRefreshGenerationHandoff(handOffThreadAffinityGeneration);
+
 function hasConfiguredPoolAccount(
   config: OcxConfig,
   accountId: string,
@@ -483,45 +492,6 @@ export function resolveCodexAccountForThread(
   return resolution.status === "selected" ? resolution.accountId : null;
 }
 
-function carriesQuotaRefusal(health: CodexUpstreamHealth | undefined): boolean {
-  return health?.lastFailureStatus === 429 || health?.lastFailureStatus === 402;
-}
-
-/**
- * Has this account refused a request on quota without serving one since?
- *
- * Thread affinity is a prompt-cache optimization and every rule around it is a preference:
- * `autoSwitchThreshold` is a hint that an account is getting busy, and `pool.cacheAffinity`
- * deliberately raises that bar further. A refusal is not a preference, and once the account has
- * told THIS thread it cannot serve, the binding has nothing left to optimize.
- *
- * The distinction matters because the cooldown a 429 writes is deliberately short. A reset
- * announcement is advisory — plan quota routinely frees up before the advertised instant — so
- * {@link CODEX_MAX_RESET_DERIVED_COOLDOWN_MS} caps it at 15 minutes. The five-hour window that
- * announcement describes is not capped, so an account whose burst window is spent looks
- * selectable again long before it is. For an unbound request that is correct: going back to find
- * out is how the pool learns the window moved. For a BOUND thread it is a loop with no exit —
- * the cooldown lapses, the account still scores lowest on the only window this proxy has a
- * reading for (its weekly bar, untouched by a burst limit), the thread rebinds, and earns the
- * identical 429. Cleared affinity does not help: the next request re-derives the same choice.
- * From the Codex side that reads exactly as reported — a new session rotates normally while an
- * existing one is locked to an exhausted account until the proxy is restarted, because a restart
- * is the only thing that drops the binding and the stale health together.
- *
- * `lastFailureStatus` is the right evidence because of when it ends: {@link preservedCooldownFields}
- * strips it from every recovery write, so it survives exactly until the account actually serves a
- * request again. Nothing here blocks that — selection is untouched, so unbound traffic still probes
- * the account and the first success releases every thread this refused.
- *
- * Scope follows where the refusal was recorded. An account-wide throttle lands in
- * `upstreamHealth` and releases every lane; a reset-derived refusal lands against one native
- * quota group, so a spent Spark window still cannot displace the same thread's Terra binding.
- */
-function hasUnrecoveredCodexQuotaRefusal(accountId: string, quotaScope?: CodexQuotaScope): boolean {
-  if (carriesQuotaRefusal(getAccountHealth(accountId))) return true;
-  return quotaScope !== undefined && carriesQuotaRefusal(scopedHealthFor(accountId, quotaScope));
-}
-
 function previewReusableAffinityAccount(
   entry: ThreadAffinityEntry | undefined,
   config: OcxConfig,
@@ -946,7 +916,7 @@ export function resolveCodexAccountForThreadDetailed(
     // the account has already told this thread it cannot serve it.
     const quotaRefused = hasUnrecoveredCodexQuotaRefusal(entry.accountId, quotaScope);
     const healthyForSharedAffinity = selectableForSharedState
-      && hasCodexQuotaHeadroom(config, entry.accountId, sharedSelectionOptions, now)
+      && hasCodexSharedStateQuotaHeadroom(config, entry.accountId, quotaScope, sharedSelectionOptions, now)
       && !quotaRefused
       && !failoverReady;
     if (
@@ -1144,7 +1114,7 @@ export function resolveCodexAccountForThreadDetailed(
     sharedSelectionOptions,
   );
   const activeHealthyForSharedSelection = activeSelectableForSharedState
-    && hasCodexQuotaHeadroom(config, active, sharedSelectionOptions, now)
+    && hasCodexSharedStateQuotaHeadroom(config, active, quotaScope, sharedSelectionOptions, now)
     && !shouldFailover(config, active, now);
   if (!isCodexAccountSelectable(config, active, now, quotaScope, selectionOptions)) {
     const fallback = pickLowestUsageCodexAccount(config, active, now, quotaScope, selectionOptions);

package/src/codex/shim-templates.ts

@@ -4,11 +4,29 @@ import { serviceApiTokenFilePath } from "../lib/service-secrets";
 import { windowsEnvIndirectBatchValue } from "../lib/win-paths";
 
 const SHIM_MARKER = "opencodex codex autostart shim";
-const UNIX_SHIM_REVISION_MARKER = "opencodex unix codex shim revision 2";
+const UNIX_SHIM_REVISION_MARKER = "opencodex unix codex shim revision 3";
 
 const CODEX_SHIM_REENTRY_EXIT_CODE = 126;
 const CODEX_SHIM_REENTRY_DIAGNOSTIC = "opencodex: saved Codex launcher resolved back to the autostart shim; run ocx codex-shim uninstall and reinstall Codex before enabling codexAutoStart.";
 
+/**
+ * Said once, on stderr, when `ocx ensure` could not bring the proxy up (#5261).
+ *
+ * The shim used to discard both of ensure's streams and ignore its exit status, so a failed
+ * autostart was completely silent: Codex launched against injected routing pointing at a port
+ * nothing was listening on, and every request — sign-in included — failed with no mention of
+ * opencodex anywhere.
+ *
+ * Ensure's own streams stay discarded rather than being let through. Ensure prints progress and
+ * warnings on exit-zero runs too, and a wrapper that leaked those would put noise in front of
+ * every ordinary Codex launch, which is how a diagnostic gets ignored. The exit status is the
+ * signal; this line is the whole message.
+ *
+ * It names `ocx restore` because bringing the proxy back is only half the choice. A user who
+ * cannot sign in needs the way out that does not require the proxy at all.
+ */
+export const CODEX_SHIM_ENSURE_FAILED_DIAGNOSTIC = "opencodex: proxy autostart failed; launching Codex anyway. Run 'ocx doctor' for details, or 'ocx restore' to hand Codex back to its own account.";
+
 const CODEX_INTERNAL_COMMANDS = [
   "app-server",
   "archive",
@@ -136,7 +154,9 @@ case "$ocx_subcommand" in
     ;;
   *)
     if [ -z "$OCX_SHIM_BYPASS" ]; then
-      ${BUN_RUNTIME_SOURCE_ENV}=${shQuote(bunRuntimeSource)} ${BUN_RUNTIME_PATH_ENV}=${shQuote(bunPath)} ${shQuote(bunPath)} ${shQuote(cliPath)} ensure >/dev/null 2>&1 || true
+      if ! ${BUN_RUNTIME_SOURCE_ENV}=${shQuote(bunRuntimeSource)} ${BUN_RUNTIME_PATH_ENV}=${shQuote(bunPath)} ${shQuote(bunPath)} ${shQuote(cliPath)} ensure >/dev/null 2>&1; then
+        printf '%s\\n' ${shQuote(CODEX_SHIM_ENSURE_FAILED_DIAGNOSTIC)} >&2
+      fi
     fi
     ;;
 esac
@@ -197,6 +217,7 @@ setlocal\r
 ${windowsBatchSet(BUN_RUNTIME_SOURCE_ENV, bunRuntimeSource)}\r
 ${windowsBatchSet(BUN_RUNTIME_PATH_ENV, bunPath)}\r
 "%OCX_BUN%" "%OCX_CLI%" ensure >nul 2>nul\r
+if errorlevel 1 echo ${CODEX_SHIM_ENSURE_FAILED_DIAGNOSTIC} 1>&2\r
 endlocal\r
 :run_codex\r
 "%OCX_REAL_CODEX%" %*\r
@@ -239,13 +260,18 @@ if (-not $skipEnsure) {
   $priorRuntimePath = $env:${BUN_RUNTIME_PATH_ENV}
   $env:${BUN_RUNTIME_SOURCE_ENV} = ${psString(bunRuntimeSource)}
   $env:${BUN_RUNTIME_PATH_ENV} = ${psString(bunPath)}
-  try { & ${psString(bunPath)} ${psString(cliPath)} ensure *> $null }
+  $ocxEnsureFailed = $false
+  # Caught, not propagated: a throwing ensure used to escape this wrapper and Codex never
+  # launched at all, which is a lockout produced by the autostart helper itself (#5261).
+  try { & ${psString(bunPath)} ${psString(cliPath)} ensure *> $null; if ($LASTEXITCODE -ne 0) { $ocxEnsureFailed = $true } }
+  catch { $ocxEnsureFailed = $true }
   finally {
     if ($null -eq $priorRuntimeSource) { Remove-Item Env:\\${BUN_RUNTIME_SOURCE_ENV} -ErrorAction SilentlyContinue }
     else { $env:${BUN_RUNTIME_SOURCE_ENV} = $priorRuntimeSource }
     if ($null -eq $priorRuntimePath) { Remove-Item Env:\\${BUN_RUNTIME_PATH_ENV} -ErrorAction SilentlyContinue }
     else { $env:${BUN_RUNTIME_PATH_ENV} = $priorRuntimePath }
   }
+  if ($ocxEnsureFailed) { [Console]::Error.WriteLine(${psString(CODEX_SHIM_ENSURE_FAILED_DIAGNOSTIC)}) }
 }
 & ${psString(realCodexPath)} @args
 $codexExitCode = $LASTEXITCODE

package/src/codex/shim.ts

@@ -241,7 +241,7 @@ function backupPathFor(path: string): string {
  */
 function destroyedShimMessage(file: ShimFileState): string {
   const wrapper = existsSync(file.wrapperPath)
-    ? isShim(file.wrapperPath) ? "present but unusable" : "present but not an opencodex shim"
+    ? stableShimPathProbe(file.wrapperPath)?.prefix.includes(SHIM_MARKER) ? "present but unusable" : "present but not an opencodex shim"
     : "missing";
   const backup = existsSync(file.backupPath) ? "present" : "missing";
   const base = `Codex autostart shim not restored: wrapper ${wrapper} at ${file.wrapperPath}; original backup ${backup} at ${file.backupPath}.`;

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

@@ -905,8 +905,16 @@ export function hasCodexAgentModelFallbackField(role: string, codexHome = CODEX_
 }
 
 /** Roles whose TOML still carries `model_fallback`, including empty arrays. */
-export function scanCodexAgentRolesWithTomlModelFallback(codexHome = CODEX_HOME): string[] {
-  return listCodexAgentRoles(codexHome).filter(role => hasCodexAgentModelFallbackField(role, codexHome));
+export function scanCodexAgentRolesWithTomlModelFallback(
+  codexHome = CODEX_HOME,
+  onListError?: (cause: unknown) => void,
+): string[] {
+  try {
+    return listCodexAgentRoles(codexHome).filter(role => hasCodexAgentModelFallbackField(role, codexHome));
+  } catch (cause) {
+    onListError?.(cause);
+    return [];
+  }
 }
 
 const TOML_MODEL_KEY = /^\s*(?:model|"model"|'model')\s*=/;
@@ -984,9 +992,19 @@ const OPENCODEX_DERIVED_ROLE_MARKERS = ["generated-by: opencodex", "ocx-route:"]
  * authorizes writing to, repairing, or removing these files, and the marker-based ownership rules
  * that govern the files opencodex does write are unchanged.
  */
-export function scanOpencodexDerivedCodexAgentRolesWithoutModelPin(codexHome = CODEX_HOME): string[] {
+export function scanOpencodexDerivedCodexAgentRolesWithoutModelPin(
+  codexHome = CODEX_HOME,
+  onListError?: (cause: unknown) => void,
+): string[] {
   const findings: string[] = [];
-  for (const role of listCodexAgentRoles(codexHome)) {
+  let roles: string[];
+  try {
+    roles = listCodexAgentRoles(codexHome);
+  } catch (cause) {
+    onListError?.(cause);
+    return [];
+  }
+  for (const role of roles) {
     let content: string;
     try {
       content = readFileSync(join(codexHome, "agents", `${role}.toml`), "utf8");

package/src/combos/failover.ts

@@ -399,6 +399,9 @@ function isRequestLocalTargetIncompatibility(status: number, message: string, co
     if (errorCode === "unsupported_value"
       && (e.param === "reasoning.effort" || e.param === "reasoning_effort")
       && e.message.startsWith("Unsupported value:") && e.message.includes("not supported")) return true;
+    if (e.code === null
+      && e.param === "reasoning_effort"
+      && /^Function tools with reasoning_effort are not supported for gpt-6-astra(?:-\d{4}-\d{2}-\d{2})? in \/v1\/chat\/completions\. To use function tools, use \/v1\/responses or set reasoning_effort to 'none'\.$/.test(e.message)) return true;
     return e.param === "input"
       && (errorCode === "" || errorCode === "invalid_request_error")
       && /^Model '[^']{1,256}' does not support image inputs\./.test(e.message);