@minionry/minion 0.7.36

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

@@ -0,0 +1,696 @@
+// Copyright (c) 2025-present Minionry, Inc.
+// SPDX-License-Identifier: LicenseRef-Minionry-Software
+import { EventEmitter } from 'node:events';
+import { readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { etaTargetKey, getEtaProfileCached } from '../../cli/eta-estimator.js';
+import { describeDispatchBlocker, engineAvailability } from '../../cli/headless/engine-availability.js';
+import { describeParkUntil } from '../../cli/headless/engine-notice.js';
+import { runWithFileLogger } from '../../cli/headless/headless-logger.js';
+import { resolveHistoryPaths } from '../../cli/improvisation-history-store.js';
+import { legacyThinkingChunk } from '../timeline/index.js';
+import { movementWrittenFiles } from '../websocket/movement-written-files.js';
+import { persistTranscriptSession } from '../websocket/session-history.js';
+import { DEFAULT_MAX_PARALLEL_AGENTS, getBoardMaxParallelAgents, getBoardQualityGate, resolveActiveBoardId, resolveBoardDir, resolveBoardWorktreePath, tryCompleteBoardIfDone, } from './board-config.js';
+import { ConfigInstaller } from './config-installer.js';
+import { resolveReadyToWork } from './dependency-resolver.js';
+import { loadBoardIssues, loadProjectIssues } from './issue-loader.js';
+import { buildIssuePrompt } from './issue-prompt-builder.js';
+import { runIssueWithRetry } from './issue-retry.js';
+import { appendCancellationNote, extractIssueStatus, recoverStaleIssues, revertIncompleteIssues, updateIssueFrontMatter, validateIssuePath, } from './issue-writer.js';
+import { listExistingDocs, publishOutputs, resolveOutputPath } from './output-manager.js';
+import { NO_SPECS_DIR_ERROR, resolvePmDir } from './parser.js';
+import { resolveIssueExecutionTarget, toExecutionTargetInfo } from './plan-runner-factory.js';
+import { appendProgressEntry, appendProgressNote, ensureOutputDirs } from './progress-log.js';
+import { captureQualityBaseline, computeQualityDelta, persistQualityDelta, qualityGateSkipReason, unavailableQualityDelta, WORKTREE_NOT_CHECKED_REASON, } from './quality-delta.js';
+import { buildCompletionReason, detectDeadState } from './readiness-planner.js';
+import { REVIEW_GATE_EFFORT_LEVEL, REVIEW_GATE_ENGINE, REVIEW_GATE_MODEL, runReviewPipeline, } from './review-gate.js';
+import { renderReviewResultMarkdown } from './review-report.js';
+import { reconcileState } from './state-reconciler.js';
+export const MAX_DISPATCHES_PER_ISSUE = 3;
+const PARK_POLL_MS = 5_000;
+function classifyIssueOutcome(result) {
+    if (result.engineNotice?.kind === 'limit')
+        return 'limit';
+    if (result.engineNotice?.kind === 'auth')
+        return 'auth';
+    if (result.completed && !result.error)
+        return 'completed';
+    if (result.error)
+        return 'error';
+    return 'incomplete';
+}
+const MAX_CONSECUTIVE_EMPTY_WAVES = 3;
+function reviewLine(issueId, status) {
+    switch (status) {
+        case 'reviewing': return `${issueId} implemented, reviewing.`;
+        case 'passed': return `${issueId} passed review.`;
+        case 'failed': return `${issueId} failed review, retrying.`;
+        case 'max_attempts': return `${issueId} failed review.`;
+    }
+}
+const ISSUE_STALL_WARNING_MS = 900_000;
+const ISSUE_STALL_KILL_MS = 1_800_000;
+const ISSUE_STALL_HARD_CAP_MS = 14_400_000;
+const ISSUE_STALL_MAX_EXTENSIONS = 10;
+export class PlanExecutor extends EventEmitter {
+    status = 'idle';
+    workingDir;
+    extraEnv;
+    shouldStop = false;
+    shouldPause = false;
+    waveAbortController = null;
+    context;
+    lastStartOptions = {};
+    configInstaller;
+    waveBrowserActivity = new Map();
+    aggregateSessionId = null;
+    waveTranscripts = [];
+    waveEtaProfiles = new Map();
+    waveQualityGate = 'advise';
+    waveQualityBaselines = new Map();
+    etaProfileFor(target) {
+        return this.waveEtaProfiles.get(etaTargetKey(target));
+    }
+    attemptLedger = new Map();
+    waveEngineBlock = null;
+    metrics = {
+        issuesCompleted: 0,
+        issuesAttempted: 0,
+        totalDuration: 0,
+        currentIssueId: null,
+        currentWaveIds: [],
+    };
+    constructor(workingDir, options) {
+        super();
+        this.workingDir = workingDir;
+        this.extraEnv = options?.extraEnv;
+        this.configInstaller = new ConfigInstaller(workingDir);
+        this.context = this.buildContext({});
+    }
+    getStatus() { return this.status; }
+    getMetrics() { return { ...this.metrics }; }
+    getExecutionSnapshot() {
+        return { status: this.status, boardId: this.context.boardId };
+    }
+    startEpic(epicPath) {
+        return this.runStart({ epic: epicPath });
+    }
+    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);
+        this.waveAbortController?.abort();
+    }
+    resume() {
+        this.shouldPause = false;
+        if (this.status !== 'paused')
+            return Promise.resolve();
+        return this.runStart(this.lastStartOptions);
+    }
+    async runStart(options) {
+        if (this.status === 'executing' || this.status === 'starting')
+            return;
+        this.lastStartOptions = options;
+        this.shouldStop = false;
+        this.shouldPause = false;
+        this.status = 'starting';
+        this.emit('statusChanged', this.status);
+        this.context = this.buildContext(options);
+        this.attemptLedger = new Map();
+        this.waveEngineBlock = null;
+        const startTime = Date.now();
+        this.aggregateSessionId = `improv-${startTime}-pm-${this.effectiveBoardId() ?? 'run'}`;
+        this.status = 'executing';
+        this.emit('statusChanged', this.status);
+        await this.runStaleRecovery();
+        const stallResult = await this.runWaveLoop();
+        this.metrics.totalDuration = Date.now() - startTime;
+        if (stallResult === 'stalled' || stallResult === 'dead' || stallResult === 'auth') {
+            this.status = 'error';
+            if (stallResult === 'stalled') {
+                this.emit('error', `Execution stalled: ${MAX_CONSECUTIVE_EMPTY_WAVES} consecutive waves completed zero issues. Issues may be stuck in review or failing repeatedly.`);
+            }
+        }
+        else if (this.shouldPause) {
+            this.status = 'paused';
+        }
+        else if (this.shouldStop) {
+            this.status = 'idle';
+            this.emit('complete', 'Stopped by user');
+        }
+        else {
+            this.status = 'complete';
+        }
+        this.emit('statusChanged', this.status);
+    }
+    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),
+        };
+    }
+    emitWarn = (message, issueId) => {
+        this.emit('output', { issueId: issueId ?? 'system', text: message, boardId: this.context.boardId ?? null });
+    };
+    narrate(text) {
+        this.emit('output', { issueId: 'system', text });
+    }
+    async setIssueStatus(issuePath, newStatus) {
+        const { pmDir } = this.context;
+        if (!pmDir)
+            return;
+        await updateIssueFrontMatter(pmDir, issuePath, newStatus, this.emitWarn);
+    }
+    async runWaveLoop() {
+        let consecutiveZeroCompletions = 0;
+        while (!this.shouldStop && !this.shouldPause) {
+            const gate = await this.waitOutEngineBlock();
+            if (gate === 'auth')
+                return 'auth';
+            if (gate === 'interrupted')
+                break;
+            const { ready, disposition } = await this.pickReadyIssues();
+            if (disposition !== 'work')
+                return disposition === 'dead' ? 'dead' : 'done';
+            if (ready.length === 0)
+                continue;
+            const maxParallel = await getBoardMaxParallelAgents(this.context.pmDir, this.effectiveBoardId(), this.emitWarn);
+            this.waveEngineBlock = null;
+            const completedCount = await this.executeWave(ready.slice(0, maxParallel));
+            if (completedCount > 0) {
+                consecutiveZeroCompletions = 0;
+                continue;
+            }
+            if (this.waveEngineBlock)
+                continue;
+            consecutiveZeroCompletions++;
+            if (consecutiveZeroCompletions >= MAX_CONSECUTIVE_EMPTY_WAVES)
+                return 'stalled';
+        }
+        return 'done';
+    }
+    async waitOutEngineBlock() {
+        const blocker = engineAvailability.automaticDispatchBlocker();
+        if (!blocker)
+            return 'proceed';
+        if (blocker.kind === 'auth') {
+            const message = `Execution stopped: ${describeDispatchBlocker(blocker)}.`;
+            this.narrate(message);
+            this.emit('error', message);
+            await appendProgressNote(this.context.pmDir, this.context.boardDir, `**Stopped** — ${describeDispatchBlocker(blocker)}`, this.emitWarn);
+            return 'auth';
+        }
+        return this.parkUntilReset(blocker);
+    }
+    async parkUntilReset(blocker) {
+        const until = blocker.until ?? Date.now() + PARK_POLL_MS;
+        this.narrate(`Usage limit reached — waves paused until ${describeParkUntil(until)}.`);
+        await appendProgressNote(this.context.pmDir, this.context.boardDir, `**Paused** until ${new Date(until).toISOString()} — ${blocker.notice.text.slice(0, 200)}`, this.emitWarn);
+        while (!this.shouldStop && !this.shouldPause) {
+            if (!engineAvailability.automaticDispatchBlocker()) {
+                this.narrate('Usage limit reset — resuming waves.');
+                await appendProgressNote(this.context.pmDir, this.context.boardDir, '**Resumed** after usage limit reset', this.emitWarn);
+                return 'proceed';
+            }
+            await new Promise((resolve) => setTimeout(resolve, PARK_POLL_MS));
+        }
+        return 'interrupted';
+    }
+    attemptsFor(issueId) {
+        return this.attemptLedger.get(issueId) ?? [];
+    }
+    recordAttempt(issueId, attempt) {
+        const attempts = this.attemptsFor(issueId);
+        attempts.push(attempt);
+        this.attemptLedger.set(issueId, attempts);
+    }
+    recordReviewOutcome(issueId, result) {
+        this.emit('output', { issueId, text: renderReviewResultMarkdown(result), phase: 'review' });
+        const attempts = this.attemptsFor(issueId);
+        const last = attempts[attempts.length - 1];
+        if (!last)
+            return;
+        const failures = result.checks.filter((c) => !c.passed).map((c) => ({ name: c.name, details: c.details }));
+        if (failures.length > 0)
+            last.reviewFailures = failures;
+    }
+    async escalateCappedIssue(issue) {
+        const { pmDir } = this.context;
+        const attempts = this.attemptsFor(issue.id).length;
+        const reason = `Dispatched ${attempts} times in this run without completing — automatic re-dispatch stopped; review its logs and output before running again`;
+        await this.setIssueStatus(issue.path, 'cancelled');
+        if (pmDir)
+            await appendCancellationNote(pmDir, issue, reason, this.emitWarn);
+        this.emit('issueAbandoned', { issueId: issue.id, reason, attempts });
+        this.emit('issueError', { issueId: issue.id, error: reason });
+        this.narrate(`${issue.id} abandoned after ${attempts} dispatches.`);
+        await appendProgressNote(this.context.pmDir, this.context.boardDir, `**${issue.id}** abandoned — ${reason}`, this.emitWarn);
+    }
+    effectiveBoardId() {
+        return this.context.boardId ?? resolveActiveBoardId(this.context.pmDir);
+    }
+    async executeWave(issues) {
+        if (this.shouldStop)
+            return 0;
+        const waveStart = Date.now();
+        const waveIds = issues.map(i => i.id);
+        const waveLabel = `wave[${waveIds.join(',')}]`;
+        this.metrics.currentWaveIds = waveIds;
+        this.metrics.issuesAttempted += issues.length;
+        this.waveBrowserActivity = new Map();
+        this.waveTranscripts = [];
+        this.waveQualityBaselines = new Map();
+        this.waveQualityGate = await getBoardQualityGate(this.context.pmDir, this.effectiveBoardId(), this.emitWarn);
+        this.emit('waveStarted', { issueIds: waveIds });
+        this.waveAbortController = new AbortController();
+        const historyDir = resolveHistoryPaths(this.workingDir, '').improviseDir;
+        const waveTargets = new Map();
+        for (const issue of issues) {
+            const t = resolveIssueExecutionTarget(issue);
+            const target = { engine: t.engineId, model: t.model, fastMode: t.fastMode };
+            waveTargets.set(etaTargetKey(target), target);
+        }
+        const reviewTarget = { engine: REVIEW_GATE_ENGINE, model: REVIEW_GATE_MODEL };
+        waveTargets.set(etaTargetKey(reviewTarget), reviewTarget);
+        this.waveEtaProfiles = new Map();
+        await Promise.all([...waveTargets].map(async ([key, target]) => {
+            const profile = await getEtaProfileCached(historyDir, target).catch(() => null);
+            if (profile)
+                this.waveEtaProfiles.set(key, profile);
+        }));
+        await ensureOutputDirs(this.context.pmDir, this.context.boardDir);
+        this.configInstaller.installPermissions();
+        for (const issue of issues) {
+            await this.setIssueStatus(issue.path, 'in_progress');
+        }
+        const existingDocs = listExistingDocs(this.workingDir, this.context.boardDir);
+        const { pmDir } = this.context;
+        let completedCount = 0;
+        try {
+            const abortSignal = this.waveAbortController?.signal;
+            const runnerPromises = issues.map(issue => this.runSingleIssue(issue, pmDir, existingDocs, waveLabel, abortSignal));
+            const results = await Promise.allSettled(runnerPromises);
+            for (let i = 0; i < results.length; i++) {
+                const result = results[i];
+                if (result.status === 'rejected') {
+                    this.emit('issueError', {
+                        issueId: issues[i].id,
+                        error: result.reason instanceof Error ? result.reason.message : String(result.reason),
+                    });
+                }
+            }
+            completedCount = await this.reconcileWaveResults(issues, abortSignal);
+        }
+        catch (error) {
+            this.emit('waveError', {
+                issueIds: waveIds,
+                error: error instanceof Error ? error.message : String(error),
+            });
+            if (pmDir)
+                await revertIncompleteIssues(pmDir, issues, this.emitWarn);
+        }
+        finally {
+            this.configInstaller.uninstallPermissions();
+        }
+        this.waveAbortController = null;
+        await this.finalizeWave(issues, waveStart, waveLabel);
+        this.metrics.currentWaveIds = [];
+        return completedCount;
+    }
+    async runSingleIssue(issue, pmDir, existingDocs, waveLabel, abortSignal) {
+        const { executionDir, boardDir, workingDir } = this.context;
+        const effectiveDir = executionDir || workingDir;
+        const outputPath = resolveOutputPath(issue, workingDir, boardDir);
+        const previousAttempts = this.attemptsFor(issue.id);
+        const prompt = buildIssuePrompt({
+            issue,
+            workingDir: effectiveDir,
+            pmDir,
+            boardDir,
+            existingDocs,
+            outputPath,
+            ...(previousAttempts.length > 0 ? { previousAttempts } : {}),
+            qualityGate: this.waveQualityGate,
+        });
+        const target = resolveIssueExecutionTarget(issue);
+        this.emit('issueStarted', issue);
+        const issueEtaProfile = this.etaProfileFor({ engine: target.engineId, model: target.model, fastMode: target.fastMode });
+        this.emit('issuePrompt', {
+            issueId: issue.id,
+            prompt,
+            executionTarget: toExecutionTargetInfo(target),
+            ...(issueEtaProfile ? { etaProfile: issueEtaProfile } : {}),
+        });
+        const boardLogDir = boardDir ? join(boardDir, 'logs') : undefined;
+        const emitOutput = (text) => this.emit('output', { issueId: issue.id, text });
+        const qualityBaseline = await this.captureQualityBaseline(issue, emitOutput, abortSignal);
+        const execStart = Date.now();
+        const result = await runWithFileLogger(`pm-issue-${issue.id}`, () => runIssueWithRetry({
+            workingDir: effectiveDir,
+            prompt,
+            tabId: `${this.context.boardId ?? 'pm'}::${issue.id}`,
+            engineId: target.engineId,
+            model: target.model,
+            effortLevel: target.effortLevel,
+            fastMode: target.fastMode,
+            stallWarningMs: ISSUE_STALL_WARNING_MS,
+            stallKillMs: ISSUE_STALL_KILL_MS,
+            stallHardCapMs: ISSUE_STALL_HARD_CAP_MS,
+            stallMaxExtensions: ISSUE_STALL_MAX_EXTENSIONS,
+            outputCallback: emitOutput,
+            thinkingCallback: (text) => emitOutput(legacyThinkingChunk(text)),
+            toolUseCallback: (event) => {
+                this.emit('toolUse', { issueId: issue.id, event });
+                this.recordBrowserToolUse(issue.id, event);
+            },
+            tokenUsageCallback: (usage) => {
+                this.emit('tokenUsage', { issueId: issue.id, usage });
+            },
+            extraEnv: this.extraEnv,
+            abortSignal,
+            ...(pmDir ? {
+                appendHistory: {
+                    pmDir,
+                    issuePath: issue.path,
+                    issueId: issue.id,
+                    issueTitle: issue.title,
+                    execStart,
+                },
+            } : {}),
+        }), boardLogDir);
+        this.persistIssueTranscript(issue, prompt, result, execStart, target);
+        this.waveTranscripts.push({ issueId: issue.id, title: issue.title, prompt, result, execStart, fastMode: issue.fastMode ?? undefined, engine: target.engineId, model: target.model });
+        this.recordDispatch(issue, result, execStart, outputPath);
+        if (qualityBaseline) {
+            this.waveQualityBaselines.set(issue.id, { baseline: qualityBaseline, writtenFiles: movementWrittenFiles(result) });
+        }
+        if (!result.completed || result.error) {
+            this.emit('output', { issueId: waveLabel, text: `Issue ${issue.id}: ${result.error || 'did not complete'}` });
+        }
+    }
+    persistIssueTranscript(issue, prompt, result, execStart, target) {
+        const transcriptSessionId = `improv-${execStart}-pm-${issue.id}`;
+        const transcriptPath = persistTranscriptSession(this.context.workingDir, {
+            sessionId: transcriptSessionId,
+            userPrompt: prompt,
+            result,
+            execStart,
+            fastMode: issue.fastMode ?? undefined,
+            engine: target.engineId,
+            model: target.model,
+        });
+        if (transcriptPath) {
+            this.emit('issueTranscript', {
+                issueId: issue.id,
+                tabId: `${this.context.boardId ?? 'pm'}::${issue.id}`,
+                sessionId: transcriptSessionId,
+            });
+        }
+    }
+    recordDispatch(issue, result, execStart, outputPath) {
+        const outcome = classifyIssueOutcome(result);
+        this.recordAttempt(issue.id, {
+            startedAt: execStart,
+            durationMs: Date.now() - execStart,
+            outcome,
+            ...(result.error ? { error: result.error } : {}),
+            ...(result.assistantResponse ? { tail: result.assistantResponse.slice(-800) } : {}),
+            ...(result.toolUseHistory?.length ? { toolNames: Array.from(new Set(result.toolUseHistory.map((t) => t.toolName))) } : {}),
+            outFile: outputPath,
+        });
+        if (outcome === 'limit' || outcome === 'auth') {
+            this.waveEngineBlock = outcome;
+        }
+    }
+    recordBrowserToolUse(issueId, event) {
+        if (event.type !== 'tool_start' && event.type !== 'tool_complete')
+            return;
+        const name = event.toolName ?? '';
+        const isBrowserTool = name.startsWith('browser_') ||
+            name.startsWith('minionry-browser__browser_') ||
+            name.startsWith('mcp__minionry-browser__browser_');
+        if (!isBrowserTool)
+            return;
+        const entry = this.waveBrowserActivity.get(issueId) ?? { issueId, calls: 0, tools: [] };
+        entry.calls += 1;
+        if (!entry.tools.includes(name))
+            entry.tools.push(name);
+        if (event.type === 'tool_start' && event.completeInput) {
+            const url = event.completeInput.url;
+            if (typeof url === 'string' && url.length > 0) {
+                entry.finalUrl = url;
+            }
+        }
+        this.waveBrowserActivity.set(issueId, entry);
+    }
+    async finalizeWave(issues, waveStart, waveLabel) {
+        const { pmDir, boardDir, boardId } = this.context;
+        try {
+            reconcileState(this.workingDir, boardId ?? undefined);
+            this.emit('stateUpdated');
+        }
+        catch (err) {
+            this.emit('output', {
+                issueId: waveLabel,
+                text: `Warning: state reconciliation failed: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+        try {
+            publishOutputs(issues, this.workingDir, boardDir, {
+                onWarning: (issueId, text) => this.emit('output', { issueId, text: `Warning: ${text}` }),
+            });
+        }
+        catch (err) {
+            this.emit('output', {
+                issueId: waveLabel,
+                text: `Warning: output publishing failed: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+        try {
+            const browserActivity = new Map(this.waveBrowserActivity);
+            await appendProgressEntry(pmDir, boardDir, issues, waveStart, this.emitWarn, browserActivity);
+        }
+        catch (err) {
+            this.emit('output', {
+                issueId: waveLabel,
+                text: `Warning: progress log update failed: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+        this.persistAggregateTranscripts(waveLabel);
+    }
+    persistAggregateTranscripts(waveLabel) {
+        if (!this.aggregateSessionId)
+            return;
+        try {
+            for (const t of this.waveTranscripts) {
+                persistTranscriptSession(this.workingDir, {
+                    sessionId: this.aggregateSessionId,
+                    userPrompt: t.prompt,
+                    result: t.result,
+                    execStart: t.execStart,
+                    fastMode: t.fastMode,
+                    engine: t.engine,
+                    model: t.model,
+                });
+            }
+        }
+        catch (err) {
+            this.emit('output', {
+                issueId: waveLabel,
+                text: `Warning: aggregate history persistence failed: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+    }
+    async reconcileWaveResults(issues, abortSignal) {
+        const { pmDir } = this.context;
+        if (!pmDir)
+            return 0;
+        let completed = 0;
+        for (const issue of issues) {
+            if (this.shouldStop)
+                break;
+            const fullPath = validateIssuePath(issue.path, pmDir);
+            try {
+                const content = await readFile(fullPath, 'utf-8');
+                const currentStatus = extractIssueStatus(content) ?? 'unknown';
+                if (currentStatus === 'in_review' || currentStatus === 'done') {
+                    if (await this.finalizeCompletedIssue(issue, pmDir, abortSignal))
+                        completed++;
+                }
+                else {
+                    await this.setIssueStatus(issue.path, issue.status);
+                    this.emit('issueError', {
+                        issueId: issue.id,
+                        error: 'Issue did not complete during wave execution',
+                    });
+                }
+            }
+            catch {
+                this.emit('issueError', { issueId: issue.id, error: 'Could not read issue file after wave' });
+            }
+        }
+        return completed;
+    }
+    async finalizeCompletedIssue(issue, pmDir, abortSignal) {
+        if (issue.reviewGate === 'none') {
+            await this.setIssueStatus(issue.path, 'done');
+            this.metrics.issuesCompleted++;
+            this.emit('issueCompleted', issue);
+            this.narrate(`${issue.id} done.`);
+            return true;
+        }
+        const qualityDelta = await this.recordQualityDelta(issue);
+        const passed = await runReviewPipeline({
+            issue,
+            pmDir,
+            workingDir: this.workingDir,
+            executionDir: this.context.executionDir,
+            boardDir: this.context.boardDir,
+            extraEnv: this.extraEnv,
+            abortSignal,
+            qualityDelta,
+        }, {
+            setStatus: (path, status) => this.setIssueStatus(path, status),
+            onReviewPrompt: (issueId, prompt) => {
+                const reviewEtaProfile = this.etaProfileFor({ engine: REVIEW_GATE_ENGINE, model: REVIEW_GATE_MODEL });
+                this.emit('issuePrompt', {
+                    issueId,
+                    prompt,
+                    phase: 'review',
+                    executionTarget: { engine: REVIEW_GATE_ENGINE, model: REVIEW_GATE_MODEL, effortLevel: REVIEW_GATE_EFFORT_LEVEL },
+                    ...(reviewEtaProfile ? { etaProfile: reviewEtaProfile } : {}),
+                });
+            },
+            onOutput: (issueId, text) => this.emit('output', { issueId, text, phase: 'review' }),
+            onReviewProgress: (issueId, status) => { this.emit('reviewProgress', { issueId, status }); this.narrate(reviewLine(issueId, status)); },
+            onIssueAbandoned: (issueId, reason, attempts) => { this.emit('issueAbandoned', { issueId, reason, attempts }); this.narrate(`${issueId} abandoned after ${attempts} attempt${attempts === 1 ? '' : 's'}.`); },
+            onIssueCompleted: (completedIssue) => this.emit('issueCompleted', completedIssue),
+            onIssueError: (issueId, error) => this.emit('issueError', { issueId, error, phase: 'review' }),
+            onReviewResult: (issueId, result) => this.recordReviewOutcome(issueId, result),
+            warn: this.emitWarn,
+        });
+        if (passed)
+            this.metrics.issuesCompleted++;
+        return passed;
+    }
+    runsInWorktree() {
+        const { executionDir, pmDir } = this.context;
+        if (!executionDir)
+            return false;
+        const worktree = resolveBoardWorktreePath(pmDir, this.effectiveBoardId());
+        return worktree !== null && resolve(worktree) === resolve(executionDir);
+    }
+    async captureQualityBaseline(issue, emitOutput, abortSignal) {
+        if (qualityGateSkipReason(issue, this.waveQualityGate) !== null)
+            return null;
+        if (this.runsInWorktree())
+            return { available: false, reason: WORKTREE_NOT_CHECKED_REASON };
+        const outcome = await captureQualityBaseline({ spaceRoot: this.workingDir, signal: abortSignal }, issue);
+        if (outcome.available) {
+            const { fingerprints, checked, unchecked } = outcome.baseline;
+            const skipped = unchecked.length > 0 ? `, ${unchecked.length} unchecked` : '';
+            emitOutput(`Quality baseline: ${fingerprints.length} active finding(s) in ${checked.length} file(s)${skipped}.\n`);
+        }
+        else {
+            emitOutput(`Quality baseline unavailable: ${outcome.reason}\n`);
+        }
+        return outcome;
+    }
+    async recordQualityDelta(issue) {
+        const gate = this.waveQualityGate;
+        if (gate === 'off' || qualityGateSkipReason(issue, gate) !== null)
+            return null;
+        const { boardDir } = this.context;
+        if (!boardDir)
+            return null;
+        const kept = this.waveQualityBaselines.get(issue.id);
+        const record = this.runsInWorktree()
+            ? unavailableQualityDelta(issue.id, gate, WORKTREE_NOT_CHECKED_REASON)
+            : await computeQualityDelta({ spaceRoot: this.workingDir }, {
+                issue,
+                gate,
+                baseline: kept?.baseline ?? { available: false, reason: 'no baseline was captured before this issue ran' },
+                writtenFiles: kept?.writtenFiles ?? [],
+            });
+        try {
+            persistQualityDelta(boardDir, record);
+        }
+        catch (err) {
+            this.emitWarn(`Warning: failed to persist quality delta for ${issue.id}: ${err instanceof Error ? err.message : String(err)}`, issue.id);
+        }
+        const line = record.available
+            ? `Quality delta: ${record.introducedCount} introduced finding(s) in ${record.checked.length} file(s)${record.unchecked.length > 0 ? `, ${record.unchecked.length} unchecked` : ''}.\n`
+            : `Quality delta unavailable: ${record.reason}\n`;
+        this.emit('output', { issueId: issue.id, text: line });
+        return record;
+    }
+    async runStaleRecovery() {
+        const { pmDir } = this.context;
+        if (!pmDir)
+            return;
+        const { issues } = await this.loadScopedIssues(pmDir);
+        if (!issues)
+            return;
+        const recovered = await recoverStaleIssues(pmDir, issues, this.emitWarn);
+        if (recovered.length > 0) {
+            this.emit('output', {
+                issueId: 'recovery',
+                text: `Recovered ${recovered.length} issue${recovered.length > 1 ? 's' : ''} from previous interrupted execution: ${recovered.join(', ')}`,
+            });
+            this.emit('stateUpdated');
+        }
+    }
+    async pickReadyIssues() {
+        const { pmDir, epicScope } = this.context;
+        if (!pmDir) {
+            this.emit('error', NO_SPECS_DIR_ERROR);
+            return { ready: [], disposition: 'dead' };
+        }
+        const { issues, boardId } = await this.loadScopedIssues(pmDir);
+        if (!issues)
+            return { ready: [], disposition: 'dead' };
+        const readyAll = resolveReadyToWork(issues, epicScope ?? undefined);
+        const capped = readyAll.filter((i) => this.attemptsFor(i.id).length >= MAX_DISPATCHES_PER_ISSUE);
+        for (const issue of capped)
+            await this.escalateCappedIssue(issue);
+        const ready = readyAll.filter((i) => !capped.includes(i));
+        if (readyAll.length > 0)
+            return { ready, disposition: 'work' };
+        const deadState = detectDeadState(issues);
+        if (deadState) {
+            this.emit('error', deadState);
+            return { ready: [], disposition: 'dead' };
+        }
+        this.emit('complete', buildCompletionReason(issues, epicScope));
+        if (boardId) {
+            await tryCompleteBoardIfDone(pmDir, boardId, issues, this.emitWarn);
+        }
+        return { ready: [], disposition: 'done' };
+    }
+    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 };
+    }
+}
+export { DEFAULT_MAX_PARALLEL_AGENTS };