@bbigbang/agent-node 0.1.0

package/dist/executor.js

@@ -0,0 +1,1078 @@
+import { createRequire } from 'node:module';
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { ToolAuth, WorkspaceLockManager, clearAcpSessionId, createSession, finishRun, getSession, upsertBinding, log, } from '@bbigbang/runtime-acp';
+import { getRuntimeDriver, } from '@bbigbang/protocol';
+import { AgentHost, HostDispatchRejectedError } from './agentHost.js';
+import { ensureIsolatedClaudeConfig } from './claudeConfig.js';
+import { ensureNativeSkillMounts } from './nativeSkillMounts.js';
+import { ensureWorkspaceScaffold, migrateWorkspaceLegacyFiles } from './workspaceFs.js';
+import { enqueueDispatch, listPendingDispatches, removeDispatch, removeDispatchesForHostKey, removeDispatchesForSessionKey, updateDispatchState, } from './dispatchQueueStore.js';
+import { buildHostAssetCacheRoot } from './assetCachePaths.js';
+import { resolveBigbangCliEntry } from './bigbangCli.js';
+import { mergeDreamRuntimeEnv } from './dreamEnv.js';
+function isDreamHostKey(hostKey) {
+    return hostKey.startsWith('dream:');
+}
+import { SoloHost } from './soloHost.js';
+function resolveClaudeStartupModel(params) {
+    const explicitModel = params.explicitModel?.trim();
+    if (explicitModel)
+        return explicitModel;
+    const envModel = params.env?.ANTHROPIC_MODEL?.trim();
+    return envModel ? envModel : null;
+}
+function appendClaudeStartupArgs(agentArgs, params) {
+    const model = resolveClaudeStartupModel(params);
+    if (model) {
+        agentArgs.push('--model', model);
+    }
+}
+export class Executor {
+    db;
+    config;
+    toolAuth;
+    hosts = new Map();
+    hostBridgeSignatures = new Map();
+    hostAgentCommandEnvOverlays = new Map();
+    hostMetadata = new Map();
+    runToHost = new Map();
+    steerChains = new Map();
+    send;
+    terminalRunIds = new Set();
+    createHost;
+    createSoloHost;
+    hostSweepTimer;
+    workspaceLockManager;
+    restoredDispatchContext = new AsyncLocalStorage();
+    soloHosts = new Map();
+    closingSoloHosts = new Set();
+    constructor(params) {
+        this.db = params.db;
+        this.config = params.config;
+        this.toolAuth = new ToolAuth(params.db);
+        this.send = (msg) => {
+            if (msg.type === 'run.end') {
+                this.terminalRunIds.add(msg.runId);
+            }
+            params.send(msg);
+        };
+        this.createHost = params.createHost ?? ((hostParams) => new AgentHost(hostParams));
+        this.createSoloHost = params.createSoloHost ?? ((soloHostParams) => new SoloHost(soloHostParams));
+        this.workspaceLockManager = params.workspaceLockManager ?? new WorkspaceLockManager();
+        this.hostSweepTimer = setInterval(() => {
+            this.reapIdleHosts();
+            this.reapIdleSoloHosts();
+        }, this.config.hostSweepIntervalMs);
+        this.hostSweepTimer.unref?.();
+    }
+    buildHostConfigSignature(params) {
+        return JSON.stringify({
+            agentCommand: params.agentCommand,
+            agentArgs: params.agentArgs,
+            env: params.env,
+            model: params.agentType === 'claude_sdk' || params.agentType === 'codex_app_server' ? null : params.model ?? null,
+            reasoningEffort: params.agentType === 'claude_sdk' || params.agentType === 'codex_app_server' ? null : params.reasoningEffort ?? null,
+            claudePermissionMode: null,
+            codexServiceTier: params.agentType === 'codex_app_server' ? null : params.codexServiceTier ?? null,
+            systemPromptText: params.systemPromptText ?? null,
+            disabledToolKinds: [...(params.disabledToolKinds ?? [])].sort(),
+            assetAccessConfig: params.assetAccessConfig ?? null,
+            agentSurfaceMode: params.agentSurfaceMode,
+            workspaceRoot: params.workspaceRoot,
+        });
+    }
+    buildChannelBridgeMcpEntry(params) {
+        try {
+            const req = createRequire(import.meta.url);
+            const binPath = req.resolve('@bbigbang/channel-bridge');
+            const args = [
+                binPath,
+                '--agent-id',
+                params.agentId,
+                '--conversation-id',
+                params.conversationId,
+                '--server-url',
+                params.serverUrl,
+                '--asset-cache-root',
+                params.assetCacheRoot,
+                '--run-context-path',
+                path.join(params.assetCacheRoot, 'run-context.json'),
+                '--workspace-path',
+                params.workspaceRoot,
+            ];
+            return {
+                name: 'chat',
+                command: 'node',
+                args,
+                env: params.authToken ? [{ name: 'CHANNEL_BRIDGE_AUTH_TOKEN', value: params.authToken }] : [],
+            };
+        }
+        catch {
+            log.warn('[executor] channel-bridge package not found, skipping MCP injection');
+            return undefined;
+        }
+    }
+    buildAgentCommandEnvOverlay(params) {
+        if (!params.assetAccessConfig || !params.assetCacheRoot) {
+            return undefined;
+        }
+        const overlay = {
+            vars: {
+                BIGBANG_AGENT_ID: params.assetAccessConfig.agentId,
+                BIGBANG_CONVERSATION_ID: params.assetAccessConfig.conversationId,
+                BIGBANG_SERVER_URL: params.assetAccessConfig.serverUrl,
+                BIGBANG_RUN_CONTEXT_PATH: path.join(params.assetCacheRoot, 'run-context.json'),
+            },
+        };
+        if (params.assetAccessConfig.authToken) {
+            try {
+                fs.mkdirSync(params.assetCacheRoot, { recursive: true });
+                const tokenPath = path.join(params.assetCacheRoot, 'agent-command-token');
+                fs.writeFileSync(tokenPath, `${params.assetAccessConfig.authToken}\n`, { encoding: 'utf8', mode: 0o600 });
+                overlay.vars.BIGBANG_AUTH_TOKEN_FILE = tokenPath;
+            }
+            catch (error) {
+                log.warn('[executor] failed to write agent command token file; falling back to env token', {
+                    agentId: params.assetAccessConfig.agentId,
+                    conversationId: params.assetAccessConfig.conversationId,
+                    error: String(error?.message ?? error),
+                });
+                overlay.vars.BIGBANG_AUTH_TOKEN = params.assetAccessConfig.authToken;
+            }
+        }
+        try {
+            const bigbangEntry = resolveBigbangCliEntry();
+            if (!bigbangEntry) {
+                throw new Error('Bigbang CLI entrypoint not found');
+            }
+            const binDir = path.join(params.assetCacheRoot, 'bin');
+            fs.mkdirSync(binDir, { recursive: true });
+            const wrapperPath = path.join(binDir, process.platform === 'win32' ? 'bigbang.cmd' : 'bigbang');
+            if (process.platform === 'win32') {
+                fs.writeFileSync(wrapperPath, `@echo off\r\n"${process.execPath}" "${bigbangEntry}" %*\r\n`, { encoding: 'utf8', mode: 0o755 });
+            }
+            else {
+                fs.writeFileSync(wrapperPath, `#!/usr/bin/env bash\nexec "${process.execPath}" "${bigbangEntry}" "$@"\n`, { encoding: 'utf8', mode: 0o755 });
+            }
+            overlay.pathPrefix = binDir;
+            overlay.vars.BIGBANG_BIGBANG_BIN = wrapperPath;
+        }
+        catch (error) {
+            const message = String(error?.message ?? error);
+            log.warn('[executor] failed to expose bigbang CLI on runtime PATH', {
+                agentId: params.assetAccessConfig.agentId,
+                conversationId: params.assetAccessConfig.conversationId,
+                error: message,
+            });
+            throw new Error(`Failed to expose Bigbang CLI on runtime PATH: ${message}`);
+        }
+        return overlay;
+    }
+    mergeAgentCommandEnv(baseEnv, overlay) {
+        if (!overlay)
+            return baseEnv;
+        const env = { ...(baseEnv ?? {}), ...overlay.vars };
+        if (overlay.vars.BIGBANG_AUTH_TOKEN_FILE) {
+            delete env.BIGBANG_AUTH_TOKEN;
+        }
+        if (overlay.pathPrefix) {
+            env.PATH = `${overlay.pathPrefix}${path.delimiter}${baseEnv?.PATH ?? process.env.PATH ?? ''}`;
+        }
+        return env;
+    }
+    getOrCreateHost(params) {
+        ensureWorkspaceScaffold(params.workspaceRoot, params.agentName);
+        migrateWorkspaceLegacyFiles(params.workspaceRoot);
+        const hostConfigSignature = this.buildHostConfigSignature({
+            agentType: params.agentType,
+            agentCommand: params.agentCommand,
+            agentArgs: params.agentArgs,
+            env: params.env,
+            model: params.model,
+            reasoningEffort: params.reasoningEffort,
+            claudePermissionMode: params.claudePermissionMode,
+            codexServiceTier: params.codexServiceTier,
+            systemPromptText: params.systemPromptText,
+            disabledToolKinds: params.disabledToolKinds,
+            assetAccessConfig: params.assetAccessConfig,
+            agentSurfaceMode: params.agentSurfaceMode,
+            workspaceRoot: params.workspaceRoot,
+        });
+        let host = this.hosts.get(params.runtimeKey);
+        if (host?.getState() === 'failed') {
+            log.warn('[executor] recreating failed host', {
+                runtimeKey: params.runtimeKey,
+                sessionKey: params.sessionKey,
+                previousRunId: host.getCurrentRunId(),
+                lastError: host.getLastError(),
+            });
+            host.close();
+            this.hosts.delete(params.runtimeKey);
+            this.hostBridgeSignatures.delete(params.runtimeKey);
+            this.hostAgentCommandEnvOverlays.delete(params.runtimeKey);
+            this.hostMetadata.delete(params.runtimeKey);
+            host = undefined;
+        }
+        const previousBridgeSignature = this.hostBridgeSignatures.get(params.runtimeKey);
+        if (host &&
+            previousBridgeSignature !== hostConfigSignature &&
+            host.getState() === 'idle' &&
+            !host.getCurrentRunId() &&
+            !host.hasPendingApproval()) {
+            log.info('[executor] recreating host to refresh config', {
+                runtimeKey: params.runtimeKey,
+                sessionKey: params.sessionKey,
+            });
+            host.close();
+            this.hosts.delete(params.runtimeKey);
+            this.hostBridgeSignatures.delete(params.runtimeKey);
+            this.hostAgentCommandEnvOverlays.delete(params.runtimeKey);
+            this.hostMetadata.delete(params.runtimeKey);
+            host = undefined;
+        }
+        if (!host) {
+            const hostInstanceId = randomUUID();
+            const assetCacheRoot = params.assetAccessConfig
+                ? buildHostAssetCacheRoot(params.assetAccessConfig.agentId, params.assetAccessConfig.conversationId, hostInstanceId)
+                : undefined;
+            const channelBridgeMcpEntry = params.agentSurfaceMode === 'mcp' && params.assetAccessConfig && assetCacheRoot
+                ? this.buildChannelBridgeMcpEntry({
+                    ...params.assetAccessConfig,
+                    assetCacheRoot,
+                    workspaceRoot: params.workspaceRoot,
+                })
+                : undefined;
+            const agentCommandEnvOverlay = params.agentSurfaceMode === 'bigbang'
+                ? this.buildAgentCommandEnvOverlay({
+                    assetAccessConfig: params.assetAccessConfig,
+                    assetCacheRoot,
+                })
+                : undefined;
+            const hostEnv = this.mergeAgentCommandEnv(params.env, agentCommandEnvOverlay);
+            host = this.createHost({
+                hostKey: params.runtimeKey,
+                sessionKey: params.sessionKey,
+                bindingKey: params.bindingKey,
+                db: this.db,
+                config: { ...this.config, agentSurfaceMode: params.agentSurfaceMode },
+                toolAuth: this.toolAuth,
+                workspaceRoot: params.workspaceRoot,
+                agentType: params.agentType,
+                agentCommand: params.agentCommand,
+                agentArgs: params.agentArgs,
+                env: hostEnv,
+                model: params.model,
+                reasoningEffort: params.reasoningEffort,
+                claudePermissionMode: params.claudePermissionMode,
+                codexServiceTier: params.codexServiceTier,
+                disabledToolKinds: params.disabledToolKinds,
+                hostInstanceId,
+                channelBridgeMcpEntry,
+                assetAccessConfig: params.assetAccessConfig,
+                assetCacheRoot,
+                workspaceLockManager: this.workspaceLockManager,
+                send: this.send,
+                hooks: {
+                    onRunStart: (dispatchMsg) => {
+                        updateDispatchState(this.db, dispatchMsg.runId, 'running');
+                    },
+                    onAwaitingApproval: (dispatchMsg) => {
+                        updateDispatchState(this.db, dispatchMsg.runId, 'awaiting_approval');
+                    },
+                    onRunFinish: (dispatchMsg) => {
+                        removeDispatch(this.db, dispatchMsg.runId);
+                    },
+                },
+            });
+            this.hosts.set(params.runtimeKey, host);
+            this.hostBridgeSignatures.set(params.runtimeKey, hostConfigSignature);
+            this.hostAgentCommandEnvOverlays.set(params.runtimeKey, agentCommandEnvOverlay);
+            log.info('[executor] created runtime host', {
+                runtimeKey: params.runtimeKey,
+                sessionKey: params.sessionKey,
+                agentSurfaceMode: params.agentSurfaceMode,
+                channelBridgeMcpInjected: Boolean(channelBridgeMcpEntry),
+                agentCommandEnvInjected: Boolean(agentCommandEnvOverlay),
+            });
+        }
+        this.hostMetadata.set(params.runtimeKey, {
+            sessionKey: params.sessionKey,
+            workspaceRoot: params.workspaceRoot,
+            agentType: params.agentType,
+        });
+        return host;
+    }
+    ensureLocalSession(params) {
+        const existingSession = getSession(this.db, params.sessionKey);
+        if (!existingSession) {
+            createSession(this.db, {
+                sessionKey: params.sessionKey,
+                agentCommand: params.agentCommand,
+                agentArgs: params.agentArgs,
+                cwd: params.cwd,
+                loadSupported: false,
+            });
+            return;
+        }
+        if (existingSession.agentCommand !== params.agentCommand ||
+            existingSession.agentArgsJson !== JSON.stringify(params.agentArgs)) {
+            this.db.prepare(`UPDATE sessions
+         SET agent_command = ?, agent_args_json = ?, acp_session_id = NULL, system_prompt_text = NULL, load_supported = 0, updated_at = ?
+         WHERE session_key = ?`).run(params.agentCommand, JSON.stringify(params.agentArgs), Date.now(), params.sessionKey);
+        }
+    }
+    buildClaudeControlHost(target) {
+        const driver = getRuntimeDriver('claude_sdk');
+        const runtimeKey = target.hostKey || target.sessionKey;
+        const bindingKey = `node:${target.conversationId}:-:node_user`;
+        const workspaceRoot = target.workspaceRoot || this.config.workspaceRoot;
+        const runtimeEnv = {
+            ...(driver.defaultEnv ?? {}),
+            ...(target.envVars ?? {}),
+        };
+        const agentArgs = [...driver.args];
+        appendClaudeStartupArgs(agentArgs, { env: runtimeEnv });
+        const claudeConfigDir = ensureIsolatedClaudeConfig(workspaceRoot);
+        runtimeEnv.CLAUDE_CONFIG_DIR = claudeConfigDir;
+        ensureNativeSkillMounts({
+            agentType: 'claude_sdk',
+            workspaceRoot,
+        });
+        this.ensureLocalSession({
+            sessionKey: target.sessionKey,
+            agentCommand: driver.command,
+            agentArgs,
+            cwd: workspaceRoot,
+        });
+        upsertBinding(this.db, { platform: 'node', chatId: target.conversationId, threadId: null, userId: 'node_user' }, target.sessionKey);
+        return this.getOrCreateHost({
+            runtimeKey,
+            sessionKey: target.sessionKey,
+            bindingKey,
+            workspaceRoot,
+            agentType: 'claude_sdk',
+            agentCommand: driver.command,
+            agentArgs,
+            env: runtimeEnv,
+            disabledToolKinds: target.disabledToolKinds,
+            agentSurfaceMode: this.config.agentSurfaceMode,
+        });
+    }
+    async dispatch(msg, options) {
+        const shouldPersist = options?.persist !== false;
+        const isDreamDispatch = msg.dispatchMode === 'dream';
+        const effectiveAgentType = isDreamDispatch ? 'claude_sdk' : msg.agentType;
+        const effectiveMsg = isDreamDispatch
+            ? {
+                ...msg,
+                agentType: 'claude_sdk',
+                disabledToolKinds: [
+                    ...(msg.disabledToolKinds ?? []),
+                    'execute',
+                    'edit',
+                    'delete',
+                    'move',
+                ],
+            }
+            : msg;
+        const { runId, conversationId, sessionKey, prompt, hostKey } = effectiveMsg;
+        const agentSurfaceMode = effectiveMsg.agentSurfaceMode ?? this.config.agentSurfaceMode;
+        const bindingKey = `node:${conversationId}:-:node_user`;
+        const runtimeKey = hostKey || sessionKey;
+        const driver = getRuntimeDriver(effectiveAgentType);
+        const workspaceRoot = effectiveMsg.workspacePath ?? this.config.workspaceRoot;
+        const runtimeEnv = isDreamDispatch
+            ? mergeDreamRuntimeEnv({
+                ...(driver.defaultEnv ?? {}),
+                ...(effectiveMsg.envVars ?? {}),
+            })
+            : {
+                ...(driver.defaultEnv ?? {}),
+                ...(effectiveMsg.envVars ?? {}),
+            };
+        const agentArgs = [...driver.args];
+        if (msg.agentType === 'codex_acp' && msg.model?.trim()) {
+            agentArgs.push('-c', `model=${JSON.stringify(msg.model.trim())}`);
+        }
+        if (msg.agentType === 'codex_acp' && msg.reasoningEffort?.trim()) {
+            agentArgs.push('-c', `model_reasoning_effort=${JSON.stringify(msg.reasoningEffort.trim())}`);
+        }
+        if (msg.agentType === 'claude_acp') {
+            appendClaudeStartupArgs(agentArgs, { explicitModel: msg.model, env: runtimeEnv });
+        }
+        try {
+            if (msg.agentType === 'claude_acp' || msg.agentType === 'claude_sdk') {
+                const claudeConfigDir = ensureIsolatedClaudeConfig(workspaceRoot);
+                runtimeEnv.CLAUDE_CONFIG_DIR = claudeConfigDir;
+                ensureNativeSkillMounts({
+                    agentType: msg.agentType,
+                    workspaceRoot,
+                    skillRoots: msg.skillRoots,
+                    enabledSkillPaths: msg.enabledSkillPaths,
+                });
+            }
+            else {
+                ensureNativeSkillMounts({
+                    agentType: msg.agentType,
+                    workspaceRoot,
+                    skillRoots: msg.skillRoots,
+                    enabledSkillPaths: msg.enabledSkillPaths,
+                });
+            }
+        }
+        catch (error) {
+            const message = String(error?.message ?? error);
+            log.warn('[executor] failed to prepare native skill mounts', {
+                runId,
+                conversationId,
+                agentType: msg.agentType,
+                error: message,
+            });
+            this.send({
+                type: 'run.end',
+                runId,
+                conversationId,
+                error: `Failed to prepare native skill mounts: ${message}`,
+            });
+            throw error;
+        }
+        log.info('[executor] dispatch received', {
+            runId,
+            conversationId,
+            sessionKey,
+            runtimeKey,
+            dispatchMode: msg.dispatchMode,
+            agentType: msg.agentType,
+            agentSurfaceMode,
+        });
+        this.terminalRunIds.delete(runId);
+        if (shouldPersist) {
+            enqueueDispatch(this.db, effectiveMsg, 'queued');
+        }
+        // Ensure local session row exists (bindings has FK → sessions)
+        this.ensureLocalSession({
+            sessionKey,
+            agentCommand: driver.command,
+            agentArgs,
+            cwd: workspaceRoot,
+        });
+        // Ensure binding exists
+        upsertBinding(this.db, { platform: 'node', chatId: conversationId, threadId: null, userId: 'node_user' }, sessionKey);
+        const assetAccessConfig = effectiveMsg.channelBridgeConfig
+            ? {
+                agentId: effectiveMsg.channelBridgeConfig.agentId,
+                conversationId: effectiveMsg.channelBridgeConfig.conversationId,
+                serverUrl: effectiveMsg.channelBridgeConfig.serverUrl,
+                authToken: effectiveMsg.channelBridgeConfig.authToken,
+            }
+            : undefined;
+        const codexServiceTier = effectiveAgentType === 'codex_app_server' ? effectiveMsg.codexServiceTier : undefined;
+        let host;
+        try {
+            host = this.getOrCreateHost({
+                runtimeKey,
+                sessionKey,
+                bindingKey,
+                workspaceRoot,
+                agentName: effectiveMsg.agentName,
+                agentType: effectiveAgentType,
+                agentCommand: driver.command,
+                agentArgs,
+                env: runtimeEnv,
+                model: effectiveMsg.model,
+                reasoningEffort: effectiveMsg.reasoningEffort,
+                claudePermissionMode: effectiveMsg.claudePermissionMode,
+                codexServiceTier,
+                systemPromptText: effectiveMsg.systemPromptText,
+                disabledToolKinds: effectiveMsg.disabledToolKinds,
+                assetAccessConfig,
+                agentSurfaceMode,
+            });
+        }
+        catch (error) {
+            const message = String(error?.message ?? error);
+            log.warn('[executor] failed to prepare runtime host', {
+                runId,
+                conversationId,
+                runtimeKey,
+                agentSurfaceMode,
+                error: message,
+            });
+            removeDispatch(this.db, runId);
+            this.send({
+                type: 'run.end',
+                runId,
+                conversationId,
+                error: message,
+            });
+            throw error;
+        }
+        this.runToHost.set(runId, runtimeKey);
+        this.send({
+            type: 'run.accepted',
+            runId,
+            conversationId,
+        });
+        let dispatchSucceeded = false;
+        try {
+            const dispatchEnvVars = this.mergeAgentCommandEnv(runtimeEnv, this.hostAgentCommandEnvOverlays.get(runtimeKey));
+            await host.dispatch({
+                ...msg,
+                agentSurfaceMode,
+                envVars: dispatchEnvVars,
+            });
+            dispatchSucceeded = true;
+        }
+        catch (error) {
+            if (error instanceof HostDispatchRejectedError) {
+                log.warn('[executor] host rejected dispatch before run start', {
+                    runId,
+                    conversationId,
+                    runtimeKey,
+                    code: error.code,
+                    error: error.message,
+                });
+                this.send({
+                    type: 'run.end',
+                    runId,
+                    conversationId,
+                    error: error.message,
+                });
+            }
+            throw error;
+        }
+        finally {
+            this.runToHost.delete(runId);
+            if (!dispatchSucceeded || host.getState() === 'failed') {
+                removeDispatch(this.db, runId);
+            }
+        }
+    }
+    resumePendingDispatches() {
+        const pending = listPendingDispatches(this.db);
+        if (pending.length === 0)
+            return;
+        log.warn('[executor] restoring pending dispatches after node restart', {
+            count: pending.length,
+        });
+        for (const entry of pending) {
+            if (entry.state === 'awaiting_approval') {
+                this.failApprovalRecovery(entry);
+                continue;
+            }
+            if (isDreamHostKey(entry.hostKey) && entry.state === 'running') {
+                this.failDreamDispatchRecovery(entry);
+                continue;
+            }
+            const existingHost = this.hosts.get(entry.hostKey);
+            if (existingHost?.getCurrentRunId() === entry.runId && existingHost.getState() !== 'failed') {
+                log.info('[executor] pending dispatch already attached to live host, skipping redispatch', {
+                    runId: entry.runId,
+                    hostKey: entry.hostKey,
+                    state: entry.state,
+                });
+                this.send({
+                    type: 'run.event',
+                    runId: entry.runId,
+                    conversationId: entry.payload.conversationId,
+                    event: {
+                        type: 'conversation.status',
+                        conversationId: entry.payload.conversationId,
+                        status: 'recovering',
+                    },
+                });
+                continue;
+            }
+            const restoredMsg = !isDreamHostKey(entry.hostKey) && entry.state === 'running'
+                ? { ...entry.payload, dispatchMode: 'resume' }
+                : entry.payload;
+            this.send({
+                type: 'run.event',
+                runId: restoredMsg.runId,
+                conversationId: restoredMsg.conversationId,
+                event: {
+                    type: 'conversation.status',
+                    conversationId: restoredMsg.conversationId,
+                    status: 'recovering',
+                },
+            });
+            void this.restoredDispatchContext
+                .run({ runId: restoredMsg.runId }, () => this.dispatch(restoredMsg, { persist: false }))
+                .catch((error) => {
+                const errorMessage = String(error?.message ?? error);
+                log.warn('[executor] failed to restore pending dispatch', {
+                    runId: restoredMsg.runId,
+                    hostKey: restoredMsg.hostKey,
+                    conversationId: restoredMsg.conversationId,
+                    state: entry.state,
+                    error: errorMessage,
+                });
+                removeDispatch(this.db, restoredMsg.runId);
+                this.runToHost.delete(restoredMsg.runId);
+                this.sendRestoreFailureEndIfNeeded(restoredMsg.runId, restoredMsg.conversationId, errorMessage);
+            });
+        }
+    }
+    failRestoredDispatch(runId, error) {
+        const pending = listPendingDispatches(this.db).find((entry) => entry.runId === runId);
+        if (!pending)
+            return false;
+        const errorMessage = String(error?.message ?? error);
+        log.warn('[executor] failing restored dispatch', {
+            runId: pending.runId,
+            hostKey: pending.hostKey,
+            conversationId: pending.payload.conversationId,
+            state: pending.state,
+            error: errorMessage,
+        });
+        const host = this.hosts.get(pending.hostKey);
+        if (host) {
+            const currentRunId = host.getCurrentRunId();
+            if (currentRunId) {
+                this.runToHost.delete(currentRunId);
+            }
+            host.close();
+            this.hosts.delete(pending.hostKey);
+            this.hostBridgeSignatures.delete(pending.hostKey);
+            this.hostAgentCommandEnvOverlays.delete(pending.hostKey);
+            this.hostMetadata.delete(pending.hostKey);
+        }
+        removeDispatch(this.db, pending.runId);
+        this.runToHost.delete(pending.runId);
+        this.sendRestoreFailureEndIfNeeded(pending.runId, pending.payload.conversationId, errorMessage);
+        return true;
+    }
+    failCurrentRestoredDispatch(error) {
+        const runId = this.restoredDispatchContext.getStore()?.runId;
+        if (!runId)
+            return false;
+        return this.failRestoredDispatch(runId, error);
+    }
+    sendRestoreFailureEndIfNeeded(runId, conversationId, errorMessage) {
+        if (this.terminalRunIds.has(runId))
+            return;
+        this.send({
+            type: 'run.end',
+            runId,
+            conversationId,
+            error: `Failed to restore pending dispatch after node restart: ${errorMessage}`,
+        });
+    }
+    failDreamDispatchRecovery(entry) {
+        const errorMessage = 'Dream dispatch cannot be resumed after node restart.';
+        log.warn('[executor] dream dispatch cannot be restored after node restart', {
+            runId: entry.runId,
+            hostKey: entry.hostKey,
+            state: entry.state,
+        });
+        const host = this.hosts.get(entry.hostKey);
+        if (host?.getCurrentRunId() === entry.runId) {
+            this.runToHost.delete(entry.runId);
+            host.close();
+            this.hosts.delete(entry.hostKey);
+            this.hostBridgeSignatures.delete(entry.hostKey);
+            this.hostAgentCommandEnvOverlays.delete(entry.hostKey);
+            this.hostMetadata.delete(entry.hostKey);
+        }
+        else {
+            this.runToHost.delete(entry.runId);
+        }
+        finishRun(this.db, { runId: entry.runId, error: errorMessage });
+        removeDispatch(this.db, entry.runId);
+        this.send({
+            type: 'run.end',
+            runId: entry.runId,
+            conversationId: entry.payload.conversationId,
+            error: errorMessage,
+        });
+    }
+    failApprovalRecovery(entry) {
+        log.warn('[executor] approval request cannot be restored after reconnect/restart', {
+            runId: entry.runId,
+            hostKey: entry.hostKey,
+        });
+        const host = this.hosts.get(entry.hostKey);
+        if (host) {
+            const currentRunId = host.getCurrentRunId();
+            if (currentRunId) {
+                this.runToHost.delete(currentRunId);
+            }
+            host.close();
+            this.hosts.delete(entry.hostKey);
+            this.hostBridgeSignatures.delete(entry.hostKey);
+            this.hostAgentCommandEnvOverlays.delete(entry.hostKey);
+            this.hostMetadata.delete(entry.hostKey);
+        }
+        this.runToHost.delete(entry.runId);
+        removeDispatch(this.db, entry.runId);
+        this.send({
+            type: 'run.end',
+            runId: entry.runId,
+            conversationId: entry.payload.conversationId,
+            error: 'Approval request lost during reconnect. Re-run required.',
+        });
+    }
+    reapIdleHosts() {
+        const now = Date.now();
+        for (const [hostKey, host] of this.hosts.entries()) {
+            if (!host.isIdleExpired(now, this.config.hostIdleTimeoutMs))
+                continue;
+            log.info('[executor] reaping idle host', {
+                hostKey,
+                lastSleepAt: host.getLastSleepAt(),
+            });
+            host.close();
+            this.hosts.delete(hostKey);
+            this.hostBridgeSignatures.delete(hostKey);
+            this.hostAgentCommandEnvOverlays.delete(hostKey);
+            this.hostMetadata.delete(hostKey);
+        }
+    }
+    reapIdleSoloHosts() {
+        for (const [soloSessionId, host] of this.soloHosts.entries()) {
+            if (!host.isIdleExpired())
+                continue;
+            if (this.closingSoloHosts.has(soloSessionId))
+                continue;
+            log.info('[executor] reaping idle solo host', { soloSessionId });
+            this.closingSoloHosts.add(soloSessionId);
+            void host.close()
+                .then(() => {
+                if (this.soloHosts.get(soloSessionId) === host) {
+                    this.soloHosts.delete(soloSessionId);
+                }
+            })
+                .catch((error) => {
+                log.warn('[executor] failed to close idle solo host', {
+                    soloSessionId,
+                    error: String(error?.message ?? error),
+                });
+            })
+                .finally(() => {
+                this.closingSoloHosts.delete(soloSessionId);
+            });
+        }
+    }
+    async handleSoloDispatch(msg) {
+        if (msg.agentType !== 'codex_app_server') {
+            this.send({
+                type: 'solo.run.end',
+                soloSessionId: msg.soloSessionId,
+                stopReason: 'failed',
+                error: `Solo mode is not supported for agent type ${msg.agentType}.`,
+            });
+            return;
+        }
+        let host = this.soloHosts.get(msg.soloSessionId);
+        if (host && this.closingSoloHosts.has(msg.soloSessionId)) {
+            this.send({
+                type: 'solo.run.end',
+                soloSessionId: msg.soloSessionId,
+                stopReason: 'failed',
+                error: 'Solo session is closing. Try again in a moment.',
+            });
+            return;
+        }
+        if (host?.isClosed()) {
+            this.soloHosts.delete(msg.soloSessionId);
+            host = undefined;
+        }
+        if (!host) {
+            host = this.createSoloHost({
+                msg,
+                db: this.db,
+                config: this.config,
+                toolAuth: this.toolAuth,
+                workspaceLockManager: this.workspaceLockManager,
+                send: this.send,
+            });
+            this.soloHosts.set(msg.soloSessionId, host);
+        }
+        else {
+            host.touch();
+        }
+        if (host.isRunning()) {
+            this.send({
+                type: 'solo.run.end',
+                soloSessionId: msg.soloSessionId,
+                stopReason: 'failed',
+                error: 'Solo run already active for this session.',
+            });
+            return;
+        }
+        try {
+            await host.prompt(msg.prompt, msg.systemPromptText);
+        }
+        catch (error) {
+            const message = String(error?.message ?? error);
+            this.send({
+                type: 'solo.run.end',
+                soloSessionId: msg.soloSessionId,
+                stopReason: 'failed',
+                error: message,
+            });
+        }
+    }
+    async handleSoloCancel(msg) {
+        const host = this.soloHosts.get(msg.soloSessionId);
+        if (!host)
+            return;
+        host.touch();
+        await host.cancel();
+    }
+    async handleSoloClose(msg) {
+        const host = this.soloHosts.get(msg.soloSessionId);
+        if (!host)
+            return;
+        if (this.closingSoloHosts.has(msg.soloSessionId))
+            return;
+        this.closingSoloHosts.add(msg.soloSessionId);
+        try {
+            await host.close();
+            if (this.soloHosts.get(msg.soloSessionId) === host) {
+                this.soloHosts.delete(msg.soloSessionId);
+            }
+        }
+        finally {
+            this.closingSoloHosts.delete(msg.soloSessionId);
+        }
+    }
+    async handleSoloSteer(msg) {
+        const host = this.soloHosts.get(msg.soloSessionId);
+        if (!host)
+            return false;
+        return host.steer(msg.prompt);
+    }
+    async handleSoloPermissionResponse(msg) {
+        const host = this.soloHosts.get(msg.soloSessionId);
+        if (!host)
+            return false;
+        return host.respondToPermission(msg.requestId, msg.decision, msg.selectedActionId, msg.responseText, msg.answers);
+    }
+    async cancelRun(runId) {
+        const runtimeKey = this.runToHost.get(runId);
+        if (!runtimeKey)
+            return false;
+        const host = this.hosts.get(runtimeKey);
+        if (!host)
+            return false;
+        return host.cancelRun(runId);
+    }
+    async steerRun(runId, promptText, attachments) {
+        return this.withSteerSerial(runId, async () => {
+            const runtimeKey = this.runToHost.get(runId);
+            if (!runtimeKey)
+                return false;
+            const host = this.hosts.get(runtimeKey);
+            if (!host)
+                return false;
+            if (!host.steerRun)
+                return false;
+            return host.steerRun(runId, promptText, attachments);
+        });
+    }
+    isRunActiveInWorkspace(runId, workspaceRoot) {
+        const normalizedRunId = runId?.trim();
+        if (!normalizedRunId)
+            return false;
+        const runtimeKey = this.runToHost.get(normalizedRunId);
+        if (!runtimeKey)
+            return false;
+        const host = this.hosts.get(runtimeKey);
+        if (!host || host.getCurrentRunId() !== normalizedRunId)
+            return false;
+        return path.resolve(host.getWorkspaceRoot()) === path.resolve(workspaceRoot);
+    }
+    async handlePermissionResponse(requestId, decision, selectedActionId, responseText, answers) {
+        for (const host of this.hosts.values()) {
+            const handled = await host.handlePermissionResponse(requestId, decision, selectedActionId, responseText, answers);
+            if (handled)
+                return true;
+        }
+        return false;
+    }
+    async getClaudeControls(target) {
+        const host = this.buildClaudeControlHost(target);
+        return host.getClaudeControls();
+    }
+    async setClaudeMode(target, modeId) {
+        const host = this.buildClaudeControlHost(target);
+        if (host.getCurrentRunId() || host.hasPendingApproval()) {
+            throw new Error('Claude session is busy.');
+        }
+        return host.setClaudeMode(modeId);
+    }
+    async setClaudeModel(target, modelId) {
+        const host = this.buildClaudeControlHost(target);
+        if (host.getCurrentRunId() || host.hasPendingApproval()) {
+            throw new Error('Claude session is busy.');
+        }
+        return host.setClaudeModel(modelId);
+    }
+    async executeClaudeCommand(target, commandName, args) {
+        const host = this.buildClaudeControlHost(target);
+        if (host.getCurrentRunId() || host.hasPendingApproval()) {
+            throw new Error('Claude session is busy.');
+        }
+        const result = await host.executeClaudeCommand(commandName, args);
+        const controls = await host.getClaudeControls();
+        return { controls, result };
+    }
+    listHostSnapshots() {
+        const pendingByHost = new Map();
+        for (const pending of listPendingDispatches(this.db)) {
+            pendingByHost.set(pending.hostKey, (pendingByHost.get(pending.hostKey) ?? 0) + 1);
+        }
+        const snapshots = [];
+        for (const [hostKey, host] of this.hosts.entries()) {
+            const meta = this.hostMetadata.get(hostKey);
+            if (!meta)
+                continue;
+            const state = host.getState();
+            const currentRunId = host.getCurrentRunId();
+            const hasPendingApproval = host.hasPendingApproval();
+            const pendingDispatchCount = pendingByHost.get(hostKey) ?? 0;
+            const hostWithMetrics = host;
+            const inboxSize = typeof hostWithMetrics.getInboxSize === 'function' ? hostWithMetrics.getInboxSize() : 0;
+            const lastWakeAt = typeof hostWithMetrics.getLastWakeAt === 'function' ? hostWithMetrics.getLastWakeAt() : null;
+            const lastSleepAt = host.getLastSleepAt();
+            const lastError = host.getLastError();
+            snapshots.push({
+                hostKey,
+                hostInstanceId: host.getHostInstanceId(),
+                sessionKey: meta.sessionKey,
+                workspaceRoot: meta.workspaceRoot,
+                agentType: meta.agentType,
+                state,
+                currentRunId,
+                hasPendingApproval,
+                inboxSize,
+                pendingDispatchCount,
+                lastWakeAt,
+                lastSleepAt,
+                lastError,
+                resumable: state !== 'failed' && (currentRunId !== null || hasPendingApproval || pendingDispatchCount > 0 || state === 'idle'),
+            });
+        }
+        return snapshots.sort((a, b) => a.hostKey.localeCompare(b.hostKey));
+    }
+    closeHost(hostKey) {
+        const host = this.hosts.get(hostKey);
+        if (!host)
+            return;
+        const currentRunId = host.getCurrentRunId();
+        if (currentRunId) {
+            this.runToHost.delete(currentRunId);
+        }
+        removeDispatchesForHostKey(this.db, hostKey);
+        host.close();
+        this.hosts.delete(hostKey);
+        this.hostBridgeSignatures.delete(hostKey);
+        this.hostAgentCommandEnvOverlays.delete(hostKey);
+        this.hostMetadata.delete(hostKey);
+    }
+    async cleanupAgentRuntime(hostKeys, sessionKeys = []) {
+        let closedHosts = 0;
+        let removedDispatches = 0;
+        const sessionKeysToClear = new Set(sessionKeys.filter(Boolean));
+        for (const hostKey of [...new Set(hostKeys.filter(Boolean))]) {
+            const meta = this.hostMetadata.get(hostKey);
+            if (meta?.sessionKey)
+                sessionKeysToClear.add(meta.sessionKey);
+            const host = this.hosts.get(hostKey);
+            if (host) {
+                const currentRunId = host.getCurrentRunId();
+                if (currentRunId) {
+                    this.runToHost.delete(currentRunId);
+                }
+                if (host.closeAndWait) {
+                    await host.closeAndWait();
+                }
+                else {
+                    await Promise.resolve(host.close());
+                }
+                this.hosts.delete(hostKey);
+                this.hostBridgeSignatures.delete(hostKey);
+                this.hostAgentCommandEnvOverlays.delete(hostKey);
+                this.hostMetadata.delete(hostKey);
+                closedHosts += 1;
+            }
+            for (const [runId, mappedHostKey] of this.runToHost.entries()) {
+                if (mappedHostKey === hostKey) {
+                    this.runToHost.delete(runId);
+                }
+            }
+            removedDispatches += removeDispatchesForHostKey(this.db, hostKey);
+        }
+        for (const sessionKey of sessionKeysToClear) {
+            for (const pending of listPendingDispatches(this.db)) {
+                if (pending.payload.sessionKey === sessionKey) {
+                    this.runToHost.delete(pending.runId);
+                }
+            }
+            removedDispatches += removeDispatchesForSessionKey(this.db, sessionKey);
+            clearAcpSessionId(this.db, sessionKey);
+        }
+        return { closedHosts, removedDispatches };
+    }
+    resetWorkspace(workspaceRoot) {
+        const resolvedRoot = path.resolve(workspaceRoot);
+        for (const [hostKey, host] of this.hosts.entries()) {
+            if (path.resolve(host.getWorkspaceRoot()) !== resolvedRoot)
+                continue;
+            const currentRunId = host.getCurrentRunId();
+            if (currentRunId) {
+                this.runToHost.delete(currentRunId);
+                removeDispatch(this.db, currentRunId);
+            }
+            host.close();
+            this.hosts.delete(hostKey);
+            this.hostBridgeSignatures.delete(hostKey);
+            this.hostAgentCommandEnvOverlays.delete(hostKey);
+            this.hostMetadata.delete(hostKey);
+        }
+        for (const pending of listPendingDispatches(this.db)) {
+            const pendingRoot = path.resolve(pending.payload.workspacePath ?? this.config.workspaceRoot);
+            if (pendingRoot !== resolvedRoot)
+                continue;
+            this.runToHost.delete(pending.runId);
+            removeDispatch(this.db, pending.runId);
+        }
+    }
+    close() {
+        clearInterval(this.hostSweepTimer);
+        this.closeSoloHosts();
+        for (const host of this.hosts.values()) {
+            host.close();
+        }
+        this.hosts.clear();
+        this.hostBridgeSignatures.clear();
+        this.hostAgentCommandEnvOverlays.clear();
+        this.hostMetadata.clear();
+        this.steerChains.clear();
+    }
+    closeSoloHosts() {
+        for (const host of this.soloHosts.values()) {
+            void host.close();
+        }
+        this.soloHosts.clear();
+        this.closingSoloHosts.clear();
+    }
+    async withSteerSerial(runId, task) {
+        const previous = this.steerChains.get(runId) ?? Promise.resolve();
+        const current = previous.catch(() => undefined).then(task);
+        const tracked = current.catch(() => undefined);
+        this.steerChains.set(runId, tracked);
+        try {
+            return await current;
+        }
+        finally {
+            if (this.steerChains.get(runId) === tracked) {
+                this.steerChains.delete(runId);
+            }
+        }
+    }
+}