@bitkyc08/opencodex 2.55.0 → 2.57.0

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

@@ -0,0 +1,161 @@
+
+/**
+ * Per-account cooldown for a stored Codex pool credential whose forced refresh
+ * failed without proving the grant is dead.
+ *
+ * A token-endpoint 5xx, a generation CAS loss, or a network blip is transient
+ * (#2887): it must not quarantine the account or drop its binding. Retrying the
+ * same doomed refresh on every request, though, is how a single unhealthy
+ * account pinned the pool at 503 while healthy siblings sat idle. Consecutive
+ * non-terminal failures open a bounded growing cooldown; during that window no
+ * new forced refresh starts, and selection prefers a sibling. The first
+ * successful refresh clears it.
+ */
+
+import { fallbackCodexAccountLogLabel } from "./account-label";
+
+export const CODEX_POOL_REFRESH_INCOMPLETE_LOG_REASON = "codex_pool_refresh_incomplete";
+
+/** Growing delays between forced-refresh attempts for one account. */
+export const CODEX_POOL_REFRESH_FAILURE_BACKOFF_MS = [2_000, 5_000, 15_000, 30_000, 60_000] as const;
+
+export class CodexPoolRefreshCooldownError extends Error {
+  readonly retryable = true;
+  readonly code = "CODEX_REFRESH_COOLING";
+
+  constructor(message = "Codex credential refresh is cooling down") {
+    super(message);
+    this.name = "CodexPoolRefreshCooldownError";
+  }
+}
+
+type RefreshFailureBackoff = {
+  consecutiveFailures: number;
+  cooldownUntil: number;
+  reason: string;
+};
+
+const backoffByAccount = new Map<string, RefreshFailureBackoff>();
+/**
+ * Bumped whenever an account's failures are cleared because something proved them obsolete — a
+ * successful refresh, or a replacement credential written by login/reauth. A refresh flight that
+ * started before that moment is reporting on a grant that no longer exists, and its late failure
+ * 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 {
+  nowOverride = now;
+}
+
+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): string {
+  return `${globalFence}:${fenceByAccount.get(accountId) ?? 0}`;
+}
+
+export function clearCodexPoolRefreshFailure(accountId: string): void {
+  backoffByAccount.delete(accountId);
+  fenceByAccount.set(accountId, (fenceByAccount.get(accountId) ?? 0) + 1);
+}
+
+/**
+ * Drop every remembered failure. Called when the routing layer discards its per-account state,
+ * because a cooldown outliving the binding it was learned alongside would keep an account out of
+ * selection for a roster the operator has already replaced.
+ */
+export function clearAllCodexPoolRefreshFailures(): void {
+  backoffByAccount.clear();
+  fenceByAccount.clear();
+  globalFence += 1;
+}
+
+function currentNow(now?: number): number {
+  return now ?? nowOverride ?? Date.now();
+}
+
+function delayFor(consecutiveFailures: number): number {
+  const index = Math.min(Math.max(consecutiveFailures, 1), CODEX_POOL_REFRESH_FAILURE_BACKOFF_MS.length) - 1;
+  return CODEX_POOL_REFRESH_FAILURE_BACKOFF_MS[index]!;
+}
+
+/**
+ * How many consecutive non-terminal failures must land before a refresh is WITHHELD.
+ *
+ * Withholding on the first failure was wrong twice over. A single token-endpoint blip is the
+ * ordinary case that the very next attempt clears, and -- worse -- a withheld refresh never runs,
+ * so an account whose grant is actually revoked can no longer discover that: the terminal 401 it
+ * owes the operator turns into a retryable 503 that never resolves. The cooldown exists for the
+ * account that keeps failing, not for the one that failed once.
+ */
+export const CODEX_POOL_REFRESH_COOLDOWN_AFTER_FAILURES = 3;
+
+export function getCodexPoolRefreshCooldownUntil(accountId: string, now = currentNow()): number | null {
+  const entry = backoffByAccount.get(accountId);
+  if (!entry) return null;
+  if (entry.consecutiveFailures < CODEX_POOL_REFRESH_COOLDOWN_AFTER_FAILURES) return null;
+  return entry.cooldownUntil > now ? entry.cooldownUntil : null;
+}
+
+export function isCodexPoolRefreshCooling(accountId: string, now = currentNow()): boolean {
+  return getCodexPoolRefreshCooldownUntil(accountId, now) !== null;
+}
+
+/**
+ * Record a non-terminal forced-refresh failure. Already-cooling accounts do not
+ * grow the window: growth requires another real attempt after the previous one
+ * expired. Logs the classified reason once per account per window, with the
+ * durable hash label — never a token and never an email.
+ */
+export function noteCodexPoolRefreshFailure(
+  accountId: string,
+  reason: string,
+  now = currentNow(),
+  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
+  // that has since been replaced or proven healthy. Recording it would put the new credential
+  // back in the quarantine its predecessor earned.
+  if (fence !== undefined && fence !== codexPoolRefreshFence(accountId)) {
+    return {
+      consecutiveFailures: existing?.consecutiveFailures ?? 0,
+      cooldownUntil: existing?.cooldownUntil ?? 0,
+      openedWindow: false,
+    };
+  }
+  // The "do not grow inside an open window" rule applies only once the window is actually
+  // WITHHOLDING. Below the threshold no refresh is being withheld, so every failure is a real
+  // attempt that really failed and must count -- otherwise a client retrying the 503 once a
+  // second can never reach the threshold the cooldown is meant to protect against.
+  const withholding = existing !== undefined
+    && existing.consecutiveFailures >= CODEX_POOL_REFRESH_COOLDOWN_AFTER_FAILURES;
+  if (existing && withholding && existing.cooldownUntil > now) {
+    return {
+      consecutiveFailures: existing.consecutiveFailures,
+      cooldownUntil: existing.cooldownUntil,
+      openedWindow: false,
+    };
+  }
+  const consecutiveFailures = (existing?.consecutiveFailures ?? 0) + 1;
+  const cooldownUntil = now + delayFor(consecutiveFailures);
+  backoffByAccount.set(accountId, { consecutiveFailures, cooldownUntil, reason });
+  const label = fallbackCodexAccountLogLabel(accountId);
+  console.warn(
+    `[codex-auth] Codex pool account ${label} credential refresh failed (${reason})`,
+  );
+  return { consecutiveFailures, cooldownUntil, openedWindow: true };
+}

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/active-account.ts

@@ -0,0 +1,194 @@
+import { saveConfigPreservingClaudeCode } from "../../config";
+import { clearCodexAccountPin, pinnedCodexAccountId } from "../account-priority";
+import {
+  POOL_KEY_CODEX,
+  normalizeCodexAccountPoolStrategy,
+  seedPoolRotationAccount,
+} from "../pool-rotation";
+import type { OcxConfig } from "../../types";
+import { clearThreadAccountMap } from "./thread-affinity";
+import {
+  NATIVE_MODEL_QUOTA_SCOPES,
+  codexPoolKeyForScope,
+  deleteAccountHealth,
+  deleteScopedHealth,
+  getAccountHealth,
+  isIndependentCodexQuotaScope,
+  listScopedHealthEntries,
+  preservedCooldownFields,
+  setAccountHealth,
+  setScopedHealth,
+  type CodexUpstreamHealth,
+} from "./health-store";
+
+/**
+ * Process-local cursor for automatic RR/fill-first (and quota-429 when not
+ * sync-writing) picks. Keeps unrelated `saveConfig` from persisting transient
+ * rotation as the operator's `activeCodexAccountId`. Manual selection clears it
+ * so disk/`config.activeCodexAccountId` remains authoritative.
+ */
+let runtimeActiveCodexAccountId: string | undefined;
+
+/** Manual selection resets transient routing evidence without bypassing a real 429 cooldown. */
+export function resetCodexRoutingForManualSelection(accountId: string): void {
+  clearThreadAccountMap();
+  // Manual selection is the operator source of truth — drop any automatic runtime cursor.
+  runtimeActiveCodexAccountId = undefined;
+  // Record the pick as an unspent one-shot on the SHARED scope only. An independent scope
+  // gets no entry on purpose: every write site the guard protects is already skipped for
+  // independent scopes, so an entry there would be state nothing reads — and state nothing
+  // reads is what the next reader mistakes for a rule.
+  //
+  // Seeding happens ONLY here. A pool-driven promote must never create or move a preference,
+  // or the pool would manufacture an operator intent nobody expressed.
+  manualPreference.set(POOL_KEY_CODEX, accountId);
+  // Seed the RR ring so the next unbound new session honors the manually selected account
+  // under round-robin (affinity-cleared threads / null threadId). Fill-first already follows
+  // config.activeCodexAccountId, which the caller persists before invoking this.
+  seedPoolRotationAccount(POOL_KEY_CODEX, accountId);
+  for (const scope of new Set(Object.values(NATIVE_MODEL_QUOTA_SCOPES))) {
+    if (isIndependentCodexQuotaScope(scope)) {
+      seedPoolRotationAccount(codexPoolKeyForScope(scope), accountId);
+    }
+  }
+  // Quota avoidance is a preference, like the soft avoid dropped above, and an operator naming
+  // this account has overruled it. The hard cooldown is the part that survives.
+  const overrule = (health: CodexUpstreamHealth) => {
+    const { quotaAvoidUntil: _avoid, ...retained } = preservedCooldownFields(health);
+    return retained;
+  };
+  const current = getAccountHealth(accountId);
+  if (current) {
+    const retained = overrule(current);
+    if (Object.keys(retained).length === 0) deleteAccountHealth(accountId);
+    else setAccountHealth(accountId, { consecutiveFailures: 0, ...retained });
+  }
+  // A reset-derived refusal records its avoidance on the SCOPED map and returns before the
+  // account-wide entry is written, so naming the account has to reach that map too. Stopping
+  // at `upstreamHealth` — and returning early when it holds nothing — overruled nothing in
+  // the case that produces the avoidance this function exists to overrule.
+  for (const [scope, health] of [...(listScopedHealthEntries(accountId))]) {
+    const retained = overrule(health);
+    if (Object.keys(retained).length === 0) deleteScopedHealth(accountId, scope);
+    else setScopedHealth(accountId, scope, { consecutiveFailures: 0, ...retained });
+  }
+}
+
+/** Effective active: automatic runtime cursor, else operator/persisted selection. */
+/**
+ * Unspent operator selections, keyed by pool scope.
+ *
+ * Codex has no account-side equivalent of the Anthropic `selectionRevision`, so staleness
+ * cannot be detected by comparing values: a pool-driven promote legitimately moves the
+ * persisted active account, and reading that as staleness would silently spend the
+ * operator's one-shot. Invalidation is keyed to the OPERATOR path instead — another manual
+ * selection, the account leaving the pool, or a successful dispatch on it.
+ */
+const manualPreference = new Map<string, string>();
+
+/**
+ * Spend the one-shot for a pool scope once a dispatch on that account actually succeeded.
+ * This is the Codex analogue of `commitAnthropicSelectionRouting`, which Codex lacks.
+ *
+ * Wiring this BEFORE the guard below is not a style choice. Measured: with the guard in
+ * place and no consume site, the first manual selection freezes the automatic cursor
+ * permanently and 15 of 69 rotation tests fail.
+ */
+export function consumeManualPreference(accountId: string, poolKey: string): void {
+  if (manualPreference.get(poolKey) === accountId) manualPreference.delete(poolKey);
+}
+
+/**
+ * Drop an account's preference in every scope. Pause and exclusion do not route through
+ * `resetCodexRoutingForManualSelection`, so without this a preference could outlive the
+ * account it names and keep suppressing the automatic cursor.
+ */
+export function forgetManualPreference(accountId: string): void {
+  for (const [poolKey, preferred] of manualPreference) {
+    if (preferred === accountId) manualPreference.delete(poolKey);
+  }
+}
+
+/**
+ * True while an unspent operator selection for this scope names a DIFFERENT account than
+ * the automatic pick about to be recorded.
+ *
+ * Callers pass their own scope: an independent quota scope keeps its own entry and must
+ * never read the shared one. The failover promote does NOT consult this — see its call
+ * site for why.
+ */
+export function manualPreferenceBlocks(poolKey: string, accountId: string): boolean {
+  const preferred = manualPreference.get(poolKey);
+  return preferred !== undefined && preferred !== accountId;
+}
+
+export function getEffectiveActiveCodexAccountId(config: OcxConfig): string | undefined {
+  return runtimeActiveCodexAccountId ?? config.activeCodexAccountId;
+}
+
+/**
+ * Whether the account routing is currently on is there because an operator asked
+ * for it, rather than because a strategy landed on it. Surfaces read this instead
+ * of comparing the stored pin themselves, which would report a pin that a later
+ * automatic pick has already moved past.
+ */
+export function isEffectiveCodexAccountPinned(config: OcxConfig): boolean {
+  const pinned = pinnedCodexAccountId(config);
+  return pinned !== undefined && pinned === getEffectiveActiveCodexAccountId(config);
+}
+
+/**
+ * Automatic strategy / failover cursor only — never mutates `config.activeCodexAccountId`
+ * so an unrelated `saveConfig` cannot persist transient rotation as operator selection.
+ */
+export function rememberActiveCodexAccount(_config: OcxConfig, accountId: string): void {
+  runtimeActiveCodexAccountId = accountId;
+}
+
+/**
+ * End the manual pin when routing moves to a different account. Returns whether
+ * the pin changed so the caller can fold it into a write it was already making.
+ */
+function releaseCodexAccountPinFor(config: OcxConfig, accountId: string): boolean {
+  const pinned = pinnedCodexAccountId(config);
+  if (pinned === undefined || pinned === accountId) return false;
+  clearCodexAccountPin(config);
+  return true;
+}
+
+/** Persist operator (or quota-strategy) active selection to config + disk. */
+export function setActiveCodexAccount(config: OcxConfig, accountId: string): void {
+  runtimeActiveCodexAccountId = undefined;
+  const releasedPin = releaseCodexAccountPinFor(config, accountId);
+  if (config.activeCodexAccountId === accountId && !releasedPin) return;
+  config.activeCodexAccountId = accountId;
+  saveConfigPreservingClaudeCode(config);
+}
+
+/** Quota strategy persists; RR/fill-first keep a process-local cursor only. */
+export function promoteActiveCodexAccount(config: OcxConfig, accountId: string): void {
+  if (normalizeCodexAccountPoolStrategy(config.accountPoolStrategy) === "quota") {
+    setActiveCodexAccount(config, accountId);
+    return;
+  }
+  // Runtime-only, like the cursor itself: a caller that persists (pause, delete)
+  // saves this release with its own write; a transient failover does not, so the
+  // pin survives a restart that also clears the failure history behind it.
+  releaseCodexAccountPinFor(config, accountId);
+  rememberActiveCodexAccount(config, accountId);
+}
+
+export function clearAllManualPreferences(): void {
+  manualPreference.clear();
+}
+
+export function forgetRuntimeActiveCodexAccount(): void {
+  runtimeActiveCodexAccountId = undefined;
+}
+
+export function forgetRoutingPreferencesOutside(codexAccountIds: ReadonlySet<string>): void {
+  for (const [poolKey, preferred] of manualPreference) {
+    if (codexAccountIds.has(preferred)) continue;
+    manualPreference.delete(poolKey);
+  }
+}

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);
+}