@iislee/opencodex 2.11.0

package/src/codex/routing.ts

@@ -0,0 +1,1477 @@
+import { randomUUID } from "node:crypto";
+import { saveConfigPreservingClaudeCode } from "../config";
+import { isCodexAccountGenerationLive, readCodexAccountRecord } from "./account-store";
+import { codexAccountLogLabel } from "./account-label";
+import { isCodexAccountPaused } from "./account-pause";
+import { isCodexAccountUsable } from "./account-usability";
+import { isAccountNeedsReauth, markAccountNeedsReauth } from "./account-runtime-state";
+import {
+  POOL_KEY_CODEX,
+  normalizeAccountPoolStickyLimit,
+  normalizeAccountPoolStrategy,
+  notePoolRotationFailure,
+  notePoolRotationSuccess,
+  peekRoundRobinAccount,
+  pickRoundRobinAccount,
+  seedPoolRotationAccount,
+} from "./pool-rotation";
+import { CODEX_UNKNOWN_USAGE_SCORE, getAccountQuota } from "./quota";
+import { MAIN_CODEX_ACCOUNT_ID, getMainAccountPlan } from "./main-account";
+import { isSelectableCodexPoolAccount } from "./account-id";
+import type { OcxConfig } from "../types";
+import { captureConfigGeneration, type GenerationContext } from "../lib/state-store-sweeper";
+import { isCanonicalOpenAiForwardProvider } from "../providers/openai-tiers";
+import { retainedUtf8Bytes } from "../lib/admission";
+
+type ThreadAffinityEntry = {
+  accountId: string;
+  generation: number;
+  createdAt: number;
+  lastUsedAt: number;
+  // Last time the bound account's quota threshold was re-evaluated for this
+  // thread (interval-gated to avoid per-request flapping). See REEVAL_INTERVAL_MS.
+  lastReevalAt: number;
+};
+
+export type CodexThreadResolution =
+  | { status: "selected"; accountId: string }
+  | { status: "none" }
+  | { status: "expired"; accountId: string };
+
+/**
+ * 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;
+
+type CodexUpstreamHealth = {
+  consecutiveFailures: number;
+  /** Consecutive healthy terminals observed while recovering from escalation level 2+. */
+  consecutiveSuccesses?: number;
+  lastFailureStatus?: number;
+  lastFailureAt?: number;
+  /** Hard cooldown (quota 429). Survives a later 2xx; blocks auth + selection. */
+  cooldownUntil?: number;
+  /** When the current cooldown was recorded; origin of the probe interval clock. */
+  cooldownSince?: number;
+  /**
+   * What produced the cooldown. An explicit Retry-After is a literal retry
+   * directive and is never probed; a quota resetAt only announces a window
+   * refresh, so it may be probed early (#433).
+   */
+  cooldownSource?: CodexCooldownSource;
+  /**
+   * Bumped on every cooldown write. A probe lease records the generation it was
+   * issued for so a lease cannot clear a cooldown that a later 429 replaced.
+   */
+  cooldownGeneration?: number;
+  /**
+   * Identity of the in-flight probe. A cooled-down account sends no traffic, so
+   * no organic 2xx can prove recovery; only the outcome carrying this id may
+   * clear the cooldown.
+   */
+  probeLeaseId?: string;
+  /** Cooldown generation at the moment the lease was granted. */
+  probeLeaseGeneration?: number;
+  /** Last probe grant or conclusion; paces the probe interval. */
+  lastProbeAt?: number;
+  /**
+   * Soft avoid after connect_error / timeout / transient 5xx. Cleared on 2xx.
+   * Blocks pool selection + thread affinity reuse so a sticky session can leave a
+   * flaky account without throwing CodexAccountCooldownError (hard-only).
+   */
+  softAvoidUntil?: number;
+};
+
+const CODEX_DEFAULT_QUOTA_COOLDOWN_MS = 60_000;
+const CODEX_MAX_QUOTA_COOLDOWN_MS = 24 * 60 * 60_000;
+/**
+ * A weekly/monthly quota `resetAt` announces when the window refreshes; it is not
+ * a "come back after this" directive like Retry-After. Plan quota routinely frees
+ * up long before the advertised reset, so cap reset-derived cooldowns far below
+ * the Retry-After ceiling (#433).
+ */
+const CODEX_MAX_RESET_DERIVED_COOLDOWN_MS = 15 * 60_000;
+/** Minimum gap between probe leases for one cooled-down account. */
+export const CODEX_QUOTA_PROBE_INTERVAL_MS = 5 * 60_000;
+export const CODEX_FAILURE_WINDOW_MS = 5 * 60_000;
+/** How long a transient failure keeps the account out of pool selection. */
+export const CODEX_TRANSIENT_SOFT_AVOID_MS = 30_000;
+const CODEX_TRANSIENT_SOFT_AVOID_ESCALATION_MS = [
+  CODEX_TRANSIENT_SOFT_AVOID_MS,
+  2 * 60_000,
+  10 * 60_000,
+  30 * 60_000,
+] as const;
+export const CODEX_THREAD_AFFINITY_IDLE_TTL_MS = 24 * 60 * 60_000;
+export const CODEX_THREAD_AFFINITY_MAX_ENTRIES = 2048;
+const MAX_AFFINITY_COMPONENT_BYTES = 512;
+// Min interval between quota threshold re-evaluations for a single bound thread.
+// Well under the 5h/weekly quota windows, but enough to stop per-request flapping.
+export const CODEX_THREAD_AFFINITY_REEVAL_INTERVAL_MS = 60_000;
+
+const upstreamHealth = new Map<string, CodexUpstreamHealth>();
+/**
+ * Reset-derived 429s can describe a quota owned by one native model family,
+ * rather than the whole ChatGPT account. Keep those advisory cooldowns apart
+ * from account-wide Retry-After/default throttles and transient health.
+ */
+const quotaScopedHealth = new Map<string, Map<CodexQuotaScope, CodexUpstreamHealth>>();
+let lastReconciledGeneration = 0;
+let liveHealthAccountIds = new Set<string>();
+
+export type CodexUpstreamOutcome = number | "connect_error" | "timeout";
+export type CodexUpstreamOutcomeClass = "success" | "credential" | "quota" | "transient" | "caller" | "unknown";
+export type CodexCooldownSource = "retry-after" | "reset-derived" | "default";
+/**
+ * Native Codex quota groups known to be independent upstream. Keep the mapping
+ * deliberately conservative: unlisted models share the normal native group.
+ * Add a new explicit group here only when its independent upstream quota is
+ * confirmed, so shared limits never receive cross-model bypasses.
+ */
+export type CodexQuotaScope = "shared" | "spark";
+
+/**
+ * Requests without a resolved native model retain the historic one-account-per-
+ * thread behavior. Requests with a known quota scope get an independent
+ * affinity so a Spark failover cannot displace the same thread's Terra/Luna
+ * account (and vice versa).
+ */
+type ThreadAffinityScope = CodexQuotaScope | "legacy";
+const LEGACY_THREAD_AFFINITY_SCOPE = "legacy" as const;
+const threadAccountMap = new Map<string, Map<ThreadAffinityScope, ThreadAffinityEntry>>();
+
+const NATIVE_MODEL_QUOTA_SCOPES: Readonly<Record<string, CodexQuotaScope>> = {
+  "gpt-5.3-codex-spark": "spark",
+};
+
+// A thread can have one legacy binding plus one binding for each known scope.
+// This upper-bound guard avoids an exact map scan until it can be over capacity.
+const MAX_THREAD_AFFINITY_SCOPES = new Set([
+  LEGACY_THREAD_AFFINITY_SCOPE,
+  "shared",
+  ...Object.values(NATIVE_MODEL_QUOTA_SCOPES),
+]).size;
+
+export function codexQuotaScopeForModel(modelId: string | undefined): CodexQuotaScope | undefined {
+  if (!modelId?.trim()) return undefined;
+  return NATIVE_MODEL_QUOTA_SCOPES[modelId.trim().toLowerCase()] ?? "shared";
+}
+
+/** Independent quota groups must not mutate the shared active-account cursor. */
+function isIndependentCodexQuotaScope(quotaScope?: CodexQuotaScope): boolean {
+  return quotaScope !== undefined && quotaScope !== "shared";
+}
+
+function codexPoolKeyForScope(quotaScope?: CodexQuotaScope): string {
+  return isIndependentCodexQuotaScope(quotaScope) ? `${POOL_KEY_CODEX}:${quotaScope}` : POOL_KEY_CODEX;
+}
+
+export type CodexUpstreamOutcomeMeta = {
+  retryAfter?: string | null;
+  resetAt?: unknown | unknown[];
+  now?: number;
+  /** Native model selected for this request; used only for confirmed scoped quotas. */
+  modelId?: string;
+  /** When set, clears affinity for this thread immediately on transient failure. */
+  threadId?: string | null;
+  /**
+   * Probe lease held by this request, when it was admitted through an active
+   * quota cooldown. Only the outcome carrying the current lease may clear the
+   * cooldown (#433).
+  */
+  probeLeaseId?: string;
+  /** Scope of `probeLeaseId` when it was granted against a model-scoped cooldown. */
+  probeQuotaScope?: CodexQuotaScope;
+  /**
+   * Already-chosen alternate for same-request 429 retry. When set, promotion
+   * reuses this account instead of calling {@link pickAlternateCodexAccount}
+   * again (which would advance a round-robin ring twice).
+   */
+  promoteAccountId?: string;
+  /** Generation captured when this routed account was selected. */
+  writerGeneration?: number;
+};
+
+function hasConfiguredPoolAccount(config: OcxConfig, accountId: string): boolean {
+  if (accountId === MAIN_CODEX_ACCOUNT_ID) return isCodexAccountUsable(config, accountId);
+  return (config.codexAccounts ?? [])
+    .some(account => isSelectableCodexPoolAccount(account) && account.id === accountId);
+}
+
+export function listLiveCodexAccountIds(config: OcxConfig): ReadonlySet<string> {
+  const ids = new Set((config.codexAccounts ?? []).map(account => account.id));
+  const openai = config.providers.openai;
+  if (openai && openai.disabled !== true && isCanonicalOpenAiForwardProvider(openai)) {
+    ids.add(MAIN_CODEX_ACCOUNT_ID);
+  }
+  return ids;
+}
+
+export function clearThreadAccountMap(): void {
+  threadAccountMap.clear();
+}
+
+export function clearThreadAccountMapForAccount(accountId: string): void {
+  for (const [threadId, affinities] of threadAccountMap) {
+    for (const [scope, entry] of affinities) {
+      if (entry.accountId === accountId) affinities.delete(scope);
+    }
+    if (affinities.size === 0) threadAccountMap.delete(threadId);
+  }
+}
+
+export function clearCodexUpstreamHealth(): void {
+  upstreamHealth.clear();
+  quotaScopedHealth.clear();
+  runtimeActiveCodexAccountId = undefined;
+}
+
+export function clearCodexUpstreamHealthForAccount(accountId: string): void {
+  upstreamHealth.delete(accountId);
+  quotaScopedHealth.delete(accountId);
+}
+
+export function reconcileCodexRoutingHealth(context: GenerationContext): number {
+  if (context.generation <= lastReconciledGeneration) return 0;
+  let removed = 0;
+  for (const accountId of upstreamHealth.keys()) {
+    if (context.codexAccountIds.has(accountId)) continue;
+    upstreamHealth.delete(accountId);
+    removed += 1;
+  }
+  for (const accountId of quotaScopedHealth.keys()) {
+    if (context.codexAccountIds.has(accountId)) continue;
+    quotaScopedHealth.delete(accountId);
+    removed += 1;
+  }
+  liveHealthAccountIds = new Set(context.codexAccountIds);
+  lastReconciledGeneration = context.generation;
+  return removed;
+}
+
+export function getCodexUpstreamHealth(
+  accountId: string,
+): CodexUpstreamHealth | null {
+  return upstreamHealth.get(accountId) ?? null;
+}
+
+function scopedHealthFor(accountId: string, scope: CodexQuotaScope): CodexUpstreamHealth | undefined {
+  return quotaScopedHealth.get(accountId)?.get(scope);
+}
+
+function setScopedHealth(accountId: string, scope: CodexQuotaScope, health: CodexUpstreamHealth): void {
+  let scopes = quotaScopedHealth.get(accountId);
+  if (!scopes) {
+    scopes = new Map();
+    quotaScopedHealth.set(accountId, scopes);
+  }
+  scopes.set(scope, health);
+}
+
+function deleteScopedHealth(accountId: string, scope: CodexQuotaScope): void {
+  const scopes = quotaScopedHealth.get(accountId);
+  if (!scopes) return;
+  scopes.delete(scope);
+  if (scopes.size === 0) quotaScopedHealth.delete(accountId);
+}
+
+export function computeCodexUsageScore(quota: {
+  weeklyPercent?: number;
+  monthlyPercent?: number;
+} | null, plan?: string | null): number {
+  if (!quota) return CODEX_UNKNOWN_USAGE_SCORE;
+  const normalizedPlan = plan?.trim().toLowerCase();
+  if (normalizedPlan === "go" || normalizedPlan === "free") {
+    return typeof quota.monthlyPercent === "number" && Number.isFinite(quota.monthlyPercent)
+      ? quota.monthlyPercent
+      : CODEX_UNKNOWN_USAGE_SCORE;
+  }
+  const values = [quota.weeklyPercent, quota.monthlyPercent]
+    .filter((value): value is number => typeof value === "number" && Number.isFinite(value));
+  return values.length > 0 ? Math.max(...values) : CODEX_UNKNOWN_USAGE_SCORE;
+}
+
+export function classifyCodexUpstreamOutcome(outcome: CodexUpstreamOutcome): CodexUpstreamOutcomeClass {
+  if (outcome === "connect_error" || outcome === "timeout") return "transient";
+  if (!Number.isFinite(outcome)) return "unknown";
+  if (outcome >= 200 && outcome < 300) return "success";
+  if (outcome === 401 || outcome === 403) return "credential";
+  // 402 Payment Required is treated as quota exhaustion for pool cooldown/failover
+  // (same-request alternate retry records this outcome for the depleted account).
+  if (outcome === 429 || outcome === 402) return "quota";
+  if (outcome >= 400 && outcome < 500) return "caller";
+  if (outcome >= 500 && outcome < 600) return "transient";
+  return "unknown";
+}
+
+function clampCooldownMs(ms: number): number {
+  return Math.min(Math.max(ms, 1), CODEX_MAX_QUOTA_COOLDOWN_MS);
+}
+
+export function parseRetryAfterMs(value: string | null | undefined, now = Date.now()): number | undefined {
+  const text = value?.trim();
+  if (!text) return undefined;
+  if (/^\d+(?:\.\d+)?$/.test(text)) {
+    const seconds = Number(text);
+    if (Number.isFinite(seconds) && seconds > 0) return clampCooldownMs(Math.ceil(seconds * 1000));
+  }
+  const timestamp = Date.parse(text);
+  if (!Number.isFinite(timestamp)) return undefined;
+  const delay = timestamp - now;
+  return delay > 0 ? clampCooldownMs(delay) : undefined;
+}
+
+function resetTimestampMs(value: unknown): number | undefined {
+  const numeric = typeof value === "number"
+    ? value
+    : typeof value === "string" && value.trim() !== ""
+      ? Number(value)
+      : undefined;
+  if (typeof numeric !== "number" || !Number.isFinite(numeric) || numeric <= 0) return undefined;
+  return numeric < 1_000_000_000_000 ? numeric * 1000 : numeric;
+}
+
+export function parseResetCooldownMs(resetAt: unknown | unknown[] | undefined, now = Date.now()): number | undefined {
+  const values = Array.isArray(resetAt) ? resetAt : [resetAt];
+  let best: number | undefined;
+  for (const value of values) {
+    const timestamp = resetTimestampMs(value);
+    if (timestamp === undefined) continue;
+    const delay = timestamp - now;
+    if (delay <= 0) continue;
+    // A far-future reset must not pin the account for the full Retry-After
+    // ceiling: quota usually frees up well before the advertised window (#433).
+    const clamped = Math.min(clampCooldownMs(delay), CODEX_MAX_RESET_DERIVED_COOLDOWN_MS);
+    if (best === undefined || clamped < best) best = clamped;
+  }
+  return best;
+}
+
+export function computeQuotaCooldown(meta: CodexUpstreamOutcomeMeta = {}): {
+  until: number;
+  source: CodexCooldownSource;
+} {
+  const now = meta.now ?? Date.now();
+  const retryAfterMs = parseRetryAfterMs(meta.retryAfter, now);
+  if (retryAfterMs !== undefined) return { until: now + retryAfterMs, source: "retry-after" };
+  const resetCooldownMs = parseResetCooldownMs(meta.resetAt, now);
+  if (resetCooldownMs !== undefined) return { until: now + resetCooldownMs, source: "reset-derived" };
+  return { until: now + CODEX_DEFAULT_QUOTA_COOLDOWN_MS, source: "default" };
+}
+
+export function computeQuotaCooldownUntil(meta: CodexUpstreamOutcomeMeta = {}): number {
+  return computeQuotaCooldown(meta).until;
+}
+
+/**
+ * Grant at most one probe lease per interval for a cooled-down account.
+ *
+ * A cooled-down account is short-circuited locally, so it never sends traffic and
+ * no organic 2xx can prove that upstream quota recovered — the cooldown can only
+ * end by expiry or a proxy restart (#433). Releasing a single probe breaks that
+ * deadlock. Explicit Retry-After cooldowns are excluded: those are literal retry
+ * directives, not window announcements.
+ *
+ * Returns the lease id, or null when no probe may go out right now.
+ */
+export function tryAcquireCodexQuotaProbeLease(accountId: string, now = Date.now()): string | null {
+  if (!canAcquireCodexQuotaProbeLease(accountId, now)) return null;
+  const health = upstreamHealth.get(accountId)!;
+  const probeLeaseId = randomUUID();
+  upstreamHealth.set(accountId, {
+    ...health,
+    probeLeaseId,
+    probeLeaseGeneration: health.cooldownGeneration ?? 0,
+    lastProbeAt: now,
+  });
+  return probeLeaseId;
+}
+
+/** Side-effect-free check mirroring {@link tryAcquireCodexQuotaProbeLease} eligibility. */
+export function canAcquireCodexQuotaProbeLease(accountId: string, now = Date.now()): boolean {
+  return canAcquireQuotaProbeLease(upstreamHealth.get(accountId), now);
+}
+
+function canAcquireQuotaProbeLease(health: CodexUpstreamHealth | undefined, now: number): boolean {
+  if (!health) return false;
+  const cooldownUntil = health.cooldownUntil;
+  if (typeof cooldownUntil !== "number" || !Number.isFinite(cooldownUntil) || cooldownUntil <= now) return false;
+  if (health.cooldownSource === "retry-after") return false;
+  if (health.probeLeaseId !== undefined) return false;
+  const origin = health.lastProbeAt ?? health.cooldownSince ?? cooldownUntil;
+  return now - origin >= CODEX_QUOTA_PROBE_INTERVAL_MS;
+}
+
+/** Acquire the recovery probe for one confirmed model-specific quota group. */
+export function tryAcquireCodexQuotaScopeProbeLease(
+  accountId: string,
+  scope: CodexQuotaScope,
+  now = Date.now(),
+): string | null {
+  const health = scopedHealthFor(accountId, scope);
+  if (!canAcquireQuotaProbeLease(health, now)) return null;
+  const probeLeaseId = randomUUID();
+  setScopedHealth(accountId, scope, {
+    ...health!,
+    probeLeaseId,
+    probeLeaseGeneration: health!.cooldownGeneration ?? 0,
+    lastProbeAt: now,
+  });
+  return probeLeaseId;
+}
+
+/**
+ * Hand a probe lease back without recording an upstream outcome. Used by paths
+ * that take a lease and then fail before any request reaches upstream.
+ */
+export function releaseCodexQuotaProbeLease(accountId: string, leaseId: string, now = Date.now()): void {
+  const health = upstreamHealth.get(accountId);
+  if (!health || health.probeLeaseId !== leaseId) return;
+  upstreamHealth.set(accountId, withProbeLeaseReleased(health, now));
+}
+
+/** Release a model-specific quota probe when the request never reaches upstream. */
+export function releaseCodexQuotaScopeProbeLease(
+  accountId: string,
+  scope: CodexQuotaScope,
+  leaseId: string,
+  now = Date.now(),
+): void {
+  const health = scopedHealthFor(accountId, scope);
+  if (!health || health.probeLeaseId !== leaseId) return;
+  setScopedHealth(accountId, scope, withProbeLeaseReleased(health, now));
+}
+
+/**
+ * True when this outcome belongs to the account's in-flight probe. The
+ * undefined-id guard matters: without it an outcome carrying no lease would match
+ * an account holding no lease and be mistaken for the probe owner.
+ */
+function ownsProbeLease(health: CodexUpstreamHealth | undefined, meta: CodexUpstreamOutcomeMeta): boolean {
+  return meta.probeLeaseId !== undefined && meta.probeLeaseId === health?.probeLeaseId;
+}
+
+/**
+ * True when the owning probe may still clear the cooldown. A later 429 bumps the
+ * generation, so a probe that started under an older cooldown must not erase the
+ * newer restriction (which may carry an explicit Retry-After).
+ */
+function probeMayClearCooldown(health: CodexUpstreamHealth | undefined, meta: CodexUpstreamOutcomeMeta): boolean {
+  return ownsProbeLease(health, meta)
+    && (health!.probeLeaseGeneration ?? 0) === (health!.cooldownGeneration ?? 0);
+}
+
+/** Strip the in-flight lease while preserving every hard-cooldown field. */
+function withProbeLeaseReleased(health: CodexUpstreamHealth, now: number): CodexUpstreamHealth {
+  const { probeLeaseId: _id, probeLeaseGeneration: _gen, ...rest } = health;
+  return { ...rest, lastProbeAt: now };
+}
+
+/**
+ * Hard-cooldown bookkeeping that ordinary success/transient transitions rebuild
+ * their health object from. Dropping these would let one late unrelated response
+ * erase a Retry-After source, a cooldown generation, or someone else's live probe.
+ */
+function preservedCooldownFields(health: CodexUpstreamHealth | undefined): Partial<CodexUpstreamHealth> {
+  if (!health) return {};
+  const { consecutiveFailures: _f, consecutiveSuccesses: _s, lastFailureStatus: _st, lastFailureAt: _at, softAvoidUntil: _sa, ...cooldownFields } = health;
+  return cooldownFields;
+}
+
+/** 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;
+  // 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);
+    }
+  }
+  const current = upstreamHealth.get(accountId);
+  if (!current) return;
+  const preserved = preservedCooldownFields(current);
+  if (Object.keys(preserved).length === 0) upstreamHealth.delete(accountId);
+  else upstreamHealth.set(accountId, { consecutiveFailures: 0, ...preserved });
+}
+
+export function getCodexAccountCooldownUntil(accountId: string, now = Date.now()): number | null {
+  const cooldownUntil = upstreamHealth.get(accountId)?.cooldownUntil;
+  return typeof cooldownUntil === "number" && Number.isFinite(cooldownUntil) && cooldownUntil > now ? cooldownUntil : null;
+}
+
+/** Read-only cooldown snapshot for shared OAuth health projection (no write side effects). */
+export function getCodexAccountHealthSnapshot(accountId: string, now = Date.now()): {
+  cooldownUntil?: number;
+  cooldownSource?: CodexCooldownSource;
+} | null {
+  const cooldownUntil = getCodexAccountCooldownUntil(accountId, now);
+  if (cooldownUntil === null) return null;
+  const source = upstreamHealth.get(accountId)?.cooldownSource;
+  return {
+    cooldownUntil,
+    ...(source ? { cooldownSource: source } : {}),
+  };
+}
+
+/**
+ * Read the cooldown relevant to a routed native model. Account-wide cooldowns
+ * (Retry-After/default) always win; reset-derived scoped state applies only to
+ * its confirmed quota group.
+ */
+export function getCodexQuotaHealthSnapshot(
+  accountId: string,
+  quotaScope: CodexQuotaScope | undefined,
+  now = Date.now(),
+): {
+  cooldownUntil?: number;
+  cooldownSource?: CodexCooldownSource;
+  quotaScope?: CodexQuotaScope;
+} | null {
+  const account = getCodexAccountHealthSnapshot(accountId, now);
+  if (account) return account;
+  if (!quotaScope) return null;
+  const scoped = scopedHealthFor(accountId, quotaScope);
+  const cooldownUntil = scoped?.cooldownUntil;
+  if (typeof cooldownUntil !== "number" || !Number.isFinite(cooldownUntil) || cooldownUntil <= now) return null;
+  return {
+    cooldownUntil,
+    ...(scoped?.cooldownSource ? { cooldownSource: scoped.cooldownSource } : {}),
+    quotaScope,
+  };
+}
+
+export function isCodexAccountInCooldown(accountId: string, now = Date.now()): boolean {
+  return getCodexAccountCooldownUntil(accountId, now) !== null;
+}
+
+/**
+ * Manually lift a hard quota cooldown without touching failure history.
+ *
+ * Injected Codex routing makes this proxy the ONLY model path for Codex Desktop, so a
+ * cooldown that outlives the real upstream limit reads to the user as "the whole app is
+ * broken" with no escape but editing config.toml. This is that escape hatch.
+ *
+ * Deliberately narrow:
+ * - Failure counters and softAvoid survive. Clearing a cooldown says "the quota window
+ *   moved", not "this account is healthy"; failover must keep its knowledge.
+ * - Dropping `probeLeaseId` is what stops a stale in-flight probe from later "proving"
+ *   recovery against a NEWER cooldown: {@link ownsProbeLease} needs the id to match.
+ *   `cooldownGeneration` is preserved and bumped as redundancy only — a fresh 429 already
+ *   bumps it in {@link recordCodexUpstreamOutcome}, so the bump here is not load-bearing
+ *   today and is kept so the invariant survives a future change that retains the lease.
+ *
+ * Returns false when the account carried no live cooldown (already expired or never set).
+ */
+export function clearCodexAccountCooldown(accountId: string, now = Date.now()): boolean {
+  const clear = (health: CodexUpstreamHealth): CodexUpstreamHealth | null => {
+    const cooldownUntil = health.cooldownUntil;
+    if (typeof cooldownUntil !== "number" || !Number.isFinite(cooldownUntil) || cooldownUntil <= now) return null;
+    const {
+      cooldownUntil: _until,
+      cooldownSince: _since,
+      cooldownSource: _source,
+      probeLeaseId: _leaseId,
+      probeLeaseGeneration: _leaseGeneration,
+      ...rest
+    } = health;
+    return {
+      ...rest,
+      cooldownGeneration: (health.cooldownGeneration ?? 0) + 1,
+      lastProbeAt: now,
+    };
+  };
+
+  let cleared = false;
+  const accountHealth = upstreamHealth.get(accountId);
+  if (accountHealth) {
+    const next = clear(accountHealth);
+    if (next) {
+      upstreamHealth.set(accountId, next);
+      cleared = true;
+    }
+  }
+  for (const [scope, health] of quotaScopedHealth.get(accountId) ?? []) {
+    const next = clear(health);
+    if (next) {
+      setScopedHealth(accountId, scope, next);
+      cleared = true;
+    }
+  }
+  return cleared;
+}
+
+export function getCodexAccountSoftAvoidUntil(accountId: string, now = Date.now()): number | null {
+  const softAvoidUntil = upstreamHealth.get(accountId)?.softAvoidUntil;
+  return typeof softAvoidUntil === "number" && Number.isFinite(softAvoidUntil) && softAvoidUntil > now
+    ? softAvoidUntil
+    : null;
+}
+
+export function isCodexAccountSoftAvoided(accountId: string, now = Date.now()): boolean {
+  return getCodexAccountSoftAvoidUntil(accountId, now) !== null;
+}
+
+function isCodexAccountSelectable(
+  config: OcxConfig,
+  accountId: string,
+  now: number,
+  quotaScope?: CodexQuotaScope,
+): boolean {
+  return !isCodexAccountPaused(config, accountId)
+    && getCodexQuotaHealthSnapshot(accountId, quotaScope, now) === null
+    && !isCodexAccountSoftAvoided(accountId, now)
+    && isCodexAccountUsable(config, accountId);
+}
+
+function threadAffinityScope(quotaScope?: CodexQuotaScope): ThreadAffinityScope {
+  return quotaScope ?? LEGACY_THREAD_AFFINITY_SCOPE;
+}
+
+function admissibleAffinityComponent(value: string): boolean {
+  return retainedUtf8Bytes(value) <= MAX_AFFINITY_COMPONENT_BYTES;
+}
+
+function getThreadAffinity(threadId: string, quotaScope?: CodexQuotaScope): ThreadAffinityEntry | undefined {
+  if (!admissibleAffinityComponent(threadId)) return undefined;
+  return threadAccountMap.get(threadId)?.get(threadAffinityScope(quotaScope));
+}
+
+function deleteThreadAffinity(threadId: string, quotaScope?: CodexQuotaScope): void {
+  if (!admissibleAffinityComponent(threadId)) return;
+  const affinities = threadAccountMap.get(threadId);
+  if (!affinities) return;
+  affinities.delete(threadAffinityScope(quotaScope));
+  if (affinities.size === 0) threadAccountMap.delete(threadId);
+}
+
+/** Remove only the matching failed account's affinities for one thread. */
+function deleteThreadAffinitiesForAccount(threadId: string, accountId: string): void {
+  if (!admissibleAffinityComponent(threadId) || !admissibleAffinityComponent(accountId)) return;
+  const affinities = threadAccountMap.get(threadId);
+  if (!affinities) return;
+  for (const [scope, entry] of affinities) {
+    if (entry.accountId === accountId) affinities.delete(scope);
+  }
+  if (affinities.size === 0) threadAccountMap.delete(threadId);
+}
+
+function threadAffinityEntryCount(): number {
+  let count = 0;
+  for (const affinities of threadAccountMap.values()) count += affinities.size;
+  return count;
+}
+
+function isThreadAffinityExpired(entry: ThreadAffinityEntry, now: number): boolean {
+  return now - entry.lastUsedAt > CODEX_THREAD_AFFINITY_IDLE_TTL_MS;
+}
+
+function isThreadAffinityGenerationLive(entry: ThreadAffinityEntry): boolean {
+  if (entry.accountId === MAIN_CODEX_ACCOUNT_ID) return entry.generation === 0;
+  return isCodexAccountGenerationLive(entry.accountId, entry.generation);
+}
+
+function pruneExpiredThreadAffinities(now: number): void {
+  for (const [threadId, affinities] of threadAccountMap) {
+    for (const [scope, entry] of affinities) {
+      if (isThreadAffinityExpired(entry, now)) affinities.delete(scope);
+    }
+    if (affinities.size === 0) threadAccountMap.delete(threadId);
+  }
+}
+
+function pruneLruThreadAffinities(): void {
+  if (threadAccountMap.size * MAX_THREAD_AFFINITY_SCOPES <= CODEX_THREAD_AFFINITY_MAX_ENTRIES) return;
+  while (threadAffinityEntryCount() > CODEX_THREAD_AFFINITY_MAX_ENTRIES) {
+    let oldestThreadId: string | null = null;
+    let oldestScope: ThreadAffinityScope | null = null;
+    let oldestLastUsedAt = Number.POSITIVE_INFINITY;
+    for (const [threadId, affinities] of threadAccountMap) {
+      for (const [scope, entry] of affinities) {
+        if (entry.lastUsedAt < oldestLastUsedAt) {
+          oldestThreadId = threadId;
+          oldestScope = scope;
+          oldestLastUsedAt = entry.lastUsedAt;
+        }
+      }
+    }
+    if (!oldestThreadId || !oldestScope) return;
+    deleteThreadAffinity(oldestThreadId, oldestScope === LEGACY_THREAD_AFFINITY_SCOPE ? undefined : oldestScope);
+  }
+}
+
+function bindThreadAffinity(
+  threadId: string,
+  accountId: string,
+  now: number,
+  quotaScope?: CodexQuotaScope,
+): void {
+  if (!admissibleAffinityComponent(threadId) || !admissibleAffinityComponent(accountId)) return;
+  const record = accountId === MAIN_CODEX_ACCOUNT_ID ? undefined : readCodexAccountRecord(accountId);
+  if (accountId !== MAIN_CODEX_ACCOUNT_ID && (!record?.credential || record.deletedAt != null)) return;
+  pruneExpiredThreadAffinities(now);
+  const scope = threadAffinityScope(quotaScope);
+  const affinities = threadAccountMap.get(threadId) ?? new Map<ThreadAffinityScope, ThreadAffinityEntry>();
+  const previous = affinities.get(scope);
+  affinities.set(scope, {
+    accountId,
+    generation: accountId === MAIN_CODEX_ACCOUNT_ID ? 0 : record!.generation,
+    createdAt: previous?.createdAt ?? now,
+    lastUsedAt: now,
+    lastReevalAt: now,
+  });
+  threadAccountMap.set(threadId, affinities);
+  pruneLruThreadAffinities();
+}
+
+function getEligiblePoolAccounts(
+  config: OcxConfig,
+  excludeId?: string,
+  now = Date.now(),
+  quotaScope?: CodexQuotaScope,
+): string[] {
+  const ids = (config.codexAccounts ?? [])
+    .filter(account => isSelectableCodexPoolAccount(account)
+      && account.id !== excludeId
+      && !isCodexAccountPaused(config, account.id)
+      && !isAccountNeedsReauth(account.id))
+    .filter(account => getCodexQuotaHealthSnapshot(account.id, quotaScope, now) === null)
+    .filter(account => !isCodexAccountSoftAvoided(account.id, now))
+    .filter(account => isCodexAccountUsable(config, account.id))
+    .map(account => account.id);
+  // The main Codex account is not stored in config.codexAccounts; include it as a
+  // first-class rotation candidate when its read-only token is usable (Option A).
+  if (
+    excludeId !== MAIN_CODEX_ACCOUNT_ID
+    && !isCodexAccountPaused(config, MAIN_CODEX_ACCOUNT_ID)
+    && !isAccountNeedsReauth(MAIN_CODEX_ACCOUNT_ID)
+    && getCodexQuotaHealthSnapshot(MAIN_CODEX_ACCOUNT_ID, quotaScope, now) === null
+    && !isCodexAccountSoftAvoided(MAIN_CODEX_ACCOUNT_ID, now)
+    && isCodexAccountUsable(config, MAIN_CODEX_ACCOUNT_ID)
+  ) {
+    ids.unshift(MAIN_CODEX_ACCOUNT_ID);
+  }
+  return ids;
+}
+
+function listEligibleCodexAccountIds(
+  config: OcxConfig,
+  now: number,
+  quotaScope?: CodexQuotaScope,
+): string[] {
+  return getEligiblePoolAccounts(config, undefined, now, quotaScope);
+}
+
+function stickyLimitForConfig(config: OcxConfig): number {
+  return normalizeAccountPoolStickyLimit(config.accountPoolStickyLimit);
+}
+
+function isActiveUnderFillFirstThreshold(config: OcxConfig, accountId: string): boolean {
+  const threshold = config.autoSwitchThreshold ?? 80;
+  if (threshold <= 0) return true;
+  const usage = computeCodexUsageScore(getAccountQuota(accountId), getPoolAccountPlan(config, accountId));
+  // Unknown usage must not force fill-first to abandon the active account.
+  if (isUnknownUsage(usage)) return true;
+  return usage < threshold;
+}
+
+/**
+ * Fill-first: keep selectable active under threshold; otherwise advance to the next
+ * eligible id in stable sorted order after the current active (wrapping).
+ */
+function pickFillFirstCodexAccount(
+  config: OcxConfig,
+  now: number,
+  quotaScope?: CodexQuotaScope,
+): string | null {
+  const eligible = listEligibleCodexAccountIds(config, now, quotaScope);
+  if (eligible.length === 0) return null;
+
+  const active = getEffectiveActiveCodexAccountId(config);
+  if (active && eligible.includes(active) && isActiveUnderFillFirstThreshold(config, active)) {
+    return active;
+  }
+
+  return pickNextFillFirstCodexAccount(config, active ?? null, eligible, now);
+}
+
+/** Next eligible account in stable order after `afterId` (wrapping). */
+function pickNextFillFirstCodexAccount(
+  config: OcxConfig,
+  afterId: string | null,
+  eligible = listEligibleCodexAccountIds(config, Date.now()),
+  _now = Date.now(),
+): string | null {
+  if (eligible.length === 0) return null;
+  const ordered = [...eligible].sort((a, b) => a.localeCompare(b));
+  if (!afterId) {
+    // Prefer an under-threshold account when starting with no active cursor.
+    for (const id of ordered) {
+      if (isActiveUnderFillFirstThreshold(config, id)) return id;
+    }
+    return ordered[0] ?? null;
+  }
+
+  const allConfigured = [
+    ...(isCodexAccountUsable(config, MAIN_CODEX_ACCOUNT_ID) || afterId === MAIN_CODEX_ACCOUNT_ID
+      ? [MAIN_CODEX_ACCOUNT_ID]
+      : []),
+    ...(config.codexAccounts ?? []).filter(account => !account.isMain).map(account => account.id),
+  ];
+  const stableAll = [...new Set(allConfigured)].sort((a, b) => a.localeCompare(b));
+  const startIdx = stableAll.indexOf(afterId);
+  if (startIdx < 0) {
+    for (const id of ordered) {
+      if (isActiveUnderFillFirstThreshold(config, id)) return id;
+    }
+    return ordered[0] ?? null;
+  }
+
+  // Skip successors that are also at/above threshold (known drained usage).
+  let fallback: string | null = null;
+  for (let step = 1; step <= stableAll.length; step++) {
+    const candidate = stableAll[(startIdx + step) % stableAll.length]!;
+    if (!eligible.includes(candidate)) continue;
+    if (!fallback) fallback = candidate;
+    if (isActiveUnderFillFirstThreshold(config, candidate)) return candidate;
+  }
+  return fallback ?? ordered[0] ?? null;
+}
+
+/**
+ * Unbound new-session pick for round-robin / fill-first. Returns null to fall through
+ * to the legacy quota path (or when the strategy is quota).
+ *
+ * When `commit` is true (resolve path), remembers active in-memory, binds thread affinity, and
+ * notes RR success. When `commit` is false (preview), returns the same RR/fill-first
+ * account resolve would pick via a dry-run peek — without mutating ring weights,
+ * activeKey, sticky counters, config, or affinity.
+ *
+ * Automatic strategy picks never sync-write config; only manual selection persists active.
+ *
+ * Known limitation (follow-up): when a subagent preview peeks an RR account and the request
+ * then falls back to a non-Codex provider, the ring is not reserved/committed. Prefer seeding
+ * the peeked account if that path becomes load-bearing.
+ */
+function pickUnboundStrategyAccount(
+  config: OcxConfig,
+  threadId: string | null,
+  now: number,
+  commit: boolean,
+  quotaScope?: CodexQuotaScope,
+): string | null {
+  const strategy = normalizeAccountPoolStrategy(config.accountPoolStrategy);
+  if (strategy === "quota") return null;
+  const poolKey = codexPoolKeyForScope(quotaScope);
+
+  let picked: string | null = null;
+  if (strategy === "round-robin") {
+    const eligible = listEligibleCodexAccountIds(config, now, quotaScope);
+    const limit = stickyLimitForConfig(config);
+    if (!commit) {
+      return peekRoundRobinAccount(poolKey, eligible, limit);
+    }
+    picked = pickRoundRobinAccount(poolKey, eligible, limit);
+    if (!picked) return null;
+    if (!isIndependentCodexQuotaScope(quotaScope)) rememberActiveCodexAccount(config, picked);
+    if (threadId) bindThreadAffinity(threadId, picked, now, quotaScope);
+    notePoolRotationSuccess(poolKey, picked, limit);
+    return picked;
+  }
+
+  if (strategy === "fill-first") {
+    picked = pickFillFirstCodexAccount(config, now, quotaScope);
+    if (!picked) return null;
+    if (commit) {
+      if (!isIndependentCodexQuotaScope(quotaScope)) rememberActiveCodexAccount(config, picked);
+      if (threadId) bindThreadAffinity(threadId, picked, now, quotaScope);
+    }
+    return picked;
+  }
+
+  return null;
+}
+
+export function getPoolAccountPlan(config: OcxConfig, accountId: string): string | undefined {
+  if (accountId === MAIN_CODEX_ACCOUNT_ID) return getMainAccountPlan();
+  return (config.codexAccounts ?? [])
+    .find(account => isSelectableCodexPoolAccount(account) && account.id === accountId)?.plan;
+}
+
+function pickLowerUsageAccount(
+  config: OcxConfig,
+  active: string,
+  activeUsage: number,
+  now: number,
+  quotaScope?: CodexQuotaScope,
+): string {
+  let best = active;
+  let bestUsage = activeUsage;
+  for (const id of getEligiblePoolAccounts(config, active, now, quotaScope)) {
+    const usage = computeCodexUsageScore(getAccountQuota(id), getPoolAccountPlan(config, id));
+    if (usage < bestUsage) {
+      best = id;
+      bestUsage = usage;
+    }
+  }
+  return best;
+}
+
+export function pickLowestUsageCodexAccount(
+  config: OcxConfig,
+  excludeId?: string,
+  now = Date.now(),
+  quotaScope?: CodexQuotaScope,
+): string | null {
+  let best: string | null = null;
+  let bestUsage = Number.POSITIVE_INFINITY;
+  for (const id of getEligiblePoolAccounts(config, excludeId, now, quotaScope)) {
+    const usage = computeCodexUsageScore(getAccountQuota(id), getPoolAccountPlan(config, id));
+    if (usage < bestUsage) {
+      best = id;
+      bestUsage = usage;
+    }
+  }
+  return best;
+}
+
+/**
+ * Strategy-aware alternate after a cooled/excluded account (same-request 429 retry
+ * and active promotion). Quota keeps lowest-usage; fill-first advances stable order;
+ * round-robin takes the next ring pick (caller should have noted the failure).
+ */
+export function pickAlternateCodexAccount(
+  config: OcxConfig,
+  excludeId: string,
+  now = Date.now(),
+  quotaScope?: CodexQuotaScope,
+): string | null {
+  const strategy = normalizeAccountPoolStrategy(config.accountPoolStrategy);
+  if (strategy === "round-robin") {
+    const eligible = listEligibleCodexAccountIds(config, now, quotaScope).filter(id => id !== excludeId);
+    return pickRoundRobinAccount(codexPoolKeyForScope(quotaScope), eligible, stickyLimitForConfig(config));
+  }
+  if (strategy === "fill-first") {
+    const eligible = listEligibleCodexAccountIds(config, now, quotaScope).filter(id => id !== excludeId);
+    return pickNextFillFirstCodexAccount(config, excludeId, eligible, now);
+  }
+  return pickLowestUsageCodexAccount(config, excludeId, now, quotaScope);
+}
+
+/** Effective active: automatic runtime cursor, else operator/persisted selection. */
+export function getEffectiveActiveCodexAccountId(config: OcxConfig): string | undefined {
+  return runtimeActiveCodexAccountId ?? config.activeCodexAccountId;
+}
+
+/**
+ * Automatic strategy / failover cursor only — never mutates `config.activeCodexAccountId`
+ * so an unrelated `saveConfig` cannot persist transient rotation as operator selection.
+ */
+function rememberActiveCodexAccount(_config: OcxConfig, accountId: string): void {
+  runtimeActiveCodexAccountId = accountId;
+}
+
+/** Persist operator (or quota-strategy) active selection to config + disk. */
+function setActiveCodexAccount(config: OcxConfig, accountId: string): void {
+  runtimeActiveCodexAccountId = undefined;
+  if (config.activeCodexAccountId === accountId) return;
+  config.activeCodexAccountId = accountId;
+  saveConfigPreservingClaudeCode(config);
+}
+
+/** Quota strategy persists; RR/fill-first keep a process-local cursor only. */
+function promoteActiveCodexAccount(config: OcxConfig, accountId: string): void {
+  if (normalizeAccountPoolStrategy(config.accountPoolStrategy) === "quota") {
+    setActiveCodexAccount(config, accountId);
+    return;
+  }
+  rememberActiveCodexAccount(config, accountId);
+}
+
+/**
+ * Reconcile the effective active account after an administrative exclusion such as pause.
+ * The operator's persisted selection is cleared when it names the excluded account; quota
+ * keeps its historical persisted promotion, while rotating strategies retain the replacement
+ * only in the process-local cursor.
+ */
+export function reconcileCodexActiveAfterExclusion(
+  config: OcxConfig,
+  excludedAccountId: string,
+  now = Date.now(),
+): string | null {
+  const wasEffective = (getEffectiveActiveCodexAccountId(config) ?? MAIN_CODEX_ACCOUNT_ID) === excludedAccountId;
+  if (config.activeCodexAccountId === excludedAccountId) {
+    config.activeCodexAccountId = undefined;
+  }
+  if (!wasEffective) return getEffectiveActiveCodexAccountId(config) ?? null;
+
+  runtimeActiveCodexAccountId = undefined;
+  const fallback = pickAlternateCodexAccount(config, excludedAccountId, now);
+  if (fallback) promoteActiveCodexAccount(config, fallback);
+  return fallback;
+}
+
+function isUnknownUsage(usage: number): boolean {
+  return usage >= CODEX_UNKNOWN_USAGE_SCORE;
+}
+
+function applyQuotaAutoSwitch(
+  config: OcxConfig,
+  active: string,
+  now: number,
+  quotaScope?: CodexQuotaScope,
+): string {
+  const threshold = config.autoSwitchThreshold ?? 80;
+  if (threshold <= 0) return active;
+  const quota = getAccountQuota(active);
+  const activeUsage = computeCodexUsageScore(quota, getPoolAccountPlan(config, active));
+  // Unknown usage is not evidence that a user's explicit selection crossed the
+  // threshold. Wait for quota priming instead of rotating among guesses.
+  if (isUnknownUsage(activeUsage)) return active;
+  if (activeUsage < threshold) return active;
+  const best = pickLowerUsageAccount(config, active, activeUsage, now, quotaScope);
+  if (best !== active) {
+    if (!isIndependentCodexQuotaScope(quotaScope)) setActiveCodexAccount(config, best);
+    return best;
+  }
+
+  return active;
+}
+
+function shouldFailover(config: OcxConfig, accountId: string, now: number): boolean {
+  const threshold = config.upstreamFailoverThreshold ?? 3;
+  if (threshold <= 0) return false;
+  const health = upstreamHealth.get(accountId);
+  if (health?.lastFailureAt && now - health.lastFailureAt > CODEX_FAILURE_WINDOW_MS) return false;
+  return !!health && health.consecutiveFailures >= threshold;
+}
+
+function applyFailureFailover(config: OcxConfig, active: string, now: number): string {
+  if (!shouldFailover(config, active, now)) return active;
+  const best = pickAlternateCodexAccount(config, active, now);
+  if (best) {
+    promoteActiveCodexAccount(config, best);
+    return best;
+  }
+  return active;
+}
+
+export function resolveCodexAccountForThread(
+  threadId: string | null,
+  config: OcxConfig,
+  now = Date.now(),
+  quotaScope?: CodexQuotaScope,
+): string | null {
+  const resolution = resolveCodexAccountForThreadDetailed(threadId, config, now, quotaScope);
+  return resolution.status === "selected" ? resolution.accountId : null;
+}
+
+/**
+ * Side-effect-free preview of the Codex pool account native routing would prefer.
+ * Used for subagent fallback quota decisions before final auth.
+ *
+ * Does not mutate activeCodexAccountId, thread affinity, config on disk, or probe leases.
+ * Mirrors {@link resolveCodexAccountForThreadDetailed} account choice, including returning a
+ * configured cooled account so callers can evaluate probe/quota availability.
+ */
+export function previewCodexAccountForRequest(
+  threadId: string | null,
+  config: OcxConfig,
+  now = Date.now(),
+  quotaScope?: CodexQuotaScope,
+): string | null {
+  const entry = threadId ? getThreadAffinity(threadId, quotaScope) : undefined;
+  if (threadId && entry) {
+    if (
+      !isThreadAffinityExpired(entry, now)
+      && isThreadAffinityGenerationLive(entry)
+      && isCodexAccountSelectable(config, entry.accountId, now, quotaScope)
+      && !shouldFailover(config, entry.accountId, now)
+    ) {
+      // Quota strategy only: non-quota strategies keep affinity for ongoing threads
+      // (new-session-only rotation — docs / affinity policy A).
+      const strategy = normalizeAccountPoolStrategy(config.accountPoolStrategy);
+      if (strategy === "quota") {
+        const threshold = config.autoSwitchThreshold ?? 80;
+        if (threshold > 0) {
+          const usage = computeCodexUsageScore(
+            getAccountQuota(entry.accountId),
+            getPoolAccountPlan(config, entry.accountId),
+          );
+          if (!isUnknownUsage(usage) && usage >= threshold) {
+            const best = pickLowerUsageAccount(config, entry.accountId, usage, now, quotaScope);
+            if (best !== entry.accountId) return best;
+          }
+        }
+      }
+      return entry.accountId;
+    }
+    // Stale/unusable affinity is ignored for preview (no map mutation).
+  }
+
+  const strategyPick = pickUnboundStrategyAccount(config, threadId, now, false, quotaScope);
+  if (strategyPick) return strategyPick;
+
+  let active = getEffectiveActiveCodexAccountId(config) ?? null;
+  if (!active) {
+    return pickLowestUsageCodexAccount(config, undefined, now, quotaScope);
+  }
+  if (!isCodexAccountSelectable(config, active, now, quotaScope)) {
+    const fallback = pickLowestUsageCodexAccount(config, active, now, quotaScope);
+    if (fallback) active = fallback;
+    else if (hasConfiguredPoolAccount(config, active) && !isCodexAccountPaused(config, active)) return active;
+    else return null;
+  }
+
+  const threshold = config.autoSwitchThreshold ?? 80;
+  if (threshold > 0) {
+    const usage = computeCodexUsageScore(getAccountQuota(active), getPoolAccountPlan(config, active));
+    if (!isUnknownUsage(usage) && usage >= threshold) {
+      active = pickLowerUsageAccount(config, active, usage, now, quotaScope);
+    }
+  }
+  if (shouldFailover(config, active, now)) {
+    const best = pickLowestUsageCodexAccount(config, active, now, quotaScope);
+    if (best) active = best;
+  }
+  if (!isCodexAccountUsable(config, active)) {
+    return hasConfiguredPoolAccount(config, active) ? active : null;
+  }
+  if (isCodexAccountPaused(config, active)) return null;
+  if (getCodexQuotaHealthSnapshot(active, quotaScope, now)) {
+    return hasConfiguredPoolAccount(config, active) ? active : null;
+  }
+  return active;
+}
+
+export function resolveCodexAccountForThreadDetailed(
+  threadId: string | null,
+  config: OcxConfig,
+  now = Date.now(),
+  quotaScope?: CodexQuotaScope,
+): CodexThreadResolution {
+  const entry = threadId ? getThreadAffinity(threadId, quotaScope) : undefined;
+  if (threadId && entry) {
+    if (isThreadAffinityExpired(entry, now)) {
+      deleteThreadAffinity(threadId, quotaScope);
+      return { status: "expired", accountId: entry.accountId };
+    }
+    if (
+      isThreadAffinityGenerationLive(entry)
+      && isCodexAccountSelectable(config, entry.accountId, now, quotaScope)
+      // Affined threads must leave a failing account once the streak trips failover
+      // (soft-avoid covers the first-hit case; this catches post-avoid residual streaks).
+      && !shouldFailover(config, entry.accountId, now)
+    ) {
+      entry.lastUsedAt = now;
+      // Periodic quota re-eval: a long-lived bound thread must still switch when
+      // it crosses autoSwitchThreshold and a strictly-cooler account exists.
+      // Without this the reuse branch returns before applyQuotaAutoSwitch and the
+      // thread stays pinned for the full idle TTL (the WSL "never switches" report).
+      // Over-threshold pins re-eval immediately so a depleted primary does not keep
+      // serving for up to 60s after a secondary with quota is available (#584).
+      // Non-quota strategies (RR / fill-first) keep affinity for ongoing threads —
+      // rotation is new-session-only (affinity policy A).
+      const strategy = normalizeAccountPoolStrategy(config.accountPoolStrategy);
+      if (strategy === "quota") {
+        const threshold = config.autoSwitchThreshold ?? 80;
+        const usage = threshold > 0
+          ? computeCodexUsageScore(
+            getAccountQuota(entry.accountId),
+            getPoolAccountPlan(config, entry.accountId),
+          )
+          : 0;
+        const overThreshold = threshold > 0 && !isUnknownUsage(usage) && usage >= threshold;
+        if (overThreshold || now - entry.lastReevalAt >= CODEX_THREAD_AFFINITY_REEVAL_INTERVAL_MS) {
+          entry.lastReevalAt = now;
+          if (overThreshold) {
+            const best = pickLowerUsageAccount(config, entry.accountId, usage, now, quotaScope);
+            if (best !== entry.accountId) {
+              if (!isIndependentCodexQuotaScope(quotaScope)) setActiveCodexAccount(config, best);
+              bindThreadAffinity(threadId, best, now, quotaScope); // rebinds + resets clocks
+              return { status: "selected", accountId: best };
+            }
+          }
+        }
+      }
+      return { status: "selected", accountId: entry.accountId };
+    }
+    deleteThreadAffinity(threadId, quotaScope);
+  }
+
+  const strategyPick = pickUnboundStrategyAccount(config, threadId, now, true, quotaScope);
+  if (strategyPick) return { status: "selected", accountId: strategyPick };
+
+  let active = getEffectiveActiveCodexAccountId(config);
+  if (!active) {
+    const selected = pickLowestUsageCodexAccount(config, undefined, now, quotaScope);
+    if (!selected) return { status: "none" };
+    if (!isIndependentCodexQuotaScope(quotaScope)) setActiveCodexAccount(config, selected);
+    active = selected;
+  }
+  if (!isCodexAccountSelectable(config, active, now, quotaScope)) {
+    const fallback = pickLowestUsageCodexAccount(config, active, now, quotaScope);
+    if (fallback) {
+      if (!isIndependentCodexQuotaScope(quotaScope)) setActiveCodexAccount(config, fallback);
+      active = fallback;
+    } else if (hasConfiguredPoolAccount(config, active) && !isCodexAccountPaused(config, active)) {
+      return { status: "selected", accountId: active };
+    } else {
+      return { status: "none" };
+    }
+  }
+  active = applyQuotaAutoSwitch(config, active, now, quotaScope);
+  active = applyFailureFailover(config, active, now);
+  if (!isCodexAccountUsable(config, active)) {
+    return hasConfiguredPoolAccount(config, active) ? { status: "selected", accountId: active } : { status: "none" };
+  }
+  if (isCodexAccountPaused(config, active)) return { status: "none" };
+  if (getCodexQuotaHealthSnapshot(active, quotaScope, now)) {
+    return hasConfiguredPoolAccount(config, active) ? { status: "selected", accountId: active } : { status: "none" };
+  }
+  if (threadId) bindThreadAffinity(threadId, active, now, quotaScope);
+  return { status: "selected", accountId: active };
+}
+
+export function recordCodexUpstreamOutcome(
+  config: OcxConfig,
+  accountId: string | null,
+  outcome: CodexUpstreamOutcome,
+  meta: CodexUpstreamOutcomeMeta = {},
+): void {
+  if (!accountId) return;
+  const writerGeneration = meta.writerGeneration ?? captureConfigGeneration();
+  if (writerGeneration < lastReconciledGeneration && !liveHealthAccountIds.has(accountId)) return;
+  const now = meta.now ?? Date.now();
+  const outcomeClass = classifyCodexUpstreamOutcome(outcome);
+  const quotaScope = codexQuotaScopeForModel(meta.modelId);
+  if (outcomeClass === "success") {
+    const scopedProbe = meta.probeQuotaScope
+      ? scopedHealthFor(accountId, meta.probeQuotaScope)
+      : undefined;
+    if (scopedProbe && meta.probeQuotaScope) {
+      if (scopedProbe.cooldownUntil && probeMayClearCooldown(scopedProbe, meta)) {
+        deleteScopedHealth(accountId, meta.probeQuotaScope);
+      } else if (ownsProbeLease(scopedProbe, meta)) {
+        setScopedHealth(accountId, meta.probeQuotaScope, withProbeLeaseReleased(scopedProbe, now));
+      }
+    }
+    const current = upstreamHealth.get(accountId);
+    const cooldownUntil = getCodexAccountCooldownUntil(accountId, now);
+    // A leased probe that is still on its own cooldown generation proves the
+    // account recovered: clear the hard cooldown outright (#433).
+    if (cooldownUntil && probeMayClearCooldown(current, meta)) {
+      upstreamHealth.delete(accountId);
+      return;
+    }
+    // Owning probe on a stale generation: the lease is done, but a newer 429
+    // replaced the cooldown in the meantime, so only give the lease back.
+    // Non-owners keep every hard-cooldown field, including someone else's live lease.
+    const base = ownsProbeLease(current, meta) ? withProbeLeaseReleased(current!, now) : current;
+    const preserved = preservedCooldownFields(base);
+    const failoverEnabled = (config.upstreamFailoverThreshold ?? 3) > 0;
+    if (failoverEnabled && current && current.consecutiveFailures >= 2) {
+      const consecutiveSuccesses = (current.consecutiveSuccesses ?? 0) + 1;
+      if (consecutiveSuccesses < 2) {
+        upstreamHealth.set(accountId, {
+          ...base!,
+          ...preserved,
+          consecutiveSuccesses,
+        });
+        return;
+      }
+    }
+    // Level 1 clears immediately; escalated accounts need two consecutive healthy terminals.
+    // Hard quota cooldown intentionally survives either recovery path.
+    if (cooldownUntil) upstreamHealth.set(accountId, { consecutiveFailures: 0, ...preserved });
+    else upstreamHealth.delete(accountId);
+    return;
+  }
+  if (outcomeClass === "caller") {
+    // A 4xx does not change account health, but it does conclude an in-flight
+    // probe — otherwise the lease would never be handed back.
+    const current = upstreamHealth.get(accountId);
+    const scopedProbe = meta.probeQuotaScope
+      ? scopedHealthFor(accountId, meta.probeQuotaScope)
+      : undefined;
+    if (scopedProbe && meta.probeQuotaScope && ownsProbeLease(scopedProbe, meta)) {
+      setScopedHealth(accountId, meta.probeQuotaScope, withProbeLeaseReleased(scopedProbe, now));
+    }
+    if (ownsProbeLease(current, meta)) {
+      upstreamHealth.set(accountId, withProbeLeaseReleased(current!, now));
+    }
+    return;
+  }
+
+  const lastFailureStatus = typeof outcome === "number" ? outcome : 0;
+  if (outcomeClass === "credential") {
+    // 401/403 quarantines the account for reauth. That supersedes quota state
+    // entirely: a cooldown (and any probe lease) on an unusable account is moot.
+    upstreamHealth.set(accountId, {
+      consecutiveFailures: 1,
+      lastFailureStatus,
+      lastFailureAt: now,
+    });
+    quotaScopedHealth.delete(accountId);
+    markAccountNeedsReauth(accountId, writerGeneration);
+    clearThreadAccountMapForAccount(accountId);
+    return;
+  }
+
+  if (outcomeClass === "quota") {
+    const { until, source } = computeQuotaCooldown(meta);
+    // A reset timestamp is an advisory quota-window announcement. When the
+    // selected native model belongs to a confirmed independent group, preserve
+    // it there so a different group (Spark versus the shared native quota) can
+    // still reach upstream. Explicit Retry-After/default 429s remain account-wide.
+    if (source === "reset-derived" && quotaScope) {
+      const prior = scopedHealthFor(accountId, quotaScope);
+      const cooldownGeneration = (prior?.cooldownGeneration ?? 0) + 1;
+      const ownsLease = meta.probeQuotaScope === quotaScope && ownsProbeLease(prior, meta);
+      setScopedHealth(accountId, quotaScope, {
+        consecutiveFailures: 0,
+        lastFailureStatus,
+        lastFailureAt: now,
+        cooldownUntil: until,
+        cooldownSince: now,
+        cooldownSource: source,
+        cooldownGeneration,
+        ...(ownsLease
+          ? { lastProbeAt: now }
+          : {
+            ...(prior?.probeLeaseId !== undefined ? { probeLeaseId: prior.probeLeaseId } : {}),
+            ...(prior?.probeLeaseGeneration !== undefined ? { probeLeaseGeneration: prior.probeLeaseGeneration } : {}),
+            ...(prior?.lastProbeAt !== undefined ? { lastProbeAt: prior.lastProbeAt } : {}),
+        }),
+      });
+      // The shared native scope is the existing account-wide native behavior:
+      // threads must leave it and new requests should prefer an eligible account.
+      // Spark remains isolated so a same-account Terra/Luna combo fallback can run.
+      if (quotaScope === "shared") {
+        clearThreadAccountMapForAccount(accountId);
+        notePoolRotationFailure(POOL_KEY_CODEX, accountId);
+        if (getEffectiveActiveCodexAccountId(config) === accountId) {
+          // Same-request 429 retry already picked via excludeAccountId — reuse it so
+          // round-robin does not advance the ring a second time.
+          const reused = meta.promoteAccountId && meta.promoteAccountId !== accountId
+            ? meta.promoteAccountId
+            : null;
+          const fallback = reused ?? pickAlternateCodexAccount(config, accountId, now, quotaScope);
+          if (fallback) promoteActiveCodexAccount(config, fallback);
+        }
+      }
+      return;
+    }
+
+    // A scoped probe that received an account-wide throttle is no longer live.
+    const scopedProbe = meta.probeQuotaScope
+      ? scopedHealthFor(accountId, meta.probeQuotaScope)
+      : undefined;
+    if (scopedProbe && meta.probeQuotaScope && ownsProbeLease(scopedProbe, meta)) {
+      setScopedHealth(accountId, meta.probeQuotaScope, withProbeLeaseReleased(scopedProbe, now));
+    }
+    const prior = upstreamHealth.get(accountId);
+    // Every cooldown write bumps the generation so a probe issued against the
+    // previous cooldown can no longer clear this one (#433).
+    const cooldownGeneration = (prior?.cooldownGeneration ?? 0) + 1;
+    // A failed probe concludes its lease; an unrelated 429 leaves the live probe alone.
+    const ownsLease = ownsProbeLease(prior, meta);
+    upstreamHealth.set(accountId, {
+      consecutiveFailures: 0,
+      lastFailureStatus,
+      lastFailureAt: now,
+      cooldownUntil: until,
+      cooldownSince: now,
+      cooldownSource: source,
+      cooldownGeneration,
+      ...(ownsLease
+        ? { lastProbeAt: now }
+        : {
+          ...(prior?.probeLeaseId !== undefined ? { probeLeaseId: prior.probeLeaseId } : {}),
+          ...(prior?.probeLeaseGeneration !== undefined ? { probeLeaseGeneration: prior.probeLeaseGeneration } : {}),
+          ...(prior?.lastProbeAt !== undefined ? { lastProbeAt: prior.lastProbeAt } : {}),
+        }),
+    });
+    clearThreadAccountMapForAccount(accountId);
+    notePoolRotationFailure(POOL_KEY_CODEX, accountId);
+    const effectiveActive = getEffectiveActiveCodexAccountId(config);
+    if (effectiveActive === accountId) {
+      // Same-request 429 retry already picked via excludeAccountId — reuse it so
+      // round-robin does not advance the ring a second time.
+      const reused = meta.promoteAccountId && meta.promoteAccountId !== accountId
+        ? meta.promoteAccountId
+        : null;
+      const fallback = reused ?? pickAlternateCodexAccount(config, accountId, now);
+      if (fallback) promoteActiveCodexAccount(config, fallback);
+    }
+    return;
+  }
+
+  // transient (connect_error / timeout / 5xx)
+  const current = upstreamHealth.get(accountId);
+  const scopedProbe = meta.probeQuotaScope
+    ? scopedHealthFor(accountId, meta.probeQuotaScope)
+    : undefined;
+  if (scopedProbe && meta.probeQuotaScope && ownsProbeLease(scopedProbe, meta)) {
+    setScopedHealth(accountId, meta.probeQuotaScope, withProbeLeaseReleased(scopedProbe, now));
+  }
+  // A transient failure concludes an owning probe; an unrelated 5xx must not
+  // consume someone else's live lease or drop hard-cooldown bookkeeping (#433).
+  const transientBase = ownsProbeLease(current, meta) ? withProbeLeaseReleased(current!, now) : current;
+  const stale = current?.lastFailureAt ? now - current.lastFailureAt > CODEX_FAILURE_WINDOW_MS : false;
+  const hardCooldownUntil = getCodexAccountCooldownUntil(accountId, now) ?? undefined;
+  // Soft avoid + affinity clears are part of failover. When threshold is 0, leave
+  // sticky sessions alone (same as shouldFailover / applyFailureFailover no-ops).
+  const failoverThreshold = config.upstreamFailoverThreshold ?? 3;
+  const consecutiveFailures = stale ? 1 : (current?.consecutiveFailures ?? 0) + 1;
+  const failoverReady = failoverThreshold > 0 && consecutiveFailures >= failoverThreshold;
+  const escalationMs = CODEX_TRANSIENT_SOFT_AVOID_ESCALATION_MS[
+    Math.min(Math.max(consecutiveFailures - failoverThreshold, 0), CODEX_TRANSIENT_SOFT_AVOID_ESCALATION_MS.length - 1)
+  ]!;
+  const softAvoidUntil = failoverReady
+    ? Math.max(
+      getCodexAccountSoftAvoidUntil(accountId, now) ?? 0,
+      now + escalationMs,
+    )
+    : undefined;
+  upstreamHealth.set(accountId, {
+    ...preservedCooldownFields(transientBase),
+    consecutiveFailures,
+    lastFailureStatus,
+    lastFailureAt: now,
+    ...(hardCooldownUntil ? { cooldownUntil: hardCooldownUntil } : {}),
+    ...(softAvoidUntil !== undefined ? { softAvoidUntil } : {}),
+  });
+  // Drop this thread's pin immediately so the next continue can rebind without
+  // waiting for the soft-avoid selectable check. Guard: only delete when the
+  // thread is still pinned to the FAILING account — a late failure from account A
+  // must not delete a newer healthy binding to account B (race: T→A, A fails,
+  // T→B, late A failure must not delete B's mapping).
+  if (failoverReady && meta.threadId) {
+    deleteThreadAffinitiesForAccount(meta.threadId, accountId);
+  }
+  // Once the account is past the failover streak, clear every thread still pinned
+  // to it — matching 429 affinity behavior so "continue" cannot stay on a bad peer.
+  if (shouldFailover(config, accountId, now)) {
+    clearThreadAccountMapForAccount(accountId);
+  }
+  if (getEffectiveActiveCodexAccountId(config) === accountId) applyFailureFailover(config, accountId, now);
+}
+
+export function formatCodexProviderForLog(providerName: string, accountId: string | null, config: OcxConfig): string {
+  if (!accountId) return providerName;
+  // The main Codex login participates in rotation as "main-pool" (MAIN_CODEX_ACCOUNT_ID) but is the
+  // same physical account as the "main" passthrough (null accountId). Log both under the base provider
+  // name so usage/tokens aggregate into a single row instead of splitting into `chatgpt` + `chatgpt-main`.
+  if (accountId === MAIN_CODEX_ACCOUNT_ID) return providerName;
+  const account = (config.codexAccounts ?? [])
+    .find(candidate => isSelectableCodexPoolAccount(candidate) && candidate.id === accountId);
+  return account ? `${providerName}-${codexAccountLogLabel(account)}` : providerName;
+}