opencastle 0.26.1 → 0.27.1

package/dist/cli/convoy/engine.js

@@ -1,20 +1,320 @@
 import { execFile as execFileCb } from 'node:child_process';
 import { createHash } from 'node:crypto';
-import { mkdirSync } from 'node:fs';
+import { appendFileSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
 import { promisify } from 'node:util';
-import { createConvoyStore } from './store.js';
+import { createConvoyStore, ConvoyArtifactLimitError } from './store.js';
+import { acquireEngineLock } from './lock.js';
 import { createEventEmitter } from './events.js';
 import { createWorktreeManager } from './worktree.js';
-import { createMergeQueue } from './merge.js';
-import { createHealthMonitor } from './health.js';
+import { createMergeQueue, MergeConflictError } from './merge.js';
+import { createHealthMonitor, detectDrift } from './health.js';
 import { exportConvoyToNdjson } from './export.js';
 import { buildPhases, formatDuration } from '../run/executor.js';
-import { parseTimeout } from '../run/schema.js';
+import { parseTimeout, parseYaml } from '../run/schema.js';
 import { getAdapter, detectAdapter } from '../run/adapters/index.js';
 import { c } from '../prompt.js';
+import { validateFilePartitions, scanSymlinks, scanNewSymlinks, normalizePath, pathsOverlap } from './partition.js';
+import { scanForSecrets, runSecretScanGate, runBlastRadiusGate, browserTestGate } from './gates.js';
+import { readLessons, captureLessons, consolidateLessons } from './lessons.js';
+import { updateExpertise, feedCircuitBreaker } from './expertise.js';
+import { buildKnowledgeGraph } from './knowledge.js';
+import { injectDiscoveredIssuesInstruction, checkDiscoveredIssues, consolidateIssues } from './issues.js';
 const execFile = promisify(execFileCb);
+export class CircuitBreakerManager {
+    states = new Map();
+    threshold;
+    cooldownMs;
+    fallbackAgent;
+    constructor(config, initialState) {
+        this.threshold = config?.threshold ?? 3;
+        this.cooldownMs = config?.cooldown_ms ?? 300_000;
+        this.fallbackAgent = config?.fallback_agent ?? null;
+        if (initialState) {
+            for (const [agent, state] of Object.entries(initialState)) {
+                this.states.set(agent, state);
+            }
+        }
+    }
+    getState(agent) {
+        return this.states.get(agent) ?? { status: 'closed', failures: 0, last_failure_at: null, opened_at: null };
+    }
+    recordFailure(agent) {
+        const state = this.getState(agent);
+        const now = new Date().toISOString();
+        if (state.status === 'half-open') {
+            // Probe failed — back to open, reset cooldown
+            state.status = 'open';
+            state.opened_at = now;
+            state.last_failure_at = now;
+            this.states.set(agent, state);
+            return { tripped: true, state };
+        }
+        state.failures += 1;
+        state.last_failure_at = now;
+        if (state.failures >= this.threshold) {
+            state.status = 'open';
+            state.opened_at = now;
+            this.states.set(agent, state);
+            return { tripped: true, state };
+        }
+        this.states.set(agent, state);
+        return { tripped: false, state };
+    }
+    recordSuccess(agent) {
+        const state = this.getState(agent);
+        if (state.status === 'half-open') {
+            // Probe succeeded — close circuit
+            state.status = 'closed';
+            state.failures = 0;
+            state.opened_at = null;
+        }
+        else if (state.status === 'closed') {
+            state.failures = 0;
+        }
+        this.states.set(agent, state);
+        return state;
+    }
+    canAssign(agent) {
+        const state = this.getState(agent);
+        if (state.status === 'closed')
+            return true;
+        if (state.status === 'half-open')
+            return true; // allow 1 probe
+        // Open — check cooldown
+        if (state.opened_at) {
+            const elapsed = Date.now() - new Date(state.opened_at).getTime();
+            if (elapsed >= this.cooldownMs) {
+                state.status = 'half-open';
+                this.states.set(agent, state);
+                return true;
+            }
+        }
+        return false;
+    }
+    get fallback() {
+        return this.fallbackAgent;
+    }
+    serialize() {
+        return JSON.stringify(Object.fromEntries(this.states));
+    }
+}
+// ── Branch management ───────────────────────────────────────────────────────
+/**
+ * Ensure the given branch exists and is checked out.
+ * Creates the branch from HEAD if it does not yet exist.
+ * Fails fast if there are uncommitted changes.
+ */
+export async function ensureBranch(branchName, basePath) {
+    // Validate refspec — reject shell metacharacters
+    if (!/^[a-zA-Z0-9\-/_\.]+$/.test(branchName)) {
+        throw new Error(`Invalid branch name "${branchName}": only alphanumeric, -, /, _, and . are allowed`);
+    }
+    // Refuse to switch branches with uncommitted changes
+    const { stdout: statusOut } = await execFile('git', ['status', '--porcelain'], {
+        cwd: basePath,
+    });
+    if (statusOut.trim()) {
+        throw new Error(`Uncommitted changes detected in "${basePath}". Commit or stash before switching branches.`);
+    }
+    // Check if branch already exists
+    try {
+        await execFile('git', ['rev-parse', '--verify', branchName], { cwd: basePath });
+        // Branch exists — check it out
+        await execFile('git', ['checkout', branchName], { cwd: basePath });
+    }
+    catch {
+        // Branch does not exist — create from current HEAD
+        await execFile('git', ['checkout', '-b', branchName], { cwd: basePath });
+    }
+}
 // ── Internal helpers ──────────────────────────────────────────────────────────
+/**
+ * Truncate any trailing partial line in the NDJSON file, then replay any SQLite
+ * events for the given convoy that are missing from the file.
+ * Exported for unit testing.
+ */
+function safeJsonParse(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+export function recoverNdjson(store, convoyId, ndjsonPath) {
+    // 1. Read the NDJSON file (if it exists)
+    let fileContent;
+    try {
+        fileContent = readFileSync(ndjsonPath, 'utf8');
+    }
+    catch {
+        fileContent = '';
+    }
+    // 2. Truncate any partial trailing line (no \n terminator)
+    if (fileContent.length > 0 && !fileContent.endsWith('\n')) {
+        const lastNewline = fileContent.lastIndexOf('\n');
+        if (lastNewline === -1) {
+            writeFileSync(ndjsonPath, '');
+            fileContent = '';
+        }
+        else {
+            writeFileSync(ndjsonPath, fileContent.slice(0, lastNewline + 1));
+            fileContent = fileContent.slice(0, lastNewline + 1);
+        }
+    }
+    // 3. Count valid NDJSON event IDs for this convoy
+    const ndjsonIds = new Set();
+    for (const line of fileContent.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed.convoy_id === convoyId && parsed._event_id != null) {
+                ndjsonIds.add(parsed._event_id);
+            }
+        }
+        catch {
+            // Skip unparseable lines
+        }
+    }
+    // 4. Get all SQLite events for this convoy
+    const sqliteEvents = store.getEvents(convoyId);
+    // 5. Replay missing events (those in SQLite but not in NDJSON)
+    const missing = sqliteEvents.filter(e => e.id != null && !ndjsonIds.has(e.id));
+    if (missing.length > 0) {
+        const fd = openSync(ndjsonPath, 'a');
+        try {
+            for (const event of missing) {
+                const parsedData = event.data ? safeJsonParse(event.data) : {};
+                const record = {
+                    ...parsedData,
+                    _event_id: event.id,
+                    timestamp: event.created_at,
+                    type: event.type,
+                    convoy_id: event.convoy_id,
+                    task_id: event.task_id,
+                    worker_id: event.worker_id,
+                };
+                appendFileSync(fd, JSON.stringify(record) + '\n');
+            }
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
+    }
+}
+export function runConvoyGuard(store, convoyId, _wtManager, ndjsonPath, guardConfig) {
+    // If guard is explicitly disabled, skip all checks
+    if (guardConfig?.enabled === false) {
+        return { passed: true, warnings: [] };
+    }
+    const warnings = [];
+    const tasks = store.getTasksByConvoy(convoyId);
+    // Check 1: All task statuses are terminal
+    const terminalStatuses = new Set(['done', 'failed', 'skipped', 'timed-out', 'gate-failed', 'review-blocked', 'hook-failed', 'disputed']);
+    const nonTerminal = tasks.filter(t => !terminalStatuses.has(t.status));
+    if (nonTerminal.length > 0) {
+        warnings.push(`Non-terminal tasks: ${nonTerminal.map(t => `${t.id}(${t.status})`).join(', ')}`);
+    }
+    // Check 2: NDJSON file exists and record count >= completed task count
+    const completedTasks = tasks.filter(t => t.status === 'done');
+    try {
+        const content = readFileSync(ndjsonPath, 'utf8');
+        const lines = content.split('\n').filter(l => l.trim());
+        const convoyLines = lines.filter(l => {
+            try {
+                return JSON.parse(l).convoy_id === convoyId;
+            }
+            catch {
+                return false;
+            }
+        });
+        if (convoyLines.length < completedTasks.length) {
+            warnings.push(`NDJSON record count (${convoyLines.length}) < completed tasks (${completedTasks.length})`);
+        }
+    }
+    catch {
+        if (completedTasks.length > 0) {
+            warnings.push(`NDJSON file not found at ${ndjsonPath} but ${completedTasks.length} tasks completed`);
+        }
+    }
+    // Check 3: Every retried task has events for each attempt
+    const retriedTasks = tasks.filter(t => t.retries > 0);
+    const events = store.getEvents(convoyId);
+    for (const task of retriedTasks) {
+        const taskEvents = events.filter(e => e.task_id === task.id && e.type === 'task_started');
+        if (taskEvents.length < task.retries) {
+            warnings.push(`Task ${task.id} has ${task.retries} retries but only ${taskEvents.length} task_started events`);
+        }
+    }
+    // Check 4: Gate results recorded for all gates that ran
+    const gateEvents = events.filter(e => e.type === 'built_in_gate_result' || (e.data != null && e.data.includes('gate')));
+    const tasksWithGates = tasks.filter(t => t.gates);
+    if (tasksWithGates.length > 0 && gateEvents.length === 0) {
+        warnings.push('Tasks have gates configured but no gate result events found');
+    }
+    // Check 5: Token/cost totals computed
+    const convoy = store.getConvoy(convoyId);
+    if (convoy && convoy.total_tokens == null) {
+        const totalTokens = tasks.reduce((sum, t) => sum + (t.total_tokens ?? 0), 0);
+        if (totalTokens > 0) {
+            warnings.push('Convoy total_tokens not persisted despite tasks having token data');
+        }
+    }
+    // Check 6: No orphaned worktrees — engine already calls removeAll() during cleanup.
+    // Synchronous check is not possible; the engine handles this.
+    return { passed: warnings.length === 0, warnings };
+}
+export function evaluateReviewLevel(task, diff, heuristics, allGatesPassed) {
+    const panelPaths = heuristics?.panel_paths ?? ['auth/', 'security/', 'migrations/', 'rls/'];
+    const panelAgents = heuristics?.panel_agents ?? ['security-expert', 'database-engineer'];
+    const autoPassAgents = heuristics?.auto_pass_agents ?? ['documentation-writer', 'copywriter'];
+    const autoPassMaxLines = heuristics?.auto_pass_max_lines ?? 10;
+    const autoPassMaxFiles = heuristics?.auto_pass_max_files ?? 2;
+    // Panel: sensitive paths or agents
+    if (panelPaths.some(p => diff.filePaths.some(fp => fp.startsWith(p) || fp.includes('/' + p))))
+        return 'panel';
+    if (panelAgents.includes(task.agent))
+        return 'panel';
+    // Auto-pass: documentation/copy agents
+    if (autoPassAgents.includes(task.agent))
+        return 'auto-pass';
+    // Auto-pass: small diffs with all gates passing
+    if (diff.linesChanged <= autoPassMaxLines && diff.filesChanged <= autoPassMaxFiles && allGatesPassed !== false)
+        return 'auto-pass';
+    // Large diffs → fast review
+    if (diff.linesChanged > 200 || diff.filesChanged > 5)
+        return 'fast';
+    // Default → fast review
+    return 'fast';
+}
+class ReviewSemaphore {
+    max;
+    current = 0;
+    queue = [];
+    constructor(max) {
+        this.max = max;
+    }
+    async acquire() {
+        if (this.current < this.max) {
+            this.current++;
+            return;
+        }
+        return new Promise(resolve => {
+            this.queue.push(() => { this.current++; resolve(); });
+        });
+    }
+    release() {
+        this.current--;
+        if (this.queue.length > 0) {
+            const next = this.queue.shift();
+            next();
+        }
+    }
+}
 function msToTimeout(ms) {
     if (ms >= 3_600_000 && ms % 3_600_000 === 0)
         return `${ms / 3_600_000}h`;
@@ -22,6 +322,58 @@ function msToTimeout(ms) {
         return `${ms / 60_000}m`;
     return `${ms / 1_000}s`;
 }
+// ── DLQ markdown dual-write ───────────────────────────────────────────────────
+// Builds the DLQ markdown entry text (no I/O, no scanning).
+function buildDlqMarkdownEntry(dlqId, task, failureType, errorOutput) {
+    const marker = `<!-- dlq:${dlqId} -->`;
+    const entry = `\n${marker}\n### ${dlqId}\n\n| Field | Value |\n|-------|-------|\n| Task | ${task.id} |\n| Agent | ${task.agent} |\n| Type | ${failureType} |\n| Attempts | ${task.retries + 1} |\n| Date | ${new Date().toISOString()} |\n\n**Error:**\n\`\`\`\n${(errorOutput ?? '(no output)').slice(0, 2000)}\n\`\`\`\n`;
+    return { marker, entry };
+}
+// Appends a pre-scanned DLQ entry to AGENT-FAILURES.md. The caller must have
+// already verified the entry is clean via scanForSecrets — no re-scan here.
+function appendDlqMarkdownClean(marker, entry) {
+    const mdPath = join(resolve(process.cwd()), '.opencastle', 'AGENT-FAILURES.md');
+    try {
+        const existing = readFileSync(mdPath, 'utf8');
+        if (existing.includes(marker))
+            return;
+    }
+    catch {
+        // File doesn't exist yet — will create
+    }
+    mkdirSync(dirname(mdPath), { recursive: true });
+    appendFileSync(mdPath, entry);
+}
+function writeDisputeToMarkdown(disputeId, convoyId, task, panelResults, events) {
+    const mdPath = join(resolve(process.cwd()), 'DISPUTES.md');
+    const marker = `<!-- dispute:${disputeId} -->`;
+    try {
+        const existing = readFileSync(mdPath, 'utf8');
+        if (existing.includes(marker))
+            return;
+    }
+    catch {
+        // File doesn't exist yet
+    }
+    const blockingReasons = panelResults
+        .filter(r => r.verdict === 'block')
+        .map(r => r.feedback)
+        .join('\n\n');
+    const entry = `\n${marker}\n## Dispute: ${task.id}\n\n| Field | Value |\n|-------|-------|\n| Convoy | ${convoyId} |\n| Task | ${task.id} |\n| Date | ${new Date().toISOString()} |\n| Panel attempts | ${task.panel_attempts + 1} |\n| Agent | ${task.agent} |\n| Status | Open |\n\n**Blocking reasons:**\n\n${blockingReasons}\n`;
+    const scanResult = scanForSecrets(entry, 'DISPUTES.md');
+    if (!scanResult.clean) {
+        if (events) {
+            events.emit('secret_leak_prevented', {
+                task_id: task.id,
+                findings_count: scanResult.findings.length,
+                patterns: scanResult.findings.map((f) => f.pattern),
+                context: 'dispute_markdown_write',
+            }, { convoy_id: convoyId, task_id: task.id });
+        }
+        return;
+    }
+    appendFileSync(mdPath, entry);
+}
 function taskRecordToTask(record) {
     return {
         id: record.id,
@@ -34,6 +386,7 @@ function taskRecordToTask(record) {
         model: record.model ?? undefined,
         max_retries: record.max_retries,
         adapter: record.adapter ?? undefined,
+        gates: record.gates ? JSON.parse(record.gates) : undefined,
     };
 }
 function makeTimeoutPromise(ms) {
@@ -44,11 +397,322 @@ function makeTimeoutPromise(ms) {
     return { promise, clear: () => { if (timerId !== undefined)
             clearTimeout(timerId); } };
 }
+// ── Step condition evaluation ─────────────────────────────────────────────────
+function evaluateStepCondition(condition, stepResults, worktreePath, basePath) {
+    if (!condition)
+        return true;
+    if (condition.exitCode) {
+        const prevResult = stepResults.get(condition.step);
+        if (!prevResult)
+            return false;
+        const code = prevResult.exitCode;
+        const ec = condition.exitCode;
+        if (ec.eq !== undefined && code !== ec.eq)
+            return false;
+        if (ec.ne !== undefined && code === ec.ne)
+            return false;
+        if (ec.gt !== undefined && !(code > ec.gt))
+            return false;
+        if (ec.lt !== undefined && !(code < ec.lt))
+            return false;
+    }
+    if (condition.fileExists) {
+        const base = worktreePath ?? basePath;
+        if (condition.fileExists.path.startsWith('/')) {
+            return false; // Absolute paths not allowed in step conditions
+        }
+        const filePath = join(base, condition.fileExists.path);
+        const resolved = resolve(filePath);
+        const resolvedBase = resolve(base);
+        if (!resolved.startsWith(resolvedBase + '/') && resolved !== resolvedBase) {
+            return false; // path escapes the worktree — treat as "file doesn't exist"
+        }
+        if (!existsSync(filePath))
+            return false;
+    }
+    return true;
+}
+async function executeSteps(taskRecord, steps, adapter, worktreePath, basePath, store, convoyId, verbose) {
+    const now = () => new Date().toISOString();
+    const stepResults = new Map();
+    let combinedOutput = '';
+    let lastExitCode = 0;
+    // Track total_steps in DB
+    store.updateTaskStatus(taskRecord.id, convoyId, 'running', {});
+    for (let i = 0; i < steps.length; i++) {
+        const step = steps[i];
+        // Evaluate condition — skip step if condition is not met
+        if (step.if) {
+            const condMet = evaluateStepCondition(step.if, stepResults, worktreePath, basePath);
+            if (!condMet) {
+                const stepId = store.insertTaskStep({
+                    task_id: taskRecord.id,
+                    step_index: i,
+                    prompt: step.prompt,
+                    gates: step.gates ? JSON.stringify(step.gates) : null,
+                    status: 'skipped',
+                    exit_code: null,
+                    output: 'Skipped: condition not met',
+                    started_at: now(),
+                    finished_at: now(),
+                });
+                if (step.id) {
+                    stepResults.set(step.id, { exitCode: 0 });
+                }
+                combinedOutput += `\n[Step ${i + 1} skipped: condition not met]`;
+                continue;
+            }
+        }
+        // Insert step record as running
+        const stepDbId = store.insertTaskStep({
+            task_id: taskRecord.id,
+            step_index: i,
+            prompt: step.prompt,
+            gates: step.gates ? JSON.stringify(step.gates) : null,
+            status: 'running',
+            exit_code: null,
+            output: null,
+            started_at: now(),
+            finished_at: null,
+        });
+        // Update current_step on the task record
+        store.updateTaskStatus(taskRecord.id, convoyId, 'running', {});
+        const stepMaxRetries = step.max_retries ?? taskRecord.max_retries;
+        let stepResult = { success: false, output: '', exitCode: -1 };
+        let stepAttempt = 0;
+        while (stepAttempt <= stepMaxRetries) {
+            // Prepend prior failure context on retries
+            let stepPrompt = step.prompt;
+            if (stepAttempt > 0 && stepResult) {
+                const failedOutput = stepResult.output || '(no output)';
+                stepPrompt = `Previous attempt failed.\nExit code: ${stepResult.exitCode}\nError output:\n${failedOutput}\n\nFix the issues and try again.\n\n` + step.prompt;
+            }
+            const stepTask = {
+                id: taskRecord.id,
+                prompt: stepPrompt,
+                agent: taskRecord.agent,
+                timeout: `${taskRecord.timeout_ms}ms`,
+                depends_on: [],
+                files: taskRecord.files ? JSON.parse(taskRecord.files) : [],
+                description: `step ${i + 1}`,
+                max_retries: stepMaxRetries,
+            };
+            try {
+                stepResult = await adapter.execute(stepTask, { verbose, cwd: worktreePath ?? basePath });
+            }
+            catch (err) {
+                stepResult = { success: false, output: err.message, exitCode: -1 };
+            }
+            if (stepResult.success)
+                break;
+            stepAttempt++;
+            if (stepAttempt <= stepMaxRetries) {
+                process.stdout.write(`  ↺ step ${i + 1}/${steps.length} failed, retry ${stepAttempt}/${stepMaxRetries}\n`);
+            }
+        }
+        lastExitCode = stepResult.exitCode;
+        combinedOutput += `\n[Step ${i + 1}]\n${stepResult.output}`;
+        if (step.id) {
+            stepResults.set(step.id, { exitCode: stepResult.exitCode });
+        }
+        // Run step-level gates if present
+        if (step.gates && step.gates.length > 0 && stepResult.success) {
+            let gateFailure = null;
+            const execFileCb = (await import('node:child_process')).execFile;
+            const execFileP = (await import('node:util')).promisify(execFileCb);
+            for (const command of step.gates) {
+                try {
+                    // SECURITY: Gate/hook commands come from the .convoy.yml spec file, which is operator-controlled.
+                    // They are NOT user-supplied and are part of the trusted build configuration.
+                    await execFileP('sh', ['-c', command], { cwd: worktreePath ?? basePath });
+                }
+                catch (gateErr) {
+                    const ge = gateErr;
+                    const code = typeof ge.code === 'number' ? ge.code : 1;
+                    const output = ge.stderr || ge.stdout || ge.message || '';
+                    gateFailure = { command, exitCode: code, output };
+                    break;
+                }
+            }
+            if (gateFailure !== null) {
+                stepResult = { success: false, output: `Gate failed: ${gateFailure.command}\nExit code: ${gateFailure.exitCode}\n${gateFailure.output}`, exitCode: gateFailure.exitCode };
+                lastExitCode = gateFailure.exitCode;
+                combinedOutput += `\n[Step ${i + 1} gate failed: ${gateFailure.command}]`;
+            }
+        }
+        // Update step record
+        store.updateTaskStep(stepDbId, {
+            status: stepResult.success ? 'done' : 'failed',
+            exit_code: stepResult.exitCode,
+            output: stepResult.output,
+            finished_at: now(),
+        });
+        if (!stepResult.success) {
+            return {
+                success: false,
+                output: combinedOutput.trim(),
+                exitCode: lastExitCode,
+            };
+        }
+    }
+    return {
+        success: true,
+        output: combinedOutput.trim(),
+        exitCode: lastExitCode,
+    };
+}
+// ── File-based injection ──────────────────────────────────────────────────────
+const INJECT_DIR = '.opencastle/convoy-inject';
+const CONVOY_ID_RE = /^[a-zA-Z0-9-]+$/;
+const MAX_FILE_INJECTED_TASKS = 10;
+function pollInjectFile(convoyId, store, events, basePath) {
+    // Path traversal guard: convoy_id must be alphanumeric + hyphens only
+    if (!CONVOY_ID_RE.test(convoyId))
+        return 0;
+    const injectDir = join(basePath, INJECT_DIR, convoyId);
+    const injectPath = join(injectDir, 'inject.yml');
+    if (!existsSync(injectPath))
+        return 0;
+    // Atomic rename to prevent double-read
+    const processingPath = injectPath + '.processing';
+    try {
+        renameSync(injectPath, processingPath);
+    }
+    catch {
+        return 0; // Another process may have grabbed it
+    }
+    let raw;
+    try {
+        raw = readFileSync(processingPath, 'utf8');
+    }
+    catch {
+        return 0;
+    }
+    finally {
+        try {
+            unlinkSync(processingPath);
+        }
+        catch { /* ignore */ }
+    }
+    let parsed;
+    try {
+        parsed = parseYaml(raw);
+        if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.tasks)) {
+            process.stderr.write(`Warning: inject file has invalid format (expected { tasks: [...] })\n`);
+            return 0;
+        }
+    }
+    catch (err) {
+        process.stderr.write(`Warning: failed to parse inject file: ${err.message}\n`);
+        return 0;
+    }
+    const tasks = parsed.tasks;
+    const allExisting = store.getTasksByConvoy(convoyId);
+    const existingFileInjected = allExisting.filter(t => t.provenance === 'file-injection').length;
+    const remaining = MAX_FILE_INJECTED_TASKS - existingFileInjected;
+    let injectedCount = 0;
+    for (const rawTask of tasks) {
+        if (injectedCount >= remaining) {
+            process.stderr.write(`Warning: file injection limit reached (${MAX_FILE_INJECTED_TASKS}), skipping remaining tasks\n`);
+            break;
+        }
+        // Validate required fields
+        if (!rawTask.id || typeof rawTask.id !== 'string') {
+            process.stderr.write(`Warning: skipping injected task with missing/invalid id\n`);
+            continue;
+        }
+        if (!rawTask.prompt || typeof rawTask.prompt !== 'string') {
+            process.stderr.write(`Warning: skipping injected task "${rawTask.id}": missing prompt\n`);
+            continue;
+        }
+        if (!rawTask.agent || typeof rawTask.agent !== 'string') {
+            process.stderr.write(`Warning: skipping injected task "${rawTask.id}": missing agent\n`);
+            continue;
+        }
+        // Check ID uniqueness
+        if (allExisting.some(t => t.id === rawTask.id)) {
+            process.stderr.write(`Warning: skipping injected task "${rawTask.id}": ID already exists\n`);
+            continue;
+        }
+        // Determine phase — inject into last scheduled phase
+        const maxPhase = allExisting.reduce((max, t) => Math.max(max, t.phase), 0);
+        // Validate file paths before building the record
+        let validatedFiles = null;
+        if (rawTask.files && Array.isArray(rawTask.files)) {
+            try {
+                validatedFiles = JSON.stringify(rawTask.files.map(f => normalizePath(f)));
+            }
+            catch (err) {
+                process.stderr.write(`Warning: skipping injected task "${rawTask.id}": invalid file path: ${err.message}\n`);
+                continue;
+            }
+        }
+        const record = {
+            id: rawTask.id,
+            convoy_id: convoyId,
+            phase: maxPhase,
+            prompt: rawTask.prompt,
+            agent: rawTask.agent,
+            adapter: null,
+            model: null,
+            timeout_ms: typeof rawTask.timeout_ms === 'number' ? rawTask.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: typeof rawTask.max_retries === 'number' ? rawTask.max_retries : 1,
+            files: validatedFiles,
+            depends_on: null,
+            prompt_tokens: null,
+            completion_tokens: null,
+            total_tokens: null,
+            cost_usd: null,
+            gates: null,
+            on_exhausted: 'dlq',
+            injected: 1,
+            provenance: 'file-injection',
+            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,
+            outputs: null,
+            inputs: null,
+            discovered_issues: null,
+        };
+        try {
+            store.insertInjectedTask(record);
+            injectedCount++;
+        }
+        catch (err) {
+            process.stderr.write(`Warning: failed to inject task "${rawTask.id}": ${err.message}\n`);
+        }
+    }
+    if (injectedCount > 0) {
+        events.emit('file_injection_received', {
+            task_count: injectedCount,
+            source: injectPath,
+        }, { convoy_id: convoyId });
+    }
+    return injectedCount;
+}
 // ── Core convoy execution ─────────────────────────────────────────────────────
-async function runConvoy(convoyId, spec, adapter, store, events, wtManager, mergeQueue, basePath, baseBranch, verbose, startTime) {
+async function runConvoy(convoyId, spec, adapter, store, events, wtManager, mergeQueue, basePath, baseBranch, verbose, startTime, ndjsonPath, reviewRunner) {
     const totalTasks = spec.tasks?.length ?? 0;
     let completedCount = 0;
     const activeTaskMap = new Map();
+    const reviewSemaphore = new ReviewSemaphore(spec.defaults?.max_concurrent_reviews ?? 3);
+    let reviewTokensTotal = 0;
     const taskAdapterMap = new Map();
     const healthMonitor = createHealthMonitor({
         store,
@@ -65,6 +729,17 @@ async function runConvoy(convoyId, spec, adapter, store, events, wtManager, merg
         },
     });
     healthMonitor.start();
+    // ── Circuit breaker ────────────────────────────────────────────────────────
+    const circuitBreakerConfig = spec.defaults?.circuit_breaker;
+    const convoyRecord = store.getConvoy(convoyId);
+    const initialCircuitState = convoyRecord?.circuit_state ? JSON.parse(convoyRecord.circuit_state) : undefined;
+    const circuitBreaker = new CircuitBreakerManager(circuitBreakerConfig, initialCircuitState);
+    // ── Trust model ────────────────────────────────────────────────────────────
+    // Gate commands, hook commands, and step commands in .convoy.yml are treated
+    // as operator-controlled build configuration (analogous to Makefiles, CI
+    // configs, or package.json scripts). They are executed via sh -c and must
+    // NOT contain user-supplied input. The spec file itself is the trust boundary.
+    // ──────────────────────────────────────────────────────────────────────────
     // ── Task skipping ─────────────────────────────────────────────────────────
     function skipTask(taskId, reason, visited = new Set()) {
         if (visited.has(taskId))
@@ -101,6 +776,133 @@ async function runConvoy(convoyId, spec, adapter, store, events, wtManager, merg
             }
         }
     }
+    function handleExhaustion(taskRecord, failureType, errorOutput) {
+        const exhausted = taskRecord.on_exhausted ?? 'dlq';
+        if (exhausted === 'dlq' || exhausted === 'stop') {
+            const dlqId = `dlq-${taskRecord.id}-${Date.now()}`;
+            // Pre-scan: build the markdown entry and check for secrets BEFORE any
+            // writes. This keeps the SQLite DLQ row and the Markdown file in sync —
+            // either both are written or neither is (MF-2 dual-write atomicity).
+            const { marker: dlqMarker, entry: dlqMdEntry } = buildDlqMarkdownEntry(dlqId, taskRecord, failureType, errorOutput);
+            const dlqScanResult = scanForSecrets(dlqMdEntry, 'AGENT-FAILURES.md');
+            if (!dlqScanResult.clean) {
+                // Block BOTH writes to maintain consistent state
+                events.emit('secret_leak_prevented', {
+                    task_id: taskRecord.id,
+                    findings_count: dlqScanResult.findings.length,
+                    patterns: dlqScanResult.findings.map((f) => f.pattern),
+                    context: 'dlq_dual_write',
+                }, { convoy_id: convoyId, task_id: taskRecord.id });
+            }
+            else {
+                // Clean — proceed with both writes atomically
+                store.insertDlqEntry({
+                    id: dlqId,
+                    convoy_id: convoyId,
+                    task_id: taskRecord.id,
+                    agent: taskRecord.agent,
+                    failure_type: failureType,
+                    error_output: errorOutput,
+                    attempts: taskRecord.retries + 1,
+                    tokens_spent: taskRecord.total_tokens,
+                    escalation_task_id: null,
+                    resolved: 0,
+                    resolution: null,
+                    created_at: new Date().toISOString(),
+                    resolved_at: null,
+                });
+                appendDlqMarkdownClean(dlqMarker, dlqMdEntry);
+                events.emit('dlq_entry_created', {
+                    dlq_id: dlqId,
+                    task_id: taskRecord.id,
+                    agent: taskRecord.agent,
+                    failure_type: failureType,
+                }, { convoy_id: convoyId, task_id: taskRecord.id });
+            }
+        }
+        if (exhausted === 'stop') {
+            // Skip all remaining pending tasks + set convoy to failed
+            const allPending = store.getTasksByConvoy(convoyId).filter(t => t.status === 'pending');
+            for (const t of allPending) {
+                skipTask(t.id, `on_exhausted: stop — task "${taskRecord.id}" exhausted retries`);
+            }
+            store.updateConvoyStatus(convoyId, 'failed');
+        }
+        else if (exhausted === 'dlq' || exhausted === 'skip') {
+            // Default behavior: cascade failure to dependents only
+            cascadeFailure(taskRecord.id);
+        }
+        // ── Circuit breaker: record exhaustion failure ──────────────────────────
+        if (circuitBreakerConfig) {
+            const { tripped } = circuitBreaker.recordFailure(taskRecord.agent);
+            try {
+                store.updateConvoyCircuitState(convoyId, circuitBreaker.serialize());
+            }
+            catch { /* non-critical */ }
+            if (tripped) {
+                events.emit('circuit_breaker_tripped', {
+                    agent: taskRecord.agent,
+                    state: circuitBreaker.getState(taskRecord.agent),
+                }, { convoy_id: convoyId, task_id: taskRecord.id });
+            }
+        }
+    }
+    // ── Hook execution ────────────────────────────────────────────────────────
+    async function runHooks(hooks, lifecycle, context) {
+        const filtered = hooks.filter(h => (h.on ?? 'post_task') === lifecycle);
+        for (const hook of filtered) {
+            if (hook.type === 'command' || hook.type === 'guard' || hook.type === 'validate') {
+                const cmd = hook.command;
+                if (!cmd)
+                    continue;
+                try {
+                    // SECURITY: Gate/hook commands come from the .convoy.yml spec file, which is operator-controlled.
+                    // They are NOT user-supplied and are part of the trusted build configuration.
+                    await execFile('sh', ['-c', cmd], { cwd: context.cwd });
+                }
+                catch (err) {
+                    const execErr = err;
+                    const errorMsg = execErr.stderr || execErr.stdout || execErr.message || '';
+                    return { passed: false, failedHook: hook, error: errorMsg };
+                }
+            }
+            else if (hook.type === 'agent') {
+                if (!hook.prompt)
+                    continue;
+                const hookTask = {
+                    id: `hook-${lifecycle}-${context.taskId ?? 'convoy'}-${Date.now()}`,
+                    prompt: hook.prompt,
+                    agent: hook.name ?? 'developer',
+                    timeout: '10m',
+                    depends_on: [],
+                    files: [],
+                    description: `Hook: ${hook.name ?? hook.type}`,
+                    max_retries: 0,
+                };
+                try {
+                    const hookResult = await adapter.execute(hookTask, { verbose, cwd: context.cwd });
+                    if (!hookResult.success) {
+                        return { passed: false, failedHook: hook, error: hookResult.output };
+                    }
+                }
+                catch (err) {
+                    return { passed: false, failedHook: hook, error: err.message };
+                }
+            }
+            else if (hook.type === 'review') {
+                if (!context.taskId || !reviewRunner)
+                    continue;
+                const reviewTaskRecord = store.getTask(context.taskId, context.convoyId);
+                if (reviewTaskRecord) {
+                    const reviewResult = await reviewRunner(reviewTaskRecord, 'fast', spec.defaults?.reviewer_model ?? 'default');
+                    if (reviewResult.verdict !== 'pass') {
+                        return { passed: false, failedHook: hook, error: reviewResult.feedback };
+                    }
+                }
+            }
+        }
+        return { passed: true };
+    }
     // ── Single-task executor ──────────────────────────────────────────────────
     async function executeOneTask(taskRecord) {
         const workerId = `worker-${taskRecord.id}-${Date.now()}`;
@@ -119,6 +921,65 @@ async function runConvoy(convoyId, spec, adapter, store, events, wtManager, merg
             }
         }
         taskAdapterMap.set(taskRecord.id, taskAdapter);
+        // ── Check inputs availability ────────────────────────────────────────────
+        if (taskRecord.inputs) {
+            const inputs = JSON.parse(taskRecord.inputs);
+            for (const input of inputs) {
+                const artifact = store.getArtifact(convoyId, input.name);
+                if (!artifact) {
+                    store.updateTaskStatus(taskRecord.id, convoyId, 'wait-for-input');
+                    events.emit('task_waiting_input', {
+                        task_id: taskRecord.id,
+                        missing_artifact: input.name,
+                        from_task: input.from,
+                    }, { convoy_id: convoyId, task_id: taskRecord.id });
+                    taskAdapterMap.delete(taskRecord.id);
+                    return;
+                }
+            }
+        }
+        // ── Circuit breaker check ──────────────────────────────────────────────
+        if (circuitBreakerConfig) {
+            if (!circuitBreaker.canAssign(taskRecord.agent)) {
+                const fallback = circuitBreaker.fallback;
+                if (fallback) {
+                    events.emit('circuit_breaker_fallback', {
+                        original_agent: taskRecord.agent,
+                        fallback_agent: fallback,
+                        state: circuitBreaker.getState(taskRecord.agent),
+                    }, { convoy_id: convoyId, task_id: taskRecord.id });
+                }
+                else {
+                    events.emit('circuit_breaker_blocked', {
+                        agent: taskRecord.agent,
+                        state: circuitBreaker.getState(taskRecord.agent),
+                    }, { convoy_id: convoyId, task_id: taskRecord.id });
+                }
+                store.updateTaskStatus(taskRecord.id, convoyId, 'skipped', {
+                    output: `Circuit breaker open for agent "${taskRecord.agent}". ${fallback ? `No fallback available.` : `No fallback configured.`}`,
+                });
+                completedCount++;
+                taskAdapterMap.delete(taskRecord.id);
+                cascadeFailure(taskRecord.id);
+                return;
+            }
+        }
+        // ── Intelligence: circuit breaker weak-area avoidance (Phase 18.2) ─────
+        if (spec.defaults?.avoid_weak_agents) {
+            try {
+                const weakAreas = feedCircuitBreaker(taskRecord.agent, basePath);
+                const taskFiles = taskRecord.files ? JSON.parse(taskRecord.files) : [];
+                const matchesWeakArea = weakAreas.some(area => taskFiles.some(f => f.toLowerCase().includes(area.toLowerCase())));
+                if (matchesWeakArea && taskRecord.retries === 0) {
+                    events.emit('weak_area_skipped', { agent: taskRecord.agent, weak_areas: weakAreas, task_files: taskFiles }, { convoy_id: convoyId, task_id: taskRecord.id });
+                    store.updateTaskStatus(taskRecord.id, convoyId, 'skipped', { output: `Agent "${taskRecord.agent}" has weak-area match for task files. Skipped by avoid_weak_agents policy.` });
+                    completedCount++;
+                    taskAdapterMap.delete(taskRecord.id);
+                    return;
+                }
+            }
+            catch { /* non-critical */ }
+        }
         // Create worktree (skip for copilot adapter)
         let worktreePath = null;
         if (taskAdapter.name !== 'copilot') {
@@ -150,16 +1011,149 @@ async function runConvoy(convoyId, spec, adapter, store, events, wtManager, merg
         store.updateWorkerStatus(workerId, 'running');
         const task = taskRecordToTask(taskRecord);
         activeTaskMap.set(taskRecord.id, task);
+        // ── Inject inputs into prompt ────────────────────────────────────────────
+        if (taskRecord.inputs) {
+            const inputs = JSON.parse(taskRecord.inputs);
+            for (const input of inputs) {
+                const artifact = store.getArtifact(convoyId, input.name);
+                const templateVar = input.as ?? input.name;
+                task.prompt = task.prompt.replaceAll(`{{input.${templateVar}}}`, artifact.content);
+            }
+        }
+        // ── Scratchpad template substitution (Phase 17.1) ───────────────────────
+        const scratchpadRe = /\{\{scratchpad\.([a-zA-Z0-9_.-]+)\}\}/g;
+        let scratchpadMatch;
+        while ((scratchpadMatch = scratchpadRe.exec(task.prompt)) !== null) {
+            const spKey = scratchpadMatch[1];
+            const spVal = store.getScratchpadValue(spKey);
+            if (spVal !== null) {
+                task.prompt = task.prompt.replaceAll(`{{scratchpad.${spKey}}}`, spVal);
+                scratchpadRe.lastIndex = 0; // reset after replaceAll
+            }
+        }
         process.stdout.write(`  ${c.cyan('▶')} ${c.bold(`[${taskRecord.id}]`)} ${taskRecord.agent}${worktreePath ? c.dim(' (worktree)') : ''}\n`);
         events.emit('task_started', { worker_id: workerId }, { convoy_id: convoyId, task_id: taskRecord.id, worker_id: workerId });
         const taskStartTime = Date.now();
+        // ── Outbound prompt scan — NEVER send a prompt containing secrets ─────────
+        const promptScan = scanForSecrets(taskRecord.prompt, `task:${taskRecord.id}`);
+        if (!promptScan.clean) {
+            store.updateTaskStatus(taskRecord.id, convoyId, 'failed', {
+                finished_at: now(),
+                output: `Secret detected in prompt — task blocked before execution.\nFindings:\n${promptScan.findings
+                    .map((f) => `  ${f.pattern} at line ${f.line}: ${f.snippet}`)
+                    .join('\n')}`,
+            });
+            store.updateWorkerStatus(workerId, 'failed', { finished_at: now() });
+            completedCount++;
+            events.emit('secret_leak_prevented', {
+                task_id: taskRecord.id,
+                findings_count: promptScan.findings.length,
+                patterns: promptScan.findings.map((f) => f.pattern),
+            }, { convoy_id: convoyId, task_id: taskRecord.id });
+            cascadeFailure(taskRecord.id);
+            taskAdapterMap.delete(taskRecord.id);
+            return;
+        }
         const timeout = makeTimeoutPromise(taskRecord.timeout_ms);
         let result;
+        // Retrieve steps from spec if defined
+        const specTask = (spec.tasks ?? []).find(t => t.id === taskRecord.id);
+        const steps = specTask?.steps;
+        const taskHooks = specTask?.hooks ?? [];
+        // ── Intelligence: inject lessons (Phase 18.1) ─────────────────────────
+        if (spec.defaults?.inject_lessons !== false) {
+            try {
+                const taskFiles = taskRecord.files ? JSON.parse(taskRecord.files) : [];
+                const lessons = readLessons(taskRecord.agent, taskFiles, basePath);
+                if (lessons.length > 0) {
+                    const lessonsBlock = '\n\n---\nRelevant lessons from previous sessions:\n'
+                        + lessons.join('\n\n')
+                        + '\n---\n\n';
+                    task.prompt = lessonsBlock + task.prompt;
+                }
+            }
+            catch { /* non-critical */ }
+        }
+        // ── Intelligence: inject persistent agent identity (Phase 17.2) ────────
+        const specTaskForPersistent = (spec.tasks ?? []).find(t => t.id === taskRecord.id);
+        if (specTaskForPersistent?.persistent) {
+            try {
+                const identities = store.getAgentIdentities(taskRecord.agent, 3);
+                if (identities.length > 0) {
+                    const contextBlock = '\n\n[Previous work context]\n'
+                        + identities.map(id => id.summary).join('\n\n')
+                        + '\n[End previous context]\n\n';
+                    task.prompt = contextBlock + task.prompt;
+                }
+            }
+            catch { /* non-critical */ }
+        }
+        // ── Intelligence: inject discovered issues instruction (Phase 18.4) ────
+        if (spec.defaults?.track_discovered_issues) {
+            task.prompt = injectDiscoveredIssuesInstruction(task.prompt);
+        }
+        // ── pre_task hooks ────────────────────────────────────────────────────────
+        if (taskHooks.length > 0) {
+            const preResult = await runHooks(taskHooks, 'pre_task', {
+                taskId: taskRecord.id,
+                convoyId,
+                cwd: worktreePath ?? basePath,
+            });
+            if (!preResult.passed) {
+                await removeWorktree();
+                const hookLabel = preResult.failedHook?.name ?? preResult.failedHook?.type ?? 'unknown';
+                store.withTransaction(() => {
+                    store.updateTaskStatus(taskRecord.id, convoyId, 'hook-failed', {
+                        finished_at: now(),
+                        output: `pre_task hook "${hookLabel}" failed: ${preResult.error ?? ''}`,
+                        exit_code: 1,
+                    });
+                    store.updateWorkerStatus(workerId, 'failed', { finished_at: now() });
+                });
+                completedCount++;
+                process.stdout.write(`  ${c.red('✗')} ${c.bold(`[${taskRecord.id}]`)} pre_task hook failed ${c.dim(`[${completedCount}/${totalTasks}]`)}\n`);
+                events.emit('task_failed', { reason: 'hook-failed', hook: hookLabel, worker_id: workerId }, { convoy_id: convoyId, task_id: taskRecord.id, worker_id: workerId });
+                cascadeFailure(taskRecord.id);
+                taskAdapterMap.delete(taskRecord.id);
+                return;
+            }
+        }
+        // ── Symlink security scan (pre-execution) ────────────────────────────────
+        const taskFiles = taskRecord.files ? JSON.parse(taskRecord.files) : [];
+        if (taskFiles.length > 0 && worktreePath) {
+            try {
+                scanSymlinks(taskFiles, worktreePath);
+            }
+            catch (err) {
+                await removeWorktree();
+                store.withTransaction(() => {
+                    store.updateTaskStatus(taskRecord.id, convoyId, 'failed', {
+                        finished_at: now(),
+                        output: `Symlink security check failed: ${err.message}`,
+                        exit_code: 1,
+                    });
+                    store.updateWorkerStatus(workerId, 'failed', { finished_at: now() });
+                });
+                completedCount++;
+                events.emit('task_failed', { reason: 'symlink-escape', worker_id: workerId }, { convoy_id: convoyId, task_id: taskRecord.id, worker_id: workerId });
+                cascadeFailure(taskRecord.id);
+                taskAdapterMap.delete(taskRecord.id);
+                return;
+            }
+        }
         try {
-            result = await Promise.race([
-                taskAdapter.execute(task, { verbose, cwd: worktreePath ?? basePath }),
-                timeout.promise,
-            ]);
+            if (steps && steps.length > 0) {
+                result = await Promise.race([
+                    executeSteps(taskRecord, steps, taskAdapter, worktreePath, basePath, store, convoyId, verbose),
+                    timeout.promise,
+                ]);
+            }
+            else {
+                result = await Promise.race([
+                    taskAdapter.execute(task, { verbose, cwd: worktreePath ?? basePath }),
+                    timeout.promise,
+                ]);
+            }
             timeout.clear();
         }
         catch (err) {
@@ -184,12 +1178,14 @@ async function runConvoy(convoyId, spec, adapter, store, events, wtManager, merg
             await removeWorktree();
             const freshRecord = store.getTask(taskRecord.id, convoyId);
             if (freshRecord.retries < freshRecord.max_retries && spec.on_failure !== 'stop') {
+                const contextPrefix = `Previous attempt timed out.\n\nFix the issues and try again.\n\n`;
                 store.updateTaskStatus(taskRecord.id, convoyId, 'pending', {
                     retries: freshRecord.retries + 1,
                     worker_id: null,
                     worktree: null,
                     started_at: null,
                     finished_at: null,
+                    prompt: contextPrefix + taskRecord.prompt,
                 });
                 store.updateWorkerStatus(workerId, 'killed', { finished_at: finishedAt });
                 process.stdout.write(`  ${c.yellow('⟳')} ${c.bold(`[${taskRecord.id}]`)} timed out, retry ${freshRecord.retries + 1}/${freshRecord.max_retries}\n`);
@@ -226,23 +1222,654 @@ async function runConvoy(convoyId, spec, adapter, store, events, wtManager, merg
                     phase: taskRecord.phase,
                     convoy_id: convoyId,
                 }, { convoy_id: convoyId, task_id: taskRecord.id });
-                cascadeFailure(taskRecord.id);
+                handleExhaustion(freshRecord, 'timeout', result.output || null);
             }
             taskAdapterMap.delete(taskRecord.id);
             return;
         }
         // ── Success ─────────────────────────────────────────────────────────────
-        if (result.success) {
-            if (worktreePath) {
+        if (result.success) { // ── Per-task gates ─────────────────────────────────────────────────────
+            const taskGates = taskRecord.gates ? JSON.parse(taskRecord.gates) : [];
+            if (taskGates.length > 0) {
+                let gateFailure = null;
+                for (const command of taskGates) {
+                    try {
+                        // SECURITY: Gate/hook commands come from the .convoy.yml spec file, which is operator-controlled.
+                        // They are NOT user-supplied and are part of the trusted build configuration.
+                        await execFile('sh', ['-c', command], { cwd: worktreePath ?? basePath });
+                    }
+                    catch (err) {
+                        const execErr = err;
+                        const code = typeof execErr.code === 'number' ? execErr.code : 1;
+                        const output = execErr.stderr || execErr.stdout || execErr.message || '';
+                        gateFailure = { command, exitCode: code, output };
+                        break;
+                    }
+                }
+                if (gateFailure !== null) {
+                    await removeWorktree();
+                    const freshRecord = store.getTask(taskRecord.id, convoyId);
+                    if (freshRecord.retries < freshRecord.max_retries && spec.on_failure !== 'stop') {
+                        const contextPrefix = `Previous attempt's gate check failed.\nGate: ${gateFailure.command}\nExit code: ${gateFailure.exitCode}\nOutput:\n${gateFailure.output || '(no output)'}\n\nFix the issues and try again.\n\n`;
+                        store.updateTaskStatus(taskRecord.id, convoyId, 'pending', {
+                            retries: freshRecord.retries + 1,
+                            worker_id: null,
+                            worktree: null,
+                            started_at: null,
+                            finished_at: null,
+                            prompt: contextPrefix + taskRecord.prompt,
+                        });
+                        store.updateWorkerStatus(workerId, 'failed', { finished_at: finishedAt });
+                        process.stdout.write(`  ${c.yellow('⟳')} ${c.bold(`[${taskRecord.id}]`)} gate failed, retry ${freshRecord.retries + 1}/${freshRecord.max_retries}\n`);
+                    }
+                    else {
+                        store.withTransaction(() => {
+                            store.updateTaskStatus(taskRecord.id, convoyId, 'gate-failed', {
+                                finished_at: finishedAt,
+                                output: `Gate failed: ${gateFailure.command}\nExit code: ${gateFailure.exitCode}\n${gateFailure.output}`,
+                                exit_code: gateFailure.exitCode,
+                            });
+                            store.updateWorkerStatus(workerId, 'failed', { finished_at: finishedAt });
+                        });
+                        completedCount++;
+                        process.stdout.write(`  ${c.red('✗')} ${c.bold(`[${taskRecord.id}]`)} gate failed ${elapsed} ${c.dim(`[${completedCount}/${totalTasks}]`)}\n`);
+                        events.emit('task_failed', { reason: 'gate-failed', gate: gateFailure.command, exit_code: gateFailure.exitCode, worker_id: workerId }, { convoy_id: convoyId, task_id: taskRecord.id, worker_id: workerId });
+                        events.emit('session', {
+                            agent: taskRecord.agent,
+                            model: taskRecord.model ?? taskAdapter.name,
+                            task: taskRecord.id,
+                            outcome: 'failed',
+                            duration_min: Math.round((Date.now() - taskStartTime) / 60_000),
+                            files_changed: 0,
+                            retries: freshRecord.retries,
+                            convoy_id: convoyId,
+                        }, { convoy_id: convoyId, task_id: taskRecord.id });
+                        events.emit('delegation', {
+                            session_id: convoyId,
+                            agent: taskRecord.agent,
+                            model: taskRecord.model ?? taskAdapter.name,
+                            tier: 'standard',
+                            mechanism: 'convoy',
+                            outcome: 'failed',
+                            retries: freshRecord.retries,
+                            phase: taskRecord.phase,
+                            convoy_id: convoyId,
+                        }, { convoy_id: convoyId, task_id: taskRecord.id });
+                        handleExhaustion(freshRecord, 'gate-failed', gateFailure.output || null);
+                    }
+                    taskAdapterMap.delete(taskRecord.id);
+                    return;
+                }
+            }
+            // ── Built-in gates ────────────────────────────────────────────────────
+            const builtInGates = spec.defaults?.built_in_gates;
+            if (builtInGates && worktreePath) {
+                if (builtInGates.browser_test) {
+                    const specTask = (spec.tasks ?? []).find(t => t.id === taskRecord.id);
+                    const taskBrowserConfig = specTask?.browser_test ?? spec.defaults?.browser_test;
+                    if (!taskBrowserConfig) {
+                        process.stderr.write(`Warning: browser_test gate enabled but no browser_test config (urls) found — skipping\n`);
+                    }
+                    else {
+                        const browserResult = await browserTestGate({
+                            mcpServers: spec.defaults?.mcp_servers ?? [],
+                            taskConfig: taskBrowserConfig,
+                            worktreePath,
+                            approvalTimeout: spec.defaults?.mcp_server_approval_timeout,
+                        });
+                        events.emit('built_in_gate_result', { gate: 'browser_test', passed: browserResult.passed, output: browserResult.output }, { convoy_id: convoyId, task_id: taskRecord.id });
+                        if (!browserResult.passed) {
+                            await removeWorktree();
+                            const freshRecord = store.getTask(taskRecord.id, convoyId);
+                            if (freshRecord.retries < freshRecord.max_retries && spec.on_failure !== 'stop') {
+                                store.updateTaskStatus(taskRecord.id, convoyId, 'pending', {
+                                    retries: freshRecord.retries + 1,
+                                    worker_id: null,
+                                    worktree: null,
+                                    started_at: null,
+                                    finished_at: null,
+                                });
+                                store.updateWorkerStatus(workerId, 'failed', { finished_at: finishedAt });
+                                process.stdout.write(`  ${c.yellow('⟳')} ${c.bold(`[${taskRecord.id}]`)} browser test gate failed, retry ${freshRecord.retries + 1}/${freshRecord.max_retries}\n`);
+                            }
+                            else {
+                                store.withTransaction(() => {
+                                    store.updateTaskStatus(taskRecord.id, convoyId, 'gate-failed', {
+                                        finished_at: finishedAt,
+                                        output: `Built-in gate (browser_test) failed:\n${browserResult.output}`,
+                                        exit_code: 1,
+                                    });
+                                    store.updateWorkerStatus(workerId, 'failed', { finished_at: finishedAt });
+                                });
+                                completedCount++;
+                                process.stdout.write(`  ${c.red('✗')} ${c.bold(`[${taskRecord.id}]`)} browser test gate failed ${elapsed} ${c.dim(`[${completedCount}/${totalTasks}]`)}\n`);
+                                events.emit('task_failed', { reason: 'gate-failed', gate: 'browser_test', worker_id: workerId }, { convoy_id: convoyId, task_id: taskRecord.id, worker_id: workerId });
+                                handleExhaustion(freshRecord, 'browser-test', browserResult.output);
+                            }
+                            taskAdapterMap.delete(taskRecord.id);
+                            return;
+                        }
+                    }
+                }
+                let changedFiles = [];
+                let diff = '';
+                try {
+                    const { stdout: filesOut } = await execFile('git', ['diff', '--name-only', `${baseBranch}..HEAD`], { cwd: worktreePath });
+                    changedFiles = filesOut.split('\n').filter(Boolean);
+                    const { stdout: diffOut } = await execFile('git', ['diff', `${baseBranch}..HEAD`], { cwd: worktreePath });
+                    diff = diffOut;
+                }
+                catch { /* no commits in worktree yet — skip */ }
+                // Secret scan gate
+                if (builtInGates.secret_scan && changedFiles.length > 0) {
+                    const scanResult = await runSecretScanGate(changedFiles, worktreePath);
+                    events.emit('built_in_gate_result', { gate: 'secret_scan', passed: scanResult.passed, output: scanResult.output }, { convoy_id: convoyId, task_id: taskRecord.id });
+                    if (!scanResult.passed) {
+                        await removeWorktree();
+                        const freshRecord = store.getTask(taskRecord.id, convoyId);
+                        if (freshRecord.retries < freshRecord.max_retries && spec.on_failure !== 'stop') {
+                            store.updateTaskStatus(taskRecord.id, convoyId, 'pending', {
+                                retries: freshRecord.retries + 1,
+                                worker_id: null,
+                                worktree: null,
+                                started_at: null,
+                                finished_at: null,
+                                prompt: `Secret scan gate failed.\n${scanResult.output}\n\nFix the issues and try again.\n\n${taskRecord.prompt}`,
+                            });
+                            store.updateWorkerStatus(workerId, 'failed', { finished_at: finishedAt });
+                            process.stdout.write(`  ${c.yellow('⟳')} ${c.bold(`[${taskRecord.id}]`)} secret scan gate failed, retry ${freshRecord.retries + 1}/${freshRecord.max_retries}\n`);
+                        }
+                        else {
+                            store.withTransaction(() => {
+                                store.updateTaskStatus(taskRecord.id, convoyId, 'gate-failed', {
+                                    finished_at: finishedAt,
+                                    output: `Built-in gate (secret_scan) failed:\n${scanResult.output}`,
+                                    exit_code: 1,
+                                });
+                                store.updateWorkerStatus(workerId, 'failed', { finished_at: finishedAt });
+                            });
+                            completedCount++;
+                            process.stdout.write(`  ${c.red('✗')} ${c.bold(`[${taskRecord.id}]`)} secret scan gate failed ${elapsed} ${c.dim(`[${completedCount}/${totalTasks}]`)}\n`);
+                            events.emit('task_failed', { reason: 'gate-failed', gate: 'secret_scan', worker_id: workerId }, { convoy_id: convoyId, task_id: taskRecord.id, worker_id: workerId });
+                            handleExhaustion(freshRecord, 'secret-scan', scanResult.output);
+                        }
+                        taskAdapterMap.delete(taskRecord.id);
+                        return;
+                    }
+                }
+                // Blast radius gate
+                if (builtInGates.blast_radius && diff) {
+                    const blastResult = runBlastRadiusGate(diff);
+                    events.emit('built_in_gate_result', { gate: 'blast_radius', level: blastResult.level, passed: blastResult.passed, output: blastResult.output }, { convoy_id: convoyId, task_id: taskRecord.id });
+                    if (!blastResult.passed) {
+                        await removeWorktree();
+                        const freshRecord = store.getTask(taskRecord.id, convoyId);
+                        if (freshRecord.retries < freshRecord.max_retries && spec.on_failure !== 'stop') {
+                            store.updateTaskStatus(taskRecord.id, convoyId, 'pending', {
+                                retries: freshRecord.retries + 1,
+                                worker_id: null,
+                                worktree: null,
+                                started_at: null,
+                                finished_at: null,
+                                prompt: `Blast radius gate failed.\n${blastResult.output}\n\nFix the issues and try again.\n\n${taskRecord.prompt}`,
+                            });
+                            store.updateWorkerStatus(workerId, 'failed', { finished_at: finishedAt });
+                            process.stdout.write(`  ${c.yellow('⟳')} ${c.bold(`[${taskRecord.id}]`)} blast radius gate failed, retry ${freshRecord.retries + 1}/${freshRecord.max_retries}\n`);
+                        }
+                        else {
+                            store.withTransaction(() => {
+                                store.updateTaskStatus(taskRecord.id, convoyId, 'gate-failed', {
+                                    finished_at: finishedAt,
+                                    output: `Built-in gate (blast_radius) failed:\n${blastResult.output}`,
+                                    exit_code: 1,
+                                });
+                                store.updateWorkerStatus(workerId, 'failed', { finished_at: finishedAt });
+                            });
+                            completedCount++;
+                            process.stdout.write(`  ${c.red('✗')} ${c.bold(`[${taskRecord.id}]`)} blast radius gate failed ${elapsed} ${c.dim(`[${completedCount}/${totalTasks}]`)}\n`);
+                            events.emit('task_failed', { reason: 'gate-failed', gate: 'blast_radius', worker_id: workerId }, { convoy_id: convoyId, task_id: taskRecord.id, worker_id: workerId });
+                            handleExhaustion(freshRecord, 'gate-failed', blastResult.output);
+                        }
+                        taskAdapterMap.delete(taskRecord.id);
+                        return;
+                    }
+                }
+            }
+            // ── Drift detection ──────────────────────────────────────────────────
+            const specTaskForDrift = (spec.tasks ?? []).find(t => t.id === taskRecord.id);
+            const isDriftEnabled = specTaskForDrift?.detect_drift ?? spec.defaults?.detect_drift ?? false;
+            if (isDriftEnabled && taskRecord.drift_retried === 0) {
+                const driftResult = await detectDrift(taskRecord, taskAdapter);
+                events.emit('drift_check_result', {
+                    task_id: taskRecord.id,
+                    score: driftResult.score,
+                    threshold: driftResult.threshold,
+                    explanation: driftResult.explanation,
+                    drifted: driftResult.drifted,
+                }, { convoy_id: convoyId, task_id: taskRecord.id });
+                store.updateTaskDrift(taskRecord.id, convoyId, { drift_score: driftResult.score });
+                if (driftResult.drifted) {
+                    events.emit('drift_detected', {
+                        task_id: taskRecord.id,
+                        score: driftResult.score,
+                        threshold: driftResult.threshold,
+                    }, { convoy_id: convoyId, task_id: taskRecord.id });
+                    await removeWorktree();
+                    store.updateTaskDrift(taskRecord.id, convoyId, { drift_retried: 1 });
+                    store.updateTaskStatus(taskRecord.id, convoyId, 'pending', {
+                        worker_id: null,
+                        worktree: null,
+                        started_at: null,
+                        finished_at: null,
+                    });
+                    store.updateWorkerStatus(workerId, 'failed', { finished_at: finishedAt });
+                    process.stdout.write(`  ${c.yellow('⟳')} ${c.bold(`[${taskRecord.id}]`)} drift detected (score: ${driftResult.score.toFixed(2)}), retrying\n`);
+                    taskAdapterMap.delete(taskRecord.id);
+                    return;
+                }
+            }
+            // ── Review pipeline ──────────────────────────────────────────────────
+            const specTaskForReview = (spec.tasks ?? []).find(t => t.id === taskRecord.id);
+            const taskReviewSetting = specTaskForReview?.review ?? spec.defaults?.review ?? 'auto';
+            if (taskReviewSetting !== 'none') {
+                // Compute diff stats from worktree
+                let reviewChangedFiles = [];
+                let reviewDiffLines = 0;
+                if (worktreePath) {
+                    try {
+                        const { stdout: filesOut } = await execFile('git', ['diff', '--name-only', `${baseBranch}..HEAD`], { cwd: worktreePath });
+                        reviewChangedFiles = filesOut.split('\n').filter(Boolean);
+                        const { stdout: diffOut } = await execFile('git', ['diff', `${baseBranch}..HEAD`], { cwd: worktreePath });
+                        reviewDiffLines = diffOut.split('\n').filter(l => l.startsWith('+') || l.startsWith('-')).filter(l => !l.startsWith('+++') && !l.startsWith('---')).length;
+                    }
+                    catch { /* no commits yet */ }
+                }
+                const diffStats = {
+                    linesChanged: reviewDiffLines,
+                    filesChanged: reviewChangedFiles.length,
+                    filePaths: reviewChangedFiles,
+                };
+                // Determine review level
+                let reviewLevel;
+                if (taskReviewSetting === 'fast') {
+                    reviewLevel = 'fast';
+                }
+                else if (taskReviewSetting === 'panel') {
+                    reviewLevel = 'panel';
+                }
+                else {
+                    reviewLevel = evaluateReviewLevel(taskRecord, diffStats, spec.defaults?.review_heuristics, true);
+                }
+                const reviewerModel = spec.defaults?.reviewer_model ?? 'default';
+                events.emit('review_started', { level: reviewLevel, task_id: taskRecord.id, model: reviewerModel }, { convoy_id: convoyId, task_id: taskRecord.id });
+                if (reviewLevel === 'auto-pass') {
+                    store.updateTaskReview(taskRecord.id, convoyId, {
+                        review_level: 'auto-pass',
+                        review_verdict: 'pass',
+                        review_tokens: 0,
+                        review_model: reviewerModel,
+                    });
+                    events.emit('review_verdict', { level: 'auto-pass', verdict: 'pass', tokens: 0, model: reviewerModel, feedback_length: 0 }, { convoy_id: convoyId, task_id: taskRecord.id });
+                }
+                else if (reviewLevel === 'fast') {
+                    // Check review budget
+                    const reviewBudget = spec.defaults?.review_budget;
+                    const onBudgetExceeded = spec.defaults?.on_review_budget_exceeded ?? 'skip';
+                    if (reviewBudget != null && reviewTokensTotal >= reviewBudget) {
+                        if (onBudgetExceeded === 'stop') {
+                            const allPending = store.getTasksByConvoy(convoyId).filter(t => t.status === 'pending');
+                            for (const t of allPending)
+                                skipTask(t.id, 'review_budget exceeded with on_review_budget_exceeded: stop');
+                            store.withTransaction(() => {
+                                store.updateTaskStatus(taskRecord.id, convoyId, 'review-blocked', { finished_at: finishedAt, output: 'Review budget exceeded', exit_code: 1 });
+                                store.updateWorkerStatus(workerId, 'failed', { finished_at: finishedAt });
+                            });
+                            completedCount++;
+                            process.stdout.write(`  ${c.red('✗')} ${c.bold(`[${taskRecord.id}]`)} review budget exceeded (stop) ${elapsed} ${c.dim(`[${completedCount}/${totalTasks}]`)}\n`);
+                            events.emit('review_verdict', { level: 'fast', verdict: 'skip', tokens: 0, model: reviewerModel, feedback_length: 0, budget_exceeded: true }, { convoy_id: convoyId, task_id: taskRecord.id });
+                            taskAdapterMap.delete(taskRecord.id);
+                            return;
+                        }
+                        else if (onBudgetExceeded === 'downgrade') {
+                            store.updateTaskReview(taskRecord.id, convoyId, { review_level: 'fast', review_verdict: 'pass', review_tokens: 0, review_model: reviewerModel });
+                            events.emit('review_verdict', { level: 'fast', verdict: 'pass', tokens: 0, model: reviewerModel, feedback_length: 0, budget_downgrade: true }, { convoy_id: convoyId, task_id: taskRecord.id });
+                        }
+                        else {
+                            // 'skip': treat as passed
+                            events.emit('review_verdict', { level: 'fast', verdict: 'pass', tokens: 0, model: reviewerModel, feedback_length: 0, budget_skip: true }, { convoy_id: convoyId, task_id: taskRecord.id });
+                        }
+                    }
+                    else {
+                        await reviewSemaphore.acquire();
+                        let reviewResult;
+                        try {
+                            if (reviewRunner) {
+                                reviewResult = await reviewRunner(taskRecord, 'fast', reviewerModel);
+                            }
+                            else {
+                                reviewResult = { verdict: 'pass', feedback: '', tokens: 0, model: reviewerModel };
+                            }
+                        }
+                        finally {
+                            reviewSemaphore.release();
+                        }
+                        reviewTokensTotal += reviewResult.tokens;
+                        store.updateTaskReview(taskRecord.id, convoyId, {
+                            review_level: 'fast',
+                            review_verdict: reviewResult.verdict,
+                            review_tokens: reviewResult.tokens,
+                            review_model: reviewResult.model,
+                        });
+                        store.updateConvoyReviewTokens(convoyId, reviewTokensTotal);
+                        events.emit('review_verdict', { level: 'fast', verdict: reviewResult.verdict, tokens: reviewResult.tokens, model: reviewResult.model, feedback_length: reviewResult.feedback.length }, { convoy_id: convoyId, task_id: taskRecord.id });
+                        if (reviewResult.verdict === 'block') {
+                            await removeWorktree();
+                            const freshRecord = store.getTask(taskRecord.id, convoyId);
+                            if (freshRecord.retries < freshRecord.max_retries && spec.on_failure !== 'stop') {
+                                const contextPrefix = `Previous attempt was blocked by review.\nFeedback:\n${reviewResult.feedback}\n\nFix the issues and try again.\n\n`;
+                                store.updateTaskStatus(taskRecord.id, convoyId, 'pending', {
+                                    retries: freshRecord.retries + 1,
+                                    worker_id: null,
+                                    worktree: null,
+                                    started_at: null,
+                                    finished_at: null,
+                                    prompt: contextPrefix + taskRecord.prompt,
+                                });
+                                store.updateWorkerStatus(workerId, 'failed', { finished_at: finishedAt });
+                                process.stdout.write(`  ${c.yellow('⟳')} ${c.bold(`[${taskRecord.id}]`)} review blocked, retry ${freshRecord.retries + 1}/${freshRecord.max_retries}\n`);
+                                taskAdapterMap.delete(taskRecord.id);
+                                return;
+                            }
+                            else {
+                                store.withTransaction(() => {
+                                    store.updateTaskStatus(taskRecord.id, convoyId, 'review-blocked', {
+                                        finished_at: finishedAt,
+                                        output: `Review blocked: ${reviewResult.feedback}`,
+                                        exit_code: 1,
+                                    });
+                                    store.updateWorkerStatus(workerId, 'failed', { finished_at: finishedAt });
+                                });
+                                completedCount++;
+                                process.stdout.write(`  ${c.red('✗')} ${c.bold(`[${taskRecord.id}]`)} review blocked ${elapsed} ${c.dim(`[${completedCount}/${totalTasks}]`)}\n`);
+                                events.emit('task_failed', { reason: 'review-blocked', worker_id: workerId }, { convoy_id: convoyId, task_id: taskRecord.id, worker_id: workerId });
+                                handleExhaustion(freshRecord, 'review-blocked', reviewResult.feedback || null);
+                                taskAdapterMap.delete(taskRecord.id);
+                                return;
+                            }
+                        }
+                    }
+                }
+                else {
+                    // panel: 3 concurrent reviewer calls, majority vote
+                    await reviewSemaphore.acquire();
+                    let panelResults;
+                    try {
+                        const noopRunner = (_t, _l, m) => Promise.resolve({ verdict: 'pass', feedback: '', tokens: 0, model: m });
+                        const runner = reviewRunner ?? noopRunner;
+                        panelResults = await Promise.all([
+                            runner(taskRecord, 'panel', reviewerModel),
+                            runner(taskRecord, 'panel', reviewerModel),
+                            runner(taskRecord, 'panel', reviewerModel),
+                        ]);
+                    }
+                    finally {
+                        reviewSemaphore.release();
+                    }
+                    const panelPasses = panelResults.filter(r => r.verdict === 'pass').length;
+                    const panelBlocks = panelResults.filter(r => r.verdict === 'block').length;
+                    const totalPanelTokens = panelResults.reduce((sum, r) => sum + r.tokens, 0);
+                    reviewTokensTotal += totalPanelTokens;
+                    const freshForPanel = store.getTask(taskRecord.id, convoyId);
+                    store.updateTaskReview(taskRecord.id, convoyId, {
+                        review_level: 'panel',
+                        review_verdict: panelPasses >= 2 ? 'pass' : 'block',
+                        review_tokens: totalPanelTokens,
+                        review_model: reviewerModel,
+                        panel_attempts: freshForPanel.panel_attempts + 1,
+                    });
+                    if (totalPanelTokens > 0)
+                        store.updateConvoyReviewTokens(convoyId, reviewTokensTotal);
+                    events.emit('review_verdict', { level: 'panel', verdict: panelPasses >= 2 ? 'pass' : 'block', tokens: totalPanelTokens, model: reviewerModel, feedback_length: panelResults.map(r => r.feedback).join('').length, passes: panelPasses, blocks: panelBlocks }, { convoy_id: convoyId, task_id: taskRecord.id });
+                    if (panelBlocks >= 2) {
+                        const blockFeedback = panelResults.filter(r => r.verdict === 'block').map(r => r.feedback).join('\n\n---\n\n');
+                        await removeWorktree();
+                        // Check for dispute trigger
+                        const updatedTask = store.getTask(taskRecord.id, convoyId);
+                        if (updatedTask.panel_attempts >= 3) {
+                            const disputeId = `dispute-${taskRecord.id}-${Date.now()}`;
+                            const onDispute = spec.defaults?.on_dispute ?? 'stop';
+                            store.updateTaskDisputeStatus(taskRecord.id, convoyId, 'disputed', disputeId);
+                            writeDisputeToMarkdown(disputeId, convoyId, taskRecord, panelResults, events);
+                            events.emit('dispute_opened', {
+                                dispute_id: disputeId,
+                                task_id: taskRecord.id,
+                                agent: taskRecord.agent,
+                                panel_attempts: updatedTask.panel_attempts,
+                            }, { convoy_id: convoyId, task_id: taskRecord.id });
+                            if (onDispute === 'stop') {
+                                const allPending = store.getTasksByConvoy(convoyId).filter(t => t.status === 'pending');
+                                for (const t of allPending) {
+                                    skipTask(t.id, `on_dispute: stop — task "${taskRecord.id}" disputed`);
+                                }
+                            }
+                            completedCount++;
+                            process.stdout.write(`  ${c.red('⚡')} ${c.bold(`[${taskRecord.id}]`)} disputed after ${updatedTask.panel_attempts} panel attempts\n`);
+                            taskAdapterMap.delete(taskRecord.id);
+                            return;
+                        }
+                        const freshRecord = store.getTask(taskRecord.id, convoyId);
+                        if (freshRecord.retries < freshRecord.max_retries && spec.on_failure !== 'stop') {
+                            const contextPrefix = `Previous attempt was blocked by panel review (${panelBlocks}/3 reviewers).\nMUST-FIX:\n${blockFeedback}\n\nFix the issues and try again.\n\n`;
+                            store.updateTaskStatus(taskRecord.id, convoyId, 'pending', {
+                                retries: freshRecord.retries + 1,
+                                worker_id: null,
+                                worktree: null,
+                                started_at: null,
+                                finished_at: null,
+                                prompt: contextPrefix + taskRecord.prompt,
+                            });
+                            store.updateWorkerStatus(workerId, 'failed', { finished_at: finishedAt });
+                            process.stdout.write(`  ${c.yellow('⟳')} ${c.bold(`[${taskRecord.id}]`)} panel blocked (${panelBlocks}/3), retry ${freshRecord.retries + 1}/${freshRecord.max_retries}\n`);
+                            taskAdapterMap.delete(taskRecord.id);
+                            return;
+                        }
+                        else {
+                            store.withTransaction(() => {
+                                store.updateTaskStatus(taskRecord.id, convoyId, 'review-blocked', {
+                                    finished_at: finishedAt,
+                                    output: `Panel review blocked (${panelBlocks}/3): ${blockFeedback}`,
+                                    exit_code: 1,
+                                });
+                                store.updateWorkerStatus(workerId, 'failed', { finished_at: finishedAt });
+                            });
+                            completedCount++;
+                            process.stdout.write(`  ${c.red('✗')} ${c.bold(`[${taskRecord.id}]`)} panel blocked ${elapsed} ${c.dim(`[${completedCount}/${totalTasks}]`)}\n`);
+                            events.emit('task_failed', { reason: 'review-blocked', worker_id: workerId }, { convoy_id: convoyId, task_id: taskRecord.id, worker_id: workerId });
+                            handleExhaustion(freshRecord, 'review-blocked', blockFeedback || null);
+                            taskAdapterMap.delete(taskRecord.id);
+                            return;
+                        }
+                    }
+                }
+            }
+            // ── Intelligence: check discovered issues (Phase 18.4) ─────────────
+            if (spec.defaults?.track_discovered_issues) {
                 try {
-                    await mergeQueue.merge(worktreePath, `convoy-${workerId}`, baseBranch);
+                    checkDiscoveredIssues(taskRecord.id, events, convoyId, worktreePath ?? basePath);
+                }
+                catch { /* non-critical */ }
+            }
+            // ── post_task hooks ───────────────────────────────────────────────────
+            if (taskHooks.length > 0) {
+                const postResult = await runHooks(taskHooks, 'post_task', {
+                    taskId: taskRecord.id,
+                    convoyId,
+                    cwd: worktreePath ?? basePath,
+                });
+                if (!postResult.passed) {
+                    await removeWorktree();
+                    const hookLabel = postResult.failedHook?.name ?? postResult.failedHook?.type ?? 'unknown';
+                    store.withTransaction(() => {
+                        store.updateTaskStatus(taskRecord.id, convoyId, 'hook-failed', {
+                            finished_at: finishedAt,
+                            output: `post_task hook "${hookLabel}" failed: ${postResult.error ?? ''}`,
+                            exit_code: 1,
+                        });
+                        store.updateWorkerStatus(workerId, 'failed', { finished_at: finishedAt });
+                    });
+                    completedCount++;
+                    process.stdout.write(`  ${c.red('✗')} ${c.bold(`[${taskRecord.id}]`)} post_task hook failed ${elapsed} ${c.dim(`[${completedCount}/${totalTasks}]`)}\n`);
+                    events.emit('task_failed', { reason: 'hook-failed', hook: hookLabel, worker_id: workerId }, { convoy_id: convoyId, task_id: taskRecord.id, worker_id: workerId });
+                    cascadeFailure(taskRecord.id);
+                    taskAdapterMap.delete(taskRecord.id);
+                    return;
+                }
+            }
+            // ── Symlink security scan (post-execution) ───────────────────────────
+            if (taskFiles.length > 0 && worktreePath) {
+                try {
+                    scanNewSymlinks(worktreePath, taskFiles);
                 }
                 catch (err) {
-                    if (verbose) {
-                        process.stderr.write(`Warning: merge failed for ${taskRecord.id}: ${err.message}\n`);
+                    await removeWorktree();
+                    store.withTransaction(() => {
+                        store.updateTaskStatus(taskRecord.id, convoyId, 'failed', {
+                            finished_at: finishedAt,
+                            output: `Post-execution symlink security check failed: ${err.message}`,
+                            exit_code: 1,
+                        });
+                        store.updateWorkerStatus(workerId, 'failed', { finished_at: finishedAt });
+                    });
+                    completedCount++;
+                    events.emit('task_failed', { reason: 'symlink-escape-post', worker_id: workerId }, { convoy_id: convoyId, task_id: taskRecord.id, worker_id: workerId });
+                    cascadeFailure(taskRecord.id);
+                    taskAdapterMap.delete(taskRecord.id);
+                    return;
+                }
+            }
+            if (worktreePath) {
+                let mergeAttempt = 0;
+                const maxMergeAttempts = 2;
+                let merged = false;
+                while (mergeAttempt < maxMergeAttempts && !merged) {
+                    try {
+                        await mergeQueue.merge(worktreePath, `convoy-${workerId}`, baseBranch);
+                        merged = true;
+                    }
+                    catch (err) {
+                        if (err instanceof MergeConflictError) {
+                            mergeAttempt++;
+                            events.emit('merge_conflict_detected', {
+                                attempt: mergeAttempt,
+                                conflicting_files: err.conflictingFiles,
+                            }, { convoy_id: convoyId, task_id: taskRecord.id });
+                            if (mergeAttempt >= maxMergeAttempts) {
+                                events.emit('merge_conflict_failed', {
+                                    attempts: mergeAttempt,
+                                    conflicting_files: err.conflictingFiles,
+                                }, { convoy_id: convoyId, task_id: taskRecord.id });
+                                const freshRecord = store.getTask(taskRecord.id, convoyId);
+                                store.withTransaction(() => {
+                                    store.updateTaskStatus(taskRecord.id, convoyId, 'failed', {
+                                        finished_at: now(),
+                                        output: `Merge conflict could not be resolved after ${mergeAttempt} attempts. Files: ${err.conflictingFiles.join(', ')}`,
+                                        exit_code: 1,
+                                    });
+                                    store.updateWorkerStatus(workerId, 'failed', { finished_at: now() });
+                                });
+                                completedCount++;
+                                process.stdout.write(`  ${c.red('✗')} ${c.bold(`[${taskRecord.id}]`)} merge conflict unresolved ${elapsed} ${c.dim(`[${completedCount}/${totalTasks}]`)}\n`);
+                                events.emit('task_failed', { reason: 'merge-conflict', worker_id: workerId }, { convoy_id: convoyId, task_id: taskRecord.id, worker_id: workerId });
+                                cascadeFailure(taskRecord.id);
+                                handleExhaustion(freshRecord, 'merge-conflict', err.conflictingFiles.join(', '));
+                                break;
+                            }
+                            // Per spec: backoff on second attempt (unreachable with maxMergeAttempts=2 but follows spec)
+                            if (mergeAttempt === 2) {
+                                await new Promise(resolve => setTimeout(resolve, 30_000));
+                            }
+                            // Inject a resolution task
+                            const fileHash = createHash('sha256')
+                                .update(err.conflictingFiles.sort().join(','))
+                                .digest('hex')
+                                .slice(0, 12);
+                            const idempotencyKey = `merge-conflict:${taskRecord.phase}:${fileHash}`;
+                            const resolutionTaskId = `merge-fix-${taskRecord.id}-${mergeAttempt}`;
+                            const conflictPrompt = `Resolve merge conflicts in: ${err.conflictingFiles.join(', ')}. Ensure no conflict markers remain (<<<<<<<, =======, >>>>>>>), syntax is valid, no duplicate imports.`;
+                            const resolutionRecord = {
+                                id: resolutionTaskId,
+                                convoy_id: convoyId,
+                                phase: taskRecord.phase,
+                                prompt: conflictPrompt,
+                                agent: taskRecord.agent,
+                                adapter: null,
+                                model: null,
+                                timeout_ms: 600_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: JSON.stringify(err.conflictingFiles),
+                                depends_on: null,
+                                prompt_tokens: null,
+                                completion_tokens: null,
+                                total_tokens: null,
+                                cost_usd: null,
+                                gates: null,
+                                on_exhausted: 'dlq',
+                                injected: 1,
+                                provenance: 'merge-conflict',
+                                idempotency_key: idempotencyKey,
+                                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,
+                                outputs: null,
+                                inputs: null,
+                                discovered_issues: null,
+                            };
+                            store.insertInjectedTask(resolutionRecord);
+                            const storedResolutionRecord = store.getTask(resolutionTaskId, convoyId);
+                            await executeOneTask(storedResolutionRecord);
+                            // Next loop iteration will retry the merge
+                        }
+                        else {
+                            // Non-conflict merge error — log warning and continue to done path
+                            if (verbose) {
+                                process.stderr.write(`Warning: merge failed for ${taskRecord.id}: ${err.message}\n`);
+                            }
+                            merged = true; // Preserve original behavior: continue despite error
+                            break;
+                        }
                     }
                 }
                 await removeWorktree();
+                if (!merged) {
+                    taskAdapterMap.delete(taskRecord.id);
+                    return;
+                }
+                // ── Intelligence: update expertise post-merge (Phase 18.2) ─────────
+                try {
+                    updateExpertise(taskRecord.agent, { taskId: taskRecord.id, success: true, retries: taskRecord.retries, files: taskRecord.files ? JSON.parse(taskRecord.files) : [] }, basePath);
+                }
+                catch { /* non-critical */ }
+                // ── Intelligence: build knowledge graph post-merge (Phase 18.3) ────
+                try {
+                    const { stdout: diffOut } = await execFile('git', ['diff', 'HEAD~1'], { cwd: basePath });
+                    buildKnowledgeGraph(diffOut, convoyId, basePath);
+                }
+                catch { /* non-critical */ }
             }
             const usageExtra = {};
             if (result.usage) {
@@ -253,6 +1880,80 @@ async function runConvoy(convoyId, spec, adapter, store, events, wtManager, merg
                 if (result.usage.total_tokens != null)
                     usageExtra.total_tokens = result.usage.total_tokens;
             }
+            // ── Capture outputs as artifacts ────────────────────────────────────────
+            if (taskRecord.outputs) {
+                const outputs = JSON.parse(taskRecord.outputs);
+                for (const output of outputs) {
+                    let content;
+                    if (output.type === 'summary') {
+                        content = result.output.slice(-4096);
+                    }
+                    else if (output.type === 'json') {
+                        const jsonMatch = result.output.match(/```json\n([\s\S]*?)```/);
+                        content = jsonMatch ? jsonMatch[1].trim() : result.output;
+                    }
+                    else {
+                        content = result.output;
+                    }
+                    try {
+                        store.insertArtifact({
+                            id: `artifact-${taskRecord.id}-${output.name}-${Date.now()}`,
+                            convoy_id: convoyId,
+                            task_id: taskRecord.id,
+                            name: output.name,
+                            type: output.type,
+                            content,
+                            created_at: new Date().toISOString(),
+                        });
+                    }
+                    catch (err) {
+                        if (err instanceof ConvoyArtifactLimitError) {
+                            events.emit('artifact_limit_reached', {
+                                task_id: taskRecord.id,
+                                artifact_name: output.name,
+                            }, { convoy_id: convoyId, task_id: taskRecord.id });
+                        }
+                        else {
+                            throw err;
+                        }
+                    }
+                }
+            }
+            // ── Intelligence: capture persistent agent identity (Phase 17.2) ─────
+            const specTaskForCapture = (spec.tasks ?? []).find(t => t.id === taskRecord.id);
+            if (specTaskForCapture?.persistent && result.output) {
+                try {
+                    // Extract last 300 words, cap at 4KB
+                    const words = result.output.split(/\s+/);
+                    const lastWords = words.slice(-300).join(' ');
+                    let summary = lastWords.length > 4096 ? lastWords.slice(-4096) : lastWords;
+                    // Secret-scan the summary before storing
+                    const summaryScan = scanForSecrets(summary, `identity:${taskRecord.id}`);
+                    if (summaryScan.clean) {
+                        store.insertAgentIdentity({
+                            id: `identity-${taskRecord.id}-${Date.now()}`,
+                            agent: taskRecord.agent,
+                            convoy_id: convoyId,
+                            task_id: taskRecord.id,
+                            summary,
+                            created_at: new Date().toISOString(),
+                            retention_days: 90,
+                        });
+                        events.emit('agent_identity_captured', {
+                            agent: taskRecord.agent,
+                            summary_length: summary.length,
+                        }, { convoy_id: convoyId, task_id: taskRecord.id });
+                    }
+                    else {
+                        events.emit('agent_identity_rejected', {
+                            agent: taskRecord.agent,
+                            reason: 'secrets_detected',
+                            findings_count: summaryScan.findings.length,
+                        }, { convoy_id: convoyId, task_id: taskRecord.id });
+                    }
+                }
+                catch { /* non-critical */ }
+            }
             store.withTransaction(() => {
                 store.updateTaskStatus(taskRecord.id, convoyId, 'done', {
                     finished_at: finishedAt,
@@ -262,6 +1963,28 @@ async function runConvoy(convoyId, spec, adapter, store, events, wtManager, merg
                 });
                 store.updateWorkerStatus(workerId, 'done', { finished_at: finishedAt });
             });
+            // ── Circuit breaker: record success ────────────────────────────────────
+            if (circuitBreakerConfig) {
+                circuitBreaker.recordSuccess(taskRecord.agent);
+                try {
+                    store.updateConvoyCircuitState(convoyId, circuitBreaker.serialize());
+                }
+                catch { /* non-critical */ }
+            }
+            // ── Intelligence: capture retry lesson (Phase 18.1) ─────────────────
+            if (taskRecord.retries > 0 && spec.defaults?.inject_lessons !== false) {
+                try {
+                    captureLessons({
+                        title: `Retry success for ${taskRecord.agent} on ${taskRecord.id}`,
+                        category: 'convoy',
+                        agent: taskRecord.agent,
+                        problem: `Task ${taskRecord.id} required ${taskRecord.retries} retries`,
+                        solution: 'Succeeded after retry with adjusted approach',
+                        files: taskRecord.files ? JSON.parse(taskRecord.files) : undefined,
+                    }, basePath);
+                }
+                catch { /* non-critical */ }
+            }
             completedCount++;
             process.stdout.write(`  ${c.green('✓')} ${c.bold(`[${taskRecord.id}]`)} ${elapsed} ${c.dim(`[${completedCount}/${totalTasks}]`)}\n`);
             events.emit('task_done', { exit_code: result.exitCode, worker_id: workerId }, { convoy_id: convoyId, task_id: taskRecord.id, worker_id: workerId });
@@ -295,12 +2018,15 @@ async function runConvoy(convoyId, spec, adapter, store, events, wtManager, merg
         await removeWorktree();
         const freshRecord = store.getTask(taskRecord.id, convoyId);
         if (freshRecord.retries < freshRecord.max_retries && spec.on_failure !== 'stop') {
+            const failedOutput = result.output || '(no output)';
+            const contextPrefix = `Previous attempt failed.\nExit code: ${result.exitCode}\nError output:\n${failedOutput}\n\nFix the issues and try again.\n\n`;
             store.updateTaskStatus(taskRecord.id, convoyId, 'pending', {
                 retries: freshRecord.retries + 1,
                 worker_id: null,
                 worktree: null,
                 started_at: null,
                 finished_at: null,
+                prompt: contextPrefix + taskRecord.prompt,
             });
             store.updateWorkerStatus(workerId, 'failed', { finished_at: finishedAt });
             process.stdout.write(`  ${c.yellow('⟳')} ${c.bold(`[${taskRecord.id}]`)} retry ${freshRecord.retries + 1}/${freshRecord.max_retries}\n`);
@@ -314,6 +2040,25 @@ async function runConvoy(convoyId, spec, adapter, store, events, wtManager, merg
                 });
                 store.updateWorkerStatus(workerId, 'failed', { finished_at: finishedAt });
             });
+            // ── Intelligence: record failure in expertise (Phase 18.2) ──────────
+            try {
+                updateExpertise(taskRecord.agent, { taskId: taskRecord.id, success: false, retries: freshRecord.retries, files: taskRecord.files ? JSON.parse(taskRecord.files) : [] }, basePath);
+            }
+            catch { /* non-critical */ }
+            // ── Circuit breaker: record failure ────────────────────────────────────
+            if (circuitBreakerConfig) {
+                const { tripped } = circuitBreaker.recordFailure(taskRecord.agent);
+                try {
+                    store.updateConvoyCircuitState(convoyId, circuitBreaker.serialize());
+                }
+                catch { /* non-critical */ }
+                if (tripped) {
+                    events.emit('circuit_breaker_tripped', {
+                        agent: taskRecord.agent,
+                        state: circuitBreaker.getState(taskRecord.agent),
+                    }, { convoy_id: convoyId, task_id: taskRecord.id });
+                }
+            }
             completedCount++;
             process.stdout.write(`  ${c.red('✗')} ${c.bold(`[${taskRecord.id}]`)} failed ${elapsed} ${c.dim(`[${completedCount}/${totalTasks}]`)}\n`);
             if (verbose) {
@@ -342,26 +2087,52 @@ async function runConvoy(convoyId, spec, adapter, store, events, wtManager, merg
                 phase: taskRecord.phase,
                 convoy_id: convoyId,
             }, { convoy_id: convoyId, task_id: taskRecord.id });
-            cascadeFailure(taskRecord.id);
+            handleExhaustion(freshRecord, 'error', result.output || null);
         }
         taskAdapterMap.delete(taskRecord.id);
     }
     // ── Main execution loop ───────────────────────────────────────────────────
     let lastPhase = -1;
+    const isSwarmMode = spec.concurrency === 'auto';
+    const maxSwarmConcurrency = spec.defaults?.max_swarm_concurrency ?? 8;
+    let lastInjectPoll = 0;
+    const INJECT_POLL_INTERVAL = 2000; // 2 seconds
     try {
         let ready = store.getReadyTasks(convoyId);
-        const concurrency = spec.concurrency ?? 1;
         while (ready.length > 0) {
+            // Compute effective concurrency for this phase
+            const effectiveConcurrency = isSwarmMode
+                ? Math.min(ready.length, maxSwarmConcurrency)
+                : (typeof spec.concurrency === 'number' ? spec.concurrency : 1);
             for (const t of ready) {
                 if (t.phase !== lastPhase) {
                     lastPhase = t.phase;
                     const tasksInPhase = ready.filter(r => r.phase === t.phase);
                     const ids = tasksInPhase.map(r => r.id).join(', ');
                     process.stdout.write(`\n  ${c.bold(`Phase ${t.phase + 1}:`)} ${c.dim(ids)}\n`);
+                    if (isSwarmMode) {
+                        events.emit('swarm_concurrency_update', {
+                            phase: t.phase,
+                            pending_count: ready.length,
+                            effective_concurrency: effectiveConcurrency,
+                        }, { convoy_id: convoyId });
+                    }
                 }
             }
-            for (let i = 0; i < ready.length; i += concurrency) {
-                await Promise.all(ready.slice(i, i + concurrency).map(t => executeOneTask(t)));
+            for (let i = 0; i < ready.length; i += effectiveConcurrency) {
+                // Poll for file-based injection between batches
+                const now = Date.now();
+                if (now - lastInjectPoll >= INJECT_POLL_INTERVAL) {
+                    pollInjectFile(convoyId, store, events, basePath);
+                    lastInjectPoll = now;
+                }
+                await Promise.all(ready.slice(i, i + effectiveConcurrency).map(t => executeOneTask(t)));
+            }
+            // Reset wait-for-input tasks to pending so they are re-evaluated after
+            // upstream artifacts may have been captured in this batch
+            const waitingTasks = store.getTasksByConvoy(convoyId).filter(t => t.status === 'wait-for-input');
+            for (const wt of waitingTasks) {
+                store.updateTaskStatus(wt.id, convoyId, 'pending');
             }
             ready = store.getReadyTasks(convoyId);
         }
@@ -380,6 +2151,8 @@ async function runConvoy(convoyId, spec, adapter, store, events, wtManager, merg
         process.stdout.write(`\n  ${c.bold(gateAttempt === 0 ? 'Gates:' : `Gates (retry ${gateAttempt}/${maxGateRetries}):`)}\n`);
         for (const command of spec.gates) {
             try {
+                // SECURITY: Gate/hook commands come from the .convoy.yml spec file, which is operator-controlled.
+                // They are NOT user-supplied and are part of the trusted build configuration.
                 await execFile('sh', ['-c', command], { cwd: basePath });
                 gateResults.push({ command, exitCode: 0, passed: true });
                 process.stdout.write(`  ${c.green('✓')} ${c.dim(command)}\n`);
@@ -425,12 +2198,41 @@ async function runConvoy(convoyId, spec, adapter, store, events, wtManager, merg
             break; // Don't retry if the fix task itself fails
         }
     }
+    // ── post_convoy hooks ─────────────────────────────────────────────────────
+    const specLevelHooks = spec.hooks ?? [];
+    if (specLevelHooks.length > 0) {
+        const postConvoyResult = await runHooks(specLevelHooks, 'post_convoy', {
+            convoyId,
+            cwd: basePath,
+        });
+        if (!postConvoyResult.passed) {
+            const hookLabel = postConvoyResult.failedHook?.name ?? postConvoyResult.failedHook?.type ?? 'unknown';
+            events.emit('post_convoy_hook_failed', {
+                hook: hookLabel,
+                error: postConvoyResult.error,
+            }, { convoy_id: convoyId });
+            process.stdout.write(`  ${c.red('✗')} post_convoy hook "${hookLabel}" failed\n`);
+        }
+    }
+    // ── Intelligence: post-convoy consolidation ──────────────────────────────
+    if (spec.defaults?.inject_lessons !== false) {
+        try {
+            consolidateLessons(basePath);
+        }
+        catch { /* non-critical */ }
+    }
+    if (spec.defaults?.track_discovered_issues) {
+        try {
+            consolidateIssues(basePath);
+        }
+        catch { /* non-critical */ }
+    }
     // ── Final status & summary ────────────────────────────────────────────────
     const allTasksFinal = store.getTasksByConvoy(convoyId);
     const summary = {
         total: allTasksFinal.length,
         done: allTasksFinal.filter(t => t.status === 'done').length,
-        failed: allTasksFinal.filter(t => t.status === 'failed').length,
+        failed: allTasksFinal.filter(t => t.status === 'failed' || t.status === 'gate-failed' || t.status === 'review-blocked' || t.status === 'disputed').length,
         skipped: allTasksFinal.filter(t => t.status === 'skipped').length,
         timedOut: allTasksFinal.filter(t => t.status === 'timed-out').length,
     };
@@ -451,6 +2253,18 @@ async function runConvoy(convoyId, spec, adapter, store, events, wtManager, merg
         finished_at: new Date().toISOString(),
         total_tokens: convoyTotalTokens,
     });
+    // Run convoy guard checks
+    const guardResult = runConvoyGuard(store, convoyId, wtManager, ndjsonPath, spec.guard);
+    if (guardResult.warnings.length > 0) {
+        process.stdout.write(`\n  ${c.yellow('Guard warnings:')}\n`);
+        for (const w of guardResult.warnings) {
+            process.stdout.write(`    ${c.dim('⚠')} ${w}\n`);
+        }
+        events.emit('convoy_guard', {
+            passed: guardResult.passed,
+            warnings: guardResult.warnings,
+        }, { convoy_id: convoyId });
+    }
     return {
         convoyId,
         status: finalStatus,
@@ -481,9 +2295,45 @@ export function createConvoyEngine(options) {
         const convoyId = `convoy-${startTime}`;
         const specHash = createHash('sha256').update(specYaml).digest('hex');
         const baseBranch = spec.branch ?? (await getCurrentBranch());
+        // Ensure target branch exists before acquiring any locks.
+        // Uses _ensureBranch injection so callers/tests can override.
+        if (spec.branch !== undefined) {
+            const branchFn = options._ensureBranch ?? ensureBranch;
+            await branchFn(spec.branch, basePath);
+        }
         mkdirSync(dirname(dbPath), { recursive: true });
+        const lockDb = new DatabaseSync(dbPath);
+        lockDb.exec('PRAGMA journal_mode = WAL');
+        lockDb.exec(`CREATE TABLE IF NOT EXISTS engine_lock (
+      id INTEGER PRIMARY KEY CHECK (id = 1),
+      pid INTEGER NOT NULL,
+      hostname TEXT NOT NULL,
+      started_at TEXT NOT NULL,
+      last_heartbeat TEXT NOT NULL
+    )`);
+        const lock = (() => {
+            try {
+                return acquireEngineLock(lockDb, dbPath);
+            }
+            catch (err) {
+                lockDb.close();
+                throw err;
+            }
+        })();
+        const versionRow = lockDb.prepare('SELECT sqlite_version() as v').get();
+        const [major, minor] = versionRow.v.split('.').map(Number);
+        if (major < 3 || (major === 3 && minor < 35)) {
+            lock.release();
+            lockDb.close();
+            throw new Error(`SQLite version ${versionRow.v} is too old. Requires >= 3.35.0`);
+        }
+        lock.startHeartbeat();
         const store = createConvoyStore(dbPath);
-        const events = createEventEmitter(store, options.logsDir);
+        const ndjsonPath = options.logsDir
+            ? join(options.logsDir, 'convoy-events.ndjson')
+            : join(basePath, '.opencastle', 'logs', 'convoy-events.ndjson');
+        mkdirSync(dirname(ndjsonPath), { recursive: true });
+        const events = createEventEmitter(store, { ndjsonPath });
         const wtManager = options._worktreeManager ?? createWorktreeManager(basePath);
         const mergeQueue = options._mergeQueue ?? createMergeQueue(basePath);
         let result;
@@ -500,6 +2350,15 @@ export function createConvoyEngine(options) {
             });
             const tasks = spec.tasks ?? [];
             const phases = buildPhases(tasks);
+            // Validate file partitions before inserting tasks
+            const partitionResult = validateFilePartitions(tasks, phases);
+            if (!partitionResult.valid) {
+                const conflictSummary = partitionResult.conflicts
+                    .map((cf) => `Phase ${cf.phase}: tasks "${cf.taskA}" and "${cf.taskB}" overlap on [${cf.overlapping.join(', ')}]`)
+                    .join('\n');
+                events.emit('file_partition_conflict', { conflicts: partitionResult.conflicts }, { convoy_id: convoyId });
+                throw new Error(`File partition conflicts detected:\n${conflictSummary}`);
+            }
             for (let phaseIdx = 0; phaseIdx < phases.length; phaseIdx++) {
                 for (const task of phases[phaseIdx]) {
                     store.insertTask({
@@ -516,27 +2375,63 @@ export function createConvoyEngine(options) {
                         max_retries: task.max_retries,
                         files: task.files.length > 0 ? JSON.stringify(task.files) : null,
                         depends_on: task.depends_on.length > 0 ? JSON.stringify(task.depends_on) : null,
+                        gates: task.gates && task.gates.length > 0 ? JSON.stringify(task.gates) : null,
+                        outputs: task.outputs && task.outputs.length > 0 ? JSON.stringify(task.outputs) : null,
+                        inputs: task.inputs && task.inputs.length > 0 ? JSON.stringify(task.inputs) : null,
                     });
                 }
             }
             store.updateConvoyStatus(convoyId, 'running', { started_at: new Date().toISOString() });
             events.emit('convoy_started', { name: spec.name }, { convoy_id: convoyId });
-            result = await runConvoy(convoyId, spec, adapter, store, events, wtManager, mergeQueue, basePath, baseBranch, verbose, startTime);
+            result = await runConvoy(convoyId, spec, adapter, store, events, wtManager, mergeQueue, basePath, baseBranch, verbose, startTime, ndjsonPath, options._reviewRunner);
         }
         finally {
             try {
                 await exportConvoyToNdjson(store, convoyId, options.logsDir);
             }
             catch { /* silent */ }
+            events.close();
             store.close();
+            lock.release();
+            lockDb.close();
         }
         return result;
     }
     async function resume(convoyId) {
         const startTime = Date.now();
         mkdirSync(dirname(dbPath), { recursive: true });
+        const lockDb = new DatabaseSync(dbPath);
+        lockDb.exec('PRAGMA journal_mode = WAL');
+        lockDb.exec(`CREATE TABLE IF NOT EXISTS engine_lock (
+      id INTEGER PRIMARY KEY CHECK (id = 1),
+      pid INTEGER NOT NULL,
+      hostname TEXT NOT NULL,
+      started_at TEXT NOT NULL,
+      last_heartbeat TEXT NOT NULL
+    )`);
+        const lock = (() => {
+            try {
+                return acquireEngineLock(lockDb, dbPath);
+            }
+            catch (err) {
+                lockDb.close();
+                throw err;
+            }
+        })();
+        const versionRow = lockDb.prepare('SELECT sqlite_version() as v').get();
+        const [major, minor] = versionRow.v.split('.').map(Number);
+        if (major < 3 || (major === 3 && minor < 35)) {
+            lock.release();
+            lockDb.close();
+            throw new Error(`SQLite version ${versionRow.v} is too old. Requires >= 3.35.0`);
+        }
+        lock.startHeartbeat();
         const store = createConvoyStore(dbPath);
-        const events = createEventEmitter(store, options.logsDir);
+        const ndjsonPath = options.logsDir
+            ? join(options.logsDir, 'convoy-events.ndjson')
+            : join(basePath, '.opencastle', 'logs', 'convoy-events.ndjson');
+        mkdirSync(dirname(ndjsonPath), { recursive: true });
+        const events = createEventEmitter(store, { ndjsonPath });
         const wtManager = options._worktreeManager ?? createWorktreeManager(basePath);
         const mergeQueue = options._mergeQueue ?? createMergeQueue(basePath);
         let result;
@@ -570,18 +2465,199 @@ export function createConvoyEngine(options) {
             }
             // Remove all orphaned worktrees from the crashed run
             await wtManager.removeAll();
+            // NDJSON recovery: truncate partial lines, replay missing events
+            recoverNdjson(store, convoyId, ndjsonPath);
             events.emit('convoy_resumed', { original_created_at: convoy.created_at }, { convoy_id: convoyId });
-            result = await runConvoy(convoyId, spec, adapter, store, events, wtManager, mergeQueue, basePath, baseBranch, verbose, startTime);
+            result = await runConvoy(convoyId, spec, adapter, store, events, wtManager, mergeQueue, basePath, baseBranch, verbose, startTime, ndjsonPath, options._reviewRunner);
         }
         finally {
             try {
                 await exportConvoyToNdjson(store, convoyId, options.logsDir);
             }
             catch { /* silent */ }
+            events.close();
             store.close();
+            lock.release();
+            lockDb.close();
         }
         return result;
     }
-    return { run, resume };
+    async function retryFailed(convoyId, taskIds) {
+        mkdirSync(dirname(dbPath), { recursive: true });
+        const store = createConvoyStore(dbPath);
+        const ndjsonPath = options.logsDir
+            ? join(options.logsDir, 'convoy-events.ndjson')
+            : join(basePath, '.opencastle', 'logs', 'convoy-events.ndjson');
+        mkdirSync(dirname(ndjsonPath), { recursive: true });
+        const events = createEventEmitter(store, { ndjsonPath });
+        try {
+            const allTasks = store.getTasksByConvoy(convoyId);
+            const retryableStatuses = ['failed', 'gate-failed', 'timed-out', 'review-blocked', 'disputed'];
+            const tasksToRetry = allTasks.filter(t => {
+                if (!retryableStatuses.includes(t.status))
+                    return false;
+                if (taskIds && taskIds.length > 0)
+                    return taskIds.includes(t.id);
+                return true;
+            });
+            for (const task of tasksToRetry) {
+                store.updateTaskStatus(task.id, convoyId, 'pending', {
+                    worker_id: null,
+                    worktree: null,
+                    started_at: null,
+                    finished_at: null,
+                });
+                events.emit('task_retried', { previous_status: task.status }, { convoy_id: convoyId, task_id: task.id });
+            }
+            // Reset convoy status to running so resume can pick it up
+            store.updateConvoyStatus(convoyId, 'running', {});
+        }
+        finally {
+            events.close();
+            store.close();
+        }
+    }
+    function injectTask(convoyId, task) {
+        mkdirSync(dirname(dbPath), { recursive: true });
+        const store = createConvoyStore(dbPath);
+        try {
+            // Idempotency check
+            if (task.idempotency_key) {
+                const existing = store.getTaskByIdempotencyKey(convoyId, task.idempotency_key);
+                if (existing)
+                    return existing;
+            }
+            const allTasks = store.getTasksByConvoy(convoyId);
+            // Check max injectable tasks (10)
+            const injectedCount = allTasks.filter(t => t.injected === 1).length;
+            if (injectedCount >= 10) {
+                throw new Error(`Max injectable tasks (10) reached for convoy ${convoyId}`);
+            }
+            // Validate ID uniqueness
+            if (allTasks.some(t => t.id === task.id)) {
+                throw new Error(`Task ID "${task.id}" already exists in convoy ${convoyId}`);
+            }
+            // Validate depends_on references exist
+            const deps = task.depends_on ?? [];
+            for (const dep of deps) {
+                if (!allTasks.some(t => t.id === dep)) {
+                    throw new Error(`Dependency "${dep}" not found in convoy ${convoyId}`);
+                }
+            }
+            // Validate no file partition overlap with pending/running tasks
+            const taskFiles = task.files ?? [];
+            if (taskFiles.length > 0) {
+                // Normalize injected task file paths
+                const normalizedTaskFiles = taskFiles.map(normalizePath);
+                // Symlink pre-scan on injected files
+                const basePath = options.basePath ?? process.cwd();
+                try {
+                    scanSymlinks(normalizedTaskFiles, basePath);
+                }
+                catch (err) {
+                    throw new Error(`Injected task "${task.id}" failed symlink check: ${err.message}`);
+                }
+                // Full partition validation against active tasks
+                const activeTasks = allTasks.filter(t => t.status === 'pending' || t.status === 'running' || t.status === 'assigned');
+                for (const other of activeTasks) {
+                    const otherFiles = other.files ? JSON.parse(other.files) : [];
+                    if (otherFiles.length === 0)
+                        continue;
+                    const normalizedOther = otherFiles.map(normalizePath);
+                    const overlapping = [];
+                    for (const fileA of normalizedTaskFiles) {
+                        for (const fileB of normalizedOther) {
+                            if (pathsOverlap(fileA, fileB) && !overlapping.includes(fileA)) {
+                                overlapping.push(fileA);
+                            }
+                        }
+                    }
+                    if (overlapping.length > 0) {
+                        throw new Error(`File partition overlap with task "${other.id}": ${overlapping.join(', ')}`);
+                    }
+                }
+            }
+            // Detect dependency cycles
+            const depGraph = new Map();
+            for (const t of allTasks) {
+                depGraph.set(t.id, t.depends_on ? JSON.parse(t.depends_on) : []);
+            }
+            depGraph.set(task.id, deps);
+            function hasCycle(nodeId, visited, stack) {
+                visited.add(nodeId);
+                stack.add(nodeId);
+                for (const dep of depGraph.get(nodeId) ?? []) {
+                    if (!visited.has(dep)) {
+                        if (hasCycle(dep, visited, stack))
+                            return true;
+                    }
+                    else if (stack.has(dep)) {
+                        return true;
+                    }
+                }
+                stack.delete(nodeId);
+                return false;
+            }
+            const visited = new Set();
+            const stack = new Set();
+            for (const nodeId of depGraph.keys()) {
+                if (!visited.has(nodeId)) {
+                    if (hasCycle(nodeId, visited, stack)) {
+                        throw new Error(`Dependency cycle detected when injecting task "${task.id}"`);
+                    }
+                }
+            }
+            // Insert the task
+            const record = {
+                id: task.id,
+                convoy_id: convoyId,
+                phase: task.phase,
+                prompt: task.prompt,
+                agent: task.agent,
+                adapter: null,
+                model: null,
+                timeout_ms: task.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: task.max_retries ?? 1,
+                files: taskFiles.length > 0 ? JSON.stringify(taskFiles) : null,
+                depends_on: deps.length > 0 ? JSON.stringify(deps) : null,
+                prompt_tokens: null,
+                completion_tokens: null,
+                total_tokens: null,
+                cost_usd: null,
+                gates: null,
+                on_exhausted: task.on_exhausted ?? 'dlq',
+                injected: 1,
+                provenance: task.provenance ?? null,
+                idempotency_key: task.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,
+                outputs: null,
+                inputs: null,
+                discovered_issues: null,
+            };
+            store.insertInjectedTask(record);
+            return record;
+        }
+        finally {
+            store.close();
+        }
+    }
+    return { run, resume, retryFailed, injectTask };
 }
 //# sourceMappingURL=engine.js.map