termdock 1.4.189 → 1.4.191

package/dist/server/agent/collaborationPrompt.js

@@ -1,82 +1,117 @@
-const MESSAGE_LABELS = {
-    message: '消息',
-    ask: '问题',
-    reply: '回复',
-    task: '任务',
-    handoff: '交接',
-    done: '完成',
-};
+import { sanitizeCollaborationRole } from './collaborationStore.js';
+const SHELL_RULE = '─'.repeat(30);
+/** Body larger than this (in UTF-8 bytes) is replaced by a retrieval pointer
+ * instead of being injected into the terminal verbatim. */
+const MAX_INLINE_BODY_BYTES = 8_192;
+/**
+ * Characters that would corrupt the delivery shell header `「X」群(N 个成员)`
+ * and the per-message `来自:X · kind` line: the quote brackets and the middle
+ * dot, which the render layer uses as structure, plus control sequences
+ * (C0 controls + DEL) that could inject terminal output. Legacy and federated
+ * names may carry them, so the render layer neutralizes them defensively;
+ * user-entered names are rejected at creation instead.
+ */
+export const COLLAB_NAME_FORBIDDEN = /[【】「」·\x00-\x1f\x7f]/;
+/** Render-safe name for shell header / per-message source lines: reserved
+ * bracket and delimiter characters become spaces (they would otherwise split
+ * the `「X」群` and `来自:X · kind` lines), control characters are
+ * neutralized, whitespace collapses, and the display length is capped. */
+export function sanitizeCollaborationName(name, max = 40) {
+    const cleaned = name
+        .replace(/[【】「」]/g, ' ')
+        .replace(/·/g, ' ')
+        .replace(/[\x00-\x1f\x7f]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+    return cleaned.length > max ? `${cleaned.slice(0, max - 1)}…` : cleaned;
+}
+/** A single delivered message: `来自:X · kind` over a fenced body, with the
+ * reply route for agent-sourced messages kept outside the fence. A fan-out
+ * dispatch (message.fanOutIds present) is flagged `· 群发` and names the
+ * sibling recipients on their own line, so a broadcast is never mistaken for
+ * a one-to-one assignment — raw ids fall back to the sanitized id itself. */
+function formatCollaborationMessage(message, source, fannedNames, fence) {
+    const lines = [`来自:${source} · ${message.kind}${fannedNames.length ? ' · 群发' : ''}`];
+    if (fannedNames.length)
+        lines.push(`同时发给了:${fannedNames.join('、')}`);
+    lines.push('', fence, message.content, fence);
+    if (message.task)
+        lines.push('', `任务上报:${JSON.stringify(message.task)}`);
+    if (message.fromSessionId)
+        lines.push('', `回复:td collab reply ${message.id} "回复内容" --text`);
+    return lines.join('\n');
+}
 export function formatCollaborationDelivery(input) {
     const groupsById = new Map(input.groups.map((group) => [group.id, group]));
     const sessionsById = new Map(input.sessions.map((session) => [session.sessionId, session]));
-    const messageBlocks = input.messages.map((message) => {
+    const blocks = [];
+    for (const message of input.messages) {
         const sourceSession = message.fromSessionId ? sessionsById.get(message.fromSessionId) : null;
         const source = message.fromSessionId
-            ? [
-                sourceSession?.name ?? message.fromSessionId,
-                sourceSession?.agentNativeSessionId ? `Agent 原生 Session ID：${sourceSession.agentNativeSessionId}` : null,
-                `Termdock 会话 ID：${message.fromSessionId}`,
-            ].filter(Boolean).join('\n')
+            ? sanitizeCollaborationName(sourceSession?.name ?? message.fromSessionId)
             : '用户';
-        const group = groupsById.get(message.groupId)?.name ?? '协作组';
-        return [
-            `[${MESSAGE_LABELS[message.kind]} #${message.id}]`,
-            `来自：${source}`,
-            `协作组：${group}`,
-            '--- 消息内容 ---',
-            Buffer.byteLength(message.content) > 8_192
-                ? `大消息已完整保存（${Buffer.byteLength(message.content)} 字节）。使用 td collab message get ${message.id} --json 获取正文；不要把这条提示当作任务正文。`
-                : message.content,
-            '--- 消息结束 ---',
-            ...(message.responseKind ? [`回复类型：${message.responseKind}（ack=收到，progress=进展，result=结果；结果不保证成功）`] : []),
-            ...(message.task ? [`任务上报：${JSON.stringify(message.task)}`] : []),
-        ].join('\n');
-    });
+        const bytes = Buffer.byteLength(message.content);
+        const body = bytes > MAX_INLINE_BODY_BYTES
+            ? `大消息已完整保存（${bytes} 字节）。使用 td collab message get ${message.id} --json 获取正文；不要把这条提示当作消息正文。`
+            : message.content;
+        const fence = '`'.repeat(Math.max(3, ...Array.from(body.matchAll(/`+/g), (match) => match[0].length + 1)));
+        const fannedNames = (message.fanOutIds ?? [])
+            .map((sessionId) => sanitizeCollaborationName(sessionsById.get(sessionId)?.name ?? sessionId));
+        blocks.push(formatCollaborationMessage({ ...message, content: body }, source, fannedNames, fence));
+    }
+    // The shell header names the group only when every block belongs to one;
+    // a mixed batch drops the header entirely (no single-group claim to make).
+    // The member count rides along as the at-a-glance size of that group.
+    const groupIds = [...new Set(input.messages.map((message) => message.groupId))];
+    const singleGroup = groupIds.length === 1 ? groupsById.get(groupIds[0]) : null;
+    const shellHeader = singleGroup
+        ? `「${sanitizeCollaborationName(singleGroup.name ?? '协作组')}」群(${singleGroup.sessionIds.length} 个成员)`
+        : '';
     const peerIds = Array.from(new Set(input.groups.flatMap((group) => group.sessionIds)))
         .filter((sessionId) => sessionId !== input.targetSessionId);
-    const peers = peerIds.map((sessionId) => {
+    // Keep routing IDs once, only for peers who are not already directly replyable.
+    const sourceIds = new Set(input.messages.map((message) => message.fromSessionId));
+    const peers = peerIds.filter((id) => !sourceIds.has(id)).map((sessionId) => {
         const session = sessionsById.get(sessionId);
-        return [
-            `- ${session?.name ?? '离线会话'} · ${session?.status === 'service-unreachable' ? '服务不可达，消息无法送达；仅可排队等待服务重连' : session?.status ?? 'offline'}`,
-            ...(session?.agentNativeSessionId ? [`  Agent 原生 Session ID：${session.agentNativeSessionId}`] : []),
-            `  Termdock 会话 ID：${sessionId}`,
-        ].join('\n');
+        return `- ${session ? sanitizeCollaborationName(session.name) : '离线会话'}：\`td collab send ${sessionId} "消息内容" --text\``;
     });
-    const hasUserMessage = input.messages.some((message) => message.fromSessionId === null);
-    const hasAgentMessage = input.messages.some((message) => message.fromSessionId !== null);
-    const hasNativePeer = peerIds.some((sessionId) => Boolean(sessionsById.get(sessionId)?.agentNativeSessionId));
-    const groupLines = input.groups.map((group) => `- ${group.name} [${group.id}] · ${group.sessionIds.length} 个成员`);
-    const instructions = [
-        ...(hasNativePeer
-            ? ['- 如果你自身具备按 Agent 原生 Session ID 与其他 Session 通信的内建能力，优先使用该能力和上方的原生 ID。']
-            : []),
-        '- 如果没有这种内建能力，则使用下方 Termdock 收件箱命令；命令中的 <会话ID> 指 Termdock 会话 ID。',
-        ...(hasUserMessage ? ['- 用户消息：直接在当前会话回答或执行（无来源 Agent，不能运行 `td collab reply`）。'] : []),
-        ...(hasAgentMessage ? ['- 回复：`td collab reply <消息ID> "回复内容"`'] : []),
-        ...(peerIds.some((id) => id.startsWith('remote:')) ? ['- 跨服务成员必须使用 td collab 通信；服务不可达时消息尚未送达，不要把 pending 当作成功，也不要假定对方已收到任务。转发客户端须保持运行；网页或 PWA 暂停后，返回前台继续转发。'] : []),
-        '- 发消息：`td collab send <会话ID> "消息内容"`',
-        '- 交接：`td collab handoff <会话ID> "交接摘要"`',
-        '- 加成员：`td collab add <协作组ID> <会话ID>`',
-        '- 移成员：`td collab remove <协作组ID> <会话ID>`',
-        '- 新建 Agent：`td collab spawn <协作组ID> <agent-slug> --name "名称" --task "初始任务"`',
-        '- 查看：`td collab status` / `td collab inbox`；完整选项：`td collab --help`。默认 JSON，pending 只表示已入队。',
-        '- 确认投递：`td collab message get <消息ID> --receipt-only`；send/reply 可加 `--wait-until delivered --timeout 30s`。超时不会取消消息，重试使用同一 `--idempotency-key`。',
-        '- 只取新回复：`td collab inbox --consumer <名称> --limit 20`；处理完成后用返回的 next_cursor 执行 `td collab cursor commit <游标> --consumer <名称>`。需要明确标记读取时用 `td collab message read <消息ID>`。',
-        '- 回复应明确类型：reply 加 `--response-kind ack|progress|result`；可附 `--task-envelope` JSON（task_id、status、progress、evidence、blocker）。不要把 ACK 或 turn done 汇报为任务完成。',
-        '- Agent 状态与工具活动只作可选提示；任意接入方都可通过收件箱主动读取、确认和回复，无需专用 hooks。',
+    const unreachable = peerIds.filter((id) => sessionsById.get(id)?.status === 'service-unreachable');
+    // Education (peer roster examples) decays once the session knows the group;
+    // the `--help` pointer stays permanently as the one-line entrance to the
+    // full command surface — everything else can be looked up from there.
+    const routingHelp = input.showRoutingHelp === false ? [] : (peers.length ? ['联系其他成员：', ...peers] : []);
+    const dynamicNotices = [
+        ...(peerIds.some((id) => id.startsWith('remote:'))
+            ? ['跨服务通信使用 td collab；转发客户端须保持运行，网页或 PWA 暂停后需返回前台继续转发。'] : []),
+        ...unreachable.map((id) => {
+            const session = sessionsById.get(id);
+            return `注意：${session ? sanitizeCollaborationName(session.name) : id} 服务不可达，消息无法送达；仅可排队等待重连。`;
+        }),
     ];
-    return [
-        `[Termdock 协作收件箱 · ${input.messages.length} 条]`,
-        '',
-        messageBlocks.join('\n\n'),
-        '',
-        '协作组：',
-        ...groupLines,
-        '',
-        '同组成员：',
-        ...(peers.length > 0 ? peers : ['- 暂无其他成员']),
-        '',
-        '可用操作：',
-        ...instructions,
-    ].join('\n');
+    const notes = [...routingHelp, ...dynamicNotices, '更多操作：`td collab --help`。'];
+    // Notes (education + dynamic notices) live inside the shell, after the last
+    // message, so the closing rule still marks the end of the delivered block.
+    if (!blocks.length)
+        return notes.join('\n');
+    // Self-identity rides the shell under the header so the recipient always
+    // knows the name peers see (a rename lands on the next delivery — no
+    // separate notification needed) and, in a single-group delivery, its role.
+    // The name needs no group claim and survives mixed batches; the role (定位)
+    // only rides when the batch maps to exactly one group.
+    const ownName = sanitizeCollaborationName(sessionsById.get(input.targetSessionId)?.name ?? '');
+    const ownRole = singleGroup
+        ? sanitizeCollaborationRole(singleGroup.roles?.[input.targetSessionId] ?? '')
+        : '';
+    const lines = [SHELL_RULE];
+    if (shellHeader)
+        lines.push(shellHeader);
+    if (ownName)
+        lines.push(`你的名字:${ownName}`);
+    if (ownRole)
+        lines.push(`你的定位:${ownRole}`);
+    // No blank line between the identity block and the first message, nor
+    // between the last message and the notes: the shell reads as one compact
+    // block, and only message-to-message boundaries keep a blank line.
+    lines.push(blocks.join('\n\n'), ...notes, SHELL_RULE);
+    return lines.join('\n');
 }

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,65 @@
 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,
+];
+export function detectApprovalDialog(content) {
+    return APPROVAL_DIALOG_PATTERNS.some((pattern) => pattern.test(content));
+}
+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;
+}
+/** 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, '');
+}