@weldr/runr 0.3.1 → 0.7.2

package/dist/diagnosis/stop-explainer.js

@@ -0,0 +1,267 @@
+/**
+ * Stop Diagnostics - Explains why a run stopped and suggests fixes.
+ *
+ * When review_loop_detected or other STOPPED states occur, this module
+ * analyzes the timeline and provides actionable guidance.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Parse timeline.jsonl file
+ */
+export function parseTimeline(timelinePath) {
+    if (!fs.existsSync(timelinePath)) {
+        return [];
+    }
+    const content = fs.readFileSync(timelinePath, 'utf-8');
+    const events = [];
+    for (const line of content.split('\n')) {
+        if (line.trim()) {
+            try {
+                events.push(JSON.parse(line));
+            }
+            catch {
+                // Skip malformed lines
+            }
+        }
+    }
+    return events;
+}
+/**
+ * Extract review loop context from timeline
+ */
+export function extractReviewLoopContext(events) {
+    const reviewEvents = events.filter(e => e.event_type === 'worker_response' && e.phase === 'review');
+    const implementEvents = events.filter(e => e.event_type === 'worker_response' && e.phase === 'implement');
+    // Count review rounds
+    const loopCount = Math.max(1, reviewEvents.length);
+    // Extract review requests (look for common patterns)
+    const reviewRequests = [];
+    for (const event of reviewEvents.slice(-3)) {
+        const content = event.response || event.content || '';
+        // Look for requests in review feedback
+        const requestPatterns = [
+            /include (.+?) (output|evidence|in evidence)/gi,
+            /run (.+?) (and provide|and show|to verify)/gi,
+            /provide (.+?) (evidence|output)/gi,
+            /missing (.+?) (output|evidence)/gi,
+        ];
+        for (const pattern of requestPatterns) {
+            const matches = content.match(pattern);
+            if (matches) {
+                reviewRequests.push(...matches.slice(0, 2));
+            }
+        }
+    }
+    // Extract evidence provided
+    const evidenceProvided = [];
+    for (const event of implementEvents.slice(-3)) {
+        const content = event.response || event.content || '';
+        // Look for evidence mentions
+        if (content.includes('typecheck'))
+            evidenceProvided.push('typecheck');
+        if (content.includes('test') && content.includes('pass'))
+            evidenceProvided.push('tests');
+        if (content.includes('build'))
+            evidenceProvided.push('build');
+    }
+    return {
+        loopCount,
+        reviewRequests: [...new Set(reviewRequests)].slice(0, 5),
+        evidenceProvided: [...new Set(evidenceProvided)]
+    };
+}
+/**
+ * Generate unmet checks based on review context
+ */
+export function generateUnmetChecks(reviewRequests, evidenceProvided) {
+    const unmet = [];
+    // Check for common verification patterns
+    const checkPatterns = [
+        { keyword: 'typecheck', check: 'typecheck_output_missing' },
+        { keyword: 'test', check: 'test_output_missing' },
+        { keyword: 'build', check: 'build_output_missing' },
+        { keyword: 'lint', check: 'lint_output_missing' },
+        { keyword: 'coverage', check: 'test_coverage_not_reported' },
+    ];
+    for (const { keyword, check } of checkPatterns) {
+        const requested = reviewRequests.some(r => r.toLowerCase().includes(keyword));
+        const provided = evidenceProvided.includes(keyword);
+        if (requested && !provided) {
+            unmet.push(check);
+        }
+    }
+    // If nothing specific found but we have review requests, add generic
+    if (unmet.length === 0 && reviewRequests.length > 0) {
+        unmet.push('evidence_incomplete');
+    }
+    return unmet;
+}
+/**
+ * Generate suggested actions based on stop reason
+ */
+export function generateSuggestedActions(stopReason, runId, unmetChecks) {
+    const actions = [];
+    if (stopReason === 'review_loop_detected') {
+        // Add specific commands based on unmet checks
+        for (const check of unmetChecks) {
+            switch (check) {
+                case 'typecheck_output_missing':
+                    actions.push({
+                        command: `npm run typecheck 2>&1 | tee .runr/runs/${runId}/typecheck.log`,
+                        description: 'Run typecheck and capture output'
+                    });
+                    break;
+                case 'test_output_missing':
+                    actions.push({
+                        command: `npm test 2>&1 | tee .runr/runs/${runId}/test.log`,
+                        description: 'Run tests and capture output'
+                    });
+                    break;
+                case 'build_output_missing':
+                    actions.push({
+                        command: `npm run build 2>&1 | tee .runr/runs/${runId}/build.log`,
+                        description: 'Run build and capture output'
+                    });
+                    break;
+                case 'lint_output_missing':
+                    actions.push({
+                        command: `npm run lint 2>&1 | tee .runr/runs/${runId}/lint.log`,
+                        description: 'Run lint and capture output'
+                    });
+                    break;
+            }
+        }
+        // Always suggest resume or intervene
+        actions.push({
+            command: `runr resume ${runId}`,
+            description: 'Resume the run after fixing issues'
+        });
+        actions.push({
+            command: `runr intervene ${runId} --reason review_loop --note "Fixed manually" --cmd "npm run build"`,
+            description: 'Record manual intervention and continue'
+        });
+    }
+    else if (stopReason === 'stalled_timeout') {
+        actions.push({
+            command: `runr resume ${runId}`,
+            description: 'Resume the run (may have recovered)'
+        });
+        actions.push({
+            command: `runr intervene ${runId} --reason stalled_timeout --note "Completed manually"`,
+            description: 'Record manual completion'
+        });
+    }
+    else if (stopReason === 'verification_failed') {
+        actions.push({
+            command: `npm run build && npm test`,
+            description: 'Fix failing verification commands'
+        });
+        actions.push({
+            command: `runr resume ${runId}`,
+            description: 'Resume after fixing'
+        });
+    }
+    return actions;
+}
+/**
+ * Generate stop diagnostics from timeline
+ */
+export function generateStopDiagnostics(runStorePath, runId, stopReason) {
+    const timelinePath = path.join(runStorePath, 'timeline.jsonl');
+    const events = parseTimeline(timelinePath);
+    // Base diagnostics
+    const diagnostics = {
+        stop_reason: stopReason,
+        explanation: getExplanation(stopReason),
+        suggested_actions: []
+    };
+    if (stopReason === 'review_loop_detected') {
+        const context = extractReviewLoopContext(events);
+        diagnostics.loop_count = context.loopCount;
+        diagnostics.last_review_requests = context.reviewRequests;
+        diagnostics.last_evidence_provided = context.evidenceProvided;
+        diagnostics.unmet_checks = generateUnmetChecks(context.reviewRequests, context.evidenceProvided);
+    }
+    else if (stopReason === 'stalled_timeout') {
+        const lastEvent = events[events.length - 1];
+        if (lastEvent) {
+            diagnostics.last_activity_at = lastEvent.timestamp;
+            diagnostics.time_since_activity_ms = Date.now() - new Date(lastEvent.timestamp).getTime();
+        }
+    }
+    diagnostics.suggested_actions = generateSuggestedActions(stopReason, runId, diagnostics.unmet_checks || []);
+    return diagnostics;
+}
+/**
+ * Get human-readable explanation for stop reason
+ */
+function getExplanation(stopReason) {
+    switch (stopReason) {
+        case 'review_loop_detected':
+            return 'The run exceeded the maximum review rounds without passing all checks. ' +
+                'The reviewer kept requesting changes that were not fully addressed.';
+        case 'stalled_timeout':
+            return 'The run timed out waiting for a response from the worker. ' +
+                'The worker may have hung or encountered an unrecoverable error.';
+        case 'verification_failed':
+            return 'The verification commands failed. The implementation may have errors ' +
+                'that need to be fixed before the run can continue.';
+        case 'scope_violation':
+            return 'The implementation attempted to modify files outside the allowed scope. ' +
+                'Update the task scope or intervene to record the necessary changes.';
+        default:
+            return `The run stopped with reason: ${stopReason}`;
+    }
+}
+/**
+ * Write diagnostics to file
+ */
+export function writeStopDiagnostics(runStorePath, diagnostics) {
+    const diagnosticsPath = path.join(runStorePath, 'stop_diagnostics.json');
+    fs.writeFileSync(diagnosticsPath, JSON.stringify(diagnostics, null, 2));
+    return diagnosticsPath;
+}
+/**
+ * Print diagnostics to console
+ */
+export function printStopDiagnostics(runId, diagnostics) {
+    console.log('');
+    console.log(`Run ${runId} STOPPED: ${diagnostics.stop_reason}`);
+    console.log('');
+    console.log('Diagnostics:');
+    if (diagnostics.loop_count) {
+        console.log(`  Loop count: ${diagnostics.loop_count}`);
+    }
+    if (diagnostics.last_review_requests && diagnostics.last_review_requests.length > 0) {
+        console.log(`  Last reviewer requests:`);
+        for (const req of diagnostics.last_review_requests) {
+            console.log(`    - "${req}"`);
+        }
+    }
+    if (diagnostics.unmet_checks && diagnostics.unmet_checks.length > 0) {
+        console.log('');
+        console.log('  Unmet checks:');
+        for (const check of diagnostics.unmet_checks) {
+            console.log(`    - ${check}`);
+        }
+    }
+    if (diagnostics.time_since_activity_ms) {
+        const mins = Math.round(diagnostics.time_since_activity_ms / 60000);
+        console.log(`  Time since last activity: ${mins} minutes`);
+    }
+    if (diagnostics.suggested_actions.length > 0) {
+        console.log('');
+        console.log('  Suggested actions:');
+        diagnostics.suggested_actions.forEach((action, i) => {
+            console.log(`    ${i + 1}. ${action.description}`);
+            if (action.command) {
+                console.log(`       Run: ${action.command}`);
+            }
+            if (action.edit) {
+                console.log(`       Edit: ${action.edit}`);
+            }
+        });
+    }
+    console.log('');
+}

package/dist/diagnostics/stop-explainer.js

@@ -0,0 +1,267 @@
+/**
+ * Stop Diagnostics - Explains why a run stopped and suggests fixes.
+ *
+ * When review_loop_detected or other STOPPED states occur, this module
+ * analyzes the timeline and provides actionable guidance.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Parse timeline.jsonl file
+ */
+export function parseTimeline(timelinePath) {
+    if (!fs.existsSync(timelinePath)) {
+        return [];
+    }
+    const content = fs.readFileSync(timelinePath, 'utf-8');
+    const events = [];
+    for (const line of content.split('\n')) {
+        if (line.trim()) {
+            try {
+                events.push(JSON.parse(line));
+            }
+            catch {
+                // Skip malformed lines
+            }
+        }
+    }
+    return events;
+}
+/**
+ * Extract review loop context from timeline
+ */
+export function extractReviewLoopContext(events) {
+    const reviewEvents = events.filter(e => e.event_type === 'worker_response' && e.phase === 'review');
+    const implementEvents = events.filter(e => e.event_type === 'worker_response' && e.phase === 'implement');
+    // Count review rounds
+    const loopCount = Math.max(1, reviewEvents.length);
+    // Extract review requests (look for common patterns)
+    const reviewRequests = [];
+    for (const event of reviewEvents.slice(-3)) {
+        const content = event.response || event.content || '';
+        // Look for requests in review feedback
+        const requestPatterns = [
+            /include (.+?) (output|evidence|in evidence)/gi,
+            /run (.+?) (and provide|and show|to verify)/gi,
+            /provide (.+?) (evidence|output)/gi,
+            /missing (.+?) (output|evidence)/gi,
+        ];
+        for (const pattern of requestPatterns) {
+            const matches = content.match(pattern);
+            if (matches) {
+                reviewRequests.push(...matches.slice(0, 2));
+            }
+        }
+    }
+    // Extract evidence provided
+    const evidenceProvided = [];
+    for (const event of implementEvents.slice(-3)) {
+        const content = event.response || event.content || '';
+        // Look for evidence mentions
+        if (content.includes('typecheck'))
+            evidenceProvided.push('typecheck');
+        if (content.includes('test') && content.includes('pass'))
+            evidenceProvided.push('tests');
+        if (content.includes('build'))
+            evidenceProvided.push('build');
+    }
+    return {
+        loopCount,
+        reviewRequests: [...new Set(reviewRequests)].slice(0, 5),
+        evidenceProvided: [...new Set(evidenceProvided)]
+    };
+}
+/**
+ * Generate unmet checks based on review context
+ */
+export function generateUnmetChecks(reviewRequests, evidenceProvided) {
+    const unmet = [];
+    // Check for common verification patterns
+    const checkPatterns = [
+        { keyword: 'typecheck', check: 'typecheck_output_missing' },
+        { keyword: 'test', check: 'test_output_missing' },
+        { keyword: 'build', check: 'build_output_missing' },
+        { keyword: 'lint', check: 'lint_output_missing' },
+        { keyword: 'coverage', check: 'test_coverage_not_reported' },
+    ];
+    for (const { keyword, check } of checkPatterns) {
+        const requested = reviewRequests.some(r => r.toLowerCase().includes(keyword));
+        const provided = evidenceProvided.includes(keyword);
+        if (requested && !provided) {
+            unmet.push(check);
+        }
+    }
+    // If nothing specific found but we have review requests, add generic
+    if (unmet.length === 0 && reviewRequests.length > 0) {
+        unmet.push('evidence_incomplete');
+    }
+    return unmet;
+}
+/**
+ * Generate suggested actions based on stop reason
+ */
+export function generateSuggestedActions(stopReason, runId, unmetChecks) {
+    const actions = [];
+    if (stopReason === 'review_loop_detected') {
+        // Add specific commands based on unmet checks
+        for (const check of unmetChecks) {
+            switch (check) {
+                case 'typecheck_output_missing':
+                    actions.push({
+                        command: `npm run typecheck 2>&1 | tee .runr/runs/${runId}/typecheck.log`,
+                        description: 'Run typecheck and capture output'
+                    });
+                    break;
+                case 'test_output_missing':
+                    actions.push({
+                        command: `npm test 2>&1 | tee .runr/runs/${runId}/test.log`,
+                        description: 'Run tests and capture output'
+                    });
+                    break;
+                case 'build_output_missing':
+                    actions.push({
+                        command: `npm run build 2>&1 | tee .runr/runs/${runId}/build.log`,
+                        description: 'Run build and capture output'
+                    });
+                    break;
+                case 'lint_output_missing':
+                    actions.push({
+                        command: `npm run lint 2>&1 | tee .runr/runs/${runId}/lint.log`,
+                        description: 'Run lint and capture output'
+                    });
+                    break;
+            }
+        }
+        // Always suggest resume or intervene
+        actions.push({
+            command: `runr resume ${runId}`,
+            description: 'Resume the run after fixing issues'
+        });
+        actions.push({
+            command: `runr intervene ${runId} --reason review_loop --note "Fixed manually" --cmd "npm run build"`,
+            description: 'Record manual intervention and continue'
+        });
+    }
+    else if (stopReason === 'stalled_timeout') {
+        actions.push({
+            command: `runr resume ${runId}`,
+            description: 'Resume the run (may have recovered)'
+        });
+        actions.push({
+            command: `runr intervene ${runId} --reason stalled_timeout --note "Completed manually"`,
+            description: 'Record manual completion'
+        });
+    }
+    else if (stopReason === 'verification_failed') {
+        actions.push({
+            command: `npm run build && npm test`,
+            description: 'Fix failing verification commands'
+        });
+        actions.push({
+            command: `runr resume ${runId}`,
+            description: 'Resume after fixing'
+        });
+    }
+    return actions;
+}
+/**
+ * Generate stop diagnostics from timeline
+ */
+export function generateStopDiagnostics(runStorePath, runId, stopReason) {
+    const timelinePath = path.join(runStorePath, 'timeline.jsonl');
+    const events = parseTimeline(timelinePath);
+    // Base diagnostics
+    const diagnostics = {
+        stop_reason: stopReason,
+        explanation: getExplanation(stopReason),
+        suggested_actions: []
+    };
+    if (stopReason === 'review_loop_detected') {
+        const context = extractReviewLoopContext(events);
+        diagnostics.loop_count = context.loopCount;
+        diagnostics.last_review_requests = context.reviewRequests;
+        diagnostics.last_evidence_provided = context.evidenceProvided;
+        diagnostics.unmet_checks = generateUnmetChecks(context.reviewRequests, context.evidenceProvided);
+    }
+    else if (stopReason === 'stalled_timeout') {
+        const lastEvent = events[events.length - 1];
+        if (lastEvent) {
+            diagnostics.last_activity_at = lastEvent.timestamp;
+            diagnostics.time_since_activity_ms = Date.now() - new Date(lastEvent.timestamp).getTime();
+        }
+    }
+    diagnostics.suggested_actions = generateSuggestedActions(stopReason, runId, diagnostics.unmet_checks || []);
+    return diagnostics;
+}
+/**
+ * Get human-readable explanation for stop reason
+ */
+function getExplanation(stopReason) {
+    switch (stopReason) {
+        case 'review_loop_detected':
+            return 'The run exceeded the maximum review rounds without passing all checks. ' +
+                'The reviewer kept requesting changes that were not fully addressed.';
+        case 'stalled_timeout':
+            return 'The run timed out waiting for a response from the worker. ' +
+                'The worker may have hung or encountered an unrecoverable error.';
+        case 'verification_failed':
+            return 'The verification commands failed. The implementation may have errors ' +
+                'that need to be fixed before the run can continue.';
+        case 'scope_violation':
+            return 'The implementation attempted to modify files outside the allowed scope. ' +
+                'Update the task scope or intervene to record the necessary changes.';
+        default:
+            return `The run stopped with reason: ${stopReason}`;
+    }
+}
+/**
+ * Write diagnostics to file
+ */
+export function writeStopDiagnostics(runStorePath, diagnostics) {
+    const diagnosticsPath = path.join(runStorePath, 'stop_diagnostics.json');
+    fs.writeFileSync(diagnosticsPath, JSON.stringify(diagnostics, null, 2));
+    return diagnosticsPath;
+}
+/**
+ * Print diagnostics to console
+ */
+export function printStopDiagnostics(runId, diagnostics) {
+    console.log('');
+    console.log(`Run ${runId} STOPPED: ${diagnostics.stop_reason}`);
+    console.log('');
+    console.log('Diagnostics:');
+    if (diagnostics.loop_count) {
+        console.log(`  Loop count: ${diagnostics.loop_count}`);
+    }
+    if (diagnostics.last_review_requests && diagnostics.last_review_requests.length > 0) {
+        console.log(`  Last reviewer requests:`);
+        for (const req of diagnostics.last_review_requests) {
+            console.log(`    - "${req}"`);
+        }
+    }
+    if (diagnostics.unmet_checks && diagnostics.unmet_checks.length > 0) {
+        console.log('');
+        console.log('  Unmet checks:');
+        for (const check of diagnostics.unmet_checks) {
+            console.log(`    - ${check}`);
+        }
+    }
+    if (diagnostics.time_since_activity_ms) {
+        const mins = Math.round(diagnostics.time_since_activity_ms / 60000);
+        console.log(`  Time since last activity: ${mins} minutes`);
+    }
+    if (diagnostics.suggested_actions.length > 0) {
+        console.log('');
+        console.log('  Suggested actions:');
+        diagnostics.suggested_actions.forEach((action, i) => {
+            console.log(`    ${i + 1}. ${action.description}`);
+            if (action.command) {
+                console.log(`       Run: ${action.command}`);
+            }
+            if (action.edit) {
+                console.log(`       Edit: ${action.edit}`);
+            }
+        });
+    }
+    console.log('');
+}

package/dist/guards/checkpoint.js

@@ -0,0 +1,119 @@
+/**
+ * Checkpoint commit detection and protection.
+ *
+ * Prevents accidental amendment of checkpoint commits,
+ * which would rewrite verified/audited history.
+ */
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { getRunsRoot } from '../store/runs-root.js';
+/**
+ * Detect if HEAD is a Runr checkpoint commit.
+ *
+ * Detection methods (in order):
+ * 1. Subject prefix: "chore(runr): checkpoint"
+ * 2. Trailer: "Runr-Checkpoint: true"
+ * 3. SHA in any run's state.json checkpoint_commit_sha
+ */
+export function isCheckpointCommit(repoPath) {
+    try {
+        // Get HEAD commit info
+        const format = '%H%x00%s%x00%(trailers:key=Runr-Checkpoint,valueonly)%x00%(trailers:key=Runr-Run-Id,valueonly)';
+        const output = execSync(`git log -1 --format="${format}" HEAD`, {
+            cwd: repoPath,
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe']
+        }).trim();
+        const [sha, subject, checkpointTrailer, runIdTrailer] = output.split('\x00');
+        // Method 1: Check subject prefix
+        if (subject.startsWith('chore(runr): checkpoint')) {
+            const runIdMatch = subject.match(/checkpoint (\d{14})/);
+            return {
+                isCheckpoint: true,
+                sha,
+                runId: runIdMatch?.[1] || runIdTrailer?.trim(),
+                detectedBy: 'subject'
+            };
+        }
+        // Method 2: Check trailer
+        if (checkpointTrailer?.trim().toLowerCase() === 'true') {
+            return {
+                isCheckpoint: true,
+                sha,
+                runId: runIdTrailer?.trim(),
+                detectedBy: 'trailer'
+            };
+        }
+        // Method 3: Check state.json files
+        const runsRoot = getRunsRoot(repoPath);
+        if (fs.existsSync(runsRoot)) {
+            try {
+                const runDirs = fs.readdirSync(runsRoot, { withFileTypes: true })
+                    .filter(d => d.isDirectory() && /^\d{14}$/.test(d.name));
+                for (const runDir of runDirs) {
+                    const statePath = path.join(runsRoot, runDir.name, 'state.json');
+                    if (fs.existsSync(statePath)) {
+                        try {
+                            const state = JSON.parse(fs.readFileSync(statePath, 'utf-8'));
+                            if (state.checkpoint_commit_sha === sha) {
+                                return {
+                                    isCheckpoint: true,
+                                    sha,
+                                    runId: runDir.name,
+                                    detectedBy: 'state'
+                                };
+                            }
+                        }
+                        catch { /* ignore parse errors */ }
+                    }
+                }
+            }
+            catch { /* ignore read errors */ }
+        }
+        // Not a checkpoint
+        return { isCheckpoint: false, sha };
+    }
+    catch {
+        // Git command failed (no commits, not a repo, etc.)
+        return { isCheckpoint: false, sha: '' };
+    }
+}
+/**
+ * Check if amending HEAD is allowed.
+ *
+ * Blocks amendment if HEAD is a checkpoint commit,
+ * unless --force is provided.
+ */
+export function checkAmendAllowed(repoPath, forceOverride = false, ledgerMode = false) {
+    const info = isCheckpointCommit(repoPath);
+    if (!info.isCheckpoint) {
+        return { allowed: true, checkpointInfo: info };
+    }
+    if (forceOverride) {
+        // Force allowed, but emit warning
+        return {
+            allowed: true,
+            checkpointInfo: info,
+            error: `Warning: Amending checkpoint commit ${info.sha.slice(0, 7)} (run ${info.runId || 'unknown'}).
+This rewrites audited history. Proceed with caution.`
+        };
+    }
+    // Build error message
+    let message = `Refusing to amend: HEAD is a Runr checkpoint commit (verified work).
+This would rewrite audited history.`;
+    if (ledgerMode) {
+        message += `
+
+Ledger mode: checkpoint history is immutable.`;
+    }
+    message += `
+
+If you really mean it: re-run with --force.
+Better alternative: create a follow-up commit with trailers instead.`;
+    return {
+        allowed: false,
+        error: message,
+        checkpointInfo: info
+    };
+}