termdock 1.4.307 → 1.4.309

package/dist/server/agent/sessionResumeConfiguration.js

@@ -0,0 +1,32 @@
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+import { CollaborationError } from './collaborationProtocol.js';
+const fail = (code, message) => { throw new CollaborationError(code, message, 409); };
+/** Fingerprint only the launcher file and recovery semantics. This does not
+ * claim to fingerprint its dependencies, private Agent binaries, or history. */
+export async function resumeConfigurationFingerprint(record, adapter) {
+    const semantics = await adapter.resumeConfiguration?.(record);
+    if (semantics === undefined)
+        fail('EXACT_RESUME_UNSUPPORTED', 'Adapter does not expose exact recovery semantics');
+    try {
+        const executable = fs.realpathSync(record.profile.executable);
+        const before = fs.statSync(executable);
+        if (!before.isFile() || before.size > 512 * 1024 * 1024)
+            fail('LAUNCHER_UNAVAILABLE', 'Launcher must be a regular file within the fingerprint size limit');
+        fs.accessSync(executable, fs.constants.X_OK);
+        const hash = createHash('sha256');
+        for await (const chunk of fs.createReadStream(executable))
+            hash.update(chunk);
+        const after = fs.statSync(executable);
+        if (before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs
+            || fs.realpathSync(record.profile.executable) !== executable)
+            fail('RESUME_CONFIGURATION_CHANGED', 'Launcher changed while fingerprinting');
+        return createHash('sha256').update(JSON.stringify({ version: 1, executable, content: hash.digest('hex'),
+            agent: record.agent_slug, argv: record.profile.argv, resumeArgv: record.profile.resumeArgv, cwd: record.cwd, semantics })).digest('hex');
+    }
+    catch (error) {
+        if (error instanceof CollaborationError)
+            throw error;
+        return fail('LAUNCHER_UNAVAILABLE', 'Recovery launcher could not be read and verified');
+    }
+}

package/dist/server/cli.js

@@ -3489,7 +3489,7 @@ async function main() {
     }
     if (options.integration) {
         const argv = options.integration;
-        if (!argv.length || ['help', '--help'].includes(argv[0])) {
+        if (!argv.length || argv.includes('--help') || argv[0] === 'help') {
             console.log(INTEGRATION_HELP);
             return;
         }

package/dist/server/routes/terminal.js

@@ -2,6 +2,8 @@ import { collaborationSessionDisplayName } from '../utils/sessionDisplayName.js'
 import { integrationError } from '../agent/integrationStore.js';
 import { assertNativeResumeAvailable, collectNativeResumeOwnerCandidates } from '../agent/nativeResumeOwner.js';
 import { readNativeProcessIdentity } from '../agent/nativeProcessIdentity.js';
+import { releaseSessionRuntime } from '../agent/sessionLifecycle.js';
+import { resumeConfigurationFingerprint } from '../agent/sessionResumeConfiguration.js';
 import { integrationLaunchCommand } from '../agent/integrationSessions.js';
 import { ensureTeam } from '../agent/collaborationTeam.js';
 import { androidRecordings } from '../android/recording.js';
@@ -39,7 +41,7 @@ import { inspectLinuxInotifyUsage, isWatchResourceExhaustion } from '../utils/fi
 import { writeResponseChunk } from '../utils/httpResponse.js';
 import { getFocusSequence, removeClientFocusState, scanFocusTrackingMode, setClientFocusState, } from '../utils/tmuxFocus.js';
 import { extractProgramLabelFromArgs, normalizeProgramName, normalizeTmuxMetadataProgram, selectTmuxForegroundProgram, } from '../utils/tmuxProgramDetection.js';
-import { agentBySlug, buildResumeCommand, detectAgentFromCommand, inferResumeSessionId, getPluginNativeIdentityConfig, listAgents, } from '../agent/registry.js';
+import { agentBySlug, buildResumeCommand, detectAgentFromCommand, inferResumeSessionId, getPluginNativeIdentityConfig, getPluginResumeConfig, listAgents, } from '../agent/registry.js';
 import { applyAgentEvent, agentEventMatchesCurrentAgent, defaultAgentSessionState, parseAgentEvent, } from '../agent/session.js';
 import { canRestoreDeadAgentShell, isConfirmedAgentResumeProcess, normalizePersistedAgentResumeInfo, } from '../agent/resumePersistence.js';
 import { AgentResumeHistoryStore } from '../agent/resumeHistory.js';
@@ -1861,10 +1863,76 @@ function integrationTerminalRecord(record) {
         integrationError('SESSION_IDENTITY_MISMATCH', 'Owned TD terminal binding changed', 409);
     return terminal;
 }
+async function integrationTmuxPresent(record) {
+    try {
+        await runTmux(['has-session', '-t', `=wt-integration-${record.session_id}`]);
+        return true;
+    }
+    catch (error) {
+        if (/can't find session|no server running|no sessions|error connecting.*No such file/i.test(getErrorMessage(error)))
+            return false;
+        throw error;
+    }
+}
 export const integrationSessionAdapter = {
     subscribe(listener) { integrationSessionObservers.add(listener); return () => { integrationSessionObservers.delete(listener); }; },
     registerDeliveryGuard(guard) { integrationDeliveryGuard = guard; return () => { if (integrationDeliveryGuard === guard)
         integrationDeliveryGuard = undefined; }; },
+    pendingMessages(id) { return collaborationStore.pendingCount(id); },
+    async prepareRelease(record) {
+        if (collaborationStore.groupsForSession(record.session_id).some(group => group.id !== record.group_id))
+            integrationError('SESSION_SCOPE_CONFLICT', 'Runtime belongs to another collaboration group; administrator must resolve its membership first', 409);
+        return { group_role: collaborationStore.getGroup(record.group_id)?.roles?.[record.session_id] };
+    },
+    async resumeConfiguration(record) {
+        await listDetectedAgentLaunchers();
+        const agent = agentBySlug(record.agent_slug);
+        const command = agent && buildResumeCommand(agent, 'td-fingerprint-native-id', null);
+        if (!agent || !command)
+            integrationError('EXACT_RESUME_UNSUPPORTED', 'Agent must support exact native recovery', 409);
+        return { version: 1, slug: agent.slug, aliases: agent.aliases, capabilities: agent.capabilities ?? [],
+            resume: getPluginResumeConfig(agent.slug) ?? command, nativeIdentity: getPluginNativeIdentityConfig(agent.slug) ?? null };
+    },
+    async runtimePresent(record) {
+        if (integrationTerminalRecord(record))
+            return true;
+        if ([...terminalSessions.values()].some(s => s.mode === 'tmux' && s.tmuxSessionName === `wt-integration-${record.session_id}`))
+            return true;
+        if (collaborationStore.getGroup(record.group_id)?.sessionIds.includes(record.session_id))
+            return true;
+        return integrationTmuxPresent(record);
+    },
+    async release(record, reconcile) {
+        await releaseSessionRuntime({
+            barrier: action => collaborationDeliveryWorker.reconfigure(record.session_id, action),
+            exists: () => integrationTmuxPresent(record),
+            pendingMessages: () => collaborationStore.pendingCount(record.session_id),
+            async verifyOwnership() {
+                await integrationSessionAdapter.prepareRelease(record);
+                const terminal = integrationTerminalRecord(record);
+                if (!terminal || !record.terminal_binding)
+                    integrationError('SESSION_IDENTITY_MISMATCH', 'Live runtime lacks its exact persisted binding', 409);
+                if (globalSessionState.sessions.some(other => other.sessionId !== record.session_id && (other.tmuxSessionName === terminal.tmuxSessionName
+                    || terminal.backendSessionId && other.backendSessionId === terminal.backendSessionId)))
+                    integrationError('SESSION_IDENTITY_MISMATCH', 'Runtime has another logical owner', 409);
+            },
+            inspect: () => integrationSessionAdapter.inspect(record),
+            destroy: async () => { await destroyTmuxSessionSafely(`wt-integration-${record.session_id}`); },
+            async forgetRuntime() {
+                // Only remove exact owned PTY/inventory records after actual tmux absence.
+                integrationTerminalRecord(record);
+                await integrationSessionAdapter.prepareRelease(record);
+                for (const [id, backend] of terminalSessions)
+                    if (backend.mode === 'tmux' && backend.tmuxSessionName === `wt-integration-${record.session_id}`)
+                        cleanupSession(id, { killProcess: true });
+                removeGlobalSessionRecord(record.session_id);
+                collaborationStore.archiveSession(record.session_id);
+                collaborationRouting.remove(record.session_id);
+                await persistGlobalStateNow();
+                broadcastClientState();
+            },
+        }, reconcile);
+    },
     async capture(record) {
         const observed = await integrationSessionAdapter.inspect(record);
         if (!observed.exists || !observed.running || observed.agentSlug !== record.agent_slug || !record.terminal_binding
@@ -2011,12 +2079,18 @@ async function launchIntegrationTerminal(record, restoring, prepared) {
         if (!latest || latest.deleted)
             integrationError('TASK_GROUP_NOT_FOUND', 'Integration group changed', 409);
         collaborationStore.save({ id: latest.id, name: latest.name, sessionIds: [...new Set([...latest.sessionIds, record.session_id])] });
+        if (restoring && record.group_role)
+            collaborationStore.setRole({ groupId: latest.id, sessionId: record.session_id, role: record.group_role });
         if (restoring)
             upsertGlobalSessionRecord({ ...terminal, agentResume: { slug: record.agent_slug, sessionId: record.agent_native_session_id,
                     launchArgv: [record.profile.executable, ...record.profile.argv], updatedAt: Date.now() } });
         await persistGlobalStateNow();
         // Recheck the actual pinned shell immediately before writing. This cannot
         // use an active-pane target which might have changed during preparation.
+        if (record.resume_configuration_fingerprint && record.resume_configuration_fingerprint !== await resumeConfigurationFingerprint(record, integrationSessionAdapter))
+            integrationError('RESUME_CONFIGURATION_CHANGED', 'Recovery configuration changed before terminal input', 409);
+        if (restoring)
+            await assertIntegrationNativeResumeAvailable(record);
         const shell = await inspectCollaborationTmux({ sessionId: record.session_id, backendSessionId: opened.terminalSession.sessionId,
             mode: 'tmux', tmuxSessionName: terminal.tmuxSessionName, agentSlug: null, nativeSessionId: null, pane: pinned });
         if (shell.state !== 'ready' || !shell.pane || !await integrationPaneIsIdleShell(shell.pane))

package/docs/integrations.md

@@ -8,7 +8,9 @@
 **实际运行服务至少 1.4.304**。管理员恢复诊断要求 **CLI / 实际服务均至少 1.4.305**；
 直接 exec 为 pane PID 的原生 argv 核验及可选 Linux 持锁身份要求 **实际服务至少 1.4.306**；
 后台执行记录与用途迁移要求 **CLI / 实际服务均至少 1.4.307**；
-建议 CLI 与服务同步安装 1.4.307（既有接入命令的 CLI 最低仍为 1.4.301，诊断 CLI 最低为 1.4.305）。
+普通消息身份发送、持久回复及消息历史要求 **CLI / 实际服务均至少 1.4.308**；
+释放运行承载、稳定逻辑身份与恢复配置确认要求 **CLI / 实际服务均至少 1.4.309**；
+建议 CLI 与服务同步安装 1.4.309（既有接入命令的 CLI 最低仍为 1.4.301，诊断 CLI 最低为 1.4.305）。
 现有 `--session`、消息投递、任务报告与自动协作入口继续兼容；旧的
 `task create --integration` 仍表示代码集成子任务，新身份使用 `--principal`。
 
@@ -17,6 +19,90 @@ TD 提供受限身份、持久事件推送、关联咨询回复，以及会话
 `complete` 是执行成员的明确交付，`accepted` 是用户明确验收；投递成功、终端快照、
 事件 ACK 都不表示已读、任务完成或业务校验通过。
 
+## 普通消息接入（1.4.308，推荐用于机器人与报表）
+
+触发 Agent、追问和回帖可使用普通消息：**无需创建 task，不产生任务看板或逐期用户验收**。
+消息负责可靠投递与关联回复；业务周期、结果版本、机器校验、外部发布状态由接入方记录。
+只有需要 TD 任务分派、交付物、评审或人工验收时才使用后文 task；1.4.307 的 automation
+purpose 是可选任务能力，不是机器人接入的前置要求。已有 task/attempt/session 和外部根帖
+保持原记录，不自动迁移、重建、重投或重跑。
+
+管理员为现有身份补权限后用 `td integration update --file /private/policy.json`：
+
+```json
+"permissions": ["message.send", "message.read", "events.read", "session.create", "session.read", "session.restore"]
+```
+
+更新保留同一身份、组和凭据；保留实际需要的既有 task 权限以及原 launchProfiles。
+`message.send` 授权 send/reply，`message.read` 授权组内 message get/list；它们不授予任务操作
+或用户验收。events.read 可订阅授权组内事件。只允许该身份授权的一个本机组，拒绝跨服务目标、
+组外成员、未授权操作与 task envelope。组中其他 principal 的消息可以按组授权读取，但不能
+借其原消息 reply 或冒充其身份；只能向本组成员 send 新消息。
+
+先回读实际运行服务，再检查三个能力均为 true：
+
+```sh
+export TERMDOCK_INTEGRATION_CREDENTIAL_FILE=/private/bridge-credential.json
+td collab --principal report-bridge capabilities
+# cli_version / server_version >= 1.4.308, integration_protocol = 1
+# integration_message_send / integration_message_reply / integration_message_history = true
+
+td collab --principal report-bridge send <TD成员ID> --file /private/prompt.txt --idempotency-key run:2026-10-10
+# 保存输出 message_id、thread_id；status=pending 表示已持久入队
+# 可附 --source feishu --external-actor '{"id":"external-user"}' --external-message-id <external-id>
+
+td collab --principal report-bridge events subscribe --consumer bridge-inbox --jsonl
+# 按 event_id 去重；先将事件落盘，再 ACK 已连续持久接收的位置
+td collab --principal report-bridge events ack <cursor> --consumer bridge-inbox
+```
+
+CLI 在发送前检查运行服务 capability；旧服务返回 `INTEGRATION_MESSAGING_UNSUPPORTED`，
+不会降级成用户或终端成员发送。凭据只通过私有文件注入；`--principal <id> --help` 不需要
+凭据或运行服务。建议 CLI 与实际服务保持同一版本，版本号本身不能替代能力检测。
+
+接收 Agent 在**原终端**使用明确回复（投递提示每次都附原消息 ID 与此用法）：
+
+```sh
+td collab --session <自己的TD成员ID> reply <原消息ID> "收到" --response-kind ack --idempotency-key run:ack
+td collab --session <自己的TD成员ID> reply <原消息ID> --file /private/result.txt --response-kind result --idempotency-key run:result
+# 进展也可 --response-kind progress；不推断 Agent 内部进度或整个会话忙闲
+```
+
+回复保存到同一消息历史，`status=stored`、`stored_at`、`delivery.stage=stored`、
+`delivery_semantics=durable_storage`、`delivered_at=null`、`attempt_count=0`；
+不进终端投递队列，不伪造“写入终端”。原 message get/list 记录的 toSessionId 使用内部保留
+地址 principal:<id> 以兼容历史结构，实际接收方由 toPrincipalId 标识；不要把这个地址当作成员 ID。Agent CLI 立即返回这个保存事实，不等待不存在的接收终端。
+原发送的 receipt.result_ids/reply_ids/ack_at 来自明确的关联回复，原消息投递状态独立保留。
+原生会话、结果正文及外部校验仍由实际 Agent/业务方负责；result 不表示用户验收或外部发布成功。
+
+`message.reply` 的 payload 包含 `message_id`、`thread_id`、`reply_to`（原消息 ID）、
+`from_session_id`、`to_session_id`（后台回复为 null）、`to_principal_id`、
+`integration_origin`、`response_kind`、`stored_at`、`content`、`metadata`。
+普通消息没有 task_id/attempt_id；不要套用 task 的 to-event/respond。外部话题和结果版本
+用 message_id/thread_id 与 reply_to 关联。外部追问可以回复自己的原发送或收到的 Agent 回复：
+
+```sh
+td collab --principal report-bridge reply <原发送ID或Agent回复ID> "解释一下" --idempotency-key followup:external-id
+td collab --principal report-bridge message get <消息ID> --text
+td collab --principal report-bridge message list --thread <话题ID> --limit 50
+td collab --principal report-bridge message list --thread <话题ID> --after-id <上一页next_after_id> --limit 50
+```
+
+追问固定回原成员及原 thread，原成员不在授权组时返回 NO_REPLY_TARGET，不悄悄新建会话。
+需要恢复时显式 session restore，仍保留原 native UUID、argv/cwd/包装器与 startupInput 条件。
+命令变更必须给稳定 idempotency-key；同身份/组/key 且相同正文与参数返回同一消息 ID，
+不同 payload 返回 IDEMPOTENCY_CONFLICT。原 Agent 回复另按 principal/成员/key 隔离。
+
+消息/回复在成功返回前完成文件 fsync、原子替换和目录 fsync，事件从这些源记录持久生成。
+订阅自动断线重连，从同 consumer 已 ACK 的连续位置重放；收到事件不自动 ACK，也不表示业务
+已经处理。业务 inbox/outbox 按自身持久处理状态重试。事件保留缺口返回 EVENT_RETENTION_GAP
+并停止；需结合仍保留的消息与业务数据库对账后建立新 consumer，不能声称任意历史均可重放。
+message list 按本组 sequence 升序分页，返回 next_after_id/has_more，页还受 2 MiB 字节预算限制；
+只覆盖仍保留的消息（常规历史最多保留 2000 条，pending 和未过期幂等记录另外保护，幂等保留 7 天）。
+after-id 不在本组保留记录中返回 MESSAGE_NOT_FOUND；前缀不唯一返回 MESSAGE_ID_AMBIGUOUS。
+鉴权撤销与权限更新沿用下文错误和重连契约。普通消息 delivered 仍只表示写入终端，不能从快照
+缺少正文推断未消费，更不能因此自动重投已 delivered 消息。
+
 ## 管理员配置身份
 
 接口只监听本机 Unix socket `~/.termdock/integration-<port>.sock`（0600），
@@ -49,7 +135,7 @@ td integration list
 }
 ```
 
-`launchProfiles` 可为空（只操作已有任务）。创建会话时只能选择预配 profile 和
+`launchProfiles` 可为空（只操作已有消息或任务）。创建会话时只能选择预配 profile 和
 目录，不能传任意命令/参数。`cwd` 必须已存在，真实路径须位于 `cwdRoots` 内；
 符号链接不能逃出目录边界。参数按独立 token 引号转义，控制字符禁止。
 `{cwd}`、`{sessionId}`、`{launchArgs}` 必须是独立参数；恢复模板必须各包含一次
@@ -302,9 +388,9 @@ task 事件 `event_id` 与任务内事件 ID 一致，`respond.reply_to_event_id
 | `task.close/reopen/coordinate/pause/resume/retry/child-update/automation-blocked/review-passed/review-blocked` | `{event}`：保留服务事件的 source 与原文 |
 | `task.result` | `{artifact}`：结果 id、attemptId、actor、content、summary、evidence、createdAt |
 | `task.delivery` | `{delivery}`：任务投递 id、attemptId、messageId、status、deliveredAt、error |
-| `message.queued/message.reply` | `{message_id,thread_id,reply_to,from_session_id,to_session_id,content,metadata}` |
-| `message.delivery` | `{receipt}`：实际入队/远端接收/终端写入阶段、失败、重试计数与时间，及明确回复 ID；不含快照或已读字段 |
-| `session.starting/binding_pending/ready/restoring/failed` | `{session}`：下节公开会话记录，失败包含 error_code |
+| `message.queued/message.reply` | `{message_id,thread_id,reply_to,from_session_id,to_session_id,to_principal_id,integration_origin,response_kind,stored_at,content,metadata}` |
+| `message.delivery` | `{receipt}`：实际入队/远端接收/终端写入/后台回复保存阶段、失败、重试计数与时间，及明确回复 ID；不含快照或已读字段 |
+| `session.starting/binding_pending/ready/restoring/releasing/released/failed` | `{session}`：下节公开会话记录，失败包含 error_code |
 
 TD 在源记录提交后触发 journal 及订阅，journal 中的同一事件 ID 在重连重放时保持不变。
 新 consumer 从最早保留事件开始；接入方按 `event_id` 去重，**先持久写入 inbox，
@@ -353,7 +439,9 @@ agent_native_session_id,state,error_code,cwd,launch_profile,created_at,updated_a
 | binding_pending | 实际观察到该 Agent，尚未捕获确切原生 ID |
 | ready | 实际观察到该 Agent 和确切原生 ID；不表示任务空闲/完成 |
 | restoring | 显式恢复意图持久化，等待原 ID 的运行证据 |
-| failed | 启动、绑定、身份核验或运行观察失败，详见 error_code |
+| releasing | 释放意图已落盘；不能接收新投递，尚未证明实际承载回收 |
+| released | 实际进程/PTY/tmux/活动终端登记与本组活动成员已移除；恢复描述保留 |
+| failed | 启动、绑定、身份核验、释放或运行观察失败，详见 error_code |
 
 同键同请求返回原 TD ID；已记录但结果不明的启动不会自动重新执行。通常等
 session 事件；get 也会现场核验。120 秒内未形成绑定返回 `SESSION_BINDING_TIMEOUT`。
@@ -441,6 +529,133 @@ PID、同 ID 拒绝/不同 ID 排除、遗留 owner、错误 start_id/PID、inod
 持锁、多个 ID 和 argv 冲突。**私有 TraeX 的 1.4.306 身份接入仍需使用方实机复验**。
 原 `startupInput` 仍独立控制首次写入；核验 native ID 不表示输入初始化完成。
 
+### 会话身份与运行承载的生命周期（1.4.309）
+
+这项能力把稳定的会话记录与可回收的终端承载分开。TD 保留逻辑 `session_id`、
+原生身份、授权归属、原启动配置和消息关联；terminal/backend/tmux/pane 是可重建的
+运行承载。`released` 不进入活动终端列表，没有常驻 Agent、PTY 或 tmux。
+它不是隐藏的终端，也不表示删除 Agent 原生历史。原生历史仍由 Agent 管理。
+
+共享内核 `sessionLifecycle.ts` 提供操作串行、原生身份预留、代次和释放验证协议；
+首批调用者为现有 IntegrationSession/受限 CLI。复用原有持久恢复记录，不新增
+conversation/job/task 或裸 UUID 导入。现有用户关闭、最近关闭列表、任务执行归档
+保持现有行为，本版尚未将它们迁入该协议。principal 是调用权限，不是业务类型。
+
+```sh
+# 管理员将 session.release 追加到原身份的 permissions，凭据保持不变。
+td integration update --file /private/path/policy.json
+# 后台从 get 获取当前 generation（不能硬编码，也不能仅沿用旧事件中的代次）。
+td collab --principal report-bridge session get <session-id>
+td collab --principal report-bridge session release <session-id> \
+  --generation <current-generation> --idempotency-key <this-release-key>
+# 下一条外部消息先持久接收，显式恢复，再 send/reply。
+td collab --principal report-bridge session restore <session-id> \
+  --idempotency-key <this-restore-key>
+td collab --principal report-bridge reply <retained-original-message-id> \
+  --file /private/path/followup.txt --idempotency-key <this-message-key>
+```
+
+权限：`session.release` 与 `session.restore` 分开授权，`session.read` 用于状态回读。
+必须仍属于原 principal/本机组；没有 `session.release` 的旧身份不会获得该能力。
+运行中 Agent 必须先由调用方明确正常退出；TD 不根据 result、快照、输出间隔或
+忙闲推断代为终止。首版验证固定的单 pane、原 shell PID/前台进程组和纯交互 shell
+参数，没有 Agent 或其它前台工作。shell 中人工输入的未执行文字不属于可靠观测，
+调用方需保证不与人工输入同时操作。无原生 ID、未知进程、进行中的启动/恢复、
+pending 消息或其它组的成员归属均拒绝；不取消 pending、不补投 delivered 正文。
+
+新增公开字段：`generation`（旧记录初始为 1）、`runtime_present`（true/false/null）、
+`operation_uncertain`（可选）、`resume_configuration_fingerprint`（可选）。
+`runtime_present=null` 表示观测/操作结果不明，不能解释为零资源；shell 仍存在时
+为 true。成功 `released` 必须 `runtime_present=false,terminal_binding=null,error_code=null`。
+释放保存的原组角色在恢复时重建，组、消息、结果、旧任务不会随释放删除。
+
+实际释放和实际恢复在执行前递增 generation；管理员兼容确认也递增，以使旧观察
+失效。已经 released 的新键 release、精确运行中的新键 restore 为无动作回读，保持
+原 operation/generation。release 必须携带 get 返回的当前代次，旧值报
+`SESSION_GENERATION_MISMATCH`；代次不等于消息序号、任务 attempt 或业务周期。
+从本版开始完成的 release/restore 幂等键重放返回**该操作原结果快照**，可能已不是
+当前状态；使用 get 查当前状态。不同参数复用键返回 `IDEMPOTENCY_CONFLICT`，
+下一次实际操作使用新键。若崩溃发生在结果快照提交前，且会话已经进入后续代次，
+旧键返回 OPERATION_OUTCOME_UNCONFIRMED，不把新操作结果冒充旧结果。升级前的旧幂等
+记录仍按兼容规则回读当前状态，不重复执行。
+
+同 ID 的生命周期串行；同 Agent/native ID 的验证/启动使用服务内互斥预留，重启后
+持久的未决启动意图也阻挡另一描述启动。同一键的并发请求共用原操作，不启动两份。
+原生身份检查继续使用实际 argv/当前持锁证据；该预留不是独立程序之间的全局原子锁。
+释放先保存意图，再阻断新投递、等待正在进行的投递，重新核验后销毁，最后保存结果。
+落盘失败不先执行回收；回收失败保留描述并报告 failed，不宣称 released。
+
+重启对 releasing/不确定记录核验实际承载：已经不存在时可以清理残留登记并收口，
+仍存在时返回 `OPERATION_OUTCOME_UNCONFIRMED`，不会自动杀进程或再启动 Agent。
+调用方读 get/诊断、明确处理现场后，可用当前 generation 和新键再次请求 release。
+Released 记录若出现未授权重建的承载，同样拒绝静默接管。
+`session.releasing/released/restoring/ready/failed` 推送原 operation_id/generation；
+沿用现有 event_id 去重、连续持久接收 ACK、断线重放与保留缺口契约。
+
+Released 上 send/reply 返回 `SESSION_RELEASED`，不入队、不隐式启动。恢复重建承载后
+逻辑 ID 不变，原 retained 消息的 reply_to、thread_id 与 principal 关联不需要迁移。
+恢复返回 ready 只证明原生身份，消息仍受本次 startupInput 保护。恢复失败不得静默
+创建另一 UUID、使用 --last，或改走新的业务任务/会话。
+
+**历史保留边界不变**：普通消息仍只覆盖保留记录（通常最近 2,000 条及待投递/近期
+幂等保护记录），每组事件仍保留 10,000 条。释放不是无限历史锚点；原消息裁剪后
+reply 返回 `MESSAGE_NOT_FOUND`，不能伪造旧 reply_to。是否用同恢复会话的新普通
+消息作为新咨询锚点由业务方决定，并保留自己的外部历史。没有 forget 或删除原生
+历史接口；用户放弃历史与释放承载是不同操作，原生历史删除不在本版范围。
+
+#### 恢复配置兼容性与旧记录初始化
+
+新建可精确恢复的记录在启动前保存配置指纹。指纹涵盖当前 launcher 的真实路径、
+文件 SHA-256、原 argv/resumeArgv/cwd、Agent 别名、精确 resume 语义、插件 nativeIdentity
+声明。它不是整个私有 Agent 安装包/包装器依赖/原生历史的备份，也不会检查私有
+会话正文。包装器路径相同不能证明内容相同；文件超过 512 MiB 不支持指纹采集。
+现有不能精确 resume 的插件仍可创建终端，但不因此获得安全释放能力。
+
+旧记录未保存历史文件内容，升级时只初始化代次，不自动采集为“历史已验证”。
+第一次 release 前，管理员先读取**当前**指纹，核对原模型/参数/cwd、包装器当前内容
+和插件恢复语义，再明确授权当前配置用于原历史恢复：
+
+```sh
+td integration resume-configuration <session-id>
+# 返回 generation, recorded_fingerprint（旧记录为 null）, current_fingerprint,
+# confirmation_required。无 shell/PTY/状态改变，不返回文件正文或凭据。
+td integration confirm-resume <session-id> \
+  --generation <returned-generation> --fingerprint <current_fingerprint>
+```
+
+确认只证明管理员接受当前兼容性，**不证明未知的旧包装器内容**；不改 argv/profile/
+cwd/native UUID/私有程序。后来指纹不一致时明确失败，管理员也可在核对后用上述
+步骤确认新兼容指纹；TD 不暗中迁移模型或参数。正在执行生命周期操作时不允许确认。
+恢复继续使用原 profile 快照；同时按当前授权的 profile/cwdRoots 复核 cwd，撤销或
+缩小授权不被旧快照绕过。插件精确恢复能力消失或身份/启动条件失败仍会拒绝。
+
+能力检测：CLI/实际服务均至少 1.4.309，协议 1；服务 capabilities 必须包含
+`session_runtime_release=true,stable_session_identity=true,session_lifecycle_generation=true,
+session_resume_configuration=true,session_lifecycle_min_version="1.4.309"`。
+CLI 对旧服务先检查能力，失败为 `SESSION_RELEASE_UNSUPPORTED`，不发送回收请求。
+本地管理员配置确认同样先探测服务能力。未知或不兼容错误不得转为新会话。
+
+| 错误码 | 准确语义及处理 |
+| --- | --- |
+| SESSION_RELEASE_UNSUPPORTED | CLI/实际服务或运行适配器不支持本协议；升级两者 |
+| INVALID_SESSION_GENERATION | 缺少或非法代次；从 get 获取正整数 |
+| SESSION_GENERATION_MISMATCH | 观察已过时；重新读当前记录，不硬改旧请求 |
+| SESSION_STILL_RUNNING | 实际 Agent 仍在运行；不能推断空闲后自动退出 |
+| SESSION_PENDING_MESSAGES | 存在 pending 正文；先明确处理，不清空或重投 |
+| SESSION_OPERATION_IN_PROGRESS | 同 ID 正在操作或原启动未决 |
+| SESSION_NATIVE_OPERATION_IN_PROGRESS | 同原生身份有其它描述的在途/持久未决操作 |
+| SESSION_SCOPE_CONFLICT | 终端还属于其它组；管理员先处理归属 |
+| SESSION_IDENTITY_MISMATCH | 固定终端/pane/PID/布局或 shell 证明不符 |
+| RESUME_CONFIGURATION_UNCONFIRMED | 旧记录缺少兼容确认；管理员核对当前指纹 |
+| RESUME_CONFIGURATION_CHANGED | launcher 内容/路径或插件恢复语义变化；不自动采纳 |
+| OPERATION_OUTCOME_UNCONFIRMED | 释放结果不明或承载重新出现；保留记录并核对 |
+| SESSION_STORAGE_FULL | 恢复记录 journal 超过 64 MiB；停止新增操作并由管理员处理 |
+| SESSION_RELEASE_FAILED | 未分类释放失败；不返回私有异常输出 |
+| SESSION_RELEASED | 消息目标已释放；先显式精确 restore |
+
+原有权限/组/目录、幂等、EXACT_RESUME_UNSUPPORTED、原生重复所有者、启动/绑定错误
+继续适用；本节不改变这些错误的保护条件。
+
 ### 管理员恢复诊断（1.4.305）
 
 `capabilities.session_restore_diagnostics=true` 表示服务支持持久恢复诊断。
@@ -501,6 +716,11 @@ no-op restore 不创建新检查。报告跟随会话保存并可在服务重启
 
 ## 验收边界
 
+本版维护机验证：共享释放协议、真实 Unix socket 权限/生命周期事件、零入队拒绝、
+同键并发/旧代次/异常释放/重启对账、配置内容变化与旧记录显式确认、原消息关联；
+隔离真实 tmux 的实际销毁与原逻辑 ID 重建。本机 fixture 不等于私有 TraeX 验收，
+本版真实 TraeX 的零承载→同 UUID→真人原话题往返仍待使用方升级后验证。
+
 维护机验证：真实 Unix socket 主动推送/断线重放/撤销、journal 重载与源记录补偿、
 权限与幂等隔离、accepted 上咨询/关联答复、修订后的新结果、原 profile 恢复和
 实际 shell 参数透传。适配器测试不冒充真实 Agent 的原生会话验收。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "termdock",
-  "version": "1.4.307",
+  "version": "1.4.309",
   "description": "A complete web-based terminal application with modern UI",
   "type": "module",
   "main": ".desktop-dist/main.js",

package/runtime-manifest.json

@@ -1,13 +1,13 @@
 {
   "schemaVersion": 1,
   "packageName": "termdock",
-  "version": "1.4.307",
+  "version": "1.4.309",
   "runtimeProtocolVersion": 1,
   "minimumDesktopVersion": "1.4.46",
   "nodeMajor": 22,
   "dependencyHash": "sha256-E9GDa4nrCXADRXdyPKufusZt6IcCr4m2mGdx5h34KMQ=",
-  "serverBundleHash": "sha256-SmxpQ63ErP59HLeERjJ0euDs74G6un227eMPe9/sAEI=",
-  "clientBundleHash": "sha256-dfDbp6qzSoUEczQc0mFdVx2jNb+7Oabm+ZvcTpBThnw=",
+  "serverBundleHash": "sha256-3rATyPEt6ztAvF1p3T03N1mo2A1qIKkVUePIG0xc53w=",
+  "clientBundleHash": "sha256-Yh0fz4oTrM6A2pNHLYx+Y67/R7Wfa84cFlIPMrwAsfE=",
   "entrypoint": "dist/server/cli.js",
   "clientEntrypoint": "dist/client/index.html"
 }

package/dist/client/assets/CollaborationTaskContent-DQpH2HIj.js

@@ -1,2 +0,0 @@
-import{bv as r}from"./app-CXvK8WZg.js";import{b as m}from"./dnd-BCFAPC0L.js";import{b as n}from"./RightSidebar-CnnU7Ffp.js";import"./react-XDCjal2T.js";import"./terminal-C7X98Amf.js";import"./App-cagV-flM.js";import"./gestureArbiter-Cy5v_ZUL.js";import"./triangle-alert-BFCgLlxS.js";import"./referenceLongPress-xNXQRqYn.js";import"./DiffReview-Cn_PmN-9.js";import"./sparkles-BBYDWqCu.js";import"./DiffViewer-DRnuph7U.js";import"./ChangeWalkthroughPanel-DOj40Srm.js";function v({content:o}){const e=m.useMemo(()=>n(o.split(`
-`),null,null),[o]);return r.jsx("div",{className:"min-w-0 space-y-3 break-words text-sm leading-6 text-foreground [&_h1]:text-lg [&_h2]:text-base [&_h3]:text-sm [&_pre]:max-w-full [&_table]:text-xs",children:e.map((t,i)=>r.jsx("div",{className:"min-w-0",children:typeof t.content=="function"?t.content(null):t.content},i))})}export{v as default};

package/dist/client/assets/channel-YDx-Ycsw.js

@@ -1 +0,0 @@
-import{c as a,C as n}from"./mermaid.core-ClemZ-kc.js";const t=(r,o)=>a.lang.round(n.parse(r)[o]);export{t as c};

package/dist/client/assets/classDiagram-ZZMXUADV-qeb16N1g.js

@@ -1 +0,0 @@
-import{s as a,a as s,c as t,C as e}from"./chunk-TICWLB2K-W1cGkC4s.js";import{d as i}from"./mermaid.core-ClemZ-kc.js";import"./chunk-5VM5RSS4-LrpNvv_o.js";import"./chunk-XXDRQBXY-mXLNbLH8.js";import"./chunk-POPQ4Y6H-M5MSHOUM.js";import"./chunk-F27PBJKO-BcpMMU4P.js";import"./purify.es-4eNOHKSq.js";import"./app-CXvK8WZg.js";import"./react-XDCjal2T.js";import"./dnd-BCFAPC0L.js";import"./terminal-C7X98Amf.js";var g={parser:t,get db(){return new e},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{g as diagram};

package/dist/client/assets/classDiagram-v2-VYDZK3BY-qeb16N1g.js

@@ -1 +0,0 @@
-import{s as a,a as s,c as t,C as e}from"./chunk-TICWLB2K-W1cGkC4s.js";import{d as i}from"./mermaid.core-ClemZ-kc.js";import"./chunk-5VM5RSS4-LrpNvv_o.js";import"./chunk-XXDRQBXY-mXLNbLH8.js";import"./chunk-POPQ4Y6H-M5MSHOUM.js";import"./chunk-F27PBJKO-BcpMMU4P.js";import"./purify.es-4eNOHKSq.js";import"./app-CXvK8WZg.js";import"./react-XDCjal2T.js";import"./dnd-BCFAPC0L.js";import"./terminal-C7X98Amf.js";var g={parser:t,get db(){return new e},renderer:s,styles:a,init:i(r=>{r.class||(r.class={}),r.class.arrowMarkerAbsolute=r.arrowMarkerAbsolute},"init")};export{g as diagram};