termdock 1.4.311 → 1.4.313

package/dist/server/agent/agentLaunchCheck.js

@@ -0,0 +1,22 @@
+export function normalizeAgentLaunchCheck(input) {
+    if (!input || typeof input !== 'object')
+        return null;
+    const value = input;
+    if (typeof value.id !== 'string' || !value.id || typeof value.agentSlug !== 'string' || !value.agentSlug
+        || !Number.isFinite(value.deadline) || !(value.nativeSessionId === null || typeof value.nativeSessionId === 'string'))
+        return null;
+    return { id: value.id, agentSlug: value.agentSlug, nativeSessionId: value.nativeSessionId, deadline: value.deadline };
+}
+/** Caller supplies current terminal process evidence, never screen text or cached hooks. */
+export function agentLaunchBlockReason(check, observed, now = Date.now()) {
+    if (!check)
+        return null;
+    // A late actual observation can resolve an earlier timeout without retyping.
+    if (observed.agentSlug === check.agentSlug
+        && (!check.nativeSessionId || observed.nativeSessionId === check.nativeSessionId))
+        return null;
+    if (observed.agentSlug && observed.agentSlug !== check.agentSlug
+        || check.nativeSessionId && observed.nativeSessionId && observed.nativeSessionId !== check.nativeSessionId)
+        return 'AGENT_LAUNCH_IDENTITY_MISMATCH';
+    return now >= check.deadline ? 'AGENT_LAUNCH_TIMEOUT' : 'AGENT_LAUNCH_PENDING';
+}

package/dist/server/agent/collaborationCli.js

@@ -175,6 +175,14 @@ Idempotency retention: 7 days. Terminal delivery, ACK and result never imply eac
 Delivery semantics: delivered records completion of terminal write calls;
 it does not guarantee receipt, submission, consumption or task completion; a timeout stops waiting, it does not cancel delivery.
 Terminal input: paste once, wait 50ms, send one unbracketed CR (Enter).
+TD automatic prompts, launch commands and drive keys share each transport's input queue.
+Waiting input is bound to its original runtime; TERMINAL_INPUT_TARGET_CHANGED
+means the terminal or TD launch changed, not that an Agent rejected the message.
+TD-started/resumed Agents: the first delivery waits for current Agent process and
+terminal binding (exact native id on resume); cold starts do not require a native id.
+AGENT_LAUNCH_PENDING/TIMEOUT leaves the body queued with no terminal write.
+This one-time launch check is not application input-ready; subsequent messages
+and ordinary terminals follow the existing path. No screen text or hooks required.
 No paste-marker recognition, automatic extra Enter or consumption checks.
 The service cannot see whether the recipient's agent consumed a message.
 Use explicit replies as evidence. A screen snapshot is only an observation;
@@ -444,6 +452,11 @@ const DELIVERY_DIAGNOSTICS = {
     DELIVERY_IN_PROGRESS: '投递进行中（写入前的中间标记，正常会在数秒内推进为 delivered 或带原因的重试）',
     TERMINAL_WRITE_FAILED: '写入对方终端失败，会按重试间隔继续尝试',
     TMUX_PANE_CHANGED: '目标面板已变化，投递已跳过，等待重新绑定',
+    AGENT_LAUNCH_PENDING: 'TD 启动的 Agent 尚未确认运行和终端绑定；消息保留队列，尚未写入',
+    AGENT_LAUNCH_TIMEOUT: '120 秒内未观察到目标 Agent；消息保留，未盲投，不证明应用故障',
+    AGENT_LAUNCH_IDENTITY_MISMATCH: '启动后的 Agent 或恢复 UUID 不匹配；消息保留，未写入',
+    AGENT_LAUNCH_CHANGED: '启动操作已变化，重新检查当前启动记录',
+    TERMINAL_INPUT_TARGET_CHANGED: '等待写入时终端承载或 TD 启动代次发生变化，旧操作未继续写入新承载；请核对回执与快照',
     TMUX_PANE_IN_MODE: '目标面板处于 tmux 模式（如滚动查看），按键已跳过',
 };
 export function deliveryDiagnosticText(lastError) {

package/dist/server/agent/collaborationTmuxDelivery.js

@@ -1,5 +1,6 @@
 import { plainCollaborationSnapshot } from './collaborationText.js';
 import { normalizePromptForPaste, waitForPromptSubmit } from './promptDelivery.js';
+import { serializeTerminalInput } from './terminalInput.js';
 const TMUX_KEY_NAMES = {
     enter: 'Enter', escape: 'Escape', space: 'Space', left: 'Left', right: 'Right', up: 'Up', down: 'Down',
 };
@@ -31,21 +32,18 @@ async function assertSamePane(run, pane) {
 /** Unique-per-process buffer name so concurrent deliveries to different panes
  *  never share (or clobber) a buffer. */
 let bufferSequence = 0;
-const paneWrites = new Map();
+function paneInputKey(pane) {
+    return `${pane.serverPid}:${pane.sessionId}:${pane.paneId}:${pane.panePid}`;
+}
 /** Serialize TD paste/submit pairs for this exact runtime pane. */
-export function writeCollaborationTmuxPane(run, pane, prompt, stdin) {
-    const key = `${pane.serverPid}:${pane.sessionId}:${pane.paneId}:${pane.panePid}`;
-    const previous = paneWrites.get(key) ?? Promise.resolve();
-    const operation = previous.catch(() => undefined).then(() => writeTmuxPrompt(run, pane, prompt, stdin))
-        .finally(() => { if (paneWrites.get(key) === operation)
-        paneWrites.delete(key); });
-    paneWrites.set(key, operation);
-    return operation;
+export function writeCollaborationTmuxPane(run, pane, prompt, stdin, assertCurrent) {
+    return serializeTerminalInput(paneInputKey(pane), () => writeTmuxPrompt(run, pane, prompt, stdin, assertCurrent));
 }
 async function writeTmuxPrompt(run, pane, prompt, 
 /** Body travels on stdin so tmux cannot parse its semicolons/backslashes. */
-stdin) {
+stdin, assertCurrent) {
     await assertSamePane(run, pane);
+    assertCurrent?.();
     // A fixed pane target is independent of the current window, keyboard focus
     // and browser presence. Delivery goes through a named tmux buffer rather
     // than `send-keys -l`: while a pane is in copy-mode, literal bytes are
@@ -77,6 +75,7 @@ stdin) {
         ], normalizePromptForPaste(prompt));
         await waitForPromptSubmit();
         await assertSamePane(run, pane);
+        assertCurrent?.();
         await run([
             // The submit key rides outside the paste block: inside it, an editor
             // inserts a pasted CR as text instead of acting on it. Pasting the bare
@@ -100,10 +99,14 @@ export async function paneInMode(run, pane) {
  *  unchanged. Named keys only — no freeform keystroke passthrough. Refuses
  *  while the pane is in a mode: there the key would be taken by the mode
  *  handler (Enter in copy-mode exits the user's scroll) rather than the app. */
-export async function sendTmuxPaneKey(run, pane, key) {
+export function sendTmuxPaneKey(run, pane, key, assertCurrent) {
+    return serializeTerminalInput(paneInputKey(pane), () => sendTmuxPaneKeyUnlocked(run, pane, key, assertCurrent));
+}
+async function sendTmuxPaneKeyUnlocked(run, pane, key, assertCurrent) {
     await assertSamePane(run, pane);
     if (await paneInMode(run, pane))
         throw new Error('TMUX_PANE_IN_MODE');
+    assertCurrent?.();
     await run(['send-keys', '-t', pane.paneId, TMUX_KEY_NAMES[key]]);
 }
 /** Current pane screen text (viewport), identity-checked. */
@@ -116,14 +119,16 @@ export async function captureTmuxPaneText(run, pane, rawOutput = false) {
  *  Enter (the highlighted option). Refuses unless the screen actually shows
  *  an approval prompt: driving a dialog that isn't there would only inject
  *  a stray keystroke into the agent's work. Returns false when no dialog. */
-export async function approveCollaborationDialog(run, pane) {
-    const content = await captureTmuxPaneText(run, pane);
-    if (!detectApprovalDialog(content))
-        return false;
-    // sendTmuxPaneKey refuses in-mode panes, so a dialog-looking screen behind a
-    // user's scroll never turns Enter into copy-mode navigation.
-    await sendTmuxPaneKey(run, pane, 'enter');
-    return true;
+export function approveCollaborationDialog(run, pane, assertCurrent) {
+    return serializeTerminalInput(paneInputKey(pane), async () => {
+        assertCurrent?.();
+        const content = await captureTmuxPaneText(run, pane);
+        if (!detectApprovalDialog(content))
+            return false;
+        // The same input queue covers both the observation and requested key.
+        await sendTmuxPaneKeyUnlocked(run, pane, 'enter', assertCurrent);
+        return true;
+    });
 }
 /** History-inclusive terminal observation, without inferring consumption. */
 export async function captureTmuxPaneHistory(run, pane, lines = 800, rawOutput = false) {

package/dist/server/agent/integrationServer.js

@@ -224,6 +224,8 @@ export class IntegrationRuntime {
             startup_input_conditions: true, session_runtime_release: true, stable_session_identity: true, session_lifecycle_generation: true,
             session_resume_configuration: true, session_lifecycle_min_version: '1.4.309',
             session_startup_input_clear: true, session_startup_input_clear_min_version: '1.4.310',
+            agent_launch_process_check: true, agent_launch_process_check_min_version: '1.4.312',
+            terminal_input_runtime_fence: true, terminal_input_runtime_fence_min_version: '1.4.313',
             integration_policy_update: true,
             session_restore_diagnostics: true,
             native_identity_linux_flock_owner: process.platform === 'linux',

package/dist/server/agent/promptDelivery.js

@@ -1,3 +1,4 @@
+import { serializeTerminalInput } from './terminalInput.js';
 /**
  * Fold a prompt into the single-channel form both tmux and agent TUIs expect:
  * every line break becomes one CR (commits a line inside the editor, and is
@@ -16,18 +17,15 @@ export function waitForPromptSubmit() {
 export function buildBracketedPasteBytes(prompt) {
     return `\x1b[200~${normalizePromptForPaste(prompt)}\x1b[201~`;
 }
-const promptWrites = new WeakMap();
 /** Serialize TD prompt pairs per PTY. Success only records terminal writes. */
-export function writeBracketedPrompt(target, prompt) {
-    const previous = promptWrites.get(target) ?? Promise.resolve();
-    const operation = previous.catch(() => undefined).then(async () => {
+export function writeBracketedPrompt(target, prompt, assertCurrent) {
+    return serializeTerminalInput(target, async () => {
+        assertCurrent?.();
         target.write(buildBracketedPasteBytes(prompt));
         await waitForPromptSubmit();
+        assertCurrent?.();
         target.write('\r');
-    }).finally(() => { if (promptWrites.get(target) === operation)
-        promptWrites.delete(target); });
-    promptWrites.set(target, operation);
-    return operation;
+    });
 }
 /**
  * Process detection and hook events are independent Agent signals. A target is

package/dist/server/agent/terminalInput.js

@@ -0,0 +1,36 @@
+/** One TD input operation per actual transport, independent of application state. */
+const objectInputs = new WeakMap();
+const namedInputs = new Map();
+export function serializeTerminalInput(target, action) {
+    return typeof target === 'string' ? serializeInQueue(namedInputs, target, action)
+        : serializeInQueue(objectInputs, target, action);
+}
+function serializeInQueue(store, target, action) {
+    const previous = store.get(target) ?? Promise.resolve();
+    const operation = previous.catch(() => undefined).then(action).finally(() => {
+        if (store.get(target) === operation)
+            store.delete(target);
+    });
+    store.set(target, operation);
+    return operation;
+}
+/** Clearing a one-time launch check does not change the runtime generation. */
+export function captureTerminalInputGuard(current, expected = current()) {
+    return () => {
+        if (current() !== expected)
+            throw new Error('TERMINAL_INPUT_TARGET_CHANGED');
+    };
+}
+/** Await the actual write instead of leaving detached timers after reporting success. */
+export async function waitAndWriteTerminalInput(input) {
+    for (let attempt = 0;; attempt++) {
+        input.assertCurrent();
+        const ready = await input.ready(attempt);
+        input.assertCurrent();
+        if (ready) {
+            await input.write();
+            return;
+        }
+        await new Promise(resolve => setTimeout(resolve, 250));
+    }
+}

package/dist/server/routes/terminal.js

@@ -50,6 +50,8 @@ 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 } from '../agent/terminalInput.js';
+import { agentLaunchBlockReason, normalizeAgentLaunchCheck } from '../agent/agentLaunchCheck.js';
 import { prepareSupervisionEnable } from '../utils/enableSupervision.js';
 import { buildServerHealthState, dismissServerHealth } from '../utils/serverHealth.js';
 import { collaborationRoutes } from '../agent/collaborationRoutes.js';
@@ -965,6 +967,9 @@ function normalizePersistedClientSession(input) {
             ? candidate.shellTitle
             : null,
         agentResume: normalizePersistedAgentResumeInfo(candidate.agentResume),
+        agentLaunchCheck: normalizeAgentLaunchCheck(candidate.agentLaunchCheck),
+        agentLaunchGeneration: typeof candidate.agentLaunchGeneration === 'string' ? candidate.agentLaunchGeneration
+            : normalizeAgentLaunchCheck(candidate.agentLaunchCheck)?.id ?? null,
     };
 }
 function generateTmuxSessionName() {
@@ -1447,18 +1452,95 @@ 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');
+    const id = randomUUID();
+    upsertGlobalSessionRecord({ ...record, agentLaunchGeneration: id, agentLaunchCheck: { id, agentSlug, nativeSessionId, deadline: Date.now() + 120_000 } });
+    await persistGlobalStateNow();
 }
-function deliverAutomationPromptWhenReady(backendSessionId, prompt, attempt = 0) {
-    const session = terminalSessions.get(backendSessionId);
-    if (!session)
-        return;
-    if (canDeliverPromptToAgent(session) || attempt >= 60) {
-        void writeBracketedPrompt(session.ptyProcess, prompt).catch((error) => console.error('[automation] terminal write failed:', getErrorMessage(error)));
-        return;
+async function observeAgentLaunchCheck(record, observed) {
+    const check = record.agentLaunchCheck;
+    if (!check)
+        return null;
+    const reason = agentLaunchBlockReason(check, observed);
+    if (reason)
+        return { state: 'recovering', reason };
+    const latest = globalSessionState.sessions.find(candidate => candidate.sessionId === record.sessionId);
+    if (!latest)
+        return { state: 'offline', reason: 'SESSION_REMOVED' };
+    if (latest.agentLaunchCheck?.id !== check.id)
+        return { state: 'recovering', reason: 'AGENT_LAUNCH_CHANGED' };
+    upsertGlobalSessionRecord({ ...latest, agentLaunchCheck: null });
+    await persistGlobalStateNow();
+    return null;
+}
+function terminalInputGuard(record) {
+    const frontendSessionId = record.sessionId;
+    const backendSessionId = record.backendSessionId;
+    const generation = captureTerminalInputGuard(() => globalSessionState.sessions
+        .find(candidate => candidate.sessionId === frontendSessionId)?.agentLaunchGeneration ?? null, 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');
+        generation();
+        if (latest.backendSessionId !== backendSessionId
+            || backendSessionId && terminalSessions.get(backendSessionId) !== backend)
+            throw new Error('TERMINAL_INPUT_TARGET_CHANGED');
+    };
+}
+/** tmux input always uses the pane queue, including automation and launch commands. */
+async function automaticTerminalInput(record, assertCurrent = terminalInputGuard(record)) {
+    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);
     }
-    setTimeout(() => deliverAutomationPromptWhenReady(backendSessionId, prompt, attempt + 1), 250);
+    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);
+}
+async function writeAutomaticTerminalPrompt(frontendSessionId, prompt) {
+    const record = globalSessionState.sessions.find(candidate => candidate.sessionId === frontendSessionId);
+    if (!record)
+        throw new Error('SESSION_REMOVED');
+    const write = await automaticTerminalInput(record);
+    await write(prompt);
+}
+async function deliverAutomationPromptWhenReady(backendSessionId, prompt) {
+    const session = terminalSessions.get(backendSessionId);
+    const record = globalSessionState.sessions.find(candidate => candidate.backendSessionId === backendSessionId);
+    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');
+            return false;
+        } });
 }
 async function runAgentAutomation(automation, req) {
     const run = automationStore.beginRun(automation);
@@ -1469,13 +1551,13 @@ async function runAgentAutomation(automation, req) {
             const backend = record?.backendSessionId ? terminalSessions.get(record.backendSessionId) : null;
             if (!record || !backend)
                 throw new Error('目标会话当前不在线');
-            if (!canDeliverPromptToAgent(backend))
+            if (!record.agentLaunchCheck && !canDeliverPromptToAgent(backend))
                 throw new Error('目标会话当前没有运行中的 Agent');
             frontendSessionId = record.sessionId;
             const message = automation.prompt || automation.command;
             if (!message)
                 throw new Error('自动任务没有可发送的内容');
-            await writeBracketedPrompt(backend.ptyProcess, message);
+            await deliverAutomationPromptWhenReady(record.backendSessionId, message);
         }
         else {
             const request = req ?? {};
@@ -1489,16 +1571,20 @@ async function runAgentAutomation(automation, req) {
             const backend = terminalSessions.get(opened.terminalSession.sessionId);
             if (!backend)
                 throw new Error('自动任务会话创建失败');
-            if (automation.command)
-                writeTerminalInput(backend, `${automation.command}\r`);
+            if (automation.command) {
+                const agent = detectAgentFromCommand(automation.command, agentCustomCommands());
+                if (agent)
+                    await beginAgentLaunchCheck(frontendSessionId, agent.slug);
+                await writeAutomaticTerminalPrompt(frontendSessionId, automation.command);
+            }
             if (automation.prompt) {
                 if (automation.command)
-                    deliverAutomationPromptWhenReady(opened.terminalSession.sessionId, automation.prompt);
+                    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));
@@ -1580,7 +1666,7 @@ function formatLocalCollaborationMessages(frontendSessionId, messages) {
  *  agent-keyed selector can never reach it. Delivery still needs an agent (the
  *  confirm gate and prompt formatting assume a TUI); driving a terminal —
  *  run/capture — is a shell operation and works on any pane. */
-async function inspectCollaborationTmux(binding, requestedPane, allowPlainPane = false, nativeProcessIdentity = false) {
+async function inspectCollaborationTmux(binding, requestedPane, allowPlainPane = false, nativeProcessIdentity = false, freshProcess = false) {
     if (!binding.tmuxSessionName)
         return { state: 'offline', reason: 'TMUX_BINDING_MISSING' };
     const name = `=${binding.tmuxSessionName}`;
@@ -1599,12 +1685,12 @@ async function inspectCollaborationTmux(binding, requestedPane, allowPlainPane =
     const serverPid = Number((await runTmux(['display-message', '-p', '#{pid}'])).trim());
     if (!Number.isInteger(serverPid) || serverPid <= 0)
         throw new Error('TMUX_SERVER_IDENTITY_UNAVAILABLE');
-    if (nativeProcessIdentity && process.platform === 'linux')
+    if ((nativeProcessIdentity || freshProcess) && process.platform === 'linux')
         await getProcessSnapshot(true);
     const panes = await Promise.all(layout.windows.flatMap((window) => window.panes).map(async (pane) => {
         // Native identity needs the foreground argv even for a named binary;
         // pane_current_command alone cannot prove an exact resumed conversation.
-        const program = await resolveTmuxPaneProgram(pane, true);
+        const program = await resolveTmuxPaneProgram(pane, true, nativeProcessIdentity || freshProcess);
         const agent = detectAgentFromCommand(program?.rawArgs ?? program?.command ?? '', agentCustomCommands());
         const identity = nativeProcessIdentity ? await observeProgramNativeIdentity(agent, program)
             : { nativeId: agent && program?.rawArgs ? inferResumeSessionId(agent, splitCommandToArgv(program.rawArgs)) : null, failure: null };
@@ -1664,8 +1750,8 @@ async function rebindCollaborationRoute(frontendSessionId, paneId) {
     return { ...collaborationRouting.get(frontendSessionId), state: 'recovering' };
 }
 /**
- * Delivery is deliberately un-gated: any reachable recipient receives the
- * message immediately, whatever its agent is doing. Busy guessing (hook state,
+ * A TD-initiated Agent launch waits once for current process/binding evidence.
+ * Existing terminals receive messages whatever their agent is doing. Busy guessing (hook state,
  * turn phase) is the sender's job — the send receipt carries a screen
  * snapshot of the recipient after the write, and the sender judges from that.
  */
@@ -1678,19 +1764,24 @@ 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,
         agentSlug: record.agentResume?.slug ?? null, nativeSessionId: record.agentResume?.sessionId ?? null, pane: null,
     };
     if (binding.mode === 'tmux') {
-        const inspected = await inspectCollaborationTmux(binding);
+        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);
         if (!record)
             return { state: 'offline', reason: 'SESSION_REMOVED_DURING_RECOVERY' };
         const pane = inspected.pane;
+        const launch = await observeAgentLaunchCheck(record, { agentSlug: pane.agentSlug || null, nativeSessionId: pane.nativeSessionId });
+        if (launch)
+            return launch;
         // Remember the target before attachment. A failed attachment must not let
         // a subsequent active-pane change silently choose another recipient.
         const pinned = { serverPid: pane.serverPid, sessionId: pane.sessionId, paneId: pane.paneId, panePid: pane.panePid,
@@ -1717,17 +1808,28 @@ 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);
+    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;
+        const launch = await observeAgentLaunchCheck(record, { agentSlug: agent?.slug ?? null, nativeSessionId });
+        if (launch)
+            return launch;
+    }
     return { state: 'ready',
         isShell: backend.activeProgram?.source !== 'unknown' && shellNamesBackend.has(backend.activeProgram?.command?.toLowerCase() ?? ''),
         capture: async () => target.autoTitleContext,
@@ -1736,19 +1838,26 @@ 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();
         } };
 }
-async function refreshCollaborationAgentIdentity(backendSessionId, session) {
+async function refreshCollaborationAgentIdentity(backendSessionId, session, freshProcess = false) {
     let activeProgram = null;
     if (session.mode === 'shell') {
-        activeProgram = await getCachedShellActiveProgram(backendSessionId, session);
+        activeProgram = freshProcess ? await detectShellActiveProgram(session, true) : await getCachedShellActiveProgram(backendSessionId, session);
     }
     else if (session.tmuxSessionName) {
-        const layout = await getCachedTmuxLayout(session.tmuxSessionName);
+        const layout = freshProcess ? await getTmuxLayout(session.tmuxSessionName) : await getCachedTmuxLayout(session.tmuxSessionName);
+        if (freshProcess && process.platform === 'linux')
+            await getProcessSnapshot(true);
         const activePane = getActivePaneFromLayout(layout);
-        const resolved = activePane ? await resolveTmuxPaneProgram(activePane) : null;
+        const resolved = activePane ? await resolveTmuxPaneProgram(activePane, freshProcess, freshProcess) : null;
         activeProgram = resolved
             ? { ...resolved, updatedAt: Date.now() }
             : getActiveProgramFromTmuxLayout(layout);
@@ -1792,6 +1901,7 @@ async function spawnCollaborationAgentSession(req, group, sourceSessionId, input
     const backend = terminalSessions.get(opened.terminalSession.sessionId);
     if (!backend)
         throw new HttpStatusError(500, 'Agent Session 创建失败', 'COLLAB_AGENT_SESSION_FAILED');
+    await beginAgentLaunchCheck(frontendSessionId, launcher.slug);
     const latestGroup = collaborationStore.getGroup(group.id);
     if (!latestGroup || latestGroup.deleted) {
         const created = globalSessionState.sessions.find(record => record.sessionId === frontendSessionId);
@@ -1814,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,
@@ -2096,8 +2206,8 @@ async function launchIntegrationTerminal(record, restoring, prepared) {
         backend.agentSession = null;
         backend.agent = null;
         backend.agentResumeRecovered = false;
-        await runTmux(['send-keys', '-t', pinned.paneId, '-l', integrationLaunchCommand(record, restoring)]);
-        await runTmux(['send-keys', '-t', pinned.paneId, 'Enter']);
+        await beginAgentLaunchCheck(record.session_id, record.agent_slug, restoring ? record.agent_native_session_id : null);
+        await writeAutomaticTerminalPrompt(record.session_id, integrationLaunchCommand(record, restoring));
         broadcastClientState();
     });
 }
@@ -2144,11 +2254,12 @@ export function prepareCollaborationTaskWorker(task, template, dependencies, ser
                 throw error;
         }
         if (!currentAgent && (!launch || launch.backendId !== opened.terminalSession.sessionId)) {
+            await beginAgentLaunchCheck(record.sessionId, launcher.slug);
             // Persist before typing: a retry must never type the launcher into a newly booted Agent's prompt.
             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)
@@ -4247,7 +4358,7 @@ async function sampleTerminalSession(sessionId, session) {
     events.push({ type: 'tmux-layout', layout });
     return events;
 }
-async function detectShellActiveProgram(session) {
+async function detectShellActiveProgram(session, includeArguments = false) {
     const pid = getPtyProcessPid(session.ptyProcess);
     if (pid === null) {
         return null;
@@ -4286,10 +4397,15 @@ async function detectShellActiveProgram(session) {
             const foregroundRows = rows.filter((row) => row.command && row.tpgid > 0 && row.pgid === row.tpgid && !row.stat.startsWith('Z'));
             const preferredForeground = foregroundRows.find((row) => row.pid !== pid) ?? foregroundRows[foregroundRows.length - 1];
             if (preferredForeground?.command) {
+                // Startup checks need current argv, including an exact resume UUID;
+                // ordinary terminal sampling retains its existing inexpensive path.
+                const rawArgs = includeArguments
+                    ? (await execFileAsync('ps', ['-p', String(preferredForeground.pid), '-o', 'args='], { timeout: 3000, maxBuffer: 512 * 1024 })).stdout.trim() || null
+                    : null;
                 return {
                     command: preferredForeground.command,
                     source: 'shell-tty',
-                    rawArgs: null,
+                    rawArgs,
                     updatedAt: Date.now(),
                 };
             }
@@ -5799,16 +5915,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) {
@@ -6424,7 +6545,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 ?? {});
@@ -6447,6 +6568,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
@@ -6474,7 +6596,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 });
@@ -6495,14 +6617,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) {
@@ -6752,7 +6874,8 @@ router.post('/operations/execution-archives/:sessionId/restore', executionArchiv
         broadcastClientState();
         throw error;
     }
-    writeTerminalInput(backend, `${command}\r`);
+    await beginAgentLaunchCheck(record.sessionId, target.slug, target.nativeSessionId);
+    await writeAutomaticTerminalPrompt(opened.session.sessionId, command);
     restoreArchivedMembership(entry, record.sessionId);
     await persistGlobalStateNow();
     broadcastClientState();
@@ -7990,7 +8113,19 @@ router.post('/:sessionId/agent-resume', async (req, res) => {
         });
     }
     try {
-        await writeBracketedPrompt(session.ptyProcess, target.command);
+        const frontend = globalSessionState.sessions.find(candidate => candidate.backendSessionId === sessionId);
+        const launch = async () => {
+            if (frontend)
+                await beginAgentLaunchCheck(frontend.sessionId, target.slug, target.nativeSessionId);
+            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);
+        else
+            await launch();
         session.lastActivity = Date.now();
         res.json({ success: true, command: target.command });
     }

package/docs/integrations.md

@@ -504,6 +504,33 @@ session 事件；get 也会现场核验。120 秒内未形成绑定返回 `SESSI
 不自动补回车、不根据终端文字确认消费。`delivered`/`pty_written` 是现有回执字段，
 仅记录终端写入调用完成，不保证对方收到、提交、消费或执行。快照只作观测，明确回复单独关联。
 旧回执中的 `AGENT_CONSUME_UNCONFIRMED` 保留历史，不触发补键或重投。
+
+1.4.312 起，TD 实际启动/恢复 Agent 时持久记录一次进程检查意图。仅该次启动的
+首次投递在原终端观察到目标 Agent 后放行；恢复还须匹配原 native UUID，冷启动
+不要求首次输入前尚未生成的 UUID。已有会话和普通 Terminal 不新增检查；运行中
+no-op restore 不重新开启检查。检查是运行/绑定事实，不表示 TUI 已完成输入初始化。
+`startup_input_disabled` 仅清除画面条件，独立于该进程检查。capabilities 为
+`agent_launch_process_check=true`，最低运行服务 1.4.312；建议 CLI 同升以取得新诊断文案。
+
+未确认时普通消息保持 pending、实际写入次数不增加，诊断 `AGENT_LAUNCH_PENDING`；
+120 秒后 `AGENT_LAUNCH_TIMEOUT`，不同 Agent/原 UUID 为 `AGENT_LAUNCH_IDENTITY_MISMATCH`。
+不因超时盲投或重新启动，后续如果现场确实观察到正确进程可解除检查。检查随活动
+终端登记持久化，服务重启保留；新的实际启动/恢复重新生成检查 ID，旧观察不能清除
+新检查。一旦当前检查解除，后续普通消息沿原终端路由，不重复判断应用就绪/忙闲。
+已正常 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/包装器配置。原会话已经精确运行时直接

package/package.json

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

package/runtime-manifest.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
   "packageName": "termdock",
-  "version": "1.4.311",
+  "version": "1.4.313",
   "runtimeProtocolVersion": 1,
   "minimumDesktopVersion": "1.4.46",
   "nodeMajor": 22,
   "dependencyHash": "sha256-oaGYi/P5ob8sd6VnNBOwshKozjhdV+hYiCmLAsn5x00=",
-  "serverBundleHash": "sha256-7L8T4bDJQ154U8PiMQzdpuoJqJC2mFUEmqyAR8CeyBc=",
+  "serverBundleHash": "sha256-LRpuy83bfoSabTOSe76Yykebdslf8gyq1O1oiR4+Z0c=",
   "clientBundleHash": "sha256-rSq/8EDPH8i6WLa9SUHpZCeR4b5vZUPiTUusapoxjBs=",
   "entrypoint": "dist/server/cli.js",
   "clientEntrypoint": "dist/client/index.html"