wiggum-cli 0.16.0 → 0.17.0

package/dist/tui/utils/build-run-summary.js

@@ -3,86 +3,10 @@
  */
 import { existsSync, readFileSync } from 'node:fs';
 import { logger } from '../../utils/logger.js';
+import { execFileSync } from 'node:child_process';
 import { getCurrentCommitHash, getDiffStats, getCommitList } from './git-summary.js';
 import { getPrForBranch, getLinkedIssue } from './pr-summary.js';
-/**
- * Phase ID to human-readable label mapping
- */
-const PHASE_LABELS = {
-    planning: 'Planning',
-    implementation: 'Implementation',
-    e2e_testing: 'E2E Testing',
-    verification: 'Verification',
-    pr_review: 'PR & Review',
-};
-const VALID_PHASE_STATUSES = new Set(['success', 'skipped', 'failed']);
-/**
- * Parse phase information from the phases file written by feature-loop.sh.
- *
- * Format: phase_id|status|start_timestamp|end_timestamp
- * The parser handles duplicate phase entries defensively (last status wins,
- * durations aggregate), though feature-loop.sh normally writes one final
- * line per phase.
- *
- * @param phasesFilePath - Path to the phases file
- * @returns Array of phase info objects
- */
-function parsePhases(phasesFilePath) {
-    if (!existsSync(phasesFilePath)) {
-        logger.debug(`Phases file not found: ${phasesFilePath}`);
-        return [];
-    }
-    try {
-        const content = readFileSync(phasesFilePath, 'utf-8').trim();
-        if (!content) {
-            return [];
-        }
-        const lines = content.split('\n');
-        const phaseMap = new Map();
-        for (const line of lines) {
-            const parts = line.split('|');
-            if (parts.length < 4) {
-                logger.warn(`Skipping malformed phase line: ${line}`);
-                continue;
-            }
-            const [id, status, startStr, endStr] = parts;
-            // Validate status
-            if (!VALID_PHASE_STATUSES.has(status)) {
-                logger.warn(`Unknown phase status "${status}" for phase "${id}", treating as failed`);
-            }
-            const validatedStatus = VALID_PHASE_STATUSES.has(status)
-                ? status
-                : 'failed';
-            // Parse timestamps
-            const startTime = parseInt(startStr, 10) || 0;
-            const endTime = parseInt(endStr, 10) || 0;
-            // Calculate duration (end - start) in milliseconds
-            const durationMs = endTime > 0 && startTime > 0 ? (endTime - startTime) * 1000 : undefined;
-            // Get or create phase entry
-            let phase = phaseMap.get(id);
-            if (!phase) {
-                phase = {
-                    id,
-                    label: PHASE_LABELS[id] || id,
-                    status: validatedStatus,
-                    durationMs: 0,
-                };
-                phaseMap.set(id, phase);
-            }
-            // Update status (last status wins)
-            phase.status = validatedStatus;
-            // Aggregate duration
-            if (durationMs !== undefined) {
-                phase.durationMs = (phase.durationMs || 0) + durationMs;
-            }
-        }
-        return Array.from(phaseMap.values());
-    }
-    catch (err) {
-        logger.warn(`Failed to parse phases file: ${err instanceof Error ? err.message : String(err)}`);
-        return [];
-    }
-}
+import { parsePhases } from './loop-status.js';
 /**
  * Read baseline commit hash from the baseline file.
  *
@@ -127,7 +51,7 @@ function readBaselineCommit(baselineFilePath) {
  * which blocks the event loop. Callers should wrap in try-catch to handle
  * failures gracefully.
  */
-export function buildEnhancedRunSummary(basicSummary, projectRoot, feature) {
+export function buildEnhancedRunSummary(basicSummary, projectRoot, feature, baselineOverride) {
     const phasesFilePath = `/tmp/ralph-loop-${feature}.phases`;
     const baselineFilePath = `/tmp/ralph-loop-${feature}.baseline`;
     // Parse phases and set implementation iterations from actual loop count
@@ -153,8 +77,10 @@ export function buildEnhancedRunSummary(basicSummary, projectRoot, feature) {
         completed: basicSummary.tasksDone,
         total: basicSummary.tasksTotal,
     };
-    // Git changes and commits
-    const baselineCommit = readBaselineCommit(baselineFilePath);
+    // Git changes and commits — use override if provided (avoids re-reading a cleaned-up file)
+    const baselineCommit = baselineOverride !== undefined
+        ? (baselineOverride ? baselineOverride.substring(0, 7) : null)
+        : readBaselineCommit(baselineFilePath);
     const currentCommit = getCurrentCommitHash(projectRoot);
     let changes = { available: false };
     let commits = { available: false };
@@ -205,13 +131,19 @@ export function buildEnhancedRunSummary(basicSummary, projectRoot, feature) {
                     available: true,
                     created: true,
                 };
-                // Try to get linked issue, passing prInfo to avoid redundant gh call
-                const issueInfo = getLinkedIssue(projectRoot, basicSummary.branch, prInfo);
+                // Try to get linked issue, passing prInfo and feature name for fallback detection
+                const issueInfo = getLinkedIssue(projectRoot, basicSummary.branch, prInfo, feature);
                 if (issueInfo) {
+                    // When PR is merged with "Closes #N", GitHub auto-closes the issue.
+                    // The summary may be built before GitHub processes the webhook, so
+                    // infer closure from PR state to avoid showing stale "OPEN" status.
+                    const inferredState = prInfo.state === 'MERGED' && issueInfo.state === 'OPEN'
+                        ? 'CLOSED'
+                        : issueInfo.state;
                     issue = {
                         number: issueInfo.number,
                         url: issueInfo.url,
-                        status: issueInfo.state,
+                        status: inferredState,
                         available: true,
                         linked: true,
                     };
@@ -219,6 +151,30 @@ export function buildEnhancedRunSummary(basicSummary, projectRoot, feature) {
                 else {
                     issue = { available: true, linked: false };
                 }
+                // Enrich commits from PR when squash-merge detected (1 local commit + merged PR)
+                if (prInfo.state === 'MERGED' &&
+                    commits.available &&
+                    commits.commitList &&
+                    commits.commitList.length <= 1) {
+                    try {
+                        const prCommitsOutput = execFileSync('gh', ['pr', 'view', String(prInfo.number), '--json', 'commits'], { cwd: projectRoot, encoding: 'utf-8', timeout: 10_000 }).trim();
+                        const prCommitsData = JSON.parse(prCommitsOutput);
+                        const prCommits = prCommitsData.commits;
+                        if (Array.isArray(prCommits) && prCommits.length > 1) {
+                            commits = {
+                                ...commits,
+                                commitList: prCommits.map((c) => ({
+                                    hash: c.oid?.substring(0, 7) ?? '',
+                                    title: c.messageHeadline ?? '',
+                                })),
+                                mergeType: 'squash',
+                            };
+                        }
+                    }
+                    catch (err) {
+                        logger.debug(`Failed to fetch PR commits: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                }
             }
             else {
                 pr = { available: true, created: false };

package/dist/tui/utils/clear-screen.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Clear the terminal screen to prevent stale PTY scroll buffer artifacts.
+ *
+ * When Ink re-renders significantly shorter output (e.g. after dismissing a
+ * 25-row IssuePicker), the old content remains in the PTY scroll buffer,
+ * causing visual duplication of the banner and other content. This sends
+ * ANSI escape sequences to clear the entire screen and reset the cursor.
+ *
+ * This is an intentional mix of imperative stdout writes with Ink's
+ * declarative rendering — Ink has no API to flush the PTY scroll buffer.
+ * Call this *before* state updates that shrink the rendered output so
+ * Ink's next render paints onto a clean screen.
+ */
+export declare function clearScreen(stdout: NodeJS.WriteStream): void;

package/dist/tui/utils/clear-screen.js

@@ -0,0 +1,16 @@
+/**
+ * Clear the terminal screen to prevent stale PTY scroll buffer artifacts.
+ *
+ * When Ink re-renders significantly shorter output (e.g. after dismissing a
+ * 25-row IssuePicker), the old content remains in the PTY scroll buffer,
+ * causing visual duplication of the banner and other content. This sends
+ * ANSI escape sequences to clear the entire screen and reset the cursor.
+ *
+ * This is an intentional mix of imperative stdout writes with Ink's
+ * declarative rendering — Ink has no API to flush the PTY scroll buffer.
+ * Call this *before* state updates that shrink the rendered output so
+ * Ink's next render paints onto a clean screen.
+ */
+export function clearScreen(stdout) {
+    stdout.write('\x1b[2J\x1b[H');
+}

package/dist/tui/utils/loop-status.d.ts

@@ -1,6 +1,13 @@
 /**
  * Loop status helpers for the TUI run/monitor screens.
  */
+/**
+ * Find the implementation plan file, checking main project and git worktrees.
+ *
+ * Shared between loop-status.ts and monitor.ts to avoid duplicating the
+ * worktree search logic.
+ */
+export declare function findImplementationPlan(projectRoot: string, specsRelPath: string, feature: string): string | null;
 export interface LoopStatus {
     running: boolean;
     phase: string;
@@ -10,12 +17,14 @@ export interface LoopStatus {
     tokensOutput: number;
     cacheCreate: number;
     cacheRead: number;
+    tokensUpdatedAt?: number;
 }
 export interface TaskCounts {
     tasksDone: number;
     tasksPending: number;
     e2eDone: number;
     e2ePending: number;
+    planExists: boolean;
 }
 /**
  * Phase execution status and timing.
@@ -27,12 +36,17 @@ export interface PhaseInfo {
     /** Human-readable phase label */
     label: string;
     /** Phase completion status */
-    status: 'success' | 'skipped' | 'failed';
+    status: 'success' | 'skipped' | 'failed' | 'started';
     /** Duration in milliseconds, if available */
     durationMs?: number;
     /** Number of iterations in this phase (e.g., for implementation) */
     iterations?: number;
 }
+/**
+ * Phase ID to human-readable label mapping.
+ * Matches the phase IDs written by feature-loop.sh.
+ */
+export declare const PHASE_LABELS: Record<string, string>;
 /**
  * Return the conventional log file path for a feature loop.
  */
@@ -45,6 +59,14 @@ export declare function getLoopLogPath(feature: string): string;
  * concurrent loops are rare, but callers should be aware of the limitation.
  */
 export declare function detectPhase(feature: string): string;
+/**
+ * Read the current phase from the `.phases` file written by feature-loop.sh.
+ * Returns the human-readable label of the active phase, or null if unavailable.
+ *
+ * The file format is: phase_id|status|start_timestamp|end_timestamp
+ * A line with status "started" and no end timestamp indicates the active phase.
+ */
+export declare function readCurrentPhase(feature: string): string | null;
 /**
  * Read loop status from temp files written by feature-loop.sh.
  *
@@ -87,6 +109,10 @@ export interface ActivityEvent {
     /** Inferred status based on event content */
     status: 'success' | 'error' | 'in-progress';
 }
+/**
+ * Returns true if a log line should be excluded from the activity feed.
+ */
+export declare function shouldSkipLine(line: string): boolean;
 /**
  * Parse the loop log file into structured activity events.
  *
@@ -108,3 +134,17 @@ export declare function parsePhaseChanges(feature: string, lastKnownPhases?: Pha
     events: ActivityEvent[];
     currentPhases?: PhaseInfo[];
 };
+/**
+ * Parse phase information from the phases file written by feature-loop.sh.
+ *
+ * Format: phase_id|status|start_timestamp|end_timestamp
+ * Accepts both 3-field lines (started: phase_id|started|timestamp) and
+ * 4-field lines (completed: phase_id|status|start_ts|end_ts).
+ *
+ * The parser handles duplicate phase entries defensively (last status wins,
+ * durations aggregate), though feature-loop.sh normally writes one final
+ * line per phase.
+ *
+ * Used by build-run-summary.ts for completion summaries.
+ */
+export declare function parsePhases(phasesFilePath: string): PhaseInfo[];

package/dist/tui/utils/loop-status.js

@@ -6,6 +6,51 @@ import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { loadConfigWithDefaults } from '../../utils/config.js';
 import { logger } from '../../utils/logger.js';
+/**
+ * Find the implementation plan file, checking main project and git worktrees.
+ *
+ * Shared between loop-status.ts and monitor.ts to avoid duplicating the
+ * worktree search logic.
+ */
+export function findImplementationPlan(projectRoot, specsRelPath, feature) {
+    // 1. Check main project
+    const mainPath = join(projectRoot, specsRelPath, `${feature}-implementation-plan.md`);
+    if (existsSync(mainPath))
+        return mainPath;
+    // 2. Check git worktrees for the feature branch
+    try {
+        const output = execFileSync('git', ['worktree', 'list', '--porcelain'], {
+            cwd: projectRoot,
+            encoding: 'utf-8',
+        });
+        const worktrees = output.split('\n\n').filter(Boolean);
+        for (const wt of worktrees) {
+            const pathMatch = wt.match(/^worktree (.+)$/m);
+            const escapedFeature = feature.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            const branchMatch = wt.match(new RegExp(`^branch .+/feat/${escapedFeature}$`, 'm'));
+            if (pathMatch && branchMatch) {
+                const wtPlan = join(pathMatch[1], specsRelPath, `${feature}-implementation-plan.md`);
+                if (existsSync(wtPlan))
+                    return wtPlan;
+            }
+        }
+    }
+    catch {
+        // git worktree list failed — ignore
+    }
+    return null;
+}
+/**
+ * Phase ID to human-readable label mapping.
+ * Matches the phase IDs written by feature-loop.sh.
+ */
+export const PHASE_LABELS = {
+    planning: 'Planning',
+    implementation: 'Implementation',
+    e2e_testing: 'E2E Testing',
+    verification: 'Verification',
+    pr_review: 'PR & Review',
+};
 /**
  * Track whether pgrep is available to avoid repeated failed calls.
  * null = untested, true = available, false = unavailable
@@ -66,6 +111,48 @@ export function detectPhase(feature) {
         return 'Running';
     return 'Idle';
 }
+/**
+ * Read the current phase from the `.phases` file written by feature-loop.sh.
+ * Returns the human-readable label of the active phase, or null if unavailable.
+ *
+ * The file format is: phase_id|status|start_timestamp|end_timestamp
+ * A line with status "started" and no end timestamp indicates the active phase.
+ */
+export function readCurrentPhase(feature) {
+    const phasesFile = `/tmp/ralph-loop-${feature}.phases`;
+    let content;
+    try {
+        content = readFileSync(phasesFile, 'utf-8').trim();
+    }
+    catch {
+        return null;
+    }
+    if (!content)
+        return null;
+    const lines = content.split('\n');
+    let lastStartedPhase = null;
+    let lastCompletedPhase = null;
+    for (const line of lines) {
+        const parts = line.split('|');
+        if (parts.length < 2)
+            continue;
+        const [id, status] = parts;
+        if (status === 'started') {
+            lastStartedPhase = id;
+        }
+        else if (status === 'success' || status === 'failed' || status === 'skipped') {
+            lastCompletedPhase = id;
+        }
+    }
+    if (lastStartedPhase) {
+        return PHASE_LABELS[lastStartedPhase] || lastStartedPhase;
+    }
+    if (lastCompletedPhase) {
+        const label = PHASE_LABELS[lastCompletedPhase] || lastCompletedPhase;
+        return `post-${label}`;
+    }
+    return null;
+}
 /**
  * Read loop status from temp files written by feature-loop.sh.
  *
@@ -89,8 +176,14 @@ export function readLoopStatus(feature) {
         try {
             const content = readFileSync(fileToRead, 'utf-8').trim();
             const parts = content.split('|');
-            iteration = parseInt(parts[0] || '0', 10) || 0;
-            maxIterations = parseInt(parts[1] || '0', 10) || 0;
+            // Require at least 2 fields (iteration|maxIterations); skip partial writes
+            if (parts.length >= 2) {
+                iteration = parseInt(parts[0] || '0', 10) || 0;
+                maxIterations = parseInt(parts[1] || '0', 10) || 0;
+            }
+            else {
+                logger.debug(`Status file has fewer than 2 fields, using defaults: ${content}`);
+            }
         }
         catch (err) {
             logger.debug(`Failed to parse status file: ${err instanceof Error ? err.message : String(err)}`);
@@ -100,28 +193,48 @@ export function readLoopStatus(feature) {
     let tokensOutput = 0;
     let cacheCreate = 0;
     let cacheRead = 0;
+    let tokensUpdatedAt;
     if (existsSync(tokensFile)) {
         try {
             const content = readFileSync(tokensFile, 'utf-8').trim();
             const parts = content.split('|');
-            tokensInput = parseInt(parts[0] || '0', 10) || 0;
-            tokensOutput = parseInt(parts[1] || '0', 10) || 0;
-            cacheCreate = parseInt(parts[2] || '0', 10) || 0;
-            cacheRead = parseInt(parts[3] || '0', 10) || 0;
+            // Require at least 2 fields (input|output); cache fields are optional (legacy format)
+            if (parts.length >= 2) {
+                tokensInput = parseInt(parts[0] || '0', 10) || 0;
+                tokensOutput = parseInt(parts[1] || '0', 10) || 0;
+                cacheCreate = parts.length >= 3 ? (parseInt(parts[2] || '0', 10) || 0) : 0;
+                cacheRead = parts.length >= 4 ? (parseInt(parts[3] || '0', 10) || 0) : 0;
+                if (parts[4]) {
+                    const epoch = parseInt(parts[4], 10);
+                    if (epoch > 0)
+                        tokensUpdatedAt = epoch * 1000; // convert to ms
+                }
+            }
+            else {
+                logger.debug(`Tokens file has fewer than 2 fields, using defaults: ${content}`);
+            }
         }
         catch (err) {
             logger.debug(`Failed to parse tokens file: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    const running = isProcessRunning(`feature-loop.sh.*${feature}`);
+    // Prefer .phases file (written by feature-loop.sh on transitions) over process
+    // detection. pgrep-based detection can return stale results when old Claude
+    // sessions linger, causing the phase to appear stuck (e.g., "Planning" during
+    // Verification). The .phases file is the authoritative source of phase transitions.
+    const phaseFromFile = readCurrentPhase(feature);
+    let phase = phaseFromFile ?? detectPhase(feature);
     return {
-        running: isProcessRunning(`feature-loop.sh.*${feature}`),
-        phase: detectPhase(feature),
+        running,
+        phase,
         iteration,
         maxIterations,
         tokensInput,
         tokensOutput,
         cacheCreate,
         cacheRead,
+        tokensUpdatedAt,
     };
 }
 /**
@@ -143,12 +256,13 @@ export async function parseImplementationPlan(projectRoot, feature, specsDirOver
         }
     }
     const specsDir = specsDirOverride || config?.paths.specs || '.ralph/specs';
-    const planPath = join(projectRoot, specsDir, `${feature}-implementation-plan.md`);
+    const planPath = findImplementationPlan(projectRoot, specsDir, feature);
     let tasksDone = 0;
     let tasksPending = 0;
     let e2eDone = 0;
     let e2ePending = 0;
-    if (existsSync(planPath)) {
+    const planExists = planPath !== null;
+    if (planPath) {
         try {
             const content = readFileSync(planPath, 'utf-8');
             const lines = content.split('\n');
@@ -171,12 +285,36 @@ export async function parseImplementationPlan(projectRoot, feature, specsDirOver
                     }
                 }
             }
+            // Fallback: if no checkboxes found, count "#### Task N:" headers
+            if (tasksDone === 0 && tasksPending === 0 && e2eDone === 0 && e2ePending === 0) {
+                let headerTaskCount = 0;
+                for (const line of lines) {
+                    if (line.match(/^#{1,4}\s+Task\s+\d+/i)) {
+                        headerTaskCount++;
+                    }
+                }
+                if (headerTaskCount > 0) {
+                    // Check phases file to determine completion
+                    const phasesPath = `/tmp/ralph-loop-${feature}.phases`;
+                    let implDone = false;
+                    if (existsSync(phasesPath)) {
+                        const phases = readFileSync(phasesPath, 'utf-8');
+                        implDone = phases.includes('implementation|success');
+                    }
+                    if (implDone) {
+                        tasksDone = headerTaskCount;
+                    }
+                    else {
+                        tasksPending = headerTaskCount;
+                    }
+                }
+            }
         }
         catch (err) {
             logger.debug(`Failed to parse implementation plan: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
-    return { tasksDone, tasksPending, e2eDone, e2ePending };
+    return { tasksDone, tasksPending, e2eDone, e2ePending, planExists };
 }
 /**
  * Get current git branch.
@@ -259,14 +397,14 @@ const SKIP_LINE_PATTERNS = [
     /^Baseline commit:/,
     /^Creating branch:/,
     // Misc noise
-    /^\{"level"/, // JSON log lines (BashTool warnings etc.)
+    /^\{"/, // Any line starting with JSON object (Claude result, log entries)
     /^Pending implementation tasks: \d+$/, // raw task count (redundant with progress bar)
     /^Ready for feedback\.?$/i, // Conversational filler
 ];
 /**
  * Returns true if a log line should be excluded from the activity feed.
  */
-function shouldSkipLine(line) {
+export function shouldSkipLine(line) {
     return SKIP_LINE_PATTERNS.some((pattern) => pattern.test(line));
 }
 /**
@@ -279,13 +417,18 @@ function stripMarkdown(msg) {
         .replace(/^\s*[-*]\s+/, '') // leading bullet points
         .trim();
 }
-const SUCCESS_KEYWORDS = /completed|passed|success|approved|all implementation tasks completed/i;
-const ERROR_KEYWORDS = /error|failed|failure/i;
+const SUCCESS_KEYWORDS = /\b(completed|passed|success|approved|fixed|resolved|merged|works)\b/i;
+const ERROR_KEYWORDS = /\b(error|failed|failure)\b/i;
+const POSITIVE_ERROR_CONTEXT = /\b(fixed|resolved|added|handled|handling|recovery|boundary|boundaries|tests?\s+passed)\b/i;
 function inferStatus(message) {
     if (SUCCESS_KEYWORDS.test(message))
         return 'success';
-    if (ERROR_KEYWORDS.test(message))
+    if (ERROR_KEYWORDS.test(message)) {
+        // Avoid misclassifying positive actions that mention error-related words
+        if (POSITIVE_ERROR_CONTEXT.test(message))
+            return 'in-progress';
         return 'error';
+    }
     return 'in-progress';
 }
 /**
@@ -366,28 +509,26 @@ export function parsePhaseChanges(feature, lastKnownPhases) {
         }
         return { events: [] };
     }
-    let parsed;
-    try {
-        parsed = JSON.parse(rawContent);
-        if (!Array.isArray(parsed)) {
-            logger.debug(`parsePhaseChanges: expected array in ${phasesFile}, got ${typeof parsed}`);
-            return { events: [], currentPhases: lastKnownPhases };
-        }
-    }
-    catch (err) {
-        logger.debug(`parsePhaseChanges: invalid JSON in ${phasesFile}: ${err instanceof Error ? err.message : String(err)}`);
+    const content = rawContent.trim();
+    if (!content) {
         return { events: [], currentPhases: lastKnownPhases };
     }
-    // Validate each phase has required fields
-    const currentPhases = [];
-    for (const item of parsed) {
-        if (typeof item === 'object' && item !== null &&
-            'id' in item && typeof item.id === 'string' &&
-            'label' in item && typeof item.label === 'string' &&
-            'status' in item && typeof item.status === 'string') {
-            currentPhases.push(item);
-        }
+    // Parse pipe-delimited format: phase_id|status|start_timestamp|end_timestamp
+    const VALID_STATUSES = new Set(['success', 'skipped', 'failed', 'started']);
+    const phaseMap = new Map();
+    for (const line of content.split('\n')) {
+        const parts = line.split('|');
+        if (parts.length < 2)
+            continue;
+        const [id, status] = parts;
+        if (!id || !VALID_STATUSES.has(status))
+            continue;
+        const label = PHASE_LABELS[id] || id;
+        const validStatus = status;
+        // Last status wins for each phase id
+        phaseMap.set(id, { id, label, status: validStatus });
     }
+    const currentPhases = Array.from(phaseMap.values());
     const events = [];
     const now = Date.now();
     for (const current of currentPhases) {
@@ -411,3 +552,70 @@ export function parsePhaseChanges(feature, lastKnownPhases) {
     }
     return { events, currentPhases };
 }
+/**
+ * Parse phase information from the phases file written by feature-loop.sh.
+ *
+ * Format: phase_id|status|start_timestamp|end_timestamp
+ * Accepts both 3-field lines (started: phase_id|started|timestamp) and
+ * 4-field lines (completed: phase_id|status|start_ts|end_ts).
+ *
+ * The parser handles duplicate phase entries defensively (last status wins,
+ * durations aggregate), though feature-loop.sh normally writes one final
+ * line per phase.
+ *
+ * Used by build-run-summary.ts for completion summaries.
+ */
+export function parsePhases(phasesFilePath) {
+    if (!existsSync(phasesFilePath)) {
+        return [];
+    }
+    try {
+        const content = readFileSync(phasesFilePath, 'utf-8').trim();
+        if (!content) {
+            return [];
+        }
+        const lines = content.split('\n');
+        const VALID_STATUSES = new Set(['success', 'skipped', 'failed', 'started']);
+        const phaseMap = new Map();
+        for (const line of lines) {
+            const parts = line.split('|');
+            if (parts.length < 2)
+                continue;
+            const [id, status] = parts;
+            if (!id || !VALID_STATUSES.has(status)) {
+                logger.warn(`Unknown phase status "${status}" for phase "${id}", treating as failed`);
+                // Still process with 'failed' status
+            }
+            const validatedStatus = VALID_STATUSES.has(status)
+                ? status
+                : 'failed';
+            // Parse timestamps (may be absent for 3-field 'started' lines)
+            const startTime = parts.length >= 3 ? (parseInt(parts[2], 10) || 0) : 0;
+            const endTime = parts.length >= 4 ? (parseInt(parts[3], 10) || 0) : 0;
+            // Calculate duration (end - start) in milliseconds
+            const durationMs = endTime > 0 && startTime > 0 ? (endTime - startTime) * 1000 : undefined;
+            // Get or create phase entry
+            let phase = phaseMap.get(id);
+            if (!phase) {
+                phase = {
+                    id,
+                    label: PHASE_LABELS[id] || id,
+                    status: validatedStatus,
+                    durationMs: 0,
+                };
+                phaseMap.set(id, phase);
+            }
+            // Update status (last status wins)
+            phase.status = validatedStatus;
+            // Aggregate duration
+            if (durationMs !== undefined) {
+                phase.durationMs = (phase.durationMs || 0) + durationMs;
+            }
+        }
+        return Array.from(phaseMap.values());
+    }
+    catch (err) {
+        logger.warn(`Failed to parse phases file: ${err instanceof Error ? err.message : String(err)}`);
+        return [];
+    }
+}