ds-harness-remote 0.5.7 → 0.5.10

package/dist/acp/gateway.js

@@ -8,7 +8,10 @@ import { basename, isAbsolute, join, relative, resolve } from 'node:path';
 import { RpcError } from '../safe-error.js';
 import { PLUGIN_VERSION } from '../version.js';
 import { CursorAcpClient, CursorAcpError, } from './adapters/cursor-process.js';
+import { ClaudeAcpClient } from './adapters/claude-process.js';
+import { PiAcpClient } from './adapters/pi-process.js';
 import { AntigravityAcpClient } from './adapters/antigravity-process.js';
+import { OpencodeAcpClient, OpencodeAcpError } from './adapters/opencode-process.js';
 import { ACP_METHOD_ALLOWLIST, isSessionMutation, parseAcpCall, sessionIdFromParams, } from './method-policy.js';
 import { discoverAntigravitySessions, discoverAntigravityWorkspaces, loadTranscriptEvents } from './adapters/antigravity/transcript-loader.js';
 import { AcpPeerBridge } from './peer-bridge.js';
@@ -41,7 +44,7 @@ export class AcpRemoteGateway {
     terminalSpawner;
     backendInstances = new Map();
     sessionCwds = new Map();
-    workspaceState = new WorkspaceBridgeState();
+    workspaceState = new WorkspaceBridgeState(key => TerminalPolicy.releaseOwner(this.terminalOwners, key));
     terminalOwners = new Map();
     workspaceTools = new Map();
     peers = new Map();
@@ -60,13 +63,26 @@ export class AcpRemoteGateway {
     /** Catch-up buffer for turns that finish while the Client is reconnecting. */
     recentFrames = new Map();
     /** Per-prompt live updates; attached to prompt_completed when streaming was lossy. */
+    promptsInProgress = new Set();
+    cancelledSessions = new Set();
+    /** Identity fences asynchronous Pi preparation from a later retry of the same session. */
+    preparingPrompts = new Map();
     turnCatchUp = new Map();
     startPromise;
     startingClients = new Map();
+    /** Desired configuration is saved immediately; unfinished cleanup must remain retryable. */
+    pendingReconfiguration = new Set();
     constructor(config, logger, createAcp = (binary, targetLogger, backend) => {
         if (backend.id === 'antigravity') {
             return new AntigravityAcpClient(binary, targetLogger, undefined, { args: backend.args, cwd: backend.cwd });
         }
+        if (backend.id === 'claude')
+            return new ClaudeAcpClient(binary, targetLogger, undefined, { args: backend.args, cwd: backend.cwd });
+        if (backend.id === 'pi')
+            return new PiAcpClient(binary, targetLogger, { args: backend.args, cwd: backend.cwd });
+        if (backend.id === 'opencode') {
+            return new OpencodeAcpClient(binary, targetLogger, undefined, { args: backend.args, cwd: backend.cwd });
+        }
         return new CursorAcpClient(binary, targetLogger, undefined, { args: backend.args, cwd: backend.cwd });
     }, restartDelaysMs = DEFAULT_RESTART_DELAYS_MS, terminalEnabled = () => false, terminalSpawner) {
         this.config = config;
@@ -80,12 +96,12 @@ export class AcpRemoteGateway {
     enabledBackends() {
         if (!this.config.enabled)
             return [];
-        return this.config.backends.filter(item => item.enabled && ['antigravity', 'cursor'].includes(item.id)).map(item => item.id);
+        return this.config.backends.filter(item => item.enabled && ['antigravity', 'cursor', 'pi', 'claude', 'opencode'].includes(item.id)).map(item => item.id);
     }
     start() {
         if (this.closed)
             return Promise.reject(new RpcError('CURSOR_CLOSED', 'The ACP Remote domain is closed.'));
-        if (!this.config.enabled || this.enabledBackends().length === 0)
+        if (!this.config.enabled || !this.enabledBackends().some(id => !this.pendingReconfiguration.has(id)))
             return Promise.resolve();
         this.startPromise ??= this.startOnce().finally(() => { this.startPromise = undefined; });
         return this.startPromise;
@@ -106,12 +122,12 @@ export class AcpRemoteGateway {
         }
     }
     isAvailable() {
-        return this.config.enabled && this.available && [...this.backendInstances.values()].some(inst => inst.client.isReady());
+        return this.config.enabled && this.available && this.availableBackends().length > 0;
     }
     availableBackends() {
         const list = [];
         for (const [id, inst] of this.backendInstances) {
-            if (this.enabledBackends().includes(id) && inst.client.isReady())
+            if (!this.pendingReconfiguration.has(id) && this.enabledBackends().includes(id) && inst.client.isReady())
                 list.push(id);
         }
         return list;
@@ -134,17 +150,17 @@ export class AcpRemoteGateway {
         const bridge = new AcpPeerBridge(this, context, publish, this.logger);
         this.peers.set(context.connectionId, bridge);
         const workspaceBridge = new WorkspaceBridge(async (rawId) => {
-            const match = rawId.match(/^(acp|cursor):(.+)$/);
+            const match = rawId.match(/^(acp|cursor|pi|opencode):(.+)$/);
             const session = match ? this.sessionCwds.get(match[2]) : undefined;
-            const backend = match?.[1] === 'acp' ? 'antigravity' : 'cursor';
+            const backend = match?.[1] === 'acp' ? 'antigravity' : match?.[1] === 'pi' ? 'pi' : match?.[1] === 'opencode' ? 'opencode' : 'cursor';
             if (!session || session.backend !== backend)
                 throw new RpcError('ACP_WORKSPACE_UNAVAILABLE', 'The ACP session has no trusted workspace.');
             this.requireAcp(backend);
             this.requireSessionOwner(context.connectionId, match[2]);
             return session.cwd;
         }, this.terminalEnabled, this.workspaceState, this.terminalSpawner, {
-            domain: 'ACP', owns: value => typeof value === 'string' && /^(acp|cursor):/.test(value),
-            parse: value => typeof value === 'string' && /^(acp|cursor):[A-Za-z0-9_-]{1,240}$/.test(value)
+            domain: 'ACP', owns: value => typeof value === 'string' && /^(acp|cursor|pi|opencode):/.test(value),
+            parse: value => typeof value === 'string' && /^(acp|cursor|pi|opencode):[A-Za-z0-9_-]{1,240}$/.test(value)
                 ? { sessionId: value, nativeId: value } : undefined,
         });
         this.workspaceTools.set(context.connectionId, new AcpWorkspaceTools(workspaceBridge, new TerminalPolicy(this.terminalEnabled, context.peerDeviceId, this.terminalOwners)));
@@ -158,8 +174,12 @@ export class AcpRemoteGateway {
             sessionId: typeof call.params?.sessionId === 'string' ? shortSessionId(call.params.sessionId) : undefined,
         });
         if (typeof call.params.backend === 'string') {
+            const prefix = typeof call.params.sessionId === 'string' ? /^(acp|cursor|pi|claude):/.exec(call.params.sessionId)?.[1] : undefined;
+            if (prefix && (prefix === 'acp' ? 'antigravity' : prefix) !== call.params.backend) {
+                throw new RpcError('INVALID_MESSAGE', 'The ACP session backend does not match.');
+            }
             const sessionId = call.method === 'dsh/sessionHistory'
-                ? String(call.params.sessionId).replace(/^(acp|cursor):/, '')
+                ? String(call.params.sessionId).replace(/^(acp|cursor|pi|claude|opencode):/, '')
                 : sessionIdFromParams(call.method, call.params);
             const boundBackend = sessionId === undefined ? undefined : this.sessionBackends.get(sessionId);
             if (boundBackend !== undefined && boundBackend !== call.params.backend) {
@@ -176,6 +196,11 @@ export class AcpRemoteGateway {
             return this.listDirectory(String(call.params.path));
         }
         if (call.method === 'dsh/workspaceList') {
+            const requestedBackend = typeof call.params.backend === 'string' ? call.params.backend : this.defaultBackend();
+            if (requestedBackend === 'pi' || requestedBackend === 'claude') {
+                const sessions = await this.listCatalogSessions(requestedBackend);
+                return [...new Set(sessions.map(item => item.cwd))].map(path => ({ path, title: basename(path) || 'workspace' }));
+            }
             const candidates = new Set();
             const cwd = process.cwd();
             if (cwd)
@@ -241,23 +266,41 @@ export class AcpRemoteGateway {
                 this.logger.info('ACP session list fetched', { count: items.length });
                 return { items };
             }
+            if (backend === 'pi' || backend === 'claude') {
+                const cwd = path ? await this.requireExistingDirectory(path) : undefined;
+                const sessions = await this.listCatalogSessions(backend, cwd);
+                return { items: sessions.slice(0, limit).map(item => ({ conversationId: item.sessionId, title: item.title ?? 'Untitled Session', createdAt: Date.parse(item.updatedAt ?? '') || 0, updatedAt: Date.parse(item.updatedAt ?? '') || 0, cwd: item.cwd })) };
+            }
             return { items: [] };
         }
         if (call.method === 'dsh/sessionHistory') {
             const rawSessionId = String(call.params.sessionId);
-            const conversationId = rawSessionId.startsWith('acp:')
+            const conversationId = rawSessionId.startsWith('claude:') ? rawSessionId.slice(7) : rawSessionId.startsWith('pi:') ? rawSessionId.slice(3) : rawSessionId.startsWith('acp:')
                 ? rawSessionId.slice('acp:'.length)
                 : rawSessionId.startsWith('cursor:')
                     ? rawSessionId.slice('cursor:'.length)
-                    : rawSessionId;
+                    : rawSessionId.startsWith('opencode:')
+                        ? rawSessionId.slice('opencode:'.length)
+                        : rawSessionId;
             const boundBackend = this.sessionBackends.get(conversationId);
             const backend = typeof call.params.backend === 'string' ? call.params.backend : boundBackend ?? this.defaultBackend();
             if ((boundBackend !== undefined && boundBackend !== backend)
+                || (rawSessionId.startsWith('claude:') && backend !== 'claude')
+                || (rawSessionId.startsWith('pi:') && backend !== 'pi')
                 || (rawSessionId.startsWith('cursor:') && backend !== 'cursor')
+                || (rawSessionId.startsWith('opencode:') && backend !== 'opencode')
                 || (rawSessionId.startsWith('acp:') && backend !== 'antigravity')) {
                 throw new RpcError('INVALID_MESSAGE', 'The ACP session backend does not match.');
             }
             this.requireAcp(backend);
+            if (backend === 'pi' || backend === 'claude') {
+                const cwd = await this.catalogSessionCwd(backend, conversationId);
+                this.requireSessionOwner(connectionId, conversationId);
+                const client = this.requireAcp(backend);
+                if (!client.history)
+                    throw new RpcError('METHOD_NOT_ALLOWED', 'The ACP backend does not support history.');
+                return { events: await client.history(conversationId, cwd) };
+            }
             if (backend !== 'antigravity')
                 return { events: [] };
             const events = await loadTranscriptEvents(conversationId, rawSessionId);
@@ -280,6 +323,10 @@ export class AcpRemoteGateway {
             });
             const sessionId = readSessionId(result);
             if (sessionId !== undefined) {
+                const bound = this.sessionBackends.get(sessionId);
+                if (this.sessionOwners.has(sessionId) || this.sessionCwds.has(sessionId) || (bound !== undefined && bound !== requestedBackend)) {
+                    throw new RpcError('ACP_SESSION_COLLISION', 'The ACP backend returned an existing session identifier.');
+                }
                 this.sessionOwners.set(sessionId, connectionId);
                 this.sessionBackends.set(sessionId, requestedBackend);
                 this.sessionCwds.set(sessionId, { backend: requestedBackend, cwd });
@@ -287,7 +334,7 @@ export class AcpRemoteGateway {
             return sanitizeSessionResult(result);
         }
         const sessionId = sessionIdFromParams(call.method, call.params);
-        if (sessionId !== undefined)
+        if (sessionId !== undefined && call.method !== 'session/load')
             this.requireSessionAccess(connectionId, sessionId, call.method);
         if (call.method === 'dsh/toolCall') {
             this.requireSessionOwner(connectionId, sessionId);
@@ -305,14 +352,24 @@ export class AcpRemoteGateway {
         }
         if (call.method === 'session/load') {
             const boundBackend = sessionId !== undefined ? this.sessionBackends.get(sessionId) : undefined;
-            const targetBackend = typeof call.params.backend === 'string' ? call.params.backend : boundBackend;
+            if (typeof call.params.backend !== 'string')
+                throw new RpcError('INVALID_MESSAGE', 'Session load requires an explicit backend.');
+            const targetBackend = call.params.backend;
+            if (targetBackend === 'claude' && this.promptsInProgress.has(sessionId))
+                throw new RpcError('PROMPT_IN_PROGRESS', 'An ACP reply is already in progress.');
             if (boundBackend !== undefined && targetBackend !== boundBackend) {
                 throw new RpcError('INVALID_MESSAGE', 'The ACP session backend does not match.');
             }
+            if (targetBackend === 'pi' || targetBackend === 'claude')
+                await this.catalogSessionCwd(targetBackend, sessionId);
+            this.requireSessionOwner(connectionId, sessionId);
             const acp = this.requireAcp(targetBackend);
-            const result = await acp.call(call.method, { ...call.params, ...(sessionId && this.sessionCwds.get(sessionId) ? { cwd: this.sessionCwds.get(sessionId).cwd } : {}) });
+            const result = await acp.call(call.method, { ...call.params, ...(sessionId && this.sessionCwds.get(sessionId) ? { cwd: this.sessionCwds.get(sessionId).cwd, mcpServers: [] } : {}) });
             const loadedId = readSessionId(result) ?? sessionId;
             if (loadedId !== undefined) {
+                if (loadedId !== sessionId || (this.sessionBackends.has(loadedId) && targetBackend !== undefined && this.sessionBackends.get(loadedId) !== targetBackend)) {
+                    throw new RpcError('ACP_SESSION_COLLISION', 'The ACP backend returned a different session identifier.');
+                }
                 this.sessionOwners.set(loadedId, connectionId);
                 if (targetBackend)
                     this.sessionBackends.set(loadedId, targetBackend);
@@ -322,6 +379,11 @@ export class AcpRemoteGateway {
         if (isSessionMutation(call.method) && sessionId !== undefined) {
             this.requireSessionOwner(connectionId, sessionId);
         }
+        if ((call.method === 'dsh/sessionModels' || call.method === 'dsh/selectModel') && call.params.backend === 'pi') {
+            this.requireSessionOwner(connectionId, sessionId);
+            const cwd = await this.piSessionCwd(sessionId);
+            await this.requireAcp('pi').call('session/load', { sessionId, cwd, mcpServers: [] });
+        }
         if (call.method === 'dsh/selectModel') {
             const session = this.sessionCwds.get(sessionId);
             if (!session || session.backend !== call.params.backend) {
@@ -338,6 +400,35 @@ export class AcpRemoteGateway {
         // interleaved agent.acp.frame events (Android stays on "正在回复" with no
         // thought/text). Accept immediately and finish via stream updates.
         if (call.method === 'session/prompt' && sessionId !== undefined) {
+            if (this.promptsInProgress.has(sessionId))
+                throw new RpcError('PROMPT_IN_PROGRESS', 'An ACP reply is already in progress.');
+            this.promptsInProgress.add(sessionId);
+            this.cancelledSessions.delete(sessionId);
+            if (this.sessionBackends.get(sessionId) === 'pi') {
+                const preparation = { cancelled: false };
+                this.preparingPrompts.set(sessionId, preparation);
+                try {
+                    const cwd = await this.piSessionCwd(sessionId);
+                    if (preparation.cancelled)
+                        return { accepted: false, stopReason: 'cancelled' };
+                    await this.requireAcp('pi').call('session/load', { sessionId, cwd, mcpServers: [] });
+                    if (preparation.cancelled)
+                        return { accepted: false, stopReason: 'cancelled' };
+                }
+                catch (error) {
+                    if (preparation.cancelled)
+                        return { accepted: false, stopReason: 'cancelled' };
+                    this.promptsInProgress.delete(sessionId);
+                    throw error;
+                }
+                finally {
+                    if (this.preparingPrompts.get(sessionId) === preparation) {
+                        this.preparingPrompts.delete(sessionId);
+                        if (preparation.cancelled)
+                            this.promptsInProgress.delete(sessionId);
+                    }
+                }
+            }
             const ownerPeer = this.peers.get(connectionId);
             if (ownerPeer !== undefined && !ownerPeer.hasStreamFor(sessionId)) {
                 this.logger?.warn('Cursor prompt started without an open ACP stream', {
@@ -348,6 +439,29 @@ export class AcpRemoteGateway {
             void this.runPromptInBackground(sessionId, call.params);
             return { accepted: true, stopReason: 'in_progress' };
         }
+        if (call.method === 'session/cancel' && sessionId !== undefined) {
+            this.cancelledSessions.add(sessionId);
+            const preparation = this.preparingPrompts.get(sessionId);
+            if (preparation) {
+                // No turn exists upstream yet. Do not send a late cancel into a retry
+                // sharing this load: cancel only this preparation identity.
+                preparation.cancelled = true;
+                this.preparingPrompts.delete(sessionId);
+                this.promptsInProgress.delete(sessionId);
+                return { stopReason: 'cancelled' };
+            }
+            const pending = [...this.approvals].filter(([, approval]) => approval.sessionId === sessionId && approval.backend === this.sessionBackends.get(sessionId));
+            for (const [handle] of pending)
+                this.approvals.delete(handle);
+            // Send cancellation before rejecting approvals: rejecting a blocked tool first
+            // can otherwise complete the turn as end_turn before upstream sees cancel.
+            try {
+                return sanitizeSessionResult(await this.requireAcp(this.sessionBackends.get(sessionId)).call(call.method, call.params));
+            }
+            finally {
+                await Promise.all(pending.map(([, approval]) => approval.client.respondError(approval.upstreamId, -32800, 'ACP session cancelled.').catch(() => undefined)));
+            }
+        }
         const sessionBackend = sessionId !== undefined ? this.sessionBackends.get(sessionId) : undefined;
         return sanitizeSessionResult(await this.requireAcp(typeof call.params.backend === 'string' ? call.params.backend : sessionBackend).call(call.method, call.params));
     }
@@ -397,6 +511,9 @@ export class AcpRemoteGateway {
                 },
             }).catch(() => undefined);
         }
+        finally {
+            this.promptsInProgress.delete(sessionId);
+        }
     }
     async respond(connectionId, input) {
         const params = parseRespondEnvelope(input);
@@ -408,13 +525,18 @@ export class AcpRemoteGateway {
         if (pending.connectionId !== connectionId) {
             throw new RpcError('CURSOR_APPROVAL_NOT_FOUND', 'The Cursor approval is missing, expired, or belongs to another connection.');
         }
+        if (this.sessionOwners.get(pending.sessionId) !== connectionId
+            || this.sessionBackends.get(pending.sessionId) !== pending.backend
+            || this.requireAcp(pending.backend) !== pending.client) {
+            throw new RpcError('CURSOR_APPROVAL_NOT_FOUND', 'The ACP approval scope is no longer active.');
+        }
+        const result = mapPermissionDecision(params, pending);
         this.approvals.delete(params.requestHandle);
-        const acp = this.requireAcp(pending.backend);
+        const acp = pending.client;
         if (params.decision === 'cancel') {
             await acp.respondError(pending.upstreamId, -32800, 'Cancelled by Remote client.');
             return { resolved: true };
         }
-        const result = params.result ?? mapPermissionDecision(params.decision, pending.method);
         await acp.respond(pending.upstreamId, result);
         return { resolved: true };
     }
@@ -429,7 +551,7 @@ export class AcpRemoteGateway {
         for (const [handle, approval] of this.approvals) {
             if (approval.connectionId === connectionId) {
                 this.approvals.delete(handle);
-                void this.requireAcp(approval.backend).respondError(approval.upstreamId, -32800, 'Remote peer disconnected.').catch(() => undefined);
+                void approval.client.respondError(approval.upstreamId, -32800, 'Remote peer disconnected.').catch(() => undefined);
             }
         }
     }
@@ -489,18 +611,20 @@ export class AcpRemoteGateway {
             throw new RpcError('CURSOR_CLOSED', 'The ACP Remote domain is closed.');
         const previous = this.config;
         const implemented = (value) => ({ enabled: value.enabled,
-            backends: value.backends.filter(item => ['cursor', 'antigravity'].includes(item.id)) });
+            backends: value.backends.filter(item => ['cursor', 'antigravity', 'pi', 'claude', 'opencode'].includes(item.id)) });
         this.config = config;
-        if (JSON.stringify(implemented(previous)) === JSON.stringify(implemented(config)))
+        if (JSON.stringify(implemented(previous)) === JSON.stringify(implemented(config)) && this.pendingReconfiguration.size === 0)
             return;
         if (this.restartTimer !== undefined)
             clearTimeout(this.restartTimer);
         this.restartTimer = undefined;
-        const changed = new Set(previous.backends.filter(item => {
-            const next = config.backends.find(candidate => candidate.id === item.id);
-            return previous.enabled !== config.enabled || JSON.stringify(item) !== JSON.stringify(next);
-        }).map(item => item.id));
-        await Promise.all([...this.startingClients].filter(([, backend]) => changed.has(backend.id)).map(([client]) => client.close()));
+        const changed = new Set([...this.pendingReconfiguration, ...previous.backends.filter(item => {
+                const next = config.backends.find(candidate => candidate.id === item.id);
+                return previous.enabled !== config.enabled || JSON.stringify(item) !== JSON.stringify(next);
+            }).map(item => item.id)]);
+        for (const id of changed)
+            this.pendingReconfiguration.add(id);
+        const stopping = await Promise.allSettled([...this.startingClients].filter(([, backend]) => changed.has(backend.id)).map(([client]) => client.close()));
         await this.startPromise?.catch(() => undefined);
         const sessions = new Set([...this.sessionBackends].filter(([, backend]) => changed.has(backend)).map(([id]) => id));
         if (sessions.size > 0)
@@ -508,14 +632,8 @@ export class AcpRemoteGateway {
         for (const [id, session] of this.sessionCwds)
             if (changed.has(session.backend))
                 this.sessionCwds.delete(id);
-        for (const [key, terminal] of this.workspaceState.terminals) {
-            if (changed.has(terminal.sessionId.startsWith('acp:') ? 'antigravity' : 'cursor')) {
-                void Promise.resolve(terminal.process?.terminate()).catch(() => undefined);
-                for (const queue of terminal.subscribers)
-                    queue.end();
-                this.workspaceState.terminals.delete(key);
-            }
-        }
+        const terminalError = await this.workspaceState.dispose(sessionId => changed.has(sessionId.startsWith('acp:') ? 'antigravity' : sessionId.startsWith('pi:') ? 'pi' : sessionId.startsWith('opencode:') ? 'opencode' : 'cursor'))
+            .then(() => undefined, () => new RpcError('TERMINAL_CLEANUP_FAILED', 'Some ACP terminal processes could not be stopped. Save the backend settings again to retry.'));
         for (const id of sessions) {
             this.sessionOwners.delete(id);
             this.sessionBackends.delete(id);
@@ -525,17 +643,27 @@ export class AcpRemoteGateway {
         for (const [id, approval] of this.approvals)
             if (approval.backend !== undefined && changed.has(approval.backend))
                 this.approvals.delete(id);
-        for (const id of changed) {
+        // A terminal cleanup failure must not prevent stopping any changed backend.
+        // Keep failed backend instances fenced from RPC/startup until a later retry.
+        const processes = await Promise.allSettled([...changed].map(async (id) => {
             const instance = this.backendInstances.get(id);
             if (instance === undefined)
-                continue;
-            this.backendInstances.delete(id);
+                return;
             await this.disposeInstance(instance);
-        }
+            if (this.backendInstances.get(id) === instance)
+                this.backendInstances.delete(id);
+        }));
         this.available = this.availableBackends().length > 0;
-        this.state = this.available ? 'ready' : 'disabled';
+        const cleanupFailed = terminalError !== undefined || [...stopping, ...processes].some(result => result.status === 'rejected');
+        this.state = this.available ? 'ready' : cleanupFailed && this.enabledBackends().length > 0 ? 'unavailable' : 'disabled';
         this.restartAttempt = 0;
-        this.unavailableCode = undefined;
+        this.unavailableCode = terminalError?.code ?? (cleanupFailed ? 'ACP_RECONFIGURE_FAILED' : undefined);
+        if (terminalError)
+            throw terminalError;
+        if (cleanupFailed)
+            throw new RpcError('ACP_RECONFIGURE_FAILED', 'Some ACP backend processes could not be stopped. Save the backend settings again to retry.');
+        for (const id of changed)
+            this.pendingReconfiguration.delete(id);
         await this.start();
     }
     async close() {
@@ -550,25 +678,25 @@ export class AcpRemoteGateway {
             await peer.closeAll();
         this.peers.clear();
         this.sessionCwds.clear();
-        for (const terminal of this.workspaceState.terminals.values()) {
-            void Promise.resolve(terminal.process?.terminate()).catch(() => undefined);
-            for (const queue of terminal.subscribers)
-                queue.end();
-        }
-        this.workspaceState.terminals.clear();
-        this.terminalOwners.clear();
+        const terminals = this.workspaceState.dispose().then(() => undefined, () => new RpcError('TERMINAL_CLEANUP_FAILED', 'Some ACP terminal processes could not be stopped.'));
         this.sessionOwners.clear();
         this.sessionBackends.clear();
         this.recentFrames.clear();
         this.turnCatchUp.clear();
         this.approvals.clear();
-        await Promise.all([...this.startingClients.keys()].map(client => client.close()));
-        await this.disposeAllInstances();
+        const processes = await Promise.allSettled([...this.startingClients.keys()].map(client => client.close()).concat(this.disposeAllInstances()));
+        const terminalError = await terminals;
+        if (!terminalError)
+            this.terminalOwners.clear();
         this.available = false;
         this.state = 'disabled';
+        if (terminalError)
+            throw terminalError;
+        if (processes.some(result => result.status === 'rejected'))
+            throw new RpcError('ACP_SHUTDOWN_FAILED', 'Some ACP backend processes could not be stopped.');
     }
     async launchAcp() {
-        const candidates = this.config.backends.filter(item => this.enabledBackends().includes(item.id));
+        const candidates = this.config.backends.filter(item => !this.pendingReconfiguration.has(item.id) && this.enabledBackends().includes(item.id));
         const results = await Promise.allSettled(candidates.map(async (candidate) => {
             if (this.backendInstances.get(candidate.id)?.client.isReady())
                 return;
@@ -595,7 +723,8 @@ export class AcpRemoteGateway {
         }
         if (this.isAvailable()) {
             this.state = 'ready';
-            this.unavailableCode = undefined;
+            if (this.pendingReconfiguration.size === 0)
+                this.unavailableCode = undefined;
             this.restartAttempt = 0;
             return;
         }
@@ -603,7 +732,7 @@ export class AcpRemoteGateway {
         throw failure?.status === 'rejected' ? failure.reason : new CursorAcpError('CURSOR_BINARY_UNAVAILABLE', 'No ACP backend is available.');
     }
     backendCurrent(backend) {
-        return this.config.enabled && backend.enabled
+        return this.config.enabled && backend.enabled && !this.pendingReconfiguration.has(backend.id)
             && JSON.stringify(this.config.backends.find(item => item.id === backend.id)) === JSON.stringify(backend);
     }
     async launchBackendCandidate(backend, binary) {
@@ -626,7 +755,7 @@ export class AcpRemoteGateway {
         }
         const unsubscribeInbound = acp.onInbound(message => {
             this.inboundChain = this.inboundChain
-                .then(() => this.handleInbound(id, message))
+                .then(() => this.backendInstances.get(id)?.client === acp ? this.handleInbound(id, message) : undefined)
                 .catch(error => {
                 this.logger.warn('ACP inbound fanout failed', { id, code: errorCode(error) });
             });
@@ -651,6 +780,13 @@ export class AcpRemoteGateway {
         });
     }
     async handleInbound(backend, message) {
+        const incomingId = readSessionId(message.params) ?? readNestedSessionId(message.params);
+        const boundBackend = incomingId === undefined ? undefined : this.sessionBackends.get(incomingId);
+        if (boundBackend !== undefined && boundBackend !== backend) {
+            if (message.kind === 'request')
+                await this.requireAcp(backend).respondError(message.id, -32602, 'The ACP session backend does not match.');
+            return;
+        }
         // session/update is a stream notification even if a buggy agent attaches an id.
         if (message.kind === 'notification' || message.method === 'session/update') {
             const sessionId = readSessionId(message.params) ?? readNestedSessionId(message.params);
@@ -662,38 +798,44 @@ export class AcpRemoteGateway {
             await this.publishToSession(sessionId, { method: message.method, params: message.params });
             return;
         }
-        const sessionId = readSessionId(message.params) ?? readNestedSessionId(message.params) ?? 'unknown';
-        if (sessionId !== 'unknown' && !this.sessionBackends.has(sessionId)) {
-            this.sessionBackends.set(sessionId, backend);
+        const sessionId = incomingId;
+        const owner = sessionId === undefined ? undefined : this.sessionOwners.get(sessionId);
+        const peer = owner === undefined ? undefined : this.peers.get(owner);
+        const client = this.requireAcp(backend);
+        if (sessionId === undefined || this.cancelledSessions.has(sessionId) || owner === undefined || peer === undefined || boundBackend !== backend
+            || !['session/request_permission', 'cursor/create_plan', 'cursor/ask_question'].includes(message.method)
+            || (message.method.startsWith('cursor/') && backend !== 'cursor')) {
+            await client.respondError(message.id, -32602, 'The ACP request has no active owner or supported method.');
+            return;
+        }
+        let options = [];
+        try {
+            if (message.method === 'session/request_permission')
+                options = permissionOptions(message.params);
+        }
+        catch {
+            await client.respondError(message.id, -32602, 'The ACP permission options are invalid.');
+            return;
         }
         const requestHandle = randomUUID();
         this.approvals.set(requestHandle, {
-            upstreamId: message.id,
-            connectionId: this.sessionOwners.get(sessionId) ?? [...this.peers.keys()][0] ?? 'unknown',
-            sessionId,
-            method: message.method,
-            expiresAt: Date.now() + APPROVAL_TTL_MS,
-            backend,
+            upstreamId: message.id, connectionId: owner, sessionId, method: message.method,
+            expiresAt: Date.now() + APPROVAL_TTL_MS, backend, client, options,
         });
         this.scheduleApprovalExpiry();
-        const owner = this.sessionOwners.get(sessionId);
-        const frame = {
-            method: message.method,
-            params: {
-                requestHandle,
-                sessionId,
-                upstreamMethod: message.method,
-                ...(isRecord(message.params) ? message.params : {}),
-            },
-        };
-        if (owner !== undefined) {
-            const peer = this.peers.get(owner);
-            if (peer !== undefined) {
-                await peer.publishInbound(sessionId, frame);
-                return;
-            }
+        try {
+            await peer.publishInbound(sessionId, {
+                method: message.method,
+                params: {
+                    ...(isRecord(message.params) ? message.params : {}),
+                    requestHandle, sessionId, upstreamMethod: message.method,
+                },
+            });
+        }
+        catch {
+            this.approvals.delete(requestHandle);
+            await client.respondError(message.id, -32800, 'Remote approval delivery failed.');
         }
-        await this.publishToSession(sessionId, frame);
     }
     async publishToSession(sessionId, frame) {
         this.recordTurnCatchUp(sessionId, frame);
@@ -799,7 +941,7 @@ export class AcpRemoteGateway {
             for (const [handle, approval] of this.approvals) {
                 if (approval.expiresAt <= now) {
                     this.approvals.delete(handle);
-                    void this.requireAcp(approval.backend).respondError(approval.upstreamId, -32800, 'Cursor approval expired.').catch(() => undefined);
+                    void approval.client.respondError(approval.upstreamId, -32800, 'Cursor approval expired.').catch(() => undefined);
                 }
             }
             this.scheduleApprovalExpiry();
@@ -807,7 +949,7 @@ export class AcpRemoteGateway {
         this.approvalExpiryTimer.unref?.();
     }
     requireAcp(backend) {
-        if (!this.config.enabled || (backend !== undefined && !this.enabledBackends().includes(backend)) || !this.isAvailable()) {
+        if (!this.config.enabled || (backend !== undefined && (!this.enabledBackends().includes(backend) || this.pendingReconfiguration.has(backend))) || !this.isAvailable()) {
             throw new RpcError('CURSOR_UNAVAILABLE', 'Cursor ACP is disabled or unavailable on this Host.');
         }
         if (backend !== undefined) {
@@ -844,8 +986,10 @@ export class AcpRemoteGateway {
         return this.requireAcp().call(method, params);
     }
     requireSessionAccess(connectionId, sessionId, method) {
-        if (method === 'session/load')
+        if (method === 'session/load') {
+            this.requireSessionOwner(connectionId, sessionId);
             return;
+        }
         const owner = this.sessionOwners.get(sessionId);
         if (owner === undefined) {
             // Allow reclaim after the owning peer disconnected; the ACP process still
@@ -860,6 +1004,74 @@ export class AcpRemoteGateway {
     requireSessionOwner(connectionId, sessionId) {
         this.claimSession(connectionId, sessionId);
     }
+    captureCatalogClient(backend) {
+        const client = this.requireAcp(backend);
+        const instance = this.backendInstances.get(backend);
+        return { client, assertCurrent: () => {
+                if (this.closed || this.backendInstances.get(backend) !== instance || this.requireAcp(backend) !== client) {
+                    throw new RpcError('CURSOR_UNAVAILABLE', 'The ACP backend changed while resolving session authority.');
+                }
+            } };
+    }
+    async listCatalogSessions(backend, cwd) {
+        const { client, assertCurrent } = this.captureCatalogClient(backend);
+        const items = [];
+        let cursor;
+        const seen = new Set();
+        for (let page = 0; page < 100; page++) {
+            const result = await client.call('session/list', { ...(cwd ? { cwd } : {}), ...(cursor ? { cursor } : {}) });
+            assertCurrent();
+            if (!isRecord(result) || !Array.isArray(result.sessions)
+                || (result.nextCursor != null && (typeof result.nextCursor !== 'string' || result.nextCursor.length === 0))) {
+                throw new RpcError('INVALID_MESSAGE', 'The ACP session catalog response is invalid.');
+            }
+            for (const item of result.sessions) {
+                if (!isRecord(item) || typeof item.sessionId !== 'string' || typeof item.cwd !== 'string')
+                    continue;
+                // Directory I/O can outlive a backend restart/reconfiguration. Only the
+                // directory failure is skippable; a stale generation must reject the RPC.
+                const canonical = await this.requireExistingDirectory(item.cwd).catch(() => undefined);
+                assertCurrent();
+                if (!canonical || (cwd && canonical !== cwd))
+                    continue;
+                if (this.sessionBackends.has(item.sessionId) && this.sessionBackends.get(item.sessionId) !== backend)
+                    continue;
+                const trusted = this.sessionCwds.get(item.sessionId);
+                if (trusted && (trusted.backend !== backend || trusted.cwd !== canonical))
+                    continue;
+                this.sessionCwds.set(item.sessionId, { backend, cwd: canonical });
+                this.sessionBackends.set(item.sessionId, backend);
+                items.push({ sessionId: item.sessionId, cwd: canonical,
+                    ...(typeof item.title === 'string' ? { title: item.title } : {}),
+                    ...(typeof item.updatedAt === 'string' ? { updatedAt: item.updatedAt } : {}) });
+            }
+            if (result.nextCursor == null)
+                return items;
+            if (seen.has(result.nextCursor) || page === 99) {
+                throw new RpcError('INVALID_MESSAGE', 'The ACP session catalog pagination did not complete.');
+            }
+            cursor = result.nextCursor;
+            seen.add(cursor);
+        }
+        return items;
+    }
+    piSessionCwd(sessionId) { return this.catalogSessionCwd('pi', sessionId); }
+    async catalogSessionCwd(backend, sessionId) {
+        const { assertCurrent } = this.captureCatalogClient(backend);
+        if (!this.sessionCwds.has(sessionId))
+            await this.listCatalogSessions(backend);
+        assertCurrent();
+        const session = this.sessionCwds.get(sessionId);
+        if (!session || session.backend !== backend)
+            throw new RpcError('ACP_WORKSPACE_UNAVAILABLE', 'The ACP session has no trusted workspace.');
+        const canonical = await this.requireExistingDirectory(session.cwd);
+        assertCurrent();
+        const current = this.sessionCwds.get(sessionId);
+        if (canonical !== session.cwd || current?.backend !== backend || current.cwd !== canonical) {
+            throw new RpcError('ACP_WORKSPACE_UNAVAILABLE', 'The ACP session workspace authority changed.');
+        }
+        return canonical;
+    }
     async requireExistingDirectory(path) {
         if (!isAbsolute(path)) {
             throw new RpcError('CURSOR_PATH_NOT_ALLOWED', 'The Cursor working directory must be an absolute path.');
@@ -932,32 +1144,55 @@ function parseCallEnvelope(input) {
     return { method: input.method, params: input.params ?? {} };
 }
 function parseRespondEnvelope(input) {
-    if (!isRecord(input) || typeof input.requestHandle !== 'string' || typeof input.decision !== 'string') {
-        throw new RpcError('INVALID_MESSAGE', 'The Cursor respond envelope is invalid.');
+    if (!isRecord(input) || typeof input.requestHandle !== 'string' || input.requestHandle.length === 0
+        || Object.keys(input).some(key => !['requestHandle', 'decision', 'result'].includes(key))
+        || typeof input.decision !== 'string' || !['allow-once', 'reject-once', 'cancel'].includes(input.decision)) {
+        throw new RpcError('INVALID_MESSAGE', 'The ACP respond envelope is invalid.');
     }
-    const decision = input.decision;
-    if (decision !== 'allow-once' && decision !== 'allow-always' && decision !== 'reject-once' && decision !== 'cancel') {
-        throw new RpcError('INVALID_MESSAGE', 'The Cursor respond envelope is invalid.');
-    }
-    return {
-        requestHandle: input.requestHandle,
-        decision,
-        ...(input.result === undefined ? {} : { result: input.result }),
-    };
+    return input;
 }
-function mapPermissionDecision(decision, method) {
-    if (method === 'session/request_permission') {
-        return { outcome: { outcome: 'selected', optionId: decision === 'cancel' ? 'reject-once' : decision } };
+function permissionOptions(params) {
+    if (!isRecord(params) || !Array.isArray(params.options) || params.options.length === 0) {
+        throw new Error('Missing permission options');
     }
-    if (method === 'cursor/create_plan') {
-        if (decision === 'allow-once' || decision === 'allow-always')
-            return { outcome: { outcome: 'accepted' } };
-        return { outcome: { outcome: decision === 'cancel' ? 'cancelled' : 'rejected' } };
+    const ids = new Set();
+    const options = params.options.map(option => {
+        if (!isRecord(option) || typeof option.optionId !== 'string' || !option.optionId
+            || typeof option.kind !== 'string' || !['allow_once', 'allow_always', 'reject_once', 'reject_always'].includes(option.kind)
+            || ids.has(option.optionId))
+            throw new Error('Invalid permission option');
+        ids.add(option.optionId);
+        return { kind: option.kind, optionId: option.optionId };
+    });
+    for (const kind of ['allow_once', 'reject_once']) {
+        if (options.filter(option => option.kind === kind).length > 1)
+            throw new Error('Ambiguous permission option');
     }
-    if (method === 'cursor/ask_question') {
-        return { outcome: { outcome: 'cancelled' } };
+    return options;
+}
+function mapPermissionDecision(params, pending) {
+    const invalid = () => new RpcError('INVALID_MESSAGE', 'The ACP approval result is not allowed.');
+    if (pending.method === 'session/request_permission') {
+        if (params.result !== undefined)
+            throw invalid();
+        if (params.decision === 'cancel')
+            return undefined;
+        const kind = params.decision === 'allow-once' ? 'allow_once' : 'reject_once';
+        const option = pending.options.find(item => item.kind === kind);
+        if (!option)
+            throw invalid();
+        return { outcome: { outcome: 'selected', optionId: option.optionId } };
     }
-    return { outcome: { outcome: 'selected', optionId: decision } };
+    const outcome = pending.method === 'cursor/create_plan'
+        ? params.decision === 'allow-once' ? 'accepted' : params.decision === 'cancel' ? 'cancelled' : 'rejected'
+        : 'cancelled';
+    if (params.result !== undefined) {
+        if (!isRecord(params.result) || Object.keys(params.result).length !== 1
+            || !isRecord(params.result.outcome) || Object.keys(params.result.outcome).length !== 1
+            || params.result.outcome.outcome !== outcome)
+            throw invalid();
+    }
+    return { outcome: { outcome } };
 }
 function readSessionId(value) {
     if (!isRecord(value))
@@ -1019,10 +1254,16 @@ export function cursorBinaryCandidates(configured) {
             'agent',
         ];
     }
+    if (configured === 'opencode') {
+        return [
+            join(userHome, '.local', 'bin', 'opencode'),
+            'opencode',
+        ];
+    }
     return [configured];
 }
 function errorCode(error) {
-    if (error instanceof CursorAcpError || error instanceof RpcError)
+    if (error instanceof CursorAcpError || error instanceof OpencodeAcpError || error instanceof RpcError)
         return error.code;
     return 'CURSOR_UNAVAILABLE';
 }