termdock 1.4.311 → 1.4.312

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,11 @@ 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-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 +449,10 @@ 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: '启动操作已变化，重新检查当前启动记录',
     TMUX_PANE_IN_MODE: '目标面板处于 tmux 模式（如滚动查看），按键已跳过',
 };
 export function deliveryDiagnosticText(lastError) {

package/dist/server/agent/integrationServer.js

@@ -224,6 +224,7 @@ 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',
             integration_policy_update: true,
             session_restore_diagnostics: true,
             native_identity_linux_flock_owner: process.platform === 'linux',

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 { 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 +966,7 @@ function normalizePersistedClientSession(input) {
             ? candidate.shellTitle
             : null,
         agentResume: normalizePersistedAgentResumeInfo(candidate.agentResume),
+        agentLaunchCheck: normalizeAgentLaunchCheck(candidate.agentLaunchCheck),
     };
 }
 function generateTmuxSessionName() {
@@ -1450,15 +1452,53 @@ function searchMetadataForBackend(backendSessionId, session) {
 function writeTerminalInput(session, value) {
     session.ptyProcess.write(value.replace(/\r?\n/g, '\r'));
 }
-function deliverAutomationPromptWhenReady(backendSessionId, prompt, attempt = 0) {
+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 } });
+    await persistGlobalStateNow();
+}
+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;
+}
+async function deliverAutomationPromptWhenReady(backendSessionId, prompt, attempt = 0) {
     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 (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(() => deliverAutomationPromptWhenReady(backendSessionId, prompt, attempt + 1), 250);
+    setTimeout(() => { void deliverAutomationPromptWhenReady(backendSessionId, prompt, attempt + 1).catch(error => console.error('[automation] terminal write failed:', getErrorMessage(error))); }, 250);
 }
 async function runAgentAutomation(automation, req) {
     const run = automationStore.beginRun(automation);
@@ -1469,13 +1509,16 @@ 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);
+            if (record.agentLaunchCheck)
+                await deliverAutomationPromptWhenReady(record.backendSessionId, message);
+            else
+                await writeBracketedPrompt(backend.ptyProcess, message);
         }
         else {
             const request = req ?? {};
@@ -1489,11 +1532,15 @@ async function runAgentAutomation(automation, req) {
             const backend = terminalSessions.get(opened.terminalSession.sessionId);
             if (!backend)
                 throw new Error('自动任务会话创建失败');
-            if (automation.command)
+            if (automation.command) {
+                const agent = detectAgentFromCommand(automation.command, agentCustomCommands());
+                if (agent)
+                    await beginAgentLaunchCheck(frontendSessionId, agent.slug);
                 writeTerminalInput(backend, `${automation.command}\r`);
+            }
             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);
             }
@@ -1580,7 +1627,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 +1646,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 +1711,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.
  */
@@ -1684,13 +1731,16 @@ async function resolveCollaborationRoute(frontendSessionId) {
         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));
         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,
@@ -1726,8 +1776,15 @@ async function resolveCollaborationRoute(frontendSessionId) {
     }
     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));
     const target = backend;
+    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,
@@ -1740,15 +1797,17 @@ async function resolveCollaborationRoute(frontendSessionId) {
             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 +1851,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);
@@ -2096,6 +2156,7 @@ async function launchIntegrationTerminal(record, restoring, prepared) {
         backend.agentSession = null;
         backend.agent = null;
         backend.agentResumeRecovered = false;
+        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']);
         broadcastClientState();
@@ -2144,6 +2205,7 @@ 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 });
@@ -4247,7 +4309,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 +4348,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(),
                 };
             }
@@ -6752,6 +6819,7 @@ router.post('/operations/execution-archives/:sessionId/restore', executionArchiv
         broadcastClientState();
         throw error;
     }
+    await beginAgentLaunchCheck(record.sessionId, target.slug, target.nativeSessionId);
     writeTerminalInput(backend, `${command}\r`);
     restoreArchivedMembership(entry, record.sessionId);
     await persistGlobalStateNow();
@@ -7990,7 +8058,16 @@ 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);
+            await writeBracketedPrompt(session.ptyProcess, target.command);
+        };
+        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,21 @@ 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 在新承载上重新记录检查。
+
 任务完成继续以负责人明确 `report complete` 为准。
 
 恢复保留原 TD ID、原生 ID、argv/model/cwd/包装器配置。原会话已经精确运行时直接

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "termdock",
-  "version": "1.4.311",
+  "version": "1.4.312",
   "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.312",
   "runtimeProtocolVersion": 1,
   "minimumDesktopVersion": "1.4.46",
   "nodeMajor": 22,
   "dependencyHash": "sha256-oaGYi/P5ob8sd6VnNBOwshKozjhdV+hYiCmLAsn5x00=",
-  "serverBundleHash": "sha256-7L8T4bDJQ154U8PiMQzdpuoJqJC2mFUEmqyAR8CeyBc=",
+  "serverBundleHash": "sha256-3z8IRTcO44/bc2KIMkaUKGeZbMd7loehrVjqv4I0pGI=",
   "clientBundleHash": "sha256-rSq/8EDPH8i6WLa9SUHpZCeR4b5vZUPiTUusapoxjBs=",
   "entrypoint": "dist/server/cli.js",
   "clientEntrypoint": "dist/client/index.html"