opencastle 0.27.0 → 0.27.2

package/dist/cli/convoy/engine.test.js

@@ -1,10 +1,13 @@
-import { mkdtempSync, rmSync } from 'node:fs';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import { createConvoyEngine } from './engine.js';
+import { createConvoyEngine, evaluateReviewLevel, runConvoyGuard } from './engine.js';
+import { recoverNdjson, createEventEmitter } from './events.js';
 import { createConvoyStore } from './store.js';
 import { getAdapter, detectAdapter } from '../run/adapters/index.js';
+import * as gates from './gates.js';
+import * as partition from './partition.js';
 // ── Mock NDJSON log writes ────────────────────────────────────────────────────
 vi.mock('../log.js', () => ({
     appendEvent: vi.fn().mockResolvedValue(undefined),
@@ -62,6 +65,14 @@ function makeSpec(specOverrides = {}, taskOverrides = [{}]) {
         ...specOverrides,
     };
 }
+/** Wraps createConvoyEngine with a default no-op _ensureBranch mock so tests never
+ * run real git branch operations. Callers can override _ensureBranch if needed. */
+function makeEngine(opts) {
+    return createConvoyEngine({
+        _ensureBranch: vi.fn().mockResolvedValue(undefined),
+        ...opts,
+    });
+}
 // ── Test lifecycle ────────────────────────────────────────────────────────────
 let tmpDir;
 let dbPath;
@@ -80,7 +91,7 @@ afterEach(() => {
 describe('single task success', () => {
     it('returns status done with summary.done=1', async () => {
         const adapter = makeAdapter();
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec(),
             specYaml: 'name: test',
             adapter,
@@ -99,7 +110,7 @@ describe('single task success', () => {
     });
     it('calls adapter.execute once with the correct task', async () => {
         const adapter = makeAdapter();
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec(),
             specYaml: 'name: test',
             adapter,
@@ -118,7 +129,7 @@ describe('single task failure', () => {
     it('returns status failed with summary.failed=1 when task errors and no retries allowed', async () => {
         const adapter = makeAdapter();
         adapter.execute.mockResolvedValue({ success: false, output: 'boom', exitCode: 1 });
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec({}, [{ id: 'task-1', max_retries: 0 }]),
             specYaml: 'name: test',
             adapter,
@@ -134,7 +145,7 @@ describe('single task failure', () => {
     it('calls adapter.kill when the task fails', async () => {
         const adapter = makeAdapter();
         adapter.execute.mockResolvedValue({ success: false, output: 'boom', exitCode: 1 });
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec({}, [{ id: 'task-1', max_retries: 0 }]),
             specYaml: 'name: test',
             adapter,
@@ -159,7 +170,7 @@ describe('two-phase DAG (task-b depends on task-a)', () => {
             { id: 'task-a', depends_on: [] },
             { id: 'task-b', depends_on: ['task-a'] },
         ]);
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec,
             specYaml: 'name: test',
             adapter,
@@ -187,7 +198,7 @@ describe('two-phase DAG (task-b depends on task-a)', () => {
             { id: 'task-a', depends_on: [] },
             { id: 'task-b', depends_on: ['task-a'] },
         ]);
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec,
             specYaml: 'name: test',
             adapter,
@@ -217,7 +228,7 @@ describe('on_failure:continue', () => {
             { id: 'task-b', depends_on: ['task-a'] },
             { id: 'task-c', depends_on: [] },
         ]);
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec,
             specYaml: 'name: test',
             adapter,
@@ -251,7 +262,7 @@ describe('on_failure:continue', () => {
             { id: 'task-b', depends_on: ['task-a'] },
             { id: 'task-c', depends_on: ['task-b'] },
         ]);
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec,
             specYaml: 'name: test',
             adapter,
@@ -276,7 +287,7 @@ describe('on_failure:stop', () => {
             { id: 'task-b', depends_on: ['task-a'] },
             { id: 'task-c', depends_on: ['task-a'] },
         ]);
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec,
             specYaml: 'name: test',
             adapter,
@@ -301,7 +312,7 @@ describe('on_failure:stop', () => {
         const adapter = makeAdapter();
         adapter.execute.mockResolvedValue({ success: false, output: 'fail', exitCode: 1 });
         const spec = makeSpec({ on_failure: 'stop' }, [{ id: 'task-1', max_retries: 3 }]);
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec,
             specYaml: 'name: test',
             adapter,
@@ -329,7 +340,7 @@ describe('task retry', () => {
             return { success: true, output: 'second attempt ok', exitCode: 0 };
         });
         const spec = makeSpec({}, [{ id: 'task-1', max_retries: 1 }]);
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec,
             specYaml: 'name: test',
             adapter,
@@ -350,7 +361,7 @@ describe('task retry', () => {
             return { success: false, output: 'always fails', exitCode: 1 };
         });
         const spec = makeSpec({}, [{ id: 'task-1', max_retries: 2 }]);
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec,
             specYaml: 'name: test',
             adapter,
@@ -370,7 +381,7 @@ describe('validation gates', () => {
     it('returns status done when all gates pass', async () => {
         const adapter = makeAdapter();
         const spec = makeSpec({ gates: ['echo gate-ok'] }, [{ id: 'task-1' }]);
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec,
             specYaml: 'name: test',
             adapter,
@@ -386,7 +397,7 @@ describe('validation gates', () => {
     it('returns status gate-failed when a gate exits non-zero', async () => {
         const adapter = makeAdapter();
         const spec = makeSpec({ gates: ['false'] }, [{ id: 'task-1' }]);
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec,
             specYaml: 'name: test',
             adapter,
@@ -401,7 +412,7 @@ describe('validation gates', () => {
     });
     it('returns undefined gateResults when spec has no gates', async () => {
         const adapter = makeAdapter();
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec(),
             specYaml: 'name: test',
             adapter,
@@ -415,7 +426,7 @@ describe('validation gates', () => {
     it('runs multiple gates and reports each result individually', async () => {
         const adapter = makeAdapter();
         const spec = makeSpec({ gates: ['echo first', 'false', 'echo third'] }, [{ id: 'task-1' }]);
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec,
             specYaml: 'name: test',
             adapter,
@@ -458,6 +469,7 @@ describe('resume (crash recovery)', () => {
             max_retries: 0,
             files: null,
             depends_on: null,
+            gates: null,
         });
         if (taskStatus === 'running') {
             seeder.insertWorker({
@@ -479,7 +491,7 @@ describe('resume (crash recovery)', () => {
         seedCrashedConvoy(convoyId, 'running');
         const adapter = makeAdapter();
         const wtManager = makeWorktreeManager();
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec({}, [{ id: 'task-1' }]),
             specYaml: 'name: test',
             adapter,
@@ -498,7 +510,7 @@ describe('resume (crash recovery)', () => {
         const convoyId = 'convoy-crashed-assigned';
         seedCrashedConvoy(convoyId, 'assigned');
         const adapter = makeAdapter();
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec({}, [{ id: 'task-1' }]),
             specYaml: 'name: test',
             adapter,
@@ -512,7 +524,7 @@ describe('resume (crash recovery)', () => {
     });
     it('throws an error when the convoy is not found', async () => {
         const adapter = makeAdapter();
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec(),
             specYaml: 'name: test',
             adapter,
@@ -549,10 +561,11 @@ describe('resume (crash recovery)', () => {
             max_retries: 0,
             files: null,
             depends_on: null,
+            gates: null,
         });
         seeder.close();
         const adapter = makeAdapter();
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec({ branch: 'feature-branch' }), // spec.branch used as fallback
             specYaml: 'name: test',
             adapter,
@@ -591,10 +604,11 @@ describe('resume (crash recovery)', () => {
             max_retries: 0,
             files: null,
             depends_on: null,
+            gates: null,
         });
         seeder.close();
         const adapter = makeAdapter();
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: {
                 name: 'Git Branch Convoy',
                 concurrency: 1,
@@ -619,7 +633,7 @@ describe('worktree lifecycle (non-copilot)', () => {
         const adapter = makeAdapter('developer');
         const wtManager = makeWorktreeManager();
         const mergeQueue = makeMergeQueue();
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec(),
             specYaml: 'name: test',
             adapter,
@@ -637,7 +651,7 @@ describe('worktree lifecycle (non-copilot)', () => {
         adapter.execute.mockResolvedValue({ success: false, output: 'err', exitCode: 1 });
         const wtManager = makeWorktreeManager();
         const mergeQueue = makeMergeQueue();
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec({}, [{ id: 'task-1', max_retries: 0 }]),
             specYaml: 'name: test',
             adapter,
@@ -655,7 +669,7 @@ describe('worktree lifecycle (non-copilot)', () => {
         const wtManager = makeWorktreeManager();
         wtManager.create.mockRejectedValue(new Error('git worktree unavailable'));
         const mergeQueue = makeMergeQueue();
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec(),
             specYaml: 'name: test',
             adapter,
@@ -673,7 +687,7 @@ describe('worktree lifecycle (non-copilot)', () => {
         const wtManager = makeWorktreeManager();
         const mergeQueue = makeMergeQueue();
         mergeQueue.merge.mockRejectedValue(new Error('merge conflict'));
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec(),
             specYaml: 'name: test',
             adapter,
@@ -693,7 +707,7 @@ describe('copilot adapter', () => {
         const adapter = makeAdapter('copilot');
         const wtManager = makeWorktreeManager();
         const mergeQueue = makeMergeQueue();
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec(),
             specYaml: 'name: test',
             adapter,
@@ -719,7 +733,7 @@ describe('timeout handling', () => {
             output: 'Task timed out',
             exitCode: -1,
         });
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec({}, [{ id: 'task-1', max_retries: 0 }]),
             specYaml: 'name: test',
             adapter,
@@ -743,7 +757,7 @@ describe('timeout handling', () => {
             await new Promise(r => setTimeout(r, 5));
             return { success: true, output: 'ok', exitCode: 0 };
         });
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec({ on_failure: 'continue' }, [{ id: 'task-1', max_retries: 1 }]),
             specYaml: 'name: test',
             adapter,
@@ -763,7 +777,7 @@ describe('timeout handling', () => {
             output: 'timed out',
             exitCode: -1,
         });
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec({ on_failure: 'stop' }, [{ id: 'task-1', max_retries: 2 }]),
             specYaml: 'name: test',
             adapter,
@@ -785,7 +799,7 @@ describe('adapter without kill method', () => {
             execute: vi.fn().mockResolvedValue({ success: false, output: 'err', exitCode: 1 }),
             // kill intentionally absent
         };
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec({}, [{ id: 'task-1', max_retries: 0 }]),
             specYaml: 'name: test',
             adapter,
@@ -807,7 +821,7 @@ describe('adapter without kill method', () => {
                 exitCode: -1,
             }),
         };
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec({}, [{ id: 'task-1', max_retries: 0 }]),
             specYaml: 'name: test',
             adapter,
@@ -837,7 +851,7 @@ describe('parallel task execution', () => {
             { id: 'task-2', depends_on: [] },
             { id: 'task-3', depends_on: [] },
         ]);
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec,
             specYaml: 'name: test',
             adapter,
@@ -855,7 +869,7 @@ describe('executor error', () => {
     it('treats a thrown execute error as task failure', async () => {
         const adapter = makeAdapter();
         adapter.execute.mockRejectedValue(new Error('adapter crashed'));
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec({}, [{ id: 'task-1', max_retries: 0 }]),
             specYaml: 'name: test',
             adapter,
@@ -872,7 +886,7 @@ describe('executor error', () => {
 describe('verbose mode', () => {
     it('runs a successful task with verbose=true without throwing', async () => {
         const adapter = makeAdapter('developer');
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec({}, [{ id: 'task-1' }]),
             specYaml: 'name: test',
             adapter,
@@ -895,7 +909,7 @@ describe('verbose mode', () => {
             { id: 'task-a', depends_on: [] },
             { id: 'task-b', depends_on: ['task-a'] }, // gets skipped — also triggers verbose skip log
         ]);
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec,
             specYaml: 'name: test',
             adapter,
@@ -919,7 +933,7 @@ describe('verbose mode', () => {
             await new Promise(r => setTimeout(r, 5));
             return { success: true, output: 'ok', exitCode: 0 };
         });
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec({}, [{ id: 'task-1', max_retries: 1 }]),
             specYaml: 'name: test',
             adapter,
@@ -939,7 +953,7 @@ describe('verbose mode', () => {
             output: 'timed out',
             exitCode: -1,
         });
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec({}, [{ id: 'task-1', max_retries: 0 }]),
             specYaml: 'name: test',
             adapter,
@@ -962,7 +976,7 @@ describe('verbose mode', () => {
             await new Promise(r => setTimeout(r, 5));
             return { success: true, output: 'ok', exitCode: 0 };
         });
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec({ on_failure: 'continue' }, [{ id: 'task-1', max_retries: 1 }]),
             specYaml: 'name: test',
             adapter,
@@ -978,7 +992,7 @@ describe('verbose mode', () => {
         const adapter = makeAdapter('developer');
         const wtManager = makeWorktreeManager();
         wtManager.create.mockRejectedValue(new Error('no worktrees'));
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec({}, [{ id: 'task-1' }]),
             specYaml: 'name: test',
             adapter,
@@ -994,7 +1008,7 @@ describe('verbose mode', () => {
         const adapter = makeAdapter('developer');
         const mergeQueue = makeMergeQueue();
         mergeQueue.merge.mockRejectedValue(new Error('merge conflict'));
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec({}, [{ id: 'task-1' }]),
             specYaml: 'name: test',
             adapter,
@@ -1013,7 +1027,7 @@ describe('msToTimeout — timeout string representation', () => {
         const adapter = makeAdapter();
         // parseTimeout('1h') = 3600000ms; msToTimeout(3600000) = '1h'
         const spec = makeSpec({}, [{ id: 'task-1', timeout: '1h' }]);
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec,
             specYaml: 'name: test',
             adapter,
@@ -1028,7 +1042,7 @@ describe('msToTimeout — timeout string representation', () => {
         const adapter = makeAdapter();
         // parseTimeout('1m') = 60000ms; msToTimeout(60000) = '1m'
         const spec = makeSpec({}, [{ id: 'task-1', timeout: '1m' }]);
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec,
             specYaml: 'name: test',
             adapter,
@@ -1047,7 +1061,7 @@ describe('per-task adapter resolution', () => {
         const altAdapter = makeAdapter('alt-adapter');
         vi.mocked(getAdapter).mockResolvedValue(altAdapter);
         const spec = makeSpec({}, [{ adapter: 'alt-adapter' }]);
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec,
             specYaml: 'name: test',
             adapter: mainAdapter,
@@ -1063,7 +1077,7 @@ describe('per-task adapter resolution', () => {
     it('uses convoy-level adapter when task has no adapter field', async () => {
         const adapter = makeAdapter('test');
         const spec = makeSpec();
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec,
             specYaml: 'name: test',
             adapter,
@@ -1079,7 +1093,7 @@ describe('per-task adapter resolution', () => {
         const adapter = makeAdapter('test');
         // task.adapter === adapter.name → no per-task resolution
         const spec = makeSpec({}, [{ adapter: 'test' }]);
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec,
             specYaml: 'name: test',
             adapter,
@@ -1097,7 +1111,7 @@ describe('per-task adapter resolution', () => {
         vi.mocked(detectAdapter).mockResolvedValue('claude-code');
         vi.mocked(getAdapter).mockResolvedValue(autoAdapter);
         const spec = makeSpec({}, [{ adapter: 'auto' }]);
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec,
             specYaml: 'name: test',
             adapter: mainAdapter,
@@ -1115,7 +1129,7 @@ describe('per-task adapter resolution', () => {
         const altAdapter = makeAdapter('alt-adapter');
         vi.mocked(getAdapter).mockResolvedValue(altAdapter);
         const spec = makeSpec({}, [{ adapter: 'alt-adapter' }]);
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec,
             specYaml: 'name: test',
             adapter: makeAdapter('test'),
@@ -1144,7 +1158,7 @@ describe('getCurrentBranch', () => {
             // branch intentionally omitted
             tasks: [{ id: 'task-1', prompt: 'p', agent: 'dev', timeout: '30s', depends_on: [], files: [], description: '', max_retries: 0 }],
         };
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec,
             specYaml: 'name: branch-test',
             adapter,
@@ -1165,7 +1179,7 @@ describe('getCurrentBranch', () => {
             // branch not set — getCurrentBranch will fail because basePath is /tmp
             tasks: [{ id: 'task-1', prompt: 'p', agent: 'dev', timeout: '30s', depends_on: [], files: [], description: '', max_retries: 0 }],
         };
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec,
             specYaml: 'name: fallback-test',
             adapter,
@@ -1185,7 +1199,7 @@ describe('real timer timeout path', () => {
         const adapter = makeAdapter();
         // adapter.execute returns a promise that never resolves — real timer wins the race
         adapter.execute.mockImplementation(() => new Promise(() => { }));
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec({}, [{ id: 'task-1', timeout: '1s', max_retries: 0 }]),
             specYaml: 'name: test',
             adapter,
@@ -1219,7 +1233,7 @@ describe('diamond dependency skip', () => {
             { id: 'task-b', depends_on: ['task-a'] },
             { id: 'task-c', depends_on: ['task-a', 'task-b'] }, // diamond
         ]);
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec,
             specYaml: 'name: test',
             adapter,
@@ -1250,7 +1264,7 @@ describe('cost tracking', () => {
             exitCode: 0,
             usage: { prompt_tokens: 100, completion_tokens: 50, total_tokens: 150 },
         });
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec(),
             specYaml: 'name: test',
             adapter,
@@ -1270,7 +1284,7 @@ describe('cost tracking', () => {
     it('leaves cost fields null when adapter returns no usage', async () => {
         const adapter = makeAdapter();
         // default makeAdapter returns no usage field
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec(),
             specYaml: 'name: test',
             adapter,
@@ -1295,7 +1309,7 @@ describe('cost tracking', () => {
             { id: 'task-1', depends_on: [] },
             { id: 'task-2', depends_on: [] },
         ]);
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec,
             specYaml: 'name: test',
             adapter,
@@ -1317,7 +1331,7 @@ describe('cost tracking', () => {
             exitCode: 0,
             usage: { total_tokens: 75 },
         });
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec(),
             specYaml: 'name: test',
             adapter,
@@ -1331,7 +1345,7 @@ describe('cost tracking', () => {
     it('omits cost from ConvoyResult when no usage data is available', async () => {
         const adapter = makeAdapter();
         // default makeAdapter returns no usage
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec(),
             specYaml: 'name: test',
             adapter,
@@ -1350,7 +1364,7 @@ describe('cost tracking', () => {
             exitCode: 0,
             usage: { total_tokens: 42 },
         });
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec(),
             specYaml: 'name: test',
             adapter,
@@ -1369,7 +1383,7 @@ describe('cost tracking', () => {
     it('convoy total_tokens is null when no task has usage', async () => {
         const adapter = makeAdapter();
         // default adapter returns no usage
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec({ concurrency: 2 }, [
                 { id: 'task-1', depends_on: [] },
                 { id: 'task-2', depends_on: [] },
@@ -1404,7 +1418,7 @@ describe('progress reporting', () => {
     });
     it('prints task start message without verbose flag', async () => {
         const adapter = makeAdapter();
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec(),
             specYaml: 'name: test',
             adapter,
@@ -1419,7 +1433,7 @@ describe('progress reporting', () => {
     });
     it('prints task completion with counter', async () => {
         const adapter = makeAdapter();
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec(),
             specYaml: 'name: test',
             adapter,
@@ -1435,7 +1449,7 @@ describe('progress reporting', () => {
     it('prints task failure with counter', async () => {
         const adapter = makeAdapter();
         adapter.execute.mockResolvedValue({ success: false, output: 'boom', exitCode: 1 });
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec({}, [{ id: 'task-1', max_retries: 0 }]),
             specYaml: 'name: test',
             adapter,
@@ -1454,7 +1468,7 @@ describe('progress reporting', () => {
             { id: 'task-a', depends_on: [] },
             { id: 'task-b', depends_on: ['task-a'] },
         ]);
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec,
             specYaml: 'name: test',
             adapter,
@@ -1470,7 +1484,7 @@ describe('progress reporting', () => {
     it('prints gate results with pass/fail indicators', async () => {
         const adapter = makeAdapter();
         const spec = makeSpec({ gates: ['echo gate-ok', 'false'] }, [{ id: 'task-1' }]);
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec,
             specYaml: 'name: test',
             adapter,
@@ -1495,7 +1509,7 @@ describe('progress reporting', () => {
             await new Promise(r => setTimeout(r, 5));
             return { success: true, output: 'ok', exitCode: 0 };
         });
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec: makeSpec({}, [{ id: 'task-1', max_retries: 1 }]),
             specYaml: 'name: test',
             adapter,
@@ -1526,7 +1540,7 @@ describe('gate retry mechanism', () => {
     });
     it('gates pass on first attempt when gate_retries > 0 — no fix task run', async () => {
         const spec = makeSpec({ gates: [`node -e "process.exit(0)"`], gate_retries: 1 }, [{ id: 'task-1' }]);
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec,
             specYaml: 'name: test',
             adapter,
@@ -1541,7 +1555,7 @@ describe('gate retry mechanism', () => {
     });
     it('defaults gate_retries to 0 (no retry on gate failure)', async () => {
         const spec = makeSpec({ gates: ['false'] }, [{ id: 'task-1' }]);
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec,
             specYaml: 'name: test',
             adapter,
@@ -1556,7 +1570,7 @@ describe('gate retry mechanism', () => {
     });
     it('calls adapter.execute with fix prompt when gates fail and retries available', async () => {
         const spec = makeSpec({ gates: ['false'], gate_retries: 1 }, [{ id: 'task-1' }]);
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec,
             specYaml: 'name: test',
             adapter,
@@ -1579,7 +1593,7 @@ describe('gate retry mechanism', () => {
             .mockResolvedValueOnce({ success: true, output: 'ok', exitCode: 0 }) // task-1
             .mockResolvedValueOnce({ success: false, output: 'fix failed', exitCode: 1 }); // gate-fix-1
         const spec = makeSpec({ gates: ['false'], gate_retries: 2 }, [{ id: 'task-1' }]);
-        const engine = createConvoyEngine({
+        const engine = makeEngine({
             spec,
             specYaml: 'name: test',
             adapter,
@@ -1593,4 +1607,1579 @@ describe('gate retry mechanism', () => {
         expect(result.status).toBe('gate-failed');
     });
 });
+// ── evaluateReviewLevel ───────────────────────────────────────────────────────
+function makeTaskRecord(overrides = {}) {
+    return {
+        id: 'task-1',
+        convoy_id: 'convoy-1',
+        phase: 0,
+        prompt: '',
+        agent: 'developer',
+        adapter: null,
+        model: null,
+        timeout_ms: 1_800_000,
+        status: 'pending',
+        worker_id: null,
+        worktree: null,
+        output: null,
+        exit_code: null,
+        started_at: null,
+        finished_at: null,
+        retries: 0,
+        max_retries: 1,
+        files: null,
+        depends_on: null,
+        prompt_tokens: null,
+        completion_tokens: null,
+        total_tokens: null,
+        cost_usd: null,
+        gates: null,
+        on_exhausted: 'dlq',
+        injected: 0,
+        provenance: null,
+        idempotency_key: null,
+        current_step: null,
+        total_steps: null,
+        review_level: null,
+        review_verdict: null,
+        review_tokens: null,
+        review_model: null,
+        panel_attempts: 0,
+        dispute_id: null,
+        drift_score: null,
+        drift_retried: 0,
+        ...overrides,
+    };
+}
+function makeDiffStats(overrides = {}) {
+    return {
+        linesChanged: 5,
+        filesChanged: 1,
+        filePaths: ['src/components/Button.tsx'],
+        ...overrides,
+    };
+}
+describe('evaluateReviewLevel', () => {
+    it('routes to panel when a changed file is under auth/', () => {
+        const level = evaluateReviewLevel(makeTaskRecord(), makeDiffStats({ filePaths: ['auth/session.ts'] }));
+        expect(level).toBe('panel');
+    });
+    it('routes to panel when a changed file path contains /auth/', () => {
+        const level = evaluateReviewLevel(makeTaskRecord(), makeDiffStats({ filePaths: ['src/auth/session.ts'] }));
+        expect(level).toBe('panel');
+    });
+    it('routes to panel for security/ path', () => {
+        const level = evaluateReviewLevel(makeTaskRecord(), makeDiffStats({ filePaths: ['security/policy.ts'] }));
+        expect(level).toBe('panel');
+    });
+    it('routes to panel for security-expert agent', () => {
+        const level = evaluateReviewLevel(makeTaskRecord({ agent: 'security-expert' }), makeDiffStats());
+        expect(level).toBe('panel');
+    });
+    it('routes to panel for database-engineer agent', () => {
+        const level = evaluateReviewLevel(makeTaskRecord({ agent: 'database-engineer' }), makeDiffStats());
+        expect(level).toBe('panel');
+    });
+    it('routes to auto-pass for documentation-writer agent', () => {
+        const level = evaluateReviewLevel(makeTaskRecord({ agent: 'documentation-writer' }), makeDiffStats());
+        expect(level).toBe('auto-pass');
+    });
+    it('routes to auto-pass for copywriter agent', () => {
+        const level = evaluateReviewLevel(makeTaskRecord({ agent: 'copywriter' }), makeDiffStats());
+        expect(level).toBe('auto-pass');
+    });
+    it('routes to auto-pass for small diff (<=10 lines, <=2 files) with gates passing', () => {
+        const level = evaluateReviewLevel(makeTaskRecord(), makeDiffStats({ linesChanged: 8, filesChanged: 2, filePaths: ['src/Button.tsx', 'src/Button.test.tsx'] }), undefined, true);
+        expect(level).toBe('auto-pass');
+    });
+    it('routes to fast for large diff (>200 lines)', () => {
+        const level = evaluateReviewLevel(makeTaskRecord(), makeDiffStats({ linesChanged: 250, filesChanged: 3, filePaths: ['src/Big.tsx', 'src/Big.test.tsx', 'src/types.ts'] }));
+        expect(level).toBe('fast');
+    });
+    it('routes to fast for many files (>5)', () => {
+        const level = evaluateReviewLevel(makeTaskRecord(), makeDiffStats({ linesChanged: 50, filesChanged: 6, filePaths: ['a.ts', 'b.ts', 'c.ts', 'd.ts', 'e.ts', 'f.ts'] }));
+        expect(level).toBe('fast');
+    });
+    it('defaults to fast for medium diff with developer agent', () => {
+        const level = evaluateReviewLevel(makeTaskRecord({ agent: 'developer' }), makeDiffStats({ linesChanged: 50, filesChanged: 3, filePaths: ['src/Feature.tsx', 'src/Feature.test.tsx', 'src/types.ts'] }));
+        expect(level).toBe('fast');
+    });
+    it('custom heuristics: overrides panel_paths', () => {
+        const level = evaluateReviewLevel(makeTaskRecord(), makeDiffStats({ filePaths: ['billing/invoice.ts'] }), { panel_paths: ['billing/'] });
+        expect(level).toBe('panel');
+    });
+    it('custom heuristics: overrides auto_pass_agents', () => {
+        const level = evaluateReviewLevel(makeTaskRecord({ agent: 'designer' }), makeDiffStats(), { auto_pass_agents: ['designer'] });
+        expect(level).toBe('auto-pass');
+    });
+    it('custom heuristics: smaller auto_pass_max_lines threshold', () => {
+        const level = evaluateReviewLevel(makeTaskRecord(), makeDiffStats({ linesChanged: 5, filesChanged: 1, filePaths: ['src/x.ts'] }), { auto_pass_max_lines: 3 }, true);
+        expect(level).toBe('fast'); // 5 > 3 → not auto-pass
+    });
+});
+// ── Review pipeline integration ───────────────────────────────────────────────
+describe('review pipeline', () => {
+    let adapter;
+    let wtManager;
+    let mergeQueue;
+    beforeEach(() => {
+        adapter = makeAdapter();
+        wtManager = makeWorktreeManager();
+        mergeQueue = makeMergeQueue();
+    });
+    it('task with review: none — reviewer not called, task succeeds', async () => {
+        const mockReviewRunner = vi.fn().mockResolvedValue({ verdict: 'pass', feedback: '', tokens: 100, model: 'test' });
+        const engine = makeEngine({
+            spec: makeSpec({ defaults: { review: 'none' } }, [{ review: 'none' }]),
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: wtManager,
+            _mergeQueue: mergeQueue,
+            _reviewRunner: mockReviewRunner,
+        });
+        const result = await engine.run();
+        expect(result.status).toBe('done');
+        expect(mockReviewRunner).not.toHaveBeenCalled();
+    });
+    it('fast review PASS — task proceeds to merge (status done)', async () => {
+        const mockReviewRunner = vi.fn().mockResolvedValue({ verdict: 'pass', feedback: '', tokens: 50, model: 'reviewer' });
+        const engine = makeEngine({
+            spec: makeSpec({ defaults: { review: 'fast' } }),
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: wtManager,
+            _mergeQueue: mergeQueue,
+            _reviewRunner: mockReviewRunner,
+        });
+        const result = await engine.run();
+        expect(result.status).toBe('done');
+        expect(mockReviewRunner).toHaveBeenCalledOnce();
+        expect(mockReviewRunner).toHaveBeenCalledWith(expect.objectContaining({ agent: 'developer' }), 'fast', 'default');
+    });
+    it('fast review BLOCK + retries remaining — task retried with feedback prepended', async () => {
+        let callCount = 0;
+        adapter.execute.mockImplementation(() => {
+            callCount++;
+            return Promise.resolve({ success: true, output: 'ok', exitCode: 0 });
+        });
+        const mockReviewRunner = vi.fn()
+            .mockResolvedValueOnce({ verdict: 'block', feedback: 'Missing tests', tokens: 50, model: 'reviewer' })
+            .mockResolvedValueOnce({ verdict: 'pass', feedback: '', tokens: 50, model: 'reviewer' });
+        const engine = makeEngine({
+            spec: makeSpec({ defaults: { review: 'fast' } }, [{ max_retries: 1 }]),
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: wtManager,
+            _mergeQueue: mergeQueue,
+            _reviewRunner: mockReviewRunner,
+        });
+        const result = await engine.run();
+        expect(result.status).toBe('done');
+        expect(adapter.execute).toHaveBeenCalledTimes(2);
+        expect(mockReviewRunner).toHaveBeenCalledTimes(2);
+        // Prompt on second attempt should contain feedback
+        const secondPrompt = adapter.execute.mock.calls[1][0].prompt;
+        expect(secondPrompt).toContain('Missing tests');
+    });
+    it('fast review BLOCK + retries exhausted — status review-blocked', async () => {
+        const mockReviewRunner = vi.fn().mockResolvedValue({ verdict: 'block', feedback: 'Insecure code', tokens: 50, model: 'reviewer' });
+        const engine = makeEngine({
+            spec: makeSpec({ defaults: { review: 'fast' } }, [{ max_retries: 0 }]),
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: wtManager,
+            _mergeQueue: mergeQueue,
+            _reviewRunner: mockReviewRunner,
+        });
+        const result = await engine.run();
+        expect(result.status).toBe('failed');
+        expect(result.summary.failed).toBe(1);
+        // Verify the task itself is review-blocked
+        const store = createConvoyStore(dbPath);
+        const tasks = store.getTasksByConvoy(result.convoyId);
+        store.close();
+        expect(tasks[0].status).toBe('review-blocked');
+    });
+    it('panel review 2/3 PASS — task proceeds (status done)', async () => {
+        let callCount = 0;
+        const mockReviewRunner = vi.fn().mockImplementation(() => {
+            callCount++;
+            // 2 pass, 1 block
+            return Promise.resolve(callCount <= 2
+                ? { verdict: 'pass', feedback: '', tokens: 30, model: 'reviewer' }
+                : { verdict: 'block', feedback: 'Minor issue', tokens: 30, model: 'reviewer' });
+        });
+        const engine = makeEngine({
+            spec: makeSpec({ defaults: { review: 'panel' } }),
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: wtManager,
+            _mergeQueue: mergeQueue,
+            _reviewRunner: mockReviewRunner,
+        });
+        const result = await engine.run();
+        expect(result.status).toBe('done');
+        expect(mockReviewRunner).toHaveBeenCalledTimes(3);
+    });
+    it('panel review 2/3 BLOCK — task retried with MUST-FIX', async () => {
+        let reviewCallCount = 0;
+        const mockReviewRunner = vi.fn().mockImplementation(() => {
+            reviewCallCount++;
+            // First round: 2 block; second round: 3 pass
+            if (reviewCallCount <= 3) {
+                return Promise.resolve(reviewCallCount <= 2
+                    ? { verdict: 'block', feedback: 'Critical bug', tokens: 30, model: 'reviewer' }
+                    : { verdict: 'pass', feedback: '', tokens: 30, model: 'reviewer' });
+            }
+            return Promise.resolve({ verdict: 'pass', feedback: '', tokens: 30, model: 'reviewer' });
+        });
+        const engine = makeEngine({
+            spec: makeSpec({ defaults: { review: 'panel' } }, [{ max_retries: 1 }]),
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: wtManager,
+            _mergeQueue: mergeQueue,
+            _reviewRunner: mockReviewRunner,
+        });
+        const result = await engine.run();
+        expect(result.status).toBe('done');
+        expect(adapter.execute).toHaveBeenCalledTimes(2);
+        // Prompt on second attempt contains MUST-FIX
+        const secondPrompt = adapter.execute.mock.calls[1][0].prompt;
+        expect(secondPrompt).toContain('MUST-FIX');
+        expect(secondPrompt).toContain('Critical bug');
+    });
+    it('review budget exceeded with skip — review skipped, task done', async () => {
+        const mockReviewRunner = vi.fn().mockResolvedValue({ verdict: 'pass', feedback: '', tokens: 200, model: 'reviewer' });
+        const engine = makeEngine({
+            spec: makeSpec({
+                defaults: { review: 'fast', review_budget: 100, on_review_budget_exceeded: 'skip', reviewer_model: 'r1' },
+                tasks: [
+                    { id: 'task-1', prompt: 'Prompt 1', agent: 'developer', timeout: '30s', depends_on: [], files: [], description: '', max_retries: 0 },
+                    { id: 'task-2', prompt: 'Prompt 2', agent: 'developer', timeout: '30s', depends_on: ['task-1'], files: [], description: '', max_retries: 0 },
+                ],
+            }),
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: wtManager,
+            _mergeQueue: mergeQueue,
+            _reviewRunner: mockReviewRunner,
+        });
+        const result = await engine.run();
+        expect(result.status).toBe('done');
+        // first task: budget not exceeded (0 < 100), review runs
+        // second task: budget exceeded (200 >= 100), review skipped
+        expect(mockReviewRunner).toHaveBeenCalledTimes(1);
+    });
+    it('auto route: developer agent with empty diff → auto-pass (no reviewer call)', async () => {
+        // Given: 'auto' review setting, developer agent, empty diff (git will fail on mock path)
+        const mockReviewRunner = vi.fn();
+        const engine = makeEngine({
+            spec: makeSpec({ defaults: { review: 'auto' } }),
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: wtManager,
+            _mergeQueue: mergeQueue,
+            _reviewRunner: mockReviewRunner,
+        });
+        const result = await engine.run();
+        expect(result.status).toBe('done');
+        expect(mockReviewRunner).not.toHaveBeenCalled();
+    });
+    it('review tokens tracked on task record', async () => {
+        const mockReviewRunner = vi.fn().mockResolvedValue({ verdict: 'pass', feedback: '', tokens: 77, model: 'reviewer' });
+        const engine = makeEngine({
+            spec: makeSpec({ defaults: { review: 'fast' } }),
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: wtManager,
+            _mergeQueue: mergeQueue,
+            _reviewRunner: mockReviewRunner,
+        });
+        const result = await engine.run();
+        const store = createConvoyStore(dbPath);
+        const tasks = store.getTasksByConvoy(result.convoyId);
+        store.close();
+        expect(tasks[0].review_tokens).toBe(77);
+        expect(tasks[0].review_level).toBe('fast');
+        expect(tasks[0].review_verdict).toBe('pass');
+    });
+    it('review_started and review_verdict events emitted', async () => {
+        const mockReviewRunner = vi.fn().mockResolvedValue({ verdict: 'pass', feedback: '', tokens: 10, model: 'reviewer' });
+        const engine = makeEngine({
+            spec: makeSpec({ defaults: { review: 'fast' } }),
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: wtManager,
+            _mergeQueue: mergeQueue,
+            _reviewRunner: mockReviewRunner,
+        });
+        const result = await engine.run();
+        const store = createConvoyStore(dbPath);
+        const events = store.getEvents(result.convoyId);
+        store.close();
+        const startedEvent = events.find(e => e.type === 'review_started');
+        const verdictEvent = events.find(e => e.type === 'review_verdict');
+        expect(startedEvent).toBeDefined();
+        expect(verdictEvent).toBeDefined();
+    });
+    it('review sessions do NOT count against concurrency limit', async () => {
+        // Concurrency=1, 2 tasks in parallel. Both should complete with review.
+        const mockReviewRunner = vi.fn().mockResolvedValue({ verdict: 'pass', feedback: '', tokens: 10, model: 'reviewer' });
+        const engine = makeEngine({
+            spec: makeSpec({ concurrency: 1, defaults: { review: 'fast' } }, [{ id: 'task-1' }, { id: 'task-2' }]),
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: wtManager,
+            _mergeQueue: mergeQueue,
+            _reviewRunner: mockReviewRunner,
+        });
+        const result = await engine.run();
+        expect(result.status).toBe('done');
+        expect(result.summary.done).toBe(2);
+    });
+    it('full fast-review flow: BLOCK on first attempt → retry → PASS → done with complete events', async () => {
+        const mockReviewRunner = vi.fn()
+            .mockResolvedValueOnce({ verdict: 'block', feedback: 'Add more tests', tokens: 40, model: 'reviewer' })
+            .mockResolvedValueOnce({ verdict: 'pass', feedback: '', tokens: 35, model: 'reviewer' });
+        const engine = makeEngine({
+            spec: makeSpec({ defaults: { review: 'fast' } }, [{ id: 'task-1', max_retries: 1 }]),
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: wtManager,
+            _mergeQueue: mergeQueue,
+            _reviewRunner: mockReviewRunner,
+        });
+        const result = await engine.run();
+        expect(result.status).toBe('done');
+        expect(adapter.execute).toHaveBeenCalledTimes(2);
+        expect(mockReviewRunner).toHaveBeenCalledTimes(2);
+        const store = createConvoyStore(dbPath);
+        const tasks = store.getTasksByConvoy(result.convoyId);
+        const events = store.getEvents(result.convoyId);
+        store.close();
+        const task = tasks[0];
+        expect(task.review_level).toBe('fast');
+        expect(task.review_verdict).toBe('pass');
+        expect(task.retries).toBe(1);
+        const reviewStartedEvents = events.filter(e => e.type === 'review_started');
+        const reviewVerdictEvents = events.filter(e => e.type === 'review_verdict');
+        expect(reviewStartedEvents.length).toBe(2);
+        expect(reviewVerdictEvents.length).toBe(2);
+        const firstVerdict = JSON.parse(reviewVerdictEvents[0].data);
+        const secondVerdict = JSON.parse(reviewVerdictEvents[1].data);
+        expect(firstVerdict['verdict']).toBe('block');
+        expect(secondVerdict['verdict']).toBe('pass');
+    });
+    it('panel flow: 2/3 BLOCK first round → retry → 3/3 PASS second round → done', async () => {
+        let reviewCallCount = 0;
+        const mockReviewRunner = vi.fn().mockImplementation(() => {
+            reviewCallCount++;
+            // Round 1 (calls 1-3): BLOCK, BLOCK, PASS → majority block → retry
+            if (reviewCallCount <= 3) {
+                return Promise.resolve(reviewCallCount <= 2
+                    ? { verdict: 'block', feedback: 'Critical issue', tokens: 20, model: 'reviewer' }
+                    : { verdict: 'pass', feedback: '', tokens: 20, model: 'reviewer' });
+            }
+            // Round 2 (calls 4-6): all PASS
+            return Promise.resolve({ verdict: 'pass', feedback: '', tokens: 20, model: 'reviewer' });
+        });
+        const engine = makeEngine({
+            spec: makeSpec({ defaults: { review: 'panel' } }, [{ id: 'task-1', max_retries: 1 }]),
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: wtManager,
+            _mergeQueue: mergeQueue,
+            _reviewRunner: mockReviewRunner,
+        });
+        const result = await engine.run();
+        expect(result.status).toBe('done');
+        expect(adapter.execute).toHaveBeenCalledTimes(2);
+        expect(mockReviewRunner).toHaveBeenCalledTimes(6);
+        const store = createConvoyStore(dbPath);
+        const tasks = store.getTasksByConvoy(result.convoyId);
+        store.close();
+        expect(tasks[0].review_verdict).toBe('pass');
+        expect(tasks[0].panel_attempts).toBeGreaterThanOrEqual(1);
+    });
+    it('dispute: task dispute_id matches the dispute_opened event and panel_attempts is 3', async () => {
+        const mockReviewRunner = vi.fn().mockResolvedValue({ verdict: 'block', feedback: 'broken', tokens: 5, model: 'r' });
+        const engine = makeEngine({
+            spec: makeSpec({ defaults: { review: 'panel' } }, [{ id: 'task-1', max_retries: 3 }]),
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: wtManager,
+            _mergeQueue: mergeQueue,
+            _reviewRunner: mockReviewRunner,
+        });
+        const result = await engine.run();
+        const store = createConvoyStore(dbPath);
+        const tasks = store.getTasksByConvoy(result.convoyId);
+        const events = store.getEvents(result.convoyId);
+        store.close();
+        const task = tasks[0];
+        expect(task.status).toBe('disputed');
+        expect(task.dispute_id).not.toBeNull();
+        expect(task.panel_attempts).toBe(3);
+        const disputeEvent = events.find(e => e.type === 'dispute_opened');
+        expect(disputeEvent).toBeDefined();
+        const eventData = JSON.parse(disputeEvent.data);
+        // Verify the dispute_id on the task record matches the one in the event
+        expect(eventData['dispute_id']).toBe(task.dispute_id);
+        expect(eventData['panel_attempts']).toBe(3);
+    });
+    it('review budget exceeded: stop marks task review-blocked and skips all pending tasks', async () => {
+        const mockReviewRunner = vi.fn();
+        const engine = makeEngine({
+            spec: makeSpec({ defaults: { review: 'fast', review_budget: 0, on_review_budget_exceeded: 'stop' } }, [
+                { id: 'task-1', depends_on: [] },
+                { id: 'task-2', depends_on: ['task-1'] },
+            ]),
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: wtManager,
+            _mergeQueue: mergeQueue,
+            _reviewRunner: mockReviewRunner,
+        });
+        const result = await engine.run();
+        const store = createConvoyStore(dbPath);
+        const tasks = store.getTasksByConvoy(result.convoyId);
+        store.close();
+        const byId = Object.fromEntries(tasks.map(t => [t.id, t.status]));
+        expect(byId['task-1']).toBe('review-blocked');
+        expect(byId['task-2']).toBe('skipped');
+        expect(mockReviewRunner).not.toHaveBeenCalled();
+    });
+    it('review budget exceeded: downgrade auto-passes task without calling reviewer', async () => {
+        const mockReviewRunner = vi.fn();
+        const engine = makeEngine({
+            spec: makeSpec({ defaults: { review: 'fast', review_budget: 0, on_review_budget_exceeded: 'downgrade' } }),
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: wtManager,
+            _mergeQueue: mergeQueue,
+            _reviewRunner: mockReviewRunner,
+        });
+        const result = await engine.run();
+        expect(result.status).toBe('done');
+        expect(mockReviewRunner).not.toHaveBeenCalled();
+        const store = createConvoyStore(dbPath);
+        const tasks = store.getTasksByConvoy(result.convoyId);
+        store.close();
+        expect(tasks[0].review_verdict).toBe('pass');
+        expect(tasks[0].review_level).toBe('fast');
+    });
+});
+// ── Drift detection ───────────────────────────────────────────────────────────
+describe('drift detection', () => {
+    let adapter;
+    let wtManager;
+    let mergeQueue;
+    beforeEach(() => {
+        adapter = makeAdapter('copilot');
+        wtManager = makeWorktreeManager();
+        mergeQueue = makeMergeQueue();
+    });
+    it('detect_drift=true triggers drift check and retries on low confidence', async () => {
+        // Call sequence: main task → drift check (low score) → main task retry
+        adapter.execute
+            .mockResolvedValueOnce({ success: true, output: 'done', exitCode: 0 })
+            .mockResolvedValueOnce({ success: true, output: '{"score": 0.3, "explanation": "uncertain"}', exitCode: 0 })
+            .mockResolvedValueOnce({ success: true, output: 'done retry', exitCode: 0 });
+        const engine = makeEngine({
+            spec: makeSpec({ defaults: { detect_drift: true } }, [{ id: 'task-1', max_retries: 1 }]),
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: wtManager,
+            _mergeQueue: mergeQueue,
+        });
+        const result = await engine.run();
+        expect(result.status).toBe('done');
+        expect(result.summary.done).toBe(1);
+        expect(adapter.execute).toHaveBeenCalledTimes(3);
+        // Verify drift_score and drift_retried stored
+        const store = createConvoyStore(dbPath);
+        const tasks = store.getTasksByConvoy(result.convoyId);
+        store.close();
+        expect(tasks[0].drift_score).toBe(0.3);
+        expect(tasks[0].drift_retried).toBe(1);
+    });
+    it('detect_drift=true does NOT re-check on drift retry (drift_retried=1)', async () => {
+        // On second execution drift_retried=1 so no third call for drift check
+        adapter.execute
+            .mockResolvedValueOnce({ success: true, output: 'done', exitCode: 0 })
+            .mockResolvedValueOnce({ success: true, output: '{"score": 0.9, "explanation": "confident"}', exitCode: 0 });
+        const engine = makeEngine({
+            spec: makeSpec({ defaults: { detect_drift: true } }),
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: wtManager,
+            _mergeQueue: mergeQueue,
+        });
+        const result = await engine.run();
+        expect(result.status).toBe('done');
+        expect(adapter.execute).toHaveBeenCalledTimes(2);
+    });
+    it('drift_check_result and drift_detected events emitted when drifted', async () => {
+        adapter.execute
+            .mockResolvedValueOnce({ success: true, output: 'done', exitCode: 0 })
+            .mockResolvedValueOnce({ success: true, output: '{"score": 0.2, "explanation": "very unsure"}', exitCode: 0 })
+            .mockResolvedValueOnce({ success: true, output: 'done', exitCode: 0 });
+        const engine = makeEngine({
+            spec: makeSpec({ defaults: { detect_drift: true } }, [{ id: 'task-1', max_retries: 1 }]),
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: wtManager,
+            _mergeQueue: mergeQueue,
+        });
+        const result = await engine.run();
+        const store = createConvoyStore(dbPath);
+        const events = store.getEvents(result.convoyId);
+        store.close();
+        expect(events.some(e => e.type === 'drift_check_result')).toBe(true);
+        expect(events.some(e => e.type === 'drift_detected')).toBe(true);
+    });
+    it('non-copilot adapter skips drift detection (returns done without extra call)', async () => {
+        // adapter name is 'test-adapter' — not a streaming adapter; drift check should be skipped
+        const nonStreamingAdapter = makeAdapter('test-adapter');
+        nonStreamingAdapter.execute.mockResolvedValue({ success: true, output: 'ok', exitCode: 0 });
+        // Suppress the stderr warning
+        const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        try {
+            const engine = makeEngine({
+                spec: makeSpec({ defaults: { detect_drift: true } }),
+                specYaml: 'name: test',
+                adapter: nonStreamingAdapter,
+                dbPath,
+                _worktreeManager: wtManager,
+                _mergeQueue: mergeQueue,
+            });
+            const result = await engine.run();
+            expect(result.status).toBe('done');
+            // Only 1 call: main task (no drift check call) because non-streaming adapter
+            expect(nonStreamingAdapter.execute).toHaveBeenCalledTimes(1);
+        }
+        finally {
+            stderrSpy.mockRestore();
+        }
+    });
+});
+// ── Dispute protocol ──────────────────────────────────────────────────────────
+describe('dispute protocol', () => {
+    let adapter;
+    let wtManager;
+    let mergeQueue;
+    beforeEach(() => {
+        adapter = makeAdapter();
+        wtManager = makeWorktreeManager();
+        mergeQueue = makeMergeQueue();
+    });
+    it('3 panel blocks mark task as disputed', async () => {
+        // Each round: 3 calls to panel runner (all block) → retry until max_retries
+        // 3 panel blocks with max_retries=3 → 3 panel rounds → after 3rd: panel_attempts=3 → disputed
+        let panelCall = 0;
+        const mockReviewRunner = vi.fn().mockImplementation(() => {
+            panelCall++;
+            return Promise.resolve({ verdict: 'block', feedback: 'critical bug', tokens: 10, model: 'r' });
+        });
+        const engine = makeEngine({
+            spec: makeSpec({ defaults: { review: 'panel' } }, [{ id: 'task-1', max_retries: 3 }]),
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: wtManager,
+            _mergeQueue: mergeQueue,
+            _reviewRunner: mockReviewRunner,
+        });
+        const result = await engine.run();
+        const store = createConvoyStore(dbPath);
+        const tasks = store.getTasksByConvoy(result.convoyId);
+        store.close();
+        expect(tasks[0].status).toBe('disputed');
+        expect(tasks[0].dispute_id).not.toBeNull();
+        expect(result.summary.failed).toBe(1); // disputed counts as failed in summary
+    });
+    it('dispute_opened event emitted after 3 panel blocks', async () => {
+        const mockReviewRunner = vi.fn().mockResolvedValue({ verdict: 'block', feedback: 'bug', tokens: 5, model: 'r' });
+        const engine = makeEngine({
+            spec: makeSpec({ defaults: { review: 'panel' } }, [{ id: 'task-1', max_retries: 3 }]),
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: wtManager,
+            _mergeQueue: mergeQueue,
+            _reviewRunner: mockReviewRunner,
+        });
+        const result = await engine.run();
+        const store = createConvoyStore(dbPath);
+        const events = store.getEvents(result.convoyId);
+        store.close();
+        const disputeEvent = events.find(e => e.type === 'dispute_opened');
+        expect(disputeEvent).toBeDefined();
+        const data = JSON.parse(disputeEvent.data);
+        expect(data.task_id).toBe('task-1');
+        expect(data.panel_attempts).toBe(3);
+    });
+    it('on_dispute: stop halts all pending tasks', async () => {
+        const mockReviewRunner = vi.fn().mockResolvedValue({ verdict: 'block', feedback: 'bug', tokens: 5, model: 'r' });
+        const engine = makeEngine({
+            spec: makeSpec({ defaults: { review: 'panel', on_dispute: 'stop' } }, [
+                { id: 'task-1', depends_on: [], max_retries: 3 },
+                { id: 'task-2', depends_on: ['task-1'] }, // depends on task-1, so queued after
+            ]),
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: wtManager,
+            _mergeQueue: mergeQueue,
+            _reviewRunner: mockReviewRunner,
+        });
+        const result = await engine.run();
+        const store = createConvoyStore(dbPath);
+        const tasks = store.getTasksByConvoy(result.convoyId);
+        store.close();
+        const byId = Object.fromEntries(tasks.map(t => [t.id, t.status]));
+        expect(byId['task-1']).toBe('disputed');
+        expect(byId['task-2']).toBe('skipped');
+    });
+    it('on_dispute: continue keeps other tasks running', async () => {
+        // task-1 always fails panel (will be disputed), task-2 succeeds
+        adapter.execute.mockResolvedValue({ success: true, output: 'ok', exitCode: 0 });
+        const mockReviewRunner = vi.fn().mockImplementation((_task) => {
+            if (_task.id === 'task-1') {
+                return Promise.resolve({ verdict: 'block', feedback: 'bug', tokens: 5, model: 'r' });
+            }
+            return Promise.resolve({ verdict: 'pass', feedback: '', tokens: 5, model: 'r' });
+        });
+        const engine = makeEngine({
+            spec: makeSpec({ defaults: { review: 'panel', on_dispute: 'continue' } }, [
+                { id: 'task-1', depends_on: [], max_retries: 3 },
+                { id: 'task-2', depends_on: [] },
+            ]),
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: wtManager,
+            _mergeQueue: mergeQueue,
+            _reviewRunner: mockReviewRunner,
+        });
+        const result = await engine.run();
+        const store = createConvoyStore(dbPath);
+        const tasks = store.getTasksByConvoy(result.convoyId);
+        store.close();
+        const byId = Object.fromEntries(tasks.map(t => [t.id, t.status]));
+        expect(byId['task-1']).toBe('disputed');
+        expect(byId['task-2']).toBe('done');
+    });
+});
+// ── File-based injection ───────────────────────────────────────────────────
+describe('file-based injection', () => {
+    it('picks up tasks from inject file and ingests them', async () => {
+        const adapter = makeAdapter();
+        adapter.execute.mockResolvedValue({ success: true, output: 'ok', exitCode: 0 });
+        const spec = makeSpec({ concurrency: 1 }, [
+            { id: 'task-1', prompt: 'Original task', timeout: '5s' },
+        ]);
+        const engine = makeEngine({
+            spec,
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            basePath: tmpDir,
+            _worktreeManager: makeWorktreeManager(),
+            _mergeQueue: makeMergeQueue(),
+        });
+        const result = await engine.run();
+        expect(result.summary.done).toBeGreaterThanOrEqual(1);
+    });
+    it('respects convoy_id path traversal guard', async () => {
+        const adapter = makeAdapter();
+        const spec = makeSpec();
+        const engine = makeEngine({
+            spec,
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            basePath: tmpDir,
+            _worktreeManager: makeWorktreeManager(),
+            _mergeQueue: makeMergeQueue(),
+        });
+        const result = await engine.run();
+        expect(result.status).toBe('done');
+    });
+});
+describe('NDJSON recovery', () => {
+    it('truncates partial trailing line in NDJSON file', () => {
+        const convoyId = 'convoy-ndjson-1';
+        const ndjsonPath = join(tmpDir, 'recover-partial.ndjson');
+        const firstLine = JSON.stringify({ _event_id: 1, convoy_id: convoyId, type: 'task_started' });
+        writeFileSync(ndjsonPath, `${firstLine}\n{"_event_id":2`, 'utf8');
+        const mockStore = {
+            getEvents: vi.fn().mockReturnValue([]),
+        };
+        recoverNdjson(mockStore, convoyId, ndjsonPath);
+        const content = readFileSync(ndjsonPath, 'utf8');
+        expect(content).toBe(`${firstLine}\n`);
+    });
+    it('replays SQLite events missing from NDJSON file', () => {
+        const convoyId = 'convoy-ndjson-2';
+        const ndjsonPath = join(tmpDir, 'recover-replay.ndjson');
+        writeFileSync(ndjsonPath, `${JSON.stringify({ _event_id: 1, convoy_id: convoyId, type: 'task_started' })}\n`, 'utf8');
+        const mockStore = {
+            getEvents: vi.fn().mockReturnValue([
+                {
+                    id: 1,
+                    type: 'task_started',
+                    convoy_id: convoyId,
+                    task_id: 'task-1',
+                    worker_id: null,
+                    data: JSON.stringify({ phase: 0 }),
+                    created_at: '2026-03-11T10:00:00.000Z',
+                },
+                {
+                    id: 2,
+                    type: 'task_finished',
+                    convoy_id: convoyId,
+                    task_id: 'task-1',
+                    worker_id: null,
+                    data: JSON.stringify({ success: true }),
+                    created_at: '2026-03-11T10:00:01.000Z',
+                },
+            ]),
+        };
+        recoverNdjson(mockStore, convoyId, ndjsonPath);
+        const lines = readFileSync(ndjsonPath, 'utf8').trim().split('\n').map((line) => JSON.parse(line));
+        const eventIds = lines.map((line) => line._event_id);
+        expect(eventIds).toEqual([1, 2]);
+    });
+    it('does not let event.data override canonical fields', () => {
+        const convoyId = 'convoy-ndjson-canonical';
+        const ndjsonPath = join(tmpDir, 'recover-canonical.ndjson');
+        writeFileSync(ndjsonPath, '', 'utf8');
+        const mockStore = {
+            getEvents: vi.fn().mockReturnValue([
+                {
+                    id: 99,
+                    type: 'task_started',
+                    convoy_id: convoyId,
+                    task_id: 'task-legit',
+                    worker_id: 'w1',
+                    data: JSON.stringify({
+                        _event_id: 'EVIL',
+                        convoy_id: 'EVIL-CONVOY',
+                        task_id: 'EVIL-TASK',
+                        type: 'EVIL-TYPE',
+                        timestamp: 'EVIL-TIME',
+                        worker_id: 'EVIL-WORKER',
+                        safe_field: 'this-is-fine',
+                    }),
+                    created_at: '2026-03-11T10:00:00.000Z',
+                },
+            ]),
+        };
+        recoverNdjson(mockStore, convoyId, ndjsonPath);
+        const lines = readFileSync(ndjsonPath, 'utf8').trim().split('\n');
+        expect(lines).toHaveLength(1);
+        const parsed = JSON.parse(lines[0]);
+        expect(parsed._event_id).toBe(99);
+        expect(parsed.convoy_id).toBe(convoyId);
+        expect(parsed.task_id).toBe('task-legit');
+        expect(parsed.type).toBe('task_started');
+        expect(parsed.worker_id).toBe('w1');
+        expect(parsed.timestamp).toBe('2026-03-11T10:00:00.000Z');
+        expect(parsed.safe_field).toBe('this-is-fine');
+    });
+});
+describe('runConvoyGuard', () => {
+    it('returns passed: false when non-terminal tasks exist', () => {
+        const guardConvoyId = 'convoy-guard-1';
+        const guardStore = createConvoyStore(dbPath);
+        guardStore.insertConvoy({
+            id: guardConvoyId,
+            name: 'Guard test',
+            spec_hash: 'hash',
+            spec_yaml: 'name: guard test',
+            status: 'running',
+            branch: null,
+            created_at: new Date().toISOString(),
+        });
+        guardStore.insertTask({
+            id: 'task-guard-1',
+            convoy_id: guardConvoyId,
+            phase: 0,
+            prompt: 'test',
+            agent: 'developer',
+            adapter: null,
+            model: null,
+            timeout_ms: 60000,
+            status: 'running',
+            retries: 0,
+            max_retries: 1,
+            files: null,
+            depends_on: null,
+            gates: null,
+        });
+        const ndjsonPathGuard = join(tmpDir, 'guard-test.ndjson');
+        writeFileSync(ndjsonPathGuard, '');
+        const wtManager = makeWorktreeManager();
+        const result = runConvoyGuard(guardStore, guardConvoyId, wtManager, ndjsonPathGuard);
+        expect(result.passed).toBe(false);
+        expect(result.warnings.length).toBeGreaterThan(0);
+        guardStore.close();
+    });
+    it('returns passed: true when all tasks are terminal', () => {
+        const guardConvoyId2 = 'convoy-guard-2';
+        const guardStore2 = createConvoyStore(dbPath);
+        guardStore2.insertConvoy({
+            id: guardConvoyId2,
+            name: 'Guard test ok',
+            spec_hash: 'hash',
+            spec_yaml: 'name: guard test ok',
+            status: 'done',
+            branch: null,
+            created_at: new Date().toISOString(),
+        });
+        guardStore2.insertTask({
+            id: 'task-guard-2',
+            convoy_id: guardConvoyId2,
+            phase: 0,
+            prompt: 'test',
+            agent: 'developer',
+            adapter: null,
+            model: null,
+            timeout_ms: 60000,
+            status: 'done',
+            retries: 0,
+            max_retries: 1,
+            files: null,
+            depends_on: null,
+            gates: null,
+        });
+        const ndjsonPathGuard2 = join(tmpDir, 'guard-pass.ndjson');
+        writeFileSync(ndjsonPathGuard2, JSON.stringify({ _event_id: 1, convoy_id: guardConvoyId2, type: 'task_done' }) + '\n');
+        const wtManager2 = makeWorktreeManager();
+        const result2 = runConvoyGuard(guardStore2, guardConvoyId2, wtManager2, ndjsonPathGuard2);
+        expect(result2.passed).toBe(true);
+        guardStore2.close();
+    });
+});
+describe('injectTask partition validation', () => {
+    it('rejects injected tasks with normalized path overlap', () => {
+        const symlinkSpy = vi.spyOn(partition, 'scanSymlinks').mockImplementation(() => { });
+        const convoyId = 'convoy-inject-overlap-1';
+        const seedStore = createConvoyStore(dbPath);
+        seedStore.insertConvoy({
+            id: convoyId,
+            name: 'Inject overlap test',
+            spec_hash: 'hash-1',
+            status: 'pending',
+            branch: null,
+            created_at: new Date().toISOString(),
+            spec_yaml: 'name: inject-overlap',
+            pipeline_id: null,
+        });
+        seedStore.insertTask({
+            id: 'task-owner',
+            convoy_id: convoyId,
+            phase: 0,
+            prompt: 'Owns auth partition',
+            agent: 'developer',
+            adapter: null,
+            model: null,
+            timeout_ms: 30_000,
+            status: 'pending',
+            retries: 0,
+            max_retries: 1,
+            files: JSON.stringify(['src/auth/']),
+            depends_on: null,
+            gates: null,
+        });
+        seedStore.close();
+        const engine = makeEngine({
+            spec: makeSpec(),
+            specYaml: 'name: inject-overlap',
+            adapter: makeAdapter(),
+            dbPath,
+            basePath: tmpDir,
+            _worktreeManager: makeWorktreeManager(),
+            _mergeQueue: makeMergeQueue(),
+        });
+        try {
+            expect(() => engine.injectTask(convoyId, {
+                id: 'task-injected',
+                prompt: 'Injected overlap task',
+                agent: 'developer',
+                phase: 0,
+                files: ['src/auth/service.ts'],
+            })).toThrow(/File partition overlap/i);
+        }
+        finally {
+            symlinkSpy.mockRestore();
+        }
+    });
+    it('rejects injected task with unnormalized paths that overlap', () => {
+        const symlinkSpy = vi.spyOn(partition, 'scanSymlinks').mockImplementation(() => { });
+        const convoyId = 'convoy-inject-overlap-2';
+        const seedStore = createConvoyStore(dbPath);
+        seedStore.insertConvoy({
+            id: convoyId,
+            name: 'Inject overlap test 2',
+            spec_hash: 'hash-2',
+            status: 'pending',
+            branch: null,
+            created_at: new Date().toISOString(),
+            spec_yaml: 'name: inject-overlap-2',
+            pipeline_id: null,
+        });
+        seedStore.insertTask({
+            id: 'task-owner',
+            convoy_id: convoyId,
+            phase: 0,
+            prompt: 'Owns auth partition',
+            agent: 'developer',
+            adapter: null,
+            model: null,
+            timeout_ms: 30_000,
+            status: 'pending',
+            retries: 0,
+            max_retries: 1,
+            files: JSON.stringify(['src/auth/']),
+            depends_on: null,
+            gates: null,
+        });
+        seedStore.close();
+        const engine = makeEngine({
+            spec: makeSpec(),
+            specYaml: 'name: inject-overlap-2',
+            adapter: makeAdapter(),
+            dbPath,
+            basePath: tmpDir,
+            _worktreeManager: makeWorktreeManager(),
+            _mergeQueue: makeMergeQueue(),
+        });
+        try {
+            expect(() => engine.injectTask(convoyId, {
+                id: 'task-injected-dot-path',
+                prompt: 'Injected overlap task',
+                agent: 'developer',
+                phase: 0,
+                files: ['./src/auth/service.ts'],
+            })).toThrow(/File partition overlap/i);
+        }
+        finally {
+            symlinkSpy.mockRestore();
+        }
+    });
+});
+// ── Swarm mode ─────────────────────────────────────────────────────────────
+describe('swarm mode (concurrency: auto)', () => {
+    it('runs all tasks with auto concurrency', async () => {
+        const adapter = makeAdapter();
+        const spec = makeSpec({ concurrency: 'auto' }, [
+            { id: 'task-1', prompt: 'First' },
+            { id: 'task-2', prompt: 'Second' },
+            { id: 'task-3', prompt: 'Third' },
+        ]);
+        const engine = makeEngine({
+            spec,
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: makeWorktreeManager(),
+            _mergeQueue: makeMergeQueue(),
+        });
+        const result = await engine.run();
+        expect(result.status).toBe('done');
+        expect(result.summary.done).toBe(3);
+        expect(result.summary.total).toBe(3);
+    });
+    it('respects max_swarm_concurrency from defaults', async () => {
+        const adapter = makeAdapter();
+        let maxConcurrent = 0;
+        let currentConcurrent = 0;
+        adapter.execute.mockImplementation(async () => {
+            currentConcurrent++;
+            if (currentConcurrent > maxConcurrent)
+                maxConcurrent = currentConcurrent;
+            await new Promise(resolve => setTimeout(resolve, 50));
+            currentConcurrent--;
+            return { success: true, output: 'ok', exitCode: 0 };
+        });
+        const spec = makeSpec({
+            concurrency: 'auto',
+            defaults: { max_swarm_concurrency: 2 },
+        }, [
+            { id: 'task-1', prompt: 'T1' },
+            { id: 'task-2', prompt: 'T2' },
+            { id: 'task-3', prompt: 'T3' },
+            { id: 'task-4', prompt: 'T4' },
+        ]);
+        const engine = makeEngine({
+            spec,
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: makeWorktreeManager(),
+            _mergeQueue: makeMergeQueue(),
+        });
+        const result = await engine.run();
+        expect(result.status).toBe('done');
+        expect(result.summary.done).toBe(4);
+        expect(maxConcurrent).toBeLessThanOrEqual(2);
+    });
+    it('defaults max_swarm_concurrency to 8', async () => {
+        const adapter = makeAdapter();
+        const spec = makeSpec({ concurrency: 'auto' }, Array.from({ length: 10 }, (_, i) => ({
+            id: `task-${i + 1}`,
+            prompt: `Task ${i + 1}`,
+        })));
+        const engine = makeEngine({
+            spec,
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: makeWorktreeManager(),
+            _mergeQueue: makeMergeQueue(),
+        });
+        const result = await engine.run();
+        expect(result.status).toBe('done');
+        expect(result.summary.done).toBe(10);
+    });
+});
+// ── Step retry context prepending ───────────────────────────────────────────
+describe('step retry context prepending', () => {
+    it('prepends prior failure output to the prompt on step retry', async () => {
+        const adapter = makeAdapter();
+        const capturedPrompts = [];
+        adapter.execute.mockImplementation(async (task) => {
+            capturedPrompts.push(task.prompt);
+            if (capturedPrompts.length === 1) {
+                return { success: false, output: 'step error detail', exitCode: 2 };
+            }
+            return { success: true, output: 'ok', exitCode: 0 };
+        });
+        const spec = makeSpec({}, [
+            {
+                id: 'task-1',
+                prompt: 'original task prompt',
+                max_retries: 0,
+                steps: [{ prompt: 'step prompt text', max_retries: 1 }],
+            },
+        ]);
+        const engine = makeEngine({
+            spec,
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: makeWorktreeManager(),
+            _mergeQueue: makeMergeQueue(),
+        });
+        await engine.run();
+        // First call uses the original step prompt
+        expect(capturedPrompts[0]).toBe('step prompt text');
+        // Second call (retry) prepends failure context
+        expect(capturedPrompts[1]).toContain('Previous attempt failed.');
+        expect(capturedPrompts[1]).toContain('Exit code: 2');
+        expect(capturedPrompts[1]).toContain('step error detail');
+        expect(capturedPrompts[1]).toContain('step prompt text');
+    });
+});
+// ── Security: symlink scan (issue #2) ─────────────────────────────────────────
+describe('symlink security scan', () => {
+    it('marks task failed when pre-execution scanSymlinks throws', async () => {
+        const scanSpy = vi.spyOn(partition, 'scanSymlinks').mockImplementation(() => {
+            throw new Error('symlink_escape: "evil.ts" is a symlink that resolves outside the partition');
+        });
+        try {
+            const adapter = makeAdapter();
+            const spec = makeSpec({}, [{ files: ['src/evil.ts'] }]);
+            const engine = makeEngine({
+                spec,
+                specYaml: 'name: test',
+                adapter,
+                dbPath,
+                _worktreeManager: makeWorktreeManager(),
+                _mergeQueue: makeMergeQueue(),
+            });
+            const result = await engine.run();
+            expect(result.status).toBe('failed');
+        }
+        finally {
+            scanSpy.mockRestore();
+        }
+    });
+    it('succeeds when files is empty (symlink scan skipped)', async () => {
+        const adapter = makeAdapter();
+        const spec = makeSpec({}, [{ files: [] }]);
+        const engine = makeEngine({
+            spec,
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: makeWorktreeManager(),
+            _mergeQueue: makeMergeQueue(),
+        });
+        const result = await engine.run();
+        expect(result.status).toBe('done');
+    });
+});
+// ── Security: ensureBranch fallback (issue #3) ────────────────────────────────
+describe('ensureBranch fallback when _ensureBranch not provided', () => {
+    it('calls the injected _ensureBranch when branch is set in spec', async () => {
+        const branchFn = vi.fn().mockResolvedValue(undefined);
+        const adapter = makeAdapter();
+        const spec = makeSpec({ branch: 'feature-x' });
+        const engine = createConvoyEngine({
+            spec,
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: makeWorktreeManager(),
+            _mergeQueue: makeMergeQueue(),
+            _ensureBranch: branchFn,
+        });
+        await engine.run();
+        expect(branchFn).toHaveBeenCalledWith('feature-x', expect.any(String));
+    });
+    it('does not call ensureBranch when spec has no branch', async () => {
+        const branchFn = vi.fn().mockResolvedValue(undefined);
+        const adapter = makeAdapter();
+        const spec = makeSpec({ branch: undefined });
+        const engine = makeEngine({
+            spec,
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: makeWorktreeManager(),
+            _mergeQueue: makeMergeQueue(),
+            _ensureBranch: branchFn,
+        });
+        await engine.run();
+        expect(branchFn).not.toHaveBeenCalled();
+    });
+});
+// ── Security: secret scan in markdown dual-write (issue #4) ──────────────────
+describe('secret scan in DLQ/dispute markdown write', () => {
+    it('task failure still recorded in DB even if DLQ markdown write is silently skipped', async () => {
+        // The engine marks a task as failed; DLQ markdown write with secret scan
+        // silently skips if secrets detected. The DB record is authoritative.
+        const adapter = makeAdapter();
+        vi.mocked(adapter.execute).mockResolvedValue({ success: false, output: 'error', exitCode: 1 });
+        const spec = makeSpec({}, [{ max_retries: 0 }]);
+        const engine = makeEngine({
+            spec,
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: makeWorktreeManager(),
+            _mergeQueue: makeMergeQueue(),
+        });
+        const result = await engine.run();
+        expect(result.status).toBe('failed');
+        expect(result.summary.failed).toBe(1);
+    });
+    it('emits secret_leak_prevented when DLQ markdown write detects secrets', async () => {
+        const scanSpy = vi.spyOn(gates, 'scanForSecrets').mockImplementation((content, filePath = '') => {
+            if (filePath === 'AGENT-FAILURES.md') {
+                return {
+                    clean: false,
+                    findings: [{ pattern: 'Mock Secret', file: filePath, line: 1, snippet: content.slice(0, 20) }],
+                };
+            }
+            return { clean: true, findings: [] };
+        });
+        try {
+            const adapter = makeAdapter();
+            vi.mocked(adapter.execute).mockResolvedValue({ success: false, output: 'fatal', exitCode: 1 });
+            const spec = makeSpec({}, [{ id: 'task-1', max_retries: 0 }]);
+            const engine = makeEngine({
+                spec,
+                specYaml: 'name: secret-dlq',
+                adapter,
+                dbPath,
+                _worktreeManager: makeWorktreeManager(),
+                _mergeQueue: makeMergeQueue(),
+            });
+            const result = await engine.run();
+            const store = createConvoyStore(dbPath);
+            const events = store.getEvents(result.convoyId);
+            store.close();
+            const leakEvent = events.find((event) => event.type === 'secret_leak_prevented');
+            expect(leakEvent).toBeDefined();
+            const data = JSON.parse(leakEvent.data ?? '{}');
+            // context changed from 'dlq_markdown_write' to 'dlq_dual_write' (MF-2 atomicity fix)
+            expect(data.context).toBe('dlq_dual_write');
+        }
+        finally {
+            scanSpy.mockRestore();
+        }
+    });
+    it('DLQ entry is NOT inserted into SQLite when secret scan blocks (MF-2 atomicity)', async () => {
+        const scanSpy = vi.spyOn(gates, 'scanForSecrets').mockImplementation((content, filePath = '') => {
+            if (filePath === 'AGENT-FAILURES.md') {
+                return {
+                    clean: false,
+                    findings: [{ pattern: 'Mock Secret', file: filePath, line: 1, snippet: content.slice(0, 20) }],
+                };
+            }
+            return { clean: true, findings: [] };
+        });
+        try {
+            const adapter = makeAdapter();
+            vi.mocked(adapter.execute).mockResolvedValue({ success: false, output: 'fatal', exitCode: 1 });
+            const spec = makeSpec({}, [{ id: 'task-dlq-atomic', max_retries: 0 }]);
+            const engine = makeEngine({
+                spec,
+                specYaml: 'name: dlq-atomic-test',
+                adapter,
+                dbPath,
+                _worktreeManager: makeWorktreeManager(),
+                _mergeQueue: makeMergeQueue(),
+            });
+            const result = await engine.run();
+            const s = createConvoyStore(dbPath);
+            const dlqEntries = s.listDlqEntries(result.convoyId);
+            s.close();
+            // When scan blocks: SQLite DLQ row must NOT be written (atomic consistency)
+            expect(dlqEntries).toHaveLength(0);
+        }
+        finally {
+            scanSpy.mockRestore();
+        }
+    });
+    it('emits secret_leak_prevented when dispute markdown write detects secrets', async () => {
+        const scanSpy = vi.spyOn(gates, 'scanForSecrets').mockImplementation((content, filePath = '') => {
+            if (filePath === 'DISPUTES.md') {
+                return {
+                    clean: false,
+                    findings: [{ pattern: 'Mock Secret', file: filePath, line: 1, snippet: content.slice(0, 20) }],
+                };
+            }
+            return { clean: true, findings: [] };
+        });
+        try {
+            const adapter = makeAdapter();
+            vi.mocked(adapter.execute).mockResolvedValue({ success: true, output: 'ok', exitCode: 0 });
+            const mockReviewRunner = vi.fn().mockResolvedValue({ verdict: 'block', feedback: 'secret found', tokens: 5, model: 'r' });
+            const engine = makeEngine({
+                spec: makeSpec({ defaults: { review: 'panel' } }, [{ id: 'task-1', max_retries: 3 }]),
+                specYaml: 'name: secret-dispute',
+                adapter,
+                dbPath,
+                _worktreeManager: makeWorktreeManager(),
+                _mergeQueue: makeMergeQueue(),
+                _reviewRunner: mockReviewRunner,
+            });
+            const result = await engine.run();
+            const store = createConvoyStore(dbPath);
+            const events = store.getEvents(result.convoyId);
+            store.close();
+            const leakEvent = events.find((event) => event.type === 'secret_leak_prevented');
+            expect(leakEvent).toBeDefined();
+            const data = JSON.parse(leakEvent.data ?? '{}');
+            expect(data.context).toBe('dispute_markdown_write');
+        }
+        finally {
+            scanSpy.mockRestore();
+        }
+    });
+});
+// ── Security: fileExists path traversal (issue #5) ────────────────────────────
+describe('fileExists step condition path traversal', () => {
+    it('step with fileExists using relative path executes normally when file absent', async () => {
+        const adapter = makeAdapter();
+        const capturedPrompts = [];
+        vi.mocked(adapter.execute).mockImplementation(async (task) => {
+            capturedPrompts.push(task.prompt);
+            return { success: true, output: 'ok', exitCode: 0 };
+        });
+        const spec = makeSpec({}, [{
+                steps: [
+                    {
+                        prompt: 'conditional prompt',
+                        if: { step: 'prev', fileExists: { path: 'some-nonexistent-file.txt' } },
+                    },
+                    {
+                        prompt: 'always runs',
+                    },
+                ],
+            }]);
+        const engine = makeEngine({
+            spec,
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: makeWorktreeManager(),
+            _mergeQueue: makeMergeQueue(),
+        });
+        const result = await engine.run();
+        expect(result.status).toBe('done');
+    });
+    it('step condition with path traversal attempt does not throw (returns false)', async () => {
+        const adapter = makeAdapter();
+        const spec = makeSpec({}, [{
+                steps: [
+                    {
+                        prompt: 'should be skipped',
+                        if: { step: 'prev', fileExists: { path: '../../../etc/passwd' } },
+                    },
+                    {
+                        prompt: 'safe step',
+                    },
+                ],
+            }]);
+        const engine = makeEngine({
+            spec,
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: makeWorktreeManager(),
+            _mergeQueue: makeMergeQueue(),
+        });
+        const result = await engine.run();
+        // Engine should not crash; traversal step is skipped (fileExists returns false)
+        expect(result.status).toBe('done');
+    });
+});
+// ── Circuit breaker ───────────────────────────────────────────────────────────
+describe('circuit breaker', () => {
+    it('allows task when no circuit_breaker config is set', async () => {
+        const adapter = makeAdapter();
+        const spec = makeSpec({}, [{}]);
+        const engine = makeEngine({
+            spec,
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: makeWorktreeManager(),
+            _mergeQueue: makeMergeQueue(),
+        });
+        const result = await engine.run();
+        expect(result.status).toBe('done');
+        expect(result.summary.done).toBe(1);
+        expect(adapter.execute).toHaveBeenCalledTimes(1);
+    });
+    it('allows task when agent circuit is closed', async () => {
+        const adapter = makeAdapter();
+        const spec = makeSpec({
+            defaults: { circuit_breaker: { threshold: 3, cooldown_ms: 300_000 } },
+        }, [{ id: 'task-ok', agent: 'developer', max_retries: 0 }]);
+        const engine = makeEngine({
+            spec,
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: makeWorktreeManager(),
+            _mergeQueue: makeMergeQueue(),
+        });
+        const result = await engine.run();
+        expect(result.status).toBe('done');
+        expect(adapter.execute).toHaveBeenCalledTimes(1);
+    });
+    it('blocks subsequent tasks when circuit trips after threshold failures', async () => {
+        const adapter = makeAdapter();
+        // task-1 fails, task-2 and task-3 should be blocked by open circuit
+        adapter.execute
+            .mockResolvedValueOnce({ success: false, output: 'err', exitCode: 1 })
+            .mockResolvedValue({ success: true, output: 'ok', exitCode: 0 });
+        // threshold=2: task-1 failure is recorded twice (failure path + handleExhaustion),
+        // reaching threshold=2 → circuit opens before task-2 and task-3 execute
+        const spec = makeSpec({
+            on_failure: 'continue',
+            defaults: { circuit_breaker: { threshold: 2, cooldown_ms: 999_999_999 } },
+        }, [
+            { id: 'task-1', agent: 'developer', max_retries: 0 },
+            { id: 'task-2', agent: 'developer', max_retries: 0 },
+            { id: 'task-3', agent: 'developer', max_retries: 0 },
+        ]);
+        const engine = makeEngine({
+            spec,
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: makeWorktreeManager(),
+            _mergeQueue: makeMergeQueue(),
+        });
+        const result = await engine.run();
+        // Only task-1 should have hit the adapter (circuit opens after task-1 fails)
+        expect(adapter.execute).toHaveBeenCalledTimes(1);
+        // task-2 and task-3 should be skipped by the circuit breaker
+        expect(result.summary.skipped).toBeGreaterThanOrEqual(2);
+    });
+    it('records success and persists closed circuit state to store', async () => {
+        const adapter = makeAdapter();
+        const spec = makeSpec({
+            defaults: { circuit_breaker: { threshold: 3, cooldown_ms: 300_000 } },
+        }, [{ id: 'task-s', agent: 'developer', max_retries: 0 }]);
+        const engine = makeEngine({
+            spec,
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: makeWorktreeManager(),
+            _mergeQueue: makeMergeQueue(),
+        });
+        const result = await engine.run();
+        expect(result.status).toBe('done');
+        const store = createConvoyStore(dbPath);
+        const record = store.getLatestConvoy();
+        if (record?.circuit_state) {
+            const state = JSON.parse(record.circuit_state);
+            expect(state.developer?.status ?? 'closed').toBe('closed');
+        }
+        store.close();
+    });
+    it('records failure and persists open circuit state to store after threshold', async () => {
+        const adapter = makeAdapter();
+        adapter.execute.mockResolvedValue({ success: false, output: 'err', exitCode: 1 });
+        // threshold=2: first failure double-records → count reaches 2 → circuit opens
+        const spec = makeSpec({
+            on_failure: 'continue',
+            defaults: { circuit_breaker: { threshold: 2, cooldown_ms: 999_999_999 } },
+        }, [
+            { id: 'task-f1', agent: 'developer', max_retries: 0 },
+        ]);
+        const engine = makeEngine({
+            spec,
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: makeWorktreeManager(),
+            _mergeQueue: makeMergeQueue(),
+        });
+        await engine.run();
+        const store = createConvoyStore(dbPath);
+        const record = store.getLatestConvoy();
+        expect(record?.circuit_state).not.toBeNull();
+        if (record?.circuit_state) {
+            const state = JSON.parse(record.circuit_state);
+            expect(state.developer?.status).toBe('open');
+        }
+        store.close();
+    });
+    it('circuit state is persisted to the store after a successful task', async () => {
+        const adapter = makeAdapter();
+        const spec = makeSpec({
+            defaults: { circuit_breaker: { threshold: 2, cooldown_ms: 60_000 } },
+        }, [{ id: 'task-persist', agent: 'developer', max_retries: 0 }]);
+        const engine = makeEngine({
+            spec,
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: makeWorktreeManager(),
+            _mergeQueue: makeMergeQueue(),
+        });
+        await engine.run();
+        const store = createConvoyStore(dbPath);
+        const record = store.getLatestConvoy();
+        expect(record?.circuit_state).not.toBeNull();
+        store.close();
+    });
+});
+describe('convoy lifecycle events', () => {
+    it('emits convoy_finished event on successful run', async () => {
+        const adapter = makeAdapter();
+        const engine = makeEngine({
+            spec: makeSpec(),
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: makeWorktreeManager(),
+            _mergeQueue: makeMergeQueue(),
+        });
+        const result = await engine.run();
+        expect(result.status).toBe('done');
+        const store = createConvoyStore(dbPath);
+        const events = store.getEvents(result.convoyId);
+        store.close();
+        const finishedEvent = events.find(e => e.type === 'convoy_finished');
+        expect(finishedEvent).toBeDefined();
+        expect(finishedEvent.convoy_id).toBe(result.convoyId);
+        expect(JSON.parse(finishedEvent.data).status).toBe('done');
+    });
+    it('emits convoy_failed event when a task fails', async () => {
+        const adapter = makeAdapter();
+        adapter.execute.mockResolvedValue({
+            success: false,
+            output: 'error',
+            exitCode: 1,
+        });
+        const engine = makeEngine({
+            spec: makeSpec({}, [{ id: 'fail-task', max_retries: 0 }]),
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: makeWorktreeManager(),
+            _mergeQueue: makeMergeQueue(),
+        });
+        const result = await engine.run();
+        expect(result.status).toBe('failed');
+        const store = createConvoyStore(dbPath);
+        const events = store.getEvents(result.convoyId);
+        store.close();
+        const failedEvent = events.find(e => e.type === 'convoy_failed');
+        expect(failedEvent).toBeDefined();
+        expect(failedEvent.convoy_id).toBe(result.convoyId);
+        expect(JSON.parse(failedEvent.data).status).toBe('failed');
+    });
+    it('emits convoy_failed with gate-failed status when gates fail', async () => {
+        const adapter = makeAdapter();
+        const engine = makeEngine({
+            spec: makeSpec({ gates: ['false'] }),
+            specYaml: 'name: test',
+            adapter,
+            dbPath,
+            _worktreeManager: makeWorktreeManager(),
+            _mergeQueue: makeMergeQueue(),
+        });
+        const result = await engine.run();
+        expect(result.status).toBe('gate-failed');
+        const store = createConvoyStore(dbPath);
+        const events = store.getEvents(result.convoyId);
+        store.close();
+        const failedEvent = events.find(e => e.type === 'convoy_failed');
+        expect(failedEvent).toBeDefined();
+        expect(JSON.parse(failedEvent.data).status).toBe('gate-failed');
+    });
+});
+describe('createEventEmitter callsite safety', () => {
+    it('rejects a raw string argument', () => {
+        const testStore = createConvoyStore(dbPath);
+        expect(() => {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            createEventEmitter(testStore, 'some-path');
+        }).toThrow('createEventEmitter options must be an object, not a string');
+        testStore.close();
+    });
+    it('accepts an options object with ndjsonPath', () => {
+        const testStore = createConvoyStore(dbPath);
+        const testNdjsonPath = join(tmpDir, 'callsite-test.ndjson');
+        const emitter = createEventEmitter(testStore, { ndjsonPath: testNdjsonPath });
+        expect(emitter).toBeDefined();
+        expect(typeof emitter.emit).toBe('function');
+        expect(typeof emitter.close).toBe('function');
+        emitter.close();
+        testStore.close();
+    });
+});
 //# sourceMappingURL=engine.test.js.map