Summary

Fixes #22277. Adds agent.eager_fallback_on_timeout config flag (default false). When true AND fallback_providers is configured, a classified FailoverReason.timeout immediately activates the next fallback provider instead of retrying the same broken primary.

The bug

run_agent.py:13035-13059 already implements eager fallback for rate-limit and billing errors. But timeouts (typically a stale-detector-killed hung stream) classify as FailoverReason.timeout with retryable=True, and the retry loop just re-hits the same broken provider. With ~5 min stale-kill threshold × N retries, this compounds into the 15+ min silent hang documented in the issue.

The configured fallback chain sits idle the entire time.

Fix

Mirror the existing rate-limit eager-fallback block, gated behind a new opt-in flag:

is_timeout_eager = (
    classified.reason == FailoverReason.timeout
    and self._eager_fallback_on_timeout
    and self._fallback_index < len(self._fallback_chain)
)
if is_timeout_eager:
    self._emit_status("⚠️ Provider stalled (stream/call timeout) — switching to fallback provider...")
    if self._try_activate_fallback(reason=classified.reason):
        retry_count = 0
        compression_attempts = 0
        primary_recovery_attempted = False
        continue

Default false to preserve historical behavior; users with paid primaries + OAuth-backed fallbacks (the motivating case: Anthropic + openai-codex) opt in.

Config loaded via hermes_cli.config.load_config() rather than the cached cli.CLI_CONFIG to avoid the staleness issue addressed by #18947.

Files

• run_agent.py — _eager_fallback_on_timeout instance flag + new eager-fallback block
• hermes_cli/config.py — agent.eager_fallback_on_timeout: False schema entry with doc comment
• tests/run_agent/test_eager_fallback_on_timeout.py — 9 new tests

Tests

pytest tests/run_agent/test_eager_fallback_on_timeout.py — 9 passed:

• TestEagerFallbackConfigDefaults — default false, explicit false/true, truthy-int coercion
• TestEagerFallbackOnTimeoutGate — gate predicate fires iff reason==timeout AND flag AND chain has room; does not fire for unknown/server_error/format_error/thinking_signature

Existing fallback suite still green:

pytest tests/run_agent/test_provider_fallback.py tests/run_agent/test_fallback_model.py — 47 passed.

Notes

• The full retry-loop path is a 700-line inline block that's hard to drive end-to-end in unit tests; the gate predicate is asserted directly. Happy to add an integration test if reviewers want one.
• I did NOT change behavior on FailoverReason.connection (clean socket drops). Those still go through the normal retry-with-backoff path. Could be a follow-up.
• Symmetric to [Bug]: All openai-codex / gpt-5.5 primary calls hang silently for full stale timeout #21444's territory but the inverse direction: that issue is about Codex-as-primary stalling; this is about any-provider-as-primary stalling while a fallback exists.

Fixes #22277