@bitkyc08/opencodex 2.56.0 → 2.58.0

package/src/codex/model-entitlements.ts

@@ -1,15 +1,18 @@
 import { createHash } from "node:crypto";
 import { readBoundedResponseBody } from "../lib/bounded-body";
-import type { OcxConfig } from "../types";
+import type { CodexAccountCredentialRecord, OcxConfig } from "../types";
 import { isSelectableCodexPoolAccount } from "./account-id";
-import { getValidCodexToken, readCodexAccountRecord } from "./account-store";
+import { getValidCodexToken, loadCodexAccountRecordSnapshot } from "./account-store";
 import {
   getMainAccountToken,
   getValidMainAccountToken,
   MAIN_CODEX_ACCOUNT_ID,
   type NativeMainRefreshDependencies,
 } from "./main-account";
-import { ACCOUNT_GATED_NATIVE_OPENAI_MODELS } from "./catalog/native-models";
+import {
+  ACCOUNT_GATED_NATIVE_OPENAI_MODELS,
+  NATIVE_GPT6_ASTRA_MODEL,
+} from "./catalog/native-models";
 import { loadPersistedCodexRuntime } from "./runtime";
 import { codexRuntimeStateEpoch } from "./runtime";
 import upstreamModelsSnapshot from "./data/upstream-models.json";
@@ -520,17 +523,48 @@ function boundedCacheSet(accountId: string, value: CachedAccountModels): void {
   evictClass(accountId.startsWith(DIRECT_CALLER_ACCOUNT_PREFIX));
 }
 
+/**
+ * An identity resolver scoped to one caller's pass, reading each backing store at most once.
+ *
+ * The identity check itself is unchanged -- same prefix rule, same tombstone and missing-credential
+ * rejection, same `pool:<generation>:<chatgptAccountId>` shape -- but the READ is hoisted. Per-id
+ * resolution reloads and reparses the whole `codex-accounts.json` every call, so a loop over cache
+ * entries paid one full-store read per entry: the denial reader admits 64 accounts with four client
+ * versions each, which is up to 256 synchronous reads to score a single warm flagship request.
+ *
+ * Both stores are read lazily, so a pass that touches only Direct callers, or only native main,
+ * still opens nothing it does not need. Neither backing read is memoized across passes: a resolver
+ * lives for one synchronous loop, and that loop has no suspension point, so nothing this process
+ * does can change the file underneath it. A snapshot is therefore not staler than per-entry reads
+ * would have been -- it is strictly more coherent, because a foreign writer landing mid-loop can no
+ * longer give the earlier entries one generation and the later ones another.
+ */
+function credentialIdentityResolver(): (accountId: string) => string | undefined {
+  let records: Readonly<Record<string, CodexAccountCredentialRecord>> | undefined;
+  let mainRead = false;
+  let mainIdentity: string | undefined;
+  return (accountId: string): string | undefined => {
+    if (accountId.startsWith(DIRECT_CALLER_ACCOUNT_PREFIX)) {
+      return `direct:${accountId.slice(DIRECT_CALLER_ACCOUNT_PREFIX.length)}`;
+    }
+    if (accountId === MAIN_CODEX_ACCOUNT_ID) {
+      if (!mainRead) {
+        const token = getMainAccountToken();
+        mainIdentity = token ? `main:${token.chatgptAccountId}` : undefined;
+        mainRead = true;
+      }
+      return mainIdentity;
+    }
+    records ??= loadCodexAccountRecordSnapshot();
+    const record = records[accountId];
+    if (!record?.credential || record.deletedAt != null) return undefined;
+    return `pool:${record.generation}:${record.credential.chatgptAccountId}`;
+  };
+}
+
+/** Single-id resolution. Identical to one call through a fresh {@link credentialIdentityResolver}. */
 function currentCredentialIdentity(accountId: string): string | undefined {
-  if (accountId.startsWith(DIRECT_CALLER_ACCOUNT_PREFIX)) {
-    return `direct:${accountId.slice(DIRECT_CALLER_ACCOUNT_PREFIX.length)}`;
-  }
-  if (accountId === MAIN_CODEX_ACCOUNT_ID) {
-    const token = getMainAccountToken();
-    return token ? `main:${token.chatgptAccountId}` : undefined;
-  }
-  const record = readCodexAccountRecord(accountId);
-  if (!record?.credential || record.deletedAt != null) return undefined;
-  return `pool:${record.generation}:${record.credential.chatgptAccountId}`;
+  return credentialIdentityResolver()(accountId);
 }
 
 async function accountCredentialSnapshot(
@@ -926,8 +960,10 @@ export async function ensureCodexEntitlementFreshness(
     );
     const candidates = normalizedCandidateAccountIds(config);
     const mutationEpoch = codexCredentialMutationEpoch();
+    // Same hoist as the denial pass: this prologue is synchronous and reads once per candidate.
+    const identityOf = credentialIdentityResolver();
     const identityEntries = candidates.map(accountId => (
-      [accountId, currentCredentialIdentity(accountId) ?? null] as const
+      [accountId, identityOf(accountId) ?? null] as const
     ));
     const identityVector = new Map(identityEntries);
     const workset = candidates.filter(accountId => needsEntitlementRefresh(
@@ -980,8 +1016,9 @@ export function getCodexModelEntitlementStatus(
   clientVersion?: string | null,
 ): CodexModelEntitlementStatus {
   const version = resolveCodexEntitlementClientVersion(clientVersion);
+  const identityOf = credentialIdentityResolver();
   const accounts = candidateAccountIds(config).flatMap(accountId => {
-    const credentialIdentity = currentCredentialIdentity(accountId);
+    const credentialIdentity = identityOf(accountId);
     return credentialIdentity ? [{ accountId, credentialIdentity }] : [];
   });
   if (accounts.length === 0) return { status: "unavailable" };
@@ -1159,6 +1196,101 @@ export function availableAccountGatedNativeModels(
   )));
 }
 
+/**
+ * Native models that stay unconditionally VISIBLE while their per-account availability still
+ * varies.
+ *
+ * This is deliberately not `ACCOUNT_GATED_NATIVE_OPENAI_MODELS` and must never become it. That set
+ * fails closed on ABSENCE of evidence: membership hides the row from the catalog and refuses the
+ * request before dispatch, which is exactly what the owner decision of 2026-09-04 removed the
+ * flagships from. A timed-out fetch or a shard that has not caught up would make the model vanish
+ * from the picker, and "opencodex lost my model" is a worse failure than one upstream 400.
+ *
+ * This set carries the opposite polarity. It admits only a CONFIRMED DENIAL as evidence, and it
+ * feeds an ordering preference rather than a refusal, so absent or stale evidence changes nothing.
+ * That is the distinction #4768 asked for: a pool holding a Plus account and a Free account should
+ * stop handing Sol/Astra to the Free account whose own authenticated roster already says it cannot
+ * serve them, without gating the model on evidence that may never arrive.
+ */
+export const ENTITLEMENT_PREFERRED_NATIVE_OPENAI_MODELS: ReadonlySet<string> = new Set([
+  "gpt-5.6-sol",
+  "gpt-5.6-terra",
+  "gpt-5.6-luna",
+  NATIVE_GPT6_ASTRA_MODEL,
+]);
+
+/**
+ * Accounts whose OWN authenticated roster definitively omits `modelId`, read synchronously from
+ * evidence discovery has already gathered.
+ *
+ * Synchronous and cache-only by contract. The gated path may await `resolveCodexModelEntitlements`
+ * because a gated model is rare and already pays a bounded discovery call; the flagships are the
+ * most commonly requested models in the product, and putting an authenticated upstream fetch per
+ * account on that request path would trade one occasional 400 for latency on every turn. The cache
+ * this reads is warmed anyway: `modelsForCredential` stores each account's FULL roster, and
+ * background catalog sync (`src/codex/catalog/retained-sync.ts`) and convergence already resolve
+ * entitlements for every pool account.
+ *
+ * Returns `undefined` rather than an empty set when nothing is denied, so a caller cannot confuse
+ * "no account is denied" with "no evidence exists" — both mean the same thing here, which is that
+ * selection must be left exactly as it was.
+ *
+ * Only `denied` counts. `unknown` covers an unconfirmed account, a roster fetched under a client
+ * version too old to return the model, and an expired or credential-stale entry; none of those is
+ * proof that the account lacks the model, and treating them as proof is how 2.36.0 removed
+ * sol/terra/luna from accounts that owned them (#3022).
+ */
+export function cachedDeniedCodexAccountIdsForModel(
+  modelId: string | undefined,
+  now = Date.now(),
+  options: { excludeAccountIds?: ReadonlySet<string> } = {},
+): ReadonlySet<string> | undefined {
+  if (!modelId || !ENTITLEMENT_PREFERRED_NATIVE_OPENAI_MODELS.has(modelId)) return undefined;
+  const denied = new Set<string>();
+  const granted = new Set<string>();
+  // One resolver for the whole pass: the loop below runs once per cached (account, client version)
+  // entry, and resolving an identity per entry meant a full account-store read per entry.
+  const identityOf = credentialIdentityResolver();
+  for (const [key, entry] of accountModelsCache) {
+    const accountId = accountIdOfCacheKey(key);
+    // A forwarded Direct credential is one request's caller, never a pool candidate.
+    if (accountId.startsWith(DIRECT_CALLER_ACCOUNT_PREFIX)) continue;
+    // The caller's read fence, honoured BEFORE `identityOf` below, because that is the read: for
+    // native main it resolves the physical stored token. A request that is forbidden to read main
+    // -- a profile switch draining it, or a request-owned credential that owns no main state --
+    // must not reread account storage just to score an ordering preference. Dropping the account
+    // leaves it UNKNOWN rather than denied, which is the same outcome as having no cached roster
+    // for it and changes no selection. The resolver reads lazily for the same reason: an excluded
+    // account `continue`s here, so its store is never opened at all.
+    if (options.excludeAccountIds?.has(accountId)) continue;
+    if (entry.expiresAt <= now) continue;
+    // A credential we can currently read AND that differs is proof the entry answers for a
+    // different account than this id now names, so its denial is not evidence about the current
+    // one. An UNREADABLE credential is not proof of anything, and the same unknown-is-not-denied
+    // discipline that governs rosters governs identities: it leaves the entry in place rather
+    // than manufacturing a reason to ignore it.
+    const identity = identityOf(accountId);
+    if (identity !== undefined && identity !== entry.credentialIdentity) continue;
+    const state = codexModelEntitlementStateForRoster(
+      entry.models,
+      entry.confirmed,
+      entry.clientVersion,
+      modelId,
+    );
+    if (state === "granted") granted.add(accountId);
+    else if (state === "denied") denied.add(accountId);
+  }
+  // One account holds one entry per client version, and upstream filters the roster by that
+  // version. So the same account can legitimately carry a granted entry under a current client
+  // and a denied one under an older client that predates the model. Positive evidence is
+  // authoritative regardless of which version asked for it -- the same rule
+  // `codexModelEntitlementStateForRoster` applies within a single entry -- so a grant anywhere
+  // clears the denial rather than being outvoted by whichever entry the map happened to yield
+  // last.
+  for (const accountId of granted) denied.delete(accountId);
+  return denied.size > 0 ? denied : undefined;
+}
+
 /** Synchronous projection for management/catalog readers after a discovery pass. */
 export function cachedAvailableAccountGatedNativeModels(
   now = Date.now(),
@@ -1192,6 +1324,11 @@ export function cachedAvailableAccountGatedNativeModels(
 
 export function isCodexModelEntitlementSnapshotCurrent(snapshot: CodexModelEntitlementSnapshot): boolean {
   for (const [accountId, identity] of snapshot.credentialIdentities) {
+    // Deliberately per-id, unlike the passes above. This is a fail-closed publication gate asking
+    // whether a snapshot is STILL current, so the freshest possible answer per account is the
+    // point of the read. A pass-wide snapshot would be a coherence win everywhere else and a
+    // small weakening here: it could answer "current" for a later account from a record a
+    // concurrent reauth had already replaced.
     if (currentCredentialIdentity(accountId) !== identity) return false;
   }
   return true;

package/src/codex/native-profile-startup.ts

@@ -308,6 +308,47 @@ function observeOwner(entry: StartupEntry, owner: NativeMainOwnerSnapshot): void
  * Retain process ownership for one live server. The first reference acquires the
  * canonical-home SQLite lease and owns recovery; later same-process references share it.
  */
+/**
+ * Releases nobody is awaiting.
+ *
+ * A release closes the native-main owner's SQLite lease and its stable lock file, both of which
+ * live under CODEX_HOME. The normal shutdown path awaits it: `server.stop` goes through
+ * `releaseNativeMainStartupLifecycle`, which awaits the flight. The FAILED-start path does not —
+ * `startServer` must stay synchronous, so its rollback can only fire `void lifecycle.release()`
+ * and rethrow. Nothing could then wait for those handles to close, and on Windows an open handle
+ * does not delay an unlink, it refuses it outright with EPERM.
+ *
+ * That is invisible in production, where a failed start is followed by exit rather than by
+ * deleting the home. It is not invisible to a test whose cleanup removes the home it just used:
+ * `tests/server/server-management-auth.test.ts` binds a management ingress on the fixed port
+ * 10101, which nine other test files also use, so a collision on the six-shard Windows leg turns
+ * a passing start into the rollback path. The failure followed that collision across shards 1, 2
+ * and 3 while staying on the same file and line, which is what a shard-independent trigger looks
+ * like.
+ *
+ * Tracking the flight here rather than at the call site keeps `startServer` synchronous and
+ * unchanged, and gives anyone who needs the handles closed something to await.
+ */
+const pendingStartupReleases = new Set<Promise<void>>();
+
+function trackStartupRelease(release: Promise<void>): Promise<void> {
+  const tracked = release.finally(() => { pendingStartupReleases.delete(tracked); });
+  pendingStartupReleases.add(tracked);
+  return tracked;
+}
+
+/**
+ * Settle every native-main startup release still in flight, including ones nobody awaited.
+ *
+ * Loops rather than awaiting a single snapshot: a release can retire an owner whose own teardown
+ * starts another, and draining only the first batch would return with handles still open.
+ */
+export async function flushNativeMainStartupReleases(): Promise<void> {
+  while (pendingStartupReleases.size > 0) {
+    await Promise.allSettled([...pendingStartupReleases]);
+  }
+}
+
 export function startNativeMainStartupLifecycle(
   deps: NativeMainStartupGateDeps = {},
 ): NativeMainStartupLifecycle {
@@ -352,29 +393,32 @@ export function startNativeMainStartupLifecycle(
   }
   entry.refs += 1;
   let released = false;
+  const performRelease = async (): Promise<void> => {
+    if (released) return;
+    released = true;
+    entry!.refs = Math.max(0, entry!.refs - 1);
+    if (entry!.refs !== 0) return;
+    entry!.epoch += 1;
+    entry!.sweepStopping = true;
+    if (entry!.sweepTimer) clearTimeout(entry!.sweepTimer);
+    entry!.sweepTimer = undefined;
+    entry!.unsubscribe();
+    startupEntries.delete(homeId);
+    entry!.resolveAcquisition?.(snapshot);
+    entry!.resolveAcquisition = undefined;
+    // Startup convergence can transition from the exclusive recovery claim
+    // into a stage sweep. Keep the owner registered until that entire chain
+    // settles so no cleanup transaction starts untracked after owner detach.
+    await Promise.allSettled([entry!.settled]);
+    if (entry!.sweepInFlight) await Promise.allSettled([entry!.sweepInFlight]);
+    await entry!.owner.release();
+  };
   return {
     homeId,
     get settled() { return entry!.settled; },
-    async release() {
-      if (released) return;
-      released = true;
-      entry!.refs = Math.max(0, entry!.refs - 1);
-      if (entry!.refs !== 0) return;
-      entry!.epoch += 1;
-      entry!.sweepStopping = true;
-      if (entry!.sweepTimer) clearTimeout(entry!.sweepTimer);
-      entry!.sweepTimer = undefined;
-      entry!.unsubscribe();
-      startupEntries.delete(homeId);
-      entry!.resolveAcquisition?.(snapshot);
-      entry!.resolveAcquisition = undefined;
-      // Startup convergence can transition from the exclusive recovery claim
-      // into a stage sweep. Keep the owner registered until that entire chain
-      // settles so no cleanup transaction starts untracked after owner detach.
-      await Promise.allSettled([entry!.settled]);
-      if (entry!.sweepInFlight) await Promise.allSettled([entry!.sweepInFlight]);
-      await entry!.owner.release();
-    },
+    // Tracked so a caller that cannot await -- the synchronous rollback in `startServer` -- still
+    // leaves the flight drainable through `flushNativeMainStartupReleases`.
+    release: () => trackStartupRelease(performRelease()),
   };
 }
 

package/src/codex/pool-refresh-backoff.ts

@@ -43,6 +43,12 @@ const backoffByAccount = new Map<string, RefreshFailureBackoff>();
  * must not re-quarantine the credential that replaced it.
  */
 const fenceByAccount = new Map<string, number>();
+/**
+ * Invalidates every account fence without having to know which refresh flights are currently in
+ * progress. A bulk routing-state reset can race a first failure for an account that has no map
+ * entry yet, so iterating either map cannot close this boundary.
+ */
+let globalFence = 0;
 let nowOverride: number | undefined;
 
 export function setCodexPoolRefreshFailureNowForTests(now?: number): void {
@@ -52,12 +58,13 @@ export function setCodexPoolRefreshFailureNowForTests(now?: number): void {
 export function resetCodexPoolRefreshFailureBackoffForTests(): void {
   backoffByAccount.clear();
   fenceByAccount.clear();
+  globalFence = 0;
   nowOverride = undefined;
 }
 
 /** The value a refresh flight captures before it starts, to be handed back on failure. */
-export function codexPoolRefreshFence(accountId: string): number {
-  return fenceByAccount.get(accountId) ?? 0;
+export function codexPoolRefreshFence(accountId: string): string {
+  return `${globalFence}:${fenceByAccount.get(accountId) ?? 0}`;
 }
 
 export function clearCodexPoolRefreshFailure(accountId: string): void {
@@ -72,6 +79,8 @@ export function clearCodexPoolRefreshFailure(accountId: string): void {
  */
 export function clearAllCodexPoolRefreshFailures(): void {
   backoffByAccount.clear();
+  fenceByAccount.clear();
+  globalFence += 1;
 }
 
 function currentNow(now?: number): number {
@@ -115,7 +124,7 @@ export function noteCodexPoolRefreshFailure(
   accountId: string,
   reason: string,
   now = currentNow(),
-  fence?: number,
+  fence?: string,
 ): { consecutiveFailures: number; cooldownUntil: number; openedWindow: boolean } {
   const existing = backoffByAccount.get(accountId);
   // A flight that started before the account's failures were cleared is speaking for a grant

package/src/codex/quota-rejection.ts

@@ -8,8 +8,41 @@ const RESET_ELIGIBLE_CODE_VALUES = [
 export type CodexResetEligibleExhaustionCode =
   (typeof RESET_ELIGIBLE_CODE_VALUES)[number];
 
+/**
+ * Upstream codes that name an ORGANIZATION- or PROJECT-scoped exhaustion (#4546).
+ *
+ * These are a different animal from the reset-eligible codes above, and the difference is the
+ * whole point. `usage_limit_exceeded` describes the account that was asked; another pool account
+ * carries its own plan allowance, so rotating to it is a real move. Every code here describes a
+ * limit the CREDENTIAL does not own -- a balance, a spend cap, or a usage cap held by the
+ * organization or project the credential belongs to. Two credentials inside that organization
+ * are refused by the same counter, so rotating between them pays a cold prompt prefix for zero
+ * new capacity, which is the send amplification this unit exists to stop.
+ *
+ * openai/codex reached the same classification from the client side: #44492 maps exactly these
+ * HTTP 429 codes to a terminal `QuotaExceeded` instead of a retry-limit failure, and #45602
+ * extends it to the SSE path while deliberately KEEPING `rate_limit_exceeded` and `slow_down`
+ * retryable. The platform documentation states the same rule for the whole class: "It does not
+ * mean that quota, billing, or other errors that require user action can be resolved by
+ * retrying."
+ *
+ * Membership here says nothing about reset credits. A reset credit reconciles a ChatGPT plan
+ * window; it cannot pay an organization's bill, so these codes are deliberately absent from
+ * {@link RESET_ELIGIBLE_CODE_VALUES} and never set `resetCreditEligible`.
+ */
+const SCOPED_EXHAUSTION_CODE_VALUES = [
+  "credit_balance_exhausted",
+  "organization_spend_limit_exceeded",
+  "project_spend_limit_exceeded",
+  "organization_usage_limit_exceeded",
+] as const;
+
+export type CodexScopedExhaustionCode =
+  (typeof SCOPED_EXHAUSTION_CODE_VALUES)[number];
+
 export type CodexPreStreamRejectionKind =
   | "reset-eligible-exhaustion"
+  | "scoped-quota-exhaustion"
   | "generic-rate-limit"
   | "unverified-billing-or-quota"
   | "transient-server-error"
@@ -23,6 +56,12 @@ export interface CodexPreStreamRejection {
   alternateRetryEligible: boolean;
   resetCreditEligible: boolean;
   semanticCode?: CodexResetEligibleExhaustionCode;
+  /**
+   * The organization- or project-scoped exhaustion code the upstream body named, when it named
+   * one. Never accompanied by `semanticCode`: the two sets are disjoint, and only `semanticCode`
+   * may authorize a reset credit.
+   */
+  scopedExhaustionCode?: CodexScopedExhaustionCode;
   /**
    * Structured denial evidence for a 403. Present only when the upstream body names a
    * workspace/entitlement denial, which proves the CREDENTIAL is valid and the account
@@ -97,6 +136,7 @@ function structuredDenialCode(payload: unknown): string | undefined {
 }
 
 const RESET_ELIGIBLE_CODES: ReadonlySet<string> = new Set(RESET_ELIGIBLE_CODE_VALUES);
+const SCOPED_EXHAUSTION_CODES: ReadonlySet<string> = new Set(SCOPED_EXHAUSTION_CODE_VALUES);
 
 const TRANSIENT_SERVER_STATUSES = new Set([500, 502, 503, 504, 520, 521, 522]);
 const JSON_NUMBER_PATTERN = /-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?/y;
@@ -107,6 +147,7 @@ function rejection(
   options: {
     alternateRetryEligible?: boolean;
     semanticCode?: CodexResetEligibleExhaustionCode;
+    scopedExhaustionCode?: CodexScopedExhaustionCode;
   } = {},
 ): CodexPreStreamRejection {
   return {
@@ -115,6 +156,7 @@ function rejection(
     alternateRetryEligible: options.alternateRetryEligible === true,
     resetCreditEligible: options.semanticCode !== undefined,
     ...(options.semanticCode ? { semanticCode: options.semanticCode } : {}),
+    ...(options.scopedExhaustionCode ? { scopedExhaustionCode: options.scopedExhaustionCode } : {}),
   };
 }
 
@@ -210,9 +252,19 @@ function isUnsafeJsonDocument(text: string): boolean {
   }
 }
 
-function exactResetEligibleCode(
+/**
+ * Read the one exact, unambiguous code a container declares, and only if it is in `allowed`.
+ *
+ * Generic over the allowed set so the reset-eligible and organization-scoped classifications
+ * share one parser. They must: the strictness here -- a `code`/`type` pair that disagrees is
+ * rejected rather than resolved, and no trimming or case folding is applied -- is what keeps a
+ * near-miss from being read as an exact upstream code, and a second hand-written copy would
+ * drift away from that.
+ */
+function exactAllowedCode(
   container: Record<string, unknown>,
-): CodexResetEligibleExhaustionCode | undefined {
+  allowed: ReadonlySet<string>,
+): string | undefined {
   const hasCode = hasOwnField(container, "code");
   const hasType = hasOwnField(container, "type");
   if (!hasCode && !hasType) return undefined;
@@ -226,49 +278,80 @@ function exactResetEligibleCode(
 
   const value = hasCode ? code : type;
   if (typeof value !== "string") return undefined;
-  return RESET_ELIGIBLE_CODES.has(value as CodexResetEligibleExhaustionCode)
-    ? value as CodexResetEligibleExhaustionCode
-    : undefined;
+  return allowed.has(value) ? value : undefined;
 }
 
-function structuredResetEligibleCode(payload: unknown): CodexResetEligibleExhaustionCode | undefined {
+function structuredAllowedCode(payload: unknown, allowed: ReadonlySet<string>): string | undefined {
   if (!payload || typeof payload !== "object" || Array.isArray(payload)) return undefined;
   const root = payload as Record<string, unknown>;
   const hasRootDiscriminator = hasOwnField(root, "code") || hasOwnField(root, "type");
 
-  if (!hasOwnField(root, "error")) return exactResetEligibleCode(root);
+  if (!hasOwnField(root, "error")) return exactAllowedCode(root, allowed);
   if (hasRootDiscriminator) return undefined;
 
   const nested = root.error;
   if (!nested || typeof nested !== "object" || Array.isArray(nested)) return undefined;
-  return exactResetEligibleCode(nested as Record<string, unknown>);
+  return exactAllowedCode(nested as Record<string, unknown>, allowed);
 }
 
-async function resetEligibleCodeFromResponse(
+/**
+ * Parse one bounded body and classify its structured code against both sets at once.
+ *
+ * One read, because the caller holds a `Response` whose body may only be consumed once per
+ * clone and the two questions are asked about the same bytes.
+ */
+async function exhaustionCodeFromResponse(
   response: Response,
   signal?: AbortSignal,
-): Promise<CodexResetEligibleExhaustionCode | undefined> {
+): Promise<{
+  resetEligible?: CodexResetEligibleExhaustionCode;
+  scoped?: CodexScopedExhaustionCode;
+}> {
   try {
     const body = await readBoundedResponseBody(response.clone(), { signal, fatalUtf8: true });
-    if (!body.displaySafe || body.truncated || !body.text.trim()) return undefined;
+    if (!body.displaySafe || body.truncated || !body.text.trim()) return {};
     const payload = JSON.parse(body.text) as unknown;
     // JSON.parse silently keeps the last duplicate key, making contradictory
     // payloads order-dependent. Reject any duplicate at any object depth.
-    if (isUnsafeJsonDocument(body.text)) return undefined;
-    return structuredResetEligibleCode(payload);
+    if (isUnsafeJsonDocument(body.text)) return {};
+    const resetEligible = structuredAllowedCode(payload, RESET_ELIGIBLE_CODES);
+    if (resetEligible !== undefined) {
+      return { resetEligible: resetEligible as CodexResetEligibleExhaustionCode };
+    }
+    const scoped = structuredAllowedCode(payload, SCOPED_EXHAUSTION_CODES);
+    return scoped === undefined ? {} : { scoped: scoped as CodexScopedExhaustionCode };
   } catch {
     // Classification must fail closed. A malformed, oversized, consumed, or
     // cancelled body cannot authorize an irreversible reset-credit operation.
-    return undefined;
+    return {};
   }
 }
 
+/**
+ * The organization- or project-scoped exhaustion code this rejection names, if any.
+ *
+ * Exported for the account-rotation gate, which has to answer "may another pool account serve
+ * this?" before it has any reason to build a full classification. Fails closed to `undefined`:
+ * an unreadable, truncated, duplicate-keyed or aborted body leaves the caller's existing
+ * behaviour untouched, so only positive evidence can ever withhold a rotation.
+ */
+export async function codexScopedExhaustionCode(
+  response: Response,
+  options: { signal?: AbortSignal } = {},
+): Promise<CodexScopedExhaustionCode | undefined> {
+  return (await exhaustionCodeFromResponse(response, options.signal)).scoped;
+}
+
 /**
  * Classify an upstream Codex rejection before any response event is exposed.
  *
  * Only an exact structured exhaustion code on HTTP 429/402 is reset-eligible.
  * Status alone and message text are intentionally insufficient. The broad
  * alternate-account retry remains eligible for 429/402 to preserve #584.
+ *
+ * The one carve-out from that breadth is an organization- or project-scoped exhaustion
+ * ({@link SCOPED_EXHAUSTION_CODE_VALUES}), which reports `alternateRetryEligible: false`
+ * because every credential inside the refusing limit would be refused by the same counter.
  */
 export async function classifyCodexPreStreamRejection(
   response: Response,
@@ -283,13 +366,19 @@ export async function classifyCodexPreStreamRejection(
   if (TRANSIENT_SERVER_STATUSES.has(status)) return rejection(status, "transient-server-error");
   if (status !== 429 && status !== 402) return rejection(status, "other");
 
-  const semanticCode = await resetEligibleCodeFromResponse(response, options.signal);
+  const { resetEligible: semanticCode, scoped } = await exhaustionCodeFromResponse(
+    response,
+    options.signal,
+  );
   if (semanticCode) {
     return rejection(status, "reset-eligible-exhaustion", {
       alternateRetryEligible: true,
       semanticCode,
     });
   }
+  if (scoped) {
+    return rejection(status, "scoped-quota-exhaustion", { scopedExhaustionCode: scoped });
+  }
   return rejection(
     status,
     status === 429 ? "generic-rate-limit" : "unverified-billing-or-quota",

package/src/codex/routing/cache-affinity.ts

@@ -0,0 +1,70 @@
+import type { OcxConfig } from "../../types";
+import type { CodexAccountUsabilityOptions } from "../account-usability";
+import { isCodexAccountUsable } from "../account-usability";
+import { isCacheAffinityEnabled, isUnknownUsage } from "./selection";
+
+/**
+ * Does a healthy bound account keep its conversation when quota re-evaluation looks at it?
+ *
+ * Two independent reasons say yes, and they are not the same claim. `pool.cacheAffinity` is an
+ * operator preference about COST: provider prompt caches are account-isolated, so handing a bound
+ * conversation from account to account re-sends the whole prefix, and #4546 measured 7k-token
+ * turns becoming 150k-token ones. Setting it false restores capacity-first routing, and an
+ * operator who wants that keeps it.
+ *
+ * Uploaded-file retention is a claim about CORRECTNESS, so it does not take that instruction
+ * (#4778). Uploaded files are scoped to the account that issued them. Moving a conversation that
+ * carries live `file_id` references does not cost a cold prefix -- it orphans the reference, and
+ * because the reference stays in conversation history EVERY later turn is refused with
+ * `409 account_change_file_scope` until the user re-uploads under the serving account or starts
+ * over. That is a dead conversation rather than an expensive one, and `pool.cacheAffinity: false`
+ * was never asking to accept it: the flag trades cache locality for capacity, not correctness for
+ * capacity.
+ *
+ * This answers the VOLUNTARY move only. Its caller still releases the binding on genuine
+ * exhaustion or an unusable account, and every involuntary release that runs earlier in
+ * `resolveCodexAccountForThreadDetailed` -- quota refusal, failover streak, pause, cooldown, lost
+ * generation, affinity expiry -- never reaches here at all. So retention can never wedge a
+ * conversation on an account that cannot serve it, which is exactly why the #4710 refusal remains
+ * required: this makes that refusal rarer and does not replace it.
+ *
+ * It lives beside selection rather than inside `routing.ts` because it is a policy question two
+ * call sites ask -- the live path in `reevaluateAffinityQuota` and the side-effect-free
+ * `previewReusableAffinityAccount` that subagent fallback reads -- and those two must answer
+ * identically or preview hands fallback a different account than the request uses.
+ */
+export function retainsBoundAccountForQuota(
+  config: OcxConfig,
+  selectionOptions?: CodexAccountUsabilityOptions,
+): boolean {
+  return isCacheAffinityEnabled(config)
+    || selectionOptions?.retainAccountForUploadedFiles === true;
+}
+
+/**
+ * May a LIVE binding be moved for quota reasons?
+ *
+ * Default: no. The bar is genuine exhaustion, because moving a bound conversation discards the
+ * prompt cache warmed on its account and a threshold crossing is a hint that the account is
+ * getting busy rather than evidence it cannot serve (#4546). Deliberately NOT
+ * `hasCodexQuotaHeadroom`, which reads `usage < autoSwitchThreshold` and would reproduce the old
+ * rule under a new name.
+ *
+ * When nothing retains, the historical rule comes back: a crossing of `autoSwitchThreshold` is
+ * enough. That is capacity-first routing, and an operator who asks for it keeps it -- it is just
+ * not what an install gets by never having heard of the flag.
+ */
+export function mayRebindAffinityForQuota(
+  config: OcxConfig,
+  accountId: string,
+  usage: number,
+  threshold: number,
+  selectionOptions?: CodexAccountUsabilityOptions,
+): boolean {
+  const overThreshold = threshold > 0 && !isUnknownUsage(usage) && usage >= threshold;
+  if (!retainsBoundAccountForQuota(config, selectionOptions)) return overThreshold;
+  // The usable half is already guaranteed by both callers, which gate on
+  // isCodexAccountSelectable; kept explicit so the predicate reads correctly on its own.
+  return !isCodexAccountUsable(config, accountId, selectionOptions)
+    || (!isUnknownUsage(usage) && usage >= 100);
+}