@sanity/ailf 2.9.0 → 3.1.0

package/dist/artifact-capture/parallel-emit.js

@@ -0,0 +1,84 @@
+/**
+ * parallel-emit.ts — W0056 prototype A (client-side parallelism).
+ *
+ * Bounded-concurrency helper for fanning out artifact emits. The baseline
+ * measurement (see `docs/design-docs/artifact-upload-throughput.md`) shows
+ * producer loops call `await writer.emit(...)` serially, and per-artifact
+ * wall clock is dominated by GCS response latency. A simple `p-limit(N)`
+ * turns that into a batched-parallel flow against the existing writers.
+ *
+ * Gated on `AILF_PARALLEL_UPLOAD`:
+ *   - unset → use the per-writer default set at composition time.
+ *   - "0" → forced serial (override when default-on is undesirable).
+ *   - "1" → parallel, default concurrency 8.
+ *   - "<N>" (N > 1 integer) → parallel with concurrency N.
+ *
+ * The per-writer default is set by the composition root via
+ * `setDefaultUploadConcurrency`. Writers with measured safe parallelism
+ * (GCS direct) set 8; writers still on serial (API Gateway, until the
+ * batching rollout completes) leave it at the module default of 1.
+ */
+const DEFAULT_CONCURRENCY = 8;
+let moduleDefault = 1;
+/**
+ * Set the default concurrency used when `AILF_PARALLEL_UPLOAD` is unset.
+ * Composition root calls this once per run based on the selected remote
+ * writer. Tests reset by passing 1.
+ */
+export function setDefaultUploadConcurrency(n) {
+    moduleDefault = n >= 1 ? n : 1;
+}
+/** Exposed for tests — returns the current module default. */
+export function getDefaultUploadConcurrency() {
+    return moduleDefault;
+}
+/**
+ * Resolve the configured concurrency. Returns 1 (serial) when parallelism is
+ * explicitly disabled or the env value is invalid; otherwise returns the
+ * per-writer module default when `AILF_PARALLEL_UPLOAD` is unset.
+ */
+export function resolveUploadConcurrency() {
+    const raw = process.env.AILF_PARALLEL_UPLOAD ?? "";
+    if (raw === "0")
+        return 1;
+    if (raw === "")
+        return moduleDefault;
+    if (raw === "1")
+        return DEFAULT_CONCURRENCY;
+    const parsed = Number.parseInt(raw, 10);
+    if (Number.isFinite(parsed) && parsed > 1)
+        return parsed;
+    return moduleDefault;
+}
+/**
+ * Run `fn` against every item with at most `concurrency` active at once.
+ * Preserves input order in the result array. Rejections propagate — callers
+ * with non-blocking semantics should catch inside `fn`.
+ *
+ * When `concurrency <= 1`, runs strictly serially (drop-in equivalent of a
+ * `for … await` loop).
+ */
+export async function parallelMap(items, concurrency, fn) {
+    if (items.length === 0)
+        return [];
+    if (concurrency <= 1) {
+        const out = [];
+        for (let i = 0; i < items.length; i++) {
+            out.push(await fn(items[i], i));
+        }
+        return out;
+    }
+    const results = new Array(items.length);
+    let cursor = 0;
+    async function worker() {
+        while (true) {
+            const i = cursor++;
+            if (i >= items.length)
+                return;
+            results[i] = await fn(items[i], i);
+        }
+    }
+    const width = Math.min(concurrency, items.length);
+    await Promise.all(Array.from({ length: width }, () => worker()));
+    return results;
+}

package/dist/artifact-capture/redact-artifact.d.ts

@@ -1,9 +1,7 @@
 /**
- * Artifact redaction — strips sensitive data from captured artifacts before
- * they are written to disk.
- *
- * Applied during FilesystemArtifactCollector.flush() so that secrets
- * (resolved env vars, auth headers, session cookies) never reach storage.
+ * Artifact redaction — strips sensitive data from written artifacts so that
+ * secrets (resolved env vars, auth headers, session cookies) never reach
+ * local or remote storage.
  *
  * Two-layer approach:
  * 1. **Header stripping** — known-sensitive HTTP header keys are replaced

package/dist/artifact-capture/redact-artifact.js

@@ -1,9 +1,7 @@
 /**
- * Artifact redaction — strips sensitive data from captured artifacts before
- * they are written to disk.
- *
- * Applied during FilesystemArtifactCollector.flush() so that secrets
- * (resolved env vars, auth headers, session cookies) never reach storage.
+ * Artifact redaction — strips sensitive data from written artifacts so that
+ * secrets (resolved env vars, auth headers, session cookies) never reach
+ * local or remote storage.
  *
  * Two-layer approach:
  * 1. **Header stripping** — known-sensitive HTTP header keys are replaced

package/dist/artifact-capture/upload-metrics.d.ts

@@ -0,0 +1,62 @@
+/**
+ * UploadMetrics — spike instrumentation for W0056 (faster artifact upload).
+ *
+ * Captures per-operation timing on the artifact-upload path so the spike has
+ * a measured baseline: artifact count, total bytes, wall-clock, and the
+ * sign-RTT vs. PUT split. Gated on `AILF_UPLOAD_METRICS=1` in the composition
+ * root — a no-op when off.
+ *
+ * Design:
+ * - `UploadMetricsSink` is the narrow interface that writers depend on.
+ * - `UploadMetrics` is the in-process implementation that buffers events
+ *   and emits both a stderr summary table and an NDJSON detail file.
+ * - `summarize()` is called by `InstrumentedArtifactWriter` once, after
+ *   `writeManifest` succeeds (the natural end-of-run signal).
+ *
+ * This file is a spike deliverable — the API is intentionally ad hoc and
+ * may be promoted to `packages/core/src/ports/` if we ship anything.
+ */
+import type { Logger } from "../_vendor/ailf-core/index.d.ts";
+export type UploadPhase = "sign" | "put" | "compose" | "emit" | "ndjson-part" | "manifest";
+export interface UploadMetricEvent {
+    /** ISO timestamp the event was recorded. */
+    ts: string;
+    /** Phase being measured — writers record `sign`/`put`/`compose` at the call site; the decorator records `emit`/`ndjson-part`/`manifest` end-to-end. */
+    phase: UploadPhase;
+    /** Writer class that produced the event (e.g. "ApiGatewayArtifactWriter"). */
+    writer: string;
+    /** Artifact type (or `"manifest"`). */
+    type: string;
+    /** Wall-clock for the phase, in milliseconds. */
+    ms: number;
+    /** Body size in bytes, when applicable. */
+    bytes?: number;
+    /** True when the underlying call resolved without throwing / without a non-2xx response. */
+    success: boolean;
+}
+export interface UploadMetricsSink {
+    record(event: Omit<UploadMetricEvent, "ts">): void;
+}
+/**
+ * No-op sink — writers default to this when metrics are off, so the
+ * instrumentation call sites remain uniform whether or not the collector is
+ * active.
+ */
+export declare const NO_OP_UPLOAD_METRICS: UploadMetricsSink;
+export interface UploadMetricsOptions {
+    /** Logger used for the summary table. */
+    logger: Logger;
+    /** Absolute path where the NDJSON detail file is written. Skipped when undefined. */
+    detailFile?: string;
+}
+export declare class UploadMetrics implements UploadMetricsSink {
+    private readonly options;
+    private readonly events;
+    private summarized;
+    constructor(options: UploadMetricsOptions);
+    record(event: Omit<UploadMetricEvent, "ts">): void;
+    summarize(): Promise<void>;
+    /** Exposed for tests — returns a copy. */
+    snapshot(): readonly UploadMetricEvent[];
+}
+export declare function buildSummaryTable(events: readonly UploadMetricEvent[]): string;

package/dist/artifact-capture/upload-metrics.js

@@ -0,0 +1,125 @@
+/**
+ * UploadMetrics — spike instrumentation for W0056 (faster artifact upload).
+ *
+ * Captures per-operation timing on the artifact-upload path so the spike has
+ * a measured baseline: artifact count, total bytes, wall-clock, and the
+ * sign-RTT vs. PUT split. Gated on `AILF_UPLOAD_METRICS=1` in the composition
+ * root — a no-op when off.
+ *
+ * Design:
+ * - `UploadMetricsSink` is the narrow interface that writers depend on.
+ * - `UploadMetrics` is the in-process implementation that buffers events
+ *   and emits both a stderr summary table and an NDJSON detail file.
+ * - `summarize()` is called by `InstrumentedArtifactWriter` once, after
+ *   `writeManifest` succeeds (the natural end-of-run signal).
+ *
+ * This file is a spike deliverable — the API is intentionally ad hoc and
+ * may be promoted to `packages/core/src/ports/` if we ship anything.
+ */
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+/**
+ * No-op sink — writers default to this when metrics are off, so the
+ * instrumentation call sites remain uniform whether or not the collector is
+ * active.
+ */
+export const NO_OP_UPLOAD_METRICS = {
+    record() { },
+};
+export class UploadMetrics {
+    options;
+    events = [];
+    summarized = false;
+    constructor(options) {
+        this.options = options;
+    }
+    record(event) {
+        this.events.push({ ...event, ts: new Date().toISOString() });
+    }
+    async summarize() {
+        if (this.summarized)
+            return;
+        this.summarized = true;
+        const { logger, detailFile } = this.options;
+        if (this.events.length === 0) {
+            logger.info("[upload-metrics] no events recorded");
+            return;
+        }
+        const table = buildSummaryTable(this.events);
+        logger.info(`[upload-metrics] ${this.events.length} events recorded\n${table}`);
+        if (detailFile) {
+            try {
+                await mkdir(dirname(detailFile), { recursive: true });
+                const body = this.events.map((e) => JSON.stringify(e)).join("\n") + "\n";
+                await writeFile(detailFile, body, "utf-8");
+                logger.info(`[upload-metrics] detail written to ${detailFile}`);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                logger.warn(`[upload-metrics] failed to write detail file "${detailFile}": ${message}`);
+            }
+        }
+    }
+    /** Exposed for tests — returns a copy. */
+    snapshot() {
+        return [...this.events];
+    }
+}
+export function buildSummaryTable(events) {
+    const byKey = new Map();
+    for (const ev of events) {
+        const key = `${ev.phase}\t${ev.writer}`;
+        let bucket = byKey.get(key);
+        if (!bucket) {
+            bucket = [];
+            byKey.set(key, bucket);
+        }
+        bucket.push(ev);
+    }
+    const rows = [];
+    for (const [key, bucket] of byKey) {
+        const phase = key.split("\t").join(" · ");
+        const durations = bucket.map((e) => e.ms).sort((a, b) => a - b);
+        const totalMs = durations.reduce((sum, ms) => sum + ms, 0);
+        const totalBytes = bucket.reduce((sum, e) => sum + (e.bytes ?? 0), 0);
+        const failures = bucket.filter((e) => !e.success).length;
+        rows.push({
+            phase,
+            count: bucket.length,
+            failures,
+            totalMs,
+            totalBytes,
+            p50: percentile(durations, 0.5),
+            p95: percentile(durations, 0.95),
+            max: durations[durations.length - 1] ?? 0,
+        });
+    }
+    rows.sort((a, b) => b.totalMs - a.totalMs);
+    const header = "phase                                          |  n  | fail |  bytes      | total ms | p50 | p95 | max";
+    const sep = "-----------------------------------------------+-----+------+-------------+----------+-----+-----+-----";
+    const body = rows
+        .map((r) => `${pad(r.phase, 47)}| ${pad(String(r.count), 4)}| ${pad(String(r.failures), 5)}| ${pad(formatBytes(r.totalBytes), 12)}| ${pad(String(Math.round(r.totalMs)), 9)}| ${pad(String(Math.round(r.p50)), 4)}| ${pad(String(Math.round(r.p95)), 4)}| ${Math.round(r.max)}`)
+        .join("\n");
+    return `${header}\n${sep}\n${body}`;
+}
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    const idx = Math.min(sorted.length - 1, Math.max(0, Math.ceil(sorted.length * p) - 1));
+    return sorted[idx] ?? 0;
+}
+function pad(s, width) {
+    return s.length >= width ? `${s} ` : s + " ".repeat(width - s.length);
+}
+function formatBytes(n) {
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    if (n < 1024 * 1024 * 1024)
+        return `${(n / 1024 / 1024).toFixed(1)} MB`;
+    return `${(n / 1024 / 1024 / 1024).toFixed(2)} GB`;
+}

package/dist/cli.js

@@ -76,6 +76,60 @@ else if (process.argv.includes("--quiet") || process.argv.includes("-q")) {
     process.env.AILF_LOG_LEVEL = "quiet";
 }
 // ---------------------------------------------------------------------------
+// W0052 — hard-error on retired capture flags and env vars.
+// --------------------------------------------------------------------------
+// The legacy collector has been removed. Callers still using
+// --capture / --capture-dir / --no-capture-compress / --no-capture-extras
+// or AILF_CAPTURE* / AILF_LEGACY_COLLECTOR / AILF_UNIFIED_ARTIFACTS must
+// migrate to --artifacts-dir / --no-artifacts / --artifacts-exclude. We
+// print a clear pointer so failures don't bubble up as opaque "unknown
+// option" errors from Commander.
+// ---------------------------------------------------------------------------
+const RETIRED_FLAGS = [
+    "--capture",
+    "--capture-dir",
+    "--no-capture-compress",
+    "--no-capture-extras",
+    "--capture-exclude",
+];
+const RETIRED_ENV_VARS = [
+    "AILF_CAPTURE",
+    "AILF_CAPTURE_DIR",
+    "AILF_CAPTURE_COMPRESS",
+    "AILF_CAPTURE_EXTRAS",
+    "AILF_CAPTURE_GCS_BUCKET",
+    "AILF_CAPTURE_GCS_PREFIX",
+    "AILF_LEGACY_COLLECTOR",
+    "AILF_UNIFIED_ARTIFACTS",
+];
+function findRetiredFlag() {
+    for (const arg of process.argv) {
+        const bare = arg.split("=")[0];
+        if (RETIRED_FLAGS.includes(bare)) {
+            return bare;
+        }
+    }
+    return undefined;
+}
+function findRetiredEnv() {
+    for (const name of RETIRED_ENV_VARS) {
+        if (process.env[name] !== undefined)
+            return name;
+    }
+    return undefined;
+}
+const retiredFlag = findRetiredFlag();
+const retiredEnv = findRetiredEnv();
+if (retiredFlag || retiredEnv) {
+    const source = retiredFlag
+        ? `flag "${retiredFlag}"`
+        : `environment variable "${retiredEnv}"`;
+    console.error(`❌ ${source} was retired in W0052 along with the legacy artifact collector.`);
+    console.error("   Use --artifacts-dir / --no-artifacts / --artifacts-exclude instead.");
+    console.error("   See docs/cli.md and docs/decisions/D0033-unified-run-anchored-artifact-capture.md.");
+    process.exit(2);
+}
+// ---------------------------------------------------------------------------
 // Build CLI program
 // ---------------------------------------------------------------------------
 import { Command } from "commander";
@@ -134,6 +188,8 @@ import { createBaselineCommand } from "./commands/baseline.js";
 program.addCommand(createBaselineCommand().helpGroup(CommandGroup.CoreWorkflow));
 import { createPublishCommand } from "./commands/publish.js";
 program.addCommand(createPublishCommand().helpGroup(CommandGroup.CoreWorkflow));
+import { createRunsCommand } from "./commands/runs.js";
+program.addCommand(createRunsCommand().helpGroup(CommandGroup.CoreWorkflow));
 // ── Analysis & Reports ────────────────────────────────────────────────
 import { createReadinessReportCommand } from "./commands/readiness-report.js";
 program.addCommand(createReadinessReportCommand().helpGroup(CommandGroup.AnalysisReports));
@@ -179,8 +235,6 @@ program.addCommand(createLookupDocCommand().helpGroup(CommandGroup.PipelineInter
 import { createWebhookServerCommand } from "./commands/webhook-server.js";
 program.addCommand(createWebhookServerCommand().helpGroup(CommandGroup.PipelineInternals));
 // ── Developer Tools ───────────────────────────────────────────────────
-import { createCaptureCommand } from "./commands/capture.js";
-program.addCommand(createCaptureCommand().helpGroup(CommandGroup.DeveloperTools));
 import { createInteractiveCommand } from "./commands/interactive.js";
 program.addCommand(createInteractiveCommand().helpGroup(CommandGroup.DeveloperTools));
 // Shell completion — must be registered last (needs full program tree)

package/dist/commands/explain-handler.js

@@ -723,14 +723,10 @@ async function buildPipelineExplainPlan(actionCommand, rootDir) {
         taskSource: raw.taskSource,
         remoteCache: raw.remoteCache,
         config: raw.config,
-        capture: raw.capture ?? false,
-        captureCompress: raw.captureCompress ?? true,
-        captureExtras: raw.captureExtras ?? true,
-        captureDir: raw.captureDir,
         artifacts: raw.artifacts ?? true,
         artifactsDir: raw.artifactsDir,
         artifactsDryRun: raw.artifactsDryRun ?? false,
-        captureExclude: raw.captureExclude,
+        artifactsExclude: raw.artifactsExclude,
     };
     const resolved = computeResolvedOptions(withDefaults);
     const planOpts = {

package/dist/commands/pipeline-action.d.ts

@@ -63,10 +63,6 @@ export interface ResolvedOptions {
     urlArgs: string[];
     apiUrl: string;
     apiKey?: string;
-    captureEnabled: boolean;
-    captureDir?: string;
-    captureCompress: boolean;
-    captureExtras: boolean;
     /** D0033 / W0049 — unified artifact surface (W0050 wires it into writer). */
     artifactsDisabled: boolean;
     artifactsDir?: string;

package/dist/commands/pipeline-action.js

@@ -263,32 +263,25 @@ export function computeResolvedOptions(opts) {
         tagOption,
         taskSourceType: resolvedTaskSourceType,
         urlArgs,
-        captureEnabled: opts.capture,
-        captureDir: resolveArtifactsDir(opts),
-        captureCompress: opts.captureCompress !== false &&
-            process.env.AILF_CAPTURE_COMPRESS !== "0",
-        captureExtras: opts.captureExtras !== false && process.env.AILF_CAPTURE_EXTRAS !== "0",
         artifactsDisabled: opts.artifacts === false,
         artifactsDir: resolveArtifactsDir(opts),
         artifactsDryRun: opts.artifactsDryRun,
-        artifactsExclude: parseCaptureExcludeList(opts.captureExclude),
+        artifactsExclude: parseArtifactsExcludeList(opts.artifactsExclude),
     };
 }
 /**
- * Resolve the artifacts / capture output directory from CLI flags and env
- * vars. Precedence (highest first):
+ * Resolve the artifacts output directory from CLI flags and env vars.
+ * Precedence (highest first):
  *   1. `--artifacts-dir` flag
- *   2. `--capture-dir` flag (deprecated alias; no warning — silent rewrite)
- *   3. `AILF_ARTIFACTS_DIR` env var
- *   4. `AILF_CAPTURE_DIR` env var (deprecated alias; silent)
+ *   2. `AILF_ARTIFACTS_DIR` env var
+ *
+ * The `--capture-dir` / `AILF_CAPTURE_DIR` aliases were retired in W0052;
+ * callers of those names are rejected at CLI entry (see cli.ts).
  */
 function resolveArtifactsDir(opts) {
-    return (opts.artifactsDir ??
-        opts.captureDir ??
-        process.env.AILF_ARTIFACTS_DIR ??
-        process.env.AILF_CAPTURE_DIR);
+    return opts.artifactsDir ?? process.env.AILF_ARTIFACTS_DIR;
 }
-function parseCaptureExcludeList(raw) {
+function parseArtifactsExcludeList(raw) {
     if (!raw)
         return undefined;
     const list = raw
@@ -309,20 +302,6 @@ function resolveTaskSourceType(raw) {
 // ---------------------------------------------------------------------------
 // Pipeline entry point
 // ---------------------------------------------------------------------------
-/**
- * Module-level flag so the `--capture` deprecation warning fires exactly
- * once per process even when `executePipeline` is invoked multiple times
- * (e.g. tests, long-lived dev loops).
- */
-let warnedCaptureDeprecation = false;
-function warnCaptureDeprecationIfNeeded(cliOpts) {
-    if (!cliOpts.capture)
-        return;
-    if (warnedCaptureDeprecation)
-        return;
-    warnedCaptureDeprecation = true;
-    console.warn("--capture is deprecated and will be removed in a future release; use --artifacts-dir or --no-artifacts instead");
-}
 /**
  * Execute the evaluation pipeline.
  *
@@ -332,7 +311,6 @@ function warnCaptureDeprecationIfNeeded(cliOpts) {
  * 4. Delegate to the PipelineOrchestrator
  */
 export async function executePipeline(cliOpts) {
-    warnCaptureDeprecationIfNeeded(cliOpts);
     // When --config is provided, resolve config from file instead of CLI flags
     if (cliOpts.config) {
         const { existsSync } = await import("fs");
@@ -357,25 +335,13 @@ export async function executePipeline(cliOpts) {
         }
         // Output dir: explicit CLI flag → $CWD/.ailf/results/latest/
         config.outputDir = resolveOutputDir(cliOpts.outputDir);
-        // Capture options — CLI flags and env vars aren't in the config file,
+        // Artifact options — CLI flags and env vars aren't in the config file,
         // so merge them here (same logic as resolveOptions).
-        // AILF_CAPTURE is a no-op post-W0049; only the flag toggles captureEnabled.
-        config.captureEnabled = cliOpts.capture;
         const resolvedArtifactsDir = resolveArtifactsDir(cliOpts);
-        if (resolvedArtifactsDir) {
-            config.captureDir = resolvedArtifactsDir;
-        }
-        config.captureCompress =
-            cliOpts.captureCompress !== false &&
-                process.env.AILF_CAPTURE_COMPRESS !== "0";
-        config.captureExtras =
-            cliOpts.captureExtras !== false && process.env.AILF_CAPTURE_EXTRAS !== "0";
-        config.captureGcsBucket ??= process.env.AILF_CAPTURE_GCS_BUCKET;
-        config.captureGcsPrefix ??= process.env.AILF_CAPTURE_GCS_PREFIX;
         config.artifactsDisabled ??= cliOpts.artifacts === false;
         config.artifactsDir ??= resolvedArtifactsDir;
         config.artifactsDryRun ??= cliOpts.artifactsDryRun;
-        const excludeList = parseCaptureExcludeList(cliOpts.captureExclude);
+        const excludeList = parseArtifactsExcludeList(cliOpts.artifactsExclude);
         if (excludeList) {
             config.artifactsExclude = excludeList;
         }

package/dist/commands/pipeline.d.ts

@@ -64,13 +64,9 @@ export interface PipelineCliOptions {
     url: string[];
     urls: string[];
     apiUrl?: string;
-    capture: boolean;
-    captureDir?: string;
-    captureCompress: boolean;
-    captureExtras: boolean;
     artifacts: boolean;
     artifactsDir?: string;
     artifactsDryRun: boolean;
-    captureExclude?: string;
+    artifactsExclude?: string;
 }
 export declare function createPipelineCommand(): Command;

package/dist/commands/pipeline.js

@@ -54,14 +54,10 @@ export function createPipelineCommand() {
         .option("--repo-tasks-path <path>", "Path to repo-based task definitions (.ailf/tasks/ directory)")
         .option("--remote", "Submit evaluation to the AILF API instead of running locally", false)
         .option("--api-url <url>", "AILF API base URL (default: https://ailf-api.sanity.build)")
-        .option("--capture", "[DEPRECATED] Enable legacy artifact capture. Use --artifacts-dir / --no-artifacts instead.", false)
-        .option("--capture-dir <path>", "[DEPRECATED] Alias for --artifacts-dir.")
-        .option("--no-capture-compress", "Disable tar.gz compression of captures")
-        .option("--no-capture-extras", "Exclude mode-specific artifacts from captures")
         .option("--no-artifacts", "Disable all artifact writers (D0033). Overrides --artifacts-dir.")
         .option("--artifacts-dir <path>", "Root directory for local artifact output (D0033; default: .ailf/results/captures/)")
         .option("--artifacts-dry-run", "Run artifact writers in dry-run mode — log intended writes, touch no storage", false)
-        .option("--capture-exclude <types>", "Comma-separated artifact types to skip (e.g. traces,graderPrompts)")
+        .option("--artifacts-exclude <types>", "Comma-separated artifact types to skip (e.g. traces,graderPrompts)")
         .action(async (opts) => {
         const { executePipeline } = await import("./pipeline-action.js");
         await executePipeline(opts);

package/dist/commands/runs.d.ts

@@ -0,0 +1,18 @@
+/**
+ * runs command — utilities for working with run-anchored artifacts on disk.
+ *
+ * The unified artifact writer (D0033 M4) lays artifacts down under
+ * `.ailf/results/captures/runs/{runId}/…`. Downstream tooling (CI archivers,
+ * external consumers that used to parse the legacy collector tarball) still
+ * want a single-file bundle. `runs export --format tarball` reproduces that
+ * bundle from the existing tree — no re-materialisation, just a tar of the
+ * files already written.
+ *
+ * The on-disk layout is identical to what the legacy FilesystemArtifactCollector
+ * produced (same paths, same filenames), so the tarball shape is stable for
+ * existing consumers.
+ *
+ * @see docs/decisions/D0033-unified-run-anchored-artifact-capture.md
+ */
+import { Command } from "commander";
+export declare function createRunsCommand(): Command;

package/dist/commands/runs.js

@@ -0,0 +1,71 @@
+/**
+ * runs command — utilities for working with run-anchored artifacts on disk.
+ *
+ * The unified artifact writer (D0033 M4) lays artifacts down under
+ * `.ailf/results/captures/runs/{runId}/…`. Downstream tooling (CI archivers,
+ * external consumers that used to parse the legacy collector tarball) still
+ * want a single-file bundle. `runs export --format tarball` reproduces that
+ * bundle from the existing tree — no re-materialisation, just a tar of the
+ * files already written.
+ *
+ * The on-disk layout is identical to what the legacy FilesystemArtifactCollector
+ * produced (same paths, same filenames), so the tarball shape is stable for
+ * existing consumers.
+ *
+ * @see docs/decisions/D0033-unified-run-anchored-artifact-capture.md
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { Command } from "commander";
+const DEFAULT_ARTIFACTS_DIR = ".ailf/results/captures";
+function resolveArtifactsDir(flag) {
+    return resolve(flag ?? process.env.AILF_ARTIFACTS_DIR ?? DEFAULT_ARTIFACTS_DIR);
+}
+function resolveOutputPath(explicit, artifactsDir, runId) {
+    if (explicit)
+        return resolve(explicit);
+    return resolve(artifactsDir, `runs-${runId}.tar.gz`);
+}
+function exportTarball(opts) {
+    if (opts.format !== "tarball") {
+        console.error(`❌ Unsupported --format "${opts.format}". Supported: tarball.`);
+        return 2;
+    }
+    const artifactsDir = resolveArtifactsDir(opts.artifactsDir);
+    const runRoot = resolve(artifactsDir, "runs", opts.runId);
+    if (!existsSync(runRoot)) {
+        console.error(`❌ No artifacts on disk for run "${opts.runId}" at ${runRoot}`);
+        console.error("   Set --artifacts-dir / AILF_ARTIFACTS_DIR or check the runId.");
+        return 1;
+    }
+    const outputPath = resolveOutputPath(opts.output, artifactsDir, opts.runId);
+    const outputDir = dirname(outputPath);
+    mkdirSync(outputDir, { recursive: true });
+    // Spawn system tar — the unified tree is byte-for-byte identical to the
+    // legacy collector's output, so `tar -czf` produces a tarball with the
+    // same file list consumers depended on.
+    const tar = spawnSync("tar", ["-czf", outputPath, "-C", resolve(artifactsDir, "runs"), opts.runId], { stdio: "inherit" });
+    if (tar.status !== 0) {
+        console.error(`❌ tar exited with status ${tar.status}`);
+        return tar.status ?? 1;
+    }
+    console.log(`  ✅ Exported ${runRoot} → ${outputPath}`);
+    return 0;
+}
+export function createRunsCommand() {
+    const cmd = new Command("runs").description("Utilities for working with run-anchored artifact trees on disk");
+    cmd
+        .command("export")
+        .description("Export a run's artifact tree to a portable archive. Only `--format tarball` is supported.")
+        .requiredOption("--run-id <runId>", "Run id to export (required)")
+        .option("--format <fmt>", "Output format (currently only: tarball)", "tarball")
+        .option("--artifacts-dir <path>", "Override the root directory containing runs/{runId}/… (default: .ailf/results/captures)")
+        .option("-o, --output <path>", "Output archive path (default: {artifacts-dir}/runs-{runId}.tar.gz)")
+        .action((opts) => {
+        const code = exportTarball(opts);
+        if (code !== 0)
+            process.exit(code);
+    });
+    return cmd;
+}

package/dist/composition-root.d.ts

@@ -15,7 +15,7 @@
  * @see packages/core/src/ports/context.ts — AppContext interface
  * @see docs/archive/exec-plans/ports-and-adapters/phase-7-composition-root.md
  */
-import { type AppContext, type ArtifactWriter, type AssertionRegistration, type Logger, type ResolvedConfig } from "./_vendor/ailf-core/index.d.ts";
+import { type AppContext, type ArtifactWriter, type ArtifactWriterProgressOptions, type AssertionRegistration, type Logger, type ResolvedConfig } from "./_vendor/ailf-core/index.d.ts";
 /**
  * Create a fully wired AppContext from resolved configuration.
  *
@@ -41,7 +41,7 @@ export declare function createAppContext(config: ResolvedConfig): AppContext;
  *
  * Exported for unit-test access; not part of the public package API.
  */
-export declare function createArtifactWriter(config: ResolvedConfig, logger: Logger): ArtifactWriter;
+export declare function createArtifactWriter(config: ResolvedConfig, logger: Logger, progress?: ArtifactWriterProgressOptions): ArtifactWriter;
 /**
  * Generic Promptfoo assertion types available to all evaluation modes.
  *