termdock 1.4.168 → 1.4.169

package/dist/server/routes/terminal.js

@@ -1,3 +1,7 @@
+import { TerminalClientAttachment } from '../utils/terminalClientAttachment.js';
+import { redrawTmuxClient } from '../utils/tmuxClientRedraw.js';
+import { TmuxInitialScreen } from '../utils/tmuxInitialScreen.js';
+import { TerminalOutputDelivery, resolveTerminalReplayCursor } from '../utils/terminalOutputDelivery.js';
 import express from 'express';
 import fs from 'fs';
 import os from 'os';
@@ -111,6 +115,10 @@ const TERMDOCK_GUI_DETACHED_AT_OPTION = '@termdock-gui-detached-at';
 const TERMDOCK_FRONTEND_SESSION_ID_OPTION = '@termdock-frontend-session-id';
 // WebSocket clients per session (separate from SSE clients).
 const wsClients = new Map();
+const outputDeliveries = new WeakMap();
+const independentTmuxClients = new WeakSet();
+const independentTmuxReplays = new WeakMap();
+const TERMINAL_STREAM_EPOCH = crypto.randomUUID();
 // Sessions where copy-mode -e just auto-exited at the bottom.
 // Prevents immediate re-entry on subsequent scroll-down commands.
 const exitedAtBottom = new Set();
@@ -780,7 +788,10 @@ function getHistorySince(sessionId, sinceSeq) {
             : history.chunks.slice();
         return { chunks, lastSeq, outOfWindow: false };
     }
-    if (sinceSeq >= lastSeq) {
+    if (sinceSeq > lastSeq) {
+        return { chunks: history.chunks.slice(), lastSeq, outOfWindow: true };
+    }
+    if (sinceSeq === lastSeq) {
         return { chunks: [], lastSeq, outOfWindow: false };
     }
     const oldestSeq = history.chunks.length > 0 ? history.chunks[0].seq : history.nextSeq;
@@ -2215,89 +2226,6 @@ function enqueueTmuxIo(session, operation) {
     session.tmuxIoChain = result.then(() => undefined, () => undefined);
     return result;
 }
-function markTmuxClientsForScreenSync(sessionId, session) {
-    if (session.mode !== 'tmux')
-        return;
-    const clients = wsClients.get(sessionId);
-    if (!clients || clients.size === 0)
-        return;
-    const pending = session.tmuxScreenSyncClients ?? new Set();
-    for (const clientId of clients.keys())
-        pending.add(clientId);
-    session.tmuxScreenSyncClients = pending;
-    session.tmuxResizeGeneration = (session.tmuxResizeGeneration ?? 0) + 1;
-}
-function markTmuxClientForScreenSync(session, clientId) {
-    if (session.mode !== 'tmux')
-        return;
-    const pending = session.tmuxScreenSyncClients ?? new Set();
-    pending.add(clientId);
-    session.tmuxScreenSyncClients = pending;
-    session.tmuxResizeGeneration = (session.tmuxResizeGeneration ?? 0) + 1;
-}
-const TMUX_RESIZE_SCREEN_SYNC_DELAY_MS = 180;
-function clearTmuxScreenSyncTimer(session, clientId) {
-    const timer = session.tmuxScreenSyncTimers?.get(clientId);
-    if (timer)
-        clearTimeout(timer);
-    session.tmuxScreenSyncTimers?.delete(clientId);
-    if (session.tmuxScreenSyncTimers?.size === 0) {
-        session.tmuxScreenSyncTimers = undefined;
-    }
-}
-function scheduleTmuxScreenSyncAfterResize(sessionId, session, clientId) {
-    if (session.mode !== 'tmux' || !session.tmuxSessionName)
-        return;
-    clearTmuxScreenSyncTimer(session, clientId);
-    const timers = session.tmuxScreenSyncTimers ?? new Map();
-    const timer = setTimeout(() => {
-        clearTmuxScreenSyncTimer(session, clientId);
-        const ws = wsClients.get(sessionId)?.get(clientId);
-        if (!ws || ws.readyState !== ws.OPEN)
-            return;
-        void enqueueTmuxIo(session, () => syncTmuxScreenBeforeScroll(sessionId, clientId, session, ws));
-    }, TMUX_RESIZE_SCREEN_SYNC_DELAY_MS);
-    timer.unref?.();
-    timers.set(clientId, timer);
-    session.tmuxScreenSyncTimers = timers;
-}
-function isTmuxWheelInput(data) {
-    return /^(?:\u001b\[<6[45];\d+;\d+[Mm])+$/.test(data);
-}
-async function syncTmuxScreenBeforeScroll(sessionId, clientId, session, ws) {
-    clearTmuxScreenSyncTimer(session, clientId);
-    if (session.mode !== 'tmux'
-        || !session.tmuxSessionName
-        || !session.tmuxScreenSyncClients?.has(clientId)) {
-        return;
-    }
-    const generation = session.tmuxResizeGeneration ?? 0;
-    try {
-        // capture-pane itself enters tmux's command queue after the tty resize.
-        // Do not call refresh-client here: that emits another incremental repaint
-        // through node-pty which can arrive after this authoritative snapshot and
-        // be applied twice (for example, duplicate Codex "Working" rows).
-        const snapshot = await captureTmuxPane(session.tmuxSessionName);
-        if (ws.readyState === ws.OPEN) {
-            ws.send(JSON.stringify({
-                type: 'tmux-screen-sync',
-                chunks: buildTmuxScreenSnapshot(snapshot),
-                cols: session.cols,
-                rows: session.rows,
-                generation,
-            }));
-            session.tmuxScreenSyncClients.delete(clientId);
-            if (session.tmuxScreenSyncClients.size === 0) {
-                session.tmuxScreenSyncClients = undefined;
-            }
-        }
-    }
-    catch (error) {
-        // Keep the client marked dirty. Its next wheel event retries the exact
-        // synchronization instead of permanently accepting a partial screen.
-        console.warn(`[tmux-screen-sync] failed session=${sessionId} client=${clientId}: ${getErrorMessage(error)}`);
-    }
-}
 async function isTmuxPaneInMode(target, control) {
     const paneInModeRaw = (await sendTmuxCommand(target, control, [
         'display-message',
@@ -3576,9 +3504,7 @@ async function resolveTmuxClientTty(sessionName, preferredClientPid) {
     }
     if (preferredClientPid !== null) {
         const matched = rows.find(([clientPid]) => clientPid === String(preferredClientPid));
-        if (matched?.[1]) {
-            return matched[1];
-        }
+        return matched?.[1] || null;
     }
     return rows[0][1] || null;
 }
@@ -4088,10 +4014,6 @@ function cleanupSession(sessionId, options) {
     }
     session.flowPausedClientTimers.clear();
     session.flowPausedClients.clear();
-    for (const timer of session.tmuxScreenSyncTimers?.values() ?? []) {
-        clearTimeout(timer);
-    }
-    session.tmuxScreenSyncTimers = undefined;
     if (session.ptyPausedForFlowControl) {
         applyPtyFlowControl(sessionId, session, false, 'session-cleanup');
     }
@@ -4138,7 +4060,7 @@ function cleanupSession(sessionId, options) {
         }
     }
 }
-function broadcastToWs(sessionId, data, excludeClientId) {
+function broadcastToWs(sessionId, data, excludeClientId, output, eventType) {
     const clients = wsClients.get(sessionId);
     const session = terminalSessions.get(sessionId);
     if (!clients)
@@ -4146,8 +4068,20 @@ function broadcastToWs(sessionId, data, excludeClientId) {
     for (const [clientId, ws] of clients.entries()) {
         if (excludeClientId && clientId === excludeClientId)
             continue;
+        if (independentTmuxClients.has(ws) && (output || eventType === 'pty-size'))
+            continue;
         try {
-            ws.send(data);
+            if (ws.readyState !== ws.OPEN)
+                continue;
+            if (ws.bufferedAmount > 1024 * 1024) {
+                ws.close(1013, 'Output transport is congested');
+                continue;
+            }
+            const delivery = outputDeliveries.get(ws);
+            if (output && delivery)
+                delivery.enqueue(output);
+            else
+                ws.send(data);
         }
         catch {
             clients.delete(clientId);
@@ -4157,7 +4091,8 @@ function broadcastToWs(sessionId, data, excludeClientId) {
     }
 }
 function broadcastJsonWs(sessionId, payload, excludeClientId) {
-    broadcastToWs(sessionId, JSON.stringify(payload), excludeClientId);
+    const output = payload?.type === 'data' ? payload : undefined;
+    broadcastToWs(sessionId, JSON.stringify(payload), excludeClientId, output, payload?.type);
 }
 // 统一的 pty resize 入口：调用 ptyProcess.resize 改变 pty size 之后，把
 // 真实尺寸广播给除发起方之外的所有 ws client。多端场景下，B 端把 pty
@@ -4183,11 +4118,7 @@ function applyPtyResize(sessionId, session, cols, rows, source, originClientId)
     session.autoTitleTerminal.resize(cleanCols, cleanRows);
     session.lastActivity = Date.now();
     if (changed) {
-        markTmuxClientsForScreenSync(sessionId, session);
         broadcastJsonWs(sessionId, { type: 'pty-size', cols: cleanCols, rows: cleanRows, source }, originClientId);
-        if (originClientId) {
-            scheduleTmuxScreenSyncAfterResize(sessionId, session, originClientId);
-        }
     }
     return true;
 }
@@ -4497,7 +4428,9 @@ async function spawnTerminalSession(req, input) {
         ? getTmuxBinary()
         : (process.platform === 'win32' ? 'powershell.exe' : resolveShellCandidates()[0]);
     const args = mode === 'tmux' && tmuxSessionName
-        ? ['attach-session', '-t', tmuxSessionName]
+        // xterm supports DEC 2026. Declare it on this attached client so tmux
+        // emits real synchronized-output boundaries around its redraw batches.
+        ? ['-T', 'RGB,sync', 'attach-session', '-t', tmuxSessionName]
         : (process.platform === 'win32' ? buildPowerShellCwdHookArgs() : []);
     const envPath = buildAugmentedPath();
     const resolvedEnv = buildInteractiveColorEnvironment({
@@ -6759,6 +6692,27 @@ router.post('/:sessionId/resize', async (req, res) => {
         res.status(500).json({ error: errorMessage || 'Failed to resize terminal' });
     }
 });
+async function switchTmuxBackendSession(sessionId, session, target) {
+    if (!target)
+        throw new Error('tmuxSessionName is required');
+    const clientTty = await resolveTmuxClientTty(session.tmuxSessionName, getPtyProcessPid(session.ptyProcess));
+    if (!clientTty)
+        throw new Error('No tmux client available for current session');
+    await prepareManagedTmuxSession(target, session.cwd);
+    await sendTmuxCommand(session.tmuxSessionName, session.tmuxControl, ['switch-client', '-c', clientTty, '-t', target]);
+    session.tmuxSessionName = target;
+    session.lastActivity = Date.now();
+    if (updateGlobalBindingForBackendSession(sessionId, {
+        mode: 'tmux', tmuxSessionName: target, cwd: session.cwd, lastActivity: session.lastActivity,
+    }))
+        persistAndBroadcastGlobalState();
+    // Each display must attach to the newly selected task and initialize its
+    // own parser stream; the metadata client's bytes are never a replacement.
+    await Promise.all([...wsClients.get(sessionId)?.values() ?? []].map(ws => independentTmuxReplays.get(ws)?.()));
+    const layout = await getTmuxLayout(target);
+    broadcastEvent(sessionId, { type: 'tmux-layout', layout });
+    return layout;
+}
 router.post('/:sessionId/tmux', async (req, res) => {
     const { sessionId } = req.params;
     const session = terminalSessions.get(sessionId);
@@ -6779,25 +6733,7 @@ router.post('/:sessionId/tmux', async (req, res) => {
             if (!targetSessionName) {
                 return res.status(400).json({ error: 'tmuxSessionName is required' });
             }
-            const preferredClientPid = getPtyProcessPid(session.ptyProcess);
-            const clientTty = await resolveTmuxClientTty(tmuxTarget, preferredClientPid);
-            if (!clientTty) {
-                return res.status(500).json({ error: 'No tmux client available for current session' });
-            }
-            await prepareManagedTmuxSession(targetSessionName, session.cwd);
-            await sendTmuxCommand(tmuxTarget, session.tmuxControl, ['switch-client', '-c', clientTty, '-t', targetSessionName]);
-            session.tmuxSessionName = targetSessionName;
-            session.lastActivity = Date.now();
-            if (updateGlobalBindingForBackendSession(sessionId, {
-                mode: 'tmux',
-                tmuxSessionName: targetSessionName,
-                cwd: session.cwd,
-                lastActivity: session.lastActivity,
-            })) {
-                persistAndBroadcastGlobalState();
-            }
-            const layout = await getTmuxLayout(targetSessionName);
-            broadcastEvent(sessionId, { type: 'tmux-layout', layout });
+            const layout = await switchTmuxBackendSession(sessionId, session, targetSessionName);
             return res.json({ success: true, layout });
         }
         // All other actions: delegate to shared executeTmuxAction
@@ -7048,13 +6984,65 @@ async function executeTmuxAction(tmuxTarget, action, body, control) {
     }
     return { shouldBroadcastLayout };
 }
-export function handleTerminalWebSocket(ws, sessionId, clientId, options = {}) {
+export function handleTerminalWebSocket(ws, sessionId, clientId, options = {}, initialDimensions) {
     const session = terminalSessions.get(sessionId);
     if (!session) {
         ws.close(4001, 'Session not found');
         return;
     }
-    const sinceSeq = options.sinceSeq ?? 0;
+    const initialSince = options.sinceSeq ?? 0;
+    const delivery = new TerminalOutputDelivery((frame) => {
+        if (ws.readyState === ws.OPEN)
+            ws.send(JSON.stringify(frame));
+    }, options.flowControl === true, 128 * 1024, 512 * 1024, () => {
+        // No ACK may be outstanding (e.g. a single oversized frame). Reconnect
+        // against authoritative history instead of leaving this observer stalled.
+        if (ws.readyState === ws.OPEN)
+            ws.close(1013, 'Output observer exceeded budget');
+    });
+    outputDeliveries.set(ws, delivery);
+    let outputWanted = options.outputActive !== false;
+    let clientPaused = false;
+    let replayRequest = null;
+    let clientCols = session.cols;
+    let clientRows = session.rows;
+    let initialAttachmentResize = true;
+    let initialScreen = null;
+    if (initialDimensions && options.independentTmux) {
+        clientCols = initialDimensions.cols;
+        clientRows = initialDimensions.rows;
+    }
+    const ownTmux = session.mode === 'tmux' && options.independentTmux === true;
+    if (ownTmux)
+        independentTmuxClients.add(ws);
+    const attachment = ownTmux ? new TerminalClientAttachment(async (cols, rows) => {
+        const provider = await getPtyProvider();
+        // The metadata observer must not choose the pane size while a browser
+        // owns an attached client. Resolve by exact PID, never another client.
+        const raw = await runTmux(['list-clients', '-t', session.tmuxSessionName, '-F', '#{client_pid} #{client_tty}']);
+        const metadata = raw.split('\n').map(line => line.trim().split(/\s+/))
+            .find(([pid]) => pid === String(session.ptyProcess.pid));
+        if (metadata?.[1])
+            await runTmux(['refresh-client', '-t', metadata[1], '-f', 'ignore-size']);
+        const env = buildInteractiveColorEnvironment({ ...process.env, PATH: buildAugmentedPath() });
+        delete env.TMUX;
+        delete env.TMUX_PANE;
+        return provider.spawn(getTmuxBinary(), ['-T', 'RGB,sync', 'attach-session', '-t', session.tmuxSessionName], {
+            name: 'xterm-256color', cols, rows, cwd: session.cwd || os.homedir(),
+            env: { ...env, TERM: 'xterm-256color', COLORTERM: 'truecolor' },
+        });
+    }, (data) => {
+        if (ws.readyState !== ws.OPEN)
+            return;
+        if (ws.bufferedAmount > 1024 * 1024) {
+            ws.close(1013, 'Output transport is congested');
+            return;
+        }
+        const liveData = initialScreen ? initialScreen.push(data) : data;
+        if (liveData)
+            delivery.enqueue({ type: 'data', data: liveData });
+    }, () => { if (ws.readyState === ws.OPEN)
+        ws.close(1012, 'Tmux display client detached'); }) : null;
     // Register client
     let clients = wsClients.get(sessionId);
     if (!clients) {
@@ -7067,86 +7055,153 @@ export function handleTerminalWebSocket(ws, sessionId, clientId, options = {}) {
     if (updateGlobalBindingForBackendSession(sessionId, { cwd: session.cwd, lastActivity: session.lastActivity })) {
         persistAndBroadcastGlobalState();
     }
-    void (async () => {
-        // 连接时立即检测一次 activeProgram，避免前端首次显示闪烁
-        try {
-            if (session.mode === 'shell') {
-                const ap = await detectShellActiveProgram(session);
-                if (ap)
-                    session.activeProgram = ap;
+    const sendReplay = (requestedSince = initialSince, clientEpoch = options.streamEpoch) => {
+        if (replayRequest)
+            return replayRequest;
+        const sinceSeq = resolveTerminalReplayCursor(requestedSince, clientEpoch, TERMINAL_STREAM_EPOCH);
+        delivery.replaying = true;
+        if (attachment) {
+            attachment.close();
+            initialScreen?.cancel();
+            initialScreen = null;
+            initialAttachmentResize = true;
+            delivery.setActive(false); // Discard only this observer's obsolete stream.
+        }
+        replayRequest = (async () => {
+            // 连接时立即检测一次 activeProgram，避免前端首次显示闪烁
+            try {
+                if (session.mode === 'shell') {
+                    const ap = await detectShellActiveProgram(session);
+                    if (ap)
+                        session.activeProgram = ap;
+                }
+                else if (session.mode === 'tmux' && session.tmuxSessionName) {
+                    const layout = await getCachedTmuxLayout(session.tmuxSessionName);
+                    const ap = getActiveProgramFromTmuxLayout(layout);
+                    if (ap)
+                        session.activeProgram = ap;
+                }
             }
-            else if (session.mode === 'tmux' && session.tmuxSessionName) {
-                const layout = await getCachedTmuxLayout(session.tmuxSessionName);
-                const ap = getActiveProgramFromTmuxLayout(layout);
-                if (ap)
-                    session.activeProgram = ap;
+            catch { /* ignore */ }
+            // 计算重连补帧：
+            // - sinceSeq > 0：短线重连，shell 模式按 seq 补增量；超出窗口则发 outOfWindow + 全量。
+            // - sinceSeq == 0：首次连接（包括手机 PWA 冷启动）。以前这里只回 lastSeq、不带数据，
+            //   靠客户端单独走 HTTP /attach 拿 scrollback；但那条路径会阻塞 MultiTerminalView 的
+            //   "Restoring sessions..." 全屏 loading（蜂窝 RTT 1-3 秒）。现在直接把 restore history
+            //   塞进 'connected' 事件，省掉一次 HTTP 往返，前端 UI 可以立刻渲染、scrollback 随 WS
+            //   到达即填充。tmux 模式发 capture-pane 输出（带 clear-screen 前缀，避免与 xterm 默认
+            //   内容拼接），shell 模式发 ring buffer 内容（最多 100KB）。
+            //
+            //   replayOutOfWindow=true 的语义在 sinceSeq=0 时是"你没有基线，请清空已有内容
+            //   再应用 replayChunks"。这正好覆盖客户端"localStorage hydrate 出来的缓存 buffer"
+            //   场景：缓存内容会被服务端权威版本干净地替换，不会出现重复或顺序错位。
+            let replayChunks = [];
+            let replayLastSeq = 0;
+            let replayOutOfWindow = false;
+            if (attachment) {
+                if (ws.readyState !== ws.OPEN)
+                    return;
+                delivery.setActive(outputWanted && !clientPaused);
+                if (delivery.active) {
+                    const screen = new TmuxInitialScreen();
+                    initialScreen = screen;
+                    if (!await attachment.open(clientCols, clientRows)) {
+                        screen.cancel();
+                        return;
+                    }
+                    const first = await screen.ready;
+                    if (initialScreen === screen)
+                        initialScreen = null;
+                    if (first.status === 'cancelled' || ws.readyState !== ws.OPEN)
+                        return;
+                    if (first.status === 'overflow')
+                        throw new Error('Initial tmux screen exceeded output budget');
+                    // Bootstrap with the actual first PTY redraw, not a standalone empty
+                    // reset followed by the screen in a second client write. Subsequent
+                    // bytes already wait in delivery and retain their original ordering.
+                    replayChunks = first.data ? [first.data] : ['\x1bc'];
+                }
+                else {
+                    replayChunks = ['\x1bc'];
+                }
+                replayOutOfWindow = true;
             }
-        }
-        catch { /* ignore */ }
-        // 计算重连补帧：
-        // - sinceSeq > 0：短线重连，shell 模式按 seq 补增量；超出窗口则发 outOfWindow + 全量。
-        // - sinceSeq == 0：首次连接（包括手机 PWA 冷启动）。以前这里只回 lastSeq、不带数据，
-        //   靠客户端单独走 HTTP /attach 拿 scrollback；但那条路径会阻塞 MultiTerminalView 的
-        //   "Restoring sessions..." 全屏 loading（蜂窝 RTT 1-3 秒）。现在直接把 restore history
-        //   塞进 'connected' 事件，省掉一次 HTTP 往返，前端 UI 可以立刻渲染、scrollback 随 WS
-        //   到达即填充。tmux 模式发 capture-pane 输出（带 clear-screen 前缀，避免与 xterm 默认
-        //   内容拼接），shell 模式发 ring buffer 内容（最多 100KB）。
-        //
-        //   replayOutOfWindow=true 的语义在 sinceSeq=0 时是"你没有基线，请清空已有内容
-        //   再应用 replayChunks"。这正好覆盖客户端"localStorage hydrate 出来的缓存 buffer"
-        //   场景：缓存内容会被服务端权威版本干净地替换，不会出现重复或顺序错位。
-        let replayChunks = [];
-        let replayLastSeq = 0;
-        let replayOutOfWindow = false;
-        if (sinceSeq > 0 && session.mode === 'shell') {
-            const since = getHistorySince(sessionId, sinceSeq);
-            replayChunks = since.chunks.map((c) => c.data);
-            replayLastSeq = since.lastSeq;
-            replayOutOfWindow = since.outOfWindow;
-        }
-        else {
-            // 首次连接：直接补全量 scrollback，并强制让客户端清空已有内容（处理缓存 hydrate）
-            try {
-                replayChunks = await getRestoreHistory(sessionId, session);
+            else if (sinceSeq > 0 && session.mode === 'shell') {
+                const since = getHistorySince(sessionId, sinceSeq);
+                replayChunks = since.chunks.map((c) => c.data);
+                replayLastSeq = since.lastSeq;
+                replayOutOfWindow = since.outOfWindow;
             }
-            catch (error) {
-                console.warn(`[ws] getRestoreHistory failed for ${sessionId}: ${getErrorMessage(error)}`);
-                replayChunks = [];
+            else {
+                // 首次连接：直接补全量 scrollback，并强制让客户端清空已有内容（处理缓存 hydrate）
+                try {
+                    replayChunks = session.mode === 'shell' ? getReconnectionHistory(sessionId) : await getRestoreHistory(sessionId, session);
+                }
+                catch (error) {
+                    console.warn(`[ws] getRestoreHistory failed for ${sessionId}: ${getErrorMessage(error)}`);
+                    replayChunks = [];
+                }
+                replayLastSeq = session.mode === 'shell' ? getHistoryLastSeq(sessionId) : 0;
+                replayOutOfWindow = replayChunks.length > 0;
             }
-            replayLastSeq = session.mode === 'shell' ? getHistoryLastSeq(sessionId) : 0;
-            replayOutOfWindow = replayChunks.length > 0;
-        }
-        // Send connected event (after initial detection)
-        const runtime = globalThis.Bun ? 'bun' : 'node';
-        ws.send(JSON.stringify({
-            type: 'connected',
-            runtime,
-            ptyBackend: session.ptyBackend || 'unknown',
-            mode: session.mode,
-            tmuxSessionName: session.tmuxSessionName,
-            cwd: session.cwd ?? null,
-            activeProgram: session.activeProgram?.command ?? getPersistedActiveProgramForBackend(sessionId),
-            activeProgramRaw: session.activeProgram?.rawArgs ?? null,
-            activeProgramSource: session.activeProgram?.source ?? null,
-            tuiProgress: session.tuiProgress,
-            shellTitle: session.lastOscTitle,
-            promptState: session.lastPromptState,
-            focusTrackingRequested: session.focusTrackingRequested,
-            // 短线重连补帧：
-            // replayChunks 为补发数据；replayLastSeq 是客户端应记录的新基线；
-            // replayOutOfWindow 表示客户端基线已被服务端淘汰，前端可以选择清屏后再回放。
-            replayChunks,
-            replayLastSeq,
-            replayOutOfWindow,
-        }));
-        // Rich agent state rides its own message (see the SSE path above).
-        if (session.agent || session.agentSession || session.agentResumeRecovered) {
-            ws.send(JSON.stringify(buildAgentStatusPayload(sessionId, session)));
-        }
-        if (session.gitStatus) {
-            ws.send(JSON.stringify({ type: 'git-status', gitStatus: session.gitStatus }));
-        }
-    })();
+            if (ws.readyState !== ws.OPEN)
+                return;
+            // Empty authoritative histories still need to clear an obsolete baseline.
+            if (sinceSeq === 0 && replayChunks.length === 0) {
+                replayChunks = ['\x1bc'];
+                replayOutOfWindow = true;
+            }
+            // Send connected event (after initial detection)
+            const runtime = globalThis.Bun ? 'bun' : 'node';
+            ws.send(JSON.stringify({
+                type: 'connected',
+                streamEpoch: TERMINAL_STREAM_EPOCH,
+                outputProtocol: options.flowControl ? 2 : undefined,
+                runtime,
+                ptyBackend: session.ptyBackend || 'unknown',
+                mode: session.mode,
+                tmuxSessionName: session.tmuxSessionName,
+                cwd: session.cwd ?? null,
+                activeProgram: session.activeProgram?.command ?? getPersistedActiveProgramForBackend(sessionId),
+                activeProgramRaw: session.activeProgram?.rawArgs ?? null,
+                activeProgramSource: session.activeProgram?.source ?? null,
+                tuiProgress: session.tuiProgress,
+                shellTitle: session.lastOscTitle,
+                promptState: session.lastPromptState,
+                focusTrackingRequested: session.focusTrackingRequested,
+                // 短线重连补帧：
+                // replayChunks 为补发数据；replayLastSeq 是客户端应记录的新基线；
+                // replayOutOfWindow 表示客户端基线已被服务端淘汰，前端可以选择清屏后再回放。
+                replayChunks,
+                replayLastSeq,
+                replayOutOfWindow,
+            }));
+            delivery.finishReplay(replayLastSeq);
+            // Rich agent state rides its own message (see the SSE path above).
+            if (session.agent || session.agentSession || session.agentResumeRecovered) {
+                ws.send(JSON.stringify(buildAgentStatusPayload(sessionId, session)));
+            }
+            if (session.gitStatus) {
+                ws.send(JSON.stringify({ type: 'git-status', gitStatus: session.gitStatus }));
+            }
+        })().catch((error) => {
+            initialScreen?.cancel();
+            initialScreen = null;
+            console.warn(`[ws] replay failed session=${sessionId}: ${getErrorMessage(error)}`);
+            if (ws.readyState === ws.OPEN)
+                ws.close(1011, 'Replay unavailable');
+        }).finally(() => { replayRequest = null; });
+        return replayRequest;
+    };
+    if (attachment)
+        independentTmuxReplays.set(ws, async () => {
+            attachment.close();
+            initialScreen?.cancel();
+            await replayRequest;
+            if (ws.readyState === ws.OPEN)
+                await sendReplay(0);
+        });
+    void sendReplay();
     // Tmux layout polling (per-client, like the SSE stream does)
     let tmuxInterval = null;
     let activeProgramInterval = null;
@@ -7284,11 +7339,12 @@ export function handleTerminalWebSocket(ws, sessionId, clientId, options = {}) {
                 case 'input': {
                     if (typeof msg.data === 'string' && msg.data.length > 0) {
                         const data = msg.data;
-                        if (session.mode === 'tmux') {
+                        if (attachment) {
+                            session.lastActivity = Date.now();
+                            attachment.write(data);
+                        }
+                        else if (session.mode === 'tmux') {
                             await enqueueTmuxIo(session, async () => {
-                                if (isTmuxWheelInput(data)) {
-                                    await syncTmuxScreenBeforeScroll(sessionId, clientId, session, ws);
-                                }
                                 session.lastActivity = Date.now();
                                 session.ptyProcess.write(data);
                             });
@@ -7303,34 +7359,47 @@ export function handleTerminalWebSocket(ws, sessionId, clientId, options = {}) {
                 case 'resize': {
                     const cols = Number(msg.cols);
                     const rows = Number(msg.rows);
-                    if (cols > 0 && rows > 0) {
-                        const screenSyncGenerationBefore = session.tmuxResizeGeneration ?? 0;
+                    if (Number.isFinite(cols) && Number.isFinite(rows) && cols > 0 && rows > 0) {
+                        if (attachment) {
+                            const cleanCols = Math.floor(cols), cleanRows = Math.floor(rows);
+                            const sameSize = clientCols === cleanCols && clientRows === cleanRows;
+                            const ok = sameSize ? attachment.attached : attachment.resize(cleanCols, cleanRows);
+                            if (ok) {
+                                // The first resize confirms the grid supplied at attachment.
+                                // Its PTY is already drawing that grid; forcing refresh-client
+                                // here repeats the initial clear/full redraw. Later same-size
+                                // requests remain explicit display recovery requests.
+                                const needsRedraw = sameSize && !initialAttachmentResize;
+                                initialAttachmentResize = false;
+                                clientCols = cleanCols;
+                                clientRows = cleanRows;
+                                session.lastActivity = Date.now();
+                                if (needsRedraw)
+                                    await redrawTmuxClient(runTmux, session.tmuxSessionName, attachment.pid);
+                            }
+                            if (ws.readyState === ws.OPEN)
+                                ws.send(JSON.stringify({
+                                    type: 'resize-ack', seq: typeof msg.seq === 'number' ? msg.seq : undefined,
+                                    ok, cols: clientCols, rows: clientRows, screenSyncPending: false,
+                                }));
+                            break;
+                        }
+                        const sameSize = session.cols === Math.floor(cols) && session.rows === Math.floor(rows);
                         const ok = session.mode === 'tmux'
                             ? await enqueueTmuxIo(session, () => applyPtyResize(sessionId, session, cols, rows, `ws-resize:${clientId}`, clientId))
                             : applyPtyResize(sessionId, session, cols, rows, `ws-resize:${clientId}`, clientId);
-                        // A forced same-size resize is the client's explicit redraw
-                        // request. There is no geometry change for applyPtyResize to mark,
-                        // but the client still needs an authoritative grid (including the
-                        // cursor position) rather than waiting for the TUI to emit output.
-                        if (ok
-                            && session.mode === 'tmux'
-                            && (session.tmuxResizeGeneration ?? 0) === screenSyncGenerationBefore) {
-                            markTmuxClientForScreenSync(session, clientId);
-                            scheduleTmuxScreenSyncAfterResize(sessionId, session, clientId);
+                        // Same-size requests explicitly recover the display; actual geometry
+                        // changes already cause tmux to redraw its attached client.
+                        if (ok && session.mode === 'tmux' && sameSize) {
+                            await enqueueTmuxIo(session, () => redrawTmuxClient(runTmux, session.tmuxSessionName, session.ptyProcess.pid));
                         }
-                        const screenSyncGeneration = session.tmuxResizeGeneration ?? 0;
-                        const screenSyncPending = ok
-                            && session.mode === 'tmux'
-                            && screenSyncGeneration > screenSyncGenerationBefore
-                            && session.tmuxScreenSyncClients?.has(clientId) === true;
                         ws.send(JSON.stringify({
                             type: 'resize-ack',
                             seq: typeof msg.seq === 'number' ? msg.seq : undefined,
                             ok,
                             cols: session.cols,
                             rows: session.rows,
-                            screenSyncPending,
-                            screenSyncGeneration: screenSyncPending ? screenSyncGeneration : undefined,
+                            screenSyncPending: false,
                         }));
                     }
                     break;
@@ -7341,10 +7410,14 @@ export function handleTerminalWebSocket(ws, sessionId, clientId, options = {}) {
                         ws.send(JSON.stringify({ type: 'tmux-result', reqId, success: false, error: 'Not in tmux mode' }));
                         break;
                     }
+                    if (msg.action === 'switch-session') {
+                        const target = typeof msg.tmuxSessionName === 'string' ? msg.tmuxSessionName.trim() : '';
+                        await enqueueTmuxIo(session, () => switchTmuxBackendSession(sessionId, session, target));
+                        if (ws.readyState === ws.OPEN)
+                            ws.send(JSON.stringify({ type: 'tmux-result', reqId, success: true }));
+                        break;
+                    }
                     const result = await enqueueTmuxIo(session, async () => {
-                        if (msg.action === 'scroll') {
-                            await syncTmuxScreenBeforeScroll(sessionId, clientId, session, ws);
-                        }
                         return executeTmuxAction(session.tmuxSessionName, msg.action, msg, session.tmuxControl);
                     });
                     ws.send(JSON.stringify({ type: 'tmux-result', reqId, success: !result.error, error: result.error }));
@@ -7360,7 +7433,12 @@ export function handleTerminalWebSocket(ws, sessionId, clientId, options = {}) {
                 case 'focus': {
                     const focused = msg.focused === true;
                     const reason = typeof msg.reason === 'string' ? msg.reason : 'client-focus';
-                    updateClientFocusState(sessionId, session, clientId, focused, reason);
+                    if (attachment) {
+                        if (session.focusTrackingRequested)
+                            attachment.write(getFocusSequence(focused));
+                    }
+                    else
+                        updateClientFocusState(sessionId, session, clientId, focused, reason);
                     break;
                 }
                 case 'viewing': {
@@ -7375,10 +7453,41 @@ export function handleTerminalWebSocket(ws, sessionId, clientId, options = {}) {
                     }
                     break;
                 }
+                case 'output-subscription': {
+                    if (!options.flowControl || typeof msg.active !== 'boolean')
+                        break;
+                    outputWanted = msg.active;
+                    const resumed = delivery.setActive(outputWanted && !clientPaused);
+                    if (!delivery.active)
+                        attachment?.close();
+                    if (resumed && delivery.active) {
+                        void sendReplay(typeof msg.since === 'number' ? msg.since : 0, typeof msg.epoch === 'string' ? msg.epoch : undefined);
+                    }
+                    break;
+                }
+                case 'output-ack': {
+                    if (!options.flowControl || typeof msg.flowSeq !== 'number')
+                        break;
+                    delivery.acknowledge(msg.flowSeq);
+                    if (delivery.needsReplay && delivery.active) {
+                        void sendReplay(typeof msg.since === 'number' ? msg.since : 0, typeof msg.epoch === 'string' ? msg.epoch : undefined);
+                    }
+                    break;
+                }
                 case 'flow-control': {
                     if (typeof msg.paused === 'boolean') {
                         const reason = typeof msg.reason === 'string' ? msg.reason : 'client-flow-control';
-                        setClientFlowPaused(sessionId, session, clientId, msg.paused, reason);
+                        if (options.flowControl) {
+                            const wasPaused = clientPaused;
+                            clientPaused = msg.paused;
+                            delivery.setActive(outputWanted && !clientPaused);
+                            if (!delivery.active)
+                                attachment?.close();
+                            if (wasPaused && delivery.active)
+                                void sendReplay(0);
+                        }
+                        else
+                            setClientFlowPaused(sessionId, session, clientId, msg.paused, reason);
                     }
                     break;
                 }
@@ -7412,6 +7521,9 @@ export function handleTerminalWebSocket(ws, sessionId, clientId, options = {}) {
     });
     // Cleanup on close
     ws.on('close', () => {
+        initialScreen?.cancel();
+        initialScreen = null;
+        attachment?.close();
         if (tmuxInterval)
             clearInterval(tmuxInterval);
         if (activeProgramInterval)
@@ -7423,8 +7535,8 @@ export function handleTerminalWebSocket(ws, sessionId, clientId, options = {}) {
                 wsClients.delete(sessionId);
             }
         }
-        removeClientFocus(sessionId, session, clientId);
-        clearTmuxScreenSyncTimer(session, clientId);
+        if (!attachment)
+            removeClientFocus(sessionId, session, clientId);
         if (options.pushClientId) {
             setClientViewingSession(options.pushClientId, sessionId, false);
         }