fix(codex): keep native-main admission open across startup convergence and stop

scripts/test-layout/layout.json

@@ -1050,6 +1050,7 @@
     "main-account-hard-lock-default.test.ts": "codex-integration",
     "main-account-hard-lock-policy.test.ts": "codex-integration",
     "main-account-hard-lock-recovery.test.ts": "codex-integration",
+    "main-account-policy-binding-wait.test.ts": "codex-integration",
     "main-device-reauth-api.test.ts": "codex-integration",
     "main-device-reauth-ui.test.ts": "gui",
     "main-device-reauth.test.ts": "codex-integration",
@@ -1133,6 +1134,7 @@
     "native-profile-recovery.test.ts": "codex-integration",
     "native-profile-route-security.test.ts": "codex-integration",
     "native-profile-stage-lifecycle.test.ts": "codex-integration",
+    "native-profile-startup-release.test.ts": "codex-integration",
     "native-profile-startup.test.ts": "codex-integration",
     "native-profile-store.test.ts": "codex-integration",
     "new-model-policy.test.ts": "providers",

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,
@@ -903,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;
@@ -925,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,
@@ -961,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 (isMainAccountHardLockEnabled(policy) && 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) {
@@ -975,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 (isMainAccountHardLockEnabled(policy) && isMainAccountPolicyBindingPending()) {
-        throw new CodexMainProfileDrainingError();
-      }
+      if (isMainAccountHardLockEnabled(policy)) await awaitMainAccountPolicyBindingSettled(options);
       if (callerMatchesObservedMain(headers)) assertMainAccountPolicy(policy);
       assertCallerOwnedMainPoolNotCooled();
       if (reserve) {

src/codex/main-account-policy-wait.ts

@@ -0,0 +1,109 @@
+import {
+  isMainAccountPolicyBindingPending,
+  waitForNativeMainStartupGate,
+} from "./native-profile-startup";
+
+/**
+ * How long a request waits for an owned startup to finish binding the main-account policy
+ * before it is refused as draining.
+ *
+ * `codexMainAccountHardLock` is on by default (#5694), so the admission fence beside this
+ * constant is no longer an opt-in rarity: every request that arrives while a process-owned
+ * startup is still recovering, sweeping stages, and binding the pinned home lands on it. That
+ * window is milliseconds on a warm Linux host and seconds on Windows, which is why the fence
+ * waits for the gate instead of failing the request the moment it arrives.
+ *
+ * 15 s is deliberately just above one startup claim wait: both exclusive claims
+ * (`withNativeMainExclusiveClaim` in `convergeOwnedStartup`) allow 10 s before they give up, so a
+ * request that arrived during the last claim is not refused in the instant before the gate would
+ * have opened. Anything longer stops being a courtesy to the client and starts being a hung
+ * request, and a gate still blocked after this leaves a real answer -- retained recovery or a
+ * manual-recovery requirement -- where waiting cannot help, which is what the draining error says.
+ */
+export const MAIN_ACCOUNT_POLICY_BINDING_WAIT_MS = 15_000;
+
+/**
+ * Repoll interval for the one window where the settle promise is already resolved and the gate
+ * still reads pending: a manual-recovery fence publishes a resolved promise while an in-flight
+ * convergence is still marked pending, and re-awaiting that same resolved promise would spin the
+ * microtask queue -- which never lets the deadline timer fire.
+ */
+const MAIN_ACCOUNT_POLICY_BINDING_REPOLL_MS = 25;
+
+export interface MainAccountPolicyBindingWait {
+  /** Ends the wait with the signal's reason, as an aborted request must. */
+  signal?: AbortSignal;
+  /** Overrides {@link MAIN_ACCOUNT_POLICY_BINDING_WAIT_MS} for a bounded focused test. */
+  timeoutMs?: number;
+}
+
+/**
+ * Wait, bounded, for an owned startup's main-account policy binding to settle.
+ *
+ * Returns `true` once the binding is no longer pending, `false` when the deadline passed with it
+ * still in flight. Callers fail closed on `false`; the gate itself is re-read every iteration
+ * because a rearm replaces the settle promise rather than resolving the one already held.
+ */
+export async function waitForMainAccountPolicyBinding(
+  wait: MainAccountPolicyBindingWait = {},
+): Promise<boolean> {
+  const signal = wait.signal;
+  const timeoutMs = Math.max(0, wait.timeoutMs ?? MAIN_ACCOUNT_POLICY_BINDING_WAIT_MS);
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    if (!isMainAccountPolicyBindingPending()) return true;
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) return false;
+    const settledNow = await raceSettle(waitForNativeMainStartupGate(), remaining, signal);
+    // Settling does not always clear the flag: the gate may have been rearmed, or the resolved
+    // promise above may belong to a fence that never released the entry. Yield to the event loop
+    // before asking again so this stays a poll rather than a busy-wait.
+    if (settledNow && isMainAccountPolicyBindingPending()) {
+      await pause(Math.min(remaining, MAIN_ACCOUNT_POLICY_BINDING_REPOLL_MS), signal);
+    }
+  }
+}
+
+/** `true` when the settle promise resolved first, `false` on the deadline. */
+async function raceSettle(
+  settle: Promise<unknown>,
+  timeoutMs: number,
+  signal?: AbortSignal,
+): Promise<boolean> {
+  if (signal?.aborted) throw signal.reason;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let onAbort: (() => void) | undefined;
+  const deadline = new Promise<boolean>(resolve => {
+    timer = setTimeout(() => resolve(false), timeoutMs);
+    // A request waiting on a startup gate must never be the reason the process stays alive.
+    timer.unref?.();
+  });
+  const aborted = new Promise<never>((_resolve, reject) => {
+    if (!signal) return;
+    onAbort = () => reject(signal.reason);
+    signal.addEventListener("abort", onAbort);
+  });
+  try {
+    // A rejected settle is not an error here: the loop re-reads the gate and decides.
+    return await Promise.race([settle.then(() => true, () => true), deadline, aborted]);
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+    if (signal && onAbort) signal.removeEventListener("abort", onAbort);
+  }
+}
+
+/** One short, abortable, unref'd yield so the loop cannot monopolize the microtask queue. */
+function pause(ms: number, signal?: AbortSignal): Promise<void> {
+  if (signal?.aborted) return Promise.reject(signal.reason);
+  return new Promise<void>((resolve, reject) => {
+    const finish = (settle: () => void) => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      settle();
+    };
+    const timer = setTimeout(() => finish(resolve), ms);
+    timer.unref?.();
+    const onAbort = () => finish(() => reject(signal?.reason));
+    signal?.addEventListener("abort", onAbort);
+  });
+}

src/codex/native-profile-startup.ts

@@ -201,7 +201,9 @@ function scheduleStageSweep(entry: StartupEntry): void {
 }
 
 function convergeOwnedStartup(entry: StartupEntry): void {
-  if (entry.recoveryStarted) return;
+  // The map entry is the gate's owner of record. A released one has been deleted, and every
+  // write below belongs to a generation nothing is waiting for any more.
+  if (entry.recoveryStarted || startupEntries.get(entry.homeId) !== entry) return;
   entry.recoveryStarted = true;
   const currentEpoch = entry.epoch;
   snapshot = { status: "blocked", homeId: entry.homeId, reason: "recovery-pending" };
@@ -405,6 +407,21 @@ export function startNativeMainStartupLifecycle(
     entry!.sweepTimer = undefined;
     entry!.unsubscribe();
     startupEntries.delete(homeId);
+    // A released owner cannot leave the process fenced. Convergence runs in the background, and
+    // its only guard is this entry, so a server that stops mid-convergence used to keep the
+    // "recovery-pending" snapshot the entry armed: every later native request answered 503 until
+    // the process exited, because a server whose config does not sync Codex installs a no-op
+    // lifecycle that never touches the gate.
+    //
+    // The gate state belonged only to this entry, so reset it to the process-initial state here,
+    // synchronously and before the first await: a NEW entry created for the same home afterwards
+    // re-arms its own gate and cannot be clobbered by this release. The epoch bump retires any
+    // in-flight `initializeNativeMainStartupGate`/convergence write from the released generation.
+    if (snapshot.homeId === homeId && !startupEntries.has(homeId)) {
+      epoch += 1;
+      snapshot = ready(null);
+      settled = Promise.resolve(snapshot);
+    }
     entry!.resolveAcquisition?.(snapshot);
     entry!.resolveAcquisition = undefined;
     // Startup convergence can transition from the exclusive recovery claim

structure/codex-home.md

@@ -134,6 +134,13 @@ subsystem from fencing native traffic or creating lock contention. Presence, an
 or any observation error still takes the locked sweep and fails closed; the fast path is based only
 on proven absence, never on an unreadable path.
 
+Native-main admission is one process-global gate owned by the live startup entry. Releasing the
+last reference to that entry returns the gate to its process-initial `ready` state synchronously,
+before the release awaits anything, so a server stopped in the middle of startup convergence
+cannot leave the process fenced for the servers that follow it; an entry created afterwards for
+the same home arms its own gate, and the retired generation's late convergence writes are ignored.
+`tests/codex-integration/native-profile-startup-release.test.ts` pins that ordering.
+
 The native main slot also accepts one same-identity device reauth (#3898):
 `/api/codex-auth/main/reauth-device` (start/status/cancel) plus
 `ocx account main reauth`. The grant is the OpenAI deviceauth grant already