termdock 1.4.178 → 1.4.179

package/dist/server/federation/routeAccess.js

@@ -8,11 +8,13 @@ export class RouteAccess {
     filePath;
     now;
     canRouteSubject;
+    additionalTargets;
     tickets = new Map();
-    constructor(filePath, now = Date.now, canRouteSubject = () => false) {
+    constructor(filePath, now = Date.now, canRouteSubject = () => false, additionalTargets = () => []) {
         this.filePath = filePath;
         this.now = now;
         this.canRouteSubject = canRouteSubject;
+        this.additionalTargets = additionalTargets;
     }
     registry() {
         const empty = { relays: [], directTargets: [] };
@@ -32,8 +34,8 @@ export class RouteAccess {
             }
             const targetIds = new Set();
             for (const target of directTargets) {
-                if (!target || typeof target !== 'object' || Array.isArray(target) || Object.keys(target).some(key => !['serviceId', 'url', 'caPath'].includes(key))
-                    || !validId(target.serviceId) || targetIds.has(target.serviceId) || typeof target.url !== 'string' || (target.caPath !== undefined && typeof target.caPath !== 'string'))
+                if (!target || typeof target !== 'object' || Array.isArray(target) || Object.keys(target).some(key => !['serviceId', 'url', 'caPath', 'label'].includes(key))
+                    || (target.label !== undefined && (typeof target.label !== 'string' || target.label.length > 120)) || !validId(target.serviceId) || targetIds.has(target.serviceId) || typeof target.url !== 'string' || (target.caPath !== undefined && typeof target.caPath !== 'string'))
                     return empty;
                 const url = new URL(target.url);
                 if (!['https:', 'wss:'].includes(url.protocol) || url.username || url.password || url.search || url.hash || !['/', '/api/federation/secure'].includes(url.pathname))
@@ -90,7 +92,7 @@ export class RouteAccess {
         if (!validId(serviceId))
             return false;
         const registry = this.registry();
-        return registry.relays.some(relay => relay.targets.includes(serviceId)) || registry.directTargets.some(target => target.serviceId === serviceId);
+        return registry.relays.some(relay => relay.targets.includes(serviceId)) || registry.directTargets.some(target => target.serviceId === serviceId) || this.additionalTargets().some(target => target.serviceId === serviceId);
     }
     addDirectTarget(target) {
         const url = new URL(target.url);
@@ -120,17 +122,22 @@ export class RouteAccess {
         writeFileSync(temporary, JSON.stringify(data, null, 2), { mode: 0o600 });
         renameSync(temporary, this.filePath);
     }
-    configuredDirectTargets() { return this.registry().directTargets; }
+    configuredDirectTargets() {
+        const targets = new Map(this.additionalTargets().map(target => [target.serviceId, target]));
+        for (const target of this.registry().directTargets)
+            targets.set(target.serviceId, target);
+        return [...targets.values()];
+    }
     configuredTargets() {
         const registry = this.registry();
         const targets = new Map();
         for (const relay of registry.relays)
             for (const serviceId of relay.targets)
                 targets.set(serviceId, { serviceId });
-        for (const target of registry.directTargets) {
+        for (const target of this.configuredDirectTargets()) {
             const url = new URL(target.url);
             url.protocol = 'https:';
-            targets.set(target.serviceId, { serviceId: target.serviceId, url: url.origin });
+            targets.set(target.serviceId, { serviceId: target.serviceId, url: url.origin, ...(target.label ? { label: target.label } : {}) });
         }
         return [...targets.values()];
     }

package/dist/server/federation/trustedCa.js

@@ -0,0 +1,55 @@
+import { X509Certificate } from 'node:crypto';
+import { get } from 'node:https';
+const cache = new Map();
+/** Only the CA download is unauthenticated. Its exact SHA-256 fingerprint was
+ * already approved locally for this origin; the subsequent WSS connection must
+ * still pass normal TLS chain, hostname and expiry checks using this CA.
+ */
+export function readPinnedCertificateAuthority(origin, fingerprint) {
+    const url = new URL('/onboarding/ca.crt', origin);
+    if (url.protocol !== 'https:' || url.username || url.password || !/^(?:[\da-f]{2}:){31}[\da-f]{2}$/i.test(fingerprint))
+        return Promise.reject(new Error('Invalid pinned certificate authority'));
+    const key = `${url.origin}:${fingerprint.toUpperCase()}`;
+    const cached = cache.get(key);
+    if (cached && cached.expires > Date.now())
+        return cached.value;
+    const value = new Promise((resolve, reject) => {
+        const request = get(url, { agent: false, rejectUnauthorized: false, signal: AbortSignal.timeout(5000) }, response => {
+            if (response.statusCode !== 200) {
+                response.resume();
+                reject(new Error('Pinned certificate authority unavailable'));
+                return;
+            }
+            const chunks = [];
+            let size = 0;
+            response.on('data', (chunk) => {
+                size += chunk.length;
+                if (size > 256 * 1024) {
+                    request.destroy(new Error('Certificate authority is too large'));
+                    return;
+                }
+                chunks.push(chunk);
+            });
+            response.on('error', reject);
+            response.on('end', () => {
+                try {
+                    const pem = Buffer.concat(chunks), certificate = new X509Certificate(pem);
+                    if (!certificate.ca || certificate.fingerprint256 !== fingerprint.toUpperCase()
+                        || Date.now() < Date.parse(certificate.validFrom) || Date.now() > Date.parse(certificate.validTo))
+                        throw new Error('Certificate authority no longer matches Desktop trust');
+                    resolve(pem);
+                }
+                catch (error) {
+                    reject(error);
+                }
+            });
+        });
+        request.on('error', reject);
+    });
+    if (cache.size >= 64)
+        cache.delete(cache.keys().next().value);
+    cache.set(key, { expires: Date.now() + 120_000, value });
+    void value.catch(() => { if (cache.get(key)?.value === value)
+        cache.delete(key); });
+    return value;
+}

package/dist/server/routes/terminal.js

@@ -39,6 +39,10 @@ import { CollaborationStore } from '../agent/collaborationStore.js';
 import { formatCollaborationDelivery } from '../agent/collaborationPrompt.js';
 import { resolveCollaborationSpawnMode } from '../agent/collaborationSpawn.js';
 import { SessionSearchStore } from '../agent/sessionSearchStore.js';
+import { resolveCollaborationBackend } from '../agent/sessionBindingRecovery.js';
+import { CollaborationRoutingStore, selectCollaborationPane } from '../agent/collaborationRouting.js';
+import { CollaborationDeliveryWorker } from '../agent/collaborationDeliveryWorker.js';
+import { writeCollaborationTmuxPane } from '../agent/collaborationTmuxDelivery.js';
 import { listAllHookAgents, refreshStaleHooksAtLaunch, installHooksForSlug, uninstallHooksForSlug, } from '../agent/installers.js';
 import { loadPlugins, savePlugin, removePlugin, readPluginIcon, validateManifest, } from '../agent/plugins.js';
 import { TmuxLifecycleCoordinator } from '../utils/tmuxLifecycle.js';
@@ -60,6 +64,14 @@ const execFileAsync = promisify(execFile);
 const TERMDOCK_DIR = `${os.homedir()}/.termdock`;
 const automationStore = new AutomationStore(`${TERMDOCK_DIR}/automations.json`);
 const collaborationStore = new CollaborationStore(`${TERMDOCK_DIR}/collaboration-groups.json`);
+const collaborationRouting = new CollaborationRoutingStore(`${TERMDOCK_DIR}/collaboration-routing.json`);
+const collaborationDeliveryWorker = new CollaborationDeliveryWorker({
+    store: collaborationStore,
+    peers: () => collaborationStore.list().filter((group) => !group.deleted).flatMap((group) => group.sessionIds),
+    isLocal: (id) => !id.startsWith('remote:'),
+    resolve: resolveCollaborationRoute,
+    onError: (error) => console.warn('[collaboration] background delivery failed:', getErrorMessage(error)),
+});
 const sessionSearchStore = new SessionSearchStore(`${TERMDOCK_DIR}/session-search`);
 let atomicJsonWriteSequence = 0;
 async function readJsonFileIfExists(filePath) {
@@ -572,6 +584,7 @@ void (async () => {
     });
     pruneOrphanSessions();
     await backfillPersistedTmuxMetadata();
+    collaborationDeliveryWorker.start();
 })();
 caffeinateManager.startNetworkMonitor();
 // 清理磁盘恢复后后端已不存在的 session 引用。
@@ -1002,6 +1015,16 @@ function upsertGlobalSessionRecord(record) {
         sessions: deduplicateGlobalSessions(next),
         updatedAt: Date.now(),
     };
+    // Capture server-observed bindings when sessions are created/adopted. Client
+    // projections may later lose their backend id; the routing registry must not.
+    if (normalized.backendSessionId && terminalSessions.has(normalized.backendSessionId)) {
+        try {
+            resolveOrchestrationBackend(normalized);
+        }
+        catch (error) {
+            console.warn('[collaboration] binding persistence failed:', getErrorMessage(error));
+        }
+    }
     return normalized;
 }
 function removeGlobalSessionRecord(frontendSessionId) {
@@ -1011,8 +1034,10 @@ function removeGlobalSessionRecord(frontendSessionId) {
         updatedAt: Date.now(),
     };
     const changed = globalSessionState.sessions.length !== before;
-    if (changed)
+    if (changed) {
         collaborationStore.removeSession(frontendSessionId);
+        collaborationRouting.remove(frontendSessionId);
+    }
     return changed;
 }
 function archiveAgentResumeRecord(record, reason) {
@@ -1263,19 +1288,48 @@ async function openInventorySession(req, input) {
         reused,
     };
 }
+function resolveOrchestrationBackend(record) {
+    const recovered = resolveCollaborationBackend(record, globalSessionState.sessions, terminalSessions, collaborationRouting);
+    if (!recovered)
+        return null;
+    const [backendSessionId, backend] = recovered;
+    const changed = record.backendSessionId !== backendSessionId || record.tmuxSessionName !== backend.tmuxSessionName || record.mode !== backend.mode;
+    record.backendSessionId = backendSessionId;
+    record.mode = backend.mode;
+    record.tmuxSessionName = backend.tmuxSessionName;
+    record.cwd = backend.cwd ?? record.cwd;
+    if (changed) {
+        globalSessionState.updatedAt = Date.now();
+        schedulePersistGlobalState();
+        const metadata = searchMetadataForBackend(backendSessionId, backend);
+        if (metadata)
+            sessionSearchStore.update(metadata);
+    }
+    return backend;
+}
 function orchestrationSessionSnapshot(record) {
-    const backend = record.backendSessionId ? terminalSessions.get(record.backendSessionId) : null;
-    const agent = backend?.agent ?? (record.agentResume?.slug ? agentBySlug(record.agentResume.slug) : null);
-    const latestPrompt = backend?.autoTitlePromptPayloads.at(-1)?.trim() ?? '';
+    const binding = collaborationRouting.get(record.sessionId);
+    const backendId = binding?.backendSessionId ?? record.backendSessionId;
+    const backend = backendId ? terminalSessions.get(backendId) : null;
+    const route = collaborationDeliveryWorker.state(record.sessionId);
+    const slug = binding?.pane?.agentSlug ?? binding?.agentSlug ?? record.agentResume?.slug;
+    const agent = slug ? agentBySlug(slug) : backend?.agent;
+    const sameNativeSession = !binding?.pane || Boolean(binding.pane.nativeSessionId
+        && binding.pane.nativeSessionId === backend?.agentSession?.sessionId && binding.pane.agentSlug === backend?.agent?.slug);
+    const turnState = sameNativeSession ? backend?.agentSession?.status : undefined;
+    const latestPrompt = sameNativeSession ? backend?.autoTitlePromptPayloads.at(-1)?.trim() ?? '' : '';
     return {
-        ...collaborationStore.sessionFacts(record.sessionId, Boolean(backend), backend?.agentSession?.status),
+        ...collaborationStore.sessionFacts(record.sessionId, route.state === 'ready', turnState),
+        route_state: route.state,
+        route_error: route.reason,
+        route_checked_at: route.checkedAt,
         sessionId: record.sessionId,
-        agentNativeSessionId: backend?.agentSession?.sessionId ?? record.agentResume?.sessionId ?? null,
-        backendSessionId: record.backendSessionId ?? null,
+        agentNativeSessionId: binding?.pane ? binding.pane.nativeSessionId : binding?.nativeSessionId ?? backend?.agentSession?.sessionId ?? record.agentResume?.sessionId ?? null,
+        backendSessionId: backendId ?? null,
         name: record.name,
         cwd: backend?.cwd ?? record.cwd ?? '',
         agent: agent ? { slug: agent.slug, displayName: agent.displayName } : null,
-        status: backend?.agentSession?.status ?? (backend ? 'shell' : 'offline'),
+        status: route.state === 'ready' ? turnState ?? 'ready' : route.state,
         capability: agent
             ? [agent.displayName, ...(agent.capabilities ?? []), backend?.activeProgram?.command || record.activeProgram || 'Agent 会话'].join(' · ')
             : (backend?.activeProgram?.command || record.activeProgram || 'Shell 终端'),
@@ -1361,11 +1415,19 @@ function resolveFrontendSessionId(input) {
         return sessionId;
     const backendSessionId = typeof input.backendSessionId === 'string' ? input.backendSessionId.trim() : '';
     if (backendSessionId) {
+        const owner = collaborationRouting.ownerOfBackend(backendSessionId);
+        if (owner && globalSessionState.sessions.some((record) => record.sessionId === owner))
+            return owner;
         const resolved = globalSessionState.sessions.find((record) => record.backendSessionId === backendSessionId)?.sessionId;
         if (resolved)
             return resolved;
     }
     const tmuxSessionName = typeof input.tmuxSessionName === 'string' ? input.tmuxSessionName.trim() : '';
+    if (!tmuxSessionName)
+        return null;
+    const bound = globalSessionState.sessions.find((record) => collaborationRouting.get(record.sessionId)?.tmuxSessionName === tmuxSessionName);
+    if (bound)
+        return bound.sessionId;
     return globalSessionState.sessions.find((record) => record.tmuxSessionName === tmuxSessionName)?.sessionId ?? null;
 }
 function collaborationRemoteSessions() {
@@ -1381,45 +1443,154 @@ function tryDeliverCollaborationInbox(frontendSessionId) {
                 ? `服务 ${remote.serviceLabel} 不可达：消息尚未送达，仅保存在待发送队列；请勿等待对方已收到的回复，服务重连且 Mac 客户端运行后重试投递。`
                 : '跨服务消息尚未确认送达，正在等待 Mac 客户端转发。' };
     }
-    const record = globalSessionState.sessions.find((candidate) => candidate.sessionId === frontendSessionId);
-    const session = record?.backendSessionId ? terminalSessions.get(record.backendSessionId) : null;
-    const pending = collaborationStore.inbox(frontendSessionId, { pendingOnly: true, limit: 10 });
-    // Submit to every online Agent immediately. Its TUI owns ordering while a
-    // turn is active; Termdock only retains messages when the Agent is offline.
-    if (!session || !canDeliverPromptToAgent(session) || pending.length === 0) {
-        return { delivered: [], pending: pending.length };
-    }
-    const prompt = formatCollaborationDelivery({
-        targetSessionId: frontendSessionId,
-        messages: pending,
+    collaborationDeliveryWorker.wake(frontendSessionId);
+    const route = collaborationDeliveryWorker.state(frontendSessionId);
+    return { delivered: [], pending: collaborationStore.pendingCount(frontendSessionId),
+        reason: route.reason ?? '消息已入队，后台正在恢复路由并投递' };
+}
+function formatLocalCollaborationMessages(frontendSessionId, messages) {
+    return formatCollaborationDelivery({ targetSessionId: frontendSessionId, messages,
         groups: collaborationStore.groupsForSession(frontendSessionId),
-        sessions: [...collaborationRemoteSessions(), ...globalSessionState.sessions.map((candidate) => {
-                const snapshot = orchestrationSessionSnapshot(candidate);
-                return {
-                    sessionId: snapshot.sessionId,
-                    agentNativeSessionId: snapshot.agentNativeSessionId,
-                    name: snapshot.name,
-                    status: snapshot.status,
-                };
-            })],
+        sessions: [...collaborationRemoteSessions(), ...globalSessionState.sessions.map(orchestrationSessionSnapshot)],
     });
+}
+async function inspectCollaborationTmux(binding, requestedPane) {
+    if (!binding.tmuxSessionName)
+        return { state: 'offline', reason: 'TMUX_BINDING_MISSING' };
+    const name = `=${binding.tmuxSessionName}`;
     try {
-        session.ptyProcess.write(buildBracketedSubmitBytes(prompt));
+        await runTmux(['has-session', '-t', name]);
     }
     catch (error) {
-        for (const message of pending)
-            collaborationStore.recordTransport(message.id, {
-                relay_online: null, peer_reachable: true, attempt_count: (collaborationStore.diagnostic(message.id)?.attempt_count ?? 0) + 1,
-                next_retry_at: Date.now() + 2_000, last_error: `PTY_WRITE_FAILED: ${getErrorMessage(error)}`, checked_at: Date.now(),
-            });
-        setTimeout(() => tryDeliverCollaborationInbox(frontendSessionId), 2_000).unref?.();
-        return { delivered: [], pending: collaborationStore.pendingCount(frontendSessionId), reason: '终端写入失败，消息已保留并等待重试' };
+        if (/can't find session|no server running|no sessions|error connecting.*No such file/i.test(getErrorMessage(error))) {
+            return { state: 'offline', reason: 'TMUX_SESSION_NOT_RUNNING' };
+        }
+        throw error;
     }
-    collaborationStore.markDelivered(pending.map((message) => message.id));
-    const remaining = collaborationStore.pendingCount(frontendSessionId);
-    if (remaining)
-        setTimeout(() => tryDeliverCollaborationInbox(frontendSessionId), 300).unref?.();
-    return { delivered: pending.map((message) => message.id), pending: remaining };
+    const layout = await getTmuxLayout(binding.tmuxSessionName);
+    if (layout.sessionName !== binding.tmuxSessionName)
+        throw new Error('TMUX_SESSION_IDENTITY_CHANGED');
+    const serverPid = Number((await runTmux(['display-message', '-p', '#{pid}'])).trim());
+    if (!Number.isInteger(serverPid) || serverPid <= 0)
+        throw new Error('TMUX_SERVER_IDENTITY_UNAVAILABLE');
+    const panes = await Promise.all(layout.windows.flatMap((window) => window.panes).map(async (pane) => {
+        const program = await resolveTmuxPaneProgram(pane);
+        const agent = detectAgentFromCommand(program?.rawArgs ?? program?.command ?? '', agentCustomCommands());
+        const nativeSessionId = agent && program?.rawArgs ? inferResumeSessionId(agent, splitCommandToArgv(program.rawArgs)) : null;
+        return { serverPid, sessionId: layout.sessionId, paneId: pane.id, panePid: pane.pid,
+            agentSlug: agent?.slug ?? '', nativeSessionId, cwd: pane.currentPath };
+    }));
+    return selectCollaborationPane(binding, requestedPane ? panes.filter((pane) => pane.paneId === requestedPane) : panes);
+}
+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');
+        const previous = collaborationRouting.get(frontendSessionId);
+        const binding = {
+            sessionId: frontendSessionId, backendSessionId: previous?.backendSessionId ?? record.backendSessionId,
+            mode: record.mode, tmuxSessionName: record.tmuxSessionName ?? previous?.tmuxSessionName ?? null,
+            agentSlug: null, nativeSessionId: null, 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;
+            binding.pane = { serverPid: pane.serverPid, sessionId: pane.sessionId, paneId: pane.paneId, panePid: pane.panePid,
+                agentSlug: pane.agentSlug, nativeSessionId: pane.nativeSessionId };
+            binding.agentSlug = pane.agentSlug;
+            binding.nativeSessionId = pane.nativeSessionId;
+        }
+        else {
+            if (paneId)
+                throw new Error('PANE_REQUIRES_TMUX');
+            const backend = binding.backendSessionId ? terminalSessions.get(binding.backendSessionId) : null;
+            if (!backend)
+                throw new Error('SHELL_BACKEND_NOT_RUNNING');
+            await refreshCollaborationAgentIdentity(binding.backendSessionId, backend);
+            const agent = detectSessionAgent(backend);
+            if (!agent)
+                throw new Error('AGENT_NOT_RUNNING');
+            binding.agentSlug = agent.slug;
+            binding.nativeSessionId = backend.agentSession?.sessionId ?? null;
+        }
+        if (!globalSessionState.sessions.some((candidate) => candidate.sessionId === frontendSessionId))
+            throw new Error('SESSION_REMOVED');
+        collaborationRouting.bind(binding);
+    });
+    collaborationDeliveryWorker.wake(frontendSessionId);
+    return { ...collaborationRouting.get(frontendSessionId), state: 'recovering' };
+}
+async function resolveCollaborationRoute(frontendSessionId) {
+    let record = globalSessionState.sessions.find((candidate) => candidate.sessionId === frontendSessionId);
+    if (!record)
+        return { state: 'offline', reason: 'SESSION_REMOVED' };
+    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);
+        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;
+        // 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,
+            agentSlug: pane.agentSlug, nativeSessionId: pane.nativeSessionId ?? binding.nativeSessionId };
+        binding = { ...binding, pane: pinned, agentSlug: pinned.agentSlug, nativeSessionId: pinned.nativeSessionId };
+        collaborationRouting.bind(binding);
+        if (!backend) {
+            const cwd = pane.cwd || record.cwd;
+            if (!cwd)
+                return { state: 'detached', reason: 'TMUX_ATTACH_CWD_UNAVAILABLE' };
+            await pathValidator.allowSessionCwd(cwd);
+            // Attach only. Never recreate a vanished session or launch/resume an
+            // Agent in response to a queued collaboration message.
+            const spawned = await spawnTerminalSession({}, { cwd, mode: 'tmux',
+                tmuxSessionName: binding.tmuxSessionName, attachExistingOnly: true, tmuxAttachTarget: pane.sessionId });
+            record = globalSessionState.sessions.find((candidate) => candidate.sessionId === frontendSessionId);
+            if (!record)
+                return { state: 'offline', reason: 'SESSION_REMOVED_DURING_RECOVERY' };
+            if (!terminalSessions.has(spawned.sessionId))
+                return { state: 'detached', reason: 'TMUX_ATTACH_EXITED' };
+            binding = { ...binding, backendSessionId: spawned.sessionId };
+            collaborationRouting.bind(binding);
+            backend = resolveOrchestrationBackend(record);
+        }
+        if (!backend)
+            return { state: 'detached', reason: 'TMUX_BACKEND_UNAVAILABLE' };
+        return { state: 'ready', write: async (messages) => {
+                if (!globalSessionState.sessions.some((candidate) => candidate.sessionId === frontendSessionId))
+                    throw new Error('SESSION_REMOVED');
+                await writeCollaborationTmuxPane(runTmux, pinned, formatLocalCollaborationMessages(frontendSessionId, messages));
+                backend.lastActivity = Date.now();
+            } };
+    }
+    if (!backend || !binding.backendSessionId)
+        return { state: 'offline', reason: 'SHELL_BACKEND_NOT_RUNNING' };
+    await refreshCollaborationAgentIdentity(binding.backendSessionId, backend);
+    if (!detectSessionAgent(backend))
+        return { state: 'agent-exited', reason: 'AGENT_NOT_RUNNING' };
+    if ((binding.agentSlug && backend.agent?.slug !== binding.agentSlug)
+        || (binding.nativeSessionId && backend.agentSession?.sessionId && backend.agentSession.sessionId !== binding.nativeSessionId)) {
+        return { state: 'identity-mismatch', reason: 'AGENT_IDENTITY_CHANGED' };
+    }
+    const target = backend;
+    return { state: 'ready', write: async (messages) => {
+            if (!globalSessionState.sessions.some((candidate) => candidate.sessionId === frontendSessionId))
+                throw new Error('SESSION_REMOVED');
+            if (terminalSessions.get(binding.backendSessionId) !== target)
+                throw new Error('SHELL_BACKEND_CHANGED');
+            target.ptyProcess.write(buildBracketedSubmitBytes(formatLocalCollaborationMessages(frontendSessionId, messages)));
+            target.lastActivity = Date.now();
+        } };
 }
 async function refreshCollaborationAgentIdentity(backendSessionId, session) {
     let activeProgram = null;
@@ -1434,33 +1605,12 @@ async function refreshCollaborationAgentIdentity(backendSessionId, session) {
             ? { ...resolved, updatedAt: Date.now() }
             : getActiveProgramFromTmuxLayout(layout);
     }
-    if (!activeProgram)
-        return;
     session.activeProgram = activeProgram;
-    persistActiveProgramBinding(backendSessionId, activeProgram.command);
+    persistActiveProgramBinding(backendSessionId, activeProgram?.command);
     syncAgentIdentity(backendSessionId, session);
 }
 function deliverCollaborationInboxWhenAgentReady(frontendSessionId, backendSessionId, attempt = 0) {
-    const session = terminalSessions.get(backendSessionId);
-    if (!session)
-        return;
-    if (canDeliverPromptToAgent(session)) {
-        setTimeout(() => tryDeliverCollaborationInbox(frontendSessionId), 300).unref?.();
-        return;
-    }
-    if (attempt >= 60)
-        return;
-    void refreshCollaborationAgentIdentity(backendSessionId, session)
-        .catch(() => undefined)
-        .finally(() => {
-        if (canDeliverPromptToAgent(session)) {
-            setTimeout(() => tryDeliverCollaborationInbox(frontendSessionId), 300).unref?.();
-            return;
-        }
-        setTimeout(() => {
-            deliverCollaborationInboxWhenAgentReady(frontendSessionId, backendSessionId, attempt + 1);
-        }, 250).unref?.();
-    });
+    collaborationDeliveryWorker.wake(frontendSessionId);
 }
 async function spawnCollaborationAgentSession(req, group, sourceSessionId, input) {
     const agentSlug = typeof input.agentSlug === 'string' ? input.agentSlug.trim().toLowerCase() : '';
@@ -4435,7 +4585,22 @@ function ptyHostShellModeEnabled() {
     const isBun = typeof globalThis.Bun !== 'undefined';
     return process.platform !== 'win32' && !isBun && process.env.TERMDOCK_PTY_HOST !== 'off';
 }
+const tmuxBackendSpawns = new Map();
 async function spawnTerminalSession(req, input) {
+    const name = input.mode === 'tmux' && input.tmuxSessionName ? normalizeTmuxSessionName(input.tmuxSessionName) : null;
+    if (!name)
+        return spawnTerminalSessionUnlocked(req, input);
+    const pending = tmuxBackendSpawns.get(name);
+    if (pending)
+        return pending;
+    const existing = findBackendSessionForTmux(name);
+    if (existing)
+        return { sessionId: existing[0], session: existing[1], cols: existing[1].cols, rows: existing[1].rows };
+    const operation = spawnTerminalSessionUnlocked(req, input).finally(() => tmuxBackendSpawns.delete(name));
+    tmuxBackendSpawns.set(name, operation);
+    return operation;
+}
+async function spawnTerminalSessionUnlocked(req, input) {
     const cwd = await resolveWorkingDirectory(req, input.cwd);
     const cols = input.cols || 80;
     const rows = input.rows || 24;
@@ -4446,19 +4611,28 @@ async function spawnTerminalSession(req, input) {
     if (mode === 'tmux') {
         const tmuxStatus = await getTmuxStatus();
         if (!tmuxStatus.available) {
+            if (input.attachExistingOnly)
+                throw new Error('TMUX_UNAVAILABLE');
             console.warn('[termdock] tmux not available, falling back to shell mode:', tmuxStatus.reason);
             mode = 'shell';
         }
     }
     const tmuxSessionName = mode === 'tmux' ? normalizeTmuxSessionName(input.tmuxSessionName) : null;
     if (mode === 'tmux' && tmuxSessionName) {
-        await prepareManagedTmuxSession(tmuxSessionName, cwd);
+        if (input.attachExistingOnly) {
+            if (!await tmuxSessionExists(input.tmuxAttachTarget ?? `=${tmuxSessionName}`))
+                throw new Error('TMUX_SESSION_NOT_RUNNING');
+        }
+        else
+            await prepareManagedTmuxSession(tmuxSessionName, cwd);
     }
     const command = mode === 'tmux'
         ? getTmuxBinary()
         : (process.platform === 'win32' ? 'powershell.exe' : resolveShellCandidates()[0]);
+    const supportsFeatures = mode === 'tmux' && await supportsTmuxClientFeatures(command);
     const args = mode === 'tmux' && tmuxSessionName
-        ? buildTmuxAttachArgs(tmuxSessionName, await supportsTmuxClientFeatures(command))
+        ? [...buildTmuxAttachArgs(input.tmuxAttachTarget ?? tmuxSessionName, supportsFeatures),
+            ...(input.attachExistingOnly && supportsFeatures ? ['-f', 'ignore-size'] : [])]
         : (process.platform === 'win32' ? buildPowerShellCwdHookArgs() : []);
     const envPath = buildAugmentedPath();
     const resolvedEnv = buildInteractiveColorEnvironment({
@@ -5393,7 +5567,8 @@ router.post('/operations/orchestration/spawn', async (req, res) => {
         res.status(400).json({ error: getErrorMessage(error) });
     }
 });
-router.use('/operations/orchestration', collaborationRoutes({ store: collaborationStore, resolveSession: resolveFrontendSessionId, deliver: tryDeliverCollaborationInbox }));
+router.use('/operations/orchestration', collaborationRoutes({ store: collaborationStore, resolveSession: resolveFrontendSessionId,
+    deliver: tryDeliverCollaborationInbox, rebind: rebindCollaborationRoute }));
 router.get('/operations/session-search', (req, res) => {
     const query = typeof req.query.q === 'string' ? req.query.q : '';
     const results = sessionSearchStore.search(query, Number(req.query.limit) || 30).map((result) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "termdock",
-  "version": "1.4.178",
+  "version": "1.4.179",
   "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.178",
+  "version": "1.4.179",
   "runtimeProtocolVersion": 1,
   "minimumDesktopVersion": "1.4.46",
   "nodeMajor": 22,
   "dependencyHash": "sha256-kSujny2SLOFnZ1ffxm1FYtli7g1vEN8d3vj1oQeLLdc=",
-  "serverBundleHash": "sha256-wG7h9fvsMN8idDY+H+dioaPsjuM+ojnCMxgwFMeS61M=",
-  "clientBundleHash": "sha256-Wjd5odYe+uZp1t365akaiTeCrJ6DjjG2XFJwMyCO3Cg=",
+  "serverBundleHash": "sha256-AQUq3XFy+cNp7XbeVQmCnE6m5odhlqCbuU3LbvxFjt0=",
+  "clientBundleHash": "sha256-jofF5lZQ8B7W5pmfclW2tlMMp+FlTHRi8am3AscU2CE=",
   "entrypoint": "dist/server/cli.js",
   "clientEntrypoint": "dist/client/index.html"
 }