@forwardimpact/libharness 2.0.0 → 3.0.1

package/src/benchmark/result.js

@@ -3,16 +3,17 @@
  *
  * Two schemas live here:
  *   - RESULT_RECORD_SCHEMA — one record per (task, runIndex) from a full
- *     benchmark run. Has a happy branch (grade + collectors + judge present)
- *     and a pre-flight-failure branch (grade/judgeVerdict/submission absent).
- *   - GRADE_RECORD_SCHEMA — narrower output of `benchmark-grade`: ad-hoc
- *     grading without a full lifecycle.
+ *     benchmark run. It has a happy branch (grade + collectors + judge
+ *     present) and a pre-flight-failure branch (grade/judgeVerdict/submission
+ *     absent).
+ *   - GRADE_RECORD_SCHEMA — narrower output of `benchmark-grade`, which
+ *     grades ad hoc without a full lifecycle.
  *
- * The check rows are the authoritative grading channel: the happy branch
- * requires a `grade` object, so a pre-break record fails validation rather
- * than rendering under semantics it never carried.
+ * The check rows are the authoritative channel for grades. The happy branch
+ * requires a `grade` object, so a pre-break record fails validation. It does
+ * not render under semantics it never carried.
  *
- * Validation is throw-on-mismatch so the runner can wrap every JSONL append
+ * The validators throw on mismatch, so the runner can wrap every JSONL append
  * in a guard and reject schema drift at write time.
  */
 
@@ -27,8 +28,8 @@ const INVARIANTS_SHAPE = z.object({
 });
 
 /**
- * The normalized grading projection: `score` appears only on scored tasks,
- * `malformed` only when at least one row was malformed.
+ * The normalized projection of a grade. `score` appears only on scored
+ * tasks. `malformed` appears only when at least one row was malformed.
  */
 const GRADE_SHAPE = z.object({
   verdict: VERDICT_ENUM,
@@ -48,9 +49,9 @@ const JUDGE_VERDICT_SHAPE = z.object({
 });
 
 /**
- * Per-participant cost attribution. `costUsd` is the sum of these; the
+ * Per-participant cost attribution. `costUsd` is the sum of these. The
  * breakdown lets reports show where the spend went. The judge runs as its
- * own SDK session, so its cost is tracked separately from agent/supervisor.
+ * own SDK session, so its cost stays separate from agent/supervisor.
  */
 const COST_BREAKDOWN_SHAPE = z.object({
   agent: z.number(),
@@ -98,8 +99,8 @@ const HAPPY_RECORD = z.object({
   invariants: INVARIANTS_SHAPE,
   grade: GRADE_SHAPE,
   hiddenTests: HIDDEN_TESTS_SHAPE.optional(),
-  // The effective, judge-zeroed score `report` aggregates — present only on
-  // scored tasks.
+  // The effective, judge-zeroed score `report` aggregates. It is present
+  // only on scored tasks.
   score: z.number().min(0).max(1).optional(),
   submission: z.string(),
   judgeVerdict: JUDGE_VERDICT_SHAPE.optional(),
@@ -114,9 +115,9 @@ const PREFLIGHT_RECORD = z.object({
   ...COMMON_FIELDS,
   costUsd: z.literal(0),
   preflightError: PREFLIGHT_ERROR_SHAPE,
-  // Trace paths are populated even on preflight failure (the runner allocates
-  // them in WorkdirManager.start) so the record is uniform across branches
-  // and downstream consumers can reference them without conditional fields.
+  // The runner allocates the trace paths in WorkdirManager.start, even on
+  // preflight failure. The record then stays uniform across branches, and
+  // downstream consumers can reference the paths without conditional fields.
   agentTracePath: z.string(),
   supervisorTracePath: z.string(),
   judgeTracePath: z.string(),
@@ -133,15 +134,15 @@ export const RESULT_RECORD_SCHEMA = z.union([HAPPY_RECORD, PREFLIGHT_RECORD]);
 
 export const GRADE_RECORD_SCHEMA = z.object({
   taskId: z.string().min(1),
-  // Unlike the happy result record — where `grade.score` is the raw
-  // weighted fraction and the effective (zeroed) value lives on the
-  // top-level `score` — this record has no second score field, so its
-  // `grade.score` carries the effective health/gate-zeroed value.
+  // In the happy result record, `grade.score` is the raw weighted fraction,
+  // and the effective (zeroed) value lives on the top-level `score`. This
+  // record has no second score field, so its `grade.score` carries the
+  // effective health/gate-zeroed value.
   grade: GRADE_SHAPE,
   invariants: INVARIANTS_SHAPE,
   hiddenTests: HIDDEN_TESTS_SHAPE.optional(),
-  // Mirrors the invariants script's exit for diagnosis; the graded verdict
-  // is what drives the command's process exit.
+  // This mirrors the invariants script's exit for diagnosis. The graded
+  // verdict drives the command's process exit.
   exitCode: z.number().int(),
 });
 

package/src/benchmark/runner.js

@@ -4,19 +4,19 @@
  * Phases per (task, runIndex):
  *   1. WorkdirManager.start → seed CWD + run pre-flight probe
  *   2. Supervisor session (agent + supervisor) → produce traces + submission
- *   3. Invariants collector + hidden-test engine → merged check rows,
- *      graded by `gradeChecks` (rows are authoritative; script exit is
- *      grader health only)
+ *   3. Invariants collector + hidden-test engine → merged check rows.
+ *      `gradeChecks` grades them. The rows are authoritative. The script
+ *      exit reports grader health only.
  *   4. Judge.runJudge → Conclude-driven binary gate mapped to pass/fail
  *   5. WorkdirManager.teardown → process-group cleanup
  *
- * Cells run with bounded in-process concurrency (`CellScheduler`); `run()`
- * yields records in **completion order**, not grid order. A single drain loop
- * is the sole writer of `<output>/results.jsonl`, appending each record the
- * moment its cell settles — that incremental append is the durability and
- * crash-safety mechanism, so a killed run keeps every completed cell and there
- * is no sidecar ledger. The iterator drives CLI stdout mirroring off the same
- * stream.
+ * Cells run with bounded in-process concurrency (`CellScheduler`). `run()`
+ * yields records in **completion order**. It does not yield them in grid
+ * order. A single drain loop is the sole writer of
+ * `<output>/results.jsonl`. It appends each record the moment its cell
+ * settles. That incremental append is the durability and crash-safety
+ * mechanism, so a killed run keeps every completed cell. There is no sidecar
+ * ledger. The iterator mirrors the same stream to CLI stdout.
  */
 
 import { join, resolve as resolvePath } from "node:path";
@@ -47,11 +47,11 @@ const BASE_TOOLS = [
   "TodoWrite",
 ];
 
-// Upper bound on a single supervised agent run. A run that produces no terminal
-// message within this window is treated as a stall and recorded as an
-// agentError, so the benchmark never hangs the event loop into a silent exit.
-// Overridable per-runner via `watchdogMs` so a test can force a stall to fire
-// without waiting the full 20 minutes.
+// Upper bound on a single supervised agent run. The runner treats a run that
+// produces no terminal message within this window as a stall. It records the
+// stall as an agentError, so the benchmark never hangs the event loop into a
+// silent exit. Set `watchdogMs` per runner to override this default. A test
+// can then force a stall and skip the full 20-minute wait.
 const AGENT_WATCHDOG_MS = 20 * 60 * 1000;
 
 /** Sole orchestrator for a task-family benchmark run. */
@@ -65,25 +65,26 @@ export class BenchmarkRunner {
    * @param {string} opts.supervisorModel
    * @param {string} opts.judgeModel
    * @param {{agent?: string, judge?: string}} [opts.profiles]
-   * @param {Function} opts.query - SDK query (injected for testability).
+   * @param {Function} opts.query - SDK query. A test injects its own.
    * @param {string[]} [opts.allowedTools] - Agent tool allowlist (default: BASE_TOOLS).
    * @param {number} [opts.maxTurns] - Agent-under-test turn budget.
    * @param {number} [opts.concurrency] - Max cells in flight (integer ≥ 1).
-   *   Defaults to 1 as a defensive floor; the CLI always passes a resolved value.
+   *   Defaults to 1 as a defensive floor. The CLI always passes a resolved value.
    * @param {{index: number, total: number}} [opts.shard] - Run only the cells
    *   assigned to shard `index` of `total` (1-based). Absent ≡ the whole grid
    *   (identity `1/1`).
    * @param {number} [opts.watchdogMs] - Per-agent stall watchdog (ms). Defaults
-   *   to `AGENT_WATCHDOG_MS`; injectable so tests can force a stall in-test.
+   *   to `AGENT_WATCHDOG_MS`. A test injects its own to force a stall in-test.
    * @param {number} [opts.termGraceMs] - SIGTERM→SIGKILL grace (ms) for the per-task process group.
    * @param {Function} [opts.runAgent] - Test seam: replaces the agent-under-test
    *   session. Must return `{costUsd, turns, submission, agentError?}` and
    *   write a valid NDJSON trace to `workdir.agentTracePath`. Default uses
    *   `createAgentRunner` with the harness `BASE_TOOLS` allowlist. Internal
-   *   testing only — not part of the public API.
+   *   testing only. It is not part of the public API.
    * @param {import("@forwardimpact/libutil/runtime").Runtime} opts.runtime -
-   *   Injected ambient collaborators (`fs`, `subprocess`, `clock`, `proc`),
-   *   threaded into the installers, workdir manager, invariants, and judge.
+   *   The host injects these ambient collaborators (`fs`, `subprocess`,
+   *   `clock`, `proc`). The runner threads them into the installers, the
+   *   workdir manager, the invariants, and the judge.
    * @param {Function} [opts.runInvariants] - Test seam: replaces `runInvariants`.
    *   Same contract as `runInvariants(task, ctx, runtime)`. Internal testing only.
    * @param {Function} [opts.runHiddenTests] - Test seam: replaces
@@ -203,9 +204,9 @@ export class BenchmarkRunner {
     });
 
     const allCells = enumerateCells(tasks, this.runs);
-    // Sharding selects a deterministic subset of the grid; an unsharded run is
-    // the identity 1/1. A high-index shard may select zero cells — a valid run
-    // whose results.jsonl ends up empty.
+    // A shard selects a deterministic subset of the grid. An unsharded run is
+    // the identity 1/1. A high-index shard may select zero cells. That is a
+    // valid run whose results.jsonl ends up empty.
     const cells = this.shard
       ? selectShard(allCells, this.shard.index, this.shard.total)
       : allCells;
@@ -228,8 +229,8 @@ export class BenchmarkRunner {
     });
     // Single-writer drain: the scheduler runs up to `concurrency` cells at
     // once and pushes each settled record here in completion order. This loop
-    // is the sole writer of `results.jsonl` — workers never touch the stream —
-    // and the per-completion append is the crash-safety mechanism.
+    // is the sole writer of `results.jsonl`. Workers never touch the stream.
+    // The per-completion append is the crash-safety mechanism.
     try {
       for await (const record of scheduler.run(cells)) {
         await writeRecord(resultsStream, record);
@@ -255,11 +256,12 @@ export class BenchmarkRunner {
         t0,
       });
     } catch (e) {
-      // `wm.start()` (port acquire + workdir/env seeding) is the one throw site
-      // not caught inside `#executeCell`. Turn it into the runner's own fallback
-      // record so `#runOne` never rejects — the scheduler's one-record-per-cell
-      // contract depends on that. The fallback is schema-skipped by `report`,
-      // the same as any other runner-side schema failure.
+      // `wm.start()` (port acquire + workdir/env seed) is the one throw site
+      // that `#executeCell` does not catch. Turn it into the runner's own
+      // fallback record so `#runOne` never rejects. The scheduler's
+      // one-record-per-cell contract depends on that. `report` skips the
+      // fallback because it fails the schema, the same as any other
+      // runner-side schema failure.
       return {
         taskId: task.id,
         runIndex,
@@ -273,9 +275,9 @@ export class BenchmarkRunner {
 
   /**
    * Run one cell's lifecycle against an already-started workdir: preflight
-   * gate → supervised agent → invariants → judge → assembled record. Extracted
-   * from `#runOne` so the start/teardown/error wrapper stays under the
-   * complexity ceiling.
+   * gate → supervised agent → invariants → judge → assembled record. It is
+   * separate from `#runOne` so the start/teardown/error wrapper stays under
+   * the complexity ceiling.
    */
   async #executeCell({
     family,
@@ -313,9 +315,9 @@ export class BenchmarkRunner {
       const judgePass =
         judgeVerdict === null || judgeVerdict.verdict === "pass";
       const verdict = grade.verdict === "pass" && judgePass ? "pass" : "fail";
-      // Gates protect the score: an unhealthy grader, a failing gate row, or
-      // a failing judge zeroes the effective score. Full marks does not — a
-      // fractional score with verdict fail is the point.
+      // Gates protect the score: an unhealthy grader, a gate row that fails,
+      // or a judge that fails zeroes the effective score. Full marks does not
+      // zero it. A fractional score with verdict fail is the point.
       const scoreValid = graded.healthy && grade.gatesPass && judgePass;
       const record = {
         taskId: task.id,
@@ -365,8 +367,8 @@ export class BenchmarkRunner {
 
   /**
    * Run the judge (when the task ships a template) over the grade result.
-   * The record's judgeVerdict carries only the verdict + summary; the
-   * judge's cost is folded into costUsd / costBreakdown instead.
+   * The record's judgeVerdict carries only the verdict + summary. The runner
+   * folds the judge's cost into costUsd / costBreakdown instead.
    */
   async #judgeCell({
     task,
@@ -404,10 +406,9 @@ export class BenchmarkRunner {
   }
 
   /**
-   * Run both check-row producers against the post-run CWD and grade the
-   * merged rows via the shared derivation. Restoration happens inside the
-   * engine, so the judge (which runs after) sees the workdir exactly as the
-   * agent left it.
+   * Run both check-row producers against the post-run CWD. Grade the merged
+   * rows through the shared derivation. The engine restores the workdir, so
+   * the judge (which runs after) sees it exactly as the agent left it.
    */
   #gradeCell(family, task, workdir) {
     const ctx = {
@@ -424,9 +425,9 @@ export class BenchmarkRunner {
 
   /**
    * Dispatch to either the injected hook or the default `#runAgent`. Either
-   * path can throw; catch here so a thrown error becomes an `agentError` on
-   * the record (spec criterion 1: records on agent failure) rather than
-   * aborting the whole iterator.
+   * path can throw. Catch the error here so it becomes an `agentError` on the
+   * record (spec criterion 1: records on agent failure). The iterator then
+   * does not abort.
    */
   async #runAgentSafe(task, workdir) {
     try {
@@ -448,8 +449,9 @@ export class BenchmarkRunner {
 
   /**
    * Run the agent-under-test under a Supervisor. The supervisor writes
-   * a combined tagged NDJSON trace; after the session we split it into
-   * agent.ndjson and supervisor.ndjson and extract cost/turns/submission.
+   * a combined tagged NDJSON trace. After the session, this method splits
+   * the trace into agent.ndjson and supervisor.ndjson. It also extracts
+   * cost/turns/submission.
    */
   async #runAgent(task, workdir) {
     const fs = this.runtime.fs;
@@ -477,11 +479,12 @@ export class BenchmarkRunner {
     });
     const instructions = await fs.readFile(task.paths.instructions, "utf8");
     let agentError = null;
-    // Watchdog: a supervised session can hang without settling (e.g. the agent
-    // SDK subprocess exits without a terminal message), which would empty the
-    // event loop and exit the process mid-run with zero records. Race the run
-    // against a bounded timer so a stall becomes an `agentError` record instead
-    // of a silent exit; the timer also keeps the loop alive until it fires.
+    // Watchdog: a supervised session can hang and never settle (e.g. the agent
+    // SDK subprocess exits without a terminal message). The hang would empty
+    // the event loop and exit the process mid-run with zero records. Race the
+    // run against a bounded timer so a stall becomes an `agentError` record
+    // instead of a silent exit. The timer also keeps the loop alive until it
+    // fires.
     let watchdog;
     try {
       const result = await Promise.race([
@@ -513,8 +516,9 @@ export class BenchmarkRunner {
       workdir.agentTracePath,
       workdir.supervisorTracePath,
     );
-    // Cost is summed across every participant's result events from the one
-    // combined trace, attributed per source. Read before unlinking.
+    // `sumTraceCost` sums the cost across every participant's result events
+    // from the one combined trace, and attributes it per source. Read the
+    // trace before you unlink it.
     const combined = await fs.readFile(combinedPath, "utf8");
     const { totalCostUsd, bySource } = sumTraceCost(combined.split("\n"));
     await fs.unlink(combinedPath).catch(() => {});
@@ -586,9 +590,9 @@ export class BenchmarkRunner {
       validateResultRecord(record);
       return record;
     } catch (e) {
-      // The runner constructed the record — a schema failure is a real bug,
-      // not bad family input. Emit a noisy fallback so the iterator stays
-      // consumable and the agent budget isn't silently dropped.
+      // The runner constructed the record. A schema failure is a real bug.
+      // Bad family input is not the cause. Emit a noisy fallback so the
+      // iterator stays consumable and nothing silently drops the agent budget.
       return {
         taskId: record.taskId ?? key.taskId,
         runIndex: record.runIndex ?? key.runIndex,
@@ -601,9 +605,10 @@ export class BenchmarkRunner {
 
 /**
  * Flatten the grid into a stable ordered cell list, task-major /
- * runIndex-minor. Load-bearing ordering: Part 02's round-robin shard balance
- * depends on a task's runIndexes being adjacent in this list. Single source of
- * the cell list for both the scheduler and the shard selector.
+ * runIndex-minor. The order is load-bearing. A task's runIndexes are adjacent
+ * in this list, and Part 02's round-robin shard balance depends on that. This
+ * function is the single source of the cell list for both the scheduler and
+ * the shard selector.
  * @param {import("./task-family.js").Task[]} tasks
  * @param {number} runs
  * @returns {{task: import("./task-family.js").Task, runIndex: number}[]}
@@ -619,11 +624,11 @@ export function enumerateCells(tasks, runs) {
 /**
  * Round-robin partition of the enumerated cells: the cell at position `p` runs
  * iff `p % total === i - 1`. `i` is 1-based (Playwright-style). The union over
- * `i ∈ 1..total` is the exact grid, each cell once; when `total > cells.length`
- * the high-index shards select **zero** cells — a valid run. Because
- * `enumerateCells` is task-major, a task's run indexes are adjacent, so
- * round-robin spreads them across shards rather than handing one shard a slow
- * task's whole run block.
+ * `i ∈ 1..total` is the exact grid, each cell once. When
+ * `total > cells.length`, the high-index shards select **zero** cells. That is
+ * a valid run. `enumerateCells` is task-major, so a task's run indexes are
+ * adjacent. Round-robin then spreads them across shards. It does not hand one
+ * shard a slow task's whole run block.
  * @param {{task: object, runIndex: number}[]} cells
  * @param {number} i - 1-based shard index.
  * @param {number} total - Shard count.
@@ -634,8 +639,9 @@ export function selectShard(cells, i, total) {
 }
 
 /**
- * Validate the required BenchmarkRunner constructor arguments. Extracted from
- * the constructor to keep its cognitive complexity under the lint ceiling.
+ * Validate the required BenchmarkRunner constructor arguments. It is separate
+ * from the constructor to keep that function's cognitive complexity under the
+ * lint ceiling.
  */
 function validateRunnerArgs({
   family,
@@ -674,5 +680,5 @@ export function createBenchmarkRunner(opts) {
   return new BenchmarkRunner(opts);
 }
 
-// Internal exports used by tests.
+// Tests use these internal exports.
 export const __BASE_TOOLS = BASE_TOOLS;

package/src/benchmark/scheduler.js

@@ -1,11 +1,12 @@
 /**
- * CellScheduler — bounded concurrent execution of benchmark cells.
+ * CellScheduler — runs benchmark cells concurrently under a bound.
  *
- * Keeps at most `concurrency` `runCell(cell)` calls in flight at once and
- * yields each settled record in **completion order** (not grid order). The
- * runner's drain loop consumes this async iterable as the sole writer of
- * `results.jsonl`, so concurrency lives here in execution while the ledger
- * stays single-writer — no write mutex on the hot path.
+ * The scheduler keeps at most `concurrency` `runCell(cell)` calls in flight
+ * at once. It yields each settled record in **completion order**. It does
+ * not yield them in grid order. The runner's drain loop consumes this async
+ * iterable as the sole writer of `results.jsonl`. Concurrency lives here in
+ * execution, and the ledger stays single-writer. The hot path needs no write
+ * mutex.
  */
 
 /** Bounded pool that streams settled cell records in completion order. */
@@ -14,10 +15,10 @@ export class CellScheduler {
    * @param {object} opts
    * @param {number} opts.concurrency - Max cells in flight (integer ≥ 1).
    * @param {(cell: {task: object, runIndex: number}) => Promise<object>} opts.runCell -
-   *   Runs one cell to a settled record. By contract `runCell` never rejects —
-   *   the runner's `#runOne` catches setup, agent, and schema failures and
-   *   returns a record rather than throwing — but a rejection is still guarded
-   *   so one bad cell cannot wedge the drain.
+   *   Runs one cell to a settled record. By contract `runCell` never rejects.
+   *   The runner's `#runOne` catches setup, agent, and schema failures. It
+   *   returns a record instead of a throw. The scheduler still guards against
+   *   a rejection, so one bad cell cannot wedge the drain.
    */
   constructor({ concurrency, runCell }) {
     if (!Number.isInteger(concurrency) || concurrency < 1)
@@ -29,7 +30,7 @@ export class CellScheduler {
   }
 
   /**
-   * Run every cell with bounded concurrency, yielding each settled record the
+   * Run every cell with bounded concurrency. Yield each settled record the
    * moment its cell completes.
    * @param {{task: object, runIndex: number}[]} cells
    * @returns {AsyncGenerator<object>}
@@ -42,8 +43,8 @@ export class CellScheduler {
     const launch = () => {
       const cell = cells[next++];
       // The wrapper resolves to its own handle (for O(1) removal) plus the
-      // settled record, and never rejects — a thrown runCell becomes a fail
-      // record so the drain keeps consuming.
+      // settled record. It never rejects. A thrown runCell becomes a fail
+      // record, so the drain keeps consuming.
       const p = Promise.resolve()
         .then(() => this.runCell(cell))
         .then(
@@ -64,9 +65,9 @@ export class CellScheduler {
 }
 
 /**
- * Defensive fallback when `runCell` rejects (contract says it cannot). Keeps
- * the drain consumable; the record is intentionally minimal and will be
- * skipped by `report`'s schema validation, counted as skipped.
+ * Defensive fallback when `runCell` rejects (the contract says it cannot).
+ * The fallback keeps the drain consumable. The record is deliberately
+ * minimal. `report`'s schema validation skips it and counts it as skipped.
  */
 function schedulerFailRecord(cell, error) {
   return {

package/src/benchmark/task-family.js

@@ -14,16 +14,18 @@
  *       specs/                # copied into agent CWD
  *       workdir/              # copied into agent CWD
  *
- * `tests/` is an overlay mirror of the agent CWD: a file's path under
- * `tests/` is its staging path. Every `*.test.js` file is one check —
- * `*.gate.test.js` marks a gate, any other `*.test.js` is scored — and every
- * other file is support material, staged but never graded. The layout is
- * validated eagerly here so authoring errors fail before any agent spend.
+ * `tests/` is an overlay mirror of the agent CWD. A file's path under
+ * `tests/` is its staging path. Every `*.test.js` file is one check.
+ * `*.gate.test.js` marks a gate. Any other `*.test.js` counts toward the
+ * score. Every other file is support material. The benchmark stages it but
+ * never grades it. This loader validates the layout eagerly, so authoring
+ * errors fail before any agent spend.
  *
- * Local paths or git URLs are both accepted; git URLs are shallow-cloned into
- * a temp dir and `familyRevision` becomes `git:<sha>` of HEAD at clone time.
- * Local paths use the canonical-tree algorithm from design § Family revision
- * algorithm so the result is stable across operating systems.
+ * The loader accepts a local path or a git URL. For a git URL it makes a
+ * shallow clone into a temp dir. `familyRevision` then becomes `git:<sha>` of
+ * HEAD at clone time. Local paths use the canonical-tree algorithm from
+ * design § Family revision algorithm, so the result is stable across
+ * operating systems.
  *
  * Filesystem and subprocess access route through the injected `runtime` bag
  * (`runtime.fs` async, `runtime.subprocess.run` one-shot, `tmpdir` derived
@@ -35,13 +37,13 @@ import { join, posix, relative, resolve, sep } from "node:path";
 
 const GIT_URL_RE = /^(git@|https?:\/\/|ssh:\/\/|git:\/\/)/;
 const SKIP_DIRS = new Set([".git", "node_modules"]);
-// POSIX `X_OK` (execute permission); node's fs honours the numeric mode, so we
-// avoid importing `node:fs`'s `constants` (which would light the fs smell).
+// POSIX `X_OK` (execute permission). Node's fs honours the numeric mode, so we
+// do not import `node:fs`'s `constants`, which would light the fs smell.
 const X_OK = 1;
 
 /**
- * Derive the system temp dir from the env (node's `os.tmpdir()` is itself an
- * env-respecting wrapper). The runtime bag has no `os` slot by design.
+ * Derive the system temp dir from the env. Node's `os.tmpdir()` also reads
+ * the env. The runtime bag has no `os` slot by design.
  * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  * @returns {string}
  */
@@ -62,7 +64,7 @@ export async function loadTaskFamily(rootPathOrGitUrl, runtime) {
   let familyRevision;
   if (isGit) {
     const dir = await runtime.fs.mkdtemp(
-      join(tmpdir(runtime), "fit-benchmark-family-"),
+      join(tmpdir(runtime), "gemba-benchmark-family-"),
     );
     await gitClone(runtime, rootPathOrGitUrl, dir);
     rootPath = dir;
@@ -84,9 +86,9 @@ export async function loadTaskFamily(rootPathOrGitUrl, runtime) {
 }
 
 /**
- * Assert that `<judgeProfilesDir>/<judgeProfile>.md` exists. Called from
- * `BenchmarkRunner.run()` so a missing judge profile fails the family
- * install before any agent session starts.
+ * Assert that `<judgeProfilesDir>/<judgeProfile>.md` exists.
+ * `BenchmarkRunner.run()` calls it, so a missing judge profile fails the
+ * family install before any agent session starts.
  * @param {TaskFamily} _family
  * @param {string} judgeProfilesDir
  * @param {string} judgeProfile
@@ -161,8 +163,8 @@ const GATE_SUFFIX = ".gate.test.js";
 
 /**
  * Discover and validate a task's hidden test suite under `<taskDir>/tests/`.
- * Returns null when the directory is absent; throws on an invalid layout
- * (no check files, a dangling symlink, duplicate check names) so
+ * Returns null when the directory is absent. Throws on an invalid layout
+ * (no check files, a dangling symlink, duplicate check names), so
  * `loadTaskFamily` rejects broken suites before any agent spend.
  * @param {object} fs - Async filesystem surface (`runtime.fs`).
  * @param {string} taskDir
@@ -211,10 +213,10 @@ async function discoverSuite(fs, taskDir) {
 }
 
 /**
- * Walk a suite tree collecting `{sourcePath, stagePath}` entries. Unlike
- * `walkFiles` (which silently skips dangling symlinks for hashing), every
- * entry here must be a regular file after symlink resolution — a dangling
- * symlink or a link to a non-file target is an authoring error.
+ * Walk a suite tree and collect `{sourcePath, stagePath}` entries. Every
+ * entry here must be a regular file after symlink resolution. `walkFiles` is
+ * different. It silently skips a dangling symlink when it hashes the tree. A
+ * dangling symlink or a link to a non-file target is an authoring error.
  */
 async function walkSuiteFiles(fs, root, dir, out) {
   const entries = await fs.readdir(dir, { withFileTypes: true });
@@ -343,18 +345,18 @@ async function git(runtime, args) {
 
 /**
  * @typedef {object} HiddenCheck
- * @property {string} name - Basename stem with the check suffix stripped.
+ * @property {string} name - Basename stem without the check suffix.
  * @property {boolean} gate - True iff the filename ends `.gate.test.js`.
  * @property {string} sourcePath - Absolute path under `tests/`.
- * @property {string} stagePath - Path relative to `tests/` — the overlay
- *   mirror of the staging path under the agent CWD.
+ * @property {string} stagePath - Path relative to `tests/`. It mirrors the
+ *   staging path under the agent CWD.
  */
 
 /**
  * @typedef {object} HiddenSuite
  * @property {HiddenCheck[]} checks - In sorted stage-path order.
  * @property {{sourcePath: string, stagePath: string}[]} support - Non-check
- *   files, staged for the whole pass but never graded.
+ *   files. The benchmark stages them for the whole pass but never grades them.
  */
 
 /**

package/src/benchmark/trace-split.js

@@ -1,19 +1,20 @@
 /**
- * Combined-supervisor-trace splitting for the benchmark runner: one pass
+ * Split the combined supervisor trace for the benchmark runner. One pass
  * over the tagged NDJSON envelope stream separates agent events from
- * supervisor/orchestrator events and extracts the run summary.
+ * supervisor and orchestrator events. The same pass extracts the run summary.
  */
 
 import { createInterface } from "node:readline";
 
 /**
- * Split the combined supervisor trace into agent and supervisor files and
- * extract turn count and submission in a single pass. Agent-source events go
- * to `agentPath`; supervisor and orchestrator events go to `supervisorPath`.
+ * Split the combined supervisor trace into agent and supervisor files in a
+ * single pass. The same pass extracts the turn count and the submission.
+ * Agent-source events go to `agentPath`. Supervisor and orchestrator events
+ * go to `supervisorPath`.
  *
- * Cost is deliberately not summed here — the caller derives it from the same
- * combined trace via `sumTraceCost`, so there is one cost path across the
- * benchmark, callback, and `fit-trace cost` consumers.
+ * This function deliberately does not sum cost. The caller derives it from
+ * the same combined trace with `sumTraceCost`. One cost path then serves the
+ * benchmark, callback, and `gemba-trace cost` consumers.
  * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  * @param {string} combinedPath
  * @param {string} agentPath