@bitkyc08/opencodex 2.55.0 → 2.56.0

package/src/codex/auth-api/main-account-probe.ts

@@ -0,0 +1,331 @@
+import { parseMainPolicyUsageQuota, parseUsageQuota, setAccountQuotaFromParsed } from "../quota";
+import type { StoredAccountQuota, WhamUsageResponse } from "../quota";
+import { reconcileMainCodexAccountRuntimeState } from "../account-lifecycle";
+import { getMainChatgptAccountId, readCodexTokensResult } from "../auth-collision";
+import { clearAccountNeedsReauth, markAccountNeedsReauth } from "../account-runtime-state";
+import { extractAccountId } from "../../oauth/chatgpt";
+import { getMainAccountPlan, isMainAccountTokenVerifiablyLive, MAIN_CODEX_ACCOUNT_ID, setMainAccountPlan } from "../main-account";
+import { captureConfigGeneration } from "../../lib/state-store-sweeper";
+import { captureMainAccountIdentityGeneration, clearMainAccountInfoCache, getMainAccountInfoCache, getMainQuotaCredentialGeneration, isMainAccountIdentityGenerationLive, isMainQuotaWriterLive, matchesMainQuotaCredential, observeMainQuotaCredential, setMainAccountCredentialPresence, setMainAccountInfoCache } from "../main-account-cache";
+import type { MainQuotaWriter, MainAccountInfo } from "../main-account-cache";
+import type { CodexQuotaRefreshOutcome } from "../quota-refresh-outcome";
+import { observeMainReserveRevocation } from "../reserve-availability";
+import type { AdmissionLease } from "../../lib/admission";
+import { nonEmptyPlan } from "./runtime-config";
+import { tryAcquireNativeMainProfileClaim } from "../native-main-admission";
+import { WHAM_REQUEST_TIMEOUT_MS } from "../quota-recovery-timing";
+import { withNativeMainCredentialClaim, isNativeMainClaimUnavailable } from "./http";
+import { MAIN_TERMINAL_AUTH_CODES, readMainAuthErrorCode, nextQuotaDispatchSequence, isQuotaDispatchCurrent, publishQuotaDispatch } from "./pool-quota-probe";
+
+/**
+ * Last reset-credit count this process parsed for the main account, tagged with the
+ * physical ChatGPT account it was read from.
+ *
+ * It is deliberately memory-only. The quota store is keyed by the stable `__main__`
+ * ALIAS, and `~/.codex/auth.json` can be swapped for another account while the proxy is
+ * not running — `reconcileMainCodexAccountRuntimeState` only purges alias-keyed state
+ * when it observes the id CHANGE, and its first observation after a restart has nothing
+ * to compare against. A disk-hydrated `__main__` entry can therefore belong to the
+ * previous login, so filling the DTO from it would show one account's tickets on
+ * another's card. Pool accounts have no such hole because their store key IS the account
+ * id. Binding the value to `requestAccountId` keeps the fill honest: after a restart the
+ * badge simply waits for the first usage response that carries the summary.
+ */
+let mainResetCreditsProvenance: { accountId: string; credits: number } | null = null;
+
+export function rememberMainResetCredits(accountId: string | null, credits: number | undefined): void {
+  if (accountId === null || credits === undefined) return;
+  mainResetCreditsProvenance = { accountId, credits };
+}
+
+/** Forget the remembered count when the physical main identity is no longer the same. */
+export function mainResetCreditsForCurrentIdentity(): number | undefined {
+  if (!mainResetCreditsProvenance) return undefined;
+  const currentAccountId = getMainChatgptAccountId();
+  if (currentAccountId === null) return undefined;
+  if (currentAccountId !== mainResetCreditsProvenance.accountId) {
+    mainResetCreditsProvenance = null;
+    return undefined;
+  }
+  return mainResetCreditsProvenance.credits;
+}
+
+export const MAIN_CACHE_TTL = 5 * 60_000;
+
+/**
+ * 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.
+ */
+export 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);
+}
+
+export interface MainResetQuotaProof {
+  writer: MainQuotaWriter;
+  credentialGeneration: number;
+}
+
+export interface MainAccountInfoFetchResult {
+  info: MainAccountInfo;
+  resetRecoveryProof?: MainResetQuotaProof & { dispatchSequence: number };
+  /** Ephemeral result of this attempt, omitted when no WHAM request was made. */
+  quotaRefresh?: CodexQuotaRefreshOutcome;
+  /** Internal dispatch fence for diagnostics only; never copied into a public DTO or cache. */
+  quotaRefreshGeneration?: number;
+  /** 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;
+  quotaRefresh?: CodexQuotaRefreshOutcome;
+}
+
+export async function fetchMainAccountInfoSnapshot(forceRefresh = false): Promise<MainAccountInfoSnapshot> {
+  const result = await fetchMainAccountInfoAttempt(forceRefresh, 1);
+  return {
+    info: result.info,
+    ...(result.quotaRefresh && result.quotaRefreshGeneration !== undefined
+      && isMainAccountIdentityGenerationLive(result.quotaRefreshGeneration)
+      ? { quotaRefresh: result.quotaRefresh } : {}),
+    mainIdentityGeneration: result.identityGeneration ?? captureMainAccountIdentityGeneration(),
+  };
+}
+
+export async function fetchMainAccountInfo(forceRefresh = false): Promise<MainAccountInfo> {
+  return (await fetchMainAccountInfoSnapshot(forceRefresh)).info;
+}
+
+export const EMPTY_MAIN_ACCOUNT_INFO: MainAccountInfo = { email: null, plan: null, quota: null };
+
+export 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
+    ? fetchMainAccountInfoWhileOwned(true, retriesRemaining - 1, nativeMainLease, explicitRefresh)
+    : { info: EMPTY_MAIN_ACCOUNT_INFO, credentialChecked: true, hasCredential: true };
+}
+
+export async function fetchMainAccountInfoAttempt(
+  forceRefresh: boolean,
+  retriesRemaining: number,
+  existingNativeMainLease?: AdmissionLease,
+  nativeMainSharedClaimHeld = false,
+  explicitRefresh: boolean = forceRefresh,
+): 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, explicitRefresh),
+      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();
+  }
+}
+
+export 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
+    // account for reauth here destroyed healthy email/plan/quota state and pinned a working
+    // account as unusable. Preserve what we already know and let the caller retry; request
+    // 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, 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, credentialChecked: true, hasCredential: true };
+  }
+  // Bind quota to the owned credential and the account actually selected by WHAM's header.
+  // A conflicting legacy token/account tuple is not evidence for the new policy.
+  const mainQuotaWriter = requestAccountId === tokens.account_id
+    ? observeMainQuotaCredential(tokens.access_token, tokens.account_id)
+    : undefined;
+  const mainQuotaCredentialGeneration = getMainQuotaCredentialGeneration();
+  // Keep diagnostics separate from authentication and freshness policy. Never serialize errors.
+  const quotaSignal = AbortSignal.timeout(WHAM_REQUEST_TIMEOUT_MS);
+  let quotaPhase: "request" | "body" | "decode" | "publish" = "request";
+  let quotaRefreshGeneration = captureMainAccountIdentityGeneration();
+  try {
+    const dispatchSequence = nextQuotaDispatchSequence();
+    const resp = await fetch("https://chatgpt.com/backend-api/wham/usage", {
+      headers: { Authorization: `Bearer ${tokens.access_token}`, "ChatGPT-Account-Id": tokens.account_id },
+      signal: quotaSignal,
+    });
+    quotaPhase = "publish";
+    if (!resp.ok) {
+      const terminalAuthFailure = await isTerminalMainAuthResponse(resp, isMainAccountTokenVerifiablyLive());
+      const retried = await retryMainAccountInfoIfIdentityChanged(requestAccountId, retriesRemaining, nativeMainLease, explicitRefresh);
+      if (retried) return retried;
+      if (!isQuotaDispatchCurrent(dispatchSequence)) {
+        return { info: getMainAccountInfoCache() ?? EMPTY_MAIN_ACCOUNT_INFO,
+          credentialChecked: true, hasCredential: true };
+      }
+      if (terminalAuthFailure) {
+        // Account for this attempt's own synchronous invalidation, never prior external drift.
+        const diagnosticStillLive = isMainAccountIdentityGenerationLive(quotaRefreshGeneration);
+        clearMainAccountInfoCache();
+        if (diagnosticStillLive) quotaRefreshGeneration = captureMainAccountIdentityGeneration();
+        markAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID, writerGeneration);
+      }
+      return {
+        info: EMPTY_MAIN_ACCOUNT_INFO, credentialChecked: true, hasCredential: true,
+        quotaRefresh: { status: "http_error", httpStatus: resp.status },
+        quotaRefreshGeneration,
+      };
+    }
+    quotaPhase = "body";
+    const data = (await resp.json()) as WhamUsageResponse;
+    quotaPhase = "publish";
+    const retried = await retryMainAccountInfoIfIdentityChanged(requestAccountId, retriesRemaining, nativeMainLease, explicitRefresh);
+    if (retried) return retried;
+    quotaPhase = "decode";
+    if (data === null || typeof data !== "object" || Array.isArray(data)) {
+      throw new Error("Invalid WHAM usage object");
+    }
+    // Check after body/retry awaits and before any cache, credits, policy or
+    // Reserve publication. Returning cached state supplies no fresh recovery proof.
+    if (!isQuotaDispatchCurrent(dispatchSequence)) {
+      return { info: getMainAccountInfoCache() ?? EMPTY_MAIN_ACCOUNT_INFO,
+        credentialChecked: true, hasCredential: true };
+    }
+    quotaPhase = "publish";
+    // A delayed response from a replaced bearer cannot revoke a newer Reserve grant,
+    // even in the same workspace or after an A→B→A credential transition.
+    if (mainQuotaCredentialGeneration === getMainQuotaCredentialGeneration()
+      && matchesMainQuotaCredential(tokens.access_token, tokens.account_id)) {
+      observeMainReserveRevocation(data, mainQuotaWriter);
+    }
+    quotaPhase = "decode";
+    const plan = nonEmptyPlan(data.plan_type) ?? nonEmptyPlan(cached?.plan) ?? nonEmptyPlan(getMainAccountPlan());
+    const usage = { ...data, ...(plan ? { plan_type: plan } : {}) };
+    const quota = parseUsageQuota(usage);
+    const policyQuota = parseMainPolicyUsageQuota(usage);
+    quotaPhase = "publish";
+    const freshResetCredits = quota?.resetCredits;
+    // Tag the count with the identity it was read from, so a later response that omits the
+    // summary can restore the badge without ever crossing an account boundary.
+    rememberMainResetCredits(requestAccountId, freshResetCredits);
+    const result = {
+      email: data.email ?? null,
+      plan,
+      quota,
+      ts: Date.now(),
+    };
+    setMainAccountInfoCache(result);
+    // 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);
+    if (result.quota) {
+      setAccountQuotaFromParsed(MAIN_CODEX_ACCOUNT_ID, result.quota, writerGeneration, mainQuotaWriter, policyQuota);
+    }
+    publishQuotaDispatch(dispatchSequence);
+    return {
+      info: result,
+      quotaRefresh: { status: quota ? "ok" : "not_reported" },
+      quotaRefreshGeneration,
+      credentialChecked: true,
+      hasCredential: true,
+      ...(quota ? { freshQuota: quota } : {}),
+      ...(quota && mainQuotaWriter && isMainQuotaWriterLive(mainQuotaWriter)
+        && mainQuotaCredentialGeneration === getMainQuotaCredentialGeneration()
+        && matchesMainQuotaCredential(tokens.access_token, tokens.account_id)
+        ? { resetRecoveryProof: { writer: mainQuotaWriter, credentialGeneration: mainQuotaCredentialGeneration, dispatchSequence } }
+        : {}),
+      ...(freshResetCredits !== undefined ? { freshResetCredits } : {}),
+    };
+  } catch (error) {
+    const retried = await retryMainAccountInfoIfIdentityChanged(requestAccountId, retriesRemaining, nativeMainLease, explicitRefresh);
+    if (retried) return retried;
+    let status: CodexQuotaRefreshOutcome["status"] = "internal_error";
+    if ((quotaPhase === "request" || quotaPhase === "body") && quotaSignal.aborted) status = "timeout";
+    else if (quotaPhase === "request") status = "network_error";
+    else if (quotaPhase === "body") status = error instanceof SyntaxError ? "invalid_response" : "network_error";
+    else if (quotaPhase === "decode") status = "invalid_response";
+    return {
+      info: EMPTY_MAIN_ACCOUNT_INFO, credentialChecked: true, hasCredential: true,
+      quotaRefresh: { status },
+      quotaRefreshGeneration,
+    };
+  }
+}

package/src/codex/auth-api/pool-mode-gate.ts

@@ -0,0 +1,274 @@
+import { getCodexAccountCredential, getValidCodexToken, readCodexAccountRecord } from "../account-store";
+import { getAccountQuota, isCompleteCodexQuotaRecoverySnapshot } from "../quota";
+import { reconcileMainCodexAccountRuntimeState } from "../account-lifecycle";
+import { claimDueCodexQuotaRecoveryProbes, settleCodexQuotaRecoveryProbe } from "../routing";
+import { readCodexTokens } from "../auth-collision";
+import { isAccountNeedsReauth, markAccountNeedsReauth } from "../account-runtime-state";
+import { getValidMainAccountToken, MainAccountTokenRefreshError, MAIN_CODEX_ACCOUNT_ID } from "../main-account";
+import { captureConfigGeneration, registerStateSweepAfterTick } from "../../lib/state-store-sweeper";
+import { captureMainAccountIdentityGeneration, isMainAccountIdentityGenerationLive } from "../main-account-cache";
+import { getMainAccountHardLockStatus } from "../main-account-hard-lock";
+import type { OcxConfig } from "../../types";
+import { isCanonicalOpenAiForwardProvider, OPENAI_CODEX_PROVIDER_ID } from "../../providers/openai-tiers";
+import { providerCodexAccountMode } from "../../providers/registry";
+import { isSelectableCodexPoolAccount } from "../account-id";
+import type { AdmissionLease } from "../../lib/admission";
+import { tryAcquireNativeMainProfileClaim } from "../native-main-admission";
+import { withNativeMainCredentialClaim, isNativeMainClaimUnavailable } from "./http";
+import type { PoolQuotaResult } from "./pool-quota-probe";
+import { fetchMainAccountInfoAttempt, fetchMainAccountInfo } from "./main-account-probe";
+import { fetchPoolAccountQuota, PoolQuotaProbeBusyError, POOL_CACHE_TTL, POOL_QUOTA_REFRESH_CONCURRENCY } from "./pool-quota-probe";
+import { getRuntimeConfig, configuredPoolAccount, mapWithConcurrency } from "./runtime-config";
+
+let primeInFlight: Promise<void> | null = null;
+/**
+ * Last prime attempt per pool account. A failed WHAM lookup stores no quota, so
+ * without this the account stays "unknown" and every later prime trigger re-selects
+ * it as stale and repeats the same failing request. Successful lookups are already
+ * throttled by their stored updatedAt; this gives failures the same TTL backoff.
+ *
+ * Keyed by credential generation so a re-authentication, refresh, or account removal
+ * retries immediately instead of waiting out a backoff earned by the old credential.
+ */
+const poolQuotaPrimeAttemptedAt = new Map<string, { generation: number; at: number }>();
+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: independent scopes are already excluded at the claim site.
+        // Generic WHAM must never clear Reserve even if claim selection changes.
+        const recovered = (claim.scope === undefined || claim.scope === "shared")
+          && 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;
+}
+
+let mainHardLockRecoveryInFlight: Promise<void> | null = null;
+
+/** Metadata-only recovery on the existing sweep; failures retain the observed policy block. */
+export async function runMainAccountHardLockRecovery(config: OcxConfig): Promise<void> {
+  if (mainHardLockRecoveryInFlight) return mainHardLockRecoveryInFlight;
+  if (getMainAccountHardLockStatus(config).state !== "blocked"
+    || isAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID)) return;
+  const lease = tryAcquireNativeMainProfileClaim();
+  if (!lease) return;
+  mainHardLockRecoveryInFlight = (async () => {
+    reconcileMainCodexAccountRuntimeState();
+    if (getMainAccountHardLockStatus(config).state !== "blocked"
+      || isAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID)) return;
+    const identityGeneration = captureMainAccountIdentityGeneration();
+    const writerGeneration = captureConfigGeneration();
+    try {
+      // Refresh can require an exclusive credential claim: never hold WHAM's shared
+      // claim while obtaining a valid token. The runtime lease spans both operations.
+      if (!await getValidMainAccountToken({ preserveReauth: true })) return;
+    } catch (error) {
+      if (error instanceof MainAccountTokenRefreshError && error.reason === "reauth"
+        && isMainAccountIdentityGenerationLive(identityGeneration)) {
+        markAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID, writerGeneration);
+      }
+      return;
+    }
+    if (isAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID)) return;
+    await fetchMainAccountInfoAttempt(true, 1, lease, false, false);
+  })().catch(() => {
+    // Best-effort background metadata read; no cooldown/pause or policy clearing on failure.
+  }).finally(() => {
+    lease.release();
+    mainHardLockRecoveryInFlight = null;
+  });
+  return mainHardLockRecoveryInFlight;
+}
+
+export function registerCodexCooldownRecoveryProbeWorker(config: OcxConfig): void {
+  registerStateSweepAfterTick({
+    name: "codex-cooldown-recovery",
+    afterTick: () => {
+      void runCodexCooldownRecoveryProbes(config);
+      void runMainAccountHardLockRecovery(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;
+}
+
+let getValidPoolTokenForPrime = getValidCodexToken;
+
+/** Test-only: inject a deterministic pre-dispatch credential outcome for quota priming. */
+export function setCodexPoolQuotaTokenResolverForTests(
+  resolver: typeof getValidCodexToken,
+): () => void {
+  const previous = getValidPoolTokenForPrime;
+  getValidPoolTokenForPrime = resolver;
+  return () => {
+    if (getValidPoolTokenForPrime === resolver) getValidPoolTokenForPrime = previous;
+  };
+}
+
+export function tryAcquireNativeMainPrimeLease(): AdmissionLease | null {
+  return tryAcquireNativeMainProfileClaim();
+}
+
+/**
+ * Best-effort prime of pool-account (and main) quota so the rotation engine has
+ * real usage scores instead of leaving every account at the unknown sentinel.
+ *
+ * Quota is otherwise populated only from live upstream headers (an idle pool
+ * account never serves traffic, so it never gets scored) or from the dashboard
+ * WHAM fetch (a CLI-only user never opens it). Without priming, every account
+ * stays unknown and auto-switch cannot move (see Phase 10). This runs at startup
+ * and lazily before routing when the active account is unknown.
+ *
+ * Single-flight: concurrent callers share one pass instead of stampeding N WHAM
+ * fetches. Per-fetch 8s timeouts and the 5-minute POOL_CACHE_TTL already bound
+ * 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,
+  options: PrimeCodexPoolQuotasOptions = {},
+): Promise<void> {
+  const openai = config.providers[OPENAI_CODEX_PROVIDER_ID];
+  // Prune attempt markers for accounts that no longer exist BEFORE the eligibility
+  // return. A removal that happens while the provider is disabled or out of pool mode
+  // would otherwise leave a stale failure marker behind; restoring the same account id
+  // within POOL_CACHE_TTL would then read that old failure as current and skip the
+  // retry the restored credential is entitled to.
+  const runtimeConfig = getRuntimeConfig(config);
+  const configuredPoolIds = new Set((runtimeConfig.codexAccounts ?? []).map(account => account.id));
+  for (const accountId of poolQuotaPrimeAttemptedAt.keys()) {
+    if (!configuredPoolIds.has(accountId)) poolQuotaPrimeAttemptedAt.delete(accountId);
+  }
+  if (
+    !openai
+    || openai.disabled === true
+    || !isCanonicalOpenAiForwardProvider(openai)
+    || providerCodexAccountMode(OPENAI_CODEX_PROVIDER_ID, openai) !== "pool"
+  ) return;
+  if (primeInFlight) return primeInFlight;
+  primeInFlight = (async () => {
+    const pool = (runtimeConfig.codexAccounts ?? []).filter(isSelectableCodexPoolAccount);
+    const stale = pool.filter(a => {
+      const q = getAccountQuota(a.id);
+      if (q) return Date.now() - q.updatedAt >= POOL_CACHE_TTL;
+      // No stored quota: either never primed, or the last attempt failed. Retry only
+      // once per TTL window so an unreachable or rejecting account cannot turn every
+      // prime trigger into another upstream request.
+      const lastAttempt = poolQuotaPrimeAttemptedAt.get(a.id);
+      if (!lastAttempt) return true;
+      // A newer credential invalidates the previous failure: retry without waiting.
+      if (lastAttempt.generation !== readCodexAccountRecord(a.id)?.generation) return true;
+      return Date.now() - lastAttempt.at >= POOL_CACHE_TTL;
+    });
+    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(),
+        mapWithConcurrency(stale, POOL_QUOTA_REFRESH_CONCURRENCY, async a => {
+          if (!getCodexAccountCredential(a.id)) return;
+          let result: PoolQuotaResult;
+          try {
+            result = await fetchPoolAccountQuota(a.id, false, a.plan, getValidPoolTokenForPrime);
+          } catch (error) {
+            // Local quota-flight saturation proves no WHAM request existed for this account.
+            // Consume it per item so sibling workers remain inside the shared prime lifetime.
+            if (error instanceof PoolQuotaProbeBusyError) return;
+            throw error;
+          }
+          // Only the data-plane function knows whether upstream dispatch began. Any
+          // cache hit, credential deferral, or local admission failure remains eligible.
+          const attempted = result.quotaProbeAttempted;
+          if (!attempted) return;
+          if (!configuredPoolAccount(getRuntimeConfig(config), a.id)) {
+            poolQuotaPrimeAttemptedAt.delete(a.id);
+            return;
+          }
+          poolQuotaPrimeAttemptedAt.set(a.id, {
+            // getValidCodexToken may rotate the credential before WHAM is sent.
+            // Bind the backoff to the generation that actually made the request;
+            // otherwise the next prime sees a false generation change and retries
+            // the same failed WHAM call immediately.
+            generation: attempted.credentialGeneration,
+            at: attempted.at,
+          });
+        }),
+      ]);
+    } catch {
+      // Priming is best-effort; never propagate.
+    }
+    if (process.env.OPENCODEX_DEBUG_QUOTA === "1") {
+      console.warn(`[codex-quota] prime done (reason=${reason}, pool=${pool.length}, refreshed=${stale.length})`);
+    }
+  })().finally(() => { primeInFlight = null; });
+  return primeInFlight;
+}
+
+/** Test-only: drop any in-flight prime pass so a leaked single-flight promise
+ * from another suite cannot coalesce into the next prime. */
+export function clearCodexQuotaPrimeState(): void {
+  primeInFlight = null;
+  poolQuotaPrimeAttemptedAt.clear();
+  getValidPoolTokenForPrime = getValidCodexToken;
+}
+
+/** Test-only: drop the shared single-flight promise while keeping the per-account
+ * failure backoff, so a test can trigger a second real prime pass and still observe
+ * the throttle a production caller would see. */
+export function clearCodexQuotaPrimeSingleFlightForTests(): void {
+  primeInFlight = null;
+}
+
+/** Test-only reset for the worker-level single-flight. */
+export function clearCodexCooldownRecoveryProbeState(): void {
+  cooldownRecoveryInFlight = null;
+}