PR #66271: Control UI: avoid chat flicker on session reload

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

Description (problem / solution / changelog)

Summary

• Problem: Control UI user messages can disappear briefly after send in 2026.4.12.
• Why it matters: the chat transcript visibly flickers on every send, which makes the UI feel unreliable.
• What changed: skip the session.message-triggered history reload when it is only echoing the active run's own optimistic user message, and add a regression test.
• What did NOT change (scope boundary): no broader optimistic-message reconciliation or transcript merge behavior.

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 #66207
• Related #66207
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: 2026.4.12 added a Control UI session.message handler that unconditionally reloaded chat.history for the active session. The chat UI already renders the user's message optimistically, and loadChatHistory replaces chatMessages wholesale, so an early reload can briefly swap in a stale transcript snapshot before persistence catches up.
• Missing detection / guardrail: there was no regression test covering an active optimistic user message during a session.message echo.
• Contributing context (if known): 4.11 did not have this session.message reload path in Control UI.

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: ui/src/ui/app-gateway.sessions.node.test.ts
• Scenario the test should lock in: while chatRunId is active, a same-session session.message event carrying a user message should not trigger loadChatHistory.
• Why this is the smallest reliable guardrail: the regression was introduced in the Control UI gateway event handler, so that seam isolates the behavior directly.
• Existing test that already covers this (if any): none
• If no new test is added, why not: N/A

User-visible / Behavior Changes

• Just-sent user messages remain visible continuously instead of disappearing briefly before transcript persistence catches up.

Diagram (if applicable)

Before:
[user send] -> [optimistic user message visible] -> [session.message reloads history] -> [stale history replaces optimistic row] -> [later history reload restores message]

After:
[user send] -> [optimistic user message visible] -> [session.message user echo is ignored during active run] -> [message stays visible]

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:

Repro + Verification

Environment

• OS: macOS
• Runtime/container: local UI test runner
• Model/provider: N/A
• Integration/channel (if any): Control UI webchat
• Relevant config (redacted): default local dev config

Steps

1. Start from the Control UI chat send flow with an active chatRunId.
2. Receive a session.message event for the same session containing a user message echo.
3. Observe whether the handler reloads chat.history.

Expected

• The optimistic local user message remains visible and the handler skips the redundant reload.

Actual

• The focused regression test now passes and confirms the reload is skipped in that case.

Evidence

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

Human Verification (required)

• Verified scenarios: ran pnpm test ui/src/ui/app-gateway.sessions.node.test.ts and confirmed the new regression test plus existing session-message coverage pass.
• Edge cases checked: same-session events still reload when no active run is present; other-session events remain ignored.
• What you did not verify: manual browser reproduction in a running Control UI instance.

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)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps:

Risks and Mitigations

• Risk: a non-local user session.message event could be delayed if it arrives while chatRunId is active and only exposes role: user.
  • Mitigation: the guard is narrowly limited to the active run window and only the user-echo case that is already rendered optimistically; final assistant events and other transcript reload paths still run.

Changed files

• ui/src/ui/app-gateway.sessions.node.test.ts (modified, +61/-0)
• ui/src/ui/app-gateway.ts (modified, +55/-2)