termdock 1.4.190 → 1.4.192

package/dist/server/agent/collaborationRoutes.js

@@ -1,6 +1,13 @@
 import { Router } from 'express';
 import { COLLAB_LIMITS, CollaborationError, extrasFromBody } from './collaborationProtocol.js';
-export function collaborationRoutes({ store, resolveSession, deliver, rebind }) {
+/** Member names arrive agent-authored over a CLI; control characters would
+ * corrupt terminal shells, tmux options and persisted records. Fold them to
+ * spaces, collapse runs, and cap the length (display sanitization for the
+ * delivery shell stays in the presentation layer). */
+export function cleanMemberName(value) {
+    return value.replace(/[\u0000-\u001f\u007f]/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 80);
+}
+export function collaborationRoutes({ store, resolveSession, deliver, rebind, resolveNames, renameSession }) {
     const router = Router();
     const run = (handler) => async (req, res) => {
         try {
@@ -34,6 +41,27 @@ export function collaborationRoutes({ store, resolveSession, deliver, rebind })
         const receipts = ids.map((id) => store.receipt(id));
         res.json({ ok: true, ...receipts[0], messages, receipts });
     };
+    /** When the recipient is served by this server's own delivery worker, give
+     *  the write (and its post-write snapshot capture) a short window to finish
+     *  before the receipt leaves the send/reply call — the sender then sees the
+     *  recipient's screen right away. Un-waitable targets (relayed/federated,
+     *  offline, or a mock deliver) return immediately with the message queued. */
+    const awaitDelivery = async (id, outcome) => {
+        if (!outcome?.waitable)
+            return;
+        const deadline = Date.now() + 2_000;
+        for (;;) {
+            const receipt = store.receipt(id);
+            const settled = receipt.status !== 'pending'
+                || receipt.snapshot != null
+                || (receipt.attempt_count > 0
+                    && receipt.last_error !== 'DELIVERY_IN_PROGRESS'
+                    && (receipt.next_retry_at ?? 0) > Date.now());
+            if (settled || Date.now() >= deadline)
+                return;
+            await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+    };
     router.get('/capabilities', run((_req, res) => {
         res.json({ protocol_version: 2, limits: COLLAB_LIMITS,
             routing: { background_recovery: true, explicit_rebind: Boolean(rebind), fixed_tmux_pane: true },
@@ -44,20 +72,37 @@ export function collaborationRoutes({ store, resolveSession, deliver, rebind })
                 timeout: 'stops waiting, does not cancel delivery',
                 retry: 'same message id may be submitted again after a crash or uncertain transport result; consumers deduplicate by message id' } });
     }));
-    router.post('/send', run((req, res, sessionId) => {
+    router.post('/send', run(async (req, res, sessionId) => {
         const target = typeof req.body.targetSessionId === 'string' ? req.body.targetSessionId.trim() : '';
-        const groups = store.groupsForSession(sessionId).filter((group) => group.sessionIds.includes(target) && (!req.body.group_id || group.id === req.body.group_id));
+        // A fan-out send lists every recipient in toSessionIds; the store persists
+        // each edge with its sibling fanOutIds so recipients can tell a broadcast
+        // from a one-to-one assignment. The single-recipient shape stays intact.
+        const requestedTargets = Array.isArray(req.body.toSessionIds)
+            ? [...new Set(req.body.toSessionIds.filter((id) => typeof id === 'string' && id.trim().length > 0))]
+            : [];
+        const targets = requestedTargets.length > 0 ? requestedTargets : (target ? [target] : []);
+        if (!targets.length)
+            throw new CollaborationError('NO_TARGET', 'send requires a targetSessionId (or toSessionIds for a fan-out)', 400);
+        const groups = store.groupsForSession(sessionId)
+            .filter((group) => targets.every((candidate) => group.sessionIds.includes(candidate)) && (!req.body.group_id || group.id === req.body.group_id));
         if (!groups.length)
-            throw new CollaborationError('GROUP_NOT_FOUND', 'Sender and recipient must share the specified group');
+            throw new CollaborationError('GROUP_NOT_FOUND', 'Sender and recipients must share the specified group');
         if (groups.length > 1 && !req.body.group_id)
             throw new CollaborationError('AMBIGUOUS_GROUP', 'Multiple shared groups; specify --group');
-        const messages = store.send({ ...extrasFromBody(req.body), groupId: groups[0].id, fromSessionId: sessionId, toSessionIds: [target],
+        if (req.body.task)
+            throw new CollaborationError('DISPATCH_CARRIES_TASK', 'Dispatch carries no task state; recipients report task status through replies', 400);
+        const messages = store.send({ ...extrasFromBody(req.body), groupId: groups[0].id, fromSessionId: sessionId, toSessionIds: targets,
             kind: (req.body.kind ?? 'message'), content: typeof req.body.message === 'string' ? req.body.message : '',
             threadId: typeof req.body.thread_id === 'string' ? req.body.thread_id : undefined });
-        deliver(target);
+        // Wake and await every local recipient edge in parallel; relayed or
+        // federated ids answer immediately with the message queued, so fan-out
+        // never stalls on a peer.
+        await Promise.all(messages.map(async (message) => {
+            await awaitDelivery(message.id, (await deliver(message.toSessionId)) ?? null);
+        }));
         sent(res, messages.map((message) => message.id));
     }));
-    router.post('/reply', run((req, res, sessionId) => {
+    router.post('/reply', run(async (req, res, sessionId) => {
         const original = ownMessage(String(req.body.messageId ?? ''), sessionId, true);
         if (!original.fromSessionId)
             throw new CollaborationError('NO_REPLY_TARGET', 'User messages have no agent reply target');
@@ -66,7 +111,7 @@ export function collaborationRoutes({ store, resolveSession, deliver, rebind })
             replyTo: original.id, threadId: original.threadId });
         // Reply is explicit consumption; only mark after successful validation/persistence.
         store.markRead([original.id]);
-        deliver(original.fromSessionId);
+        await awaitDelivery(messages[0].id, (await deliver(original.fromSessionId)) ?? null);
         sent(res, messages.map((message) => message.id));
     }));
     router.get('/message/:id', run((req, res, sessionId) => {
@@ -87,11 +132,76 @@ export function collaborationRoutes({ store, resolveSession, deliver, rebind })
         const page = store.page(sessionId, { unread: string('unread') === 'true', since, afterId: string('after_id'), cursor: string('cursor'),
             consumer: string('consumer'), limit: string('limit') ? Number(string('limit')) : undefined,
             from: string('from'), group: string('group'), thread: string('thread'), kind: string('kind'), responseKind: string('response_kind'), order: string('order') });
-        res.json({ ok: true, ...page });
+        // Fan-out edges carry sibling recipients; the names map lets the CLI text
+        // renderer show 同时发给了:… as people instead of bare session ids. The
+        // fallback to the raw id stays server-side agnostic (federated/offline).
+        const nameIds = [...new Set(page.messages.flatMap((message) => [message.fromSessionId, ...(message.fanOutIds ?? [])].filter((id) => typeof id === 'string' && id.length > 0)))];
+        res.json({ ok: true, ...page, ...(nameIds.length ? { names: resolveNames?.(nameIds) ?? {} } : {}) });
     }));
     router.post('/cursor/commit', run((req, res, sessionId) => {
         store.commitCursor(sessionId, String(req.body.cursor ?? ''), String(req.body.consumer ?? ''));
         res.json({ ok: true, consumer: req.body.consumer, cursor: req.body.cursor });
     }));
+    const groupOf = (id, sessionId) => {
+        const group = store.getGroup(id);
+        if (!group || group.deleted)
+            throw new CollaborationError('GROUP_NOT_FOUND', 'Collaboration group not found', 404);
+        if (!group.sessionIds.includes(sessionId))
+            throw new CollaborationError('NOT_A_MEMBER', 'Session is not a member of this group', 403);
+        return group;
+    };
+    // Member names ride along so role lists read as people, not bare ids; the
+    // caller falls back to the session id when a name is unknown (federated or
+    // offline members have no local record).
+    const groupView = (group) => {
+        const names = resolveNames?.(group.sessionIds) ?? {};
+        return {
+            id: group.id, name: group.name, sessionIds: group.sessionIds,
+            members: group.sessionIds.map((sessionId) => ({ sessionId, name: names[sessionId] ?? null })),
+            roles: group.roles ?? {},
+        };
+    };
+    router.get('/role', run((req, res, sessionId) => {
+        const groupId = String(req.query.group ?? '');
+        if (groupId) {
+            res.json({ ok: true, group: groupView(groupOf(groupId, sessionId)) });
+            return;
+        }
+        // Without a group this lists the caller's own groups with full role
+        // snapshots — what `td collab --help` renders so a newcomer sees every
+        // member's role in one step instead of hunting the group id first.
+        res.json({ ok: true, groups: store.groupsForSession(sessionId)
+                .filter((group) => !group.deleted)
+                .map(groupView) });
+    }));
+    router.post('/role', run((req, res, sessionId) => {
+        const group = groupOf(String(req.body.group_id ?? ''), sessionId);
+        const role = req.body.role;
+        if (typeof req.body.session_id !== 'string' || !group.sessionIds.includes(req.body.session_id)) {
+            throw new CollaborationError('NOT_A_MEMBER', 'Role target must be a member of this group', 400);
+        }
+        if (role === undefined || (role !== null && typeof role !== 'string')) {
+            throw new CollaborationError('INVALID_ROLE', 'role must be text or null', 400);
+        }
+        const updated = store.setRole({ groupId: group.id, sessionId: req.body.session_id, role: role });
+        res.json({ ok: true, group: { ...updated, roles: updated.roles ?? {} } });
+    }));
+    router.post('/name', run(async (req, res, sessionId) => {
+        if (!renameSession)
+            throw new CollaborationError('RENAME_UNAVAILABLE', 'Member renaming is not available', 503);
+        const target = typeof req.body.session_id === 'string' ? req.body.session_id.trim() : '';
+        if (!store.groupsForSession(sessionId).some((group) => !group.deleted && group.sessionIds.includes(target))) {
+            throw new CollaborationError('NOT_A_MEMBER', 'Rename target must share a collaboration group with the caller', 403);
+        }
+        const name = typeof req.body.name === 'string' ? cleanMemberName(req.body.name) : '';
+        if (!name)
+            throw new CollaborationError('INVALID_NAME', 'name must be non-empty text up to 80 characters', 400);
+        const result = await renameSession(target, name);
+        if (!result.ok) {
+            const missing = result.code === 'SESSION_NOT_FOUND';
+            throw new CollaborationError(missing ? 'SESSION_NOT_FOUND' : 'RENAME_FAILED', result.error ?? 'Unable to rename the member', missing ? 404 : 400);
+        }
+        res.json({ ok: true, sessionId: target, name });
+    }));
     return router;
 }

package/dist/server/agent/collaborationSpawn.js

@@ -7,3 +7,19 @@ export function resolveCollaborationSpawnMode(input) {
         ?? asSpawnMode(input.fallbackMode)
         ?? 'shell';
 }
+/**
+ * Shell command line that boots a collaboration member agent. Spawned agents
+ * have no human at the keyboard, yet their delivery shells instruct them to
+ * run `td collab …` — without pre-authorization every such call stops at the
+ * agent's permission dialog and the collaboration loop stalls. Agents whose
+ * CLI flags are known get a scoped allowlist (collab surface only; the server
+ * guards every collab action anyway). Unsupported agents launch plain — the
+ * delivery confirm gate can dismiss their dialogs instead.
+ */
+export function buildCollaborationSpawnCommand(input) {
+    const { slug, command } = input;
+    if (slug === 'claude') {
+        return `${command} --allowedTools "Bash(td collab *)"`;
+    }
+    return command;
+}

package/dist/server/agent/collaborationStore.js

@@ -2,6 +2,25 @@ import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import { COLLAB_LIMITS, CollaborationError, STATUS_RANK, validateExtras } from './collaborationProtocol.js';
+/** Characters that would corrupt a role line injected into the delivery shell
+ * (`你的定位:...`) or smuggle terminal output. Unlike names, roles are plain
+ * prose — 「」 and · are harmless there — so only control sequences are barred. */
+export const COLLAB_ROLE_FORBIDDEN = /[\x00-\x1f\x7f]/;
+export const COLLAB_ROLE_MAX_CHARS = 200;
+/** Data/render-safe role: control characters collapse to spaces, whitespace
+ * folds, and the display length is capped with an ellipsis. Applied on write
+ * and again defensively at render time (federated peers may carry junk). */
+export function sanitizeCollaborationRole(role, max = COLLAB_ROLE_MAX_CHARS) {
+    const cleaned = role.replace(/[\x00-\x1f\x7f]/g, ' ').replace(/\s+/g, ' ').trim();
+    return cleaned.length > max ? `${cleaned.slice(0, max - 1)}…` : cleaned;
+}
+/** Drop roles whose member has left the group; survivors keep theirs. */
+function pruneRoles(group, sessionIds) {
+    if (!group.roles)
+        return group;
+    const roles = Object.fromEntries(Object.entries(group.roles).filter(([id]) => sessionIds.includes(id)));
+    return Object.keys(roles).length ? { ...group, roles } : { ...group, roles: undefined };
+}
 const MAX_MESSAGES = 2_000;
 const MESSAGE_KINDS = new Set(['message', 'ask', 'reply', 'task', 'handoff', 'done']);
 export class CollaborationStore {
@@ -41,21 +60,44 @@ export class CollaborationStore {
     save(input) {
         const now = Date.now();
         const existing = input.id ? this.document.groups.find((group) => group.id === input.id) : null;
-        const group = {
+        const sessionIds = Array.from(new Set(input.sessionIds.map((id) => id.trim()).filter(Boolean)));
+        const group = pruneRoles({
             ...existing,
-            ...(existing?.remoteSessions ? { remoteSessions: existing.remoteSessions.filter((session) => input.sessionIds.includes(session.sessionId)) } : {}),
+            ...(existing?.remoteSessions ? { remoteSessions: existing.remoteSessions.filter((session) => sessionIds.includes(session.sessionId)) } : {}),
             id: existing?.id ?? crypto.randomUUID(),
             name: input.name.trim(),
-            sessionIds: Array.from(new Set(input.sessionIds.map((id) => id.trim()).filter(Boolean))),
+            sessionIds,
             createdAt: existing?.createdAt ?? now,
             updatedAt: Math.max(now, (existing?.updatedAt ?? 0) + 1),
-        };
+        }, sessionIds);
         this.document.groups = existing
             ? this.document.groups.map((candidate) => candidate.id === group.id ? group : candidate)
             : [...this.document.groups, group];
         this.persist();
         return group;
     }
+    /** Set or clear a member's role (定位). The target may be any group member —
+     * oneself, a peer, or a federated remote session; peers can set each other's
+     * roles. Roles ride the group document into federation and are dropped
+     * together with the member on removal. */
+    setRole(input) {
+        const group = this.getGroup(input.groupId);
+        if (!group || group.deleted)
+            throw new CollaborationError('GROUP_NOT_FOUND', '协作组已删除，请刷新列表', 404);
+        if (!group.sessionIds.includes(input.sessionId))
+            throw new CollaborationError('NOT_A_MEMBER', '该会话不在协作组中，无法设置定位', 400);
+        const role = input.role === null ? null : sanitizeCollaborationRole(input.role);
+        const roles = { ...(group.roles ?? {}) };
+        if (role)
+            roles[input.sessionId] = role;
+        else
+            delete roles[input.sessionId];
+        const updated = { ...group, roles: Object.keys(roles).length ? roles : undefined,
+            updatedAt: Math.max(Date.now(), group.updatedAt + 1) };
+        this.document.groups = this.document.groups.map((candidate) => candidate.id === group.id ? updated : candidate);
+        this.persist();
+        return updated;
+    }
     remove(id) {
         const before = this.document.groups.length;
         const existing = this.getGroup(id);
@@ -88,9 +130,9 @@ export class CollaborationStore {
                 if (group.id === source.id) {
                     if (dissolved)
                         return group.federated ? [{ ...group, deleted: true, updatedAt: Math.max(now, group.updatedAt + 1) }] : [];
-                    return [{ ...group, sessionIds: sourceIds,
+                    return [pruneRoles({ ...group, sessionIds: sourceIds,
                             ...(group.remoteSessions ? { remoteSessions: group.remoteSessions.filter((session) => sourceIds.includes(session.sessionId)) } : {}),
-                            updatedAt: Math.max(now, group.updatedAt + 1) }];
+                            updatedAt: Math.max(now, group.updatedAt + 1) }, sourceIds)];
                 }
                 return group.id === target.id ? [{ ...group, sessionIds: [...new Set([...group.sessionIds, input.sessionId])], updatedAt: Math.max(now, group.updatedAt + 1) }] : [group];
             }),
@@ -109,7 +151,8 @@ export class CollaborationStore {
                 return [group];
             if (dissolvedIds.has(group.id))
                 return group.federated ? [{ ...group, deleted: true, updatedAt: Math.max(now, group.updatedAt + 1) }] : [];
-            return [{ ...group, sessionIds: group.sessionIds.filter((id) => id !== sessionId), updatedAt: Math.max(now, group.updatedAt + 1) }];
+            const remaining = group.sessionIds.filter((id) => id !== sessionId);
+            return [pruneRoles({ ...group, sessionIds: remaining, updatedAt: Math.max(now, group.updatedAt + 1) }, remaining)];
         });
         this.document.messages = this.document.messages.filter((message) => !dissolvedIds.has(message.groupId)
             && message.fromSessionId !== sessionId
@@ -160,6 +203,7 @@ export class CollaborationStore {
             sequence: this.nextSequence(),
             id: crypto.randomUUID(), groupId: group.id, fromSessionId: input.fromSessionId,
             toSessionId, kind: input.kind, content, threadId,
+            fanOutIds: recipients.length > 1 ? recipients.filter((id) => id !== toSessionId) : undefined,
             replyTo: input.replyTo?.trim() || null, status: 'pending', createdAt: now,
             deliveredAt: null, readAt: null,
         }));
@@ -195,10 +239,14 @@ export class CollaborationStore {
     markDelivered(messageIds) {
         return this.updateStatus(messageIds, 'delivered');
     }
-    markRead(messageIds) {
-        return this.updateStatus(messageIds, 'read');
+    /**
+     * @param source 'explicit' — a consumer acknowledged the message (CLI/UI).
+     *   Idempotent; never implies an application-level ACK.
+     */
+    markRead(messageIds, source = 'explicit') {
+        return this.updateStatus(messageIds, 'read', source);
     }
-    updateStatus(messageIds, status) {
+    updateStatus(messageIds, status, readSource = 'explicit') {
         const ids = new Set(messageIds);
         this.expire();
         const now = Date.now();
@@ -207,7 +255,7 @@ export class CollaborationStore {
             if (!ids.has(message.id) || message.status === 'expired' || message.status === 'failed' || message.status === 'read')
                 return message;
             const updated = status === 'read'
-                ? { ...message, status, deliveredAt: message.deliveredAt ?? now, readAt: now, readSource: 'explicit', deliverySource: message.deliverySource ?? (message.deliveredAt === null ? 'consumer_read' : 'legacy_or_unspecified') }
+                ? { ...message, status, deliveredAt: message.deliveredAt ?? now, readAt: now, readSource, deliverySource: message.deliverySource ?? (message.deliveredAt === null ? 'consumer_read' : 'legacy_or_unspecified') }
                 : message.status === 'pending' ? { ...message, status, deliveredAt: now, deliverySource: 'pty_written' } : message;
             changed.push(updated);
             return updated;
@@ -321,6 +369,13 @@ export class CollaborationStore {
             this.persist();
         }
     }
+    setSnapshot(id, snapshot) {
+        const message = this.getMessage(id);
+        if (!message)
+            return;
+        message.snapshot = snapshot;
+        this.persist();
+    }
     diagnostic(id) { return this.document.transport?.[id] ?? null; }
     recordTransport(id, diagnostic) {
         if (!this.getMessage(id))
@@ -337,6 +392,7 @@ export class CollaborationStore {
         return { message_id: id, thread_id: message.threadId, status: message.status, queued_at: message.createdAt,
             delivered_at: message.deliveredAt, read_at: message.readAt, expires_at: message.expiresAt ?? null,
             failure_reason: message.failureReason ?? null, delivery_semantics: message.deliverySource ?? (message.deliveredAt === null ? 'not_delivered' : 'legacy_or_unspecified'), read_semantics: message.readAt ? message.readSource ?? 'legacy_or_unspecified' : 'not_read',
+            snapshot: message.snapshot ?? null,
             idempotency_key: message.idempotencyKey ?? null,
             ack_at: replies.find((reply) => reply.responseKind === 'ack')?.createdAt ?? null,
             reply_ids: replies.map((reply) => reply.id), result_ids: replies.filter((reply) => reply.responseKind === 'result').map((reply) => reply.id),
@@ -354,11 +410,29 @@ export class CollaborationStore {
         for (const message of reports)
             if (message.task)
                 tasks.set(message.task.task_id, { task_id: message.task.task_id, status: message.task.status, reported_at: message.createdAt, message_id: message.id });
+        // Aggregated from the *latest* report of each task, never inferred: an
+        // agent handed a task that has not yet replied is simply idle here —
+        // dispatch in flight is the sender-side receipt's concern (pending), not a
+        // fact about this session. blocked counts as active: the agent holds the
+        // task open. A failed terminal state only surfaces once no task is still
+        // in flight, since another in-progress task means the agent is busy.
+        const latest = [...tasks.values()];
+        const taskState = latest.some((task) => task.status === 'ack' || task.status === 'working' || task.status === 'blocked') ? 'active'
+            : latest.some((task) => task.status === 'failed') ? 'failed'
+                : 'idle';
         return { session_state: online ? 'online' : 'offline', turn_state: turnState === 'done' ? 'ended' : turnState ?? 'unknown',
-            task_state: 'unknown', tasks: [...tasks.values()], last_heartbeat: null, last_tool_activity_at: null,
+            task_state: taskState, tasks: [...tasks.values()], last_heartbeat: null, last_tool_activity_at: null,
             last_message_at: reports.length ? Math.max(...reports.map((message) => message.createdAt)) : null,
             state_source: 'optional_adapter', task_source: 'explicit_message' };
     }
+    /** Timeline of one task as reported by a session, oldest first. The lineage
+     *  starts at the recipient's first reply carrying that task_id — a bare
+     *  dispatch carries no envelope. Messages without a task simply never
+     *  match. */
+    byTask(sessionId, taskId) {
+        this.expire();
+        return this.document.messages.filter((message) => message.fromSessionId === sessionId && message.task?.task_id === taskId);
+    }
     page(sessionId, options = {}) {
         this.expire();
         if (options.responseKind && !['ack', 'progress', 'result'].includes(options.responseKind))

package/dist/server/agent/collaborationTmuxDelivery.js

@@ -1,10 +1,95 @@
 import { buildBracketedSubmitBytes } from './promptDelivery.js';
-export async function writeCollaborationTmuxPane(run, pane, prompt) {
+const TMUX_KEY_NAMES = {
+    enter: 'Enter', escape: 'Escape', space: 'Space', left: 'Left', right: 'Right', up: 'Up', down: 'Down',
+};
+/** Screen text that means an interactive approval/confirm dialog is showing.
+ * Driving approve sends Enter, which activates the highlighted option — the
+ * number of tools that render such prompts is finite, but the phrasing is
+ * not, so match generously and never press keys without this evidence. */
+const APPROVAL_DIALOG_PATTERNS = [
+    /requires approval/i,
+    /needs? approval/i,
+    /do you want to proceed/i,
+    /do you want to (continue|run this)/i,
+    /is this ok/i,
+    /\b1\.\s*yes\b/i,
+    /需要批准|需要授权|等待批准/i,
+    /是否(允许|继续|执行|批准)/,
+    /\b1\.\s*是\b/,
+    /允许.*执行|确认.*执行/i,
+];
+/** Agent TUIs collapse pasted input in the input box to a marker line like
+ * "[Pasted text #3 +42 lines]". While the paste sits unsubmitted the marker
+ * stays on screen; a submitted paste clears the box and only the transcript
+ * holds the content. Session-unique #N lets us diff screen captures. */
+const PASTE_MARKER_PATTERN = /\[Pasted text #(\d+)/g;
+export function detectApprovalDialog(content) {
+    return APPROVAL_DIALOG_PATTERNS.some((pattern) => pattern.test(content));
+}
+/** Paste marker sequence numbers visible in a screen capture. */
+export function extractPasteMarkerNumbers(content) {
+    return new Set([...content.matchAll(PASTE_MARKER_PATTERN)].map((match) => Number(match[1])));
+}
+/** True when `after` shows a paste marker that was not in `before`. Diffing
+ * prevents a recovery Enter from submitting a stale paste that predates this
+ * delivery (or someone else's draft): we only ever submit what we just put
+ * there, at most once per delivery. */
+export function hasNewPasteMarker(after, before) {
+    const beforeNumbers = extractPasteMarkerNumbers(before);
+    return [...extractPasteMarkerNumbers(after)].some((number) => !beforeNumbers.has(number));
+}
+async function assertSamePane(run, pane) {
     const identity = (await run(['display-message', '-p', '-t', pane.paneId,
         '#{pid}:#{session_id}:#{pane_id}:#{pane_pid}'])).trim();
     if (identity !== `${pane.serverPid}:${pane.sessionId}:${pane.paneId}:${pane.panePid}`)
         throw new Error('TMUX_PANE_CHANGED');
+}
+export async function writeCollaborationTmuxPane(run, pane, prompt) {
+    await assertSamePane(run, pane);
     // A fixed pane target is independent of the current window, keyboard focus
     // and browser presence. One invocation preserves the bracketed submit bytes.
     await run(['send-keys', '-t', pane.paneId, '-l', '--', buildBracketedSubmitBytes(prompt)]);
 }
+/** Inject a named key into a member pane after proving the pane identity
+ *  unchanged. Named keys only — no freeform keystroke passthrough. */
+export async function sendTmuxPaneKey(run, pane, key) {
+    await assertSamePane(run, pane);
+    await run(['send-keys', '-t', pane.paneId, TMUX_KEY_NAMES[key]]);
+}
+/** Current pane screen text (viewport), identity-checked. */
+export async function captureTmuxPaneText(run, pane) {
+    await assertSamePane(run, pane);
+    const raw = await run(['capture-pane', '-p', '-J', '-t', pane.paneId]);
+    return raw.replace(/\x1b\][^\x07]*(\x07|\x1b\\)/g, '').replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, '');
+}
+/** Dismiss an interactive approval dialog on the member pane by pressing
+ *  Enter (the highlighted option). Refuses unless the screen actually shows
+ *  an approval prompt: driving a dialog that isn't there would only inject
+ *  a stray keystroke into the agent's work. Returns false when no dialog. */
+export async function approveCollaborationDialog(run, pane) {
+    const content = await captureTmuxPaneText(run, pane);
+    if (!detectApprovalDialog(content))
+        return false;
+    await sendTmuxPaneKey(run, pane, 'enter');
+    return true;
+}
+/** Submit a paste that arrived while the agent was finishing its previous
+ *  turn and is still sitting unsubmitted in the input box. Only acts on
+ *  differential evidence — a paste marker that appeared after the write —
+ *  never on pre-existing stale markers, and returns whether Enter was sent.
+ *  Committing the whole input buffer is safe: each delivery is written once,
+ *  so each marker's content enters the transcript exactly once. */
+export async function recoverStuckPaste(run, pane, baseline) {
+    const viewport = await captureTmuxPaneText(run, pane);
+    if (!hasNewPasteMarker(viewport, baseline))
+        return false;
+    await sendTmuxPaneKey(run, pane, 'enter');
+    return true;
+}
+/** History-inclusive pane text (scrollback + viewport) used to confirm a
+ *  delivery was actually rendered by the agent, not wiped by a boot clear. */
+export async function captureTmuxPaneHistory(run, pane, lines = 800) {
+    await assertSamePane(run, pane);
+    const raw = await run(['capture-pane', '-p', '-J', '-S', `-${lines}`, '-t', pane.paneId]);
+    return raw.replace(/\x1b\][^\x07]*(\x07|\x1b\\)/g, '').replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, '');
+}

package/dist/server/cli.js

@@ -1244,12 +1244,13 @@ async function getLocalJson(baseUrl, token, endpoint, timeoutMs = 30_000) {
     });
 }
 async function runCollab(command) {
-    if (command.action === 'help') {
-        console.log(COLLAB_HELP);
-        return;
-    }
     const runningState = getRunningState();
     if (!runningState?.localApiToken) {
+        // Help is a plain read: it must stay available without a running server.
+        if (command.action === 'help') {
+            console.log(COLLAB_HELP);
+            return;
+        }
         console.error(JSON.stringify({ ok: false, code: 'SERVICE_UNAVAILABLE', error: 'Termdock is not running or its local API token is unavailable.' }));
         process.exit(1);
     }
@@ -1275,6 +1276,12 @@ async function runCollab(command) {
         }
     }
     if (!backendSessionId && !tmuxSessionName) {
+        // Bare help stays reachable from a plain shell; the roster snapshot in
+        // help needs a session identity and only appears when one is available.
+        if (command.action === 'help') {
+            console.log(COLLAB_HELP);
+            return;
+        }
         console.error(JSON.stringify({ ok: false, code: 'SESSION_NOT_FOUND', error: 'td collab must run inside a Termdock-managed Session.' }));
         process.exit(1);
     }