@tagma/sdk 0.4.2 → 0.4.4

package/dist/engine.js

@@ -0,0 +1,815 @@
+import { resolve, dirname } from 'path';
+import { mkdir, readdir, rm } from 'fs/promises';
+import { buildDag } from './dag';
+import { getHandler, hasHandler, loadPlugins } from './registry';
+import { runSpawn, runCommand } from './runner';
+import { parseDuration, nowISO, generateRunId, validatePath } from './utils';
+import { executeHook, buildPipelineStartContext, buildTaskContext, buildPipelineCompleteContext, buildPipelineErrorContext, } from './hooks';
+import { Logger, tailLines, clip } from './logger';
+import { InMemoryApprovalGateway } from './approval';
+// ═══ A7: Typed trigger errors ═══
+// Replace string-matching on error messages with structured error types so
+// coincidental substrings don't cause misclassification.
+export class TriggerBlockedError extends Error {
+    code = 'TRIGGER_BLOCKED';
+    constructor(message) {
+        super(message);
+        this.name = 'TriggerBlockedError';
+    }
+}
+export class TriggerTimeoutError extends Error {
+    code = 'TRIGGER_TIMEOUT';
+    constructor(message) {
+        super(message);
+        this.name = 'TriggerTimeoutError';
+    }
+}
+// ═══ Preflight Validation ═══
+function preflight(config, dag) {
+    const errors = [];
+    for (const [, node] of dag.nodes) {
+        const task = node.task;
+        const track = node.track;
+        const driverName = task.driver ?? track.driver ?? config.driver ?? 'claude-code';
+        // Pure command tasks don't use a driver — skip driver registration check.
+        const isCommandOnly = task.command && !task.prompt;
+        if (!isCommandOnly && !hasHandler('drivers', driverName)) {
+            errors.push(`Task "${node.taskId}": driver "${driverName}" not registered`);
+        }
+        if (task.trigger && !hasHandler('triggers', task.trigger.type)) {
+            errors.push(`Task "${node.taskId}": trigger type "${task.trigger.type}" not registered`);
+        }
+        if (task.completion && !hasHandler('completions', task.completion.type)) {
+            errors.push(`Task "${node.taskId}": completion type "${task.completion.type}" not registered`);
+        }
+        const mws = task.middlewares ?? track.middlewares ?? [];
+        for (const mw of mws) {
+            if (!hasHandler('middlewares', mw.type)) {
+                errors.push(`Task "${node.taskId}": middleware type "${mw.type}" not registered`);
+            }
+        }
+        if (task.continue_from && hasHandler('drivers', driverName)) {
+            const driver = getHandler('drivers', driverName);
+            if (!driver.capabilities.sessionResume) {
+                const upstreamId = resolveRefInDag(dag, task.continue_from, track.id);
+                if (upstreamId) {
+                    const upstream = dag.nodes.get(upstreamId);
+                    if (upstream) {
+                        // A handoff is possible via session resume (already ruled out above),
+                        // an output file, OR in-memory text injection through normalizedMap
+                        // (when the upstream driver implements parseResult and returns normalizedOutput).
+                        const upstreamDriverName = upstream.task.driver ?? upstream.track.driver
+                            ?? config.driver ?? 'claude-code';
+                        const upstreamDriver = hasHandler('drivers', upstreamDriverName)
+                            ? getHandler('drivers', upstreamDriverName)
+                            : null;
+                        const canNormalize = typeof upstreamDriver?.parseResult === 'function';
+                        if (!upstream.task.output && !canNormalize) {
+                            errors.push(`Task "${node.taskId}" uses continue_from: "${task.continue_from}", ` +
+                                `but upstream task "${upstreamId}" has no "output" field and its driver ` +
+                                `does not implement parseResult for text-injection handoff. ` +
+                                `Add output to the upstream task, use a driver with parseResult, or remove continue_from.`);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    if (errors.length > 0) {
+        throw new Error(`Preflight validation failed:\n  - ${errors.join('\n  - ')}`);
+    }
+}
+function resolveRefInDag(dag, ref, fromTrackId) {
+    // Already fully qualified
+    if (dag.nodes.has(ref))
+        return ref;
+    // Same-track match (preferred)
+    const sameTrack = `${fromTrackId}.${ref}`;
+    if (dag.nodes.has(sameTrack))
+        return sameTrack;
+    // Cross-track bare name lookup — must be unambiguous (aligned with buildDag's resolveRef)
+    let match = null;
+    for (const [id] of dag.nodes) {
+        if (id.endsWith(`.${ref}`)) {
+            if (match !== null) {
+                // Ambiguous: multiple tasks share the bare name across tracks
+                return null;
+            }
+            match = id;
+        }
+    }
+    return match;
+}
+// Poll interval when no tasks are in-flight but non-terminal tasks remain
+// (e.g. tasks waiting on a file or manual trigger).
+const POLL_INTERVAL_MS = 50;
+// R15: cap on each normalized-output entry stored in normalizedMap so a
+// runaway parseResult can't accumulate hundreds of MB across tasks. 1 MB
+// is generous for any text-context handoff between AI tasks.
+const MAX_NORMALIZED_BYTES = 1_000_000;
+export async function runPipeline(config, workDir, options = {}) {
+    const approvalGateway = options.approvalGateway ?? new InMemoryApprovalGateway();
+    const maxLogRuns = options.maxLogRuns ?? 20;
+    // Load any plugins declared in the pipeline config before preflight so that
+    // drivers, completions, and middlewares referenced in YAML are registered.
+    // Hosts that pre-load plugins from a custom path (e.g. the editor loading
+    // from the user's workspace node_modules) pass skipPluginLoading: true so
+    // we don't re-resolve via Node's cwd-based default import.
+    if (!options.skipPluginLoading && config.plugins?.length) {
+        await loadPlugins(config.plugins);
+    }
+    const dag = buildDag(config);
+    const runId = options.runId ?? generateRunId();
+    preflight(config, dag);
+    const startedAt = nowISO();
+    const pipelineInfo = { name: config.name, run_id: runId, started_at: startedAt };
+    // Forward every structured log line to subscribers as task_log events.
+    // Reading options.onEvent inside the callback (vs. capturing it once) keeps
+    // the SDK behavior correct if callers pass a fresh onEvent on each run.
+    const log = new Logger(workDir, runId, (record) => {
+        options.onEvent?.({
+            type: 'task_log',
+            runId,
+            taskId: record.taskId,
+            level: record.level,
+            timestamp: record.timestamp,
+            text: record.text,
+        });
+    });
+    try {
+        log.info('[pipeline]', `start "${config.name}" run_id=${runId}`);
+        // File-only: dump the resolved pipeline shape + DAG topology for post-mortem.
+        log.section('Pipeline configuration');
+        log.quiet(`name:          ${config.name}`);
+        log.quiet(`driver:        ${config.driver ?? '(default: claude-code)'}`);
+        log.quiet(`timeout:       ${config.timeout ?? '(none)'}`);
+        log.quiet(`tracks:        ${config.tracks.length}`);
+        log.quiet(`tasks (total): ${dag.nodes.size}`);
+        log.quiet(`plugins:       ${(config.plugins ?? []).join(', ') || '(none)'}`);
+        log.quiet(`hooks:         ${config.hooks ? Object.keys(config.hooks).join(', ') || '(none)' : '(none)'}`);
+        log.section('DAG topology');
+        for (const [id, node] of dag.nodes) {
+            const deps = node.dependsOn.length ? node.dependsOn.join(', ') : '(root)';
+            const kind = node.task.prompt ? 'ai' : 'cmd';
+            log.quiet(`  • ${id}  [${kind}]  track=${node.track.id}  deps=[${deps}]`);
+        }
+        log.quiet('');
+        // Initialize states (before hook, so we can return them even if blocked)
+        const states = new Map();
+        for (const [id, node] of dag.nodes) {
+            states.set(id, {
+                config: node.task,
+                trackConfig: node.track,
+                status: 'idle',
+                result: null,
+                startedAt: null,
+                finishedAt: null,
+            });
+        }
+        // Pipeline start hook (gate)
+        const startHook = await executeHook(config.hooks, 'pipeline_start', buildPipelineStartContext(pipelineInfo), workDir);
+        if (!startHook.allowed) {
+            console.error(`Pipeline blocked by pipeline_start hook (exit code ${startHook.exitCode})`);
+            await executeHook(config.hooks, 'pipeline_error', buildPipelineErrorContext(pipelineInfo, 'pipeline_blocked', 'pipeline_blocked'), workDir);
+            // All tasks stay idle — pipeline never started
+            return {
+                success: false,
+                runId,
+                logPath: log.path,
+                summary: { total: dag.nodes.size, success: 0, failed: 0, skipped: 0, timeout: 0, blocked: 0 },
+                states: freezeStates(states),
+            };
+        }
+        // Pipeline approved — transition all tasks to waiting
+        for (const [, state] of states) {
+            state.status = 'waiting';
+        }
+        // Include a full states snapshot so listeners can initialize their mirrors without missing events
+        const statesSnapshot = new Map([...states.entries()].map(([id, s]) => [id, { ...s }]));
+        options.onEvent?.({ type: 'pipeline_start', runId, states: statesSnapshot });
+        const sessionMap = new Map();
+        const outputMap = new Map();
+        const normalizedMap = new Map();
+        // Pipeline timeout
+        const pipelineTimeoutMs = config.timeout ? parseDuration(config.timeout) : 0;
+        let pipelineAborted = false;
+        const abortController = new AbortController();
+        let pipelineTimer = null;
+        if (pipelineTimeoutMs > 0) {
+            pipelineTimer = setTimeout(() => {
+                pipelineAborted = true;
+                abortController.abort();
+            }, pipelineTimeoutMs);
+        }
+        // When the pipeline is aborted (timeout, external shutdown), drain all
+        // pending approvals so waiting triggers unblock immediately.
+        abortController.signal.addEventListener('abort', () => {
+            approvalGateway.abortAll('pipeline aborted');
+        });
+        // Wire external cancel signal into the internal abort controller.
+        const externalAbortHandler = () => {
+            pipelineAborted = true;
+            abortController.abort();
+        };
+        if (options.signal) {
+            if (options.signal.aborted) {
+                externalAbortHandler();
+            }
+            else {
+                options.signal.addEventListener('abort', externalAbortHandler, { once: true });
+            }
+        }
+        // ── Helpers ──
+        function emit(event) {
+            options.onEvent?.(event);
+        }
+        function setTaskStatus(taskId, newStatus) {
+            const state = states.get(taskId);
+            // Terminal lock: once a task reaches a terminal state it must not be
+            // re-transitioned. This prevents stop_all from marking running tasks as
+            // skipped and then having their in-flight processTask promise overwrite
+            // that with success/failed, producing an invalid double transition.
+            if (isTerminal(state.status))
+                return;
+            const prevStatus = state.status;
+            state.status = newStatus;
+            // Snapshot state at emit time — result and finishedAt must be set before calling this for terminal statuses
+            const snapshot = {
+                config: state.config,
+                trackConfig: state.trackConfig,
+                status: state.status,
+                result: state.result,
+                startedAt: state.startedAt,
+                finishedAt: state.finishedAt,
+            };
+            emit({ type: 'task_status_change', taskId, status: newStatus, prevStatus, runId, state: snapshot });
+        }
+        function getOnFailure(taskId) {
+            return dag.nodes.get(taskId)?.track.on_failure ?? 'skip_downstream';
+        }
+        function isDependencySatisfied(depId) {
+            const depState = states.get(depId);
+            if (!depState)
+                return 'skip';
+            switch (depState.status) {
+                case 'success': return 'satisfied';
+                case 'skipped': return 'skip';
+                case 'failed':
+                case 'timeout':
+                case 'blocked':
+                    return getOnFailure(depId) === 'ignore' ? 'satisfied' : 'skip';
+                default: return 'unsatisfied';
+            }
+        }
+        /**
+         * H3: "stop_all" historically only stopped tasks within the same track,
+         * which contradicted both its name and user expectations. It now stops
+         * the **entire pipeline**:
+         *   - In-flight tasks are signalled via the shared abort controller so
+         *     drivers / runner.ts can cancel cooperatively (returning
+         *     `failureKind: 'timeout'`).
+         *   - Still-waiting tasks across every track are immediately marked
+         *     skipped so the run completes promptly.
+         * The terminal lock in setTaskStatus prevents any later re-transition
+         * should a completed running task try to overwrite the skipped state.
+         */
+        function applyStopAll(_failedTrackId) {
+            pipelineAborted = true;
+            abortController.abort();
+            for (const [id, state] of states) {
+                if (state.status === 'waiting') {
+                    state.finishedAt = nowISO();
+                    setTaskStatus(id, 'skipped');
+                }
+            }
+        }
+        function buildTaskInfoObj(taskId) {
+            const state = states.get(taskId);
+            return {
+                id: taskId,
+                name: state.config.name,
+                type: state.config.prompt ? 'ai' : 'command',
+                status: state.status,
+                exit_code: state.result?.exitCode ?? null,
+                duration_ms: state.result?.durationMs ?? null,
+                output_path: state.result?.outputPath ?? null,
+                stderr_path: state.result?.stderrPath ?? null,
+                session_id: state.result?.sessionId ?? null,
+                started_at: state.startedAt,
+                finished_at: state.finishedAt,
+            };
+        }
+        function trackInfoOf(taskId) {
+            const node = dag.nodes.get(taskId);
+            return { id: node.track.id, name: node.track.name };
+        }
+        async function fireHook(taskId, event) {
+            await executeHook(config.hooks, event, buildTaskContext(event, pipelineInfo, trackInfoOf(taskId), buildTaskInfoObj(taskId)), workDir, abortController.signal);
+        }
+        // ── Process a single task ──
+        async function processTask(taskId) {
+            const state = states.get(taskId);
+            const node = dag.nodes.get(taskId);
+            const task = node.task;
+            const track = node.track;
+            log.section(`Task ${taskId}`, taskId);
+            log.debug(`[task:${taskId}]`, `type=${task.prompt ? 'ai' : 'cmd'} track=${track.id} deps=[${node.dependsOn.join(', ') || '(root)'}]`);
+            // 1. Check dependencies
+            for (const depId of node.dependsOn) {
+                const result = isDependencySatisfied(depId);
+                if (result === 'skip') {
+                    const depStatus = states.get(depId)?.status ?? 'unknown';
+                    log.debug(`[task:${taskId}]`, `skipped (upstream "${depId}" status=${depStatus})`);
+                    state.finishedAt = nowISO();
+                    setTaskStatus(taskId, 'skipped');
+                    return;
+                }
+                if (result === 'unsatisfied')
+                    return; // still waiting
+            }
+            // 2. Check trigger
+            if (task.trigger) {
+                log.debug(`[task:${taskId}]`, `trigger wait: type=${task.trigger.type} ${JSON.stringify(task.trigger)}`);
+                try {
+                    const triggerPlugin = getHandler('triggers', task.trigger.type);
+                    // R6: race the plugin's watch() against the pipeline's abort signal.
+                    // Third-party triggers may forget to wire up ctx.signal — without
+                    // this race, an aborted pipeline would hang forever waiting for the
+                    // plugin's watch promise to resolve. The race resolves on whichever
+                    // path settles first, and the cleanup paths in finally never run on
+                    // the orphaned plugin promise (it's allowed to leak a watcher; the
+                    // pipeline is being torn down anyway).
+                    await new Promise((resolve, reject) => {
+                        let settled = false;
+                        const onAbort = () => {
+                            if (settled)
+                                return;
+                            settled = true;
+                            abortController.signal.removeEventListener('abort', onAbort);
+                            reject(new Error('Pipeline aborted'));
+                        };
+                        if (abortController.signal.aborted) {
+                            onAbort();
+                            return;
+                        }
+                        abortController.signal.addEventListener('abort', onAbort, { once: true });
+                        triggerPlugin.watch(task.trigger, {
+                            taskId: node.taskId,
+                            trackId: track.id,
+                            workDir: task.cwd ?? workDir,
+                            signal: abortController.signal,
+                            approvalGateway,
+                        }).then((v) => {
+                            if (settled)
+                                return;
+                            settled = true;
+                            abortController.signal.removeEventListener('abort', onAbort);
+                            resolve(v);
+                        }, (e) => {
+                            if (settled)
+                                return;
+                            settled = true;
+                            abortController.signal.removeEventListener('abort', onAbort);
+                            reject(e);
+                        });
+                    });
+                    log.debug(`[task:${taskId}]`, `trigger fired`);
+                }
+                catch (err) {
+                    // If pipeline was aborted while we were still waiting for the trigger,
+                    // this task never entered running state → skipped, not timeout.
+                    state.finishedAt = nowISO();
+                    if (pipelineAborted) {
+                        setTaskStatus(taskId, 'skipped');
+                    }
+                    else if (err instanceof TriggerBlockedError) {
+                        setTaskStatus(taskId, 'blocked'); // user/policy rejection
+                    }
+                    else if (err instanceof TriggerTimeoutError) {
+                        setTaskStatus(taskId, 'timeout'); // genuine trigger wait timeout
+                    }
+                    else {
+                        // A7 fallback: also check message strings for backward-compat with
+                        // third-party trigger plugins that don't throw typed errors yet.
+                        const msg = err instanceof Error ? err.message : String(err);
+                        if (msg.includes('rejected') || msg.includes('denied')) {
+                            setTaskStatus(taskId, 'blocked');
+                        }
+                        else if (msg.includes('timeout')) {
+                            setTaskStatus(taskId, 'timeout');
+                        }
+                        else {
+                            setTaskStatus(taskId, 'failed'); // plugin error, watcher crash, etc.
+                        }
+                    }
+                    try {
+                        await fireHook(taskId, 'task_failure');
+                    }
+                    catch (hookErr) {
+                        log.error(`[task:${taskId}]`, `hook execution failed: ${hookErr instanceof Error ? hookErr.message : String(hookErr)}`);
+                    }
+                    return;
+                }
+            }
+            // 3. task_start hook (gate)
+            const hookResult = await executeHook(config.hooks, 'task_start', buildTaskContext('task_start', pipelineInfo, trackInfoOf(taskId), buildTaskInfoObj(taskId)), workDir, abortController.signal);
+            if (hookResult.exitCode !== 0 || config.hooks?.task_start) {
+                log.debug(`[task:${taskId}]`, `task_start hook exit=${hookResult.exitCode} allowed=${hookResult.allowed}`);
+            }
+            if (!hookResult.allowed) {
+                state.finishedAt = nowISO();
+                setTaskStatus(taskId, 'blocked');
+                try {
+                    await fireHook(taskId, 'task_failure');
+                }
+                catch (hookErr) {
+                    log.error(`[task:${taskId}]`, `hook execution failed: ${hookErr instanceof Error ? hookErr.message : String(hookErr)}`);
+                }
+                return;
+            }
+            // 4. Mark running — set startedAt before emitting so subscribers see a
+            // complete snapshot (startedAt non-null) in the task_status_change event.
+            state.startedAt = nowISO();
+            setTaskStatus(taskId, 'running');
+            log.info(`[task:${taskId}]`, task.command ? `running: ${task.command}` : `running (driver task)`);
+            // File-only: resolved config for this task
+            const resolvedDriver = task.driver ?? track.driver ?? config.driver ?? 'claude-code';
+            const resolvedTier = task.model_tier ?? track.model_tier ?? '(default)';
+            const resolvedPerms = task.permissions ?? track.permissions ?? '(default)';
+            const resolvedCwd = task.cwd ?? track.cwd ?? workDir;
+            log.debug(`[task:${taskId}]`, `resolved: driver=${resolvedDriver} tier=${resolvedTier} cwd=${resolvedCwd}`);
+            log.debug(`[task:${taskId}]`, `permissions: ${JSON.stringify(resolvedPerms)}`);
+            if (task.continue_from) {
+                log.debug(`[task:${taskId}]`, `continue_from: "${task.continue_from}"`);
+            }
+            if (task.timeout) {
+                log.debug(`[task:${taskId}]`, `timeout: ${task.timeout}`);
+            }
+            try {
+                let result;
+                const timeoutMs = task.timeout ? parseDuration(task.timeout) : undefined;
+                const runOpts = { timeoutMs, signal: abortController.signal };
+                if (task.command) {
+                    log.debug(`[task:${taskId}]`, `command: ${task.command}`);
+                    result = await runCommand(task.command, task.cwd ?? workDir, runOpts);
+                }
+                else {
+                    // AI task: apply middleware chain
+                    const driverName = task.driver ?? track.driver ?? config.driver ?? 'claude-code';
+                    const driver = getHandler('drivers', driverName);
+                    let prompt = task.prompt;
+                    const originalLen = prompt.length;
+                    const mws = task.middlewares !== undefined ? task.middlewares : track.middlewares;
+                    if (mws && mws.length > 0) {
+                        log.debug(`[task:${taskId}]`, `middleware chain: ${mws.map(m => m.type).join(' → ')}`);
+                        const mwCtx = {
+                            task, track, outputMap, workDir: task.cwd ?? workDir,
+                        };
+                        for (const mwConfig of mws) {
+                            const before = prompt.length;
+                            const mwPlugin = getHandler('middlewares', mwConfig.type);
+                            const next = await mwPlugin.enhance(prompt, mwConfig, mwCtx);
+                            // R3: a middleware that returns undefined / null / a non-string
+                            // would silently corrupt the prompt sent to the driver. Fail loud
+                            // here so the user sees "middleware X.enhance returned ..." in the
+                            // task log instead of "[object Object]" arriving at the model.
+                            if (typeof next !== 'string') {
+                                throw new Error(`middleware "${mwConfig.type}".enhance() returned ${next === null ? 'null' : typeof next}, expected string`);
+                            }
+                            prompt = next;
+                            log.debug(`[task:${taskId}]`, `  ${mwConfig.type}: ${before} → ${prompt.length} chars`);
+                        }
+                    }
+                    log.debug(`[task:${taskId}]`, `prompt: ${originalLen} chars (final: ${prompt.length} chars)`);
+                    log.quiet(`--- prompt (final) ---\n${clip(prompt)}\n--- end prompt ---`, taskId);
+                    // H1: hand the driver a continue_from that has already been
+                    // qualified by dag.ts. Without this, drivers like codex/opencode/
+                    // claude-code do `outputMap.get(task.continue_from)` directly with
+                    // the user's raw (possibly bare) string, which races whenever two
+                    // tracks share a task name. dag.ts has the only authoritative
+                    // resolver, so we use its precomputed answer here.
+                    const enrichedTask = {
+                        ...task,
+                        prompt,
+                        continue_from: node.resolvedContinueFrom ?? task.continue_from,
+                    };
+                    const driverCtx = {
+                        sessionMap, outputMap, normalizedMap, workDir: task.cwd ?? workDir,
+                    };
+                    const spec = await driver.buildCommand(enrichedTask, track, driverCtx);
+                    log.debug(`[task:${taskId}]`, `driver=${driverName}`);
+                    log.debug(`[task:${taskId}]`, `spawn args: ${JSON.stringify(spec.args)}`);
+                    if (spec.cwd)
+                        log.debug(`[task:${taskId}]`, `spawn cwd: ${spec.cwd}`);
+                    if (spec.env)
+                        log.debug(`[task:${taskId}]`, `spawn env overrides: ${Object.keys(spec.env).join(', ')}`);
+                    if (spec.stdin)
+                        log.debug(`[task:${taskId}]`, `spawn stdin: ${spec.stdin.length} chars`);
+                    result = await runSpawn(spec, driver, runOpts);
+                }
+                // 5. Write output file with RAW stdout (preserves driver output format).
+                // Done BEFORE the completion check so a `file_exists` completion pointing
+                // at `task.output` observes the AI-generated artefact. Writes happen
+                // regardless of exit code so failed/timed-out tasks still leave a
+                // debuggable artefact on disk.
+                if (task.output) {
+                    // validatePath enforces no .. traversal and no absolute paths escaping workDir.
+                    const outPath = validatePath(task.output, workDir);
+                    await mkdir(dirname(outPath), { recursive: true });
+                    await Bun.write(outPath, result.stdout);
+                    result = { ...result, outputPath: outPath };
+                    // H1: only write the fully-qualified taskId. The previous "also store
+                    // bare id when not yet present" trick produced non-deterministic
+                    // continue_from lookups when two tracks shared a task name —
+                    // whichever finished first won the bare key. dag.ts now resolves
+                    // continue_from to a qualified id (DagNode.resolvedContinueFrom),
+                    // and the enrichedTask handed to drivers carries that qualified
+                    // version, so bare keys are no longer needed.
+                    outputMap.set(taskId, outPath);
+                }
+                // 6. Determine terminal status (without emitting yet — result must be complete first)
+                // H2: branch on failureKind so spawn errors no longer masquerade as
+                // timeouts. Old runners that don't set failureKind still work — we
+                // fall back to the historical `exitCode === -1 → timeout` heuristic so
+                // pre-existing third-party drivers don't regress.
+                let terminalStatus;
+                const kind = result.failureKind;
+                if (kind === 'timeout') {
+                    terminalStatus = 'timeout';
+                }
+                else if (kind === 'spawn_error') {
+                    terminalStatus = 'failed';
+                }
+                else if (kind === undefined && result.exitCode === -1) {
+                    // Legacy path: pre-H2 driver returned -1 with no kind. Treat as
+                    // timeout for backward compatibility (the previous behaviour).
+                    terminalStatus = 'timeout';
+                }
+                else if (result.exitCode !== 0) {
+                    terminalStatus = 'failed';
+                }
+                else if (task.completion) {
+                    const plugin = getHandler('completions', task.completion.type);
+                    const completionCtx = { workDir: task.cwd ?? workDir, signal: abortController.signal };
+                    const passed = await plugin.check(task.completion, result, completionCtx);
+                    // R4: strict boolean check. Truthy strings/numbers used to be coerced
+                    // to success — a check returning "ok" would let a failing task pass.
+                    if (typeof passed !== 'boolean') {
+                        throw new Error(`completion "${task.completion.type}".check() returned ${passed === null ? 'null' : typeof passed}, expected boolean`);
+                    }
+                    terminalStatus = passed ? 'success' : 'failed';
+                }
+                else {
+                    terminalStatus = 'success';
+                }
+                // Store normalized text separately (in-memory) for continue_from handoff.
+                // R15: clip oversized values so a runaway parseResult can't accumulate
+                // hundreds of MB across tasks.
+                if (result.normalizedOutput !== null) {
+                    const clipped = result.normalizedOutput.length > MAX_NORMALIZED_BYTES
+                        ? result.normalizedOutput.slice(0, MAX_NORMALIZED_BYTES) +
+                            `\n[…clipped at ${MAX_NORMALIZED_BYTES} bytes]`
+                        : result.normalizedOutput;
+                    // H1: qualified-only key (see comment near outputMap above).
+                    normalizedMap.set(taskId, clipped);
+                }
+                if (result.stderr) {
+                    const stderrPath = resolve(log.dir, `${taskId.replace(/\./g, '_')}.stderr`);
+                    await Bun.write(stderrPath, result.stderr);
+                    result = { ...result, stderrPath };
+                }
+                if (result.sessionId) {
+                    // H1: qualified-only key (see comment near outputMap above).
+                    sessionMap.set(taskId, result.sessionId);
+                }
+                // Set result and finishedAt before emitting terminal status so listeners see complete state
+                state.result = result;
+                state.finishedAt = nowISO();
+                setTaskStatus(taskId, terminalStatus);
+                // Log task outcome with relevant details
+                const durSec = (result.durationMs / 1000).toFixed(1);
+                if (terminalStatus === 'success') {
+                    log.info(`[task:${taskId}]`, `success (${durSec}s)`);
+                }
+                else {
+                    log.error(`[task:${taskId}]`, `${terminalStatus} exit=${result.exitCode} duration=${durSec}s`);
+                    if (result.stderr) {
+                        const tail = tailLines(result.stderr, 10);
+                        log.error(`[task:${taskId}]`, `stderr tail:\n${tail}`);
+                    }
+                }
+                // File-only: full stdout/stderr dump (clipped) + extracted metadata
+                log.debug(`[task:${taskId}]`, `stdout: ${result.stdout.length} chars, stderr: ${result.stderr.length} chars`);
+                if (result.sessionId) {
+                    log.debug(`[task:${taskId}]`, `sessionId: ${result.sessionId}`);
+                }
+                if (result.outputPath) {
+                    log.debug(`[task:${taskId}]`, `wrote output: ${result.outputPath}`);
+                }
+                if (result.stderrPath) {
+                    log.debug(`[task:${taskId}]`, `wrote stderr: ${result.stderrPath}`);
+                }
+                if (result.stdout) {
+                    log.quiet(`--- stdout (${taskId}) ---\n${clip(result.stdout)}\n--- end stdout ---`, taskId);
+                }
+                if (result.stderr) {
+                    log.quiet(`--- stderr (${taskId}) ---\n${clip(result.stderr)}\n--- end stderr ---`, taskId);
+                }
+                if (task.completion) {
+                    log.debug(`[task:${taskId}]`, `completion check: type=${task.completion.type} result=${terminalStatus}`);
+                }
+            }
+            catch (err) {
+                const errMsg = err instanceof Error ? (err.stack ?? err.message) : String(err);
+                log.error(`[task:${taskId}]`, `failed before execution: ${errMsg}`);
+                state.result = {
+                    exitCode: -1,
+                    stdout: '',
+                    stderr: errMsg,
+                    outputPath: null, stderrPath: null, durationMs: 0,
+                    sessionId: null, normalizedOutput: null,
+                    // H2: Engine-level pre-execution errors (driver throw, middleware
+                    // throw, getHandler 404) classify as spawn_error — the process never
+                    // ran, so calling them "timeout" was actively misleading.
+                    failureKind: 'spawn_error',
+                };
+                state.finishedAt = nowISO();
+                setTaskStatus(taskId, 'failed');
+            }
+            // 7. Fire hooks
+            const finalStatus = state.status;
+            try {
+                await fireHook(taskId, finalStatus === 'success' ? 'task_success' : 'task_failure');
+            }
+            catch (hookErr) {
+                log.error(`[task:${taskId}]`, `hook execution failed: ${hookErr instanceof Error ? hookErr.message : String(hookErr)}`);
+            }
+            // 8. Handle stop_all for failure states
+            if (finalStatus !== 'success' && getOnFailure(taskId) === 'stop_all') {
+                applyStopAll(node.track.id);
+            }
+        }
+        // ── Event loop ──
+        // Each task is launched as soon as ALL its deps reach a terminal state.
+        // We track in-flight tasks in `running` so a task completing mid-batch
+        // immediately unblocks its dependents without waiting for sibling tasks.
+        const running = new Map();
+        try {
+            while (!pipelineAborted) {
+                // Launch every task whose deps are all terminal and that isn't already in-flight
+                for (const [id, state] of states) {
+                    if (state.status !== 'waiting' || running.has(id))
+                        continue;
+                    const node = dag.nodes.get(id);
+                    const allDepsTerminal = node.dependsOn.length === 0 ||
+                        node.dependsOn.every(d => isTerminal(states.get(d).status));
+                    if (!allDepsTerminal)
+                        continue;
+                    const p = processTask(id).finally(() => running.delete(id));
+                    running.set(id, p);
+                }
+                // All tasks terminal — done
+                if ([...states.values()].every(s => isTerminal(s.status)))
+                    break;
+                if (running.size === 0) {
+                    // Nothing in-flight but non-terminal tasks exist (e.g. trigger-wait states
+                    // that processTask hasn't been called for yet). Poll briefly.
+                    await new Promise(r => setTimeout(r, POLL_INTERVAL_MS));
+                }
+                else {
+                    // Wait for any one task to finish, then re-scan for new launchables.
+                    await Promise.race(running.values());
+                }
+            }
+            if (pipelineAborted) {
+                // Wait for in-flight tasks to honour the abort signal before marking states.
+                if (running.size > 0)
+                    await Promise.allSettled(running.values());
+                for (const [id, state] of states) {
+                    if (!isTerminal(state.status)) {
+                        // Running tasks get timeout (they were killed); waiting tasks get skipped
+                        state.finishedAt = nowISO();
+                        setTaskStatus(id, state.status === 'running' ? 'timeout' : 'skipped');
+                    }
+                }
+            }
+        }
+        finally {
+            if (pipelineTimer)
+                clearTimeout(pipelineTimer);
+            // Clean up the external abort signal listener to prevent dead references
+            // accumulating on long-lived shared AbortControllers.
+            if (options.signal) {
+                options.signal.removeEventListener('abort', externalAbortHandler);
+            }
+            // Safety net: drain any approvals still pending at shutdown (e.g. crash path).
+            if (approvalGateway.pending().length > 0) {
+                approvalGateway.abortAll('pipeline finished');
+            }
+        }
+        // ── Summary ──
+        const summary = { total: 0, success: 0, failed: 0, skipped: 0, timeout: 0, blocked: 0 };
+        for (const [, state] of states) {
+            summary.total++;
+            switch (state.status) {
+                case 'success':
+                    summary.success++;
+                    break;
+                case 'failed':
+                    summary.failed++;
+                    break;
+                case 'skipped':
+                    summary.skipped++;
+                    break;
+                case 'timeout':
+                    summary.timeout++;
+                    break;
+                case 'blocked':
+                    summary.blocked++;
+                    break;
+            }
+        }
+        const finishedAt = nowISO();
+        const durationMs = new Date(finishedAt).getTime() - new Date(startedAt).getTime();
+        if (pipelineAborted) {
+            await executeHook(config.hooks, 'pipeline_error', buildPipelineErrorContext(pipelineInfo, 'Pipeline timeout exceeded'), workDir);
+        }
+        else {
+            await executeHook(config.hooks, 'pipeline_complete', buildPipelineCompleteContext({ ...pipelineInfo, finished_at: finishedAt, duration_ms: durationMs }, summary), workDir);
+        }
+        const allSuccess = !pipelineAborted
+            && summary.failed === 0 && summary.timeout === 0 && summary.blocked === 0;
+        log.section('Pipeline summary');
+        log.quiet(`status:   ${pipelineAborted ? 'aborted (timeout)' : 'completed'}`);
+        log.quiet(`duration: ${(durationMs / 1000).toFixed(1)}s`);
+        log.quiet(`counts:   total=${summary.total} success=${summary.success} ` +
+            `failed=${summary.failed} skipped=${summary.skipped} ` +
+            `timeout=${summary.timeout} blocked=${summary.blocked}`);
+        log.quiet('');
+        log.quiet('per-task:');
+        for (const [id, state] of states) {
+            const dur = state.result?.durationMs != null
+                ? `${(state.result.durationMs / 1000).toFixed(1)}s` : '-';
+            const exit = state.result?.exitCode ?? '-';
+            log.quiet(`  ${state.status.padEnd(8)} ${id}  (exit=${exit}, ${dur})`);
+        }
+        log.info('[pipeline]', `completed "${config.name}"`);
+        log.info('[pipeline]', `Total: ${summary.total} | Success: ${summary.success} | Failed: ${summary.failed} | Skipped: ${summary.skipped} | Timeout: ${summary.timeout} | Blocked: ${summary.blocked}`);
+        log.info('[pipeline]', `Duration: ${(durationMs / 1000).toFixed(1)}s`);
+        log.info('[pipeline]', `Log: ${log.path}`);
+        emit({ type: 'pipeline_end', runId, success: allSuccess });
+        return { success: allSuccess, runId, logPath: log.path, summary, states: freezeStates(states) };
+    }
+    finally {
+        // Close the persistent log file handle before pruning.
+        log.close();
+        // Prune old per-run log directories on every exit path (normal, blocked, or thrown).
+        // Exclude the current runId so a concurrent run cannot delete its own live directory.
+        if (maxLogRuns > 0) {
+            await pruneLogDirs(resolve(workDir, '.tagma', 'logs'), maxLogRuns, runId);
+        }
+    }
+}
+/**
+ * Delete the oldest subdirectories under `logsDir`, keeping only the most recent `keep`.
+ * Directories are sorted lexicographically; because runIds are prefixed with a base-36
+ * timestamp, lexicographic order equals chronological order.
+ *
+ * `excludeRunId` is always skipped from deletion even if it would otherwise be pruned —
+ * this prevents a concurrent run from removing a live log directory that is still in use.
+ */
+async function pruneLogDirs(logsDir, keep, excludeRunId) {
+    let entries;
+    try {
+        entries = await readdir(logsDir);
+    }
+    catch {
+        return; // logsDir doesn't exist yet — nothing to prune
+    }
+    // Only consider directories that look like run IDs (run_<...>), excluding the live run.
+    const runDirs = entries.filter(e => e.startsWith('run_') && e !== excludeRunId).sort();
+    const toDelete = runDirs.slice(0, Math.max(0, runDirs.length - keep));
+    await Promise.all(toDelete.map(dir => rm(resolve(logsDir, dir), { recursive: true, force: true }).catch(() => {
+        // Ignore deletion errors — stale dirs are better than a crash
+    })));
+}
+function isTerminal(status) {
+    return status === 'success' || status === 'failed' || status === 'timeout'
+        || status === 'skipped' || status === 'blocked';
+}
+/** Return a deep-copied, caller-safe snapshot of the states map. */
+function freezeStates(states) {
+    const copy = new Map();
+    for (const [id, s] of states) {
+        copy.set(id, {
+            config: { ...s.config },
+            trackConfig: { ...s.trackConfig },
+            status: s.status,
+            result: s.result ? { ...s.result } : null,
+            startedAt: s.startedAt,
+            finishedAt: s.finishedAt,
+        });
+    }
+    return copy;
+}
+//# sourceMappingURL=engine.js.map