mstro-app 0.4.52 → 0.5.1

package/server/services/plan/executor.ts

@@ -1,5 +1,4 @@
 // Copyright (c) 2025-present Mstro, Inc. All rights reserved.
-// Licensed under the MIT License. See LICENSE file for details.
 
 /**
  * Plan Executor — Wave-based execution with parallel headless Claude Code instances.
@@ -9,41 +8,90 @@
  * reconciles state, and repeats.
  *
  * Implementation is split across focused modules:
+ * - board-config.ts          — board.md metadata reads, workspace.json active board resolution
  * - config-installer.ts      — tool permissions install/uninstall
  * - issue-prompt-builder.ts  — per-issue prompt construction
+ * - issue-writer.ts          — issue front-matter updates, recovery, revert, cancellation notes
  * - output-manager.ts        — output path resolution, listing, publishing
- * - review-gate.ts           — AI-powered quality gate (review, parse, persist)
- * - front-matter.ts          — YAML front matter field editing utility
+ * - progress-log.ts          — progress.md writer + output dir creation
+ * - review-gate.ts           — AI-powered quality gate (review, parse, persist, full pipeline)
  */
 
 import { EventEmitter } from 'node:events';
-import { existsSync, readFileSync } from 'node:fs';
-import { appendFile, mkdir, readFile, writeFile } from 'node:fs/promises';
-import { isAbsolute, join, relative, resolve } from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
 import { runWithFileLogger } from '../../cli/headless/headless-logger.js';
+import {
+  DEFAULT_MAX_PARALLEL_AGENTS,
+  getBoardMaxParallelAgents,
+  resolveActiveBoardId,
+  resolveBoardDir,
+  tryCompleteBoardIfDone,
+} from './board-config.js';
 import { ConfigInstaller } from './config-installer.js';
 import { resolveReadyToWork } from './dependency-resolver.js';
-import { checkAllAcceptanceCriteria, replaceFrontMatterField, setFrontMatterFieldAsync } from './front-matter.js';
+import { loadBoardIssues, loadProjectIssues } from './issue-loader.js';
 import { buildIssuePrompt } from './issue-prompt-builder.js';
 import { runIssueWithRetry } from './issue-retry.js';
+import {
+  extractIssueStatus,
+  recoverStaleIssues,
+  revertIncompleteIssues,
+  updateIssueFrontMatter,
+  validateIssuePath,
+  type WarnFn,
+} from './issue-writer.js';
 import { listExistingDocs, publishOutputs, resolveOutputPath } from './output-manager.js';
-import { parseBoardDirectory, parsePlanDirectory, resolvePmDir } from './parser.js';
-import { appendReviewFeedback, getReviewAttemptCount, MAX_REVIEW_ATTEMPTS, persistReviewResult, reviewIssue } from './review-gate.js';
+import { resolvePmDir } from './parser.js';
+import { appendProgressEntry, ensureOutputDirs } from './progress-log.js';
+import { buildCompletionReason, detectDeadState, hasBlockedIssues } from './readiness-planner.js';
+import { runReviewPipeline } from './review-gate.js';
 import { reconcileState } from './state-reconciler.js';
 import type { Issue } from './types.js';
 
 export type ExecutionStatus = 'idle' | 'starting' | 'executing' | 'paused' | 'stopping' | 'complete' | 'error';
 
-/** Default max parallel agents when board doesn't specify. */
-const DEFAULT_MAX_PARALLEL_AGENTS = 3;
-
 /** Stop after this many consecutive waves with zero completions. */
 const MAX_CONSECUTIVE_EMPTY_WAVES = 3;
 
+/**
+ * Render a tool-call event as a short single-line label for the verbose
+ * Output stream — `Read · package.json`, `Bash · npm test`, etc. The web UI
+ * splits the label on the first ` · ` to render the tool name as a badge.
+ */
+function formatToolCallLine(toolName: string, input: Record<string, unknown> | undefined): string {
+  const arg = pickPrimaryArg(toolName, input);
+  return arg ? `${toolName} · ${arg}` : toolName;
+}
+
+function pickPrimaryArg(toolName: string, input: Record<string, unknown> | undefined): string {
+  if (!input) return '';
+  // Map common Claude Code tools to their most informative single argument.
+  const candidates: Record<string, string[]> = {
+    Read: ['file_path'],
+    Write: ['file_path'],
+    Edit: ['file_path'],
+    Glob: ['pattern'],
+    Grep: ['pattern'],
+    Bash: ['command'],
+    WebFetch: ['url'],
+    WebSearch: ['query'],
+    Task: ['description'],
+  };
+  const keys = candidates[toolName] ?? ['command', 'file_path', 'path', 'pattern', 'url', 'query'];
+  for (const key of keys) {
+    const value = input[key];
+    if (typeof value === 'string' && value.length > 0) {
+      return value.length > 120 ? `${value.slice(0, 117)}...` : value;
+    }
+  }
+  return '';
+}
+
 /** Per-issue stall timeouts (ms) — shorter than Agent Teams wave timeouts */
 const ISSUE_STALL_WARNING_MS = 900_000;    // 15 min
 const ISSUE_STALL_KILL_MS = 1_800_000;     // 30 min
-const ISSUE_STALL_HARD_CAP_MS = 3_600_000; // 1 hr hard cap
+const ISSUE_STALL_HARD_CAP_MS = 14_400_000; // 4 hr backstop — only fires after stall signals flag the run
 const ISSUE_STALL_MAX_EXTENSIONS = 10;
 
 export interface ExecutionMetrics {
@@ -55,27 +103,44 @@ export interface ExecutionMetrics {
   currentWaveIds: string[];
 }
 
+/** Scope options for a single run. Passed to start(), startBoard(), startEpic(). */
+export interface StartOptions {
+  /** Epic file path — restricts execution to issues under that epic. */
+  epic?: string;
+  /** Board ID to execute (e.g. "BOARD-001"). */
+  board?: string;
+  /** Optional worktree directory for running agents. PM data is always read from workingDir. */
+  executionDir?: string;
+}
+
+/**
+ * Immutable per-run context resolved when a run starts. Groups paths, scope,
+ * and environment so helper methods can read them in one place rather than
+ * reaching for scattered fields on the executor.
+ */
+interface PlanExecutionContext {
+  readonly workingDir: string;
+  readonly extraEnv?: Record<string, string>;
+  readonly epicScope: string | null;
+  readonly boardId: string | null;
+  readonly executionDir: string | null;
+  readonly pmDir: string | null;
+  readonly boardDir: string | null;
+}
+
 export class PlanExecutor extends EventEmitter {
   private status: ExecutionStatus = 'idle';
-  private workingDir: string;
+  private readonly workingDir: string;
+  private readonly extraEnv?: Record<string, string>;
   private shouldStop = false;
   private shouldPause = false;
   /** AbortController for killing running HeadlessRunner processes on stop. */
   private waveAbortController: AbortController | null = null;
-  private epicScope: string | null = null;
-  /** Cached PM directory path — resolved once per start(). */
-  private pmDir: string | null = null;
-  /** Board directory path (e.g. /path/.mstro/pm/boards/BOARD-001). Used for outputs, reviews, progress. */
-  private boardDir: string | null = null;
-  /** Board ID being executed (e.g. "BOARD-001") */
-  private boardId: string | null = null;
+  /** Resolved context for the current/last run — rebuilt each runStart(). */
+  private context: PlanExecutionContext;
+  /** Options from the last run; replayed on resume() to preserve scope. */
+  private lastStartOptions: StartOptions = {};
   private configInstaller: ConfigInstaller;
-  /** Flag to prevent start() from clearing scope set by startBoard/startEpic */
-  private _scopeSetByCall = false;
-  /** Extra environment variables forwarded to HeadlessRunner child processes (e.g. API keys) */
-  private extraEnv?: Record<string, string>;
-  /** Optional worktree directory for running AI agents. PM data is always read from workingDir. */
-  private executionDir: string | null = null;
   private metrics: ExecutionMetrics = {
     issuesCompleted: 0,
     issuesAttempted: 0,
@@ -89,59 +154,60 @@ export class PlanExecutor extends EventEmitter {
     this.workingDir = workingDir;
     this.extraEnv = options?.extraEnv;
     this.configInstaller = new ConfigInstaller(workingDir);
-  }
-
-  private validateIssuePath(issuePath: string, baseDir: string): string {
-    const resolvedBase = resolve(baseDir);
-    const resolvedFull = resolve(resolvedBase, issuePath);
-    const rel = relative(resolvedBase, resolvedFull);
-    if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) {
-      throw new Error(`Invalid issue path: path traversal detected in "${issuePath}"`);
-    }
-    return resolvedFull;
+    this.context = this.buildContext({});
   }
 
   getStatus(): ExecutionStatus { return this.status; }
   getMetrics(): ExecutionMetrics { return { ...this.metrics }; }
 
-  async startEpic(epicPath: string): Promise<void> {
-    this.epicScope = epicPath;
-    this._scopeSetByCall = true;
-    return this.start();
+  startEpic(epicPath: string): Promise<void> {
+    return this.runStart({ epic: epicPath });
   }
 
   /** Start execution, optionally scoped to a specific board. */
-  async startBoard(boardId: string, executionDir?: string): Promise<void> {
-    this.boardId = boardId;
-    this.executionDir = executionDir ?? null;
-    this._scopeSetByCall = true;
-    return this.start();
+  startBoard(boardId: string, executionDir?: string): Promise<void> {
+    return this.runStart({ board: boardId, executionDir });
+  }
+
+  start(options: StartOptions = {}): Promise<void> {
+    return this.runStart(options);
+  }
+
+  pause(): void { this.shouldPause = true; }
+
+  stop(): void {
+    this.shouldStop = true;
+    this.status = 'stopping';
+    this.emit('statusChanged', this.status);
+    // Kill all running HeadlessRunner processes in the current wave
+    this.waveAbortController?.abort();
   }
 
-  async start(): Promise<void> {
+  resume(): Promise<void> {
+    if (this.status !== 'paused') return Promise.resolve();
+    this.shouldPause = false;
+    // Replay the options from the previous run to preserve epic/board scope.
+    return this.runStart(this.lastStartOptions);
+  }
+
+  // ── Run orchestration ────────────────────────────────────────
+
+  private async runStart(options: StartOptions): Promise<void> {
     if (this.status === 'executing' || this.status === 'starting') return;
 
+    this.lastStartOptions = options;
     this.shouldStop = false;
     this.shouldPause = false;
-    // Reset scoping from previous runs unless explicitly set by startBoard/startEpic
-    if (!this._scopeSetByCall) {
-      this.epicScope = null;
-      this.boardId = null;
-      this.executionDir = null;
-    }
-    this._scopeSetByCall = false;
     this.status = 'starting';
     this.emit('statusChanged', this.status);
 
+    this.context = this.buildContext(options);
+
     const startTime = Date.now();
     this.status = 'executing';
     this.emit('statusChanged', this.status);
 
-    this.pmDir = resolvePmDir(this.workingDir);
-    this.boardDir = this.resolveBoardDir();
-
-    await this.recoverStaleIssues();
-
+    await this.runStaleRecovery();
     const stallResult = await this.runWaveLoop();
 
     this.metrics.totalDuration = Date.now() - startTime;
@@ -163,10 +229,43 @@ export class PlanExecutor extends EventEmitter {
     this.emit('statusChanged', this.status);
   }
 
+  /** Build an immutable execution context from start options. */
+  private buildContext(options: StartOptions): PlanExecutionContext {
+    const pmDir = resolvePmDir(this.workingDir);
+    const boardId = options.board ?? null;
+    return {
+      workingDir: this.workingDir,
+      extraEnv: this.extraEnv,
+      epicScope: options.epic ?? null,
+      boardId,
+      executionDir: options.executionDir ?? null,
+      pmDir,
+      boardDir: resolveBoardDir(pmDir, boardId),
+    };
+  }
+
+  // ── Warning / update helpers bound to the executor's event stream ──
+
+  /**
+   * Forward module-emitted warnings as executor 'output' events so they flow
+   * through to the WebSocket broadcast like inline warnings always have.
+   */
+  private emitWarn: WarnFn = (message, issueId) => {
+    this.emit('output', { issueId: issueId ?? 'system', text: message, boardId: this.context.boardId ?? null });
+  };
+
+  private async setIssueStatus(issuePath: string, newStatus: string): Promise<void> {
+    const { pmDir } = this.context;
+    if (!pmDir) return;
+    await updateIssueFrontMatter(pmDir, issuePath, newStatus, this.emitWarn);
+  }
+
+  // ── Wave loop ────────────────────────────────────────────────
+
   /** Run waves until done, paused, stopped, or stalled. */
   private async runWaveLoop(): Promise<'done' | 'stalled' | 'dead'> {
     let consecutiveZeroCompletions = 0;
-    const maxParallel = await this.getBoardMaxParallelAgents();
+    const maxParallel = await getBoardMaxParallelAgents(this.context.pmDir, this.effectiveBoardId(), this.emitWarn);
 
     while (!this.shouldStop && !this.shouldPause) {
       const readyIssues = await this.pickReadyIssues();
@@ -187,33 +286,15 @@ export class PlanExecutor extends EventEmitter {
     return 'done';
   }
 
-  private async hasDeadIssues(): Promise<boolean> {
-    const pmDir = this.pmDir;
-    if (!pmDir) return false;
-    const effectiveBoardId = this.boardId ?? this.resolveActiveBoardId();
-    const issues = effectiveBoardId
-      ? await this.loadBoardIssues(pmDir, effectiveBoardId)
-      : this.loadProjectIssues();
-    if (!issues) return false;
-    const terminalStatuses = new Set(['done', 'cancelled']);
-    return issues.some(i => i.type !== 'epic' && !terminalStatuses.has(i.status) && i.status !== 'todo');
-  }
-
-  pause(): void { this.shouldPause = true; }
-  stop(): void {
-    this.shouldStop = true;
-    this.status = 'stopping';
-    this.emit('statusChanged', this.status);
-    // Kill all running HeadlessRunner processes in the current wave
-    this.waveAbortController?.abort();
+  private effectiveBoardId(): string | null {
+    return this.context.boardId ?? resolveActiveBoardId(this.context.pmDir);
   }
 
-  resume(): Promise<void> {
-    if (this.status !== 'paused') return Promise.resolve();
-    this.shouldPause = false;
-    // Preserve board/epic scope across resume by marking as a scoped call
-    this._scopeSetByCall = true;
-    return this.start();
+  private async hasDeadIssues(): Promise<boolean> {
+    const { pmDir } = this.context;
+    if (!pmDir) return false;
+    const { issues } = await this.loadScopedIssues(pmDir);
+    return issues ? hasBlockedIssues(issues) : false;
   }
 
   // ── Wave execution ───────────────────────────────────────────
@@ -229,15 +310,15 @@ export class PlanExecutor extends EventEmitter {
     // Create abort controller for this wave — stop() will abort it
     this.waveAbortController = new AbortController();
 
-    await this.ensureOutputDirs();
+    await ensureOutputDirs(this.context.pmDir, this.context.boardDir);
     this.configInstaller.installPermissions();
 
     for (const issue of issues) {
-      await this.updateIssueFrontMatter(issue.path, 'in_progress');
+      await this.setIssueStatus(issue.path, 'in_progress');
     }
 
-    const existingDocs = listExistingDocs(this.workingDir, this.boardDir);
-    const pmDir = this.pmDir;
+    const existingDocs = listExistingDocs(this.workingDir, this.context.boardDir);
+    const { pmDir } = this.context;
 
     let completedCount = 0;
 
@@ -264,7 +345,7 @@ export class PlanExecutor extends EventEmitter {
         issueIds: waveIds,
         error: error instanceof Error ? error.message : String(error),
       });
-      await this.revertIncompleteIssues(issues);
+      if (pmDir) await revertIncompleteIssues(pmDir, issues, this.emitWarn);
     } finally {
       this.configInstaller.uninstallPermissions();
     }
@@ -283,18 +364,20 @@ export class PlanExecutor extends EventEmitter {
     waveLabel: string,
     abortSignal?: AbortSignal,
   ): Promise<void> {
-    const effectiveDir = this.executionDir || this.workingDir;
-    const outputPath = resolveOutputPath(issue, this.workingDir, this.boardDir);
+    const { executionDir, boardDir, workingDir } = this.context;
+    const effectiveDir = executionDir || workingDir;
+    const outputPath = resolveOutputPath(issue, workingDir, boardDir);
     const prompt = buildIssuePrompt({
       issue,
       workingDir: effectiveDir,
       pmDir,
-      boardDir: this.boardDir,
+      boardDir,
       existingDocs,
       outputPath,
     });
 
-    const boardLogDir = this.boardDir ? join(this.boardDir, 'logs') : undefined;
+    const boardLogDir = boardDir ? join(boardDir, 'logs') : undefined;
+    const emitOutput = (text: string) => this.emit('output', { issueId: issue.id, text });
     const result = await runWithFileLogger(`pm-issue-${issue.id}`, () => runIssueWithRetry({
       workingDir: effectiveDir,
       prompt,
@@ -302,8 +385,16 @@ export class PlanExecutor extends EventEmitter {
       stallKillMs: ISSUE_STALL_KILL_MS,
       stallHardCapMs: ISSUE_STALL_HARD_CAP_MS,
       stallMaxExtensions: ISSUE_STALL_MAX_EXTENSIONS,
-      outputCallback: (text: string) => {
-        this.emit('output', { issueId: issue.id, text });
+      outputCallback: emitOutput,
+      // Thinking deltas: marker-prefix so the web UI can classify them as a
+      // separate verbose-only block type without needing a new message field.
+      thinkingCallback: (text: string) => emitOutput(`[[MSTRO_THINKING]]${text}`),
+      // Tool calls: emit a single line per completed tool with a short arg
+      // summary. The 'tool_complete' event fires after input has fully
+      // streamed in, so we can render the tool with its real arguments.
+      toolUseCallback: (event) => {
+        if (event.type !== 'tool_complete' || !event.toolName) return;
+        emitOutput(`[[MSTRO_TOOL]]${formatToolCallLine(event.toolName, event.completeInput)}`);
       },
       extraEnv: this.extraEnv,
       abortSignal,
@@ -319,8 +410,10 @@ export class PlanExecutor extends EventEmitter {
    * doesn't prevent the others or kill the while loop in start().
    */
   private async finalizeWave(issues: Issue[], waveStart: number, waveLabel: string): Promise<void> {
+    const { pmDir, boardDir, boardId } = this.context;
+
     try {
-      reconcileState(this.workingDir, this.boardId ?? undefined);
+      reconcileState(this.workingDir, boardId ?? undefined);
       this.emit('stateUpdated');
     } catch (err) {
       this.emit('output', {
@@ -330,7 +423,7 @@ export class PlanExecutor extends EventEmitter {
     }
 
     try {
-      publishOutputs(issues, this.workingDir, this.boardDir, {
+      publishOutputs(issues, this.workingDir, boardDir, {
         onWarning: (issueId, text) => this.emit('output', { issueId, text: `Warning: ${text}` }),
       });
     } catch (err) {
@@ -341,7 +434,7 @@ export class PlanExecutor extends EventEmitter {
     }
 
     try {
-      await this.appendProgressEntry(issues, waveStart);
+      await appendProgressEntry(pmDir, boardDir, issues, waveStart, this.emitWarn);
     } catch (err) {
       this.emit('output', {
         issueId: waveLabel,
@@ -358,30 +451,21 @@ export class PlanExecutor extends EventEmitter {
    * and either confirmed `done` (passed) or reverted to `todo` (failed).
    */
   private async reconcileWaveResults(issues: Issue[]): Promise<number> {
-    const pmDir = this.pmDir;
+    const { pmDir } = this.context;
     if (!pmDir) return 0;
 
     let completed = 0;
 
     for (const issue of issues) {
-      const fullPath = this.validateIssuePath(issue.path, pmDir);
+      const fullPath = validateIssuePath(issue.path, pmDir);
       try {
         const content = await readFile(fullPath, 'utf-8');
-        const statusMatch = content.match(/^status:\s*(\S+)/m);
-        const currentStatus = statusMatch?.[1] ?? 'unknown';
+        const currentStatus = extractIssueStatus(content) ?? 'unknown';
 
         if (currentStatus === 'in_review' || currentStatus === 'done') {
-          if (issue.reviewGate === 'none') {
-            // Skip review gate — mark done directly
-            await this.updateIssueFrontMatter(issue.path, 'done');
-            this.metrics.issuesCompleted++;
-            this.emit('issueCompleted', issue);
-            completed++;
-          } else {
-            completed += await this.runReviewGate(issue, pmDir);
-          }
+          if (await this.finalizeCompletedIssue(issue, pmDir)) completed++;
         } else {
-          await this.updateIssueFrontMatter(issue.path, issue.status);
+          await this.setIssueStatus(issue.path, issue.status);
           this.emit('issueError', {
             issueId: issue.id,
             error: 'Issue did not complete during wave execution',
@@ -395,56 +479,41 @@ export class PlanExecutor extends EventEmitter {
     return completed;
   }
 
-  /** Run the review gate for a single issue that agents marked as done. Returns 1 if passed, 0 otherwise. */
-  private async runReviewGate(issue: Issue, pmDir: string): Promise<number> {
-    const reviewDir = this.boardDir ?? pmDir;
-    const attempts = getReviewAttemptCount(reviewDir, issue);
-    if (attempts >= MAX_REVIEW_ATTEMPTS) {
-      await this.updateIssueFrontMatter(issue.path, 'cancelled');
-      await this.appendCancellationNote(issue, pmDir, `Cancelled after ${MAX_REVIEW_ATTEMPTS} failed reviews — issue may need restructuring`);
-      this.emit('reviewProgress', { issueId: issue.id, status: 'max_attempts' });
-      this.emit('issueAbandoned', {
-        issueId: issue.id,
-        reason: `Review failed ${MAX_REVIEW_ATTEMPTS} times — cancelled to unblock dependents`,
-        attempts,
-      });
-      this.emit('output', { issueId: issue.id, text: `Review: max attempts reached, cancelling issue to unblock dependents` });
-      return 0;
-    }
-
-    await this.updateIssueFrontMatter(issue.path, 'in_review');
-    this.emit('reviewProgress', { issueId: issue.id, status: 'reviewing' });
-
-    const outputPath = resolveOutputPath(issue, this.workingDir, this.boardDir);
-    const result = await reviewIssue({
-      workingDir: this.executionDir || this.workingDir,
-      issue,
-      pmDir,
-      outputPath,
-      onOutput: (text) => this.emit('output', { issueId: issue.id, text }),
-      logDir: this.boardDir ? join(this.boardDir, 'logs') : undefined,
-      reviewCriteria: await this.getBoardReviewCriteria(),
-      boardDir: this.boardDir,
-      extraEnv: this.extraEnv,
-    });
-    persistReviewResult(reviewDir, issue, result);
-
-    if (result.passed) {
-      await this.updateIssueFrontMatter(issue.path, 'done');
+  /**
+   * Finalize a single issue whose status reached `in_review`/`done`. Runs the
+   * review pipeline unless the issue opted out via `reviewGate: 'none'`.
+   * Returns true when the issue is confirmed done (counted toward completions).
+   */
+  private async finalizeCompletedIssue(issue: Issue, pmDir: string): Promise<boolean> {
+    if (issue.reviewGate === 'none') {
+      await this.setIssueStatus(issue.path, 'done');
       this.metrics.issuesCompleted++;
-      this.emit('reviewProgress', { issueId: issue.id, status: 'passed' });
       this.emit('issueCompleted', issue);
-      return 1;
-    }
-
-    await this.updateIssueFrontMatter(issue.path, 'todo');
-    appendReviewFeedback(pmDir, issue, result);
-    this.emit('reviewProgress', { issueId: issue.id, status: 'failed' });
-    this.emit('issueError', {
-      issueId: issue.id,
-      error: `Review failed: ${result.checks.filter(c => !c.passed).map(c => c.name).join(', ')}`,
-    });
-    return 0;
+      return true;
+    }
+
+    const passed = await runReviewPipeline(
+      {
+        issue,
+        pmDir,
+        workingDir: this.workingDir,
+        executionDir: this.context.executionDir,
+        boardDir: this.context.boardDir,
+        boardId: this.context.boardId,
+        extraEnv: this.extraEnv,
+      },
+      {
+        setStatus: (path, status) => this.setIssueStatus(path, status),
+        onOutput: (issueId, text) => this.emit('output', { issueId, text }),
+        onReviewProgress: (issueId, status) => this.emit('reviewProgress', { issueId, status }),
+        onIssueAbandoned: (issueId, reason, attempts) => this.emit('issueAbandoned', { issueId, reason, attempts }),
+        onIssueCompleted: (completedIssue) => this.emit('issueCompleted', completedIssue),
+        onIssueError: (issueId, error) => this.emit('issueError', { issueId, error }),
+        warn: this.emitWarn,
+      },
+    );
+    if (passed) this.metrics.issuesCompleted++;
+    return passed;
   }
 
   // ── Recovery ─────────────────────────────────────────────────
@@ -455,28 +524,14 @@ export class PlanExecutor extends EventEmitter {
    * these issues block the dependency graph and cause the executor to
    * find zero ready issues, making "Implement" appear to do nothing.
    */
-  private async recoverStaleIssues(): Promise<void> {
-    const pmDir = this.pmDir;
+  private async runStaleRecovery(): Promise<void> {
+    const { pmDir } = this.context;
     if (!pmDir) return;
 
-    const effectiveBoardId = this.boardId ?? this.resolveActiveBoardId();
-    const issues = effectiveBoardId
-      ? await this.loadBoardIssues(pmDir, effectiveBoardId)
-      : this.loadProjectIssues();
-
+    const { issues } = await this.loadScopedIssues(pmDir);
     if (!issues) return;
 
-    const staleStatuses = new Set(['in_progress', 'in_review']);
-    const recovered: string[] = [];
-
-    for (const issue of issues) {
-      if (issue.type === 'epic') continue;
-      if (staleStatuses.has(issue.status)) {
-        await this.updateIssueFrontMatter(issue.path, 'todo');
-        recovered.push(`${issue.id} (${issue.status} → todo)`);
-      }
-    }
-
+    const recovered = await recoverStaleIssues(pmDir, issues, this.emitWarn);
     if (recovered.length > 0) {
       this.emit('output', {
         issueId: 'recovery',
@@ -486,315 +541,49 @@ export class PlanExecutor extends EventEmitter {
     }
   }
 
-  // ── Helpers ──────────────────────────────────────────────────
-
-  /** Read the board's maxParallelAgents setting, falling back to default. */
-  private async getBoardMaxParallelAgents(): Promise<number> {
-    const pmDir = this.pmDir;
-    if (!pmDir) return DEFAULT_MAX_PARALLEL_AGENTS;
-
-    const effectiveBoardId = this.boardId ?? this.resolveActiveBoardId();
-    if (!effectiveBoardId) return DEFAULT_MAX_PARALLEL_AGENTS;
-
-    const boardMdPath = join(pmDir, 'boards', effectiveBoardId, 'board.md');
-    if (!existsSync(boardMdPath)) return DEFAULT_MAX_PARALLEL_AGENTS;
-
-    try {
-      const content = await readFile(boardMdPath, 'utf-8');
-      const match = content.match(/^max_parallel_agents:\s*(\d+)/m);
-      return match ? Math.max(1, Math.min(Number(match[1]), 10)) : DEFAULT_MAX_PARALLEL_AGENTS;
-    } catch (err) {
-      this.emit('output', { issueId: 'system', text: `Warning: failed to read board max_parallel_agents: ${err instanceof Error ? err.message : String(err)}`, boardId: this.boardId ?? null });
-      return DEFAULT_MAX_PARALLEL_AGENTS;
-    }
-  }
-
-  /** Read the board's custom review criteria, if set. */
-  private async getBoardReviewCriteria(): Promise<string | undefined> {
-    const pmDir = this.pmDir;
-    if (!pmDir) return undefined;
-
-    const effectiveBoardId = this.boardId ?? this.resolveActiveBoardId();
-    if (!effectiveBoardId) return undefined;
-
-    const boardMdPath = join(pmDir, 'boards', effectiveBoardId, 'board.md');
-    if (!existsSync(boardMdPath)) return undefined;
-
-    try {
-      const content = await readFile(boardMdPath, 'utf-8');
-      const match = content.match(/^review_criteria:\s*"(.+)"/m);
-      if (!match) return undefined;
-      const raw = match[1].replace(/\\"/g, '"').replace(/\\n/g, '\n').trim();
-      return raw || undefined;
-    } catch (err) {
-      this.emit('output', { issueId: 'system', text: `Warning: failed to read board review criteria: ${err instanceof Error ? err.message : String(err)}`, boardId: this.boardId ?? null });
-      return undefined;
-    }
-  }
+  // ── Issue loading & readiness ────────────────────────────────
 
   private async pickReadyIssues(): Promise<Issue[]> {
-    const pmDir = this.pmDir;
+    const { pmDir, epicScope } = this.context;
     if (!pmDir) {
       this.emit('error', 'No PM directory found');
       return [];
     }
 
-    const effectiveBoardId = this.boardId ?? this.resolveActiveBoardId();
-    const issues = effectiveBoardId
-      ? await this.loadBoardIssues(pmDir, effectiveBoardId)
-      : this.loadProjectIssues();
-
+    const { issues, boardId } = await this.loadScopedIssues(pmDir);
     if (!issues) return [];
 
-    const readyIssues = resolveReadyToWork(issues, this.epicScope ?? undefined);
+    const readyIssues = resolveReadyToWork(issues, epicScope ?? undefined);
     if (readyIssues.length === 0) {
-      const deadState = this.detectDeadState(issues);
+      const deadState = detectDeadState(issues);
       if (deadState) {
         this.emit('error', deadState);
       } else {
-        this.emit('complete', this.buildCompletionReason(issues));
-        if (effectiveBoardId) {
-          await this.tryCompleteBoardIfDone(pmDir, effectiveBoardId, issues);
+        this.emit('complete', buildCompletionReason(issues, epicScope));
+        if (boardId) {
+          await tryCompleteBoardIfDone(pmDir, boardId, issues, this.emitWarn);
         }
       }
     }
     return readyIssues;
   }
 
-  /** Load issues from a specific board, auto-activating draft boards. Returns null on error. */
-  private async loadBoardIssues(pmDir: string, boardId: string): Promise<Issue[] | null> {
-    const boardState = parseBoardDirectory(pmDir, boardId);
-    if (!boardState) {
-      this.emit('error', `Board not found: ${boardId}`);
-      return null;
-    }
-    if (boardState.state.paused) {
-      this.emit('error', 'Board is paused');
-      return null;
-    }
-    if (boardState.board.status === 'draft') {
-      await this.activateBoard(pmDir, boardId);
-    } else if (boardState.board.status !== 'active') {
-      this.emit('error', `Board ${boardId} is not active (status: ${boardState.board.status})`);
-      return null;
-    }
-    return boardState.issues;
-  }
-
-  /** Load project-level issues (legacy or no boards). Returns null on error. */
-  private loadProjectIssues(): Issue[] | null {
-    const fullState = parsePlanDirectory(this.workingDir);
-    if (!fullState) {
-      this.emit('error', 'No PM directory found');
-      return null;
-    }
-    if (fullState.state.paused) {
-      this.emit('error', 'Project is paused');
-      return null;
-    }
-    return fullState.issues;
-  }
-
-  /** Activate a draft board by updating its status in board.md. */
-  private async activateBoard(pmDir: string, boardId: string): Promise<void> {
-    const boardMdPath = join(pmDir, 'boards', boardId, 'board.md');
-    if (!existsSync(boardMdPath)) return;
-    try {
-      const content = await readFile(boardMdPath, 'utf-8');
-      await writeFile(boardMdPath, replaceFrontMatterField(content, 'status', 'active'), 'utf-8');
-    } catch (err) {
-      this.emit('output', { issueId: 'system', text: `Warning: failed to activate board ${boardId}: ${err instanceof Error ? err.message : String(err)}`, boardId: this.boardId ?? null });
-    }
-  }
-
-  /** Check if all issues in a board are done and mark board as completed. */
-  private async tryCompleteBoardIfDone(pmDir: string, boardId: string, issues: Issue[]): Promise<void> {
-    const allDone = issues.length > 0 && issues.every(i => i.status === 'done' || i.status === 'cancelled');
-    if (!allDone) return;
-
-    const boardMdPath = join(pmDir, 'boards', boardId, 'board.md');
-    if (!existsSync(boardMdPath)) return;
-
-    try {
-      let content = await readFile(boardMdPath, 'utf-8');
-      content = replaceFrontMatterField(content, 'status', 'completed');
-      content = replaceFrontMatterField(content, 'completed_at', `"${new Date().toISOString()}"`);
-      await writeFile(boardMdPath, content, 'utf-8');
-    } catch (err) {
-      this.emit('output', { issueId: 'system', text: `Warning: failed to mark board ${boardId} as completed: ${err instanceof Error ? err.message : String(err)}`, boardId: this.boardId ?? null });
-    }
-  }
-
-  private resolveActiveBoardId(): string | null {
-    const pmDir = this.pmDir;
-    if (!pmDir) return null;
-    try {
-      const workspacePath = join(pmDir, 'workspace.json');
-      if (!existsSync(workspacePath)) return null;
-      const workspace = JSON.parse(readFileSync(workspacePath, 'utf-8'));
-      return workspace.activeBoardId ?? null;
-    } catch {
-      return null;
-    }
-  }
-
-  private buildCompletionReason(issues: Issue[]): string {
-    const nonEpic = issues.filter(i => i.type !== 'epic');
-    const done = nonEpic.filter(i => i.status === 'done' || i.status === 'cancelled').length;
-    const blocked = nonEpic.filter(i => i.status === 'todo').length;
-    if (done === nonEpic.length) return this.epicScope ? 'All epic issues are done' : 'All issues are done';
-    if (blocked > 0) return `${done}/${nonEpic.length} issues done, ${blocked} blocked by incomplete dependencies`;
-    return this.epicScope ? 'All epic issues are done or blocked' : 'All work is done or blocked';
-  }
-
-  /** Detect issues stuck in non-terminal states with no path to completion. */
-  private detectDeadState(issues: Issue[]): string | null {
-    const nonEpic = issues.filter(i => i.type !== 'epic');
-    const terminalStatuses = new Set(['done', 'cancelled']);
-    const stuck = nonEpic.filter(i => !terminalStatuses.has(i.status) && i.status !== 'todo');
-
-    if (stuck.length === 0) return null;
-
-    const stuckIds = stuck.map(i => `${i.id} (${i.status})`).join(', ');
-
-    const issueByPath = new Map(issues.map(i => [i.path, i]));
-    const blockedByStuck = nonEpic.filter(i => {
-      if (i.status !== 'todo') return false;
-      return i.blockedBy.some(bp => {
-        const blocker = issueByPath.get(bp);
-        return blocker && !terminalStatuses.has(blocker.status);
-      });
-    });
-    const blockedIds = blockedByStuck.map(i => i.id).join(', ');
-
-    return `Board stuck: ${stuckIds} cannot progress${blockedIds ? `. Blocking: ${blockedIds}` : ''}`;
-  }
-
-  private async revertIncompleteIssues(issues: Issue[]): Promise<void> {
-    const pmDir = this.pmDir;
-    if (!pmDir) return;
-    for (const issue of issues) {
-      const fullPath = this.validateIssuePath(issue.path, pmDir);
-      try {
-        const content = await readFile(fullPath, 'utf-8');
-        if (content.match(/^status:\s*in_progress$/m)) {
-          await this.updateIssueFrontMatter(issue.path, issue.status);
-        }
-      } catch (err) {
-        this.emit('output', { issueId: issue.id, text: `Warning: failed to revert issue status: ${err instanceof Error ? err.message : String(err)}`, boardId: this.boardId ?? null });
-      }
-    }
-  }
-
-  private async appendCancellationNote(issue: Issue, pmDir: string, reason: string): Promise<void> {
-    const fullPath = this.validateIssuePath(issue.path, pmDir);
-    try {
-      let content = await readFile(fullPath, 'utf-8');
-      const entry = `- Cancelled (${new Date().toISOString().split('T')[0]}): ${reason}`;
-      if (content.includes('## Activity')) {
-        content = content.replace(/## Activity/, `## Activity\n${entry}`);
-      } else {
-        content += `\n\n## Activity\n${entry}`;
-      }
-      await writeFile(fullPath, content, 'utf-8');
-    } catch (err) {
-      this.emit('output', { issueId: issue.id, text: `Warning: failed to append cancellation note: ${err instanceof Error ? err.message : String(err)}`, boardId: this.boardId ?? null });
-    }
-  }
-
-  private async updateIssueFrontMatter(issuePath: string, newStatus: string): Promise<void> {
-    const pmDir = this.pmDir;
-    if (!pmDir) return;
-    try {
-      const fullPath = this.validateIssuePath(issuePath, pmDir);
-      await setFrontMatterFieldAsync(fullPath, 'status', newStatus);
-
-      if (newStatus === 'done') {
-        const content = await readFile(fullPath, 'utf-8');
-        const updated = checkAllAcceptanceCriteria(content);
-        if (updated !== content) await writeFile(fullPath, updated, 'utf-8');
-      }
-    } catch (err) {
-      this.emit('output', { issueId: 'system', text: `Warning: failed to update issue front matter for ${issuePath}: ${err instanceof Error ? err.message : String(err)}`, boardId: this.boardId ?? null });
-    }
-  }
-
-  private async ensureOutputDirs(): Promise<void> {
-    if (this.boardDir) {
-      const boardOutDir = join(this.boardDir, 'out');
-      if (!existsSync(boardOutDir)) await mkdir(boardOutDir, { recursive: true });
-    } else {
-      const pmDir = this.pmDir;
-      if (pmDir) {
-        const outDir = join(pmDir, 'out');
-        if (!existsSync(outDir)) await mkdir(outDir, { recursive: true });
-      }
-    }
-  }
-
-  private async appendProgressEntry(issues: Issue[], waveStart: number): Promise<void> {
-    const pmDir = this.pmDir;
-    if (!pmDir) return;
-
-    const progressPath = this.boardDir
-      ? join(this.boardDir, 'progress.md')
-      : join(pmDir, 'progress.md');
-
-    const durationMin = Math.round((Date.now() - waveStart) / 60_000);
-    const timestamp = new Date().toISOString().replace('T', ' ').slice(0, 16);
-
-    const completed: string[] = [];
-    const failed: string[] = [];
-    for (const issue of issues) {
-      try {
-        const content = await readFile(this.validateIssuePath(issue.path, pmDir), 'utf-8');
-        const statusMatch = content.match(/^status:\s*(\S+)/m);
-        if (statusMatch?.[1] === 'done') {
-          completed.push(issue.id);
-        } else {
-          failed.push(issue.id);
-        }
-      } catch {
-        failed.push(issue.id);
-      }
-    }
-
-    const lines = [
-      '',
-      `## ${timestamp} — Wave [${issues.map(i => i.id).join(', ')}]`,
-      '',
-      `- **Duration**: ${durationMin} min`,
-      `- **Completed**: ${completed.length}/${issues.length}${completed.length > 0 ? ` (${completed.join(', ')})` : ''}`,
-    ];
-    if (failed.length > 0) {
-      lines.push(`- **Failed**: ${failed.join(', ')}`);
-    }
-    lines.push('');
-
-    await this.writeProgressLines(progressPath, lines);
-  }
-
-  private async writeProgressLines(filePath: string, lines: string[]): Promise<void> {
-    try {
-      if (existsSync(filePath)) {
-        await appendFile(filePath, `\n${lines.join('\n')}`, 'utf-8');
-      } else {
-        await writeFile(filePath, `# Board Progress\n${lines.join('\n')}`, 'utf-8');
-      }
-    } catch (err) {
-      this.emit('output', { issueId: 'system', text: `Warning: failed to write progress log: ${err instanceof Error ? err.message : String(err)}`, boardId: this.boardId ?? null });
-    }
-  }
-
-  /** Resolve the active board's directory path for outputs, reviews, and progress. */
-  private resolveBoardDir(): string | null {
-    const pmDir = this.pmDir;
-    if (!pmDir) return null;
-
-    const effectiveBoardId = this.boardId ?? this.resolveActiveBoardId();
-    if (!effectiveBoardId) return null;
-
-    const boardDir = join(pmDir, 'boards', effectiveBoardId);
-    return existsSync(boardDir) ? boardDir : null;
+  /**
+   * Load issues for the active execution scope. Returns the resolved boardId
+   * alongside the issues so callers can branch on board-specific logic without
+   * re-resolving the scope.
+   */
+  private async loadScopedIssues(pmDir: string): Promise<{ issues: Issue[] | null; boardId: string | null }> {
+    const boardId = this.effectiveBoardId();
+    const issues = boardId
+      ? await loadBoardIssues(pmDir, boardId, {
+          onError: msg => this.emit('error', msg),
+          warn: this.emitWarn,
+        })
+      : loadProjectIssues(this.workingDir, { onError: msg => this.emit('error', msg) });
+    return { issues, boardId };
   }
 }
+
+// Re-export for backwards compatibility with modules that imported the constant from here.
+export { DEFAULT_MAX_PARALLEL_AGENTS };