@prismatic-io/lux 0.0.2-preview.4 → 0.0.2-preview.41

package/src/cli/render/format.ts

@@ -59,7 +59,7 @@ export const formatAlignedUsage = (usage: TokenUsage): string =>
     ].join("  "),
   ].join("      ");
 
-export const formatScore = (score: number): string => `${Math.round(score * 100)}%`;
+export const formatScore = (score: number): string => `${Number((score * 100).toPrecision(15))}%`;
 
 /** A one-line count summary: "2 passed · 1 failed · 1 running  (4)". */
 export const formatTally = (parts: [count: number, label: string][], total: number): string => {

package/src/cli/render/reporter.ts

@@ -19,6 +19,7 @@ import {
   TurnUsageSchema,
   totalTokens,
 } from "../../core/index.js";
+import { hasAgentUsage } from "../../core/usage.js";
 import type { CaseObserver, SuiteCaseResult, SuiteObserver } from "../../orchestrator/index.js";
 import {
   formatAlignedUsage,
@@ -80,6 +81,7 @@ type CaseView = {
   assertions: GradingAssertionEntry[];
   skippedAssertions: NonNullable<GradingReport["skippedAssertions"]>;
   usage: RunUsage;
+  agentUsageReported: boolean;
   /** Per-API-call agent usage, in order — the split behind `usage.agent`. */
   agentTurns: TurnUsage[];
   phaseDurationMs: PhaseDurations | null;
@@ -119,7 +121,10 @@ const statusMark = (status: CaseStatus, theme: Theme): string => {
 
 const assertionTally = (view: CaseView): string => {
   const passed = view.assertions.filter((a) => a.passed).length;
-  const evaluated = view.assertions.length === 0 ? "—" : `${passed}/${view.assertions.length}`;
+  const evaluated =
+    view.assertions.length === 0
+      ? "—"
+      : `${passed}/${view.assertions.filter((a) => a.passed !== null).length}`;
   return view.skippedAssertions.length > 0
     ? `${evaluated} · ${view.skippedAssertions.length} skipped`
     : evaluated;
@@ -159,9 +164,12 @@ const cell = (text: string, width: number): string => {
  */
 const scoreNote = (entry: GradingAssertionEntry): string => {
   if (entry.errorMessage) return entry.errorMessage;
-  if (entry.passed) return "";
+  if (entry.abstention) return "insufficient evidence";
+  if (entry.passed === null) return `informational; score ${formatScore(entry.score)}`;
+  if (entry.passed) return entry.score < 1 ? `score ${formatScore(entry.score)}` : "";
   const score = formatScore(entry.score);
-  if (entry.threshold > 0) return `score ${score} < ${formatScore(entry.threshold)}`;
+  if (entry.threshold !== undefined && entry.threshold > 0)
+    return `score ${score} < ${formatScore(entry.threshold)}`;
   return entry.score > 0 ? `score ${score}` : "";
 };
 
@@ -240,6 +248,7 @@ export class ConsoleReporter implements SuiteObserver {
       assertions: [],
       skippedAssertions: [],
       usage: emptyRunUsage(),
+      agentUsageReported: false,
       agentTurns: [],
       phaseDurationMs: null,
       runDir: null,
@@ -273,6 +282,13 @@ export class ConsoleReporter implements SuiteObserver {
       view.toolUnresolved = tools.unresolved;
       view.toolUnmatchedResults = tools.unmatchedResults;
       view.toolMalformed = tools.malformedEvents;
+    } else if (event.type === "progress" && event.kind === "driver-stderr" && this.verbose) {
+      const payload = event.payload as { text?: unknown; truncated?: unknown } | null;
+      if (payload && typeof payload.text === "string") {
+        this.region.staticLine(this.theme.dim(` [${view.caseId}] ${payload.text}`));
+        if (payload.truncated === true)
+          this.region.staticLine(this.theme.dim(" [driver stderr truncated]"));
+      }
     } else if (event.type === "progress" && event.kind === "usage") {
       const turn = TurnUsageSchema.safeParse(event.payload).data;
       if (turn) view.agentTurns.push(turn);
@@ -307,6 +323,7 @@ export class ConsoleReporter implements SuiteObserver {
       view.assertions = result.result.grading.assertions;
       view.skippedAssertions = result.result.grading.skippedAssertions ?? [];
       view.usage = result.result.metadata.usage;
+      view.agentUsageReported = hasAgentUsage(result.result.metadata);
       view.phaseDurationMs = result.result.metadata.phaseDurationMs ?? null;
       const tools = result.result.metadata.toolOutcomes;
       if (tools) {
@@ -451,10 +468,14 @@ export class ConsoleReporter implements SuiteObserver {
       Math.max(NAME_MIN, ...view.assertions.map((a) => a.name.length)),
     );
     for (const entry of view.assertions) {
-      const mark = entry.passed ? this.theme.green("✓") : this.theme.red("✗");
+      let mark = entry.passed ? this.theme.green("✓") : this.theme.red("✗");
+      if (entry.passed === null) mark = this.theme.dim("ℹ");
+      if (entry.abstention) mark = this.theme.dim("?");
       const duration = formatDuration(entry.durationMs).padStart(DURATION_COL);
       const note = scoreNote(entry);
-      const suffix = note ? `  ${this.theme.red(note)}` : "";
+      const suffix = note
+        ? `  ${entry.abstention || entry.passed !== false ? this.theme.dim(note) : this.theme.red(note)}`
+        : "";
       nodes.push({
         head: `${mark} ${cell(entry.name, width)}  ${this.theme.dim(duration)}${suffix}`,
         body: !entry.passed && entry.comment ? [this.theme.dim(entry.comment)] : [],
@@ -566,11 +587,12 @@ export class ConsoleReporter implements SuiteObserver {
     const skippedAssertions = this.cases.flatMap((c) => c.skippedAssertions);
     if (assertions.length > 0 || skippedAssertions.length > 0) {
       const ok = assertions.filter((a) => a.passed).length;
-      const bad = assertions.length - ok;
+      const bad = assertions.filter((a) => a.passed === false).length;
       const tally = formatTally(
         [
           [ok, this.theme.green("passed")],
           [bad, this.theme.red("failed")],
+          [assertions.filter((a) => a.passed === null).length, this.theme.dim("informational")],
           [skippedAssertions.length, this.theme.dim("skipped")],
         ],
         assertions.length + skippedAssertions.length,
@@ -630,11 +652,17 @@ export class ConsoleReporter implements SuiteObserver {
       emptyRunUsage(),
     );
     const harness = harnessUsage(total);
-    if (isUsageEmpty(total.agent) && isUsageEmpty(harness)) {
+    const reported = this.cases.filter(
+      (view) => view.agentUsageReported || !isUsageEmpty(this.agentUsageOf(view)),
+    ).length;
+    if (reported === 0 && isUsageEmpty(total.agent) && isUsageEmpty(harness)) {
       return live ? [] : [` ${label("Tokens")}${this.theme.dim("none reported")}`];
     }
 
-    const agentText = isUsageEmpty(total.agent) ? this.theme.dim("none") : formatUsage(total.agent);
+    const missing = this.cases.length - reported;
+    const partial = missing > 0 ? ` (${missing} run${missing === 1 ? "" : "s"} unavailable)` : "";
+    const agentText =
+      reported === 0 ? this.theme.dim("unavailable") : `${formatUsage(total.agent)}${partial}`;
     if (live) {
       const harnessText = isUsageEmpty(harness)
         ? ""

package/src/cli/run-options.ts

@@ -1,4 +1,9 @@
-import { InvalidArgumentError } from "commander";
+import { existsSync } from "node:fs";
+import { basename, extname, resolve } from "node:path";
+import { Errors } from "incur";
+import type { HarnessFocus, ReasoningEffort } from "../core/index.js";
+import { type DiscoveredCase, type SuiteItem, selectCases } from "../orchestrator/index.js";
+import { planHarnessItems } from "./harness-plan.js";
 
 export type RunOptions = {
   tag?: string[];
@@ -11,26 +16,21 @@ export type RunOptions = {
   skipJudge?: boolean;
   runsRoot?: string;
   profile?: string;
+  driver?: string;
+  model?: string;
+  effort?: ReasoningEffort;
   subjectRoot?: string;
   verbose?: boolean;
 };
 
-export const collectTags = (value: string, previous: string[]): string[] =>
-  previous.concat(
-    value
-      .split(",")
-      .map((tag) => tag.trim())
-      .filter(Boolean),
-  );
-
-export const collectValues = (value: string, previous: string[]): string[] => [...previous, value];
-
 export const parseAnnotationAssertion = (
   value: string,
 ): [string, { passed: boolean; score?: number }] => {
   const match = /^(.+)=(pass|fail)(?::(.+))?$/.exec(value);
-  if (!match?.[1] || !match[2]) {
-    throw new InvalidArgumentError("--assertion must use id=pass, id=fail, or id=pass:0.8 syntax");
+  if (!match?.[1]?.trim() || !match[2]) {
+    throw new Errors.ParseError({
+      message: "--assertion must use id=pass, id=fail, or id=pass:0.8 syntax",
+    });
   }
   const score = match[3] === undefined ? undefined : parseUnitInterval(match[3]);
   return [
@@ -42,19 +42,10 @@ export const parseAnnotationAssertion = (
   ];
 };
 
-export const parsePositiveInt = (value: string): number => {
-  // Number() rejects partial numbers such as "3abc" and "2.9".
+const parseUnitInterval = (value: string): number => {
   const parsed = Number(value);
-  if (!Number.isInteger(parsed) || parsed < 1) {
-    throw new InvalidArgumentError("must be a positive integer");
-  }
-  return parsed;
-};
-
-export const parseUnitInterval = (value: string): number => {
-  const parsed = Number(value);
-  if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) {
-    throw new InvalidArgumentError("must be a number between 0 and 1");
+  if (!value.trim() || !Number.isFinite(parsed) || parsed < 0 || parsed > 1) {
+    throw new Errors.ParseError({ message: "must be a number between 0 and 1" });
   }
   return parsed;
 };
@@ -81,3 +72,118 @@ export const resolveAnswererOverride = (options: RunOptions): string | undefined
   if (options.claudeAnswerer) return "claude-code";
   return undefined;
 };
+
+const caseIdOf = (casePath: string): string => basename(casePath, extname(casePath));
+
+export const suiteTitle = (
+  patterns: string[],
+  tags: string[],
+  explicit: SuiteItem[],
+  loop: number,
+  focus: HarnessFocus,
+): string => {
+  const parts = [...patterns, ...explicit.map((e) => e.id), ...tags.map((t) => `#${t}`)];
+  const filter = parts.length > 0 ? ` ${parts.join(" ")}` : "";
+  const focusParts = [focus.driver, focus.model, focus.effort].filter(
+    (part): part is string => part !== undefined,
+  );
+  const focused = focusParts.length > 0 ? ` @${focusParts.join(":")}` : "";
+  const repeat = loop > 1 ? ` ×${loop}` : "";
+  return `run${filter}${focused}${repeat}`;
+};
+
+type FilterPartition = { explicit: SuiteItem[]; patterns: string[] };
+
+// A filter that names an existing `.ts` file runs that file directly — it may
+// sit outside the discovery root. Everything else is a substring pattern — but
+// a `.ts` filter that resolves to nothing is almost always a typo'd path, so
+// the silent downgrade to a pattern gets called out.
+export const partitionFilters = (filters: string[], cwd: string): FilterPartition => {
+  const explicit: SuiteItem[] = [];
+  const patterns: string[] = [];
+  for (const f of filters) {
+    const abs = resolve(cwd, f);
+    if (f.endsWith(".ts") && existsSync(abs)) {
+      explicit.push({ path: abs, id: caseIdOf(f) });
+    } else {
+      if (f.endsWith(".ts")) {
+        process.stderr.write(`lux: ${abs} does not exist; treating "${f}" as a pattern\n`);
+      }
+      patterns.push(f);
+    }
+  }
+  return { explicit, patterns };
+};
+
+// The selected set — substring/tag matches plus explicitly named files — is
+// the same whether it is run, `--list`ed, or `--list-tags`ed. No filters at
+// all means "everything discovered"; any filter narrows.
+export const selectSuite = (
+  cases: DiscoveredCase[],
+  { explicit, patterns }: FilterPartition,
+  tags: string[],
+): DiscoveredCase[] => {
+  const hasFilter = explicit.length > 0 || patterns.length > 0 || tags.length > 0;
+  const byPath = new Map<string, DiscoveredCase>();
+  if (!hasFilter) {
+    for (const c of cases) byPath.set(c.path, c);
+  } else {
+    if (patterns.length > 0 || tags.length > 0) {
+      for (const c of selectCases(cases, { patterns, tags })) byPath.set(c.path, c);
+    }
+    for (const e of explicit) {
+      const discovered = cases.find((c) => c.path === e.path);
+      // Discovery knows the case's declared id; the filename-derived one is
+      // only a fallback for files discovery never saw.
+      byPath.set(e.path, {
+        path: e.path,
+        id: discovered?.id ?? e.id,
+        relPath: discovered?.relPath ?? e.id,
+        tags: discovered?.tags ?? [],
+      });
+    }
+  }
+  return [...byPath.values()].sort((a, b) => a.id.localeCompare(b.id));
+};
+
+// `--loop` repeats each eval before moving to the next; each repeat gets a
+// `#n` display suffix so the reporter keeps them apart, while `caseId` keeps
+// every repeat filed under one run history.
+export const expandLoop = (base: SuiteItem[], loop: number): SuiteItem[] =>
+  loop > 1
+    ? base.flatMap((b) =>
+        Array.from({ length: loop }, (_, i) => ({
+          ...b,
+          id: `${b.id} #${i + 1}`,
+          caseId: b.caseId ?? b.id,
+        })),
+      )
+    : base;
+
+export const planSuiteItems = async (
+  selected: readonly { path: string; id: string }[],
+  options: Parameters<typeof planHarnessItems>[1],
+): Promise<SuiteItem[]> => {
+  const plan = await planHarnessItems(selected, options);
+  for (const skipped of plan.unavailable) {
+    process.stderr.write(
+      `lux: skipping ${skipped.id}: harness command not found: ${skipped.commands.join(", ")}\n`,
+    );
+  }
+  if (plan.excluded.length > 0) {
+    process.stderr.write(
+      `lux: the harness focus excludes ${plan.excluded.length} pinned case${plan.excluded.length === 1 ? "" : "s"}: ${plan.excluded.join(", ")}\n`,
+    );
+  }
+  if (plan.items.length === 0) {
+    throw new Errors.IncurError({
+      code: plan.unavailable.length > 0 ? "NO_RUNNABLE_HARNESSES" : "NO_CASES_MATCHED",
+      message:
+        plan.unavailable.length > 0
+          ? "No cases remain: all selected matrix harnesses are unavailable."
+          : "No cases remain after applying the harness focus.",
+      exitCode: 1,
+    });
+  }
+  return plan.items;
+};

package/src/cli/view.ts

@@ -0,0 +1,129 @@
+import { resolve } from "node:path";
+import { Errors } from "incur";
+import {
+  isExperimentRun,
+  listExperimentRuns,
+  listRuns,
+  listSuiteRuns,
+  loadExperimentRun,
+  loadLuxConfig,
+  loadRunDetail,
+  loadSuiteRun,
+} from "../orchestrator/index.js";
+import { openPreviewUrl, startPreviewServer } from "../previewer/server.js";
+import { abortOnInterrupt, ensureDirectory, failWith } from "./command-runtime.js";
+
+const SIGINT_EXIT_CODE = 130;
+
+export type ViewOptions = {
+  runsRoot?: string;
+  case?: string;
+  suites?: boolean;
+  experiments?: boolean;
+  web?: boolean;
+  port?: number;
+  open?: boolean;
+};
+
+const previewKind = async (
+  initialPath: string | undefined,
+  options: ViewOptions,
+): Promise<"run" | "suite" | "experiment" | undefined> => {
+  if (initialPath) {
+    if (isExperimentRun(initialPath)) return "experiment";
+    if (await loadSuiteRun(initialPath)) return "suite";
+    return "run";
+  }
+  if (options.experiments) return "experiment";
+  if (options.suites) return "suite";
+  return undefined;
+};
+
+export async function* webViewCommand(
+  runDirArg: string | undefined,
+  options: ViewOptions,
+): AsyncGenerator<{ url: string; runsRoot: string }, void> {
+  const config = await loadLuxConfig(process.cwd());
+  const runsRoot = options.runsRoot ? resolve(options.runsRoot) : config.runsRoot;
+  const initialPath = runDirArg ? resolve(runDirArg) : undefined;
+  if (initialPath && !(await ensureDirectory("view", initialPath))) failWith(1);
+  const initialKind = await previewKind(initialPath, options);
+  using controller = abortOnInterrupt();
+  const preview = await startPreviewServer({
+    runsRoot,
+    ...(options.port !== undefined ? { port: options.port } : {}),
+    ...(initialPath ? { initialPath } : {}),
+    ...(initialKind ? { initialKind } : {}),
+    ...(options.case ? { caseFilter: options.case } : {}),
+    signal: controller.signal,
+  });
+  try {
+    yield { url: preview.url, runsRoot };
+    if (options.open !== false) {
+      try {
+        await openPreviewUrl(preview.url);
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        process.stderr.write(`lux view: could not open a browser (${message})\n`);
+      }
+    }
+    await preview.closed;
+    if (controller.signal.aborted) failWith(SIGINT_EXIT_CODE);
+  } finally {
+    await preview.close();
+  }
+}
+
+export const viewCommand = async (
+  runDirArg: string | undefined,
+  options: ViewOptions,
+): Promise<unknown> => {
+  if (options.port !== undefined || options.open === false) {
+    throw new Errors.ParseError({ message: "--port and --no-open require --web" });
+  }
+  if (runDirArg) {
+    const path = resolve(runDirArg);
+    if (!(await ensureDirectory("view", path))) return;
+    if (isExperimentRun(path)) {
+      const experiment = await loadExperimentRun(path);
+      if (!experiment) {
+        throw new Errors.IncurError({
+          code: "INVALID_EXPERIMENT",
+          message: `Invalid experiment at ${path}.`,
+          exitCode: 1,
+        });
+      }
+      return { experimentDir: path, ...experiment };
+    }
+    const suite = await loadSuiteRun(path);
+    if (suite) {
+      return { suiteDir: path, ...suite };
+    }
+    return loadRunDetail(path);
+  }
+
+  const config = await loadLuxConfig(process.cwd());
+  const runsRoot = options.runsRoot ? resolve(options.runsRoot) : config.runsRoot;
+  const readErrors: Array<{ path: string; message: string }> = [];
+  const listingOptions = {
+    onReadError: (path: string, error: unknown) => {
+      readErrors.push({ path, message: error instanceof Error ? error.message : String(error) });
+    },
+  };
+  if (options.experiments) {
+    const experiments = await listExperimentRuns(runsRoot, listingOptions);
+    return { runsRoot, experiments, ...(readErrors.length ? { readErrors } : {}) };
+  }
+  if (options.suites) {
+    const suites = await listSuiteRuns(runsRoot, listingOptions);
+    return { runsRoot, suites, ...(readErrors.length ? { readErrors } : {}) };
+  }
+  const all = await listRuns(runsRoot);
+  const runs = options.case ? all.filter((run) => run.caseSlug === options.case) : all;
+  return {
+    runsRoot,
+    ...(!options.case ? { suites: await listSuiteRuns(runsRoot, listingOptions) } : {}),
+    runs,
+    ...(readErrors.length ? { readErrors } : {}),
+  };
+};

package/src/container/driver.ts

@@ -0,0 +1,213 @@
+import { realpath } from "node:fs/promises";
+import { posix } from "node:path";
+import type { AgentDriver, Artifact, DriverEventMap, StartContext } from "../core/driver.js";
+import type { ContainerExecution } from "../core/driver-execution.js";
+import { TypedEmitter } from "../core/emitter.js";
+import {
+  type Answer,
+  DoneSchema,
+  ErrorEventSchema,
+  InterruptSchema,
+  ProgressSchema,
+  type ReadyState,
+  ReadyStateSchema,
+} from "../core/events.js";
+import { type ManagedProcess, spawnManagedProcess } from "../core/exec.js";
+import { walkArtifacts } from "../drivers/shared/artifacts.js";
+import { LUX_VERSION } from "../orchestrator/package-version.js";
+import { containerPaths } from "./paths.js";
+import { type Message, readMessages, writeMessage } from "./protocol.js";
+import { prepareContainer } from "./resources.js";
+
+export class ContainerDriver extends TypedEmitter<DriverEventMap> implements AgentDriver {
+  private process: ManagedProcess | undefined;
+  private resources: Awaited<ReturnType<typeof prepareContainer>> | undefined;
+  private sequence = 0;
+  private pending = new Map<
+    number,
+    { resolve: (value: unknown) => void; reject: (error: Error) => void }
+  >();
+  private closing: Promise<void> | undefined;
+  private context: StartContext | undefined;
+  private terminal = false;
+  private readonly abort = () => {
+    void this.close().catch(() => {});
+  };
+
+  private readonly name: string;
+  private readonly config: unknown;
+  private readonly execution: ContainerExecution;
+  constructor(name: string, config: unknown, execution: ContainerExecution) {
+    super();
+    this.name = name;
+    this.config = config;
+    this.execution = execution;
+    JSON.stringify(config, (_key, value: unknown) => {
+      if (typeof value === "function" || typeof value === "symbol" || typeof value === "bigint")
+        throw new Error("container driver configuration must be JSON serializable");
+      return value;
+    });
+  }
+
+  private fail = (error: Error): void => {
+    for (const pending of this.pending.values()) pending.reject(error);
+    this.pending.clear();
+    if (!this.terminal && !this.closing) {
+      this.terminal = true;
+      void this.emit("error", { exitReason: "error", reason: error.message }).catch(() => {});
+    }
+  };
+
+  private receive = (message: Message): void => {
+    if (message.event) {
+      const dispatch = async () => {
+        switch (message.event) {
+          case "interrupt":
+            await this.emit("interrupt", InterruptSchema.parse(message.value));
+            break;
+          case "progress":
+            await this.emit("progress", ProgressSchema.parse(message.value));
+            break;
+          case "done":
+            this.terminal = true;
+            await this.emit("done", DoneSchema.parse(message.value));
+            break;
+          case "error":
+            this.terminal = true;
+            await this.emit("error", ErrorEventSchema.parse(message.value));
+            break;
+          default:
+            throw new Error("unknown container event");
+        }
+        if (this.process) writeMessage(this.process.child.stdin, { id: message.id, ack: true });
+      };
+      void dispatch().catch(this.fail);
+      return;
+    }
+    const pending = this.pending.get(message.id);
+    if (!pending) return;
+    this.pending.delete(message.id);
+    if (message.error !== undefined) pending.reject(new Error(message.error));
+    else pending.resolve(message.value);
+  };
+
+  private rpc = (method: string, value?: unknown, timeoutMs = 30_000): Promise<unknown> =>
+    new Promise((resolvePromise, reject) => {
+      if (!this.process) {
+        reject(new Error("container process is unavailable"));
+        return;
+      }
+      const id = ++this.sequence;
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`container ${method} timed out`));
+      }, timeoutMs);
+      this.pending.set(id, {
+        resolve: (result) => {
+          clearTimeout(timer);
+          resolvePromise(result);
+        },
+        reject: (error) => {
+          clearTimeout(timer);
+          reject(error);
+        },
+      });
+      try {
+        writeMessage(this.process.child.stdin, { id, method, value });
+      } catch (error) {
+        this.pending.get(id)?.reject(error as Error);
+        this.pending.delete(id);
+      }
+    });
+
+  async start(ctx: StartContext): Promise<ReadyState> {
+    this.context = ctx;
+    if (ctx.abortSignal.aborted) throw new Error("container run aborted before startup");
+    const raw = this.config as { cwd?: string; cwdMode?: string };
+    if (raw?.cwdMode === "runDir")
+      throw new Error("container drivers must use the artifacts workspace, not cwdMode: runDir");
+    if (raw?.cwd && (await realpath(raw.cwd)) !== (await realpath(ctx.artifactsDir)))
+      throw new Error("container driver cwd must be the mounted artifacts workspace");
+    this.resources = await prepareContainer(this.execution, ctx.artifactsDir);
+    try {
+      this.process = spawnManagedProcess(this.resources.command, this.resources.args, {
+        env: this.resources.env,
+      });
+      readMessages(this.process.child.stdout, this.receive, this.fail);
+      // Harness stderr can contain secrets. The normalized driver protocol is the evidence surface.
+      this.process.child.stderr.resume();
+      void this.process.exited.then(() => this.fail(new Error("container worker exited")));
+      ctx.abortSignal.addEventListener("abort", this.abort, { once: true });
+      await this.process.spawned;
+      if (ctx.abortSignal.aborted) throw new Error("container run aborted during startup");
+      const { abortSignal: _signal, ...context } = ctx;
+      const ready = ReadyStateSchema.parse(
+        await this.rpc(
+          "start",
+          {
+            version: LUX_VERSION,
+            name: this.name,
+            config: containerPaths(this.config, this.resources.pathMappings),
+            module: this.execution.driverModule,
+            context: {
+              ...containerPaths(context, this.resources.pathMappings),
+              artifactsDir: this.resources.containerRoot,
+              ...(context.fixtures
+                ? { fixtures: { ...context.fixtures, rootDir: this.resources.containerRoot } }
+                : {}),
+              runDir: "/tmp/lux-run",
+              runsRoot: "/tmp/lux-runs",
+            },
+          },
+          this.execution.startupTimeoutMs ?? 60_000,
+        ),
+      );
+      return {
+        ...ready,
+        detail: { ...ready.detail, execution: "container", image: this.resources.image },
+      };
+    } catch (error) {
+      await this.close();
+      throw error;
+    }
+  }
+
+  async respond(answer: Answer): Promise<void> {
+    await this.rpc("respond", answer);
+  }
+  async quiesce(): Promise<void> {
+    await this.rpc("quiesce");
+  }
+  async collect(): Promise<Artifact[]> {
+    const root = this.resources?.root;
+    const containerRoot = this.resources?.containerRoot;
+    if (!root || !containerRoot) return [];
+    try {
+      const artifacts = (await this.rpc("collect")) as Artifact[];
+      for (const artifact of artifacts) {
+        const path = posix.resolve(artifact.root ?? containerRoot, artifact.path);
+        if (path !== containerRoot && !path.startsWith(`${containerRoot}/`))
+          throw new Error("container driver returned artifacts outside its mounted workspace");
+      }
+    } finally {
+      await this.close();
+    }
+    return walkArtifacts(root);
+  }
+  close(): Promise<void> {
+    this.closing ??= (async () => {
+      this.context?.abortSignal.removeEventListener("abort", this.abort);
+      try {
+        if (this.process) {
+          await this.rpc("close", undefined, 5_000).catch(() => {});
+          this.process.child.stdin.end();
+        }
+        await this.resources?.cleanup();
+      } finally {
+        await this.process?.terminate();
+        this.fail(new Error("container driver closed"));
+      }
+    })();
+    return this.closing;
+  }
+}

package/src/container/paths.ts

@@ -0,0 +1,29 @@
+/** Translate only mounted host paths; unrelated configuration remains untouched. */
+export const containerPaths = <T>(
+  value: T,
+  mappings: readonly (readonly [string, string])[],
+): T => {
+  const ordered = [...mappings].sort(([a], [b]) => b.length - a.length);
+  const visit = (entry: unknown): unknown => {
+    if (typeof entry === "string") {
+      let text = entry;
+      for (const [source, target] of ordered) {
+        if (source === target) continue;
+        if (text === source) return target;
+        if (text.startsWith(`${source}\\`) || text.startsWith(`${source}/`))
+          return target + text.slice(source.length).replaceAll("\\", "/");
+        const escaped = source.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        text = text.replace(
+          new RegExp(`${escaped}([\\\\/][^\\s"']*)?(?=$|[\\s"'])`, "g"),
+          (_match, suffix: string | undefined) => target + (suffix ?? "").replaceAll("\\", "/"),
+        );
+      }
+      return text;
+    }
+    if (Array.isArray(entry)) return entry.map(visit);
+    if (entry && typeof entry === "object")
+      return Object.fromEntries(Object.entries(entry).map(([key, item]) => [key, visit(item)]));
+    return entry;
+  };
+  return visit(value) as T;
+};