[Feature]: fair session ring across Anthropic OAuth, API keys, and Codex API pools #8178

Area

Authentication and account pool

What are you trying to accomplish?

We want fair, session-pinned rotation for new sessions across Anthropic OAuth accounts, Anthropic API-key pool entries, and Codex pool accounts. One session should stay on one credential while new sessions are spread evenly. This should work for Claude Code and Codex API clients.

What prevents this today?

Round-robin chooses a new account per request, and affinity only binds after a session key exists. There is no shared ring that assigns new sessions fairly and keeps each session pinned across the Anthropic OAuth pool, single-key Anthropic providers, and the Codex pool. Existing pieces are partial:

• Anthropic OAuth affinity persists bindings (src/oauth/anthropic-session-affinity-store.ts).
• The Claude Messages bridge now has a pool session (src/server/claude-bridge-pool-session.ts).
• Codex pool pins survive restarts (fix(codex): keep Codex pool session pins across proxy restarts #8098).
• API-key cache affinity is proposed in feat(providers): provider cache affinity for multi-key routes #7738.
• None of these provides one fair ring across those credential families, including Codex API clients.

We run a local anthropic-session-ring patch for the Anthropic side and want to retire it once upstream provides the behavior.

What should OpenCodex do?

Add an opt-in per-provider session ring:

• Maintain an ordered ring of eligible credentials.
• Assign each new session to the next eligible credential.
• Keep the session on that credential across turns and proxy restarts.
• On a credential failure, cooldown, pause, reauthentication, or removal, advance the ring and rebind once.
• Preserve existing bindings and quota rules.
• Include Anthropic OAuth accounts, Anthropic API-key pool entries, and Codex pool accounts (Codex API/Responses).
• Use a bounded idle TTL and entry cap.
• Expose the selected credential and ring position in request logs or diagnostics.

Example usage or interface

{
  "providers": {
    "anthropic": {
      "sessionRing": { "enabled": true, "idleTtlMs": 86400000 }
    },
    "codex": {
      "sessionRing": { "enabled": true, "idleTtlMs": 86400000 }
    }
  }
}

ocx account pool anthropic --session-ring on
ocx account pool codex --session-ring on

Alternatives or workarounds

Round-robin without a ring moves a session between accounts. Affinity alone does not spread new sessions fairly across credential types. Running one credential per proxy instance avoids the problem but loses pool capacity.

Additional context

Related: #3375 (generic OAuth pool lifecycle), #7738 (API-key cache affinity), #8098 (Codex pool pins across restart), #8092 (round-robin quota headroom), #7813 (Anthropic affinity persistence). This request is the fair ring plus one-session-one-credential contract, including Codex API.

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.