@minionry/minion 0.7.36

package/dist/server/services/websocket/handler.js

@@ -0,0 +1,1197 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { can, isViewOperation, normalizeStoredRole } from '@minionry/roles';
+import { machineFile } from '../../../bin/machine-layout.js';
+import { setAgentBrowserHostAttached } from '../../cli/headless/mcp-config.js';
+import { getBrowserDriverState } from '../browser/driver-state.js';
+import { toBrowserPreflightPayload } from '../browser/preflight.js';
+import { CollabSessionRegistry } from '../collab/registry.js';
+import { COLLAB_EVENT_BUFFER_MAX_AGE_MS, COLLAB_EVENT_BUFFER_MAX_BYTES, COLLAB_EVENT_BUFFER_MAX_EVENTS, } from '../collab/types.js';
+import { respawnInstance } from '../instances.js';
+import { PmTimelineRegistry } from '../plan/pm-timeline.js';
+import { parseDeclaredEnvironment, resolveCliEnvironment } from '../platform-url.js';
+import { getAgentScheduler } from '../schedule/agent-scheduler.js';
+import { getQualityScheduler } from '../schedule/quality-scheduler.js';
+import { getScheduler } from '../schedule/scheduler.js';
+import { attachSdkBrowserTransport } from '../sdk/browser-transport.js';
+import { teardownSdkForViewer, teardownSdkOnTransportClose } from '../sdk/revoke.js';
+import { captureException } from '../sentry.js';
+import { createExpander, defaultSnippetSources, SnippetRegistry, SnippetWatcher, } from '../snippets/index.js';
+import { getPTYManager } from '../terminal/pty-manager.js';
+import { ChatTimelineRegistry } from '../timeline/index.js';
+import { handleAgentScheduleMessage } from './agent-schedule-handlers.js';
+import { handleAppsMessage } from './apps-handlers.js';
+import { resolvePendingQuestion } from './ask-user-question-bridge.js';
+import { AutocompleteService } from './autocomplete.js';
+import { activeBrowserAgentTarget } from './browser-agent-runtime.js';
+import { attachBrowserHostBroadcast, broadcastAgentTabState, browserHostPolicy, handleBrowserHostMessage, onViewerDisconnected as onBrowserViewerDisconnected, onWsContextClosed as onBrowserWsContextClosed, } from './browser-handlers.js';
+import { addressToViewer } from './browser-viewer-registry.js';
+import { handleCollabMessage } from './collab-handlers.js';
+import { createCommitSuggestionService, GIT_VIEW_TAB_ID, isAnyExecutionActive } from './commit-suggestion-service.js';
+import { debugLog } from './debug-log.js';
+import { handleEngineAuthMessage } from './engine-auth-handlers.js';
+import { EngineCredentialWatcher } from './engine-credential-watcher.js';
+import { handleModelProfileMessage } from './engine-profile-handlers.js';
+import { FileDownloadHandler } from './file-download-handler.js';
+import { handleFileExplorerMessage, handleFileMessage, resolveFileDomainRoot } from './file-explorer-handlers.js';
+import { handleFileShareMessage, isFileShareRequestType } from './file-share-handlers.js';
+import { FileUploadHandler } from './file-upload-handler.js';
+import { handleGitMessage } from './git-handlers.js';
+import { GitHeadWatcher } from './git-head-watcher.js';
+import { hasScopeBinding, resolveScopeDir } from './handler-context.js';
+import { MsgIdTracker } from './msg-id-tracker.js';
+import { maybeStartAutoImplement } from './plan-execution-handlers.js';
+import { handlePlanMessage } from './plan-handlers.js';
+import { executorCache } from './plan-helpers.js';
+import { buildLateAnswerPrompt } from './recommended-answers.js';
+import { handleScheduleMessage } from './schedule-handlers.js';
+import { installSdkAgentHost, installSdkQualityReviewHost, installSdkSessionHost } from './sdk-agent-host.js';
+import { installSdkBrowserHost } from './sdk-browser-host.js';
+import { installSdkComposerHost } from './sdk-composer-host.js';
+import { installSdkGitHost, notifySdkGitCommitSuggestion } from './sdk-git-host.js';
+import { handleSdkMessage } from './sdk-handlers.js';
+import { installSdkTerminalHost } from './sdk-terminal-host.js';
+import { handleHistoryMessage, handleSessionMessage, initializeTab, resolveTabSession, restoreWorktreeFromRegistry, resumeHistoricalSession } from './session-handlers.js';
+import { SessionRegistry } from './session-registry.js';
+import { SessionRoleDirectory } from './session-role-directory.js';
+import { generateNotificationSummary, handleCreateSystemPrompt, handleDeleteSystemPrompt, handleGetModelCatalog, handleGetSettings, handleGetSystemPromptProfiles, handleReadSystemPrompt, handleSaveSystemPrompt, handleUpdateSettings } from './settings-handlers.js';
+import { handleListSkills } from './skill-handlers.js';
+import { SkillsWatcher } from './skill-watcher.js';
+import { buildSnippetListResultData, handleSnippetMessage } from './snippet-handlers.js';
+import { SeqEventBuffer, SeqEventBufferRegistry, TabEventBufferRegistry } from './tab-event-buffer.js';
+import { handleCreateTab, handleGetActiveTabs, handleMarkTabViewed, handleRemoveTab, handleReorderTabs, handleSetTabEngine, handleSyncTabMeta } from './tab-handlers.js';
+import { cleanupTerminalSubscribers, handleTerminalMessage } from './terminal-handlers.js';
+const log = debugLog('handler');
+export class WebSocketImproviseHandler {
+    sessions = new Map();
+    connections = new Map();
+    autocompleteService;
+    frecencyPath;
+    usageReporter = null;
+    gitScopes = new Map();
+    gitBranches = new Map();
+    sessionRegistry = null;
+    allConnections = new Set();
+    activeSearches = new Map();
+    terminalListenerCleanups = new Map();
+    terminalSubscribers = new Map();
+    fileUploadHandler = null;
+    fileDownloadHandler = null;
+    gitHeadWatcher = null;
+    skillsWatcher = null;
+    engineCredentialWatcher = null;
+    snippetRegistry = null;
+    snippetExpander = null;
+    snippetWatcher = null;
+    tabEventBuffers = new TabEventBufferRegistry();
+    chatTimelines = new ChatTimelineRegistry();
+    pmEventBuffers = new SeqEventBufferRegistry();
+    pmTimelines = new PmTimelineRegistry();
+    collabEventBuffers = new SeqEventBufferRegistry(() => new SeqEventBuffer(COLLAB_EVENT_BUFFER_MAX_EVENTS, COLLAB_EVENT_BUFFER_MAX_AGE_MS, Date.now, COLLAB_EVENT_BUFFER_MAX_BYTES));
+    collabSessions = new CollabSessionRegistry(this);
+    msgIdTracker = new MsgIdTracker();
+    commitSuggestions = null;
+    instanceRegistry;
+    shutdownInProgress = false;
+    browserHost = null;
+    browserHostBroadcastDispose = null;
+    browserHostLeaseExpiredDispose = null;
+    browserHostErrorDispose = null;
+    browserHostSdkDispose = null;
+    browserDriverStateDispose = null;
+    currentWorkingDir = null;
+    sessionRoles = new SessionRoleDirectory();
+    constructor(instanceRegistry = null, browserHost = null) {
+        this.frecencyPath = machineFile('frecency');
+        const frecencyData = this.loadFrecencyData();
+        this.autocompleteService = new AutocompleteService(frecencyData);
+        this.instanceRegistry = instanceRegistry;
+        this.commitSuggestions = createCommitSuggestionService({
+            isSystemActive: () => isAnyExecutionActive(this.sessions.values(), executorCache.values()),
+            broadcast: (suggestion) => {
+                this.broadcastToAll({ type: 'gitCommitSuggestion', tabId: GIT_VIEW_TAB_ID, data: suggestion });
+                notifySdkGitCommitSuggestion(suggestion);
+            },
+        });
+        if (browserHost)
+            this.setBrowserHost(browserHost);
+        installSdkAgentHost(this);
+        installSdkSessionHost(this);
+        installSdkQualityReviewHost(this);
+        installSdkBrowserHost(this);
+        installSdkComposerHost(this);
+        installSdkGitHost(this);
+        installSdkTerminalHost(this);
+        process.on('exit', () => {
+            if (this.frecencySaveTimer) {
+                clearTimeout(this.frecencySaveTimer);
+                this.saveFrecencyData();
+            }
+        });
+    }
+    setBrowserHost(host) {
+        if (this.browserHost === host)
+            return;
+        this.clearBrowserHost();
+        this.browserHost = host;
+        setAgentBrowserHostAttached(true);
+        const onSupervisorError = (err) => {
+            console.warn(`[wsHandler] browser host non-fatal supervisor error: ${err.message}`);
+            captureException(err, { context: 'wsHandler.browserHost.error' });
+        };
+        host.on('error', onSupervisorError);
+        this.browserHostBroadcastDispose = attachBrowserHostBroadcast(host, {
+            send: (ws, response) => this.send(ws, response),
+            broadcastToAll: (response) => this.broadcastToAll(response),
+        });
+        this.browserHostErrorDispose = () => host.off('error', onSupervisorError);
+        const onLeaseExpired = (event) => {
+            let owner = null;
+            try {
+                const driverState = getBrowserDriverState();
+                owner = driverState.getOwner(event.tabId);
+                driverState.clearOwner(event.tabId);
+            }
+            catch (err) {
+                captureException(err, { context: 'wsHandler.leaseExpired.clearOwner' });
+            }
+            const attributed = owner?.ownerAgentId === event.agentId ? owner : null;
+            void broadcastAgentTabState(host, 
+            { broadcastToAll: (response) => this.broadcastToAll(response) }, event.agentId, attributed?.ownerAgentLabel ?? event.agentId, attributed?.ownerSessionId ? { sessionId: attributed.ownerSessionId } : {});
+        };
+        host.on('leaseExpired', onLeaseExpired);
+        this.browserHostLeaseExpiredDispose = () => host.off('leaseExpired', onLeaseExpired);
+        const driverState = getBrowserDriverState();
+        const onDriverState = (payload) => {
+            log('tx.driver_state', `tab=${payload.tabId.slice(0, 8)} state=${payload.state} mode=${payload.mode ?? '-'}`);
+            this.broadcastToAll({ type: 'browser_driver_state', data: payload });
+        };
+        driverState.on('change', onDriverState);
+        this.browserDriverStateDispose = () => driverState.off('change', onDriverState);
+        this.browserHostSdkDispose = attachSdkBrowserTransport(host, {
+            getWorkingDir: () => this.currentWorkingDir,
+            consent: {
+                listOwnerSessions: () => this.sessionRoles.listOwnerTierViewerIds(),
+                deliverToSession: (viewerId, frame) => {
+                    const entry = this.sessionRoles.get(viewerId);
+                    if (!entry)
+                        return;
+                    const out = { type: frame.type, data: frame.data };
+                    out._target = viewerId;
+                    this.send(entry.ws, out);
+                },
+                broadcast: (frame) => {
+                    this.broadcastToAll({ type: frame.type, data: frame.data });
+                },
+            },
+        });
+    }
+    clearBrowserHost() {
+        setAgentBrowserHostAttached(false);
+        if (this.browserHostBroadcastDispose) {
+            this.browserHostBroadcastDispose();
+            this.browserHostBroadcastDispose = null;
+        }
+        if (this.browserHostLeaseExpiredDispose) {
+            this.browserHostLeaseExpiredDispose();
+            this.browserHostLeaseExpiredDispose = null;
+        }
+        if (this.browserHostErrorDispose) {
+            this.browserHostErrorDispose();
+            this.browserHostErrorDispose = null;
+        }
+        if (this.browserHostSdkDispose) {
+            this.browserHostSdkDispose();
+            this.browserHostSdkDispose = null;
+        }
+        if (this.browserDriverStateDispose) {
+            this.browserDriverStateDispose();
+            this.browserDriverStateDispose = null;
+        }
+        this.browserHost = null;
+    }
+    getRegistry(workingDir) {
+        if (!this.sessionRegistry) {
+            this.sessionRegistry = new SessionRegistry(workingDir);
+        }
+        return this.sessionRegistry;
+    }
+    getBrowserHost() {
+        return this.browserHost;
+    }
+    triggerAutoImplement(workingDir, boardId) {
+        maybeStartAutoImplement(this, workingDir, boardId);
+    }
+    setUsageReporter(reporter) {
+        this.usageReporter = reporter;
+    }
+    loadFrecencyData() {
+        try {
+            if (existsSync(this.frecencyPath)) {
+                const data = readFileSync(this.frecencyPath, 'utf-8');
+                return JSON.parse(data);
+            }
+        }
+        catch (error) {
+            console.error('[WebSocketImproviseHandler] Error loading frecency data:', error);
+        }
+        return {};
+    }
+    saveFrecencyData() {
+        try {
+            const dir = dirname(this.frecencyPath);
+            if (!existsSync(dir)) {
+                mkdirSync(dir, { recursive: true });
+            }
+            writeFileSync(this.frecencyPath, JSON.stringify(this.autocompleteService.getFrecencyData(), null, 2));
+        }
+        catch (error) {
+            console.error('[WebSocketImproviseHandler] Error saving frecency data:', error);
+        }
+    }
+    frecencySaveTimer = null;
+    recordFileSelection(filePath) {
+        this.autocompleteService.recordFileSelection(filePath);
+        if (!this.frecencySaveTimer) {
+            this.frecencySaveTimer = setTimeout(() => {
+                this.frecencySaveTimer = null;
+                this.saveFrecencyData();
+            }, 2000);
+        }
+    }
+    handleConnection(ws, workingDir) {
+        this.connections.set(ws, new Map());
+        this.allConnections.add(ws);
+        if (!ws._viewerId)
+            ws._viewerId = randomUUID();
+        if (workingDir)
+            this.currentWorkingDir = workingDir;
+        if (!this.gitHeadWatcher && workingDir) {
+            this.gitHeadWatcher = new GitHeadWatcher(workingDir, this);
+            this.gitHeadWatcher.start();
+        }
+        if (!this.skillsWatcher && workingDir) {
+            this.skillsWatcher = new SkillsWatcher(workingDir, this);
+            this.skillsWatcher.start();
+        }
+        if (!this.engineCredentialWatcher) {
+            this.engineCredentialWatcher = new EngineCredentialWatcher(this);
+            this.engineCredentialWatcher.start();
+        }
+        if (workingDir) {
+            getScheduler(workingDir, this).start();
+            getAgentScheduler(workingDir, this).start();
+            getQualityScheduler(workingDir).start();
+        }
+        if (!this.snippetRegistry && workingDir) {
+            const sources = defaultSnippetSources(workingDir);
+            this.snippetRegistry = new SnippetRegistry(sources);
+            this.snippetExpander = createExpander(this.snippetRegistry);
+            this.snippetWatcher = new SnippetWatcher(this.snippetRegistry, sources, () => {
+                this.broadcastToAll({ type: 'snippetListResult', data: buildSnippetListResultData(this.snippetRegistry) });
+            });
+            this.snippetWatcher.start();
+        }
+        if (this.browserHost) {
+            this.send(ws, {
+                type: 'browser_status',
+                data: this.browserHost.getStatus(),
+            });
+        }
+    }
+    async handleMessage(ws, message, workingDir) {
+        try {
+            const msg = JSON.parse(message);
+            if (isFileShareRequestType(msg.type) || msg._share !== undefined) {
+                handleFileShareMessage(this, ws, msg, workingDir);
+                return;
+            }
+            const tabId = msg.tabId || 'default';
+            const role = msg._role === undefined ? 'owner' : normalizeStoredRole(msg._role);
+            delete msg._role;
+            const explicitViewerStamp = msg._viewer !== undefined;
+            const viewerId = msg._viewer ?? ws._viewerId;
+            delete msg._viewer;
+            this.sessionRoles.noteMessage(viewerId, role, ws, { explicitViewerStamp, messageType: msg.type });
+            await this.dispatchMessage(ws, msg, tabId, workingDir, role, viewerId);
+        }
+        catch (error) {
+            console.error('[WebSocketImproviseHandler] Error handling message:', error);
+            captureException(error, { context: 'websocket.handleMessage' });
+            this.send(ws, {
+                type: 'error',
+                data: { message: error instanceof Error ? error.message : String(error) }
+            });
+        }
+    }
+    static DISPATCH = {
+        execute: 'session', cancel: 'session', getHistory: 'session', new: 'session', approve: 'session', reject: 'session', queueEnqueuePrompt: 'session', queueRemovePrompt: 'session', queueClearPrompts: 'session',
+        getTimeline: 'session',
+        getSessions: 'history', getSessionsCount: 'history', getSessionById: 'history', deleteSession: 'history', clearHistory: 'history', searchHistory: 'history',
+        exportSession: 'history', importSession: 'history',
+        autocomplete: 'file', readFile: 'file', recordSelection: 'file',
+        terminalInit: 'terminal', terminalReconnect: 'terminal', terminalList: 'terminal', terminalInput: 'terminal', terminalResize: 'terminal', terminalClose: 'terminal',
+        listDirectory: 'fileExplorer', writeFile: 'fileExplorer', createFile: 'fileExplorer', createDirectory: 'fileExplorer', deleteFile: 'fileExplorer', renameFile: 'fileExplorer', notifyFileOpened: 'fileExplorer', searchFileContents: 'fileExplorer', cancelSearch: 'fileExplorer', findDefinition: 'fileExplorer',
+        collabJoin: 'collab', collabLeave: 'collab', collabPush: 'collab', collabCursor: 'collab', collabFlush: 'collab',
+        gitStatus: 'git', gitStage: 'git', gitUnstage: 'git', gitCommit: 'git', gitCommitWithAI: 'git', gitPush: 'git', gitPull: 'git', gitLog: 'git', gitDiscoverRepos: 'git', gitSetDirectory: 'git', gitGetRemoteInfo: 'git', gitCreatePR: 'git', gitGeneratePRDescription: 'git', gitListBranches: 'git', gitCheckout: 'git', gitCreateBranch: 'git', gitDeleteBranch: 'git', gitDiff: 'git', gitShowCommit: 'git', gitCommitDiff: 'git', gitListTags: 'git', gitCreateTag: 'git', gitPushTag: 'git', gitWorktreeList: 'git', gitWorktreeCreate: 'git', gitWorktreeCreateAndAssign: 'git', gitWorktreeRemove: 'git', tabWorktreeSwitch: 'git', tabRepoWorktreeSwitch: 'git', gitWorktreePush: 'git', gitWorktreeCreatePR: 'git', gitMergePreview: 'git', gitWorktreeMerge: 'git', gitMergeAbort: 'git', gitMergeComplete: 'git', gitMergeStashPop: 'git', gitMergeDiscardBlockers: 'git',
+        planInit: 'plan', planGetState: 'plan', planListIssues: 'plan', planGetIssue: 'plan', planGetSprint: 'plan', planGetMilestone: 'plan', planUpdateIssue: 'plan', planDeleteIssue: 'plan', planScaffold: 'plan', planPrompt: 'plan', planExecute: 'plan', planExecuteEpic: 'plan', planPause: 'plan', planStop: 'plan', planResume: 'plan', planCreateBoard: 'plan', planUpdateBoard: 'plan', planArchiveBoard: 'plan', planRestoreBoard: 'plan', planGetBoard: 'plan', planGetBoardState: 'plan', planReorderBoards: 'plan', planSetActiveBoard: 'plan', planGetBoardArtifacts: 'plan', planExportBoard: 'plan', planImportBoard: 'plan', planDownloadBoard: 'plan', planInstantiateTemplate: 'plan', planCreateSprint: 'plan', planActivateSprint: 'plan', planCompleteSprint: 'plan', planGetSprintArtifacts: 'plan', chatToBoard: 'plan', queueEnqueueComposerPrompt: 'plan', queueRemoveComposerPrompt: 'plan', queueClearComposerPrompts: 'plan',
+        getPmTimeline: 'plan',
+        planScheduleCreate: 'schedule', planScheduleUpdate: 'schedule', planScheduleDelete: 'schedule', planScheduleList: 'schedule', planScheduleValidateSource: 'schedule',
+        agentScheduleCreate: 'agentSchedule', agentScheduleUpdate: 'agentSchedule', agentScheduleDelete: 'agentSchedule', agentScheduleList: 'agentSchedule',
+        fileUploadStart: 'fileUpload', fileUploadChunk: 'fileUpload', fileUploadComplete: 'fileUpload', fileUploadCancel: 'fileUpload',
+        fileDownloadStart: 'fileDownload', fileDownloadCancel: 'fileDownload',
+        sdkConnect: 'sdk', sdkRequest: 'sdk', sdkAgentRun: 'sdk', sdkPmWrite: 'sdk', sdkPmExecute: 'sdk', sdkPmSchedule: 'sdk', sdkFilesWrite: 'sdk', sdkStorageWrite: 'sdk', sdkCancel: 'sdk', sdkRevoke: 'sdk', sdkConsentDecision: 'sdk', sdkAgentSession: 'sdk', sdkAgentInteract: 'sdk', sdkGitWrite: 'sdk', sdkTerminalWrite: 'sdk', sdkToolsServe: 'sdk', sdkQualityWrite: 'sdk', sdkBrowserWrite: 'sdk', sdkInferenceRun: 'sdk', sdkEndpointsWrite: 'sdk',
+        appInstallLocal: 'apps', appServeStatus: 'apps', appStop: 'apps', appUpdate: 'apps', appGreenlightDecision: 'apps', appSpaceList: 'apps', appSpaceAdd: 'apps', appSpaceRemove: 'apps', appSpaceConfigure: 'apps',
+        browser_preflight: 'browser', browser_snapshot: 'browser', browser_resume_driver: 'browser',
+        browser_navigate: 'browser', browser_back: 'browser', browser_forward: 'browser', browser_reload: 'browser', browser_stop: 'browser',
+        browser_resize: 'browser', browser_set_bounds: 'browser', browser_set_device_profile: 'browser',
+        browser_input: 'browser',
+        browser_tab_open: 'browser', browser_tab_close: 'browser', browser_tab_select: 'browser',
+        browser_webrtc_answer: 'browser', browser_webrtc_ice: 'browser', browser_webrtc_ice_config: 'browser', browser_webrtc_state: 'browser', browser_webrtc_attach: 'browser',
+        browser_lease_release: 'browser', browser_agent_task: 'browser', browser_agent_approve: 'browser',
+    };
+    static APPS_READ_TYPES = new Set(['appServeStatus', 'appSpaceList']);
+    async dispatchMessage(ws, msg, tabId, workingDir, role, viewerId) {
+        if (await this.dispatchInlineMessage(ws, msg, tabId, workingDir, role))
+            return;
+        const domain = WebSocketImproviseHandler.DISPATCH[msg.type];
+        if (!domain) {
+            this.handleUnknownDomain(ws, msg, viewerId);
+            return;
+        }
+        if (msg.tabId && !hasScopeBinding(this, tabId)) {
+            restoreWorktreeFromRegistry(this, this.getRegistry(workingDir), tabId);
+        }
+        const effectiveDir = resolveScopeDir(this, tabId, workingDir);
+        return this.routeToDomainHandler(domain, ws, msg, tabId, workingDir, effectiveDir, role, viewerId);
+    }
+    handleUnknownDomain(ws, msg, viewerId) {
+        if (msg.type.startsWith('browser_')) {
+            console.warn(`[WebSocketImproviseHandler] Unrouted browser envelope: ${msg.type}`);
+            this.sendBrowserError(ws, 'unrouted_envelope', `CLI has no handler for envelope "${msg.type}". This is a wiring bug — please report.`, viewerId);
+            return;
+        }
+        if (msg.type.startsWith('plan')) {
+            console.warn(`[WebSocketImproviseHandler] Unrouted plan envelope: ${msg.type}`);
+            this.send(ws, {
+                type: 'planError',
+                data: { error: `This minion CLI has no handler for "${msg.type}". Update the minion CLI and try again.` },
+            });
+            return;
+        }
+        if (/^app[A-Z]/.test(msg.type)) {
+            console.warn(`[WebSocketImproviseHandler] Unrouted apps envelope: ${msg.type}`);
+            this.send(ws, {
+                type: 'appError',
+                data: {
+                    operation: msg.type,
+                    code: 'NOT_IMPLEMENTED',
+                    message: `This minion CLI has no handler for "${msg.type}". Update the minion CLI and try again.`,
+                },
+            });
+            return;
+        }
+        console.warn(`[WebSocketImproviseHandler] Ignoring unknown message type: ${msg.type}`);
+    }
+    routeToDomainHandler(domain, ws, msg, tabId, workingDir, effectiveDir, role, viewerId) {
+        switch (domain) {
+            case 'session': return handleSessionMessage(this, ws, msg, tabId, role);
+            case 'history':
+                if (msg.type === 'importSession' && !can(role, 'execute')) {
+                    this.sendPermissionDenied(ws, msg.type);
+                    return;
+                }
+                return handleHistoryMessage(this, ws, msg, tabId, workingDir);
+            case 'file': return handleFileMessage(this, ws, msg, tabId, resolveFileDomainRoot(tabId, workingDir, effectiveDir), role);
+            case 'terminal':
+                if (!isViewOperation(msg.type) && !can(role, 'terminal')) {
+                    this.sendPermissionDenied(ws, msg.type);
+                    return;
+                }
+                return handleTerminalMessage(this, ws, msg, tabId, workingDir);
+            case 'fileExplorer': return handleFileExplorerMessage(this, ws, msg, tabId, effectiveDir, role);
+            case 'collab': return handleCollabMessage(this, ws, msg, effectiveDir, role, viewerId);
+            case 'git':
+                if (!isViewOperation(msg.type) && !can(role, 'git')) {
+                    this.sendPermissionDenied(ws, msg.type);
+                    return;
+                }
+                return handleGitMessage(this, ws, msg, tabId, workingDir);
+            case 'plan': return handlePlanMessage(this, ws, msg, tabId, workingDir, role);
+            case 'schedule': return handleScheduleMessage(this, ws, msg, tabId, workingDir, role);
+            case 'agentSchedule': return handleAgentScheduleMessage(this, ws, msg, workingDir, role);
+            case 'fileUpload': return this.handleFileUploadMessage(ws, msg, tabId, effectiveDir, role);
+            case 'fileDownload': return this.handleFileDownloadMessage(ws, msg, tabId, effectiveDir);
+            case 'sdk': return handleSdkMessage(this, ws, msg, tabId, workingDir, role, viewerId);
+            case 'apps':
+                if (!WebSocketImproviseHandler.APPS_READ_TYPES.has(msg.type) && !can(role, 'editSettings')) {
+                    this.sendPermissionDenied(ws, msg.type);
+                    return;
+                }
+                return handleAppsMessage(this, ws, msg, workingDir);
+            case 'browser': return this.dispatchBrowserMessage(ws, msg, role, viewerId);
+        }
+    }
+    async dispatchInlineMessage(ws, msg, tabId, workingDir, role) {
+        if (await this.dispatchDelegatedMessage(ws, msg, tabId, workingDir, role))
+            return true;
+        switch (msg.type) {
+            case 'ping':
+                this.send(ws, { type: 'pong', tabId });
+                return true;
+            case 'resumeSession':
+                if (!msg.data?.historicalSessionId)
+                    throw new Error('Historical session ID is required');
+                await resumeHistoricalSession(this, ws, tabId, workingDir, msg.data.historicalSessionId, msg.data);
+                return true;
+            case 'requestNotificationSummary':
+                if (!msg.data?.prompt || !msg.data?.output)
+                    throw new Error('Prompt and output are required for notification summary');
+                await generateNotificationSummary(this, ws, tabId, msg.data.prompt, msg.data.output, workingDir);
+                return true;
+            case 'getSettings':
+                handleGetSettings(this, ws);
+                return true;
+            case 'updateSettings':
+                if (can(role, 'editSettings'))
+                    handleUpdateSettings(this, ws, msg);
+                return true;
+            case 'getModelCatalog':
+                await handleGetModelCatalog(this, ws, msg);
+                return true;
+            case 'getSystemPromptProfiles':
+            case 'createSystemPrompt':
+            case 'readSystemPrompt':
+            case 'saveSystemPrompt':
+            case 'deleteSystemPrompt':
+                this.handleSystemPromptMessage(ws, msg, role);
+                return true;
+            case 'engineAuthStatus':
+            case 'setEngineApiKey':
+            case 'removeEngineApiKey':
+            case 'startEngineLogin':
+            case 'testEngineCredential':
+                if (can(role, 'editSettings'))
+                    await handleEngineAuthMessage(this, ws, msg);
+                else
+                    this.sendPermissionDenied(ws, msg.type);
+                return true;
+            case 'engineModelProfiles':
+            case 'setEngineModelProfile':
+            case 'removeEngineModelProfile':
+                if (can(role, 'editSettings'))
+                    handleModelProfileMessage(this, ws, msg);
+                else
+                    this.sendPermissionDenied(ws, msg.type);
+                return true;
+            case 'listSkills':
+                handleListSkills(this, ws, workingDir);
+                return true;
+            case 'snippetAutocomplete':
+            case 'snippetList':
+                handleSnippetMessage(this, ws, msg, tabId);
+                return true;
+            case 'snippetCreate':
+                if (can(role, 'editSettings'))
+                    handleSnippetMessage(this, ws, msg, tabId);
+                return true;
+            case 'snippetGet':
+            case 'snippetUpdate':
+                if (can(role, 'editSettings'))
+                    handleSnippetMessage(this, ws, msg, tabId);
+                return true;
+            case 'shutdownInstance':
+                this.handleShutdownInstance(ws, role, msg);
+                return true;
+            case 'restartInstance':
+                this.handleRestartInstance(ws, role, msg);
+                return true;
+            case 'askUserQuestionResponse':
+                if (can(role, 'execute'))
+                    this.handleAskUserQuestionResponse(msg, tabId, ws);
+                return true;
+            default:
+                return false;
+        }
+    }
+    async dispatchDelegatedMessage(ws, msg, tabId, workingDir, role) {
+        if (await this.dispatchTabMessage(ws, msg, tabId, workingDir, role))
+            return true;
+        return false;
+    }
+    async dispatchTabMessage(ws, msg, tabId, workingDir, role) {
+        switch (msg.type) {
+            case 'initTab':
+                await initializeTab(this, ws, tabId, workingDir, msg.data?.tabName, msg.data);
+                return true;
+            case 'getActiveTabs':
+                handleGetActiveTabs(this, ws, workingDir);
+                return true;
+            case 'createTab':
+                await handleCreateTab(this, ws, workingDir, msg.data?.tabName, msg.data?.optimisticTabId);
+                return true;
+            case 'reorderTabs':
+                handleReorderTabs(this, ws, workingDir, msg.data?.tabOrder);
+                return true;
+            case 'syncTabMeta':
+                handleSyncTabMeta(this, ws, msg, tabId, workingDir);
+                return true;
+            case 'removeTab':
+                handleRemoveTab(this, ws, tabId, workingDir);
+                return true;
+            case 'markTabViewed':
+                handleMarkTabViewed(this, ws, tabId, workingDir);
+                return true;
+            case 'setTabEngine':
+                if (can(role, 'editSettings'))
+                    handleSetTabEngine(this, ws, msg, tabId, workingDir);
+                return true;
+            default:
+                return false;
+        }
+    }
+    async dispatchBrowserMessage(ws, msg, role, viewerId) {
+        if (msg.type === 'browser_snapshot') {
+            this.handleBrowserSnapshotRequest(ws, viewerId);
+            return;
+        }
+        if (!can(role, 'driveBrowser')) {
+            if (msg.type !== 'browser_input')
+                log('drop', `type=${msg.type} reason=role role=${role}`);
+            return;
+        }
+        if (msg.type === 'browser_preflight') {
+            void this.handleBrowserPreflight(ws, viewerId);
+            return;
+        }
+        if (msg.type === 'browser_resume_driver') {
+            this.handleBrowserResumeDriver(msg);
+            return;
+        }
+        if (msg.type !== 'browser_input') {
+            log('dispatch', `type=${msg.type} viewer=${viewerId?.slice(0, 8) ?? '-'} stamped=${viewerId !== undefined && viewerId !== ws._viewerId} relay=${ws._isPlatformRelay === true} hostAttached=${this.browserHost !== null} hostState=${this.browserHost?.getStatus().state ?? 'n/a'}`);
+        }
+        if (!this.browserHost) {
+            this.sendBrowserHostUnavailable(ws, viewerId);
+            return;
+        }
+        const policy = browserHostPolicy(msg.type);
+        if (policy === 'start') {
+            await this.dispatchToReadyHost(ws, msg, role, this.browserHost, viewerId);
+            return;
+        }
+        const hostState = this.browserHost.getStatus().state;
+        if (policy === 'ifReady' && hostState !== 'ready') {
+            log('drop', `type=${msg.type} reason=session_frame_host_${hostState}`);
+            return;
+        }
+        await handleBrowserHostMessage(this.browserHost, ws, msg, undefined, this.browserResponseSink(), viewerId);
+    }
+    browserResponseSink() {
+        return {
+            send: (target, response) => this.send(target, response),
+            broadcastToAll: (response) => this.broadcastToAll(response),
+        };
+    }
+    async dispatchToReadyHost(ws, msg, role, host, viewerId) {
+        await this.ensureBrowserHostStarted(ws, viewerId);
+        const finalState = host.getStatus().state;
+        if (msg.type !== 'browser_input') {
+            log('dispatchToReadyHost', `type=${msg.type} finalState=${finalState}`);
+        }
+        if (finalState === 'ready') {
+            await handleBrowserHostMessage(host, ws, msg, can(role, 'driveBrowser') ? undefined : 'view', this.browserResponseSink(), viewerId);
+            return;
+        }
+        if (finalState === 'crashed') {
+            log.info('drop', `type=${msg.type} reason=crashed`);
+            return;
+        }
+        log.info('drop', `type=${msg.type} reason=unready state=${finalState}`);
+        this.sendBrowserError(ws, 'browser_host_unready', `Browser host did not reach ready (state=${finalState}); please retry.`, viewerId);
+    }
+    sendBrowserHostUnavailable(ws, viewerId) {
+        this.sendBrowserError(ws, 'browser_host_unavailable', 'Browser host is not configured on this CLI. Run a recent Minionry CLI build with the Electron host included.', viewerId);
+    }
+    browserHostStartPromise = null;
+    async ensureBrowserHostStarted(ws, viewerId) {
+        const host = this.browserHost;
+        if (!host)
+            return;
+        const state = host.getStatus().state;
+        log('ensureStarted.enter', `state=${state} inflight=${this.browserHostStartPromise !== null}`);
+        if (this.browserHostStartPromise) {
+            await this.joinInflightStart(ws, viewerId, host, this.browserHostStartPromise);
+            return;
+        }
+        if (state === 'ready') {
+            log('ensureStarted.alreadyReady', 'no-op');
+            return;
+        }
+        if (state === 'crashed') {
+            await this.spawnRecovery(ws, viewerId, host);
+            return;
+        }
+        await this.spawnNewStart(ws, viewerId, host, state);
+    }
+    async joinInflightStart(ws, viewerId, host, inflight) {
+        log('ensureStarted.awaitInflight', 'piggy-backing on in-flight start');
+        try {
+            await inflight;
+            log('ensureStarted.inflightResolved', `state=${host.getStatus().state}`);
+        }
+        catch (err) {
+            log.info('ensureStarted.inflightRejected', err instanceof Error ? err.message : String(err));
+            this.sendBrowserError(ws, 'browser_host_start_failed', err instanceof Error ? err.message : String(err), viewerId);
+        }
+    }
+    async spawnNewStart(ws, viewerId, host, fromState) {
+        log.info('ensureStarted.spawn', `state=${fromState} → starting`);
+        const startedAt = Date.now();
+        const startPromise = host.start({ orchestraId: 'default' });
+        this.browserHostStartPromise = startPromise;
+        try {
+            await startPromise;
+            log.info('ensureStarted.resolved', `state=${host.getStatus().state} elapsedMs=${Date.now() - startedAt}`);
+        }
+        catch (err) {
+            log.info('ensureStarted.rejected', `elapsedMs=${Date.now() - startedAt} err=${err instanceof Error ? err.message : String(err)}`);
+            captureException(err, { context: 'wsHandler.ensureBrowserHostStarted' });
+            this.sendBrowserError(ws, 'browser_host_start_failed', err instanceof Error ? err.message : String(err), viewerId);
+        }
+        finally {
+            if (this.browserHostStartPromise === startPromise) {
+                this.browserHostStartPromise = null;
+            }
+        }
+    }
+    async spawnRecovery(ws, viewerId, host) {
+        log.info('ensureStarted.recover', 'state=crashed → recovering');
+        const startedAt = Date.now();
+        const recoverPromise = host.recover();
+        this.browserHostStartPromise = recoverPromise;
+        try {
+            await recoverPromise;
+            log.info('ensureStarted.recovered', `state=${host.getStatus().state} elapsedMs=${Date.now() - startedAt}`);
+        }
+        catch (err) {
+            log.info('ensureStarted.recoverRejected', `elapsedMs=${Date.now() - startedAt} err=${err instanceof Error ? err.message : String(err)}`);
+            captureException(err, { context: 'wsHandler.ensureBrowserHostStarted.recover' });
+            this.sendBrowserError(ws, 'browser_host_start_failed', err instanceof Error ? err.message : String(err), viewerId);
+        }
+        finally {
+            if (this.browserHostStartPromise === recoverPromise) {
+                this.browserHostStartPromise = null;
+            }
+        }
+    }
+    handleBrowserResumeDriver(msg) {
+        try {
+            const tabId = (msg.data?.tabId ?? msg.tabId);
+            log('resumeDriver', `tab=${tabId?.slice(0, 8) ?? 'missing'}`);
+            if (!tabId)
+                return;
+            getBrowserDriverState().resume(tabId);
+        }
+        catch (err) {
+            captureException(err);
+        }
+    }
+    sendBrowserError(ws, code, message, viewerId) {
+        log.info('tx.browser_error', `code=${code} viewer=${viewerId?.slice(0, 8) ?? '-'} message=${message}`);
+        this.send(ws, addressToViewer({
+            type: 'browser_error',
+            data: { code, message },
+        }, ws, viewerId));
+    }
+    sendPermissionDenied(ws, operation) {
+        this.send(ws, {
+            type: 'permissionDenied',
+            data: { operation, message: 'Your role does not permit this action' },
+        });
+    }
+    handleSystemPromptMessage(ws, msg, role) {
+        if (msg.type === 'getSystemPromptProfiles') {
+            handleGetSystemPromptProfiles(this, ws);
+            return;
+        }
+        if (!can(role, 'editSettings'))
+            return;
+        switch (msg.type) {
+            case 'createSystemPrompt':
+                handleCreateSystemPrompt(this, ws, msg);
+                return;
+            case 'readSystemPrompt':
+                handleReadSystemPrompt(this, ws, msg);
+                return;
+            case 'saveSystemPrompt':
+                handleSaveSystemPrompt(this, ws, msg);
+                return;
+            case 'deleteSystemPrompt':
+                handleDeleteSystemPrompt(this, ws, msg);
+                return;
+        }
+    }
+    handleFileDownloadMessage(ws, msg, tabId, workingDir) {
+        if (!this.fileDownloadHandler) {
+            this.fileDownloadHandler = new FileDownloadHandler(workingDir);
+        }
+        const handler = this.fileDownloadHandler;
+        const send = this.send.bind(this);
+        switch (msg.type) {
+            case 'fileDownloadStart':
+                handler.handleDownloadStart(ws, send, tabId, msg.data);
+                break;
+            case 'fileDownloadCancel':
+                handler.handleDownloadCancel(ws, send, tabId, msg.data);
+                break;
+        }
+    }
+    handleFileUploadMessage(ws, msg, tabId, workingDir, role) {
+        if (!this.fileUploadHandler) {
+            this.fileUploadHandler = new FileUploadHandler(this);
+        }
+        const handler = this.fileUploadHandler;
+        const send = this.send.bind(this);
+        switch (msg.type) {
+            case 'fileUploadStart':
+                handler.handleUploadStart(ws, send, tabId, msg.data, workingDir, can(role, 'editFiles') ? undefined : 'view');
+                break;
+            case 'fileUploadChunk':
+                handler.handleUploadChunk(ws, send, tabId, msg.data);
+                break;
+            case 'fileUploadComplete':
+                handler.handleUploadComplete(ws, send, tabId, msg.data);
+                break;
+            case 'fileUploadCancel':
+                handler.handleUploadCancel(ws, send, tabId, msg.data);
+                break;
+        }
+    }
+    handleClose(ws) {
+        const tabMap = this.connections.get(ws);
+        if (tabMap) {
+            this.cleanupConnectionResources(tabMap);
+        }
+        this.connections.delete(ws);
+        this.allConnections.delete(ws);
+        cleanupTerminalSubscribers(this, ws);
+        this.sessionRoles.dropWs(ws);
+        if (ws._viewerId) {
+            teardownSdkForViewer(ws._viewerId);
+        }
+        if (ws._viewerId) {
+            this.collabSessions.dropViewer(ws._viewerId);
+        }
+        if (this.browserHost) {
+            try {
+                onBrowserWsContextClosed(this.browserHost, ws);
+            }
+            catch (err) {
+                captureException(err, { context: 'websocket.handleClose.browserDetach' });
+            }
+        }
+        if (this.allConnections.size === 0) {
+            teardownSdkOnTransportClose();
+            this.sessionRoles.clear();
+            this.disposeGlobalSingletons();
+            this.reapOrphanPtys();
+        }
+    }
+    handleTransportDetach(ws) {
+        const tabMap = this.connections.get(ws);
+        if (tabMap) {
+            for (const tabId of tabMap.keys()) {
+                const searchProcess = this.activeSearches.get(tabId);
+                if (searchProcess) {
+                    try {
+                        searchProcess.kill();
+                    }
+                    catch {   }
+                    this.activeSearches.delete(tabId);
+                }
+            }
+        }
+        this.connections.delete(ws);
+        this.allConnections.delete(ws);
+        cleanupTerminalSubscribers(this, ws);
+        this.sessionRoles.dropWs(ws);
+        if (this.browserHost) {
+            try {
+                onBrowserWsContextClosed(this.browserHost, ws);
+            }
+            catch (err) {
+                captureException(err, { context: 'websocket.handleTransportDetach.browserDetach' });
+            }
+        }
+        this.collabSessions.onTransportDetach();
+    }
+    handleBrowserViewerDisconnected(viewerId) {
+        teardownSdkForViewer(viewerId);
+        this.sessionRoles.dropViewer(viewerId);
+        this.collabSessions.dropViewer(viewerId);
+        if (!this.browserHost)
+            return;
+        try {
+            onBrowserViewerDisconnected(this.browserHost, viewerId);
+        }
+        catch (err) {
+            captureException(err, { context: 'websocket.handleBrowserViewerDisconnected' });
+        }
+    }
+    disposeGlobalSingletons() {
+        this.collabSessions.dispose('shutdown');
+        if (this.fileUploadHandler) {
+            this.fileUploadHandler.destroy();
+            this.fileUploadHandler = null;
+        }
+        if (this.fileDownloadHandler) {
+            this.fileDownloadHandler.destroy();
+            this.fileDownloadHandler = null;
+        }
+        if (this.gitHeadWatcher) {
+            this.gitHeadWatcher.stop();
+            this.gitHeadWatcher = null;
+        }
+        if (this.skillsWatcher) {
+            this.skillsWatcher.stop();
+            this.skillsWatcher = null;
+        }
+        if (this.engineCredentialWatcher) {
+            this.engineCredentialWatcher.stop();
+            this.engineCredentialWatcher = null;
+        }
+        if (this.snippetWatcher) {
+            this.snippetWatcher.stop();
+            this.snippetWatcher = null;
+        }
+        this.snippetRegistry = null;
+        this.snippetExpander = null;
+    }
+    reapOrphanPtys() {
+        const ptyManager = getPTYManager();
+        const activeTerminals = ptyManager.getActiveTerminals();
+        if (activeTerminals.length === 0)
+            return;
+        console.log(`[handler] No web subscribers — closing ${activeTerminals.length} orphan PTY${activeTerminals.length === 1 ? '' : 's'}`);
+        ptyManager.closeAll();
+    }
+    executingSessionSummaries() {
+        const tabBySession = new Map();
+        for (const tabMap of this.connections.values()) {
+            for (const [tabId, sessionId] of tabMap)
+                tabBySession.set(sessionId, tabId);
+        }
+        const executing = [];
+        for (const [sessionId, session] of this.sessions) {
+            if (!session.isExecuting)
+                continue;
+            executing.push({
+                sessionId,
+                ...(tabBySession.has(sessionId) ? { tabId: tabBySession.get(sessionId) } : {}),
+                ...(session.executionStartTimestamp ? { executionStartTimestamp: session.executionStartTimestamp } : {}),
+            });
+        }
+        return executing;
+    }
+    settleExecutingSessions(origin) {
+        let settled = 0;
+        for (const [sessionId, session] of this.sessions) {
+            try {
+                if (session.settleForLifecycle(origin)) {
+                    settled++;
+                    console.log(`[WebSocketImproviseHandler] Settled executing session ${sessionId} on ${origin}`);
+                }
+            }
+            catch (err) {
+                console.error(`[WebSocketImproviseHandler] Failed to settle session ${sessionId} on ${origin}:`, err);
+            }
+        }
+        return settled;
+    }
+    refuseIfExecuting(ws, msg, action) {
+        if (msg.data?.force === true)
+            return false;
+        const executing = this.executingSessionSummaries();
+        if (executing.length === 0)
+            return false;
+        console.log(`[WebSocketImproviseHandler] Refusing ${msg.type}: ${executing.length} session(s) executing (${executing.map((e) => e.sessionId).join(', ')})`);
+        this.send(ws, {
+            type: 'error',
+            data: {
+                code: 'executions_in_flight',
+                message: `${executing.length} agent session${executing.length === 1 ? ' is' : 's are'} still running — wait for ${executing.length === 1 ? 'it' : 'them'} to finish or stop ${executing.length === 1 ? 'it' : 'them'} first, then ${action} again.`,
+                executing,
+            },
+        });
+        return true;
+    }
+    cleanupConnectionResources(tabMap) {
+        const sessionIds = new Set(tabMap.values());
+        for (const sessionId of sessionIds) {
+            const session = this.sessions.get(sessionId);
+            if (!session)
+                continue;
+            if (session.isExecuting)
+                continue;
+            session.destroy();
+            this.sessions.delete(sessionId);
+        }
+        for (const tabId of tabMap.keys()) {
+            const searchProcess = this.activeSearches.get(tabId);
+            if (searchProcess) {
+                try {
+                    searchProcess.kill();
+                }
+                catch {   }
+                this.activeSearches.delete(tabId);
+            }
+        }
+    }
+    send(ws, response) {
+        try {
+            ws.send(JSON.stringify(response));
+        }
+        catch (error) {
+            console.error('[WebSocketImproviseHandler] Error sending message:', error);
+        }
+    }
+    broadcastToOthers(sender, response) {
+        for (const ws of this.allConnections) {
+            if (ws !== sender) {
+                this.send(ws, response);
+            }
+        }
+    }
+    broadcastToAll(response) {
+        for (const ws of this.allConnections) {
+            this.send(ws, response);
+        }
+    }
+    cleanupSession(sessionId) {
+        this.sessions.delete(sessionId);
+    }
+    handleAskUserQuestionResponse(msg, tabId, ws) {
+        const data = msg.data;
+        const toolUseId = typeof data?.toolUseId === 'string' ? data.toolUseId : '';
+        const answersIn = data?.answers;
+        if (!toolUseId)
+            return;
+        const answers = {};
+        if (answersIn && typeof answersIn === 'object' && !Array.isArray(answersIn)) {
+            for (const [k, v] of Object.entries(answersIn)) {
+                if (typeof v === 'string')
+                    answers[k] = v;
+            }
+        }
+        const resolved = resolvePendingQuestion(toolUseId, answers);
+        if (resolved)
+            return;
+        if (Object.keys(answers).length === 0)
+            return;
+        const session = resolveTabSession(this, ws, tabId);
+        if (!session)
+            return;
+        session.executePrompt(buildLateAnswerPrompt(answers)).catch((err) => {
+            captureException(err, { context: 'wsHandler.askUserQuestion.lateReengage' });
+        });
+    }
+    deniesEnvironmentScope(ws, msg) {
+        const declared = parseDeclaredEnvironment(msg.data?.environment);
+        const mine = resolveCliEnvironment();
+        if (declared === mine)
+            return false;
+        console.log(`[WebSocketImproviseHandler] Rejecting ${msg.type} addressed to "${declared}" — this Space is "${mine}"`);
+        this.send(ws, {
+            type: 'error',
+            data: {
+                code: 'environment_mismatch',
+                message: `This Space runs in the ${mine} environment and cannot be controlled from ${declared}.`,
+            },
+        });
+        return true;
+    }
+    handleShutdownInstance(ws, role, msg) {
+        if (role !== 'owner') {
+            console.log('[WebSocketImproviseHandler] Rejecting shutdownInstance from non-owner');
+            this.send(ws, {
+                type: 'error',
+                data: {
+                    code: 'forbidden',
+                    message: 'Only the owner can shut down this instance.'
+                }
+            });
+            return;
+        }
+        if (this.deniesEnvironmentScope(ws, msg))
+            return;
+        if (this.refuseIfExecuting(ws, msg, 'shut down'))
+            return;
+        if (this.shutdownInProgress) {
+            console.log('[WebSocketImproviseHandler] shutdownInstance already in progress — ignoring duplicate request');
+            return;
+        }
+        this.shutdownInProgress = true;
+        console.log('[WebSocketImproviseHandler] shutdownInstance requested by owner — broadcasting shuttingDown and exiting');
+        this.collabSessions.flushAll('shutdown');
+        this.settleExecutingSessions('shutdown');
+        this.broadcastToAll({ type: 'shuttingDown', data: { reason: 'user-requested' } });
+        setTimeout(() => {
+            if (this.instanceRegistry) {
+                this.instanceRegistry.unregister();
+            }
+            process.exit(0);
+        }, 100);
+    }
+    handleRestartInstance(ws, role, msg) {
+        if (role !== 'owner') {
+            console.log('[WebSocketImproviseHandler] Rejecting restartInstance from non-owner');
+            this.send(ws, {
+                type: 'error',
+                data: {
+                    code: 'forbidden',
+                    message: 'Only the owner can restart this instance.'
+                }
+            });
+            return;
+        }
+        if (this.deniesEnvironmentScope(ws, msg))
+            return;
+        if (this.refuseIfExecuting(ws, msg, 'restart'))
+            return;
+        if (this.shutdownInProgress) {
+            console.log('[WebSocketImproviseHandler] restartInstance ignored — shutdown/restart already in progress');
+            return;
+        }
+        this.shutdownInProgress = true;
+        const workingDirectory = this.instanceRegistry?.getCurrentInstance()?.workingDirectory ??
+            process.env.MINIONRY_WORKING_DIR ??
+            process.cwd();
+        console.log(`[WebSocketImproviseHandler] restartInstance requested by owner — updating and relaunching minion in ${workingDirectory}`);
+        this.collabSessions.flushAll('shutdown');
+        this.settleExecutingSessions('restart');
+        this.broadcastToAll({ type: 'shuttingDown', data: { reason: 'restart' } });
+        setTimeout(() => {
+            try {
+                respawnInstance(workingDirectory, { update: true });
+            }
+            catch (err) {
+                console.error('[WebSocketImproviseHandler] Failed to relaunch minion on restart:', err);
+                captureException(err, { context: 'wsHandler.restartInstance.respawn' });
+            }
+            if (this.instanceRegistry) {
+                this.instanceRegistry.unregister();
+            }
+            process.exit(0);
+        }, 100);
+    }
+    async handleBrowserPreflight(ws, viewerId) {
+        log('preflight.enter', `viewer=${viewerId?.slice(0, 8) ?? '-'}`);
+        try {
+            const { preflight: runPreflight } = await import('../browser/preflight.js');
+            let result = await runPreflight();
+            log.info('preflight.result', `ok=${result.ok} failing=${result.checks.filter(c => !c.ok).map(c => c.id).join(',') || '-'}`);
+            if (result.checks.some((c) => c.id === 'electron' && !c.ok)) {
+                const { ensureElectronProvisioned, isElectronProvisioning } = await import('../browser/electron-provision.js');
+                log('preflight.provision', isElectronProvisioning() ? 'join-in-flight' : 'start');
+                this.replyPreflight(ws, viewerId, result, { chromiumInstalling: true });
+                try {
+                    const outcome = await ensureElectronProvisioned((line) => log('provision', line));
+                    log('preflight.provision.done', `ok=${outcome.ok} action=${outcome.action}`);
+                }
+                catch (err) {
+                    log('preflight.provision.error', err instanceof Error ? err.message : String(err));
+                }
+                result = await runPreflight();
+                log.info('preflight.reresult', `ok=${result.ok} failing=${result.checks.filter(c => !c.ok).map(c => c.id).join(',') || '-'}`);
+            }
+            this.deliverPreflight(ws, viewerId, result);
+        }
+        catch (err) {
+            log.error('preflight.threw', err);
+            this.send(ws, addressToViewer({
+                type: 'browser_preflight_result',
+                data: {
+                    ok: false,
+                    message: err instanceof Error ? err.message : String(err),
+                },
+            }, ws, viewerId));
+        }
+    }
+    deliverPreflight(ws, viewerId, result) {
+        const host = this.browserHost;
+        if (host)
+            this.sendBrowserSnapshot(ws, viewerId, host);
+        this.replyPreflight(ws, viewerId, result, { chromiumInstalling: false });
+        if (!host)
+            return;
+        void this.sendAgentRosterSnapshot(ws, viewerId, host);
+        if (result.ok && host.getStatus().state === 'crashed') {
+            log('preflight.autoRecover', 'state=crashed && result.ok → spawnRecovery');
+            void this.spawnRecovery(ws, viewerId, host);
+        }
+    }
+    handleBrowserSnapshotRequest(ws, viewerId) {
+        const host = this.browserHost;
+        if (!host) {
+            log('snapshot.noHost', `viewer=${viewerId?.slice(0, 8) ?? '-'}`);
+            return;
+        }
+        this.sendBrowserSnapshot(ws, viewerId, host);
+        void this.sendAgentRosterSnapshot(ws, viewerId, host);
+    }
+    sendBrowserSnapshot(ws, viewerId, host) {
+        const roster = host.getTabsSnapshot();
+        const status = host.getStatus();
+        const driverState = getBrowserDriverState();
+        const driving = [];
+        for (const tab of roster.tabs) {
+            const snapshot = driverState.getSnapshot(tab.id);
+            if (snapshot)
+                driving.push(snapshot);
+        }
+        log.info('snapshot.tx', `viewer=${viewerId?.slice(0, 8) ?? '-'} tabs=${roster.tabs.length} current=${roster.currentTabId?.slice(0, 8) ?? 'null'} host=${status.state} driverStates=${driving.length}`);
+        const unicast = (type, data) => {
+            this.send(ws, addressToViewer({ type, data }, ws, viewerId));
+        };
+        unicast('browser_state_update', { tabs: roster.tabs, currentTabId: roster.currentTabId });
+        unicast('browser_status', status);
+        for (const snapshot of driving)
+            unicast('browser_driver_state', snapshot);
+    }
+    async sendAgentRosterSnapshot(ws, viewerId, host) {
+        if (host.getStatus().state !== 'ready')
+            return;
+        try {
+            const leases = await host.listLeases();
+            const driverState = getBrowserDriverState();
+            const toDevice = {
+                broadcastToAll: (response) => this.send(ws, addressToViewer(response, ws, viewerId)),
+            };
+            for (const agentId of new Set(leases.map((lease) => lease.agentId))) {
+                const owner = leases
+                    .filter((lease) => lease.agentId === agentId)
+                    .map((lease) => driverState.getOwner(lease.tabId))
+                    .find((candidate) => candidate?.ownerAgentId === agentId);
+                const run = activeBrowserAgentTarget(agentId);
+                await broadcastAgentTabState(host, toDevice, agentId, owner?.ownerAgentLabel ?? run?.label ?? agentId, {
+                    ...(run?.engine ? { engine: run.engine } : {}),
+                    ...(run?.model ? { model: run.model } : {}),
+                    ...(owner?.ownerSessionId ? { sessionId: owner.ownerSessionId } : {}),
+                });
+            }
+        }
+        catch (err) {
+            log.warn('snapshot.agentRoster.failed', err instanceof Error ? err.message : String(err));
+        }
+    }
+    replyPreflight(ws, viewerId, result, opts) {
+        this.send(ws, addressToViewer({
+            type: 'browser_preflight_result',
+            data: toBrowserPreflightPayload(result, opts),
+        }, ws, viewerId));
+    }
+}