termdock 1.4.312 → 1.4.314

package/dist/server/routes/terminal.js

@@ -50,6 +50,7 @@ import { archiveTaskWorkspace, restoreTaskWorkspace, snapshotTaskWorkspace } fro
 import { isTmuxRecoveryCandidate } from '../utils/tmuxRecoveryCandidate.js';
 import { AutomationStore, normalizeAutomationSchedule } from '../agent/automationStore.js';
 import { writeBracketedPrompt, canDeliverPromptToAgent } from '../agent/promptDelivery.js';
+import { captureTerminalInputGuard, waitAndWriteTerminalInput, TerminalInputTargetChangedError } from '../agent/terminalInput.js';
 import { agentLaunchBlockReason, normalizeAgentLaunchCheck } from '../agent/agentLaunchCheck.js';
 import { prepareSupervisionEnable } from '../utils/enableSupervision.js';
 import { buildServerHealthState, dismissServerHealth } from '../utils/serverHealth.js';
@@ -967,6 +968,8 @@ function normalizePersistedClientSession(input) {
             : null,
         agentResume: normalizePersistedAgentResumeInfo(candidate.agentResume),
         agentLaunchCheck: normalizeAgentLaunchCheck(candidate.agentLaunchCheck),
+        agentLaunchGeneration: typeof candidate.agentLaunchGeneration === 'string' ? candidate.agentLaunchGeneration
+            : normalizeAgentLaunchCheck(candidate.agentLaunchCheck)?.id ?? null,
     };
 }
 function generateTmuxSessionName() {
@@ -1449,14 +1452,12 @@ function searchMetadataForBackend(backendSessionId, session) {
         updatedAt: session.lastActivity,
     };
 }
-function writeTerminalInput(session, value) {
-    session.ptyProcess.write(value.replace(/\r?\n/g, '\r'));
-}
 async function beginAgentLaunchCheck(frontendSessionId, agentSlug, nativeSessionId = null) {
     const record = globalSessionState.sessions.find(candidate => candidate.sessionId === frontendSessionId);
     if (!record)
         throw new Error('SESSION_REMOVED');
-    upsertGlobalSessionRecord({ ...record, agentLaunchCheck: { id: randomUUID(), agentSlug, nativeSessionId, deadline: Date.now() + 120_000 } });
+    const id = randomUUID();
+    upsertGlobalSessionRecord({ ...record, agentLaunchGeneration: id, agentLaunchCheck: { id, agentSlug, nativeSessionId, deadline: Date.now() + 120_000 } });
     await persistGlobalStateNow();
 }
 async function observeAgentLaunchCheck(record, observed) {
@@ -1475,30 +1476,71 @@ async function observeAgentLaunchCheck(record, observed) {
     await persistGlobalStateNow();
     return null;
 }
-async function deliverAutomationPromptWhenReady(backendSessionId, prompt, attempt = 0) {
+function terminalInputGuard(record) {
+    const frontendSessionId = record.sessionId;
+    const backendSessionId = record.backendSessionId;
+    const launchId = record.agentLaunchGeneration ?? null;
+    const backend = backendSessionId ? terminalSessions.get(backendSessionId) : undefined;
+    return () => {
+        const latest = globalSessionState.sessions.find(candidate => candidate.sessionId === frontendSessionId);
+        if (!latest)
+            throw new Error('SESSION_REMOVED');
+        const instanceMatches = !backendSessionId || terminalSessions.get(backendSessionId) === backend;
+        if ((latest.agentLaunchGeneration ?? null) !== launchId || latest.backendSessionId !== backendSessionId || !instanceMatches) {
+            throw new TerminalInputTargetChangedError({ expected_backend_session_id: backendSessionId, current_backend_session_id: latest.backendSessionId,
+                expected_launch_id: launchId, current_launch_id: latest.agentLaunchGeneration ?? null, backend_instance_matches: instanceMatches });
+        }
+    };
+}
+/** tmux input always uses the pane queue, including automation and launch commands. */
+async function automaticTerminalInput(record, assertCurrent = terminalInputGuard(record), progress) {
+    assertCurrent();
+    if (record.mode === 'tmux') {
+        const binding = collaborationRouting.get(record.sessionId) ?? {
+            sessionId: record.sessionId, backendSessionId: record.backendSessionId, mode: record.mode,
+            tmuxSessionName: record.tmuxSessionName, agentSlug: null, nativeSessionId: null, pane: null,
+        };
+        const inspected = await inspectCollaborationTmux(binding, null, true);
+        assertCurrent();
+        if (inspected.state !== 'ready' || !inspected.pane)
+            throw new Error(inspected.reason ?? 'TMUX_PANE_UNAVAILABLE');
+        const pane = inspected.pane;
+        return (prompt) => writeCollaborationTmuxPane(runTmux, pane, prompt, runTmuxStdin, assertCurrent, progress);
+    }
+    const backend = record.backendSessionId ? terminalSessions.get(record.backendSessionId) : null;
+    if (!backend)
+        throw new Error('SHELL_BACKEND_NOT_RUNNING');
+    return (prompt) => writeBracketedPrompt(backend.ptyProcess, prompt, assertCurrent, progress);
+}
+async function writeAutomaticTerminalPrompt(frontendSessionId, prompt, progress) {
+    const record = globalSessionState.sessions.find(candidate => candidate.sessionId === frontendSessionId);
+    if (!record)
+        throw new Error('SESSION_REMOVED');
+    const write = await automaticTerminalInput(record, terminalInputGuard(record), progress);
+    await write(prompt);
+}
+async function deliverAutomationPromptWhenReady(backendSessionId, prompt) {
     const session = terminalSessions.get(backendSessionId);
-    if (!session)
-        return;
     const record = globalSessionState.sessions.find(candidate => candidate.backendSessionId === backendSessionId);
-    if (record?.agentLaunchCheck) {
-        await refreshCollaborationAgentIdentity(backendSessionId, session, true);
-        const agent = detectAgentFromCommand(session.activeProgram?.rawArgs ?? session.activeProgram?.command ?? '', agentCustomCommands());
-        const nativeSessionId = agent && session.activeProgram?.rawArgs ? inferResumeSessionId(agent, splitCommandToArgv(session.activeProgram.rawArgs)) : null;
-        const blocked = await observeAgentLaunchCheck(record, { agentSlug: agent?.slug ?? null, nativeSessionId });
-        if (blocked) {
+    if (!session || !record)
+        throw new Error('SHELL_BACKEND_NOT_RUNNING');
+    const assertCurrent = terminalInputGuard(record);
+    const write = await automaticTerminalInput(record, assertCurrent);
+    await waitAndWriteTerminalInput({ assertCurrent, write: () => write(prompt), ready: async (attempt) => {
+            const latest = globalSessionState.sessions.find(candidate => candidate.sessionId === record.sessionId);
+            if (!latest.agentLaunchCheck)
+                return canDeliverPromptToAgent(session) || attempt >= 60;
+            await refreshCollaborationAgentIdentity(backendSessionId, session, true);
+            assertCurrent();
+            const agent = detectAgentFromCommand(session.activeProgram?.rawArgs ?? session.activeProgram?.command ?? '', agentCustomCommands());
+            const nativeSessionId = agent && session.activeProgram?.rawArgs ? inferResumeSessionId(agent, splitCommandToArgv(session.activeProgram.rawArgs)) : null;
+            const blocked = await observeAgentLaunchCheck(latest, { agentSlug: agent?.slug ?? null, nativeSessionId });
+            if (!blocked)
+                return true;
             if (blocked.reason !== 'AGENT_LAUNCH_PENDING')
                 throw new Error(blocked.reason ?? 'AGENT_LAUNCH_PENDING');
-            await new Promise(resolve => setTimeout(resolve, 250));
-            return deliverAutomationPromptWhenReady(backendSessionId, prompt, attempt + 1);
-        }
-        await writeBracketedPrompt(session.ptyProcess, prompt);
-        return;
-    }
-    if (canDeliverPromptToAgent(session) || attempt >= 60) {
-        void writeBracketedPrompt(session.ptyProcess, prompt).catch((error) => console.error('[automation] terminal write failed:', getErrorMessage(error)));
-        return;
-    }
-    setTimeout(() => { void deliverAutomationPromptWhenReady(backendSessionId, prompt, attempt + 1).catch(error => console.error('[automation] terminal write failed:', getErrorMessage(error))); }, 250);
+            return false;
+        } });
 }
 async function runAgentAutomation(automation, req) {
     const run = automationStore.beginRun(automation);
@@ -1515,10 +1557,7 @@ async function runAgentAutomation(automation, req) {
             const message = automation.prompt || automation.command;
             if (!message)
                 throw new Error('自动任务没有可发送的内容');
-            if (record.agentLaunchCheck)
-                await deliverAutomationPromptWhenReady(record.backendSessionId, message);
-            else
-                await writeBracketedPrompt(backend.ptyProcess, message);
+            await deliverAutomationPromptWhenReady(record.backendSessionId, message);
         }
         else {
             const request = req ?? {};
@@ -1536,16 +1575,16 @@ async function runAgentAutomation(automation, req) {
                 const agent = detectAgentFromCommand(automation.command, agentCustomCommands());
                 if (agent)
                     await beginAgentLaunchCheck(frontendSessionId, agent.slug);
-                writeTerminalInput(backend, `${automation.command}\r`);
+                await writeAutomaticTerminalPrompt(frontendSessionId, automation.command);
             }
             if (automation.prompt) {
                 if (automation.command)
                     await deliverAutomationPromptWhenReady(opened.terminalSession.sessionId, automation.prompt);
                 else
-                    await writeBracketedPrompt(backend.ptyProcess, automation.prompt);
+                    await writeAutomaticTerminalPrompt(frontendSessionId, automation.prompt);
             }
         }
-        automationStore.finishRun(run.id, 'success', frontendSessionId, '任务已投递');
+        automationStore.finishRun(run.id, 'success', frontendSessionId, '已粘贴到终端并发送回车');
     }
     catch (error) {
         automationStore.finishRun(run.id, 'failed', frontendSessionId, getErrorMessage(error));
@@ -1725,6 +1764,7 @@ async function resolveCollaborationRoute(frontendSessionId) {
     const startup = await integrationDeliveryGuard?.(frontendSessionId);
     if (startup && !startup.allowed)
         return { state: 'recovering', reason: startup.reason ?? 'SESSION_STARTUP_INPUT_PENDING' };
+    const assertGeneration = captureTerminalInputGuard(() => globalSessionState.sessions.find(candidate => candidate.sessionId === frontendSessionId)?.agentLaunchGeneration ?? null, record.agentLaunchGeneration ?? null);
     let backend = resolveOrchestrationBackend(record);
     let binding = collaborationRouting.get(frontendSessionId) ?? {
         sessionId: record.sessionId, backendSessionId: null, mode: record.mode, tmuxSessionName: record.tmuxSessionName,
@@ -1732,6 +1772,7 @@ async function resolveCollaborationRoute(frontendSessionId) {
     };
     if (binding.mode === 'tmux') {
         const inspected = await inspectCollaborationTmux(binding, undefined, false, Boolean(record.agentLaunchCheck?.nativeSessionId), Boolean(record.agentLaunchCheck));
+        assertGeneration();
         if (inspected.state !== 'ready' || !inspected.pane)
             return inspected;
         record = globalSessionState.sessions.find((candidate) => candidate.sessionId === frontendSessionId);
@@ -1767,17 +1808,21 @@ async function resolveCollaborationRoute(frontendSessionId) {
         }
         if (!backend)
             return { state: 'detached', reason: 'TMUX_BACKEND_UNAVAILABLE' };
+        assertGeneration();
+        const assertCurrent = terminalInputGuard(globalSessionState.sessions.find(candidate => candidate.sessionId === frontendSessionId));
         return { state: 'ready', isShell: pane.isShell, capture: async () => captureTmuxPaneText(runTmux, pinned), write: async (messages) => {
                 if (!globalSessionState.sessions.some((candidate) => candidate.sessionId === frontendSessionId))
                     throw new Error('SESSION_REMOVED');
-                await writeCollaborationTmuxPane(runTmux, pinned, formatLocalCollaborationMessages(frontendSessionId, messages), runTmuxStdin);
+                await writeCollaborationTmuxPane(runTmux, pinned, formatLocalCollaborationMessages(frontendSessionId, messages), runTmuxStdin, () => { assertGeneration(); assertCurrent(); });
                 backend.lastActivity = Date.now();
             } };
     }
     if (!backend || !binding.backendSessionId)
         return { state: 'offline', reason: 'SHELL_BACKEND_NOT_RUNNING' };
     await refreshCollaborationAgentIdentity(binding.backendSessionId, backend, Boolean(record.agentLaunchCheck));
+    assertGeneration();
     const target = backend;
+    const assertCurrent = terminalInputGuard(record);
     if (record.agentLaunchCheck) {
         const agent = detectAgentFromCommand(target.activeProgram?.rawArgs ?? target.activeProgram?.command ?? '', agentCustomCommands());
         const nativeSessionId = agent && target.activeProgram?.rawArgs ? inferResumeSessionId(agent, splitCommandToArgv(target.activeProgram.rawArgs)) : null;
@@ -1793,7 +1838,12 @@ async function resolveCollaborationRoute(frontendSessionId) {
                 throw new Error('SESSION_REMOVED');
             if (terminalSessions.get(binding.backendSessionId) !== target)
                 throw new Error('SHELL_BACKEND_CHANGED');
-            await writeBracketedPrompt(target.ptyProcess, formatLocalCollaborationMessages(frontendSessionId, messages));
+            await writeBracketedPrompt(target.ptyProcess, formatLocalCollaborationMessages(frontendSessionId, messages), () => {
+                assertGeneration();
+                assertCurrent();
+                if (terminalSessions.get(binding.backendSessionId) !== target)
+                    throw new Error('TERMINAL_INPUT_TARGET_CHANGED');
+            });
             target.lastActivity = Date.now();
         } };
 }
@@ -1874,7 +1924,7 @@ async function spawnCollaborationAgentSession(req, group, sourceSessionId, input
         collaborationStore.setRole({ groupId: group.id, sessionId: frontendSessionId, role: bootstrapRole });
     if (profile)
         collaborationStore.setMemberLaunchProfile(group.id, frontendSessionId, profile);
-    writeTerminalInput(backend, `${buildCollaborationSpawnCommand({ slug: launcher.slug, command: profile?.command ?? launcher.command })}\r`);
+    await writeAutomaticTerminalPrompt(frontendSessionId, buildCollaborationSpawnCommand({ slug: launcher.slug, command: profile?.command ?? launcher.command }));
     const requestedTask = typeof input.task === 'string' ? input.task.trim().slice(0, 20_000) : '';
     collaborationStore.send({
         groupId: updatedGroup.id,
@@ -1935,6 +1985,7 @@ export const integrationSessionAdapter = {
     registerDeliveryGuard(guard) { integrationDeliveryGuard = guard; return () => { if (integrationDeliveryGuard === guard)
         integrationDeliveryGuard = undefined; }; },
     pendingMessages(id) { return collaborationStore.pendingCount(id); },
+    messageHistory(id) { return collaborationStore.hasTerminalMessageHistory(id); },
     async prepareRelease(record) {
         if (collaborationStore.groupsForSession(record.session_id).some(group => group.id !== record.group_id))
             integrationError('SESSION_SCOPE_CONFLICT', 'Runtime belongs to another collaboration group; administrator must resolve its membership first', 409);
@@ -2026,21 +2077,28 @@ export const integrationSessionAdapter = {
             collaborationRouting.bind({ ...route, nativeSessionId: nativeId, pane: { ...route.pane, nativeSessionId: nativeId } });
         return { exists: true, running: Boolean(pane.agentSlug), shell: await integrationPaneIsIdleShell(pane), agentSlug: pane.agentSlug || null, nativeId };
     },
-    async create(record, prepared) {
+    async create(record, prepared, progress) {
         await listDetectedAgentLaunchers();
         if (!agentBySlug(record.agent_slug))
             integrationError('COLLAB_AGENT_UNAVAILABLE', 'Configured agent plugin is not installed');
         if (integrationTerminalRecord(record))
             integrationError('SESSION_CREATE_OUTCOME_UNKNOWN', 'Creation intent already has a terminal; inspect it instead of relaunching', 409);
-        await launchIntegrationTerminal(record, false, prepared);
+        await launchIntegrationTerminal(record, false, prepared, progress);
     },
-    async restore(record, prepared) {
+    async restore(record, prepared, progress) {
         await listDetectedAgentLaunchers();
         const agent = agentBySlug(record.agent_slug);
         if (!record.agent_native_session_id || !agent || !buildResumeCommand(agent, record.agent_native_session_id, null))
             integrationError('EXACT_RESUME_UNSUPPORTED', 'Agent plugin must support exact native resume');
+        progress?.('native_owner_check');
         await assertIntegrationNativeResumeAvailable(record);
-        await launchIntegrationTerminal(record, true, prepared);
+        await launchIntegrationTerminal(record, true, prepared, progress);
+    },
+    async retryCold(record, prepared, progress) {
+        await listDetectedAgentLaunchers();
+        if (!agentBySlug(record.agent_slug))
+            integrationError('COLLAB_AGENT_UNAVAILABLE', 'Configured agent plugin is not installed');
+        await launchIntegrationTerminal(record, false, prepared, progress, true);
     },
 };
 async function assertIntegrationNativeResumeAvailable(record) {
@@ -2091,12 +2149,28 @@ async function assertIntegrationNativeResumeAvailable(record) {
                 program: program?.command ?? null, processSource: program?.source, argumentsObserved: !!program?.rawArgs }];
     });
 }
-async function launchIntegrationTerminal(record, restoring, prepared) {
+async function launchIntegrationTerminal(record, restoring, prepared, progress, retryCold = false) {
     await collaborationDeliveryWorker.reconfigure(record.session_id, async () => {
+        progress?.('runtime_prepare');
         const group = collaborationStore.getGroup(record.group_id);
         if (!group || group.deleted)
             integrationError('TASK_GROUP_NOT_FOUND', 'Integration group no longer exists', 404);
         const original = await integrationSessionAdapter.inspect(record);
+        if (retryCold) {
+            await integrationSessionAdapter.prepareRelease(record);
+            const owned = integrationTerminalRecord(record);
+            if (!owned || globalSessionState.sessions.some(other => other.sessionId !== record.session_id
+                && (other.tmuxSessionName === owned.tmuxSessionName || owned.backendSessionId && other.backendSessionId === owned.backendSessionId))) {
+                integrationError('SESSION_IDENTITY_MISMATCH', 'Cold retry runtime lacks unique logical ownership', 409);
+            }
+            const history = collaborationStore.hasTerminalMessageHistory(record.session_id);
+            if (history === null)
+                integrationError('SESSION_MESSAGE_HISTORY_UNCONFIRMED', 'Message history cannot be verified', 409);
+            if (history || collaborationStore.pendingCount(record.session_id))
+                integrationError('SESSION_MESSAGE_HISTORY_PRESENT', 'TD message history appeared before retry', 409);
+            if (!record.terminal_binding || !original.exists || original.running || !original.shell || original.nativeId)
+                integrationError('SESSION_COLD_RETRY_RUNTIME_UNCONFIRMED', 'Original shell could not be confirmed before retry', 409);
+        }
         if (!original.exists) {
             let tmuxExists = false;
             try {
@@ -2128,6 +2202,7 @@ async function launchIntegrationTerminal(record, restoring, prepared) {
         const pane = inspected.pane;
         const pinned = { serverPid: pane.serverPid, sessionId: pane.sessionId,
             paneId: pane.paneId, panePid: pane.panePid, agentSlug: record.agent_slug, nativeSessionId: record.agent_native_session_id };
+        progress?.('binding_persist');
         prepared(pinned); // Must persist before the command enters the terminal.
         collaborationRouting.bind({ sessionId: record.session_id, backendSessionId: opened.terminalSession.sessionId,
             mode: 'tmux', tmuxSessionName: terminal.tmuxSessionName, agentSlug: record.agent_slug, nativeSessionId: record.agent_native_session_id, pane: pinned });
@@ -2145,8 +2220,11 @@ async function launchIntegrationTerminal(record, restoring, prepared) {
         // use an active-pane target which might have changed during preparation.
         if (record.resume_configuration_fingerprint && record.resume_configuration_fingerprint !== await resumeConfigurationFingerprint(record, integrationSessionAdapter))
             integrationError('RESUME_CONFIGURATION_CHANGED', 'Recovery configuration changed before terminal input', 409);
-        if (restoring)
+        if (restoring) {
+            progress?.('native_owner_check');
             await assertIntegrationNativeResumeAvailable(record);
+        }
+        progress?.('runtime_verify');
         const shell = await inspectCollaborationTmux({ sessionId: record.session_id, backendSessionId: opened.terminalSession.sessionId,
             mode: 'tmux', tmuxSessionName: terminal.tmuxSessionName, agentSlug: null, nativeSessionId: null, pane: pinned });
         if (shell.state !== 'ready' || !shell.pane || !await integrationPaneIsIdleShell(shell.pane))
@@ -2156,9 +2234,9 @@ async function launchIntegrationTerminal(record, restoring, prepared) {
         backend.agentSession = null;
         backend.agent = null;
         backend.agentResumeRecovered = false;
+        progress?.('launch_intent');
         await beginAgentLaunchCheck(record.session_id, record.agent_slug, restoring ? record.agent_native_session_id : null);
-        await runTmux(['send-keys', '-t', pinned.paneId, '-l', integrationLaunchCommand(record, restoring)]);
-        await runTmux(['send-keys', '-t', pinned.paneId, 'Enter']);
+        await writeAutomaticTerminalPrompt(record.session_id, integrationLaunchCommand(record, restoring), progress);
         broadcastClientState();
     });
 }
@@ -2210,7 +2288,7 @@ export function prepareCollaborationTaskWorker(task, template, dependencies, ser
             const temporary = `${launchFile}.${process.pid}.tmp`;
             await fs.promises.writeFile(temporary, JSON.stringify({ sessionId: record.sessionId, backendId: opened.terminalSession.sessionId }), { mode: 0o600 });
             await fs.promises.rename(temporary, launchFile);
-            writeTerminalInput(backend, `${buildCollaborationSpawnCommand({ slug: launcher.slug, command: inheritedProfile?.command ?? launcher.command })}\r`);
+            await writeAutomaticTerminalPrompt(opened.session.sessionId, buildCollaborationSpawnCommand({ slug: launcher.slug, command: inheritedProfile?.command ?? launcher.command }));
         }
         const group = collaborationStore.getGroup(task.groupId);
         if (!group || group.deleted)
@@ -5866,16 +5944,21 @@ router.post('/tmux/recovery/restore-all', async (_req, res) => {
             continue;
         }
         try {
-            await tmuxLifecycle.run(`restore:${record.tmuxSessionName}`, async () => {
+            await collaborationDeliveryWorker.reconfigure(frontendSessionId, () => tmuxLifecycle.run(`restore:${record.tmuxSessionName}`, async () => {
                 await prepareManagedTmuxSessionUnlocked(record.tmuxSessionName, record.cwd);
                 const metadata = await resolveLiveTmuxMetadata(record.tmuxSessionName);
                 const foreground = metadata?.program?.toLowerCase() ?? null;
                 if (foreground && !shellNamesBackend.has(foreground)) {
                     throw new Error(`pane is busy with ${foreground}`);
                 }
-                await runTmux(['send-keys', '-t', record.tmuxSessionName, '-l', '--', command]);
-                await runTmux(['send-keys', '-t', record.tmuxSessionName, 'Enter']);
-            });
+                // Explicit recovery may replace the vanished tmux pane. A pending
+                // message alone must never replace that binding.
+                const previous = collaborationRouting.get(frontendSessionId);
+                if (previous)
+                    collaborationRouting.bind({ ...previous, pane: null });
+                await beginAgentLaunchCheck(frontendSessionId, agent.slug, target.nativeSessionId);
+                await writeAutomaticTerminalPrompt(frontendSessionId, command);
+            }));
             outcomes.push({ sessionId: frontendSessionId, restored: true });
         }
         catch (error) {
@@ -6491,7 +6574,7 @@ router.post('/operations/orchestration/cleanup', async (req, res) => {
 // caller, tmux-local only, and `approve` refuses unless an approval dialog is
 // actually showing (Enter on the highlighted option). The dialogs may be
 // approving any command the member agent asked for; the caller is presumed to
-// own that decision (the delivery confirm gate uses the same primitive).
+// own that decision. Ordinary delivery never invokes approval automatically.
 const DRIVE_KEYS = new Set(['enter', 'escape', 'space', 'left', 'right', 'up', 'down']);
 router.post('/operations/orchestration/drive', async (req, res) => {
     const sourceSessionId = resolveFrontendSessionId(req.body ?? {});
@@ -6514,6 +6597,7 @@ router.post('/operations/orchestration/drive', async (req, res) => {
         return res.status(409).json({ error: '目标会话不是 tmux 会话，无法从 CLI 驱动（模式：' + (record.mode ?? 'unknown') + '）' });
     }
     const binding = collaborationRouting.get(target);
+    const assertCurrent = terminalInputGuard(record);
     let pane = binding?.pane ?? null;
     if (!pane) {
         // No pinned Agent pane: resolve the session's pane directly so a plain
@@ -6541,7 +6625,7 @@ router.post('/operations/orchestration/drive', async (req, res) => {
     }
     try {
         if (action === 'approve') {
-            const approved = await approveCollaborationDialog(runTmux, pane);
+            const approved = await approveCollaborationDialog(runTmux, pane, assertCurrent);
             if (!approved)
                 return res.status(409).json({ ok: false, code: 'NO_APPROVAL_DIALOG', error: '目标面板当前没有显示审批对话框；未发送任何按键' });
             return res.json({ ok: true, action, sessionId: target, approved: true });
@@ -6562,14 +6646,14 @@ router.post('/operations/orchestration/drive', async (req, res) => {
                 return res.status(400).json({ error: 'run 文本过长（上限 10000 字符）；需要更多内容请走 td collab send 投递' });
             // Same bracketed-paste write path deliveries use: one line, one submit,
             // embedded newlines stay inside the recipient's editor.
-            await writeCollaborationTmuxPane(runTmux, pane, text, runTmuxStdin);
+            await writeCollaborationTmuxPane(runTmux, pane, text, runTmuxStdin, assertCurrent);
             const snapshot = await captureTmuxPaneText(runTmux, pane);
             return res.json({ ok: true, action, sessionId: target, text, snapshot });
         }
         if (!DRIVE_KEYS.has(action)) {
             return res.status(400).json({ error: `未知动作 ${action}；可用：approve|enter|escape|space|left|right|up|down|capture|run` });
         }
-        await sendTmuxPaneKey(runTmux, pane, action);
+        await sendTmuxPaneKey(runTmux, pane, action, assertCurrent);
         res.json({ ok: true, action, sessionId: target });
     }
     catch (error) {
@@ -6820,7 +6904,7 @@ router.post('/operations/execution-archives/:sessionId/restore', executionArchiv
         throw error;
     }
     await beginAgentLaunchCheck(record.sessionId, target.slug, target.nativeSessionId);
-    writeTerminalInput(backend, `${command}\r`);
+    await writeAutomaticTerminalPrompt(opened.session.sessionId, command);
     restoreArchivedMembership(entry, record.sessionId);
     await persistGlobalStateNow();
     broadcastClientState();
@@ -8062,7 +8146,10 @@ router.post('/:sessionId/agent-resume', async (req, res) => {
         const launch = async () => {
             if (frontend)
                 await beginAgentLaunchCheck(frontend.sessionId, target.slug, target.nativeSessionId);
-            await writeBracketedPrompt(session.ptyProcess, target.command);
+            if (frontend)
+                await writeAutomaticTerminalPrompt(frontend.sessionId, target.command);
+            else
+                await writeBracketedPrompt(session.ptyProcess, target.command, captureTerminalInputGuard(() => terminalSessions.get(sessionId), session));
         };
         if (frontend)
             await collaborationDeliveryWorker.reconfigure(frontend.sessionId, launch);

package/docs/integrations.md

@@ -519,6 +519,18 @@ no-op restore 不重新开启检查。检查是运行/绑定事实，不表示 T
 新检查。一旦当前检查解除，后续普通消息沿原终端路由，不重复判断应用就绪/忙闲。
 已正常 release 的承载登记被移除，下一次 restore 在新承载上重新记录检查。
 
+1.4.313 起，定时发送、Agent 启动/恢复命令和普通消息复用实际终端的串行输入队列；
+tmux 的显式 `drive keys/approve` 也在该队列中执行，不插进正文和回车之间。
+定时发送等待实际写入调用结束后才记录成功。等待或排队中的输入绑定原承载和
+TD 启动代次，代次检查解除后仍保留；承载替换、移除或再次启动时，旧操作报
+`TERMINAL_INPUT_TARGET_CHANGED`（登记删除为 `SESSION_REMOVED`），不会跟随逻辑 ID
+写入新的承载。该检查在正文写入前及发送回车前执行；如果承载在两步之间变化，
+正文可能已写入旧终端，回车不会发给新承载。此错误不证明应用是否收到了正文，
+也不自动补键或重发正文。持久消息 worker 仍沿已有回执/路由重试规则处理失败，
+可能写入过的消息须由调用者核对。直接键盘输入不进入自动输入队列。
+能力探测为 `terminal_input_runtime_fence=true`，最低运行服务 1.4.313；CLI 同升
+可读取完整帮助和 `TERMINAL_INPUT_TARGET_CHANGED` 的诊断文案。
+
 任务完成继续以负责人明确 `report complete` 为准。
 
 恢复保留原 TD ID、原生 ID、argv/model/cwd/包装器配置。原会话已经精确运行时直接
@@ -773,6 +785,104 @@ no-op restore 不创建新检查。报告跟随会话保存并可在服务重启
 - 启动/恢复：`SESSION_CREATE_OUTCOME_UNKNOWN`, `SESSION_OPERATION_IN_PROGRESS`, `SESSION_BINDING_TIMEOUT`, `EXACT_RESUME_UNSUPPORTED`, `NATIVE_SESSION_ALREADY_RUNNING`, `NATIVE_SESSION_OWNER_UNCONFIRMED`, `AGENT_NOT_RUNNING`。
 - 未分类异常：`SESSION_LAUNCH_FAILED`, `SESSION_OBSERVATION_FAILED`；错误不包含包装器输出、密钥或原始堆栈。
 
+## 1.4.314：启动诊断与显式冷启动重试
+
+最低 CLI 和实际运行服务均为 **1.4.314**，协议仍为 1。先回读两者版本及实际服务
+`session_launch_diagnostics=true`、`session_cold_retry=true`；对应
+`*_min_version` 均为 `1.4.314`。CLI 遇到不支持重试的服务返回
+`SESSION_COLD_RETRY_UNSUPPORTED`，不发出重试请求。
+
+管理员沿用 `td integration diagnostics <TD-session-id>`，同一响应新增
+`launch_diagnostics`（可为 null）与 `launch_diagnostics_history`（最多 16 个此前实际
+启动操作）。旧 `diagnostics` 原生所有者报告字段保持兼容；该入口仅回读持久记录，
+不重新扫描进程、不挂接终端、不发送输入。313 及更早启动没有新增报告，不能从升级
+反推旧失败原因。已有失败会话可以在满足下述检查后显式重试，产生新的诊断。
+
+启动报告字段：
+
+| 字段 | 含义 |
+| --- | --- |
+| `operation_id / generation / kind` | 此次操作和承载代次；kind 为 `cold_start / cold_retry / native_restore` |
+| `phase / updated_at / steps` | 最后持久阶段和时间；steps 最多最近 24 个阶段，时间是 TD 记录时间 |
+| `error_code / reason_code` | 公开失败码及已分类原因；无法分类为 `UNCLASSIFIED_LAUNCH_ERROR`，不保存原始错误文本 |
+| `paste / submit` | 各自为 `not_attempted / attempted / write_returned`；attempted 在调用输入前持久保存，write_returned 表示调用返回 |
+| `runtime_exists` | 最后观察是否存在原承载；没有观察时为 null，不代表读取时的实时进程 |
+| `target_change` | 仅发生承载 fencing 冲突时可有：期望/当前 backend ID、期望/当前 launch ID、backend 实例是否相同 |
+
+阶段清单：`configuration`、`runtime_prepare`、`binding_persist`、
+`native_owner_check`（精确恢复）、`runtime_verify`、`launch_intent`、
+`queue_wait`、`queue_acquired`、`paste_attempted`、`paste_written`、
+`submit_attempted`、`submit_written`、`binding_observe`；中断冷重试回读到原 shell 时
+另记 `reconciled_shell`。阶段只表示 TD 实际到达的步骤，不推断私有 CLI 根因。
+崩溃在输入调用附近时，attempted 不能证明写入发生或未发生，不能据此补键。
+write_returned 不证明原生程序消费、提交、成功执行或最终结果。正文仍按原机制
+粘贴一次、等待至少 50ms、发送一次 CR；没有新的屏幕识别、启动 sleep 或额外 Enter。
+
+完整报告仅管理员可读；principal 与主动 session 事件只返回
+`launch_diagnostics_available=true`，不返回阶段、其他候选或结构证据。报告不保存
+argv、命令正文、stdout/stderr、环境变量或凭据。报告历史受上述条数及原描述总存储
+预算约束，不是无限保留的排查日志。
+
+正式冷重试命令：
+
+```sh
+td collab --principal <id> session get <TD-session-id>
+td integration diagnostics <TD-session-id>
+td collab --principal <id> session retry-cold <TD-session-id> \
+  --generation <get返回的generation> --idempotency-key <本次操作唯一键>
+```
+
+权限沿用 **session.create**，并核对记录所属 principal/本机组、原 profile 当前仍被授权、
+原 cwd 同时符合旧快照和当前目录授权。使用原启动配置快照，不接受新 argv/cwd/profile
+参数。它保留逻辑 TD ID、消息关联和旧操作证据；实际尝试递增 generation、建立新
+operation_id，状态为 starting，可能随后 binding_pending/ready/failed。返回的操作
+快照不是实时状态；用 session get 查询最新状态。
+
+只允许 failed、尚未绑定 native UUID、无 TD 消息历史/待投递且没有进行中或未确认操作
+的记录；还需核实原绑定的唯一承载仍存在、原前台 Agent 已退出、回到合格 shell。
+TD 会在生命周期锁及 worker 承载变更屏障内复核，不终止 Agent，不删除旧记录，不重建
+消失或身份不明的终端。shell 检查不声称可读取用户未提交的任意草稿，调用方仍须拥有
+输入操作权限并避免其他手工输入。TD 消息入队前设置持久、单调的历史标记；即使稍后
+入队失败也保守拒绝冷重试。314 起消息裁剪保留双方历史标记；升级前已裁剪且没有 sender 标记的
+历史无法证明完整，没有已知消息也返回未确认。旧格式或不可读存储同样拒绝；此缺口
+持久保留，不因一次正常写入而被误判已修复。
+
+必须有可信的原 launcher/plugin 恢复语义指纹且当前仍匹配；缺少指纹时管理员沿用
+resume-configuration / confirm-resume 明确核对确认，不能把路径相同当内容相同。
+指纹只覆盖 TD 已记录的 launcher 文件、原配置和插件恢复语义，不声称验证包装器依赖
+或私有 Agent 二进制全部内容。
+
+**cold retry 不是 native restore。** 无已知 UUID 时不能保证延续之前未知的原生历史，
+也不证明旧程序未创建过原生历史；重试可能创建新 UUID。已有 UUID 必须使用原
+session restore 与原生身份/重复所有者保护。原 session create 同幂等键继续回读已有
+记录，不会自动冷重试。
+
+同键同参数回读原操作结果，不再次启动；同键不同参数返回 IDEMPOTENCY_CONFLICT。
+同会话不同操作键不能并发启动。重试意图和新代次在输入前持久保存，重试期间 send/reply
+拒绝且不入队。服务重启后不会自动再启动：session get 核实原程序与 UUID 后可以转为
+ready；回读精确原 shell 则为 failed/SESSION_COLD_RETRY_INTERRUPTED，明确结束未确认
+状态，后续需新键显式重试；承载消失或仍不能确认时保留 cold_retry_pending=true 并拒绝
+发送/重试。旧操作结果未提交且出现后续代次时，同旧键返回 OPERATION_OUTCOME_UNCONFIRMED，
+不能把当前代次伪装为旧操作结果。
+
+| 拒绝码（HTTP 409，另有注明时除外） | 含义 |
+| --- | --- |
+| `INVALID_SESSION_GENERATION / SESSION_GENERATION_MISMATCH` | 未传有效数值代次 / 代次已变 |
+| `SESSION_COLD_RETRY_UNSUPPORTED` | CLI 或运行服务/adapter 不支持 |
+| `SESSION_COLD_RETRY_NATIVE_BOUND` | 已有 UUID，应走精确 restore |
+| `SESSION_COLD_RETRY_NOT_FAILED` | 当前不是 failed 冷启动 |
+| `SESSION_MESSAGE_HISTORY_PRESENT / SESSION_MESSAGE_HISTORY_UNCONFIRMED` | 有消息/入队尝试 / 无法可靠核实历史 |
+| `SESSION_COLD_RETRY_RUNTIME_UNCONFIRMED` | 无法核实原承载和退出 shell |
+| `SESSION_OPERATION_IN_PROGRESS / OPERATION_OUTCOME_UNCONFIRMED` | 操作在进行 / 前次结果须对账 |
+| `RESUME_CONFIGURATION_UNCONFIRMED / RESUME_CONFIGURATION_CHANGED` | 指纹缺失 / launcher 或恢复语义变化 |
+| `SESSION_SCOPE_CONFLICT / SESSION_IDENTITY_MISMATCH` | 跨组承载或逻辑所有权冲突 |
+| `LAUNCH_PROFILE_DENIED / SESSION_CWD_DENIED`（403） | 原 profile 或 cwd 当前不再授权 |
+
+其他启动错误仍沿用前述准确码；fencing 冲突可为
+`TERMINAL_INPUT_TARGET_CHANGED`，观察失败为 `SESSION_OBSERVATION_FAILED`，未知启动异常
+为 `SESSION_LAUNCH_FAILED`，原 shell 检查失败可为 `SESSION_TARGET_NOT_SHELL`。
+新能力并未确认 DevBox 私有 TraeX 的间歇启动原因，也不代替业务明确回复验收。
+
 ## 验收边界
 
 本版维护机验证：共享释放协议、真实 Unix socket 权限/生命周期事件、零入队拒绝、

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "termdock",
-  "version": "1.4.312",
+  "version": "1.4.314",
   "description": "A complete web-based terminal application with modern UI",
   "type": "module",
   "main": ".desktop-dist/main.js",

package/runtime-manifest.json

@@ -1,13 +1,13 @@
 {
   "schemaVersion": 1,
   "packageName": "termdock",
-  "version": "1.4.312",
+  "version": "1.4.314",
   "runtimeProtocolVersion": 1,
   "minimumDesktopVersion": "1.4.46",
   "nodeMajor": 22,
   "dependencyHash": "sha256-oaGYi/P5ob8sd6VnNBOwshKozjhdV+hYiCmLAsn5x00=",
-  "serverBundleHash": "sha256-3z8IRTcO44/bc2KIMkaUKGeZbMd7loehrVjqv4I0pGI=",
-  "clientBundleHash": "sha256-rSq/8EDPH8i6WLa9SUHpZCeR4b5vZUPiTUusapoxjBs=",
+  "serverBundleHash": "sha256-8BA4Rs7jbm4c4qf54MOmbAbAWGquvvGNzdCYk1qugCw=",
+  "clientBundleHash": "sha256-dQ3PY+dGYy454zmBVdQy9UamsgCO4JNtEHkXzfSF99k=",
   "entrypoint": "dist/server/cli.js",
   "clientEntrypoint": "dist/client/index.html"
 }

package/dist/client/assets/CollaborationTaskContent-BDQMRhU9.js

@@ -1,2 +0,0 @@
-import{bx as r}from"./app-CHxLSuGQ.js";import{b as m}from"./dnd-BCFAPC0L.js";import{b as n}from"./RightSidebar-VMdXpo4h.js";import"./react-XDCjal2T.js";import"./terminal-C7X98Amf.js";import"./App-ChS2-lkz.js";import"./gestureArbiter-DXLmNGli.js";import"./triangle-alert-xPHw25jD.js";import"./referenceLongPress-DFSrssSr.js";import"./DiffReview-DqrOcRfP.js";import"./sparkles-CapLTKAs.js";import"./DiffViewer-F-uQSmhG.js";import"./ChangeWalkthroughPanel-BlQ5-VPp.js";function g({content:o}){const e=m.useMemo(()=>n(o.split(`
-`),null,null),[o]);return r.jsx("div",{className:"min-w-0 space-y-3 break-words text-sm leading-6 text-foreground [&_h1]:text-lg [&_h2]:text-base [&_h3]:text-sm [&_pre]:max-w-full [&_table]:text-xs",children:e.map((t,i)=>r.jsx("div",{className:"min-w-0",children:typeof t.content=="function"?t.content(null):t.content},i))})}export{g as default};