termdock 1.4.307 → 1.4.309

package/dist/server/agent/collaborationCli.js

@@ -52,12 +52,41 @@ export const COLLAB_HELP = `td collab — durable messages; no agent-specific ho
 ── 后台集成（独立凭据；本机 Unix socket） ──
   td integration help（管理授权与启动配置）
   td collab --principal <id> capabilities
+  send <成员id> "执行正文" --idempotency-key <key>（权限 message.send；普通消息，不创建看板任务）
+  reply <原消息id> "追问正文" --idempotency-key <key>（回到原成员、原话题）
+  message get <id> | message list [--thread <id>] [--after-id <id>] [--limit 1..200]
+    （权限 message.read；list 返回保留记录，next_after_id/has_more 用于分页）
+  以上命令均需前缀 td collab --principal <id>；send/reply 支持 --file/--stdin。
+  来源可附 --source <name> --external-actor '<JSON object>' --external-message-id <id>。
+  Agent 在终端收到消息后：td collab --session <自己的TD成员id> reply <原消息id> "答复" --response-kind result --idempotency-key <key>
+    ack=明确回复收到；progress=原文进展；result=原文结果。后台回复 status=stored，仅表示持久保存。
+    回复通过 message.reply 事件主动推送；payload.reply_to 关联原消息，response_kind 标记回复类型。
   events subscribe --consumer <name> --jsonl（主动推送，默认持续运行）
   events ack <cursor> --consumer <name>（仅声明已持久接收）
+    events 需权限 events.read；按 event_id 去重，落盘后 ACK 连续前缀；订阅读到不等于 ACK。
+    断线自动重连，同 consumer 从已 ACK 处重放；保留缺口 EVENT_RETENTION_GAP 停止，需对账后换 consumer。
+    消息历史只覆盖仍保留记录；不存在的 after-id 返回 MESSAGE_NOT_FOUND，不能据此声称历史完整。
   session create --group <id> --launch-profile <id> --cwd <absolute-path> --idempotency-key <key>
   session get <id> | session restore <id> --idempotency-key <key>
+  session release <id> --generation <session-get-generation> --idempotency-key <key>
+    权限 session.release；仅原 Agent 已退出、精确空 shell、无 pending 消息时释放实际运行承载。
+    released: runtime_present=false、terminal_binding=null；保留逻辑 ID/原生 UUID/原消息，restore 后可继续 reply。
+    released 上 send/reply 返回 SESSION_RELEASED，不入队、不隐式恢复；业务先持久接收，再明确 restore。
+    释放/恢复最低 CLI/实际服务 1.4.309；检查 session_runtime_release/stable_session_identity/session_lifecycle_generation。
+    generation 每次实际 restore/release/管理员兼容确认递增；旧 generation 拒绝，运行中精确 restore 不递增。
+    重用同幂等键回读原操作结果，不能用于新一轮恢复；用 session get 查询当前状态。
+    旧配置须管理员 td integration resume-configuration <id> 查看，再 confirm-resume 显式确认当前指纹。
+    状态 starting/restoring/binding_pending/ready/failed/releasing/released；runtime_present=null 表示无法确认。
+    失败码：INVALID_SESSION_GENERATION、SESSION_GENERATION_MISMATCH、SESSION_RELEASE_UNSUPPORTED；
+    SESSION_PENDING_MESSAGES/SESSION_STILL_RUNNING/SESSION_OPERATION_IN_PROGRESS 表示应先处理原现场；
+    SESSION_NATIVE_OPERATION_IN_PROGRESS、SESSION_SCOPE_CONFLICT、SESSION_IDENTITY_MISMATCH 拒绝并发或身份/归属冲突；
+    SESSION_RELEASE_FAILED、SESSION_STORAGE_FULL 保留原记录，不表示回收成功；
+    RESUME_CONFIGURATION_CHANGED/RESUME_CONFIGURATION_UNCONFIRMED 拒绝静默替换配置；OPERATION_OUTCOME_UNCONFIRMED 保留记录待核对。
   task respond <task-id> --attempt <attempt-id> --to-event <comment-event-id> --content <答复>
   凭据通过 TERMDOCK_INTEGRATION_CREDENTIAL_FILE 注入，不通过命令行传 token。
+  消息接入最低 CLI/实际服务均为 1.4.308；capabilities 回读双方版本与 integration_message_send/reply/history。
+  principal 只操作获授权本机组；不能冒充用户/成员或用户验收。普通消息不需要 task/accepted。
+  任务命令适用于需要任务闭环的流程；message.send/read 与 task 权限独立。
   已验收任务可追加纯咨询；respond 保留当前结果与验收，revise 是修改要求。
 ── 常用 ──
   status (who is in my groups, their names, roles, observed activity.
@@ -145,11 +174,11 @@ Message limit: ${COLLAB_LIMITS.message_bytes} UTF-8 bytes; metadata: ${COLLAB_LI
 Idempotency retention: 7 days. Terminal delivery, ACK and result never imply each other.
 Delivery semantics: delivered = written to the terminal — never proof of
 reading or task completion; a timeout stops waiting, it does not cancel delivery.
-The service cannot see whether the recipient's agent consumed a message. To
-judge for yourself, use --wait-until delivered and read the recipient-screen
-snapshot in the receipt: if your message is not visible on that screen, send it
-again (a fresh send is a new message and will be written again); if it is
-visible but unanswered, the recipient may simply not have started yet.`;
+The service cannot see whether the recipient's agent consumed a message.
+Use explicit replies as evidence. A screen snapshot is only an observation;
+do not automatically resend a delivered message because it is absent from a snapshot.
+stored = durable reply to a nonterminal principal; terminal delivery waits do not apply.
+Idempotent retries reuse the same key and payload; a fresh key creates a new message.`;
 /** One roster row: prefer the member's human name, keep the full session id
  * reachable for role set/unset targeting, mark unset members explicitly. */
 function roleLine(member, role) {
@@ -157,7 +186,7 @@ function roleLine(member, role) {
     return role ? `- ${label}：${role}` : `- ${label}（未设置）`;
 }
 const BOOLEAN_OPTIONS = new Set(['json', 'jsonl', 'text', 'follow', 'stdin', 'receipt-only', 'confirm', 'raw', 'help', 'no-rules', 'managed', 'shared-directory', 'integration']);
-const VALUE_OPTIONS = new Set(['purpose', 'principal', 'source', 'external-actor', 'external-message-id', 'launch-profile', 'to-event', 'decision', 'work-type', 'summary', 'verdict', 'reviewers', 'title', 'content', 'constraints', 'acceptance', 'assignee', 'coordinator', 'parent', 'depends-on', 'attempt', 'status', 'artifact', 'options', 'revision', 'evidence', 'session', 'group', 'thread', 'idempotency-key', 'file', 'wait-until', 'timeout', 'expect-reply', 'response-kind', 'metadata', 'task-envelope', 'expires-at', 'since', 'after-id', 'cursor', 'consumer', 'limit', 'from', 'kind', 'name', 'cwd', 'task', 'pane', 'lines', 'if-version', 'origin']);
+const VALUE_OPTIONS = new Set(['generation', 'purpose', 'principal', 'source', 'external-actor', 'external-message-id', 'launch-profile', 'to-event', 'decision', 'work-type', 'summary', 'verdict', 'reviewers', 'title', 'content', 'constraints', 'acceptance', 'assignee', 'coordinator', 'parent', 'depends-on', 'attempt', 'status', 'artifact', 'options', 'revision', 'evidence', 'session', 'group', 'thread', 'idempotency-key', 'file', 'wait-until', 'timeout', 'expect-reply', 'response-kind', 'metadata', 'task-envelope', 'expires-at', 'since', 'after-id', 'cursor', 'consumer', 'limit', 'from', 'kind', 'name', 'cwd', 'task', 'pane', 'lines', 'if-version', 'origin']);
 export function parseCollaborationCommand(argv) {
     const options = {};
     const positional = [];
@@ -223,12 +252,14 @@ export function parseCollaborationCommand(argv) {
             throw new Error('Unexpected integration arguments');
         if (action === 'events' && (!['subscribe', 'ack'].includes(command.operation ?? '') || (command.operation === 'ack' ? !command.target : Boolean(command.target))))
             throw new Error('Usage: events subscribe | events ack <cursor>');
-        if (action === 'session' && (!['create', 'get', 'restore'].includes(command.operation ?? '') || (command.operation === 'create' ? Boolean(command.target) : !command.target)))
-            throw new Error('Usage: session create|get|restore');
+        if (action === 'session' && (!['create', 'get', 'restore', 'release'].includes(command.operation ?? '') || (command.operation === 'create' ? Boolean(command.target) : !command.target)))
+            throw new Error('Usage: session create|get|restore|release');
         if (action === 'session' && command.operation !== 'get' && !options['idempotency-key'])
             throw new Error('Session mutation requires an explicit --idempotency-key');
+        if (action === 'session' && command.operation === 'release' && (!/^[1-9][0-9]*$/.test(String(options.generation ?? '')) || !Number.isSafeInteger(Number(options.generation))))
+            throw new Error('session release requires --generation from session get');
         const integrationFlags = action === 'events' ? command.operation === 'ack' ? ['consumer'] : ['consumer', 'group', 'timeout']
-            : command.operation === 'create' ? ['group', 'launch-profile', 'cwd', 'idempotency-key'] : command.operation === 'restore' ? ['idempotency-key'] : [];
+            : command.operation === 'create' ? ['group', 'launch-profile', 'cwd', 'idempotency-key'] : command.operation === 'restore' ? ['idempotency-key'] : command.operation === 'release' ? ['idempotency-key', 'generation'] : [];
         for (const flag of Object.keys(options))
             if (!['principal', 'json', 'jsonl', 'text', 'help', ...integrationFlags].includes(flag))
                 throw new Error(`--${flag} is not supported by ${action} ${command.operation}`);
@@ -250,6 +281,8 @@ export function parseCollaborationCommand(argv) {
             throw new Error(`${action} requires a target and message`);
         if ([Boolean(command.message), Boolean(options.file), Boolean(options.stdin)].filter(Boolean).length !== 1)
             throw new Error('Choose inline body, --file, or --stdin');
+        if (options.principal && !options['idempotency-key'])
+            throw new Error('Integration message mutation requires an explicit --idempotency-key');
     }
     else if (action === 'rules') {
         command.operation = positional.shift();
@@ -286,8 +319,15 @@ export function parseCollaborationCommand(argv) {
     else if (action === 'message') {
         command.operation = positional.shift();
         command.target = positional.shift();
-        if (!['get', 'watch', 'confirm-shell'].includes(command.operation ?? '') || !command.target || positional.length)
-            throw new Error('Usage: td collab message get|watch|confirm-shell <id>');
+        if (!['get', 'watch', 'confirm-shell', 'list'].includes(command.operation ?? '') || (command.operation === 'list' ? !options.principal || Boolean(command.target) : !command.target) || positional.length)
+            throw new Error('Usage: td collab message get|watch|confirm-shell <id>; --principal <id> message list');
+        if (command.operation === 'list') {
+            for (const flag of Object.keys(options))
+                if (!['principal', 'json', 'jsonl', 'text', 'group', 'thread', 'after-id', 'limit'].includes(flag))
+                    throw new Error(`--${flag} is not supported by message list`);
+        }
+        else if (['group', 'thread', 'after-id', 'limit'].some(flag => options[flag] !== undefined))
+            throw new Error('History filters apply to --principal message list only');
     }
     else if (action === 'cursor') {
         command.operation = positional.shift();
@@ -357,18 +397,21 @@ export function parseCollaborationCommand(argv) {
         throw new Error(`Unexpected arguments for ${action}`);
     const allowed = new Set(['json', 'jsonl', 'text', 'help', 'session', 'principal']);
     const byAction = {
-        events: ['consumer', 'group', 'timeout'], session: ['group', 'launch-profile', 'cwd', 'idempotency-key'],
+        events: ['consumer', 'group', 'timeout'], session: ['group', 'launch-profile', 'cwd', 'idempotency-key', 'generation'],
         task: ['purpose', 'to-event', 'decision', 'source', 'external-actor', 'external-message-id', 'metadata', 'work-type', 'summary', 'integration', 'managed', 'shared-directory', 'reviewers', 'verdict', 'group', 'title', 'content', 'constraints', 'acceptance', 'assignee', 'coordinator', 'parent', 'depends-on', 'attempt', 'status', 'artifact', 'options', 'revision', 'evidence', 'idempotency-key', 'file', 'stdin'],
         rules: ['file', 'stdin', 'if-version'], transport: ['file', 'origin'], group: ['file'], status: [], capabilities: [], rebind: ['pane'], help: [...BOOLEAN_OPTIONS, ...VALUE_OPTIONS],
         send: ['group', 'thread', 'idempotency-key', 'file', 'stdin', 'wait-until', 'timeout', 'expect-reply', 'response-kind', 'metadata', 'expires-at', 'kind'],
         handoff: ['group', 'thread', 'idempotency-key', 'file', 'stdin', 'wait-until', 'timeout', 'expect-reply', 'response-kind', 'metadata', 'expires-at'],
         reply: ['idempotency-key', 'file', 'stdin', 'wait-until', 'timeout', 'expect-reply', 'response-kind', 'metadata', 'task-envelope', 'expires-at'],
         inbox: ['raw', 'since', 'after-id', 'cursor', 'consumer', 'limit', 'from', 'group', 'thread', 'kind', 'response-kind', 'follow', 'timeout'],
-        message: ['raw', 'receipt-only', 'no-rules', 'follow', 'wait-until', 'timeout', 'expect-reply'], cursor: ['consumer'],
+        message: ['raw', 'receipt-only', 'no-rules', 'follow', 'wait-until', 'timeout', 'expect-reply', 'group', 'thread', 'after-id', 'limit'], cursor: ['consumer'],
         add: [], remove: [], spawn: ['launch-profile', 'name', 'cwd', 'task'], role: [], rename: [], cleanup: ['confirm'], drive: ['lines', 'raw'],
     };
     for (const option of byAction[action])
         allowed.add(option);
+    if (options.principal && ['send', 'reply'].includes(action))
+        for (const option of ['source', 'external-actor', 'external-message-id'])
+            allowed.add(option);
     for (const option of Object.keys(options))
         if (!allowed.has(option))
             throw new Error(`--${option} is not supported by ${action}`);
@@ -394,7 +437,7 @@ export function waitSatisfied(receipt, stage, reply) {
  *  machine reasons onto what the sender should do next, so a settled-but-
  *  unconsumed message is not mistaken for a lost one (or a good one). */
 const DELIVERY_DIAGNOSTICS = {
-    AGENT_CONSUME_UNCONFIRMED: '消息已写入对方终端，但未确认被对方消费；它可能尚未开始处理，可用 capture 查看当前屏幕或重发',
+    AGENT_CONSUME_UNCONFIRMED: '消息已写入对方终端，但未确认被对方消费；等待明确回复，不从终端快照推断消费或自动重发',
     SHELL_CONFIRMATION_REQUIRED: '目标当前是 shell，消息可能被当命令执行；确认请运行 message confirm-shell <id>',
     DELIVERY_IN_PROGRESS: '投递进行中（写入前的中间标记，正常会在数秒内推进为 delivered 或带原因的重试）',
     TERMINAL_WRITE_FAILED: '写入对方终端失败，会按重试间隔继续尝试',
@@ -430,17 +473,22 @@ export async function executeCollaborationCommand(command, context, io) {
     const output = (value) => {
         if (o.text) {
             let diagnosed = false;
-            if (Array.isArray(value.messages))
+            if (Array.isArray(value.messages)) {
                 for (const message of value.messages) {
                     const fanIds = Array.isArray(message.fanOutIds) ? message.fanOutIds : [];
                     const names = value.names ?? {};
-                    io.write(`[${message.responseKind ?? message.kind}] ${canonicalShortId(message.id)} from ${message.fromSessionId ?? 'user'}${fanIds.length ? ' · 群发' : ''}`);
+                    io.write(`[${message.responseKind ?? message.kind}] ${canonicalShortId(message.id)} from ${message.fromSessionId ?? (message.integrationOrigin ? `principal:${message.integrationOrigin.integrationId}` : 'user')}${fanIds.length ? ' · 群发' : ''}`);
                     // A fan-out dispatch names its sibling recipients so a broadcast is
                     // never read as a one-to-one assignment; unknown ids stay raw.
                     if (fanIds.length)
                         io.write(`同时发给了:${fanIds.map((id) => names[id] ?? id).join('、')}`);
                     io.write(message.content);
+                    if (message.status === 'stored')
+                        io.write('答复已持久保存；接收方是后台程序，不是终端。');
                 }
+                if (value.next_after_id !== undefined)
+                    io.write(`next_after_id=${value.next_after_id ?? ''} has_more=${value.has_more === true}（仅保留记录）`);
+            }
             else if (value.message) {
                 // One line instead of the full rules text — the CLI is stateless so it
                 // cannot diff versions across calls; --no-rules silences it entirely.
@@ -645,12 +693,24 @@ export async function executeCollaborationCommand(command, context, io) {
             return 0;
         }
         if (command.action === 'message') {
+            if (command.operation === 'list') {
+                const params = new URLSearchParams();
+                for (const key of ['group', 'thread', 'after-id', 'limit'])
+                    if (o[key])
+                        params.set(key, String(o[key]));
+                output(await request('GET', `/message?${params}`));
+                return 0;
+            }
             const route = `/message/${encodeURIComponent(command.target)}`;
             if (command.operation === 'confirm-shell') {
                 output(await request('POST', `${route}/${command.operation}`));
                 return 0;
             }
             receipt = await request('GET', `${route}?receipt_only=${Boolean(o['receipt-only'] || command.operation === 'watch')}&raw=${Boolean(o.raw)}`);
+            if (receipt.status === 'stored') {
+                output(receipt);
+                return 0;
+            }
             if (command.operation === 'get' && !o.follow && !o['wait-until'] && !o['expect-reply']) {
                 output(receipt);
                 return 0;
@@ -692,7 +752,7 @@ export async function executeCollaborationCommand(command, context, io) {
             // CLI receipts stay small even when the message is a large evidence package.
             delete receipt.messages;
             receipt.idempotency_key = idempotencyKey;
-            if (receipt.task_recorded) {
+            if (receipt.task_recorded || receipt.integration_recorded) {
                 output(receipt);
                 return 0;
             }

package/dist/server/agent/collaborationPrompt.js

@@ -89,7 +89,7 @@ export function formatCollaborationDelivery(input) {
         const sourceSession = message.fromSessionId ? sessionsById.get(message.fromSessionId) : null;
         const source = message.fromSessionId
             ? sanitizeCollaborationName(sourceSession?.name ?? message.fromSessionId)
-            : '用户';
+            : message.integrationOrigin ? `后台接入 ${sanitizeCollaborationName(message.integrationOrigin.integrationId, 80)}` : '用户';
         const token = tokens.get(message.id) ?? message.id;
         const bytes = Buffer.byteLength(message.content);
         // A remote recipient's CLI cannot detect its identity (the session is not
@@ -103,6 +103,8 @@ export function formatCollaborationDelivery(input) {
         const fannedNames = (message.fanOutIds ?? [])
             .map((sessionId) => sanitizeCollaborationName(sessionsById.get(sessionId)?.name ?? sessionId));
         blocks.push(formatCollaborationMessage({ ...message, content: body }, source, fannedNames, fence, token));
+        if (message.integrationOrigin)
+            blocks.push(`此消息来自后台程序，使用原消息 id 回复：td collab --session ${input.targetSessionId} reply ${token} "答复正文" --response-kind result --idempotency-key <稳定唯一key> --text\n需要时用 --response-kind ack|progress 明确回复收到或进展；result 提交结果。回复持久保存为 stored 并主动推送给后台，不创建看板任务，不代表用户验收。`);
     }
     // 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).

package/dist/server/agent/collaborationProtocol.js

@@ -143,4 +143,4 @@ export function extrasFromBody(body) {
         responseKind: body.response_kind, metadata: body.metadata,
         task: body.task, expiresAt: body.expires_at });
 }
-export const STATUS_RANK = { pending: 0, failed: 1, expired: 1, delivered: 2, read: 3 };
+export const STATUS_RANK = { pending: 0, failed: 1, expired: 1, delivered: 2, read: 3, stored: 4 };

package/dist/server/agent/collaborationRoutes.js

@@ -159,8 +159,9 @@ export function collaborationRoutes({ store, resolveSession, deliver, rebind, re
                 background_task_records: true, task_purpose_configuration: true, explicit_execution_state: true,
                 task_reply: 'Replies to task-linked user messages are stored in the task; status=stored is not a terminal delivery receipt' },
             routing: { background_recovery: true, explicit_rebind: Boolean(rebind), fixed_tmux_pane: true },
-            statuses: ['pending', 'delivered', 'failed', 'expired'], queued_status: 'pending',
+            statuses: ['pending', 'delivered', 'failed', 'expired', 'stored'], queued_status: 'pending',
             semantics: { delivered: 'written to terminal; no application acknowledgement implied',
+                stored: 'durable reply to a nonterminal integration principal; never a terminal write',
                 ack: 'explicit response_kind=ack', result: 'explicit response_kind=result; inspect task.status and evidence',
                 snapshot: 'terminal observation, never proof of reading or task completion',
                 timeout: 'stops waiting, does not cancel delivery',
@@ -208,6 +209,11 @@ export function collaborationRoutes({ store, resolveSession, deliver, rebind, re
     }));
     router.post('/reply', run(async (req, res, sessionId) => {
         const original = ownMessage(String(req.body.messageId ?? ''), sessionId, true);
+        if (original.integrationOrigin) {
+            const reply = store.storeIntegrationReply(original.id, sessionId, req.body.content, extrasFromBody(req.body));
+            res.json({ ok: true, ...store.receipt(reply.id), integration_recorded: true });
+            return;
+        }
         if (!original.fromSessionId) {
             const link = original.metadata?.termdockTask;
             if (link?.taskId && req.app.locals.collaborationTasks) {

package/dist/server/agent/collaborationStore.js

@@ -45,6 +45,8 @@ export class CollaborationStore {
     drawId;
     onMessageQueued;
     changeListeners = new Set();
+    runtimeGuards = new Set();
+    registerRuntimeGuard(guard) { this.runtimeGuards.add(guard); return () => { this.runtimeGuards.delete(guard); }; }
     subscribe(listener) { this.changeListeners.add(listener); return () => { this.changeListeners.delete(listener); }; }
     snapshotMessages() { return structuredClone(this.document.messages); }
     peerActivity = new Map();
@@ -318,16 +320,27 @@ export class CollaborationStore {
             throw new Error('消息类型无效');
         const extras = validateExtras(input);
         const content = input.content;
+        if (typeof content !== 'string')
+            throw new CollaborationError('INVALID_MESSAGE', 'Message content must be text');
         if (Buffer.byteLength(content) > COLLAB_LIMITS.message_bytes)
             throw new CollaborationError('MESSAGE_TOO_LARGE', `Message exceeds ${COLLAB_LIMITS.message_bytes} UTF-8 bytes`, 413);
         if (!content.trim())
             throw new Error('消息不能为空');
+        for (const id of input.toSessionIds)
+            for (const guard of this.runtimeGuards)
+                guard(id);
         const recipients = Array.from(new Set(input.toSessionIds)).filter((id) => group.sessionIds.includes(id) && id !== input.fromSessionId);
         if (recipients.length === 0)
             throw new Error('没有有效的接收会话');
         const now = Date.now();
-        const key = input.idempotencyKey ? JSON.stringify([input.groupId, input.fromSessionId, input.idempotencyKey]) : null;
-        const hash = crypto.createHash('sha256').update(stableJson([recipients.slice().sort(), input.kind, content, input.threadId ?? null, input.replyTo ?? null, extras.responseKind, extras.metadata, extras.task, extras.expiresAt])).digest('hex');
+        const key = input.idempotencyKey ? JSON.stringify([input.groupId, input.integrationOrigin ? `principal:${input.integrationOrigin.integrationId}` : input.fromSessionId, input.idempotencyKey]) : null;
+        const payload = [recipients.slice().sort(), input.kind, content, input.threadId ?? null, input.replyTo ?? null, extras.responseKind, extras.metadata, extras.task, extras.expiresAt];
+        if (input.integrationOrigin) {
+            if (input.fromSessionId !== null || group.federated || !/^[a-zA-Z0-9._-]{1,80}$/.test(input.integrationOrigin.integrationId))
+                throw new CollaborationError('INVALID_INTEGRATION_MESSAGE', 'Integration messages require an authenticated local nonterminal source');
+            payload.push(input.integrationOrigin);
+        }
+        const hash = crypto.createHash('sha256').update(stableJson(payload)).digest('hex');
         const previous = key ? this.document.idempotency?.[key] : null;
         if (previous && previous.expiresAt > now) {
             if (previous.hash !== hash)
@@ -340,6 +353,7 @@ export class CollaborationStore {
         const taken = this.takenIds();
         const threadId = input.threadId?.trim() || newCollaborationId(taken, this.drawId);
         const messages = recipients.map((toSessionId) => ({
+            ...(input.integrationOrigin ? { integrationOrigin: structuredClone(input.integrationOrigin) } : {}),
             idempotencyKey: input.idempotencyKey, responseKind: extras.responseKind, metadata: extras.metadata, task: extras.task, expiresAt: extras.expiresAt,
             sequence: this.nextSequence(),
             id: newCollaborationId(taken, this.drawId), groupId: group.id, fromSessionId: input.fromSessionId,
@@ -353,10 +367,51 @@ export class CollaborationStore {
         this.document.messages.push(...messages);
         if (key)
             (this.document.idempotency ??= {})[key] = { hash, ids: messages.map((message) => message.id), expiresAt: now + COLLAB_LIMITS.idempotency_retention_ms };
-        this.persist();
+        this.persist(!!input.integrationOrigin);
         queueMicrotask(() => this.onMessageQueued?.());
         return messages;
     }
+    /** An original recipient can persist a reply to a nonterminal integration.
+     * This is a stored fact, not a fake terminal write or a new task. */
+    storeIntegrationReply(originalId, sessionId, content, input) {
+        const original = this.getMessage(originalId), group = original && this.getGroup(original.groupId);
+        if (!original?.integrationOrigin || original.fromSessionId !== null || original.toSessionId !== sessionId
+            || !group || group.deleted || group.federated || !group.sessionIds.includes(sessionId))
+            throw new CollaborationError('NOT_MESSAGE_RECIPIENT', 'Only the original local recipient can reply to this integration message', 403);
+        const extras = validateExtras(input);
+        if (extras.task || extras.metadata?.termdockTask)
+            throw new CollaborationError('INVALID_INTEGRATION_REPLY', 'Ordinary integration replies cannot carry task envelopes');
+        if (!extras.idempotencyKey)
+            throw new CollaborationError('INVALID_IDEMPOTENCY_KEY', 'Integration replies require an idempotency key');
+        if (typeof content !== 'string' || !content.trim())
+            throw new CollaborationError('INVALID_MESSAGE', 'Reply content must not be empty');
+        if (Buffer.byteLength(content) > COLLAB_LIMITS.message_bytes)
+            throw new CollaborationError('MESSAGE_TOO_LARGE', 'Reply exceeds 1 MiB', 413);
+        if (extras.expiresAt !== undefined && extras.expiresAt !== null)
+            throw new CollaborationError('STORED_REPLY_CANNOT_EXPIRE', 'A persisted reply is not a pending delivery and cannot expire');
+        const principalId = original.integrationOrigin.integrationId;
+        const key = JSON.stringify([original.groupId, `integration-reply:${principalId}:${sessionId}`, extras.idempotencyKey]);
+        const hash = crypto.createHash('sha256').update(stableJson([original.id, content, extras.responseKind, extras.metadata, extras.task])).digest('hex');
+        const previous = this.document.idempotency?.[key];
+        if (previous && previous.expiresAt > Date.now()) {
+            if (previous.hash !== hash)
+                throw new CollaborationError('IDEMPOTENCY_CONFLICT', 'Reply key was already used with different content', 409);
+            const reply = this.getMessage(previous.ids[0]);
+            if (!reply)
+                throw new CollaborationError('IDEMPOTENCY_RECORD_GONE', 'Original reply is no longer retained', 409);
+            return reply;
+        }
+        const now = Date.now();
+        const reply = { ...extras, id: newCollaborationId(this.takenIds(), this.drawId), sequence: this.nextSequence(),
+            groupId: original.groupId, fromSessionId: sessionId, toSessionId: `principal:${principalId}`, toPrincipalId: principalId,
+            kind: 'reply', content, threadId: original.threadId, replyTo: original.id, status: 'stored', createdAt: now, storedAt: now, deliveredAt: null, readAt: null };
+        if (Buffer.byteLength(JSON.stringify(reply)) > COLLAB_LIMITS.wire_bytes)
+            throw new CollaborationError('MESSAGE_WIRE_TOO_LARGE', 'Encoded reply exceeds the wire limit', 413);
+        this.document.messages.push(reply);
+        (this.document.idempotency ??= {})[key] = { hash, ids: [reply.id], expiresAt: now + COLLAB_LIMITS.idempotency_retention_ms };
+        this.persist(true);
+        return reply;
+    }
     listMessages(groupId, limit = 200) {
         return this.document.messages.filter((message) => message.groupId === groupId).slice(-Math.max(1, Math.min(limit, 500)));
     }
@@ -414,7 +469,7 @@ export class CollaborationStore {
         const now = Date.now();
         const changed = [];
         this.document.messages = this.document.messages.map((message) => {
-            if (!ids.has(message.id) || message.status === 'expired' || message.status === 'failed' || message.status === 'read')
+            if (!ids.has(message.id) || message.status === 'stored' || message.status === 'expired' || message.status === 'failed' || message.status === 'read')
                 return message;
             const updated = status === 'read'
                 ? { ...message, status, deliveredAt: message.deliveredAt ?? now, readAt: now, readSource, deliverySource: message.deliverySource ?? (message.deliveredAt === null ? 'consumer_read' : 'legacy_or_unspecified') }
@@ -499,7 +554,7 @@ export class CollaborationStore {
             if (!message || typeof message !== 'object')
                 continue;
             const group = this.getGroup(message.groupId);
-            if (!group?.federated || group.deleted || !group.sessionIds.includes(message.toSessionId)
+            if (!group?.federated || group.deleted || message.status === 'stored' || message.integrationOrigin || message.toPrincipalId || !group.sessionIds.includes(message.toSessionId)
                 || (message.fromSessionId !== null && !group.sessionIds.includes(message.fromSessionId))
                 || typeof message.id !== 'string' || typeof message.threadId !== 'string' || !Number.isFinite(message.createdAt)
                 || typeof message.content !== 'string'
@@ -581,15 +636,18 @@ export class CollaborationStore {
         const message = this.getMessage(id);
         if (!message)
             throw new CollaborationError('MESSAGE_NOT_FOUND', 'Message not found or no longer retained', 404);
-        const replies = this.document.messages.filter((reply) => reply.replyTo === id && reply.fromSessionId === message.toSessionId && reply.toSessionId === message.fromSessionId);
+        const replies = this.document.messages.filter(reply => reply.replyTo === id
+            && (message.toPrincipalId ? reply.integrationOrigin?.integrationId === message.toPrincipalId : reply.fromSessionId === message.toSessionId)
+            && (message.integrationOrigin ? reply.toPrincipalId === message.integrationOrigin.integrationId : reply.toSessionId === message.fromSessionId));
         const diagnostic = this.diagnostic(id);
         const facts = terminalMessage(message, raw);
-        return { message_id: id, thread_id: message.threadId, status: facts.status, queued_at: message.createdAt,
+        return { message_id: id, thread_id: message.threadId, status: facts.status, queued_at: message.status === 'stored' ? null : message.createdAt, stored_at: message.storedAt ?? null,
+            from_principal_id: message.integrationOrigin?.integrationId ?? null, to_principal_id: message.toPrincipalId ?? null,
             delivered_at: facts.deliveredAt, expires_at: message.expiresAt ?? null,
-            failure_reason: message.failureReason ?? null, delivery_semantics: facts.deliverySource ?? (facts.deliveredAt === null ? 'not_delivered' : 'legacy_or_unspecified'),
+            failure_reason: message.failureReason ?? null, delivery_semantics: message.status === 'stored' ? 'durable_storage' : facts.deliverySource ?? (facts.deliveredAt === null ? 'not_delivered' : 'legacy_or_unspecified'),
             snapshot: message.snapshot ? (raw ? message.snapshot : plainCollaborationSnapshot(message.snapshot)) : null,
             delivery: { status: facts.status,
-                stage: facts.deliveredAt !== null ? 'terminal_written' : diagnostic?.remote_received_at ? 'remote_received' : 'queued',
+                stage: message.status === 'stored' ? 'stored' : facts.deliveredAt !== null ? 'terminal_written' : diagnostic?.remote_received_at ? 'remote_received' : 'queued',
                 remote_received_at: diagnostic?.remote_received_at ?? null, delivered_at: facts.deliveredAt, error: message.failureReason ?? diagnostic?.last_error ?? null },
             reply: { status: replies.length ? 'received' : 'pending', ack_at: replies.find(reply => reply.responseKind === 'ack')?.createdAt ?? null, reply_ids: replies.map(reply => reply.id) },
             idempotency_key: message.idempotencyKey ?? null,
@@ -725,7 +783,7 @@ export class CollaborationStore {
         this.persist();
         return { message_id: fragment.message_id, received, total: state.total, complete: received === state.total };
     }
-    persist() {
+    persist(durable = false) {
         const now = Date.now();
         for (const [key, record] of Object.entries(this.document.idempotency ?? {}))
             if (record.expiresAt <= now)
@@ -744,9 +802,26 @@ export class CollaborationStore {
         try {
             fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
             const serialized = JSON.stringify(this.document);
-            fs.writeFileSync(temporaryPath, serialized, { mode: 0o600 });
+            const descriptor = fs.openSync(temporaryPath, 'w', 0o600);
+            try {
+                fs.writeFileSync(descriptor, serialized);
+                if (durable)
+                    fs.fsyncSync(descriptor);
+            }
+            finally {
+                fs.closeSync(descriptor);
+            }
             fs.renameSync(temporaryPath, this.filePath);
             this.persistedDocument = serialized;
+            if (durable) {
+                const directory = fs.openSync(path.dirname(this.filePath), 'r');
+                try {
+                    fs.fsyncSync(directory);
+                }
+                finally {
+                    fs.closeSync(directory);
+                }
+            }
             for (const listener of this.changeListeners) {
                 try {
                     listener();

package/dist/server/agent/collaborationTaskService.js

@@ -268,6 +268,8 @@ export class CollaborationTaskService {
     }
     receipt(messageId) {
         const receipt = this.messages.receipt(messageId);
+        if (receipt.status === 'stored')
+            throw new CollaborationError('INVALID_TASK_DELIVERY', 'A nonterminal reply cannot be a task delivery');
         return { messageId, status: receipt.status, deliveredAt: receipt.delivered_at, error: receipt.delivery.error };
     }
     start() { this.timer = setInterval(() => void this.flush(), 1500); this.timer.unref(); void this.flush(); }

package/dist/server/agent/integrationCli.js

@@ -4,16 +4,28 @@ import http from 'node:http';
 import { INTEGRATION_PROTOCOL } from './integrationStore.js';
 import { integrationSocketPath } from './integrationServer.js';
 import { CollaborationError } from './collaborationProtocol.js';
-import { executeCollaborationCommand, duration } from './collaborationCli.js';
+import { COLLAB_HELP, executeCollaborationCommand, duration } from './collaborationCli.js';
 import { getTermdockVersion } from '../utils/version.js';
 export const INTEGRATION_HELP = `td integration — local scoped integration administration
   groups | list
+  resume-configuration <TD-session-id> (read current/recorded fingerprints; no mutation)
+  confirm-resume <TD-session-id> --generation <N> --fingerprint <sha256>
+    Administrator explicitly authorizes the current launcher/plugin recovery semantics.
+    This never proves unknown historical file contents or modifies Agent configuration.
+    Old records need this confirmation before release; new records capture a fingerprint.
+    Later changes fail closed. Grant session.release separately for runtime reclamation.
+    Minimum CLI/running service 1.4.309; capabilities.session_resume_configuration=true.
+    Errors: RESUME_CONFIGURATION_CHANGED, EXACT_RESUME_UNSUPPORTED,
+    SESSION_GENERATION_MISMATCH, SESSION_OPERATION_IN_PROGRESS, LAUNCHER_UNAVAILABLE.
   diagnostics <TD-session-id> (read the last restore check; administrator only)
   create --file <policy.json> --credential-file <private-output.json>
   update --file <policy.json> (same identity/group; preserves the credential)
   revoke <principal-id>
 Credentials are saved as a private file and never printed. Workers set
 TERMDOCK_INTEGRATION_CREDENTIAL_FILE, then use td collab --principal <id> …
+Ordinary messages: permissions message.send, message.read, events.read;
+td collab --principal <id> --help lists send/reply/history and event examples.
+No task or user acceptance is required for a message-driven integration.
 Only the local administrator can provision/revoke grants. See docs/integrations.md.`;
 export function readIntegrationCredential(file, principalId) {
     const info = fs.lstatSync(file);
@@ -55,11 +67,35 @@ export async function runIntegrationAdmin(argv, port, adminToken, write) {
     let reserved;
     try {
         const action = argv[0] ?? 'help', options = {};
-        if (action === 'help' || action === '--help') {
+        if (action === 'help' || argv.includes('--help')) {
             write(INTEGRATION_HELP);
             return 0;
         }
         const socketPath = integrationSocketPath(port);
+        if (action === 'resume-configuration' || action === 'confirm-resume') {
+            const id = argv[1];
+            if (!id || !/^[a-zA-Z0-9._-]{1,80}$/.test(id))
+                throw new Error('A full TD session id is required');
+            const capabilities = parsed(await request(socketPath, 'GET', '/admin/capabilities', undefined, headers(undefined, adminToken)));
+            if (capabilities.session_resume_configuration !== true)
+                throw new CollaborationError('SESSION_RELEASE_UNSUPPORTED', 'CLI and running service must be at least 1.4.309', 409);
+            let body;
+            if (action === 'confirm-resume') {
+                const args = {};
+                for (let i = 2; i < argv.length; i += 2) {
+                    if (!['--generation', '--fingerprint'].includes(argv[i]) || !argv[i + 1] || args[argv[i]])
+                        throw new Error('confirm-resume requires --generation and --fingerprint');
+                    args[argv[i]] = argv[i + 1];
+                }
+                if (!/^[1-9][0-9]*$/.test(args['--generation'] ?? '') || !Number.isSafeInteger(Number(args['--generation'])) || !/^[a-f0-9]{64}$/.test(args['--fingerprint'] ?? ''))
+                    throw new Error('Invalid generation or fingerprint');
+                body = { generation: Number(args['--generation']), fingerprint: args['--fingerprint'] };
+            }
+            else if (argv.length !== 2)
+                throw new Error('resume-configuration requires one TD session id');
+            write(JSON.stringify(parsed(await request(socketPath, body ? 'POST' : 'GET', `/admin/sessions/${encodeURIComponent(id)}/resume-configuration`, body, headers(undefined, adminToken)))));
+            return 0;
+        }
         if (action === 'diagnostics') {
             if (argv.length !== 2 || !/^[a-zA-Z0-9._-]{1,80}$/.test(argv[1]))
                 throw new Error('diagnostics requires one TD session id');
@@ -131,6 +167,10 @@ export async function revokeIntegration(id, port, adminToken, write) {
 }
 export async function runIntegrationCollab(command, port, io) {
     try {
+        if (command.action === 'help') {
+            io.write(COLLAB_HELP);
+            return 0;
+        }
         const principalId = String(command.options.principal), file = process.env.TERMDOCK_INTEGRATION_CREDENTIAL_FILE;
         if (!file)
             throw new CollaborationError('INTEGRATION_CREDENTIAL_REQUIRED', 'Set TERMDOCK_INTEGRATION_CREDENTIAL_FILE to a private credential file', 401);
@@ -154,14 +194,20 @@ export async function runIntegrationCollab(command, port, io) {
             return subscribe(socketPath, `/events?${params}`, credential, command.options.timeout ? duration(String(command.options.timeout)) : undefined, io.write);
         }
         if (command.action === 'session') {
-            const route = command.operation === 'create' ? '/sessions' : `/sessions/${encodeURIComponent(command.target)}${command.operation === 'restore' ? '/restore' : ''}`;
+            if (command.operation === 'release' && (capability.session_runtime_release !== true || capability.session_lifecycle_generation !== true || capability.stable_session_identity !== true))
+                throw new CollaborationError('SESSION_RELEASE_UNSUPPORTED', 'CLI and running service must support the lifecycle contract (minimum 1.4.309)', 409);
+            const route = command.operation === 'create' ? '/sessions' : `/sessions/${encodeURIComponent(command.target)}${['restore', 'release'].includes(command.operation) ? `/${command.operation}` : ''}`;
             const body = command.operation === 'create' ? { group_id: command.options.group, launch_profile: command.options['launch-profile'], cwd: command.options.cwd, idempotency_key: command.options['idempotency-key'] }
-                : command.operation === 'restore' ? { idempotency_key: command.options['idempotency-key'] } : undefined;
+                : ['restore', 'release'].includes(command.operation) ? { ...(command.operation === 'release' ? { generation: Number(command.options.generation) } : {}), idempotency_key: command.options['idempotency-key'] } : undefined;
             io.write(JSON.stringify(parsed(await request(socketPath, command.operation === 'get' ? 'GET' : 'POST', route, body, headers(credential)))));
             return 0;
         }
-        if (!['task', 'message', 'help'].includes(command.action) || command.action === 'message' && command.operation !== 'get')
-            throw new CollaborationError('INTEGRATION_OPERATION_DENIED', 'Command is not exposed to integration identities', 403);
+        const messageCapability = command.action === 'send' ? 'integration_message_send' : command.action === 'reply' ? 'integration_message_reply'
+            : command.action === 'message' && command.operation === 'list' ? 'integration_message_history' : null;
+        if (messageCapability && capability[messageCapability] !== true)
+            throw new CollaborationError('INTEGRATION_MESSAGING_UNSUPPORTED', 'CLI and running service must support integration messaging (minimum 1.4.308); upgrade both and read capabilities', 409);
+        if (!['task', 'message', 'send', 'reply'].includes(command.action) || command.action === 'message' && !['get', 'list'].includes(command.operation))
+            throw new CollaborationError('INTEGRATION_OPERATION_DENIED', 'Command is not exposed to integration identities; see td collab --principal <id> --help', 403);
         return executeCollaborationCommand(command, {}, { ...io, request: async (method, endpoint, body, timeout) => {
                 const origin = { source: command.options.source, externalActor: command.options['external-actor'] ? JSON.parse(String(command.options['external-actor'])) : undefined,
                     externalMessageId: command.options['external-message-id'], metadata: command.options.metadata ? JSON.parse(String(command.options.metadata)) : undefined };