Skip to content

[Bugfix #442] Add terminal WebSocket auto-reconnect with session resumption#445

Merged
waleedkadous merged 2 commits intomainfrom
builder/bugfix-442-terminal-websocket-auto-reconn
Feb 19, 2026
Merged

[Bugfix #442] Add terminal WebSocket auto-reconnect with session resumption#445
waleedkadous merged 2 commits intomainfrom
builder/bugfix-442-terminal-websocket-auto-reconn

Conversation

@waleedkadous
Copy link
Contributor

Summary

Fixes #442

Root Cause

The dashboard Terminal component had zero reconnection logic — when a WebSocket closed (common on cloud connections), it displayed [Terminal disconnected] and stopped permanently. The only recovery was a full page reload.

Fix

Client-side (Terminal.tsx):

  • Auto-reconnect with exponential backoff (1s, 2s, 4s, 8s, 16s, 30s cap)
  • Track sequence numbers from server seq control frames
  • On reconnect, pass ?resume=N query param for session resumption from ring buffer
  • Show yellow "Reconnecting..." overlay during reconnection attempts
  • Detect rapid failures (session gone, e.g. builder terminated) — stops after 5 rapid failures
  • Give up after 15 total attempts with permanent disconnect message
  • Reset counters on successful reconnection

Server-side (tower-websocket.ts):

  • Send seq control frame with current ring buffer sequence after replay
  • Periodic 10-second heartbeat with updated sequence number
  • Support reading resume sequence from URL query param (browser WebSocket API doesn't support custom headers)
  • Clean up heartbeat interval on connection close

Protocol (ws-protocol.ts):

  • Added seq to the ControlMessage type union

Test Plan

  • Added Terminal.reconnect.test.tsx (10 tests): backoff timing, seq tracking, overlay show/hide, rapid failure detection, max attempts, unmount cleanup
  • Updated tower-websocket.test.ts (+4 tests): seq frame after replay, heartbeat, query param resume, interval cleanup
  • All 48 directly related tests pass (tower-websocket: 25, ring-buffer: 15, ws-protocol: 8)
  • TypeScript compiles cleanly (both packages/codev and dashboard)
  • No regressions in existing tests (7 pre-existing failures on main confirmed)

CMAP Review

To be added after review

- Client-side: exponential backoff (1s to 30s cap), seq tracking from
  server control frames, ?resume=N query param on reconnect, visual
  reconnecting overlay, rapid failure detection for session-gone
- Server-side: send seq control frame after replay and every 10s
  heartbeat, support resume from URL query param (browser WS limitation)
- Add 'seq' control message type to ws-protocol
- Update tower-websocket tests for seq frame, heartbeat, query param resume
- Add Terminal.reconnect.test.tsx: backoff, overlay, rapid failure, max attempts
@waleedkadous waleedkadous merged commit bb2eaed into main Feb 19, 2026
6 checks passed
@waleedkadous waleedkadous deleted the builder/bugfix-442-terminal-websocket-auto-reconn branch February 19, 2026 16:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Terminal WebSocket auto-reconnect with session resumption

1 participant