@forwardimpact/libharness 1.0.0 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libharness",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Agent evaluation framework — prove whether agent changes improved outcomes with reproducible evidence.",
   "keywords": [
     "eval",

package/src/benchmark/report.js

@@ -433,21 +433,55 @@ function median(arr) {
 // Record loading
 // ---------------------------------------------------------------------------
 
+// Directories never worth descending for a `results.jsonl`.
+const SKIP_DIRS = new Set([".git", "node_modules"]);
+
+/**
+ * Load and union every `results.jsonl` found recursively under `inputDir`.
+ *
+ * A single non-sharded run has one root-level ledger — the trivial one-match
+ * case of the same walk. A sharded run lays each shard's partial ledger in its
+ * own subdirectory; merging them equals reporting a single run over the same
+ * cells. An *existing* dir with no ledger yields the empty union (exit 0); a
+ * *missing* dir lets `readdir`'s ENOENT propagate so `report` still errors.
+ * @param {string} inputDir
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
+ * @returns {Promise<{records: object[], skipped: number}>}
+ */
 async function loadRecords(inputDir, runtime) {
-  const path = join(inputDir, "results.jsonl");
-  let content;
+  let files;
   try {
-    content = await runtime.fs.readFile(path, "utf8");
+    files = await collectResultsFiles(inputDir, runtime);
   } catch (e) {
     // Re-throw with the stack collapsed to the message line so the CLI's
-    // error rendering stays free of node-internal async `readFile` frames
-    // (matching the pre-1370 stream-error shape the golden captured).
+    // error rendering stays free of node-internal async `readdir` frames
+    // (a missing --input dir surfaces its ENOENT as exit 1, matching the
+    // pre-1370 stream-error shape the golden captured).
     const err = new Error(e.message);
     if (e.code) err.code = e.code;
     err.stack = `Error: ${e.message}`;
     throw err;
   }
   const records = [];
+  let skipped = 0;
+  for (const file of files) {
+    const content = await runtime.fs.readFile(file, "utf8");
+    skipped += parseLedgerInto(content, records, runtime);
+  }
+  warnOnDuplicateCells(records, runtime);
+  return { records, skipped };
+}
+
+/**
+ * Parse one ledger's JSONL into `records`, skipping malformed or schema-invalid
+ * lines with a stderr warning. Returns the skipped count. Extracted from
+ * `loadRecords` to keep its cognitive complexity under the lint ceiling.
+ * @param {string} content
+ * @param {object[]} records - Accumulator, appended in place.
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
+ * @returns {number} Skipped line count.
+ */
+function parseLedgerInto(content, records, runtime) {
   let skipped = 0;
   for (const line of content.split("\n")) {
     const trimmed = line.trim();
@@ -473,7 +507,55 @@ async function loadRecords(inputDir, runtime) {
     }
     records.push(record);
   }
-  return { records, skipped };
+  return skipped;
+}
+
+/**
+ * Recursively collect paths of every file named `results.jsonl` under `dir`,
+ * skipping `.git`/`node_modules` and never following symlinks. A purpose-built
+ * `readdir` walk — `task-family.js`'s private `walkFiles` resolves symlinks and
+ * is unexported, which is the wrong contract here.
+ * @param {string} dir
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
+ * @returns {Promise<string[]>}
+ */
+async function collectResultsFiles(dir, runtime) {
+  const entries = await runtime.fs.readdir(dir, { withFileTypes: true });
+  entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  const out = [];
+  for (const entry of entries) {
+    if (entry.isSymbolicLink()) continue;
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      out.push(...(await collectResultsFiles(full, runtime)));
+    } else if (entry.isFile() && entry.name === "results.jsonl") {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+/**
+ * Warn (do not silently merge) when a `(taskId, runIndex)` cell appears more
+ * than once across shard ledgers. The shard partition guarantees uniqueness, so
+ * a duplicate signals misconfiguration; both copies stay in the group so the
+ * count is honest.
+ * @param {object[]} records
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
+ */
+function warnOnDuplicateCells(records, runtime) {
+  const counts = new Map();
+  for (const r of records) {
+    const key = `${r.taskId}#${r.runIndex}`;
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  for (const [key, n] of counts) {
+    if (n > 1)
+      runtime.proc.stderr.write(
+        `benchmark report: duplicate cell ${key} appears ${n} times across shard ledgers — the shard partition should make each cell unique\n`,
+      );
+  }
 }
 
 function describeError(e) {

package/src/benchmark/runner.js

@@ -8,10 +8,13 @@
  *   4. Judge.runJudge → Conclude-driven verdict mapped to pass/fail
  *   5. WorkdirManager.teardown → process-group cleanup
  *
- * Results stream as an async iterable AND are appended to
- * `<output>/results.jsonl` for durability. The two paths are different
- * consumers of the same record — the iterator drives CLI stdout mirroring,
- * the JSONL append is the system of record.
+ * 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.
  */
 
 import { createInterface } from "node:readline";
@@ -27,6 +30,7 @@ import { validateResultRecord } from "./result.js";
 import { runInvariants } from "./invariants.js";
 import { assertJudgeProfileStaged, loadTaskFamily } from "./task-family.js";
 import { createWorkdirManager } from "./workdir.js";
+import { CellScheduler } from "./scheduler.js";
 
 const BASE_TOOLS = [
   "Bash",
@@ -42,6 +46,8 @@ const BASE_TOOLS = [
 // 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.
 const AGENT_WATCHDOG_MS = 20 * 60 * 1000;
 
 /** Sole orchestrator for a task-family benchmark run. */
@@ -58,6 +64,13 @@ export class BenchmarkRunner {
    * @param {Function} opts.query - SDK query (injected for testability).
    * @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.
+   * @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.
    * @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
@@ -91,6 +104,9 @@ export class BenchmarkRunner {
     query,
     allowedTools,
     maxTurns,
+    concurrency,
+    watchdogMs,
+    shard,
     task,
     skillsFrom,
     termGraceMs,
@@ -117,6 +133,9 @@ export class BenchmarkRunner {
     };
     this.query = query;
     this.maxTurns = maxTurns;
+    this.concurrency = concurrency ?? 1;
+    this.watchdogMs = watchdogMs ?? AGENT_WATCHDOG_MS;
+    this.shard = shard ?? null;
     this.taskFilter = task ?? null;
     this.skillsFrom = skillsFrom ?? null;
     this.termGraceMs = termGraceMs;
@@ -173,24 +192,38 @@ export class BenchmarkRunner {
       runtime,
     });
 
+    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.
+    const cells = this.shard
+      ? selectShard(allCells, this.shard.index, this.shard.total)
+      : allCells;
+    const scheduler = new CellScheduler({
+      concurrency: this.concurrency,
+      runCell: (cell) =>
+        this.#runOne(
+          family,
+          wm,
+          cell.task,
+          cell.runIndex,
+          skillSetHash,
+          judgeProfilesDir,
+        ),
+    });
+
     const resultsPath = join(this.output, "results.jsonl");
     const resultsStream = runtime.fs.createWriteStream(resultsPath, {
       flags: "a",
     });
+    // 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.
     try {
-      for (const task of tasks) {
-        for (let runIndex = 0; runIndex < this.runs; runIndex++) {
-          const record = await this.#runOne(
-            family,
-            wm,
-            task,
-            runIndex,
-            skillSetHash,
-            judgeProfilesDir,
-          );
-          await writeRecord(resultsStream, record);
-          yield record;
-        }
+      for await (const record of scheduler.run(cells)) {
+        await writeRecord(resultsStream, record);
+        yield record;
       }
     } finally {
       await new Promise((r) => resultsStream.end(r));
@@ -199,22 +232,62 @@ export class BenchmarkRunner {
 
   async #runOne(family, wm, task, runIndex, skillSetHash, judgeProfilesDir) {
     const t0 = this.runtime.clock.now();
-    const workdir = await wm.start(task, runIndex);
+    let workdir;
     try {
-      if (workdir.preflightError) {
-        const record = this.#buildPreflightFailureRecord({
-          task,
-          runIndex,
-          workdir,
-          skillSetHash,
-          familyRevision: family.familyRevision,
-          durationMs: this.runtime.clock.now() - t0,
-        });
-        return this.#validateOrFallback(
-          record,
-          resultsRecordKey(task, runIndex),
-        );
-      }
+      workdir = await wm.start(task, runIndex);
+      return await this.#executeCell({
+        family,
+        workdir,
+        task,
+        runIndex,
+        skillSetHash,
+        judgeProfilesDir,
+        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.
+      return {
+        taskId: task.id,
+        runIndex,
+        verdict: "fail",
+        schemaError: `cell setup failed: ${e.message ?? String(e)}`,
+      };
+    } finally {
+      if (workdir) await wm.teardown(workdir).catch(() => {});
+    }
+  }
+
+  /**
+   * 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.
+   */
+  async #executeCell({
+    family,
+    workdir,
+    task,
+    runIndex,
+    skillSetHash,
+    judgeProfilesDir,
+    t0,
+  }) {
+    if (workdir.preflightError) {
+      const record = this.#buildPreflightFailureRecord({
+        task,
+        runIndex,
+        workdir,
+        skillSetHash,
+        familyRevision: family.familyRevision,
+        durationMs: this.runtime.clock.now() - t0,
+      });
+      return this.#validateOrFallback(record, resultsRecordKey(task, runIndex));
+    }
+    {
       const agentRun = await this.#runAgentSafe(task, workdir);
       const { costUsd, turns, submission, agentError } = agentRun;
       const breakdown = agentRun.costBreakdown ?? { agent: 0, supervisor: 0 };
@@ -295,8 +368,6 @@ export class BenchmarkRunner {
         ...(agentError && { agentError }),
       };
       return this.#validateOrFallback(record, resultsRecordKey(task, runIndex));
-    } finally {
-      await wm.teardown(workdir).catch(() => {});
     }
   }
 
@@ -369,10 +440,10 @@ export class BenchmarkRunner {
             () =>
               reject(
                 new Error(
-                  `agent run produced no result within ${AGENT_WATCHDOG_MS}ms (possible stall)`,
+                  `agent run produced no result within ${this.watchdogMs}ms (possible stall)`,
                 ),
               ),
-            AGENT_WATCHDOG_MS,
+            this.watchdogMs,
           );
         }),
       ]);
@@ -477,6 +548,40 @@ 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.
+ * @param {import("./task-family.js").Task[]} tasks
+ * @param {number} runs
+ * @returns {{task: import("./task-family.js").Task, runIndex: number}[]}
+ */
+export function enumerateCells(tasks, runs) {
+  const cells = [];
+  for (const task of tasks)
+    for (let runIndex = 0; runIndex < runs; runIndex++)
+      cells.push({ task, runIndex });
+  return cells;
+}
+
+/**
+ * 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.
+ * @param {{task: object, runIndex: number}[]} cells
+ * @param {number} i - 1-based shard index.
+ * @param {number} total - Shard count.
+ * @returns {{task: object, runIndex: number}[]}
+ */
+export function selectShard(cells, i, total) {
+  return cells.filter((_, p) => p % total === i - 1);
+}
+
 /**
  * Validate the required BenchmarkRunner constructor arguments. Extracted from
  * the constructor to keep its cognitive complexity under the lint ceiling.

package/src/benchmark/scheduler.js

@@ -0,0 +1,78 @@
+/**
+ * CellScheduler — bounded concurrent execution of benchmark cells.
+ *
+ * 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.
+ */
+
+/** Bounded pool that streams settled cell records in completion order. */
+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.
+   */
+  constructor({ concurrency, runCell }) {
+    if (!Number.isInteger(concurrency) || concurrency < 1)
+      throw new Error("concurrency must be an integer ≥ 1");
+    if (typeof runCell !== "function")
+      throw new Error("runCell must be a function");
+    this.concurrency = concurrency;
+    this.runCell = runCell;
+  }
+
+  /**
+   * Run every cell with bounded concurrency, yielding each settled record the
+   * moment its cell completes.
+   * @param {{task: object, runIndex: number}[]} cells
+   * @returns {AsyncGenerator<object>}
+   */
+  async *run(cells) {
+    let next = 0;
+    /** @type {Set<Promise<{p: Promise<*>, record: object}>>} */
+    const inFlight = new Set();
+
+    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.
+      const p = Promise.resolve()
+        .then(() => this.runCell(cell))
+        .then(
+          (record) => ({ p, record }),
+          (error) => ({ p, record: schedulerFailRecord(cell, error) }),
+        );
+      inFlight.add(p);
+    };
+
+    while (next < cells.length && inFlight.size < this.concurrency) launch();
+    while (inFlight.size > 0) {
+      const { p, record } = await Promise.race(inFlight);
+      inFlight.delete(p);
+      yield record;
+      if (next < cells.length) launch();
+    }
+  }
+}
+
+/**
+ * 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.
+ */
+function schedulerFailRecord(cell, error) {
+  return {
+    taskId: cell.task?.id,
+    runIndex: cell.runIndex,
+    verdict: "fail",
+    schedulerError: error?.message ?? String(error),
+  };
+}

package/src/benchmark/workdir.js

@@ -59,6 +59,9 @@ export class WorkdirManager {
     this.termGraceMs = termGraceMs ?? DEFAULT_TERM_GRACE_MS;
     this.familyRootPath = familyRootPath ?? null;
     this.runtime = runtime;
+    // One registry per manager: hands out distinct, bindable ports under a lock
+    // so concurrent cells can never be handed the same number.
+    this.ports = new PortRegistry();
   }
 
   /**
@@ -120,7 +123,7 @@ export class WorkdirManager {
     const envNames =
       envDirs.length > 0 ? await loadEnv(envDirs, cwd, this.runtime) : [];
 
-    const port = await allocatePort();
+    const port = await this.ports.acquire();
     const agentTracePath = join(runDir, "agent.ndjson");
     const supervisorTracePath = join(runDir, "supervisor.ndjson");
     const judgeTracePath = join(runDir, "judge.ndjson");
@@ -175,9 +178,52 @@ export class WorkdirManager {
         2_000,
       );
     }
-    const portFree = await isPortFree(workdir.port);
-    const descendants = await countDescendants(this.runtime, workdir.pgid);
-    return { portFree, descendants };
+    // Release the reservation in a finally so a throwing probe cannot leak the
+    // number from the in-use set; release after the port-free probe so a freed
+    // number can be re-handed to a waiting cell.
+    try {
+      const portFree = await isPortFree(workdir.port);
+      const descendants = await countDescendants(this.runtime, workdir.pgid);
+      return { portFree, descendants };
+    } finally {
+      this.ports.release(workdir.port);
+    }
+  }
+}
+
+/**
+ * Hands out distinct, bindable TCP ports under a lock. Replaces the bare
+ * close-then-return allocator whose allocate→bind window let two concurrent
+ * cells receive the same number.
+ *
+ * The reservation is the *number*, not a held socket — a held socket could not
+ * be bound by the agent later. `acquire` serializes through a one-slot promise
+ * chain and re-probes if the OS hands back a number already in the live in-use
+ * set, so no two in-flight cells share a port.
+ */
+export class PortRegistry {
+  #inUse = new Set();
+  #tail = Promise.resolve();
+
+  /** @returns {Promise<number>} A distinct, currently-bindable port. */
+  acquire() {
+    const next = this.#tail.then(async () => {
+      let port;
+      do {
+        port = await probeFreePort();
+      } while (this.#inUse.has(port));
+      this.#inUse.add(port);
+      return port;
+    });
+    // Keep the chain alive even if one acquire rejects, so later acquires
+    // still run; swallow here, surface the rejection on `next`.
+    this.#tail = next.catch(() => {});
+    return next;
+  }
+
+  /** @param {number} port */
+  release(port) {
+    this.#inUse.delete(port);
   }
 }
 
@@ -222,7 +268,7 @@ async function runPreflight(runtime, script, cwd, port, vars) {
   };
 }
 
-function allocatePort() {
+function probeFreePort() {
   return new Promise((res, rej) => {
     const server = createServer();
     server.unref();

package/src/commands/benchmark-definition.js

@@ -77,6 +77,16 @@ export const definition = {
           description:
             "Agent-under-test turn budget (default: 50, 0 = unlimited)",
         },
+        concurrency: {
+          type: "string",
+          description:
+            "Max cells run concurrently (positive integer; default: CPU-aware min(4, max(2, cores/2)); env: LIBHARNESS_BENCHMARK_CONCURRENCY)",
+        },
+        shard: {
+          type: "string",
+          description:
+            "Run only shard i of N as i/N (1-based; default: the whole family). Each shard writes a partial results.jsonl; report --input merges them.",
+        },
         "allowed-tools": {
           type: "string",
           description:

package/src/commands/benchmark-run.js

@@ -5,6 +5,7 @@
  */
 
 import { resolve } from "node:path";
+import { availableParallelism } from "node:os";
 
 import { createConfig } from "@forwardimpact/libconfig";
 import { createBenchmarkRunner } from "../benchmark/runner.js";
@@ -51,20 +52,37 @@ export async function runBenchmarkRunCommand(ctx) {
     runtime.proc.stdout.write(JSON.stringify(record) + "\n");
     if (record.verdict !== "pass") anyFail = true;
   }
-  // A run that emits zero records did nothing (no tasks discovered, or the
-  // agent never produced output). That is a failure, not a silent success —
-  // surface it loudly so CI does not go green on an empty benchmark.
-  if (count === 0) {
-    return {
-      ok: false,
-      code: 1,
-      error:
-        "benchmark produced no result records — no task ran to completion; check the family's tasks/, apm install, and agent availability (ANTHROPIC_API_KEY / claude CLI / IS_SANDBOX)",
-    };
-  }
+  if (count === 0) return resolveZeroRecordOutcome(opts, runtime);
   return anyFail ? { ok: false, code: 1, error: "" } : { ok: true };
 }
 
+/**
+ * Decide the exit outcome when a run streamed zero records. A run that emits no
+ * records normally did nothing (no tasks discovered, or the agent never
+ * produced output) — a failure, surfaced loudly so CI does not go green on an
+ * empty benchmark. The one exception is a deliberately-empty shard: a
+ * high-index `--shard=i/N` with `N > cell count` legitimately selects zero
+ * cells, so it exits 0 with a stderr note. Exported so the relaxed-guard branch
+ * is testable without the full handler's config/SDK setup.
+ * @param {{shard: {index: number, total: number} | null}} opts
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
+ * @returns {{ok: true} | {ok: false, code: number, error: string}}
+ */
+export function resolveZeroRecordOutcome(opts, runtime) {
+  if (opts.shard) {
+    runtime.proc.stderr.write(
+      `shard ${opts.shard.index}/${opts.shard.total} selected no cells\n`,
+    );
+    return { ok: true };
+  }
+  return {
+    ok: false,
+    code: 1,
+    error:
+      "benchmark produced no result records — no task ran to completion; check the family's tasks/, apm install, and agent availability (ANTHROPIC_API_KEY / claude CLI / IS_SANDBOX)",
+  };
+}
+
 /**
  * Parse and validate benchmark run options. Exported so tests can verify
  * defaults, including the resolved work tracker.
@@ -95,6 +113,8 @@ export function parseRunOptions(values, env = {}) {
       judge: values["judge-profile"] ?? null,
     },
     maxTurns: parseMaxTurns(values["max-turns"]),
+    concurrency: resolveConcurrency(values, env),
+    shard: parseShard(values.shard),
     allowedTools: values["allowed-tools"]
       ? values["allowed-tools"]
           .split(",")
@@ -109,3 +129,47 @@ function parseMaxTurns(raw) {
   if (raw === "0") return 0;
   return Number.parseInt(raw, 10);
 }
+
+/**
+ * Parse a `--shard=<i>/<N>` selector into `{index, total}` (1-based), or `null`
+ * for an unsharded run. Validates `1 ≤ index ≤ total` with integer parts.
+ * @param {string|undefined} raw
+ * @returns {{index: number, total: number} | null}
+ */
+export function parseShard(raw) {
+  if (raw == null || raw === "") return null;
+  const m = /^(\d+)\/(\d+)$/.exec(raw.trim());
+  if (!m) throw new Error("--shard must be in the form i/N (e.g. 1/4)");
+  const index = Number.parseInt(m[1], 10);
+  const total = Number.parseInt(m[2], 10);
+  if (total < 1 || index < 1 || index > total)
+    throw new Error("--shard requires 1 ≤ i ≤ N");
+  return { index, total };
+}
+
+// Conservative because each cell spawns ~3 agent subprocesses (lead +
+// agent-under-test + judge); a low ceiling keeps a single runner from
+// thrashing. The bulk of the CI speedup comes from Layer-2 sharding across
+// machines, not from raising this in-job default.
+const CONCURRENCY_CEILING = 4;
+
+/**
+ * Resolve the cell concurrency: `--concurrency` flag > the
+ * `LIBHARNESS_BENCHMARK_CONCURRENCY` env var > a CPU-aware default of
+ * `min(CONCURRENCY_CEILING, max(2, ⌊cores/2⌋))`. The default is `> 1` so
+ * concurrency is on transparently without any consumer opting in.
+ * @param {Record<string, string|undefined>} values
+ * @param {Record<string, string|undefined>} [env]
+ * @returns {number}
+ */
+export function resolveConcurrency(values, env = {}) {
+  const raw = values.concurrency ?? env.LIBHARNESS_BENCHMARK_CONCURRENCY;
+  if (raw != null && raw !== "") {
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < 1)
+      throw new Error("--concurrency must be a positive integer");
+    return n;
+  }
+  const cores = availableParallelism();
+  return Math.min(CONCURRENCY_CEILING, Math.max(2, Math.floor(cores / 2)));
+}