mstro-app 0.4.52 → 0.5.0

package/dist/server/services/plan/executor.js

@@ -8,56 +8,51 @@
  * 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, } 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';
-/** 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;
 /** 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 class PlanExecutor extends EventEmitter {
     status = 'idle';
     workingDir;
+    extraEnv;
     shouldStop = false;
     shouldPause = false;
     /** AbortController for killing running HeadlessRunner processes on stop. */
     waveAbortController = null;
-    epicScope = null;
-    /** Cached PM directory path — resolved once per start(). */
-    pmDir = null;
-    /** Board directory path (e.g. /path/.mstro/pm/boards/BOARD-001). Used for outputs, reviews, progress. */
-    boardDir = null;
-    /** Board ID being executed (e.g. "BOARD-001") */
-    boardId = null;
+    /** Resolved context for the current/last run — rebuilt each runStart(). */
+    context;
+    /** Options from the last run; replayed on resume() to preserve scope. */
+    lastStartOptions = {};
     configInstaller;
-    /** Flag to prevent start() from clearing scope set by startBoard/startEpic */
-    _scopeSetByCall = false;
-    /** Extra environment variables forwarded to HeadlessRunner child processes (e.g. API keys) */
-    extraEnv;
-    /** Optional worktree directory for running AI agents. PM data is always read from workingDir. */
-    executionDir = null;
     metrics = {
         issuesCompleted: 0,
         issuesAttempted: 0,
@@ -70,50 +65,49 @@ export class PlanExecutor extends EventEmitter {
         this.workingDir = workingDir;
         this.extraEnv = options?.extraEnv;
         this.configInstaller = new ConfigInstaller(workingDir);
-    }
-    validateIssuePath(issuePath, baseDir) {
-        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() { return this.status; }
     getMetrics() { return { ...this.metrics }; }
-    async startEpic(epicPath) {
-        this.epicScope = epicPath;
-        this._scopeSetByCall = true;
-        return this.start();
+    startEpic(epicPath) {
+        return this.runStart({ epic: epicPath });
     }
     /** Start execution, optionally scoped to a specific board. */
-    async startBoard(boardId, executionDir) {
-        this.boardId = boardId;
-        this.executionDir = executionDir ?? null;
-        this._scopeSetByCall = true;
-        return this.start();
+    startBoard(boardId, executionDir) {
+        return this.runStart({ board: boardId, executionDir });
+    }
+    start(options = {}) {
+        return this.runStart(options);
+    }
+    pause() { this.shouldPause = true; }
+    stop() {
+        this.shouldStop = true;
+        this.status = 'stopping';
+        this.emit('statusChanged', this.status);
+        // Kill all running HeadlessRunner processes in the current wave
+        this.waveAbortController?.abort();
+    }
+    resume() {
+        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);
     }
-    async start() {
+    // ── Run orchestration ────────────────────────────────────────
+    async runStart(options) {
         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;
         if (stallResult === 'stalled' || stallResult === 'dead') {
@@ -135,10 +129,39 @@ export class PlanExecutor extends EventEmitter {
         }
         this.emit('statusChanged', this.status);
     }
+    /** Build an immutable execution context from start options. */
+    buildContext(options) {
+        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.
+     */
+    emitWarn = (message, issueId) => {
+        this.emit('output', { issueId: issueId ?? 'system', text: message, boardId: this.context.boardId ?? null });
+    };
+    async setIssueStatus(issuePath, newStatus) {
+        const { pmDir } = this.context;
+        if (!pmDir)
+            return;
+        await updateIssueFrontMatter(pmDir, issuePath, newStatus, this.emitWarn);
+    }
+    // ── Wave loop ────────────────────────────────────────────────
     /** Run waves until done, paused, stopped, or stalled. */
     async runWaveLoop() {
         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();
             if (readyIssues.length === 0) {
@@ -156,34 +179,15 @@ export class PlanExecutor extends EventEmitter {
         }
         return 'done';
     }
+    effectiveBoardId() {
+        return this.context.boardId ?? resolveActiveBoardId(this.context.pmDir);
+    }
     async hasDeadIssues() {
-        const pmDir = this.pmDir;
+        const { pmDir } = this.context;
         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() { this.shouldPause = true; }
-    stop() {
-        this.shouldStop = true;
-        this.status = 'stopping';
-        this.emit('statusChanged', this.status);
-        // Kill all running HeadlessRunner processes in the current wave
-        this.waveAbortController?.abort();
-    }
-    resume() {
-        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();
+        const { issues } = await this.loadScopedIssues(pmDir);
+        return issues ? hasBlockedIssues(issues) : false;
     }
     // ── Wave execution ───────────────────────────────────────────
     async executeWave(issues) {
@@ -195,13 +199,13 @@ export class PlanExecutor extends EventEmitter {
         this.emit('waveStarted', { issueIds: waveIds });
         // 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;
         try {
             // Spawn one HeadlessRunner per issue in parallel
@@ -225,7 +229,8 @@ 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();
@@ -237,17 +242,18 @@ export class PlanExecutor extends EventEmitter {
     }
     /** Run a single issue via its own headless Claude Code instance with retry logic. */
     async runSingleIssue(issue, pmDir, existingDocs, waveLabel, abortSignal) {
-        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 result = await runWithFileLogger(`pm-issue-${issue.id}`, () => runIssueWithRetry({
             workingDir: effectiveDir,
             prompt,
@@ -270,8 +276,9 @@ export class PlanExecutor extends EventEmitter {
      * doesn't prevent the others or kill the while loop in start().
      */
     async finalizeWave(issues, waveStart, waveLabel) {
+        const { pmDir, boardDir, boardId } = this.context;
         try {
-            reconcileState(this.workingDir, this.boardId ?? undefined);
+            reconcileState(this.workingDir, boardId ?? undefined);
             this.emit('stateUpdated');
         }
         catch (err) {
@@ -281,7 +288,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}` }),
             });
         }
@@ -292,7 +299,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', {
@@ -308,30 +315,21 @@ export class PlanExecutor extends EventEmitter {
      * and either confirmed `done` (passed) or reverted to `todo` (failed).
      */
     async reconcileWaveResults(issues) {
-        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);
+                    if (await this.finalizeCompletedIssue(issue, pmDir))
                         completed++;
-                    }
-                    else {
-                        completed += await this.runReviewGate(issue, pmDir);
-                    }
                 }
                 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',
@@ -344,52 +342,38 @@ 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. */
-    async runReviewGate(issue, pmDir) {
-        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;
+    /**
+     * 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).
+     */
+    async finalizeCompletedIssue(issue, pmDir) {
+        if (issue.reviewGate === 'none') {
+            await this.setIssueStatus(issue.path, 'done');
+            this.metrics.issuesCompleted++;
+            this.emit('issueCompleted', issue);
+            return true;
         }
-        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,
+        const passed = await runReviewPipeline({
             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,
+            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,
         });
-        persistReviewResult(reviewDir, issue, result);
-        if (result.passed) {
-            await this.updateIssueFrontMatter(issue.path, 'done');
+        if (passed)
             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 passed;
     }
     // ── Recovery ─────────────────────────────────────────────────
     /**
@@ -398,26 +382,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.
      */
-    async recoverStaleIssues() {
-        const pmDir = this.pmDir;
+    async runStaleRecovery() {
+        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 = [];
-        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',
@@ -426,317 +398,47 @@ export class PlanExecutor extends EventEmitter {
             this.emit('stateUpdated');
         }
     }
-    // ── Helpers ──────────────────────────────────────────────────
-    /** Read the board's maxParallelAgents setting, falling back to default. */
-    async getBoardMaxParallelAgents() {
-        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. */
-    async getBoardReviewCriteria() {
-        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 ────────────────────────────────
     async pickReadyIssues() {
-        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. */
-    async loadBoardIssues(pmDir, boardId) {
-        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. */
-    loadProjectIssues() {
-        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. */
-    async activateBoard(pmDir, boardId) {
-        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. */
-    async tryCompleteBoardIfDone(pmDir, boardId, issues) {
-        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 });
-        }
-    }
-    resolveActiveBoardId() {
-        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;
-        }
-    }
-    buildCompletionReason(issues) {
-        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. */
-    detectDeadState(issues) {
-        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}` : ''}`;
-    }
-    async revertIncompleteIssues(issues) {
-        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 });
-            }
-        }
-    }
-    async appendCancellationNote(issue, pmDir, reason) {
-        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 });
-        }
-    }
-    async updateIssueFrontMatter(issuePath, newStatus) {
-        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 });
-        }
-    }
-    async ensureOutputDirs() {
-        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 });
-            }
-        }
-    }
-    async appendProgressEntry(issues, waveStart) {
-        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 = [];
-        const failed = [];
-        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);
-    }
-    async writeProgressLines(filePath, lines) {
-        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. */
-    resolveBoardDir() {
-        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.
+     */
+    async loadScopedIssues(pmDir) {
+        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 };
 //# sourceMappingURL=executor.js.map