@forwardimpact/libharness 2.0.0 → 3.0.1

package/src/benchmark/workdir.js

@@ -7,9 +7,9 @@
  * runAgent → invariants → judge → teardown.
  *
  * Filesystem, subprocess, clock, and process-signal access all route through
- * the injected `runtime` bag. Only raw TCP plumbing (`node:net`) stays direct —
- * it is not an ambient-dependency smell and the runtime bag models no socket
- * surface.
+ * the injected `runtime` bag. Only raw TCP plumbing (`node:net`) stays
+ * direct. It is not an ambient-dependency smell, and the runtime bag models
+ * no socket surface.
  */
 
 import { createServer } from "node:net";
@@ -27,7 +27,7 @@ const DEFAULT_TERM_GRACE_MS = 5_000;
  * @property {string} runDir - Parent of `cwd`; holds trace/log siblings.
  * @property {number} port - Allocated TCP port for the agent.
  * @property {number} pgid - Process-group id captured from the preflight child.
- * @property {*} scaffold - Reserved per design § Components; v1 sets null.
+ * @property {*} scaffold - Reserved per design § Components. v1 sets null.
  * @property {string} agentTracePath
  * @property {string} supervisorTracePath
  * @property {string} judgeTracePath
@@ -59,8 +59,8 @@ 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.
+    // One registry per manager. It hands out distinct, bindable ports under a
+    // lock, so two concurrent cells never get the same number.
     this.ports = new PortRegistry();
   }
 
@@ -77,9 +77,10 @@ export class WorkdirManager {
     const cwd = join(runDir, "cwd");
     await fs.mkdir(cwd, { recursive: true });
 
-    // Family-level shared fixtures: convention-over-configuration, copied if
-    // present. They form the shared base; the per-task workdir/specs below
-    // overlay on top (fs.cp defaults to force:true, so a per-task file wins).
+    // Family-level shared fixtures follow convention over configuration. The
+    // manager copies them if they are present. They form the shared base. The
+    // per-task workdir/specs below overlay on top (fs.cp defaults to
+    // force:true, so a per-task file wins).
     if (this.familyRootPath) {
       await fs
         .cp(join(this.familyRootPath, "workdir"), cwd, { recursive: true })
@@ -162,7 +163,7 @@ export class WorkdirManager {
       try {
         proc.kill(-workdir.pgid, "SIGTERM");
       } catch {
-        // Process group already gone — fine.
+        // The process group is already gone. That is fine.
       }
       await clock.sleep(this.termGraceMs);
       try {
@@ -170,17 +171,17 @@ export class WorkdirManager {
       } catch {
         // Already exited.
       }
-      // Poll briefly until the process group is empty — SIGKILL returns
-      // before the kernel finishes reaping descendants.
+      // Poll briefly until the process group is empty. SIGKILL returns
+      // before the kernel reaps every descendant.
       await waitFor(
         this.runtime,
         async () => (await countDescendants(this.runtime, workdir.pgid)) === 0,
         2_000,
       );
     }
-    // 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.
+    // Release the reservation in a finally, so a probe that throws cannot leak
+    // the number from the in-use set. Release after the port-free probe, so the
+    // registry can hand a freed number to a cell that waits.
     try {
       const portFree = await isPortFree(workdir.port);
       const descendants = await countDescendants(this.runtime, workdir.pgid);
@@ -196,10 +197,10 @@ export class WorkdirManager {
  * 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.
+ * The reservation is the *number*. The registry holds no socket, because the
+ * agent could not bind a held socket later. `acquire` serializes through a
+ * one-slot promise chain. It 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();
@@ -216,7 +217,7 @@ export class PortRegistry {
       return port;
     });
     // Keep the chain alive even if one acquire rejects, so later acquires
-    // still run; swallow here, surface the rejection on `next`.
+    // still run. Swallow the rejection here. Surface it on `next`.
     this.#tail = next.catch(() => {});
     return next;
   }
@@ -231,8 +232,8 @@ export class PortRegistry {
  * Spawn preflight. Stays detached so we can SIGTERM the whole process group.
  * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  * @param {string} script
- * @param {string} cwd - Agent CWD passed via $AGENT_CWD.
- * @param {number} port - Free TCP port passed via $PORT.
+ * @param {string} cwd - Agent CWD, passed in $AGENT_CWD.
+ * @param {number} port - Free TCP port, passed in $PORT.
  * @param {{taskId: string, taskDir: string, hooksDir: string, familyDir: string|null}} vars - Extra hook env vars.
  * @returns {Promise<{pgid: number, error?: {phase: string, message: string, exitCode: number}}>}
  */
@@ -269,8 +270,9 @@ async function runPreflight(runtime, script, cwd, port, vars) {
 }
 
 /**
- * Allocate a free TCP port by binding to 0 and releasing it. Shared with the
- * `grade` subcommand, which needs a plausible `$PORT` for the hook env.
+ * Allocate a free TCP port. Bind to port 0, then release it. The `grade`
+ * subcommand shares this function, because it needs a plausible `$PORT` for
+ * the hook env.
  * @returns {Promise<number>}
  */
 export function probeFreePort() {
@@ -340,7 +342,7 @@ async function waitFor(runtime, predicate, timeoutMs) {
 }
 
 /**
- * Factory function — wires real dependencies.
+ * Factory function. Wires the real dependencies.
  * @param {ConstructorParameters<typeof WorkdirManager>[0]} deps
  * @returns {WorkdirManager}
  */

package/src/claude-code-executable.js

@@ -3,26 +3,26 @@
  *
  * `query()` spawns a native `claude` binary that the SDK resolves from its own
  * platform-specific optional dependency (`@anthropic-ai/claude-agent-sdk-<platform>`).
- * `bun build --compile` bundles the SDK's JavaScript but not that separate
- * native package — it is not part of the import graph — so a compiled fit-*
- * binary can't self-resolve it and `query()` throws "Native CLI binary for
- * <platform> not found".
+ * `bun build --compile` bundles the SDK's JavaScript. It does not bundle that
+ * separate native package, which is not part of the import graph. So a
+ * compiled fit-* binary cannot self-resolve it, and `query()` throws "Native
+ * CLI binary for <platform> not found".
  *
- * In a compiled binary we point the SDK at the standalone `claude` on PATH,
- * installed beside fit-harness by the bootstrap action's `fit-install.sh`.
- * Running from source keeps `node_modules`, where the SDK resolves its own
- * version-matched binary, so there we return undefined and defer to the SDK.
+ * In a compiled binary we point the SDK at the standalone `claude` on PATH.
+ * The gemba-bootstrap action's `fit-install.sh` installs it beside gemba-harness. A
+ * run from source keeps `node_modules`, where the SDK resolves its own
+ * version-matched binary. There we return undefined and defer to the SDK.
  */
 import { LIBCLI_IS_COMPILED } from "@forwardimpact/libcli";
 
 /**
  * @param {object} [deps]
  * @param {(cmd: string) => string | null | undefined} [deps.which] -
- *   PATH resolver (injected for testing).
+ *   PATH resolver (tests inject it).
  * @param {boolean} [deps.isCompiled] -
- *   Whether this is a `bun --compile` binary (injected for testing).
+ *   Whether this is a `bun --compile` binary (tests inject it).
  * @returns {string | undefined} absolute path to `claude`, or undefined to
- *   defer resolution to the SDK.
+ *   let the SDK resolve it.
  */
 export function resolveClaudeCodeExecutable({
   which = defaultWhich,

package/src/commands/advisor-flags.js

@@ -1,15 +1,16 @@
 /**
- * Shared advisor-flag parsing for the four session-mode commands. The two
- * flags are identical everywhere: `--advisor-model` (no default — absent
- * means the Advisor tool is not offered) and `--advisor-max-uses`
- * (default 3), which is a usage error without the model flag.
+ * Shared advisor-flag parser for the four session-mode commands. The two
+ * flags are identical everywhere: `--advisor-model` and `--advisor-max-uses`.
+ * `--advisor-model` has no default. When it is absent, the commands do not
+ * offer the Advisor tool. `--advisor-max-uses` defaults to 3. It is a usage
+ * error without the model flag.
  */
 
 /**
  * Parse `--advisor-model` / `--advisor-max-uses` from parsed option values.
- * A malformed max-uses is a usage error, not a silent fallback: NaN would
- * make the budget check (`used >= maxUses`) permanently false and disable
- * the code-enforced cap the flag exists to guarantee.
+ * A malformed max-uses raises a usage error. It never falls back silently.
+ * NaN would make the budget check (`used >= maxUses`) permanently false. It
+ * would disable the code-enforced cap the flag exists to guarantee.
  * @param {object} values - Parsed option values from cli.parse()
  * @returns {{advisorModel: string|undefined, advisorMaxUses: number}}
  */

package/src/commands/assert.js

@@ -67,10 +67,10 @@ export function evaluateAssertion(values, args, fsSync) {
 }
 
 /**
- * Attach the check-row grading role: `--gate` marks a gate check, `--weight`
- * attaches a numeric weight (0 marks the row diagnostic). `--gate` with any
- * `--weight` — 0 included — is invalid: a stray weight must never silently
- * disarm a gate.
+ * Attach the grading role of the check row. `--gate` marks a gate check.
+ * `--weight` attaches a numeric weight, and 0 marks the row diagnostic.
+ * `--gate` with any `--weight` is invalid, and that includes 0. A stray
+ * weight must never silently disarm a gate.
  * @param {object} values
  * @param {{test: string, pass: boolean, message?: string}} output - Mutated.
  */
@@ -92,8 +92,9 @@ function applyGradingFlags(values, output) {
 }
 
 /**
- * Parse a `--weight` value; null when invalid. A blank string is invalid —
- * `Number("")` is 0, which would silently demote the check to a diagnostic.
+ * Parse a `--weight` value. Return null when it is invalid. A blank string is
+ * invalid, because `Number("")` is 0. That would silently demote the check to
+ * a diagnostic.
  * @param {string} raw
  * @returns {number | null}
  */
@@ -104,11 +105,11 @@ function parseWeight(raw) {
 }
 
 /**
- * The grading role an emit-then-fail row keeps: a failing check must not
- * lose its authored role — an errored gate that demoted to a scored row
- * would let a broken scaffold earn partial credit instead of zeroing the
- * score. Invalid or conflicting flags yield no role (the row fails as a
- * unit-weight scored check).
+ * The grading role an emit-then-fail row keeps. A check that fails must not
+ * lose its authored role. An errored gate that demoted to a scored row would
+ * let a broken scaffold earn partial credit. The score would not drop to
+ * zero. Invalid flags, or flags that conflict, yield no role. The row then
+ * fails as a unit-weight scored check.
  * @param {object} values
  * @returns {{gate?: true, weight?: number}}
  */
@@ -126,10 +127,10 @@ function errorRowRole(values) {
  * Run an assertion, write JSON to stdout, and return a failure envelope when
  * the assertion does not pass.
  *
- * Emit-then-fail on every failure path: an invalid grading flag or an
- * errored evaluation (e.g. `--grep` against a file the agent deleted) writes
- * a failing row before the nonzero exit, so a typo or a vanished target
- * shrinks the score, never the denominator.
+ * Emit-then-fail applies on every failure path. An invalid grading flag
+ * writes a failed row before the nonzero exit. An errored evaluation does the
+ * same, for example `--grep` against a file the agent deleted. So a typo or a
+ * vanished target shrinks the score. It never shrinks the denominator.
  * @param {import("@forwardimpact/libcli").InvocationContext} ctx
  * @returns {Promise<{ok: true} | {ok: false, code: number, error: string}>}
  */

package/src/commands/benchmark-definition.js

@@ -1,7 +1,7 @@
 /**
- * `fit-benchmark` CLI definition. Lives in `src/` so the bin stays an
- * execute-on-import entry point — launcher packages import the bin to run
- * it — while tests import the definition without running the CLI.
+ * `gemba-benchmark` CLI definition. It lives in `src/` so the bin stays an
+ * execute-on-import entry point. Launcher packages import the bin to run it.
+ * Tests import the definition and never run the CLI.
  */
 
 import { runBenchmarkRunCommand } from "./benchmark-run.js";
@@ -13,7 +13,7 @@ import {
 } from "@forwardimpact/libutil/models";
 
 export const definition = {
-  name: "fit-benchmark",
+  name: "gemba-benchmark",
   description:
     "Run coding-agent task families, grade hidden tests, and aggregate pass@k across runs.",
   commands: [
@@ -36,7 +36,7 @@ export const definition = {
         "skills-from": {
           type: "string",
           description:
-            "Stage .claude/ from this directory (a root containing .claude/) instead of running apm install — exercise local, unpublished skills",
+            "Stage .claude/ from this directory (a root that holds .claude/) instead of an apm install, to exercise local, unpublished skills",
         },
         output: {
           type: "string",
@@ -85,7 +85,7 @@ export const definition = {
         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.",
+            "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",
@@ -99,7 +99,7 @@ export const definition = {
       args: [],
       handler: runBenchmarkGradeCommand,
       description:
-        "Grade a single task against a post-run workdir without invoking an agent: run the hidden test suite and the invariants script, then derive the verdict from the check rows (the exit mirrors it).",
+        "Grade a single task against a post-run workdir with no agent. Run the hidden test suite and the invariants script. Then derive the verdict from the check rows (the exit mirrors it).",
       options: {
         family: {
           type: "string",
@@ -112,7 +112,7 @@ export const definition = {
         "run-dir": {
           type: "string",
           description:
-            "Post-run directory whose cwd/ subdir is the agent CWD; both producers run against that cwd — the path hooks receive as $AGENT_CWD",
+            "Post-run directory whose cwd/ subdir is the agent CWD. Both producers run against that cwd. Hooks receive it as $AGENT_CWD",
         },
         output: {
           type: "string",
@@ -125,12 +125,12 @@ export const definition = {
       args: [],
       handler: runBenchmarkReportCommand,
       description:
-        "Aggregate result records into pass@k via the OpenAI HumanEval estimator.",
+        "Aggregate result records into pass@k with the OpenAI HumanEval estimator.",
       options: {
         input: {
           type: "string",
           description:
-            "Run-output directory containing results.jsonl (default: benchmark-runs)",
+            "Run-output directory that holds results.jsonl (default: benchmark-runs)",
         },
         k: {
           type: "string",
@@ -143,7 +143,7 @@ export const definition = {
         detail: {
           type: "string",
           description:
-            "Text report verbosity (full|compact, default: full). compact omits per-task detail — useful for sharded run summaries.",
+            "Text report verbosity (full|compact, default: full). compact omits per-task detail, which helps with sharded run summaries.",
         },
       },
     },
@@ -154,14 +154,14 @@ export const definition = {
     json: { type: "boolean", description: "Output help as JSON" },
   },
   examples: [
-    "fit-benchmark run --family=./families/coding",
-    "fit-benchmark run --family=./families/coding --task=todo-api --runs=1",
-    "fit-benchmark run --family=./families/coding --work-tracker=filesystem",
-    "fit-benchmark run --family=./families/coding --skills-from=. --task=todo-api",
-    `fit-benchmark run --family=./families/coding --runs=10 --agent-model=${BENCHMARK_AGENT_MODEL}`,
-    "fit-benchmark grade --family=./families/coding --task=todo-api --run-dir=./benchmark-runs/runs/todo-api/0",
-    "fit-benchmark report --format=text",
-    "fit-benchmark report --input=./runs/today --k=1,3,5 --format=text",
+    "gemba-benchmark run --family=./families/coding",
+    "gemba-benchmark run --family=./families/coding --task=todo-api --runs=1",
+    "gemba-benchmark run --family=./families/coding --work-tracker=filesystem",
+    "gemba-benchmark run --family=./families/coding --skills-from=. --task=todo-api",
+    `gemba-benchmark run --family=./families/coding --runs=10 --agent-model=${BENCHMARK_AGENT_MODEL}`,
+    "gemba-benchmark grade --family=./families/coding --task=todo-api --run-dir=./benchmark-runs/runs/todo-api/0",
+    "gemba-benchmark report --format=text",
+    "gemba-benchmark report --input=./runs/today --k=1,3,5 --format=text",
   ],
   documentation: [
     {
@@ -174,7 +174,7 @@ export const definition = {
       title: "Automate with GitHub Actions",
       url: "https://www.forwardimpact.team/docs/libraries/prove-changes/run-benchmark/ci-workflow/index.md",
       description:
-        "Run benchmarks in CI with the forwardimpact/benchmark action.",
+        "Run benchmarks in CI with the forwardimpact/gemba-benchmark action.",
     },
   ],
 };

package/src/commands/benchmark-grade.js

@@ -1,9 +1,9 @@
 /**
- * `fit-benchmark grade` — run both check-row producers (the hidden test
- * suite and the invariants script) against a post-run workdir directory and
- * grade the merged rows with the same derivation the benchmark runner uses.
- * No agent and no judge run, so authors validate a task's grading material
- * against fixtures without paying for agent sessions; the process exit
+ * `gemba-benchmark grade` — run both check-row producers (the hidden test
+ * suite and the invariants script) against a post-run workdir directory.
+ * Grade the merged rows with the same derivation the benchmark runner uses.
+ * No agent runs and no judge runs. So an author validates a task's grading
+ * material against fixtures, and pays for no agent session. The process exit
  * mirrors the graded verdict.
  */
 
@@ -46,12 +46,12 @@ export async function runBenchmarkGradeCommand(ctx) {
       runInvariants,
       runHiddenTests,
     });
-  // Same effective-score rule as the runner, minus the judge (none runs
-  // here): an unhealthy grader or a failing gate zeroes the score, so a
-  // crashed hook can never mint marks from the rows it emitted before dying.
-  // Unlike a runner record — where `grade.score` stays the raw fraction and
-  // the zeroing lands on the top-level `score` — this record has no second
-  // field, so `grade.score` carries the effective value here.
+  // The effective-score rule matches the runner, minus the judge (none runs
+  // here). An unhealthy grader or a gate that fails zeroes the score. So a
+  // crashed hook can never mint marks from the rows it emitted before it
+  // died. A runner record keeps the raw fraction in `grade.score` and zeroes
+  // the top-level `score` instead. This record has no second field, so
+  // `grade.score` carries the effective value here.
   if (grade.score !== undefined && !(healthy && grade.gatesPass)) {
     grade.score = 0;
   }
@@ -65,7 +65,8 @@ export async function runBenchmarkGradeCommand(ctx) {
         ...(engineError && { error: engineError.message }),
       },
     }),
-    // Mirrors the script for diagnosis; the graded verdict drives the exit.
+    // This mirrors the script for diagnosis. The graded verdict drives the
+    // exit.
     exitCode: invariants.exitCode,
   };
   validateGradeRecord(record);

package/src/commands/benchmark-report.js

@@ -1,9 +1,9 @@
 /**
- * `fit-benchmark report` — aggregate `results.jsonl` into pass@k via the
- * OpenAI HumanEval estimator. Output is JSON by default; pass --format=text
- * to render a markdown table. --detail=compact drops the per-task detail
- * sections so a sharded run's per-shard summary stays short (the merge job
- * renders the full report over the combined ledger).
+ * `gemba-benchmark report` — aggregate `results.jsonl` into pass@k with the
+ * OpenAI HumanEval estimator. The command writes JSON by default. Pass
+ * --format=text to render a markdown table. --detail=compact drops the
+ * per-task detail sections, so a sharded run's per-shard summary stays short.
+ * The merge job renders the full report over the combined ledger.
  */
 
 import { resolve } from "node:path";

package/src/commands/benchmark-run.js

@@ -1,7 +1,7 @@
 /**
- * `fit-benchmark run` — run every task in a family for N runs, stream each
- * ResultRecord to stdout (one JSON line per record), and append to the
- * canonical `<output>/results.jsonl` for the report subcommand.
+ * `gemba-benchmark run` — run every task in a family for N runs. Stream each
+ * ResultRecord to stdout (one JSON line per record). Append each record to
+ * the canonical `<output>/results.jsonl` for the report subcommand.
  */
 
 import { resolve } from "node:path";
@@ -30,15 +30,15 @@ export async function runBenchmarkRunCommand(ctx) {
   }
   const config = await createConfig("script", "benchmark");
   runtime.proc.env.ANTHROPIC_API_KEY = await config.anthropicToken();
-  // The benchmark agent runs via createBenchmarkRunner, not the supervise
-  // command, so the active-tracker env must land here before the runner
-  // spawns the subprocess that inherits process.env.
+  // The benchmark agent runs through createBenchmarkRunner. The supervise
+  // command does not run it. So the active-tracker env must land here before
+  // the runner spawns the subprocess that inherits process.env.
   runtime.proc.env.LIBHARNESS_WORK_TRACKER = opts.workTracker;
 
   // The Claude Agent SDK spawns a `claude` subprocess that inherits
-  // process.env. NODE_EXTRA_CA_CERTS causes undici (the HTTP client
-  // inside that subprocess) to fail with UND_ERR_INVALID_ARG on
-  // Node 22+, aborting every API call after 10 retries. Strip it
+  // process.env. NODE_EXTRA_CA_CERTS makes undici (the HTTP client
+  // inside that subprocess) fail with UND_ERR_INVALID_ARG on Node 22+.
+  // Undici then aborts every API call after 10 retries. Strip it
   // before the SDK loads so the subprocess gets a clean environment.
   delete runtime.proc.env.NODE_EXTRA_CA_CERTS;
 
@@ -57,13 +57,14 @@ export async function runBenchmarkRunCommand(ctx) {
 }
 
 /**
- * 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.
+ * Decide the exit outcome when a run streamed zero records. A run that emits
+ * no records normally did nothing. Either it discovered no tasks, or the
+ * agent never produced output. That is a failure. The command surfaces it
+ * loudly so CI does not go green on an empty benchmark. A deliberately-empty
+ * shard is the one exception. A high-index `--shard=i/N` with
+ * `N > cell count` legitimately selects zero cells, so it exits 0 with a
+ * stderr note. This function is exported so a test can reach the
+ * relaxed-guard branch without the full handler's config and 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}}
@@ -79,16 +80,17 @@ export function resolveZeroRecordOutcome(opts, runtime) {
     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)",
+      "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.
+ * Parse and validate benchmark run options. This function is exported so a
+ * test can verify the defaults and the resolved work tracker.
  * @param {Record<string, string|undefined>} values - Parsed option values
- * @param {Record<string, string|undefined>} [env] - Process environment, read
- *   for the `LIBHARNESS_WORK_TRACKER` fallback when `--work-tracker` is absent.
+ * @param {Record<string, string|undefined>} [env] - Process environment. The
+ *   parser reads it for the `LIBHARNESS_WORK_TRACKER` fallback when
+ *   `--work-tracker` is absent.
  * @returns {object}
  */
 export function parseRunOptions(values, env = {}) {
@@ -132,7 +134,8 @@ function parseMaxTurns(raw) {
 
 /**
  * Parse a `--shard=<i>/<N>` selector into `{index, total}` (1-based), or `null`
- * for an unsharded run. Validates `1 ≤ index ≤ total` with integer parts.
+ * for an unsharded run. Validate that the parts are integers and that
+ * `1 ≤ index ≤ total`.
  * @param {string|undefined} raw
  * @returns {{index: number, total: number} | null}
  */
@@ -147,17 +150,17 @@ export function parseShard(raw) {
   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.
+// The ceiling is conservative because each cell spawns ~3 agent subprocesses
+// (lead + agent-under-test + judge). A low ceiling makes sure that a single
+// runner does not thrash. Most of the CI speedup comes from Layer-2 shards
+// across machines. It does not come from a higher 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.
+ * `min(CONCURRENCY_CEILING, max(2, ⌊cores/2⌋))`. The default is `> 1`, so
+ * concurrency is on transparently. No consumer needs to opt in.
  * @param {Record<string, string|undefined>} values
  * @param {Record<string, string|undefined>} [env]
  * @returns {number}

package/src/commands/by-discussion.js

@@ -4,11 +4,11 @@ const FIRST_LINE_CAP = 64 * 1024;
 
 /**
  * Read the first newline-terminated line of a file, bounded to the first
- * {@link FIRST_LINE_CAP} bytes. Trace `.ndjson` files can be many MB; the
- * Step 2.6 meta header is always small, so a bounded positional read avoids
- * loading whole files into memory just to inspect the header. The positional
- * `openSync`/`readSync`/`closeSync` trio is read off the injected
- * `runtime.fsSync` surface.
+ * {@link FIRST_LINE_CAP} bytes. Trace `.ndjson` files can be many MB. The
+ * Step 2.6 meta header is always small. So a bounded positional read does
+ * not load whole files into memory just to inspect the header. This function
+ * reads the positional `openSync`/`readSync`/`closeSync` trio off the
+ * injected `runtime.fsSync` surface.
  *
  * @param {object} fsSync - Sync filesystem surface (`runtime.fsSync`).
  * @param {string} path
@@ -30,9 +30,9 @@ function readFirstLine(fsSync, path) {
 /**
  * Scan a directory for `.ndjson` files whose meta header carries the
  * given discussion_id. The Step 2.6 first-line guarantee makes the
- * lookup cheap: we read only the first line per file. Files without a
- * meta header (e.g. legacy supervise/facilitate traces) are skipped
- * silently — not erroneous.
+ * lookup cheap. This function reads only the first line per file. It
+ * silently skips files without a meta header (e.g. legacy
+ * supervise/facilitate traces). Such a file is not an error.
  *
  * @param {string} dir
  * @param {string} discussionId
@@ -72,10 +72,10 @@ export function findTracesByDiscussion(dir, discussionId, fsSync) {
 }
 
 /**
- * `fit-trace by-discussion <discussion-id> [trace-dir]` — list trace
+ * `gemba-trace by-discussion <discussion-id> [trace-dir]` — list trace
  * files whose meta header carries the given discussion_id, one per
- * line, ordered by first-event timestamp (file mtime ascending). The
- * result is usable with `xargs cat` for a chronological merge.
+ * line. Order them by first-event timestamp (file mtime ascending).
+ * You can use the result with `xargs cat` for a chronological merge.
  *
  * @param {import("@forwardimpact/libcli").InvocationContext} ctx
  * @returns {Promise<{ok: true} | {ok: false, code: number, error: string}>}

package/src/commands/callback.js

@@ -3,12 +3,12 @@ import { sumTraceCost } from "../cost.js";
 /**
  * Scan an NDJSON trace and return the last orchestrator summary event,
  * the first `meta` event's `discussion_id`, and any structured replies
- * collected by the discusser. Skips malformed lines.
+ * the discusser collected. This function skips malformed lines.
  *
- * The runner is verdict-agnostic — verbatim passthrough of whatever the
- * trace carries ("success"/"failure" from supervise/facilitate; canonical
- * "adjourned"/"recessed"/"failed" from discuss). The bridge layer maps to
- * its channel semantics.
+ * The runner is verdict-agnostic. It passes through whatever the trace
+ * carries, verbatim ("success"/"failure" from supervise/facilitate;
+ * canonical "adjourned"/"recessed"/"failed" from discuss). The bridge
+ * layer maps to its channel semantics.
  *
  * @param {string} content - Raw NDJSON trace content.
  * @returns {{verdict: string, summary: string, replies: object[], trigger?: object, discussionId?: string} | null}
@@ -53,9 +53,9 @@ function readTraceSummary(content) {
 }
 
 /**
- * Callback command — read an NDJSON trace, extract the terminal
- * orchestrator summary, and POST a canonical callback body to the
- * configured URL. Used by `kata-dispatch.yml` to deliver the lead's
+ * Callback command — read an NDJSON trace and extract the terminal
+ * orchestrator summary. POST a canonical callback body to the configured
+ * URL. `kata-dispatch.yml` uses this command to deliver the lead's
  * conclusion to the bridge that dispatched the run.
  *
  * Wire shape (single shape across modes):
@@ -87,11 +87,11 @@ export async function runCallbackCommand(ctx) {
   const content = runtime.fsSync.readFileSync(traceFile, "utf8");
   const found = readTraceSummary(content) ?? {
     verdict: "failed",
-    summary: "Run ended without producing a summary.",
+    summary: "The run ended and produced no summary.",
     replies: [],
   };
-  // Total spend across every participant in the trace — the bridge surfaces
-  // it alongside the verdict so a dispatched run reports what it cost.
+  // Total spend across every participant in the trace. The bridge surfaces
+  // it alongside the verdict, so a dispatched run reports what it cost.
   const { totalCostUsd } = sumTraceCost(content.split("\n"));
 
   const discussionId = found.discussionId ?? discussionIdOverride ?? null;