termdock 1.4.307 → 1.4.309

package/dist/server/agent/integrationServer.js

@@ -4,12 +4,20 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { homedir } from 'node:os';
 import { timingSafeEqual } from 'node:crypto';
-import { CollaborationError } from './collaborationProtocol.js';
+import { CollaborationError, resolveIdPrefix } from './collaborationProtocol.js';
 import { terminalMessage } from './collaborationStore.js';
 import { IntegrationStore, INTEGRATION_PROTOCOL, INTEGRATION_OPERATIONS, integrationError } from './integrationStore.js';
 import { IntegrationSessions, publicIntegrationSession } from './integrationSessions.js';
 import { getTermdockVersion } from '../utils/version.js';
 export function integrationSocketPath(port) { return path.join(homedir(), '.termdock', `integration-${port}.sock`); }
+function scopedId(input, ids, type) {
+    if (typeof input !== 'string')
+        integrationError(`INVALID_${type}_ID`, 'A message or member id is required');
+    const result = resolveIdPrefix([...new Set(ids)], input);
+    if (result.status !== 'ok')
+        integrationError(`${type}_${result.status === 'ambiguous' ? 'ID_AMBIGUOUS' : 'NOT_FOUND'}`, `No unique ${type.toLowerCase()} in this integration group`, result.status === 'ambiguous' ? 409 : 404);
+    return result.id;
+}
 /** A local authenticated API and push stream. It is never mounted on the
  * public HTTP application and does not reuse an integration's admin token. */
 export class IntegrationRuntime {
@@ -26,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();
         }
@@ -35,7 +44,7 @@ export class IntegrationRuntime {
         } };
         this.stops.push(options.messages.subscribe(changed), options.taskStore.subscribe(changed), this.sessions.subscribe(changed));
         const app = express();
-        app.use(express.json({ limit: '1mb' }));
+        app.use(express.json({ limit: '2mb' }));
         app.use((req, res, next) => {
             if (req.headers['x-termdock-integration-protocol'] !== String(INTEGRATION_PROTOCOL)) {
                 res.status(409).json({ ...this.error(new CollaborationError('INCOMPATIBLE_INTEGRATION_PROTOCOL', 'Unsupported integration protocol', 409)), protocol: INTEGRATION_PROTOCOL });
@@ -62,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();
@@ -103,11 +114,70 @@ export class IntegrationRuntime {
             const event = options.taskStore.integrationRequestEvent(p.id, input.idempotencyKey, task.id);
             return { task, event_id: event?.id ?? null, attempt_id: event?.attemptId ?? null, delivery_id: event?.deliveryId ?? null };
         }));
+        app.post('/send', run(req => {
+            const p = principal(req);
+            this.authorize(p, 'message.send', req.body?.group_id);
+            const group = this.group(p.groupId), raw = req.body ?? {};
+            if (raw.kind && raw.kind !== 'message')
+                integrationError('INTEGRATION_OPERATION_DENIED', 'Integration send uses ordinary messages only', 403);
+            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 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');
+            const messages = options.messages.send({ ...this.messageExtras(raw), groupId: p.groupId, fromSessionId: null,
+                integrationOrigin: this.origin(p, raw.origin), toSessionIds: recipients, kind: 'message', content: raw.message, threadId: thread });
+            this.sync();
+            return { ok: true, message_ids: messages.map(m => m.id), receipts: messages.map(m => options.messages.receipt(m.id)), ...options.messages.receipt(messages[0].id) };
+        }));
+        app.post('/reply', run(req => {
+            const p = principal(req);
+            this.authorize(p, 'message.send', req.body?.group_id);
+            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,
+                integrationOrigin: this.origin(p, raw.origin), toSessionIds: [target], kind: 'reply', content: raw.content, threadId: original.threadId, replyTo: original.id });
+            this.sync();
+            return { ok: true, ...options.messages.receipt(messages[0].id) };
+        }));
+        app.get('/message', run(req => {
+            const p = principal(req);
+            this.authorize(p, 'message.read', req.query.group);
+            const messages = options.messages.snapshotMessages().filter(m => m.groupId === p.groupId).sort((a, b) => a.sequence - b.sequence);
+            const after = req.query['after-id'] ? this.message(p, String(req.query['after-id'])) : null;
+            const limit = req.query.limit === undefined ? 50 : Number(req.query.limit);
+            if (!Number.isInteger(limit) || limit < 1 || limit > 200)
+                integrationError('INVALID_MESSAGE_LIMIT', 'limit must be 1..200');
+            const thread = req.query.thread ? scopedId(String(req.query.thread), messages.map(m => m.threadId), 'THREAD') : null;
+            const filtered = messages.filter(m => (!after || m.sequence > after.sequence) && (!thread || m.threadId === thread));
+            const page = [];
+            let bytes = 0;
+            for (const message of filtered.slice(0, limit)) {
+                const size = Buffer.byteLength(JSON.stringify(message));
+                if (page.length && bytes + size > 2 * 1024 * 1024)
+                    break;
+                page.push(message);
+                bytes += size;
+            }
+            return { messages: page.map(m => terminalMessage(m)), next_after_id: page.at(-1)?.id ?? after?.id ?? null, has_more: filtered.length > page.length, retention: 'retained_messages_only' };
+        }));
         app.get('/message/:id', run(req => {
-            const p = principal(req), message = options.messages.getMessage(req.params.id);
-            if (!message)
-                integrationError('MESSAGE_NOT_FOUND', 'Message does not exist', 404);
-            this.authorize(p, 'task.read', message.groupId);
+            const p = principal(req);
+            this.authorize(p, p.permissions.includes('message.read') ? 'message.read' : 'task.read');
+            const message = this.message(p, req.params.id);
             const receipt = options.messages.receipt(message.id);
             const { snapshot: _, ...diagnostic } = receipt;
             return { ok: true, ...diagnostic, ...(req.query.receipt_only === 'true' ? {} : { message: terminalMessage(message) }) };
@@ -121,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);
@@ -144,11 +215,13 @@ 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',
             background_task_records: true, task_purpose_configuration: true, explicit_execution_state: true,
+            integration_message_send: true, integration_message_reply: true, integration_message_history: true,
             permissions: INTEGRATION_OPERATIONS };
     }
     error(error) {
@@ -170,6 +243,18 @@ export class IntegrationRuntime {
             integrationError('TASK_NOT_FOUND', 'Task does not exist within this integration grant', 404);
         this.authorize(p, operation, task.groupId);
     }
+    message(p, id) {
+        const scoped = this.options.messages.snapshotMessages().filter(m => m.groupId === p.groupId);
+        const resolved = scopedId(id, scoped.map(m => m.id), 'MESSAGE');
+        return this.options.messages.getMessage(resolved);
+    }
+    messageExtras(raw) {
+        if (typeof raw.idempotency_key !== 'string' || !raw.idempotency_key.trim())
+            integrationError('IDEMPOTENCY_KEY_REQUIRED', 'Integration message mutations require an explicit idempotency key');
+        if (raw.task || raw.task_envelope || raw.metadata?.termdockTask)
+            integrationError('INTEGRATION_OPERATION_DENIED', 'Ordinary messages cannot forge task envelopes', 403);
+        return { idempotencyKey: raw.idempotency_key, responseKind: raw.response_kind, metadata: raw.metadata, expiresAt: raw.expires_at };
+    }
     origin(p, input) {
         const value = input && typeof input === 'object' ? input : {};
         if (Buffer.byteLength(JSON.stringify(value)) > 16384)
@@ -215,11 +300,16 @@ export class IntegrationRuntime {
                 if (groups.has(message.groupId)) {
                     const link = message.metadata?.termdockTask;
                     const context = { group_id: message.groupId, task_id: link?.taskId ?? null, attempt_id: link?.attemptId ?? null,
-                        reply_to_event_id: link?.replyToEventId ?? null, message_id: message.id, source: message.fromSessionId ? 'member' : 'system' };
+                        reply_to_event_id: link?.replyToEventId ?? null, message_id: message.id, source: message.integrationOrigin ? 'integration' : message.fromSessionId ? 'member' : 'system',
+                        actor: message.integrationOrigin ? { integration_id: message.integrationOrigin.integrationId } : message.fromSessionId ? { session_id: message.fromSessionId } : null,
+                        external_actor: message.integrationOrigin?.externalActor ?? null };
                     updates.push({ sourceKey: `message:${message.id}`, sourceVersion: '1', event: { ...context,
                             kind: message.kind === 'reply' ? 'message.reply' : 'message.queued', created_at: message.createdAt,
                             payload: { message_id: message.id, thread_id: message.threadId, reply_to: message.replyTo ?? null,
-                                from_session_id: message.fromSessionId, to_session_id: message.toSessionId, content: message.content, metadata: message.metadata ?? null } } });
+                                from_session_id: message.fromSessionId, to_session_id: message.toPrincipalId ? null : message.toSessionId,
+                                to_principal_id: message.toPrincipalId ?? null, integration_origin: message.integrationOrigin ?? null,
+                                response_kind: message.responseKind ?? null, stored_at: message.storedAt ?? null,
+                                content: message.content, metadata: message.metadata ?? null } } });
                     const { snapshot: _, ...receipt } = this.options.messages.receipt(message.id);
                     updates.push({ sourceKey: `message-status:${message.id}`, sourceVersion: JSON.stringify(receipt), event: {
                             ...context, kind: 'message.delivery', created_at: message.deliveredAt ?? message.createdAt, payload: { receipt }

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 = ['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();
+    });
+}