PR #62602: fix:(tui) reset stale streaming state after event gaps

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

Description (problem / solution / changelog)

Summary

Describe the problem and fix in 2–5 bullets:

If this PR fixes a plugin beta-release blocker, title it fix(<plugin-id>): beta blocker - <summary> and link the matching Beta blocker: <plugin-name> - <summary> issue labeled beta-blocker. Contributors cannot label PRs, so the title is the PR-side signal for maintainers and automation.

• Problem: TUI could stay stuck in streaming after a run effectively ended when a gateway event gap/desync happened.
• Why it matters: the status line looked busy indefinitely and stale activeChatRunId could block clean progress to the next run.
• What changed: added explicit TUI gap-reset handling to clear stale active run state and wired it into client.onGap (with reload) and client.onDisconnected (no reload).
• What did NOT change (scope boundary): no protocol/gateway contract changes, no plugin/channel behavior changes, no config/schema changes.

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

Root Cause (if applicable)

For bug fixes or regressions, explain why this happened, not just what changed. Otherwise write N/A. If the cause is unclear, write Unknown.

• Root cause: event-gap recovery did not clear stale activeChatRunId / streaming state in the TUI state machine.
• Missing detection / guardrail: no gap-specific reset path test to assert transition back to idle and acceptance of a fresh run.
• Contributing context (if known): TUI relied on normal final/aborted/error chat events for cleanup, but gap/desync can skip those events.

Regression Test Plan (if applicable)

For bug fixes or regressions, name the smallest reliable test coverage that should catch this. Otherwise write N/A.

• 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/tui/tui-event-handlers.test.ts
  • Scenario the test should lock in: a stream receives delta, then a gap reset occurs, state returns to idle, stale run is cleared, and next run streams normally.
  • Why this is the smallest reliable guardrail: the bug is TUI state-transition logic in event handlers; unit coverage is direct and deterministic.
  • Existing test that already covers this (if any): none specific to gap reset prior to this.
  • If no new test is added, why not: N/A (new tests added).

User-visible / Behavior Changes

List user-visible changes (including defaults/config).
If none, write None.

• TUI now recovers to idle after an event gap instead of potentially remaining stuck in streaming.
• After a gap reset, subsequent runs can become the active stream normally.

Diagram (if applicable)

For UI changes or non-trivial logic flows, include a small ASCII diagram reviewers can scan quickly. Otherwise write N/A.

Before: [event gap during stream] -> [stale activeChatRunId remains] -> [status can stay "streaming"]

After: [event gap during stream] -> [handleEventGap clears stale run + sets idle] -> [history refresh] -> [next run streams normally]

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

Repro + Verification

Environment

• OS: macOS (local dev machine)
• Runtime/container: Node v25.5.0, pnpm
• Model/provider: N/A
• Integration/channel (if any): TUI + gateway chat event stream
• Relevant config (redacted): default local dev config

Steps

1. Start TUI and begin a chat stream (delta events).
2. Trigger/observe an event-gap/desync path.
3. Check activity state and ability to continue with a new run.

Expected

• Activity returns to idle after gap recovery.
• Stale active run is cleared.
• New run can stream normally.

Actual

• Added and passed unit tests confirming gap reset and non-regression for active streams.

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:

• Verified scenarios: ran targeted test files manually:
  • pnpm test src/tui/tui-event-handlers.test.ts (24 passed)
  • pnpm test src/tui/tui.test.ts (27 passed)
• Edge cases checked: gap reset clears stale run; ongoing valid stream is not cleared.
• What you did not verify: full repo test matrix; manual interactive end-to-end gap reproduction in live TUI session.

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.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

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

Risks and Mitigations

List only real risks for this PR. Add/remove entries as needed. If none, write None.

• Risk: gap handling may clear an active run aggressively in borderline transient conditions.
• Mitigation: scoped reset only on explicit onGap/disconnect paths plus regression tests for normal active-stream continuity.

Built with Codex

Changed files

• src/tui/tui-command-handlers.test.ts (modified, +6/-3)
• src/tui/tui-command-handlers.ts (modified, +2/-0)
• src/tui/tui-event-handlers.test.ts (modified, +279/-0)
• src/tui/tui-event-handlers.ts (modified, +54/-3)
• src/tui/tui.ts (modified, +20/-16)