termdock 1.4.298 → 1.4.300

package/dist/server/agent/integrationServer.js

@@ -0,0 +1,326 @@
+import express from 'express';
+import { createServer } from 'node:http';
+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 { terminalMessage } from './collaborationStore.js';
+import { IntegrationStore, INTEGRATION_PROTOCOL, 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`); }
+/** 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 {
+    options;
+    store;
+    sessions;
+    server;
+    stops = [];
+    streams = new Set();
+    sent = new Map();
+    syncing = false;
+    retry;
+    constructor(options) {
+        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);
+        const changed = () => { try {
+            this.sync();
+        }
+        catch (error) {
+            this.failStreams(error);
+            this.scheduleRetry();
+        } };
+        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((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 });
+                return;
+            }
+            next();
+        });
+        const run = (handler) => async (req, res) => {
+            try {
+                const value = await handler(req, res);
+                if (!res.headersSent)
+                    res.json(value);
+            }
+            catch (error) {
+                res.status(error instanceof CollaborationError ? error.httpStatus : 500).json(this.error(error));
+            }
+        };
+        const principal = (req) => this.store.authenticate(String(req.headers['x-termdock-integration-id'] ?? ''), String(req.headers.authorization ?? '').replace(/^Bearer /, ''));
+        const admin = (req) => {
+            const given = Buffer.from(String(req.headers['x-termdock-local-token'] ?? '')), expected = Buffer.from(options.adminToken ?? '');
+            if (!expected.length || given.length !== expected.length || !timingSafeEqual(given, expected))
+                integrationError('INTEGRATION_ADMIN_REQUIRED', 'Local administration credential is required', 401);
+        };
+        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/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();
+        }
+        catch {
+            this.scheduleRetry();
+        } return { id: provisioned.principal.id, token: provisioned.token, protocol: INTEGRATION_PROTOCOL }; }));
+        app.post('/admin/principals/:id/revoke', run(req => { admin(req); this.store.revoke(req.params.id); return { ok: true }; }));
+        app.get('/capabilities', run(req => { const p = principal(req); return { ...this.capabilities(), principal: { id: p.id, group_id: p.groupId, permissions: p.permissions, launch_profiles: p.launchProfiles.map(profile => ({ id: profile.id, agent_slug: profile.agentSlug, cwd_roots: profile.cwdRoots })) } }; }));
+        app.get('/tasks', run(req => { const p = principal(req); this.authorize(p, 'task.read', req.query.group); return { tasks: options.tasks.list(p.groupId, null) }; }));
+        app.get('/tasks/:id', run(async (req) => { const p = principal(req); this.taskPermission(p, req.params.id, 'task.read'); return { task: await options.tasks.get(req.params.id, null) }; }));
+        app.post('/tasks', run(async (req) => {
+            const p = principal(req), raw = req.body?.input ?? {};
+            this.authorize(p, 'task.create', raw.groupId);
+            if (raw.managed || raw.parentTaskId || raw.dependsOn?.length || raw.coordinatorSessionId || raw.reviewerSessionIds?.length || raw.integration)
+                integrationError('INTEGRATION_OPERATION_DENIED', 'Integration creates ordinary standalone tasks only', 403);
+            const input = { idempotencyKey: raw.idempotencyKey, groupId: p.groupId, title: raw.title, spec: raw.spec,
+                constraints: raw.constraints, acceptance: raw.acceptance, assignee: raw.assigneeSessionId ? options.peers.taskMember(String(raw.assigneeSessionId)) : undefined };
+            if (input.assignee)
+                this.authorize(p, 'task.assign');
+            const task = await options.tasks.create(input, null, this.origin(p, req.body?.origin));
+            this.sync();
+            return { task };
+        }));
+        app.post('/tasks/:id', run(async (req) => {
+            const p = principal(req), raw = req.body?.input ?? {};
+            const permissions = { assign: 'task.assign', comment: 'task.comment', revise: 'task.revise', answer: 'task.answer' };
+            const permission = permissions[raw.kind];
+            if (!permission)
+                integrationError('INTEGRATION_OPERATION_DENIED', 'Operation requires a user or terminal member', 403);
+            this.taskPermission(p, req.params.id, permission);
+            const input = { kind: raw.kind, idempotencyKey: raw.idempotencyKey, content: raw.content,
+                expectedRevision: raw.expectedRevision, decisionId: raw.decisionId,
+                assignee: raw.assigneeSessionId ? options.peers.taskMember(String(raw.assigneeSessionId)) : undefined };
+            const task = await options.tasks.apply(req.params.id, input, null, this.origin(p, req.body?.origin));
+            this.sync();
+            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.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 receipt = options.messages.receipt(message.id);
+            const { snapshot: _, ...diagnostic } = receipt;
+            return { ok: true, ...diagnostic, ...(req.query.receipt_only === 'true' ? {} : { message: terminalMessage(message) }) };
+        }));
+        app.post('/sessions', run(async (req) => {
+            const p = principal(req);
+            this.authorize(p, 'session.create', req.body?.group_id);
+            const session = await this.sessions.create(p, { profile: req.body?.launch_profile, cwd: req.body?.cwd, idempotencyKey: req.body?.idempotency_key });
+            this.sync();
+            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/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.get('/events', run((req, res) => {
+            const p = principal(req);
+            this.authorize(p, 'events.read', req.query.group);
+            this.sync();
+            this.stream(p, String(req.query.consumer ?? 'default'), req, res);
+        }));
+        app.post('/events/ack', run(req => {
+            const p = principal(req);
+            this.authorize(p, 'events.read');
+            const cursor = String(req.body?.cursor ?? ''), consumer = String(req.body?.consumer ?? 'default');
+            const sequence = this.store.cursorSequence(p.groupId, cursor);
+            if (sequence > (this.sent.get(`${p.id}:${p.groupId}:${consumer}`) ?? -1))
+                integrationError('EVENT_ACK_NOT_SENT', 'Subscribe and durably receive the continuous prefix before acknowledging', 409);
+            return this.store.ack(p, consumer, cursor);
+        }));
+        app.use((_error, _req, res, _next) => { res.status(400).json(this.error(new CollaborationError('INVALID_REQUEST', 'Invalid integration request', 400))); });
+        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,
+            event_ack_semantics: 'durable_received', correlated_task_responses: true, accepted_task_comments: true,
+            idempotent_session_create: true, exact_session_restore: true, external_validation: false,
+            permissions: ['task.read', 'task.create', 'task.assign', 'task.comment', 'task.revise', 'task.answer', 'events.read', 'session.create', 'session.read', 'session.restore'] };
+    }
+    error(error) {
+        return { type: 'error', ok: false, code: error instanceof CollaborationError ? error.code : 'INTEGRATION_INTERNAL_ERROR',
+            error: error instanceof CollaborationError ? error.message : 'Integration operation failed', retryable: !(error instanceof CollaborationError) || error.httpStatus >= 500 };
+    }
+    group(id) {
+        const group = typeof id === 'string' ? this.options.messages.getGroup(id) : null;
+        if (!group || group.deleted)
+            integrationError('TASK_GROUP_NOT_FOUND', 'A live group is required', 404);
+        if (group.federated)
+            integrationError('INTEGRATION_LOCAL_ONLY', 'First integration protocol uses a local collaboration group', 409);
+        return group;
+    }
+    authorize(p, operation, group) { this.store.authorize(p, operation, group === undefined ? p.groupId : String(group)); this.group(p.groupId); }
+    taskPermission(p, id, operation) {
+        const task = this.options.taskStore.get(id);
+        if (!task || task.groupId !== p.groupId)
+            integrationError('TASK_NOT_FOUND', 'Task does not exist within this integration grant', 404);
+        this.authorize(p, operation, task.groupId);
+    }
+    origin(p, input) {
+        const value = input && typeof input === 'object' ? input : {};
+        if (Buffer.byteLength(JSON.stringify(value)) > 16384)
+            integrationError('INVALID_SOURCE_METADATA', 'Source metadata exceeds 16 KiB');
+        if (value.externalActor !== undefined && (!value.externalActor || typeof value.externalActor !== 'object' || Array.isArray(value.externalActor)))
+            integrationError('INVALID_SOURCE_METADATA', 'externalActor must be an object');
+        if (value.metadata !== undefined && (!value.metadata || typeof value.metadata !== 'object' || Array.isArray(value.metadata)))
+            integrationError('INVALID_SOURCE_METADATA', 'metadata must be an object');
+        return { integrationId: p.id, source: typeof value.source === 'string' ? value.source.slice(0, 128) : 'integration',
+            ...(value.externalActor ? { externalActor: value.externalActor } : {}),
+            ...(typeof value.externalMessageId === 'string' ? { externalMessageId: value.externalMessageId.slice(0, 512) } : {}),
+            ...(value.metadata ? { metadata: value.metadata } : {}) };
+    }
+    sync() {
+        if (this.syncing)
+            return;
+        this.syncing = true;
+        try {
+            const groups = new Set(this.store.policies().filter(p => !p.revoked).map(p => p.groupId)), updates = [];
+            if (!groups.size)
+                return;
+            for (const task of this.options.taskStore.snapshot())
+                if (groups.has(task.groupId)) {
+                    for (const event of task.events)
+                        updates.push({ sourceKey: `task:${task.id}:${event.id}`, sourceVersion: '1', eventId: event.id, event: {
+                                group_id: task.groupId, kind: `task.${event.kind}`, created_at: event.createdAt, task_id: task.id, attempt_id: event.attemptId,
+                                artifact_id: event.artifactId ?? null, reply_to_event_id: event.replyToEventId ?? null,
+                                source: event.source ?? (event.actor ? 'member' : 'user'), actor: event.actor, external_actor: event.origin?.externalActor ?? null, payload: { event }
+                            } });
+                    for (const artifact of task.artifacts)
+                        if (artifact.kind === 'result')
+                            updates.push({ sourceKey: `artifact:${artifact.id}`, sourceVersion: '1', event: {
+                                    group_id: task.groupId, kind: 'task.result', created_at: artifact.createdAt, task_id: task.id, attempt_id: artifact.attemptId,
+                                    artifact_id: artifact.id, source: 'member', actor: artifact.actor, payload: { artifact }
+                                } });
+                    for (const delivery of task.deliveries)
+                        updates.push({ sourceKey: `task-delivery:${delivery.id}`, sourceVersion: JSON.stringify(delivery), event: {
+                                group_id: task.groupId, kind: 'task.delivery', created_at: delivery.deliveredAt ?? task.updatedAt,
+                                task_id: task.id, attempt_id: delivery.attemptId, message_id: delivery.messageId, source: 'system', payload: { delivery }
+                            } });
+                }
+            for (const message of this.options.messages.snapshotMessages())
+                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' };
+                    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 } } });
+                    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 }
+                        } });
+                }
+            for (const session of this.sessions.snapshot())
+                if (groups.has(session.group_id))
+                    updates.push({ sourceKey: `session:${session.session_id}`, sourceVersion: JSON.stringify(publicIntegrationSession(session)), event: {
+                            group_id: session.group_id, kind: `session.${session.state}`, created_at: session.updated_at, source: 'system', actor: { integration_id: session.principal_id }, payload: { session: publicIntegrationSession(session) }
+                        } });
+            updates.sort((a, b) => a.event.created_at - b.event.created_at);
+            this.store.append(updates);
+        }
+        finally {
+            this.syncing = false;
+        }
+    }
+    failStreams(error) {
+        for (const stream of this.streams)
+            stream.end(`${JSON.stringify(this.error(error))}\n`);
+    }
+    scheduleRetry() {
+        if (this.retry)
+            return;
+        this.retry = setTimeout(() => { this.retry = undefined; try {
+            this.sync();
+        }
+        catch {
+            this.scheduleRetry();
+        } }, 1000);
+        this.retry.unref();
+    }
+    stream(p, consumer, req, res) {
+        let cursor, pumping = false, closed = false;
+        const key = `${p.id}:${p.groupId}:${consumer}`;
+        // Resolve the initial cursor before sending headers so retention gaps
+        // and bad consumer names are ordinary machine-readable HTTP errors.
+        const initial = this.store.page(p, consumer);
+        cursor = initial.cursor;
+        res.setHeader('Content-Type', 'application/x-ndjson');
+        res.setHeader('Cache-Control', 'no-store');
+        res.flushHeaders();
+        this.streams.add(res);
+        const stop = this.store.subscribe(() => pump());
+        const cleanup = () => { closed = true; stop(); clearInterval(heartbeat); this.streams.delete(res); };
+        const pump = () => {
+            if (pumping || closed)
+                return;
+            pumping = true;
+            try {
+                this.authorize(p, 'events.read');
+                for (;;) {
+                    const page = this.store.page(p, consumer, cursor);
+                    if (!page.events.length)
+                        break;
+                    for (const event of page.events) {
+                        if (res.writableLength > 1024 * 1024)
+                            integrationError('EVENT_CONSUMER_SLOW', 'Reconnect from the last acknowledged cursor', 503);
+                        res.write(`${JSON.stringify({ type: 'event', ...event })}\n`);
+                        cursor = event.cursor;
+                        this.sent.set(key, Math.max(this.sent.get(key) ?? 0, event.sequence));
+                    }
+                }
+            }
+            catch (error) {
+                res.end(`${JSON.stringify(this.error(error))}\n`);
+                cleanup();
+            }
+            finally {
+                pumping = false;
+            }
+        };
+        const heartbeat = setInterval(() => { pump(); if (!closed)
+            res.write(`${JSON.stringify({ type: 'heartbeat', ack_semantics: 'durable_received' })}\n`); }, 15000);
+        heartbeat.unref();
+        res.once('close', cleanup);
+        req.once('aborted', cleanup);
+        pump();
+    }
+    async listen() {
+        fs.mkdirSync(path.dirname(this.options.socketPath), { recursive: true, mode: 0o700 });
+        // A stale socket may be removed only after proving no listener exists.
+        if (fs.existsSync(this.options.socketPath)) {
+            const { createConnection } = await import('node:net');
+            const active = await new Promise((resolve, reject) => {
+                const socket = createConnection(this.options.socketPath);
+                socket.once('connect', () => { socket.destroy(); resolve(true); });
+                socket.once('error', (error) => { socket.destroy(); if (['ECONNREFUSED', 'ENOENT'].includes(error.code ?? ''))
+                    resolve(false);
+                else
+                    reject(error); });
+            });
+            if (active)
+                integrationError('INTEGRATION_SOCKET_IN_USE', 'Another integration service owns this socket', 409);
+            if (!fs.lstatSync(this.options.socketPath).isSocket())
+                integrationError('INTEGRATION_SOCKET_INVALID', 'Refusing to replace a non-socket file');
+            fs.unlinkSync(this.options.socketPath);
+        }
+        await new Promise((resolve, reject) => { this.server.once('error', reject); this.server.listen(this.options.socketPath, () => { this.server.removeListener('error', reject); fs.chmodSync(this.options.socketPath, 0o600); resolve(); }); });
+        this.sync();
+        await this.sessions.refreshAll();
+    }
+    async close() {
+        for (const stop of this.stops)
+            stop();
+        if (this.retry)
+            clearTimeout(this.retry);
+        this.sessions.close();
+        for (const stream of this.streams)
+            stream.destroy();
+        await new Promise(resolve => this.server.close(() => resolve()));
+    }
+}

package/dist/server/agent/integrationSessions.js

@@ -0,0 +1,296 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import { atomicJson, integrationError } from './integrationStore.js';
+/** Quote each configured argument as literal shell data, including paths. */
+export function integrationLaunchCommand(record, restore) {
+    const launchArgs = record.profile.argv.map(arg => arg === '{cwd}' ? record.cwd : arg);
+    const args = restore ? record.profile.resumeArgv.flatMap(arg => arg === '{launchArgs}' ? launchArgs
+        : [arg === '{sessionId}' ? record.agent_native_session_id : arg === '{cwd}' ? record.cwd : arg]) : launchArgs;
+    const quote = (value) => "'" + value.replaceAll("'", "'\\''") + "'";
+    return `cd -- ${quote(record.cwd)} && ${[record.profile.executable, ...args].map(quote).join(' ')}`;
+}
+export function publicIntegrationSession(record) {
+    const { profile: _, deadline: _deadline, launch_submitted: _submitted, ...publicRecord } = record;
+    return publicRecord;
+}
+export function permittedCwd(profile, cwd) {
+    if (typeof cwd !== 'string' || !path.isAbsolute(cwd) || /[\x00-\x1f\x7f]/.test(cwd))
+        integrationError('SESSION_CWD_DENIED', 'cwd must be absolute', 403);
+    let real;
+    try {
+        real = fs.realpathSync(cwd);
+        if (/[\x00-\x1f\x7f]/.test(real) || !fs.statSync(real).isDirectory())
+            throw new Error();
+    }
+    catch {
+        return integrationError('SESSION_CWD_MISSING', 'Task working directory must exist');
+    }
+    if (!profile.cwdRoots.some(root => { try {
+        const relative = path.relative(fs.realpathSync(root), real);
+        return !relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative);
+    }
+    catch {
+        return false;
+    } }))
+        integrationError('SESSION_CWD_DENIED', 'Working directory is outside the configured roots', 403);
+    return real;
+}
+/** 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: {} };
+    pending = new Map();
+    listeners = new Set();
+    restoring = new Set();
+    timers = new Set();
+    stopObservation;
+    observing = false;
+    observeAgain = false;
+    constructor(file, adapter, bindingTimeout = 120000) {
+        this.file = file;
+        this.adapter = adapter;
+        this.bindingTimeout = bindingTimeout;
+        try {
+            const doc = JSON.parse(fs.readFileSync(file, 'utf8'));
+            if (doc.version !== 1 || !Array.isArray(doc.sessions) || !doc.requests)
+                throw new Error('Invalid integration session store');
+            this.doc = doc;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        for (const record of this.doc.sessions)
+            if (['starting', 'restoring', 'binding_pending'].includes(record.state))
+                this.scheduleRefresh(record);
+        this.stopObservation = adapter.subscribe(() => { void this.refreshAll().catch(() => { }); });
+    }
+    scheduleRefresh(record) {
+        const timer = setTimeout(() => { this.timers.delete(timer); void this.refresh(record.session_id).catch(() => { }); }, Math.max(1, record.deadline - Date.now() + 5));
+        timer.unref();
+        this.timers.add(timer);
+    }
+    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();
+        }
+        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)];
+        try {
+            this.save();
+        }
+        catch (error) {
+            this.doc.sessions = before;
+            throw error;
+        }
+    }
+    lookup(principal, id) {
+        const record = this.doc.sessions.find(s => s.session_id === id && s.group_id === principal.groupId && s.principal_id === principal.id);
+        if (!record)
+            integrationError('INTEGRATION_SESSION_NOT_FOUND', 'Session is not owned by this integration', 404);
+        return structuredClone(record);
+    }
+    request(principal, key, input) {
+        if (!key || typeof key !== 'string' || key.length > 256)
+            integrationError('INVALID_IDEMPOTENCY_KEY', 'An idempotency key is required');
+        const scoped = `${principal.id}:${key}`, hash = createHash('sha256').update(JSON.stringify(input)).digest('hex');
+        const previous = this.doc.requests[scoped];
+        if (previous && previous.hash !== hash)
+            integrationError('IDEMPOTENCY_CONFLICT', 'Key was already used for different session parameters', 409);
+        return { scoped, hash, previous };
+    }
+    async create(principal, input) {
+        const request = this.request(principal, input.idempotencyKey, ['create', input.profile, input.cwd]);
+        if (request.previous)
+            return this.pending.get(request.previous.sessionId) ?? this.get(principal, request.previous.sessionId);
+        const profile = principal.launchProfiles.find(p => p.id === input.profile);
+        if (!profile)
+            integrationError('LAUNCH_PROFILE_DENIED', 'Profile is not allowed by this integration', 403);
+        const cwd = permittedCwd(profile, input.cwd);
+        try {
+            fs.accessSync(profile.executable, fs.constants.X_OK);
+        }
+        catch {
+            return integrationError('LAUNCHER_UNAVAILABLE', 'Configured executable is not available');
+        }
+        if (this.doc.sessions.length >= 2000)
+            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),
+            created_at: now, updated_at: now, deadline: now + this.bindingTimeout, launch_submitted: false };
+        this.doc.requests[request.scoped] = { hash: request.hash, sessionId: record.session_id };
+        try {
+            this.saveRecord(record);
+        }
+        catch (error) {
+            delete this.doc.requests[request.scoped];
+            throw error;
+        }
+        return this.launch(record, false);
+    }
+    launch(record, restoring) {
+        const promise = (async () => {
+            try {
+                // Store intent before launching. A failed persistence cannot execute.
+                record.launch_submitted = true;
+                this.saveRecord(record);
+                const prepared = (binding) => { record.terminal_binding = binding; this.saveRecord(record); };
+                if (restoring)
+                    await this.adapter.restore(record, prepared);
+                else
+                    await this.adapter.create(record, prepared);
+                await this.refresh(record.session_id);
+                this.scheduleRefresh(record);
+            }
+            catch (error) {
+                const current = this.doc.sessions.find(s => s.session_id === record.session_id);
+                const code = error.code;
+                this.saveRecord({ ...current, state: 'failed', error_code: typeof code === 'string' ? code : 'SESSION_LAUNCH_FAILED', updated_at: Date.now() });
+            }
+            return structuredClone(this.doc.sessions.find(s => s.session_id === record.session_id));
+        })().finally(() => this.pending.delete(record.session_id));
+        this.pending.set(record.session_id, promise);
+        return promise;
+    }
+    async get(principal, id) { this.lookup(principal, id); await this.refresh(id); return this.lookup(principal, id); }
+    async restore(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))
+            integrationError('SESSION_OPERATION_IN_PROGRESS', 'Another session operation is in progress', 409);
+        this.restoring.add(id);
+        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))
+                integrationError('LAUNCH_PROFILE_DENIED', 'Original launch profile is no longer authorized', 403);
+            permittedCwd(record.profile, record.cwd);
+            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 };
+                try {
+                    this.save();
+                }
+                catch (error) {
+                    delete this.doc.requests[request.scoped];
+                    throw error;
+                }
+                return record;
+            }
+            if (['starting', 'restoring', 'binding_pending'].includes(record.state))
+                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);
+            record.state = 'restoring';
+            record.error_code = null;
+            record.operation_id = randomUUID();
+            record.deadline = Date.now() + this.bindingTimeout;
+            record.updated_at = Date.now();
+            this.doc.requests[request.scoped] = { hash: request.hash, sessionId: id };
+            try {
+                this.saveRecord(record);
+            }
+            catch (error) {
+                delete this.doc.requests[request.scoped];
+                throw error;
+            }
+            return await this.launch(record, true);
+        }
+        finally {
+            this.restoring.delete(id);
+        }
+    }
+    async refresh(id) {
+        const record = structuredClone(this.doc.sessions.find(s => s.session_id === id));
+        if (!record)
+            return;
+        let observed;
+        try {
+            observed = await this.adapter.inspect(record);
+        }
+        catch (error) {
+            const current = this.doc.sessions.find(s => s.session_id === id);
+            if (JSON.stringify(current) !== JSON.stringify(record))
+                return;
+            const code = error.code;
+            if (record.state !== 'failed' || record.error_code !== code)
+                this.saveRecord({ ...record, state: 'failed', error_code: typeof code === 'string' ? code : 'SESSION_OBSERVATION_FAILED', updated_at: Date.now() });
+            return;
+        }
+        const next = { ...record };
+        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';
+        }
+        else if (observed.running && observed.agentSlug !== record.agent_slug) {
+            next.state = 'failed';
+            next.error_code = 'SESSION_IDENTITY_MISMATCH';
+        }
+        else if (observed.running && observed.nativeId) {
+            if (record.agent_native_session_id && record.agent_native_session_id !== observed.nativeId) {
+                next.state = 'failed';
+                next.error_code = 'NATIVE_SESSION_ID_MISMATCH';
+            }
+            else {
+                next.agent_native_session_id = observed.nativeId;
+                if (next.terminal_binding)
+                    next.terminal_binding = { ...next.terminal_binding, nativeSessionId: observed.nativeId };
+                next.state = 'ready';
+                next.error_code = null;
+            }
+        }
+        else if (observed.running) {
+            next.state = Date.now() > record.deadline ? 'failed' : 'binding_pending';
+            next.error_code = next.state === 'failed' ? 'SESSION_BINDING_TIMEOUT' : null;
+        }
+        else if (record.state === 'ready') {
+            next.state = 'failed';
+            next.error_code = 'AGENT_NOT_RUNNING';
+        }
+        else if (Date.now() > record.deadline && record.state !== 'failed') {
+            next.state = 'failed';
+            next.error_code = 'SESSION_BINDING_TIMEOUT';
+        }
+        if (JSON.stringify(this.doc.sessions.find(s => s.session_id === id)) !== JSON.stringify(record))
+            return;
+        if (next.state !== record.state || next.error_code !== record.error_code || next.agent_native_session_id !== record.agent_native_session_id) {
+            next.updated_at = Date.now();
+            this.saveRecord(next);
+        }
+    }
+    async refreshAll() {
+        if (this.observing) {
+            this.observeAgain = true;
+            return;
+        }
+        this.observing = true;
+        try {
+            do {
+                this.observeAgain = false;
+                for (const record of this.snapshot())
+                    await this.refresh(record.session_id);
+            } while (this.observeAgain);
+        }
+        finally {
+            this.observing = false;
+        }
+    }
+    close() { this.stopObservation(); for (const timer of this.timers)
+        clearTimeout(timer); }
+}