@hyperdrive.bot/bmad-workflow 1.0.17 → 1.0.19

package/dist/services/WorkflowReporter.js

@@ -0,0 +1,691 @@
+/**
+ * WorkflowReporter
+ *
+ * Real-time progress visualization for multi-layer parallel workflow execution
+ * using listr2. Implements the WorkflowCallbacks interface to observe workflow
+ * lifecycle events without coupling to orchestration internals.
+ *
+ * Features:
+ * - Top-level phase task groups with emoji-annotated titles
+ * - Nested concurrent task groups for parallel spawn layers
+ * - Live status updates for spawn transitions (queued → running → completed/failed)
+ * - Collapsible layer summaries on completion
+ */
+import Table from 'cli-table3';
+import { Listr } from 'listr2';
+import { formatBox, formatDuration } from '../utils/formatters.js';
+import { DEFAULT_TERMINAL_WIDTH, formatLayerSummary, formatPlainPhaseHeader, formatPlainSpawnMarker, formatPlainSummary, formatVerboseSpawnOutput, getPhaseActionVerb, getPhaseEmoji, isTTY, PHASE_TITLES, STATUS_INDICATORS, stripAnsi, truncateText, } from '../utils/listr2-helpers.js';
+/**
+ * WorkflowReporter provides real-time structured progress visualization
+ * of multi-layer parallel execution using listr2.
+ *
+ * Usage:
+ * ```typescript
+ * const reporter = new WorkflowReporter({ verbose: false })
+ * orchestrator.setCallbacks(reporter.getCallbacks())
+ * // ... workflow execution ...
+ * reporter.dispose()
+ * ```
+ */
+export class WorkflowReporter {
+    currentPhaseIndex = 0;
+    currentPhaseName = null;
+    disposed = false;
+    options;
+    // Phase tracking for display
+    phaseOrder = [];
+    phases = new Map();
+    // Listr2 instance management — one per active phase, chained transitions
+    listrInstance = null;
+    listrPromise = null;
+    phaseTransitionChain = Promise.resolve();
+    // Phase task resolver — resolves the phase-level listr2 task on phase complete
+    phaseTaskResolver = null;
+    // Phase task output updater — updates the spinner line with spawn progress
+    phaseTaskOutput = null;
+    // Phase task title updater — updates the spinner title dynamically
+    phaseTaskTitle = null;
+    // Which phase the current phaseTaskOutput/phaseTaskTitle closures belong to.
+    // Prevents cross-phase contamination in pipelined mode where story and dev overlap.
+    currentTaskPhase = null;
+    // Buffered values for title/output set before listr task is ready
+    pendingTitle = null;
+    pendingOutput = null;
+    // Live ticker — refreshes spawn lines with spinners + elapsed time
+    tickerInterval = null;
+    tickerFrame = 0;
+    static SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+    constructor(options = {}) {
+        // Auto-detect non-TTY mode if not explicitly set
+        const isNonTTY = options.nonTTY ?? !isTTY();
+        this.options = {
+            maxWidth: DEFAULT_TERMINAL_WIDTH,
+            noColor: false,
+            nonTTY: isNonTTY,
+            verbose: false,
+            ...options,
+            // Ensure nonTTY is set based on detection if not provided
+            ...(options.nonTTY === undefined ? { nonTTY: isNonTTY } : {}),
+        };
+    }
+    /**
+     * Display final boxed dashboard with workflow summary (AC: #4)
+     */
+    displayFinalDashboard(summary) {
+        if (this.options.nonTTY) {
+            this.displayPlainTextDashboard(summary);
+            return;
+        }
+        this.displayRichDashboard(summary);
+    }
+    /**
+     * Dispose of resources and clean up listr2 instance
+     */
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.stopTicker();
+        // Resolve any pending phase task to prevent hanging
+        if (this.phaseTaskResolver) {
+            this.phaseTaskResolver.resolve();
+            this.phaseTaskResolver = null;
+        }
+        this.phaseTaskOutput = null;
+        this.phaseTaskTitle = null;
+        this.currentTaskPhase = null;
+        this.pendingTitle = null;
+        this.pendingOutput = null;
+        // Clear state
+        this.phases.clear();
+        this.currentPhaseName = null;
+        this.listrInstance = null;
+        this.listrPromise = null;
+    }
+    /**
+     * Get the workflow callbacks interface for registering with orchestrator
+     */
+    getCallbacks() {
+        return {
+            onError: this.handleError.bind(this),
+            onLayerComplete: this.handleLayerComplete.bind(this),
+            onLayerStart: this.handleLayerStart.bind(this),
+            onPhaseComplete: this.handlePhaseComplete.bind(this),
+            onPhaseStart: this.handlePhaseStart.bind(this),
+            onSpawnComplete: this.handleSpawnComplete.bind(this),
+            onSpawnOutput: this.handleSpawnOutput.bind(this),
+            onSpawnStart: this.handleSpawnStart.bind(this),
+        };
+    }
+    /**
+     * Get the configured max width for output formatting
+     */
+    getMaxWidth() {
+        return this.options.maxWidth ?? DEFAULT_TERMINAL_WIDTH;
+    }
+    /**
+     * Check if reporter has been disposed
+     */
+    isDisposed() {
+        return this.disposed;
+    }
+    /**
+     * Check if reporter is in TTY mode
+     */
+    isTTYMode() {
+        return !this.options.nonTTY;
+    }
+    /**
+     * Check if reporter is in verbose mode
+     */
+    isVerboseMode() {
+        return this.options.verbose ?? false;
+    }
+    /**
+     * Wait for all listr2 tasks to complete (called after orchestrator finishes)
+     */
+    async waitForCompletion() {
+        // Wait for any pending phase transitions to finish
+        try {
+            await this.phaseTransitionChain;
+        }
+        catch { /* handled internally */ }
+        // Wait for the final listr instance to finish rendering
+        if (this.listrPromise) {
+            try {
+                await this.listrPromise;
+            }
+            catch { /* handled internally */ }
+        }
+    }
+    // ============================================================================
+    // Listr2 Phase Management
+    // ============================================================================
+    /**
+     * Clean up the current listr2 instance — resolve pending tasks and wait for
+     * the renderer to finish so the next phase gets a clean terminal.
+     */
+    async cleanupCurrentListr() {
+        this.stopTicker();
+        // Resolve the current phase task if still pending
+        if (this.phaseTaskResolver) {
+            this.phaseTaskResolver.resolve();
+            this.phaseTaskResolver = null;
+        }
+        this.phaseTaskOutput = null;
+        this.phaseTaskTitle = null;
+        this.currentTaskPhase = null;
+        // NOTE: Do NOT clear pendingTitle/pendingOutput here — they may have been
+        // set by handleSpawnStart between onPhaseStart and the promise chain resolving.
+        // They are consumed (and cleared) by the flush in createPhaseListr's task function.
+        // Wait for the listr run() promise to settle (renderer finishes)
+        if (this.listrPromise) {
+            try {
+                await this.listrPromise;
+            }
+            catch { /* errors tracked in state */ }
+        }
+        this.listrInstance = null;
+        this.listrPromise = null;
+    }
+    /**
+     * Create a new listr2 instance for a phase. The phase gets a single top-level
+     * task with a spinner. Spawn progress is piped as task output (shown below the
+     * spinner line). The task resolves when handlePhaseComplete fires.
+     *
+     * Phase transitions are chained: old instance is fully cleaned up before the
+     * new one starts rendering, preventing two renderers fighting over stdout.
+     */
+    createPhaseListr(phaseState) {
+        // Chain: cleanup old instance → create new instance
+        this.phaseTransitionChain = this.phaseTransitionChain
+            .then(() => this.cleanupCurrentListr())
+            .then(() => {
+            if (this.disposed)
+                return;
+            const phaseName = phaseState.phaseName;
+            const emoji = getPhaseEmoji(phaseName);
+            const title = PHASE_TITLES[phaseName] || `${phaseName} Phase`;
+            const phaseTitle = `${title} ${emoji}`;
+            this.listrInstance = new Listr([
+                {
+                    rendererOptions: {
+                        outputBar: 1,
+                        persistentOutput: false,
+                    },
+                    task: (_ctx, task) => new Promise((resolve, reject) => {
+                        this.phaseTaskResolver = { resolve, reject };
+                        this.phaseTaskOutput = (output) => {
+                            task.output = output;
+                        };
+                        this.phaseTaskTitle = (title) => {
+                            task.title = title;
+                        };
+                        this.currentTaskPhase = phaseName;
+                        // Flush any buffered title/output set before listr was ready
+                        if (this.pendingTitle) {
+                            task.title = this.pendingTitle;
+                            this.pendingTitle = null;
+                        }
+                        if (this.pendingOutput) {
+                            task.output = this.pendingOutput;
+                            this.pendingOutput = null;
+                        }
+                    }),
+                    title: phaseTitle,
+                },
+            ], {
+                concurrent: false,
+                exitOnError: false,
+                fallbackRendererCondition: () => this.options.nonTTY ?? false,
+                renderer: this.options.nonTTY ? 'simple' : 'default',
+                ...(this.options.nonTTY ? {} : {
+                    rendererOptions: {
+                        collapseErrors: false,
+                        collapseSubtasks: true,
+                        formatOutput: 'wrap',
+                        lazy: false,
+                        removeEmptyLines: false,
+                        showSubtasks: true,
+                        showTimer: false,
+                        suffixSkips: false,
+                    },
+                }),
+            });
+            // Run the listr (non-blocking — we chain via phaseTransitionChain)
+            this.listrPromise = this.listrInstance.run().catch(() => {
+                // Errors handled in state tracking
+            });
+        });
+    }
+    // ============================================================================
+    // Phase Banner
+    // ============================================================================
+    /**
+     * Display a phase banner. In verbose mode, shows a full formatBox banner.
+     * In non-verbose TTY mode, the listr2 spinner is the only display (no banner).
+     * In non-TTY mode, shows a plain-text header.
+     */
+    displayPhaseBanner(phaseName, itemCount) {
+        if (this.options.nonTTY) {
+            const header = formatPlainPhaseHeader(phaseName);
+            if (itemCount > 0) {
+                console.log('\n' + header);
+                console.log(`${getPhaseActionVerb(phaseName)} ${itemCount} ${itemCount === 1 ? 'item' : 'items'}`);
+            }
+            else {
+                console.log('\n' + header);
+            }
+            return;
+        }
+        // In verbose mode, show a full banner box
+        if (this.options.verbose) {
+            const emoji = getPhaseEmoji(phaseName);
+            const title = PHASE_TITLES[phaseName] || `${phaseName} Phase`;
+            const totalPhases = 4;
+            const phaseNumber = this.currentPhaseIndex;
+            const bannerTitle = `${emoji} ${title} (${phaseNumber}/${totalPhases})`;
+            const bannerContent = itemCount > 0
+                ? `${getPhaseActionVerb(phaseName)} ${itemCount} ${itemCount === 1 ? 'item' : 'items'}`
+                : '';
+            const banner = formatBox(bannerTitle, bannerContent);
+            console.log('\n' + banner);
+        }
+        // In non-verbose TTY mode: no banner — the listr2 spinner is enough
+    }
+    // ============================================================================
+    // Dashboard Display
+    // ============================================================================
+    displayPlainTextDashboard(summary) {
+        console.log('');
+        console.log(formatPlainSummary(summary.totalSpawns, summary.passedCount, summary.failedCount, summary.totalDuration));
+        if (summary.sessionReportPath) {
+            console.log('');
+            console.log('Session Report:');
+            console.log(summary.sessionReportPath);
+        }
+        console.log('');
+    }
+    displayRichDashboard(summary) {
+        const table = new Table({
+            chars: {
+                'bottom': '─', 'bottom-left': '└', 'bottom-mid': '┴', 'bottom-right': '┘',
+                'left': '│', 'left-mid': '├', 'mid': '─', 'mid-mid': '┼', 'middle': '│',
+                'right': '│', 'right-mid': '┤', 'top': '─', 'top-left': '┌', 'top-mid': '┬', 'top-right': '┐',
+            },
+            head: ['Phase', 'Passed', 'Failed', 'Duration'],
+            style: { border: ['gray'], head: ['cyan'] },
+        });
+        for (const phase of summary.phases) {
+            const emoji = getPhaseEmoji(phase.name);
+            const phaseName = `${emoji} ${PHASE_TITLES[phase.name] || phase.name}`;
+            const passedStr = phase.passed > 0 ? STATUS_INDICATORS.completed + ' ' + phase.passed : '0';
+            const failedStr = phase.failed > 0 ? STATUS_INDICATORS.failed + ' ' + phase.failed : '0';
+            const durationStr = formatDuration(phase.duration);
+            table.push([phaseName, passedStr, failedStr, durationStr]);
+        }
+        const totalPassedStr = summary.passedCount > 0
+            ? STATUS_INDICATORS.completed + ' ' + summary.passedCount : '0';
+        const totalFailedStr = summary.failedCount > 0
+            ? STATUS_INDICATORS.failed + ' ' + summary.failedCount : '0';
+        const totalDurationStr = formatDuration(summary.totalDuration);
+        table.push(['Total', totalPassedStr, totalFailedStr, totalDurationStr]);
+        const overallStatus = summary.failedCount === 0
+            ? STATUS_INDICATORS.completed + ' All spawns passed'
+            : STATUS_INDICATORS.failed + ` ${summary.failedCount} spawn(s) failed`;
+        // Print table and summary directly (no formatBox — ANSI codes break width calculation)
+        console.log('\n  Workflow Complete\n');
+        console.log(table.toString());
+        console.log('\n  ' + overallStatus);
+        if (summary.sessionReportPath) {
+            console.log(`\n  Session Report: ${summary.sessionReportPath}`);
+        }
+        console.log('');
+    }
+    // ============================================================================
+    // Phase Event Handlers
+    // ============================================================================
+    handlePhaseStart(context) {
+        if (this.disposed)
+            return;
+        const { itemCount, phaseName, startTime } = context;
+        const phaseKey = phaseName.toLowerCase();
+        // Track phase order for numbering
+        if (!this.phaseOrder.includes(phaseKey)) {
+            this.phaseOrder.push(phaseKey);
+        }
+        this.currentPhaseIndex = this.phaseOrder.indexOf(phaseKey) + 1;
+        // Create phase state
+        const phaseState = {
+            currentLayerIndex: -1,
+            failureCount: 0,
+            itemCount,
+            layers: new Map(),
+            phaseName: phaseKey,
+            startTime,
+            successCount: 0,
+        };
+        this.phases.set(phaseKey, phaseState);
+        this.currentPhaseName = phaseKey;
+        // Display phase banner
+        this.displayPhaseBanner(phaseKey, itemCount);
+        // Create listr2 spinner for this phase (chained after previous phase cleanup)
+        this.createPhaseListr(phaseState);
+    }
+    handlePhaseComplete(context) {
+        if (this.disposed)
+            return;
+        const { duration, failureCount, itemCount, phaseName, successCount } = context;
+        const phaseKey = phaseName.toLowerCase();
+        const phaseState = this.phases.get(phaseKey);
+        // Stop the live ticker
+        this.stopTicker();
+        if (phaseState) {
+            phaseState.successCount = successCount ?? 0;
+            phaseState.failureCount = failureCount ?? 0;
+            const emoji = getPhaseEmoji(phaseKey);
+            const title = PHASE_TITLES[phaseKey] || `${phaseKey} Phase`;
+            const durationStr = formatDuration(duration ?? 0);
+            const countStr = `${successCount ?? 0}/${itemCount}`;
+            const failNote = (failureCount ?? 0) > 0 ? ` (${failureCount} failed)` : '';
+            // Update the title to a clean one-liner summary (output lines disappear since persistentOutput=false)
+            // listr2's ✔/✖ already signals success/failure, so no custom icon needed
+            // Guard: only write to closures if they belong to THIS phase (prevents cross-phase contamination)
+            if (this.phaseTaskTitle && this.currentTaskPhase === phaseKey) {
+                this.phaseTaskTitle(`${title} ${emoji} ${countStr} (${durationStr})${failNote}`);
+            }
+            // Resolve the listr2 phase task — this completes the spinner with a checkmark
+            if (this.phaseTaskResolver) {
+                this.phaseTaskResolver.resolve();
+                this.phaseTaskResolver = null;
+            }
+        }
+        // Null out stale task references AFTER resolving — prevents late spawn callbacks
+        // from writing to a completed listr2 task whose renderer buffers are already cleaned up.
+        // Without this, listr2's OUTPUT event handler does buffer.output.get(task.id).write()
+        // on a cleared map → undefined.write() → TypeError.
+        // Only null if closures belong to this phase — another phase may have already claimed them.
+        if (this.currentTaskPhase === phaseKey) {
+            this.phaseTaskOutput = null;
+            this.phaseTaskTitle = null;
+            this.currentTaskPhase = null;
+        }
+        if (this.currentPhaseName === phaseKey) {
+            this.currentPhaseName = null;
+        }
+    }
+    // ============================================================================
+    // Layer Event Handlers
+    // ============================================================================
+    handleLayerStart(context) {
+        if (this.disposed)
+            return;
+        const { layerIndex, phaseName, spawnCount, startTime, totalLayers } = context;
+        const phaseKey = phaseName.toLowerCase();
+        const phaseState = this.phases.get(phaseKey);
+        if (!phaseState)
+            return;
+        const layerState = {
+            completedCount: 0,
+            failureCount: 0,
+            layerIndex,
+            spawnCount,
+            spawns: new Map(),
+            startTime,
+            successCount: 0,
+            totalLayers,
+        };
+        phaseState.layers.set(layerIndex, layerState);
+        phaseState.currentLayerIndex = layerIndex;
+    }
+    handleLayerComplete(context) {
+        if (this.disposed)
+            return;
+        const { duration, failureCount, layerIndex, phaseName, spawnCount, successCount } = context;
+        const phaseKey = phaseName.toLowerCase();
+        const phaseState = this.phases.get(phaseKey);
+        if (!phaseState)
+            return;
+        const layerState = phaseState.layers.get(layerIndex);
+        if (layerState) {
+            layerState.successCount = successCount ?? 0;
+            layerState.failureCount = failureCount ?? 0;
+        }
+        const layerResult = {
+            durationMs: duration ?? 0,
+            failureCount: failureCount ?? 0,
+            layerIndex,
+            spawnCount,
+            successCount: successCount ?? 0,
+        };
+        const summary = formatLayerSummary(layerResult);
+        const plainSummary = stripAnsi(summary);
+        // Update listr2 phase task with layer summary
+        // Guard: only write if closures belong to THIS phase
+        if (this.phaseTaskOutput && this.currentTaskPhase === phaseKey) {
+            this.phaseTaskOutput(plainSummary);
+        }
+        // Also log to console for non-TTY and verbose
+        if (this.options.nonTTY || this.options.verbose) {
+            console.log(plainSummary);
+        }
+    }
+    // ============================================================================
+    // Spawn Event Handlers
+    // ============================================================================
+    handleSpawnStart(context) {
+        if (this.disposed)
+            return;
+        const { agentType, itemId, itemTitle, phaseName, spawnId, startTime } = context;
+        const phaseKey = phaseName.toLowerCase();
+        const phaseState = this.phases.get(phaseKey);
+        if (!phaseState)
+            return;
+        // Auto-create a default layer if none exists (epic/story phases don't fire onLayerStart)
+        let layerState = phaseState.layers.get(phaseState.currentLayerIndex);
+        if (!layerState) {
+            layerState = {
+                completedCount: 0,
+                failureCount: 0,
+                layerIndex: 0,
+                spawnCount: 0,
+                spawns: new Map(),
+                startTime: Date.now(),
+                successCount: 0,
+                totalLayers: 1,
+            };
+            phaseState.layers.set(0, layerState);
+            phaseState.currentLayerIndex = 0;
+        }
+        // Track spawn state
+        const spawnState = {
+            agentType,
+            itemId,
+            itemTitle,
+            spawnId,
+            startTime,
+            status: 'running',
+        };
+        layerState.spawns.set(spawnId, spawnState);
+        // Render all spawn lines immediately
+        this.tickSpawns(phaseState);
+        // Start the live ticker if not already running (refreshes every 1s)
+        if (!this.tickerInterval) {
+            this.tickerInterval = setInterval(() => {
+                const currentPhase = this.currentPhaseName ? this.phases.get(this.currentPhaseName) : null;
+                if (currentPhase) {
+                    this.tickSpawns(currentPhase);
+                }
+            }, 1000);
+        }
+        // Log spawn start marker (only in verbose/nonTTY)
+        if (this.options.nonTTY || this.options.verbose) {
+            const marker = formatPlainSpawnMarker(itemId, 'STARTED');
+            console.log(marker);
+        }
+    }
+    /**
+     * Live-tick the phase title — rotates through running spawns with elapsed time.
+     * Called every 2s by the ticker interval AND once immediately on spawn start.
+     */
+    stopTicker() {
+        if (this.tickerInterval) {
+            clearInterval(this.tickerInterval);
+            this.tickerInterval = null;
+        }
+        this.tickerFrame = 0;
+    }
+    /**
+     * Build and render all spawn lines with per-item spinners + elapsed time.
+     * Called every second by the ticker interval AND once on spawn start/complete.
+     */
+    tickSpawns(phaseState) {
+        const phaseName = phaseState.phaseName;
+        const emoji = getPhaseEmoji(phaseName);
+        const title = PHASE_TITLES[phaseName] || `${phaseName} Phase`;
+        const actionVerb = getPhaseActionVerb(phaseName);
+        // Collect all spawns (running + recently completed)
+        const allSpawns = [];
+        let runningCount = 0;
+        for (const [, ls] of phaseState.layers) {
+            for (const [, ss] of ls.spawns) {
+                allSpawns.push(ss);
+                if (ss.status === 'running')
+                    runningCount++;
+            }
+        }
+        // Update phase title
+        const phaseTitle = runningCount > 1
+            ? `${title} ${emoji} ${actionVerb} ${runningCount} in parallel`
+            : runningCount === 1
+                ? `${title} ${emoji} ${actionVerb}...`
+                : `${title} ${emoji}`;
+        // Guard against listr2 renderer errors AND cross-phase contamination:
+        // 1. After a phase task resolves, listr2 cleans up its buffer map → TypeError.
+        // 2. In pipelined mode, a story callback could write to the dev phase's listr2 task.
+        // The currentTaskPhase check ensures closures only write to their owning phase.
+        try {
+            if (this.phaseTaskTitle && this.currentTaskPhase === phaseName) {
+                this.phaseTaskTitle(phaseTitle);
+            }
+            else {
+                this.pendingTitle = phaseTitle;
+            }
+        }
+        catch {
+            // listr2 renderer already cleaned up — buffer to pending instead
+            this.phaseTaskTitle = null;
+            this.pendingTitle = phaseTitle;
+        }
+        // Build per-item output lines
+        const frame = WorkflowReporter.SPINNER_FRAMES[this.tickerFrame % WorkflowReporter.SPINNER_FRAMES.length];
+        this.tickerFrame++;
+        const lines = allSpawns.map((ss) => {
+            const truncTitle = ss.itemTitle ? truncateText(ss.itemTitle, 50) : '...';
+            if (ss.status === 'running') {
+                const elapsed = formatDuration(Date.now() - ss.startTime);
+                return `${frame} ${ss.itemId} — ${truncTitle} (${elapsed})`;
+            }
+            else if (ss.status === 'completed') {
+                const elapsed = ss.endTime ? formatDuration(ss.endTime - ss.startTime) : '';
+                return `${STATUS_INDICATORS.completed} ${ss.itemId} — ${truncTitle}${elapsed ? ` (${elapsed})` : ''}`;
+            }
+            else {
+                const errMsg = ss.error ? truncateText(ss.error, 30) : 'failed';
+                return `${STATUS_INDICATORS.failed} ${ss.itemId} — ${errMsg}`;
+            }
+        });
+        const output = lines.join('\n');
+        try {
+            if (this.phaseTaskOutput && this.currentTaskPhase === phaseName) {
+                this.phaseTaskOutput(output);
+            }
+            else {
+                this.pendingOutput = output;
+            }
+        }
+        catch {
+            // listr2 renderer already cleaned up — buffer to pending instead
+            this.phaseTaskOutput = null;
+            this.pendingOutput = output;
+        }
+    }
+    handleSpawnComplete(context) {
+        if (this.disposed)
+            return;
+        const { agentType, duration, error, itemId, itemTitle, phaseName, spawnId, success } = context;
+        const phaseKey = phaseName.toLowerCase();
+        const phaseState = this.phases.get(phaseKey);
+        if (!phaseState)
+            return;
+        // Auto-create a default layer if none exists (epic/story phases don't fire onLayerStart)
+        let layerState = phaseState.layers.get(phaseState.currentLayerIndex);
+        if (!layerState) {
+            layerState = {
+                completedCount: 0,
+                failureCount: 0,
+                layerIndex: 0,
+                spawnCount: 0,
+                spawns: new Map(),
+                startTime: Date.now(),
+                successCount: 0,
+                totalLayers: 1,
+            };
+            phaseState.layers.set(0, layerState);
+            phaseState.currentLayerIndex = 0;
+        }
+        const spawnState = layerState.spawns.get(spawnId);
+        if (spawnState) {
+            spawnState.status = success ? 'completed' : 'failed';
+            spawnState.endTime = Date.now();
+            spawnState.error = error;
+        }
+        layerState.completedCount++;
+        if (success) {
+            layerState.successCount++;
+        }
+        else {
+            layerState.failureCount++;
+        }
+        // Re-render all spawn lines immediately (shows ✓/✗ for completed spawn)
+        this.tickSpawns(phaseState);
+        // Log spawn completion marker (only in verbose/nonTTY)
+        if (this.options.nonTTY || this.options.verbose) {
+            const completionStatus = success ? 'COMPLETED' : 'FAILED';
+            const completionMarker = formatPlainSpawnMarker(itemId, completionStatus, duration, error);
+            console.log(completionMarker);
+        }
+    }
+    handleSpawnOutput(context, output) {
+        if (this.disposed)
+            return;
+        if (!this.options.verbose)
+            return;
+        const { itemId, spawnId } = context;
+        const maxWidth = this.options.maxWidth ?? DEFAULT_TERMINAL_WIDTH;
+        if (this.options.nonTTY) {
+            const cleanOutput = stripAnsi(output);
+            const wrappedOutput = formatVerboseSpawnOutput(itemId || spawnId, cleanOutput, maxWidth);
+            console.log(wrappedOutput);
+        }
+        else {
+            const wrappedOutput = formatVerboseSpawnOutput(itemId || spawnId, output, maxWidth);
+            console.log(wrappedOutput);
+        }
+    }
+    // ============================================================================
+    // Error Handler
+    // ============================================================================
+    handleError(context) {
+        if (this.disposed)
+            return;
+        const { message, phaseName, recoverable, spawnId } = context;
+        const prefix = recoverable ? '[WARN]' : '[ERROR]';
+        const location = spawnId
+            ? `spawn:${spawnId}`
+            : phaseName
+                ? `phase:${phaseName}`
+                : 'workflow';
+        console.error(`${prefix} [${location}] ${message}`);
+    }
+}