@forwardimpact/libeval 0.1.50 → 0.1.52

package/src/benchmark/apm-installer.js

@@ -4,26 +4,25 @@
  * staging directory, and computes the manifest fingerprint from the lockfile.
  * Per-task copy happens later in WorkdirManager.
  *
- * The class takes a `spawn` seam so tests can substitute a fake child process
- * without ever shelling out to a real `apm` binary. See `createApmInstaller`
- * for the real-dependency wiring; `installApm` is a thin free-function wrapper
- * for callers that don't need to inject anything.
+ * Subprocess and filesystem access route through the injected `runtime` bag
+ * (`runtime.subprocess.spawn` for the streaming `apm` child, `runtime.fs` for
+ * the async staging copies). See `createApmInstaller` for the real-dependency
+ * wiring; `installApm` is a thin free-function wrapper.
  */
 
-import { spawn as nodeSpawn } from "node:child_process";
 import { createHash } from "node:crypto";
-import { access, cp, mkdir, readFile, rm } from "node:fs/promises";
 import { join } from "node:path";
 
 /** Installs apm and stages `.claude/` for a task family. */
 export class ApmInstaller {
   /**
-   * @param {object} [deps]
-   * @param {typeof nodeSpawn} [deps.spawn] - Spawn seam (defaults to
-   *   `node:child_process` spawn). Tests inject a fake to avoid shelling out.
+   * @param {object} deps
+   * @param {import("@forwardimpact/libutil/runtime").Runtime} deps.runtime -
+   *   Ambient collaborators; uses `subprocess.spawn` and `fs`.
    */
-  constructor({ spawn } = {}) {
-    this.spawn = spawn ?? nodeSpawn;
+  constructor({ runtime }) {
+    if (!runtime) throw new Error("runtime is required");
+    this.runtime = runtime;
   }
 
   /**
@@ -32,19 +31,21 @@ export class ApmInstaller {
    * @returns {Promise<{stagingDir: string, skillSetHash: string, judgeProfilesDir: string}>}
    */
   async install(family, outputDir) {
+    const fs = this.runtime.fs;
     const stagingDir = join(outputDir, ".apm-staging");
     const stagedClaude = join(stagingDir, ".claude");
     const sourceClaude = join(family.rootPath, ".claude");
     const apmYml = join(family.rootPath, "apm.yml");
 
-    const hasApm = await access(apmYml)
+    const hasApm = await fs
+      .access(apmYml)
       .then(() => true)
       .catch(() => false);
 
     if (hasApm) {
       await this.#runApmInstall(family.rootPath);
       try {
-        await access(sourceClaude);
+        await fs.access(sourceClaude);
       } catch {
         throw new Error(
           `apm install did not produce .claude/ at ${sourceClaude}; check the family's apm.yml`,
@@ -52,14 +53,15 @@ export class ApmInstaller {
       }
     }
 
-    await rm(stagingDir, { recursive: true, force: true });
-    const hasClaudeDir = await access(sourceClaude)
+    await fs.rm(stagingDir, { recursive: true, force: true });
+    const hasClaudeDir = await fs
+      .access(sourceClaude)
       .then(() => true)
       .catch(() => false);
     if (hasClaudeDir) {
-      await cp(sourceClaude, stagedClaude, { recursive: true });
+      await fs.cp(sourceClaude, stagedClaude, { recursive: true });
     } else {
-      await mkdir(stagedClaude, { recursive: true });
+      await fs.mkdir(stagedClaude, { recursive: true });
     }
 
     // Stage the family-local judge profile outside .claude/ so it is available
@@ -67,15 +69,15 @@ export class ApmInstaller {
     const judgeSource = join(family.rootPath, "judge.md");
     const judgeProfilesDir = join(stagingDir, "judge-profiles");
     try {
-      await access(judgeSource);
-      await mkdir(judgeProfilesDir, { recursive: true });
-      await cp(judgeSource, join(judgeProfilesDir, "judge.md"));
+      await fs.access(judgeSource);
+      await fs.mkdir(judgeProfilesDir, { recursive: true });
+      await fs.cp(judgeSource, join(judgeProfilesDir, "judge.md"));
     } catch {}
 
     const lockPath = join(family.rootPath, "apm.lock.yaml");
     let skillSetHash = "";
     try {
-      const lockBytes = await readFile(lockPath);
+      const lockBytes = await fs.readFile(lockPath);
       skillSetHash =
         "sha256:" +
         createHash("sha256").update(normalizeLf(lockBytes)).digest("hex");
@@ -86,25 +88,26 @@ export class ApmInstaller {
     return { stagingDir, skillSetHash, judgeProfilesDir };
   }
 
-  #runApmInstall(cwd) {
-    return new Promise((res, rej) => {
-      const child = this.spawn("apm", ["install", "--target", "claude"], {
-        cwd,
-        stdio: ["ignore", "pipe", "pipe"],
-      });
-      let stderr = "";
-      child.stdout.on("data", () => {});
-      child.stderr.on("data", (d) => {
-        stderr += d.toString();
-      });
-      child.on("error", (e) => {
-        rej(new Error(`failed to spawn apm: ${e.message}`));
-      });
-      child.on("close", (code) => {
-        if (code === 0) res();
-        else rej(new Error(`apm install exited ${code}: ${stderr}`));
-      });
-    });
+  async #runApmInstall(cwd) {
+    const child = this.runtime.subprocess.spawn(
+      "apm",
+      ["install", "--target", "claude"],
+      { cwd, stdio: ["ignore", "pipe", "pipe"] },
+    );
+    // Drain stdout concurrently so the child never blocks on backpressure;
+    // capture stderr for the failure message.
+    let stderr = "";
+    const drainStdout = (async () => {
+      for await (const _chunk of child.stdout) {
+        // discard
+      }
+    })();
+    for await (const chunk of child.stderr) stderr += chunk.toString();
+    await drainStdout;
+    const code = await child.exitCode;
+    if (code !== 0) {
+      throw new Error(`apm install exited ${code}: ${stderr}`);
+    }
   }
 }
 
@@ -119,7 +122,7 @@ function normalizeLf(buf) {
 
 /**
  * Factory function — wires real dependencies.
- * @param {ConstructorParameters<typeof ApmInstaller>[0]} [deps]
+ * @param {ConstructorParameters<typeof ApmInstaller>[0]} deps
  * @returns {ApmInstaller}
  */
 export function createApmInstaller(deps) {
@@ -127,10 +130,11 @@ export function createApmInstaller(deps) {
 }
 
 /**
- * Free-function shorthand for callers that don't need to inject a spawn seam.
+ * Free-function shorthand for callers that thread a runtime bag.
  * @param {import("./task-family.js").TaskFamily} family
  * @param {string} outputDir
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  */
-export function installApm(family, outputDir) {
-  return new ApmInstaller().install(family, outputDir);
+export function installApm(family, outputDir, runtime) {
+  return new ApmInstaller({ runtime }).install(family, outputDir);
 }

package/src/benchmark/env-loader.js

@@ -14,7 +14,6 @@
  * AND rendered (with resolved values) into the agent working directory.
  */
 
-import { readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 
 const ENV_FILES = [".env.local", ".env"];
@@ -48,12 +47,13 @@ export function parseEnvFile(content) {
 
 /**
  * Read and parse an env file, returning [] if the file does not exist.
+ * @param {object} fs - Async filesystem surface (`runtime.fs`).
  * @param {string} filePath
  * @returns {Promise<Array<{key: string, value: string}>>}
  */
-async function readEnvFile(filePath) {
+async function readEnvFile(fs, filePath) {
   try {
-    const content = await readFile(filePath, "utf8");
+    const content = await fs.readFile(filePath, "utf8");
     return parseEnvFile(content);
   } catch (e) {
     if (e.code === "ENOENT") return [];
@@ -62,32 +62,36 @@ async function readEnvFile(filePath) {
 }
 
 /**
- * Load entries into process.env. Existing keys are never overwritten.
+ * Load entries into the process env map. Existing keys are never overwritten.
+ * @param {Record<string, string|undefined>} env - The `runtime.proc.env` map.
  * @param {Array<{key: string, value: string}>} entries
  * @returns {string[]} var names that were loaded
  */
-function applyToProcessEnv(entries) {
+function applyToProcessEnv(env, entries) {
   const names = [];
   for (const { key, value } of entries) {
     names.push(key);
-    if (process.env[key] === undefined) {
-      process.env[key] = value;
+    if (env[key] === undefined) {
+      env[key] = value;
     }
   }
   return names;
 }
 
 /**
- * Load one env file: apply to process.env, record keys in the merged map.
+ * Load one env file: apply to the env map, record keys in the merged map.
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  * @param {string} dir
  * @param {string} file
  * @param {Set<string>} names
  * @param {Map<string, Map<string, true>>} merged
  */
-async function loadOneEnvFile(dir, file, names, merged) {
-  const entries = await readEnvFile(join(dir, file));
+async function loadOneEnvFile(runtime, dir, file, names, merged) {
+  const entries = await readEnvFile(runtime.fs, join(dir, file));
   if (entries.length === 0) return;
-  for (const name of applyToProcessEnv(entries)) names.add(name);
+  for (const name of applyToProcessEnv(runtime.proc.env, entries)) {
+    names.add(name);
+  }
   if (!merged.has(file)) merged.set(file, new Map());
   const fileMap = merged.get(file);
   for (const { key } of entries) {
@@ -96,17 +100,18 @@ async function loadOneEnvFile(dir, file, names, merged) {
 }
 
 /**
- * Scan directories for env files, load into process.env, and collect
+ * Scan directories for env files, load into the env map, and collect
  * a merged key manifest per filename.
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  * @param {string[]} dirs
  * @returns {Promise<{names: Set<string>, merged: Map<string, Map<string, true>>}>}
  */
-async function collectEnvEntries(dirs) {
+async function collectEnvEntries(runtime, dirs) {
   const names = new Set();
   const merged = new Map();
   for (const dir of dirs) {
     for (const file of ENV_FILES) {
-      await loadOneEnvFile(dir, file, names, merged);
+      await loadOneEnvFile(runtime, dir, file, names, merged);
     }
   }
   return { names, merged };
@@ -114,17 +119,22 @@ async function collectEnvEntries(dirs) {
 
 /**
  * Write resolved env files into the agent CWD and warn about empty values.
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  * @param {Map<string, Map<string, true>>} merged
  * @param {string} agentCwd
  */
-async function renderEnvFiles(merged, agentCwd) {
+async function renderEnvFiles(runtime, merged, agentCwd) {
+  const env = runtime.proc.env;
   for (const [file, keyMap] of merged) {
     const keys = [...keyMap.keys()];
-    const resolved = keys.map((key) => `${key}=${process.env[key] ?? ""}`);
-    await writeFile(join(agentCwd, file), resolved.join("\n") + "\n");
-    const empty = keys.filter((key) => !process.env[key]);
+    const resolved = keys.map((key) => `${key}=${env[key] ?? ""}`);
+    await runtime.fs.writeFile(
+      join(agentCwd, file),
+      resolved.join("\n") + "\n",
+    );
+    const empty = keys.filter((key) => !env[key]);
     if (empty.length > 0) {
-      process.stderr.write(
+      runtime.proc.stderr.write(
         `libeval: env warning: ${file} declares vars with no value: ${empty.join(", ")}\n`,
       );
     }
@@ -133,14 +143,16 @@ async function renderEnvFiles(merged, agentCwd) {
 
 /**
  * Discover `.env` / `.env.local` in one or more directories, load them
- * into process.env, and render the resolved values into the agent CWD.
+ * into the process env map, and render the resolved values into the agent CWD.
  *
  * @param {string[]} dirs - Directories to scan (family root, task dir, etc.)
  * @param {string} agentCwd - Agent working directory to render into.
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime - Ambient
+ *   collaborators; uses `fs` (async read/write), `proc.env`, `proc.stderr`.
  * @returns {Promise<string[]>} All var names discovered (for redaction).
  */
-export async function loadEnv(dirs, agentCwd) {
-  const { names, merged } = await collectEnvEntries(dirs);
-  await renderEnvFiles(merged, agentCwd);
+export async function loadEnv(dirs, agentCwd, runtime) {
+  const { names, merged } = await collectEnvEntries(runtime, dirs);
+  await renderEnvFiles(runtime, merged, agentCwd);
   return [...names];
 }

package/src/benchmark/invariants.js

@@ -0,0 +1,128 @@
+/**
+ * Invariants — runs `<task.paths.hooks>/invariants.sh` from the template path
+ * against the post-run agent CWD. The exit code is authoritative for the
+ * verdict; structured per-check rows arrive on fd 3 (`$RESULTS_FD=3`) as NDJSON.
+ *
+ * Subprocess access flows through `runtime.subprocess.spawn`; the fd-3 backing
+ * store and the stderr log use the sync filesystem surface (`runtime.fsSync`) —
+ * the only surface this module touches, per design Decision 7.
+ */
+
+import { join } from "node:path";
+
+/**
+ * @typedef {object} InvariantsResult
+ * @property {"pass" | "fail"} verdict
+ * @property {Array<object>} details
+ * @property {number} exitCode
+ */
+
+/**
+ * Run the task's invariants script.
+ * @param {import("./task-family.js").Task} task
+ * @param {{cwd: string, port: number, runDir: string}} ctx
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
+ * @returns {Promise<InvariantsResult>}
+ */
+export async function runInvariants(task, ctx, runtime) {
+  if (!runtime) throw new Error("runtime is required");
+  if (!task.paths.invariants) {
+    return { verdict: "pass", details: [], exitCode: 0 };
+  }
+  const fsSync = runtime.fsSync;
+  const script = task.paths.invariants;
+  const stderrLogPath = join(ctx.runDir, "invariants.stderr.log");
+
+  // Bun's child_process pipe setup for fd >= 3 is racy under load (it
+  // creates a unix socket pair and the connect() can return ENOENT). Use
+  // a temp file as the fd-3 backing store instead — the script still
+  // writes via `$RESULTS_FD`, but we hand it a real file descriptor.
+  const fd3Path = join(ctx.runDir, "invariants.fd3.ndjson");
+  const fd3File = fsSync.openSync(fd3Path, "w+");
+
+  let child;
+  try {
+    child = runtime.subprocess.spawn(script, [], {
+      env: {
+        ...runtime.proc.env,
+        WORKDIR: ctx.cwd,
+        PORT: String(ctx.port),
+        RESULTS_FD: "3",
+      },
+      stdio: ["inherit", "pipe", "pipe", fd3File],
+    });
+  } catch (e) {
+    tryClose(fsSync, fd3File);
+    throw e;
+  }
+
+  // Drain stdout (do not require consumers to read it); capture stderr to log.
+  const drainStdout = (async () => {
+    for await (const _chunk of child.stdout) {
+      // discard
+    }
+  })();
+  let stderr = "";
+  for await (const chunk of child.stderr) stderr += chunk.toString();
+  await drainStdout;
+  const code = await child.exitCode;
+
+  fsSync.writeFileSync(stderrLogPath, stderr);
+  tryClose(fsSync, fd3File);
+
+  const raw = readAndUnlink(fsSync, fd3Path);
+  const details = [];
+  parseFd3Buffer(raw, details);
+  const exitCode = typeof code === "number" ? code : -1;
+  return {
+    verdict: exitCode === 0 ? "pass" : "fail",
+    details,
+    exitCode,
+  };
+}
+
+function pushRow(line, details) {
+  const trimmed = line.trim();
+  if (!trimmed) return;
+  try {
+    details.push(JSON.parse(trimmed));
+  } catch {
+    details.push({ raw: trimmed, parseError: true });
+  }
+}
+
+function tryClose(fsSync, fd) {
+  try {
+    fsSync.closeSync(fd);
+  } catch {
+    // already closed
+  }
+}
+
+function readAndUnlink(fsSync, path) {
+  let raw = "";
+  try {
+    raw = fsSync.readFileSync(path, "utf8");
+  } catch {
+    // empty
+  }
+  try {
+    fsSync.unlinkSync(path);
+  } catch {
+    // best-effort cleanup
+  }
+  return raw;
+}
+
+/**
+ * Parse the fd-3 buffer (read from the temp-file backing) into one NDJSON
+ * row per detail entry.
+ */
+function parseFd3Buffer(buf, details) {
+  if (!buf) return;
+  const parts = buf.split("\n");
+  for (let i = 0; i < parts.length - 1; i++) pushRow(parts[i], details);
+  if (parts[parts.length - 1].trim()) {
+    pushRow(parts[parts.length - 1], details);
+  }
+}

package/src/benchmark/judge.js

@@ -9,13 +9,11 @@
  *   {{AGENT_INSTRUCTIONS}}  — contents of agent.task.md
  *   {{AGENT_PROFILE}}       — agent profile body (empty string if none)
  *   {{AGENT_TRACE_PATH}}    — path to agent.ndjson
- *   {{SCORING_RESULT}}      — JSON scoring object
+ *   {{INVARIANTS_RESULT}}   — JSON invariants object
  *   {{SKILL_SET_HASH}}      — SHA-256 from apm.lock.yaml
  *   {{TASK_ID}}             — task name (directory under tasks/)
  *   {{TASK_DIR}}            — agent working directory path
  *
- * Legacy alias: {{SCORING}} is accepted as an alias for {{SCORING_RESULT}}.
- *
  * The judge verdict is captured from the orchestration context's
  * `concluded` flag directly — no trace parsing on the happy path.
  * `parseConcludeFromTrace` is preserved for offline analysis and as a
@@ -23,9 +21,6 @@
  * historical run from its judge.ndjson file).
  */
 
-import { createReadStream, createWriteStream } from "node:fs";
-import { readFile } from "node:fs/promises";
-import { createInterface } from "node:readline";
 import { createJudge } from "../judge.js";
 import { createRedactor } from "../redaction.js";
 
@@ -46,17 +41,19 @@ import { createRedactor } from "../redaction.js";
  * Run the judge over a completed task run.
  * @param {import("./task-family.js").Task} task
  * @param {import("./workdir.js").Workdir} workdir
- * @param {import("./scorer.js").ScoringResult} scoring
- * @param {{query: Function, model: string, judgeProfile?: string, profilesDir?: string}} deps
+ * @param {import("./invariants.js").InvariantsResult} invariants
+ * @param {{query: Function, model: string, judgeProfile?: string, profilesDir?: string, runtime: import("@forwardimpact/libutil/runtime").Runtime}} deps
  * @param {JudgeContext} [context]
  * @returns {Promise<JudgeVerdict>}
  */
-export async function runJudge(task, workdir, scoring, deps, context) {
-  const template = await readFile(task.paths.judge, "utf8");
-  const scoringJson = JSON.stringify(scoring, null, 2);
+export async function runJudge(task, workdir, invariants, deps, context) {
+  const runtime = deps.runtime;
+  if (!runtime) throw new Error("runtime is required");
+  const fs = runtime.fs;
+  const template = await fs.readFile(task.paths.judge, "utf8");
+  const invariantsJson = JSON.stringify(invariants, null, 2);
   const taskText = template
-    .replaceAll("{{SCORING_RESULT}}", scoringJson)
-    .replaceAll("{{SCORING}}", scoringJson)
+    .replaceAll("{{INVARIANTS_RESULT}}", invariantsJson)
     .replaceAll("{{AGENT_TRACE_PATH}}", workdir.agentTracePath)
     .replaceAll("{{AGENT_INSTRUCTIONS}}", context?.agentInstructions ?? "")
     .replaceAll("{{AGENT_PROFILE}}", context?.agentProfile ?? "")
@@ -64,7 +61,7 @@ export async function runJudge(task, workdir, scoring, deps, context) {
     .replaceAll("{{TASK_ID}}", task.id)
     .replaceAll("{{TASK_DIR}}", workdir.cwd);
 
-  const output = createWriteStream(workdir.judgeTracePath);
+  const output = fs.createWriteStream(workdir.judgeTracePath);
   const judge = createJudge({
     cwd: workdir.cwd,
     query: deps.query,
@@ -73,7 +70,8 @@ export async function runJudge(task, workdir, scoring, deps, context) {
     judgeProfile: deps.judgeProfile,
     profilesDir: deps.profilesDir,
     maxTurns: 25,
-    redactor: createRedactor(),
+    redactor: createRedactor({ runtime }),
+    runtime,
   });
 
   let outcome;
@@ -98,13 +96,14 @@ export async function runJudge(task, workdir, scoring, deps, context) {
  * and map the verdict (`success → pass`, `failure → fail`). Preserved for
  * offline analysis; not used on the runtime happy path.
  * @param {string} tracePath
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  * @returns {Promise<JudgeVerdict | null>}
  */
-export async function parseConcludeFromTrace(tracePath) {
-  const stream = createReadStream(tracePath);
-  const rl = createInterface({ input: stream, crlfDelay: Infinity });
+export async function parseConcludeFromTrace(tracePath, runtime) {
+  if (!runtime) throw new Error("runtime is required");
+  const content = await runtime.fs.readFile(tracePath, "utf8");
   let last = null;
-  for await (const line of rl) {
+  for (const line of content.split("\n")) {
     const candidate = extractConcludeInput(line);
     if (candidate) last = candidate;
   }

package/src/benchmark/npm-installer.js

@@ -3,23 +3,22 @@
  * is present, then copies the resulting `node_modules/` into the staging
  * directory so WorkdirManager can seed each per-task CWD.
  *
- * Symmetric to ApmInstaller: constructor injection of `spawn` for testability,
- * factory function, and a free-function shorthand.
+ * Symmetric to ApmInstaller: the subprocess and filesystem flow through the
+ * injected `runtime` bag (`runtime.subprocess.spawn` + `runtime.fs`).
  */
 
-import { spawn as nodeSpawn } from "node:child_process";
-import { access, cp } from "node:fs/promises";
 import { join } from "node:path";
 
 /** Run `bun install` in the family root and stage node_modules/ for per-task CWDs. */
 export class NpmInstaller {
   /**
-   * @param {object} [deps]
-   * @param {typeof nodeSpawn} [deps.spawn] - Spawn seam (defaults to
-   *   `node:child_process` spawn). Tests inject a fake to avoid shelling out.
+   * @param {object} deps
+   * @param {import("@forwardimpact/libutil/runtime").Runtime} deps.runtime -
+   *   Ambient collaborators; uses `subprocess.spawn` and `fs`.
    */
-  constructor({ spawn } = {}) {
-    this.spawn = spawn ?? nodeSpawn;
+  constructor({ runtime }) {
+    if (!runtime) throw new Error("runtime is required");
+    this.runtime = runtime;
   }
 
   /**
@@ -28,8 +27,10 @@ export class NpmInstaller {
    * @returns {Promise<void>}
    */
   async install(family, stagingDir) {
+    const fs = this.runtime.fs;
     const pkgJson = join(family.rootPath, "package.json");
-    const hasPkg = await access(pkgJson)
+    const hasPkg = await fs
+      .access(pkgJson)
       .then(() => true)
       .catch(() => false);
     if (!hasPkg) return;
@@ -38,37 +39,35 @@ export class NpmInstaller {
 
     const sourceModules = join(family.rootPath, "node_modules");
     try {
-      await access(sourceModules);
+      await fs.access(sourceModules);
     } catch {
       throw new Error(
         `bun install did not produce node_modules/ at ${sourceModules}; check the family's package.json`,
       );
     }
 
-    await cp(sourceModules, join(stagingDir, "node_modules"), {
+    await fs.cp(sourceModules, join(stagingDir, "node_modules"), {
       recursive: true,
     });
   }
 
-  #runBunInstall(cwd) {
-    return new Promise((res, rej) => {
-      const child = this.spawn("bun", ["install"], {
-        cwd,
-        stdio: ["ignore", "pipe", "pipe"],
-      });
-      let stderr = "";
-      child.stdout.on("data", () => {});
-      child.stderr.on("data", (d) => {
-        stderr += d.toString();
-      });
-      child.on("error", (e) => {
-        rej(new Error(`failed to spawn bun: ${e.message}`));
-      });
-      child.on("close", (code) => {
-        if (code === 0) res();
-        else rej(new Error(`bun install exited ${code}: ${stderr}`));
-      });
+  async #runBunInstall(cwd) {
+    const child = this.runtime.subprocess.spawn("bun", ["install"], {
+      cwd,
+      stdio: ["ignore", "pipe", "pipe"],
     });
+    let stderr = "";
+    const drainStdout = (async () => {
+      for await (const _chunk of child.stdout) {
+        // discard
+      }
+    })();
+    for await (const chunk of child.stderr) stderr += chunk.toString();
+    await drainStdout;
+    const code = await child.exitCode;
+    if (code !== 0) {
+      throw new Error(`bun install exited ${code}: ${stderr}`);
+    }
   }
 }
 
@@ -78,10 +77,11 @@ export function createNpmInstaller(deps) {
 }
 
 /**
- * Free-function shorthand for callers that don't need to inject a spawn seam.
+ * Free-function shorthand for callers that thread a runtime bag.
  * @param {import("./task-family.js").TaskFamily} family
  * @param {string} stagingDir
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  */
-export function installNpm(family, stagingDir) {
-  return new NpmInstaller().install(family, stagingDir);
+export function installNpm(family, stagingDir, runtime) {
+  return new NpmInstaller({ runtime }).install(family, stagingDir);
 }