@weldr/runr 0.3.1 → 0.7.2

package/dist/commands/submit.js

@@ -0,0 +1,374 @@
+import { execa } from 'execa';
+import path from 'node:path';
+import fs from 'node:fs';
+import { RunStore } from '../store/run-store.js';
+import { loadConfig, resolveConfigPath } from '../config/load.js';
+import { clearActiveState } from './hooks.js';
+/**
+ * Check if git object exists locally.
+ */
+async function objectExists(repoPath, sha) {
+    try {
+        await execa('git', ['cat-file', '-e', `${sha}^{commit}`], { cwd: repoPath });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if branch exists.
+ */
+async function branchExists(repoPath, branch) {
+    try {
+        await execa('git', ['show-ref', '--verify', '--quiet', `refs/heads/${branch}`], {
+            cwd: repoPath
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Check if working tree is clean.
+ */
+async function isWorkingTreeClean(repoPath) {
+    const result = await execa('git', ['status', '--porcelain'], { cwd: repoPath });
+    return result.stdout.trim().length === 0;
+}
+/**
+ * Get current branch name.
+ */
+async function getCurrentBranch(repoPath) {
+    const result = await execa('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: repoPath });
+    return result.stdout.trim();
+}
+/**
+ * Get conflicted files (sorted alphabetically).
+ */
+async function getConflictedFiles(repoPath) {
+    try {
+        const result = await execa('git', ['diff', '--name-only', '--diff-filter=U'], {
+            cwd: repoPath
+        });
+        return result.stdout
+            .split('\n')
+            .map(f => f.trim())
+            .filter(Boolean)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Get files changed in a commit.
+ */
+async function getFilesInCommit(repoPath, sha) {
+    try {
+        const result = await execa('git', ['diff-tree', '--no-commit-id', '--name-only', '-r', sha], {
+            cwd: repoPath
+        });
+        return result.stdout
+            .split('\n')
+            .map(f => f.trim())
+            .filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Check if cherry-pick would cause conflict (dry-run).
+ */
+async function wouldCherryPickConflict(repoPath, targetBranch, sha) {
+    try {
+        // Try cherry-pick with --no-commit to detect conflicts without making changes
+        await execa('git', ['cherry-pick', '--no-commit', sha], { cwd: repoPath });
+        // If successful, reset and report no conflicts
+        await execa('git', ['reset', '--hard', 'HEAD'], { cwd: repoPath });
+        return { conflicts: false, files: [] };
+    }
+    catch {
+        // Get conflicted files
+        const files = await getConflictedFiles(repoPath);
+        // Abort and reset
+        try {
+            await execa('git', ['cherry-pick', '--abort'], { cwd: repoPath });
+        }
+        catch {
+            // Reset as fallback
+            await execa('git', ['reset', '--hard', 'HEAD'], { cwd: repoPath });
+        }
+        return { conflicts: true, files };
+    }
+}
+/**
+ * Emit validation failure event and exit.
+ */
+function failValidation(runStore, runId, reason, details) {
+    runStore.appendEvent({
+        type: 'submit_validation_failed',
+        source: 'submit',
+        payload: {
+            run_id: runId,
+            reason,
+            details
+        }
+    });
+    console.error(`Submit blocked: ${reason}`);
+    console.error(details);
+    process.exitCode = 1;
+}
+/**
+ * Submit command: Cherry-pick verified checkpoint to integration branch.
+ */
+export async function submitCommand(options) {
+    const runStore = RunStore.init(options.runId, options.repo);
+    // Load run state
+    let state;
+    try {
+        state = runStore.readState();
+    }
+    catch {
+        console.error(`Error: run state not found for ${options.runId}`);
+        process.exitCode = 1;
+        return;
+    }
+    // Load config with workflow settings
+    const config = loadConfig(resolveConfigPath(options.repo, options.config));
+    // Get workflow config (use safe defaults if not configured)
+    const workflow = config.workflow ?? {
+        profile: 'solo',
+        mode: 'flow',
+        integration_branch: 'dev',
+        require_clean_tree: true,
+        require_verification: true,
+        submit_strategy: 'cherry-pick'
+    };
+    // Validation: checkpoint exists in state
+    const checkpointSha = state.checkpoint_commit_sha;
+    if (!checkpointSha) {
+        failValidation(runStore, options.runId, 'no_checkpoint', 'Run has no checkpoint_commit_sha in state.json');
+        return;
+    }
+    // Validation: checkpoint exists as git object
+    if (!(await objectExists(options.repo, checkpointSha))) {
+        failValidation(runStore, options.runId, 'run_not_ready', `Checkpoint commit not found locally: ${checkpointSha}`);
+        return;
+    }
+    // Validation: verification evidence (if required)
+    if (workflow.require_verification) {
+        if (!state.last_verification_evidence) {
+            failValidation(runStore, options.runId, 'verification_missing', 'Verification required but last_verification_evidence is missing');
+            return;
+        }
+    }
+    // Validation: clean working tree (if required)
+    if (workflow.require_clean_tree) {
+        if (!(await isWorkingTreeClean(options.repo))) {
+            failValidation(runStore, options.runId, 'dirty_tree', 'Working tree is not clean (uncommitted changes present)');
+            return;
+        }
+    }
+    // Validation: target branch exists
+    const targetBranch = options.to ?? workflow.integration_branch;
+    if (!(await branchExists(options.repo, targetBranch))) {
+        failValidation(runStore, options.runId, 'target_branch_missing', `Target branch does not exist: ${targetBranch}`);
+        return;
+    }
+    // DRY RUN: print plan and check for conflicts (no events, no changes)
+    if (options.dryRun) {
+        console.log('Submit plan (dry-run):');
+        console.log(`  run_id: ${options.runId}`);
+        console.log(`  checkpoint: ${checkpointSha}`);
+        console.log(`  target: ${targetBranch}`);
+        console.log(`  strategy: cherry-pick`);
+        console.log(`  push: ${options.push ? 'yes' : 'no'}`);
+        // Check for potential conflicts without making changes
+        const startingBranch = await getCurrentBranch(options.repo);
+        try {
+            await execa('git', ['checkout', targetBranch], { cwd: options.repo });
+            const conflictCheck = await wouldCherryPickConflict(options.repo, targetBranch, checkpointSha);
+            if (conflictCheck.conflicts) {
+                console.log('');
+                console.log('  ⚠️  Would conflict:');
+                for (const file of conflictCheck.files) {
+                    console.log(`      - ${file}`);
+                }
+            }
+            else {
+                console.log('');
+                console.log('  ✓ No conflicts detected');
+            }
+        }
+        finally {
+            // Always restore starting branch
+            try {
+                await execa('git', ['checkout', startingBranch], { cwd: options.repo });
+            }
+            catch {
+                // Best effort
+            }
+        }
+        return;
+    }
+    // Capture starting branch for restoration
+    const startingBranch = await getCurrentBranch(options.repo);
+    try {
+        // Checkout target branch
+        await execa('git', ['checkout', targetBranch], { cwd: options.repo });
+        // Cherry-pick checkpoint
+        try {
+            await execa('git', ['cherry-pick', checkpointSha], { cwd: options.repo });
+        }
+        catch {
+            // Get conflicted files
+            const conflictedFiles = await getConflictedFiles(options.repo);
+            // Abort cherry-pick
+            try {
+                await execa('git', ['cherry-pick', '--abort'], { cwd: options.repo });
+            }
+            catch {
+                // Ignore abort errors
+            }
+            // Restore starting branch (best-effort)
+            try {
+                await execa('git', ['checkout', startingBranch], { cwd: options.repo });
+            }
+            catch {
+                // Ignore restoration errors
+            }
+            // Verify tree is actually clean after abort
+            const treeClean = await isWorkingTreeClean(options.repo);
+            const currentBranch = await getCurrentBranch(options.repo);
+            const branchRestored = currentBranch === startingBranch;
+            // Log warnings if invariants fail
+            if (!branchRestored) {
+                console.warn(`Warning: Could not restore branch. Expected ${startingBranch}, got ${currentBranch}`);
+            }
+            if (!treeClean) {
+                console.warn('Warning: Working tree is not clean after conflict cleanup');
+            }
+            // Emit enhanced conflict event
+            runStore.appendEvent({
+                type: 'submit_conflict',
+                source: 'submit',
+                payload: {
+                    run_id: options.runId,
+                    checkpoint_sha: checkpointSha,
+                    target_branch: targetBranch,
+                    conflicted_files: conflictedFiles,
+                    recovery_branch: currentBranch,
+                    recovery_state: treeClean ? 'clean' : 'dirty',
+                    suggested_commands: [
+                        `git checkout ${targetBranch}`,
+                        `git cherry-pick ${checkpointSha}`,
+                        '# resolve conflicts',
+                        'git add .',
+                        'git cherry-pick --continue'
+                    ]
+                }
+            });
+            // Print conflict message with recovery recipe (exact spec format)
+            console.error('');
+            console.error('Cherry-pick conflict detected.');
+            console.error('');
+            console.error(`Checkpoint: ${checkpointSha}`);
+            console.error(`Target: ${targetBranch}`);
+            console.error('');
+            console.error('Conflicted files:');
+            for (const file of conflictedFiles) {
+                console.error(`  - ${file}`);
+            }
+            console.error('');
+            // Recovery state with checkmarks
+            console.error('Recovery state:');
+            if (branchRestored) {
+                console.error(`  ✓ Branch restored to ${startingBranch}`);
+            }
+            else {
+                console.error(`  ✗ Branch NOT restored (currently on ${currentBranch})`);
+            }
+            if (treeClean) {
+                console.error('  ✓ Working tree is clean');
+            }
+            else {
+                console.error('  ✗ Working tree is NOT clean');
+            }
+            console.error('');
+            // Copy-paste ready recovery commands
+            console.error('To resolve manually:');
+            console.error(`  git checkout ${targetBranch}`);
+            console.error(`  git cherry-pick ${checkpointSha}`);
+            console.error('  # resolve conflicts');
+            console.error('  git add .');
+            console.error('  git cherry-pick --continue');
+            // Conditional CHANGELOG tip:
+            // - Only show if CHANGELOG.md exists
+            // - Only show if checkpoint doesn't already modify CHANGELOG.md
+            // - Suppress if CHANGELOG is in conflicted files (already mentioned above)
+            const changelogPath = path.join(options.repo, 'CHANGELOG.md');
+            const changelogExists = fs.existsSync(changelogPath);
+            const checkpointModifiesChangelog = (await getFilesInCommit(options.repo, checkpointSha))
+                .some(f => f.toLowerCase().includes('changelog'));
+            const changelogInConflicts = conflictedFiles.some(f => f.toLowerCase().includes('changelog'));
+            if (changelogExists && !checkpointModifiesChangelog && !changelogInConflicts) {
+                console.error('');
+                console.error('If this adds new features, consider updating CHANGELOG.md.');
+            }
+            else if (changelogInConflicts) {
+                console.error('');
+                console.error('Tip: CHANGELOG.md conflicts are common; consider moving');
+                console.error('     changelog updates into a dedicated task.');
+            }
+            console.error('');
+            process.exitCode = 1;
+            return;
+        }
+        // Push to origin (if requested)
+        if (options.push) {
+            try {
+                await execa('git', ['push', 'origin', targetBranch], { cwd: options.repo });
+            }
+            catch (error) {
+                console.error('Warning: cherry-pick succeeded but push failed');
+                console.error(String(error));
+                // Don't fail - cherry-pick succeeded, which is the primary goal
+            }
+        }
+        // Emit success event
+        runStore.appendEvent({
+            type: 'run_submitted',
+            source: 'submit',
+            payload: {
+                run_id: options.runId,
+                checkpoint_sha: checkpointSha,
+                target_branch: targetBranch,
+                strategy: 'cherry-pick',
+                submitted_at: new Date().toISOString()
+            }
+        });
+        // Clear active state sentinel (run is now submitted)
+        clearActiveState(options.repo);
+        console.log(`✓ Submitted ${checkpointSha} to ${targetBranch}`);
+    }
+    catch (error) {
+        // Git error (not conflict)
+        failValidation(runStore, options.runId, 'git_error', `Git error: ${String(error)}`);
+        return;
+    }
+    finally {
+        // Always restore starting branch (best-effort)
+        try {
+            const currentBranch = await getCurrentBranch(options.repo);
+            if (currentBranch !== startingBranch) {
+                await execa('git', ['checkout', startingBranch], { cwd: options.repo });
+            }
+        }
+        catch {
+            // Ignore restoration errors (best-effort)
+        }
+    }
+}

package/dist/config/schema.js

@@ -149,6 +149,30 @@ const resilienceSchema = z.object({
     /** Maximum review rounds per milestone before stopping with review_loop_detected (default: 2) */
     max_review_rounds: z.number().int().positive().default(2)
 });
+// Receipts configuration for output capture and redaction
+const receiptsConfigSchema = z.object({
+    /** Enable secret redaction in command output */
+    redact: z.boolean().default(true),
+    /** How much command output to capture: full, truncated, or metadata_only */
+    capture_cmd_output: z.enum(['full', 'truncated', 'metadata_only']).default('truncated'),
+    /** Maximum output bytes to store (when truncated) */
+    max_output_bytes: z.number().int().positive().default(10240) // 10KB
+});
+// Workflow configuration for integration strategy
+const workflowConfigSchema = z.object({
+    /** Workflow profile preset (solo/pr/trunk) */
+    profile: z.enum(['solo', 'pr', 'trunk']).default('solo'),
+    /** Workflow mode: flow (permissive) or ledger (strict) */
+    mode: z.enum(['flow', 'ledger']).default('flow'),
+    /** Target branch for integrating verified checkpoints */
+    integration_branch: z.string(),
+    /** Submit strategy (v1: cherry-pick only) */
+    submit_strategy: z.literal('cherry-pick').default('cherry-pick'),
+    /** Require clean working tree before submit */
+    require_clean_tree: z.boolean().default(true),
+    /** Require verification evidence before submit */
+    require_verification: z.boolean().default(true)
+});
 export const agentConfigSchema = z.object({
     agent: agentSchema,
     repo: repoSchema.default({}),
@@ -156,5 +180,41 @@ export const agentConfigSchema = z.object({
     verification: verificationSchema,
     workers: workersSchema.default({}),
     phases: phasesSchema.default({}),
-    resilience: resilienceSchema.default({})
+    resilience: resilienceSchema.default({}),
+    workflow: workflowConfigSchema.optional(),
+    receipts: receiptsConfigSchema.default({})
 });
+/**
+ * Get default workflow config values for a given profile.
+ */
+export function getWorkflowProfileDefaults(profile) {
+    switch (profile) {
+        case 'solo':
+            return {
+                profile: 'solo',
+                mode: 'flow',
+                integration_branch: 'dev',
+                submit_strategy: 'cherry-pick',
+                require_clean_tree: true,
+                require_verification: true
+            };
+        case 'pr':
+            return {
+                profile: 'pr',
+                mode: 'flow',
+                integration_branch: 'main',
+                submit_strategy: 'cherry-pick',
+                require_clean_tree: true,
+                require_verification: false
+            };
+        case 'trunk':
+            return {
+                profile: 'trunk',
+                mode: 'ledger',
+                integration_branch: 'main',
+                submit_strategy: 'cherry-pick',
+                require_clean_tree: true,
+                require_verification: true
+            };
+    }
+}

package/dist/diagnosis/analyzer.js

@@ -20,6 +20,8 @@ function categoryToFamily(category) {
             return 'guard';
         case 'verification_failure':
             return 'verification';
+        case 'review_loop_detected':
+            return 'review';
         case 'worker_parse_failure':
             return 'worker';
         case 'stall_timeout':
@@ -69,7 +71,8 @@ export function diagnoseStop(context) {
         diagnoseStallTimeout(context),
         diagnoseMaxTicksReached(context),
         diagnoseTimeBudgetExceeded(context),
-        diagnoseGuardViolationDirty(context)
+        diagnoseGuardViolationDirty(context),
+        diagnoseReviewLoopDetected(context)
     ].filter((r) => r.confidence > 0);
     // Sort by confidence descending
     results.sort((a, b) => b.confidence - a.confidence);
@@ -647,6 +650,88 @@ function diagnoseGuardViolationDirty(ctx) {
             : []
     };
 }
+/**
+ * Rule 11: Review loop detected
+ */
+function diagnoseReviewLoopDetected(ctx) {
+    const signals = [];
+    let confidence = 0;
+    let pattern = 'unknown';
+    let reviewRounds = 0;
+    let maxReviewRounds = 2;
+    let milestoneIndex = ctx.state.milestone_index;
+    let requestedChanges = [];
+    // Check stop reason or find event
+    if (ctx.state.stop_reason === 'review_loop_detected') {
+        confidence = 0.9;
+        // Find the review_loop_detected event for details
+        const event = ctx.events.find((e) => e.type === 'review_loop_detected');
+        if (event?.payload) {
+            const payload = event.payload;
+            const sameFingerprint = payload.same_fingerprint;
+            reviewRounds = payload.review_rounds ?? 0;
+            maxReviewRounds = payload.max_review_rounds ?? 2;
+            milestoneIndex = payload.milestone_index ?? ctx.state.milestone_index;
+            const lastChanges = payload.last_changes;
+            pattern = sameFingerprint ? 'identical_review_feedback' : 'max_review_rounds_exceeded';
+            if (lastChanges && lastChanges.length > 0) {
+                requestedChanges = lastChanges.slice(0, 2);
+            }
+            signals.push({
+                source: 'event.review_loop_detected',
+                pattern,
+                snippet: `Milestone ${milestoneIndex + 1}, ${reviewRounds} rounds (max: ${maxReviewRounds}), changes: ${requestedChanges.join('; ')}`
+            });
+        }
+        else {
+            // Event not found but stop_reason matches
+            signals.push({
+                source: 'state.stop_reason',
+                pattern: 'review_loop_detected',
+                snippet: ctx.state.last_error?.slice(0, 200) || 'Review loop detected'
+            });
+            confidence = 0.7;
+        }
+    }
+    return {
+        category: 'review_loop_detected',
+        confidence,
+        signals,
+        nextActions: confidence > 0
+            ? [
+                {
+                    title: 'Open run artifacts',
+                    command: `node dist/cli.js open ${ctx.runId}`,
+                    why: 'View all run artifacts including review digest and timeline'
+                },
+                {
+                    title: 'Read review digest',
+                    command: `cat ${ctx.runDir}/review_digest.md`,
+                    why: 'See exact requested changes and review verdict'
+                },
+                {
+                    title: 'View run journal',
+                    command: `node dist/cli.js journal ${ctx.runId}`,
+                    why: 'Understand what the agent did across review rounds'
+                },
+                {
+                    title: 'Rewrite milestone acceptance criteria',
+                    why: 'Make criteria explicit as 3-7 checkboxes with concrete file paths and testable conditions. Loops usually mean the agent cannot translate review feedback into deterministic work.'
+                },
+                {
+                    title: 'Check resume plan',
+                    command: `node dist/cli.js resume ${ctx.runId} --plan`,
+                    why: 'Preview what resume will do before running it'
+                },
+                {
+                    title: 'Run diagnostics',
+                    command: `node dist/cli.js doctor`,
+                    why: 'Verify environment and repository health'
+                }
+            ]
+            : []
+    };
+}
 // ============================================================================
 // Helpers
 // ============================================================================

package/dist/diagnosis/formatter.js

@@ -16,6 +16,7 @@ const categoryDescriptions = {
     time_budget_exceeded: 'Ran out of allocated time.',
     guard_violation_dirty: 'Working directory has uncommitted changes.',
     ownership_violation: 'Task modified files outside its declared owns: paths.',
+    review_loop_detected: 'Review feedback repeated or max review rounds exceeded.',
     unknown: 'Could not determine specific cause.'
 };
 /**
@@ -130,6 +131,8 @@ function getEscalationAdvice(category) {
             return 'For complex tasks, allocate more time upfront: --time 120 or higher.';
         case 'guard_violation_dirty':
             return 'Always use --worktree for runs on repos with active development.';
+        case 'review_loop_detected':
+            return 'If feedback loops persist, split the milestone into smaller steps or add explicit acceptance criteria as checkboxes. Consider adjusting verification commands to catch issues earlier.';
         default:
             return 'Review the timeline and logs carefully. Open an issue if the problem persists.';
     }

package/dist/diagnosis/index.js

@@ -4,3 +4,4 @@
 export * from './types.js';
 export * from './analyzer.js';
 export * from './formatter.js';
+export * from './stop-explainer.js';