termdock 1.4.308 → 1.4.310

package/dist/server/agent/integrationCli.js

@@ -8,6 +8,26 @@ 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
+  clear-startup-input <TD-session-id> --generation <N>
+    Administrator removes this session's saved screen conditions and disables
+    inheritance on later restores; original identity/launch/history are preserved.
+    Pending messages may then use the ordinary delivery worker; delivered bodies
+    are never replayed. No Agent restart, resize, RPC or readiness claim.
+    The generation increments once; read session get for the new generation and
+    startup_input_disabled=true. Repeating with the old generation is rejected.
+    Minimum CLI/running service 1.4.310; session_startup_input_clear=true.
+    Errors: SESSION_STARTUP_INPUT_CLEAR_UNSUPPORTED, INVALID_SESSION_GENERATION,
+    SESSION_GENERATION_MISMATCH, SESSION_OPERATION_IN_PROGRESS,
+    INTEGRATION_SESSION_NOT_FOUND. Profile policy update alone keeps old snapshots.
+  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 +83,42 @@ export async function runIntegrationAdmin(argv, port, adminToken, write) {
             return 0;
         }
         const socketPath = integrationSocketPath(port);
+        if (action === 'clear-startup-input') {
+            const id = argv[1];
+            if (argv.length !== 4 || !id || !/^[a-zA-Z0-9._-]{1,80}$/.test(id) || argv[2] !== '--generation'
+                || !/^[1-9][0-9]*$/.test(argv[3]) || !Number.isSafeInteger(Number(argv[3]))) {
+                throw new Error('Usage: td integration clear-startup-input <TD-session-id> --generation <positive integer>');
+            }
+            const capabilities = parsed(await request(socketPath, 'GET', '/admin/capabilities', undefined, headers(undefined, adminToken)));
+            if (capabilities.session_startup_input_clear !== true)
+                throw new CollaborationError('SESSION_STARTUP_INPUT_CLEAR_UNSUPPORTED', 'CLI and running service must be at least 1.4.310', 409);
+            write(JSON.stringify(parsed(await request(socketPath, 'POST', `/admin/sessions/${encodeURIComponent(id)}/startup-input/clear`, { generation: Number(argv[3]) }, headers(undefined, adminToken)))));
+            return 0;
+        }
+        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 +217,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,14 @@ 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.post('/admin/sessions/:id/startup-input/clear', run(async (req) => {
+            admin(req);
+            const session = await this.sessions.clearStartupInput(req.params.id, req.body?.generation);
+            this.sync();
+            return { session: publicIntegrationSession(session) };
+        }));
         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 +129,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 +150,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 +197,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 +221,9 @@ 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',
+            session_startup_input_clear: true, session_startup_input_clear_min_version: '1.4.310',
             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) {
@@ -12,6 +14,8 @@ export function integrationLaunchCommand(record, restore) {
     return `cd -- ${quote(record.cwd)} && ${[record.profile.executable, ...args].map(quote).join(' ')}`;
 }
 function startupInput(record, now) {
+    if (record.startup_input_disabled)
+        return undefined;
     const condition = record.startup_condition ?? record.profile.startupInput;
     return condition ? { state: 'pending', deadline: now + (condition.timeoutMs ?? 120000), matched_since: null, observed_at: null } : undefined;
 }
@@ -50,7 +54,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 +75,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 +98,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 +153,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 +170,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 +216,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,16 +297,23 @@ 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();
             record.deadline = Date.now() + this.bindingTimeout;
             record.updated_at = Date.now();
             record.restore_diagnostics = undefined;
-            if (!record.profile.startupInput && !record.startup_condition)
+            if (!record.startup_input_disabled && !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 +324,156 @@ 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 clearStartupInput(id, generation) {
+        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) || record.operation_uncertain || ['starting', 'restoring', 'binding_pending', 'releasing'].includes(record.state)) {
+                integrationError('SESSION_OPERATION_IN_PROGRESS', 'Resolve the current lifecycle operation before clearing startup input conditions', 409);
+            }
+            if (record.startup_input_disabled && !record.profile.startupInput && !record.startup_condition && !record.startup_input)
+                return record;
+            delete record.profile.startupInput;
+            delete record.startup_condition;
+            delete record.startup_input;
+            record.startup_input_disabled = true;
+            record.generation = generation + 1;
+            record.updated_at = Date.now();
+            this.saveRecord(record);
+            return record;
+        });
+    }
+    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 +487,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 +551,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', 'Operation requires the generation returned by session get');
+    if (generation !== (record.generation ?? 1))
+        fail('SESSION_GENERATION_MISMATCH', 'Session generation changed; read its current state before retrying');
+}
+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();
+    });
+}