@async/pipeline 0.1.5 → 0.2.3

package/dist/internal/node/runner.js

@@ -1,15 +1,16 @@
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
 import { availableParallelism } from "node:os";
-import { posix, relative } from "node:path";
+import { join, posix, relative } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
-import { sh, tasksForJob } from "../core/index.js";
-import { computeTaskCacheKey, createStore, outputFilesExist, readCacheEntry, resolveOutputFiles, restoreCacheOutputs, writeCacheEntry, writeExecution, writeTaskLog } from "./store.js";
+import { isAgentStep, isResolvedAgentStep, pipelineError, sh, tasksForJob } from "../core/index.js";
+import { acquireRunLock, computeTaskCacheKey, computeTaskCacheKeyDetailed, createStore, diffInputManifests, outputFilesExist, readCacheEntry, readCacheInputManifest, readTaskBaseline, resolveOutputFiles, restoreCacheOutputs, writeAgentPrompt, writeAgentTranscript, writeCacheEntry, writeCacheInputManifest, writeContextPack, writeExecution, writeTaskBaseline, writeTaskLog } from "./store.js";
 import { createRunPlan, sourceContext } from "./sources.js";
 export class HostCommandExecutor {
     name = "host";
     runShell(command, options) {
-        return runProcess(command, { cwd: options.cwd, env: options.env, timeoutMs: options.timeoutMs });
+        return runProcess(command, { cwd: options.cwd, env: options.env, echo: options.echo, timeoutMs: options.timeoutMs, label: options.task?.id, redactValues: options.redactValues });
     }
     async checkTool(tool) {
         const result = await runProcess(`command -v ${shellEscape(tool)}`, { cwd: process.cwd(), env: process.env, echo: false });
@@ -23,17 +24,20 @@ export class DockerCommandExecutor {
         this.options = options;
     }
     runShell(command, options) {
-        return runProcess(this.dockerCommand(command, options.cwd, options.env), { cwd: this.options.hostCwd, env: options.env, timeoutMs: options.timeoutMs });
+        return runProcess(this.dockerCommand(command, options.cwd, options.env, options.forwardEnvKeys ?? []), { cwd: this.options.hostCwd, env: options.env, echo: options.echo, timeoutMs: options.timeoutMs, label: options.task?.id, redactValues: options.redactValues });
     }
     async checkTool(tool) {
-        const result = await runProcess(this.dockerCommand(`command -v ${shellEscape(tool)}`, this.options.hostCwd, process.env), {
+        const result = await runProcess(this.dockerCommand(`command -v ${shellEscape(tool)}`, this.options.hostCwd, process.env, []), {
             cwd: this.options.hostCwd,
             env: process.env,
             echo: false
         });
         return result.code === 0;
     }
-    dockerCommand(command, cwd, env) {
+    dockerCommand(command, cwd, env, forwardEnvKeys) {
+        // Only explicitly forwarded keys cross the container boundary. Forwarding
+        // the whole host env would leak unrelated secrets into every container.
+        const forwarded = [...new Set(forwardEnvKeys)].filter((key) => env[key] !== undefined).sort();
         return [
             "docker",
             "run",
@@ -41,7 +45,7 @@ export class DockerCommandExecutor {
             "-w",
             shellEscape(this.containerCwd(cwd)),
             ...this.options.volumes.flatMap((volume) => ["-v", shellEscape(`${volume.source}:${volume.target}${volume.readonly ? ":ro" : ""}`)]),
-            ...Object.keys(env).filter((key) => env[key] !== undefined).flatMap((key) => ["-e", shellEscape(key)]),
+            ...forwarded.flatMap((key) => ["-e", shellEscape(key)]),
             shellEscape(this.options.image),
             "bash",
             "-lc",
@@ -64,9 +68,8 @@ export class LimaCommandExecutor {
         this.vm = vm;
     }
     runShell(command, options) {
-        const vm = options.task.environment?.vm ?? this.vm;
         const escaped = shellEscape(`cd ${shellEscape(options.cwd)} && ${command}`);
-        return runProcess(`limactl shell ${shellEscape(vm)} -- bash -lc ${escaped}`, { cwd: options.cwd, env: options.env, timeoutMs: options.timeoutMs });
+        return runProcess(`limactl shell ${shellEscape(this.vm)} -- bash -lc ${escaped}`, { cwd: options.cwd, env: options.env, echo: options.echo, timeoutMs: options.timeoutMs, label: options.task?.id, redactValues: options.redactValues });
     }
     async checkTool(tool) {
         const result = await runProcess(`limactl shell ${shellEscape(this.vm)} -- bash -lc ${shellEscape(`command -v ${shellEscape(tool)}`)}`, {
@@ -76,37 +79,43 @@ export class LimaCommandExecutor {
         return result.code === 0;
     }
 }
-export function hostWorkspace(options = {}) {
-    return {
-        cwd: options.cwd ?? process.cwd(),
-        env: options.env ?? process.env,
+/**
+ * Resolve flat run options into the execution context a run uses: host by
+ * default, or the selected sandbox (by id from `pipeline.sandboxes`, or an
+ * inline definition).
+ */
+export function resolveExecutionContext(pipeline, target = {}) {
+    const cwd = target.cwd ?? process.cwd();
+    const env = target.env ?? process.env;
+    const base = {
+        cwd,
+        env,
         fs: { kind: "host" },
-        executor: options.executor ?? new HostCommandExecutor(),
-        commands: options.commands
+        executor: target.executor ?? new HostCommandExecutor(),
+        commands: target.commands
     };
-}
-export function dockerWorkspace(options) {
-    const cwd = options.cwd ?? process.cwd();
-    const workdir = options.workdir ?? "/workspace";
-    return hostWorkspace({
-        cwd,
-        env: options.env,
+    const ref = target.sandbox;
+    if (!ref || ref === "host")
+        return base;
+    const definition = typeof ref === "string" ? pipeline.sandboxes[ref] : ref;
+    if (!definition) {
+        throw new Error(`Unknown sandbox "${String(ref)}". Declare it under \`sandboxes\` in the pipeline config.`);
+    }
+    if (definition.kind === "host")
+        return base;
+    if (definition.kind === "lima") {
+        return { ...base, executor: new LimaCommandExecutor(definition.vm) };
+    }
+    const workdir = definition.workdir ?? "/workspace";
+    return {
+        ...base,
         executor: new DockerCommandExecutor({
-            image: options.image,
+            image: definition.image,
             hostCwd: cwd,
             workdir,
-            volumes: options.volumes ?? [{ source: cwd, target: workdir }]
-        }),
-        commands: options.commands
-    });
-}
-export function limaWorkspace(options = {}) {
-    return hostWorkspace({
-        cwd: options.cwd,
-        env: options.env,
-        executor: new LimaCommandExecutor(options.vm),
-        commands: options.commands
-    });
+            volumes: definition.volumes ?? [{ source: cwd, target: workdir }]
+        })
+    };
 }
 export function commandProxy(policy = { rules: [] }) {
     const records = [];
@@ -116,7 +125,7 @@ export function commandProxy(policy = { rules: [] }) {
             const started = Date.now();
             const action = matchingAction(policy, invocation.argv);
             const status = commandStatus(action);
-            const result = await runCommandAction(action, next);
+            const result = await runCommandAction(action, invocation, next);
             const outputPolicy = action.output ?? policy.output ?? {};
             if (policy.record) {
                 records.push({
@@ -144,18 +153,34 @@ export function commandProxy(policy = { rules: [] }) {
 const memoryCacheEntries = new Map();
 const DEFAULT_MAX_CONCURRENCY = 4;
 export async function runJob(pipeline, options) {
-    const workspace = options.workspace ?? hostWorkspace();
-    const store = await createStore(workspace.cwd);
-    const plan = await createRunPlan(pipeline, workspace.cwd, store);
+    // Install before any task spawns so an early Ctrl-C still finalizes the record.
+    ensureSignalForwarding();
+    const context = resolveExecutionContext(pipeline, options);
+    const store = await createStore(context.cwd);
+    // One run at a time per project: concurrent runs would race on the task
+    // cache, run records, and synced outputs. A lock whose holder process is
+    // dead is reclaimed automatically.
+    const lock = await acquireRunLock(store);
+    try {
+        return await runJobLocked(pipeline, options, context, store);
+    }
+    finally {
+        await lock.release();
+    }
+}
+async function runJobLocked(pipeline, options, context, store) {
+    const plan = await createRunPlan(pipeline, context.cwd, store);
     const graph = tasksForJob(plan.pipeline, options.id);
     const record = {
+        schemaVersion: 1,
         id: `${new Date().toISOString().replaceAll(/[:.]/g, "-")}-${randomUUID().slice(0, 8)}`,
         pipelineName: plan.pipeline.name,
         jobId: options.id,
-        cwd: workspace.cwd,
+        cwd: context.cwd,
+        pid: process.pid,
         startedAt: new Date().toISOString(),
         status: "running",
-        mode: options.mode ?? (workspace.env.CI ? "ci" : "manual"),
+        mode: options.mode ?? (context.env.CI ? "ci" : "manual"),
         tasks: [],
         sources: Object.fromEntries(Object.entries(plan.sources).map(([sourceId, resolved]) => [sourceId, resolved.record]))
     };
@@ -199,10 +224,11 @@ export async function runJob(pipeline, options) {
         if (!promise) {
             promise = runSourcePrepare(source, {
                 candidate: plan.candidate,
-                executor: workspace.executor,
-                rootCwd: workspace.cwd,
+                executor: context.executor,
+                rootCwd: context.cwd,
                 runId: record.id,
-                workspaceEnv: workspace.env,
+                contextEnv: context.env,
+                echo: options.echo,
                 store
             });
             sourcePreparePromises.set(source.id, promise);
@@ -233,70 +259,188 @@ export async function runJob(pipeline, options) {
         }
         const result = await runTask(plan.pipeline, taskDefinition, {
             candidate: plan.candidate,
-            cwd: taskDefinition.source?.dir || workspace.cwd,
-            executor: workspace.executor,
-            rootCwd: workspace.cwd,
+            cwd: taskDefinition.source?.dir || context.cwd,
+            executor: context.executor,
+            rootCwd: context.cwd,
             runId: record.id,
             source: taskDefinition.source,
             envDefinitions,
-            workspaceEnv: workspace.env,
+            contextEnv: context.env,
             sourcePrepareCommands: taskSource ? await resolvePrepareCommands(taskSource, {
                 candidate: plan.candidate,
-                rootCwd: workspace.cwd,
+                rootCwd: context.cwd,
                 runId: record.id,
-                workspaceEnv: workspace.env
+                contextEnv: context.env
             }) : [],
             dependencyFingerprints: Object.fromEntries(taskDefinition.dependsOn.map((dependency) => [
                 dependency,
                 taskFingerprints.get(dependency) ?? null
             ])),
+            force: options.force,
+            echo: options.echo,
             store
         });
         results.push({ order: graphIndex.get(taskId) ?? results.length, result });
         return { taskId, failed: result.status === "failed", results, taskResult: result };
     };
-    while (ready.length > 0 || running.size > 0) {
-        while (!failed && ready.length > 0 && running.size < concurrency) {
-            const taskId = ready.shift();
-            if (!taskId)
+    const scheduleTask = (taskId) => 
+    // The scheduler races these promises, so they must never reject: an
+    // unexpected throw becomes a failed task result and the record finalizes.
+    runScheduledTask(taskId).catch((error) => {
+        const result = {
+            id: taskId,
+            status: "failed",
+            startedAt: new Date().toISOString(),
+            finishedAt: new Date().toISOString(),
+            durationMs: 0,
+            attempts: 0,
+            cacheHit: false,
+            error: error instanceof Error ? error.message : String(error)
+        };
+        return {
+            taskId,
+            failed: true,
+            results: [{ order: graphIndex.get(taskId) ?? 0, result }],
+            taskResult: result
+        };
+    });
+    try {
+        while (ready.length > 0 || running.size > 0) {
+            while (!failed && ready.length > 0 && running.size < concurrency) {
+                const taskId = ready.shift();
+                if (!taskId)
+                    break;
+                running.set(taskId, scheduleTask(taskId));
+            }
+            if (running.size === 0)
                 break;
-            running.set(taskId, runScheduledTask(taskId));
-        }
-        if (running.size === 0)
-            break;
-        const completed = await Promise.race(running.values());
-        running.delete(completed.taskId);
-        for (const entry of completed.results) {
-            recordedResults.set(entry.result.id, entry);
-        }
-        if (completed.taskResult) {
-            taskFingerprints.set(completed.taskId, completed.taskResult.cacheKey ?? `${completed.taskId}:${completed.taskResult.status}`);
-        }
-        await updateRecord();
-        if (completed.failed) {
-            failed = true;
-            ready.length = 0;
-            continue;
-        }
-        if (failed || !completed.taskResult)
-            continue;
-        const node = graphNodes.get(completed.taskId);
-        for (const dependent of node?.dependents ?? []) {
-            if (!plan.pipeline.tasks[dependent])
+            const completed = await Promise.race(running.values());
+            running.delete(completed.taskId);
+            for (const entry of completed.results) {
+                recordedResults.set(entry.result.id, entry);
+            }
+            if (completed.taskResult) {
+                taskFingerprints.set(completed.taskId, completed.taskResult.cacheKey ?? `${completed.taskId}:${completed.taskResult.status}`);
+            }
+            await updateRecord();
+            if (completed.failed) {
+                failed = true;
+                ready.length = 0;
                 continue;
-            const remaining = Math.max(0, (dependencyCounts.get(dependent) ?? 0) - 1);
-            dependencyCounts.set(dependent, remaining);
-            if (remaining === 0) {
-                ready.push(dependent);
             }
+            if (failed || !completed.taskResult)
+                continue;
+            const node = graphNodes.get(completed.taskId);
+            for (const dependent of node?.dependents ?? []) {
+                if (!plan.pipeline.tasks[dependent])
+                    continue;
+                const remaining = Math.max(0, (dependencyCounts.get(dependent) ?? 0) - 1);
+                dependencyCounts.set(dependent, remaining);
+                if (remaining === 0) {
+                    ready.push(dependent);
+                }
+            }
+            ready.sort((left, right) => (graphIndex.get(left) ?? 0) - (graphIndex.get(right) ?? 0));
         }
-        ready.sort((left, right) => (graphIndex.get(left) ?? 0) - (graphIndex.get(right) ?? 0));
+    }
+    catch (error) {
+        // Never leave an execution record stuck in "running" on disk.
+        record.status = "failed";
+        record.finishedAt = new Date().toISOString();
+        await writeExecution(store, record).catch(() => { });
+        throw error;
     }
     record.status = failed ? "failed" : "passed";
     record.finishedAt = new Date().toISOString();
     await writeExecution(store, record);
     return record;
 }
+/**
+ * Computes the execution order and predicted cache behavior for a job without running it.
+ * Predictions reuse the real cache-key chain but do not validate cached output files.
+ */
+export async function planJob(pipeline, options) {
+    const context = resolveExecutionContext(pipeline, options);
+    const store = await createStore(context.cwd);
+    const plan = await createRunPlan(pipeline, context.cwd, store);
+    const graph = tasksForJob(plan.pipeline, options.id);
+    const jobDefinition = plan.pipeline.jobs[options.id];
+    const envDefinitions = {
+        ...plan.pipeline.env,
+        ...(jobDefinition?.env ?? {})
+    };
+    const fingerprints = new Map();
+    const entries = [];
+    for (const taskId of graph.executionOrder) {
+        const taskDefinition = plan.pipeline.tasks[taskId];
+        if (!taskDefinition)
+            continue;
+        try {
+            const taskCwd = taskDefinition.source?.dir || context.cwd;
+            const resolvedEnv = buildTaskEnv(context.env, {
+                candidate: plan.candidate,
+                envDefinitions,
+                rootCwd: context.cwd,
+                source: taskDefinition.source,
+                taskId
+            });
+            const taskContext = createTaskContext(taskDefinition, {
+                candidate: plan.candidate,
+                cwd: taskCwd,
+                env: resolvedEnv.env,
+                metadata: {},
+                rootCwd: context.cwd,
+                runId: "dry-run",
+                source: taskDefinition.source,
+                writeLog() { }
+            });
+            const steps = await resolveTaskSteps(plan.pipeline.agents, taskDefinition.steps, taskContext);
+            const taskSource = taskDefinition.source?.name ? plan.sources[taskDefinition.source.name] : undefined;
+            const prepareCommands = taskSource
+                ? (await resolvePrepareCommands(taskSource, {
+                    candidate: plan.candidate,
+                    rootCwd: context.cwd,
+                    runId: "dry-run",
+                    contextEnv: context.env
+                })).map((command) => command.command)
+                : [];
+            const cacheKey = await computeTaskCacheKey(plan.pipeline, taskDefinition, taskCwd, {
+                candidate: plan.candidate,
+                dependencyFingerprints: Object.fromEntries(taskDefinition.dependsOn.map((dependency) => [
+                    dependency,
+                    fingerprints.get(dependency) ?? null
+                ])),
+                prepareCommands,
+                source: taskDefinition.source,
+                steps
+            });
+            fingerprints.set(taskId, cacheKey);
+            if (!taskDefinition.cache.enabled) {
+                entries.push({ id: taskId, cacheEnabled: false, predicted: "run", cacheKey });
+                continue;
+            }
+            const cached = await readTaskCacheEntry(taskDefinition, store, cacheKey);
+            const fresh = cached?.status === "passed" && isCacheEntryFresh(cached, taskDefinition.cache.ttlMs);
+            entries.push({
+                id: taskId,
+                cacheEnabled: true,
+                predicted: fresh ? "cached" : "run",
+                cacheKey,
+                reason: fresh ? undefined : cached ? "stale or unusable cache entry" : "no cache entry"
+            });
+        }
+        catch (error) {
+            fingerprints.set(taskId, null);
+            entries.push({
+                id: taskId,
+                cacheEnabled: taskDefinition.cache.enabled ?? false,
+                predicted: "unknown",
+                reason: error instanceof Error ? error.message : String(error)
+            });
+        }
+    }
+    return { jobId: options.id, executionOrder: graph.executionOrder, entries };
+}
 export async function runSingleTask(pipeline, taskId, options = {}) {
     const syntheticJobId = `task:${taskId}`;
     const syntheticPipeline = {
@@ -312,16 +456,21 @@ async function runTask(pipeline, taskDefinition, options) {
     const started = Date.now();
     const startedAt = new Date().toISOString();
     const metadata = {};
-    let combinedLog = "";
+    const taskLog = cappedBuffer(resolveMaxLogBytes(options.contextEnv));
     let taskEnv;
+    let envSecretValues = [];
+    let forwardEnvKeys = [];
     try {
-        taskEnv = buildTaskEnv(options.workspaceEnv, {
+        const resolvedTaskEnv = buildTaskEnv(options.contextEnv, {
             candidate: options.candidate,
             envDefinitions: options.envDefinitions,
             rootCwd: options.rootCwd,
             source: options.source,
             taskId: taskDefinition.id
         });
+        taskEnv = resolvedTaskEnv.env;
+        envSecretValues = resolvedTaskEnv.secretValues;
+        forwardEnvKeys = [...resolvedTaskEnv.definedKeys, ...(taskDefinition.requires?.secrets ?? [])];
     }
     catch (error) {
         const lastError = error instanceof Error ? error.message : String(error);
@@ -347,18 +496,25 @@ async function runTask(pipeline, taskDefinition, options) {
         runId: options.runId,
         source: options.source,
         writeLog(message) {
-            combinedLog += `${message}\n`;
+            taskLog.append(`${message}\n`);
         }
     });
-    const resolvedSteps = await resolveTaskSteps(taskDefinition.steps, context);
-    const cacheKey = await computeTaskCacheKey(pipeline, taskDefinition, options.cwd, {
+    const redactValues = [
+        ...envSecretValues,
+        ...(taskDefinition.requires?.secrets ?? [])
+            .map((secret) => taskEnv[secret])
+            .filter((value) => typeof value === "string" && value.length > 0)
+    ];
+    const redactLog = (log) => redactKnownValues(log, redactValues);
+    const resolvedSteps = await resolveTaskSteps(pipeline.agents, taskDefinition.steps, context);
+    const { cacheKey, inputs: inputManifest } = await computeTaskCacheKeyDetailed(pipeline, taskDefinition, options.cwd, {
         candidate: options.candidate,
         dependencyFingerprints: options.dependencyFingerprints,
         prepareCommands: (options.sourcePrepareCommands ?? []).map((command) => command.command),
         source: options.source,
         steps: resolvedSteps
     });
-    if (taskDefinition.cache.enabled) {
+    if (taskDefinition.cache.enabled && !options.force) {
         const cached = await readTaskCacheEntry(taskDefinition, options.store, cacheKey);
         if (cached?.status === "passed") {
             const cacheHit = await validateTaskCacheHit(taskDefinition, options.store, cacheKey, options.cwd, cached);
@@ -375,9 +531,15 @@ async function runTask(pipeline, taskDefinition, options) {
                     durationMs: Date.now() - started
                 };
                 await writeTaskLog(options.store, options.runId, taskDefinition.id, `[cache hit] ${cacheKey}\n`);
+                // A hit proves this input state passes: refresh the diff baseline, and
+                // backfill the digest manifest for entries created before 0.2.3.
+                if ((await readCacheInputManifest(options.store, cacheKey)) === null) {
+                    await writeCacheInputManifest(options.store, cacheKey, inputManifest);
+                }
+                await writeTaskBaseline(options.store, taskDefinition.id, cacheKey);
                 return result;
             }
-            combinedLog += `[cache miss] ${cacheHit.reason}\n`;
+            taskLog.append(`[cache miss] ${cacheHit.reason}\n`);
         }
     }
     let attempts = 0;
@@ -402,12 +564,36 @@ async function runTask(pipeline, taskDefinition, options) {
                     await runFunctionStep(step, context, taskDefinition.timeoutMs);
                     continue;
                 }
+                if (isAgentStep(step)) {
+                    if (!isResolvedAgentStep(step)) {
+                        throw new Error(`Agent step for task "${taskDefinition.id}" was not resolved.`);
+                    }
+                    const result = await runAgentStep(step, taskDefinition, {
+                        executor: options.executor,
+                        cwd: options.cwd,
+                        env: taskEnv,
+                        echo: options.echo,
+                        redactValues,
+                        forwardEnvKeys,
+                        store: options.store,
+                        runId: options.runId
+                    });
+                    taskLog.append(result.stdout);
+                    taskLog.append(result.stderr);
+                    if (result.timedOut) {
+                        throw new Error(`Task "${taskDefinition.id}" timed out after ${taskDefinition.timeoutMs}ms.`);
+                    }
+                    if (result.code !== 0) {
+                        throw new Error(`Agent step failed with exit code ${result.code} (profile "${step.use}", model "${step.model}").`);
+                    }
+                    continue;
+                }
                 if (!isShellCommand(step)) {
                     throw new Error(`Deferred shell step for task "${taskDefinition.id}" was not resolved.`);
                 }
-                const result = await runShellStep(step, taskDefinition, { ...options, env: taskEnv });
-                combinedLog += result.stdout;
-                combinedLog += result.stderr;
+                const result = await runShellStep(step, taskDefinition, { executor: options.executor, cwd: options.cwd, env: taskEnv, echo: options.echo, redactValues, forwardEnvKeys });
+                taskLog.append(result.stdout);
+                taskLog.append(result.stderr);
                 if (result.timedOut) {
                     throw new Error(`Task "${taskDefinition.id}" timed out after ${taskDefinition.timeoutMs}ms.`);
                 }
@@ -427,15 +613,21 @@ async function runTask(pipeline, taskDefinition, options) {
                 cacheHit: false,
                 metadata
             };
-            await writeTaskLog(options.store, options.runId, taskDefinition.id, combinedLog);
+            await writeTaskLog(options.store, options.runId, taskDefinition.id, redactLog(taskLog.read()));
             if (taskDefinition.cache.enabled) {
                 await writeTaskCacheEntry(taskDefinition, options.store, cacheKey, result, options.cwd);
+                await writeCacheInputManifest(options.store, cacheKey, inputManifest);
+                await writeTaskBaseline(options.store, taskDefinition.id, cacheKey);
             }
             return result;
         }
         catch (error) {
             lastError = error instanceof Error ? error.message : String(error);
-            combinedLog += `[attempt ${attempts}] ${lastError}\n`;
+            taskLog.append(`[attempt ${attempts}] ${lastError}\n`);
+            // Don't retry (or sleep through a retry delay) while shutting down;
+            // the failure is the shutdown itself, not a flaky task.
+            if (shutdownState)
+                break;
             if (attempts < maxAttempts && taskDefinition.retry.delayMs) {
                 await delay(taskDefinition.retry.delayMs);
             }
@@ -453,7 +645,111 @@ async function runTask(pipeline, taskDefinition, options) {
         error: lastError,
         metadata
     };
-    await writeTaskLog(options.store, options.runId, taskDefinition.id, combinedLog);
+    const redactedLog = redactLog(taskLog.read());
+    await writeTaskLog(options.store, options.runId, taskDefinition.id, redactedLog);
+    try {
+        await writeFailureContextPack({
+            store: options.store,
+            runId: options.runId,
+            taskDefinition,
+            error: redactLog(lastError),
+            attempts,
+            cacheKey,
+            redactedLog,
+            inputManifest,
+            rootCwd: options.rootCwd
+        });
+    }
+    catch {
+        // Packs are evidence, not state: failing to write one must not mask the task failure.
+    }
+    return result;
+}
+const CONTEXT_PACK_LOG_TAIL_BYTES = 4096;
+/**
+ * ADR-0003: a bounded, machine-readable failure summary next to the run
+ * record — the failing task, a redacted log tail, the reproduction command,
+ * the input diff against the task's last passing cache entry (digests only,
+ * never contents), and the registered claims whose test titles appear in the
+ * log.
+ */
+async function writeFailureContextPack(options) {
+    let inputDiff = { baselineMissing: true };
+    const baseline = await readTaskBaseline(options.store, options.taskDefinition.id);
+    if (baseline) {
+        const baselineManifest = await readCacheInputManifest(options.store, baseline.cacheKey);
+        if (baselineManifest) {
+            inputDiff = {
+                baselineCacheKey: baseline.cacheKey,
+                baselineRecordedAt: baseline.recordedAt,
+                ...diffInputManifests(baselineManifest, options.inputManifest)
+            };
+        }
+    }
+    const claims = await matchRegisteredClaims(options.rootCwd, options.redactedLog);
+    const pack = {
+        schemaVersion: 1,
+        task: options.taskDefinition.id,
+        runId: options.runId,
+        status: "failed",
+        error: options.error,
+        attempts: options.attempts,
+        cacheKey: options.cacheKey,
+        reproduce: `async-pipeline run-task ${options.taskDefinition.id}`,
+        logTail: options.redactedLog.slice(-CONTEXT_PACK_LOG_TAIL_BYTES),
+        inputDiff,
+        ...(claims.length > 0 ? { claims } : {})
+    };
+    await writeContextPack(options.store, options.runId, options.taskDefinition.id, pack);
+}
+/** When the project keeps a claims registry, name the promises this failure touches. */
+async function matchRegisteredClaims(rootCwd, log) {
+    try {
+        const registry = JSON.parse(await readFile(join(rootCwd, "tests", "claims.json"), "utf8"));
+        const matched = [];
+        for (const claim of registry.claims ?? []) {
+            if (!claim.id || !Array.isArray(claim.tests))
+                continue;
+            if (claim.tests.some((title) => typeof title === "string" && title.length > 0 && log.includes(title))) {
+                matched.push(claim.id);
+            }
+        }
+        return matched.sort();
+    }
+    catch {
+        return [];
+    }
+}
+async function runAgentStep(step, taskDefinition, options) {
+    // The prompt travels as a file redirected to the adapter's stdin: shell-safe
+    // for arbitrary prompt text, and the prompt becomes run evidence alongside
+    // the transcript. The adapter also sees profile/model/prompt-file env keys
+    // so wrapper scripts can stay generic.
+    const promptPath = await writeAgentPrompt(options.store, options.runId, taskDefinition.id, step.prompt);
+    const command = `${step.command.map((part) => shellEscape(part)).join(" ")} < ${shellEscape(promptPath)}`;
+    const env = {
+        ...options.env,
+        ASYNC_PIPELINE_AGENT_PROFILE: step.use,
+        ASYNC_PIPELINE_AGENT_MODEL: step.model,
+        ASYNC_PIPELINE_AGENT_PROMPT_FILE: promptPath
+    };
+    const startedAt = new Date().toISOString();
+    const started = Date.now();
+    const result = await options.executor.runShell(command, {
+        cwd: options.cwd,
+        env,
+        task: taskDefinition,
+        timeoutMs: taskDefinition.timeoutMs,
+        echo: options.echo,
+        redactValues: options.redactValues,
+        forwardEnvKeys: options.forwardEnvKeys
+    });
+    const redact = (value) => redactKnownValues(value, options.redactValues ?? []);
+    const transcript = [
+        JSON.stringify({ type: "request", at: startedAt, task: taskDefinition.id, profile: step.use, model: step.model, prompt: redact(step.prompt) }),
+        JSON.stringify({ type: "response", at: new Date().toISOString(), durationMs: Date.now() - started, code: result.code, timedOut: result.timedOut ?? false, stdout: redact(result.stdout), stderr: redact(result.stderr) })
+    ].join("\n");
+    await writeAgentTranscript(options.store, options.runId, taskDefinition.id, `${transcript}\n`);
     return result;
 }
 async function runShellStep(step, taskDefinition, options) {
@@ -461,7 +757,10 @@ async function runShellStep(step, taskDefinition, options) {
         cwd: options.cwd,
         env: options.env,
         task: taskDefinition,
-        timeoutMs: taskDefinition.timeoutMs
+        timeoutMs: taskDefinition.timeoutMs,
+        echo: options.echo,
+        redactValues: options.redactValues,
+        forwardEnvKeys: options.forwardEnvKeys
     });
 }
 async function runSourcePrepare(source, options) {
@@ -471,24 +770,25 @@ async function runSourcePrepare(source, options) {
     const startedAt = new Date().toISOString();
     const taskId = `${source.id}:prepare`;
     const sourceTaskContext = sourceContext(source);
-    let log = "";
+    const log = cappedBuffer(resolveMaxLogBytes(options.contextEnv));
+    const prepareEnv = buildTaskEnv(options.contextEnv, {
+        candidate: options.candidate,
+        rootCwd: options.rootCwd,
+        source: sourceTaskContext
+    });
     const context = createTaskContext({ id: taskId }, {
         candidate: options.candidate,
         cwd: source.dir,
-        env: buildTaskEnv(options.workspaceEnv, {
-            candidate: options.candidate,
-            rootCwd: options.rootCwd,
-            source: sourceTaskContext
-        }),
+        env: prepareEnv.env,
         metadata: {},
         rootCwd: options.rootCwd,
         runId: options.runId,
         source: sourceTaskContext,
         writeLog(message) {
-            log += `${message}\n`;
+            log.append(`${message}\n`);
         }
     });
-    const steps = await resolveTaskSteps(source.definition.prepare, context);
+    const steps = await resolveTaskSteps({}, source.definition.prepare, context);
     try {
         for (const step of steps) {
             if (typeof step === "function") {
@@ -500,15 +800,14 @@ async function runSourcePrepare(source, options) {
             }
             const result = await options.executor.runShell(step.command, {
                 cwd: source.dir,
-                env: buildTaskEnv(options.workspaceEnv, {
-                    candidate: options.candidate,
-                    rootCwd: options.rootCwd,
-                    source: sourceTaskContext
-                }),
-                task: { id: taskId }
+                env: prepareEnv.env,
+                task: { id: taskId },
+                echo: options.echo,
+                redactValues: prepareEnv.secretValues,
+                forwardEnvKeys: prepareEnv.definedKeys
             });
-            log += result.stdout;
-            log += result.stderr;
+            log.append(result.stdout);
+            log.append(result.stderr);
             if (result.code !== 0) {
                 throw new Error(`Command failed with exit code ${result.code}: ${step.command}`);
             }
@@ -522,7 +821,7 @@ async function runSourcePrepare(source, options) {
             attempts: 1,
             cacheHit: false
         };
-        await writeTaskLog(options.store, options.runId, taskId, log);
+        await writeTaskLog(options.store, options.runId, taskId, log.read());
         return result;
     }
     catch (error) {
@@ -536,8 +835,8 @@ async function runSourcePrepare(source, options) {
             cacheHit: false,
             error: error instanceof Error ? error.message : String(error)
         };
-        log += `[prepare] ${result.error}\n`;
-        await writeTaskLog(options.store, options.runId, taskId, log);
+        log.append(`[prepare] ${result.error}\n`);
+        await writeTaskLog(options.store, options.runId, taskId, log.read());
         return result;
     }
 }
@@ -545,27 +844,31 @@ async function resolvePrepareCommands(source, options) {
     const context = createTaskContext({ id: `${source.id}:prepare` }, {
         candidate: options.candidate,
         cwd: source.dir,
-        env: buildTaskEnv(options.workspaceEnv, {
+        env: buildTaskEnv(options.contextEnv, {
             candidate: options.candidate,
             rootCwd: options.rootCwd,
             source: sourceContext(source)
-        }),
+        }).env,
         metadata: {},
         rootCwd: options.rootCwd,
         runId: options.runId,
         source: sourceContext(source),
         writeLog() { }
     });
-    const steps = await resolveTaskSteps(source.definition.prepare, context);
+    const steps = await resolveTaskSteps({}, source.definition.prepare, context);
     return steps.filter(isShellCommand);
 }
-async function resolveTaskSteps(steps, context) {
+async function resolveTaskSteps(agents, steps, context) {
     const resolved = [];
     for (const step of steps) {
         if (typeof step === "function" || step.kind === "shell") {
             resolved.push(step);
             continue;
         }
+        if (step.kind === "agent") {
+            resolved.push(resolveAgentStep(agents, step, context));
+            continue;
+        }
         const command = await step.command(context);
         if (command.kind !== "shell") {
             throw new Error(`Deferred shell step for task "${context.taskId}" must return sh\`...\`.`);
@@ -574,6 +877,33 @@ async function resolveTaskSteps(steps, context) {
     }
     return resolved;
 }
+/** Mirrors env.var(...) resolution in resolveEnvDefinitions: selector from the task env, optional default, optional value map. */
+function resolveAgentValue(value, env, what, taskId) {
+    if (typeof value === "string")
+        return value;
+    const selector = env[value.name] ?? value.default;
+    if (selector === undefined || selector === "") {
+        throw new Error(`Required variable "${value.name}" for ${what} is not available for task "${taskId}".`);
+    }
+    if (value.values) {
+        const mapped = value.values[selector];
+        if (mapped === undefined) {
+            throw new Error(`Variable "${value.name}" value "${selector}" is not mapped for ${what} in task "${taskId}".`);
+        }
+        return mapped;
+    }
+    return selector;
+}
+function resolveAgentStep(agents, step, context) {
+    const use = resolveAgentValue(step.use, context.env, "the agent profile selection", context.taskId);
+    const profile = agents[use];
+    if (!profile) {
+        const known = Object.keys(agents).sort();
+        throw pipelineError("ASYNC_PIPELINE_AGENT_UNKNOWN", `Task "${context.taskId}" resolved agent profile "${use}", which is not declared in the pipeline's agents block.${known.length > 0 ? ` Known profiles: ${known.join(", ")}.` : " No agent profiles are declared."}`);
+    }
+    const model = resolveAgentValue(step.model ?? profile.model, context.env, `agent profile "${use}" model`, context.taskId);
+    return { kind: "agent", use, prompt: step.prompt, model, command: [...profile.command] };
+}
 function createTaskContext(taskDefinition, options) {
     return {
         taskId: taskDefinition.id,
@@ -595,10 +925,8 @@ function createTaskContext(taskDefinition, options) {
     };
 }
 function buildTaskEnv(baseEnv, options) {
-    const resolvedEnv = resolveEnvDefinitions(options.envDefinitions ?? {}, baseEnv, options.taskId);
-    return {
-        ...baseEnv,
-        ...resolvedEnv,
+    const { resolved: resolvedEnv, secretValues } = resolveEnvDefinitions(options.envDefinitions ?? {}, baseEnv, options.taskId);
+    const contextEnv = {
         ASYNC_PIPELINE_ROOT_DIR: options.rootCwd,
         ASYNC_PIPELINE_CANDIDATE_DIR: options.candidate.dir,
         ASYNC_PIPELINE_CANDIDATE_FINGERPRINT: options.candidate.fingerprint,
@@ -607,9 +935,19 @@ function buildTaskEnv(baseEnv, options) {
         ASYNC_PIPELINE_SOURCE_REF: options.source?.ref,
         ASYNC_PIPELINE_SOURCE_COMMIT: options.source?.commit
     };
+    return {
+        env: {
+            ...baseEnv,
+            ...resolvedEnv,
+            ...contextEnv
+        },
+        secretValues,
+        definedKeys: [...Object.keys(resolvedEnv), ...Object.keys(contextEnv), "CI"]
+    };
 }
 function resolveEnvDefinitions(definitions, baseEnv, taskId = "unknown") {
     const resolved = {};
+    const secretValues = [];
     for (const [key, value] of Object.entries(definitions)) {
         if (typeof value === "string") {
             resolved[key] = value;
@@ -621,6 +959,7 @@ function resolveEnvDefinitions(definitions, baseEnv, taskId = "unknown") {
                 throw new Error(`Required secret "${value.name}" for env "${key}" is not available for task "${taskId}".`);
             }
             resolved[key] = secretValue;
+            secretValues.push(secretValue);
             continue;
         }
         if (value.kind === "async-pipeline.env.var") {
@@ -641,7 +980,7 @@ function resolveEnvDefinitions(definitions, baseEnv, taskId = "unknown") {
             continue;
         }
     }
-    return resolved;
+    return { resolved, secretValues };
 }
 function isShellCommand(step) {
     return typeof step !== "function" && step.kind === "shell";
@@ -731,52 +1070,215 @@ async function runFunctionStep(step, context, timeoutMs) {
             clearTimeout(timeout);
     }
 }
+// Track live task processes so terminal signals terminate the whole run.
+// detached children live in their own process groups and would otherwise
+// survive Ctrl-C on the CLI.
+const activeKillers = new Set();
+const installedSignalForwarders = new Set();
+let shutdownState = null;
+const SHUTDOWN_ESCALATE_DELAY_MS = 500;
+const SHUTDOWN_EXIT_DEADLINE_MS = 10_000;
+/**
+ * Abort the run: terminate every live task process group (SIGTERM-style
+ * signal first, SIGKILL after a grace period), refuse to start new task
+ * processes, and hard-exit if the run has not finalized its execution
+ * record by the deadline. Idempotent; the first caller wins.
+ */
+export function beginShutdown(signal, exitCode) {
+    if (shutdownState)
+        return;
+    shutdownState = { signal, exitCode };
+    for (const kill of activeKillers)
+        kill(signal);
+    const escalate = setTimeout(() => {
+        for (const kill of activeKillers)
+            kill("SIGKILL");
+    }, SHUTDOWN_ESCALATE_DELAY_MS);
+    escalate.unref();
+    const deadline = setTimeout(() => process.exit(exitCode), SHUTDOWN_EXIT_DEADLINE_MS);
+    deadline.unref();
+}
+/** Exit code requested by an in-progress shutdown, if any. */
+export function shutdownExitCode() {
+    return shutdownState ? shutdownState.exitCode : null;
+}
+function ensureSignalForwarding() {
+    for (const signal of ["SIGINT", "SIGTERM"]) {
+        if (installedSignalForwarders.has(signal))
+            continue;
+        installedSignalForwarders.add(signal);
+        process.once(signal, () => {
+            // 128 + signal number, the conventional interrupted-exit status.
+            const exitCode = signal === "SIGINT" ? 130 : 143;
+            beginShutdown(signal, exitCode);
+            process.exitCode = exitCode;
+            // Stay alive so the dead tasks surface as failures and the execution
+            // record is finalized instead of being left "running". A second
+            // signal or the shutdown deadline exits immediately.
+            process.once(signal, () => process.exit(exitCode));
+        });
+    }
+}
+const DEFAULT_MAX_LOG_BYTES = 8 * 1024 * 1024;
+function resolveMaxLogBytes(env) {
+    const raw = env.ASYNC_PIPELINE_MAX_LOG_BYTES ?? process.env.ASYNC_PIPELINE_MAX_LOG_BYTES;
+    if (raw === undefined || raw === "")
+        return DEFAULT_MAX_LOG_BYTES;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed) || parsed < 0)
+        return DEFAULT_MAX_LOG_BYTES;
+    return parsed === 0 ? Number.POSITIVE_INFINITY : Math.max(parsed, 4096);
+}
+/** Keeps the byte-accurate tail of a stream bounded so huge task output cannot exhaust memory. */
+function cappedBuffer(maxBytes) {
+    const chunks = [];
+    let byteLength = 0;
+    let dropped = 0;
+    return {
+        append(chunk) {
+            const buffer = Buffer.from(chunk, "utf8");
+            chunks.push(buffer);
+            byteLength += buffer.byteLength;
+            while (byteLength > maxBytes) {
+                const head = chunks[0];
+                if (!head)
+                    break;
+                const excess = byteLength - maxBytes;
+                if (head.byteLength <= excess) {
+                    chunks.shift();
+                    byteLength -= head.byteLength;
+                    dropped += head.byteLength;
+                }
+                else {
+                    chunks[0] = head.subarray(excess);
+                    byteLength -= excess;
+                    dropped += excess;
+                }
+            }
+        },
+        read() {
+            const text = Buffer.concat(chunks).toString("utf8");
+            if (dropped === 0)
+                return text;
+            return `[async-pipeline] output truncated: dropped ${dropped} leading bytes (ASYNC_PIPELINE_MAX_LOG_BYTES).\n${text}`;
+        }
+    };
+}
 function runProcess(command, options) {
     return new Promise((resolve) => {
+        if (shutdownState) {
+            // The run is shutting down (signal or closed output pipe): fail fast
+            // instead of spawning processes that would immediately be killed.
+            resolve({ code: 1, stdout: "", stderr: `[interrupted] Run is shutting down (${shutdownState.signal}); not starting: ${options.label ?? command}\n` });
+            return;
+        }
+        // detached puts the shell in its own process group on POSIX so a timeout
+        // can terminate the whole tree, not only the wrapping shell.
+        const detached = process.platform !== "win32";
         const child = spawn(command, {
             cwd: options.cwd,
             env: options.env,
             shell: true,
+            detached,
             stdio: ["ignore", "pipe", "pipe"]
         });
-        let stdout = "";
-        let stderr = "";
+        const maxLogBytes = resolveMaxLogBytes(options.env);
+        const stdout = cappedBuffer(maxLogBytes);
+        const stderr = cappedBuffer(maxLogBytes);
         let timedOut = false;
         let timeout;
         let forceKillTimeout;
+        const redactValues = options.redactValues ?? [];
+        const echoStdout = createEchoWriter(process.stdout, options.label, redactValues);
+        const echoStderr = createEchoWriter(process.stderr, options.label, redactValues);
+        const killTree = (signal) => {
+            if (detached && child.pid) {
+                try {
+                    process.kill(-child.pid, signal);
+                    return;
+                }
+                catch {
+                    // Fall through to killing the direct child.
+                }
+            }
+            child.kill(signal);
+        };
+        activeKillers.add(killTree);
+        ensureSignalForwarding();
         if (options.timeoutMs) {
             timeout = setTimeout(() => {
                 timedOut = true;
-                child.kill("SIGTERM");
-                forceKillTimeout = setTimeout(() => child.kill("SIGKILL"), 500);
+                killTree("SIGTERM");
+                forceKillTimeout = setTimeout(() => killTree("SIGKILL"), 500);
             }, options.timeoutMs);
         }
         child.stdout.setEncoding("utf8");
         child.stderr.setEncoding("utf8");
         child.stdout.on("data", (chunk) => {
-            stdout += chunk;
+            stdout.append(chunk);
             if (options.echo !== false)
-                process.stdout.write(chunk);
+                echoStdout.write(chunk);
         });
         child.stderr.on("data", (chunk) => {
-            stderr += chunk;
+            stderr.append(chunk);
             if (options.echo !== false)
-                process.stderr.write(chunk);
+                echoStderr.write(chunk);
         });
         child.on("close", (code) => {
+            activeKillers.delete(killTree);
             if (timeout)
                 clearTimeout(timeout);
             if (forceKillTimeout)
                 clearTimeout(forceKillTimeout);
+            if (options.echo !== false) {
+                echoStdout.flush();
+                echoStderr.flush();
+            }
+            const finalStdout = redactKnownValues(stdout.read(), redactValues);
+            const finalStderr = redactKnownValues(stderr.read(), redactValues);
             if (timedOut) {
                 const timeoutMessage = `[timeout] Command timed out after ${options.timeoutMs}ms.\n`;
-                resolve({ code: 124, stdout, stderr: `${stderr}${timeoutMessage}`, timedOut: true });
+                resolve({ code: 124, stdout: finalStdout, stderr: `${finalStderr}${timeoutMessage}`, timedOut: true });
                 return;
             }
-            resolve({ code: code ?? 1, stdout, stderr });
+            resolve({ code: code ?? 1, stdout: finalStdout, stderr: finalStderr });
         });
     });
 }
+function createEchoWriter(stream, label, redactValues) {
+    let buffered = "";
+    const prefix = label ? `[${label}] ` : "";
+    const writeLine = (line) => {
+        stream.write(`${prefix}${redactKnownValues(line, redactValues)}\n`);
+    };
+    return {
+        write(chunk) {
+            buffered += chunk;
+            const lastNewline = buffered.lastIndexOf("\n");
+            if (lastNewline < 0)
+                return;
+            for (const line of buffered.slice(0, lastNewline).split("\n"))
+                writeLine(line);
+            buffered = buffered.slice(lastNewline + 1);
+        },
+        flush() {
+            if (!buffered)
+                return;
+            writeLine(buffered);
+            buffered = "";
+        }
+    };
+}
+const MIN_REDACTED_VALUE_LENGTH = 4;
+function redactKnownValues(output, values) {
+    let redacted = output;
+    for (const value of [...new Set(values)].sort((left, right) => right.length - left.length)) {
+        if (!value || value.length < MIN_REDACTED_VALUE_LENGTH)
+            continue;
+        redacted = redacted.split(value).join("[redacted]");
+    }
+    return redacted;
+}
 function matchingAction(policy, argv) {
     for (const rule of policy.rules) {
         if (matchesCommandRule(rule, argv))
@@ -806,11 +1308,19 @@ function commandStatus(action) {
         return "approval-required";
     return "allowed";
 }
-async function runCommandAction(action, next) {
+async function runCommandAction(action, invocation, next) {
     if (action.kind === "async-pipeline.command.allow")
         return next();
-    if (action.kind === "async-pipeline.command.requireEnvironment")
-        return next();
+    if (action.kind === "async-pipeline.command.requireEnvironment") {
+        const current = invocation.env.ASYNC_PIPELINE_ENVIRONMENT;
+        if (current === action.name)
+            return next();
+        return {
+            code: 1,
+            stdout: "",
+            stderr: `Command requires environment "${action.name}" (current: ${current ? `"${current}"` : "unset"}). Set ASYNC_PIPELINE_ENVIRONMENT to allow it.\n`
+        };
+    }
     if (action.kind === "async-pipeline.command.mock") {
         return {
             code: action.code ?? 0,