@forwardimpact/libharness 3.0.2 → 3.2.0

package/src/commands/trace.js

@@ -3,6 +3,7 @@ import { isoTimestamp } from "@forwardimpact/libutil";
 import { createTraceCollector, sumTraceCost } from "@forwardimpact/libharness";
 import { createTraceQuery } from "../trace-query.js";
 import { createTraceGitHub } from "../trace-github.js";
+import { splitTrace } from "../trace-split.js";
 import { stripSignatures } from "../signature-filter.js";
 import { runOver, aggregate, compareTwo } from "../trace-multi.js";
 import {
@@ -100,7 +101,9 @@ export async function runRunsCommand(ctx) {
 }
 
 /**
- * Resolve a participant's lane trace for a known run id in one keyed lookup.
+ * Resolve a trace lane for a known run id in one keyed lookup. The key may
+ * be an exact member filename, a case id, or a participant name; ambiguous
+ * keys error with the matching candidates.
  * @param {import("@forwardimpact/libcli").InvocationContext} ctx
  */
 export async function runFindCommand(ctx) {
@@ -110,7 +113,7 @@ export async function runFindCommand(ctx) {
     repo: ctx.options.repo,
     runtime,
   });
-  const result = await gh.findByKey(ctx.args["run-id"], ctx.args.participant, {
+  const result = await gh.findByKey(ctx.args["run-id"], ctx.args.key, {
     dir: ctx.options.dir,
   });
   writeJSON(runtime, result, ctx.options);
@@ -118,7 +121,22 @@ export async function runFindCommand(ctx) {
 }
 
 /**
- * Download a trace artifact and auto-convert to structured JSON.
+ * The single `.ndjson` member to auto-convert to structured JSON, or null
+ * when the artifact carries zero or several. Multi-member bundles (kata
+ * dispatch, harness matrix, eval shards) get no `structured.json` — the
+ * prior first-member conversion picked an arbitrary lane, which was actively
+ * misleading; the analysis verbs read the `.ndjson` members directly.
+ * @param {string[]} files - Extracted member paths, relative to the artifact dir.
+ * @returns {string|null}
+ */
+export function structuredConvertTarget(files) {
+  const ndjson = files.filter((f) => f.endsWith(".ndjson"));
+  return ndjson.length === 1 ? ndjson[0] : null;
+}
+
+/**
+ * Download a trace artifact; auto-convert to structured JSON only when the
+ * artifact carries exactly one `.ndjson` member.
  * @param {import("@forwardimpact/libcli").InvocationContext} ctx
  */
 export async function runDownloadCommand(ctx) {
@@ -133,7 +151,7 @@ export async function runDownloadCommand(ctx) {
     name: ctx.options.artifact,
   });
 
-  const ndjsonFile = result.files.find((f) => f.endsWith(".ndjson"));
+  const ndjsonFile = structuredConvertTarget(result.files);
   if (ndjsonFile) {
     const ndjsonPath = join(result.dir, ndjsonFile);
     const collector = createTraceCollector({
@@ -496,27 +514,13 @@ export async function runCompareCommand(ctx) {
 
 // --- Split command ---
 
-/**
- * A valid source name starts with a lowercase letter. The rest uses lowercase
- * alphanumeric characters or hyphens.
- */
-const VALID_SOURCE_NAME = /^[a-z][a-z0-9-]*$/;
-
-/**
- * Sources whose name is itself a structural role. The splitter classifies
- * each one into the role it represents.
- */
-const STRUCTURAL_ROLES = new Set(["agent", "supervisor", "facilitator"]);
-
 /**
  * Split a combined NDJSON trace into per-source files. The output names
  * follow the `trace--<case>--<participant>.<role>.ndjson` convention.
  *
- * Each valid envelope source becomes one output file. Structural sources
- * (`agent`, `supervisor`, `facilitator`) classify into the matching role.
- * They use their own name as participant. Profile-named sources (e.g.
- * `staff-engineer`) classify as agents with the profile in the participant
- * slot. The command drops orchestrator events and invalid source names.
+ * The command owns the CLI concerns only: input and `--mode` validation,
+ * defaults, and output-dir creation. The shared `splitTrace` implementation
+ * owns the split itself, including source-to-role classification.
  *
  * @param {import("@forwardimpact/libcli").InvocationContext} ctx
  */
@@ -525,10 +529,11 @@ export async function runSplitCommand(ctx) {
   const file = ctx.args.file;
   if (!file) return { ok: false, code: 1, error: "split: missing input file" };
 
-  // `discuss` has the same lead + N-participants shape as `facilitate`. The
-  // splitter buckets purely by envelope `source`, which is mode-independent.
-  // So the CLI accepts `discuss` alongside the structural modes. The CLI owns
-  // this rule. Callers do not.
+  // `discuss` has the same lead + N-participants shape as `facilitate`, and the
+  // splitter buckets purely by envelope `source` (mode-independent), so it is
+  // accepted alongside the structural modes. The CLI owns this, not callers.
+  // `--mode` stays required-but-inert: the harness action passes it and that
+  // surface is out of scope for the shared-split extraction.
   const mode = ctx.options.mode;
   if (!mode) return { ok: false, code: 1, error: "split: --mode is required" };
   if (!["run", "supervise", "facilitate", "discuss"].includes(mode)) {
@@ -539,52 +544,10 @@ export async function runSplitCommand(ctx) {
   const outputDir = ctx.options["output-dir"] || dirname(file);
   runtime.fsSync.mkdirSync(outputDir, { recursive: true });
 
-  const buckets = parseBuckets(runtime.fsSync.readFileSync(file, "utf8"));
-
-  for (const [source, lines] of buckets.entries()) {
-    if (!VALID_SOURCE_NAME.test(source)) continue;
-    const role = STRUCTURAL_ROLES.has(source) ? source : "agent";
-    const outPath = join(
-      outputDir,
-      `trace--${caseId}--${source}.${role}.ndjson`,
-    );
-    runtime.fsSync.writeFileSync(outPath, lines.join("\n") + "\n");
-  }
+  await splitTrace(runtime, file, { caseId, outputDir });
   return { ok: true };
 }
 
-/**
- * Parse NDJSON content into per-source buckets of unwrapped event lines.
- * Skips empty lines, malformed JSON, non-envelope lines, and orchestrator events.
- * @param {string} content - Raw NDJSON file content
- * @returns {Map<string, string[]>} source name -> array of unwrapped JSON lines
- */
-function parseBuckets(content) {
-  const buckets = new Map();
-
-  for (const raw of content.split("\n")) {
-    const trimmed = raw.trim();
-    if (!trimmed) continue;
-
-    let envelope;
-    try {
-      envelope = JSON.parse(trimmed);
-    } catch {
-      continue;
-    }
-
-    if (!envelope.event || typeof envelope.source !== "string") continue;
-    if (envelope.source === "orchestrator") continue;
-
-    if (!buckets.has(envelope.source)) {
-      buckets.set(envelope.source, []);
-    }
-    buckets.get(envelope.source).push(JSON.stringify(envelope.event));
-  }
-
-  return buckets;
-}
-
 // --- Shared helpers ---
 
 /**

package/src/events/github.js

@@ -1,6 +1,5 @@
 /**
- * GitHub event → task-prompt composition. Replaces ~70 lines of shell in
- * kata-dispatch.yml's `Compose task text` step. Each branch in the dispatch
+ * GitHub event → task-prompt composition. Each branch in the dispatch
  * function corresponds to one (event_name, action) the agent workflows react
  * to.
  *

package/src/index.js

@@ -7,9 +7,9 @@ export {
   createTraceGitHub,
   detectRepoSlug,
   parseGitRemote,
-  participantInNames,
   pickTraceArtifact,
 } from "./trace-github.js";
+export { participantInNames } from "./trace-identity.js";
 export { AgentRunner, createAgentRunner } from "./agent-runner.js";
 export { resolveClaudeCodeExecutable } from "./claude-code-executable.js";
 export {

package/src/trace-github.js

@@ -4,6 +4,8 @@ import { Readable } from "node:stream";
 
 import { isoTimestamp } from "@forwardimpact/libutil";
 
+import { nameMatchesKey, participantInNames } from "./trace-identity.js";
+
 const API = "https://api.github.com";
 
 /**
@@ -48,14 +50,18 @@ export class TraceGitHub {
    * trace content.
    *
    * @param {object} [opts]
-   * @param {string} [opts.pattern] - Case-insensitive regex to match workflow name (default: "kata|agent", which covers `Kata: Shift`, `Kata: Dispatch`, and any `agent`-named workflow)
+   * @param {string} [opts.pattern] - Case-insensitive regex to match workflow name (default: "kata|agent|eval|benchmark" — covers `Kata: Shift`, `Kata: Dispatch`, benchmark-driven eval workflows, and any `agent`-named workflow)
    * @param {number} [opts.limit=50] - Max runs to return from GitHub API
    * @param {string} [opts.lookback="7d"] - How far back to search (e.g. "7d", "24h", "2w")
    * @param {string} [opts.participant] - Participant name. When set, the method filters and annotates runs by trace lane
    * @returns {Promise<object[]>} Array of {workflow, runId, status, conclusion, createdAt, branch, url[, match]}
    */
   async listRuns(opts = {}) {
-    const { pattern = "kata|agent", limit = 50, lookback = "7d" } = opts;
+    const {
+      pattern = "kata|agent|eval|benchmark",
+      limit = 50,
+      lookback = "7d",
+    } = opts;
     const cutoff = parseLookback(lookback, this.runtime.clock.now());
 
     const params = new URLSearchParams({
@@ -140,33 +146,41 @@ export class TraceGitHub {
     }
 
     // Dispatch host: one shared artifact whose members name the participant.
-    // Download and list member filenames (names only).
+    // Download and list member filenames (names only). Members are nested
+    // relative paths (`runs/<taskId>/<idx>/trace--*` on eval artifacts), so
+    // match on basenames — the `trace--` prefix check never matches a nested
+    // path directly.
     for (const artifact of traceArtifacts) {
       const { files } = await this.downloadTrace(runId, {
         name: artifact.name,
       });
-      if (participantInNames(files, participant)) return "confirmed";
+      const basenames = files.map((f) => path.basename(f));
+      if (participantInNames(basenames, participant)) return "confirmed";
     }
     return "omit";
   }
 
   /**
-   * Resolve a participant's lane trace path for a known run in one keyed
-   * lookup. The method does not enumerate runs. It does not inspect trace
-   * content.
+   * Resolve a trace lane path for a known run in one keyed lookup. The method
+   * does not enumerate runs. It does not inspect trace content. The key is an
+   * exact member filename, a case id, or a participant name.
    *
-   * Matrix host: the artifact name carries the participant (no download).
-   * Dispatch host: download the shared `trace--*` artifact. Return the
-   * extracted member file whose name carries the participant.
+   * Matrix host: the artifact name carries the key, so no download happens.
+   * Dispatch host: download every `trace--*` artifact and match member
+   * basenames against the key. Exactly one match resolves. Several matches
+   * throw an error that lists the candidates, so the caller narrows the key.
+   * This replaces a silent first-match, which returned an arbitrary cell's
+   * lane on eval runs, because every cell emits the same participants.
    *
    * @param {number|string} runId
-   * @param {string} participant
+   * @param {string} key - Exact member filename, case id, or participant name.
    * @param {object} [opts]
    * @param {string} [opts.dir] - Output directory for a downloaded dispatch artifact
-   * @returns {Promise<{runId: (number|string), participant: string, host: "matrix"|"dispatch", artifact: string, path: string}>}
-   * @throws {Error} when the run has no trace artifacts, or none carries the participant's lane.
+   * @returns {Promise<{runId: (number|string), key: string, host: "matrix"|"dispatch", artifact: string, path: string}>}
+   * @throws {Error} when the run has no trace artifacts, no member matches
+   *   the key, or several members match.
    */
-  async findByKey(runId, participant, opts = {}) {
+  async findByKey(runId, key, opts = {}) {
     const url = `${API}/repos/${this.owner}/${this.repo}/actions/runs/${runId}/artifacts`;
     const data = await this.#get(url);
     const artifacts = data.artifacts ?? [];
@@ -177,41 +191,57 @@ export class TraceGitHub {
       throw new Error(`No trace artifacts for run ${runId}`);
     }
 
-    // Matrix host: the artifact name carries the participant. No download.
+    // Matrix host: the artifact name carries the key. No download.
     const matrix = traceArtifacts.find((a) =>
-      participantInNames([a.name], participant),
+      participantInNames([a.name], key),
     );
     if (matrix) {
       return {
         runId,
-        participant,
+        key,
         host: "matrix",
         artifact: matrix.name,
         path: matrix.name,
       };
     }
 
-    // Dispatch host: download the shared artifact and match a member filename.
+    // Dispatch host: download every shared artifact and collect the members
+    // whose basename matches the key (members are nested relative paths).
+    // Each artifact extracts into its own subdirectory — a shared extract
+    // dir would re-list earlier artifacts' members on every iteration, so a
+    // uniquely-matching key on a multi-artifact (sharded) run would throw a
+    // spurious ambiguity error.
+    const baseDir = opts.dir ?? `/tmp/trace-${runId}`;
+    const matches = [];
     for (const artifact of traceArtifacts) {
       const { dir, files } = await this.downloadTrace(runId, {
         name: artifact.name,
-        dir: opts.dir,
+        dir: path.join(baseDir, artifact.name),
       });
-      const member = files.find((f) => participantInNames([f], participant));
-      if (member) {
-        return {
-          runId,
-          participant,
-          host: "dispatch",
-          artifact: artifact.name,
-          path: path.join(dir, member),
-        };
+      for (const member of files) {
+        if (nameMatchesKey(path.basename(member), key)) {
+          matches.push({ artifact: artifact.name, dir, member });
+        }
       }
     }
 
-    throw new Error(
-      `No trace lane for participant "${participant}" in run ${runId}`,
-    );
+    if (matches.length === 1) {
+      const m = matches[0];
+      return {
+        runId,
+        key,
+        host: "dispatch",
+        artifact: m.artifact,
+        path: path.join(m.dir, m.member),
+      };
+    }
+    if (matches.length > 1) {
+      const names = matches.map((m) => m.member).join(", ");
+      throw new Error(
+        `Ambiguous key "${key}" for run ${runId}: matches ${names}. Narrow the key to a case id or exact filename.`,
+      );
+    }
+    throw new Error(`No trace lane for key "${key}" in run ${runId}`);
   }
 
   /**
@@ -271,9 +301,9 @@ export class TraceGitHub {
       );
     }
 
-    // List extracted files.
-    const entries = await fs.readdir(dir);
-    const files = entries.filter((f) => !f.endsWith(".zip"));
+    // List extracted files — recursively, since eval artifacts carry nested
+    // members (`runs/<taskId>/<idx>/trace--*`).
+    const files = await listExtractedFiles(this.runtime, dir);
 
     return { dir, artifact: artifact.name, files };
   }
@@ -301,34 +331,22 @@ export class TraceGitHub {
 }
 
 /**
- * Test whether a participant's trace lane is present in a list of names.
- *
- * This function matches the two trace-name shapes by *name* only (never by
- * content):
- *   - matrix artifact name: `trace--<participant>`
- *   - dispatch member filename: `trace--<case>--<participant>.<role>.ndjson`
- *
- * The `--` separator delimits the participant segment. The segment ends at
- * the next `--`, at a `.`, or at the end of the string. So a substring like
- * `release` does not match `release-engineer` and vice versa.
- *
- * @param {string[]} names - Artifact names or extracted member filenames.
- * @param {string} participant - Participant name to look for.
- * @returns {boolean}
+ * List every regular file under `dir` recursively, as paths relative to
+ * `dir`, excluding `*.zip` (the downloaded archive itself). Sorted for a
+ * deterministic member order.
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
+ * @param {string} dir
+ * @returns {Promise<string[]>}
  */
-export function participantInNames(names, participant) {
-  return names.some((name) => {
-    if (!name.startsWith("trace--")) return false;
-    const rest = name.slice("trace--".length);
-    // Matrix: `<participant>` is the whole remainder (artifact name).
-    if (rest === participant) return true;
-    // Dispatch: `<case>--<participant>.<role>.ndjson`.
-    const sep = rest.indexOf("--");
-    if (sep === -1) return false;
-    const afterCase = rest.slice(sep + 2);
-    const participantSegment = afterCase.split(".")[0];
-    return participantSegment === participant;
+export async function listExtractedFiles(runtime, dir) {
+  const entries = await runtime.fs.readdir(dir, {
+    recursive: true,
+    withFileTypes: true,
   });
+  return entries
+    .filter((e) => e.isFile() && !e.name.endsWith(".zip"))
+    .map((e) => path.relative(dir, path.join(e.parentPath ?? e.path, e.name)))
+    .sort();
 }
 
 /**

package/src/trace-identity.js

@@ -0,0 +1,132 @@
+/**
+ * Trace identity grammar — the single owner of case ids and lane filenames.
+ *
+ * Builds case ids (`<taskId>-r<runIndex>`), builds raw/lane filenames under
+ * the shared `trace--` convention, validates task ids, and parses names back
+ * into identity. Workdir allocation, task-family loading, the shared split
+ * module, and GitHub discovery all invoke this module — files agreeing by
+ * convention is the drifted-copies pattern this module retires.
+ */
+
+import { basename } from "node:path";
+
+/**
+ * Task ids must not contain "--" or start/end with "-": the "--" delimiter
+ * and the terminal "-r<digits>" suffix then parse unambiguously.
+ * @param {string} id
+ * @returns {boolean}
+ */
+export function isValidTaskId(id) {
+  if (typeof id !== "string" || id.length === 0) return false;
+  if (id.includes("--")) return false;
+  if (id.startsWith("-") || id.endsWith("-")) return false;
+  return true;
+}
+
+/**
+ * Build the grid-unique case id `<taskId>-r<runIndex>`. Shards partition one
+ * grid, so (task, runIndex) is already grid- and shard-unique.
+ * @param {string} taskId
+ * @param {number} runIndex
+ * @returns {string}
+ * @throws {Error} when `isValidTaskId(taskId)` is false or `runIndex` is not
+ *   a non-negative integer.
+ */
+export function buildCaseId(taskId, runIndex) {
+  if (!isValidTaskId(taskId)) {
+    throw new Error(
+      `invalid task id '${taskId}': task ids must not contain "--" or start/end with "-"`,
+    );
+  }
+  if (!Number.isInteger(runIndex) || runIndex < 0) {
+    throw new Error(`invalid run index '${runIndex}': must be an integer ≥ 0`);
+  }
+  return `${taskId}-r${runIndex}`;
+}
+
+/**
+ * Filename of the combined raw envelope trace: `trace--<caseId>.raw.ndjson`.
+ * @param {string} caseId
+ * @returns {string}
+ */
+export function rawTraceFilename(caseId) {
+  return `trace--${caseId}.raw.ndjson`;
+}
+
+/**
+ * Filename of a per-participant lane:
+ * `trace--<caseId>--<participant>.<role>.ndjson`.
+ * @param {string} caseId
+ * @param {string} participant
+ * @param {string} role
+ * @returns {string}
+ */
+export function laneFilename(caseId, participant, role) {
+  return `trace--${caseId}--${participant}.${role}.ndjson`;
+}
+
+/**
+ * Parse `trace--<case>--<participant>.<role>.ndjson` into `{caseName,
+ * participant}`. On no match, `caseName` is the basename minus its final
+ * `.ndjson` extension only and `participant` is null.
+ * @param {string} file
+ * @returns {{caseName: string, participant: string|null}}
+ */
+export function parseIdentity(file) {
+  const name = basename(file);
+  const match = name.match(/^trace--(.+?)--(.+?)\.[^.]+\.ndjson$/);
+  if (match) {
+    return { caseName: match[1], participant: match[2] };
+  }
+  return { caseName: name.replace(/\.ndjson$/, ""), participant: null };
+}
+
+/**
+ * Test whether a participant's trace lane is present in a list of names.
+ *
+ * Matches the two trace-naming shapes by *name* only (never by content):
+ *   - matrix artifact name: `trace--<participant>`
+ *   - dispatch member filename: `trace--<case>--<participant>.<role>.ndjson`
+ *
+ * The participant segment is delimited by `--` and ends at the next `--`, `.`,
+ * or end-of-string, so a substring like `release` does not match
+ * `release-engineer` and vice versa.
+ *
+ * Kept as a distinct shape from {@link parseIdentity} deliberately: this
+ * matcher also accepts bare artifact names with no extension, which the
+ * filename regex cannot.
+ *
+ * @param {string[]} names - Artifact names or extracted member filenames.
+ * @param {string} participant - Participant name to look for.
+ * @returns {boolean}
+ */
+export function participantInNames(names, participant) {
+  return names.some((name) => {
+    if (!name.startsWith("trace--")) return false;
+    const rest = name.slice("trace--".length);
+    // Matrix: `<participant>` is the whole remainder (artifact name).
+    if (rest === participant) return true;
+    // Dispatch: `<case>--<participant>.<role>.ndjson`.
+    const sep = rest.indexOf("--");
+    if (sep === -1) return false;
+    const afterCase = rest.slice(sep + 2);
+    const participantSegment = afterCase.split(".")[0];
+    return participantSegment === participant;
+  });
+}
+
+/**
+ * Keyed-lookup rule for one name: true when `key` equals the exact basename,
+ * the parsed case segment, or the parsed participant segment. Derives case
+ * and participant via {@link parseIdentity} and reuses the
+ * {@link participantInNames} single-name check — no second grammar.
+ * @param {string} name - A member basename or artifact name.
+ * @param {string} key - Exact filename, case id, or participant name.
+ * @returns {boolean}
+ */
+export function nameMatchesKey(name, key) {
+  if (name === key) return true;
+  const identity = parseIdentity(name);
+  if (identity.participant !== null && identity.caseName === key) return true;
+  return participantInNames([name], key);
+}

package/src/trace-multi.js

@@ -12,6 +12,8 @@
  */
 import { basename } from "node:path";
 
+import { parseIdentity } from "./trace-identity.js";
+
 /**
  * Load each file → `TraceQuery`. Run `query(tq)`. Tag each emitted record
  * with `source: <basename>` only when the caller supplies more than one file.
@@ -84,20 +86,3 @@ export function compareTwo(a, b, load) {
     bIdentity: parseIdentity(b),
   });
 }
-
-/**
- * Parse `trace--<case>--<participant>.<role>.ndjson` into `{caseName,
- * participant}`. On no match, `caseName` is the basename without its final
- * `.ndjson` extension. The function removes that one extension only.
- * `participant` is then null.
- * @param {string} file
- * @returns {{caseName: string, participant: string|null}}
- */
-export function parseIdentity(file) {
-  const name = basename(file);
-  const match = name.match(/^trace--(.+?)--(.+?)\.[^.]+\.ndjson$/);
-  if (match) {
-    return { caseName: match[1], participant: match[2] };
-  }
-  return { caseName: name.replace(/\.ndjson$/, ""), participant: null };
-}

package/src/trace-split.js

@@ -0,0 +1,103 @@
+/**
+ * Shared trace-split implementation — the single owner of source-to-role
+ * classification. Both the `gemba-trace split` command and the benchmark
+ * runner drive this module, so exactly one split policy exists (the same
+ * treatment the one-cost-path rule gives `sumTraceCost`).
+ */
+
+import { join } from "node:path";
+import { createInterface } from "node:readline";
+
+import { laneFilename } from "./trace-identity.js";
+
+/** Valid source name pattern: lowercase letter, then lowercase alphanumeric or hyphen. */
+const VALID_SOURCE_NAME = /^[a-z][a-z0-9-]*$/;
+
+/**
+ * Sources whose name is itself a structural role; classified into the role
+ * they represent. `judge` is structural so the judge lane classifies under
+ * one rule — no current producer feeds judge-source envelopes through split
+ * (the judge is its own session), so kata split output is unchanged.
+ */
+const STRUCTURAL_ROLES = new Set([
+  "agent",
+  "supervisor",
+  "facilitator",
+  "judge",
+]);
+
+/**
+ * Split a combined `{source, seq, event}` NDJSON trace into per-source lane
+ * files named by `laneFilename(caseId, source, role)`.
+ *
+ * Classification: sources in the structural-role set ("agent", "supervisor",
+ * "facilitator", "judge") take their own name as role; any other valid source
+ * name classifies as role "agent" with the source as participant. Skips
+ * empty/malformed/non-envelope lines and orchestrator events; drops sources
+ * failing `/^[a-z][a-z0-9-]*$/`. Lane files carry unwrapped event JSON, one
+ * per line.
+ *
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime -
+ *   Ambient collaborators; streams via `runtime.fs`.
+ * @param {string} inputPath - Combined NDJSON trace to split.
+ * @param {object} opts
+ * @param {string} opts.caseId - Case identity embedded in lane filenames.
+ * @param {string} opts.outputDir - Directory the lane files are written to.
+ * @returns {Promise<string[]>} Paths written, resolved against `outputDir`
+ *   (absolute iff `outputDir` is absolute).
+ */
+export async function splitTrace(runtime, inputPath, { caseId, outputDir }) {
+  const fs = runtime.fs;
+  const rl = createInterface({
+    input: fs.createReadStream(inputPath),
+    crlfDelay: Infinity,
+  });
+  const streams = new Map();
+  const paths = [];
+  for await (const line of rl) {
+    const envelope = parseEnvelopeLine(line);
+    if (!envelope) continue;
+    if (envelope.source === "orchestrator") continue;
+    if (!VALID_SOURCE_NAME.test(envelope.source)) continue;
+
+    let stream = streams.get(envelope.source);
+    if (!stream) {
+      const role = STRUCTURAL_ROLES.has(envelope.source)
+        ? envelope.source
+        : "agent";
+      const outPath = join(
+        outputDir,
+        laneFilename(caseId, envelope.source, role),
+      );
+      stream = fs.createWriteStream(outPath);
+      streams.set(envelope.source, stream);
+      paths.push(outPath);
+    }
+    stream.write(JSON.stringify(envelope.event) + "\n");
+  }
+  await Promise.all(
+    [...streams.values()].map((s) => new Promise((r) => s.end(r))),
+  );
+  return paths;
+}
+
+/**
+ * Parse one NDJSON line into a `{source, seq, event}` envelope, or null when
+ * the line is blank, malformed, or not an envelope. Shared with the
+ * raw-summary reader so exactly one envelope-line parser exists; callers add
+ * their own source filters.
+ * @param {string} line
+ * @returns {{source: string, event: object}|null}
+ */
+export function parseEnvelopeLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed) return null;
+  let envelope;
+  try {
+    envelope = JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+  if (!envelope.event || typeof envelope.source !== "string") return null;
+  return envelope;
+}