@async/pipeline 0.1.5 → 0.2.3

package/dist/internal/node/cli.js

@@ -1,38 +1,44 @@
 #!/usr/bin/env node
-import { existsSync } from "node:fs";
-import { basename, resolve } from "node:path";
+import { existsSync, realpathSync } from "node:fs";
+import { readFile, readdir, rm } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { buildGraph, composePipelines, tasksForJob } from "../core/index.js";
 import { runDoctor } from "./doctor.js";
 import { checkGitHubWorkflow, jobsForGitHubEvent, readGitHubEventContext, renderGitHubWorkflow, writeGitHubWorkflow } from "./github.js";
 import { loadPipeline } from "./loader.js";
-import { commandProxy, dockerWorkspace, hostWorkspace, limaWorkspace, runJob, runSingleTask } from "./runner.js";
-import { createStore } from "./store.js";
+import { beginShutdown, commandProxy, planJob, runJob, runSingleTask, shutdownExitCode } from "./runner.js";
+import { runMcpServer } from "./mcp.js";
+import { computeTaskInputManifest, createStore, diffInputManifests, pruneCacheEntries, readCacheInputManifest, readContextPacks, readTaskBaseline } from "./store.js";
 import { matrixForJob, readPipelineMetadata, resolveSources, sourceContext } from "./sources.js";
 import { checkTaskSync, describeTaskSync, renderTaskSync, writeTaskSync } from "./sync.js";
 export async function runPipelineCli(options) {
-    let stdout = "";
-    let stderr = "";
-    const writeStdout = (text) => {
-        stdout += text;
-    };
-    const writeStderr = (text) => {
-        stderr += text;
-    };
+    const sinkStdout = options.stdout ?? ((text) => { process.stdout.write(text); });
+    const sinkStderr = options.stderr ?? ((text) => { process.stderr.write(text); });
+    let streamedStdout = 0;
+    let streamedStderr = 0;
     const result = await runPipelineCliBuffered({
         args: options.args,
-        workspace: options.workspace ?? hostWorkspace(),
+        cwd: options.cwd ?? process.cwd(),
+        env: options.env ?? process.env,
+        commands: options.commands,
         program: options.program,
-        stdout: writeStdout,
-        stderr: writeStderr,
+        onStdout(text) {
+            streamedStdout += text.length;
+            sinkStdout(text);
+        },
+        onStderr(text) {
+            streamedStderr += text.length;
+            sinkStderr(text);
+        },
         applyCommandPolicy: true
     });
-    options.stdout?.(result.stdout);
-    options.stderr?.(result.stderr);
-    if (!options.stdout)
-        process.stdout.write(result.stdout);
-    if (!options.stderr)
-        process.stderr.write(result.stderr);
+    // Streamed text is always a prefix of the final result text; replaced output
+    // (command policy deny/mock, or errors) was never streamed, so flush the rest.
+    if (result.stdout.length > streamedStdout)
+        sinkStdout(result.stdout.slice(streamedStdout));
+    if (result.stderr.length > streamedStderr)
+        sinkStderr(result.stderr.slice(streamedStderr));
     return result;
 }
 async function runPipelineCliBuffered(options) {
@@ -40,18 +46,20 @@ async function runPipelineCliBuffered(options) {
         const parsed = parseGlobalOptions(options.args);
         const [commandName, ...args] = parsed.args;
         const program = options.program ?? programName();
-        const cwd = options.workspace.cwd;
+        const cwd = options.cwd;
         const configPath = findPipelineConfig(cwd);
         let stdout = "";
         let stderr = "";
         const out = (text) => {
             stdout += text;
+            options.onStdout?.(text);
         };
         const err = (text) => {
             stderr += text;
+            options.onStderr?.(text);
         };
         if (commandName === "doctor") {
-            const checks = await runDoctor();
+            const checks = await runDoctor(cwd);
             for (const check of checks)
                 out(`${check.status.toUpperCase()} ${check.name}: ${check.message}\n`);
             return { code: checks.some((check) => check.status === "fail") ? 1 : 0, stdout, stderr };
@@ -64,25 +72,36 @@ async function runPipelineCliBuffered(options) {
             throw new Error(`No pipeline.ts, pipeline.mjs, or pipeline.js found in ${cwd}.`);
         }
         const pipeline = await loadPipeline(configPath);
-        const workspace = selectWorkspace(parsed.workspaceId, pipeline, options.workspace);
-        if (options.applyCommandPolicy && workspace.commands) {
-            return workspace.commands.run({
+        const configDir = dirname(configPath);
+        // Validate the sandbox id before the command policy can mock the
+        // invocation, so typos fail loudly even under mocked CLI commands.
+        if (parsed.sandboxId && parsed.sandboxId !== "host" && !pipeline.sandboxes[parsed.sandboxId]) {
+            throw new Error(`Unknown sandbox "${parsed.sandboxId}". Declare it under \`sandboxes\` in the pipeline config.`);
+        }
+        const commands = options.commands ?? (pipeline.commands ? commandProxy(pipeline.commands) : undefined);
+        if (options.applyCommandPolicy && commands) {
+            return commands.run({
                 argv: ["async-pipeline", ...options.args],
-                cwd: workspace.cwd,
-                env: workspace.env
+                cwd: configDir,
+                env: options.env
             }, () => runPipelineCliBuffered({
                 ...options,
                 args: options.args,
-                workspace,
+                cwd: configDir,
+                commands,
                 applyCommandPolicy: false
             }));
         }
         const context = {
             concurrency: parsed.concurrency,
-            cwd,
+            force: parsed.force,
+            dryRun: parsed.dryRun,
+            cwd: configDir,
             configPath,
             pipeline,
-            workspace,
+            env: options.env,
+            commands,
+            sandboxId: parsed.sandboxId,
             stdout: out,
             stderr: err
         };
@@ -119,17 +138,26 @@ async function dispatchCommand(commandName, args, context, program) {
             return 0;
         }
         if (subcommand === "run") {
-            const eventContext = await readGitHubEventContext(context.workspace.env);
-            const jobs = jobsForGitHubEvent(context.pipeline, eventContext);
+            const explicitJobs = collectFlagValues(args.slice(1), "--job");
+            const eventContext = await readGitHubEventContext(context.env);
+            const jobs = explicitJobs.length > 0
+                ? explicitJobs.map((jobId) => {
+                    const selected = context.pipeline.jobs[jobId];
+                    if (!selected)
+                        throw new Error(`Unknown job "${jobId}".`);
+                    return selected;
+                })
+                : jobsForGitHubEvent(context.pipeline, eventContext);
             if (jobs.length === 0) {
-                context.stdout(`No pipeline jobs matched GitHub event "${eventContext.eventName}".\n`);
+                context.stdout(`No pipeline jobs matched GitHub event "${eventContext.eventName}". Jobs without a manual trigger need an explicit --job <id> on workflow_dispatch.\n`);
                 return 0;
             }
             let failed = false;
             for (const selectedJob of jobs) {
                 const graph = tasksForJob(context.pipeline, selectedJob.id);
                 context.stdout(`Running ${context.pipeline.name}:${selectedJob.id} (${graph.executionOrder.join(" -> ")})\n`);
-                const result = await runJob(context.pipeline, { id: selectedJob.id, mode: "ci", workspace: context.workspace, concurrency: context.concurrency });
+                const result = await runJob(context.pipeline, { id: selectedJob.id, mode: "ci", cwd: context.cwd, env: context.env, commands: context.commands, sandbox: context.sandboxId, concurrency: context.concurrency });
+                reportFailedTasks(context, result.tasks);
                 context.stdout(`Pipeline ${result.status}: ${result.id}\n`);
                 if (result.status !== "passed")
                     failed = true;
@@ -176,14 +204,85 @@ async function dispatchCommand(commandName, args, context, program) {
         throw new Error(`Unsupported graph format "${format}".`);
     }
     if (commandName === "explain") {
-        const taskId = args[0];
-        if (!taskId)
-            throw new Error(`Usage: ${program} explain <task>`);
         const store = virtualStore(context.cwd);
+        const formatIndex = args.indexOf("--format");
+        const explainFormat = formatIndex >= 0 ? args[formatIndex + 1] : "text";
+        if (explainFormat !== "text" && explainFormat !== "json")
+            throw new Error(`Unsupported explain format "${explainFormat}".`);
+        const runIndex = args.indexOf("--run");
+        if (runIndex >= 0) {
+            const runId = args[runIndex + 1];
+            if (!runId || runId.startsWith("--"))
+                throw new Error(`Usage: ${program} explain --run <run-id> [--format json]`);
+            const packs = await readContextPacks(store, runId);
+            if (explainFormat === "json") {
+                context.stdout(`${JSON.stringify(packs, null, 2)}\n`);
+                return 0;
+            }
+            if (packs.length === 0) {
+                context.stdout(`No context packs recorded for run ${runId}.\n`);
+                return 0;
+            }
+            for (const pack of packs) {
+                context.stdout(`Task ${pack.task} failed after ${pack.attempts} attempt${pack.attempts === 1 ? "" : "s"}: ${pack.error}\n`);
+                if ("baselineMissing" in pack.inputDiff) {
+                    context.stdout("  inputs: no passing baseline recorded\n");
+                }
+                else {
+                    const diff = pack.inputDiff;
+                    context.stdout(`  inputs vs last pass: ${diff.changed.length} changed, ${diff.added.length} added, ${diff.removed.length} removed\n`);
+                    for (const path of diff.changed)
+                        context.stdout(`    ~ ${path}\n`);
+                    for (const path of diff.added)
+                        context.stdout(`    + ${path}\n`);
+                    for (const path of diff.removed)
+                        context.stdout(`    - ${path}\n`);
+                }
+                if (pack.claims?.length)
+                    context.stdout(`  claims touched: ${pack.claims.join(", ")}\n`);
+                context.stdout(`  reproduce: ${pack.reproduce}\n`);
+            }
+            return 0;
+        }
+        const taskId = args[0];
+        if (!taskId || taskId.startsWith("--"))
+            throw new Error(`Usage: ${program} explain <task> [--diff-inputs] | explain --run <run-id>`);
         const explainPipeline = await loadAvailableSourceGraph(context.pipeline, context.cwd, store);
         const task = explainPipeline.tasks[taskId];
         if (!task)
             throw new Error(`Unknown task "${taskId}".`);
+        if (args.includes("--diff-inputs")) {
+            const baseline = await readTaskBaseline(store, taskId);
+            const baselineManifest = baseline ? await readCacheInputManifest(store, baseline.cacheKey) : null;
+            const current = await computeTaskInputManifest(explainPipeline, task, context.cwd);
+            if (!baseline || !baselineManifest) {
+                if (explainFormat === "json") {
+                    context.stdout(`${JSON.stringify({ task: taskId, baselineMissing: true, current }, null, 2)}\n`);
+                }
+                else {
+                    context.stdout(`No passing baseline recorded for task "${taskId}" (${Object.keys(current.files).length} current input file(s)). Run the task to record one.\n`);
+                }
+                return 0;
+            }
+            const diff = diffInputManifests(baselineManifest, current);
+            if (explainFormat === "json") {
+                context.stdout(`${JSON.stringify({ task: taskId, baselineCacheKey: baseline.cacheKey, baselineRecordedAt: baseline.recordedAt, ...diff }, null, 2)}\n`);
+                return 0;
+            }
+            const total = diff.changed.length + diff.added.length + diff.removed.length;
+            context.stdout(`Inputs for "${taskId}" vs last passing entry (recorded ${baseline.recordedAt}):\n`);
+            if (total === 0) {
+                context.stdout("  unchanged\n");
+                return 0;
+            }
+            for (const path of diff.changed)
+                context.stdout(`  ~ ${path}\n`);
+            for (const path of diff.added)
+                context.stdout(`  + ${path}\n`);
+            for (const path of diff.removed)
+                context.stdout(`  - ${path}\n`);
+            return 0;
+        }
         context.stdout(`${JSON.stringify(task, jsonReplacer, 2)}\n`);
         return 0;
     }
@@ -201,6 +300,19 @@ async function dispatchCommand(commandName, args, context, program) {
         context.stdout(`${JSON.stringify(metadata, jsonReplacer, 2)}\n`);
         return 0;
     }
+    if (commandName === "mcp") {
+        return runMcpServer({
+            pipeline: context.pipeline,
+            configPath: context.configPath,
+            cwd: context.cwd,
+            env: context.env,
+            store: virtualStore(context.cwd),
+            allowRun: args.includes("--allow-run"),
+            serverVersion: await ownPackageVersion(),
+            input: process.stdin,
+            write: (line) => context.stdout(`${line}\n`)
+        });
+    }
     if (commandName === "matrix") {
         const jobId = args[0];
         if (!jobId)
@@ -216,22 +328,168 @@ async function dispatchCommand(commandName, args, context, program) {
         const jobId = args[0];
         if (!jobId)
             throw new Error(`Usage: ${program} run <job>`);
+        const format = runOutputFormat(args, program);
         const graph = tasksForJob(context.pipeline, jobId);
-        context.stdout(`Running ${context.pipeline.name}:${jobId} (${graph.executionOrder.join(" -> ")})\n`);
-        const result = await runJob(context.pipeline, { id: jobId, mode: context.workspace.env.CI ? "ci" : "manual", workspace: context.workspace, concurrency: context.concurrency });
-        context.stdout(`Pipeline ${result.status}: ${result.id}\n`);
+        if (context.dryRun) {
+            return printDryRun(context, format, jobId);
+        }
+        if (format === "text")
+            context.stdout(`Running ${context.pipeline.name}:${jobId} (${graph.executionOrder.join(" -> ")})\n`);
+        const result = await runJob(context.pipeline, { id: jobId, mode: context.env.CI ? "ci" : "manual", cwd: context.cwd, env: context.env, commands: context.commands, sandbox: context.sandboxId, concurrency: context.concurrency, force: context.force, echo: format === "text" });
+        if (format === "json") {
+            context.stdout(`${JSON.stringify(result, null, 2)}\n`);
+        }
+        else {
+            reportFailedTasks(context, result.tasks);
+            context.stdout(`Pipeline ${result.status}: ${result.id}\n`);
+        }
+        await pruneRunsAfterRun(context);
         return result.status === "passed" ? 0 : 1;
     }
     if (commandName === "run-task") {
         const taskId = args[0];
         if (!taskId)
             throw new Error(`Usage: ${program} run-task <task>`);
-        const result = await runSingleTask(context.pipeline, taskId, { mode: context.workspace.env.CI ? "ci" : "manual", workspace: context.workspace, concurrency: context.concurrency });
-        context.stdout(`Task run ${result.status}: ${result.id}\n`);
+        const format = runOutputFormat(args, program);
+        if (context.dryRun) {
+            return printDryRun(context, format, undefined, taskId);
+        }
+        const result = await runSingleTask(context.pipeline, taskId, { mode: context.env.CI ? "ci" : "manual", cwd: context.cwd, env: context.env, commands: context.commands, sandbox: context.sandboxId, concurrency: context.concurrency, force: context.force, echo: format === "text" });
+        if (format === "json") {
+            context.stdout(`${JSON.stringify(result, null, 2)}\n`);
+        }
+        else {
+            reportFailedTasks(context, result.tasks);
+            context.stdout(`Task run ${result.status}: ${result.id}\n`);
+        }
+        await pruneRunsAfterRun(context);
         return result.status === "passed" ? 0 : 1;
     }
+    if (commandName === "cache") {
+        const subcommand = args[0];
+        if (subcommand === "clear") {
+            await rm(join(context.cwd, ".async", "cache", "tasks"), { recursive: true, force: true });
+            context.stdout("Cleared task cache.\n");
+            return 0;
+        }
+        throw new Error(`Unknown cache command "${subcommand ?? ""}". Use: ${program} cache clear`);
+    }
+    if (commandName === "gc") {
+        const keep = parsePositiveInteger(args, "--keep", 20);
+        const cacheDays = parsePositiveInteger(args, "--cache-days", 30);
+        const removed = await pruneRuns(context.cwd, keep);
+        const remaining = await countRuns(context.cwd);
+        const removedCacheEntries = await pruneCacheEntries(context.cwd, cacheDays);
+        context.stdout(`Removed ${removed} run record${removed === 1 ? "" : "s"}; kept ${remaining}.\n`);
+        context.stdout(cacheDays > 0
+            ? `Removed ${removedCacheEntries} cache entr${removedCacheEntries === 1 ? "y" : "ies"} unused for ${cacheDays}+ days.\n`
+            : "Cache pruning disabled (--cache-days 0).\n");
+        return 0;
+    }
     throw new Error(`Unknown command "${commandName}".`);
 }
+async function printDryRun(context, format, jobId, taskId) {
+    let pipeline = context.pipeline;
+    let id = jobId;
+    if (taskId !== undefined) {
+        id = `task:${taskId}`;
+        pipeline = {
+            ...pipeline,
+            jobs: { ...pipeline.jobs, [id]: { id, target: [taskId], trigger: [] } }
+        };
+    }
+    if (!id)
+        throw new Error("Dry run requires a job or task.");
+    const plan = await planJob(pipeline, { id, cwd: context.cwd, env: context.env, sandbox: context.sandboxId });
+    if (format === "json") {
+        context.stdout(`${JSON.stringify(plan, null, 2)}\n`);
+        return 0;
+    }
+    context.stdout(`Plan ${context.pipeline.name}:${jobId ?? taskId} (${plan.executionOrder.join(" -> ")})\n`);
+    for (const entry of plan.entries) {
+        const note = context.force && entry.predicted === "cached"
+            ? "run (cache ignored by --force)"
+            : entry.predicted;
+        context.stdout(`  ${entry.id}\t${note}${entry.reason ? `\t${entry.reason}` : ""}\n`);
+    }
+    context.stdout("Dry run: no tasks executed. Cached predictions do not verify restored output files.\n");
+    return 0;
+}
+function runOutputFormat(args, program) {
+    const formatIndex = args.indexOf("--format");
+    if (formatIndex < 0)
+        return "text";
+    const format = args[formatIndex + 1];
+    if (format !== "text" && format !== "json") {
+        throw new Error(`Usage: ${program} run <job> --format text|json`);
+    }
+    return format;
+}
+const DEFAULT_KEPT_RUNS = 50;
+async function pruneRunsAfterRun(context) {
+    const raw = context.env.ASYNC_PIPELINE_KEEP_RUNS;
+    let keep = DEFAULT_KEPT_RUNS;
+    if (raw !== undefined && raw !== "") {
+        const parsed = Number(raw);
+        if (!Number.isInteger(parsed) || parsed < 0)
+            return;
+        if (parsed === 0)
+            return; // 0 disables automatic pruning.
+        keep = parsed;
+    }
+    await pruneRuns(context.cwd, keep);
+}
+async function pruneRuns(cwd, keep) {
+    const runsDir = join(cwd, ".async", "runs");
+    let runIds = [];
+    try {
+        runIds = (await readdir(runsDir, { withFileTypes: true }))
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort((left, right) => right.localeCompare(left));
+    }
+    catch {
+        return 0;
+    }
+    const stale = runIds.slice(keep);
+    for (const runId of stale) {
+        await rm(join(runsDir, runId), { recursive: true, force: true });
+    }
+    return stale.length;
+}
+async function countRuns(cwd) {
+    try {
+        const entries = await readdir(join(cwd, ".async", "runs"), { withFileTypes: true });
+        return entries.filter((entry) => entry.isDirectory()).length;
+    }
+    catch {
+        return 0;
+    }
+}
+function collectFlagValues(args, flag) {
+    const values = [];
+    for (let index = 0; index < args.length; index += 1) {
+        if (args[index] !== flag)
+            continue;
+        const value = args[index + 1];
+        if (!value)
+            throw new Error(`${flag} requires a value.`);
+        values.push(value);
+        index += 1;
+    }
+    return values;
+}
+function parsePositiveInteger(args, flag, fallback) {
+    const index = args.indexOf(flag);
+    if (index < 0)
+        return fallback;
+    const raw = args[index + 1];
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < 0) {
+        throw new Error(`${flag} requires a non-negative integer.`);
+    }
+    return value;
+}
 async function handleSourcesCommand(args, context) {
     const subcommand = args[0] ?? "list";
     if (subcommand === "list") {
@@ -256,11 +514,13 @@ async function handleSourcesCommand(args, context) {
 }
 function printHelp(program) {
     return `Usage:
-  ${program} run <job> [--workspace <id>] [--concurrency <n>]
-  ${program} run-task <task> [--workspace <id>] [--concurrency <n>]
+  ${program} run <job> [--sandbox <id>] [--concurrency <n>] [--force] [--dry-run] [--format text|json]
+  ${program} run-task <task> [--sandbox <id>] [--concurrency <n>] [--force] [--dry-run] [--format text|json]
   ${program} list
   ${program} graph --format json|dot
-  ${program} explain <task>
+  ${program} explain <task> [--diff-inputs] [--format text|json]
+  ${program} explain --run <run-id> [--format text|json]
+  ${program} mcp [--allow-run]
   ${program} sources list
   ${program} sources sync
   ${program} metadata --format json [--include-sources]
@@ -276,7 +536,9 @@ function printHelp(program) {
   ${program} sync tasks check
   ${program} github generate [--workflow <path>] [--lock <path>]
   ${program} github check [--workflow <path>] [--lock <path>]
-  ${program} github run [--workspace <id>] [--concurrency <n>]
+  ${program} github run [--job <id>] [--sandbox <id>] [--concurrency <n>]
+  ${program} cache clear
+  ${program} gc [--keep <n>] [--cache-days <n>]
   ${program} doctor\n`;
 }
 async function handleSyncCommand(args, context) {
@@ -405,15 +667,25 @@ async function handleSyncTasksCommand(subcommand, context, options) {
 function parseGlobalOptions(args) {
     const rest = [];
     let concurrency;
-    let workspaceId;
+    let sandboxId;
+    let force = false;
+    let dryRun = false;
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (arg === undefined)
             continue;
-        if (arg === "--workspace") {
-            workspaceId = args[index + 1];
-            if (!workspaceId)
-                throw new Error("Usage: async-pipeline <command> --workspace <id>");
+        if (arg === "--force") {
+            force = true;
+            continue;
+        }
+        if (arg === "--dry-run") {
+            dryRun = true;
+            continue;
+        }
+        if (arg === "--sandbox") {
+            sandboxId = args[index + 1];
+            if (!sandboxId)
+                throw new Error("Usage: async-pipeline <command> --sandbox <id>");
             index += 1;
             continue;
         }
@@ -427,52 +699,56 @@ function parseGlobalOptions(args) {
         }
         rest.push(arg);
     }
-    return { args: rest, concurrency, workspaceId };
-}
-function selectWorkspace(workspaceId, pipeline, base) {
-    const commands = base.commands ?? (pipeline.commands ? commandProxy(pipeline.commands) : undefined);
-    if (!workspaceId || workspaceId === "host") {
-        return { ...base, commands };
-    }
-    const definition = pipeline.workspaces[workspaceId];
-    if (!definition)
-        throw new Error(`Unknown workspace "${workspaceId}".`);
-    return createWorkspaceFromDefinition(definition, base, commands);
-}
-function createWorkspaceFromDefinition(definition, base, commands) {
-    if (definition.kind === "host")
-        return hostWorkspace({ cwd: base.cwd, env: base.env, commands });
-    if (definition.kind === "lima")
-        return limaWorkspace({ cwd: base.cwd, env: base.env, vm: definition.vm, commands });
-    if (definition.kind === "docker") {
-        return dockerWorkspace({
-            cwd: base.cwd,
-            env: base.env,
-            image: definition.image,
-            workdir: definition.workdir,
-            volumes: definition.volumes,
-            commands
-        });
-    }
-    throw new Error(`Workspace kind "${definition.kind}" is declared but not executable in this tranche.`);
+    return { args: rest, concurrency, sandboxId, force, dryRun };
 }
 function findPipelineConfig(cwd) {
-    for (const fileName of ["pipeline.ts", "pipeline.mjs", "pipeline.js"]) {
-        const configPath = resolve(cwd, fileName);
-        if (existsSync(configPath))
-            return configPath;
+    let current = resolve(cwd);
+    for (;;) {
+        for (const fileName of ["pipeline.ts", "pipeline.mjs", "pipeline.js"]) {
+            const configPath = join(current, fileName);
+            if (existsSync(configPath))
+                return configPath;
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
     }
-    return null;
 }
 function programName() {
     const name = basename(process.argv[1] ?? "async-pipeline");
     return name === "cli.js" ? "async-pipeline" : name;
 }
+// Failed runs must name the reason on the terminal, not only inside
+// .async/runs/<id>/execution.json. Task output was already streamed; this
+// repeats the recorded per-task error next to the final status line.
+function reportFailedTasks(context, tasks) {
+    for (const failed of tasks.filter((task) => task.status === "failed")) {
+        context.stderr(`Task ${failed.id} failed${failed.error ? `: ${failed.error}` : ""}\n`);
+    }
+}
 function jsonReplacer(_key, value) {
     if (typeof value === "function")
         return "[function]";
     return value;
 }
+/**
+ * The published package's version for MCP serverInfo, falling back to this
+ * internal package's own. Best-effort: identity metadata, not behavior.
+ */
+async function ownPackageVersion() {
+    for (const candidate of ["../../pipeline/package.json", "../package.json"]) {
+        try {
+            const manifest = JSON.parse(await readFile(new URL(candidate, import.meta.url), "utf8"));
+            if (typeof manifest.version === "string")
+                return manifest.version;
+        }
+        catch {
+            // Try the next candidate.
+        }
+    }
+    return undefined;
+}
 function githubGenerationPaths(args) {
     const workflowIndex = args.indexOf("--workflow");
     const lockIndex = args.indexOf("--lock");
@@ -506,12 +782,43 @@ function virtualStore(root) {
         sourcesDir: resolve(root, ".async", "sources")
     };
 }
-if (process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url) {
-    runPipelineCli({ args: process.argv.slice(2) }).then((result) => {
-        process.exitCode = result.code;
+export function runCliMain() {
+    // When the downstream pipe closes (e.g. `async-pipeline run x | head`),
+    // terminate running task process groups, let the run finalize its
+    // execution record, and exit 141 (128 + SIGPIPE) instead of crashing
+    // with an unhandled EPIPE or orphaning task processes.
+    const shutdownOnEpipe = (error) => {
+        if (error.code === "EPIPE") {
+            beginShutdown("SIGTERM", 141);
+            return;
+        }
+        throw error;
+    };
+    process.stdout.on("error", shutdownOnEpipe);
+    process.stderr.on("error", shutdownOnEpipe);
+    return runPipelineCli({ args: process.argv.slice(2) }).then((result) => {
+        process.exitCode = shutdownExitCode() ?? result.code;
     }).catch((error) => {
         console.error(error instanceof Error ? error.message : String(error));
-        process.exitCode = 1;
+        process.exitCode = shutdownExitCode() ?? 1;
     });
 }
+// True only when this module is the executed entrypoint. The public package
+// bin (`@async/pipeline` dist/cli.js) is a different wrapper module, so it
+// cannot rely on this guard; it imports and calls runCliMain() explicitly.
+// Realpath the argv path so bin shims and node_modules symlinks still count
+// as direct execution of this file.
+function isCliEntrypoint(argvPath) {
+    if (!argvPath)
+        return false;
+    try {
+        return pathToFileURL(realpathSync(argvPath)).href === import.meta.url;
+    }
+    catch {
+        return false;
+    }
+}
+if (isCliEntrypoint(process.argv[1])) {
+    void runCliMain();
+}
 //# sourceMappingURL=cli.js.map