termdock 1.4.383 → 1.4.384

package/dist/server/agent/integrationJournal.js

@@ -0,0 +1,273 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { CollaborationError } from './collaborationProtocol.js';
+const segmentName = /^[a-f0-9-]{36}\.jsonl$/;
+const digest = (bytes) => createHash('sha256').update(bytes).digest('hex');
+/** File fsync precedes rename; directory fsync precedes reporting a commit. */
+export function atomicIntegrationWrite(file, write) {
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    const temporary = `${file}.${process.pid}.${randomUUID()}.tmp`;
+    let descriptor;
+    try {
+        descriptor = fs.openSync(temporary, 'wx', 0o600);
+        write(descriptor);
+        fs.fsyncSync(descriptor);
+        fs.closeSync(descriptor);
+        descriptor = undefined;
+        fs.renameSync(temporary, file);
+        const directory = fs.openSync(path.dirname(file), 'r');
+        try {
+            fs.fsyncSync(directory);
+        }
+        finally {
+            fs.closeSync(directory);
+        }
+    }
+    finally {
+        if (descriptor !== undefined)
+            fs.closeSync(descriptor);
+        fs.rmSync(temporary, { force: true });
+    }
+}
+export function atomicJson(file, value) {
+    atomicIntegrationWrite(file, descriptor => fs.writeFileSync(descriptor, JSON.stringify(value)));
+}
+function writeBuffers(file, parts) {
+    atomicIntegrationWrite(file, descriptor => {
+        let index = 0, offset = 0;
+        while (index < parts.length) {
+            const vectors = parts.slice(index, index + 512);
+            if (offset)
+                vectors[0] = vectors[0].subarray(offset);
+            let written;
+            try {
+                written = fs.writevSync(descriptor, vectors);
+            }
+            catch (error) {
+                if (error.code === 'EINTR')
+                    continue;
+                throw error;
+            }
+            if (written <= 0)
+                throw new Error('Integration segment write made no progress');
+            while (index < parts.length) {
+                const available = parts[index].length - offset;
+                if (written < available) {
+                    offset += written;
+                    break;
+                }
+                written -= available;
+                index++;
+                offset = 0;
+                if (!written)
+                    break;
+            }
+        }
+    });
+}
+/** Immutable segments become visible ONLY through the committed manifest.
+ * A failed/crashed append leaves the old manifest authoritative. Orphans are
+ * collected after a later commit, never replayed as committed events. */
+export class IntegrationJournal {
+    file;
+    segmentBytes;
+    directory;
+    segments = [];
+    legacy;
+    manifest;
+    uncertain = false;
+    committedEvents;
+    constructor(file, segmentBytes) {
+        this.file = file;
+        this.segmentBytes = segmentBytes;
+        this.directory = `${file}.segments`;
+    }
+    read() {
+        let raw;
+        try {
+            raw = fs.readFileSync(this.file);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        }
+        const document = JSON.parse(raw.toString('utf8'));
+        if (!document || !Array.isArray(document.principals) || !document.sources || !document.consumers || !document.sequences || !document.prunedThrough)
+            throw new Error('Invalid integration journal');
+        for (const [group, sequence] of Object.entries(document.sequences)) {
+            const floor = document.prunedThrough[group] ?? 0;
+            if (!Number.isSafeInteger(sequence) || sequence < 0 || !Number.isSafeInteger(floor) || floor < 0 || floor > sequence)
+                throw new Error('Invalid integration sequence metadata');
+        }
+        for (const value of Object.values(document.consumers))
+            if (!Number.isSafeInteger(value) || value < 0)
+                throw new Error('Invalid integration consumer watermark');
+        if (document.version === 1 && Array.isArray(document.events)) {
+            this.legacy = raw;
+            this.manifest = raw.toString('utf8');
+            return document;
+        }
+        if (document.version !== 2 || !Array.isArray(document.segments))
+            throw new Error('Invalid integration journal version');
+        const names = new Set(), events = [], previous = new Map();
+        for (const segment of document.segments) {
+            if (!segmentName.test(segment.name) || names.has(segment.name) || !Number.isSafeInteger(segment.bytes) || segment.bytes < 1
+                || !Number.isSafeInteger(segment.count) || segment.count < 1 || !/^[a-f0-9]{64}$/.test(segment.sha256))
+                throw new Error('Invalid integration segment descriptor');
+            names.add(segment.name);
+            const bytes = fs.readFileSync(path.join(this.directory, segment.name));
+            if (bytes.length !== segment.bytes || digest(bytes) !== segment.sha256 || bytes.at(-1) !== 10)
+                throw new Error('Integration segment integrity check failed');
+            const entries = bytes.toString('utf8').slice(0, -1).split('\n').map(line => JSON.parse(line));
+            if (entries.length !== segment.count)
+                throw new Error('Integration segment count mismatch');
+            for (const event of entries) {
+                if (!event || typeof event.group_id !== 'string' || typeof event.event_id !== 'string' || !Number.isSafeInteger(event.sequence)
+                    || event.sequence <= (previous.get(event.group_id) ?? 0) || event.sequence > (document.sequences[event.group_id] ?? 0))
+                    throw new Error('Invalid integration segment event');
+                previous.set(event.group_id, event.sequence);
+                events.push(event);
+            }
+            this.segments.push({ descriptor: segment, events: entries });
+        }
+        this.manifest = raw.toString('utf8');
+        this.committedEvents = events;
+        const { segments: _, version: _version, ...metadata } = document;
+        return { ...metadata, version: 1, events };
+    }
+    /** Migrates all existing events before any retention/byte reclamation. */
+    migrate(document, encode) {
+        if (this.legacy)
+            this.commit(document, encode);
+    }
+    pack(events, encode) {
+        const result = [];
+        let parts = [], chunk = [], bytes = 0;
+        const flush = () => {
+            if (!chunk.length)
+                return;
+            const descriptor = { name: `${randomUUID()}.jsonl`, bytes, count: chunk.length,
+                sha256: digest(Buffer.concat(parts)) };
+            writeBuffers(path.join(this.directory, descriptor.name), parts);
+            result.push({ descriptor, events: chunk });
+            parts = [];
+            chunk = [];
+            bytes = 0;
+        };
+        for (const event of events) {
+            const encoded = encode(event);
+            if (chunk.length && bytes + encoded.length + 1 > this.segmentBytes)
+                flush();
+            parts.push(encoded, Buffer.from('\n'));
+            chunk.push(event);
+            bytes += encoded.length + 1;
+        }
+        flush();
+        return result;
+    }
+    commit(document, encode) {
+        if (this.uncertain)
+            throw new CollaborationError('EVENT_COMMIT_UNCONFIRMED', 'Reopen integration storage to reconcile an uncertain manifest commit', 503);
+        // Detect another writer or a stale store before overwriting its ACK/identity.
+        let current;
+        try {
+            current = fs.readFileSync(this.file, 'utf8');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (current !== this.manifest)
+            throw new CollaborationError('EVENT_JOURNAL_CHANGED', 'Integration storage changed; reopen before writing', 503);
+        let next = this.segments;
+        if (document.events !== this.committedEvents) {
+            const retained = new Set(document.events), known = new Set();
+            next = [];
+            for (const segment of this.segments) {
+                for (const event of segment.events)
+                    known.add(event);
+                const kept = segment.events.filter(event => retained.has(event));
+                if (kept.length === segment.events.length)
+                    next.push(segment);
+                else
+                    next.push(...this.pack(kept, encode));
+            }
+            const added = document.events.filter(event => !known.has(event));
+            if (added.length) {
+                const tail = next.at(-1);
+                if (tail && tail.descriptor.bytes < this.segmentBytes) {
+                    next.pop();
+                    next.push(...this.pack([...tail.events, ...added], encode));
+                }
+                else
+                    next.push(...this.pack(added, encode));
+            }
+        }
+        const { version: _, events: _events, ...metadata } = document;
+        const manifest = { ...metadata, version: 2, segments: next.map(segment => segment.descriptor) };
+        const serialized = JSON.stringify(manifest);
+        if (this.legacy) {
+            // Never overwrite a previously created recovery copy.
+            const backup = `${this.file}.v1-backup`;
+            if (fs.existsSync(backup)) {
+                if (!fs.readFileSync(backup).equals(this.legacy))
+                    throw new Error('Existing integration migration backup differs');
+            }
+            else
+                atomicIntegrationWrite(backup, descriptor => fs.writeFileSync(descriptor, this.legacy));
+        }
+        try {
+            atomicIntegrationWrite(this.file, descriptor => fs.writeFileSync(descriptor, serialized));
+        }
+        catch (error) {
+            // rename may have happened before directory fsync failed. Neither claim
+            // success nor permit another write against an unknown in-memory version.
+            try {
+                this.uncertain = fs.readFileSync(this.file, 'utf8') !== this.manifest;
+            }
+            catch {
+                this.uncertain = true;
+            }
+            throw error;
+        }
+        this.manifest = serialized;
+        this.segments = next;
+        this.committedEvents = document.events;
+        this.legacy = undefined;
+        // GC failure cannot turn an already committed ACK into a reported failure.
+        try {
+            this.sweep();
+        }
+        catch { /* Next commit retries orphan collection. */ }
+    }
+    sweep() {
+        const keep = new Set(this.segments.map(segment => segment.descriptor.name));
+        let names;
+        try {
+            names = fs.readdirSync(this.directory);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                return;
+            throw error;
+        }
+        for (const name of names) {
+            if (segmentName.test(name) && !keep.has(name))
+                fs.unlinkSync(path.join(this.directory, name));
+            const temporary = name.match(/^[a-f0-9-]{36}\.jsonl\.(\d+)\.[a-f0-9-]{36}\.tmp$/);
+            if (temporary) {
+                try {
+                    process.kill(Number(temporary[1]), 0);
+                }
+                catch (error) {
+                    if (error.code === 'ESRCH')
+                        fs.unlinkSync(path.join(this.directory, name));
+                }
+            }
+        }
+    }
+    get metadataBytes() { return Buffer.byteLength(this.manifest ?? ''); }
+    get segmentCount() { return this.segments.length; }
+}

package/dist/server/agent/integrationServer.js

@@ -9,6 +9,7 @@ import { terminalMessage } from './collaborationStore.js';
 import { IntegrationStore, INTEGRATION_PROTOCOL, INTEGRATION_OPERATIONS, atomicJson, integrationError } from './integrationStore.js';
 import { IntegrationSessions, publicIntegrationSession } from './integrationSessions.js';
 import { getTermdockVersion } from '../utils/version.js';
+import { SessionAccessStore } from '../federation/sessionAccess.js';
 export function integrationSocketPath(port, home = homedir()) {
     const preferred = path.join(home, '.termdock', `integration-${port}.sock`);
     // Darwin's sockaddr_un is shorter than Linux's. Node can truncate a long
@@ -33,6 +34,7 @@ export class IntegrationRuntime {
     options;
     store;
     sessions;
+    sessionAccess;
     server;
     stops = [];
     streams = new Set();
@@ -46,8 +48,11 @@ export class IntegrationRuntime {
     releaseBatchRunning = false;
     constructor(options) {
         this.options = options;
-        this.store = new IntegrationStore(path.join(options.directory, 'integrations.json'));
+        this.store = new IntegrationStore(path.join(options.directory, 'integrations.json'), 10000, options.eventStorage);
         this.sessions = new IntegrationSessions(path.join(options.directory, 'integration-sessions.json'), options.sessions);
+        this.sessionAccess = new SessionAccessStore(path.join(options.directory, 'session-access.json'), (id, principalId) => {
+            return this.sessions.permitsSessionAccess(id, principalId) && this.store.permits(principalId, 'session.access');
+        });
         this.releaseBatchFile = path.join(options.directory, 'session-release-batches.json');
         try {
             const saved = JSON.parse(fs.readFileSync(this.releaseBatchFile, 'utf8'));
@@ -74,7 +79,8 @@ export class IntegrationRuntime {
                 this.sync();
             }
             catch (error) {
-                this.failStreams(error);
+                if (!this.capacityBlocked(error))
+                    this.failStreams(error);
                 this.scheduleRetry();
             }
         };
@@ -104,6 +110,19 @@ export class IntegrationRuntime {
             if (!expected.length || given.length !== expected.length || !timingSafeEqual(given, expected))
                 integrationError('INTEGRATION_ADMIN_REQUIRED', 'Local administration credential is required', 401);
         };
+        app.get('/admin/storage', run(req => {
+            admin(req);
+            return { ...this.store.storageStatus(),
+                related: { sessions: this.sessions.storageStatus(), tasks: options.taskStore.storageStatus(), messages: options.messages.storageStatus() } };
+        }));
+        app.get('/admin/consumers', run(req => { admin(req); return { consumers: this.store.consumerStatus() }; }));
+        app.post('/admin/consumers/retire', run(req => {
+            admin(req);
+            const body = req.body;
+            if (!body || typeof body !== 'object' || Array.isArray(body) || Object.keys(body).some(key => !['principal_id', 'consumer', 'expected_sequence', 'idempotency_key'].includes(key)))
+                integrationError('INVALID_CONSUMER_RETIREMENT', 'Specify principal_id, consumer, expected_sequence and idempotency_key only');
+            return this.store.retireConsumer(body.principal_id, body.consumer, body.expected_sequence, body.idempotency_key);
+        }));
         app.get('/admin/groups', run(req => { admin(req); return { groups: options.messages.listLocalGroupMetadata(req.query.include_archived === 'true') }; }));
         app.get('/admin/groups/:id', run(req => { admin(req); return { group: options.messages.getLocalGroupMetadata(req.params.id) }; }));
         app.post('/admin/groups/:id/rename', run(req => {
@@ -266,6 +285,30 @@ export class IntegrationRuntime {
             return { session: publicIntegrationSession(session) };
         }));
         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/access', run(async (req) => {
+            const p = principal(req);
+            this.authorize(p, 'session.access');
+            await this.sessions.get(p, req.params.id);
+            return this.sessionAccess.update(req.params.id, p.id, req.body);
+        }));
+        app.get('/sessions/:id/access-state', run(async (req) => {
+            const p = principal(req);
+            this.authorize(p, 'session.access');
+            const session = await this.sessions.get(p, req.params.id);
+            return { sessionId: session.session_id, ...this.sessionAccess.revision(session.session_id, p.id) };
+        }));
+        app.post('/sessions/:id/access-readers', run(async (req) => {
+            const p = principal(req);
+            this.authorize(p, 'session.access');
+            await this.sessions.get(p, req.params.id);
+            return this.sessionAccess.updateReaders(req.params.id, p.id, req.body);
+        }));
+        app.post('/sessions/:id/access-ticket', run(async (req) => {
+            const p = principal(req);
+            this.authorize(p, 'session.access');
+            await this.sessions.get(p, req.params.id);
+            return { ticket: this.sessionAccess.ticket(req.params.id, p.id, req.body?.deviceId, req.body?.readerId) };
+        }));
         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/retry-cold', run(async (req) => { const p = principal(req); this.authorize(p, 'session.create'); const session = await this.sessions.retryCold(p, req.params.id, req.body?.generation, 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) }; }));
@@ -284,10 +327,20 @@ export class IntegrationRuntime {
         }));
         app.post('/sessions/:id/rename', run(async (req) => { const p = principal(req); this.authorize(p, 'session.rename'); const session = await this.sessions.rename(p, req.params.id, req.body?.generation, req.body?.name, req.body?.idempotency_key); this.sync(); return { session: publicIntegrationSession(session) }; }));
         app.post('/sessions/:id/close', run(async (req) => { const p = principal(req); this.authorize(p, 'session.close'); const session = await this.sessions.closeSession(p, req.params.id, req.body?.generation, req.body?.idempotency_key); this.sync(); return { session: publicIntegrationSession(session) }; }));
+        app.delete('/sessions/:id', run(async (req) => { const p = principal(req); this.authorize(p, 'session.forget'); await this.sessions.forget(p, req.params.id, req.body?.generation); this.sync(); return { forgotten: true }; }));
         app.get('/events', run((req, res) => {
             const p = principal(req);
             this.authorize(p, 'events.read', req.query.group);
-            this.sync();
+            // Capacity backpressure must not prevent a consumer from draining and
+            // confirming the already committed suffix that releases that capacity.
+            try {
+                this.sync();
+            }
+            catch (error) {
+                if (!this.capacityBlocked(error))
+                    throw error;
+                this.scheduleRetry();
+            }
             this.stream(p, String(req.query.consumer ?? 'default'), req, res);
         }));
         app.post('/events/ack', run(req => {
@@ -303,9 +356,11 @@ export class IntegrationRuntime {
         this.server = createServer(app);
     }
     capabilities() {
-        return { integration_protocol: INTEGRATION_PROTOCOL, server_version: getTermdockVersion(), local_only: true,
-            integration_principal: true, group_scoped_permissions: true, durable_event_push: true,
+        return { integration_protocol: INTEGRATION_PROTOCOL, server_version: getTermdockVersion(), service_id: this.options.serviceId, local_only: true,
+            integration_principal: true, group_scoped_permissions: true, durable_event_push: true, session_access_tickets: true, session_access_readers: true,
+            session_access_exclusive: true, session_access_state: true,
             event_ack_semantics: 'durable_received', correlated_task_responses: true, accepted_task_comments: true,
+            segmented_event_storage: true, event_storage_diagnostics: true, explicit_consumer_retirement: true,
             idempotent_session_create: true, exact_session_restore: true, external_validation: false,
             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',
@@ -322,6 +377,7 @@ export class IntegrationRuntime {
             session_cold_retry: true, session_cold_retry_min_version: '1.4.314',
             session_rename: true, session_rename_min_version: '1.4.315',
             session_close: true, session_close_min_version: '1.4.315',
+            session_forget: true,
             session_close_diagnostics: true, session_close_diagnostics_min_version: '1.4.349',
             session_close_detached_registration: process.platform === 'linux', session_close_detached_registration_min_version: '1.4.349',
             admin_local_group_create: true, admin_local_group_create_min_version: '1.4.318',
@@ -549,7 +605,27 @@ export class IntegrationRuntime {
                         }
                     });
             updates.sort((a, b) => a.event.created_at - b.event.created_at);
-            this.store.append(updates);
+            // Group sequences are independent. A large/stalled group's backpressure
+            // must not roll back otherwise admissible groups in the same source scan.
+            const batches = new Map();
+            for (const update of updates) {
+                const batch = batches.get(update.event.group_id) ?? [];
+                batch.push(update);
+                batches.set(update.event.group_id, batch);
+            }
+            let blocked;
+            for (const batch of batches.values()) {
+                try {
+                    this.store.append(batch);
+                }
+                catch (error) {
+                    if (!this.capacityBlocked(error))
+                        throw error;
+                    blocked ??= error;
+                }
+            }
+            if (blocked)
+                throw blocked;
             this.syncedGroups = groupVersion;
         }
         catch (error) {
@@ -567,6 +643,7 @@ export class IntegrationRuntime {
         for (const stream of this.streams)
             stream.end(`${JSON.stringify(this.error(error))}\n`);
     }
+    capacityBlocked(error) { return error instanceof CollaborationError && error.code === 'EVENT_STORAGE_FULL'; }
     scheduleRetry() {
         if (this.retry)
             return;
@@ -665,7 +742,14 @@ export class IntegrationRuntime {
                 }
             });
         });
-        this.sync();
+        try {
+            this.sync();
+        }
+        catch (error) {
+            if (!this.capacityBlocked(error))
+                throw error;
+            this.scheduleRetry();
+        }
         await this.sessions.refreshAll();
         void this.pumpReleaseBatches();
     }

package/dist/server/agent/integrationSessions.js

@@ -2,7 +2,8 @@ import fs from 'node:fs';
 import { cleanMemberName } from './collaborationRoutes.js';
 import path from 'node:path';
 import { createHash, randomBytes, randomUUID } from 'node:crypto';
-import { atomicJson, integrationError } from './integrationStore.js';
+import { integrationError } from './integrationStore.js';
+import { JsonStorageBudget } from '../utils/jsonStorageBudget.js';
 import { SessionLifecycleCoordinator, assertMessageRuntime, assertReleaseFacts, assertReleaseGeneration } from './sessionLifecycle.js';
 import { resumeConfigurationFingerprint } from './sessionResumeConfiguration.js';
 import { NativeResumeOwnerError } from './nativeResumeOwner.js';
@@ -52,7 +53,6 @@ export function permittedCwd(profile, cwd) {
 /** Creation intent and exact launch configuration are durable before any input
  * enters a PTY. An ambiguous crash never starts another Agent automatically. */
 export class IntegrationSessions {
-    file;
     adapter;
     bindingTimeout;
     doc = { version: 1, sessions: [], requests: {} };
@@ -70,10 +70,11 @@ export class IntegrationSessions {
     observeAgain = false;
     observationTimer;
     stopped = false;
-    constructor(file, adapter, bindingTimeout = 120000) {
-        this.file = file;
+    storage;
+    constructor(file, adapter, bindingTimeout = 120000, options = {}) {
         this.adapter = adapter;
         this.bindingTimeout = bindingTimeout;
+        this.storage = new JsonStorageBudget(file, 'integration-sessions', 'TERMDOCK_SESSION_STORAGE_MAX_BYTES', 64 * 1024 * 1024, () => new CollaborationError('SESSION_STORAGE_FULL', 'New recovery operations exceed capacity; existing outcomes and close/release remain recordable. Configure TERMDOCK_SESSION_STORAGE_MAX_BYTES', 503), options);
         try {
             const doc = JSON.parse(fs.readFileSync(file, 'utf8'));
             if (doc.version !== 1 || !Array.isArray(doc.sessions) || !doc.requests)
@@ -122,10 +123,13 @@ export class IntegrationSessions {
     }
     subscribe(listener) { this.listeners.add(listener); return () => { this.listeners.delete(listener); }; }
     snapshot() { return structuredClone(this.doc.sessions); }
-    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);
+    permitsSessionAccess(id, principalId) {
+        const record = this.doc.sessions.find(s => s.session_id === id && s.principal_id === principalId);
+        return !!record && !['closed', 'closing', 'released', 'releasing'].includes(record.state);
+    }
+    storageStatus() { return this.storage.status(); }
+    save(admission = false) {
+        this.storage.write(JSON.stringify(this.doc), !admission);
         for (const listener of this.listeners) {
             try {
                 listener();
@@ -133,13 +137,13 @@ export class IntegrationSessions {
             catch { /* Durable session state is reconciled on restart. */ }
         }
     }
-    saveRecord(record) {
+    saveRecord(record, admission = false) {
         const before = this.doc.sessions;
         const seen = before.find(s => s.session_id === record.session_id)?.message_history_seen;
         this.doc.sessions = [...before.filter(s => s.session_id !== record.session_id), structuredClone({ ...record,
                 ...(seen ? { message_history_seen: true } : {}) })];
         try {
-            this.save();
+            this.save(admission);
         }
         catch (error) {
             this.doc.sessions = before;
@@ -159,6 +163,8 @@ export class IntegrationSessions {
         const previous = this.doc.requests[scoped];
         if (previous && previous.hash !== hash)
             integrationError('IDEMPOTENCY_CONFLICT', 'Key was already used for different session parameters', 409);
+        if (previous?.forgottenGroupId)
+            integrationError('SESSION_FORGOTTEN', 'The original session was permanently removed; use a new creation key', 409);
         return { scoped, hash, previous };
     }
     async create(principal, input) {
@@ -185,7 +191,7 @@ export class IntegrationSessions {
         record.startup_input = startupInput(record, now);
         this.doc.requests[request.scoped] = { hash: request.hash, sessionId: record.session_id };
         try {
-            this.saveRecord(record);
+            this.saveRecord(record, true);
         }
         catch (error) {
             delete this.doc.requests[request.scoped];
@@ -396,7 +402,7 @@ export class IntegrationSessions {
                 record.launch_diagnostics = beginLaunchDiagnostics(record.operation_id, record.generation, 'cold_retry');
                 this.doc.requests[request.scoped] = { hash: request.hash, sessionId: id, operationId: record.operation_id, generation: record.generation };
                 try {
-                    this.saveRecord(record);
+                    this.saveRecord(record, true);
                 }
                 catch (error) {
                     delete this.doc.requests[request.scoped];
@@ -441,7 +447,7 @@ export class IntegrationSessions {
                     integrationError('SESSION_IDENTITY_MISMATCH', 'Existing process does not prove the exact native binding', 409);
                 this.doc.requests[request.scoped] = { hash: request.hash, sessionId: id, operationId: record.operation_id, generation: record.generation };
                 try {
-                    this.save();
+                    this.save(true);
                 }
                 catch (error) {
                     delete this.doc.requests[request.scoped];
@@ -473,7 +479,7 @@ export class IntegrationSessions {
             record.startup_input = startupInput(record, Date.now());
             this.doc.requests[request.scoped] = { hash: request.hash, sessionId: id, operationId: record.operation_id, generation: record.generation };
             try {
-                this.saveRecord(record);
+                this.saveRecord(record, true);
             }
             catch (error) {
                 delete this.doc.requests[request.scoped];
@@ -574,7 +580,7 @@ export class IntegrationSessions {
             record.rename_pending = true;
             this.doc.requests[request.scoped] = { hash: request.hash, sessionId: id, operationId: record.operation_id, generation: record.generation };
             try {
-                this.saveRecord(record);
+                this.saveRecord(record, true);
             }
             catch (error) {
                 delete this.doc.requests[request.scoped];
@@ -659,6 +665,35 @@ export class IntegrationSessions {
             }
         }));
     }
+    /** Remove a closed recovery descriptor, retaining only idempotency tombstones.
+     * Native provider history and audit events are deliberately outside this API. */
+    async forget(principal, id, generation) {
+        return this.lifecycle.run(id, async () => {
+            const record = this.doc.sessions.find(s => s.session_id === id && s.principal_id === principal.id && s.group_id === principal.groupId);
+            if (!record) {
+                if (Object.entries(this.doc.requests).some(([key, value]) => key.startsWith(principal.id + ':') && value.sessionId === id
+                    && value.forgottenGroupId === principal.groupId && value.generation === generation))
+                    return;
+                integrationError('INTEGRATION_SESSION_NOT_FOUND', 'Session is not owned by this integration', 404);
+            }
+            assertReleaseGeneration(record, generation);
+            if (record.state !== 'closed' || record.close_intent || record.terminal_binding || record.runtime_present !== false
+                || !this.adapter.runtimePresent || await this.adapter.runtimePresent(record)) {
+                integrationError('SESSION_NOT_CLOSED', 'Confirm a completed close before removing its recovery descriptor', 409);
+            }
+            this.assertManagementIdle(record);
+            const before = this.doc;
+            this.doc = { ...before, sessions: before.sessions.filter(s => s.session_id !== id), requests: Object.fromEntries(Object.entries(before.requests).map(([key, value]) => [key, key.startsWith(principal.id + ':') && value.sessionId === id
+                        ? { hash: value.hash, sessionId: id, generation, forgottenGroupId: principal.groupId } : value])) };
+            try {
+                this.save();
+            }
+            catch (error) {
+                this.doc = before;
+                throw error;
+            }
+        });
+    }
     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]);