PR #75356: fix(ui): prevent webchat sends into isolated heartbeat sessions

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

Description (problem / solution / changelog)

Summary

• Problem: Control UI webchat could keep agent:main:main:heartbeat selected after the base agent:main:main session was pruned.
• Why it matters: User messages could be sent into the isolated heartbeat session instead of the real main chat session.
• What changed: Isolated heartbeat rows now expose their base session key, the UI session picker hides heartbeat-only rows, and both UI and gateway chat.send route stale heartbeat selections back to the base session.
• What did NOT change (scope boundary): Heartbeat creation, heartbeat execution, session pruning policy, and normal non-heartbeat session routing are unchanged.

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

Root Cause (if applicable)

• Root cause: Isolated heartbeat sessions are persisted as normal session rows with keys like <base>:heartbeat, and the Control UI could select that row when the base session was absent from sessions.list.
• Missing detection / guardrail: Neither the UI picker nor chat.send treated heartbeatIsolatedBaseSessionKey as a non-user-chat target.
• Contributing context (if known): Session maintenance can prune the base session while leaving the newer heartbeat session row.

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-render.helpers.node.test.ts
  • ui/src/ui/controllers/chat.test.ts
• Scenario the test should lock in: A heartbeat-only session row is not offered as the chat target, and sends from a stale heartbeat selection use the base session key.
• Why this is the smallest reliable guardrail: The regression is in UI session selection and chat-send request construction; these tests cover both without requiring a full gateway/browser E2E.
• Existing test that already covers this (if any): None.
• If no new test is added, why not: N/A.

User-visible / Behavior Changes

Control UI no longer shows isolated heartbeat sessions as selectable chat sessions. If a stale UI state points at an isolated heartbeat session, sending a message resumes the base session instead.

Diagram (if applicable)

Before:
[webchat active key = agent:main:main:heartbeat] -> chat.send -> [heartbeat session]

After:
[webchat active key = agent:main:main:heartbeat] -> resolve base key -> chat.send -> [agent:main:main]

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: N/A.

Repro + Verification

Environment

• OS: Linux
• Runtime/container: Node v22.22.0 via nvm
• Model/provider: N/A
• Integration/channel (if any): Control UI webchat
• Relevant config (redacted): agents.defaults.heartbeat.isolatedSession: true, session.maintenance.mode: enforce

Steps

1. Seed sessions.json with only agent:main:main:heartbeat, including heartbeatIsolatedBaseSessionKey: "agent:main:main".
2. Load session options for active key agent:main:main:heartbeat.
3. Send a Control UI chat message from that stale active key.

Expected

• The picker offers agent:main:main, not agent:main:main:heartbeat.
• chat.send uses sessionKey: "agent:main:main".

Actual

• Before this fix, chat.send used sessionKey: "agent:main:main:heartbeat".
• After this fix, chat.send uses sessionKey: "agent:main:main".

Evidence

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

Human Verification

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

• Verified scenarios:
  • Focused UI session picker regression test passes.
  • Focused chat send regression test passes.
  • Headless reproduction now routes to agent:main:main.
• Edge cases checked:
  • Stale active heartbeat key.
  • Heartbeat-only sessions.list state.
  • Server-side chat.send fallback guard.
• What you did not verify:
  • Full browser E2E with a live gateway.

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: N/A.

Risks and Mitigations

• Risk: A real user-created session key could intentionally end with :heartbeat.
• Mitigation: The behavior only applies when the row carries heartbeatIsolatedBaseSessionKey, not by suffix alone.

Changed files

• src/gateway/server-methods/chat.ts (modified, +10/-2)
• src/gateway/session-utils.test.ts (modified, +28/-0)
• src/gateway/session-utils.ts (modified, +1/-0)
• src/gateway/session-utils.types.ts (modified, +1/-0)
• ui/src/ui/app-render.helpers.node.test.ts (modified, +32/-1)
• ui/src/ui/app-render.helpers.ts (modified, +16/-4)
• ui/src/ui/chat/session-controls.ts (modified, +35/-6)
• ui/src/ui/controllers/chat.test.ts (modified, +74/-0)
• ui/src/ui/controllers/chat.ts (modified, +36/-7)
• ui/src/ui/controllers/sessions.ts (modified, +1/-0)
• ui/src/ui/types.ts (modified, +1/-0)