@borgee/agents-host 0.2.28 → 0.2.31

package/dist/providers/claude/cli-client.js

@@ -1,49 +1,31 @@
-import { randomUUID } from 'node:crypto';
-import { resolve } from 'node:path';
+import { Readable, Writable } from 'node:stream';
+import { createRequire } from 'node:module';
+import { dirname, resolve } from 'node:path';
 import spawn from 'cross-spawn';
+import { assertClaudeCommandCompatibility, DEFAULT_CLAUDE_COMMAND, isLegacyClaudeCompatibilityAlias, } from '../../config.js';
+import { PROTOCOL_VERSION, client, methods, ndJsonStream, } from '@agentclientprotocol/sdk';
 import { HostLogger, summarizeChildStderr, summarizeError } from '../../debug.js';
+import { resolveCopilotPermissionResponse } from '../../policy/copilot-permission.js';
+const SESSION_TAINTED_ERRORS = new WeakSet();
+const DEFAULT_SHUTDOWN_GRACE_PERIOD_MS = 250;
+const DEFAULT_SHUTDOWN_FORCE_KILL_WAIT_MS = 250;
+const DEFAULT_SESSION_CAPABILITIES = {
+    loadSession: false,
+    resumeSession: false,
+};
+const require = createRequire(import.meta.url);
 const DEFAULT_RUNTIME = {
     spawn,
+    client,
+    ndJsonStream,
+    methods,
+    protocolVersion: PROTOCOL_VERSION,
     cwd: process.cwd(),
+    shutdownGracePeriodMs: DEFAULT_SHUTDOWN_GRACE_PERIOD_MS,
+    shutdownForceKillWaitMs: DEFAULT_SHUTDOWN_FORCE_KILL_WAIT_MS,
 };
-const STREAM_JSON_ARGS = ['--verbose', '--output-format', 'stream-json', '--include-partial-messages'];
-class ClaudeCliProcessError extends Error {
-    exitCode;
-    signal;
-    stderrBytes;
-    stderrLineCount;
-    staleResume;
-    constructor(exitCode, signal, stderrBytes, stderrLineCount, staleResume = false) {
-        super(formatClaudeCliFailureMessage(exitCode, signal, stderrBytes, stderrLineCount));
-        this.name = 'ClaudeCliProcessError';
-        if (exitCode !== null) {
-            this.exitCode = exitCode;
-        }
-        if (signal !== null) {
-            this.signal = signal;
-        }
-        this.stderrBytes = stderrBytes;
-        this.stderrLineCount = stderrLineCount;
-        this.staleResume = staleResume;
-    }
-}
-function formatClaudeCliFailureMessage(exitCode, signal, stderrBytes, stderrLineCount) {
-    const processOutcome = signal ? `signal ${signal}` : `code ${String(exitCode ?? 'unknown')}`;
-    const lineLabel = stderrLineCount === 1 ? 'line' : 'lines';
-    return `Claude CLI failed with ${processOutcome} (stderr: ${stderrBytes} bytes across ${stderrLineCount} ${lineLabel})`;
-}
-function matchesStaleResumeText(text) {
-    const normalized = text.toLowerCase();
-    return normalized.includes('session not found')
-        || normalized.includes('cannot resume')
-        || normalized.includes('no conversation found with session id');
-}
-function isStaleResumeFailure(error) {
-    if (error instanceof ClaudeCliProcessError) {
-        return error.staleResume;
-    }
-    const message = normalizeError(error).message.toLowerCase();
-    return matchesStaleResumeText(message);
+function hasVisibleText(value) {
+    return typeof value === 'string' && value.trim().length > 0;
 }
 function normalizeError(error) {
     return error instanceof Error ? error : new Error(String(error));
@@ -58,6 +40,9 @@ function parsePersistedSessionRecord(rawValue) {
                 cwd: typeof parsed.cwd === 'string' && parsed.cwd.trim().length > 0
                     ? parsed.cwd
                     : undefined,
+                visibilityKey: typeof parsed.visibilityKey === 'string' && parsed.visibilityKey.trim().length > 0
+                    ? parsed.visibilityKey
+                    : undefined,
             };
         }
     }
@@ -67,15 +52,117 @@ function serializePersistedSessionRecord(record) {
     return JSON.stringify({
         sessionId: record.sessionId,
         ...(record.cwd ? { cwd: record.cwd } : {}),
+        ...(record.visibilityKey ? { visibilityKey: record.visibilityKey } : {}),
     });
 }
+function formatClaudeAcpFailureMessage(exitCode, signal, stderrBytes, stderrLineCount) {
+    const processOutcome = signal ? `signal ${signal}` : `code ${String(exitCode ?? 'unknown')}`;
+    const lineLabel = stderrLineCount === 1 ? 'line' : 'lines';
+    return `Claude ACP process failed with ${processOutcome} (stderr: ${stderrBytes} bytes across ${stderrLineCount} ${lineLabel})`;
+}
+class ClaudeCliProcessError extends Error {
+    exitCode;
+    signal;
+    stderrBytes;
+    stderrLineCount;
+    constructor(exitCode, signal, stderrBytes, stderrLineCount) {
+        super(formatClaudeAcpFailureMessage(exitCode, signal, stderrBytes, stderrLineCount));
+        this.name = 'ClaudeCliProcessError';
+        if (exitCode !== null) {
+            this.exitCode = exitCode;
+        }
+        if (signal !== null) {
+            this.signal = signal;
+        }
+        this.stderrBytes = stderrBytes;
+        this.stderrLineCount = stderrLineCount;
+    }
+}
+function formatToolProgress(title, status) {
+    const normalizedTitle = hasVisibleText(title) ? title.trim() : null;
+    switch (status) {
+        case 'completed':
+            return normalizedTitle ? `Completed ${normalizedTitle}` : 'Completed tool call';
+        case 'failed':
+            return normalizedTitle ? `Failed ${normalizedTitle}` : 'Tool call failed';
+        case 'pending':
+        case 'in_progress':
+        case undefined:
+        case null:
+            return normalizedTitle ? `Running ${normalizedTitle}…` : 'Running tool…';
+        default:
+            return normalizedTitle ? `${status} ${normalizedTitle}` : status;
+    }
+}
+function formatPlanProgress(entries) {
+    const current = entries.find((entry) => entry.status === 'in_progress') ??
+        entries.find((entry) => entry.status === 'pending') ??
+        entries[0];
+    return hasVisibleText(current?.content) ? `Plan: ${current.content.trim()}` : null;
+}
+class ClaudeProgressCollector {
+    onProgress;
+    publicText = '';
+    lastPublished = null;
+    toolTitles = new Map();
+    constructor(onProgress) {
+        this.onProgress = onProgress;
+    }
+    consume(update) {
+        switch (update.update.sessionUpdate) {
+            case 'agent_message_chunk':
+                if (update.update.content.type !== 'text') {
+                    return;
+                }
+                this.publicText += update.update.content.text;
+                this.publish(this.publicText);
+                return;
+            case 'tool_call':
+                this.toolTitles.set(update.update.toolCallId, update.update.title);
+                this.publishFallback(formatToolProgress(update.update.title, update.update.status));
+                return;
+            case 'tool_call_update': {
+                const nextTitle = update.update.title ?? this.toolTitles.get(update.update.toolCallId);
+                if (hasVisibleText(nextTitle)) {
+                    this.toolTitles.set(update.update.toolCallId, nextTitle);
+                }
+                this.publishFallback(formatToolProgress(nextTitle, update.update.status));
+                return;
+            }
+            case 'plan':
+                this.publishFallback(formatPlanProgress(update.update.entries.map((entry) => ({
+                    content: entry.content,
+                    status: entry.status,
+                }))));
+                return;
+            default:
+                return;
+        }
+    }
+    getFinalText() {
+        return this.publicText.trim();
+    }
+    publishFallback(text) {
+        if (hasVisibleText(this.publicText)) {
+            return;
+        }
+        this.publish(text);
+    }
+    publish(text) {
+        if (!this.onProgress || !hasVisibleText(text) || text === this.lastPublished) {
+            return;
+        }
+        this.lastPublished = text;
+        this.onProgress({ text });
+    }
+}
 function createDeferredTurn(channelId, prompt, sessionPersistence, promptContext, options) {
     let settled = false;
     let resolvePromise;
     let rejectPromise;
-    const promise = new Promise((resolve, reject) => {
-        resolvePromise = resolve;
-        rejectPromise = reject;
+    const promise = new Promise((resolvePromiseParam, rejectPromiseParam) => {
+        resolvePromise = resolvePromiseParam;
+        rejectPromise = rejectPromiseParam;
     });
     return {
         channelId,
@@ -98,145 +185,171 @@ function createDeferredTurn(channelId, prompt, sessionPersistence, promptContext
         },
     };
 }
+function resolveSessionRouting(turn) {
+    return {
+        channelId: turn.channelId,
+        key: turn.providerSessionRouting?.key ?? turn.channelId,
+        persistence: turn.providerSessionRouting?.persistence ?? 'persistent',
+    };
+}
 function asObject(value) {
     return typeof value === 'object' && value !== null ? value : null;
 }
-function asString(value) {
-    return typeof value === 'string' ? value : undefined;
+function readSessionCapabilities(response) {
+    const agentCapabilities = asObject(asObject(response)?.agentCapabilities);
+    const sessionCapabilities = asObject(agentCapabilities?.sessionCapabilities ?? agentCapabilities?.session);
+    return {
+        loadSession: agentCapabilities?.loadSession === true,
+        resumeSession: asObject(sessionCapabilities?.resume) !== null,
+    };
 }
-function hasVisibleText(value) {
-    return typeof value === 'string' && value.trim().length > 0;
+function isStaleRestoreFailure(error) {
+    const normalized = normalizeError(error);
+    const code = asObject(error)?.code;
+    const dataCode = asObject(asObject(error)?.data)?.code;
+    if (code === 'session_not_found' || dataCode === 'session_not_found') {
+        return true;
+    }
+    const message = normalized.message.toLowerCase();
+    return message.includes('session not found')
+        || message.includes('unknown session')
+        || message.includes('cannot resume')
+        || message.includes('no conversation found with session id')
+        || message.includes('not found');
+}
+function markSessionTainted(error) {
+    const normalized = normalizeError(error);
+    SESSION_TAINTED_ERRORS.add(normalized);
+    return normalized;
+}
+function isSessionTainted(error) {
+    return error instanceof Error && SESSION_TAINTED_ERRORS.has(error);
+}
+function resolveBundledClaudeAdapterPath() {
+    return require.resolve('@agentclientprotocol/claude-agent-acp/dist/index.js');
 }
 function isRelativePathLike(value) {
     return value.startsWith('./') || value.startsWith('../');
 }
+function useBundledClaudeAdapter(command, args) {
+    return command === DEFAULT_CLAUDE_COMMAND;
+}
+function useLegacyClaudeCompatibilityAlias(command, args) {
+    return isLegacyClaudeCompatibilityAlias(command, args);
+}
 function resolveClaudeLaunch(command, args, baseCwd) {
-    const resolvedCommand = isRelativePathLike(command) ? resolve(baseCwd, command) : command;
-    const resolvedArgs = args.map((arg) => (isRelativePathLike(arg) ? resolve(baseCwd, arg) : arg));
+    if (useBundledClaudeAdapter(command, args)) {
+        return {
+            command: process.execPath,
+            args: [resolveBundledClaudeAdapterPath(), ...args],
+        };
+    }
+    if (useLegacyClaudeCompatibilityAlias(command, args)) {
+        return {
+            command: process.execPath,
+            args: [resolveBundledClaudeAdapterPath()],
+        };
+    }
     return {
-        command: resolvedCommand,
-        args: resolvedArgs,
+        command: isRelativePathLike(command) ? resolve(baseCwd, command) : command,
+        args: args.map((arg) => (isRelativePathLike(arg) ? resolve(baseCwd, arg) : arg)),
     };
 }
-function readTextBlocks(blocks) {
-    if (!Array.isArray(blocks)) {
-        return [];
+function buildClaudeSessionSystemPrompt(promptContext) {
+    if (!promptContext) {
+        return undefined;
     }
-    const segments = [];
-    for (const entry of blocks) {
-        const block = asObject(entry);
-        if (!block)
-            continue;
-        if (block.type === 'text' && hasVisibleText(asString(block.text))) {
-            segments.push(asString(block.text));
-        }
+    const lines = [];
+    if (promptContext.channelContextPayloadPath) {
+        lines.push('Channel-scoped local context is available for this session.');
+        lines.push(`Channel context payload: ${promptContext.channelContextPayloadPath}`);
     }
-    return segments;
-}
-function extractTextDelta(event) {
-    if (event.type === 'content_block_delta') {
-        const delta = asObject(event.delta);
-        if (!delta)
-            return null;
-        const deltaType = asString(delta.type);
-        if (deltaType !== undefined && deltaType !== 'text_delta') {
-            return null;
-        }
-        return asString(delta.text) ?? null;
+    if (promptContext.skillRuntime) {
+        lines.push(`Skill guide: ${promptContext.skillRuntime.skillMarkdownPath}`);
+        lines.push(`Node bootstrap CLI: node ${promptContext.skillRuntime.nodeCliPath} --context ${promptContext.channelContextPayloadPath} --print-bootstrap`);
+        lines.push(`Python bootstrap CLI: python3 ${promptContext.skillRuntime.pythonCliPath} --context ${promptContext.channelContextPayloadPath} --print-bootstrap`);
     }
-    if (event.type === 'content_block_start') {
-        const block = asObject(event.content_block) ?? asObject(event.block);
-        if (!block || block.type !== 'text') {
-            return null;
+    if (promptContext.localhostGateway && promptContext.gatewayAuthPath) {
+        lines.push(`Gateway auth sidecar for this session: ${promptContext.gatewayAuthPath}`);
+        if (promptContext.localhostGateway.baseUrl) {
+            lines.push(`Loopback gateway base URL: ${promptContext.localhostGateway.baseUrl}`);
         }
-        return asString(block.text) ?? null;
     }
-    return null;
-}
-function extractToolSummary(event) {
-    if (event.type === 'tool_use') {
-        const toolName = asString(event.name) ?? asString(event.tool_name);
-        return hasVisibleText(toolName) ? `Running ${toolName}…` : 'Running tool…';
+    if (promptContext.taskWorkspace) {
+        lines.push(`Task-scoped writable workspace root: ${promptContext.taskWorkspace.rootPath}.`);
+        lines.push('This writable workspace is local to agents-host for the current task thread and does not imply that the target repository is already checked out there.');
     }
-    if (event.type === 'content_block_start') {
-        const block = asObject(event.content_block) ?? asObject(event.block);
-        if (!block || block.type !== 'tool_use') {
-            return null;
-        }
-        const toolName = asString(block.name);
-        return hasVisibleText(toolName) ? `Running ${toolName}…` : 'Running tool…';
+    if (promptContext.taskAssignmentContext?.currentTaskId) {
+        lines.push(`Current assigned task id: ${promptContext.taskAssignmentContext.currentTaskId}.`);
     }
-    return null;
+    return lines.length > 0 ? lines.join('\n') : undefined;
 }
-function extractFinalText(event) {
-    if (event.type === 'result') {
-        const result = asString(event.result);
-        if (result !== undefined) {
-            return result;
-        }
-    }
-    if (event.type === 'message' || event.type === 'assistant') {
-        const message = asObject(event.message) ?? event;
-        const joined = readTextBlocks(message.content).join('');
-        if (joined.length > 0) {
-            return joined;
-        }
+function buildClaudeSessionMeta(promptContext) {
+    const systemPromptAppend = buildClaudeSessionSystemPrompt(promptContext);
+    if (!systemPromptAppend) {
+        return undefined;
     }
-    return null;
+    return {
+        systemPrompt: {
+            append: systemPromptAppend,
+        },
+    };
 }
-class ClaudeStreamCollector {
-    onProgress;
-    publicText = '';
-    finalText = null;
-    lastPublished = null;
-    constructor(onProgress) {
-        this.onProgress = onProgress;
+function resolveSessionAdditionalDirectories(promptContext) {
+    const directories = new Set();
+    if (promptContext?.channelContextPayloadPath) {
+        directories.add(dirname(promptContext.channelContextPayloadPath));
     }
-    consume(event) {
-        const payload = event.type === 'stream_event' ? asObject(event.event) ?? event : event;
-        const textDelta = extractTextDelta(payload);
-        if (textDelta !== null) {
-            this.publicText += textDelta;
-            this.publish(this.publicText);
-        }
-        if (!hasVisibleText(this.publicText)) {
-            const toolSummary = extractToolSummary(payload);
-            if (toolSummary) {
-                this.publish(toolSummary);
-            }
-        }
-        const finalText = extractFinalText(event) ?? extractFinalText(payload);
-        if (finalText !== null) {
-            this.finalText = finalText;
-        }
+    if (promptContext?.gatewayAuthPath) {
+        directories.add(dirname(promptContext.gatewayAuthPath));
     }
-    getFinalText() {
-        const text = this.finalText ?? this.publicText;
-        return hasVisibleText(text) ? text : '';
+    if (promptContext?.skillRuntime?.skillDirectoryPath) {
+        directories.add(promptContext.skillRuntime.skillDirectoryPath);
     }
-    publish(text) {
-        if (!this.onProgress || !hasVisibleText(text) || text === this.lastPublished) {
-            return;
-        }
-        this.lastPublished = text;
-        this.onProgress({ text });
+    return directories.size > 0 ? [...directories].sort((left, right) => left.localeCompare(right)) : undefined;
+}
+function resolveSessionVisibilityKey(promptContext) {
+    const additionalDirectories = resolveSessionAdditionalDirectories(promptContext);
+    if (!additionalDirectories) {
+        return undefined;
     }
+    return JSON.stringify({ additionalDirectories });
 }
-function resolveSessionRouting(turn) {
+function buildSessionRequest(cwd, promptContext, additionalDirectories) {
+    const meta = buildClaudeSessionMeta(promptContext);
     return {
-        channelId: turn.channelId,
-        key: turn.providerSessionRouting?.key ?? turn.channelId,
-        persistence: turn.providerSessionRouting?.persistence ?? 'persistent',
+        cwd,
+        mcpServers: [],
+        ...(additionalDirectories && additionalDirectories.length > 0
+            ? { additionalDirectories }
+            : {}),
+        ...(meta ? { _meta: meta } : {}),
     };
 }
+function shouldReusePersistedSession(record, cwd, runtimeCwd, visibilityKey) {
+    if (record.cwd) {
+        if (record.cwd !== cwd) {
+            return false;
+        }
+    }
+    else if (cwd !== runtimeCwd) {
+        return false;
+    }
+    if (visibilityKey !== undefined) {
+        return record.visibilityKey === visibilityKey;
+    }
+    if (record.visibilityKey !== undefined) {
+        return false;
+    }
+    return true;
+}
 /**
- * CLI client for the Claude Code CLI (`claude`) non-interactive mode, with
- * native provider-session continuity.
+ * Persistent ACP-backed client for the Claude ACP adapter.
  *
- * Claude session memory remains entirely inside the Claude CLI. This client
- * only pins one native session id per routed provider session and serializes
- * turns per route so `--resume` is never called concurrently for the same
- * native session.
+ * The public caller surface intentionally stays stable: callers still create a
+ * `ClaudeCliClient`, then call `generateReply()` and `dispose()`. Internally,
+ * the shipped runtime now runs one Claude ACP adapter process and reuses one
+ * ACP session per routed Borgee channel.
  */
 export class ClaudeCliClient {
     command;
@@ -247,21 +360,42 @@ export class ClaudeCliClient {
     runtime;
     channels = new Map();
     persistedSessions = new Map();
+    closingSessions = new WeakSet();
+    pendingSessionStarts = new Set();
+    pendingSessionCloses = new Set();
+    pendingSessionStoreOperations = new Set();
+    fatalPromise;
+    rejectFatalPromise;
+    child;
+    connection;
+    startPromise;
+    shutdownPromise;
+    childExitPromise;
+    resolveChildExit;
+    fatalError = null;
+    disposing = false;
+    backendClosed = false;
     loadedSessionStoreAgentId = null;
-    stopped = false;
     sessionStoreLoadPromise = null;
     sessionStoreWriteQueue = Promise.resolve();
-    constructor(command, args, runtimeOverrides = {}, sessionStore, resolveSessionStoreAgentId = () => undefined, logger = new HostLogger()) {
+    sessionCapabilities = DEFAULT_SESSION_CAPABILITIES;
+    childStderr = '';
+    constructor(command, args = [], runtimeOverrides = {}, sessionStore, resolveSessionStoreAgentId = () => undefined, logger = new HostLogger()) {
         this.command = command;
         this.args = args;
         this.sessionStore = sessionStore;
         this.resolveSessionStoreAgentId = resolveSessionStoreAgentId;
         this.logger = logger;
         this.runtime = { ...DEFAULT_RUNTIME, ...runtimeOverrides };
+        assertClaudeCommandCompatibility(command, args, 'Claude provider runtime');
+        this.fatalPromise = new Promise((_, reject) => {
+            this.rejectFatalPromise = reject;
+        });
+        void this.fatalPromise.catch(() => { });
     }
     async generateReply(channelIdOrTurn, promptOrOptions, maybeOptions) {
-        if (this.stopped) {
-            throw new Error('Claude CLI backend stopped');
+        if (this.fatalError) {
+            throw this.fatalError;
         }
         const preparedTurn = typeof channelIdOrTurn === 'string'
             ? {
@@ -273,42 +407,145 @@ export class ClaudeCliClient {
             ? maybeOptions
             : promptOrOptions;
         const sessionRouting = resolveSessionRouting(preparedTurn);
-        const state = this.getOrCreateChannelState(sessionRouting.key, sessionRouting.persistence);
-        const pendingTurn = createDeferredTurn(preparedTurn.channelId, preparedTurn.prompt, sessionRouting.persistence, preparedTurn.promptContext, options);
-        state.queue.push(pendingTurn);
+        const state = this.getOrCreateChannelState(sessionRouting.key, preparedTurn.channelId, sessionRouting.persistence);
+        const turn = createDeferredTurn(preparedTurn.channelId, preparedTurn.prompt, sessionRouting.persistence, preparedTurn.promptContext, options);
+        state.queue.push(turn);
         this.processChannelQueue(sessionRouting.key, state);
-        return pendingTurn.promise;
+        return turn.promise;
     }
     async dispose() {
-        if (this.stopped)
-            return;
-        this.stopped = true;
-        const stoppedError = new Error('Claude CLI backend stopped');
-        for (const state of this.channels.values()) {
-            state.activeTurn?.reject(stoppedError);
-            for (const queuedTurn of state.queue) {
-                queuedTurn.reject(stoppedError);
+        const error = new Error('Claude ACP backend stopped');
+        this.disposing = true;
+        this.logger?.debug('stopping Claude ACP backend');
+        const closed = this.connection?.closed ?? Promise.resolve();
+        this.failAll(error);
+        let thrown;
+        try {
+            await Promise.all([closed, this.shutdownPromise ?? Promise.resolve()]);
+        }
+        catch (disposeError) {
+            thrown = disposeError;
+        }
+        try {
+            await Promise.allSettled(this.pendingSessionStoreOperations);
+            await this.sessionStoreWriteQueue;
+            await this.sessionStore?.close?.();
+        }
+        catch (closeError) {
+            thrown ??= closeError;
+        }
+        if (thrown) {
+            throw thrown;
+        }
+    }
+    async ensureStarted() {
+        if (this.fatalError) {
+            throw this.fatalError;
+        }
+        if (!this.startPromise) {
+            this.startPromise = this.startBackend();
+        }
+        await this.startPromise;
+        if (this.fatalError) {
+            throw this.fatalError;
+        }
+        if (!this.connection) {
+            throw new Error('Claude ACP connection is not available');
+        }
+    }
+    async startBackend() {
+        const launch = resolveClaudeLaunch(this.command, this.args, this.runtime.cwd);
+        this.childStderr = '';
+        this.logger?.debug('starting Claude ACP process', {
+            command: launch.command,
+            args: launch.args,
+            cwd: this.runtime.cwd,
+        });
+        const child = this.runtime.spawn(launch.command, launch.args, {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            cwd: this.runtime.cwd,
+        });
+        this.child = child;
+        child.stderr.setEncoding('utf8');
+        child.stderr.on('data', (chunk) => {
+            this.childStderr += chunk;
+            this.logger?.childStderr('claude stderr', summarizeChildStderr(chunk));
+        });
+        child.stderr.resume();
+        this.logger?.debug('spawned Claude ACP process', { pid: child.pid });
+        child.once('error', (error) => {
+            this.logger?.debugError('Claude ACP process error', error);
+            this.failAll(new Error(`Claude ACP process error: ${normalizeError(error).message}`));
+        });
+        child.once('exit', (code, signal) => {
+            this.resolveChildExit?.();
+            if (this.disposing) {
+                this.logger?.debug('Claude ACP process exited during shutdown', { code, signal });
+                return;
             }
-            state.queue = [];
-            state.activeChild?.kill('SIGTERM');
+            const stderrSummary = summarizeChildStderr(this.childStderr);
+            const failure = new ClaudeCliProcessError(code, signal, stderrSummary.bytes, stderrSummary.lineCount);
+            this.logger?.debugError('Claude ACP process exited unexpectedly', {
+                code,
+                signal,
+                stderrBytes: stderrSummary.bytes,
+                stderrLineCount: stderrSummary.lineCount,
+            });
+            this.failAll(failure);
+        });
+        this.childExitPromise = new Promise((resolveChildExit) => {
+            this.resolveChildExit = resolveChildExit;
+        });
+        const output = Writable.toWeb(child.stdin);
+        const input = Readable.toWeb(child.stdout);
+        const stream = this.runtime.ndJsonStream(output, input);
+        const app = this.runtime
+            .client({ name: 'borgee-agents-host' })
+            .onRequest(this.runtime.methods.client.session.requestPermission, ({ params }) => (this.handlePermissionRequest(params)));
+        const connection = app.connect(stream);
+        this.connection = connection;
+        void connection.closed.then(() => {
+            if (!this.disposing) {
+                this.logger?.debugError('Claude ACP connection closed unexpectedly');
+                this.failAll(new Error('Claude ACP connection closed unexpectedly'));
+            }
+        });
+        try {
+            const initializeResponse = await connection.agent.request(this.runtime.methods.agent.initialize, {
+                protocolVersion: this.runtime.protocolVersion,
+                clientCapabilities: {},
+                clientInfo: {
+                    name: '@borgee/agents-host',
+                    version: '0.2.29',
+                },
+            });
+            this.sessionCapabilities = readSessionCapabilities(initializeResponse);
+            this.logger?.debug('initialized Claude ACP connection', {
+                loadSession: this.sessionCapabilities.loadSession,
+                resumeSession: this.sessionCapabilities.resumeSession,
+            });
+        }
+        catch (error) {
+            const normalized = new Error(`Claude ACP initialize failed: ${normalizeError(error).message}`);
+            this.logger?.debugError('Claude ACP initialize failed', normalized);
+            this.failAll(normalized);
+            throw normalized;
         }
-        await this.sessionStoreWriteQueue;
-        await this.sessionStore?.close?.();
     }
-    getOrCreateChannelState(channelId, sessionPersistence) {
+    getOrCreateChannelState(channelId, resolvedChannelId, sessionPersistence) {
         let state = this.channels.get(channelId);
         if (!state) {
             state = {
+                channelId: resolvedChannelId,
                 sessionPersistence,
                 processing: false,
                 queue: [],
-                sessionHydrated: false,
-                sessionEstablished: false,
             };
             this.channels.set(channelId, state);
         }
-        else if (state.sessionPersistence !== sessionPersistence) {
-            throw new Error(`Claude session routing persistence changed for key "${channelId}"`);
+        else if (state.channelId !== resolvedChannelId
+            || state.sessionPersistence !== sessionPersistence) {
+            throw new Error(`Claude session routing changed for key "${channelId}"`);
         }
         return state;
     }
@@ -319,28 +556,30 @@ export class ClaudeCliClient {
         state.processing = true;
         void (async () => {
             try {
-                while (!this.stopped) {
-                    const queuedTurn = state.queue[0];
-                    if (!queuedTurn) {
-                        return;
-                    }
-                    try {
-                        if (state.sessionPersistence === 'persistent' && await this.ensureSessionStoreLoaded()) {
-                            this.hydrateChannelState(channelId, state);
-                        }
-                    }
-                    catch (error) {
-                        state.queue.shift()?.reject(error);
-                        continue;
-                    }
+                while (!this.fatalError) {
                     const turn = state.queue.shift();
                     if (!turn) {
                         return;
                     }
                     state.activeTurn = turn;
                     try {
-                        const text = await this.runTurn(channelId, state, turn);
-                        turn.resolve(text);
+                        state.cwd = this.resolveSessionCwd(turn.promptContext);
+                        state.visibilityKey = resolveSessionVisibilityKey(turn.promptContext);
+                        await this.ensureStarted();
+                        await this.recycleSessionIfScopeChanged(channelId, state);
+                        const session = await this.getOrCreateSession(channelId, state, turn.promptContext);
+                        let reply;
+                        try {
+                            reply = await this.runTurn(session, turn.prompt, turn.options);
+                        }
+                        catch (error) {
+                            if (isSessionTainted(error)) {
+                                this.invalidateSession(channelId, state, session);
+                                this.rejectQueuedTurnsAfterSessionTaint(state, error);
+                            }
+                            throw error;
+                        }
+                        turn.resolve(reply);
                     }
                     catch (error) {
                         turn.reject(error);
@@ -352,54 +591,309 @@ export class ClaudeCliClient {
             }
             finally {
                 state.processing = false;
-                if (state.sessionPersistence === 'ephemeral' && !this.stopped && state.queue.length === 0) {
-                    state.sessionEstablished = false;
-                    state.sessionHydrated = false;
-                    state.sessionId = undefined;
+                if (state.sessionPersistence === 'ephemeral' && !this.fatalError && !this.disposing && state.queue.length === 0) {
+                    const session = state.session;
+                    state.session = undefined;
                     state.sessionCwd = undefined;
+                    state.sessionVisibilityKey = undefined;
+                    if (session) {
+                        this.closeSession(session);
+                    }
                     this.channels.delete(channelId);
                 }
-                if (state.queue.length > 0 && !this.stopped) {
+                if (state.queue.length > 0 && !this.fatalError) {
                     this.processChannelQueue(channelId, state);
                 }
             }
         })();
     }
-    async runTurn(channelId, state, turn) {
-        await this.resetSessionIfCwdChanged(channelId, state, turn);
-        return this.runTurnAttempt(channelId, state, turn, true);
+    async getOrCreateSession(channelId, state, promptContext) {
+        if (state.session) {
+            return state.session;
+        }
+        if (state.sessionPromise) {
+            return state.sessionPromise;
+        }
+        if (!this.connection) {
+            throw new Error('Claude ACP connection is not available');
+        }
+        const cwd = state.cwd ?? this.runtime.cwd;
+        const persistedSessionId = state.sessionPersistence === 'persistent'
+            ? await this.readPersistedSessionId(channelId, cwd, state.visibilityKey)
+            : undefined;
+        const additionalDirectories = resolveSessionAdditionalDirectories(promptContext);
+        const sessionPromise = persistedSessionId
+            ? this.restoreOrCreateSession(channelId, persistedSessionId, cwd, promptContext, additionalDirectories)
+            : this.startFreshSession(channelId, cwd, promptContext, additionalDirectories);
+        this.pendingSessionStarts.add(sessionPromise);
+        state.sessionPromise = sessionPromise;
+        let sessionAdopted = false;
+        void sessionPromise
+            .then((session) => {
+            if (!sessionAdopted &&
+                (this.fatalError !== null || this.disposing || state.sessionPromise !== sessionPromise)) {
+                this.closeSession(session);
+            }
+        })
+            .finally(() => {
+            this.pendingSessionStarts.delete(sessionPromise);
+        })
+            .catch(() => { });
+        try {
+            const session = await this.raceWithFatal(sessionPromise);
+            if (this.fatalError) {
+                this.closeSession(session);
+                throw this.fatalError;
+            }
+            sessionAdopted = true;
+            state.session = session;
+            state.sessionCwd = cwd;
+            state.sessionVisibilityKey = state.visibilityKey;
+            return session;
+        }
+        catch (error) {
+            state.session = undefined;
+            state.sessionCwd = undefined;
+            state.sessionVisibilityKey = undefined;
+            throw error;
+        }
+        finally {
+            if (state.sessionPromise === sessionPromise) {
+                state.sessionPromise = undefined;
+            }
+        }
+    }
+    async startFreshSession(channelId, cwd, promptContext, additionalDirectories) {
+        if (!this.connection) {
+            throw new Error('Claude ACP connection is not available');
+        }
+        const session = await this.connection.agent.buildSession(buildSessionRequest(cwd, promptContext, additionalDirectories)).start();
+        this.logger?.debug('started fresh Claude ACP session', { channelId, cwd });
+        const state = this.channels.get(channelId);
+        if (state?.sessionPersistence === 'persistent') {
+            await this.persistSessionBestEffort(channelId, session.sessionId, state.visibilityKey, cwd);
+        }
+        return session;
+    }
+    async restoreOrCreateSession(channelId, sessionId, cwd, promptContext, additionalDirectories) {
+        if (!this.sessionCapabilities.resumeSession) {
+            this.logger?.debug('Claude ACP restore unsupported; starting fresh session', { channelId });
+            return this.startFreshSession(channelId, cwd, promptContext, additionalDirectories);
+        }
+        try {
+            const session = await this.restoreSession(sessionId, cwd, promptContext, additionalDirectories);
+            this.logger?.debug('restored Claude ACP session', {
+                channelId,
+                restoreMethod: this.sessionCapabilities.resumeSession ? 'session/resume' : 'session/load',
+            });
+            return session;
+        }
+        catch (error) {
+            if (!isStaleRestoreFailure(error)) {
+                throw normalizeError(error);
+            }
+            this.logger?.debug('discarded stale Claude ACP session and started fresh', { channelId });
+            await this.clearPersistedSessionBestEffort(channelId);
+            return this.startFreshSession(channelId, cwd, promptContext, additionalDirectories);
+        }
     }
-    async runTurnAttempt(channelId, state, turn, allowFreshRetryAfterStaleResume) {
-        if (this.stopped) {
-            throw new Error('Claude CLI backend stopped');
+    async restoreSession(sessionId, cwd, promptContext, additionalDirectories) {
+        if (!this.connection) {
+            throw new Error('Claude ACP connection is not available');
+        }
+        const agent = this.connection.agent;
+        if (typeof agent.attachSession !== 'function') {
+            throw new Error('Claude ACP SDK does not expose session attachment helpers');
         }
-        const sessionId = state.sessionEstablished ? state.sessionId : randomUUID();
-        const sessionArgs = state.sessionEstablished ? ['--resume', sessionId] : ['--session-id', sessionId];
+        const session = agent.attachSession({ sessionId });
         try {
-            const text = await this.run(state, [...this.args, ...sessionArgs, ...STREAM_JSON_ARGS], turn.prompt, turn.promptContext, turn.options);
-            state.sessionId = sessionId;
-            state.sessionEstablished = true;
-            state.sessionCwd = this.resolveTurnCwd(turn);
-            if (turn.sessionPersistence === 'persistent') {
-                await this.persistSessionBestEffort(channelId, sessionId, state.sessionCwd);
+            const request = {
+                sessionId,
+                ...buildSessionRequest(cwd, promptContext, additionalDirectories),
+            };
+            if (this.sessionCapabilities.resumeSession) {
+                await this.connection.agent.request(this.runtime.methods.agent.session.resume, request);
+                return session;
+            }
+            if (this.sessionCapabilities.loadSession) {
+                await this.connection.agent.request(this.runtime.methods.agent.session.load, request);
+                this.clearBufferedSessionReplay(session);
+                return session;
             }
-            return text;
+            throw new Error('Claude ACP agent does not advertise session restore capabilities');
         }
         catch (error) {
-            if (state.sessionEstablished && isStaleResumeFailure(error)) {
-                if (turn.sessionPersistence === 'persistent') {
-                    await this.resetPersistedSessionBestEffort(channelId, state);
+            session.dispose();
+            throw normalizeError(error);
+        }
+    }
+    clearBufferedSessionReplay(session) {
+        const updates = session.updates;
+        if (updates && Array.isArray(updates.values)) {
+            updates.values = [];
+        }
+    }
+    resolveSessionCwd(promptContext) {
+        return promptContext?.taskWorkspace?.rootPath ?? this.runtime.cwd;
+    }
+    async recycleSessionIfScopeChanged(channelId, state) {
+        const session = state.session;
+        if (!session) {
+            return;
+        }
+        const nextCwd = state.cwd ?? this.runtime.cwd;
+        if (state.sessionCwd === nextCwd
+            && state.sessionVisibilityKey === state.visibilityKey) {
+            return;
+        }
+        this.logger?.debug('recycling Claude ACP session after session scope changed', {
+            channelId,
+            previousCwd: state.sessionCwd,
+            nextCwd,
+            previousVisibilityKey: state.sessionVisibilityKey,
+            nextVisibilityKey: state.visibilityKey,
+        });
+        state.session = undefined;
+        state.sessionCwd = undefined;
+        state.sessionVisibilityKey = undefined;
+        if (!this.disposing && !this.backendClosed && state.sessionPersistence === 'persistent') {
+            await this.clearPersistedSessionBestEffort(channelId);
+        }
+        this.closeSession(session);
+    }
+    async runTurn(session, prompt, options) {
+        const promptPromise = this.raceWithFatal(session.prompt(prompt));
+        const promptFailure = new Promise((_, reject) => {
+            void promptPromise.catch((error) => reject(markSessionTainted(error)));
+        });
+        const collector = new ClaudeProgressCollector(options?.onProgress);
+        for (;;) {
+            let update;
+            try {
+                update = await this.raceWithFatal(Promise.race([session.nextUpdate(), promptFailure]));
+            }
+            catch (error) {
+                if (this.fatalError && error === this.fatalError) {
+                    throw error;
                 }
-                else {
-                    state.sessionEstablished = false;
-                    state.sessionId = undefined;
+                throw markSessionTainted(error);
+            }
+            if (update.kind === 'stop') {
+                let response;
+                try {
+                    response = await promptPromise;
                 }
-                if (allowFreshRetryAfterStaleResume) {
-                    return this.runTurnAttempt(channelId, state, turn, false);
+                catch (error) {
+                    throw markSessionTainted(error);
                 }
+                const output = collector.getFinalText();
+                if (response.stopReason !== 'end_turn' && !hasVisibleText(output)) {
+                    throw new Error(`Claude ACP turn stopped with stopReason "${response.stopReason}"`);
+                }
+                return output;
+            }
+            collector.consume(update);
+        }
+    }
+    async raceWithFatal(promise) {
+        if (this.fatalError) {
+            throw this.fatalError;
+        }
+        return Promise.race([promise, this.fatalPromise]);
+    }
+    failAll(error) {
+        if (this.fatalError) {
+            return;
+        }
+        this.fatalError = error;
+        this.rejectFatalPromise(error);
+        for (const [channelId, state] of this.channels.entries()) {
+            state.activeTurn?.reject(error);
+            for (const turn of state.queue) {
+                turn.reject(error);
+            }
+            state.queue.length = 0;
+            if (state.session) {
+                this.closeSession(state.session);
+            }
+            state.session = undefined;
+            state.sessionCwd = undefined;
+            state.sessionVisibilityKey = undefined;
+            state.sessionPromise = undefined;
+            state.activeTurn = undefined;
+            if (!state.processing) {
+                this.channels.delete(channelId);
             }
-            throw error;
         }
+        this.channels.clear();
+        this.shutdownPromise = this.shutdownBackend(error);
+    }
+    handlePermissionRequest(params) {
+        return resolveCopilotPermissionResponse({
+            gateEnabled: true,
+            policyMode: 'enforce',
+            params,
+            logger: this.logger,
+            agentId: this.resolveSessionStoreAgentId()?.trim() || undefined,
+            channelId: this.findChannelIdBySessionId(params.sessionId),
+        });
+    }
+    invalidateSession(channelId, state, session) {
+        if (state.session === session) {
+            state.session = undefined;
+            state.sessionCwd = undefined;
+            state.sessionVisibilityKey = undefined;
+        }
+        this.logger?.debug('discarding tainted Claude ACP session', { channelId });
+        this.closeSession(session);
+        if (!this.disposing && !this.backendClosed && state.sessionPersistence === 'persistent') {
+            void this.clearPersistedSessionBestEffort(channelId);
+        }
+    }
+    closeSession(session) {
+        if (this.closingSessions.has(session)) {
+            return;
+        }
+        this.closingSessions.add(session);
+        const agent = this.connection?.agent;
+        const closeMethod = this.runtime.methods.agent.session?.close;
+        const closePromise = typeof agent?.closeSession === 'function'
+            ? agent.closeSession({ sessionId: session.sessionId })
+            : closeMethod
+                ? this.connection?.agent.request(closeMethod, { sessionId: session.sessionId })
+                : undefined;
+        session.dispose();
+        if (!closePromise) {
+            return;
+        }
+        let trackedClosePromise;
+        trackedClosePromise = Promise.resolve(closePromise)
+            .then(() => undefined)
+            .catch(() => { })
+            .finally(() => {
+            this.pendingSessionCloses.delete(trackedClosePromise);
+        });
+        this.pendingSessionCloses.add(trackedClosePromise);
+    }
+    rejectQueuedTurnsAfterSessionTaint(state, error) {
+        if (state.queue.length === 0) {
+            return;
+        }
+        const rejection = new Error('Claude ACP session was reset after a failed turn; queued turns were dropped instead of replaying them on a fresh session', {
+            cause: normalizeError(error),
+        });
+        for (const turn of state.queue) {
+            turn.reject(rejection);
+        }
+        state.queue.length = 0;
+    }
+    findChannelIdBySessionId(sessionId) {
+        for (const state of this.channels.values()) {
+            if (state.session?.sessionId === sessionId) {
+                return state.channelId;
+            }
+        }
+        return undefined;
     }
     currentSessionStoreAgentId() {
         const agentId = this.resolveSessionStoreAgentId()?.trim();
@@ -417,9 +911,6 @@ export class ClaudeCliClient {
             this.loadedSessionStoreAgentId = null;
             this.sessionStoreLoadPromise = null;
             this.persistedSessions.clear();
-            for (const state of this.channels.values()) {
-                state.sessionHydrated = false;
-            }
         }
         if (!this.sessionStoreLoadPromise) {
             this.sessionStoreLoadPromise = (async () => {
@@ -440,38 +931,41 @@ export class ClaudeCliClient {
         await this.sessionStoreLoadPromise;
         return true;
     }
-    hydrateChannelState(channelId, state) {
-        if (state.sessionHydrated) {
-            return;
+    async readPersistedSessionId(channelId, cwd, visibilityKey) {
+        if (!await this.ensureSessionStoreLoaded()) {
+            return undefined;
         }
-        state.sessionHydrated = true;
-        const persistedSession = this.persistedSessions.get(channelId);
-        if (!persistedSession) {
-            return;
+        const record = this.persistedSessions.get(channelId);
+        if (!record) {
+            return undefined;
         }
-        state.sessionId = persistedSession.sessionId;
-        state.sessionCwd = persistedSession.cwd;
-        state.sessionEstablished = true;
+        if (!shouldReusePersistedSession(record, cwd, this.runtime.cwd, visibilityKey)) {
+            await this.clearPersistedSessionBestEffort(channelId);
+            return undefined;
+        }
+        return record.sessionId;
     }
-    async persistSession(channelId, sessionId, cwd) {
+    async persistSession(channelId, sessionId, visibilityKey, cwd) {
         if (!this.sessionStore || !this.loadedSessionStoreAgentId) {
             return;
         }
         await this.enqueueSessionStoreWrite(async () => {
             const current = this.persistedSessions.get(channelId);
-            if (current?.sessionId === sessionId && current.cwd === cwd) {
+            if (current?.sessionId === sessionId
+                && current.cwd === cwd
+                && current.visibilityKey === visibilityKey) {
                 return;
             }
-            this.persistedSessions.set(channelId, { sessionId, cwd });
+            this.persistedSessions.set(channelId, { sessionId, cwd, visibilityKey });
             await this.sessionStore.save(this.loadedSessionStoreAgentId, Object.fromEntries([...this.persistedSessions.entries()].map(([persistedChannelId, record]) => [
                 persistedChannelId,
                 serializePersistedSessionRecord(record),
             ])));
         });
     }
-    async persistSessionBestEffort(channelId, sessionId, cwd) {
+    async persistSessionBestEffort(channelId, sessionId, visibilityKey, cwd) {
         try {
-            await this.persistSession(channelId, sessionId, cwd);
+            await this.trackSessionStoreOperation(this.persistSession(channelId, sessionId, visibilityKey, cwd));
         }
         catch (error) {
             this.logger.error('failed to persist Claude session map; keeping reply delivery', {
@@ -482,10 +976,7 @@ export class ClaudeCliClient {
             });
         }
     }
-    async resetPersistedSession(channelId, state) {
-        state.sessionEstablished = false;
-        state.sessionId = undefined;
-        state.sessionCwd = undefined;
+    async clearPersistedSession(channelId) {
         if (!this.sessionStore || !this.loadedSessionStoreAgentId) {
             return;
         }
@@ -500,28 +991,9 @@ export class ClaudeCliClient {
             ])));
         });
     }
-    resolveTurnCwd(turn) {
-        return turn.promptContext?.taskWorkspace?.rootPath ?? this.runtime.cwd;
-    }
-    async resetSessionIfCwdChanged(channelId, state, turn) {
-        if (!state.sessionEstablished) {
-            return;
-        }
-        const nextCwd = this.resolveTurnCwd(turn);
-        if (state.sessionCwd === nextCwd) {
-            return;
-        }
-        if (turn.sessionPersistence === 'persistent') {
-            await this.resetPersistedSessionBestEffort(channelId, state);
-            return;
-        }
-        state.sessionEstablished = false;
-        state.sessionId = undefined;
-        state.sessionCwd = undefined;
-    }
-    async resetPersistedSessionBestEffort(channelId, state) {
+    async clearPersistedSessionBestEffort(channelId) {
         try {
-            await this.resetPersistedSession(channelId, state);
+            await this.trackSessionStoreOperation(this.clearPersistedSession(channelId));
         }
         catch (error) {
             this.logger.error('failed to clear stale Claude session map; retrying in-memory only', {
@@ -532,88 +1004,82 @@ export class ClaudeCliClient {
         }
     }
     async enqueueSessionStoreWrite(writeOperation) {
-        const queuedWrite = this.sessionStoreWriteQueue.then(writeOperation);
-        this.sessionStoreWriteQueue = queuedWrite.catch(() => undefined);
-        await queuedWrite;
-    }
-    async run(state, args, prompt, promptContext, options) {
-        return new Promise((resolve, reject) => {
-            const launch = resolveClaudeLaunch(this.command, args, this.runtime.cwd);
-            const child = this.runtime.spawn(launch.command, launch.args, {
-                stdio: ['pipe', 'pipe', 'pipe'],
-                cwd: promptContext?.taskWorkspace?.rootPath ?? this.runtime.cwd,
-            });
-            state.activeChild = child;
-            const collector = new ClaudeStreamCollector(options?.onProgress);
-            let stderr = '';
-            let lineBuffer = '';
-            let settled = false;
-            const settleReject = (error) => {
-                if (settled)
-                    return;
-                settled = true;
-                reject(normalizeError(error));
-            };
-            const settleResolve = (value) => {
-                if (settled)
-                    return;
-                settled = true;
-                resolve(value);
-            };
-            child.stdout.setEncoding('utf8');
-            child.stderr.setEncoding('utf8');
-            child.stdout.on('data', (chunk) => {
-                lineBuffer += chunk;
-                while (true) {
-                    const newlineIndex = lineBuffer.indexOf('\n');
-                    if (newlineIndex === -1) {
-                        break;
-                    }
-                    const line = lineBuffer.slice(0, newlineIndex).trim();
-                    lineBuffer = lineBuffer.slice(newlineIndex + 1);
-                    if (!line)
-                        continue;
-                    try {
-                        const event = JSON.parse(line);
-                        collector.consume(event);
-                    }
-                    catch (error) {
-                        settleReject(new Error(`Claude stream-json parse failed: ${normalizeError(error).message}`));
-                        child.kill('SIGTERM');
-                        return;
-                    }
-                }
-            });
-            child.stderr.on('data', (chunk) => {
-                stderr += chunk;
-                this.logger?.childStderr('claude stderr', summarizeChildStderr(chunk));
-            });
-            child.once('error', (error) => {
-                settleReject(error);
-            });
-            child.once('close', (code, signal) => {
-                if (state.activeChild === child) {
-                    state.activeChild = undefined;
-                }
-                if (lineBuffer.trim().length > 0 && !settled) {
-                    try {
-                        collector.consume(JSON.parse(lineBuffer.trim()));
-                        lineBuffer = '';
-                    }
-                    catch (error) {
-                        settleReject(new Error(`Claude stream-json parse failed: ${normalizeError(error).message}`));
-                        return;
-                    }
-                }
-                if (code !== 0) {
-                    const stderrSummary = summarizeChildStderr(stderr);
-                    settleReject(new ClaudeCliProcessError(code, signal, stderrSummary.bytes, stderrSummary.lineCount, matchesStaleResumeText(stderr)));
-                    return;
-                }
-                settleResolve(collector.getFinalText());
-            });
-            child.stdin.write(prompt);
-            child.stdin.end();
+        const write = this.sessionStoreWriteQueue.then(writeOperation);
+        this.sessionStoreWriteQueue = write.catch(() => { });
+        await write;
+    }
+    async trackSessionStoreOperation(operation) {
+        const tracked = operation.finally(() => {
+            this.pendingSessionStoreOperations.delete(tracked);
         });
+        this.pendingSessionStoreOperations.add(tracked);
+        return tracked;
+    }
+    async shutdownBackend(error) {
+        if (this.backendClosed) {
+            return;
+        }
+        this.backendClosed = true;
+        const connection = this.connection;
+        const child = this.child;
+        await this.waitForPendingSessionStarts();
+        await this.waitForPendingSessionCloses();
+        connection?.close(error);
+        this.connection = undefined;
+        if (!child) {
+            this.child = undefined;
+            return;
+        }
+        const childExitPromise = this.childExitPromise ?? Promise.resolve();
+        this.logger?.debug('sending SIGTERM to Claude ACP process');
+        child.kill('SIGTERM');
+        const exitedAfterTerm = await this.waitForChildExit(childExitPromise, this.runtime.shutdownGracePeriodMs);
+        if (exitedAfterTerm) {
+            this.logger?.debug('Claude ACP process exited after SIGTERM');
+            this.child = undefined;
+            return;
+        }
+        this.logger?.debug('sending SIGKILL to Claude ACP process after SIGTERM grace timeout');
+        child.kill('SIGKILL');
+        await this.waitForChildExit(childExitPromise, this.runtime.shutdownForceKillWaitMs);
+        this.child = undefined;
+    }
+    async waitForPendingSessionStarts() {
+        if (this.pendingSessionStarts.size === 0) {
+            return;
+        }
+        await Promise.race([
+            Promise.allSettled([...this.pendingSessionStarts]).then(() => undefined),
+            new Promise((resolveDelay) => {
+                setTimeout(resolveDelay, this.runtime.shutdownGracePeriodMs);
+            }),
+        ]);
+    }
+    async waitForPendingSessionCloses() {
+        if (this.pendingSessionCloses.size === 0) {
+            return;
+        }
+        await Promise.race([
+            Promise.allSettled([...this.pendingSessionCloses]).then(() => undefined),
+            new Promise((resolveDelay) => {
+                setTimeout(resolveDelay, this.runtime.shutdownGracePeriodMs);
+            }),
+        ]);
+    }
+    async waitForChildExit(childExitPromise, timeoutMs) {
+        let timeoutHandle;
+        try {
+            return await Promise.race([
+                childExitPromise.then(() => true),
+                new Promise((resolveDelay) => {
+                    timeoutHandle = setTimeout(() => resolveDelay(false), timeoutMs);
+                }),
+            ]);
+        }
+        finally {
+            if (timeoutHandle) {
+                clearTimeout(timeoutHandle);
+            }
+        }
     }
 }