fix(background-agent): skip unavailable fallback models

[kywoo26]

Summary

• skip fallback candidates that are not available in the current runtime model catalog
• use the runtime's connected-provider model cache when selecting fallback candidates
• keep the existing provider-based behavior when no model cache is available

Changes

• update model-fallback candidate selection to prefer runtime-available fallback models
• update background fallback retry selection to do the same
• add targeted test coverage for unavailable fallback candidate handling

Testing

bun test src/features/background-agent/fallback-retry-handler.test.ts src/features/background-agent/manager.polling.test.ts src/features/background-agent/session-idle-event-handler.test.ts
bun run typecheck
bun run build

Manual validation:

• reproduced unavailable fallback attempts in a no-override local setup
• confirmed the patched selection skips unavailable candidates instead of attempting them

Related Issues

Closes #3400

---

Summary by cubic

Skip fallback models that aren’t available at runtime to avoid wasted background-agent retries. Use the provider-model cache to pick the first available fallback and prefer the connected preferred provider when possible; fall back to the old provider-based logic when no cache is present.

• Bug Fixes
  • Prefer runtime-available models using the provider-model cache; skip unavailable candidates.
  • Prefer the connected preferred provider when the model exists in cache; fall back to provider-based selection when no cache.
  • Apply the same logic in background retries and the model-fallback hook; add targeted tests.
  • Closes [Bug]: background fallback retries models that are not available in the current runtime #3400.

^{Written for commit 77d86f2. Summary will update on new commits.}

[github-actions]

All contributors have signed the CLA. Thank you! ✅
_{Posted by the CLA Assistant Lite bot.}

[kywoo26]

I have read the CLA Document and I hereby sign the CLA

[cubic-dev-ai]

1 issue found across 3 files

Confidence score: 3/5

• There is a concrete behavior risk in src/features/background-agent/fallback-retry-handler.ts: availability resolution can ignore the connected preferred provider path, which may skip valid fallback providers when cache data is present.
• Given the issue is medium severity (6/10) with high confidence (8/10) and affects fallback selection logic, this introduces a real chance of user-facing reliability regressions.
• Pay close attention to src/features/background-agent/fallback-retry-handler.ts - ensure preferred-provider and cached-availability paths are reconciled so valid fallbacks are not skipped.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/features/background-agent/fallback-retry-handler.ts">

<violation number="1" location="src/features/background-agent/fallback-retry-handler.ts:90">
P2: Availability resolution ignores the connected preferred provider path, so valid fallbacks can be skipped when cache data exists.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

0 issues found across 4 files (changes from recent commits).

_{Auto-approved: Fixes wasted fallback retries by checking model availability against the runtime cache. Includes targeted test coverage and maintains legacy behavior when cache is unavailable.}