@iislee/opencodex 2.11.0 → 2.35.0

package/src/codex/auth-api.ts

@@ -1,5 +1,11 @@
-import { ConfigMutationLockError, loadConfig, mutatePersistedConfig, saveConfigPreservingClaudeCode } from "../config";
-import { withCodexAccountLogLabel } from "./account-label";
+import {
+  ConfigMutationLockError,
+  loadConfig,
+  mutatePersistedConfig,
+  saveConfigPreservingClaudeCode,
+  withConfigMutationLockSync,
+} from "../config";
+import { codexAccountLogLabel, withCodexAccountLogLabel } from "./account-label";
 import {
   getCodexAccountCredential,
   getValidCodexToken,
@@ -14,27 +20,52 @@ import {
   TokenRefreshError,
 } from "./account-store";
 import { deleteCodexAccount, reconcileMainCodexAccountRuntimeState } from "./account-lifecycle";
+import {
+  appendDefaultCodexAccountNamespace,
+  codexAccountPickerEnabled,
+} from "./account-namespaces";
+import {
+  catalogRefreshIsPending,
+  normalizeCatalogDisposition,
+} from "./catalog-refresh-status";
 import { isCodexAccountPaused, setCodexAccountPaused } from "./account-pause";
 import {
+  clearCodexAccountPin,
+  getCodexAccountPriority,
+  isCodexAccountPriorityKey,
+  pinnedCodexAccountId,
+  setCodexAccountPin,
+  setCodexAccountPriority,
+} from "./account-priority";
+import {
+  claimDueCodexQuotaRecoveryProbes,
   clearCodexAccountCooldown,
   clearThreadAccountMapForAccount,
   getEffectiveActiveCodexAccountId,
+  isEffectiveCodexAccountPinned,
   reconcileCodexActiveAfterExclusion,
   resetCodexRoutingForManualSelection,
+  settleCodexQuotaRecoveryProbe,
 } from "./routing";
 import {
+  DEFAULT_ACCOUNT_PRIORITY,
+  MAX_ACCOUNT_PRIORITY,
+  MIN_ACCOUNT_PRIORITY,
   normalizeAccountPoolStickyLimit,
   normalizeAccountPoolStrategy,
   parseAccountPoolStickyLimit,
   parseAccountPoolStrategy,
+  parseAccountPriority,
 } from "./pool-rotation";
 import { checkAccountIdCollision, getMainChatgptAccountId, readCodexTokens, readCodexTokensResult } from "./auth-collision";
+import { codexPlanValue, isThirtyDayOnlyCodexPlan } from "./plan";
 export { checkAccountIdCollision, getMainChatgptAccountId } from "./auth-collision";
 export { clearAccountNeedsReauth, isAccountNeedsReauth, markAccountNeedsReauth } from "./account-runtime-state";
 import { clearAccountNeedsReauth, isAccountNeedsReauth, markAccountNeedsReauth } from "./account-runtime-state";
 import {
   clearAccountQuota,
   getAccountQuota,
+  isCompleteCodexQuotaRecoverySnapshot,
   isCodexQuotaExhausted,
   listAccountQuotas,
   parseUsageQuota,
@@ -51,24 +82,30 @@ export {
   setAccountQuotaFromParsed,
   updateAccountQuota,
 } from "./quota";
-import { extractAccountId, decodeJwtPayload } from "../oauth/chatgpt";
-import { getMainAccountPlan, MAIN_CODEX_ACCOUNT_ID, setMainAccountPlan } from "./main-account";
-import { captureConfigGeneration } from "../lib/state-store-sweeper";
+import { extractAccountId } from "../oauth/chatgpt";
+import { getMainAccountPlan, isMainAccountTokenVerifiablyLive, MAIN_CODEX_ACCOUNT_ID, setMainAccountPlan } from "./main-account";
+import { captureConfigGeneration, registerStateSweepAfterTick } from "../lib/state-store-sweeper";
 import { reconcileLiveStateStores } from "../lib/state-store-registrations";
 import {
+  captureMainAccountIdentityGeneration,
   clearMainAccountInfoCache,
+  getMainAccountCredentialPresence,
   getMainAccountInfoCache,
+  isMainAccountIdentityGenerationLive,
+  setMainAccountCredentialPresence,
   setMainAccountInfoCache,
   type MainAccountInfo,
 } from "./main-account-cache";
 export { clearMainAccountInfoCache } from "./main-account-cache";
 import { maskEmail } from "../lib/privacy";
-import { CodexWarmupError, codexWarmupFailureReason, warmCodexAccount } from "./warmup";
+import { codexWarmupFailureReason, warmCodexAccount } from "./warmup";
 export { maskEmail } from "../lib/privacy";
-import type { CodexAccount, OcxConfig } from "../types";
+import type { CodexAccount, CodexAccountCredentials, OcxConfig } from "../types";
+import type { CatalogDisposition } from "./convergence-types";
 import { isCanonicalOpenAiForwardProvider, OPENAI_CODEX_PROVIDER_ID } from "../providers/openai-tiers";
 import { providerCodexAccountMode } from "../providers/registry";
-import { readBoundedResponseBody } from "../lib/bounded-body";
+import { BOUNDED_BODY_MAX_BYTES, readBoundedResponseBody } from "../lib/bounded-body";
+import { cancelBodyOnAbort, signalWithTimeout } from "../lib/abort";
 import {
   oauthAccountHealthFields,
   projectCodexAccountHealth,
@@ -82,7 +119,20 @@ import {
   isValidCodexAccountId,
 } from "./account-id";
 import { codexAccountIdNamespaceCollisionError } from "./account-namespace-match";
-import { ResourceAdmissionError } from "../lib/admission";
+import { ResourceAdmissionError, type AdmissionLease } from "../lib/admission";
+import { tryAcquireNativeMainProfileClaim } from "./native-main-admission";
+import { withNativeMainSharedClaim } from "./native-main-claim";
+import { resolveNativeProfileContext } from "./native-profile-store";
+import { NativeProfileError } from "./native-profile-types";
+
+function isNativeMainClaimUnavailable(error: unknown): error is NativeProfileError {
+  return error instanceof NativeProfileError
+    && (error.code === "NATIVE_MAIN_CLAIM_BUSY" || error.code === "NATIVE_MAIN_CLAIM_UNAVAILABLE");
+}
+
+function withNativeMainCredentialClaim<T>(operation: () => Promise<T>): Promise<T> {
+  return withNativeMainSharedClaim(resolveNativeProfileContext(), operation);
+}
 
 function jsonResponse(data: unknown, status = 200): Response {
   return new Response(JSON.stringify(data), {
@@ -91,11 +141,28 @@ function jsonResponse(data: unknown, status = 200): Response {
   });
 }
 
-const MANUAL_IMPORT_ENV = "OPENCODEX_ENABLE_UNVERIFIED_CODEX_IMPORT";
+function nativeMainProfileBusyResponse(): Response {
+  const response = jsonResponse({ error: "server_busy", code: "server_busy" }, 503);
+  response.headers.set("Retry-After", "1");
+  return response;
+}
+
+const CODEX_CREDENTIAL_PERSISTENCE_ERROR = "Account was saved, but credential setup did not complete. Reauthenticate or remove the account.";
+const CODEX_CREDENTIAL_PERSISTENCE_CODE = "codex_credential_persistence_failed";
 
 const MAX_CODEX_LOGIN_STATE_ROWS = 32;
 const CODEX_LOGIN_TERMINAL_TTL_MS = 300_000;
-interface CodexLoginStateRow { status: string; startedAt: number; accountId?: string; email?: string; error?: string; doneAt?: number }
+interface CodexLoginStateRow {
+  status: string;
+  startedAt: number;
+  accountId?: string;
+  email?: string;
+  error?: string;
+  code?: string;
+  needsReauth?: boolean;
+  catalogRefreshPending?: boolean;
+  doneAt?: number;
+}
 const codexAuthLoginState = new Map<string, CodexLoginStateRow>();
 export class CodexLoginStateBusyError extends ResourceAdmissionError {
   constructor() { super("codex_login_state_rows", MAX_CODEX_LOGIN_STATE_ROWS); this.name = "CodexLoginStateBusyError"; }
@@ -142,21 +209,59 @@ function codexAccountPersistenceConflict(
     : undefined;
 }
 
-function isThirtyDayOnlyPlan(plan: string | null | undefined): boolean {
-  const normalized = plan?.trim().toLowerCase();
-  return normalized === "go" || normalized === "free";
+/**
+ * The exact label `parseUsageQuota` emits for the Codex Spark window (quota.ts).
+ * Matching on the label rather than on "is a custom window" is load-bearing: the same array
+ * carries Cursor's First-party models / API usage, Anthropic's Fable / Opus / Sonnet,
+ * Antigravity's Gem / Cla, Kimi's subscription credits and a dozen dynamic provider meters.
+ */
+const CODEX_SPARK_WINDOW_LABEL = "GPT-5.3-Codex-Spark Weekly";
+
+/**
+ * Drop the Spark window unless the operator asked for it (default hidden).
+ *
+ * Applied at the DTO boundary, never at parse or cache time: custom windows participate in
+ * quota-presence checks, snapshot reconciliation and capacity aggregation, so removing Spark
+ * upstream of this point would change routing state rather than display.
+ *
+ * Both GUI surfaces funnel through here — the Codex Auth rows directly, and /api/provider-quotas
+ * via listCodexAuthAccountsSnapshot — so one filter covers both. Filtering only one would leave
+ * the other still rendering the row the operator switched off.
+ */
+export function withSparkVisibility<T extends Omit<StoredAccountQuota, "updatedAt"> | StoredAccountQuota | null>(
+  quota: T,
+): T {
+  if (!quota?.customWindows?.length) return quota;
+  if (loadConfig().showCodexSparkQuota === true) return quota;
+  const kept = quota.customWindows.filter(window => window.label !== CODEX_SPARK_WINDOW_LABEL);
+  if (kept.length === quota.customWindows.length) return quota;
+  // An empty list is dropped rather than serialized: an absent field and an empty array should
+  // not be two different ways of saying "no custom windows" on the wire.
+  const next = { ...quota } as Record<string, unknown>;
+  if (kept.length > 0) next.customWindows = kept;
+  else delete next.customWindows;
+  return next as T;
 }
 
+
 function quotaForPlan<T extends Omit<StoredAccountQuota, "updatedAt"> | StoredAccountQuota | null>(
   quota: T,
-  plan: string | null | undefined,
+  plan: unknown,
 ): T {
-  if (!quota || !isThirtyDayOnlyPlan(plan)) return quota;
+  const visible = withSparkVisibility(quota);
+  if (!visible || !isThirtyDayOnlyCodexPlan(plan)) return visible;
+  const quotaWindows = visible;
   return {
-    ...(quota.monthlyPercent !== undefined ? { monthlyPercent: quota.monthlyPercent } : {}),
-    ...(quota.monthlyResetAt !== undefined ? { monthlyResetAt: quota.monthlyResetAt } : {}),
-    ...(quota.resetCredits !== undefined ? { resetCredits: quota.resetCredits } : {}),
-    ...("updatedAt" in quota ? { updatedAt: quota.updatedAt } : {}),
+    ...(quotaWindows.monthlyPercent !== undefined ? { monthlyPercent: quotaWindows.monthlyPercent } : {}),
+    ...(quotaWindows.monthlyResetAt !== undefined ? { monthlyResetAt: quotaWindows.monthlyResetAt } : {}),
+    // A 30-day plan can still carry a burst window, and it blocks the account on its own.
+    // Dropping it here would show a healthy card for an account upstream is refusing (#1791).
+    ...(quotaWindows.shortPercent !== undefined ? { shortPercent: quotaWindows.shortPercent } : {}),
+    ...(quotaWindows.shortResetAt !== undefined ? { shortResetAt: quotaWindows.shortResetAt } : {}),
+    ...(quotaWindows.shortWindowSeconds !== undefined ? { shortWindowSeconds: quotaWindows.shortWindowSeconds } : {}),
+    ...(quotaWindows.customWindows !== undefined ? { customWindows: quotaWindows.customWindows } : {}),
+    ...(quotaWindows.resetCredits !== undefined ? { resetCredits: quotaWindows.resetCredits } : {}),
+    ...("updatedAt" in quotaWindows ? { updatedAt: quotaWindows.updatedAt } : {}),
   } as T;
 }
 
@@ -165,18 +270,21 @@ function poolAccountDto(
   quotaResult: PoolQuotaResult,
   hasCredential: boolean,
   paused: boolean,
+  priority: number,
 ): CodexAuthAccountDto {
-  const quota = quotaForPlan(quotaResult.quota, account.plan);
+  const plan = codexPlanValue(account.plan);
+  const quota = quotaForPlan(quotaResult.quota, plan);
   const needsReauth = !hasCredential || quotaResult.needsReauth || isAccountNeedsReauth(account.id);
   const health = projectCodexAccountHealth({ accountId: account.id, needsReauth });
   return {
     id: account.id,
-    email: account.email,
+    email: maskEmail(account.email) ?? account.email,
     ...(account.alias !== undefined ? { alias: account.alias } : {}),
-    ...(account.plan !== undefined ? { plan: account.plan } : {}),
-    ...(account.logLabel !== undefined ? { logLabel: account.logLabel } : {}),
+    ...(plan !== undefined ? { plan } : {}),
+    logLabel: codexAccountLogLabel(account),
     isMain: false,
     paused,
+    priority,
     quota: quota ? { ...quota } : null,
     needsReauth,
     hasCredential,
@@ -185,20 +293,52 @@ function poolAccountDto(
   };
 }
 
-async function resolveResetCreditAuth(
+interface ResetCreditAuth {
+  isMain: boolean;
+  accessToken: string;
+  chatgptAccountId: string;
+  nativeMainLease?: AdmissionLease;
+  nativeMainSharedClaimHeld?: true;
+}
+
+async function withResetCreditAuth<T>(
   runtimeConfig: OcxConfig,
   accountId: string,
-): Promise<
-  | { ok: true; isMain: boolean; accessToken: string; chatgptAccountId: string }
-  | { ok: false; response: Response }
-> {
+  operation: (auth: ResetCreditAuth) => Promise<T>,
+): Promise<{ ok: true; value: T } | { ok: false; response: Response }> {
   if (accountId === MAIN_CODEX_ACCOUNT_ID) {
     if (hasLegacyMainCodexPoolAccount(runtimeConfig.codexAccounts)) {
       return { ok: false, response: jsonResponse({ error: "Remove the legacy __main__ pool row before using the Desktop account" }, 409) };
     }
-    const tokens = readCodexTokens();
-    if (!tokens) return { ok: false, response: jsonResponse({ error: "Main Codex account not logged in" }, 401) };
-    return { ok: true, isMain: true, accessToken: tokens.access_token, chatgptAccountId: tokens.account_id };
+    const nativeMainLease = tryAcquireNativeMainProfileClaim();
+    if (!nativeMainLease) return { ok: false, response: nativeMainProfileBusyResponse() };
+    try {
+      try {
+        return await withNativeMainCredentialClaim(async () => {
+          const tokens = readCodexTokens();
+          if (!tokens) {
+            return { ok: false, response: jsonResponse({ error: "Main Codex account not logged in" }, 401) };
+          }
+          return {
+            ok: true,
+            value: await operation({
+              isMain: true,
+              accessToken: tokens.access_token,
+              chatgptAccountId: tokens.account_id,
+              nativeMainLease,
+              nativeMainSharedClaimHeld: true,
+            }),
+          };
+        });
+      } catch (error) {
+        if (isNativeMainClaimUnavailable(error)) {
+          return { ok: false, response: nativeMainProfileBusyResponse() };
+        }
+        throw error;
+      }
+    } finally {
+      nativeMainLease.release();
+    }
   }
   if (!isValidCodexAccountId(accountId)) {
     return { ok: false, response: jsonResponse({ error: "Invalid account id format" }, 400) };
@@ -207,7 +347,14 @@ async function resolveResetCreditAuth(
     return { ok: false, response: jsonResponse({ error: "Unknown Codex account" }, 404) };
   }
   const cred = await getValidCodexToken(accountId);
-  return { ok: true, isMain: false, accessToken: cred.accessToken, chatgptAccountId: cred.chatgptAccountId };
+  return {
+    ok: true,
+    value: await operation({
+      isMain: false,
+      accessToken: cred.accessToken,
+      chatgptAccountId: cred.chatgptAccountId,
+    }),
+  };
 }
 
 function safeResetCreditsDto(input: unknown): { credits: { granted_at: string; expires_at: string }[]; available_count?: number } {
@@ -233,8 +380,41 @@ function safeResetCreditConsumeDto(input: unknown): { code: string } {
   return { code: typeof obj.code === "string" ? obj.code : "unknown" };
 }
 
-export function isUnverifiedCodexImportEnabled(): boolean {
-  return process.env[MANUAL_IMPORT_ENV] === "1";
+type ResetCreditJsonRead =
+  | { ok: true; value: unknown }
+  | { ok: false };
+
+function cancelResponseBodyWithoutWaiting(body: ReadableStream<Uint8Array> | null): void {
+  if (!body) return;
+  try {
+    void body.cancel().catch(() => undefined);
+  } catch {
+    // Some stream implementations throw synchronously from cancel().
+  }
+}
+
+async function readResetCreditJson(
+  response: Response,
+  signal: AbortSignal,
+): Promise<ResetCreditJsonRead> {
+  const declaredLength = Number(response.headers.get("content-length"));
+  if (Number.isSafeInteger(declaredLength)
+    && declaredLength >= 0
+    && declaredLength > BOUNDED_BODY_MAX_BYTES) {
+    cancelResponseBodyWithoutWaiting(response.body);
+    return { ok: false };
+  }
+  try {
+    const body = await readBoundedResponseBody(response, {
+      signal,
+      maxBytes: BOUNDED_BODY_MAX_BYTES,
+      fatalUtf8: true,
+    });
+    if (!body.displaySafe || body.truncated || !body.text.trim()) return { ok: false };
+    return { ok: true, value: JSON.parse(body.text) as unknown };
+  } catch {
+    return { ok: false };
+  }
 }
 
 function manualImportDisabledResponse(): Response {
@@ -254,13 +434,10 @@ async function verifyCodexAccountWarmup(
     return { ok: true, validatedAt: Date.now() };
   } catch (err) {
     const reason = codexWarmupFailureReason(err);
-    const upstream = err instanceof CodexWarmupError ? err.upstreamDetail : undefined;
     return {
       ok: false,
       response: jsonResponse({
-        error: upstream
-          ? `Codex account warmup failed: ${upstream}`
-          : "Codex account warmup failed. Reauthenticate the account and try again.",
+        error: "Codex account warmup failed. Reauthenticate the account and try again.",
         code: "codex_warmup_failed",
         reason,
         accountId,
@@ -291,7 +468,7 @@ const POOL_CACHE_TTL = 5 * 60_000;
 const POOL_QUOTA_REFRESH_CONCURRENCY = 4;
 
 function nonEmptyPlan(value: unknown): string | null {
-  return typeof value === "string" && value.trim() !== "" ? value : null;
+  return codexPlanValue(value) ?? null;
 }
 
 function isRuntimeConfig(config: OcxConfig): boolean {
@@ -311,6 +488,100 @@ function saveRuntimeConfig(sourceConfig: OcxConfig, nextConfig: OcxConfig): void
   Object.assign(sourceConfig, nextConfig);
 }
 
+interface StagedNewCodexAccountState {
+  credential: CodexAccountCredentials;
+  validatedAt: number;
+}
+
+type PersistNewCodexAccountOutcome =
+  | { status: "committed"; pickerVisibilityChanged: boolean }
+  | { status: "publication-failed"; pickerVisibilityChanged: boolean };
+
+function codexCredentialPersistenceFailure(accountId: string, catalogRefreshPending: boolean) {
+  return {
+    error: CODEX_CREDENTIAL_PERSISTENCE_ERROR,
+    code: CODEX_CREDENTIAL_PERSISTENCE_CODE,
+    accountId,
+    needsReauth: true as const,
+    ...(catalogRefreshPending ? { catalogRefreshPending: true as const } : {}),
+  };
+}
+
+/** Persist config before publishing secret or runtime state under the shared mutation coordinator. */
+function persistNewCodexAccount(
+  sourceConfig: OcxConfig,
+  runtimeConfig: OcxConfig,
+  addedAccount: CodexAccount,
+  staged: StagedNewCodexAccountState,
+): PersistNewCodexAccountOutcome {
+  return withConfigMutationLockSync(() => {
+    const previousConfig = { ...runtimeConfig };
+    let pickerVisibilityChanged: boolean;
+    try {
+      const accounts = [...(runtimeConfig.codexAccounts ?? [])];
+      const retainedPickerBindingRestored = codexAccountPickerEnabled(runtimeConfig)
+        && Object.values(runtimeConfig.codexAccountNamespaces ?? {}).includes(addedAccount.id);
+      accounts.push(addedAccount);
+      runtimeConfig.codexAccounts = accounts;
+
+      // Presence of the explicit flag distinguishes a dashboard-managed map from
+      // a hand-authored legacy map. Preserve manual maps exactly.
+      const tracksPickerNamespaces = runtimeConfig.codexAccountPickerEnabled !== undefined;
+      if (tracksPickerNamespaces && runtimeConfig.codexAccountNamespaces) {
+        runtimeConfig.codexAccountNamespaces = { ...runtimeConfig.codexAccountNamespaces };
+      }
+      const namespaceAdded = tracksPickerNamespaces
+        && appendDefaultCodexAccountNamespace(runtimeConfig, addedAccount);
+      pickerVisibilityChanged = namespaceAdded || retainedPickerBindingRestored;
+      saveRuntimeConfig(sourceConfig, runtimeConfig);
+    } catch (error) {
+      for (const key of Object.keys(runtimeConfig) as Array<keyof OcxConfig>) {
+        delete runtimeConfig[key];
+      }
+      Object.assign(runtimeConfig, previousConfig);
+      throw error;
+    }
+
+    try {
+      saveCodexAccountCredential(addedAccount.id, staged.credential);
+      markCodexAccountValidated(addedAccount.id, staged.validatedAt);
+      clearAccountNeedsReauth(addedAccount.id);
+    } catch {
+      // Config is already durable. Return the failure outcome through the coordinator so its
+      // generation commit is not rolled back while config.json remains changed.
+      return { status: "publication-failed" as const, pickerVisibilityChanged };
+    }
+    return { status: "committed" as const, pickerVisibilityChanged };
+  });
+}
+
+/** Bounded catalog-convergence callback supplied by the management dispatcher. */
+export type CodexAuthCatalogConvergence = () => Promise<CatalogDisposition>;
+
+interface AccountNamespaceCatalogRefresh {
+  catalogRefreshPending: boolean;
+}
+
+/** Collapse post-persistence convergence into the one public recovery bit. */
+async function convergeAccountNamespaceCatalog(
+  config: OcxConfig,
+  changed: boolean,
+  convergeCodexCatalog?: CodexAuthCatalogConvergence,
+): Promise<AccountNamespaceCatalogRefresh> {
+  if (!changed || !codexAccountPickerEnabled(config)) {
+    return { catalogRefreshPending: false };
+  }
+  if (!convergeCodexCatalog) return { catalogRefreshPending: true };
+
+  try {
+    const catalogRefresh = normalizeCatalogDisposition(await convergeCodexCatalog());
+    if (!catalogRefresh) return { catalogRefreshPending: true };
+    return { catalogRefreshPending: catalogRefreshIsPending(catalogRefresh) };
+  } catch {
+    return { catalogRefreshPending: true };
+  }
+}
+
 async function mapWithConcurrency<T, R>(
   items: T[],
   concurrency: number,
@@ -333,12 +604,31 @@ const MAIN_TERMINAL_AUTH_CODES = new Set([
   "invalid_refresh_token",
 ]);
 
-async function isTerminalMainAuthResponse(resp: Response): Promise<boolean> {
-  if (resp.status === 401) return true;
+/**
+ * A WHAM 401 is not itself proof the local credential died. Upstream edges can
+ * transiently reject a still-valid access token (region/anti-abuse/rotation
+ * races), and fail-closing on every bare 401 makes a healthy main account flip
+ * needs-reauth on the next GUI quota poll. Only treat the response as terminal
+ * when the body carries a known terminal code or the local access token is not
+ * verifiably live (`accessTokenLive`). Liveness must be strict: a JWT whose
+ * `exp` cannot be decoded is NOT live — an undecodable token that vouched for
+ * itself would make a real 401 permanently transient.
+ */
+async function isTerminalMainAuthResponse(resp: Response, accessTokenLive: boolean): Promise<boolean> {
+  if (resp.status === 401) {
+    if (!accessTokenLive) return true;
+    const code = await readMainAuthErrorCode(resp);
+    return typeof code === "string" && MAIN_TERMINAL_AUTH_CODES.has(code);
+  }
   if (resp.status !== 403) return false;
+  const code = await readMainAuthErrorCode(resp);
+  return typeof code === "string" && MAIN_TERMINAL_AUTH_CODES.has(code);
+}
+
+async function readMainAuthErrorCode(resp: Response): Promise<unknown> {
   try {
     const body = await readBoundedResponseBody(resp, { totalTimeoutMs: 1_000, inactivityTimeoutMs: 1_000 });
-    if (!body.displaySafe) return false;
+    if (!body.displaySafe) return undefined;
     const parsed = JSON.parse(body.text) as {
       detail?: { code?: unknown } | string;
       error?: { code?: unknown } | string;
@@ -349,23 +639,41 @@ async function isTerminalMainAuthResponse(resp: Response): Promise<boolean> {
       : typeof parsed.error === "object" && parsed.error !== null
         ? parsed.error.code
         : parsed.code;
-    return typeof code === "string" && MAIN_TERMINAL_AUTH_CODES.has(code);
+    return code;
   } catch {
-    return false;
+    return undefined;
   }
 }
 
 interface MainAccountInfoFetchResult {
   info: MainAccountInfo;
+  /** Whether this attempt safely inspected the physical native-main credential. */
+  credentialChecked: boolean;
+  /** Meaningful only when credentialChecked is true. */
+  hasCredential: boolean;
+  /** Main identity generation captured while the native-main claim was held. */
+  identityGeneration?: number;
   /** Present only when this call freshly parsed a WHAM usage response. */
   freshQuota?: Omit<StoredAccountQuota, "updatedAt">;
   /** Present only when this call's WHAM response included `rate_limit_reset_credits.available_count`. */
   freshResetCredits?: number;
 }
 
+export interface MainAccountInfoSnapshot {
+  info: MainAccountInfo;
+  mainIdentityGeneration: number;
+}
+
+export async function fetchMainAccountInfoSnapshot(forceRefresh = false): Promise<MainAccountInfoSnapshot> {
+  const result = await fetchMainAccountInfoAttempt(forceRefresh, 1);
+  return {
+    info: result.info,
+    mainIdentityGeneration: result.identityGeneration ?? captureMainAccountIdentityGeneration(),
+  };
+}
+
 export async function fetchMainAccountInfo(forceRefresh = false): Promise<MainAccountInfo> {
-  const { info } = await fetchMainAccountInfoAttempt(forceRefresh, 1);
-  return info;
+  return (await fetchMainAccountInfoSnapshot(forceRefresh)).info;
 }
 
 const EMPTY_MAIN_ACCOUNT_INFO: MainAccountInfo = { email: null, plan: null, quota: null };
@@ -373,19 +681,72 @@ const EMPTY_MAIN_ACCOUNT_INFO: MainAccountInfo = { email: null, plan: null, quot
 async function retryMainAccountInfoIfIdentityChanged(
   requestAccountId: string | null,
   retriesRemaining: number,
+  nativeMainLease: AdmissionLease,
+  explicitRefresh: boolean,
 ): Promise<MainAccountInfoFetchResult | null> {
   const currentAccountId = getMainChatgptAccountId();
   if (currentAccountId === null || currentAccountId === requestAccountId) return null;
   reconcileMainCodexAccountRuntimeState();
   return retriesRemaining > 0
-    ? fetchMainAccountInfoAttempt(true, retriesRemaining - 1)
-    : { info: EMPTY_MAIN_ACCOUNT_INFO };
+    ? fetchMainAccountInfoWhileOwned(true, retriesRemaining - 1, nativeMainLease, explicitRefresh)
+    : { info: EMPTY_MAIN_ACCOUNT_INFO, credentialChecked: true, hasCredential: true };
 }
 
-async function fetchMainAccountInfoAttempt(forceRefresh: boolean, retriesRemaining: number): Promise<MainAccountInfoFetchResult> {
+async function fetchMainAccountInfoAttempt(
+  forceRefresh: boolean,
+  retriesRemaining: number,
+  existingNativeMainLease?: AdmissionLease,
+  nativeMainSharedClaimHeld = false,
+): Promise<MainAccountInfoFetchResult> {
+  const nativeMainLease = existingNativeMainLease ?? tryAcquireNativeMainProfileClaim();
+  if (!nativeMainLease) {
+    return {
+      info: EMPTY_MAIN_ACCOUNT_INFO,
+      credentialChecked: false,
+      hasCredential: false,
+      identityGeneration: captureMainAccountIdentityGeneration(),
+    };
+  }
+  try {
+    const operation = async () => ({
+      ...await fetchMainAccountInfoWhileOwned(forceRefresh, retriesRemaining, nativeMainLease),
+      identityGeneration: captureMainAccountIdentityGeneration(),
+    });
+    if (nativeMainSharedClaimHeld) return await operation();
+    try {
+      return await withNativeMainCredentialClaim(operation);
+    } catch (error) {
+      if (isNativeMainClaimUnavailable(error)) {
+        return {
+          info: EMPTY_MAIN_ACCOUNT_INFO,
+          credentialChecked: false,
+          hasCredential: false,
+          identityGeneration: captureMainAccountIdentityGeneration(),
+        };
+      }
+      throw error;
+    }
+  } finally {
+    if (!existingNativeMainLease) nativeMainLease.release();
+  }
+}
+
+async function fetchMainAccountInfoWhileOwned(
+  forceRefresh: boolean,
+  retriesRemaining: number,
+  nativeMainLease: AdmissionLease,
+  /**
+   * Whether the *caller* asked for this refresh. `forceRefresh` also means "bypass the
+   * cache", and `retryMainAccountInfoIfIdentityChanged` re-enters with it set purely to
+   * re-read after the identity changed. Keeping the two apart stops that retry from
+   * promoting a background poll into operator intent below.
+   */
+  explicitRefresh: boolean = forceRefresh,
+): Promise<MainAccountInfoFetchResult> {
   const writerGeneration = captureConfigGeneration();
   reconcileMainCodexAccountRuntimeState();
   const tokenRead = readCodexTokensResult();
+  setMainAccountCredentialPresence(tokenRead.status === "ok");
   if (tokenRead.status !== "ok") {
     // A local read failure is NOT proof of sign-out: a missing file can be a non-atomic rewrite
     // gap, and malformed JSON can be a half-written file. Clearing the cache and marking the
@@ -394,13 +755,13 @@ async function fetchMainAccountInfoAttempt(forceRefresh: boolean, retriesRemaini
     // routing stays fail-closed because getMainAccountToken() re-reads the file itself, and the
     // account DTO still reports hasCredential=false while the file is unreadable.
     const preserved = getMainAccountInfoCache();
-    return { info: preserved ?? EMPTY_MAIN_ACCOUNT_INFO };
+    return { info: preserved ?? EMPTY_MAIN_ACCOUNT_INFO, credentialChecked: true, hasCredential: false };
   }
   const tokens = tokenRead.tokens;
   const requestAccountId = extractAccountId(tokens.id_token, tokens.access_token) ?? (tokens.account_id || null);
   const cached = getMainAccountInfoCache();
   if (!forceRefresh && cached && Date.now() - cached.ts < MAIN_CACHE_TTL) {
-    return { info: cached };
+    return { info: cached, credentialChecked: true, hasCredential: true };
   }
   try {
     const resp = await fetch("https://chatgpt.com/backend-api/wham/usage", {
@@ -408,17 +769,17 @@ async function fetchMainAccountInfoAttempt(forceRefresh: boolean, retriesRemaini
       signal: AbortSignal.timeout(8000),
     });
     if (!resp.ok) {
-      const terminalAuthFailure = await isTerminalMainAuthResponse(resp);
-      const retried = await retryMainAccountInfoIfIdentityChanged(requestAccountId, retriesRemaining);
+      const terminalAuthFailure = await isTerminalMainAuthResponse(resp, isMainAccountTokenVerifiablyLive());
+      const retried = await retryMainAccountInfoIfIdentityChanged(requestAccountId, retriesRemaining, nativeMainLease, explicitRefresh);
       if (retried) return retried;
       if (terminalAuthFailure) {
         clearMainAccountInfoCache();
         markAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID, writerGeneration);
       }
-      return { info: EMPTY_MAIN_ACCOUNT_INFO };
+      return { info: EMPTY_MAIN_ACCOUNT_INFO, credentialChecked: true, hasCredential: true };
     }
     const data = (await resp.json()) as WhamUsageResponse;
-    const retried = await retryMainAccountInfoIfIdentityChanged(requestAccountId, retriesRemaining);
+    const retried = await retryMainAccountInfoIfIdentityChanged(requestAccountId, retriesRemaining, nativeMainLease, explicitRefresh);
     if (retried) return retried;
     const plan = nonEmptyPlan(data.plan_type) ?? nonEmptyPlan(cached?.plan) ?? nonEmptyPlan(getMainAccountPlan());
     const quota = parseUsageQuota({ ...data, ...(plan ? { plan_type: plan } : {}) });
@@ -430,7 +791,16 @@ async function fetchMainAccountInfoAttempt(forceRefresh: boolean, retriesRemaini
       ts: Date.now(),
     };
     setMainAccountInfoCache(result);
-    clearAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
+    // Only an explicit refresh may retract a reauth quarantine. A 200 from
+    // /wham/usage proves the token authenticates to the usage endpoint; it does not
+    // prove the account can serve Responses traffic, which is a different backend path
+    // and still answers 403 for a workspace the token may no longer select (#327).
+    // Letting the background poll clear the flag put such an account straight back into
+    // rotation: the next request failed the same way and re-marked it, so needsReauth
+    // never settled and the dashboard kept showing nothing — the symptom #327 reported.
+    // An explicit refresh is an operator asking to re-evaluate, normally right after
+    // signing in again, so it stays authoritative.
+    if (explicitRefresh) clearAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
     // Mirror main quota + plan into the shared stores so the rotation engine can
     // score and auto-switch the main account exactly like a pool account (Option A).
     setMainAccountPlan(result.plan);
@@ -439,12 +809,14 @@ async function fetchMainAccountInfoAttempt(forceRefresh: boolean, retriesRemaini
     }
     return {
       info: result,
+      credentialChecked: true,
+      hasCredential: true,
       ...(quota ? { freshQuota: quota } : {}),
       ...(freshResetCredits !== undefined ? { freshResetCredits } : {}),
     };
   } catch {
-    const retried = await retryMainAccountInfoIfIdentityChanged(requestAccountId, retriesRemaining);
-    return retried ?? { info: EMPTY_MAIN_ACCOUNT_INFO };
+    const retried = await retryMainAccountInfoIfIdentityChanged(requestAccountId, retriesRemaining, nativeMainLease, explicitRefresh);
+    return retried ?? { info: EMPTY_MAIN_ACCOUNT_INFO, credentialChecked: true, hasCredential: true };
   }
 }
 
@@ -514,6 +886,8 @@ export interface CodexAuthAccountDto {
   logLabel?: string;
   isMain: boolean;
   paused: boolean;
+  /** Selection order; higher is used earlier. Always present, 0 when unset. */
+  priority: number;
   quota: (StoredAccountQuota | (Omit<StoredAccountQuota, "updatedAt"> & { updatedAt: number })) | null;
   needsReauth?: boolean;
   hasCredential: boolean;
@@ -551,6 +925,15 @@ function reconcileFreshPoolAccountPlans(runtimeConfig: OcxConfig, updates: Fresh
         accepted.push(update);
         if (persistedAccount.plan !== update.plan) {
           persistedAccount.plan = update.plan;
+          // WHAM is the authoritative plan source: stamp provenance so a later JWT
+          // reconcile cannot overwrite this observation within the same credential
+          // generation (src/codex/plan-from-token.ts jwtMayWritePlan). Stamped only
+          // alongside a real plan change: a steady-state refresh whose plan is
+          // unchanged must stay write-free (no-config-write contract), and an
+          // unchanged value needs no fence — a JWT rewrite to the same text is a
+          // no-op under the caller's own equality check.
+          persistedAccount.planSource = "wham";
+          persistedAccount.planCredentialGeneration = update.credentialGeneration;
           changed = true;
         }
       }
@@ -570,6 +953,8 @@ function reconcileFreshPoolAccountPlans(runtimeConfig: OcxConfig, updates: Fresh
     const liveAccount = configuredPoolAccount(runtimeConfig, update.accountId);
     if (liveAccount) {
       liveAccount.plan = update.plan;
+      liveAccount.planSource = "wham";
+      liveAccount.planCredentialGeneration = update.credentialGeneration;
     }
   }
 }
@@ -689,6 +1074,60 @@ async function fetchPoolAccountQuota(accountId: string, forceRefresh = false, co
 }
 
 let primeInFlight: Promise<void> | null = null;
+let cooldownRecoveryInFlight: Promise<void> | null = null;
+
+export async function runCodexCooldownRecoveryProbes(config: OcxConfig, now = Date.now()): Promise<void> {
+  const openai = config.providers[OPENAI_CODEX_PROVIDER_ID];
+  if (!openai
+    || openai.disabled === true
+    || !isCanonicalOpenAiForwardProvider(openai)
+    || providerCodexAccountMode(OPENAI_CODEX_PROVIDER_ID, openai) !== "pool") return;
+  if (cooldownRecoveryInFlight) return cooldownRecoveryInFlight;
+  cooldownRecoveryInFlight = (async () => {
+    const claims = claimDueCodexQuotaRecoveryProbes(config, POOL_QUOTA_REFRESH_CONCURRENCY, now);
+    await mapWithConcurrency(claims, POOL_QUOTA_REFRESH_CONCURRENCY, async claim => {
+      const account = configuredPoolAccount(config, claim.accountId);
+      if (!account) {
+        settleCodexQuotaRecoveryProbe(claim, false, {}, now);
+        return;
+      }
+      try {
+        const result = await fetchPoolAccountQuota(claim.accountId, true, account.plan);
+        // Defence in depth: `spark` is already excluded at the claim site, since generic WHAM
+        // cannot prove a spark recovery. Keep the settle-side guard so a future claim change
+        // cannot silently start clearing spark on generic evidence.
+        const recovered = claim.scope !== "spark"
+          && isCompleteCodexQuotaRecoverySnapshot(result.freshQuota ?? null, result.freshPlan ?? account.plan);
+        settleCodexQuotaRecoveryProbe(claim, recovered, {
+          credentialGeneration: result.freshCredentialGeneration,
+        }, now);
+      } catch {
+        settleCodexQuotaRecoveryProbe(claim, false, {}, now);
+      }
+    });
+  })().catch(() => {
+    // Background recovery is best-effort; routing keeps the cooldown on failure.
+  }).finally(() => { cooldownRecoveryInFlight = null; });
+  return cooldownRecoveryInFlight;
+}
+
+export function registerCodexCooldownRecoveryProbeWorker(config: OcxConfig): void {
+  registerStateSweepAfterTick({
+    name: "codex-cooldown-recovery",
+    afterTick: () => { void runCodexCooldownRecoveryProbes(config); },
+  });
+}
+
+export interface PrimeCodexPoolQuotasOptions {
+  /** Test seams for proving fenced/recovery priming performs no native-main work. */
+  reconcileMainAccount?: typeof reconcileMainCodexAccountRuntimeState;
+  readMainTokens?: typeof readCodexTokens;
+  fetchMainInfo?: typeof fetchMainAccountInfo;
+}
+
+function tryAcquireNativeMainPrimeLease(): AdmissionLease | null {
+  return tryAcquireNativeMainProfileClaim();
+}
 
 /**
  * Best-effort prime of pool-account (and main) quota so the rotation engine has
@@ -705,7 +1144,11 @@ let primeInFlight: Promise<void> | null = null;
  * cost, so the worst case is one WHAM call per account per TTL window. Failures
  * are swallowed: a blocked WSL network must never crash startup or a request.
  */
-export async function primeCodexPoolQuotas(config: OcxConfig, reason: string): Promise<void> {
+export async function primeCodexPoolQuotas(
+  config: OcxConfig,
+  reason: string,
+  options: PrimeCodexPoolQuotasOptions = {},
+): Promise<void> {
   const openai = config.providers[OPENAI_CODEX_PROVIDER_ID];
   if (
     !openai
@@ -714,10 +1157,6 @@ export async function primeCodexPoolQuotas(config: OcxConfig, reason: string): P
     || providerCodexAccountMode(OPENAI_CODEX_PROVIDER_ID, openai) !== "pool"
   ) return;
   if (primeInFlight) return primeInFlight;
-  // Seed the observed physical main identity before startup/lazy priming can populate quota or
-  // plan state. Otherwise the first post-startup account switch sees no previous identity and
-  // skips the purge that protects the stable __main__ alias.
-  reconcileMainCodexAccountRuntimeState();
   primeInFlight = (async () => {
     const runtimeConfig = getRuntimeConfig(config);
     const pool = (runtimeConfig.codexAccounts ?? []).filter(isSelectableCodexPoolAccount);
@@ -725,10 +1164,30 @@ export async function primeCodexPoolQuotas(config: OcxConfig, reason: string): P
       const q = getAccountQuota(a.id);
       return !q || Date.now() - q.updatedAt >= POOL_CACHE_TTL;
     });
-    const primeMain = !!readCodexTokens() && !getAccountQuota(MAIN_CODEX_ACCOUNT_ID);
+    const primeMain = async () => {
+      const mainLease = tryAcquireNativeMainPrimeLease();
+      if (!mainLease) return;
+      try {
+        try {
+          await withNativeMainCredentialClaim(async () => {
+            // Keep one local owner and one cross-process reader from physical
+            // identity reconciliation through WHAM and all quota publication.
+            (options.reconcileMainAccount ?? reconcileMainCodexAccountRuntimeState)();
+            if (getAccountQuota(MAIN_CODEX_ACCOUNT_ID)) return;
+            if (!(options.readMainTokens ?? readCodexTokens)()) return;
+            if (options.fetchMainInfo) await options.fetchMainInfo(false);
+            else await fetchMainAccountInfoAttempt(false, 1, mainLease, true);
+          });
+        } catch (error) {
+          if (!isNativeMainClaimUnavailable(error)) throw error;
+        }
+      } finally {
+        mainLease.release();
+      }
+    };
     try {
       await Promise.allSettled([
-        primeMain ? fetchMainAccountInfo(false) : Promise.resolve(),
+        primeMain(),
         mapWithConcurrency(stale, POOL_QUOTA_REFRESH_CONCURRENCY, async a => {
           if (!getCodexAccountCredential(a.id)) return;
           await fetchPoolAccountQuota(a.id, false, a.plan);
@@ -750,10 +1209,27 @@ export function clearCodexQuotaPrimeState(): void {
   primeInFlight = null;
 }
 
-export async function listCodexAuthAccounts(config: OcxConfig, forceRefresh = false): Promise<CodexAuthAccountDto[]> {
+/** Test-only reset for the worker-level single-flight. */
+export function clearCodexCooldownRecoveryProbeState(): void {
+  cooldownRecoveryInFlight = null;
+}
+
+export function effectiveCodexAuthAccountId(config: OcxConfig): string {
+  return getEffectiveActiveCodexAccountId(config) ?? MAIN_CODEX_ACCOUNT_ID;
+}
+
+export interface CodexAuthAccountsSnapshot {
+  accounts: CodexAuthAccountDto[];
+  mainIdentityGeneration: number;
+}
+
+export async function listCodexAuthAccountsSnapshot(
+  config: OcxConfig,
+  forceRefresh = false,
+): Promise<CodexAuthAccountsSnapshot> {
   const runtimeConfig = getRuntimeConfig(config);
   const poolAccounts = (runtimeConfig.codexAccounts ?? []).filter(isSelectableCodexPoolAccount);
-  const mainInfo = await fetchMainAccountInfo(forceRefresh);
+  const mainResult = await fetchMainAccountInfoAttempt(forceRefresh, 1);
   const refreshedPool = await mapWithConcurrency(poolAccounts, POOL_QUOTA_REFRESH_CONCURRENCY, async account => {
     const cred = getCodexAccountCredential(account.id);
     let quotaResult: PoolQuotaResult;
@@ -796,6 +1272,7 @@ export async function listCodexAuthAccounts(config: OcxConfig, forceRefresh = fa
         { quota: null, needsReauth: true },
         false,
         isCodexAccountPaused(runtimeConfig, accountId),
+        getCodexAccountPriority(runtimeConfig, accountId),
       )];
     }
     const resultGeneration = quotaResult.credentialGeneration ?? quotaResult.freshCredentialGeneration;
@@ -814,10 +1291,17 @@ export async function listCodexAuthAccounts(config: OcxConfig, forceRefresh = fa
       effectiveQuotaResult,
       true,
       isCodexAccountPaused(runtimeConfig, accountId),
+      getCodexAccountPriority(runtimeConfig, accountId),
     )];
   });
-  const hasMainCredential = readCodexTokens() !== null;
-  const mainNeedsReauth = !hasMainCredential || isAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
+  const fetchedMainGeneration = mainResult.identityGeneration ?? captureMainAccountIdentityGeneration();
+  const mainSnapshotLive = isMainAccountIdentityGenerationLive(fetchedMainGeneration);
+  const mainInfo = mainSnapshotLive ? mainResult.info : EMPTY_MAIN_ACCOUNT_INFO;
+  const hasMainCredential = mainSnapshotLive && mainResult.credentialChecked
+    ? mainResult.hasCredential
+    : getMainAccountCredentialPresence() ?? false;
+  const mainNeedsReauth = (mainSnapshotLive && mainResult.credentialChecked && !hasMainCredential)
+    || isAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID);
   const mainHealth = projectCodexAccountHealth({
     accountId: MAIN_CODEX_ACCOUNT_ID,
     needsReauth: mainNeedsReauth,
@@ -826,14 +1310,30 @@ export async function listCodexAuthAccounts(config: OcxConfig, forceRefresh = fa
     id: MAIN_CODEX_ACCOUNT_ID,
     email: mainInfo.email ?? "Codex App login",
     plan: mainInfo.plan,
+    logLabel: "main",
     isMain: true,
     paused: isCodexAccountPaused(runtimeConfig, MAIN_CODEX_ACCOUNT_ID),
+    priority: getCodexAccountPriority(runtimeConfig, MAIN_CODEX_ACCOUNT_ID),
     hasCredential: hasMainCredential,
     needsReauth: mainNeedsReauth,
-    quota: mainInfo.quota ? { ...quotaForPlan({ ...mainInfo.quota, updatedAt: Date.now() }, mainInfo.plan) } : null,
+    quota: mainInfo.quota ? {
+      ...quotaForPlan({
+        ...mainInfo.quota,
+        updatedAt: getAccountQuota(MAIN_CODEX_ACCOUNT_ID)?.updatedAt ?? Date.now(),
+      }, mainInfo.plan),
+    } : null,
     ...oauthAccountHealthFields("codex", MAIN_CODEX_ACCOUNT_ID, mainHealth),
   };
-  return [main, ...withQuota];
+  return {
+    accounts: [main, ...withQuota],
+    mainIdentityGeneration: mainSnapshotLive
+      ? fetchedMainGeneration
+      : captureMainAccountIdentityGeneration(),
+  };
+}
+
+export async function listCodexAuthAccounts(config: OcxConfig, forceRefresh = false): Promise<CodexAuthAccountDto[]> {
+  return (await listCodexAuthAccountsSnapshot(config, forceRefresh)).accounts;
 }
 
 interface PauseExhaustedResult {
@@ -846,63 +1346,102 @@ function selectFallbackAfterPause(config: OcxConfig, pausedActiveId: string): vo
   reconcileCodexActiveAfterExclusion(config, pausedActiveId);
 }
 
-async function pauseExhaustedCodexAccounts(config: OcxConfig): Promise<PauseExhaustedResult> {
+async function pauseExhaustedCodexAccounts(
+  config: OcxConfig,
+  persistPausedAccounts: () => void,
+): Promise<PauseExhaustedResult> {
   const poolAccounts = (config.codexAccounts ?? []).filter(account => !account.isMain);
-  const mainAttempted = readCodexTokens() !== null;
-  const [mainResult, poolResults] = await Promise.all([
-    fetchMainAccountInfoAttempt(true, 1),
-    mapWithConcurrency(poolAccounts, POOL_QUOTA_REFRESH_CONCURRENCY, async account => {
-      if (!getCodexAccountCredential(account.id)) return { account, quotaResult: null };
-      return {
-        account,
-        quotaResult: await fetchPoolAccountQuota(account.id, true, account.plan),
+  const nativeMainLease = tryAcquireNativeMainProfileClaim();
+  try {
+    const performPause = async (mainLease?: AdmissionLease): Promise<PauseExhaustedResult> => {
+      const mainWork = async (): Promise<{
+        shouldPause: boolean;
+        checkedAccountCount: number;
+        failedAccountCount: number;
+      }> => {
+        if (!mainLease) return { shouldPause: false, checkedAccountCount: 0, failedAccountCount: 1 };
+        const mainResult = await fetchMainAccountInfoAttempt(true, 1, mainLease, true);
+        if (!mainResult.credentialChecked || !mainResult.hasCredential) {
+          return { shouldPause: false, checkedAccountCount: 0, failedAccountCount: 0 };
+        }
+        if (!mainResult.freshQuota || !mainResult.info.plan) {
+          return { shouldPause: false, checkedAccountCount: 0, failedAccountCount: 1 };
+        }
+        return {
+          shouldPause: !isCodexAccountPaused(config, MAIN_CODEX_ACCOUNT_ID)
+            && isCodexQuotaExhausted(mainResult.freshQuota, mainResult.info.plan),
+          checkedAccountCount: 1,
+          failedAccountCount: 0,
+        };
       };
-    }),
-  ]);
-
-  let checkedAccountCount = 0;
-  let failedAccountCount = 0;
-  const exhaustedIds: string[] = [];
-  if (mainAttempted) {
-    if (mainResult.freshQuota && mainResult.info.plan) {
-      checkedAccountCount += 1;
-      if (
-        !isCodexAccountPaused(config, MAIN_CODEX_ACCOUNT_ID)
-        && isCodexQuotaExhausted(mainResult.freshQuota, mainResult.info.plan)
-      ) {
-        exhaustedIds.push(MAIN_CODEX_ACCOUNT_ID);
+      const [mainResult, poolResults] = await Promise.all([
+        mainWork(),
+        mapWithConcurrency(poolAccounts, POOL_QUOTA_REFRESH_CONCURRENCY, async account => {
+          if (!getCodexAccountCredential(account.id)) return { account, quotaResult: null };
+          try {
+            return {
+              account,
+              quotaResult: await fetchPoolAccountQuota(account.id, true, account.plan),
+            };
+          } catch {
+            // Settle each pool probe independently so a busy/failing account cannot
+            // abandon an already-confirmed main decision before atomic publication.
+            return { account, quotaResult: null };
+          }
+        }),
+      ]);
+
+      let checkedAccountCount = mainResult.checkedAccountCount;
+      let failedAccountCount = mainResult.failedAccountCount;
+      const exhaustedIds: string[] = mainResult.shouldPause ? [MAIN_CODEX_ACCOUNT_ID] : [];
+      for (const { account, quotaResult } of poolResults) {
+        const currentAccount = (config.codexAccounts ?? []).find(candidate => candidate.id === account.id && !candidate.isMain);
+        if (!currentAccount) continue;
+        const generation = quotaResult?.freshCredentialGeneration;
+        const plan = quotaResult?.freshPlan ?? currentAccount.plan;
+        if (!quotaResult?.freshQuota || generation === undefined || !isCodexAccountGenerationLive(account.id, generation) || !plan) {
+          failedAccountCount += 1;
+          continue;
+        }
+        checkedAccountCount += 1;
+        if (!isCodexAccountPaused(config, account.id) && isCodexQuotaExhausted(quotaResult.freshQuota, plan)) {
+          exhaustedIds.push(account.id);
+        }
       }
-    } else {
-      failedAccountCount += 1;
-    }
-  }
-  for (const { account, quotaResult } of poolResults) {
-    const currentAccount = (config.codexAccounts ?? []).find(candidate => candidate.id === account.id && !candidate.isMain);
-    if (!currentAccount) continue;
-    const generation = quotaResult?.freshCredentialGeneration;
-    const plan = quotaResult?.freshPlan ?? currentAccount.plan;
-    if (!quotaResult?.freshQuota || generation === undefined || !isCodexAccountGenerationLive(account.id, generation) || !plan) {
-      failedAccountCount += 1;
-      continue;
-    }
-    checkedAccountCount += 1;
-    if (!isCodexAccountPaused(config, account.id) && isCodexQuotaExhausted(quotaResult.freshQuota, plan)) {
-      exhaustedIds.push(account.id);
-    }
-  }
 
-  for (const id of exhaustedIds) {
-    setCodexAccountPaused(config, id, true);
-    clearThreadAccountMapForAccount(id);
+      for (const id of exhaustedIds) {
+        setCodexAccountPaused(config, id, true);
+        clearThreadAccountMapForAccount(id);
+      }
+      for (const id of exhaustedIds) selectFallbackAfterPause(config, id);
+      const result = {
+        pausedAccountIds: exhaustedIds,
+        checkedAccountCount,
+        failedAccountCount,
+      };
+      // Persist while both the in-process admission and cross-process shared
+      // claim still own the physical-main identity used for the decision.
+      if (result.pausedAccountIds.length > 0) persistPausedAccounts();
+      return result;
+    };
+
+    if (!nativeMainLease) return await performPause();
+    try {
+      return await withNativeMainCredentialClaim(() => performPause(nativeMainLease));
+    } catch (error) {
+      if (isNativeMainClaimUnavailable(error)) return await performPause();
+      throw error;
+    }
+  } finally {
+    nativeMainLease?.release();
   }
-  for (const id of exhaustedIds) selectFallbackAfterPause(config, id);
-  return { pausedAccountIds: exhaustedIds, checkedAccountCount, failedAccountCount };
 }
 
 export async function handleCodexAuthAPI(
   req: Request,
   url: URL,
   config: OcxConfig,
+  convergeCodexCatalog?: CodexAuthCatalogConvergence,
 ): Promise<Response | null> {
 
   if (url.pathname === "/api/codex-auth/accounts" && req.method === "GET") {
@@ -911,50 +1450,7 @@ export async function handleCodexAuthAPI(
   }
 
   if (url.pathname === "/api/codex-auth/accounts" && req.method === "POST") {
-    if (!isUnverifiedCodexImportEnabled()) return manualImportDisabledResponse();
-
-    let body: { id: string; email: string; plan?: string; accessToken: string; refreshToken: string; chatgptAccountId: string };
-    try { body = (await req.json()) as typeof body; } catch { return jsonResponse({ error: "Invalid JSON" }, 400); }
-    if (!body.id || !body.email || !body.accessToken || !body.refreshToken || !body.chatgptAccountId) {
-      return jsonResponse({ error: "Missing required fields" }, 400);
-    }
-    if (!isValidCodexAccountId(body.id)) {
-      return jsonResponse({ error: "Invalid account id format" }, 400);
-    }
-    if (body.accessToken.length > 10_000 || body.refreshToken.length > 10_000) {
-      return jsonResponse({ error: "Input too large" }, 400);
-    }
-    const runtimeConfig = getRuntimeConfig(config);
-    const preflightConflict = codexAccountPersistenceConflict(runtimeConfig, body.id, "create");
-    if (preflightConflict) return jsonResponse({ error: preflightConflict }, 400);
-    // 1.1: Duplicate check is scoped by personal vs workspace plan bucket.
-    const derivedAccountId = extractAccountId(undefined, body.accessToken) ?? body.chatgptAccountId;
-    const collision = checkAccountIdCollision(derivedAccountId, body.email, body.plan);
-    if (collision.collision) {
-      return jsonResponse({ error: collision.reason }, 400);
-    }
-    // 4.2: use JWT exp for expiresAt instead of hardcoded 1 hour
-    const payload = decodeJwtPayload(body.accessToken);
-    const exp = typeof payload?.exp === "number" ? payload.exp * 1000 : Date.now() + 3600_000;
-    const warmup = await verifyCodexAccountWarmup(body.id, body.accessToken, derivedAccountId);
-    if (!warmup.ok) return warmup.response;
-    const latestConfig = getRuntimeConfig(config);
-    const commitConflict = codexAccountPersistenceConflict(latestConfig, body.id, "create");
-    if (commitConflict) return jsonResponse({ error: commitConflict }, 400);
-    saveCodexAccountCredential(body.id, {
-      accessToken: body.accessToken,
-      refreshToken: body.refreshToken,
-      expiresAt: exp,
-      chatgptAccountId: derivedAccountId,
-    });
-    markCodexAccountValidated(body.id, warmup.validatedAt);
-    clearAccountNeedsReauth(body.id);
-    const accounts = latestConfig.codexAccounts ?? [];
-    accounts.push(withCodexAccountLogLabel({ id: body.id, email: body.email, plan: body.plan, isMain: false }, accounts));
-    latestConfig.codexAccounts = accounts;
-    saveRuntimeConfig(config, latestConfig);
-    reconcileLiveStateStores();
-    return jsonResponse({ ok: true });
+    return manualImportDisabledResponse();
   }
 
   if (url.pathname === "/api/codex-auth/accounts" && req.method === "DELETE") {
@@ -966,10 +1462,15 @@ export async function handleCodexAuthAPI(
     if (!isValidCodexAccountId(id) && !isLegacyPoolAccount) {
       return jsonResponse({ error: "Invalid account id format" }, 400);
     }
-    deleteCodexAccount(runtimeConfig, id);
+    const pickerVisibilityChanged = deleteCodexAccount(runtimeConfig, id);
     saveRuntimeConfig(config, runtimeConfig);
     reconcileLiveStateStores();
-    return jsonResponse({ ok: true });
+    const catalogRefresh = await convergeAccountNamespaceCatalog(
+      runtimeConfig,
+      pickerVisibilityChanged,
+      convergeCodexCatalog,
+    );
+    return jsonResponse({ ok: true, ...catalogRefresh });
   }
 
   if (url.pathname === "/api/codex-auth/accounts/alias" && req.method === "PUT") {
@@ -1018,9 +1519,59 @@ export async function handleCodexAuthAPI(
     });
   }
 
+  // Deliberately a route of its own rather than a field on the alias PATCH: aliases
+  // are display-only and reject __main__, while selection order is routing metadata
+  // that the Desktop account must be able to carry. Re-ordering never kicks a live
+  // thread, so there is no affinity clearing and no appliesImmediately here.
+  if (url.pathname === "/api/codex-auth/accounts/priority" && req.method === "PUT") {
+    let parsedBody: unknown;
+    try { parsedBody = await req.json(); } catch { return jsonResponse({ error: "Invalid JSON" }, 400); }
+    if (typeof parsedBody !== "object" || parsedBody === null || Array.isArray(parsedBody)) {
+      return jsonResponse({ error: "body must be an object" }, 400);
+    }
+    const body = parsedBody as { id?: unknown; priority?: unknown };
+    const id = typeof body.id === "string" ? body.id.trim() : "";
+    if (!isCodexAccountPriorityKey(id)) {
+      return jsonResponse({ error: "Invalid account id format" }, 400);
+    }
+
+    let priority = DEFAULT_ACCOUNT_PRIORITY;
+    if (body.priority !== null) {
+      const parsed = parseAccountPriority(body.priority);
+      if (parsed === null) {
+        return jsonResponse({
+          error: `priority must be null or an integer ${MIN_ACCOUNT_PRIORITY}-${MAX_ACCOUNT_PRIORITY}`,
+        }, 400);
+      }
+      priority = parsed;
+    }
+
+    const runtimeConfig = getRuntimeConfig(config);
+    const exists = id === MAIN_CODEX_ACCOUNT_ID
+      || (runtimeConfig.codexAccounts ?? []).some(account => isSelectableCodexPoolAccount(account) && account.id === id);
+    if (!exists) return jsonResponse({ error: "Account not found" }, 404);
+
+    setCodexAccountPriority(runtimeConfig, id, priority);
+    // Both a pin and an order are the operator saying which account to use, so the newer
+    // statement wins. Without this a pin made before any order existed — an ordinary
+    // account switch — would outrank the order forever: it blocks preemption and caps
+    // every eligibility list at its own tier until that account drains or is paused.
+    clearCodexAccountPin(runtimeConfig);
+    saveRuntimeConfig(config, runtimeConfig);
+    return jsonResponse({
+      ok: true,
+      id,
+      priority,
+      activeCodexAccountId: getEffectiveActiveCodexAccountId(runtimeConfig) ?? null,
+    });
+  }
+
   if (url.pathname === "/api/codex-auth/accounts/pause-exhausted" && req.method === "PUT") {
     const runtimeConfig = getRuntimeConfig(config);
-    const result = await pauseExhaustedCodexAccounts(runtimeConfig);
+    const result = await pauseExhaustedCodexAccounts(
+      runtimeConfig,
+      () => saveRuntimeConfig(config, runtimeConfig),
+    );
     const { pausedAccountIds, checkedAccountCount, failedAccountCount } = result;
     if (checkedAccountCount === 0 && failedAccountCount > 0) {
       return jsonResponse({
@@ -1030,7 +1581,6 @@ export async function handleCodexAuthAPI(
         failedAccountCount,
       }, 502);
     }
-    if (pausedAccountIds.length > 0) saveRuntimeConfig(config, runtimeConfig);
     return jsonResponse({
       ok: true,
       pausedAccountIds,
@@ -1078,6 +1628,15 @@ export async function handleCodexAuthAPI(
       if (!exists) return jsonResponse({ error: "Account not found" }, 400);
     }
     runtimeConfig.activeCodexAccountId = body.accountId ?? undefined;
+    // "Use this account now" outranks selection order until the account is spent:
+    // persisted here rather than in resetCodexRoutingForManualSelection, which is
+    // runtime state only. A null id clears the selection instead of making one, so it
+    // must release the pin rather than record one: pinning the `targetAccountId`
+    // fallback would leave a pin that no effective active account matches, which
+    // `isEffectiveCodexAccountPinned` reports as unpinned while the tier filter still
+    // honours it as a ceiling — invisibly capping the pool at the main account's tier.
+    if (body.accountId == null) clearCodexAccountPin(runtimeConfig);
+    else setCodexAccountPin(runtimeConfig, targetAccountId);
     resetCodexRoutingForManualSelection(targetAccountId);
     saveRuntimeConfig(config, runtimeConfig);
     return jsonResponse({ ok: true, activeCodexAccountId: body.accountId, appliesImmediately: true });
@@ -1087,6 +1646,13 @@ export async function handleCodexAuthAPI(
     const runtimeConfig = getRuntimeConfig(config);
     return jsonResponse({
       activeCodexAccountId: getEffectiveActiveCodexAccountId(runtimeConfig) ?? null,
+      pinned: isEffectiveCodexAccountPinned(runtimeConfig),
+      // Which account carries the pin, not just whether the active one does. Under
+      // round-robin or fill-first the pin caps the tier ceiling at its own tier while the
+      // strategy cursor moves freely inside that tier, so `pinned` alone goes false on a
+      // sibling's turn even though the pin is still suppressing every higher tier. The id
+      // lets a surface mark the account the operator actually chose.
+      pinnedAccountId: pinnedCodexAccountId(runtimeConfig) ?? null,
       autoSwitchThreshold: runtimeConfig.autoSwitchThreshold ?? 80,
       upstreamFailoverThreshold: runtimeConfig.upstreamFailoverThreshold ?? 3,
       accountPoolStrategy: normalizeAccountPoolStrategy(runtimeConfig.accountPoolStrategy),
@@ -1169,24 +1735,47 @@ export async function handleCodexAuthAPI(
     if (!accountId) return jsonResponse({ error: "accountId required" }, 400);
 
     try {
-      const auth = await resolveResetCreditAuth(getRuntimeConfig(config), accountId);
-      if (!auth.ok) return auth.response;
-
-      const resp = await fetch(
-        "https://chatgpt.com/backend-api/wham/rate-limit-reset-credits",
-        {
-          headers: {
-            Authorization: `Bearer ${auth.accessToken}`,
-            "ChatGPT-Account-Id": auth.chatgptAccountId,
-          },
-          signal: AbortSignal.timeout(8000),
-        },
-      );
-      if (!resp.ok) {
-        await resp.body?.cancel().catch(() => {});
-        return jsonResponse({ error: `Upstream error ${resp.status}` }, resp.status);
-      }
-      return jsonResponse(safeResetCreditsDto(await resp.json()));
+      const result = await withResetCreditAuth(getRuntimeConfig(config), accountId, async auth => {
+        const linkedSignal = signalWithTimeout(8000, req.signal);
+        let detachBodyAbort = () => {};
+        try {
+          let resp: Response;
+          try {
+            resp = await fetch(
+              "https://chatgpt.com/backend-api/wham/rate-limit-reset-credits",
+              {
+                headers: {
+                  Authorization: `Bearer ${auth.accessToken}`,
+                  "ChatGPT-Account-Id": auth.chatgptAccountId,
+                },
+                signal: linkedSignal.signal,
+              },
+            );
+          } catch (error) {
+            if (linkedSignal.signal.aborted) {
+              return jsonResponse({ error: "Invalid upstream reset-credit response" }, 502);
+            }
+            throw error;
+          }
+          // Own the response body before the bounded reader attaches. If the client
+          // disconnects in that narrow window, Bun otherwise tears down the native
+          // body off the awaited path and can report an unhandled rejection.
+          detachBodyAbort = cancelBodyOnAbort(resp.body, linkedSignal.signal);
+          if (!resp.ok) {
+            await resp.body?.cancel().catch(() => {});
+            return jsonResponse({ error: `Upstream error ${resp.status}` }, resp.status);
+          }
+          const parsed = await readResetCreditJson(resp, linkedSignal.signal);
+          if (!parsed.ok) {
+            return jsonResponse({ error: "Invalid upstream reset-credit response" }, 502);
+          }
+          return jsonResponse(safeResetCreditsDto(parsed.value));
+        } finally {
+          detachBodyAbort();
+          linkedSignal.cleanup();
+        }
+      });
+      return result.ok ? result.value : result.response;
     } catch (e) {
       return jsonResponse({ error: e instanceof Error ? e.message : "Reset credit lookup failed" }, 500);
     }
@@ -1195,49 +1784,55 @@ export async function handleCodexAuthAPI(
   if (url.pathname === "/api/codex-auth/reset-credits/consume" && req.method === "POST") {
     const body = (await req.json().catch(() => ({}))) as { accountId?: string };
     if (!body.accountId) return jsonResponse({ error: "accountId required" }, 400);
+    const accountId = body.accountId;
 
     try {
-      const auth = await resolveResetCreditAuth(getRuntimeConfig(config), body.accountId);
-      if (!auth.ok) return auth.response;
-
-      const idempotencyKey = crypto.randomUUID();
-      const resp = await fetch(
-        "https://chatgpt.com/backend-api/wham/rate-limit-reset-credits/consume",
-        {
-          method: "POST",
-          headers: {
-            Authorization: `Bearer ${auth.accessToken}`,
-            "ChatGPT-Account-Id": auth.chatgptAccountId,
-            "Content-Type": "application/json",
+      const operation = await withResetCreditAuth(getRuntimeConfig(config), accountId, async auth => {
+        const idempotencyKey = crypto.randomUUID();
+        const resp = await fetch(
+          "https://chatgpt.com/backend-api/wham/rate-limit-reset-credits/consume",
+          {
+            method: "POST",
+            headers: {
+              Authorization: `Bearer ${auth.accessToken}`,
+              "ChatGPT-Account-Id": auth.chatgptAccountId,
+              "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ redeem_request_id: idempotencyKey }),
+            signal: AbortSignal.timeout(10_000),
           },
-          body: JSON.stringify({ redeem_request_id: idempotencyKey }),
-          signal: AbortSignal.timeout(10_000),
-        },
-      );
-      if (!resp.ok) {
-        await resp.body?.cancel().catch(() => {});
-        return jsonResponse({ error: `Upstream error ${resp.status}` }, resp.status);
-      }
-      const result = safeResetCreditConsumeDto(await resp.json());
-      // After a successful redeem (or an idempotent already_redeemed), refresh WHAM usage
-      // and return remaining only when that refresh freshly parsed available_count.
-      // Do not fall back to a preserved cached resetCredits (failed/omitted refresh).
-      if (result.code === "reset" || result.code === "already_redeemed") {
-        let freshResetCredits: number | undefined;
-        if (auth.isMain) {
-          ({ freshResetCredits } = await fetchMainAccountInfoAttempt(true, 1));
-        } else {
-          const account = configuredPoolAccount(getRuntimeConfig(config), body.accountId);
-          ({ freshResetCredits } = await fetchPoolAccountQuota(body.accountId, true, account?.plan));
+        );
+        if (!resp.ok) {
+          await resp.body?.cancel().catch(() => {});
+          return jsonResponse({ error: `Upstream error ${resp.status}` }, resp.status);
         }
-        return jsonResponse({
-          code: result.code,
-          ...(typeof freshResetCredits === "number" && Number.isFinite(freshResetCredits)
-            ? { remaining: freshResetCredits }
-            : {}),
-        });
-      }
-      return jsonResponse(result);
+        const result = safeResetCreditConsumeDto(await resp.json());
+        // After a successful redeem (or an idempotent already_redeemed), refresh WHAM usage
+        // and return remaining only when that refresh freshly parsed available_count.
+        // Do not fall back to a preserved cached resetCredits (failed/omitted refresh).
+        if (result.code === "reset" || result.code === "already_redeemed") {
+          let freshResetCredits: number | undefined;
+          if (auth.isMain) {
+            ({ freshResetCredits } = await fetchMainAccountInfoAttempt(
+              true,
+              1,
+              auth.nativeMainLease,
+              auth.nativeMainSharedClaimHeld === true,
+            ));
+          } else {
+            const account = configuredPoolAccount(getRuntimeConfig(config), accountId);
+            ({ freshResetCredits } = await fetchPoolAccountQuota(accountId, true, account?.plan));
+          }
+          return jsonResponse({
+            code: result.code,
+            ...(typeof freshResetCredits === "number" && Number.isFinite(freshResetCredits)
+              ? { remaining: freshResetCredits }
+              : {}),
+          });
+        }
+        return jsonResponse(result);
+      });
+      return operation.ok ? operation.value : operation.response;
     } catch (e) {
       if (e instanceof PoolQuotaProbeBusyError) {
         const response = jsonResponse({ error: "server_busy", code: "server_busy" }, 503);
@@ -1249,7 +1844,7 @@ export async function handleCodexAuthAPI(
   }
 
   if (url.pathname === "/api/codex-auth/login" && req.method === "POST") {
-    const body = (await req.json().catch(() => ({}))) as { id?: string; reauth?: boolean };
+    const body = (await req.json().catch(() => ({}))) as { id?: string; reauth?: boolean; openBrowser?: unknown };
     const requestedAccountId = body.id?.trim();
     const reauth = body.reauth === true;
     if (requestedAccountId && !isValidCodexAccountId(requestedAccountId)) {
@@ -1278,12 +1873,14 @@ export async function handleCodexAuthAPI(
     const loginOwner: CodexLoginStateRow = { status: "starting", startedAt: Date.now() };
     codexAuthLoginState.set(flowId, loginOwner);
     try {
-      const { startLoginFlow, getLoginStatus } = await import("../oauth");
+      const { startLoginFlow, getLoginStatus, publicOAuthAuthenticationErrorMessage } = await import("../oauth");
       const result = await startLoginFlow("chatgpt", { forceLogin: true });
 
       // Open the browser server-side (same pattern as /api/oauth/login in management-api.ts).
       // The GUI's window.open is popup-blocked because it runs after an await, not a direct click.
-      if (result.url) {
+      // Both login routes share one resolver so this surface cannot drift from the other.
+      const { shouldOpenBrowserForLogin } = await import("../oauth/open-browser-choice");
+      if (result.url && shouldOpenBrowserForLogin(body.openBrowser, runtimeConfig)) {
         const { openUrl } = await import("../lib/open-url");
         openUrl(result.url);
       }
@@ -1391,6 +1988,8 @@ export async function handleCodexAuthAPI(
                 const latestConfig = getRuntimeConfig(config);
                 const accounts = latestConfig.codexAccounts ?? [];
                 const existingIdx = accounts.findIndex(account => account.id === accountId);
+                let pickerVisibilityChanged = false;
+                let newAccountPersistence: PersistNewCodexAccountOutcome | null = null;
                 const commitConflict = codexAccountPersistenceConflict(
                   latestConfig,
                   accountId,
@@ -1406,22 +2005,21 @@ export async function handleCodexAuthAPI(
                   break;
                 }
 
-                saveCodexAccountCredential(accountId, {
+                const credential: CodexAccountCredentials = {
                   accessToken: cred.access,
                   refreshToken: cred.refresh,
                   expiresAt: cred.expires,
                   chatgptAccountId: oauthAccountId,
-                });
-                // A successful reauthentication replaces the credential generation. Do not let a
-                // failed optional WHAM probe make the replacement inherit quota from the old record.
-                if (reauth) clearAccountQuota(accountId);
-                markCodexAccountValidated(accountId, warmup.validatedAt);
-                clearAccountNeedsReauth(accountId);
-                if (quota) {
-                  setAccountQuotaFromParsed(accountId, quota);
-                }
+                };
 
                 if (existingIdx >= 0) {
+                  saveCodexAccountCredential(accountId, credential);
+                  // A successful reauthentication replaces the credential generation. Do not let a
+                  // failed optional WHAM probe make the replacement inherit quota from the old record.
+                  if (reauth) clearAccountQuota(accountId);
+                  markCodexAccountValidated(accountId, warmup.validatedAt);
+                  clearAccountNeedsReauth(accountId);
+                  if (quota) setAccountQuotaFromParsed(accountId, quota);
                   // Keep the pool id stable; refresh display metadata after a successful login/reauth.
                   accounts[existingIdx] = withCodexAccountLogLabel({
                     ...accounts[existingIdx],
@@ -1432,18 +2030,60 @@ export async function handleCodexAuthAPI(
                   latestConfig.codexAccounts = accounts;
                   saveRuntimeConfig(config, latestConfig);
                 } else {
-                  accounts.push(withCodexAccountLogLabel({ id: accountId, email, plan, isMain: false }, accounts));
-                  latestConfig.codexAccounts = accounts;
-                  saveRuntimeConfig(config, latestConfig);
+                  const addedAccount = withCodexAccountLogLabel({ id: accountId, email, plan, isMain: false }, accounts);
+                  newAccountPersistence = persistNewCodexAccount(
+                    config,
+                    latestConfig,
+                    addedAccount,
+                    {
+                      credential,
+                      validatedAt: warmup.validatedAt,
+                    },
+                  );
+                  pickerVisibilityChanged = newAccountPersistence.pickerVisibilityChanged;
                 }
                 reconcileLiveStateStores();
-                setCodexLoginState(flowId, { status: "done", accountId, email, doneAt: Date.now() });
-                completed = true;
+                if (newAccountPersistence?.status === "publication-failed") {
+                  markAccountNeedsReauth(accountId);
+                }
+                // A new quota row is generation-gated by live account ownership. Reconcile the
+                // durable config owner first so a partial prior sweep cannot reject this write.
+                if (newAccountPersistence?.status === "committed" && quota) {
+                  setAccountQuotaFromParsed(accountId, quota);
+                }
+                const { catalogRefreshPending } = await convergeAccountNamespaceCatalog(
+                  latestConfig,
+                  pickerVisibilityChanged,
+                  convergeCodexCatalog,
+                );
+                if (newAccountPersistence?.status === "publication-failed") {
+                  setCodexLoginState(flowId, {
+                    status: "error",
+                    ...codexCredentialPersistenceFailure(accountId, catalogRefreshPending),
+                    doneAt: Date.now(),
+                  });
+                  completed = true;
+                } else {
+                  setCodexLoginState(flowId, {
+                    status: "done",
+                    accountId,
+                    email,
+                    ...(catalogRefreshPending ? { catalogRefreshPending: true } : {}),
+                    doneAt: Date.now(),
+                  });
+                  completed = true;
+                }
               }
               break;
             }
             if (st.done && st.error) {
-              setCodexLoginState(flowId, { status: "error", error: st.error, doneAt: Date.now() });
+              setCodexLoginState(flowId, {
+                status: "error",
+                // startLoginFlow projects background failures before storing login status, so
+                // fixed actionable OAuth messages retain their type-derived remediation here.
+                error: st.error,
+                doneAt: Date.now(),
+              });
               completed = true;
               break;
             }
@@ -1461,7 +2101,7 @@ export async function handleCodexAuthAPI(
             ? "Configuration is busy; retry login shortly."
             : error instanceof CodexCredentialRefreshBusyError || error instanceof CodexCredentialRefreshStaleError
               ? "Credential refresh is busy; retry login shortly."
-            : error instanceof Error ? error.message : String(error);
+            : publicOAuthAuthenticationErrorMessage(error);
           setCodexLoginState(flowId, {
             status: "error",
             error: message,
@@ -1478,7 +2118,7 @@ export async function handleCodexAuthAPI(
     } catch (e) {
       if (codexAuthLoginState.get(flowId) === loginOwner) codexAuthLoginState.delete(flowId);
       const msg = e instanceof Error ? e.message : String(e);
-      if (msg.includes("already in progress")) {
+      if (msg === "A login for chatgpt is already in progress") {
         return jsonResponse({ error: msg, status: "pending" }, 409);
       }
       if (e instanceof CodexCredentialRefreshBusyError || e instanceof CodexCredentialRefreshStaleError) {
@@ -1486,7 +2126,8 @@ export async function handleCodexAuthAPI(
         response.headers.set("Retry-After", "1");
         return response;
       }
-      return jsonResponse({ error: msg }, 500);
+      const { publicOAuthAuthenticationErrorMessage } = await import("../oauth");
+      return jsonResponse({ error: publicOAuthAuthenticationErrorMessage(e) }, 500);
     }
   }
 
@@ -1524,7 +2165,13 @@ export async function handleCodexAuthAPI(
     const reauthStatus = url.searchParams.get("reauth") === "1";
     if (flowId) {
       const st = codexAuthLoginState.get(flowId);
-      if (!st && accountId && !reauthStatus && getCodexAccountCredential(accountId)) {
+      if (
+        !st
+        && accountId
+        && !reauthStatus
+        && !isAccountNeedsReauth(accountId)
+        && getCodexAccountCredential(accountId)
+      ) {
         return jsonResponse({ status: "done", accountId });
       }
       return jsonResponse(st ? { ...st, email: st.email ?? undefined } : { status: "expired" });