Feature request: quota-aware fallback between configured model providers

### What variant of Codex are you using?

Codex CLI/TUI 0.144.1.

What feature would you like to see?

Add an opt-in, quota-aware fallback policy between configured model providers.

The primary use case is:

1. Prefer the official ChatGPT/OpenAI provider.
2. Monitor the structured 5-hour and weekly ChatGPT usage windows.
3. If either window is exhausted, continue on a separately authenticated fallback provider.
4. Track every exhausted window and its resets_at value.
5. Return to the primary provider only after all exhausted windows are available again.
6. Allow manual auto, primary, and fallback overrides.

This should be provider failover, not generic HTTP retry and not localized error-string matching.

Why native support is needed

Codex already exposes the required structured data through RateLimitSnapshot, UsageLimitReachedError, and app-server account/rateLimits/read / account/rateLimits/updated.

An external wrapper can switch files and resume a session, but it cannot safely provide:

• provider-scoped credential selection;
• exact same-turn retry;
• protection against duplicate tool side effects;
• reliable config/auth reload in every Codex surface;
• consistent TUI, exec, IDE, and app-server transition events.

Proposed configuration

One possible shape:

[provider_failover]
mode = "auto"
primary = "openai"
fallbacks = ["fallback-provider"]
fallback_on = ["chatgpt_usage_limit"]
restore = "when_all_exhausted_windows_reset"
max_turn_retries = 1

[model_providers.fallback-provider]
name = "Fallback provider"
base_url = "https://provider.example.invalid"
wire_api = "responses"
env_key = "FALLBACK_PROVIDER_API_KEY"
requires_openai_auth = false

The exact schema is open for discussion.

Required state behavior

PrimaryAvailable
  -> PrimaryLimited(exhausted windows + reset timestamps)
  -> FallbackActive
  -> ProbePrimary
  -> PrimaryAvailable

If both the 5-hour and weekly windows are exhausted, the primary provider must not be restored at the earlier reset. Recovery should wait until every exhausted window has reset and a structured probe confirms availability.

Manual override should be independent of automatic state:

Auto | ForcePrimary | ForceFallback(provider_id)

Authentication and security

Provider credentials must be isolated.

• Never send ChatGPT bearer or refresh tokens to a custom provider URL.
• A fallback is eligible only if its own credential can be resolved.
• Missing fallback auth should fail closed with a clear diagnostic.
• Transition logs may contain provider IDs and reasons, but never credentials.

Turn retry safety

• Retry the same turn automatically only when no assistant output or tool side effect has been committed.
• If side effects already occurred, preserve the thread and resume from an explicit continuation boundary.
• Bound all failover and recovery loops.

User-visible behavior

Codex should report transitions concisely:

Primary provider usage limit reached; switched to "fallback-provider".

Primary provider quota is available again; switched back to "openai".

/status and app-server status should expose the provider mode, active provider, transition reason, exhausted windows, and next probe/reset time.

Acceptance criteria

• [ ] Primary remains active while all applicable quota windows are available.
• [ ] Exhausting either the 5-hour or weekly window activates fallback.
• [ ] Multiple exhausted windows use strict all-window recovery.
• [ ] Recovery uses structured rate-limit data.
• [ ] Manual auto/primary/fallback overrides work.
• [ ] Credentials are provider-scoped and never cross provider boundaries.
• [ ] Same-turn retry is bounded and does not duplicate committed side effects.
• [ ] Existing behavior is unchanged when failover is not configured.

Related issues

• #20310: scriptable usage-limit status.
• #21073: auto-resume after a usage-limit reset.

This request is different: it continues immediately on another independently authenticated provider, then restores the preferred provider after quota recovery.

Reference implementation

A sanitized external proof of concept is available in a current fork:

https://github.com/guangxiangdebizi/codex/tree/main/tools/provider-switcher

It validates the two-window state machine, structured app-server probing, manual overrides, automatic recovery, and Windows process/session resumption. Native support is still required for secure provider-scoped auth and exact turn-level failover.