@forwardimpact/libharness 3.0.0 → 3.0.1

package/src/benchmark/apm-installer.js

@@ -1,13 +1,13 @@
 /**
  * ApmInstaller — runs `apm install --target claude` in the family root to
- * materialise skills and agents, copies the resulting `.claude/` into a
- * staging directory, and computes the manifest fingerprint from the lockfile.
- * Per-task copy happens later in WorkdirManager.
+ * materialise skills and agents. It copies the resulting `.claude/` into a
+ * staging directory. It computes the manifest fingerprint from the lockfile.
+ * WorkdirManager makes the per-task copy later.
  *
- * Subprocess and filesystem access route through the injected `runtime` bag
- * (`runtime.subprocess.spawn` for the streaming `apm` child, `runtime.fs` for
- * the async staging copies). See `createApmInstaller` for the real-dependency
- * wiring; `installApm` is a thin free-function wrapper.
+ * Subprocess and filesystem access route through the injected `runtime` bag.
+ * The `apm` child streams through `runtime.subprocess.spawn`. The async
+ * staging copies use `runtime.fs`. See `createApmInstaller`, which wires the
+ * real dependencies. `installApm` is a thin free-function wrapper.
  */
 
 import { createHash } from "node:crypto";
@@ -18,7 +18,7 @@ export class ApmInstaller {
   /**
    * @param {object} deps
    * @param {import("@forwardimpact/libutil/runtime").Runtime} deps.runtime -
-   *   Ambient collaborators; uses `subprocess.spawn` and `fs`.
+   *   Ambient collaborators. The installer uses `subprocess.spawn` and `fs`.
    */
   constructor({ runtime }) {
     if (!runtime) throw new Error("runtime is required");
@@ -30,8 +30,8 @@ export class ApmInstaller {
    * @param {string} outputDir - The benchmark run's output directory.
    * @param {object} [options]
    * @param {string|null} [options.skillsFrom] - Stage `.claude/` from this
-   *   directory instead of running apm install. The path is a root containing
-   *   a `.claude/` tree (e.g. a working tree), letting a run exercise local,
+   *   directory and do not run apm install. The path is a root that contains
+   *   a `.claude/` tree (e.g. a working tree). A run can then exercise local,
    *   unpublished skills.
    * @returns {Promise<{stagingDir: string, skillSetHash: string, judgeProfilesDir: string}>}
    */
@@ -44,7 +44,7 @@ export class ApmInstaller {
       : join(family.rootPath, ".claude");
     const apmYml = join(family.rootPath, "apm.yml");
 
-    // --skills-from takes precedence over apm install: the caller is supplying
+    // --skills-from takes precedence over apm install. The caller supplies
     // the skill tree explicitly, so no remote fetch runs.
     const hasApm =
       !skillsFrom &&
@@ -59,7 +59,7 @@ export class ApmInstaller {
         await fs.access(sourceClaude);
       } catch {
         throw new Error(
-          `apm install did not produce .claude/ at ${sourceClaude}; check the family's apm.yml`,
+          `apm install did not produce .claude/ at ${sourceClaude}. Check the family's apm.yml`,
         );
       }
     }
@@ -78,18 +78,18 @@ export class ApmInstaller {
       await fs.mkdir(stagedClaude, { recursive: true });
     }
 
-    // apm's claude target deploys a pack's skills/ into .claude/skills/ but
-    // never its agents/ subtree (agent profiles + references). Stage that from
-    // the installed apm_modules into .claude/agents/ so a skill that cites an
-    // agent reference (e.g. the work-item tracker matrix) resolves in the
-    // agent CWD. No-op when --skills-from supplied a tree or no apm_modules
-    // exist.
+    // apm's claude target deploys a pack's skills/ into .claude/skills/. It
+    // never deploys that pack's agents/ subtree (agent profiles +
+    // references). Stage that subtree from the installed apm_modules into
+    // .claude/agents/. A skill that cites an agent reference (e.g. the
+    // work-item tracker matrix) then resolves in the agent CWD. This is a
+    // no-op when --skills-from supplied a tree or no apm_modules exist.
     if (!skillsFrom) {
       await this.#stageApmAgents(family.rootPath, stagedClaude);
     }
 
-    // Stage the family-local judge profile outside .claude/ so it is available
-    // to the judge but never copied into the agent-under-test's CWD.
+    // Stage the family-local judge profile outside .claude/, so the judge can
+    // reach it. Nothing copies it into the agent-under-test's CWD.
     const judgeSource = join(family.rootPath, "judge.md");
     const judgeProfilesDir = join(stagingDir, "judge-profiles");
     try {
@@ -106,7 +106,7 @@ export class ApmInstaller {
         "sha256:" +
         createHash("sha256").update(normalizeLf(lockBytes)).digest("hex");
     } catch {
-      // No lockfile — family doesn't use skill packs.
+      // No lockfile. The family doesn't use skill packs.
     }
 
     return { stagingDir, skillSetHash, judgeProfilesDir };
@@ -115,8 +115,8 @@ export class ApmInstaller {
   /**
    * Merge each installed pack's `agents/` subtree (profiles + references) from
    * `apm_modules/<owner>/<pack>/agents/` into the staged `.claude/agents/`.
-   * apm's claude target deploys `skills/` only, so without this an agent
-   * reference a skill cites is absent from the agent CWD.
+   * apm's claude target deploys `skills/` only. Without this merge, an agent
+   * reference that a skill cites is absent from the agent CWD.
    * @param {string} familyRoot
    * @param {string} stagedClaude
    */
@@ -127,7 +127,7 @@ export class ApmInstaller {
     try {
       owners = await fs.readdir(modulesRoot, { withFileTypes: true });
     } catch {
-      return; // no apm_modules — nothing to stage
+      return; // no apm_modules, so nothing to stage
     }
     const stagedAgents = join(stagedClaude, "agents");
     for (const owner of owners) {
@@ -159,8 +159,8 @@ export class ApmInstaller {
       ["install", "--target", "claude"],
       { cwd, stdio: ["ignore", "pipe", "pipe"] },
     );
-    // Drain stdout concurrently so the child never blocks on backpressure;
-    // capture stderr for the failure message.
+    // Drain stdout concurrently so the child never blocks on backpressure.
+    // Capture stderr for the failure message.
     let stderr = "";
     const drainStdout = (async () => {
       for await (const _chunk of child.stdout) {
@@ -199,8 +199,8 @@ export function createApmInstaller(deps) {
  * @param {import("./task-family.js").TaskFamily} family
  * @param {string} outputDir
  * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
- * @param {object} [options] - Forwarded to `ApmInstaller.install` (e.g.
- *   `{ skillsFrom }`).
+ * @param {object} [options] - This function forwards these to
+ *   `ApmInstaller.install` (e.g. `{ skillsFrom }`).
  */
 export function installApm(family, outputDir, runtime, options = {}) {
   return new ApmInstaller({ runtime }).install(family, outputDir, options);

package/src/benchmark/env-loader.js

@@ -1,17 +1,20 @@
 /**
  * Env-loader — auto-discover `.env` / `.env.local` files in a task family
- * and its tasks, load them into `process.env`, and render the merged result
+ * and its tasks. Load them into `process.env`. Render the merged result
  * into each agent CWD.
  *
- * Discovery paths (loaded in this order, first value per key wins):
- *   1. process.env  (CI secrets, shell env — never overwritten)
+ * The loader reads the discovery paths in this order. The first value per
+ * key wins:
+ *   1. process.env  (CI secrets and shell env, which the loader never
+ *      overwrites)
  *   2. <family>/.env.local
  *   3. <family>/.env
  *   4. tasks/<id>/.env.local
  *   5. tasks/<id>/.env
  *
- * Every discovered env file — family or task — is loaded into process.env
- * AND rendered (with resolved values) into the agent working directory.
+ * The loader loads every discovered env file, family or task, into
+ * process.env. It also renders the file (with resolved values) into the
+ * agent working directory.
  */
 
 import { join } from "node:path";
@@ -20,7 +23,8 @@ const ENV_FILES = [".env.local", ".env"];
 
 /**
  * Parse a `.env` file into an array of {key, value} pairs.
- * Handles KEY=VALUE, # comments, blank lines, and single/double-quoted values.
+ * It handles KEY=VALUE, # comments, blank lines, and single/double-quoted
+ * values.
  * @param {string} content
  * @returns {Array<{key: string, value: string}>}
  */
@@ -46,7 +50,7 @@ export function parseEnvFile(content) {
 }
 
 /**
- * Read and parse an env file, returning [] if the file does not exist.
+ * Read and parse an env file. Return [] if the file does not exist.
  * @param {object} fs - Async filesystem surface (`runtime.fs`).
  * @param {string} filePath
  * @returns {Promise<Array<{key: string, value: string}>>}
@@ -62,10 +66,11 @@ async function readEnvFile(fs, filePath) {
 }
 
 /**
- * Load entries into the process env map. Existing keys are never overwritten.
+ * Load entries into the process env map. This function never overwrites an
+ * existing key.
  * @param {Record<string, string|undefined>} env - The `runtime.proc.env` map.
  * @param {Array<{key: string, value: string}>} entries
- * @returns {string[]} var names that were loaded
+ * @returns {string[]} the var names it loaded
  */
 function applyToProcessEnv(env, entries) {
   const names = [];
@@ -79,7 +84,8 @@ function applyToProcessEnv(env, entries) {
 }
 
 /**
- * Load one env file: apply to the env map, record keys in the merged map.
+ * Load one env file. Apply it to the env map. Record the keys in the merged
+ * map.
  * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  * @param {string} dir
  * @param {string} file
@@ -100,7 +106,7 @@ async function loadOneEnvFile(runtime, dir, file, names, merged) {
 }
 
 /**
- * Scan directories for env files, load into the env map, and collect
+ * Scan directories for env files. Load them into the env map. Collect
  * a merged key manifest per filename.
  * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  * @param {string[]} dirs
@@ -118,7 +124,7 @@ async function collectEnvEntries(runtime, dirs) {
 }
 
 /**
- * Write resolved env files into the agent CWD and warn about empty values.
+ * Write resolved env files into the agent CWD. Warn about empty values.
  * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  * @param {Map<string, Map<string, true>>} merged
  * @param {string} agentCwd
@@ -142,14 +148,16 @@ async function renderEnvFiles(runtime, merged, agentCwd) {
 }
 
 /**
- * Discover `.env` / `.env.local` in one or more directories, load them
- * into the process env map, and render the resolved values into the agent CWD.
+ * Discover `.env` / `.env.local` in one or more directories. Load them
+ * into the process env map. Render the resolved values into the agent CWD.
  *
  * @param {string[]} dirs - Directories to scan (family root, task dir, etc.)
  * @param {string} agentCwd - Agent working directory to render into.
  * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime - Ambient
- *   collaborators; uses `fs` (async read/write), `proc.env`, `proc.stderr`.
- * @returns {Promise<string[]>} All var names discovered (for redaction).
+ *   collaborators. It uses `fs` (async read/write), `proc.env`, and
+ *   `proc.stderr`.
+ * @returns {Promise<string[]>} Every var name the loader discovered (for
+ *   redaction).
  */
 export async function loadEnv(dirs, agentCwd, runtime) {
   const { names, merged } = await collectEnvEntries(runtime, dirs);

package/src/benchmark/grade.js

@@ -1,46 +1,50 @@
 /**
- * Grading derivation — the sole home of the check-row arithmetic.
+ * Grade derivation — the sole home of the check-row arithmetic.
  *
- * Check rows are the single authoritative grading channel. Every row is a
- * check by default; a row declares its role with its own fields, checked in
- * order:
+ * Check rows are the one authoritative input to the grade. Every row is a
+ * check by default. A row declares its role with its own fields. The
+ * classifier checks the roles in this order:
  *
  *   1. Gate       — `gate` is exactly `true`, `pass` is boolean, and no
- *                   `weight` key is present. Any failing gate → `gatesPass`
- *                   false.
- *   2. Diagnostic — no `gate` key and `weight` is exactly `0`. Free-form;
- *                   never graded.
+ *                   `weight` key is present. A gate that fails sets
+ *                   `gatesPass` to false.
+ *   2. Diagnostic — no `gate` key and `weight` is exactly `0`. The row is
+ *                   free-form. The grader never scores it.
  *   3. Scored     — no `gate` key, boolean `pass`, `weight` absent (defaults
  *                   to 1) or finite > 0.
- *   4. Malformed  — everything else: any `gate`+`weight` co-occurrence (a
- *                   stray weight must never silently disarm a gate), a
+ *   4. Malformed  — everything else: any `gate`+`weight` co-occurrence, a
  *                   non-boolean `gate`, a missing or non-boolean `pass` on a
  *                   graded row, an invalid `weight`, an fd-3 line that failed
- *                   to parse, a non-object row. Counts as a **failing scored
- *                   check** — dropping a defect could mint full marks;
- *                   failing the whole run would zero completed work.
+ *                   to parse, a non-object row. A stray weight must never
+ *                   silently disarm a gate. A malformed row counts as a
+ *                   **scored check that fails**. If the grader dropped the
+ *                   defect, the cell could mint full marks. If it failed the
+ *                   whole run, it would zero completed work.
  *
- * The producers' `source` stamp is display metadata, never a grading input.
+ * The producers' `source` stamp is display metadata. The grader never reads
+ * it.
  */
 
 /**
  * @typedef {object} GradeResult
  * @property {"pass" | "fail"} verdict - `healthy ∧ gatesPass ∧ fullMarks`.
  * @property {boolean} gatesPass - Every gate row passes (vacuously true).
- * @property {number | null} score - Weighted fraction of passing scored
- *   checks; `null` when the cell has zero scored checks (binary task).
- * @property {boolean} fullMarks - Integer count predicate: no malformed rows
- *   and every scored check passes. Never a float comparison, so fractional
- *   weights carry no equality hazard. Vacuously true with zero scored checks.
+ * @property {number | null} score - Weighted fraction of the scored checks
+ *   that pass. It is `null` when the cell has zero scored checks (binary
+ *   task).
+ * @property {boolean} fullMarks - An integer count predicate. It is true when
+ *   no row is malformed and every scored check passes. It is never a float
+ *   comparison, so fractional weights carry no equality hazard. It is
+ *   vacuously true with zero scored checks.
  * @property {number} malformed - Malformed row count.
  */
 
 /**
  * Grade the merged check rows against grader health.
  *
- * `healthy` is the completion signal a crashed grader cannot fake: when it is
- * false the verdict is `fail` whatever the rows say, so a hook that dies
- * after emitting passing rows can never mint marks.
+ * `healthy` is the completion signal a crashed grader cannot fake. When it is
+ * false, the verdict is `fail` whatever the rows say. A hook that emits rows
+ * that pass and then dies can never mint marks.
  * @param {unknown[]} details - Merged check rows from both producers.
  * @param {boolean} healthy - Invariants exited 0 AND the hidden-test engine
  *   did not throw.
@@ -73,7 +77,7 @@ export function gradeChecks(details, healthy) {
 }
 
 /**
- * Fold one row into the running tally per its classified role.
+ * Fold one row into the tally per its classified role.
  * @param {{gatesPass: boolean, malformed: number, scored: number, passing: number, weightAll: number, weightPassing: number}} tally
  * @param {unknown} row
  */
@@ -96,11 +100,10 @@ function tallyRow(tally, row) {
 }
 
 /**
- * Run both check-row producers and grade the merged rows — the one
- * composition shared by the runner and the `grade` subcommand. An engine
- * throw is grader fault: its message lands on the returned `engineError`
- * and health fails, so a crashed grader can never mint marks from rows it
- * happened to emit first.
+ * Run both check-row producers and grade the merged rows. The runner and the
+ * `grade` subcommand share this one composition. An engine throw is grader
+ * fault. Its message lands on the returned `engineError` and health fails. A
+ * crashed grader can never mint marks from rows it emitted first.
  * @param {import("./task-family.js").Task} task
  * @param {{cwd: string, port: number, runDir: string, familyDir?: string|null}} ctx
  * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
@@ -126,8 +129,8 @@ export async function runProducersAndGrade(task, ctx, runtime, producers) {
 
 /**
  * Merge the two producers' rows (invariants first) and stamp each row's
- * provenance. The stamp is display metadata, never a grading input, and
- * non-object rows (malformed by contract) pass through verbatim.
+ * provenance. The stamp is display metadata. The grader never reads it.
+ * Non-object rows (malformed by contract) pass through verbatim.
  * @param {unknown[]} invariantsDetails
  * @param {unknown[]} hiddenDetails
  * @returns {unknown[]}
@@ -147,9 +150,9 @@ function stampSource(row, source) {
 }
 
 /**
- * Project the raw `gradeChecks` return onto the record schema: `fullMarks`
- * is derivable and dropped, `score` is omitted on binary tasks (`null`),
- * `malformed` is omitted when clean.
+ * Project the raw `gradeChecks` return onto the record schema. `fullMarks` is
+ * derivable, so this function drops it. It omits `score` on binary tasks
+ * (`null`). It omits `malformed` when the rows are clean.
  * @param {GradeResult} raw
  * @returns {{verdict: "pass"|"fail", gatesPass: boolean, score?: number, malformed?: number}}
  */
@@ -177,9 +180,9 @@ function classifyRow(row) {
 }
 
 /**
- * A row carrying a `gate` key: valid only as `gate: true` with a boolean
- * `pass` and no `weight` key — any co-occurring weight is malformed so a
- * stray weight can never silently disarm a gate.
+ * Classify a row that has a `gate` key. The row is valid only as `gate: true`
+ * with a boolean `pass` and no `weight` key. Any weight that co-occurs makes
+ * the row malformed. A stray weight can never silently disarm a gate.
  * @param {object} row
  * @returns {"gate" | "malformed"}
  */
@@ -191,9 +194,9 @@ function classifyGateRow(row) {
 }
 
 /**
- * A gate-less row carrying a `weight` key: exactly 0 is a diagnostic, a
- * finite positive weight with a boolean `pass` is scored, anything else is
- * malformed.
+ * Classify a gate-less row that has a `weight` key. A weight of exactly 0 is
+ * a diagnostic. A finite positive weight with a boolean `pass` is scored.
+ * Anything else is malformed.
  * @param {object} row
  * @returns {"diagnostic" | "scored" | "malformed"}
  */
@@ -205,8 +208,8 @@ function classifyWeightedRow(row) {
 }
 
 /**
- * A malformed row fails at its own weight when it carries a valid positive
- * one, else at unit weight 1.
+ * A malformed row fails at its own weight when that weight is valid and
+ * positive. Otherwise it fails at unit weight 1.
  * @param {unknown} row
  * @returns {number}
  */

package/src/benchmark/hidden-tests.js

@@ -1,14 +1,14 @@
 /**
- * Hidden-test engine — executes a task's `tests/` overlay against the
- * post-run agent CWD: stage each file at its mirrored path, run each check
- * with `node --test`, convert the exit status into one check row, and
- * restore the tree so the judge sees the workdir exactly as the agent left
- * it.
+ * Hidden-test engine — runs a task's `tests/` overlay against the post-run
+ * agent CWD. The engine stages each file at its mirrored path. It runs each
+ * check with `node --test`. It converts the exit status into one check row.
+ * It restores the tree, so the judge sees the workdir exactly as the agent
+ * left it.
  *
- * Fault attribution is the engine's contract: a stage or spawn failure (the
- * agent deleted the scaffold) is a *failing row* — agent fault; the engine
- * itself throwing is grader fault, which the caller records as unhealthy so
- * a crashed grader can never mint marks.
+ * Fault attribution is the engine's contract. A stage or spawn failure (the
+ * agent deleted the scaffold) is agent fault, so the engine returns a *row
+ * that fails*. A throw from the engine itself is grader fault. The caller
+ * records that as unhealthy, so a crashed grader can never mint marks.
  */
 
 import { dirname, join } from "node:path";
@@ -16,8 +16,8 @@ import { dirname, join } from "node:path";
 import { buildHookEnv } from "./hook-env.js";
 
 // Fixed per-check budget. A wedged test process runs outside the agent
-// watchdog, so this bound is what keeps a hung hidden test from stalling the
-// cell; the timeout row keeps the failure visible.
+// watchdog. Without this bound, a hung hidden test would stall the cell. The
+// timeout row keeps the failure visible.
 const CHECK_TIMEOUT_MS = 120_000;
 const STDERR_TAIL_CHARS = 500;
 
@@ -50,9 +50,9 @@ export async function runHiddenTests(task, ctx, runtime, opts = {}) {
 }
 
 /**
- * Stage one check, run it, and restore its staging — the check's own row is
- * the only trace it leaves. A stage failure is the agent's fault (a deleted
- * scaffold), so it becomes a failing row rather than a throw.
+ * Stage one check, run it, then put the tree back. The check's own row is the
+ * only trace it leaves. A stage failure is the agent's fault (a deleted
+ * scaffold). The engine returns a row that fails. It does not throw.
  */
 async function runOneCheck(task, ctx, runtime, timeoutMs, check) {
   const stager = newStager();
@@ -71,7 +71,8 @@ async function runOneCheck(task, ctx, runtime, timeoutMs, check) {
 /**
  * Spawn `node --test <staged path>` from the agent CWD under the hook env
  * and map the exit status onto one row. The clock timer SIGKILLs a child
- * that outlives the per-check budget; the row fails with a timeout message.
+ * that outlives the per-check budget. The row then fails with a timeout
+ * message.
  */
 async function spawnCheck(task, ctx, runtime, timeoutMs, check) {
   const env = buildHookEnv(runtime.proc.env, {
@@ -83,8 +84,8 @@ async function spawnCheck(task, ctx, runtime, timeoutMs, check) {
     familyDir: ctx.familyDir,
   });
   // An inherited test-runner context makes the child `node --test` report
-  // exit 0 even when its tests fail — a failing check would mint a passing
-  // row whenever the harness itself runs under `node --test`.
+  // exit 0 even when its tests fail. A check that fails would then mint a row
+  // that passes whenever the harness itself runs under `node --test`.
   delete env.NODE_TEST_CONTEXT;
   const child = runtime.subprocess.spawn("node", ["--test", check.stagePath], {
     cwd: ctx.cwd,
@@ -129,8 +130,8 @@ function newStager() {
 }
 
 /**
- * Copy the symlink-resolved source to its mirrored path under the agent CWD,
- * backing up a collided file's bytes and tracking every directory created so
+ * Copy the symlink-resolved source to its mirrored path under the agent CWD.
+ * Back up the bytes of a collided file. Track every directory created, so
  * `unstage` can put the tree back exactly.
  */
 async function stageFile(fs, cwd, stager, { sourcePath, stagePath }) {
@@ -154,7 +155,7 @@ async function ensureParents(fs, cwd, stager, dir) {
     await fs.access(dir);
     return;
   } catch {
-    // missing — create below
+    // missing, so create it below
   }
   await ensureParents(fs, cwd, stager, dirname(dir));
   await fs.mkdir(dir);
@@ -162,10 +163,10 @@ async function ensureParents(fs, cwd, stager, dir) {
 }
 
 /**
- * Reverse the staging: staged copies out, collided bytes back, created
- * directories removed (deepest first — a check's own artifacts inside a
- * created directory go with it, since that directory did not exist when the
- * agent finished).
+ * Reverse the stage step. Remove the staged copies. Write the collided bytes
+ * back. Remove the created directories, deepest first. A check's own
+ * artifacts inside a created directory go with it, because that directory did
+ * not exist when the agent finished.
  */
 async function unstage(fs, stager) {
   for (const target of stager.staged) {

package/src/benchmark/hook-env.js

@@ -1,12 +1,13 @@
 /**
- * Shared environment builder for the benchmark hook scripts (`preflight.sh` and
- * `invariants.sh`). Keeping both spawns on one helper guarantees they expose the
- * same variable set, so hook authors never have to wonder which vars a given
- * hook receives.
+ * Shared environment builder for the benchmark hook scripts (`preflight.sh`
+ * and `invariants.sh`). One helper serves both spawns, so both expose the
+ * same variable set. Hook authors never have to wonder which vars a hook
+ * receives.
  *
  * Path vars (TASK_DIR, FAMILY_DIR, HOOKS_DIR) let hooks reference real
- * locations instead of reconstructing them from `$0`. They are paths, not
- * secrets, so they need no redaction allowlist entry.
+ * locations. Hooks do not have to rebuild the locations from `$0`. They are
+ * paths. They are not secrets, so they need no entry in the redaction
+ * allowlist.
  */
 
 /**
@@ -27,9 +28,10 @@ export function buildHookEnv(
 ) {
   return {
     ...baseEnv,
-    // The agent CWD itself — hooks reference emitted files as `$AGENT_CWD/<path>`.
-    // Distinct from the `invariants` CLI's `--run-dir` (the parent that
-    // *contains* `cwd/`), so the two are never confused.
+    // The agent CWD itself. Hooks reference emitted files as
+    // `$AGENT_CWD/<path>`. This var is distinct from the `invariants` CLI's
+    // `--run-dir` (the parent that *contains* `cwd/`), so the two are never
+    // confused.
     AGENT_CWD: cwd,
     PORT: String(port),
     TASK_ID: taskId,

package/src/benchmark/invariants.js

@@ -1,14 +1,15 @@
 /**
  * Invariants — runs `<task.paths.hooks>/invariants.sh` from the template path
- * against the post-run agent CWD. A pure collector with no verdict of its
- * own: structured per-check rows arrive on fd 3 (`$RESULTS_FD=3`) as NDJSON
- * and grading happens downstream over the merged rows. The exit code is
- * script health only — nonzero means the grader itself failed, never that a
- * check failed.
+ * against the post-run agent CWD. The module is a pure collector with no
+ * verdict of its own. Structured per-check rows arrive on fd 3
+ * (`$RESULTS_FD=3`) as NDJSON. Downstream code grades the merged rows. The
+ * exit code is script health only. A nonzero code means the grader itself
+ * failed. It never means that a check failed.
  *
- * Subprocess access flows through `runtime.subprocess.spawn`; the fd-3 backing
- * store and the stderr log use the sync filesystem surface (`runtime.fsSync`) —
- * the only surface this module touches, per design Decision 7.
+ * Subprocess access flows through `runtime.subprocess.spawn`. The fd-3
+ * backing store and the stderr log use the sync filesystem surface
+ * (`runtime.fsSync`). That surface is the only one this module touches, per
+ * design Decision 7.
  */
 
 import { join } from "node:path";
@@ -18,11 +19,12 @@ import { buildHookEnv } from "./hook-env.js";
 /**
  * @typedef {object} InvariantsResult
  * @property {Array<object>} details
- * @property {number} exitCode - Script health: nonzero means the hook itself
- *   failed, never that a check failed.
+ * @property {number} exitCode - Script health. A nonzero code means the hook
+ *   itself failed. It never means that a check failed.
  * @property {string} [stderr] - Trimmed script stderr, present only when the
- *   script wrote to stderr. Surfaces hook failures (e.g. a missing tool) that
- *   leave `details` empty, so they read distinctly from a real invariant miss.
+ *   script wrote to stderr. This field surfaces hook failures (e.g. a missing
+ *   tool) that leave `details` empty. A reader can then tell them apart from
+ *   a real invariant miss.
  */
 
 /**
@@ -43,8 +45,8 @@ export async function runInvariants(task, ctx, runtime) {
 
   // Bun's child_process pipe setup for fd >= 3 is racy under load (it
   // creates a unix socket pair and the connect() can return ENOENT). Use
-  // a temp file as the fd-3 backing store instead — the script still
-  // writes via `$RESULTS_FD`, but we hand it a real file descriptor.
+  // a temp file as the fd-3 backing store instead. The script still writes
+  // through `$RESULTS_FD`, but we hand it a real file descriptor.
   const fd3Path = join(ctx.runDir, "invariants.fd3.ndjson");
   const fd3File = fsSync.openSync(fd3Path, "w+");
 
@@ -69,7 +71,8 @@ export async function runInvariants(task, ctx, runtime) {
     throw e;
   }
 
-  // Drain stdout (do not require consumers to read it); capture stderr to log.
+  // Drain stdout (do not require consumers to read it). Capture stderr to
+  // the log.
   const drainStdout = (async () => {
     for await (const _chunk of child.stdout) {
       // discard
@@ -127,8 +130,8 @@ function readAndUnlink(fsSync, path) {
 }
 
 /**
- * Parse the fd-3 buffer (read from the temp-file backing) into one NDJSON
- * row per detail entry.
+ * Parse the fd-3 buffer (read from the temp-file backing store) into one
+ * NDJSON row per detail entry.
  */
 function parseFd3Buffer(buf, details) {
   if (!buf) return;