PR #59959: fix: preserve selected session model after fallback

• Repository: openclaw/openclaw
• Author: neeravmakwana
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/59959

Description (problem / solution / changelog)

Summary

• Problem: session control paths and the session list kept preferring persisted runtime model fields after a fallback run, so a fallback model could look like the selected model and stick across follow-up control operations.
• Why it matters: after one fallback, switching or resetting a session could continue to reflect the fallback model instead of the configured primary or explicit session override.
• What changed: resolveSessionModelRef() and resolveLiveSessionModelSelection() now prefer explicit session overrides ahead of runtime model fields, and sessions.list now surfaces the selected override model while preserving runtime identity behavior when no override exists.
• What did NOT change (scope boundary): this PR does not redesign fallback notices or add separate selected-vs-active model fields to the gateway session payload.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #59928
• Related #59928
• This PR fixes a bug or regression

Root Cause / Regression History (if applicable)

• Root cause: src/gateway/session-utils.ts resolved the effective session model by preferring persisted runtime fields before session overrides, and src/agents/live-model-switch.ts mirrored that precedence for live selection.
• Missing detection / guardrail: regression tests covered runtime-first behavior, but there was no test asserting that explicit session overrides remain authoritative after a fallback run.
• Prior context (git blame, prior PR, issue, or refactor if known): issue #59928 reported the stuck-fallback behavior; this PR addresses the verified control-path cause in the current code.
• Why this regressed now: persisted runtime fields were treated as the effective session model instead of last-run identity.
• If unknown, what was ruled out: the generic fallback runner itself was not changed here; the verified issue was in session model resolution and session row rendering.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/gateway/session-utils.test.ts, src/agents/live-model-switch.test.ts
• Scenario the test should lock in: a session with a configured override and persisted fallback runtime fields should still resolve and report the selected override model.
• Why this is the smallest reliable guardrail: the bug lives in small model-resolution helpers used by gateway control paths and the session list.
• Existing test that already covers this (if any): existing helper tests covered runtime/model parsing and were updated to assert the corrected precedence.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

• Session control paths now respect the configured primary or explicit session override after a fallback run.
• The session list reports the selected override model instead of showing the persisted fallback runtime model as current.

Diagram (if applicable)

Before:
[fallback run persists runtime model] -> [session control paths read runtime fields first] -> [fallback looks like selected model]

After:
[fallback run persists runtime model] -> [session control paths read selected override/default first] -> [fallback stays runtime-only identity]

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS: macOS 25.3.0
• Runtime/container: local Node/Bun repo workflow
• Model/provider: N/A
• Integration/channel (if any): gateway session model resolution
• Relevant config (redacted): agent default primary plus session override with persisted runtime fallback fields

Steps

1. Configure a primary model and at least one fallback model.
2. Persist a session override or switch the session back to the primary model after a fallback run.
3. Read the session via gateway control paths or sessions.list.

Expected

• Explicit session selection remains authoritative.
• Runtime fallback identity does not replace the selected session model.

Actual

• Before this fix, persisted runtime fields could continue to win and make the fallback model appear selected.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

• Verified scenarios:
  • pnpm test -- src/gateway/session-utils.test.ts src/agents/live-model-switch.test.ts
  • pnpm check
  • pnpm build
• Edge cases checked:
  • runtime model still resolves when no session override exists
  • session list keeps legacy/runtime identity behavior when no override exists
  • live model switching now keeps the explicit session override authoritative
• What you did not verify:
  • live Control UI repro against a running OpenClaw instance
  • full pnpm test completion, because the suite currently fails on unrelated src/tts/status-config.test.ts expectations (provider: \"auto\" vs \"microsoft\") outside this touched surface

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps:

Risks and Mitigations

• Risk: gateway session rows still expose a single model field, so this fix intentionally keeps runtime identity separate only where the selected override is present.
  • Mitigation: regression tests now lock in both override-first control resolution and the no-override runtime fallback behavior.

AI Assistance

• This PR was prepared with AI assistance.
• Testing level: locally verified with focused regression tests plus pnpm check and pnpm build.

Made with Cursor

Changed files

• src/agents/live-model-switch.test.ts (modified, +29/-2)
• src/agents/live-model-switch.ts (modified, +6/-2)
• src/gateway/session-utils.test.ts (modified, +60/-1)
• src/gateway/session-utils.ts (modified, +29/-19)