@bitkyc08/opencodex 2.64.0 → 2.65.0-preview.20260925

package/src/codex/auth-context.ts

@@ -28,6 +28,7 @@ import {
 } from "./main-account";
 import { isMainAccountPolicyBindingPending, isNativeMainTrafficBlocked, nativeMainStartupGateSnapshot } from "./native-profile-startup";
 import type { NativeMainStartupBlockReason } from "./native-profile-startup";
+import { waitForMainAccountPolicyBinding } from "./main-account-policy-wait";
 import {
   codexQuotaScopeForModel,
   computeCodexUsageScore,
@@ -67,7 +68,12 @@ import type { CodexAccountMode, OcxConfig, OcxProviderConfig } from "../types";
 import { FORWARD_HEADERS } from "../adapters/openai-responses";
 import { captureConfigGeneration } from "../lib/state-store-sweeper";
 import { extractAccountId, extractEmail } from "../oauth/chatgpt";
-import { getMainAccountHardLockStatus, isMainAccountHardLocked } from "./main-account-hard-lock";
+import {
+  MAIN_ACCOUNT_HARD_LOCK_PERCENT,
+  getMainAccountHardLockStatus,
+  isMainAccountHardLockEnabled,
+  isMainAccountHardLocked,
+} from "./main-account-hard-lock";
 import {
   captureMainAccountIdentityGeneration,
   captureMainQuotaWriter,
@@ -508,7 +514,7 @@ export class CodexMainAccountHardLockError extends CodexAccountCooldownError {
     super(MAIN_CODEX_ACCOUNT_ID, resetAt ?? 0);
     this.name = "CodexMainAccountHardLockError";
     this.resetAt = resetAt;
-    this.message = "Codex main account is blocked by the 99% main-account quota policy."
+    this.message = `Codex main account is blocked by the ${MAIN_ACCOUNT_HARD_LOCK_PERCENT}% main-account quota policy.`
       + " Choose another account, wait for quota to reset, or disable codexMainAccountHardLock in Settings.";
   }
 }
@@ -898,6 +904,8 @@ export interface ResolveCodexAuthContextOptions {
   getValidMainAccountToken?: typeof getValidMainAccountToken;
   nativeMainRefreshDependencies?: NativeMainRefreshDependencies;
   signal?: AbortSignal;
+  /** Test seam: overrides the bounded startup policy-binding wait before the hard-lock fence. */
+  mainAccountPolicyBindingWaitMs?: number;
   primeCodexPoolQuotas?: (config: OcxConfig, reason: string) => Promise<void>;
   /** Test seam for account-gated native model discovery. */
   resolveCodexModelEntitlements?: typeof resolveCodexModelEntitlements;
@@ -920,6 +928,32 @@ export interface CodexAccountSelectionAdmission {
   release(): void;
 }
 
+/**
+ * Wait, bounded, for an owned startup's main-policy binding, then fail closed while it is still
+ * in flight.
+ *
+ * #5694 turned `codexMainAccountHardLock` on by default, so this fence stopped being an opt-in
+ * rarity and started intercepting ordinary requests: for the seconds a Windows startup spends
+ * recovering, sweeping stages, and binding the pinned home, every caller-owned direct request
+ * was answered with a 503 "native-main profile maintenance is active; retry". Waiting is the
+ * right answer for a window that closes on its own -- the request resumes and the hard lock
+ * below still decides on identity and quota, exactly as it does after startup. A gate still
+ * pending at the deadline (retained recovery, a manual-recovery requirement) is a real refusal,
+ * and that is the one case that keeps the draining error.
+ *
+ * Both reads are memory-only: neither this fence nor the wait probes a foreign home.
+ */
+async function awaitMainAccountPolicyBindingSettled(
+  options: ResolveCodexAuthContextOptions,
+): Promise<void> {
+  if (!isMainAccountPolicyBindingPending()) return;
+  const settled = await waitForMainAccountPolicyBinding({
+    signal: options.signal,
+    timeoutMs: options.mainAccountPolicyBindingWaitMs,
+  });
+  if (!settled) throw new CodexMainProfileDrainingError();
+}
+
 export async function resolveCodexAuthContext(
   headers: Headers,
   config: OcxConfig,
@@ -956,9 +990,11 @@ export async function resolveCodexAuthContext(
   );
   const requestOwnedMainPinCandidate = mainPinState().candidate;
   // During an owned startup, equality cannot be established until recovery and the
-  // memory-only policy binding finish. This read-only fence never probes a foreign home.
-  if (policy.codexMainAccountHardLock === true && requestOwnedMainPinCandidate && isMainAccountPolicyBindingPending()) {
-    throw new CodexMainProfileDrainingError();
+  // memory-only policy binding finish. This read-only fence never probes a foreign home, and it
+  // waits out a window that closes on its own instead of refusing a request that arrived inside
+  // it. Only a binding still pending at the deadline fails closed.
+  if (isMainAccountHardLockEnabled(policy) && requestOwnedMainPinCandidate) {
+    await awaitMainAccountPolicyBindingSettled(options);
   }
   const preserveRequestOwnedMainPin = () => mainPinState().preserve;
   if (fixedAccountId !== undefined && options.excludeAccountId !== undefined) {
@@ -970,9 +1006,7 @@ export async function resolveCodexAuthContext(
     // Trusted substitution still has to claim and validate stored main below.
     if (!substituteStoredMain && !hasCallerCodexBearer(headers)) throw new CodexDirectAuthenticationError();
     if (!substituteStoredMain) {
-      if (policy.codexMainAccountHardLock === true && isMainAccountPolicyBindingPending()) {
-        throw new CodexMainProfileDrainingError();
-      }
+      if (isMainAccountHardLockEnabled(policy)) await awaitMainAccountPolicyBindingSettled(options);
       if (callerMatchesObservedMain(headers)) assertMainAccountPolicy(policy);
       assertCallerOwnedMainPoolNotCooled();
       if (reserve) {
@@ -1014,7 +1048,7 @@ export async function resolveCodexAuthContext(
       ) {
         throw new CodexMainProfileDrainingError();
       }
-      if (policy.codexMainAccountHardLock === true) reconcileMainCodexAccountRuntimeState();
+      if (isMainAccountHardLockEnabled(policy)) reconcileMainCodexAccountRuntimeState();
       assertMainAccountPolicy(policy);
       if (options.modelId && ACCOUNT_GATED_NATIVE_OPENAI_MODELS.has(options.modelId)) {
         const entitled = entitledCodexAccountIdsForModel(
@@ -1542,7 +1576,11 @@ export function materializeCodexUpstreamAuth(
     if (accountId) selected.set("chatgpt-account-id", accountId);
   }
   if (ctx.kind === "main" && options.substituteMainCredential === true) {
-    if (options.config?.codexMainAccountHardLock === true) reconcileMainCodexAccountRuntimeState();
+    // No config object is "no policy input", not the persisted opt-out: only a config that
+    // actually says `false` disables the default-on lock (#5694).
+    if (options.config !== undefined && isMainAccountHardLockEnabled(options.config)) {
+      reconcileMainCodexAccountRuntimeState();
+    }
     const writer = captureObservedMainWriter();
     const stored = getMainAccountToken();
     // Fail BEFORE any upstream I/O. Falling through here would send the admission secret.
@@ -1620,7 +1658,9 @@ export async function materializeCodexUpstreamAuthAsync(
     const value = headers.get(name);
     if (value) selected.set(name, value);
   }
-  if (options.config?.codexMainAccountHardLock === true) reconcileMainCodexAccountRuntimeState();
+  if (options.config !== undefined && isMainAccountHardLockEnabled(options.config)) {
+    reconcileMainCodexAccountRuntimeState();
+  }
   const writer = captureObservedMainWriter();
   const stored = await getValidMainAccountToken({
     signal: options.signal,

package/src/codex/catalog/derive-entry.ts

@@ -1,6 +1,6 @@
 import type { OcxConfig } from "../../types";
 import { effectiveProviderAlias } from "../../providers/default-aliases";
-import { identifyRoutedModel } from "../../adapters/identity";
+import { neutralizeIdentity } from "../../adapters/identity";
 import { COMBO_NAMESPACE } from "../../combos";
 import {
   CODEX_CUSTOM_MODEL_CATALOG_KIND,
@@ -145,13 +145,13 @@ export function deriveEntry(
         delete e.max_context_window;
         delete e.auto_compact_token_limit;
       }
-      // Native id for identity text + metadata lookups — the slug may be an encoded
-      // alias (`provider/vendor-model`); the model object carries the native id.
-      const modelName = model?.id ?? slug.slice(slug.indexOf("/") + 1);
       if (typeof e.base_instructions === "string") {
         // Proxy-neutral: keep the GPT-5/OpenAI disclaimer but never advertise the opencodex proxy
         // (leaking that into base_instructions is a non-first-party signature → ToS risk).
-        e.base_instructions = identifyRoutedModel(e.base_instructions, modelName);
+        // Model-neutral on disk (#5217): Codex stores this block as the session's instructions and
+        // replays it verbatim into a sub-agent spawned on a DIFFERENT model, so a baked-in model id
+        // follows the worker and misnames it. The destination id is written at request time instead.
+        e.base_instructions = neutralizeIdentity(e.base_instructions);
       }
       applyReasoningLevels(
         e,

package/src/codex/catalog/gather-capture.ts

@@ -25,11 +25,13 @@ import {
 } from "../model-cache";
 import {
   buildModelsRequest,
+  getOAuthCredentialApiBaseUrl,
   getValidAccessTokenSnapshot,
   observeActiveOAuthAccessToken,
   resolveModelsAuthToken,
   type OAuthActiveTokenObservation,
 } from "../../oauth";
+import { getAccountSet } from "../../oauth/store";
 import type { OcxConfig, OcxProviderConfig } from "../../types";
 import { modelInList } from "../../types";
 import { CODEX_REASONING_LEVELS, codexEffortRank, configuredReasoningEfforts, modelRecordValue, sanitizeCodexReasoningEfforts } from "../../reasoning-effort";
@@ -150,6 +152,12 @@ export interface CapturedProviderGather {
   readonly metadataModelIdCaseFold: boolean;
   readonly effectiveAlias?: string | null;
   readonly observedAuth?: ModelsAuthResolution;
+  /**
+   * The active OAuth account a refreshing capture was taken under. It is part of the
+   * flight's auth identity, so a caller on another account never joins a pending
+   * discovery started for this one, even when both accounts share an API host.
+   */
+  readonly refreshingOAuthAccountId?: string;
   /**
    * Configured model ids this provider must keep even when live discovery omits
    * them — combo targets that are also listed in providers.*.models (OCX-111).
@@ -315,14 +323,12 @@ export function captureTrustedOpenAiApiPolicy(
   });
 }
 
-function captureModelsRequest(
+export function captureModelsRequest(
   name: string,
   provider: OcxProviderConfig,
-  observedAuth: ModelsAuthResolution | undefined,
+  oauthApiBaseUrl: string | undefined,
 ): CapturedModelsRequest {
-  const observed = observedAuth
-    ? { oauthApiBaseUrl: observedAuth.oauthApiBaseUrl }
-    : undefined;
+  const observed = { oauthApiBaseUrl };
   const withoutCredential = buildModelsRequest(provider, undefined, name, observed);
   const withCredential = buildModelsRequest(provider, REQUEST_CREDENTIAL_SENTINEL, name, observed);
   const method = withoutCredential.method ?? "GET";
@@ -378,7 +384,18 @@ export function captureProviderGather(
     && provider.liveModels !== false
     ? authResolver.resolve(name, provider)
     : undefined;
-  const request = captureModelsRequest(name, provider, observedAuth);
+  // A refreshing capture carries the stored origin so accounts on different hosts keep separate
+  // flights. The send is rebuilt from the auth the gather resolves, and the observed path never
+  // reads the live store.
+  const oauthApiBaseUrl = observedAuth
+    ? observedAuth.oauthApiBaseUrl
+    : authResolver.kind === "refreshing" && provider.authMode === "oauth"
+      ? getOAuthCredentialApiBaseUrl(name)
+      : undefined;
+  const request = captureModelsRequest(name, provider, oauthApiBaseUrl);
+  const refreshingOAuthAccountId = !observedAuth && authResolver.kind === "refreshing" && provider.authMode === "oauth"
+    ? getAccountSet(name)?.activeAccountId
+    : undefined;
   const resolved = resolveProviderModelDiscovery(name, provider);
   const discovery = detachedFrozen({
     ...(resolved.spec ? { spec: resolved.spec } : {}),
@@ -413,6 +430,7 @@ export function captureProviderGather(
     metadataModelIdCaseFold,
     effectiveAlias,
     ...(observedAuth ? { observedAuth: Object.freeze({ ...observedAuth }) } : {}),
+    ...(refreshingOAuthAccountId ? { refreshingOAuthAccountId } : {}),
     ...(retainConfiguredModelIds && retainConfiguredModelIds.size > 0
       ? { retainConfiguredModelIds }
       : {}),
@@ -447,6 +465,7 @@ export function captureGatherFlight(
       liveModels: provider.provider.liveModels ?? null,
       credential: provider.provider.apiKey ?? null,
       observedAuth: provider.observedAuth ?? null,
+      oauthAccount: provider.refreshingOAuthAccountId ?? null,
       headers: provider.request.headersWithCredential,
       url: provider.request.url,
     }))),

package/src/codex/catalog/metadata.ts

@@ -16,7 +16,7 @@ import { getProviderRegistryEntry, providerCodexAccountMode } from "../../provid
 import { applyProviderContextCap, providerContextCap } from "../../providers/context-cap";
 import { clampAutoCompactTokenLimit } from "../../providers/auto-compact-budget";
 import { routedSlug, slugEquals, slugsEquivalent } from "../../providers/slug-codec";
-import { identifyRoutedModel } from "../../adapters/identity";
+import { neutralizeIdentity } from "../../adapters/identity";
 import { filterCursorConfiguredModelsByLiveDiscovery } from "../../adapters/cursor/discovery";
 import { fetchCursorUsableModels } from "../../adapters/cursor/live-models";
 import { isCanonicalOpenAiForwardProvider, OPENAI_API_PROVIDER_ID, OPENAI_CODEX_PROVIDER_ID } from "../../providers/openai-tiers";
@@ -584,14 +584,14 @@ function upstreamNativeEntryForSlug(slug: string): RawEntry | undefined {
   alias.display_name = presentation.displayName;
   alias.description = presentation.description;
   if (typeof alias.base_instructions === "string") {
-    alias.base_instructions = identifyRoutedModel(alias.base_instructions, slug);
+    alias.base_instructions = neutralizeIdentity(alias.base_instructions);
   }
   if (alias.model_messages && typeof alias.model_messages === "object" && !Array.isArray(alias.model_messages)) {
     const modelMessages = alias.model_messages as Record<string, unknown>;
     if (typeof modelMessages.instructions_template === "string") {
       alias.model_messages = {
         ...modelMessages,
-        instructions_template: identifyRoutedModel(modelMessages.instructions_template, slug),
+        instructions_template: neutralizeIdentity(modelMessages.instructions_template),
       };
     }
   }

package/src/codex/catalog/parsing.ts

@@ -731,6 +731,7 @@ export function applyMultiAgentMode(
 ): RawEntry[] {
   if (mode === "v2" && options.keepNativeChatGptOnV1 === true) {
     for (const entry of entries) {
+      recordMultiAgentOrigin(entry);
       entry.multi_agent_version = catalogEntryIsNativeChatGpt(entry) ? "v1" : "v2";
     }
     return entries;
@@ -739,6 +740,9 @@ export function applyMultiAgentMode(
     // Restore upstream defaults: clear any stale forced multi_agent_version and
     // re-apply upstream pins from the snapshot for native entries that have one.
     for (const entry of entries) {
+      // A forced mode recorded what this row carried before it was overwritten; returning
+      // to default consumes that record whichever branch below decides the row.
+      const origin = takeMultiAgentOrigin(entry);
       if (options.preserveDefaultMultiAgentVersion?.(entry)) continue;
       const slug = typeof entry.slug === "string" ? entry.slug : "";
       const nativeAlias = entry.opencodex_catalog_kind === CODEX_NATIVE_ALIAS_CATALOG_KIND;
@@ -777,7 +781,17 @@ export function applyMultiAgentMode(
         && isNativeCatalogEntry
         && !hasNativeDefault
         && typeof entry.multi_agent_version === "string") {
-        continue;
+        // The baseline predates this native row, so it cannot say whether the live pin
+        // is genuine. With a recorded origin it no longer has to guess: restore what the
+        // row carried before the first forced mode (issue 5636). A row without a record
+        // (older catalogs) keeps the non-destructive read.
+        if (origin === undefined) continue;
+        if (typeof origin === "string") {
+          entry.multi_agent_version = origin;
+          continue;
+        }
+        if (v2FeatureEnabled) entry.multi_agent_version = "v2";
+        else delete entry.multi_agent_version;
       } else if (v2FeatureEnabled) {
         entry.multi_agent_version = "v2";
       } else {
@@ -787,11 +801,35 @@ export function applyMultiAgentMode(
     return entries;
   }
   for (const entry of entries) {
+    recordMultiAgentOrigin(entry);
     entry.multi_agent_version = mode;
   }
   return entries;
 }
 
+/**
+ * Provenance for a forced multi-agent stamp: the value the row carried before the first
+ * forced v1/v2 pass, or null when it carried none. Repeated forced passes never replace it,
+ * so a v1 -> v2 -> default round trip still restores the original. Codex ignores unknown
+ * catalog fields, as it does opencodex_catalog_kind.
+ */
+export const MULTI_AGENT_ORIGIN_FIELD = "opencodex_multi_agent_version_origin";
+
+function recordMultiAgentOrigin(entry: RawEntry): void {
+  if (Object.hasOwn(entry, MULTI_AGENT_ORIGIN_FIELD)) return;
+  (entry as Record<string, unknown>)[MULTI_AGENT_ORIGIN_FIELD] = typeof entry.multi_agent_version === "string"
+    ? entry.multi_agent_version
+    : null;
+}
+
+/** Remove and return the recorded origin: a string pin, null for "no pin", undefined when unrecorded. */
+function takeMultiAgentOrigin(entry: RawEntry): string | null | undefined {
+  if (!Object.hasOwn(entry, MULTI_AGENT_ORIGIN_FIELD)) return undefined;
+  const raw = (entry as Record<string, unknown>)[MULTI_AGENT_ORIGIN_FIELD];
+  delete (entry as Record<string, unknown>)[MULTI_AGENT_ORIGIN_FIELD];
+  return typeof raw === "string" ? raw : raw === null ? null : undefined;
+}
+
 export function normalizeRoutedCatalogEntry(
   entry: RawEntry,
   parallelToolCalls = false,

package/src/codex/catalog/provider-models.ts

@@ -105,7 +105,7 @@ import type {
 import type { CapturedProviderGather, CatalogGatherProviderAuthOutcome, CatalogGatherProviderModelOutcome, ModelsAuthResolution, ModelsAuthResolver } from "./gather-capture";
 import { QUIET_AUTHORITATIVE_CATALOG_PROVIDERS, applyConfigHintsToCachedModels, applyProviderConfigHints, boundedOwnedBy, catalogHintsFromModelsApiItem, catalogHintsFromProviderConfig } from "./model-hints";
 import { mergeConfiguredModelsIntoLiveCatalog, shouldExposeProviderModel, warnDroppedConfiguredIdsOnce } from "./model-visibility";
-import { captureProviderGather, materializeCapturedHeaders } from "./gather-capture";
+import { captureModelsRequest, captureProviderGather, materializeCapturedHeaders } from "./gather-capture";
 
 export interface ProviderModelsResult {
   readonly models: CatalogModel[];
@@ -151,7 +151,7 @@ export async function fetchProviderModelsWithAuth(
   contextCap: number | undefined,
   resolveAuth: ModelsAuthResolver,
 ): Promise<ProviderModelsResult> {
-  const { name, provider: prov, discovery, request, metadataModelIdCaseFold } = captured;
+  const { name, provider: prov, discovery, metadataModelIdCaseFold } = captured;
   const observed = (
     models: CatalogModel[],
     state: CatalogGatherProviderModelOutcome["state"],
@@ -217,10 +217,7 @@ export async function fetchProviderModelsWithAuth(
     return observed(configured, "authoritative");
   }
   const auth: ModelsAuthResolution = captured.observedAuth ?? (resolveAuth.kind === "refreshing"
-    ? prov.authMode === "oauth" && (
-      effectiveGoogleMode(name, prov) === "cloud-code-assist"
-      || prov.adapter === "devin"
-    )
+    ? prov.authMode === "oauth"
       ? await getValidAccessTokenSnapshot(name)
         .then(snapshot => ({
           apiKey: snapshot.accessToken,
@@ -475,6 +472,11 @@ export async function fetchProviderModelsWithAuth(
       "degraded",
     );
   }
+  // The captured request predates any refresh, so a refreshing gather rebuilds it
+  // from the auth it resolved: the token and its origin, together.
+  const request = resolveAuth.kind === "refreshing"
+    ? captureModelsRequest(name, prov, auth.oauthApiBaseUrl)
+    : captured.request;
   const url = request.url;
   let headers = materializeCapturedHeaders(request, apiKey);
   // One Ollama authority contract: for canonical ollama-cloud/ollama-native rows, discovery

package/src/codex/catalog/retained-sync.ts

@@ -649,11 +649,13 @@ export async function syncCatalogModels(
   };
 }
 
-export function invalidateCodexModelsCacheWithPermit(
+export type CodexCacheInvalidationOutcome = "written" | "unchanged" | "missing_catalog" | "desired_disabled" | "failed";
+
+export function invalidateCodexModelsCacheWithPermitOutcome(
   permit: CatalogWritePermit,
   owningCodexHome: string,
   options?: CodexCatalogSyncOptions,
-): boolean {
+): CodexCacheInvalidationOutcome {
   try {
     // This permit is a REACQUISITION: refreshCodexModelCatalog's commit released
     // K before this rewrite runs, so the commit-path desired-state check cannot
@@ -661,9 +663,9 @@ export function invalidateCodexModelsCacheWithPermit(
     // routed cache write — re-read intent under this permit, same as the commit.
     // The catalog-only sync override applies here too so an explicit refresh
     // keeps the cache consistent with the catalog it just wrote.
-    if (!shouldSyncCodexOnStart(loadConfig()) && options?.allowWhenDesiredDisabled !== true) return false;
+    if (!shouldSyncCodexOnStart(loadConfig()) && options?.allowWhenDesiredDisabled !== true) return "desired_disabled";
     const catalogPath = readCodexCatalogPathForHome(owningCodexHome);
-    if (!existsSync(catalogPath)) return false;
+    if (!existsSync(catalogPath)) return "missing_catalog";
     const catalog = JSON.parse(readFileSync(catalogPath, "utf8"));
     const models = catalog.models ?? catalog;
     const cachePath = join(owningCodexHome, "models_cache.json");
@@ -711,14 +713,22 @@ export function invalidateCodexModelsCacheWithPermit(
     // `cacheSynced` mean what its name and its consumers already assume, and what
     // `pullRemoteCatalog` and the early returns in `refreshCodexModelCatalog`
     // already assert: a write happened.
-    if (!preparedBytesDifferFromDisk(preparedCache)) return false;
+    if (!preparedBytesDifferFromDisk(preparedCache)) return "unchanged";
     replaceCodexModelsCache(permit, owningCodexHome, preparedCache);
-    return true;
+    return "written";
   } catch {
-    return false;
+    return "failed";
   }
 }
 
+export function invalidateCodexModelsCacheWithPermit(
+  permit: CatalogWritePermit,
+  owningCodexHome: string,
+  options?: CodexCatalogSyncOptions,
+): boolean {
+  return invalidateCodexModelsCacheWithPermitOutcome(permit, owningCodexHome, options) === "written";
+}
+
 export function invalidateCodexModelsCache(options?: CodexCatalogSyncOptions): boolean {
   const owningCodexHome = getCodexHome();
   const outcome = withCatalogWriteSerialization(

package/src/codex/catalog/sync.ts

@@ -46,7 +46,7 @@ export {
 export {
   syncCatalogModels,
   invalidateCodexModelsCache,
-  invalidateCodexModelsCacheWithPermit,
+  invalidateCodexModelsCacheWithPermit, invalidateCodexModelsCacheWithPermitOutcome,
 } from "./retained-sync";
-export type { CodexCatalogSyncOptions } from "./retained-sync";
+export type { CodexCacheInvalidationOutcome, CodexCatalogSyncOptions } from "./retained-sync";
 export { restoreCodexCatalog, restoreCodexCatalogWithPermit } from "./restore";

package/src/codex/desktop-app-restart.ts

@@ -40,6 +40,7 @@ import { rootShells, type DesktopAppAdapter, type DesktopExec, type DesktopProce
 import { darwinDesktopAppAdapter, darwinDefaultExec } from "./desktop-app/darwin";
 import { linuxDesktopAppAdapter, linuxDefaultExec } from "./desktop-app/linux";
 import { windowsDesktopAppAdapter, windowsDefaultExec } from "./desktop-app/windows";
+import { isTestHomeGuardArmed } from "../lib/test-home-guard";
 
 export type { DesktopAppExecOptions } from "./desktop-app/types";
 
@@ -81,6 +82,7 @@ export interface DesktopAppRestartIo {
 
 export type DesktopAppRestartReason =
   | "unsupported_platform"
+  | "test_environment"
   | "package_discovery_failed"
   | "process_probe_failed"
   | "no_targets"
@@ -213,6 +215,12 @@ export function restartCodexDesktopApp(io: DesktopAppRestartIo = {}): DesktopApp
   const adapter = io.adapter ?? selected?.adapter;
   const exec = io.execFile ?? selected?.exec;
   if (!adapter || !exec) return skipped("unsupported_platform");
+  // In an armed test process a call without an injected exec would reach the real OS (an injected
+  // adapter still execs through the platform default): on a developer Mac, `performCodexRestart`
+  // tests quit the user's ChatGPT (Codex) app and relaunched it through `/usr/bin/open` with the
+  // runner's sandbox HOME, logged out. Armed means the test preload's flag, not NODE_ENV, for the
+  // reason test-home-guard gives: a real `NODE_ENV=test ocx ...` must still restart the app.
+  if (!io.execFile && isTestHomeGuardArmed()) return skipped("test_environment");
 
   // Step 0. Two restarts at once are destructive rather than merely wasteful: the
   // first quits and relaunches, the second sees the freshly started shell as a target

package/src/codex/desktop-switches.ts

@@ -88,7 +88,15 @@ export function describeCodexDesktopSwitches(
   };
 }
 
-export async function applyCodexDesktopSwitches(
+/**
+ * Re-run the Codex config injection so a setting that lives in `~/.codex/config.toml` follows the
+ * stored config NOW rather than at the next `ocx sync`.
+ *
+ * Shared by the Desktop switches (`codexDesktopAuthless`, `codexClientCompaction`) and the
+ * web-search sidecar's Codex-side key. Both write through the same artifact transaction, so the
+ * failure vocabulary — and the "run 'ocx sync' to retry" advice that reads it — has to be one thing.
+ */
+export async function applyCodexConfigInjection(
   config: OcxConfig,
 ): Promise<CodexDesktopSwitchApply> {
   if (!shouldSyncCodexOnStart(config)) {

package/src/codex/home.ts

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, posix, resolve, win32 } from "node:path";
-import { expandUserPath } from "../config";
+import { expandUserPath } from "../config/paths";
 import { redactUserPath } from "../lib/redact";
 
 export type CodexHomeDeps = {
@@ -135,9 +135,48 @@ export function findWslWindowsCodexHome(deps: CodexHomeDeps = {}): string | null
 export function defaultCodexHome(deps: CodexHomeDeps = {}): string {
   const home = (deps.homedir ?? homedir)();
   const defaultHome = join(home, ".codex");
-  const exists = deps.existsSync ?? existsSync;
-  const detected = !exists(join(defaultHome, "config.toml")) ? findWslWindowsCodexHome(deps) : null;
-  return detected ?? defaultHome;
+  // A local ~/.codex that Codex is already using is the user's Codex home even before
+  // config.toml exists (a fresh install: login writes auth.json, first use writes
+  // sessions/ and history.jsonl). A local directory with none of that state is not
+  // evidence of a local Codex: before #5441 such a home let WSL discovery pick the
+  // Windows home, and existing WSL users who run against that Windows home must not
+  // be moved to an empty local one on upgrade.
+  if (localCodexHomeIsDirectory(defaultHome, deps) && localCodexHomeInUse(defaultHome, deps)) return defaultHome;
+  return findWslWindowsCodexHome(deps) ?? defaultHome;
+}
+
+function localCodexHomeInUse(home: string, deps: CodexHomeDeps): boolean {
+  // Files and directories Codex itself writes into a home it is using. Kept local: defaultCodexHome
+  // runs during other modules' initialisation (the storage workers reach it through an import
+  // cycle), and a module-level const declared below it is still in its temporal dead zone then.
+  return ["config.toml", "auth.json", "sessions", "history.jsonl"].some(entry => pathPresent(join(home, entry), deps));
+}
+
+/** stat-based presence: an unexpected stat error counts as present, never as a reason to switch homes. */
+function pathPresent(path: string, deps: CodexHomeDeps): boolean {
+  const stat = deps.statSync ?? statSync;
+  try {
+    stat(path);
+    return true;
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException | null)?.code;
+    return !(code === "ENOENT" || code === "ENOTDIR");
+  }
+}
+
+function localCodexHomeIsDirectory(path: string, deps: CodexHomeDeps): boolean {
+  const stat = deps.statSync ?? statSync;
+  // stat, not existsSync: existsSync reports false for an access error too, and that
+  // must not read as "absent" and hand the user's state to a different home.
+  try {
+    return stat(path).isDirectory();
+  } catch (error) {
+    const code = (error as NodeJS.ErrnoException | null)?.code;
+    if (code === "ENOENT" || code === "ENOTDIR") return false;
+    // An unreadable local home is still the local home; never switch to a
+    // different Codex home because a stat failed for an unexpected reason.
+    return true;
+  }
 }
 
 export function resolveCodexHomeDir(deps: CodexHomeDeps = {}): string {