termdock 1.4.320 → 1.4.322

package/dist/server/routes/terminal.js

@@ -51,7 +51,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, TerminalInputTargetChangedError } from '../agent/terminalInput.js';
+import { captureTerminalInputGuard, captureRuntimeInputGuard, waitAndWriteTerminalInput } from '../agent/terminalInput.js';
+import { mergeSessionLaunchState } from '../agent/sessionLaunchState.js';
 import { agentLaunchBlockReason, normalizeAgentLaunchCheck } from '../agent/agentLaunchCheck.js';
 import { prepareSupervisionEnable } from '../utils/enableSupervision.js';
 import { buildServerHealthState, dismissServerHealth } from '../utils/serverHealth.js';
@@ -66,7 +67,7 @@ import { SessionSearchStore } from '../agent/sessionSearchStore.js';
 import { NativeSessionSearch } from '../agent/nativeSessionSearch.js';
 import { CollaborationError } from '../agent/collaborationProtocol.js';
 import { resolveCollaborationBackend, resolveCollaborationSessionId } from '../agent/sessionBindingRecovery.js';
-import { CollaborationRoutingStore, selectCollaborationPane, selectDrivePane } from '../agent/collaborationRouting.js';
+import { CollaborationRoutingStore, selectCollaborationPane, selectDrivePane, assessCollaborationRouteIdentity } from '../agent/collaborationRouting.js';
 import { CollaborationDeliveryWorker } from '../agent/collaborationDeliveryWorker.js';
 import { approveCollaborationDialog, captureTmuxPaneHistory, captureTmuxPaneText, sendTmuxPaneKey, writeCollaborationTmuxPane } from '../agent/collaborationTmuxDelivery.js';
 import { listAllHookAgents, refreshStaleHooksAtLaunch, installHooksForSlug, uninstallHooksForSlug, } from '../agent/installers.js';
@@ -678,6 +679,9 @@ process.on('SIGINT', () => { void shutdownWithRecordings(); });
 // 服务启动时从磁盘加载（带去重，防止历史累积的重复条目复活）
 void (async () => {
     await Promise.all([loadGlobalSessionStateFromDisk(), loadTmuxRecoveryStateFromDisk()]);
+    // Delivery needs the loaded inventory, not optional PTY adoption/metadata backfill.
+    // Those steps must not leave durable messages without a background scheduler.
+    collaborationDeliveryWorker.start();
     await watchGlobalSessionStateFile();
     // pty-host adoption runs after the state load (its record upserts must not
     // be clobbered) and before pruning (surviving shell records' backends are
@@ -687,7 +691,6 @@ void (async () => {
     });
     pruneOrphanSessions();
     await backfillPersistedTmuxMetadata();
-    collaborationDeliveryWorker.start();
 })();
 caffeinateManager.startNetworkMonitor();
 // 清理磁盘恢复后后端已不存在的 session 引用。
@@ -1080,8 +1083,9 @@ async function withInventoryOpenLock(key, task) {
     inventoryOpenLocks.set(key, pending);
     return pending;
 }
-function upsertGlobalSessionRecord(record) {
-    const normalized = normalizePersistedClientSession(record);
+function upsertGlobalSessionRecord(record, launchChange) {
+    const current = globalSessionState.sessions.find(candidate => candidate.sessionId === record.sessionId);
+    const normalized = normalizePersistedClientSession(mergeSessionLaunchState(record, current, launchChange));
     if (!normalized) {
         throw new Error('invalid session record');
     }
@@ -1460,8 +1464,16 @@ async function beginAgentLaunchCheck(frontendSessionId, agentSlug, nativeSession
     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();
+    const updated = upsertGlobalSessionRecord(record, { expectedGeneration: record.agentLaunchGeneration ?? null,
+        expectedCheckId: record.agentLaunchCheck?.id ?? null, generation: id,
+        check: { id, agentSlug, nativeSessionId, deadline: Date.now() + 120_000 } });
+    // Capture the guard before persistence yields. The launch command must use
+    // this exact generation, even if another launch occurs during an await.
+    const assertCurrent = terminalInputGuard(updated);
+    assertCurrent('guard_capture');
+    await persistGlobalStateNow(true);
+    assertCurrent('launch_persisted');
+    return assertCurrent;
 }
 async function observeAgentLaunchCheck(record, observed) {
     const check = record.agentLaunchCheck;
@@ -1475,51 +1487,56 @@ async function observeAgentLaunchCheck(record, observed) {
         return { state: 'offline', reason: 'SESSION_REMOVED' };
     if (latest.agentLaunchCheck?.id !== check.id)
         return { state: 'recovering', reason: 'AGENT_LAUNCH_CHANGED' };
-    upsertGlobalSessionRecord({ ...latest, agentLaunchCheck: null });
+    upsertGlobalSessionRecord(latest, { expectedGeneration: latest.agentLaunchGeneration ?? null,
+        expectedCheckId: check.id, generation: latest.agentLaunchGeneration ?? null, check: null });
     await persistGlobalStateNow();
     return null;
 }
 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 expected = { backendSessionId, launchId: record.agentLaunchGeneration ?? null,
+        routeRevision: collaborationRouting.get(frontendSessionId)?.routeRevision ?? null,
+        backendInstance: backendSessionId ? terminalSessions.get(backendSessionId) : undefined };
+    return captureRuntimeInputGuard(() => {
         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 });
-        }
-    };
+        return { backendSessionId: latest.backendSessionId, launchId: latest.agentLaunchGeneration ?? null,
+            routeRevision: collaborationRouting.get(frontendSessionId)?.routeRevision ?? null,
+            backendInstance: latest.backendSessionId ? terminalSessions.get(latest.backendSessionId) : undefined };
+    }, expected);
 }
 /** tmux input always uses the pane queue, including automation and launch commands. */
 async function automaticTerminalInput(record, assertCurrent = terminalInputGuard(record), progress) {
-    assertCurrent();
+    progress?.('guard_captured');
+    assertCurrent('runtime_resolve');
+    progress?.('runtime_resolving');
     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();
+        assertCurrent('runtime_resolved');
         if (inspected.state !== 'ready' || !inspected.pane)
             throw new Error(inspected.reason ?? 'TMUX_PANE_UNAVAILABLE');
         const pane = inspected.pane;
+        progress?.('runtime_resolved');
         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');
+    assertCurrent('runtime_resolved');
+    progress?.('runtime_resolved');
     return (prompt) => writeBracketedPrompt(backend.ptyProcess, prompt, assertCurrent, progress);
 }
-async function writeAutomaticTerminalPrompt(frontendSessionId, prompt, progress) {
+async function writeAutomaticTerminalPrompt(frontendSessionId, prompt, progress, launchGuard) {
     const record = globalSessionState.sessions.find(candidate => candidate.sessionId === frontendSessionId);
     if (!record)
         throw new Error('SESSION_REMOVED');
-    const write = await automaticTerminalInput(record, terminalInputGuard(record), progress);
+    const write = await automaticTerminalInput(record, launchGuard ?? terminalInputGuard(record), progress);
     await write(prompt);
 }
 async function deliverAutomationPromptWhenReady(backendSessionId, prompt) {
@@ -1576,9 +1593,8 @@ async function runAgentAutomation(automation, req) {
                 throw new Error('自动任务会话创建失败');
             if (automation.command) {
                 const agent = detectAgentFromCommand(automation.command, agentCustomCommands());
-                if (agent)
-                    await beginAgentLaunchCheck(frontendSessionId, agent.slug);
-                await writeAutomaticTerminalPrompt(frontendSessionId, automation.command);
+                const launchGuard = agent ? await beginAgentLaunchCheck(frontendSessionId, agent.slug) : undefined;
+                await writeAutomaticTerminalPrompt(frontendSessionId, automation.command, undefined, launchGuard);
             }
             if (automation.prompt) {
                 if (automation.command)
@@ -1612,6 +1628,7 @@ export function resolveStableFederationSessionId(id) {
 }
 function collaborationRemoteSessions() {
     return Array.from(new Map(collaborationStore.list().flatMap((group) => group.remoteSessions ?? [])
+        .filter(session => session.sessionId.startsWith('remote:'))
         .map((session) => {
         const facts = collaborationStore.sessionFacts(session.sessionId, false);
         const { currentTask: _currentTask, ...terminalSession } = session;
@@ -1622,8 +1639,7 @@ function collaborationRemoteSessions() {
     })).values());
 }
 function tryDeliverCollaborationInbox(frontendSessionId) {
-    const remote = collaborationRemoteSessions().find((session) => session.sessionId === frontendSessionId);
-    if (remote) {
+    if (frontendSessionId.startsWith('remote:')) {
         return { delivered: [], pending: collaborationStore.pendingCount(frontendSessionId), waitable: true,
             reason: '跨服务消息已入队，服务后台正在投递；使用 message get 查看送达回执或注册、重试原因。' };
     }
@@ -1669,7 +1685,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, freshProcess = false) {
+async function inspectCollaborationTmux(binding, requestedPane, allowPlainPane = false, nativeProcessIdentity = false, freshProcess = false, describeNativeFailure = false) {
     if (!binding.tmuxSessionName)
         return { state: 'offline', reason: 'TMUX_BINDING_MISSING' };
     const name = `=${binding.tmuxSessionName}`;
@@ -1696,14 +1712,16 @@ async function inspectCollaborationTmux(binding, requestedPane, allowPlainPane =
         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 };
-        if (identity.failure)
+            : { nativeId: agent && program?.rawArgs ? inferResumeSessionId(agent, splitCommandToArgv(program.rawArgs)) : null, failure: null, source: null };
+        if (identity.failure && !describeNativeFailure)
             integrationError(identity.failure === 'NATIVE_SESSION_IDENTITY_CONFLICT'
                 ? 'NATIVE_SESSION_ID_MISMATCH' : 'NATIVE_SESSION_OWNER_UNCONFIRMED', 'Current process native identity evidence conflicts or cannot be uniquely verified', 409);
         const nativeSessionId = identity.nativeId;
         return { serverPid, sessionId: layout.sessionId, paneId: pane.id, panePid: pane.pid,
             agentSlug: agent?.slug ?? '', nativeSessionId, cwd: pane.currentPath,
-            isShell: shellNamesBackend.has(normalizeProgramName(program?.command ?? '')?.toLowerCase() ?? '') };
+            isShell: shellNamesBackend.has(normalizeProgramName(program?.command ?? '')?.toLowerCase() ?? ''),
+            ...(nativeProcessIdentity ? { nativeIdentitySource: identity.source, nativeIdentityFailure: identity.failure,
+                nativeIdentityVerified: identity.source === 'linux-flock-owner' && !identity.failure } : {}) };
     }));
     const candidates = requestedPane ? panes.filter((pane) => pane.paneId === requestedPane) : panes;
     if (allowPlainPane && !binding.pane) {
@@ -1711,24 +1729,56 @@ async function inspectCollaborationTmux(binding, requestedPane, allowPlainPane =
         // pane so a plain shell member is drivable (run/capture are shell ops).
         return selectDrivePane(binding, candidates, layout.activePaneId);
     }
-    return selectCollaborationPane(binding, candidates);
+    return { ...selectCollaborationPane(binding, candidates), candidates };
+}
+function routeOwnershipConfirmed(frontendSessionId, binding, panes) {
+    const record = globalSessionState.sessions.find(candidate => candidate.sessionId === frontendSessionId);
+    return !!record && record.mode === 'tmux' && record.tmuxSessionName === binding.tmuxSessionName
+        && !globalSessionState.sessions.some(other => other.sessionId !== frontendSessionId && (other.tmuxSessionName === binding.tmuxSessionName
+            || !!binding.backendSessionId && other.backendSessionId === binding.backendSessionId))
+        && (!binding.backendSessionId || [null, frontendSessionId].includes(collaborationRouting.ownerOfBackend(binding.backendSessionId)))
+        && panes.every(pane => !collaborationRouting.hasOtherPaneOwner(frontendSessionId, pane));
+}
+function routeHasUnconfirmedWrite(frontendSessionId) {
+    return collaborationStore.hasUnconfirmedDelivery(frontendSessionId);
+}
+async function describeCollaborationRoute(frontendSessionId) {
+    const record = globalSessionState.sessions.find(candidate => candidate.sessionId === frontendSessionId);
+    if (!record)
+        throw new Error('SESSION_REMOVED');
+    const binding = collaborationRouting.get(frontendSessionId);
+    if (!binding || binding.mode !== 'tmux')
+        return { session_id: frontendSessionId, binding,
+            worker: collaborationDeliveryWorker.diagnostics(frontendSessionId), identity: null };
+    const inspected = await inspectCollaborationTmux(binding, null, false, true, true, true);
+    const assessment = assessCollaborationRouteIdentity(binding, inspected.candidates ?? [], routeOwnershipConfirmed(frontendSessionId, binding, inspected.candidates ?? []), routeHasUnconfirmedWrite(frontendSessionId));
+    return { session_id: frontendSessionId, binding, worker: collaborationDeliveryWorker.diagnostics(frontendSessionId),
+        observed_at: Date.now(), state: inspected.state, error: inspected.reason ?? null, identity: assessment.diagnostics,
+        integration_managed: record.tmuxSessionName?.startsWith('wt-integration-') ?? false };
 }
 async function rebindCollaborationRoute(frontendSessionId, paneId) {
     await collaborationDeliveryWorker.reconfigure(frontendSessionId, async () => {
         const record = globalSessionState.sessions.find((candidate) => candidate.sessionId === frontendSessionId);
         if (!record)
             throw new Error('SESSION_REMOVED');
+        if (record.tmuxSessionName?.startsWith('wt-integration-'))
+            throw new Error('INTEGRATION_SESSION_RESTORE_REQUIRED: use the owning principal session restore lifecycle');
         const previous = collaborationRouting.get(frontendSessionId);
+        if (routeHasUnconfirmedWrite(frontendSessionId))
+            throw new Error('ROUTE_DELIVERY_OUTCOME_UNCONFIRMED: inspect prior write outcome before rebinding; the body is not replayed');
         const binding = {
             sessionId: frontendSessionId, backendSessionId: previous?.backendSessionId ?? record.backendSessionId,
             mode: record.mode, tmuxSessionName: record.tmuxSessionName ?? previous?.tmuxSessionName ?? null,
             agentSlug: null, nativeSessionId: null, pane: null,
+            routeRevision: crypto.randomUUID(), lastRecovery: { kind: 'owner-confirmed', at: Date.now(), previousPane: previous?.pane ?? null },
         };
         if (binding.mode === 'tmux') {
             const inspected = await inspectCollaborationTmux(binding, paneId);
             if (inspected.state !== 'ready' || !inspected.pane)
                 throw new Error(inspected.reason ?? 'AGENT_NOT_RUNNING');
             const pane = inspected.pane;
+            if (!routeOwnershipConfirmed(frontendSessionId, binding, [pane]))
+                throw new Error('ROUTE_OWNERSHIP_UNCONFIRMED');
             binding.pane = { serverPid: pane.serverPid, sessionId: pane.sessionId, paneId: pane.paneId, panePid: pane.panePid,
                 agentSlug: pane.agentSlug, nativeSessionId: pane.nativeSessionId };
             binding.agentSlug = pane.agentSlug;
@@ -1759,6 +1809,7 @@ async function rebindCollaborationRoute(frontendSessionId, paneId) {
  * snapshot of the recipient after the write, and the sender judges from that.
  */
 async function resolveCollaborationRoute(frontendSessionId) {
+    let recoveredNativeIdentity = false;
     let record = globalSessionState.sessions.find((candidate) => candidate.sessionId === frontendSessionId);
     if (!record)
         return { state: 'offline', reason: 'SESSION_REMOVED' };
@@ -1774,7 +1825,26 @@ 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, undefined, false, Boolean(record.agentLaunchCheck?.nativeSessionId), Boolean(record.agentLaunchCheck));
+        let inspected = await inspectCollaborationTmux(binding, undefined, false, Boolean(record.agentLaunchCheck?.nativeSessionId), Boolean(record.agentLaunchCheck));
+        if (inspected.state === 'identity-mismatch' && !record.tmuxSessionName?.startsWith('wt-integration-')) {
+            const observed = await inspectCollaborationTmux(binding, null, false, true, true, true);
+            const assessment = assessCollaborationRouteIdentity(binding, observed.candidates ?? [], routeOwnershipConfirmed(frontendSessionId, binding, observed.candidates ?? []), routeHasUnconfirmedWrite(frontendSessionId));
+            if (assessment.diagnostics.recovery !== 'automatic' || !assessment.pane)
+                return { state: 'identity-mismatch', reason: 'TMUX_PANE_CHANGED', diagnostics: assessment.diagnostics };
+            const previous = collaborationRouting.get(frontendSessionId);
+            if (JSON.stringify(previous) !== JSON.stringify(binding))
+                return { state: 'recovering', reason: 'ROUTE_CHANGED_DURING_RECOVERY' };
+            const verify = await inspectCollaborationTmux(binding, null, false, true, true, true);
+            const confirmed = assessCollaborationRouteIdentity(binding, verify.candidates ?? [], routeOwnershipConfirmed(frontendSessionId, binding, verify.candidates ?? []), routeHasUnconfirmedWrite(frontendSessionId));
+            if (confirmed.diagnostics.recovery !== 'automatic' || !confirmed.pane || JSON.stringify(confirmed.pane) !== JSON.stringify(assessment.pane)) {
+                return { state: 'identity-mismatch', reason: 'ROUTE_CHANGED_DURING_RECOVERY', diagnostics: confirmed.diagnostics };
+            }
+            binding = { ...binding, pane: confirmed.pane, routeRevision: crypto.randomUUID(),
+                lastRecovery: { kind: 'native-identity', at: Date.now(), previousPane: binding.pane } };
+            collaborationRouting.bind(binding);
+            inspected = { state: 'ready', pane: confirmed.pane };
+            recoveredNativeIdentity = true;
+        }
         assertGeneration();
         if (inspected.state !== 'ready' || !inspected.pane)
             return inspected;
@@ -1816,6 +1886,14 @@ async function resolveCollaborationRoute(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');
+                if (recoveredNativeIdentity) {
+                    const current = await inspectCollaborationTmux(binding, null, false, true, true, true);
+                    const proof = current.candidates?.find(candidate => candidate.serverPid === pinned.serverPid && candidate.sessionId === pinned.sessionId
+                        && candidate.paneId === pinned.paneId && candidate.panePid === pinned.panePid);
+                    if (!proof?.nativeIdentityVerified || proof.nativeIdentityFailure || proof.nativeSessionId !== pinned.nativeSessionId
+                        || proof.agentSlug !== pinned.agentSlug || !routeOwnershipConfirmed(frontendSessionId, binding, [proof]))
+                        throw new Error('ROUTE_NATIVE_IDENTITY_CHANGED_BEFORE_WRITE');
+                }
                 await writeCollaborationTmuxPane(runTmux, pinned, formatLocalCollaborationMessages(frontendSessionId, messages), runTmuxStdin, () => { assertGeneration(); assertCurrent(); });
                 backend.lastActivity = Date.now();
             } };
@@ -1904,7 +1982,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 launchGuard = await beginAgentLaunchCheck(frontendSessionId, launcher.slug);
     const latestGroup = collaborationStore.getGroup(group.id);
     if (!latestGroup || latestGroup.deleted) {
         const created = globalSessionState.sessions.find(record => record.sessionId === frontendSessionId);
@@ -1927,7 +2005,7 @@ async function spawnCollaborationAgentSession(req, group, sourceSessionId, input
         collaborationStore.setRole({ groupId: group.id, sessionId: frontendSessionId, role: bootstrapRole, creationKey });
     if (profile)
         collaborationStore.setMemberLaunchProfile(group.id, frontendSessionId, profile);
-    await writeAutomaticTerminalPrompt(frontendSessionId, buildCollaborationSpawnCommand({ slug: launcher.slug, command: profile?.command ?? launcher.command }));
+    await writeAutomaticTerminalPrompt(frontendSessionId, buildCollaborationSpawnCommand({ slug: launcher.slug, command: profile?.command ?? launcher.command }), undefined, launchGuard);
     const requestedTask = typeof input.task === 'string' ? input.task.trim().slice(0, 20_000) : '';
     collaborationStore.send({
         groupId: updatedGroup.id,
@@ -2357,8 +2435,8 @@ async function launchIntegrationTerminal(record, restoring, prepared, progress,
         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 writeAutomaticTerminalPrompt(record.session_id, integrationLaunchCommand(record, restoring), progress);
+        const launchGuard = await beginAgentLaunchCheck(record.session_id, record.agent_slug, restoring ? record.agent_native_session_id : null);
+        await writeAutomaticTerminalPrompt(record.session_id, integrationLaunchCommand(record, restoring), progress, launchGuard);
         broadcastClientState();
     });
 }
@@ -2405,12 +2483,12 @@ export function prepareCollaborationTaskWorker(task, template, dependencies, ser
                 throw error;
         }
         if (!currentAgent && (!launch || launch.backendId !== opened.terminalSession.sessionId)) {
-            await beginAgentLaunchCheck(record.sessionId, launcher.slug);
+            const launchGuard = 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);
-            await writeAutomaticTerminalPrompt(opened.session.sessionId, buildCollaborationSpawnCommand({ slug: launcher.slug, command: inheritedProfile?.command ?? launcher.command }));
+            await writeAutomaticTerminalPrompt(opened.session.sessionId, buildCollaborationSpawnCommand({ slug: launcher.slug, command: inheritedProfile?.command ?? launcher.command }), undefined, launchGuard);
         }
         const group = collaborationStore.getGroup(task.groupId);
         if (!group || group.deleted)
@@ -6078,8 +6156,8 @@ router.post('/tmux/recovery/restore-all', async (_req, res) => {
                 const previous = collaborationRouting.get(frontendSessionId);
                 if (previous)
                     collaborationRouting.bind({ ...previous, pane: null });
-                await beginAgentLaunchCheck(frontendSessionId, agent.slug, target.nativeSessionId);
-                await writeAutomaticTerminalPrompt(frontendSessionId, command);
+                const launchGuard = await beginAgentLaunchCheck(frontendSessionId, agent.slug, target.nativeSessionId);
+                await writeAutomaticTerminalPrompt(frontendSessionId, command, undefined, launchGuard);
             }));
             outcomes.push({ sessionId: frontendSessionId, restored: true });
         }
@@ -6474,7 +6552,8 @@ router.get('/operations/collaboration-groups/:groupId/messages', (req, res) => {
         return ambiguousGroupResponse(res, ambiguous);
     if (!group)
         return res.status(404).json({ error: '协作组不存在' });
-    res.json({ messages: collaborationStore.listMessages(group.id, Number(req.query.limit) || 200) });
+    res.json({ messages: collaborationStore.listMessages(group.id, Number(req.query.limit) || 200)
+            .map(message => ({ ...message, delivery: collaborationStore.receipt(message.id).delivery })) });
 });
 router.post('/operations/collaboration-groups/:groupId/messages', (req, res) => {
     try {
@@ -6789,7 +6868,7 @@ router.post('/operations/orchestration/drive', async (req, res) => {
     }
 });
 router.use('/operations/orchestration', collaborationRoutes({ store: collaborationStore, resolveSession: resolveFrontendSessionId,
-    deliver: tryDeliverCollaborationInbox, rebind: rebindCollaborationRoute,
+    deliver: tryDeliverCollaborationInbox, rebind: rebindCollaborationRoute, diagnoseRoute: describeCollaborationRoute,
     resolveNames: (ids) => {
         const names = new Map([...collaborationRemoteSessions(),
             ...globalSessionState.sessions.map(orchestrationSessionSnapshot)].map((session) => [session.sessionId, session.name]));
@@ -7031,8 +7110,8 @@ router.post('/operations/execution-archives/:sessionId/restore', executionArchiv
         broadcastClientState();
         throw error;
     }
-    await beginAgentLaunchCheck(record.sessionId, target.slug, target.nativeSessionId);
-    await writeAutomaticTerminalPrompt(opened.session.sessionId, command);
+    const launchGuard = await beginAgentLaunchCheck(record.sessionId, target.slug, target.nativeSessionId);
+    await writeAutomaticTerminalPrompt(opened.session.sessionId, command, undefined, launchGuard);
     restoreArchivedMembership(entry, record.sessionId);
     await persistGlobalStateNow();
     broadcastClientState();
@@ -8276,10 +8355,9 @@ router.post('/:sessionId/agent-resume', async (req, res) => {
     try {
         const frontend = globalSessionState.sessions.find(candidate => candidate.backendSessionId === sessionId);
         const launch = async () => {
+            const launchGuard = frontend ? await beginAgentLaunchCheck(frontend.sessionId, target.slug, target.nativeSessionId) : undefined;
             if (frontend)
-                await beginAgentLaunchCheck(frontend.sessionId, target.slug, target.nativeSessionId);
-            if (frontend)
-                await writeAutomaticTerminalPrompt(frontend.sessionId, target.command);
+                await writeAutomaticTerminalPrompt(frontend.sessionId, target.command, undefined, launchGuard);
             else
                 await writeBracketedPrompt(session.ptyProcess, target.command, captureTerminalInputGuard(() => terminalSessions.get(sessionId), session));
         };

package/docs/integrations.md

@@ -1169,3 +1169,125 @@ TD/native session ID、消息/reply、事件/consumer 历史。没有 Agent 启
 并发不同键竞争/同键重放、删除/跨服务、管理员 Unix 路由/CLI 权限及 JSON、网页列表
 回读和旧网页表单版本冲突。DevBox 业务组及真实 macOS/iOS 显示尚待接入方实机验收，
 不以源码/模拟回归代替其运行现场。
+
+## 1.4.321：普通协作会话的承载变化、阻断诊断与恢复
+
+最低 CLI/实际服务均为 **1.4.321**；普通协作协议仍为 2，integration protocol 仍为 1。
+当前 CLI 版本不能替代实际服务版本；普通成员使用
+`td collab --session <自身ID> capabilities --json` 回读 `server_version`、
+`route_diagnostics=true`、`route_identity_recovery=true`、
+`route_identity_recovery_min_version=1.4.321`。
+
+```sh
+td collab --session <自身ID> route get <精确本地目标ID> --json
+td collab --session <自身ID> message get <原消息ID> --receipt-only --json
+# 只有目标拥有者在自己的真实终端确认“当前承载就是目标”后执行：
+td collab --session <目标自身ID> rebind --pane <当前pane-ID> --json
+```
+
+`route get` 为只读 `GET /operations/orchestration/route/:id`，只允许自身或共享组的本地
+成员；不解析前缀/名称，不替远端拥有者查询其当前进程。旧服务缺能力时 CLI 明确拒绝。
+返回 `route.session_id/binding/worker/observed_at/state/error/identity`：worker 包括
+`started/tick_in_progress/recipient_in_progress/last_tick_at/route/pending_count`；identity
+包括原 `expected`、当前 `observed`（最多 20 项、`truncated`）、`recovery/reason` 和
+拥有者正式 `rebind_command`。只导出承载标识、Agent 类型及原生身份证据元数据，
+没有终端正文、argv、环境或凭据。证据未知即未知，不使用旧缓存 UUID 替代当前身份。
+只读查询不启动/恢复 Agent、改绑或补键，不把进程/身份正确称为输入已就绪。
+
+已绑定的 tmux server/session/pane/PID 变化时，原物理身份保护仍拒绝直接写入。
+消息维持 `status=pending`，诊断会给 `delivery.stage=blocked`、`error=TMUX_PANE_CHANGED`、
+`route_state`、`requires_confirmation` 及 `route` 差异/建议；`attempt_count=0` 表示尚未
+尝试写入，不等于失败后可重发。现有 `message.delivery` 主动事件携带该 receipt；
+网页协作记录也展示绑定变化和投递暂停，保留原正文。跨服务交换在状态不变但错误变化
+时仍同步错误，不因 pending 状态相同而隐去新的阻断。运行服务未采集过的历史差异
+不能由新版本凭空补出；`worker.started` 等字段用于确认当前调度事实。
+
+本地/远端目标依据稳定 `remote:` 地址区分，组是否 federated 不影响组内本地消息进入
+本地 worker。后台 worker 在会话登记加载完成后启动，不等待额外 PTY adoption 或
+tmux 元数据 backfill；订阅消息存储变化并保留定时重试。缺绑定/进程/权限时仍保留原
+消息，诊断拒绝原因，不依赖网页维持投递。此加固不能替代旧现场的运行证据，也不能
+从过去缺少 transport 条目推断唯一内部根因。
+
+承载变化后的**自动**更新仅用于普通 tmux 会话，并同时要求：原生 ID/Agent 类型已知，
+当前可信 provider 独立核验同一原生 ID、同一 Agent，唯一匹配且原逻辑记录/后端/pane
+归属无冲突，没有原待投递消息的未确认写入尝试。对账前再次核验当前候选和登记，
+首次继续写入前再次核验当前原生身份。只改绑定，不启动/恢复/切换原生 Agent。
+当前独立证据 provider 是已配置的 Linux flock-owner 核验；核心不按 Agent 名称或
+TUI 展示字符串分支。argv 的 resume ID 只能作为启动意图元数据，单独不满足自动更新。
+因此没有可靠 provider 的 Mac 冷启动 Codex 等场景需要明确拥有者确认，不能宣称跨
+平台自动身份恢复已通过。独立证据的能力/适用平台由 provider 决定。
+
+原生身份缺失/不同、多匹配、归属不明或此前写入结果不明时，保留原消息并显示
+`confirmation-required` 及对应原因（`NATIVE_IDENTITY_UNCONFIRMED`、
+`MULTIPLE_NATIVE_IDENTITY_MATCHES`、`ROUTE_OWNERSHIP_UNCONFIRMED`、
+`DELIVERY_OUTCOME_UNCONFIRMED`）。拥有者确认当前承载后可用现有 rebind 明确接受当前
+Agent/原生身份；这不是承诺精确恢复旧原生历史，也不要求猜 UUID 或编辑私有记录。
+无运行 tmux 的情况须先通过原会话恢复入口恢复承载，不能靠 rebind 新建。
+
+重新绑定与投递按该逻辑成员的 worker 屏障串行，持久保存 `routeRevision` 和
+`lastRecovery={kind,at,previousPane}`，后者只记录最近一次自动/显式绑定恢复。
+绑定以 routing 文件原子替换提交；失败不采用新绑定。输入队列同时核验 routeRevision，
+旧队列不能在新绑定上继续粘贴/提交。待处理消息已经记录尝试（`attempt_count>0`）而结果
+未确认时，显式 rebind 返回 `ROUTE_DELIVERY_OUTCOME_UNCONFIRMED`，先对账，不能借修复
+重发正文。记录不承诺永久审计或跨掉电的恰好一次输入；原终端传输的写入语义/保留
+边界不变。
+
+`IntegrationSession` 不通过普通 rebind 绕过其代次/精确 UUID/配置与所有者保护，须继续
+用受限 principal 的 `session get/restore`；普通 rebind 对此返回
+`INTEGRATION_SESSION_RESTORE_REQUIRED`。当前修复不改变业务任务、principal、组、
+message/thread/幂等键或历史，不自动补 Enter、不用屏幕文字识别消费；delivered 仍只
+表示终端写入，完成须明确回复。
+
+回归覆盖同组本地消息处于 federated 组、存储变化唤醒/后台阻断、修复后原消息单次
+投递、不同/缺失/弱原生证据、多匹配/归属/未知旧写入拒绝、绑定持久化和失败、
+只读路由权限/CLI、网页暂停提示及加密传输边界。Mac 实际现场的当前原生身份尚未独立确认，原消息尚待拥有者确认及接入方实际服务
+升级/回读后继续投递；不以维护机回归冒充该现场已恢复。
+
+
+## 1.4.322：启动代次一致性与输入检查诊断
+
+最低实际服务 **1.4.322**，配套 CLI 也升级至 1.4.322。`capabilities` 回读：
+`agent_launch_generation_consistency=true`、
+`agent_launch_generation_consistency_min_version=1.4.322`、
+`terminal_input_check_diagnostics=true`。普通协作协议仍为 2，integration protocol 仍为 1；
+不新增权限。只更新 CLI 不会改变正在运行的旧服务。
+
+启动代次是 TD 服务生成的 `agentLaunchGeneration`，与原生 Agent UUID、
+IntegrationSession 的数值 `generation` 分别记录。同一 backend 在启动准备时从 null
+变为新的启动 UUID 是正常动作。名称、cwd、原生身份元数据等整记录更新过去可能
+携带 await 之前的旧启动字段写回；本版将启动字段交由专门的比较后更新路径管理，
+普通元数据更新继承当前启动代次与一次性检查，不能覆盖或复活旧值。
+
+启动操作在写入本次代次后、持久化之前捕获自己的输入检查令牌，并在持久化返回、
+承载解析、获取输入队列及粘贴/提交前持续使用它。冷启动、精确恢复、显式 cold retry
+和普通启动共用这条保护；不会为了继续输入而采纳后来出现的启动代次。启动状态
+落盘失败时不输入。真实 backend 对象/ID、绑定版本、tmux pane 或启动代次变化仍拒绝，
+保留 `TERMINAL_INPUT_TARGET_CHANGED` / `TMUX_PANE_CHANGED` 等错误。
+
+管理员沿现有入口读取已保存的诊断：
+
+```sh
+td integration diagnostics <TD-session-id>
+```
+
+`launch_diagnostics.steps` 追加可选阶段 `guard_captured / runtime_resolving / runtime_resolved`；
+既有 `queue_wait / queue_acquired / paste_* / submit_*` 保留。拒绝时
+`target_change` 可含 `check_phase / guard_captured_at / checked_at`，以及
+`expected_launch_id / current_launch_id`、backend ID/实例比较、绑定版本比较。
+`check_phase` 包含 `launch_state_commit / guard_capture / launch_persisted / runtime_resolve /
+runtime_resolved / queue_acquired / before_paste / before_submit`。时间是 TD 检查时间，
+不是内核首字节写入时间；不包含正文、argv、环境或凭据。旧记录不补造缺失的证据。
+
+这次修复不增加自动重试：原 create 同键只回读原操作。失败现场保留，先用
+`session get` 核对当前事实；明确授权后才按现有 `session retry-cold` 契约显式操作，
+必须满足无原生 UUID、无 TD 消息历史或待投递、精确原 shell、配置指纹与代次等条件。
+已有原生 UUID 的会话继续精确 restore，不能以 cold retry 替代。消息正文不因升级重发。
+
+升级由现场唯一维护者协调：保留现有 HTTPS/鉴权参数，仅替换并重启 TD 服务；
+核对在跑 tmux/Agent 完整身份没有变化，再回读实际服务版本和以上能力。
+本版不要求重启、重建或重试业务 Agent，不更改 launch profile、sandbox 或业务调度。
+终端动作仍是粘贴一次、50ms 后发送一次回车；TD 仍不保证应用提交、消费或执行完成。
+
+确定性交错回归覆盖延迟改名/元数据回写、清除检查、持久化等待、输入队列等待、
+真实第二次启动、backend 替换及重新绑定；发生真实换代时，旧输入及旧的延迟回车
+仍被拒绝。测试证明 TD 一致性与终端写入边界，不代替私有 Agent 的实机消费验收。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "termdock",
-  "version": "1.4.320",
+  "version": "1.4.322",
   "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.320",
+  "version": "1.4.322",
   "runtimeProtocolVersion": 1,
   "minimumDesktopVersion": "1.4.46",
   "nodeMajor": 22,
   "dependencyHash": "sha256-oaGYi/P5ob8sd6VnNBOwshKozjhdV+hYiCmLAsn5x00=",
-  "serverBundleHash": "sha256-gDDXXi77xb12IjXMDyoQfphY068s3YYypX7eonkYaBI=",
-  "clientBundleHash": "sha256-/khgWBy20WS07NVRjRse/qqfC/0Z7Oq5E30fwmuL3Ww=",
+  "serverBundleHash": "sha256-T9JZp3X9tfMUYciSrnZbiUIXuc+IHqHJuGp6Wf5bHs8=",
+  "clientBundleHash": "sha256-4wVT4/UzD+TMRQjVw307g0c0x0cJm6NknoDeybiIQfA=",
   "entrypoint": "dist/server/cli.js",
   "clientEntrypoint": "dist/client/index.html"
 }

package/dist/client/assets/CollaborationTaskContent-WQ5CC-0d.js

@@ -1,2 +0,0 @@
-import{by as r}from"./app-BRESmgxW.js";import{b as m}from"./dnd-BCFAPC0L.js";import{b as n}from"./RightSidebar-7C9-PfhA.js";import"./react-XDCjal2T.js";import"./terminal-C7X98Amf.js";import"./App-BF6YvbKL.js";import"./gestureArbiter-DalDKZKj.js";import"./triangle-alert-DG_BJhJY.js";import"./referenceLongPress-DfQ5jnsk.js";import"./DiffReview-CjEi6PCy.js";import"./sparkles-DbcgKKVd.js";import"./DiffViewer-Bh6lvUYN.js";import"./ChangeWalkthroughPanel-B59JwhzK.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};