fix(websocket): prevent duplicate lines on reconnect via replay snapshot

Server now sends scrollback (and any alt-screen re-entry) as a single
`replay` message instead of an `output`. Client treats `replay` as an
authoritative snapshot — drops pending writes and resets the terminal
before applying it — so preserved xterm.js content no longer gets
appended-onto on reconnect, fixing duplicate-line artefacts in plain
shells. Also adds a stale-socket guard to onmessage handlers and updates
the API docs.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: dorlugasigal

packages/site/src/content/docs/api.md

@@ -1033,11 +1033,12 @@ The preview proxies **one port at a time** via HTTP only. It does not proxy WebS
 
 <!-- prettier-ignore -->
 :::tip[Limitations when accessed through a tunnel]
+
 - **Server-rendered apps** (Next.js SSR, Rails, Django) work best — the browser receives complete HTML with no extra fetches.
 - **Client-side SPAs** may break if they make API calls to a different port or use hardcoded `localhost` URLs. Apps that use a single point with an internal reverse proxy (e.g., nginx proxying `/api` to a backend) work fine.
 - **Multi-port architectures** (e.g., frontend on port 3000 making API calls to port 4000) won't work unless the app routes all requests through TermBeam's preview proxy (e.g., `/preview/4000/api` instead of `localhost:4000/api`).
 - The upstream service must be listening on `127.0.0.1` (localhost) on the machine running TermBeam.
-:::
+  :::
 
 **Response:** The upstream response is streamed back with its original status code and headers.
 
@@ -1187,7 +1188,7 @@ The connection is closed after sending this message. Sending any non-auth messag
 { "type": "attach", "sessionId": "a1b2c3d4" }
 ```
 
-After a successful `attached` response, the server immediately sends an `output` message containing the session's scrollback buffer (up to ~1,000,000 characters). When the buffer grows beyond this size, it is trimmed back to ~500,000 characters to keep memory usage bounded, allowing the client to display recent terminal output.
+After a successful attach, the server sends a single `replay` message containing the session's sanitized scrollback buffer (up to ~1,000,000 characters; trimmed back to ~500,000 when it grows beyond that), followed by the `attached` confirmation. Clients should treat `replay` as an authoritative state snapshot and reset their terminal before applying it — this prevents duplicated content on reconnect when the terminal UI is preserved across socket lifecycles.
 
 #### Send Input
 
@@ -1211,6 +1212,14 @@ The server validates resize dimensions: `cols` must be between 1–500 and `rows
 { "type": "output", "data": "..." }
 ```
 
+#### Replay Snapshot
+
+Sent on attach. Contains sanitized scrollback (and an alt-screen re-entry sequence when the session is currently in alt-screen). Clients should drop pending writes, reset their terminal, and write this payload — do not append it on top of preserved terminal content.
+
+```json
+{ "type": "replay", "data": "..." }
+```
+
 #### Attached Confirmation
 
 ```json

src/frontend/src/hooks/useAgentSocket.ts

@@ -232,6 +232,9 @@ export function useAgentSocket(options: UseAgentSocketOptions): UseAgentSocketRe
       };
 
       ws.onmessage = (event) => {
+        // Stale-socket guard: force-reconnect paths null `onclose` but may
+        // leave `onmessage` live; ignore messages from a superseded socket.
+        if (wsRef.current !== ws) return;
         if (!mountedRef.current) return;
 
         let msg: WSServerMessage;
@@ -249,12 +252,16 @@ export function useAgentSocket(options: UseAgentSocketOptions): UseAgentSocketRe
             }
             setConnected(true);
             setReconnecting(false);
-
-            // Replay scrollback through parser to reconstruct message history
-            if (msg.scrollback) {
-              const events = parser.feed(msg.scrollback);
-              processEvents(events, rawBufferRef, onRawOutputRef.current);
-            }
+            break;
+          }
+          case 'replay': {
+            // Server-authored snapshot of agent terminal output. Preserve the
+            // prior `attached.scrollback` behavior: feed through the parser so
+            // message history can be reconstructed on first attach. (Note: on
+            // reconnects within the same mount this can re-add events to the
+            // store; agent reconnect dedup is tracked separately.)
+            const events = parser.feed(msg.data);
+            processEvents(events, rawBufferRef, onRawOutputRef.current);
             break;
           }
           case 'output': {

src/frontend/src/hooks/useTerminalSocket.ts

@@ -187,6 +187,10 @@ export function useTerminalSocket(options: UseTerminalSocketOptions): UseTermina
       };
 
       ws.onmessage = (event) => {
+        // Stale-socket guard: a force-reconnect path may null `onclose` but
+        // leave `onmessage` live. Without this guard, late messages from the
+        // old socket can interleave with replay/output from the new one.
+        if (wsRef.current !== ws) return;
         if (!mountedRef.current || !terminal) return;
 
         let msg: WSServerMessage;
@@ -212,9 +216,6 @@ export function useTerminalSocket(options: UseTerminalSocketOptions): UseTermina
             setConnected(true);
             setReconnecting(false);
             onConnected?.();
-            if (msg.scrollback) {
-              terminal.write(stripOscSequences(msg.scrollback));
-            }
             // Send current dimensions so the PTY adjusts to this client's viewport
             if (terminal.cols && terminal.rows) {
               ws.send(JSON.stringify({ type: 'resize', cols: terminal.cols, rows: terminal.rows }));
@@ -228,6 +229,19 @@ export function useTerminalSocket(options: UseTerminalSocketOptions): UseTermina
             );
             break;
           }
+          case 'replay': {
+            // Authoritative state snapshot from the server. The xterm.js instance
+            // is preserved across React re-renders / socket reconnects, so
+            // appending the replay would duplicate visible content for plain
+            // shells. Drop any pending writes and reset the terminal first.
+            writeBuffer = '';
+            rafPending = false;
+            terminal.reset();
+            if (msg.data) {
+              terminal.write(stripOscSequences(msg.data));
+            }
+            break;
+          }
           case 'output': {
             scheduleWrite(msg.data);
 

src/frontend/src/types/websocket.ts

@@ -23,10 +23,18 @@ export interface WSOutputMessage {
   data: string;
 }
 
+// Server-authored snapshot of the session's display state (sanitized scrollback
+// plus any alt-screen re-entry). Sent on attach. Clients should treat this as
+// authoritative: drop any pending writes, reset their terminal, then write the
+// payload. Prevents duplicate content on reconnect when xterm.js is preserved.
+export interface WSReplayMessage {
+  type: 'replay';
+  data: string;
+}
+
 export interface WSAttachedMessage {
   type: 'attached';
   sessionId: string;
-  scrollback?: string;
 }
 
 export interface WSExitMessage {
@@ -67,6 +75,7 @@ export interface WSTunnelStatusMessage {
 
 export type WSServerMessage =
   | WSOutputMessage
+  | WSReplayMessage
   | WSAttachedMessage
   | WSExitMessage
   | WSErrorMessage

src/server/websocket.js

@@ -28,6 +28,23 @@ function sanitizeForReplay(buf) {
   return buf;
 }
 
+// Build an atomic replay payload for an attaching client: sanitized scrollback
+// followed by an alt-screen-enter sequence when the session is currently in
+// alt-screen. Sent as a single `replay` message so the client can reset its
+// terminal state once and write this snapshot, instead of appending it on top
+// of preserved xterm.js content (which caused duplicated lines on reconnect).
+function buildReplayPayload(session) {
+  let payload = '';
+  if (session.scrollbackBuf && session.scrollbackBuf.length > 0) {
+    payload += sanitizeForReplay(session.scrollbackBuf);
+  }
+  if (session.inAltScreen) {
+    const mode = session.altScreenMode || '1049';
+    payload += `\x1b[?${mode}h`;
+  }
+  return payload;
+}
+
 function recalcPtySize(session) {
   const now = Date.now();
   let activeCols = Infinity;
@@ -163,17 +180,15 @@ function setupWebSocket(wss, { auth, sessions, copilotService }) {
             ws._pendingResize = true;
           } else {
             session.clients.add(ws);
-            if (session.scrollbackBuf.length > 0) {
-              ws.send(
-                JSON.stringify({ type: 'output', data: sanitizeForReplay(session.scrollbackBuf) }),
-              );
+            // Send sanitized scrollback (and any alt-screen re-entry) as a single
+            // `replay` snapshot. Client treats `replay` as an authoritative full
+            // state and resets its terminal before writing — preventing duplicate
+            // lines on reconnect when the xterm.js instance is preserved.
+            const payload = buildReplayPayload(session);
+            if (payload.length > 0) {
+              ws.send(JSON.stringify({ type: 'replay', data: payload }));
             }
-            // After replaying scrollback (which has alt-screen sequences
-            // stripped by sanitizeForReplay), re-enter alt-screen so xterm.js
-            // uses the correct buffer before SIGWINCH triggers the app to repaint.
             if (session.inAltScreen) {
-              const mode = session.altScreenMode || '1049';
-              ws.send(JSON.stringify({ type: 'output', data: `\x1b[?${mode}h` }));
               ws._needsRedraw = true;
             }
           }
@@ -381,20 +396,13 @@ function setupWebSocket(wss, { auth, sessions, copilotService }) {
                 recalcPtySize(attached);
               } else {
                 attached.clients.add(ws);
-                if (attached.scrollbackBuf.length > 0) {
-                  ws.send(
-                    JSON.stringify({
-                      type: 'output',
-                      data: sanitizeForReplay(attached.scrollbackBuf),
-                    }),
-                  );
+                // Single atomic `replay` snapshot (scrollback + optional alt-screen
+                // re-entry). Client resets its terminal before applying it.
+                const payload = buildReplayPayload(attached);
+                if (payload.length > 0) {
+                  ws.send(JSON.stringify({ type: 'replay', data: payload }));
                 }
-                // After replaying scrollback (which has alt-screen sequences
-                // stripped), re-enter alt-screen so xterm.js uses the correct
-                // buffer before SIGWINCH triggers the TUI to repaint.
                 if (attached.inAltScreen) {
-                  const mode = attached.altScreenMode || '1049';
-                  ws.send(JSON.stringify({ type: 'output', data: `\x1b[?${mode}h` }));
                   // Force SIGWINCH so the TUI repaints into the alt buffer
                   recalcPtySize(attached);
                   const targetCols = attached._lastCols || cols;

test/server/websocket.test.js

@@ -301,7 +301,7 @@ describe('WebSocket', () => {
       assert.strictEqual(err.message, 'Session not found');
     });
 
-    it('should send scrollback on attach for returning clients', () => {
+    it('should send replay snapshot on attach for returning clients', () => {
       const session = createMockSession('s1', {
         scrollback: ['hello ', 'world'],
         hasHadClient: true,
@@ -312,9 +312,12 @@ describe('WebSocket', () => {
       wss._simulateConnection(ws);
       ws._simulateMessage({ type: 'attach', sessionId: 's1' });
 
-      const output = ws._sent.find((m) => m.type === 'output');
-      assert.ok(output);
-      assert.strictEqual(output.data, 'hello world');
+      const replay = ws._sent.find((m) => m.type === 'replay');
+      assert.ok(replay, 'should send a replay message');
+      assert.strictEqual(replay.data, 'hello world');
+      // No `output` for scrollback — preserved xterm.js content would duplicate
+      const stray = ws._sent.find((m) => m.type === 'output');
+      assert.strictEqual(stray, undefined, 'scrollback must not be sent as output');
     });
 
     it('should defer first-ever client until first resize (size mismatch)', () => {
@@ -328,7 +331,9 @@ describe('WebSocket', () => {
 
       // Client deferred — not yet in session.clients, scrollback NOT pre-cleared
       const output = ws._sent.find((m) => m.type === 'output');
+      const replay = ws._sent.find((m) => m.type === 'replay');
       assert.strictEqual(output, undefined);
+      assert.strictEqual(replay, undefined);
       assert.strictEqual(session.hasHadClient, true);
       assert.ok(!session.clients.has(ws));
       assert.strictEqual(ws._pendingResize, true);
@@ -367,9 +372,9 @@ describe('WebSocket', () => {
       assert.strictEqual(session.scrollbackBuf, 'correct-prompt'); // NOT cleared
       assert.strictEqual(session._resizes.length, 0); // no SIGWINCH
 
-      const output = ws._sent.find((m) => m.type === 'output');
-      assert.ok(output);
-      assert.strictEqual(output.data, 'correct-prompt');
+      const replay = ws._sent.find((m) => m.type === 'replay');
+      assert.ok(replay);
+      assert.strictEqual(replay.data, 'correct-prompt');
     });
 
     it('should add returning client to session on attach', () => {
@@ -396,7 +401,7 @@ describe('WebSocket', () => {
       assert.ok(!session.clients.has(ws));
     });
 
-    it('should send alt screen enter after replay when session is in alt screen', () => {
+    it('should fold alt-screen enter into the replay payload when in alt screen', () => {
       const session = createMockSession('s1', { hasHadClient: true, scrollbackBuf: 'some output' });
       session.inAltScreen = true;
       session.altScreenMode = '1049';
@@ -406,10 +411,17 @@ describe('WebSocket', () => {
       wss._simulateConnection(ws);
       ws._simulateMessage({ type: 'attach', sessionId: 's1' });
 
-      // Alt-screen enter should come AFTER scrollback replay
-      const replayIdx = ws._sent.findIndex((m) => m.type === 'output' && m.data !== '\x1b[?1049h');
-      const altIdx = ws._sent.findIndex((m) => m.type === 'output' && m.data === '\x1b[?1049h');
-      assert.ok(altIdx > replayIdx, 'alt-screen enter should come after replay');
+      const replay = ws._sent.find((m) => m.type === 'replay');
+      assert.ok(replay, 'should send a replay message');
+      // Scrollback first, alt-screen enter appended at the end
+      assert.ok(
+        replay.data.endsWith('\x1b[?1049h'),
+        'replay payload should end with alt-screen enter',
+      );
+      assert.ok(
+        replay.data.startsWith('some output'),
+        'replay payload should start with sanitized scrollback',
+      );
       assert.strictEqual(ws._needsRedraw, true, 'should flag client for redraw');
     });
 
@@ -423,11 +435,12 @@ describe('WebSocket', () => {
       wss._simulateConnection(ws);
       ws._simulateMessage({ type: 'attach', sessionId: 's1' });
 
-      const altMsg = ws._sent.find((m) => m.type === 'output' && m.data === '\x1b[?1047h');
-      assert.ok(altMsg, 'should use mode 1047 for alt-screen enter');
+      const replay = ws._sent.find((m) => m.type === 'replay');
+      assert.ok(replay, 'should send a replay message');
+      assert.ok(replay.data.endsWith('\x1b[?1047h'), 'should use mode 1047 for alt-screen enter');
     });
 
-    it('should not send alt screen enter when session is not in alt screen', () => {
+    it('should not include alt screen enter when session is not in alt screen', () => {
       const session = createMockSession('s1', { hasHadClient: true, scrollbackBuf: 'hello' });
       session.inAltScreen = false;
       sessions._add(session);
@@ -436,11 +449,32 @@ describe('WebSocket', () => {
       wss._simulateConnection(ws);
       ws._simulateMessage({ type: 'attach', sessionId: 's1' });
 
-      const altScreenMsg = ws._sent.find((m) => m.type === 'output' && m.data === '\x1b[?1049h');
-      assert.strictEqual(altScreenMsg, undefined, 'should not send alt screen enter');
+      const replay = ws._sent.find((m) => m.type === 'replay');
+      assert.ok(replay);
+      assert.strictEqual(replay.data, 'hello', 'replay payload should be just scrollback');
+      assert.ok(
+        !replay.data.includes('\x1b[?1049h'),
+        'replay payload must not include alt-screen enter',
+      );
       assert.strictEqual(ws._needsRedraw, undefined, 'should not flag for redraw');
     });
 
+    it('should send replay with only alt-screen enter when scrollback is empty', () => {
+      const session = createMockSession('s1', { hasHadClient: true });
+      session.scrollbackBuf = '';
+      session.inAltScreen = true;
+      session.altScreenMode = '1049';
+      sessions._add(session);
+
+      const ws = createMockWs();
+      wss._simulateConnection(ws);
+      ws._simulateMessage({ type: 'attach', sessionId: 's1' });
+
+      const replay = ws._sent.find((m) => m.type === 'replay');
+      assert.ok(replay, 'should still send replay so client can re-enter alt-screen');
+      assert.strictEqual(replay.data, '\x1b[?1049h');
+    });
+
     it('should force SIGWINCH via temporary resize on first resize after alt-screen reattach', () => {
       const session = createMockSession('s1', { hasHadClient: true, _lastCols: 80, _lastRows: 24 });
       session.inAltScreen = true;
@@ -1164,9 +1198,9 @@ describe('WebSocket', () => {
       // Should enter the inAltScreen branch and create bounce timer
       assert.ok(session._resizeBounceTimer, 'bounce timer should be set for alt-screen same-size');
 
-      // Should have sent alt-screen enter sequence
-      const altEnter = ws._sent.find((m) => m.type === 'output' && m.data.includes('\x1b[?1049h'));
-      assert.ok(altEnter, 'should send alt-screen enter');
+      // Should have sent alt-screen enter sequence (folded into replay payload)
+      const replay = ws._sent.find((m) => m.type === 'replay' && m.data.includes('\x1b[?1049h'));
+      assert.ok(replay, 'should send replay containing alt-screen enter');
 
       // Wait for bounce timer to complete
       await new Promise((r) => setTimeout(r, 80));