termdock 1.4.384 → 1.4.385

package/dist/server/cli.js

@@ -1271,7 +1271,7 @@ async function readStdinText() {
         process.stdin.on('error', reject);
     });
 }
-async function postLocalJson(baseUrl, token, endpoint, payload, timeoutMs = 30_000) {
+async function postLocalJson(baseUrl, token, endpoint, payload, timeoutMs = 30_000, extraHeaders = {}) {
     const url = new URL(endpoint, baseUrl);
     const body = JSON.stringify(payload);
     const isHttps = url.protocol === 'https:';
@@ -1289,6 +1289,7 @@ async function postLocalJson(baseUrl, token, endpoint, payload, timeoutMs = 30_0
                 'Content-Type': 'application/json',
                 'Content-Length': Buffer.byteLength(body),
                 'X-Termdock-Local-Token': token,
+                ...extraHeaders,
             },
         }, (res) => {
             let responseBody = '';
@@ -1303,7 +1304,7 @@ async function postLocalJson(baseUrl, token, endpoint, payload, timeoutMs = 30_0
         req.end();
     });
 }
-async function getLocalJson(baseUrl, token, endpoint, timeoutMs = 30_000, method = 'GET') {
+async function getLocalJson(baseUrl, token, endpoint, timeoutMs = 30_000, method = 'GET', extraHeaders = {}) {
     const url = new URL(endpoint, baseUrl);
     const isHttps = url.protocol === 'https:';
     const requestImpl = isHttps ? https.request : http.request;
@@ -1318,6 +1319,7 @@ async function getLocalJson(baseUrl, token, endpoint, timeoutMs = 30_000, method
             ca,
             headers: {
                 'X-Termdock-Local-Token': token,
+                ...extraHeaders,
             },
         }, (res) => {
             let responseBody = '';
@@ -3456,10 +3458,17 @@ async function main() {
             return;
         }
         const baseUrl = state.localUrl ?? `${state.scheme ?? 'http'}://${state.host === '0.0.0.0' ? 'localhost' : state.host}:${state.port}`;
+        const context = await detectLocalSessionContext();
+        if (process.env.TERMDOCK === '1' && !context.backendSessionId && !context.tmuxSessionName) {
+            console.error(JSON.stringify({ ok: false, error: '无法确认 Termdock 调用会话，请在有效终端中重试' }));
+            process.exitCode = 1;
+            return;
+        }
+        const todoHeaders = { 'X-Termdock-Todo-Context': encodeURIComponent(JSON.stringify(context)) };
         process.exitCode = await executeTodoCommand(options.todo, {
             request: (method, endpoint, body) => method === 'POST'
-                ? postLocalJson(baseUrl, state.localApiToken, endpoint, body)
-                : getLocalJson(baseUrl, state.localApiToken, endpoint),
+                ? postLocalJson(baseUrl, state.localApiToken, endpoint, body, 30_000, todoHeaders)
+                : getLocalJson(baseUrl, state.localApiToken, endpoint, 30_000, 'GET', todoHeaders),
             self: () => resolveCurrentLocalSessionId(baseUrl, state.localApiToken),
             stdin: readStdinText, write: line => console.log(line),
         });

package/dist/server/routes/terminal.js

@@ -2,6 +2,7 @@ import { prepareCodexThread, codexColdLaunchArgv, codexPreparedResumeCommand } f
 import { validateSharedChatTarget } from '../agent/sharedChatTarget.js';
 import { normalizeAgentLaunchAttempt, replayAgentLaunchAttempt } from '../agent/agentLaunchAttempt.js';
 import { shouldAutomaticallyRecoverTmuxIncident } from '../utils/tmuxRecovery.js';
+import { assessTmuxRecoveryLoad, configuredTmuxRecoveryLoadBudget } from '../utils/tmuxRecoveryAdmission.js';
 import { isSharedCodexDaemon } from '../utils/codexSharedDaemon.js';
 import { confirmRecoveryAgent } from '../utils/recoveryAgentConfirmation.js';
 import { TmuxPaneOutputObserver } from '../utils/tmuxPaneOutput.js';
@@ -146,7 +147,6 @@ function sharedChatMessageAllowed(message) {
 }
 const collaborationDeliveryWorker = new CollaborationDeliveryWorker({
     store: collaborationStore,
-    peers: () => collaborationStore.list().filter((group) => !group.deleted).flatMap((group) => group.sessionIds),
     isLocal: (id) => !id.startsWith('remote:'),
     resolve: resolveCollaborationRoute,
     authorizeMessage: sharedChatMessageAllowed,
@@ -2528,8 +2528,6 @@ export const integrationSessionAdapter = {
             async destroy(target) {
                 // Kill by immutable tmux session ID, not by a potentially reused name.
                 // No process-group kill or application prompt is sent.
-                if (JSON.stringify(await observeIntegrationCloseTarget(record)) !== JSON.stringify(target))
-                    integrationError('SESSION_CLOSE_TARGET_CHANGED', 'Close target changed before teardown', 409);
                 intentionallyDeletingTmuxSessions.add(`wt-integration-${record.session_id}`);
                 try {
                     await runTmux(['kill-session', '-t', target.binding.sessionId]);
@@ -2994,154 +2992,6 @@ async function runTmuxStdin(args, input) {
     });
     return stdout;
 }
-// ---- Persistent tmux control-mode connection ----
-// Instead of spawning a new `tmux` process per command (execFile overhead),
-// maintain a single `tmux -C attach` child process per session.  Commands
-// are written to stdin and responses are parsed from stdout using tmux's
-// control-mode protocol (%begin / %end / %exit).
-const TMUX_CONTROL_ENABLED = false;
-const TMUX_CONTROL_COMMAND_TIMEOUT_MS = 2000;
-function spawnTmuxControl(sessionName) {
-    const process = tmuxClientReaper.trackControl(spawn(getTmuxBinary(), ['-u', '-C', 'attach', '-t', sessionName], {
-        stdio: ['pipe', 'pipe', 'pipe'],
-    }));
-    const control = {
-        process,
-        nextSeq: 0,
-        pending: new Map(),
-        buffer: '',
-        dead: false,
-    };
-    process.stdout?.on('data', (chunk) => {
-        control.buffer += chunk.toString();
-        const lines = control.buffer.split('\n');
-        control.buffer = lines.pop() || '';
-        for (const line of lines) {
-            // %begin <seq>  — start of command output block
-            const beginMatch = line.match(/^%begin\s+(\d+)$/);
-            if (beginMatch) {
-                // Subsequent lines (until %end) are the output.
-                continue;
-            }
-            // %end <seq>  — end of output block
-            const endMatch = line.match(/^%end\s+(\d+)$/);
-            if (endMatch) {
-                continue;
-            }
-            // %exit <seq> <code>  — command finished
-            const exitMatch = line.match(/^%exit\s+(\d+)\s+(\d+)$/);
-            if (exitMatch) {
-                const seq = parseInt(exitMatch[1], 10);
-                const code = parseInt(exitMatch[2], 10);
-                const entry = control.pending.get(seq);
-                if (entry) {
-                    control.pending.delete(seq);
-                    if (code === 0) {
-                        entry.resolve(entry.output);
-                    }
-                    else {
-                        entry.reject(new Error(`tmux command exited with code ${code}`));
-                    }
-                }
-                continue;
-            }
-            // Output line between %begin and %end — attach to the most recent
-            // pending entry (the one with the matching sequence).
-            // We don't know which seq this belongs to until %end/%exit,
-            // so stash it on the newest pending entry.
-            if (control.pending.size > 0) {
-                const lastEntry = Array.from(control.pending.values()).pop();
-                if (lastEntry) {
-                    lastEntry.output += (lastEntry.output ? '\n' : '') + line;
-                }
-            }
-        }
-    });
-    process.on('error', (err) => {
-        control.dead = true;
-        for (const [, entry] of control.pending) {
-            entry.reject(err);
-        }
-        control.pending.clear();
-    });
-    process.on('exit', () => {
-        control.dead = true;
-        for (const [, entry] of control.pending) {
-            entry.reject(new Error('tmux control process exited'));
-        }
-        control.pending.clear();
-    });
-    process.stderr?.on('data', (chunk) => {
-        console.warn(`[tmux-control ${sessionName}] ${chunk.toString().trim()}`);
-    });
-    return control;
-}
-/**
- * Send a command through the persistent control-mode connection and wait
- * for the response.  Falls back to `execFile` if the control process is
- * dead, the write fails, or the command times out.
- */
-async function sendTmuxCommand(_sessionName, control, args) {
-    if (control && !control.dead) {
-        const seq = control.nextSeq++;
-        const command = args.join(' ');
-        try {
-            return await new Promise((resolve, reject) => {
-                const timeout = setTimeout(() => {
-                    control.pending.delete(seq);
-                    reject(new Error('tmux control command timed out'));
-                }, TMUX_CONTROL_COMMAND_TIMEOUT_MS);
-                control.pending.set(seq, {
-                    resolve: (value) => { clearTimeout(timeout); resolve(value); },
-                    reject: (err) => { clearTimeout(timeout); reject(err); },
-                    output: '',
-                });
-                control.process.stdin?.write(command + '\n');
-            });
-        }
-        catch {
-            // Control mode failed — mark dead and fall through to execFile.
-            control.dead = true;
-        }
-    }
-    // Fallback: spawn a one-shot tmux process
-    return runTmux(args);
-}
-/**
- * Fire-and-forget variant for scroll commands where we don't need to wait
- * for a response.  Writes through the control process if available;
- * falls back to a one-shot execFile on any failure.
- */
-function sendTmuxCommandFireAndForget(_sessionName, control, args) {
-    if (control && !control.dead) {
-        try {
-            control.process.stdin?.write(args.join(' ') + '\n');
-            return;
-        }
-        catch {
-            control.dead = true;
-            // Fall through to execFile fallback below
-        }
-    }
-    // Fallback: spawn a one-shot process (fire-and-forget)
-    const child = execFile(getTmuxBinary(), args, { timeout: 5000 });
-    child.on('error', () => { });
-}
-function destroyTmuxControl(control) {
-    if (!control)
-        return;
-    control.dead = true;
-    for (const [, entry] of control.pending) {
-        entry.reject(new Error('tmux control process destroyed'));
-    }
-    control.pending.clear();
-    try {
-        tmuxClientReaper.stop(control.process);
-    }
-    catch {
-        // Process may already be dead
-    }
-}
 function isTmuxUnavailableMessage(errorMessage) {
     return /no such file or directory|not found|enoent/i.test(errorMessage);
 }
@@ -3452,19 +3302,23 @@ async function listLiveTmuxInventorySessions() {
         throw error;
     }
 }
+const tmuxServerPidSnapshots = new SharedSnapshotCache(0, 1, 1000);
 async function getTmuxServerPid() {
-    try {
-        const raw = (await runTmux(['display-message', '-p', '#{pid}'])).trim();
-        const pid = Number.parseInt(raw, 10);
-        if (!Number.isInteger(pid) || pid <= 0)
-            throw new Error('Invalid tmux server pid response');
-        return pid;
-    }
-    catch (error) {
-        if (isTmuxServerMissingMessage(getErrorMessage(error)))
-            return null;
-        throw error;
-    }
+    return tmuxServerPidSnapshots.get('server', async () => {
+        try {
+            const raw = (await runTmux(['display-message', '-p', '#{pid}'])).trim();
+            const pid = Number.parseInt(raw, 10);
+            if (!Number.isInteger(pid) || pid <= 0)
+                throw new Error('Invalid tmux server pid response');
+            return pid;
+        }
+        catch (error) {
+            if (isTmuxServerMissingMessage(getErrorMessage(error)))
+                return null;
+            console.warn('[tmux-recovery] Failed to read tmux server pid:', getErrorMessage(error));
+            throw error;
+        }
+    });
 }
 function getTmuxRecoveryView() {
     const incident = tmuxRecoveryState.incident;
@@ -3515,8 +3369,7 @@ async function observeTmuxServerGeneration(liveTmuxSessions, authoritativeTmuxLi
     try {
         currentServerPid = await getTmuxServerPid();
     }
-    catch (error) {
-        console.warn('[tmux-recovery] Failed to read tmux server pid:', getErrorMessage(error));
+    catch {
         return;
     }
     const liveSessionNames = new Set(liveTmuxSessions.map((session) => session.name));
@@ -3575,7 +3428,8 @@ async function observeTmuxServerGeneration(liveTmuxSessions, authoritativeTmuxLi
     }
     if (changed)
         await persistTmuxRecoveryState();
-    if (shouldAutomaticallyRecoverTmuxIncident(incident, tmuxRecoveryOperations.all().map(operation => operation.incidentId))) {
+    if (process.env.TD_TMUX_AUTO_RECOVERY === '1'
+        && shouldAutomaticallyRecoverTmuxIncident(incident, tmuxRecoveryOperations.all().map(operation => operation.incidentId))) {
         // Leave this inventory build before the worker broadcasts progress. The
         // durable key coalesces concurrent observations and prevents replay.
         setTimeout(() => {
@@ -3835,8 +3689,8 @@ function enqueueTmuxIo(session, operation) {
     session.tmuxIoChain = result.then(() => undefined, () => undefined);
     return result;
 }
-async function isTmuxPaneInMode(target, control) {
-    const paneInModeRaw = (await sendTmuxCommand(target, control, [
+async function isTmuxPaneInMode(target) {
+    const paneInModeRaw = (await runTmux([
         'display-message',
         '-t',
         target,
@@ -4846,8 +4700,8 @@ try {
 catch { /* plugin loading must never block startup */ }
 let processSnapshot = null;
 let processSnapshotPromise = null;
-const ttyProcessSnapshots = new SharedSnapshotCache(PROCESS_SNAPSHOT_CACHE_TTL_MS);
-const shellProgramSnapshots = new SharedSnapshotCache(ACTIVE_PROGRAM_POLL_INTERVAL);
+const ttyProcessSnapshots = new SharedSnapshotCache(PROCESS_SNAPSHOT_CACHE_TTL_MS, 256, 1000);
+const shellProgramSnapshots = new SharedSnapshotCache(ACTIVE_PROGRAM_POLL_INTERVAL, 256, 1000);
 function parseProcessSnapshot(stdout) {
     return stdout
         .split('\n')
@@ -5108,7 +4962,10 @@ function subscribeTerminalSampling(sessionId, session, observer) {
         shared?.sampler.stop();
         shared = {
             session,
-            sampler: new SharedSessionSampler(() => sampleTerminalSession(sessionId, session), () => session.mode === 'tmux' ? TMUX_POLL_INTERVAL : ACTIVE_PROGRAM_POLL_INTERVAL, error => console.warn(`[terminal-sampling] ${sessionId}: ${getErrorMessage(error)}`)),
+            sampler: new SharedSessionSampler(() => sampleTerminalSession(sessionId, session), () => {
+                const interval = session.mode === 'tmux' ? TMUX_POLL_INTERVAL : ACTIVE_PROGRAM_POLL_INTERVAL;
+                return session.focusAggregation.effectiveFocused ? interval : Math.max(interval, 10_000);
+            }, error => console.warn(`[terminal-sampling] ${sessionId}: ${getErrorMessage(error)}`)),
         };
         terminalSamplers.set(sessionId, shared);
     }
@@ -5487,32 +5344,19 @@ async function prepareManagedTmuxSession(sessionName, cwd) {
 async function getTmuxLayout(sessionName) {
     return readTmuxLayout(runTmux, sessionName);
 }
-let tmuxLayoutsSnapshot = null;
-let tmuxLayoutsSnapshotPromise = null;
+const tmuxLayoutsSnapshot = new SharedSnapshotCache(TMUX_LAYOUT_CACHE_TTL_MS, 1, 1000);
+const tmuxLayoutFallbacks = new SharedSnapshotCache(TMUX_LAYOUT_CACHE_TTL_MS, 256, 1000);
 async function buildTmuxLayoutsSnapshot() {
     return readTmuxLayouts(runTmux);
 }
 async function getCachedTmuxLayout(sessionName) {
-    if (tmuxLayoutsSnapshot && Date.now() - tmuxLayoutsSnapshot.fetchedAt < TMUX_LAYOUT_CACHE_TTL_MS) {
-        const cached = tmuxLayoutsSnapshot.layouts.get(sessionName);
-        if (cached)
-            return cached;
-    }
-    if (!tmuxLayoutsSnapshotPromise) {
-        tmuxLayoutsSnapshotPromise = buildTmuxLayoutsSnapshot().then((layouts) => {
-            tmuxLayoutsSnapshot = { layouts, fetchedAt: Date.now() };
-            return layouts;
-        }).finally(() => {
-            tmuxLayoutsSnapshotPromise = null;
-        });
-    }
-    const layouts = await tmuxLayoutsSnapshotPromise;
+    const layouts = await tmuxLayoutsSnapshot.get('all', buildTmuxLayoutsSnapshot);
     const layout = layouts.get(sessionName);
     if (layout)
         return layout;
     // A just-created session can race the global snapshot. Keep that rare path
     // correct without returning stale metadata for the new terminal.
-    return getTmuxLayout(sessionName);
+    return tmuxLayoutFallbacks.get(sessionName, () => getTmuxLayout(sessionName));
 }
 async function getRestoreHistory(sessionId, session) {
     // In tmux mode, scrollback belongs to tmux itself rather than the app layer,
@@ -5651,8 +5495,6 @@ function cleanupSession(sessionId, options) {
     session.autoTitleTerminal.dispose();
     lastAgentStatusSnapshots.delete(sessionId);
     lastGitStatusSnapshots.delete(sessionId);
-    destroyTmuxControl(session.tmuxControl);
-    session.tmuxControl = undefined;
     for (const timer of session.flowPausedClientTimers.values()) {
         clearTimeout(timer);
     }
@@ -5902,6 +5744,8 @@ function updateClientFocusState(sessionId, session, clientId, focused, reason) {
     const result = setClientFocusState(session.focusAggregation, clientId, focused);
     if (result.changed) {
         emitFocusSequenceIfNeeded(sessionId, session, result.effectiveFocused, reason);
+        if (result.effectiveFocused)
+            terminalSamplers.get(sessionId)?.sampler.refresh();
     }
 }
 function removeClientFocus(sessionId, session, clientId) {
@@ -6313,27 +6157,6 @@ async function spawnTerminalSessionUnlocked(req, input) {
     // First git snapshot for the pane's spawn cwd (throttle-free).
     refreshGitStatus(sessionId, session, { minIntervalMs: 0 });
     setupPtyHandlers(sessionId, session);
-    if (mode === 'tmux' && tmuxSessionName) {
-        // Session was prepared before attach so the first tmux client sees the
-        // right server/session options immediately.
-        // Spawn a persistent control-mode connection so scroll commands
-        // don't pay execFile process-spawn overhead on every frame.
-        if (TMUX_CONTROL_ENABLED) {
-            let ctrl;
-            try {
-                ctrl = spawnTmuxControl(tmuxSessionName);
-                // Verify the control process is healthy before we rely on it.
-                await sendTmuxCommand(tmuxSessionName, ctrl, ['display-message', '-p', 'ok']);
-                session.tmuxControl = ctrl;
-            }
-            catch (error) {
-                // Control process failed — clean up and fall back to execFile.
-                console.warn(`Failed to start tmux control for ${tmuxSessionName}: ${getErrorMessage(error)}`);
-                if (ctrl)
-                    destroyTmuxControl(ctrl);
-            }
-        }
-    }
     return { sessionId, session, cols, rows };
 }
 // ── pty-host adoption (shell-mode persistence across server restarts) ──
@@ -6776,13 +6599,22 @@ async function resolveTmuxRecoveryScope(scope, incident) {
 }
 tmuxRecoveryOperations.setRunner(restoreTmuxRecoverySession);
 const tmuxAgentResourceBudget = configuredAgentResourceBudget();
+const tmuxRecoveryLoadBudget = configuredTmuxRecoveryLoadBudget();
 tmuxRecoveryOperations.setAdmission(async (_operationId, sessionId) => {
     try {
+        const clientPids = await runTmux(['list-clients', '-F', '#{client_pid}']).catch(error => {
+            if (isTmuxServerMissingMessage(getErrorMessage(error)))
+                return '';
+            throw error;
+        });
+        const clientCount = clientPids.trim() ? clientPids.trim().split('\n').length : 0;
+        const load = assessTmuxRecoveryLoad(clientCount, tmuxRecoveryLoadBudget, undefined, tmuxRecoveryOperations.activeLaunches * 3);
+        if (!load.admitted)
+            return load;
         const snapshot = await collectHostResourceSnapshot();
         const managedSessions = globalSessionState.sessions.filter(item => item.mode === 'tmux' && item.tmuxSessionName);
         const liveSessions = await listLiveTmuxInventorySessions();
-        const activeRecoverySessionIds = tmuxRecoveryOperations.all().flatMap(operation => operation.items)
-            .filter(item => item.state === 'running').map(item => item.sessionId);
+        const activeRecoverySessionIds = tmuxRecoveryOperations.runningSessionIds();
         const ownedAgentSessionIds = getTermdockOwnedAgentSessionIds({ managedSessions,
             liveAgentSessions: liveSessions.filter(item => item.program && agentBySlug(item.program)).map(item => ({ name: item.name, sourceFrontendSessionId: item.sourceFrontendSessionId })),
             activeRecoverySessionIds });
@@ -6806,8 +6638,7 @@ async function sampleTmuxRecoveryHealth() {
     try {
         const [snapshot, liveSessions] = await Promise.all([collectHostResourceSnapshot(), listLiveTmuxInventorySessions()]);
         const managedSessions = globalSessionState.sessions.filter(item => item.mode === 'tmux' && item.tmuxSessionName);
-        const activeRecoverySessionIds = tmuxRecoveryOperations.all().flatMap(operation => operation.items)
-            .filter(item => item.state === 'running').map(item => item.sessionId);
+        const activeRecoverySessionIds = tmuxRecoveryOperations.runningSessionIds();
         const tdOwnedAgentSessionIds = getTermdockOwnedAgentSessionIds({ managedSessions,
             liveAgentSessions: liveSessions.filter(item => item.program && agentBySlug(item.program)).map(item => ({ name: item.name, sourceFrontendSessionId: item.sourceFrontendSessionId })),
             activeRecoverySessionIds });
@@ -7171,6 +7002,12 @@ const todoCollectionSessions = {
 };
 const todoRuntime = {
     collectionSessions: todoCollectionSessions,
+    callerSession(context) {
+        const id = resolveFrontendSessionId(context);
+        if (!id)
+            throw new TodoError('无法确认调用会话，请在有效的 Termdock 会话中重试', 403);
+        return id;
+    },
     async claimTarget(input) {
         const record = globalSessionState.sessions.find(candidate => input.sessionId ? candidate.sessionId === input.sessionId : input.backendSessionId && candidate.backendSessionId === input.backendSessionId);
         if (!record)
@@ -9630,7 +9467,7 @@ async function switchTmuxBackendSession(sessionId, session, target) {
     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]);
+    await runTmux(['switch-client', '-c', clientTty, '-t', target]);
     session.tmuxSessionName = target;
     session.lastOutputAt = 0;
     startTmuxPaneOutputActivity(sessionId, session);
@@ -9670,7 +9507,7 @@ router.post('/:sessionId/tmux', async (req, res) => {
             return res.json({ success: true, layout });
         }
         // All other actions: delegate to shared executeTmuxAction
-        const result = await executeTmuxAction(tmuxTarget, action, req.body, session.tmuxControl);
+        const result = await executeTmuxAction(tmuxTarget, action, req.body);
         if (result.error) {
             return res.status(400).json({ error: result.error });
         }
@@ -9787,7 +9624,7 @@ router.post('/force-kill', (req, res) => {
     res.json({ success: true, killedCount });
 });
 // ---- WebSocket handler (replaces SSE + HTTP POST for terminal I/O) ----
-async function executeTmuxAction(tmuxTarget, action, body, control) {
+async function executeTmuxAction(tmuxTarget, action, body) {
     let shouldBroadcastLayout = true;
     switch (action) {
         case 'copy-selection': {
@@ -9798,33 +9635,33 @@ async function executeTmuxAction(tmuxTarget, action, body, control) {
             const paneId = typeof body.paneId === 'string' ? body.paneId : '';
             if (!paneId)
                 return { shouldBroadcastLayout: false, error: 'paneId is required' };
-            await sendTmuxCommand(tmuxTarget, control, ['select-pane', '-t', paneId]);
+            await runTmux(['select-pane', '-t', paneId]);
             break;
         }
         case 'select-window': {
             const windowId = typeof body.windowId === 'string' ? body.windowId : '';
             if (!windowId)
                 return { shouldBroadcastLayout: false, error: 'windowId is required' };
-            await sendTmuxCommand(tmuxTarget, control, ['select-window', '-t', windowId]);
+            await runTmux(['select-window', '-t', windowId]);
             break;
         }
         case 'split-pane': {
             const dir = body.direction === 'h' ? '-h' : '-v';
-            await sendTmuxCommand(tmuxTarget, control, ['split-window', '-t', tmuxTarget, dir]);
+            await runTmux(['split-window', '-t', tmuxTarget, dir]);
             break;
         }
         case 'close-pane': {
             const paneId = typeof body.paneId === 'string' ? body.paneId : '';
             if (!paneId)
                 return { shouldBroadcastLayout: false, error: 'paneId is required' };
-            await sendTmuxCommand(tmuxTarget, control, ['kill-pane', '-t', paneId]);
+            await runTmux(['kill-pane', '-t', paneId]);
             break;
         }
         case 'copy-mode': {
             const enabled = body.enabled !== false;
             if (enabled) {
                 try {
-                    await sendTmuxCommand(tmuxTarget, control, ['copy-mode', '-He', '-t', tmuxTarget]);
+                    await runTmux(['copy-mode', '-He', '-t', tmuxTarget]);
                 }
                 catch (error) {
                     if (!isAlreadyInCopyModeError(getErrorMessage(error)))
@@ -9833,7 +9670,7 @@ async function executeTmuxAction(tmuxTarget, action, body, control) {
             }
             else {
                 try {
-                    await sendTmuxCommand(tmuxTarget, control, ['send-keys', '-t', tmuxTarget, '-X', 'cancel']);
+                    await runTmux(['send-keys', '-t', tmuxTarget, '-X', 'cancel']);
                 }
                 catch (error) {
                     if (!isNotInCopyModeError(getErrorMessage(error)))
@@ -9845,7 +9682,7 @@ async function executeTmuxAction(tmuxTarget, action, body, control) {
         case 'scroll': {
             const direction = body.direction === 'down' ? 'down' : 'up';
             const lines = Math.max(1, Math.min(50, Math.floor(Number(body.lines) || 1)));
-            let inCopyMode = await isTmuxPaneInMode(tmuxTarget, control);
+            let inCopyMode = await isTmuxPaneInMode(tmuxTarget);
             // Down-scroll outside copy mode: already at the live prompt, nothing to do.
             if (direction === 'down' && !inCopyMode) {
                 shouldBroadcastLayout = false;
@@ -9857,7 +9694,7 @@ async function executeTmuxAction(tmuxTarget, action, body, control) {
             if (!inCopyMode) {
                 // Re-check history_size on every entry — the pane may have
                 // accumulated scrollback since last check.
-                const histRaw = (await sendTmuxCommand(tmuxTarget, control, [
+                const histRaw = (await runTmux([
                     'display-message', '-t', tmuxTarget, '-p', '#{history_size}',
                 ])).trim();
                 const historySize = parseInt(histRaw, 10) || 0;
@@ -9868,19 +9705,18 @@ async function executeTmuxAction(tmuxTarget, action, body, control) {
                 }
                 exitedAtBottom.delete(tmuxTarget);
                 try {
-                    await sendTmuxCommand(tmuxTarget, control, ['copy-mode', '-He', '-t', tmuxTarget]);
+                    await runTmux(['copy-mode', '-He', '-t', tmuxTarget]);
                 }
                 catch (error) {
                     if (!isAlreadyInCopyModeError(getErrorMessage(error)))
                         throw error;
                 }
-                inCopyMode = await isTmuxPaneInMode(tmuxTarget, control);
+                inCopyMode = await isTmuxPaneInMode(tmuxTarget);
                 if (!inCopyMode) {
                     shouldBroadcastLayout = false;
                     break;
                 }
             }
-            // Scroll commands are fire-and-forget — don't wait for %exit.
             const scrollCmd = direction === 'up' ? 'scroll-up' : 'scroll-down';
             const fallbackCmds = direction === 'up'
                 ? ['up-line', 'cursor-up']
@@ -9888,14 +9724,7 @@ async function executeTmuxAction(tmuxTarget, action, body, control) {
             let sent = false;
             for (const cmd of [scrollCmd, ...fallbackCmds]) {
                 try {
-                    if (control && !control.dead) {
-                        sendTmuxCommandFireAndForget(tmuxTarget, control, [
-                            'send-keys', '-t', tmuxTarget, '-X', '-N', String(lines), cmd,
-                        ]);
-                    }
-                    else {
-                        await runTmux(['send-keys', '-t', tmuxTarget, '-X', '-N', String(lines), cmd]);
-                    }
+                    await runTmux(['send-keys', '-t', tmuxTarget, '-X', '-N', String(lines), cmd]);
                     sent = true;
                     break;
                 }
@@ -9908,7 +9737,7 @@ async function executeTmuxAction(tmuxTarget, action, body, control) {
                 break;
             }
             if (direction === 'down') {
-                const stillInCopyMode = await isTmuxPaneInMode(tmuxTarget, control);
+                const stillInCopyMode = await isTmuxPaneInMode(tmuxTarget);
                 if (!stillInCopyMode) {
                     exitedAtBottom.add(tmuxTarget);
                 }
@@ -9917,7 +9746,7 @@ async function executeTmuxAction(tmuxTarget, action, body, control) {
             break;
         }
         case 'new-window': {
-            await sendTmuxCommand(tmuxTarget, control, ['new-window', '-t', tmuxTarget]);
+            await runTmux(['new-window', '-t', tmuxTarget]);
             break;
         }
         case 'switch-session': {
@@ -9928,7 +9757,7 @@ async function executeTmuxAction(tmuxTarget, action, body, control) {
                 return { shouldBroadcastLayout: false, error: 'tmuxSessionName is required' };
             }
             await prepareManagedTmuxSession(targetSessionName);
-            await sendTmuxCommand(tmuxTarget, control, ['switch-client', '-t', targetSessionName]);
+            await runTmux(['switch-client', '-t', targetSessionName]);
             break;
         }
         default:
@@ -10251,7 +10080,7 @@ export function handleTerminalWebSocket(ws, sessionId, clientId, options = {}, i
                         }
                         const exitCopyMode = msg.exitCopyMode === true && session.mode === 'tmux' && !!session.tmuxSessionName;
                         inputQueue.push(exitCopyMode && msg.data === '\x1b' ? [] : parts, exitCopyMode ? async () => {
-                            await enqueueTmuxIo(session, () => executeTmuxAction(session.tmuxSessionName, 'copy-mode', { enabled: false }, session.tmuxControl));
+                            await enqueueTmuxIo(session, () => executeTmuxAction(session.tmuxSessionName, 'copy-mode', { enabled: false }));
                             // Preserve the confirmed copy-mode state for all observers without
                             // holding the first key behind a layout query or a browser ACK.
                             const target = session.tmuxSessionName;
@@ -10312,7 +10141,7 @@ export function handleTerminalWebSocket(ws, sessionId, clientId, options = {}, i
                         break;
                     }
                     const result = await enqueueTmuxIo(session, async () => {
-                        return executeTmuxAction(session.tmuxSessionName, msg.action, msg, session.tmuxControl);
+                        return executeTmuxAction(session.tmuxSessionName, msg.action, msg);
                     }).catch((error) => {
                         // A correlated copy failure must settle this socket's request, not
                         // become an unrelated terminal error followed by a 30-second wait.

package/dist/server/shared/chatPresentation.js

@@ -2,6 +2,30 @@
  * versioned opt-in, never guessed from terminal output or ordinary code fences. */
 export const CHAT_UI_VERSION = 2;
 const record = (value) => !!value && typeof value === 'object' && !Array.isArray(value);
+/** Validate new chat replies without guessing a rendering mode or rewriting JSON. */
+export function chatReplyFormatError(content, metadata) {
+    const declared = record(metadata?.openui);
+    let body;
+    try {
+        body = JSON.parse(content);
+    }
+    catch {
+        return declared ? '结构化回复必须是 JSON 对象，包含可独立阅读的 text 正文。' : undefined;
+    }
+    if (declared) {
+        if (!record(body) || typeof body.text !== 'string' || !body.text.trim() || body.text.length > 32000) {
+            return '结构化回复的 text 必须是非空 Markdown 正文，最长 32000 字符。';
+        }
+        if (body.ui !== undefined && (typeof body.ui !== 'string' || body.ui.length > 64000)) {
+            return '结构化回复的 ui 必须是界面程序字符串，最长 64000 字符。';
+        }
+        return undefined;
+    }
+    if (record(body) && typeof body.text === 'string' && Object.keys(body).every(key => key === 'text' || key === 'ui')) {
+        return '回复包含 text/ui JSON 包装，但未声明结构化格式。普通回复请直接发送 Markdown（--file 原样读取）；交互界面请按 td collab ui --text 添加 --metadata。若要展示 JSON 原文，请放入代码块。';
+    }
+    return undefined;
+}
 export function chatPresentation(content, metadata) {
     if (!record(metadata?.openui))
         return { content };