[Feature]: Fail over to another logged-in account on 429 for any OAuth provider with 2+ accounts, not just Codex and opt-in Anthropic #2568

Area

Authentication and account pool

What are you trying to accomplish?

When I have more than one logged-in account for a provider, I want a 429 to fail over to another account of the SAME provider automatically, without first discovering and enabling a provider-specific opt-in toggle.

Today my ocx account list looks like this (masked):

PROVIDER             TYPE     ID          STATUS
openai               codex    main        selected
openai               codex    chatgpt-…   -
xai                  oauth    f49f684e    -
xai                  oauth    43b56558…   active
xai                  oauth    3488ef5e…   -
anthropic            oauth    1278f8da    -
anthropic            oauth    e112f28b    active
anthropic            oauth    b245be97…   -
google-antigravity   oauth    39d5ad0e    active
cursor               oauth    c78c4427…   active

Three xAI accounts are logged in. When the active xAI account returns 429, the request fails and the other two idle accounts are never tried. The credentials are already stored, already valid, and already selectable by hand with ocx account use xai <id> — the proxy just does not reach for them on a rate limit.

What prevents this today?

Same-provider 429 failover exists, but only on three disjoint paths, and OAuth multi-account failover is implemented for exactly one provider:

1. API-key pools — hasKeyPoolFailover / rotateKeyOn429 in key-failover.ts. Works for any key-auth provider with 2+ pool keys, and it is on by default. hasKeyPoolFailover returns false for authMode === "oauth", so no OAuth account ever enters this loop.
2. Codex/OpenAI pool — the account-cooldown and alternate-selection machinery in routing.ts (excludeAccountId, same-request 429 retry, quota cooldowns). Rich, but bound to the Codex pool ledger (codex-accounts.json) and codexAccountMode: "pool".
3. Anthropic OAuth pool — rotateAnthropicAccountOn429 in anthropic-routing.ts, driven from core.ts. It is gated behind isAnthropicAccountPoolEnabled(config) and its doc comment states "Default OFF".

So the failover ladder has a hole exactly where the user's mental model says it should not: xAI, Cursor, Kimi, GitHub Copilot, Google Antigravity, and Nous all store multiple OAuth accounts through the same multiauth store (store.ts, listAccounts(provider)), and none of them rotate on 429. The generic OAuth multiauth store already has everything the rotation needs — a per-provider account list, a stable activeAccountId, per-account credentials, and a needsReauth flag — but no consumer walks it on a rate limit.

Two secondary gaps make this worse:

• The Anthropic pool is off by default even when the user has visibly logged in three Anthropic accounts. A user who takes the trouble to add a second account has already expressed the intent that a pool is meant to capture; the opt-in re-asks a question the login already answered.
• retryOn429 (rateLimitRetryPolicyFor) deliberately returns null for OAuth providers — correct, since replaying on the same token is pointless — but nothing takes its place for OAuth. The result is that an OAuth 429 has no recovery path at all unless it is Codex or opted-in Anthropic.

What should OpenCodex do?

Generalize same-provider 429 account failover to every provider whose OAuth account set has 2 or more eligible accounts, with the number of stored accounts as the activation signal:

1. On a 429 from an OAuth provider, cool the account that actually failed (honouring Retry-After, falling back to a default backoff), pick the next eligible account from listAccounts(provider) skipping cooled and needsReauth entries, mint its access token, and replay the same request. Bound the rotations per request the way ANTHROPIC_POOL_MAX_FAILOVERS_PER_REQUEST already does.
2. Make it active whenever the provider has 2+ eligible accounts, matching how hasKeyPoolFailover treats a 2+ key pool as consent. A single-account provider stays a strict no-op, so nothing changes for the common case.
3. Keep the Codex pool exactly as it is. It has quota scopes, probe leases, and affinity semantics that a generic rotator must not attempt to replicate; the generic path should apply to non-Codex OAuth providers only.
4. Keep an explicit escape hatch: a config knob (for example oauthAccountFailover: { enabled: false } or a per-provider override) so an operator with a ToS concern can force single-account behaviour. Anthropic's existing anthropicAccountPool.enabled should keep winning where it is set explicitly, so no current configuration changes meaning.
5. Preserve session affinity where a provider already has it, and do not carry an in-flight request's chosen account across the rotation boundary in a way that breaks prompt caching more than the 429 already did.

Observable result: with three xAI accounts logged in, a 429 on the active account is retried on the next eligible one and the request succeeds instead of surfacing the rate limit to the client.

Example usage or interface

Before (today), with three xAI OAuth accounts stored:

$ ocx account list xai
xai  oauth  f49f684e   -
xai  oauth  43b56558…  active
xai  oauth  3488ef5e…  -

# active account hits its limit
→ client receives 429; f49f684e and 3488ef5e are never attempted

After:

[oauth-failover] xai: 429 on account 43b56558; rotating to account f49f684e
→ same request replayed on f49f684e, 200 returned to the client

Opt-out for an operator who wants strict single-account behaviour:

{
  "providers": {
    "xai": {
      "oauthAccountFailover": { "enabled": false }
    }
  }
}

Alternatives or workarounds

• Manually run ocx account use xai <other-id> after every rate limit. Works, but it is a human in the retry loop, and by the time the user notices, the client has already surfaced the error.
• Enable anthropicAccountPool — helps Anthropic only; there is no equivalent for xAI, Cursor, Kimi, Copilot, Antigravity, or Nous.
• Convert an OAuth provider to an API-key provider so the key pool path applies. Not possible for subscription-backed OAuth providers, which is precisely where users keep multiple accounts.
• Use a combo (combo/<id>) with failover strategy. That fails over across provider/model targets, not across accounts of one provider, and it changes the model identity of the request.

Additional context

Related prior art in this repository:

• [Feature]: Claude account pool — parity with ChatGPT/Codex multi-account routing #294 — the Anthropic OAuth account pool that this proposal generalizes.
• Multi-account failover issue: Session freezes on depleted primary account despite active secondary Pro account #584 — alternate-account retry on the Codex side.
• Subagent fallback can reuse the wrong Pool account across model quota scopes #2509 — subagent fallback reusing the wrong pool account across model quota scopes; relevant because a generic rotator must not repeat that mistake.
• [Feature]: Allow Anthropic account-pool quota routing to select by weekly usage #2539 — extending Anthropic pool quota routing to weekly usage; same subsystem.

Design notes: getEligibleAnthropicAccounts, rotateAnthropicAccountOn429, and getAnthropicPoolAccessToken in anthropic-routing.ts are already written against generic primitives (listAccounts, getAccountCredential, setActiveAccount, pool-rotation.ts). The provider-specific parts are the constant PROVIDER = "anthropic", the config gate, and the token minting — which suggests the generalization is mostly a parameterization rather than a new subsystem.

ToS consideration worth deciding explicitly in review: automatic rotation across subscription accounts is more sensitive than rotating API keys, which is why the Anthropic pool shipped opt-in. The counter-argument for making it presence-driven is that logging in a second account is itself the operator's decision, and the opt-out knob preserves the strict behaviour for anyone who wants it.

Checks

• I searched existing issues and documentation.
• This request describes a concrete OpenCodex workflow rather than merely naming a desired technology.
• I removed secrets and personal data.