wiggum-cli 0.13.2 → 0.15.0

package/dist/tui/screens/RunScreen.js

@@ -18,12 +18,16 @@ import { execFileSync, spawn } from 'node:child_process';
 import { closeSync, existsSync, openSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { Confirm } from '../components/Confirm.js';
+import { Select } from '../components/Select.js';
 import { AppShell } from '../components/AppShell.js';
 import { RunCompletionSummary } from '../components/RunCompletionSummary.js';
 import { colors, theme } from '../theme.js';
 import { readLoopStatus, parseImplementationPlan, getGitBranch, formatNumber, getLoopLogPath, } from '../utils/loop-status.js';
+import { buildEnhancedRunSummary } from '../utils/build-run-summary.js';
+import { writeRunSummaryFile } from '../../utils/summary-file.js';
 import { loadConfigWithDefaults } from '../../utils/config.js';
 import { logger } from '../../utils/logger.js';
+import { readActionRequest, writeActionReply, cleanupActionFiles } from '../utils/action-inbox.js';
 const POLL_INTERVAL_MS = 2500;
 const ERROR_TAIL_LINES = 12;
 function findFeatureLoopScript(projectRoot, scriptsDir) {
@@ -80,7 +84,7 @@ function readLogTail(logPath, maxLines) {
         return `[Unable to read log: ${err instanceof Error ? err.message : String(err)}]`;
     }
 }
-export function RunScreen({ header, featureName, projectRoot, sessionState, monitorOnly = false, onComplete, onBackground, onCancel, }) {
+export function RunScreen({ header, featureName, projectRoot, sessionState, monitorOnly = false, reviewMode: reviewModeProp, onComplete, onBackground, onCancel, }) {
     const [status, setStatus] = useState(() => {
         try {
             return readLoopStatus(featureName);
@@ -101,6 +105,7 @@ export function RunScreen({ header, featureName, projectRoot, sessionState, moni
     const [isStarting, setIsStarting] = useState(!monitorOnly);
     const [showConfirm, setShowConfirm] = useState(false);
     const [completionSummary, setCompletionSummary] = useState(null);
+    const [actionRequest, setActionRequest] = useState(null);
     const childRef = useRef(null);
     const stopRequestedRef = useRef(false);
     const isMountedRef = useRef(true);
@@ -111,6 +116,7 @@ export function RunScreen({ header, featureName, projectRoot, sessionState, moni
     const scriptsDirRef = useRef('.ralph/scripts');
     const maxIterationsRef = useRef(0);
     const maxE2eAttemptsRef = useRef(0);
+    const handledActionIdRef = useRef(null);
     useInput((input, key) => {
         // If showing completion summary, Enter or Esc dismisses
         if (completionSummary) {
@@ -121,6 +127,9 @@ export function RunScreen({ header, featureName, projectRoot, sessionState, moni
         }
         if (showConfirm)
             return;
+        // Action prompt handles its own input (Select component)
+        if (actionRequest)
+            return;
         if (key.ctrl && input === 'c') {
             setShowConfirm(true);
             return;
@@ -147,6 +156,21 @@ export function RunScreen({ header, featureName, projectRoot, sessionState, moni
         if (!isMountedRef.current)
             return;
         setBranch(getGitBranch(projectRoot));
+        // Check for pending action request (loop waiting for user input)
+        const request = readActionRequest(featureName);
+        if (!isMountedRef.current)
+            return;
+        if (request) {
+            // Only show if we haven't already handled this action
+            if (request.id !== handledActionIdRef.current) {
+                setActionRequest(request);
+            }
+        }
+        else {
+            // File cleaned up by shell — reset tracking so future requests work
+            handledActionIdRef.current = null;
+            setActionRequest((prev) => prev ? null : prev);
+        }
         // In monitor mode, detect completion (only fire once)
         if (monitorOnly && !nextStatus.running && !completionSentRef.current) {
             completionSentRef.current = true;
@@ -159,7 +183,7 @@ export function RunScreen({ header, featureName, projectRoot, sessionState, moni
             const tasksDone = nextTasks.tasksDone + nextTasks.e2eDone;
             const tasksTotal = tasksDone + nextTasks.tasksPending + nextTasks.e2ePending;
             const errorTail = exitCode !== 0 ? readLogTail(logPath, ERROR_TAIL_LINES) || undefined : undefined;
-            setCompletionSummary({
+            const basicSummary = {
                 feature: featureName,
                 iterations: nextStatus.iteration,
                 maxIterations: nextStatus.maxIterations,
@@ -172,9 +196,26 @@ export function RunScreen({ header, featureName, projectRoot, sessionState, moni
                 branch: getGitBranch(projectRoot),
                 logPath,
                 errorTail,
+            };
+            let enhancedSummary;
+            try {
+                enhancedSummary = buildEnhancedRunSummary(basicSummary, projectRoot, featureName);
+            }
+            catch (err) {
+                logger.error(`Failed to build enhanced summary for ${featureName}: ${err instanceof Error ? err.message : String(err)}`);
+                enhancedSummary = basicSummary;
+            }
+            setCompletionSummary(enhancedSummary);
+            // Persist summary to JSON file (non-blocking)
+            writeRunSummaryFile(featureName, enhancedSummary).catch((err) => {
+                logger.error(`Failed to persist summary file for ${featureName}: ${err instanceof Error ? err.message : String(err)}`);
             });
         }
     }, [featureName, projectRoot, monitorOnly]);
+    // Keep a stable ref to the latest refreshStatus so the spawn effect
+    // can schedule polls without re-running when refreshStatus changes.
+    const refreshStatusRef = useRef(refreshStatus);
+    useEffect(() => { refreshStatusRef.current = refreshStatus; }, [refreshStatus]);
     const stopLoop = useCallback(() => {
         stopRequestedRef.current = true;
         if (childRef.current) {
@@ -229,11 +270,11 @@ export function RunScreen({ header, featureName, projectRoot, sessionState, moni
                 if (cancelled)
                     return;
                 setIsStarting(false);
-                refreshStatus().catch((err) => {
+                refreshStatusRef.current().catch((err) => {
                     logger.warn(`Status refresh failed: ${err instanceof Error ? err.message : String(err)}`);
                 });
                 pollTimer = setInterval(() => {
-                    refreshStatus().catch((err) => {
+                    refreshStatusRef.current().catch((err) => {
                         logger.warn(`Status refresh failed: ${err instanceof Error ? err.message : String(err)}`);
                     });
                 }, POLL_INTERVAL_MS);
@@ -272,12 +313,16 @@ export function RunScreen({ header, featureName, projectRoot, sessionState, moni
                     setIsStarting(false);
                     return;
                 }
-                const reviewMode = config.loop.reviewMode ?? 'manual';
-                if (reviewMode !== 'manual' && reviewMode !== 'auto') {
-                    setError(`Invalid reviewMode '${reviewMode}'. Allowed values are 'manual' or 'auto'.`);
+                const reviewMode = reviewModeProp ?? config.loop.reviewMode ?? 'manual';
+                if (reviewMode !== 'manual' && reviewMode !== 'auto' && reviewMode !== 'merge') {
+                    setError(`Invalid reviewMode '${reviewMode}'. Allowed values are 'manual', 'auto', or 'merge'.`);
                     setIsStarting(false);
                     return;
                 }
+                // Clean up stale action files from previous runs
+                await cleanupActionFiles(featureName).catch((err) => {
+                    logger.warn(`Failed to clean up stale action files: ${err instanceof Error ? err.message : String(err)}`);
+                });
                 const logPath = getLoopLogPath(featureName);
                 const logFd = openSync(logPath, 'a');
                 let logFdClosed = false;
@@ -306,11 +351,11 @@ export function RunScreen({ header, featureName, projectRoot, sessionState, moni
                         child.kill('SIGINT');
                     }
                     pollTimer = setInterval(() => {
-                        refreshStatus().catch((err) => {
+                        refreshStatusRef.current().catch((err) => {
                             logger.warn(`Status refresh failed: ${err instanceof Error ? err.message : String(err)}`);
                         });
                     }, POLL_INTERVAL_MS);
-                    refreshStatus().catch((err) => {
+                    refreshStatusRef.current().catch((err) => {
                         logger.warn(`Status refresh failed: ${err instanceof Error ? err.message : String(err)}`);
                     });
                     child.on('error', (err) => {
@@ -348,7 +393,7 @@ export function RunScreen({ header, featureName, projectRoot, sessionState, moni
                         const tasksTotal = tasksDone + latestTasks.tasksPending + latestTasks.e2ePending;
                         const exitCode = typeof code === 'number' ? code : 1;
                         const errorTail = exitCode === 0 ? undefined : readLogTail(logPath, ERROR_TAIL_LINES) || undefined;
-                        const summary = {
+                        const basicSummary = {
                             feature: featureName,
                             iterations: latestStatus.iteration,
                             maxIterations: latestStatus.maxIterations || config.loop.maxIterations,
@@ -361,8 +406,21 @@ export function RunScreen({ header, featureName, projectRoot, sessionState, moni
                             logPath,
                             errorTail,
                         };
+                        // Build enhanced summary with phases, git stats, PR/issue metadata
+                        let enhancedSummary;
+                        try {
+                            enhancedSummary = buildEnhancedRunSummary(basicSummary, projectRoot, featureName);
+                        }
+                        catch (err) {
+                            logger.error(`Failed to build enhanced summary for ${featureName}: ${err instanceof Error ? err.message : String(err)}`);
+                            enhancedSummary = basicSummary;
+                        }
                         // Show completion summary inline
-                        setCompletionSummary(summary);
+                        setCompletionSummary(enhancedSummary);
+                        // Persist summary to JSON file (non-blocking)
+                        writeRunSummaryFile(featureName, enhancedSummary).catch((err) => {
+                            logger.error(`Failed to persist summary file for ${featureName}: ${err instanceof Error ? err.message : String(err)}`);
+                        });
                     });
                 }
                 catch (spawnErr) {
@@ -387,7 +445,10 @@ export function RunScreen({ header, featureName, projectRoot, sessionState, moni
             if (pollTimer)
                 clearInterval(pollTimer);
         };
-    }, [featureName, projectRoot, refreshStatus, monitorOnly, sessionState.config]);
+        // Note: refreshStatusRef (not refreshStatus) is used inside to avoid re-spawning
+        // the child process when the callback identity changes due to actionRequest updates.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [featureName, projectRoot, monitorOnly, sessionState.config]);
     const totalTasks = tasks.tasksDone + tasks.tasksPending;
     const totalE2e = tasks.e2eDone + tasks.e2ePending;
     const totalAll = totalTasks + totalE2e;
@@ -401,11 +462,47 @@ export function RunScreen({ header, featureName, projectRoot, sessionState, moni
     // Tips text
     const tips = completionSummary
         ? 'Enter to return to shell'
-        : monitorOnly
-            ? 'Ctrl+C stop, Esc back'
-            : 'Ctrl+C stop, Esc background';
-    // Input element (only show Confirm when stopping)
-    const inputElement = showConfirm ? (_jsx(Confirm, { message: stopRequestedRef.current ? 'Stopping loop...' : 'Stop the feature loop?', onConfirm: handleConfirm, onCancel: () => setShowConfirm(false), initialValue: false })) : null;
+        : actionRequest
+            ? 'Select an option, Esc for default'
+            : monitorOnly
+                ? 'Ctrl+C stop, Esc back'
+                : 'Ctrl+C stop, Esc background';
+    // Action select handler — awaits write before clearing prompt
+    const handleActionSelect = useCallback(async (choiceId) => {
+        if (!actionRequest)
+            return;
+        try {
+            await writeActionReply(featureName, { id: actionRequest.id, choice: choiceId });
+            handledActionIdRef.current = actionRequest.id;
+            setActionRequest(null);
+        }
+        catch (err) {
+            logger.error(`Failed to write action reply: ${err instanceof Error ? err.message : String(err)}`);
+            setError(`Failed to send action reply. The loop may time out to the default.`);
+        }
+    }, [actionRequest, featureName]);
+    // Action cancel handler (Esc = use default) — awaits write before clearing
+    const handleActionCancel = useCallback(async () => {
+        if (!actionRequest)
+            return;
+        try {
+            await writeActionReply(featureName, { id: actionRequest.id, choice: actionRequest.default });
+            handledActionIdRef.current = actionRequest.id;
+            setActionRequest(null);
+        }
+        catch (err) {
+            logger.error(`Failed to write action reply (default): ${err instanceof Error ? err.message : String(err)}`);
+            setError(`Failed to send action reply. The loop may time out to the default.`);
+        }
+    }, [actionRequest, featureName]);
+    // Input element: completionSummary > showConfirm > actionRequest > null
+    const actionSelectOptions = actionRequest
+        ? actionRequest.choices.map((c) => ({ value: c.id, label: c.label }))
+        : null;
+    const actionInitialIndex = actionRequest
+        ? Math.max(0, actionRequest.choices.findIndex((c) => c.id === actionRequest.default))
+        : 0;
+    const inputElement = showConfirm ? (_jsx(Confirm, { message: stopRequestedRef.current ? 'Stopping loop...' : 'Stop the feature loop?', onConfirm: handleConfirm, onCancel: () => setShowConfirm(false), initialValue: false })) : !completionSummary && actionRequest && actionSelectOptions ? (_jsx(Select, { message: actionRequest.prompt, options: actionSelectOptions, onSelect: handleActionSelect, onCancel: handleActionCancel, initialIndex: actionInitialIndex })) : null;
     return (_jsx(AppShell, { header: header, tips: tips, isWorking: isRunning && !isStarting, workingStatus: `${phaseLine} \u2014 ${featureName}`, workingHint: monitorOnly ? 'esc to go back' : 'esc to background', input: inputElement, error: error, footerStatus: {
             action: 'Run Loop',
             phase: phaseLine,

package/dist/tui/utils/action-inbox.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Action inbox helpers for file-based IPC between loop processes and the TUI.
+ *
+ * The loop writes an action request file; the TUI reads it and writes a reply.
+ * Both files live in /tmp with the conventional ralph-loop-<feature> prefix.
+ */
+export interface ActionChoice {
+    id: string;
+    label: string;
+}
+export interface ActionRequest {
+    id: string;
+    prompt: string;
+    choices: ActionChoice[];
+    default: string;
+}
+export interface ActionReply {
+    id: string;
+    choice: string;
+}
+/**
+ * Return the path to the action request file for a feature.
+ */
+export declare function getActionRequestPath(feature: string): string;
+/**
+ * Return the path to the action reply file for a feature.
+ */
+export declare function getActionReplyPath(feature: string): string;
+/**
+ * Read and validate the action request file for a feature.
+ *
+ * Returns null if the file does not exist, cannot be parsed, or is missing
+ * required fields. Logs a warning on parse errors.
+ */
+export declare function readActionRequest(feature: string): ActionRequest | null;
+/**
+ * Write an action reply file atomically (write to .tmp then rename).
+ */
+export declare function writeActionReply(feature: string, reply: ActionReply): Promise<void>;
+/**
+ * Remove both action request and reply files. Only suppresses ENOENT (file not found).
+ */
+export declare function cleanupActionFiles(feature: string): Promise<void>;

package/dist/tui/utils/action-inbox.js

@@ -0,0 +1,109 @@
+/**
+ * Action inbox helpers for file-based IPC between loop processes and the TUI.
+ *
+ * The loop writes an action request file; the TUI reads it and writes a reply.
+ * Both files live in /tmp with the conventional ralph-loop-<feature> prefix.
+ */
+import { rename, unlink, writeFile } from 'node:fs/promises';
+import { existsSync, readFileSync } from 'node:fs';
+import { logger } from '../../utils/logger.js';
+const FEATURE_REGEX = /^[a-zA-Z0-9_-]+$/;
+function validateFeature(feature) {
+    if (!FEATURE_REGEX.test(feature)) {
+        throw new Error(`Invalid feature name: "${feature}". Must contain only letters, numbers, hyphens, and underscores.`);
+    }
+}
+/**
+ * Return the path to the action request file for a feature.
+ */
+export function getActionRequestPath(feature) {
+    validateFeature(feature);
+    return `/tmp/ralph-loop-${feature}.action.json`;
+}
+/**
+ * Return the path to the action reply file for a feature.
+ */
+export function getActionReplyPath(feature) {
+    validateFeature(feature);
+    return `/tmp/ralph-loop-${feature}.action.reply.json`;
+}
+/**
+ * Read and validate the action request file for a feature.
+ *
+ * Returns null if the file does not exist, cannot be parsed, or is missing
+ * required fields. Logs a warning on parse errors.
+ */
+export function readActionRequest(feature) {
+    validateFeature(feature);
+    const path = getActionRequestPath(feature);
+    if (!existsSync(path)) {
+        return null;
+    }
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf-8');
+    }
+    catch (err) {
+        logger.warn(`Failed to read action request file: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        logger.warn(`Failed to parse action request JSON: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+    if (typeof parsed !== 'object' ||
+        parsed === null ||
+        typeof parsed.id !== 'string' ||
+        typeof parsed.prompt !== 'string' ||
+        !Array.isArray(parsed.choices) ||
+        parsed.choices.length === 0 ||
+        typeof parsed.default !== 'string') {
+        logger.warn('Action request file is missing required fields (id, prompt, choices, default) or choices is empty');
+        return null;
+    }
+    const record = parsed;
+    const choices = record.choices;
+    for (const choice of choices) {
+        if (typeof choice !== 'object' ||
+            choice === null ||
+            typeof choice.id !== 'string' ||
+            typeof choice.label !== 'string') {
+            logger.warn('Action request choices contain invalid entries (each must have id and label)');
+            return null;
+        }
+    }
+    return {
+        id: record.id,
+        prompt: record.prompt,
+        choices: choices,
+        default: record.default,
+    };
+}
+/**
+ * Write an action reply file atomically (write to .tmp then rename).
+ */
+export async function writeActionReply(feature, reply) {
+    validateFeature(feature);
+    const replyPath = getActionReplyPath(feature);
+    const tmpPath = `${replyPath}.tmp`;
+    const json = JSON.stringify(reply);
+    await writeFile(tmpPath, json, 'utf-8');
+    await rename(tmpPath, replyPath);
+}
+/**
+ * Remove both action request and reply files. Only suppresses ENOENT (file not found).
+ */
+export async function cleanupActionFiles(feature) {
+    validateFeature(feature);
+    const requestPath = getActionRequestPath(feature);
+    const replyPath = getActionReplyPath(feature);
+    const safeUnlink = (path) => unlink(path).catch((err) => {
+        if (err.code !== 'ENOENT')
+            throw err;
+    });
+    await Promise.all([safeUnlink(requestPath), safeUnlink(replyPath)]);
+}

package/dist/tui/utils/build-run-summary.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Build enhanced run summary from loop state and external data sources.
+ */
+import type { RunSummary } from '../screens/RunScreen.js';
+/**
+ * Build enhanced run summary from loop completion state.
+ *
+ * This function aggregates data from:
+ * - Basic loop state (iterations, tasks, tokens, exit code)
+ * - Phase timing file (/tmp/ralph-loop-<feature>.phases)
+ * - Baseline commit file (/tmp/ralph-loop-<feature>.baseline)
+ * - Git diff stats (via git-summary utilities)
+ * - PR/issue metadata (via pr-summary utilities)
+ *
+ * @param basicSummary - The minimal RunSummary constructed by RunScreen
+ * @param projectRoot - Root directory of the project
+ * @param feature - Feature name
+ * @returns Enhanced RunSummary with all available metadata
+ *
+ * Note: This function performs synchronous I/O and subprocess execution,
+ * which blocks the event loop. Callers should wrap in try-catch to handle
+ * failures gracefully.
+ */
+export declare function buildEnhancedRunSummary(basicSummary: RunSummary, projectRoot: string, feature: string): RunSummary;

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

@@ -0,0 +1,241 @@
+/**
+ * Build enhanced run summary from loop state and external data sources.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { logger } from '../../utils/logger.js';
+import { getCurrentCommitHash, getDiffStats } 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 [];
+    }
+}
+/**
+ * Read baseline commit hash from the baseline file.
+ *
+ * @param baselineFilePath - Path to the baseline file
+ * @returns Short commit hash, or null if not available
+ */
+function readBaselineCommit(baselineFilePath) {
+    if (!existsSync(baselineFilePath)) {
+        logger.debug(`Baseline file not found: ${baselineFilePath}`);
+        return null;
+    }
+    try {
+        const content = readFileSync(baselineFilePath, 'utf-8').trim();
+        // Validate content looks like a hex commit hash
+        if (!/^[0-9a-f]{7,40}$/i.test(content)) {
+            logger.warn(`Baseline file ${baselineFilePath} contains invalid content: "${content.substring(0, 20)}"`);
+            return null;
+        }
+        return content.substring(0, 7) || null;
+    }
+    catch (err) {
+        logger.warn(`Failed to read baseline file: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}
+/**
+ * Build enhanced run summary from loop completion state.
+ *
+ * This function aggregates data from:
+ * - Basic loop state (iterations, tasks, tokens, exit code)
+ * - Phase timing file (/tmp/ralph-loop-<feature>.phases)
+ * - Baseline commit file (/tmp/ralph-loop-<feature>.baseline)
+ * - Git diff stats (via git-summary utilities)
+ * - PR/issue metadata (via pr-summary utilities)
+ *
+ * @param basicSummary - The minimal RunSummary constructed by RunScreen
+ * @param projectRoot - Root directory of the project
+ * @param feature - Feature name
+ * @returns Enhanced RunSummary with all available metadata
+ *
+ * Note: This function performs synchronous I/O and subprocess execution,
+ * which blocks the event loop. Callers should wrap in try-catch to handle
+ * failures gracefully.
+ */
+export function buildEnhancedRunSummary(basicSummary, projectRoot, feature) {
+    const phasesFilePath = `/tmp/ralph-loop-${feature}.phases`;
+    const baselineFilePath = `/tmp/ralph-loop-${feature}.baseline`;
+    // Parse phases and set implementation iterations from actual loop count
+    const phases = parsePhases(phasesFilePath);
+    const implPhase = phases.find((p) => p.id === 'implementation');
+    if (implPhase) {
+        implPhase.iterations = basicSummary.iterations;
+    }
+    // Calculate total duration from phases
+    let totalDurationMs;
+    if (phases.length > 0) {
+        const totalMs = phases.reduce((sum, phase) => sum + (phase.durationMs || 0), 0);
+        totalDurationMs = totalMs > 0 ? totalMs : undefined;
+    }
+    // Build iteration breakdown
+    const iterationBreakdown = {
+        total: basicSummary.iterations,
+        implementation: phases.find((p) => p.id === 'implementation')?.iterations,
+        // TODO: Detect resumes from multiple phase entries (future enhancement)
+    };
+    // Build task summary
+    const tasks = {
+        completed: basicSummary.tasksDone,
+        total: basicSummary.tasksTotal,
+    };
+    // Git changes and commits
+    const baselineCommit = readBaselineCommit(baselineFilePath);
+    const currentCommit = getCurrentCommitHash(projectRoot);
+    let changes = { available: false };
+    let commits = { available: false };
+    if (baselineCommit && currentCommit) {
+        commits = {
+            fromHash: baselineCommit,
+            toHash: currentCommit,
+            mergeType: 'none', // TODO: Detect merge type from git history
+            available: true,
+        };
+        // Get diff stats
+        const diffStats = getDiffStats(projectRoot, baselineCommit, currentCommit);
+        if (diffStats !== null) {
+            changes = {
+                totalFilesChanged: diffStats.length,
+                files: diffStats.map((stat) => ({
+                    path: stat.path,
+                    added: stat.added,
+                    removed: stat.removed,
+                })),
+                available: true,
+            };
+        }
+        else {
+            changes = { available: true }; // Git is available but diff failed
+        }
+    }
+    else if (currentCommit) {
+        // Only current commit available (no baseline)
+        commits = {
+            toHash: currentCommit,
+            available: true,
+        };
+    }
+    // PR and issue metadata
+    let pr = { available: false, created: false };
+    let issue = { available: false, linked: false };
+    if (basicSummary.branch) {
+        try {
+            const prInfo = getPrForBranch(projectRoot, basicSummary.branch);
+            if (prInfo) {
+                pr = {
+                    number: prInfo.number,
+                    url: prInfo.url,
+                    available: true,
+                    created: true,
+                };
+                // Try to get linked issue, passing prInfo to avoid redundant gh call
+                const issueInfo = getLinkedIssue(projectRoot, basicSummary.branch, prInfo);
+                if (issueInfo) {
+                    issue = {
+                        number: issueInfo.number,
+                        url: issueInfo.url,
+                        status: issueInfo.state,
+                        available: true,
+                        linked: true,
+                    };
+                }
+                else {
+                    issue = { available: true, linked: false };
+                }
+            }
+            else {
+                pr = { available: true, created: false };
+                issue = { available: true, linked: false };
+            }
+        }
+        catch (err) {
+            logger.warn(`gh CLI query failed: ${err instanceof Error ? err.message : String(err)}`);
+            // pr and issue remain { available: false } from defaults above
+        }
+    }
+    return {
+        ...basicSummary,
+        totalDurationMs,
+        iterationBreakdown,
+        tasks,
+        phases,
+        changes,
+        commits,
+        pr,
+        issue,
+    };
+}