maka-agent 0.2.0-dev.30.20260912 → 0.2.0-dev.31.20260913

package/dist/acp/session-registry.js

@@ -20,17 +20,31 @@ import { randomUUID } from 'node:crypto';
 import { realpath } from 'node:fs/promises';
 import { isAbsolute, normalize } from 'node:path';
 import { RequestError, } from '@agentclientprotocol/sdk';
-import { readRuntimeHostConnectionCatalog, readRuntimeHostSessionCatalogPage, RuntimeHostCatalogReadError, RuntimeHostOperationError, RuntimeHostRequestInterruptedError, RuntimeHostSessionCatalogRevisionChangedError, } from '@maka/runtime-host/client';
-import { SESSION_CATALOG_CURSOR_MAX_BYTES, SESSION_CATALOG_CWD_MAX_BYTES, } from '@maka/runtime-host/protocol';
-import { RuntimeHostSessionUpdateError, requireRuntimeHostSessionProjection, updateRuntimeHostSession, } from '../runtime-host-session-update.js';
+import { isRuntimeHostTerminalTurn } from '@maka/runtime-host/adapter';
+import { readRuntimeHostConnectionCatalog, readRuntimeHostSessionCatalogPage, RuntimeHostCatalogReadError, RuntimeHostOperationError, RuntimeHostRequestInterruptedError, RuntimeHostSubscriptionError, RuntimeHostSessionCatalogRevisionChangedError, } from '@maka/runtime-host/client';
+import { SESSION_CATALOG_CURSOR_MAX_BYTES, SESSION_CATALOG_CWD_MAX_BYTES, HOST_OPERATION_SPECS, } from '@maka/runtime-host/protocol';
+import { RuntimeHostSessionChannel } from '../runtime-host-session-channel.js';
+import { RuntimeHostSessionUpdateError, getRuntimeHostSession, requireRuntimeHostSessionProjection, updateRuntimeHostSession, } from '../runtime-host-session-update.js';
 import { AcpSessionConfigInputError, createAcpSessionConfigPatch, projectAcpSessionConfigOptions, validateAcpSessionConfigOptionRequest, } from './session-configuration.js';
+import { AcpSessionEventMapper } from './session-event-mapper.js';
+import { mapAcpPromptContent, publishAcpPromptAttachments } from './prompt-content.js';
 const ACP_SESSION_CURSOR_MAX_BYTES = 8 * 1024;
+const ADMISSION_QUERY_MAX_ATTEMPTS = 5;
+const ADMISSION_QUERY_TIMEOUT_MS = 1_000;
+const ADMISSION_QUERY_RETRY_MS = 25;
 /** Owns all Runtime Host resources associated with one ACP connection. */
 export class AcpSessionRegistry {
     #connect;
     #newSessionId;
+    #newTurnId;
     #inFlightOperations = new Set();
     #ownedSessionIds = new Set();
+    #attachments = new Map();
+    #attachmentOpenControllers = new Map();
+    #attachmentConfigurations = new Map();
+    #pendingConfigSets = new Map();
+    #activePrompts = new Map();
+    #sessionCloseTasks = new Map();
     #connection;
     #connectTask;
     #connectAbortController;
@@ -40,6 +54,7 @@ export class AcpSessionRegistry {
     constructor(options) {
         this.#connect = options.connect;
         this.#newSessionId = options.newSessionId ?? randomUUID;
+        this.#newTurnId = options.newTurnId ?? randomUUID;
     }
     async create(params) {
         this.#assertOpen('session.create');
@@ -61,7 +76,54 @@ export class AcpSessionRegistry {
         catch (error) {
             throw requestErrorFromConfigInput(error);
         }
-        return this.#track(this.#setConfigOption(params));
+        const configuration = this.#attachmentConfigurations.get(params.sessionId);
+        const operation = this.#track(configuration
+            ? this.#queueConfiguration(configuration, () => this.#setConfigOption(params, configuration))
+            : this.#setConfigOption(params));
+        let pending = this.#pendingConfigSets.get(params.sessionId);
+        if (!pending) {
+            pending = new Set();
+            this.#pendingConfigSets.set(params.sessionId, pending);
+        }
+        pending.add(operation);
+        try {
+            return await operation;
+        }
+        finally {
+            pending.delete(operation);
+            if (pending.size === 0)
+                this.#pendingConfigSets.delete(params.sessionId);
+        }
+    }
+    async prompt(params, context) {
+        this.#assertOpen('turn.start');
+        this.#assertOwned(params.sessionId);
+        return this.#track(this.#prompt(params, context));
+    }
+    async cancel(params) {
+        if (this.#closing)
+            return;
+        await this.#cancelSession(params.sessionId);
+    }
+    async close(params) {
+        this.#assertOpen('session.close');
+        const existing = this.#sessionCloseTasks.get(params.sessionId);
+        if (existing)
+            return existing;
+        this.#assertOwned(params.sessionId);
+        this.#ownedSessionIds.delete(params.sessionId);
+        const configuration = this.#attachmentConfigurations.get(params.sessionId);
+        const delivery = configuration?.delivery;
+        this.#attachmentConfigurations.delete(params.sessionId);
+        const task = this.#track(this.#closeSession(params.sessionId, delivery));
+        this.#sessionCloseTasks.set(params.sessionId, task);
+        const forget = () => {
+            if (this.#sessionCloseTasks.get(params.sessionId) === task) {
+                this.#sessionCloseTasks.delete(params.sessionId);
+            }
+        };
+        void task.then(forget, forget);
+        return task;
     }
     dispose() {
         this.#closing = true;
@@ -69,6 +131,499 @@ export class AcpSessionRegistry {
         this.#disposeTask ??= this.#dispose();
         return this.#disposeTask;
     }
+    async #prompt(params, context) {
+        const turnId = this.#newTurnId();
+        const active = {
+            sessionId: params.sessionId,
+            turnId,
+            mapper: new AcpSessionEventMapper({
+                sessionId: params.sessionId,
+                notify: async (notification) => {
+                    if (!this.#closing && this.#ownedSessionIds.has(params.sessionId)) {
+                        await context.notify(notification);
+                    }
+                },
+            }),
+            waiters: new Set(),
+            dispatchStarted: false,
+            startRequestSettled: false,
+            admissionSettled: false,
+            cancelled: false,
+            finished: false,
+        };
+        this.#addActivePrompt(active);
+        const onAbort = () => {
+            void this.#cancelPrompt(active).catch(() => undefined);
+        };
+        context.signal.addEventListener('abort', onAbort, { once: true });
+        if (context.signal.aborted)
+            onAbort();
+        try {
+            const content = await mapAcpPromptContent(params.prompt);
+            let startInput;
+            try {
+                startInput = HOST_OPERATION_SPECS['turn.start'].decodeInput({
+                    sessionId: params.sessionId,
+                    turnId,
+                    content,
+                });
+            }
+            catch {
+                throw RequestError.invalidParams({ field: 'prompt', reason: 'runtime_host_admission_rejected' }, 'Prompt cannot be admitted by Runtime Host');
+            }
+            if (active.cancelled)
+                return { stopReason: await this.#cancelledStopReason(active) };
+            const connection = await this.#getConnection('subscription.open');
+            let attachment;
+            try {
+                attachment = await this.#ensureAttachment(params.sessionId, connection, context.notify);
+            }
+            catch (error) {
+                if (active.cancelled)
+                    return { stopReason: await this.#cancelledStopReason(active) };
+                throw error;
+            }
+            active.attachment = attachment;
+            this.#wake(active);
+            if (active.cancelled)
+                return { stopReason: await this.#cancelledStopReason(active) };
+            try {
+                startInput = {
+                    ...startInput,
+                    content: await publishAcpPromptAttachments(content, {
+                        sessionId: params.sessionId,
+                        connection,
+                        assertActive: () => {
+                            if (active.cancelled)
+                                throw new Error('ACP prompt cancelled before Turn admission');
+                            this.#assertOpen('turn.start');
+                            this.#assertOwned(params.sessionId);
+                        },
+                    }),
+                };
+            }
+            catch (error) {
+                if (error instanceof RequestError)
+                    throw error;
+                throw requestErrorFromRuntimeHost(error, 'artifact.ingest');
+            }
+            if (active.cancelled)
+                return { stopReason: await this.#cancelledStopReason(active) };
+            const observation = this.#consumePromptEvents(active, attachment.eventsForTurn(turnId));
+            // Mark the observer as handled immediately: turn.start may still be in flight
+            // when the live subscription reports a failure.
+            void observation.catch(() => undefined);
+            active.dispatchStarted = true;
+            this.#wake(active);
+            try {
+                const result = await connection.request('turn.start', startInput);
+                active.startRequestSettled = true;
+                active.admissionSettled = true;
+                if (result.kind === 'started')
+                    active.startedTurn = result.turn;
+                this.#wake(active);
+                if (result.kind === 'blocked') {
+                    const error = new Error('Runtime Host blocked the requested Turn');
+                    attachment.failTurn(turnId, error);
+                    throw error;
+                }
+            }
+            catch (error) {
+                // A lost dispatched response does not establish whether Host admitted
+                // this Turn. Retain this attempt until subscription or query facts do.
+                active.startRequestSettled = true;
+                active.admissionSettled ||= !(error instanceof RuntimeHostRequestInterruptedError && error.dispatch === 'dispatched');
+                if (!active.admissionSettled) {
+                    this.#queryPromptAdmission(active, connection);
+                }
+                this.#wake(active);
+                attachment.failTurn(turnId, error);
+                if (!active.cancelled)
+                    throw requestErrorFromRuntimeHost(error, 'turn.start');
+            }
+            if (active.cancelled) {
+                await active.stopTask?.catch(() => undefined);
+                return { stopReason: await this.#cancelledStopReason(active) };
+            }
+            const stopReason = await observation;
+            return { stopReason };
+        }
+        catch (error) {
+            // A failed projection must not leave the corresponding Host Turn running.
+            active.stopTask ??= this.#stopPromptWhenObservable(active);
+            await active.stopTask.catch(() => undefined);
+            if (active.cancelled)
+                return { stopReason: await this.#cancelledStopReason(active) };
+            if (active.admissionFailure)
+                throw active.admissionFailure;
+            if (error instanceof RequestError)
+                throw error;
+            throw requestErrorFromRuntimeHost(error, 'subscription.open');
+        }
+        finally {
+            context.signal.removeEventListener('abort', onAbort);
+            // A terminal subscription event can precede the Stop response. Retain this
+            // prompt so close/dispose cannot release its connection while Stop is in flight.
+            await active.stopTask?.catch(() => undefined);
+            active.finished = true;
+            this.#wake(active);
+            this.#removeActivePrompt(active);
+        }
+    }
+    async #consumePromptEvents(active, events) {
+        try {
+            for await (const event of events) {
+                if (!active.cancelled)
+                    await active.mapper.accept(event);
+            }
+            return active.cancelled ? this.#cancelledStopReason(active) : 'end_turn';
+        }
+        catch (error) {
+            if (active.cancelled)
+                return this.#cancelledStopReason(active);
+            throw error;
+        }
+    }
+    async #cancelledStopReason(active) {
+        await active.mapper.flush();
+        return 'cancelled';
+    }
+    #cancelSession(sessionId) {
+        const active = [...(this.#activePrompts.get(sessionId) ?? [])];
+        const cancellations = active.map((prompt) => this.#cancelPrompt(prompt));
+        this.#attachmentOpenControllers.get(sessionId)?.abort();
+        const attachment = this.#attachments.get(sessionId);
+        if (attachment) {
+            cancellations.push(attachment.then(async (opened) => {
+                const root = opened.snapshot.rootTurn;
+                // Local prompts already latch cancellation across pending turn.start.
+                // An idle attachment may also observe a Turn started by another client.
+                if (root &&
+                    !isRuntimeHostTerminalTurn(root) &&
+                    !active.some((prompt) => prompt.turnId === root.turnId)) {
+                    await this.#connection?.request('turn.stop', {
+                        sessionId: root.sessionId,
+                        turnId: root.turnId,
+                        runId: root.runId,
+                    });
+                }
+            }, () => undefined));
+        }
+        return Promise.allSettled(cancellations);
+    }
+    async #cancelPrompt(active) {
+        active.cancelled = true;
+        this.#wake(active);
+        if ([...(this.#activePrompts.get(active.sessionId) ?? [])].every((prompt) => prompt.cancelled && !prompt.dispatchStarted)) {
+            this.#attachmentOpenControllers.get(active.sessionId)?.abort();
+        }
+        active.stopTask ??= this.#stopPromptWhenObservable(active);
+        await Promise.all([
+            active.mapper.flush(),
+            active.stopTask.catch((error) => {
+                // End only this prompt's observation. Failed delivery does not establish
+                // a terminal Host Turn, and teardown still receives the original error.
+                active.attachment?.failTurn(active.turnId, error);
+                throw error;
+            }),
+        ]);
+    }
+    async #stopPromptWhenObservable(active) {
+        if (!active.dispatchStarted)
+            return;
+        while (!active.finished) {
+            const observed = active.attachment?.snapshot.rootTurn;
+            // Subscription teardown can precede the start response. Keep the admitted
+            // identity until exact Stop completes, even when observation has ended.
+            const root = observed?.turnId === active.turnId ? observed : active.startedTurn;
+            if (root) {
+                if (isRuntimeHostTerminalTurn(root))
+                    return;
+                const connection = this.#connection;
+                if (!connection)
+                    return;
+                try {
+                    await connection.request('turn.stop', {
+                        sessionId: root.sessionId,
+                        turnId: root.turnId,
+                        runId: root.runId,
+                    });
+                }
+                catch (error) {
+                    console.error('[acp] Host Stop delivery failed:', error);
+                    throw error;
+                }
+                return;
+            }
+            if (active.admissionSettled && active.startRequestSettled)
+                return;
+            if (active.admissionFailure) {
+                console.error('[acp] Host Turn admission remains unknown:', active.admissionFailure);
+                throw active.admissionFailure;
+            }
+            await this.#waitForPromptChange(active);
+        }
+    }
+    #queryPromptAdmission(active, connection) {
+        // Recovery and the lost start response can both request this read. Keep one
+        // bounded retry task; neither a healthy subscription nor a failed query
+        // establishes whether a dispatched start was admitted.
+        active.admissionQuery ??= this.#readPromptAdmission(active, connection);
+    }
+    async #readPromptAdmission(active, connection) {
+        let lastError;
+        for (let attempt = 0; attempt < ADMISSION_QUERY_MAX_ATTEMPTS; attempt += 1) {
+            if (active.finished || active.admissionSettled || (this.#closing && attempt > 0))
+                return;
+            const observed = active.attachment?.snapshot.rootTurn;
+            if (observed?.turnId === active.turnId) {
+                active.startedTurn = observed;
+                active.admissionSettled = true;
+                this.#wake(active);
+                return;
+            }
+            try {
+                const turn = await connection.request('turn.query', { sessionId: active.sessionId, turnId: active.turnId }, ADMISSION_QUERY_TIMEOUT_MS);
+                if (!active.finished && !active.admissionSettled) {
+                    active.startedTurn = turn;
+                    active.admissionSettled = true;
+                    this.#wake(active);
+                }
+                return;
+            }
+            catch (error) {
+                if (error instanceof RuntimeHostOperationError && error.code === 'not_found') {
+                    active.admissionSettled = true;
+                    this.#wake(active);
+                    return;
+                }
+                lastError = error;
+            }
+            if (active.finished || active.admissionSettled || this.#closing)
+                return;
+            if (attempt + 1 < ADMISSION_QUERY_MAX_ATTEMPTS) {
+                await this.#waitForPromptChange(active, ADMISSION_QUERY_RETRY_MS * 2 ** attempt);
+            }
+        }
+        if (active.attachment?.snapshot.rootTurn?.turnId === active.turnId) {
+            this.#wake(active);
+            return;
+        }
+        active.admissionFailure = RequestError.internalError({
+            source: 'runtime_host',
+            operation: 'turn.query',
+            code: 'outcome_unknown',
+            reason: 'admission_query_failed',
+            attempts: ADMISSION_QUERY_MAX_ATTEMPTS,
+            cause: runtimeHostErrorData(lastError, 'turn.query'),
+        }, 'Runtime Host Turn admission could not be established; Stop could not be confirmed');
+        this.#wake(active);
+    }
+    async #ensureAttachment(sessionId, connection, notify) {
+        const existing = this.#attachments.get(sessionId);
+        if (existing)
+            return existing;
+        const openingController = new AbortController();
+        this.#attachmentOpenControllers.set(sessionId, openingController);
+        const configuration = {
+            notify,
+            // Setters can outlive an absent or failed attachment. Their responses
+            // must precede refreshes delivered by the new attachment's queue.
+            tail: Promise.allSettled([...(this.#pendingConfigSets.get(sessionId) ?? [])]),
+        };
+        this.#attachmentConfigurations.set(sessionId, configuration);
+        let task;
+        let attachment;
+        let earlyFailure;
+        const failAttachment = (error) => {
+            if (!attachment) {
+                earlyFailure = error;
+                return;
+            }
+            this.#retireFailedAttachment(sessionId, task, attachment, error);
+        };
+        task = RuntimeHostSessionChannel.open({
+            connection,
+            signal: openingController.signal,
+            openInitialSessionSubscription: connection.openSessionSubscriptionOnce.bind(connection),
+            sessionId,
+            now: Date.now,
+            onTurnStarted: () => undefined,
+            onRuntimeResourceChanged: () => undefined,
+            onSnapshotChanged: (snapshot) => {
+                this.#wakeSession(sessionId);
+                if (configuration.metadataRevision === undefined) {
+                    configuration.metadataRevision = snapshot.session.metadataRevision;
+                    return;
+                }
+                if (configuration.metadataRevision === snapshot.session.metadataRevision)
+                    return;
+                configuration.metadataRevision = snapshot.session.metadataRevision;
+                void this.#queueConfiguration(configuration, async () => {
+                    if (!this.#configurationIsLive(sessionId, configuration))
+                        return;
+                    const session = await getRuntimeHostSession(connection, sessionId);
+                    if (!session)
+                        throw unknownSessionError();
+                    const configOptions = await this.#projectConfigOptions(connection, session);
+                    await this.#notifyConfiguration(sessionId, configuration, configOptions);
+                }).catch((error) => {
+                    // Closing or replacing the attachment intentionally invalidates any
+                    // in-flight presentation refresh; its interrupted read is no longer actionable.
+                    if (this.#configurationIsLive(sessionId, configuration)) {
+                        console.error('[acp] Session configuration refresh failed:', error);
+                    }
+                });
+            },
+            onTranscriptReplaced: (turnId, messages) => {
+                for (const active of this.#activePrompts.get(sessionId) ?? []) {
+                    if (active.turnId === turnId && !active.cancelled) {
+                        void active.mapper.replaceTranscript(turnId, messages).catch((error) => {
+                            active.attachment?.failTurn(turnId, error);
+                        });
+                    }
+                }
+            },
+            onInteractionPending: (pending) => {
+                if (![...(this.#activePrompts.get(sessionId) ?? [])].some((active) => active.turnId === pending.turnId && active.dispatchStarted)) {
+                    // An idle attachment may observe another client's Turn. Retain its
+                    // identity so a later ACP cancel/close can still stop that root.
+                    return;
+                }
+                // Full interaction mapping belongs to the next ACP capability increment.
+                // Retire observation so the prompt's existing failure path stops its exact Turn.
+                failAttachment(RequestError.internalError({ source: 'adapter', code: 'unsupported_interaction', kind: pending.request.kind }, 'This ACP adapter does not support interactions yet; the prompt failed'));
+            },
+            onInteractionResolved: () => undefined,
+            onTranscriptSettlement: () => undefined,
+            onGoalChanged: () => undefined,
+            onFailed: failAttachment,
+            onRecovered: () => {
+                for (const active of this.#activePrompts.get(sessionId) ?? []) {
+                    if (active.attachment !== attachment ||
+                        !active.startRequestSettled ||
+                        active.admissionSettled) {
+                        continue;
+                    }
+                    // Recovery may hydrate a snapshot taken before start admission.
+                    // An absent root needs a fresh query; a matching root can be stopped
+                    // directly by the existing cancellation task.
+                    if (attachment?.snapshot.rootTurn?.turnId !== active.turnId) {
+                        this.#queryPromptAdmission(active, connection);
+                    }
+                    this.#wake(active);
+                }
+            },
+        })
+            .then(({ channel }) => {
+            channel.activate();
+            attachment = channel;
+            if (earlyFailure) {
+                this.#retireFailedAttachment(sessionId, task, channel, earlyFailure);
+                throw earlyFailure;
+            }
+            if (this.#closing || !this.#ownedSessionIds.has(sessionId)) {
+                return channel.close().then(() => {
+                    throw this.#closing ? registryClosedError('subscription.open') : unknownSessionError();
+                });
+            }
+            return channel;
+        })
+            .catch((error) => {
+            if (this.#attachments.get(sessionId) === task) {
+                this.#attachments.delete(sessionId);
+                this.#attachmentConfigurations.delete(sessionId);
+            }
+            if (error instanceof RequestError)
+                throw error;
+            throw requestErrorFromRuntimeHost(error, 'subscription.open');
+        })
+            .finally(() => {
+            if (this.#attachmentOpenControllers.get(sessionId) === openingController) {
+                this.#attachmentOpenControllers.delete(sessionId);
+            }
+        });
+        this.#attachments.set(sessionId, task);
+        return task;
+    }
+    #retireFailedAttachment(sessionId, task, attachment, error) {
+        if (this.#attachments.get(sessionId) === task) {
+            this.#attachments.delete(sessionId);
+            this.#attachmentConfigurations.delete(sessionId);
+        }
+        for (const active of this.#activePrompts.get(sessionId) ?? []) {
+            if (active.attachment !== attachment)
+                continue;
+            // Losing observation cannot settle a dispatched start. Its pending
+            // response or bounded admission query still owns the exact Stop identity.
+            attachment.failTurn(active.turnId, error);
+            this.#wake(active);
+        }
+        void attachment.close().catch(() => undefined);
+    }
+    async #closeSession(sessionId, delivery) {
+        const cancellation = await this.#cancelSession(sessionId);
+        const attachmentTask = this.#attachments.get(sessionId);
+        this.#attachments.delete(sessionId);
+        let closeError;
+        if (attachmentTask) {
+            try {
+                // A rejected open has no retained resource; close still releases ownership.
+                const attachment = await attachmentTask.catch(() => undefined);
+                await attachment?.close();
+            }
+            catch (error) {
+                closeError = error;
+            }
+        }
+        await delivery;
+        const failedCancellation = cancellation.find((result) => result.status === 'rejected');
+        if (failedCancellation)
+            throw failedCancellation.reason;
+        if (closeError)
+            throw closeError;
+        return {};
+    }
+    #addActivePrompt(active) {
+        const prompts = this.#activePrompts.get(active.sessionId);
+        if (prompts)
+            prompts.add(active);
+        else
+            this.#activePrompts.set(active.sessionId, new Set([active]));
+    }
+    #removeActivePrompt(active) {
+        const prompts = this.#activePrompts.get(active.sessionId);
+        prompts?.delete(active);
+        if (prompts?.size === 0)
+            this.#activePrompts.delete(active.sessionId);
+    }
+    #wakeSession(sessionId) {
+        for (const active of this.#activePrompts.get(sessionId) ?? [])
+            this.#wake(active);
+    }
+    #wake(active) {
+        for (const resolve of active.waiters)
+            resolve();
+        active.waiters.clear();
+    }
+    #waitForPromptChange(active, timeoutMs) {
+        return new Promise((resolve) => {
+            let timer;
+            const wake = () => {
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                active.waiters.delete(wake);
+                resolve();
+            };
+            active.waiters.add(wake);
+            if (timeoutMs !== undefined)
+                timer = setTimeout(wake, timeoutMs);
+        });
+    }
+    #assertOwned(sessionId) {
+        if (!this.#ownedSessionIds.has(sessionId))
+            throw unknownSessionError();
+    }
     async #create(params) {
         const connection = await this.#getConnection('session.create');
         const sessionId = this.#newSessionId();
@@ -83,18 +638,23 @@ export class AcpSessionRegistry {
         catch (error) {
             throw requestErrorFromRuntimeHost(error, 'session.create', { sessionId });
         }
-        let created;
+        // Session creation has committed. Optional presentation failures must not
+        // turn that success into an unreachable durable Session.
+        let configOptions;
         try {
-            created = requireRuntimeHostSessionProjection(result, 'session.create');
+            const created = requireRuntimeHostSessionProjection(result, 'session.create');
+            configOptions = await this.#projectConfigOptions(connection, created);
         }
-        catch (error) {
-            throw requestErrorFromSessionUpdate(error, 'session.create', { sessionId });
+        catch {
+            // The client can still prompt, configure, list, or close the returned ID.
         }
-        const configOptions = await this.#projectConfigOptions(connection, created);
-        this.#ownedSessionIds.add(sessionId);
-        return { sessionId, configOptions };
+        // Do not admit mutations while projection is pending, or resurrect ownership
+        // if connection shutdown raced the successful Host creation.
+        if (!this.#closing)
+            this.#ownedSessionIds.add(sessionId);
+        return { sessionId, ...(configOptions ? { configOptions } : {}) };
     }
-    async #setConfigOption(params) {
+    async #setConfigOption(params, configuration) {
         const connection = await this.#getConnection('session.configuration.update');
         let committed;
         try {
@@ -104,13 +664,46 @@ export class AcpSessionRegistry {
                 patch: createAcpSessionConfigPatch(params),
             }), {
                 operation: 'session.configuration.update',
-                assertRequestAllowed: () => this.#assertOpen('session.configuration.update'),
+                assertRequestAllowed: () => {
+                    this.#assertOpen('session.configuration.update');
+                    this.#assertOwned(params.sessionId);
+                },
             });
         }
         catch (error) {
             throw requestErrorFromSessionUpdate(error, 'session.configuration.update');
         }
-        return { configOptions: await this.#projectConfigOptions(connection, committed) };
+        const configOptions = await this.#projectConfigOptions(connection, committed);
+        if (configuration)
+            await this.#notifyConfiguration(params.sessionId, configuration, configOptions);
+        return { configOptions };
+    }
+    #configurationIsLive(sessionId, configuration) {
+        return (!this.#closing &&
+            this.#ownedSessionIds.has(sessionId) &&
+            this.#attachmentConfigurations.get(sessionId) === configuration);
+    }
+    #queueConfiguration(configuration, operation) {
+        // Serialize asynchronous catalog projection and delivery, not Host frames:
+        // session-channel/projector remain the only subscription ordering authority.
+        // A local set emits its committed options before its response; subscription
+        // refreshes observed during that set follow its notification in this queue.
+        const result = configuration.tail.then(operation, operation);
+        configuration.tail = result.catch(() => undefined);
+        return result;
+    }
+    async #notifyConfiguration(sessionId, configuration, configOptions) {
+        if (!this.#configurationIsLive(sessionId, configuration))
+            return;
+        const options = JSON.stringify(configOptions);
+        if (configuration.options === options)
+            return;
+        configuration.delivery = configuration.notify({
+            sessionId,
+            update: { sessionUpdate: 'config_option_update', configOptions },
+        });
+        await configuration.delivery;
+        configuration.options = options;
     }
     async #projectConfigOptions(connection, session) {
         let catalog;
@@ -163,9 +756,42 @@ export class AcpSessionRegistry {
         };
     }
     async #dispose() {
-        const connectionClose = this.#closeOwnedConnection();
-        await Promise.allSettled([connectionClose]);
-        await Promise.allSettled([...this.#inFlightOperations]);
+        const sessionIds = new Set([...this.#activePrompts.keys(), ...this.#attachments.keys()]);
+        const activePrompts = [...sessionIds].flatMap((sessionId) => [
+            ...(this.#activePrompts.get(sessionId) ?? []),
+        ]);
+        const cancellations = [...sessionIds].map((sessionId) => this.#cancelSession(sessionId));
+        const attachments = [...this.#attachments.values()];
+        this.#attachments.clear();
+        const configurations = [...this.#attachmentConfigurations.values()];
+        this.#attachmentConfigurations.clear();
+        await Promise.allSettled(attachments.map(async (attachment) => (await attachment).close()));
+        await Promise.allSettled(activePrompts.map(async (active) => {
+            while (active.dispatchStarted && !active.startRequestSettled && !active.finished) {
+                await this.#waitForPromptChange(active);
+            }
+        }));
+        const unknownAdmissions = activePrompts.filter((active) => {
+            const observed = active.attachment?.snapshot.rootTurn;
+            const hasStopIdentity = observed?.turnId === active.turnId || active.startedTurn !== undefined;
+            return active.dispatchStarted && !active.admissionSettled && !hasStopIdentity;
+        });
+        if (unknownAdmissions.length > 0) {
+            // At shutdown the attachment is already closed and each start request has
+            // settled, leaving recovery/query as the only remaining fact source.
+            // Close the owned connection so those reads cannot deadlock EOF cleanup.
+            await Promise.allSettled([this.#closeOwnedConnection()]);
+            for (const active of unknownAdmissions) {
+                active.admissionSettled = true;
+                this.#wake(active);
+            }
+        }
+        await Promise.allSettled(cancellations);
+        await Promise.allSettled([this.#closeOwnedConnection()]);
+        await Promise.allSettled([
+            ...this.#inFlightOperations,
+            ...configurations.map(({ tail }) => tail),
+        ]);
         this.#ownedSessionIds.clear();
     }
     #closeOwnedConnection() {
@@ -237,6 +863,9 @@ export class AcpSessionRegistry {
         throw registryClosedError(operation);
     }
 }
+function unknownSessionError() {
+    return RequestError.invalidParams({ reason: 'unknown_session' }, 'Session is not owned by this ACP connection');
+}
 function registryClosedError(operation) {
     return RequestError.internalError({ source: 'runtime_host', operation, code: 'registry_closed' }, 'ACP session registry is closed');
 }
@@ -302,6 +931,14 @@ function runtimeHostErrorData(error, operation) {
             dispatch: error.dispatch,
         };
     }
+    if (error instanceof RuntimeHostSubscriptionError) {
+        return {
+            source: 'runtime_host',
+            operation,
+            code: 'subscription_failure',
+            reason: error.reason,
+        };
+    }
     if (error instanceof RuntimeHostCatalogReadError) {
         return {
             source: 'runtime_host',