@forwardimpact/libharness 3.0.0 → 3.0.2

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 gemba-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 @@
 /**
- * `gemba-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";
@@ -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.",
         },
       },
     },
@@ -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 @@
 /**
  * `gemba-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
+ * 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 @@
 /**
- * `gemba-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 @@
 /**
- * `gemba-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
@@ -74,8 +74,8 @@ export function findTracesByDiscussion(dir, discussionId, fsSync) {
 /**
  * `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;

package/src/commands/discuss.js

@@ -17,8 +17,8 @@ function parseAgentProfiles(raw, cwd, maxTurns) {
 }
 
 /**
- * Parse and validate discuss command options. Exported so tests can verify
- * defaults and the legacy-flag clean break.
+ * Parse and validate discuss command options. This function is exported so a
+ * test can verify the defaults and the legacy-flag clean break.
  * @param {object} values - Parsed option values
  * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  * @returns {object}
@@ -30,8 +30,8 @@ export function parseDiscussOptions(values, runtime) {
   );
 
   const profilesRaw = values["agent-profiles"];
-  // `||` (not `??`) so an empty-string flag from a CI forwarder falls back to
-  // the default rather than overriding it with "".
+  // `||` (not `??`) so an empty-string flag from a CI forwarder falls back
+  // to the default. The empty string does not override the default.
   const agentCwd = resolve(values["agent-cwd"] || ".");
 
   const maxTurnsRaw = values["max-turns"] || "40";
@@ -74,8 +74,8 @@ export function parseDiscussOptions(values, runtime) {
 
 /**
  * Discuss command — run a discusser-led session with suspend/resume
- * semantics, threading `discussion_id` through the trace so multi-run
- * conversations are queryable as one.
+ * semantics. The session threads `discussion_id` through the trace, so
+ * you can query multi-run conversations as one.
  *
  * @param {import("@forwardimpact/libcli").InvocationContext} ctx
  * @returns {Promise<{ok: boolean, code?: number, error?: string}>}
@@ -102,7 +102,8 @@ export async function runDiscussCommand(ctx) {
     runtime.proc.env.LIBHARNESS_AGENT_PROFILE = opts.leadProfile;
   }
   // Unconditional so the default "github" is observable to the agent's
-  // active-tracker resolution, mirroring --agent-profile's env write above.
+  // active-tracker resolution. This mirrors --agent-profile's env write
+  // above.
   runtime.proc.env.LIBHARNESS_WORK_TRACKER = opts.workTracker;
 
   const { query } = await import("@anthropic-ai/claude-agent-sdk");

package/src/commands/facilitate.js

@@ -22,9 +22,9 @@ function parseAgentProfiles(raw, cwd, maxTurns) {
 }
 
 /**
- * Parse and validate facilitate command options. Exported for test
- * coverage of the `--max-turns` → per-agent threading contract; not part
- * of the package's public API.
+ * Parse and validate facilitate command options. This function is exported
+ * so a test can cover the contract that threads `--max-turns` to each
+ * agent. It is not part of the package's public API.
  * @param {object} values - Parsed option values
  * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  * @returns {object} Parsed options
@@ -37,17 +37,18 @@ export function parseFacilitateOptions(values, runtime) {
 
   const profilesRaw = values["agent-profiles"];
   if (!profilesRaw) throw new Error("--agent-profiles is required");
-  // `||` (not `??`) so an empty-string flag from a CI forwarder falls back to
-  // the default rather than overriding it with "".
+  // `||` (not `??`) so an empty-string flag from a CI forwarder falls back
+  // to the default. The empty string does not override the default.
   const agentCwd = resolve(values["agent-cwd"] || ".");
 
   const maxTurnsRaw = values["max-turns"] || "20";
   const maxTurns = maxTurnsRaw === "0" ? 0 : parseInt(maxTurnsRaw, 10);
 
-  // Thread --max-turns into each participant: without this, every facilitated
-  // agent silently falls back to the 50-turn default in facilitator.js even
-  // when the caller raises the budget. Observed in run 26078312414 where
-  // staff-engineer terminated at 51 turns despite --max-turns=200.
+  // Thread --max-turns into each participant. Without this, every
+  // facilitated agent silently falls back to the 50-turn default in
+  // facilitator.js, even when the caller raises the budget. Run
+  // 26078312414 showed this. In it, staff-engineer terminated at 51
+  // turns despite --max-turns=200.
   const agentConfigs = parseAgentProfiles(profilesRaw, agentCwd, maxTurns);
 
   return {
@@ -77,9 +78,9 @@ export async function runFacilitateCommand(ctx) {
   const runtime = ctx.deps.runtime;
   const opts = parseFacilitateOptions(ctx.options, runtime);
 
-  // Build the redactor as the first observable side-effect after option
-  // parsing — the env snapshot must freeze BEFORE any in-process
-  // env writes the command performs (e.g. LIBHARNESS_AGENT_PROFILE).
+  // Build the redactor as the first observable side-effect after the parser
+  // reads the options. The env snapshot must freeze BEFORE any in-process
+  // env write the command performs (e.g. LIBHARNESS_AGENT_PROFILE).
   const redactor = createRedactor({ runtime });
 
   const fileStream = opts.outputPath
@@ -98,7 +99,8 @@ export async function runFacilitateCommand(ctx) {
     runtime.proc.env.LIBHARNESS_AGENT_PROFILE = opts.facilitatorProfile;
   }
   // Unconditional so the default "github" is observable to the agent's
-  // active-tracker resolution, mirroring --agent-profile's env write above.
+  // active-tracker resolution. This mirrors --agent-profile's env write
+  // above.
   runtime.proc.env.LIBHARNESS_WORK_TRACKER = opts.workTracker;
 
   const { query } = await import("@anthropic-ai/claude-agent-sdk");

package/src/commands/output.js

@@ -21,8 +21,9 @@ export async function runOutputCommand(ctx) {
     now: () => isoTimestamp(runtime.clock.now()),
   });
 
-  // `runtime.proc.stdin` is an AsyncIterable of UTF-8 lines (newline-split by
-  // the runtime), so each yielded value is exactly one NDJSON record.
+  // `runtime.proc.stdin` is an AsyncIterable of UTF-8 lines. The runtime
+  // splits them on newlines. So each yielded value is exactly one NDJSON
+  // record.
   for await (const line of runtime.proc.stdin) {
     collector.addLine(line);
   }