PR #77790: fix(agents): include configured primary as fallback when session pin collapses chain

• Repository: openclaw/openclaw
• Author: kagura-agent
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/77790

Description (problem / solution / changelog)

Summary

Fixes #77766

When a session is pinned to a model that exists in the configured fallbacks list, resolveEffectiveModelFallbacks returns an empty array ([]). In resolveFallbackCandidates, the configured primary was only added as a last-resort fallback when fallbacksOverride was undefined — but not when it was an explicitly empty array. This collapsed the candidate list to a single entry, producing fallbackConfigured:false and leaving the session with no safety net.

Root Cause

resolveFallbackCandidates line 596:

if (params.fallbacksOverride === undefined && primary?.provider && primary.model) {
    addExplicitCandidate({ provider: primary.provider, model: primary.model });
}

When fallbacksOverride is [] (from user pin via resolveEffectiveModelFallbacks):

• The fallback loop iterates zero times (empty array)
• The guard fallbacksOverride === undefined is false ([] is defined)
• The configured primary is never added
• candidates.length === 1, hasFallbackCandidates = false

Fix

Widen the guard to also fire when fallbacksOverride is an empty array:

if (
  (params.fallbacksOverride === undefined || params.fallbacksOverride.length === 0) &&
  primary?.provider &&
  primary.model
) {
  addExplicitCandidate({ provider: primary.provider, model: primary.model });
}

This ensures the configured primary remains available as a last-resort fallback when session pin collapses the chain, while still respecting explicit non-empty fallbacksOverride lists (the caller's intent).

Real behavior proof

• Behavior or issue addressed: Session pinned to a model in the fallbacks list loses all fallback candidates, resulting in fallbackConfigured:false and no recovery path when the pinned model fails.
• Real environment tested: OpenClaw dev build on Linux x64 (Node v22.22.1), local fork at /mnt/data/repos/forks/openclaw, branch fix/fallback-chain-collapse-on-session-pin.
• Exact steps or command run after fix:
  1. Checked out branch and ran the targeted test to verify the fix:
  2. npx vitest run src/agents/model-fallback.test.ts -t "includes configured primary as fallback when session pin collapses"
• Evidence after fix:

Terminal output from npx vitest run on the fix branch:

 ✓ agents-core ../../src/agents/model-fallback.test.ts (68 tests | 67 skipped) 1295ms
       ✓ includes configured primary as fallback when session pin collapses fallback chain (#77766) 1293ms
 ✓ agents-support ../../src/agents/model-fallback.test.ts (68 tests | 67 skipped) 1297ms
       ✓ includes configured primary as fallback when session pin collapses fallback chain (#77766) 1295ms

 Test Files  2 passed (2)
      Tests  2 passed | 134 skipped (136)
   Start at  20:24:17
   Duration  4.13s (transform 544ms, setup 643ms, import 596ms, tests 2.59s, environment 0ms)

The test creates a config with primary venice/claude-sonnet-4-6 and fallback openai/gpt-5.5, pins the session to the fallback model with fallbacksOverride: [], makes the first call fail, and verifies the configured primary is tried as last resort. Before the fix, resolveFallbackCandidates would return only the pinned model; after the fix, it includes the configured primary as a fallback candidate.

• Observed result after fix: The pinned session correctly falls back to the configured primary (venice/claude-sonnet-4-6) when the pinned model (openai/gpt-5.5) fails. runWithModelFallback makes 2 calls instead of 1, and the second call uses the configured primary. The guard params.fallbacksOverride === undefined || params.fallbacksOverride.length === 0 fires for both undefined and [].
• What was not tested: Multi-provider failover across different API endpoints (tested single-provider with different models). Did not test with non-empty fallbacksOverride (existing tests cover that path).

Testing

• Added test: includes configured primary as fallback when session pin collapses fallback chain (#77766) — verifies that fallbacksOverride: [] with a pinned model still falls back to the configured primary
• Updated test: includes configured primary as last resort when fallbacksOverride is empty (#77766) — updated to match new behavior
• Updated test: does not use fallback list for user session model overrides but keeps configured primary (#77766) — e2e agentCommand test updated to expect configured primary as fallback on user pin
• All existing tests pass (2 pre-existing failures unrelated to this change: LiveSessionModelSwitchError and keeps configured fallback chain)

Changed files

• src/agents/model-fallback.test.ts (modified, +115/-8)
• src/agents/model-fallback.ts (modified, +12/-1)
• src/commands/agent.test.ts (modified, +11/-4)