Summary

Describe the problem and fix in 2–5 bullets:

• Problem: model fallback activation/clear transitions were not clearly surfaced to users in a cohesive way across chat verbosity, /status, and WebUI.
• Why it matters: users could see a selected model but not easily understand when runtime had switched to fallback, why it switched, or when fallback
  cleared.
• What changed: added one-time fallback lifecycle notices, unified fallback reason summaries, and aligned /status + WebUI presentation for selected-vs-
  active model context.
• What did NOT change (scope boundary): fallback routing decision logic/provider behavior itself was not redesigned; this PR focuses on observability and
  UX consistency.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• 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 Feature: Show current model name in chat #9550
• Related #None

User-visible / Behavior Changes

• Verbose mode now emits one-time lifecycle messages for fallback activation and fallback clear transitions.
• Fallback notices use consistent wording (Model Fallback:) and reason summaries.
• /status now shows Active: only when fallback is active, includes selected-model-like credential context, and appends reason as (Reason:
  ).
• WebUI fallback indicators now align with existing tool/event stream UX patterns for cohesive visibility.

Security Impact (required)

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

Repro + Verification

Environment

• OS: macOS host + VM (clawbox-1)
• Runtime/container: OpenClaw gateway in VM, hot-reload via pnpm:gateway watch
• Model/provider: primary fireworks/fireworks/minimax-m2p5, fallback deepinfra/moonshotai/Kimi-K2.5
• Integration/channel (if any): WebUI chat + /status
• Relevant config (redacted): Fireworks cooldown set/cleared in ~/.openclaw/auth-profiles.json to deterministically force fallback transitions

Steps

1. Configure primary + fallback and force primary cooldown.
2. Send message in WebUI with verbose enabled and observe fallback lifecycle message + indicator behavior.
3. Clear cooldown and send again; confirm one-time fallback-cleared transition and /status updates.

Expected

• One-time fallback activation message appears when fallback begins.
• One-time fallback-cleared message appears when fallback ends.
• /status shows Active: only while fallback is active and includes reason summary consistently.

Actual

• Matches expected behavior in manual VM/WebUI validation.

Evidence

Attach at least one:

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

Human Verification (required)

What you personally verified (not just CI), and how:

The chat channel validation loop was:

• Set agent's primary model to a cooldown state

• Send a new message to the agent, triggering a model fallback
  Observe: Verbose-mode message, /status shows new 'Active:' line

• Send another message to the agent
  Observe: No second verbose-mode message, /status still shows 'Active:' line

• Remove agent's primary model cooldown state

• Send a new message to the agent, triggering a model fallback (to primary)
  Observe: Verbose-mode 'clear' message, /status no longer shows 'Active:' line

• Send another message to the agent
  Observe: No second verbose-mode message, /status still no longer shows 'Active:' line

The WebUI validation loop was the same, except looking for the 'compaction toast'-type UI.

Compatibility / Migration

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

Failure Recovery (if this breaks)

• How to disable/revert this change quickly: disable verbose output for runtime notices and/or revert this feature commit.
• Files/config to restore: auto-reply fallback observability paths and WebUI fallback indicator rendering paths from previous commit.
• Known bad symptoms reviewers should watch for: repeated fallback notices every turn, missing fallback-clear notice, /status showing stale Active: line
  when fallback is not active.

Risks and Mitigations

• Risk: lifecycle notice spam if transition state tracking regresses.
• Mitigation: explicit transition-state helper with one-time emission tests.
• Risk: reason text drift between backend and UI.
• Mitigation: backend canonical summary reuse and parser simplification in UI path.

Screenshots

Greptile Summary

Added model fallback lifecycle visibility across CLI, WebUI, and verbose logs. When the runtime switches from a selected model to a fallback model (e.g., due to rate limits or provider cooldowns), users now see one-time transition notices and consistent status indicators.

• Introduced fallback-state.ts with transition detection logic that tracks selected vs active model pairs and emits one-time notices for fallback activation and clearing transitions
• Extended SessionEntry with fallbackNoticeSelectedModel, fallbackNoticeActiveModel, and fallbackNoticeReason fields to persist transition state across runs
• Enhanced runReplyAgent to emit lifecycle agent events (phase: "fallback" and phase: "fallback_cleared") with verbose notices prepended to reply payloads
• Updated /status command to display both selected model and active runtime model when fallback is active, including reason summary
• Added WebUI fallback indicators (toast-style notifications) that appear for 8 seconds during transitions and align with existing compaction indicator UX patterns
• Comprehensive test coverage includes unit tests for state transitions, integration tests for one-time emission guarantees, and WebUI event handling tests

Confidence Score: 5/5

• This PR is safe to merge with high confidence
• The implementation is well-architected with clear separation of concerns: state management in fallback-state.ts, runtime integration in agent-runner.ts, status display in status.ts, and UI rendering in WebUI components. The PR includes comprehensive test coverage (110 lines in fallback-state.test.ts, 390+ lines added to agent-runner.runreplyagent.test.ts, 137 lines in server-chat.agent-events.test.ts, and 86 lines in app-tool-stream.node.test.ts) that validates transition logic, one-time emission guarantees, and session-scoped event handling. The changes are purely additive for observability and do not modify fallback routing decision logic itself, minimizing risk to existing behavior. Type safety is maintained throughout, and the implementation follows existing patterns (agent events, session state persistence, WebUI toast indicators).
• No files require special attention

_{Last reviewed commit: 0e1e23e}

_{(5/5) You can turn off certain types of comments like style here!}