Summary

Fixes #27719 — NameError: name '_pool_may_recover_from_rate_limit' is not defined when the eager rate-limit fallback path fires.

Root cause

agent/conversation_loop.py calls _pool_may_recover_from_rate_limit(...) at the rate-limit/billing fallback branch (~L2254), but the helper is defined in run_agent.py and was never imported into agent/conversation_loop.py.

So whenever a primary provider returned a 429/quota error and a fallback chain was configured (e.g. DeepSeek exhausted → OpenRouter fallback as in the issue), the code crashed with NameError instead of switching to the fallback provider.

grep confirms the missing reference:

agent/conversation_loop.py:2254:  pool_may_recover = _pool_may_recover_from_rate_limit(...)
run_agent.py:239: def _pool_may_recover_from_rate_limit(...)   ← defined here

Fix

Use a lazy local import right above the call site:

from run_agent import _pool_may_recover_from_rate_limit
pool_may_recover = _pool_may_recover_from_rate_limit(...)

Why lazy: run_agent.py already imports extensively from agent/* (including agent.conversation_loop), so a top-level from run_agent import ... would create a circular import. The lazy import runs only when the rate-limit fallback branch is hit, which is a cold path.

Test

Added tests/agent/test_fallback_pool_recover_import.py with two checks:

1. _pool_may_recover_from_rate_limit is callable from run_agent and None short-circuits to False.
2. AST scan of agent/conversation_loop.py confirms an explicit from run_agent import _pool_may_recover_from_rate_limit exists — so the historical NameError cannot silently regress.

$ pytest tests/agent/test_fallback_pool_recover_import.py \
         tests/run_agent/test_provider_fallback.py \
         tests/agent/test_gemini_fast_fallback.py -q
30 passed in 12.59s

Scope

• agent/conversation_loop.py — 1 line added (lazy import)
• tests/agent/test_fallback_pool_recover_import.py — new regression test