termdock 1.4.308 → 1.4.309

package/dist/server/agent/collaborationCli.js

@@ -68,6 +68,20 @@ export const COLLAB_HELP = `td collab — durable messages; no agent-specific ho
     消息历史只覆盖仍保留记录；不存在的 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。
@@ -172,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 = [];
@@ -238,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}`);
@@ -381,7 +397,7 @@ 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'],

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();
@@ -324,6 +326,9 @@ export class CollaborationStore {
             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('没有有效的接收会话');

package/dist/server/agent/integrationCli.js

@@ -8,6 +8,15 @@ import { COLLAB_HELP, executeCollaborationCommand, duration } from './collaborat
 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)
@@ -63,6 +72,30 @@ export async function runIntegrationAdmin(argv, port, adminToken, write) {
             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');
@@ -161,9 +194,11 @@ 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;
         }

package/dist/server/agent/integrationServer.js

@@ -34,6 +34,7 @@ export class IntegrationRuntime {
         this.options = options;
         this.store = new IntegrationStore(path.join(options.directory, 'integrations.json'));
         this.sessions = new IntegrationSessions(path.join(options.directory, 'integration-sessions.json'), options.sessions);
+        this.stops.push(options.messages.registerRuntimeGuard(id => this.sessions.assertRuntimeMessage(id)));
         const changed = () => { try {
             this.sync();
         }
@@ -70,6 +71,8 @@ export class IntegrationRuntime {
         app.get('/admin/groups', run(req => { admin(req); return { groups: options.messages.list().filter(g => !g.federated).map(g => ({ id: g.id, name: g.name })) }; }));
         app.get('/admin/capabilities', run(req => { admin(req); return this.capabilities(); }));
         app.get('/admin/sessions/:id/restore-diagnostics', run(req => { admin(req); return this.sessions.restoreDiagnostics(req.params.id); }));
+        app.get('/admin/sessions/:id/resume-configuration', run(async (req) => { admin(req); return this.sessions.resumeConfiguration(req.params.id); }));
+        app.post('/admin/sessions/:id/resume-configuration', run(async (req) => { admin(req); return { session: publicIntegrationSession(await this.sessions.confirmResumeConfiguration(req.params.id, req.body?.generation, req.body?.fingerprint)) }; }));
         app.get('/admin/principals', run(req => { admin(req); return { integrations: this.store.policies() }; }));
         app.post('/admin/principals', run(req => { admin(req); this.group(req.body?.groupId); const provisioned = this.store.provision(req.body); try {
             this.sync();
@@ -120,7 +123,13 @@ export class IntegrationRuntime {
             const targets = Array.isArray(raw.toSessionIds) ? raw.toSessionIds : [raw.targetSessionId];
             if (!targets.length || targets.some((id) => typeof id !== 'string'))
                 integrationError('INVALID_MESSAGE_TARGET', 'Specify a local group member');
-            const recipients = targets.map((id) => scopedId(id, group.sessionIds, 'SESSION'));
+            const descriptors = this.sessions.snapshot().filter(s => s.group_id === p.groupId);
+            const recipients = targets.map((id) => scopedId(id, [...group.sessionIds, ...descriptors.map(s => s.session_id)], 'SESSION'));
+            for (const id of recipients) {
+                this.sessions.assertMessageTarget(p, id);
+                if (!group.sessionIds.includes(id))
+                    integrationError('SESSION_NOT_FOUND', 'Restore the original runtime and membership before sending', 404);
+            }
             let thread;
             if (raw.thread_id)
                 thread = scopedId(raw.thread_id, options.messages.snapshotMessages().filter(m => m.groupId === p.groupId).map(m => m.threadId), 'THREAD');
@@ -135,6 +144,8 @@ export class IntegrationRuntime {
             const raw = req.body ?? {}, original = this.message(p, raw.messageId);
             const target = original.toPrincipalId === p.id ? original.fromSessionId
                 : original.integrationOrigin?.integrationId === p.id ? original.toSessionId : null;
+            if (target)
+                this.sessions.assertMessageTarget(p, target);
             if (!target || !this.group(p.groupId).sessionIds.includes(target))
                 integrationError('NO_REPLY_TARGET', 'Reply requires your own message and its original live group member', 409);
             const messages = options.messages.send({ ...this.messageExtras(raw), groupId: p.groupId, fromSessionId: null,
@@ -180,6 +191,7 @@ export class IntegrationRuntime {
         }));
         app.get('/sessions/:id', run(async (req) => { const p = principal(req); this.authorize(p, 'session.read'); return { session: publicIntegrationSession(await this.sessions.get(p, req.params.id)) }; }));
         app.post('/sessions/:id/restore', run(async (req) => { const p = principal(req); this.authorize(p, 'session.restore'); const session = await this.sessions.restore(p, req.params.id, req.body?.idempotency_key); this.sync(); return { session: publicIntegrationSession(session) }; }));
+        app.post('/sessions/:id/release', run(async (req) => { const p = principal(req); this.authorize(p, 'session.release'); const session = await this.sessions.release(p, req.params.id, req.body?.generation, req.body?.idempotency_key); this.sync(); return { session: publicIntegrationSession(session) }; }));
         app.get('/events', run((req, res) => {
             const p = principal(req);
             this.authorize(p, 'events.read', req.query.group);
@@ -203,7 +215,8 @@ export class IntegrationRuntime {
             integration_principal: true, group_scoped_permissions: true, durable_event_push: true,
             event_ack_semantics: 'durable_received', correlated_task_responses: true, accepted_task_comments: true,
             idempotent_session_create: true, exact_session_restore: true, external_validation: false,
-            startup_input_conditions: true,
+            startup_input_conditions: true, session_runtime_release: true, stable_session_identity: true, session_lifecycle_generation: true,
+            session_resume_configuration: true, session_lifecycle_min_version: '1.4.309',
             integration_policy_update: true,
             session_restore_diagnostics: true,
             native_identity_linux_flock_owner: process.platform === 'linux',

package/dist/server/agent/integrationSessions.js

@@ -2,6 +2,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { createHash, randomBytes, randomUUID } from 'node:crypto';
 import { atomicJson, integrationError } from './integrationStore.js';
+import { SessionLifecycleCoordinator, assertMessageRuntime, assertReleaseFacts, assertReleaseGeneration } from './sessionLifecycle.js';
+import { resumeConfigurationFingerprint } from './sessionResumeConfiguration.js';
 import { NativeResumeOwnerError } from './nativeResumeOwner.js';
 /** Quote each configured argument as literal shell data, including paths. */
 export function integrationLaunchCommand(record, restore) {
@@ -50,7 +52,8 @@ export class IntegrationSessions {
     doc = { version: 1, sessions: [], requests: {} };
     pending = new Map();
     listeners = new Set();
-    restoring = new Set();
+    lifecycle = new SessionLifecycleCoordinator();
+    mutations = new Map();
     timers = new Set();
     stopObservation;
     stopDeliveryGuard;
@@ -70,8 +73,12 @@ export class IntegrationSessions {
             if (error.code !== 'ENOENT')
                 throw error;
         }
+        for (const record of this.doc.sessions) {
+            record.generation ??= 1;
+            record.runtime_present ??= null;
+        }
         for (const record of this.doc.sessions)
-            if (['starting', 'restoring', 'binding_pending'].includes(record.state) || record.startup_input?.state === 'pending')
+            if (['starting', 'restoring', 'binding_pending'].includes(record.state) || record.state === 'releasing' || record.startup_input?.state === 'pending')
                 this.scheduleRefresh(record);
         // A pre-restart partial match cannot prove continuity of the live screen.
         for (const record of this.doc.sessions)
@@ -89,12 +96,17 @@ export class IntegrationSessions {
     }
     subscribe(listener) { this.listeners.add(listener); return () => { this.listeners.delete(listener); }; }
     snapshot() { return structuredClone(this.doc.sessions); }
-    save() { atomicJson(this.file, this.doc); for (const listener of this.listeners) {
-        try {
-            listener();
+    save() {
+        if (Buffer.byteLength(JSON.stringify(this.doc)) > 64 * 1024 * 1024)
+            integrationError('SESSION_STORAGE_FULL', 'Recovery descriptor journal is full; no new operation was committed', 503);
+        atomicJson(this.file, this.doc);
+        for (const listener of this.listeners) {
+            try {
+                listener();
+            }
+            catch { /* Durable session state is reconciled on restart. */ }
         }
-        catch { /* Durable session state is reconciled on restart. */ }
-    } }
+    }
     saveRecord(record) {
         const before = this.doc.sessions;
         this.doc.sessions = [...before.filter(s => s.session_id !== record.session_id), structuredClone(record)];
@@ -139,7 +151,7 @@ export class IntegrationSessions {
             integrationError('INTEGRATION_SESSION_LIMIT', 'Integration session storage is full', 409);
         const now = Date.now(), record = { operation_id: randomUUID(), session_id: randomBytes(6).toString('hex'),
             group_id: principal.groupId, principal_id: principal.id, agent_slug: profile.agentSlug, agent_native_session_id: null,
-            state: 'starting', error_code: null, cwd, launch_profile: profile.id, profile: structuredClone(profile),
+            state: 'starting', generation: 1, runtime_present: null, error_code: null, cwd, launch_profile: profile.id, profile: structuredClone(profile),
             created_at: now, updated_at: now, deadline: now + this.bindingTimeout, launch_submitted: false };
         record.startup_input = startupInput(record, now);
         this.doc.requests[request.scoped] = { hash: request.hash, sessionId: record.session_id };
@@ -156,6 +168,21 @@ export class IntegrationSessions {
         const promise = (async () => {
             try {
                 // Store intent before launching. A failed persistence cannot execute.
+                if (this.adapter.resumeConfiguration) {
+                    try {
+                        const fingerprint = await resumeConfigurationFingerprint(record, this.adapter);
+                        if (record.resume_configuration_fingerprint && record.resume_configuration_fingerprint !== fingerprint)
+                            integrationError('RESUME_CONFIGURATION_CHANGED', 'Recovery launcher or plugin semantics changed', 409);
+                        if (!restoring)
+                            record.resume_configuration_fingerprint = fingerprint;
+                    }
+                    catch (error) {
+                        // Existing creation supports plugins without an exact resume path.
+                        // They remain launchable, but cannot gain a releasable descriptor.
+                        if (restoring || error.code !== 'EXACT_RESUME_UNSUPPORTED')
+                            throw error;
+                    }
+                }
                 record.launch_submitted = true;
                 this.saveRecord(record);
                 const prepared = (binding) => { record.terminal_binding = binding; this.saveRecord(record); };
@@ -187,27 +214,74 @@ export class IntegrationSessions {
         return structuredClone({ session_id: record.session_id, operation_id: record.operation_id,
             state: record.state, error_code: record.error_code, diagnostics: record.restore_diagnostics ?? null });
     }
-    async restore(principal, id, idempotencyKey) {
+    assertRuntimeMessage(id) { assertMessageRuntime(this.doc.sessions.find(s => s.session_id === id)); }
+    assertMessageTarget(principal, id) {
+        const record = this.doc.sessions.find(s => s.session_id === id && s.group_id === principal.groupId);
+        assertMessageRuntime(record);
+    }
+    async mutate(principal, key, input, action) {
+        const request = this.request(principal, key, input);
+        if (request.previous?.result) {
+            this.lookup(principal, request.previous.sessionId);
+            return structuredClone(request.previous.result);
+        }
+        const active = this.mutations.get(request.scoped);
+        if (active) {
+            if (active.hash !== request.hash)
+                integrationError('IDEMPOTENCY_CONFLICT', 'Operation key parameters changed', 409);
+            return active.promise;
+        }
+        const promise = action().then(result => {
+            if (this.doc.requests[request.scoped]) {
+                const before = this.doc.requests[request.scoped];
+                this.doc.requests[request.scoped] = { ...before, result: structuredClone(result) };
+                try {
+                    this.save();
+                }
+                catch (error) {
+                    this.doc.requests[request.scoped] = before;
+                    throw error;
+                }
+            }
+            return result;
+        }).finally(() => this.mutations.delete(request.scoped));
+        this.mutations.set(request.scoped, { hash: request.hash, promise });
+        return promise;
+    }
+    async replayRequest(principal, id, request) {
+        const record = await (this.pending.get(id) ?? this.get(principal, id));
+        if (request.operationId && (record.operation_id !== request.operationId || record.generation !== request.generation))
+            integrationError('OPERATION_OUTCOME_UNCONFIRMED', 'Original operation result was not committed and a later generation exists; read session get, do not reuse this key', 409);
+        return record;
+    }
+    async restore(principal, id, key) {
+        return this.mutate(principal, key, ['restore', id], () => this.lifecycle.run(id, () => this.restoreOnce(principal, id, key)));
+    }
+    async restoreOnce(principal, id, idempotencyKey) {
         const request = this.request(principal, idempotencyKey, ['restore', id]);
         if (request.previous)
-            return this.pending.get(id) ?? this.get(principal, id);
-        if (this.pending.has(id) || this.restoring.has(id))
+            return this.replayRequest(principal, id, request.previous);
+        if (this.pending.has(id))
             integrationError('SESSION_OPERATION_IN_PROGRESS', 'Another session operation is in progress', 409);
-        this.restoring.add(id);
+        let releaseNative;
         try {
             const record = await this.get(principal, id);
             if (!record.agent_native_session_id)
                 integrationError('NATIVE_SESSION_ID_MISSING', 'An exact native session binding is required', 409);
             // Recheck the current grant and actual directories; restore uses the
             // original profile snapshot, never changed model or wrapper defaults.
-            if (!principal.launchProfiles.some(p => p.id === record.launch_profile))
+            const authorizedProfile = principal.launchProfiles.find(p => p.id === record.launch_profile);
+            if (!authorizedProfile)
                 integrationError('LAUNCH_PROFILE_DENIED', 'Original launch profile is no longer authorized', 403);
+            permittedCwd(authorizedProfile, record.cwd);
             permittedCwd(record.profile, record.cwd);
+            if (record.operation_uncertain || record.state === 'releasing')
+                integrationError('OPERATION_OUTCOME_UNCONFIRMED', 'Reconcile prior release using session get before restore', 409);
             const observed = await this.adapter.inspect(record);
             if (observed.running) {
                 if (observed.agentSlug !== record.agent_slug || observed.nativeId !== record.agent_native_session_id)
                     integrationError('SESSION_IDENTITY_MISMATCH', 'Existing process does not prove the exact native binding', 409);
-                this.doc.requests[request.scoped] = { hash: request.hash, sessionId: id };
+                this.doc.requests[request.scoped] = { hash: request.hash, sessionId: id, operationId: record.operation_id, generation: record.generation };
                 try {
                     this.save();
                 }
@@ -221,6 +295,13 @@ export class IntegrationSessions {
                 integrationError('SESSION_OPERATION_IN_PROGRESS', 'Prior launch outcome is not yet resolved; inspect the original session', 409);
             if (observed.exists && !observed.shell)
                 integrationError('SESSION_TARGET_NOT_SHELL', 'Original pane is not a verified shell', 409);
+            if (record.state === 'released' && !record.resume_configuration_fingerprint)
+                integrationError('RESUME_CONFIGURATION_UNCONFIRMED', 'Administrator must explicitly confirm the current recovery configuration', 409);
+            releaseNative = this.lifecycle.reserveNative(record, this.doc.sessions);
+            if (record.resume_configuration_fingerprint && record.resume_configuration_fingerprint !== await resumeConfigurationFingerprint(record, this.adapter))
+                integrationError('RESUME_CONFIGURATION_CHANGED', 'Recovery launcher or plugin semantics changed', 409);
+            record.generation = (record.generation ?? 1) + 1;
+            record.runtime_present = observed.exists;
             record.state = 'restoring';
             record.error_code = null;
             record.operation_id = randomUUID();
@@ -230,7 +311,7 @@ export class IntegrationSessions {
             if (!record.profile.startupInput && !record.startup_condition)
                 record.startup_condition = structuredClone(principal.launchProfiles.find(profile => profile.id === record.launch_profile)?.startupInput);
             record.startup_input = startupInput(record, Date.now());
-            this.doc.requests[request.scoped] = { hash: request.hash, sessionId: id };
+            this.doc.requests[request.scoped] = { hash: request.hash, sessionId: id, operationId: record.operation_id, generation: record.generation };
             try {
                 this.saveRecord(record);
             }
@@ -241,13 +322,135 @@ export class IntegrationSessions {
             return await this.launch(record, true);
         }
         finally {
-            this.restoring.delete(id);
+            releaseNative?.();
         }
     }
+    async resumeConfiguration(id) {
+        const record = this.doc.sessions.find(s => s.session_id === id);
+        if (!record)
+            return integrationError('INTEGRATION_SESSION_NOT_FOUND', 'Recovery record does not exist', 404);
+        return { session_id: id, generation: record.generation ?? 1, recorded_fingerprint: record.resume_configuration_fingerprint ?? null,
+            current_fingerprint: await resumeConfigurationFingerprint(record, this.adapter), confirmation_required: !record.resume_configuration_fingerprint };
+    }
+    async confirmResumeConfiguration(id, generation, fingerprint) {
+        return this.lifecycle.run(id, async () => {
+            const record = structuredClone(this.doc.sessions.find(s => s.session_id === id));
+            if (!record)
+                return integrationError('INTEGRATION_SESSION_NOT_FOUND', 'Recovery record does not exist', 404);
+            assertReleaseGeneration(record, generation);
+            if (this.pending.has(id) || ['starting', 'restoring', 'binding_pending', 'releasing'].includes(record.state))
+                integrationError('SESSION_OPERATION_IN_PROGRESS', 'Resolve the current operation before confirming compatibility', 409);
+            if (!/^[a-f0-9]{64}$/.test(fingerprint) || fingerprint !== await resumeConfigurationFingerprint(record, this.adapter))
+                integrationError('RESUME_CONFIGURATION_CHANGED', 'Current fingerprint no longer matches the administrator confirmation', 409);
+            record.resume_configuration_fingerprint = fingerprint;
+            record.generation = generation + 1;
+            record.updated_at = Date.now();
+            this.saveRecord(record);
+            return record;
+        });
+    }
+    async release(principal, id, generation, key) {
+        return this.mutate(principal, key, ['release', id, generation], () => this.lifecycle.run(id, async () => {
+            const request = this.request(principal, key, ['release', id, generation]);
+            if (request.previous)
+                return this.replayRequest(principal, id, request.previous);
+            if (!this.adapter.release || !this.adapter.runtimePresent)
+                integrationError('SESSION_RELEASE_UNSUPPORTED', 'Runtime adapter does not support release', 409);
+            if (this.pending.has(id))
+                integrationError('SESSION_OPERATION_IN_PROGRESS', 'Launch is in progress', 409);
+            const record = await this.get(principal, id);
+            assertReleaseGeneration(record, generation);
+            if (record.state !== 'released') {
+                assertReleaseFacts(record, await this.adapter.inspect(record));
+                if (this.adapter.pendingMessages?.(id))
+                    integrationError('SESSION_PENDING_MESSAGES', 'Pending messages must be resolved before release', 409);
+                if (!record.resume_configuration_fingerprint)
+                    integrationError('RESUME_CONFIGURATION_UNCONFIRMED', 'Administrator must inspect and confirm the recovery configuration before release', 409);
+                if (record.resume_configuration_fingerprint !== await resumeConfigurationFingerprint(record, this.adapter))
+                    integrationError('RESUME_CONFIGURATION_CHANGED', 'Recovery launcher or plugin semantics changed', 409);
+            }
+            if (record.state === 'released') {
+                this.doc.requests[request.scoped] = { hash: request.hash, sessionId: id, operationId: record.operation_id, generation: record.generation };
+                try {
+                    this.save();
+                }
+                catch (error) {
+                    delete this.doc.requests[request.scoped];
+                    throw error;
+                }
+                return record;
+            }
+            if (this.adapter.prepareRelease)
+                record.group_role = (await this.adapter.prepareRelease(record)).group_role;
+            record.state = 'releasing';
+            record.operation_id = randomUUID();
+            record.generation = generation + 1;
+            record.operation_uncertain = false;
+            record.error_code = null;
+            record.updated_at = Date.now();
+            this.doc.requests[request.scoped] = { hash: request.hash, sessionId: id, operationId: record.operation_id, generation: record.generation };
+            try {
+                this.saveRecord(record);
+            }
+            catch (error) {
+                delete this.doc.requests[request.scoped];
+                throw error;
+            }
+            try {
+                await this.adapter.release(record, false);
+                if (await this.adapter.runtimePresent(record))
+                    integrationError('OPERATION_OUTCOME_UNCONFIRMED', 'Runtime removal could not be confirmed', 409);
+                record.state = 'released';
+                record.runtime_present = false;
+                record.terminal_binding = null;
+                record.startup_input = undefined;
+            }
+            catch (error) {
+                record.state = 'failed';
+                record.operation_uncertain = true;
+                record.runtime_present = null;
+                record.error_code = typeof error.code === 'string' ? error.code : 'SESSION_RELEASE_FAILED';
+            }
+            record.updated_at = Date.now();
+            this.saveRecord(record);
+            return record;
+        }));
+    }
     async refresh(id) {
         const record = structuredClone(this.doc.sessions.find(s => s.session_id === id));
         if (!record)
             return;
+        if (record.state === 'released' || record.state === 'releasing' || record.operation_uncertain) {
+            if (this.lifecycle.active(id))
+                return;
+            try {
+                if (record.state !== 'released')
+                    await this.adapter.release?.(record, true);
+                const present = await this.adapter.runtimePresent?.(record);
+                if (present === undefined)
+                    integrationError('SESSION_RELEASE_UNSUPPORTED', 'Runtime presence is unavailable', 409);
+                if (record.state !== 'released') {
+                    if (present)
+                        integrationError('OPERATION_OUTCOME_UNCONFIRMED', 'Prior release still has a runtime; explicit release retry is required', 409);
+                    // Absent runtime metadata has been reconciled without killing a live runtime.
+                }
+                else if (present)
+                    integrationError('OPERATION_OUTCOME_UNCONFIRMED', 'A runtime exists for a released descriptor', 409);
+                const next = { ...record, state: 'released', runtime_present: false, terminal_binding: null, startup_input: undefined, operation_uncertain: false, error_code: null };
+                if (JSON.stringify(this.doc.sessions.find(s => s.session_id === id)) !== JSON.stringify(record))
+                    return;
+                if (JSON.stringify(next) !== JSON.stringify(record))
+                    this.saveRecord({ ...next, updated_at: Date.now() });
+            }
+            catch (error) {
+                if (JSON.stringify(this.doc.sessions.find(s => s.session_id === id)) !== JSON.stringify(record))
+                    return;
+                const next = { ...record, state: 'failed', runtime_present: null, operation_uncertain: true, error_code: typeof error.code === 'string' ? error.code : 'OPERATION_OUTCOME_UNCONFIRMED' };
+                if (JSON.stringify(next) !== JSON.stringify(record))
+                    this.saveRecord({ ...next, updated_at: Date.now() });
+            }
+            return;
+        }
         let observed;
         try {
             observed = await this.adapter.inspect(record);
@@ -261,7 +464,7 @@ export class IntegrationSessions {
                 this.saveRecord({ ...record, state: 'failed', error_code: typeof code === 'string' ? code : 'SESSION_OBSERVATION_FAILED', updated_at: Date.now() });
             return;
         }
-        const next = { ...record };
+        const next = { ...record, runtime_present: this.adapter.runtimePresent ? await this.adapter.runtimePresent(record) : observed.exists };
         if (observed.nativeId && (typeof observed.nativeId !== 'string' || observed.nativeId.length > 256 || /[\x00-\x1f\x7f]/.test(observed.nativeId))) {
             next.state = 'failed';
             next.error_code = 'NATIVE_SESSION_ID_INVALID';
@@ -325,7 +528,12 @@ export class IntegrationSessions {
     }
     /** Only gates configured launches. Native UUID and Agent turn state are not input prerequisites. */
     async deliveryReadiness(id) {
-        if (!this.doc.sessions.find(record => record.session_id === id)?.startup_input)
+        const existing = this.doc.sessions.find(record => record.session_id === id);
+        if (!existing)
+            return null;
+        if (existing.state === 'released' || existing.state === 'releasing' || existing.operation_uncertain)
+            return { allowed: false, reason: existing.state === 'released' ? 'SESSION_RELEASED' : 'SESSION_OPERATION_IN_PROGRESS' };
+        if (!existing.startup_input)
             return null;
         await this.refresh(id);
         const record = this.doc.sessions.find(record => record.session_id === id);

package/dist/server/agent/integrationStore.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { createHash, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
 import { CollaborationError } from './collaborationProtocol.js';
 export const INTEGRATION_PROTOCOL = 1;
-export const INTEGRATION_OPERATIONS = ['message.send', 'message.read', 'task.read', 'task.create', 'task.configure', 'task.assign', 'task.comment', 'task.revise', 'task.answer', 'events.read', 'session.create', 'session.read', 'session.restore'];
+export const INTEGRATION_OPERATIONS = ['message.send', 'message.read', 'task.read', 'task.create', 'task.configure', 'task.assign', 'task.comment', 'task.revise', 'task.answer', 'events.read', 'session.create', 'session.read', 'session.restore', 'session.release'];
 export function integrationError(code, message, status = 400) { throw new CollaborationError(code, message, status); }
 export function atomicJson(file, value) {
     fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });

package/dist/server/agent/sessionLifecycle.js

@@ -0,0 +1,81 @@
+import { CollaborationError } from './collaborationProtocol.js';
+const fail = (code, message) => { throw new CollaborationError(code, message, 409); };
+/** One coordinator per service. A reservation covers validation and launch;
+ * persisted unresolved intents also block a second identity after restart.
+ * This does not promise atomic exclusion of independently launched programs. */
+export class SessionLifecycleCoordinator {
+    operations = new Set();
+    natives = new Map();
+    async run(id, action) {
+        if (this.operations.has(id))
+            fail('SESSION_OPERATION_IN_PROGRESS', 'Another lifecycle operation is in progress');
+        this.operations.add(id);
+        try {
+            return await action();
+        }
+        finally {
+            this.operations.delete(id);
+        }
+    }
+    active(id) { return this.operations.has(id); }
+    reserveNative(record, descriptors) {
+        const key = JSON.stringify([record.agent_slug, record.agent_native_session_id]);
+        const owner = this.natives.get(key);
+        if (owner && owner !== record.session_id || descriptors.some(other => other.session_id !== record.session_id
+            && other.agent_slug === record.agent_slug && other.agent_native_session_id === record.agent_native_session_id
+            && (['starting', 'restoring', 'binding_pending'].includes(other.state) || other.operation_uncertain))) {
+            fail('SESSION_NATIVE_OPERATION_IN_PROGRESS', 'Another descriptor has an unresolved operation for this native identity');
+        }
+        this.natives.set(key, record.session_id);
+        return () => { if (this.natives.get(key) === record.session_id)
+            this.natives.delete(key); };
+    }
+}
+export function assertReleaseGeneration(record, generation) {
+    if (!Number.isSafeInteger(generation) || Number(generation) < 1)
+        fail('INVALID_SESSION_GENERATION', 'release requires the generation returned by session get');
+    if (generation !== (record.generation ?? 1))
+        fail('SESSION_GENERATION_MISMATCH', 'Session generation changed; read its current state before releasing');
+}
+export function assertReleaseFacts(record, facts) {
+    if (!record.agent_native_session_id)
+        fail('NATIVE_SESSION_ID_MISSING', 'Release requires a durable exact native identity');
+    if (['starting', 'restoring', 'binding_pending', 'releasing'].includes(record.state))
+        fail('SESSION_OPERATION_IN_PROGRESS', 'Prior operation is unresolved');
+    if (facts.running)
+        fail('SESSION_STILL_RUNNING', 'Agent is still running; explicitly exit it before releasing the runtime');
+    if (facts.exists && !facts.shell)
+        fail('SESSION_IDENTITY_MISMATCH', 'Runtime is not the verified original empty shell');
+}
+export function assertMessageRuntime(record) {
+    if (!record)
+        return;
+    if (record.state === 'released')
+        fail('SESSION_RELEASED', 'Runtime was released; explicitly restore this session before sending');
+    if (record.state === 'releasing')
+        fail('SESSION_OPERATION_IN_PROGRESS', 'Runtime release is in progress; message was not enqueued');
+    if (record.operation_uncertain)
+        fail('OPERATION_OUTCOME_UNCONFIRMED', 'Lifecycle outcome needs reconciliation before sending');
+}
+/** Shared release protocol. No Agent idle inference, task result, or UI
+ * visibility participates in deciding whether a process may be destroyed. */
+export async function releaseSessionRuntime(adapter, reconcile) {
+    await adapter.barrier(async () => {
+        if (adapter.pendingMessages())
+            fail('SESSION_PENDING_MESSAGES', 'Pending messages appeared before runtime release');
+        if (await adapter.exists()) {
+            if (reconcile)
+                fail('OPERATION_OUTCOME_UNCONFIRMED', 'Original runtime still exists; restart reconciliation will not terminate it');
+            await adapter.verifyOwnership();
+            const facts = await adapter.inspect();
+            if (facts.running)
+                fail('SESSION_STILL_RUNNING', 'Agent restarted before release');
+            if (!facts.exists || !facts.shell)
+                fail('SESSION_IDENTITY_MISMATCH', 'Original runtime is not a verified foreground shell');
+            await adapter.destroy();
+        }
+        if (await adapter.exists())
+            fail('OPERATION_OUTCOME_UNCONFIRMED', 'Owned runtime still exists after release');
+        await adapter.forgetRuntime();
+    });
+}

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/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

@@ -9,7 +9,8 @@
 直接 exec 为 pane PID 的原生 argv 核验及可选 Linux 持锁身份要求 **实际服务至少 1.4.306**；
 后台执行记录与用途迁移要求 **CLI / 实际服务均至少 1.4.307**；
 普通消息身份发送、持久回复及消息历史要求 **CLI / 实际服务均至少 1.4.308**；
-建议 CLI 与服务同步安装 1.4.308（既有接入命令的 CLI 最低仍为 1.4.301，诊断 CLI 最低为 1.4.305）。
+释放运行承载、稳定逻辑身份与恢复配置确认要求 **CLI / 实际服务均至少 1.4.309**；
+建议 CLI 与服务同步安装 1.4.309（既有接入命令的 CLI 最低仍为 1.4.301，诊断 CLI 最低为 1.4.305）。
 现有 `--session`、消息投递、任务报告与自动协作入口继续兼容；旧的
 `task create --integration` 仍表示代码集成子任务，新身份使用 `--principal`。
 
@@ -389,7 +390,7 @@ task 事件 `event_id` 与任务内事件 ID 一致，`respond.reply_to_event_id
 | `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,to_principal_id,integration_origin,response_kind,stored_at,content,metadata}` |
 | `message.delivery` | `{receipt}`：实际入队/远端接收/终端写入/后台回复保存阶段、失败、重试计数与时间，及明确回复 ID；不含快照或已读字段 |
-| `session.starting/binding_pending/ready/restoring/failed` | `{session}`：下节公开会话记录，失败包含 error_code |
+| `session.starting/binding_pending/ready/restoring/releasing/released/failed` | `{session}`：下节公开会话记录，失败包含 error_code |
 
 TD 在源记录提交后触发 journal 及订阅，journal 中的同一事件 ID 在重连重放时保持不变。
 新 consumer 从最早保留事件开始；接入方按 `event_id` 去重，**先持久写入 inbox，
@@ -438,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`。
@@ -526,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` 表示服务支持持久恢复诊断。
@@ -586,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.308",
+  "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,12 +1,12 @@
 {
   "schemaVersion": 1,
   "packageName": "termdock",
-  "version": "1.4.308",
+  "version": "1.4.309",
   "runtimeProtocolVersion": 1,
   "minimumDesktopVersion": "1.4.46",
   "nodeMajor": 22,
   "dependencyHash": "sha256-E9GDa4nrCXADRXdyPKufusZt6IcCr4m2mGdx5h34KMQ=",
-  "serverBundleHash": "sha256-KCZQLf7sIa26nzVvLZBZhHNcitDKANSYJdK523lF3qg=",
+  "serverBundleHash": "sha256-3rATyPEt6ztAvF1p3T03N1mo2A1qIKkVUePIG0xc53w=",
   "clientBundleHash": "sha256-Yh0fz4oTrM6A2pNHLYx+Y67/R7Wfa84cFlIPMrwAsfE=",
   "entrypoint": "dist/server/cli.js",
   "clientEntrypoint": "dist/client/index.html"