@forwardimpact/libeval 0.1.50 → 0.1.51

package/src/commands/output.js

@@ -6,29 +6,28 @@ import { createTraceCollector } from "@forwardimpact/libeval";
  *
  * Usage: fit-eval output [--format=json|text] < trace.ndjson
  *
- * @param {object} values - Parsed option values from cli.parse()
- * @param {string[]} args - Positional arguments
+ * @param {import("@forwardimpact/libcli").InvocationContext} ctx
+ * @returns {Promise<{ok: true}>}
  */
-export async function runOutputCommand(values, _args) {
+export async function runOutputCommand(ctx) {
+  const values = ctx.options;
+  const runtime = ctx.deps.runtime;
   const format =
     values.format === "text" || values.format === "json"
       ? values.format
       : "json";
   const collector = createTraceCollector();
 
-  const chunks = [];
-  for await (const chunk of process.stdin) {
-    chunks.push(chunk);
-  }
-  const input = Buffer.concat(chunks).toString("utf8");
-
-  for (const line of input.split("\n")) {
+  // `runtime.proc.stdin` is an AsyncIterable of UTF-8 lines (newline-split by
+  // the runtime), so each yielded value is exactly one NDJSON record.
+  for await (const line of runtime.proc.stdin) {
     collector.addLine(line);
   }
 
   if (format === "text") {
-    process.stdout.write(collector.toText() + "\n");
+    runtime.proc.stdout.write(collector.toText() + "\n");
   } else {
-    process.stdout.write(JSON.stringify(collector.toJSON()) + "\n");
+    runtime.proc.stdout.write(JSON.stringify(collector.toJSON()) + "\n");
   }
+  return { ok: true };
 }

package/src/commands/run.js

@@ -12,10 +12,14 @@ import { createServiceConfig } from "@forwardimpact/libconfig";
 /**
  * Parse and validate run command options from parsed values.
  * @param {object} values - Parsed option values from cli.parse()
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  * @returns {{ taskContent: string, cwd: string, model: string, maxTurns: number, outputPath: string|undefined, agentProfile: string|undefined, allowedTools: string[] }}
  */
-function parseRunOptions(values) {
-  const { task: taskContent, amend: taskAmend } = resolveTaskContent(values);
+function parseRunOptions(values, runtime) {
+  const { task: taskContent, amend: taskAmend } = resolveTaskContent(
+    values,
+    runtime,
+  );
   const maxTurnsRaw = values["max-turns"] ?? "50";
 
   return {
@@ -39,10 +43,11 @@ function parseRunOptions(values) {
  *
  * Usage: fit-eval run [options]
  *
- * @param {object} values - Parsed option values from cli.parse()
- * @param {string[]} args - Positional arguments
+ * @param {import("@forwardimpact/libcli").InvocationContext} ctx
+ * @returns {Promise<{ok: boolean, code?: number, error?: string}>}
  */
-export async function runRunCommand(values, _args) {
+export async function runRunCommand(ctx) {
+  const runtime = ctx.deps.runtime;
   const {
     taskContent,
     taskAmend,
@@ -53,19 +58,23 @@ export async function runRunCommand(values, _args) {
     agentProfile,
     allowedTools,
     mcpServer,
-  } = parseRunOptions(values);
+  } = parseRunOptions(ctx.options, runtime);
 
   // Build the redactor as the first observable side-effect after option
   // parsing — the env snapshot must freeze BEFORE any in-process
-  // process.env writes the command performs (e.g. LIBEVAL_AGENT_PROFILE).
-  const redactor = createRedactor();
+  // env writes the command performs (e.g. LIBEVAL_AGENT_PROFILE).
+  const redactor = createRedactor({ runtime });
 
   // When --output is specified, stream text to stdout while writing NDJSON to file.
   // Otherwise, write NDJSON directly to stdout (backwards-compatible).
   const fileStream = outputPath ? createWriteStream(outputPath) : null;
   const output = fileStream
-    ? createTeeWriter({ fileStream, textStream: process.stdout, mode: "raw" })
-    : process.stdout;
+    ? createTeeWriter({
+        fileStream,
+        textStream: runtime.proc.stdout,
+        mode: "raw",
+      })
+    : runtime.proc.stdout;
 
   const counter = new SequenceCounter();
   const devNull = new Writable({
@@ -93,7 +102,7 @@ export async function runRunCommand(values, _args) {
   }
 
   if (agentProfile) {
-    process.env.LIBEVAL_AGENT_PROFILE = agentProfile;
+    runtime.proc.env.LIBEVAL_AGENT_PROFILE = agentProfile;
   }
 
   const systemPrompt = agentProfile
@@ -116,6 +125,7 @@ export async function runRunCommand(values, _args) {
     taskAmend,
     mcpServers,
     redactor,
+    runtime,
   });
 
   const result = await runner.run(taskContent);
@@ -125,5 +135,5 @@ export async function runRunCommand(values, _args) {
     await new Promise((r) => fileStream.end(r));
   }
 
-  process.exit(result.success ? 0 : 1);
+  return result.success ? { ok: true } : { ok: false, code: 1, error: "" };
 }

package/src/commands/supervise.js

@@ -1,6 +1,5 @@
-import { createWriteStream, mkdtempSync } from "node:fs";
+import { createWriteStream } from "node:fs";
 import { resolve, join } from "node:path";
-import { tmpdir } from "node:os";
 import { createSupervisor } from "../supervisor.js";
 import { createRedactor } from "../redaction.js";
 import { createTeeWriter } from "../tee-writer.js";
@@ -10,19 +9,27 @@ import { createServiceConfig } from "@forwardimpact/libconfig";
 /**
  * Parse all supervise flags from parsed values into an options object.
  * @param {object} values - Parsed option values from cli.parse()
- * @returns {object}
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
+ * @returns {Promise<object>}
  */
-export function parseSuperviseOptions(values) {
-  const { task: taskContent, amend: taskAmend } = resolveTaskContent(values);
+export async function parseSuperviseOptions(values, runtime) {
+  const { task: taskContent, amend: taskAmend } = resolveTaskContent(
+    values,
+    runtime,
+  );
   const supervisorAllowedToolsRaw = values["supervisor-allowed-tools"];
 
+  const tmpRoot = runtime.proc.env.TMPDIR ?? "/tmp";
+  const agentCwd = resolve(
+    values["agent-cwd"] ??
+      (await runtime.fs.mkdtemp(join(tmpRoot, "fit-eval-agent-"))),
+  );
+
   return {
     taskContent,
     taskAmend,
     supervisorCwd: resolve(values["supervisor-cwd"] ?? "."),
-    agentCwd: resolve(
-      values["agent-cwd"] ?? mkdtempSync(join(tmpdir(), "fit-eval-agent-")),
-    ),
+    agentCwd,
     agentModel: values["agent-model"] ?? "claude-opus-4-7[1m]",
     supervisorModel: values["lead-model"] ?? "claude-opus-4-7[1m]",
     maxTurns: (() => {
@@ -50,16 +57,17 @@ export function parseSuperviseOptions(values) {
  *
  * Usage: fit-eval supervise [options]
  *
- * @param {object} values - Parsed option values from cli.parse()
- * @param {string[]} args - Positional arguments
+ * @param {import("@forwardimpact/libcli").InvocationContext} ctx
+ * @returns {Promise<{ok: boolean, code?: number, error?: string}>}
  */
-export async function runSuperviseCommand(values, _args) {
-  const opts = parseSuperviseOptions(values);
+export async function runSuperviseCommand(ctx) {
+  const runtime = ctx.deps.runtime;
+  const opts = await parseSuperviseOptions(ctx.options, runtime);
 
   // Build the redactor as the first observable side-effect after option
   // parsing — the env snapshot must freeze BEFORE any in-process
-  // process.env writes the command performs (e.g. LIBEVAL_AGENT_PROFILE).
-  const redactor = createRedactor();
+  // env writes the command performs (e.g. LIBEVAL_AGENT_PROFILE).
+  const redactor = createRedactor({ runtime });
 
   // When --output is specified, stream text to stdout while writing NDJSON to file.
   // Otherwise, write NDJSON directly to stdout (backwards-compatible).
@@ -69,10 +77,10 @@ export async function runSuperviseCommand(values, _args) {
   const output = fileStream
     ? createTeeWriter({
         fileStream,
-        textStream: process.stdout,
+        textStream: runtime.proc.stdout,
         mode: "supervised",
       })
-    : process.stdout;
+    : runtime.proc.stdout;
 
   let agentMcpServers = null;
   if (opts.mcpServer) {
@@ -88,7 +96,7 @@ export async function runSuperviseCommand(values, _args) {
   }
 
   if (opts.agentProfile) {
-    process.env.LIBEVAL_AGENT_PROFILE = opts.agentProfile;
+    runtime.proc.env.LIBEVAL_AGENT_PROFILE = opts.agentProfile;
   }
 
   const { query } = await import("@anthropic-ai/claude-agent-sdk");
@@ -107,6 +115,7 @@ export async function runSuperviseCommand(values, _args) {
     taskAmend: opts.taskAmend,
     agentMcpServers,
     redactor,
+    runtime,
   });
 
   const result = await supervisor.run(opts.taskContent);
@@ -116,5 +125,5 @@ export async function runSuperviseCommand(values, _args) {
     await new Promise((r) => fileStream.end(r));
   }
 
-  process.exit(result.success ? 0 : 1);
+  return result.success ? { ok: true } : { ok: false, code: 1, error: "" };
 }

package/src/commands/task-input.js

@@ -1,4 +1,3 @@
-import { readFileSync } from "node:fs";
 import { composeTaskFromGitHubEvent } from "../events/github.js";
 
 /**
@@ -11,9 +10,12 @@ import { composeTaskFromGitHubEvent } from "../events/github.js";
  * works as before.
  *
  * @param {object} values - Parsed option values from cli.parse()
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime - Ambient
+ *   collaborators; `fsSync.readFileSync` loads `--task-file`/`--task-event`
+ *   and `proc.env` resolves `GITHUB_EVENT_NAME`.
  * @returns {{ task: string, amend: string | undefined }}
  */
-export function resolveTaskContent(values) {
+export function resolveTaskContent(values, runtime) {
   const taskFile = values["task-file"];
   const taskText = values["task-text"];
   const taskEvent = values["task-event"];
@@ -33,17 +35,20 @@ export function resolveTaskContent(values) {
   const amendFlag = values["task-amend"] ?? undefined;
 
   if (taskFile) {
-    return { task: readFileSync(taskFile, "utf8"), amend: amendFlag };
+    return {
+      task: runtime.fsSync.readFileSync(taskFile, "utf8"),
+      amend: amendFlag,
+    };
   }
   if (taskText) {
     return { task: taskText, amend: amendFlag };
   }
 
-  const eventName = process.env.GITHUB_EVENT_NAME;
+  const eventName = runtime.proc.env.GITHUB_EVENT_NAME;
   if (!eventName) {
     throw new Error("--task-event requires GITHUB_EVENT_NAME to be set");
   }
-  const payload = JSON.parse(readFileSync(taskEvent, "utf8"));
+  const payload = JSON.parse(runtime.fsSync.readFileSync(taskEvent, "utf8"));
   const composed = composeTaskFromGitHubEvent(payload, eventName);
   return { task: composed.task, amend: amendFlag ?? composed.amend };
 }

package/src/commands/trace.js

@@ -1,153 +1,227 @@
-import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { createTraceCollector } from "@forwardimpact/libeval";
 import { createTraceQuery } from "../trace-query.js";
 import { createTraceGitHub } from "../trace-github.js";
 import { stripSignatures } from "../signature-filter.js";
 
+// Every handler receives a libcli `InvocationContext`:
+//   ctx.options — parsed flag values (`cli.parse().values`)
+//   ctx.args    — named positionals declared on the subcommand
+//   ctx.deps    — host-injected collaborators: `{ runtime, config }`
+// Handlers read/write the filesystem and stdout exclusively through
+// `ctx.deps.runtime` and return `{ ok: true }` on success.
+
 // --- GitHub commands ---
 
 /**
  * List recent workflow runs matching a pattern.
- * @param {object} values - Parsed option values
- * @param {string[]} args - [pattern?]
- * @param {{config: import("@forwardimpact/libconfig").Config}} ctx
+ * @param {import("@forwardimpact/libcli").InvocationContext} ctx
  */
-export async function runRunsCommand(values, args, ctx) {
+export async function runRunsCommand(ctx) {
+  const { runtime, config } = ctx.deps;
   const gh = await createTraceGitHub({
-    token: ctx.config.ghToken(),
-    repo: values.repo,
+    token: config.ghToken(),
+    repo: ctx.options.repo,
+    runtime,
   });
-  const pattern = args[0] ?? "agent";
-  const lookback = values.lookback ?? "7d";
+  const pattern = ctx.args.pattern ?? "agent";
+  const lookback = ctx.options.lookback ?? "7d";
   const runs = await gh.listRuns({ pattern, lookback });
-  writeJSON(runs, values);
+  writeJSON(runtime, runs, ctx.options);
+  return { ok: true };
 }
 
 /**
  * Download a trace artifact and auto-convert to structured JSON.
- * @param {object} values - Parsed option values
- * @param {string[]} args - [run-id]
- * @param {{config: import("@forwardimpact/libconfig").Config}} ctx
+ * @param {import("@forwardimpact/libcli").InvocationContext} ctx
  */
-export async function runDownloadCommand(values, args, ctx) {
+export async function runDownloadCommand(ctx) {
+  const { runtime, config } = ctx.deps;
   const gh = await createTraceGitHub({
-    token: ctx.config.ghToken(),
-    repo: values.repo,
+    token: config.ghToken(),
+    repo: ctx.options.repo,
+    runtime,
   });
-  const result = await gh.downloadTrace(args[0], {
-    dir: values.dir,
-    name: values.artifact,
+  const result = await gh.downloadTrace(ctx.args["run-id"], {
+    dir: ctx.options.dir,
+    name: ctx.options.artifact,
   });
 
   const ndjsonFile = result.files.find((f) => f.endsWith(".ndjson"));
   if (ndjsonFile) {
     const ndjsonPath = join(result.dir, ndjsonFile);
     const collector = createTraceCollector();
-    for (const line of readFileSync(ndjsonPath, "utf8").split("\n")) {
+    for (const line of runtime.fsSync
+      .readFileSync(ndjsonPath, "utf8")
+      .split("\n")) {
       collector.addLine(line);
     }
     const structuredPath = join(result.dir, "structured.json");
-    writeFileSync(structuredPath, JSON.stringify(collector.toJSON()) + "\n");
+    runtime.fsSync.writeFileSync(
+      structuredPath,
+      JSON.stringify(collector.toJSON()) + "\n",
+    );
     result.files.push("structured.json");
   }
 
-  writeJSON(result, values);
+  writeJSON(runtime, result, ctx.options);
+  return { ok: true };
 }
 
 // --- Query commands ---
 
-/** @param {object} values @param {string[]} args - [file] */
-export async function runOverviewCommand(values, args) {
-  writeJSON(loadTrace(args[0]).overview(), values);
+/** @param {import("@forwardimpact/libcli").InvocationContext} ctx */
+export async function runOverviewCommand(ctx) {
+  const { runtime } = ctx.deps;
+  writeJSON(runtime, loadTrace(runtime, ctx.args.file).overview(), ctx.options);
+  return { ok: true };
 }
 
-/** @param {object} values @param {string[]} args - [file] */
-export async function runCountCommand(values, args) {
-  process.stdout.write(String(loadTrace(args[0]).count()) + "\n");
+/** @param {import("@forwardimpact/libcli").InvocationContext} ctx */
+export async function runCountCommand(ctx) {
+  const { runtime } = ctx.deps;
+  runtime.proc.stdout.write(
+    String(loadTrace(runtime, ctx.args.file).count()) + "\n",
+  );
+  return { ok: true };
 }
 
-/** @param {object} values @param {string[]} args - [file, from, to] */
-export async function runBatchCommand(values, args) {
+/** @param {import("@forwardimpact/libcli").InvocationContext} ctx */
+export async function runBatchCommand(ctx) {
+  const { runtime } = ctx.deps;
   writeJSON(
-    loadTrace(args[0]).batch(parseInt(args[1], 10), parseInt(args[2], 10)),
-    values,
+    runtime,
+    loadTrace(runtime, ctx.args.file).batch(
+      parseInt(ctx.args.from, 10),
+      parseInt(ctx.args.to, 10),
+    ),
+    ctx.options,
   );
+  return { ok: true };
 }
 
-/** @param {object} values @param {string[]} args - [file, N?] */
-export async function runHeadCommand(values, args) {
-  const n = args[1] ? parseInt(args[1], 10) : 10;
-  writeJSON(loadTrace(args[0]).head(n), values);
+/** @param {import("@forwardimpact/libcli").InvocationContext} ctx */
+export async function runHeadCommand(ctx) {
+  const { runtime } = ctx.deps;
+  const n = ctx.args.n ? parseInt(ctx.args.n, 10) : 10;
+  writeJSON(runtime, loadTrace(runtime, ctx.args.file).head(n), ctx.options);
+  return { ok: true };
 }
 
-/** @param {object} values @param {string[]} args - [file, N?] */
-export async function runTailCommand(values, args) {
-  const n = args[1] ? parseInt(args[1], 10) : 10;
-  writeJSON(loadTrace(args[0]).tail(n), values);
+/** @param {import("@forwardimpact/libcli").InvocationContext} ctx */
+export async function runTailCommand(ctx) {
+  const { runtime } = ctx.deps;
+  const n = ctx.args.n ? parseInt(ctx.args.n, 10) : 10;
+  writeJSON(runtime, loadTrace(runtime, ctx.args.file).tail(n), ctx.options);
+  return { ok: true };
 }
 
-/** @param {object} values @param {string[]} args - [file, pattern] */
-export async function runSearchCommand(values, args) {
-  const limit = values.limit ? parseInt(values.limit, 10) : 50;
-  const context = values.context ? parseInt(values.context, 10) : 0;
-  const full = values.full ?? false;
+/** @param {import("@forwardimpact/libcli").InvocationContext} ctx */
+export async function runSearchCommand(ctx) {
+  const { runtime } = ctx.deps;
+  const limit = ctx.options.limit ? parseInt(ctx.options.limit, 10) : 50;
+  const context = ctx.options.context ? parseInt(ctx.options.context, 10) : 0;
+  const full = ctx.options.full ?? false;
   writeJSON(
-    loadTrace(args[0]).search(args[1], { limit, context, full }),
-    values,
+    runtime,
+    loadTrace(runtime, ctx.args.file).search(ctx.args.pattern, {
+      limit,
+      context,
+      full,
+    }),
+    ctx.options,
   );
+  return { ok: true };
 }
 
-/** @param {object} values @param {string[]} args - [file] */
-export async function runToolsCommand(values, args) {
-  writeJSON(loadTrace(args[0]).toolFrequency(), values);
+/** @param {import("@forwardimpact/libcli").InvocationContext} ctx */
+export async function runToolsCommand(ctx) {
+  const { runtime } = ctx.deps;
+  writeJSON(
+    runtime,
+    loadTrace(runtime, ctx.args.file).toolFrequency(),
+    ctx.options,
+  );
+  return { ok: true };
 }
 
-/** @param {object} values @param {string[]} args - [file, name] */
-export async function runToolCommand(values, args) {
-  writeJSON(loadTrace(args[0]).tool(args[1]), values);
+/** @param {import("@forwardimpact/libcli").InvocationContext} ctx */
+export async function runToolCommand(ctx) {
+  const { runtime } = ctx.deps;
+  writeJSON(
+    runtime,
+    loadTrace(runtime, ctx.args.file).tool(ctx.args.name),
+    ctx.options,
+  );
+  return { ok: true };
 }
 
-/** @param {object} values @param {string[]} args - [file] */
-export async function runErrorsCommand(values, args) {
-  writeJSON(loadTrace(args[0]).errors(), values);
+/** @param {import("@forwardimpact/libcli").InvocationContext} ctx */
+export async function runErrorsCommand(ctx) {
+  const { runtime } = ctx.deps;
+  writeJSON(runtime, loadTrace(runtime, ctx.args.file).errors(), ctx.options);
+  return { ok: true };
 }
 
-/** @param {object} values @param {string[]} args - [file] */
-export async function runReasoningCommand(values, args) {
-  const from = values.from ? parseInt(values.from, 10) : undefined;
-  const to = values.to ? parseInt(values.to, 10) : undefined;
-  writeJSON(loadTrace(args[0]).reasoning({ from, to }), values);
+/** @param {import("@forwardimpact/libcli").InvocationContext} ctx */
+export async function runReasoningCommand(ctx) {
+  const { runtime } = ctx.deps;
+  const from = ctx.options.from ? parseInt(ctx.options.from, 10) : undefined;
+  const to = ctx.options.to ? parseInt(ctx.options.to, 10) : undefined;
+  writeJSON(
+    runtime,
+    loadTrace(runtime, ctx.args.file).reasoning({ from, to }),
+    ctx.options,
+  );
+  return { ok: true };
 }
 
-/** @param {object} values @param {string[]} args - [file] */
-export async function runTimelineCommand(values, args) {
-  const lines = loadTrace(args[0]).timeline();
-  process.stdout.write(lines.join("\n") + "\n");
+/** @param {import("@forwardimpact/libcli").InvocationContext} ctx */
+export async function runTimelineCommand(ctx) {
+  const { runtime } = ctx.deps;
+  const lines = loadTrace(runtime, ctx.args.file).timeline();
+  runtime.proc.stdout.write(lines.join("\n") + "\n");
+  return { ok: true };
 }
 
-/** @param {object} values @param {string[]} args - [file] */
-export async function runStatsCommand(values, args) {
-  writeJSON(loadTrace(args[0]).stats(), values);
+/** @param {import("@forwardimpact/libcli").InvocationContext} ctx */
+export async function runStatsCommand(ctx) {
+  const { runtime } = ctx.deps;
+  writeJSON(runtime, loadTrace(runtime, ctx.args.file).stats(), ctx.options);
+  return { ok: true };
 }
 
-/** @param {object} values @param {string[]} args - [file] */
-export async function runInitCommand(values, args) {
-  writeJSON(loadTrace(args[0]).init(), values);
+/** @param {import("@forwardimpact/libcli").InvocationContext} ctx */
+export async function runInitCommand(ctx) {
+  const { runtime } = ctx.deps;
+  writeJSON(runtime, loadTrace(runtime, ctx.args.file).init(), ctx.options);
+  return { ok: true };
 }
 
-/** @param {object} values @param {string[]} args - [file, index] */
-export async function runTurnCommand(values, args) {
-  writeJSON(loadTrace(args[0]).turn(parseInt(args[1], 10)), values);
+/** @param {import("@forwardimpact/libcli").InvocationContext} ctx */
+export async function runTurnCommand(ctx) {
+  const { runtime } = ctx.deps;
+  writeJSON(
+    runtime,
+    loadTrace(runtime, ctx.args.file).turn(parseInt(ctx.args.index, 10)),
+    ctx.options,
+  );
+  return { ok: true };
 }
 
-/** @param {object} values @param {string[]} args - [file] */
-export async function runFilterCommand(values, args) {
+/** @param {import("@forwardimpact/libcli").InvocationContext} ctx */
+export async function runFilterCommand(ctx) {
+  const { runtime } = ctx.deps;
   const opts = {};
-  if (values.role) opts.role = values.role;
-  if (values.tool) opts.toolName = values.tool;
-  if (values.error) opts.isError = true;
-  writeJSON(loadTrace(args[0]).filter(opts), values);
+  if (ctx.options.role) opts.role = ctx.options.role;
+  if (ctx.options.tool) opts.toolName = ctx.options.tool;
+  if (ctx.options.error) opts.isError = true;
+  writeJSON(
+    runtime,
+    loadTrace(runtime, ctx.args.file).filter(opts),
+    ctx.options,
+  );
+  return { ok: true };
 }
 
 // --- Split command ---
@@ -168,24 +242,24 @@ const STRUCTURAL_ROLES = new Set(["agent", "supervisor", "facilitator"]);
  * `staff-engineer`) classify as agents with the profile in the participant
  * slot. Orchestrator events and invalid source names are dropped.
  *
- * @param {object} values - Parsed option values
- * @param {string[]} args - [file]
+ * @param {import("@forwardimpact/libcli").InvocationContext} ctx
  */
-export async function runSplitCommand(values, args) {
-  const file = args[0];
-  if (!file) throw new Error("split: missing input file");
+export async function runSplitCommand(ctx) {
+  const { runtime } = ctx.deps;
+  const file = ctx.args.file;
+  if (!file) return { ok: false, code: 1, error: "split: missing input file" };
 
-  const mode = values.mode;
-  if (!mode) throw new Error("split: --mode is required");
+  const mode = ctx.options.mode;
+  if (!mode) return { ok: false, code: 1, error: "split: --mode is required" };
   if (!["run", "supervise", "facilitate"].includes(mode)) {
-    throw new Error(`split: invalid --mode "${mode}"`);
+    return { ok: false, code: 1, error: `split: invalid --mode "${mode}"` };
   }
 
-  const caseId = values.case ?? "default";
-  const outputDir = values["output-dir"] || dirname(file);
-  mkdirSync(outputDir, { recursive: true });
+  const caseId = ctx.options.case ?? "default";
+  const outputDir = ctx.options["output-dir"] || dirname(file);
+  runtime.fsSync.mkdirSync(outputDir, { recursive: true });
 
-  const buckets = parseBuckets(readFileSync(file, "utf8"));
+  const buckets = parseBuckets(runtime.fsSync.readFileSync(file, "utf8"));
 
   for (const [source, lines] of buckets.entries()) {
     if (!VALID_SOURCE_NAME.test(source)) continue;
@@ -194,8 +268,9 @@ export async function runSplitCommand(values, args) {
       outputDir,
       `trace--${caseId}--${source}.${role}.ndjson`,
     );
-    writeFileSync(outPath, lines.join("\n") + "\n");
+    runtime.fsSync.writeFileSync(outPath, lines.join("\n") + "\n");
   }
+  return { ok: true };
 }
 
 /**
@@ -234,11 +309,12 @@ function parseBuckets(content) {
 
 /**
  * Load a trace file. Supports structured JSON and raw NDJSON.
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  * @param {string} file
  * @returns {import("../trace-query.js").TraceQuery}
  */
-function loadTrace(file) {
-  const content = readFileSync(file, "utf8");
+function loadTrace(runtime, file) {
+  const content = runtime.fsSync.readFileSync(file, "utf8");
 
   try {
     const parsed = JSON.parse(content);
@@ -260,10 +336,11 @@ function loadTrace(file) {
  * Write JSON output to stdout. By default strips `thinking.signature`
  * base64 blobs from the payload so they don't dominate terminal output;
  * pass `--signatures` (surfaced as `values.signatures`) to keep them.
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  * @param {*} data
  * @param {object} [values]
  */
-function writeJSON(data, values = {}) {
+function writeJSON(runtime, data, values = {}) {
   const output = values.signatures ? data : stripSignatures(data);
-  process.stdout.write(JSON.stringify(output, null, 2) + "\n");
+  runtime.proc.stdout.write(JSON.stringify(output, null, 2) + "\n");
 }