mstro-app 0.4.3 → 0.4.4

package/server/services/websocket/handler.ts

@@ -118,7 +118,30 @@ export class WebSocketImproviseHandler implements HandlerContext {
     }
   }
 
+  /** Dispatch table mapping message types to domain handlers. Built once, looked up per message. */
+  private static readonly DISPATCH: Record<string, 'session' | 'history' | 'file' | 'terminal' | 'fileExplorer' | 'git' | 'quality' | 'plan' | 'fileUpload'> = {
+    // Session
+    execute: 'session', cancel: 'session', getHistory: 'session', new: 'session', approve: 'session', reject: 'session',
+    // History
+    getSessions: 'history', getSessionsCount: 'history', getSessionById: 'history', deleteSession: 'history', clearHistory: 'history', searchHistory: 'history',
+    // File autocomplete/read
+    autocomplete: 'file', readFile: 'file', recordSelection: 'file',
+    // Terminal
+    terminalInit: 'terminal', terminalReconnect: 'terminal', terminalList: 'terminal', terminalInput: 'terminal', terminalResize: 'terminal', terminalClose: 'terminal',
+    // File explorer
+    listDirectory: 'fileExplorer', writeFile: 'fileExplorer', createFile: 'fileExplorer', createDirectory: 'fileExplorer', deleteFile: 'fileExplorer', renameFile: 'fileExplorer', notifyFileOpened: 'fileExplorer', searchFileContents: 'fileExplorer', cancelSearch: 'fileExplorer', findDefinition: 'fileExplorer',
+    // Git
+    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', gitWorktreePush: 'git', gitWorktreeCreatePR: 'git', gitMergePreview: 'git', gitWorktreeMerge: 'git', gitMergeAbort: 'git', gitMergeComplete: 'git',
+    // Quality
+    qualityDetectTools: 'quality', qualityScan: 'quality', qualityInstallTools: 'quality', qualityCodeReview: 'quality', qualityFixIssues: 'quality', qualityLoadState: 'quality', qualitySaveDirectories: 'quality',
+    // Plan + boards + sprints
+    planInit: 'plan', planGetState: 'plan', planListIssues: 'plan', planGetIssue: 'plan', planGetSprint: 'plan', planGetMilestone: 'plan', planCreateIssue: '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', planGetBoard: 'plan', planGetBoardState: 'plan', planReorderBoards: 'plan', planSetActiveBoard: 'plan', planGetBoardArtifacts: 'plan', planCreateSprint: 'plan', planActivateSprint: 'plan', planCompleteSprint: 'plan', planGetSprintArtifacts: 'plan',
+    // File upload
+    fileUploadStart: 'fileUpload', fileUploadChunk: 'fileUpload', fileUploadComplete: 'fileUpload', fileUploadCancel: 'fileUpload',
+  };
+
   private async dispatchMessage(ws: WSContext, msg: WebSocketMessage, tabId: string, workingDir: string, permission?: 'control' | 'view'): Promise<void> {
+    // Handle messages with custom inline logic first
     switch (msg.type) {
       case 'ping':
         this.send(ws, { type: 'pong', tabId });
@@ -128,86 +151,9 @@ export class WebSocketImproviseHandler implements HandlerContext {
       case 'resumeSession':
         if (!msg.data?.historicalSessionId) throw new Error('Historical session ID is required');
         return void await resumeHistoricalSession(this, ws, tabId, workingDir, msg.data.historicalSessionId);
-      // Session messages
-      case 'execute':
-      case 'cancel':
-      case 'getHistory':
-      case 'new':
-      case 'approve':
-      case 'reject':
-        return handleSessionMessage(this, ws, msg, tabId, permission);
-      // History messages
-      case 'getSessions':
-      case 'getSessionsCount':
-      case 'getSessionById':
-      case 'deleteSession':
-      case 'clearHistory':
-      case 'searchHistory':
-        return handleHistoryMessage(this, ws, msg, tabId, workingDir);
-      // File autocomplete/read
-      case 'autocomplete':
-      case 'readFile':
-      case 'recordSelection':
-        return handleFileMessage(this, ws, msg, tabId, workingDir, permission);
-      // Notification summary
       case 'requestNotificationSummary':
         if (!msg.data?.prompt || !msg.data?.output) throw new Error('Prompt and output are required for notification summary');
         return void await generateNotificationSummary(this, ws, tabId, msg.data.prompt, msg.data.output, workingDir);
-      // Terminal messages
-      case 'terminalInit':
-      case 'terminalReconnect':
-      case 'terminalList':
-      case 'terminalInput':
-      case 'terminalResize':
-      case 'terminalClose':
-        return handleTerminalMessage(this, ws, msg, tabId, workingDir, permission);
-      // File explorer messages
-      case 'listDirectory':
-      case 'writeFile':
-      case 'createFile':
-      case 'createDirectory':
-      case 'deleteFile':
-      case 'renameFile':
-      case 'notifyFileOpened':
-      case 'searchFileContents':
-      case 'cancelSearch':
-      case 'findDefinition':
-        return handleFileExplorerMessage(this, ws, msg, tabId, workingDir, permission);
-      // Git messages
-      case 'gitStatus':
-      case 'gitStage':
-      case 'gitUnstage':
-      case 'gitCommit':
-      case 'gitCommitWithAI':
-      case 'gitPush':
-      case 'gitPull':
-      case 'gitLog':
-      case 'gitDiscoverRepos':
-      case 'gitSetDirectory':
-      case 'gitGetRemoteInfo':
-      case 'gitCreatePR':
-      case 'gitGeneratePRDescription':
-      case 'gitListBranches':
-      case 'gitCheckout':
-      case 'gitCreateBranch':
-      case 'gitDeleteBranch':
-      case 'gitDiff':
-      case 'gitListTags':
-      case 'gitCreateTag':
-      case 'gitPushTag':
-      case 'gitWorktreeList':
-      case 'gitWorktreeCreate':
-      case 'gitWorktreeCreateAndAssign':
-      case 'gitWorktreeRemove':
-      case 'tabWorktreeSwitch':
-      case 'gitWorktreePush':
-      case 'gitWorktreeCreatePR':
-      case 'gitMergePreview':
-      case 'gitWorktreeMerge':
-      case 'gitMergeAbort':
-      case 'gitMergeComplete':
-        return handleGitMessage(this, ws, msg, tabId, workingDir);
-      // Tab sync messages
       case 'getActiveTabs':
         return handleGetActiveTabs(this, ws, workingDir);
       case 'createTab':
@@ -222,59 +168,26 @@ export class WebSocketImproviseHandler implements HandlerContext {
         return handleRemoveTab(this, ws, tabId, workingDir);
       case 'markTabViewed':
         return handleMarkTabViewed(this, ws, tabId, workingDir);
-      // Quality messages
-      case 'qualityDetectTools':
-      case 'qualityScan':
-      case 'qualityInstallTools':
-      case 'qualityCodeReview':
-      case 'qualityFixIssues':
-      case 'qualityLoadState':
-      case 'qualitySaveDirectories':
-        return handleQualityMessage(this, ws, msg, tabId, workingDir);
-      // Plan messages
-      case 'planInit':
-      case 'planGetState':
-      case 'planListIssues':
-      case 'planGetIssue':
-      case 'planGetSprint':
-      case 'planGetMilestone':
-      case 'planCreateIssue':
-      case 'planUpdateIssue':
-      case 'planDeleteIssue':
-      case 'planScaffold':
-      case 'planPrompt':
-      case 'planExecute':
-      case 'planPause':
-      case 'planStop':
-      case 'planResume':
-      // Board lifecycle messages
-      case 'planCreateBoard':
-      case 'planUpdateBoard':
-      case 'planArchiveBoard':
-      case 'planGetBoard':
-      case 'planGetBoardState':
-      case 'planReorderBoards':
-      case 'planSetActiveBoard':
-      case 'planGetBoardArtifacts':
-      // Sprint lifecycle messages (legacy)
-      case 'planCreateSprint':
-      case 'planActivateSprint':
-      case 'planCompleteSprint':
-      case 'planGetSprintArtifacts':
-        return handlePlanMessage(this, ws, msg, tabId, workingDir, permission);
-      // Settings messages
       case 'getSettings':
         return handleGetSettings(this, ws);
       case 'updateSettings':
         return handleUpdateSettings(this, ws, msg);
-      // File upload messages (chunked remote uploads)
-      case 'fileUploadStart':
-      case 'fileUploadChunk':
-      case 'fileUploadComplete':
-      case 'fileUploadCancel':
-        return this.handleFileUploadMessage(ws, msg, tabId, workingDir);
-      default:
-        throw new Error(`Unknown message type: ${msg.type}`);
+    }
+
+    // Dispatch table lookup for domain handlers
+    const domain = WebSocketImproviseHandler.DISPATCH[msg.type];
+    if (!domain) throw new Error(`Unknown message type: ${msg.type}`);
+
+    switch (domain) {
+      case 'session':    return handleSessionMessage(this, ws, msg, tabId, permission);
+      case 'history':    return handleHistoryMessage(this, ws, msg, tabId, workingDir);
+      case 'file':       return handleFileMessage(this, ws, msg, tabId, workingDir, permission);
+      case 'terminal':   return handleTerminalMessage(this, ws, msg, tabId, workingDir, permission);
+      case 'fileExplorer': return handleFileExplorerMessage(this, ws, msg, tabId, workingDir, permission);
+      case 'git':        return handleGitMessage(this, ws, msg, tabId, workingDir);
+      case 'quality':    return handleQualityMessage(this, ws, msg, tabId, workingDir);
+      case 'plan':       return handlePlanMessage(this, ws, msg, tabId, workingDir, permission);
+      case 'fileUpload': return this.handleFileUploadMessage(ws, msg, tabId, workingDir);
     }
   }
 

package/server/services/websocket/plan-board-handlers.ts

@@ -0,0 +1,277 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for details.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { replaceFrontMatterField } from '../plan/front-matter.js';
+import { getNextBoardId, getNextBoardNumber, parseBoardArtifacts, parseBoardDirectory, parsePlanDirectory, resolvePmDir } from '../plan/parser.js';
+import type { Workspace } from '../plan/types.js';
+import type { HandlerContext } from './handler-context.js';
+import { denyIfViewOnly, formatYamlValue } from './plan-helpers.js';
+import type { WebSocketMessage, WSContext } from './types.js';
+
+// ============================================================================
+// Board lifecycle handlers
+// ============================================================================
+
+export function handleCreateBoard(
+  ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage,
+  workingDir: string, permission?: 'control' | 'view',
+): void {
+  if (denyIfViewOnly(ctx, ws, permission)) return;
+
+  const pmDir = resolvePmDir(workingDir);
+  if (!pmDir) {
+    ctx.send(ws, { type: 'planError', data: { error: 'No PM directory found' } });
+    return;
+  }
+
+  const fullState = parsePlanDirectory(workingDir);
+  if (!fullState) return;
+
+  const boardId = getNextBoardId(fullState.boards);
+  const boardNum = getNextBoardNumber(fullState.boards);
+  const title = msg.data?.title || `Board ${boardNum}`;
+  const goal = msg.data?.goal || '';
+  const boardDir = join(pmDir, 'boards', boardId);
+
+  for (const dir of ['backlog', 'out', 'reviews', 'logs']) {
+    mkdirSync(join(boardDir, dir), { recursive: true });
+  }
+
+  const today = new Date().toISOString().split('T')[0];
+  writeFileSync(join(boardDir, 'board.md'), `---
+id: ${boardId}
+title: "${title.replace(/"/g, '\\"')}"
+status: draft
+created: "${today}"
+completed_at: null
+goal: "${goal.replace(/"/g, '\\"')}"
+---
+
+# ${title}
+
+## Goal
+${goal}
+
+## Notes
+`, 'utf-8');
+
+  writeFileSync(join(boardDir, 'STATE.md'), `---
+project: ../../project.md
+board: board.md
+paused: false
+---
+
+# Board State
+
+## Ready to Work
+
+## In Progress
+
+## Blocked
+
+## Recently Completed
+
+## Warnings
+`, 'utf-8');
+
+  writeFileSync(join(boardDir, 'progress.md'), '# Board Progress\n', 'utf-8');
+
+  const wsPath = join(pmDir, 'workspace.json');
+  if (!existsSync(wsPath)) {
+    writeFileSync(wsPath, JSON.stringify({ activeBoardId: null, boardOrder: [] }, null, 2), 'utf-8');
+  }
+  const workspaceContent = readFileSync(wsPath, 'utf-8');
+  const workspace: Workspace = JSON.parse(workspaceContent);
+  workspace.boardOrder.push(boardId);
+  if (!workspace.activeBoardId) {
+    workspace.activeBoardId = boardId;
+  }
+  writeFileSync(join(pmDir, 'workspace.json'), JSON.stringify(workspace, null, 2), 'utf-8');
+
+  const boardState = parseBoardDirectory(pmDir, boardId);
+  if (boardState) {
+    ctx.broadcastToAll({ type: 'planBoardCreated', data: boardState.board });
+    ctx.broadcastToAll({ type: 'planWorkspaceUpdated', data: workspace });
+  }
+}
+
+export function handleUpdateBoard(
+  ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage,
+  workingDir: string, permission?: 'control' | 'view',
+): void {
+  if (denyIfViewOnly(ctx, ws, permission)) return;
+
+  const { boardId, fields } = msg.data || {};
+  if (!boardId || !fields) {
+    ctx.send(ws, { type: 'planError', data: { error: 'Board ID and fields required' } });
+    return;
+  }
+
+  const pmDir = resolvePmDir(workingDir);
+  if (!pmDir) return;
+
+  const boardMdPath = join(pmDir, 'boards', boardId, 'board.md');
+  if (!existsSync(boardMdPath)) {
+    ctx.send(ws, { type: 'planError', data: { error: `Board not found: ${boardId}` } });
+    return;
+  }
+
+  let content = readFileSync(boardMdPath, 'utf-8');
+  for (const [key, value] of Object.entries(fields as Record<string, unknown>)) {
+    const yamlKey = key.replace(/([A-Z])/g, '_$1').toLowerCase();
+    content = replaceFrontMatterField(content, yamlKey, formatYamlValue(value));
+  }
+  writeFileSync(boardMdPath, content, 'utf-8');
+
+  const boardState = parseBoardDirectory(pmDir, boardId);
+  if (boardState) {
+    ctx.broadcastToAll({ type: 'planBoardUpdated', data: boardState.board });
+  }
+}
+
+export function handleArchiveBoard(
+  ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage,
+  workingDir: string, permission?: 'control' | 'view',
+): void {
+  if (denyIfViewOnly(ctx, ws, permission)) return;
+
+  const boardId = msg.data?.boardId;
+  if (!boardId) {
+    ctx.send(ws, { type: 'planError', data: { error: 'Board ID required' } });
+    return;
+  }
+
+  const pmDir = resolvePmDir(workingDir);
+  if (!pmDir) return;
+
+  const boardMdPath = join(pmDir, 'boards', boardId, 'board.md');
+  if (!existsSync(boardMdPath)) {
+    ctx.send(ws, { type: 'planError', data: { error: `Board not found: ${boardId}` } });
+    return;
+  }
+
+  let content = readFileSync(boardMdPath, 'utf-8');
+  content = replaceFrontMatterField(content, 'status', 'archived');
+  writeFileSync(boardMdPath, content, 'utf-8');
+
+  const workspacePath = join(pmDir, 'workspace.json');
+  if (existsSync(workspacePath)) {
+    const workspace: Workspace = JSON.parse(readFileSync(workspacePath, 'utf-8'));
+    workspace.boardOrder = workspace.boardOrder.filter(id => id !== boardId);
+    if (workspace.activeBoardId === boardId) {
+      workspace.activeBoardId = workspace.boardOrder[0] || null;
+    }
+    writeFileSync(workspacePath, JSON.stringify(workspace, null, 2), 'utf-8');
+    ctx.broadcastToAll({ type: 'planWorkspaceUpdated', data: workspace });
+  }
+
+  const boardState = parseBoardDirectory(pmDir, boardId);
+  if (boardState) {
+    ctx.broadcastToAll({ type: 'planBoardArchived', data: boardState.board });
+  }
+}
+
+export function handleGetBoard(
+  ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage,
+  workingDir: string,
+): void {
+  const boardId = msg.data?.boardId;
+  if (!boardId) {
+    ctx.send(ws, { type: 'planError', data: { error: 'Board ID required' } });
+    return;
+  }
+
+  const pmDir = resolvePmDir(workingDir);
+  if (!pmDir) return;
+
+  const boardState = parseBoardDirectory(pmDir, boardId);
+  if (!boardState) {
+    ctx.send(ws, { type: 'planError', data: { error: `Board not found: ${boardId}` } });
+    return;
+  }
+
+  ctx.send(ws, { type: 'planBoardState', data: boardState });
+}
+
+export function handleGetBoardState(
+  ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage,
+  workingDir: string,
+): void {
+  handleGetBoard(ctx, ws, msg, workingDir);
+}
+
+export function handleReorderBoards(
+  ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage,
+  workingDir: string, permission?: 'control' | 'view',
+): void {
+  if (denyIfViewOnly(ctx, ws, permission)) return;
+
+  const boardOrder = msg.data?.boardOrder;
+  if (!Array.isArray(boardOrder)) {
+    ctx.send(ws, { type: 'planError', data: { error: 'boardOrder array required' } });
+    return;
+  }
+
+  const pmDir = resolvePmDir(workingDir);
+  if (!pmDir) return;
+
+  const workspacePath = join(pmDir, 'workspace.json');
+  if (!existsSync(workspacePath)) return;
+
+  const workspace: Workspace = JSON.parse(readFileSync(workspacePath, 'utf-8'));
+  workspace.boardOrder = boardOrder;
+  writeFileSync(workspacePath, JSON.stringify(workspace, null, 2), 'utf-8');
+
+  ctx.broadcastToAll({ type: 'planWorkspaceUpdated', data: workspace });
+}
+
+export function handleSetActiveBoard(
+  ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage,
+  workingDir: string, permission?: 'control' | 'view',
+): void {
+  if (denyIfViewOnly(ctx, ws, permission)) return;
+
+  const boardId = msg.data?.boardId;
+  if (!boardId) {
+    ctx.send(ws, { type: 'planError', data: { error: 'Board ID required' } });
+    return;
+  }
+
+  const pmDir = resolvePmDir(workingDir);
+  if (!pmDir) return;
+
+  const workspacePath = join(pmDir, 'workspace.json');
+  if (!existsSync(workspacePath)) return;
+
+  const workspace: Workspace = JSON.parse(readFileSync(workspacePath, 'utf-8'));
+  workspace.activeBoardId = boardId;
+  writeFileSync(workspacePath, JSON.stringify(workspace, null, 2), 'utf-8');
+
+  ctx.broadcastToAll({ type: 'planWorkspaceUpdated', data: workspace });
+
+  const boardState = parseBoardDirectory(pmDir, boardId);
+  if (boardState) {
+    ctx.send(ws, { type: 'planBoardState', data: boardState });
+  }
+}
+
+export function handleGetBoardArtifacts(
+  ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage,
+  workingDir: string,
+): void {
+  const boardId = msg.data?.boardId;
+  if (!boardId) {
+    ctx.send(ws, { type: 'planError', data: { error: 'Board ID required' } });
+    return;
+  }
+
+  const artifacts = parseBoardArtifacts(workingDir, boardId);
+  if (!artifacts) {
+    ctx.send(ws, { type: 'planBoardArtifacts', data: { boardId, progressLog: '', outputFiles: [], reviewResults: [], executionLogs: [] } });
+    return;
+  }
+
+  ctx.send(ws, { type: 'planBoardArtifacts', data: artifacts });
+}

package/server/services/websocket/plan-execution-handlers.ts

@@ -0,0 +1,184 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for details.
+
+import { handlePlanPrompt } from '../plan/composer.js';
+import type { PlanExecutor } from '../plan/executor.js';
+import { parsePlanDirectory } from '../plan/parser.js';
+import type { HandlerContext } from './handler-context.js';
+import { denyIfViewOnly, executorCache, getExecutor } from './plan-helpers.js';
+import type { WebSocketMessage, WSContext } from './types.js';
+
+// ============================================================================
+// Composer + Execution handlers
+// ============================================================================
+
+export function handlePrompt(
+  ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage,
+  workingDir: string, permission?: 'control' | 'view',
+): void {
+  if (denyIfViewOnly(ctx, ws, permission)) return;
+
+  const prompt = msg.data?.prompt;
+  const boardId = msg.data?.boardId as string | undefined;
+  if (!prompt) {
+    ctx.send(ws, { type: 'planError', data: { error: 'Prompt required' } });
+    return;
+  }
+  handlePlanPrompt(ctx, ws, prompt, workingDir, boardId).catch(error => {
+    ctx.send(ws, {
+      type: 'planError',
+      data: { error: error instanceof Error ? error.message : String(error) },
+    });
+  });
+}
+
+function wireExecutorEvents(executor: PlanExecutor, ctx: HandlerContext, workingDir: string): void {
+  executor.removeAllListeners();
+
+  executor.on('statusChanged', (status: string) => {
+    ctx.broadcastToAll({ type: 'planExecutionProgress', data: { status } });
+  });
+
+  executor.on('issueStarted', (issue: { id: string; title: string }) => {
+    ctx.broadcastToAll({
+      type: 'planExecutionProgress',
+      data: { issueId: issue.id, status: 'executing', title: issue.title },
+    });
+  });
+
+  executor.on('output', (data: { issueId: string; text: string }) => {
+    ctx.broadcastToAll({ type: 'planExecutionOutput', data });
+  });
+
+  executor.on('issueCompleted', () => {
+    ctx.broadcastToAll({ type: 'planExecutionMetrics', data: executor.getMetrics() });
+    const fullState = parsePlanDirectory(workingDir);
+    if (fullState) {
+      ctx.broadcastToAll({ type: 'planStateUpdated', data: fullState });
+    }
+  });
+
+  executor.on('issueError', (data: { issueId: string; error: string }) => {
+    ctx.broadcastToAll({ type: 'planExecutionError', data });
+  });
+
+  executor.on('waveStarted', (data: { issueIds: string[] }) => {
+    ctx.broadcastToAll({
+      type: 'planExecutionProgress',
+      data: { status: 'wave', issueIds: data.issueIds },
+    });
+  });
+
+  executor.on('waveError', (data: { issueIds: string[]; error: string }) => {
+    ctx.broadcastToAll({ type: 'planExecutionError', data });
+  });
+
+  executor.on('stateUpdated', () => {
+    const fullState = parsePlanDirectory(workingDir);
+    if (fullState) {
+      ctx.broadcastToAll({ type: 'planStateUpdated', data: fullState });
+    }
+  });
+
+  executor.on('reviewProgress', (data: { issueId: string; status: string }) => {
+    ctx.broadcastToAll({ type: 'planReviewProgress', data });
+  });
+
+  executor.on('complete', (reason: string) => {
+    ctx.broadcastToAll({ type: 'planExecutionComplete', data: { reason, metrics: executor.getMetrics() } });
+  });
+
+  executor.on('error', (error: string) => {
+    ctx.broadcastToAll({ type: 'planExecutionError', data: { error } });
+  });
+}
+
+export function handleExecute(
+  ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage,
+  workingDir: string, permission?: 'control' | 'view',
+): void {
+  if (denyIfViewOnly(ctx, ws, permission)) return;
+
+  const executor = getExecutor(workingDir);
+
+  if (executor.getStatus() === 'executing' || executor.getStatus() === 'starting') {
+    ctx.send(ws, { type: 'planError', data: { error: 'Execution already in progress' } });
+    return;
+  }
+
+  wireExecutorEvents(executor, ctx, workingDir);
+
+  const boardId = msg.data?.boardId as string | undefined;
+  ctx.send(ws, { type: 'planExecutionStarted', data: { status: 'executing', boardId } });
+  const startPromise = boardId ? executor.startBoard(boardId) : executor.start();
+  startPromise.catch(error => {
+    ctx.send(ws, {
+      type: 'planExecutionError',
+      data: { error: error instanceof Error ? error.message : String(error) },
+    });
+  });
+}
+
+export function handleExecuteEpic(
+  ctx: HandlerContext, ws: WSContext, msg: WebSocketMessage,
+  workingDir: string, permission?: 'control' | 'view',
+): void {
+  if (denyIfViewOnly(ctx, ws, permission)) return;
+
+  const epicPath = msg.data?.epicPath;
+  if (!epicPath) {
+    ctx.send(ws, { type: 'planError', data: { error: 'Epic path required' } });
+    return;
+  }
+
+  const executor = getExecutor(workingDir);
+
+  if (executor.getStatus() === 'executing' || executor.getStatus() === 'starting') {
+    ctx.send(ws, { type: 'planError', data: { error: 'Execution already in progress' } });
+    return;
+  }
+
+  wireExecutorEvents(executor, ctx, workingDir);
+
+  ctx.send(ws, { type: 'planExecutionStarted', data: { status: 'executing', epicPath } });
+  executor.startEpic(epicPath).catch(error => {
+    ctx.send(ws, {
+      type: 'planExecutionError',
+      data: { error: error instanceof Error ? error.message : String(error) },
+    });
+  });
+}
+
+export function handlePause(
+  ctx: HandlerContext, ws: WSContext,
+  workingDir: string, permission?: 'control' | 'view',
+): void {
+  if (denyIfViewOnly(ctx, ws, permission)) return;
+  const executor = executorCache.get(workingDir);
+  if (executor) executor.pause();
+}
+
+export function handleStop(
+  ctx: HandlerContext, ws: WSContext,
+  workingDir: string, permission?: 'control' | 'view',
+): void {
+  if (denyIfViewOnly(ctx, ws, permission)) return;
+  const executor = executorCache.get(workingDir);
+  if (executor) executor.stop();
+}
+
+export function handleResume(
+  ctx: HandlerContext, ws: WSContext,
+  workingDir: string, permission?: 'control' | 'view',
+): void {
+  if (denyIfViewOnly(ctx, ws, permission)) return;
+  const executor = executorCache.get(workingDir);
+  if (executor) {
+    executor.resume().catch(error => {
+      ctx.send(ws, {
+        type: 'planExecutionError',
+        data: { error: error instanceof Error ? error.message : String(error) },
+      });
+    });
+  }
+}