@weldr/runr 0.3.0

package/dist/store/runs-root.js

@@ -0,0 +1,126 @@
+import path from 'node:path';
+import fs from 'node:fs';
+// Track if we've shown the deprecation warning this session
+let shownLegacyWarning = false;
+/**
+ * Get all canonical runr paths for a repository.
+ * This is the single source of truth - import this everywhere.
+ *
+ * Layout (new):
+ * ```
+ * .runr/
+ *   runs/<runId>/...
+ *   orchestrations/<orchId>/...
+ * .runr-worktrees/
+ *   <runId>/
+ * ```
+ *
+ * Layout (legacy, still supported):
+ * ```
+ * .agent/
+ *   runs/<runId>/...
+ *   orchestrations/<orchId>/...
+ * .agent-worktrees/
+ *   <runId>/
+ * ```
+ *
+ * Worktrees are stored OUTSIDE .runr/ to avoid conflicts with denylist patterns
+ * like `.runr/**`. This prevents both:
+ * 1. Git-level dirtiness (parent repo seeing worktree as untracked files)
+ * 2. Worker-level confusion (absolute CWD containing `.runr/` matching denylist)
+ *
+ * Override worktrees location with RUNR_WORKTREES_DIR (or legacy AGENT_WORKTREES_DIR) env var.
+ *
+ * @param repoPath - The target repository path
+ * @returns All runr paths as absolute paths
+ */
+export function getRunrPaths(repoPath) {
+    const repoRoot = path.resolve(repoPath);
+    // Check for new .runr/ directory first, fall back to legacy .agent/
+    const newRoot = path.join(repoRoot, '.runr');
+    const legacyRoot = path.join(repoRoot, '.agent');
+    let runrRoot;
+    let usingLegacy = false;
+    if (fs.existsSync(newRoot)) {
+        runrRoot = newRoot;
+    }
+    else if (fs.existsSync(legacyRoot)) {
+        runrRoot = legacyRoot;
+        usingLegacy = true;
+        if (!shownLegacyWarning) {
+            console.warn('\x1b[33m⚠ Deprecation: .agent/ directory is deprecated. Rename to .runr/\x1b[0m');
+            shownLegacyWarning = true;
+        }
+    }
+    else {
+        // Neither exists - default to new location (will be created on first run)
+        runrRoot = newRoot;
+    }
+    // Worktrees: check new env var first, then legacy, then default
+    const worktreesOverride = process.env.RUNR_WORKTREES_DIR || process.env.AGENT_WORKTREES_DIR;
+    let worktreesDir;
+    if (worktreesOverride) {
+        worktreesDir = path.isAbsolute(worktreesOverride)
+            ? worktreesOverride
+            : path.resolve(repoRoot, worktreesOverride);
+    }
+    else if (usingLegacy) {
+        worktreesDir = path.join(repoRoot, '.agent-worktrees');
+    }
+    else {
+        worktreesDir = path.join(repoRoot, '.runr-worktrees');
+    }
+    return {
+        repo_root: repoRoot,
+        runr_root: runrRoot,
+        runs_dir: path.join(runrRoot, 'runs'),
+        worktrees_dir: worktreesDir,
+        orchestrations_dir: path.join(runrRoot, 'orchestrations'),
+        using_legacy: usingLegacy
+    };
+}
+/**
+ * @deprecated Use getRunrPaths instead
+ */
+export function getAgentPaths(repoPath) {
+    return getRunrPaths(repoPath);
+}
+/**
+ * Get the runs root directory for a given repo path.
+ * @deprecated Use getRunrPaths(repoPath).runs_dir instead
+ */
+export function getRunsRoot(repoPath) {
+    return getRunrPaths(repoPath).runs_dir;
+}
+/**
+ * Get the worktrees root directory for a given repo path.
+ */
+export function getWorktreesRoot(repoPath) {
+    return getRunrPaths(repoPath).worktrees_dir;
+}
+/**
+ * Get the run directory for a specific run ID within a repo.
+ *
+ * @param repoPath - The target repository path
+ * @param runId - The run ID (timestamp format)
+ * @returns The absolute path to the run directory
+ */
+export function getRunDir(repoPath, runId) {
+    return path.join(getRunrPaths(repoPath).runs_dir, runId);
+}
+/**
+ * Get the orchestrations root directory.
+ *
+ * @param repoPath - The target repository path
+ * @returns The absolute path to the orchestrations directory
+ */
+export function getOrchestrationsRoot(repoPath) {
+    return getRunrPaths(repoPath).orchestrations_dir;
+}
+/**
+ * Legacy orchestrations path (for migration).
+ * Old location was nested under runs.
+ */
+export function getLegacyOrchestrationsRoot(repoPath) {
+    return path.join(getRunrPaths(repoPath).runs_dir, 'orchestrations');
+}

package/dist/supervisor/__tests__/evidence-gate.test.js

@@ -0,0 +1,111 @@
+import { describe, it, expect } from 'vitest';
+import { validateNoChangesEvidence, formatEvidenceErrors } from '../evidence-gate.js';
+describe('validateNoChangesEvidence', () => {
+    const allowlist = ['src/game/**', 'src/utils/**'];
+    describe('when no evidence provided', () => {
+        it('should fail with no evidence', () => {
+            const result = validateNoChangesEvidence(undefined, allowlist);
+            expect(result.ok).toBe(false);
+            expect(result.errors).toContain('No evidence provided for no_changes_needed claim');
+        });
+        it('should fail with empty evidence object', () => {
+            const result = validateNoChangesEvidence({}, allowlist);
+            expect(result.ok).toBe(false);
+            expect(result.errors.length).toBeGreaterThan(0);
+        });
+    });
+    describe('files_checked evidence', () => {
+        it('should pass with files_checked in scope', () => {
+            const result = validateNoChangesEvidence({ files_checked: ['src/game/combat.ts', 'src/game/utils.ts'] }, allowlist);
+            expect(result.ok).toBe(true);
+            expect(result.satisfied_by).toBe('files_checked');
+        });
+        it('should fail with files_checked out of scope', () => {
+            const result = validateNoChangesEvidence({ files_checked: ['package.json', 'src/game/combat.ts'] }, allowlist);
+            expect(result.ok).toBe(false);
+            expect(result.errors.some(e => e.includes('outside scope'))).toBe(true);
+        });
+        it('should fail with empty files_checked array', () => {
+            const result = validateNoChangesEvidence({ files_checked: [] }, allowlist);
+            expect(result.ok).toBe(false);
+        });
+    });
+    describe('grep_output evidence', () => {
+        it('should pass with non-empty grep_output', () => {
+            const result = validateNoChangesEvidence({ grep_output: 'src/game/combat.ts:42: function alreadyImplemented()' }, allowlist);
+            expect(result.ok).toBe(true);
+            expect(result.satisfied_by).toBe('grep_output');
+        });
+        it('should fail with empty grep_output', () => {
+            const result = validateNoChangesEvidence({ grep_output: '' }, allowlist);
+            expect(result.ok).toBe(false);
+        });
+        it('should fail with whitespace-only grep_output', () => {
+            const result = validateNoChangesEvidence({ grep_output: '   \n\t  ' }, allowlist);
+            expect(result.ok).toBe(false);
+        });
+    });
+    describe('commands_run evidence', () => {
+        it('should pass with commands_run all exit_code 0', () => {
+            const result = validateNoChangesEvidence({
+                commands_run: [
+                    { command: 'grep -r "feature" src/', exit_code: 0 },
+                    { command: 'test -f src/feature.ts', exit_code: 0 }
+                ]
+            }, allowlist);
+            expect(result.ok).toBe(true);
+            expect(result.satisfied_by).toBe('commands_run');
+        });
+        it('should fail with commands_run containing non-zero exit_code', () => {
+            const result = validateNoChangesEvidence({
+                commands_run: [
+                    { command: 'grep -r "feature" src/', exit_code: 1 }
+                ]
+            }, allowlist);
+            expect(result.ok).toBe(false);
+            expect(result.errors.some(e => e.includes('failed commands'))).toBe(true);
+        });
+        it('should fail with empty commands_run array', () => {
+            const result = validateNoChangesEvidence({ commands_run: [] }, allowlist);
+            expect(result.ok).toBe(false);
+        });
+    });
+    describe('priority order', () => {
+        it('should prefer files_checked over grep_output', () => {
+            const result = validateNoChangesEvidence({
+                files_checked: ['src/game/combat.ts'],
+                grep_output: 'some output'
+            }, allowlist);
+            expect(result.ok).toBe(true);
+            expect(result.satisfied_by).toBe('files_checked');
+        });
+        it('should fall back to grep_output if files_checked is out of scope', () => {
+            const result = validateNoChangesEvidence({
+                files_checked: ['package.json'],
+                grep_output: 'some valid output'
+            }, allowlist);
+            expect(result.ok).toBe(true);
+            expect(result.satisfied_by).toBe('grep_output');
+        });
+    });
+});
+describe('formatEvidenceErrors', () => {
+    it('should return empty string for ok result', () => {
+        const result = formatEvidenceErrors({
+            ok: true,
+            errors: [],
+            satisfied_by: 'files_checked'
+        });
+        expect(result).toBe('');
+    });
+    it('should format errors for failed result', () => {
+        const result = formatEvidenceErrors({
+            ok: false,
+            errors: ['No evidence provided', 'files_checked is empty']
+        });
+        expect(result).toContain('Insufficient evidence');
+        expect(result).toContain('No evidence provided');
+        expect(result).toContain('files_checked is empty');
+        expect(result).toContain('Required:');
+    });
+});

package/dist/supervisor/__tests__/ownership.test.js

@@ -0,0 +1,103 @@
+import { describe, it, expect } from 'vitest';
+import { checkOwnership } from '../runner.js';
+describe('checkOwnership', () => {
+    describe('when no ownership declared', () => {
+        it('does not enforce - always returns ok', () => {
+            const result = checkOwnership(['README.md', 'src/index.ts', 'package.json'], [], // no ownership declared
+            ['node_modules/**']);
+            expect(result.ok).toBe(true);
+            expect(result.owned_paths).toEqual([]);
+            expect(result.semantic_changed).toEqual([]);
+            expect(result.violating_files).toEqual([]);
+        });
+        it('does not enforce even with changes outside would-be owns', () => {
+            // This is the key test: tasks without owns should continue to work unchanged
+            const result = checkOwnership(['README.md', 'docs/guide.md', 'src/unrelated.ts'], [], // no ownership - no enforcement
+            []);
+            expect(result.ok).toBe(true);
+            expect(result.violating_files).toEqual([]);
+        });
+    });
+    describe('when ownership declared', () => {
+        it('allows changes within owned paths', () => {
+            const result = checkOwnership(['courses/a/lesson1.md', 'courses/a/lesson2.md'], ['courses/a/**'], []);
+            expect(result.ok).toBe(true);
+            expect(result.owned_paths).toEqual(['courses/a/**']);
+            expect(result.semantic_changed).toEqual(['courses/a/lesson1.md', 'courses/a/lesson2.md']);
+            expect(result.violating_files).toEqual([]);
+        });
+        it('detects violation when changing files outside owned paths', () => {
+            const result = checkOwnership(['courses/a/lesson1.md', 'README.md'], ['courses/a/**'], []);
+            expect(result.ok).toBe(false);
+            expect(result.owned_paths).toEqual(['courses/a/**']);
+            expect(result.semantic_changed).toEqual(['courses/a/lesson1.md', 'README.md']);
+            expect(result.violating_files).toEqual(['README.md']);
+        });
+        it('reports all violating files', () => {
+            const result = checkOwnership(['courses/a/lesson.md', 'README.md', 'docs/guide.md', 'src/index.ts'], ['courses/a/**'], []);
+            expect(result.ok).toBe(false);
+            expect(result.violating_files).toEqual(['README.md', 'docs/guide.md', 'src/index.ts']);
+        });
+        it('supports multiple owned paths', () => {
+            const result = checkOwnership(['courses/a/lesson.md', 'docs/a.md'], ['courses/a/**', 'docs/**'], []);
+            expect(result.ok).toBe(true);
+            expect(result.violating_files).toEqual([]);
+        });
+    });
+    describe('env artifact filtering', () => {
+        it('excludes env artifacts from ownership check', () => {
+            const result = checkOwnership(['courses/a/lesson.md', 'node_modules/foo/bar.js'], ['courses/a/**'], ['node_modules/**']);
+            expect(result.ok).toBe(true);
+            expect(result.semantic_changed).toEqual(['courses/a/lesson.md']);
+            expect(result.violating_files).toEqual([]);
+        });
+        it('only checks semantic changes, not env noise', () => {
+            // If all changes are env artifacts, no enforcement needed
+            const result = checkOwnership(['node_modules/foo/bar.js', '.next/cache/file'], ['courses/a/**'], ['node_modules/**', '.next/**']);
+            expect(result.ok).toBe(true);
+            expect(result.semantic_changed).toEqual([]);
+            expect(result.violating_files).toEqual([]);
+        });
+    });
+    describe('rename handling (when both paths are included)', () => {
+        it('blocks rename from outside into owned paths', () => {
+            // Simulates: git mv README.md courses/a/README.md
+            // listChangedFiles now returns BOTH paths
+            const result = checkOwnership(['README.md', 'courses/a/README.md'], ['courses/a/**'], []);
+            expect(result.ok).toBe(false);
+            expect(result.violating_files).toEqual(['README.md']);
+        });
+        it('allows rename within owned paths', () => {
+            // Simulates: git mv courses/a/old.md courses/a/new.md
+            const result = checkOwnership(['courses/a/old.md', 'courses/a/new.md'], ['courses/a/**'], []);
+            expect(result.ok).toBe(true);
+            expect(result.violating_files).toEqual([]);
+        });
+        it('blocks rename from owned to outside', () => {
+            // Simulates: git mv courses/a/file.md README.md
+            const result = checkOwnership(['courses/a/file.md', 'README.md'], ['courses/a/**'], []);
+            expect(result.ok).toBe(false);
+            expect(result.violating_files).toEqual(['README.md']);
+        });
+    });
+    describe('defensive normalization', () => {
+        it('normalizes raw directory paths to glob patterns', () => {
+            // Caller passes raw "courses/a/" instead of normalized "courses/a/**"
+            const result = checkOwnership(['courses/a/lesson.md'], ['courses/a/'], // raw, not normalized
+            []);
+            expect(result.ok).toBe(true);
+            expect(result.owned_paths).toEqual(['courses/a/**']); // normalized in output
+        });
+        it('normalizes Windows-style paths', () => {
+            const result = checkOwnership(['courses/a/lesson.md'], ['courses\\a\\'], // Windows-style
+            []);
+            expect(result.ok).toBe(true);
+            expect(result.owned_paths).toEqual(['courses/a/**']);
+        });
+        it('handles ./prefix in ownership patterns', () => {
+            const result = checkOwnership(['courses/a/lesson.md'], ['./courses/a/'], []);
+            expect(result.ok).toBe(true);
+            expect(result.owned_paths).toEqual(['courses/a/**']);
+        });
+    });
+});

package/dist/supervisor/__tests__/state-machine.test.js

@@ -0,0 +1,290 @@
+import { describe, it, expect } from 'vitest';
+import { createInitialState, updatePhase, stopRun, computeResumeTargetPhase, prepareForResume } from '../state-machine.js';
+describe('createInitialState', () => {
+    it('creates state with INIT phase', () => {
+        const state = createInitialState({
+            run_id: 'test-run-123',
+            repo_path: '/test/repo',
+            task_text: 'Test task',
+            allowlist: ['src/**'],
+            denylist: ['node_modules/**']
+        });
+        expect(state.run_id).toBe('test-run-123');
+        expect(state.repo_path).toBe('/test/repo');
+        expect(state.phase).toBe('INIT');
+        expect(state.milestone_index).toBe(0);
+        expect(state.scope_lock.allowlist).toEqual(['src/**']);
+        expect(state.scope_lock.denylist).toEqual(['node_modules/**']);
+        expect(state.risk_score).toBe(0);
+        expect(state.retries).toBe(0);
+    });
+    it('parses task text into milestones', () => {
+        const state = createInitialState({
+            run_id: 'test',
+            repo_path: '/test',
+            task_text: 'Add a new feature\n\nMore details here',
+            allowlist: [],
+            denylist: []
+        });
+        expect(state.milestones.length).toBeGreaterThan(0);
+        expect(state.milestones[0].goal).toBe('Add a new feature');
+    });
+});
+describe('updatePhase', () => {
+    it('updates phase and tracks last_successful_phase as previous phase', () => {
+        const initial = createInitialState({
+            run_id: 'test',
+            repo_path: '/test',
+            task_text: 'Test',
+            allowlist: [],
+            denylist: []
+        });
+        const updated = updatePhase(initial, 'PLAN');
+        expect(updated.phase).toBe('PLAN');
+        // last_successful_phase tracks the previous phase (INIT in this case)
+        expect(updated.last_successful_phase).toBe('INIT');
+        // updated_at is set (may be same as initial if test runs in same ms)
+        expect(typeof updated.updated_at).toBe('string');
+        expect(updated.updated_at.length).toBeGreaterThan(0);
+    });
+    it('preserves other state properties', () => {
+        const initial = createInitialState({
+            run_id: 'preserve-test',
+            repo_path: '/preserve',
+            task_text: 'Preserve task',
+            allowlist: ['src/**'],
+            denylist: ['dist/**']
+        });
+        const updated = updatePhase(initial, 'IMPLEMENT');
+        expect(updated.run_id).toBe('preserve-test');
+        expect(updated.repo_path).toBe('/preserve');
+        expect(updated.scope_lock.allowlist).toEqual(['src/**']);
+    });
+});
+describe('stopRun', () => {
+    it('sets phase to STOPPED and records reason', () => {
+        const initial = createInitialState({
+            run_id: 'stop-test',
+            repo_path: '/test',
+            task_text: 'Test',
+            allowlist: [],
+            denylist: []
+        });
+        const stopped = stopRun(initial, 'verification_failed');
+        expect(stopped.phase).toBe('STOPPED');
+        expect(stopped.stop_reason).toBe('verification_failed');
+    });
+    it('preserves state when stopping', () => {
+        let state = createInitialState({
+            run_id: 'stop-preserve',
+            repo_path: '/test',
+            task_text: 'Test',
+            allowlist: ['src/**'],
+            denylist: []
+        });
+        state = updatePhase(state, 'IMPLEMENT');
+        state = { ...state, milestone_index: 2 };
+        const stopped = stopRun(state, 'complete');
+        expect(stopped.milestone_index).toBe(2);
+        expect(stopped.scope_lock.allowlist).toEqual(['src/**']);
+    });
+});
+describe('phase ordering', () => {
+    it('follows expected phase progression for success path', () => {
+        const phases = [];
+        let state = createInitialState({
+            run_id: 'phase-order',
+            repo_path: '/test',
+            task_text: 'Test',
+            allowlist: [],
+            denylist: []
+        });
+        phases.push(state.phase);
+        state = updatePhase(state, 'PLAN');
+        phases.push(state.phase);
+        state = updatePhase(state, 'IMPLEMENT');
+        phases.push(state.phase);
+        state = updatePhase(state, 'VERIFY');
+        phases.push(state.phase);
+        state = updatePhase(state, 'REVIEW');
+        phases.push(state.phase);
+        state = updatePhase(state, 'CHECKPOINT');
+        phases.push(state.phase);
+        state = updatePhase(state, 'FINALIZE');
+        phases.push(state.phase);
+        expect(phases).toEqual([
+            'INIT',
+            'PLAN',
+            'IMPLEMENT',
+            'VERIFY',
+            'REVIEW',
+            'CHECKPOINT',
+            'FINALIZE'
+        ]);
+    });
+    it('can loop back to IMPLEMENT after CHECKPOINT for multiple milestones', () => {
+        let state = createInitialState({
+            run_id: 'loop-test',
+            repo_path: '/test',
+            task_text: 'Multi milestone task',
+            allowlist: [],
+            denylist: []
+        });
+        // First milestone
+        state = updatePhase(state, 'PLAN');
+        state = updatePhase(state, 'IMPLEMENT');
+        state = updatePhase(state, 'VERIFY');
+        state = updatePhase(state, 'REVIEW');
+        state = updatePhase(state, 'CHECKPOINT');
+        state = { ...state, milestone_index: 1 };
+        // Second milestone - loops back to IMPLEMENT
+        state = updatePhase(state, 'IMPLEMENT');
+        expect(state.phase).toBe('IMPLEMENT');
+        expect(state.milestone_index).toBe(1);
+        state = updatePhase(state, 'VERIFY');
+        state = updatePhase(state, 'REVIEW');
+        state = updatePhase(state, 'CHECKPOINT');
+        state = { ...state, milestone_index: 2 };
+        // Finalize after all milestones
+        state = updatePhase(state, 'FINALIZE');
+        expect(state.phase).toBe('FINALIZE');
+        expect(state.milestone_index).toBe(2);
+    });
+    it('stops on verification failure', () => {
+        let state = createInitialState({
+            run_id: 'verify-fail',
+            repo_path: '/test',
+            task_text: 'Test',
+            allowlist: [],
+            denylist: []
+        });
+        state = updatePhase(state, 'PLAN');
+        state = updatePhase(state, 'IMPLEMENT');
+        state = updatePhase(state, 'VERIFY');
+        // Verification fails - stop run
+        state = stopRun(state, 'verification_failed');
+        expect(state.phase).toBe('STOPPED');
+        expect(state.stop_reason).toBe('verification_failed');
+        // last_successful_phase is set by updatePhase (previous phase), not stopRun
+        expect(state.last_successful_phase).toBe('IMPLEMENT');
+    });
+});
+describe('computeResumeTargetPhase', () => {
+    it('returns current phase if not STOPPED', () => {
+        const state = createInitialState({
+            run_id: 'test',
+            repo_path: '/test',
+            task_text: 'Test',
+            allowlist: [],
+            denylist: []
+        });
+        const updated = updatePhase(state, 'IMPLEMENT');
+        expect(computeResumeTargetPhase(updated)).toBe('IMPLEMENT');
+    });
+    it('returns next phase after last_successful_phase when STOPPED', () => {
+        let state = createInitialState({
+            run_id: 'test',
+            repo_path: '/test',
+            task_text: 'Test',
+            allowlist: [],
+            denylist: []
+        });
+        state = updatePhase(state, 'PLAN');
+        state = updatePhase(state, 'IMPLEMENT');
+        state = updatePhase(state, 'VERIFY');
+        state = stopRun(state, 'stalled_timeout');
+        // last_successful_phase is IMPLEMENT (from the VERIFY transition)
+        expect(state.last_successful_phase).toBe('IMPLEMENT');
+        expect(computeResumeTargetPhase(state)).toBe('VERIFY');
+    });
+    it('returns INIT when STOPPED with no last_successful_phase', () => {
+        const state = createInitialState({
+            run_id: 'test',
+            repo_path: '/test',
+            task_text: 'Test',
+            allowlist: [],
+            denylist: []
+        });
+        const stopped = stopRun(state, 'guard_violation');
+        expect(computeResumeTargetPhase(stopped)).toBe('INIT');
+    });
+});
+describe('prepareForResume', () => {
+    it('clears stop state and sets resume phase', () => {
+        let state = createInitialState({
+            run_id: 'test',
+            repo_path: '/test',
+            task_text: 'Test',
+            allowlist: [],
+            denylist: []
+        });
+        // Simulate normal phase progression: INIT -> PLAN -> IMPLEMENT -> VERIFY
+        // Each updatePhase sets last_successful_phase to the PREVIOUS phase
+        state = updatePhase(state, 'PLAN'); // last_successful_phase = 'INIT'
+        state = updatePhase(state, 'IMPLEMENT'); // last_successful_phase = 'PLAN'
+        state = updatePhase(state, 'VERIFY'); // last_successful_phase = 'IMPLEMENT'
+        state = stopRun(state, 'stalled_timeout');
+        state = { ...state, last_error: 'Some error' };
+        const resumed = prepareForResume(state);
+        // Resume from phase after last_successful_phase ('IMPLEMENT' -> 'VERIFY')
+        expect(resumed.phase).toBe('VERIFY');
+        expect(resumed.stop_reason).toBeUndefined();
+        expect(resumed.last_error).toBeUndefined();
+        expect(resumed.resume_token).toBe('test');
+    });
+    it('increments auto_resume_count when requested', () => {
+        let state = createInitialState({
+            run_id: 'test',
+            repo_path: '/test',
+            task_text: 'Test',
+            allowlist: [],
+            denylist: []
+        });
+        state = stopRun(state, 'stalled_timeout');
+        const resumed = prepareForResume(state, { incrementAutoResumeCount: true });
+        expect(resumed.auto_resume_count).toBe(1);
+        // Resume again
+        const stoppedAgain = stopRun(resumed, 'worker_call_timeout');
+        const resumedAgain = prepareForResume(stoppedAgain, { incrementAutoResumeCount: true });
+        expect(resumedAgain.auto_resume_count).toBe(2);
+    });
+    it('preserves auto_resume_count when not incrementing', () => {
+        let state = createInitialState({
+            run_id: 'test',
+            repo_path: '/test',
+            task_text: 'Test',
+            allowlist: [],
+            denylist: []
+        });
+        state = { ...state, auto_resume_count: 3 };
+        state = stopRun(state, 'stalled_timeout');
+        const resumed = prepareForResume(state);
+        expect(resumed.auto_resume_count).toBe(3);
+    });
+    it('handles missing auto_resume_count (migration-safe)', () => {
+        let state = createInitialState({
+            run_id: 'test',
+            repo_path: '/test',
+            task_text: 'Test',
+            allowlist: [],
+            denylist: []
+        });
+        // Simulate old state without auto_resume_count
+        delete state.auto_resume_count;
+        state = stopRun(state, 'stalled_timeout');
+        const resumed = prepareForResume(state, { incrementAutoResumeCount: true });
+        expect(resumed.auto_resume_count).toBe(1);
+    });
+    it('uses custom resumeToken when provided', () => {
+        let state = createInitialState({
+            run_id: 'original-run',
+            repo_path: '/test',
+            task_text: 'Test',
+            allowlist: [],
+            denylist: []
+        });
+        state = stopRun(state, 'stalled_timeout');
+        const resumed = prepareForResume(state, { resumeToken: 'custom-token' });
+        expect(resumed.resume_token).toBe('custom-token');
+    });
+});