@forwardimpact/libharness 3.0.0 → 3.0.1

package/src/commands/run.js

@@ -34,8 +34,8 @@ export function parseRunOptions(values, runtime) {
     values,
     runtime,
   );
-  // `||` (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 maxTurnsRaw = values["max-turns"] || "50";
 
   return {
@@ -64,10 +64,10 @@ const devNull = new Writable({
 
 /**
  * Wire the run-mode agent session: external MCP entry, `LIBHARNESS_*` env
- * writes, system-prompt composition, and — when an advisor model is set —
- * the advisor wiring (budget, recorder, advisor session, dedicated MCP
- * server holding only the `Advisor` tool). Extracted from `runRunCommand`
- * so tests can inject a fake `query`.
+ * writes, and system-prompt composition. When an advisor model is set, also
+ * wire the advisor (budget, recorder, advisor session, and a dedicated MCP
+ * server that holds only the `Advisor` tool). This function is extracted
+ * from `runRunCommand` so a test can inject a fake `query`.
  *
  * Run mode has no stop path (the command simply awaits the runner), so the
  * consult timeout is deliberately the advisor's only guard.
@@ -120,9 +120,9 @@ export async function wireRunSession({
   runtime.proc.env.LIBHARNESS_WORK_TRACKER = opts.workTracker;
 
   // With a profile, the consult guidance rides the profile composer's
-  // amendment parameter; with no profile, a preset-append prompt carries
+  // amendment parameter. With no profile, a preset-append prompt carries
   // the guidance as its only session-protocol fragment. Advisor off and no
-  // profile means no system prompt — today's behavior, unchanged.
+  // profile means no system prompt. That is today's behavior, unchanged.
   let systemPrompt;
   if (opts.agentProfile) {
     systemPrompt = composeProfilePrompt(opts.agentProfile, {
@@ -161,7 +161,7 @@ export async function wireRunSession({
       budget,
       model: opts.advisorModel,
     });
-    // No allowlist push: in-process SDK MCP servers work under
+    // No allowlist push. In-process SDK MCP servers work under
     // bypassPermissions without allowlist entries (loop-mode precedent).
     mcpServers = {
       ...mcpServers,
@@ -195,7 +195,7 @@ export async function wireRunSession({
 }
 
 /**
- * Run command — execute a single agent via the Claude Agent SDK.
+ * Run command — execute a single agent through the Claude Agent SDK.
  *
  * Usage: gemba-harness run [options]
  *
@@ -206,12 +206,12 @@ export async function runRunCommand(ctx) {
   const runtime = ctx.deps.runtime;
   const opts = parseRunOptions(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 });
 
-  // When --output is specified, stream text to stdout while writing NDJSON to file.
+  // With --output, stream text to stdout and write NDJSON to the file.
   // Otherwise, write NDJSON directly to stdout (backwards-compatible).
   const fileStream = opts.outputPath
     ? runtime.fs.createWriteStream(opts.outputPath)

package/src/commands/scan-logs.js

@@ -2,27 +2,28 @@
  * `gemba-harness scan-logs` — scan a run's log archive for secret literals and
  * fail closed.
  *
- * A run-lifecycle concern (not an NDJSON trace, so it lives here rather than
- * in `gemba-trace`): after a CI run that handled secrets, download or accept the
- * run's own log archive and assert none of a supplied set of literals leaked
- * into it. Any hit exits non-zero; any download/extract failure also exits
- * non-zero — the gate must never silently disarm.
+ * This is a run-lifecycle concern. It is not an NDJSON trace, so it lives
+ * here rather than in `gemba-trace`. After a CI run that handled secrets,
+ * download or accept the run's own log archive. Then assert that none of a
+ * supplied set of literals leaked into it. Any hit exits non-zero. Any
+ * download or extract failure also exits non-zero. The gate must never
+ * silently disarm.
  *
  * Log resolution:
  *   - `--archive <zip>` — an already-resolved archive (extracted locally).
- *   - `--run-id <id> --repo <owner/repo>` — download this run's archive via
+ *   - `--run-id <id> --repo <owner/repo>` — download this run's archive with
  *     `gh` first, then extract.
  *
  * Secrets are `--secret <label>=<literal>`, repeatable. The literal is
- * everything after the FIRST `=` (JWTs and base64 keys contain `=`); the label
- * is only cosmetic, named in the `FAIL:` line.
+ * everything after the FIRST `=` (JWTs and base64 keys contain `=`). The
+ * label is only cosmetic. The `FAIL:` line names it.
  */
 
 import { join } from "node:path";
 
 /**
  * Parse repeatable `--secret label=literal` flags. libcli's `multiple: true`
- * yields an array from node's parseArgs in every case; tolerate a bare string
+ * yields an array from node's parseArgs in every case. Tolerate a bare string
  * or undefined defensively. Split on the FIRST `=` only.
  *
  * @param {string[]|string|undefined} secretOpt
@@ -42,8 +43,9 @@ export function parseSecrets(secretOpt) {
 }
 
 /**
- * Walk a directory tree and return every file path. Uses per-level readdir so
- * it works against both node:fs and the libmock fs (no `recursive` reliance).
+ * Walk a directory tree and return every file path. It uses per-level readdir
+ * so it works against both node:fs and the libmock fs (no `recursive`
+ * reliance).
  */
 async function collectFiles(dir, runtime) {
   const out = [];
@@ -60,9 +62,9 @@ async function collectFiles(dir, runtime) {
 }
 
 /**
- * Scan every file under `dir` for each secret literal. Returns the labels of
- * secrets whose non-empty literal appears in any file (empty literals are
- * skipped — a secret the run never set cannot leak).
+ * Scan every file under `dir` for each secret literal. Return the labels of
+ * secrets whose non-empty literal appears in any file. The scan skips empty
+ * literals, because a secret the run never set cannot leak.
  *
  * @param {object} params
  * @param {string} params.dir
@@ -84,9 +86,9 @@ export async function scanDirectory({ dir, secrets, runtime }) {
 }
 
 /**
- * Resolve a directory of extracted log files, downloading the archive first
- * when given a run id. Throws (→ fail closed) on any download or extract
- * failure or on missing/invalid inputs.
+ * Resolve a directory of extracted log files. Download the archive first when
+ * the caller gives a run id. Throw (→ fail closed) on any download or extract
+ * failure, and on a missing or invalid input.
  */
 async function resolveLogsDir({ options, runtime }) {
   const tmpRoot = runtime.proc.env.RUNNER_TEMP || "/tmp";
@@ -142,8 +144,8 @@ export async function runScanLogsCommand(ctx) {
   try {
     dir = await resolveLogsDir({ options, runtime });
   } catch (err) {
-    // Fail closed: an unresolvable archive must not pass as "no leak". The
-    // dispatcher prints the returned `error`, so don't also write it here.
+    // Fail closed. An unresolvable archive must not pass as "no leak". The
+    // dispatcher prints the returned `error`, so do not also write it here.
     return { ok: false, code: 1, error: `scan-logs: ${err.message}` };
   }
 

package/src/commands/selfedit.js

@@ -1,15 +1,15 @@
 /**
- * Safeguard-and-write logic behind the `gemba-selfedit` bin: write content
- * to a path that .claude/settings.json permits Edit on, while on a non-main
- * git branch. See libraries/libharness/README.md § gemba-selfedit for the
- * full rationale.
+ * Safeguard-and-write logic behind the `gemba-selfedit` bin. It writes
+ * content to a path that .claude/settings.json permits Edit on. The write
+ * happens only on a non-main git branch. See
+ * libraries/libharness/README.md § gemba-selfedit for the full rationale.
  */
 
 import { resolve, relative, dirname } from "node:path";
 
 import { minimatch } from "minimatch";
 
-/** A safeguard violation — callers map it to exit code 2. */
+/** A safeguard violation. Callers map it to exit code 2. */
 export class SelfeditError extends Error {
   /** @param {string} message failure description */
   constructor(message) {
@@ -21,18 +21,18 @@ export class SelfeditError extends Error {
 /**
  * Check every safeguard for a selfedit write, then perform it.
  *
- * Safeguards (checked in order):
+ * The function checks these safeguards in order:
  * 1. The nearest .claude/settings.json must contain an Edit(<glob>) rule in
  *    permissions.allow[] that resolves to the target path.
  * 2. HEAD must not be detached and the current branch must not be 'main'.
  * 3. The target's parent directory must exist.
  *
- * @param {string} targetArg target path as given on the command line
+ * @param {string} targetArg target path from the command line
  * @param {Buffer} content bytes to write
  * @param {{ runtime: object }} deps runtime bag (fsSync, proc, subprocess,
- *   finder); targetArg resolves against `runtime.proc.cwd()`
+ *   finder). targetArg resolves against `runtime.proc.cwd()`
  * @returns {{ bytes: number, relativeTarget: string, matchedPattern: string,
- *   branch: string }} what was written and which rule allowed it
+ *   branch: string }} what the function wrote and which rule allowed it
  * @throws {SelfeditError} on any safeguard violation
  */
 export function runSelfeditCommand(targetArg, content, { runtime }) {
@@ -41,7 +41,7 @@ export function runSelfeditCommand(targetArg, content, { runtime }) {
   const absoluteTarget = resolve(cwd, targetArg);
 
   // Safeguard 1: settings.json must grant Edit() on this path. Resolve the
-  // finder off the runtime bag rather than constructing a Finder here.
+  // finder off the runtime bag. Do not construct a Finder here.
   const settingsPath = finder.findUpward(
     dirname(absoluteTarget),
     ".claude/settings.json",
@@ -89,25 +89,25 @@ export function runSelfeditCommand(targetArg, content, { runtime }) {
     );
   }
 
-  // Safeguard 2: branch must not be main and HEAD must not be detached.
+  // Safeguard 2: the branch must not be main and HEAD must not be detached.
   const git = subprocess.runSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
     cwd,
   });
   if (git.exitCode !== 0) {
     throw new SelfeditError(
-      "failed to read current git branch (not inside a git repository?)",
+      "failed to read the current git branch (this may not be a git repository)",
     );
   }
   const branch = git.stdout.trim();
 
   if (branch === "HEAD") {
     throw new SelfeditError(
-      "HEAD is detached — refusing (check out a non-main branch first)",
+      "will not write while HEAD is detached. Check out a non-main branch first",
     );
   }
   if (branch === "main") {
     throw new SelfeditError(
-      "refusing to write while on branch 'main' — switch to a feature branch",
+      "will not write while on branch 'main'. Switch to a feature branch",
     );
   }
 

package/src/commands/supervise.js

@@ -23,7 +23,8 @@ export async function parseSuperviseOptions(values, runtime) {
   const supervisorAllowedToolsRaw = values["supervisor-allowed-tools"];
 
   // `||` (not `??`) throughout so an empty-string flag from a CI forwarder
-  // falls back to the default rather than overriding it with "".
+  // falls back to the default. The empty string does not override the
+  // default.
   const tmpRoot = runtime.proc.env.TMPDIR ?? "/tmp";
   const agentCwd = resolve(
     values["agent-cwd"] ||
@@ -58,9 +59,9 @@ export async function parseSuperviseOptions(values, runtime) {
 }
 
 /**
- * Supervise command — run one agent under a supervisor via the
- * orchestration loop. The supervisor delegates work through Ask, sees
- * each reply on its next turn, and ends with Conclude.
+ * Supervise command — run one agent under a supervisor through the
+ * orchestration loop. The supervisor delegates work through Ask. It sees
+ * each reply on its next turn. It ends with Conclude.
  *
  * Usage: gemba-harness supervise [options]
  *
@@ -71,12 +72,12 @@ export async function runSuperviseCommand(ctx) {
   const runtime = ctx.deps.runtime;
   const opts = await parseSuperviseOptions(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 });
 
-  // When --output is specified, stream text to stdout while writing NDJSON to file.
+  // With --output, stream text to stdout and write NDJSON to the file.
   // Otherwise, write NDJSON directly to stdout (backwards-compatible).
   const fileStream = opts.outputPath
     ? runtime.fs.createWriteStream(opts.outputPath)
@@ -107,7 +108,8 @@ export async function runSuperviseCommand(ctx) {
     runtime.proc.env.LIBHARNESS_AGENT_PROFILE = opts.agentProfile;
   }
   // 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/task-input.js

@@ -1,18 +1,18 @@
 import { composeTaskFromGitHubEvent } from "../events/github.js";
 
 /**
- * Resolve `--task-file` / `--task-text` / `--task-event` into the task pair the
- * runner consumes. Exactly one of the three must be set. For `--task-event`,
- * libharness reads the event payload and extracts both the main task (from the
- * template that matches `$GITHUB_EVENT_NAME` + `payload.action`) and the
- * amendment (from `payload.inputs?.prompt`) — so the workflow doesn't need to
- * wire `--task-amend` separately. For the other two modes, `--task-amend`
- * works as before.
+ * Resolve `--task-file` / `--task-text` / `--task-event` into the task pair
+ * the runner consumes. Exactly one of the three must be set. For
+ * `--task-event`, libharness reads the event payload. It extracts both the
+ * main task (from the template that matches `$GITHUB_EVENT_NAME` +
+ * `payload.action`) and the amendment (from `payload.inputs?.prompt`). So the
+ * workflow does not need to wire `--task-amend` separately. For the other two
+ * modes, `--task-amend` works as before.
  *
  * @param {object} values - Parsed option values from cli.parse()
  * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime - Ambient
- *   collaborators; `fsSync.readFileSync` loads `--task-file`/`--task-event`
- *   and `proc.env` resolves `GITHUB_EVENT_NAME`.
+ *   collaborators. `fsSync.readFileSync` loads `--task-file`/`--task-event`.
+ *   `proc.env` resolves `GITHUB_EVENT_NAME`.
  * @returns {{ task: string, amend: string | undefined }}
  */
 export function resolveTaskContent(values, runtime) {

package/src/commands/tee.js

@@ -4,10 +4,11 @@ import { isoTimestamp } from "@forwardimpact/libutil";
 import { createTeeWriter } from "../tee-writer.js";
 
 /**
- * Tee command — stream text output to stdout while optionally saving the raw
- * NDJSON to a file. Reads stdin line-by-line through the injected runtime and
- * re-delimits each record with a newline so the TeeWriter's line splitter sees
- * the same framing the raw byte stream produced.
+ * Tee command — stream text output to stdout. Save the raw NDJSON to a file
+ * when the caller gives an output path. The command reads stdin line by line
+ * through the injected runtime. It re-delimits each record with a newline.
+ * The TeeWriter's line splitter then sees the same record boundaries that the
+ * raw byte stream produced.
  *
  * Usage: gemba-harness tee [output.ndjson] < trace.ndjson
  *
@@ -21,8 +22,8 @@ export async function runTeeCommand(ctx) {
     ? runtime.fs.createWriteStream(outputPath)
     : null;
 
-  // TeeWriter requires a fileStream; when no output file is specified,
-  // use a PassThrough as a no-op sink (NDJSON is not saved).
+  // TeeWriter requires a fileStream. When the caller gives no output file,
+  // use a PassThrough as a no-op sink. The command then saves no NDJSON.
   const sink = fileStream ?? new PassThrough();
   const tee = createTeeWriter({
     fileStream: sink,
@@ -32,9 +33,9 @@ export async function runTeeCommand(ctx) {
   });
 
   try {
-    // `runtime.proc.stdin` yields newline-stripped lines; re-append `\n` so the
-    // TeeWriter's `_write` line splitter frames records exactly as it did when
-    // piped the raw byte stream.
+    // `runtime.proc.stdin` yields newline-stripped lines. Re-append `\n` so
+    // the TeeWriter's `_write` line splitter frames records exactly as it did
+    // when the caller piped the raw byte stream into it.
     const lines = (async function* () {
       for await (const line of runtime.proc.stdin) yield `${line}\n`;
     })();

package/src/commands/trace.js

@@ -20,18 +20,18 @@ import {
 //   ctx.options — parsed flag values (`cli.parse().values`)
 //   ctx.args    — named positionals declared on the subcommand
 //   ctx.deps    — host-injected collaborators: `{ runtime, config }`
-// Handlers read/write the filesystem and stdout exclusively through
-// `ctx.deps.runtime` and return `{ ok: true }` on success.
+// Handlers read and write the filesystem and stdout only through
+// `ctx.deps.runtime`. They return `{ ok: true }` on success.
 
-/** Characters whose presence in a `--file` value marks it as a glob. */
+/** These characters mark a `--file` value as a glob. */
 const GLOB_CHARS = /[*?[\]{}]/;
 
 /**
  * Resolve the cross-trace `--file` option (`ctx.options.file`) into a sorted
- * flat list of file paths. A literal path passes through; a value carrying
- * glob metacharacters expands via `runtime.fsSync.globSync`. The literal-path
- * fast path means the common single-file and shell-pre-expanded cases never
- * touch `globSync`.
+ * flat list of file paths. A literal path passes through. A value that
+ * carries glob metacharacters expands through `runtime.fsSync.globSync`. The
+ * literal-path fast path means the common single-file and shell-pre-expanded
+ * cases never touch `globSync`.
  * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  * @param {import("@forwardimpact/libcli").InvocationContext} ctx
  * @returns {string[]}
@@ -51,10 +51,11 @@ function resolveFiles(runtime, ctx) {
 }
 
 /**
- * Emit a query result for a cross-trace verb: under `--format json` write the
- * JSON payload (single-object verbs unwrap when single-file so the envelope
- * deep-equals today's output); otherwise render text to stdout. Source
- * attribution is the renderer's job, gated by `multi`.
+ * Emit a query result for a cross-trace verb. Under `--format json` this
+ * function writes the JSON payload. Single-object verbs unwrap when there is
+ * one file, so the envelope deep-equals today's output. Otherwise this
+ * function renders text to stdout. The renderer owns source attribution.
+ * `multi` gates it.
  * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  * @param {object|object[]} result
  * @param {Function} renderer
@@ -78,7 +79,7 @@ function emit(runtime, result, renderer, ctx, multi, unwrap = false) {
 // --- GitHub commands ---
 
 /**
- * List recent workflow runs matching a pattern.
+ * List recent workflow runs that match a pattern.
  * @param {import("@forwardimpact/libcli").InvocationContext} ctx
  */
 export async function runRunsCommand(ctx) {
@@ -332,8 +333,8 @@ export async function runStatsCommand(ctx) {
   if (files.length === 0) return noFiles("stats");
   const multi = files.length > 1;
   const query = statsQuery(ctx);
-  // stats results are per-file objects; one block per file (no cross-file sum),
-  // tagged with source only when multi-file.
+  // stats results are per-file objects. Each file gets one block and no
+  // cross-file sum. Each block carries a source tag only when multi-file.
   const results = files.map((file) => ({
     result: query(loadTrace(runtime, file)),
     source: multi ? basename(file) : undefined,
@@ -356,20 +357,22 @@ export async function runStatsCommand(ctx) {
 }
 
 /**
- * Total run cost across every participant (agent, supervisor, judge, and any
- * named profile), summed from each `result` event in the trace and attributed
- * per source. The combined trace from a supervised, facilitated, or discuss
- * session already interleaves all participants, so one file yields the whole
- * run's spend. Default output is `{totalCostUsd, bySource}` JSON; `--markdown`
- * emits a GitHub-flavored block to redirect into `$GITHUB_STEP_SUMMARY`.
+ * Report the total run cost across every participant (agent, supervisor,
+ * judge, and any named profile). The command sums each `result` event in the
+ * trace. It attributes the cost per source. The combined trace from a
+ * supervised, facilitated, or discuss session already interleaves all
+ * participants, so one file yields the whole run's spend. The default output
+ * is `{totalCostUsd, bySource}` JSON. `--markdown` emits a GitHub-flavored
+ * block to redirect into `$GITHUB_STEP_SUMMARY`.
  *
  * @param {import("@forwardimpact/libcli").InvocationContext} ctx
  */
 export async function runCostCommand(ctx) {
   const { runtime } = ctx.deps;
-  // Tolerate a missing/empty trace: a CI step reports cost under `always()`,
-  // so the trace may not exist (the run failed before producing one). Print
-  // nothing and exit 0 rather than throwing — the caller needs no `if [ -f ]`.
+  // Tolerate a missing or empty trace. A CI step reports cost under
+  // `always()`, so the trace may not exist. The run can fail before it
+  // produces one. Print nothing and exit 0. Do not throw. The caller then
+  // needs no `if [ -f ]`.
   const file = ctx.args.file;
   if (!file || !runtime.fsSync.existsSync(file)) return { ok: true };
   const cost = computeTraceCost(runtime.fsSync.readFileSync(file, "utf8"));
@@ -383,7 +386,8 @@ export async function runCostCommand(ctx) {
 
 /**
  * Render a cost summary as a GitHub-flavored markdown block for a CI step
- * summary: a headline total plus a per-participant table (descending).
+ * summary. The block holds a headline total and a per-participant table. The
+ * table lists the highest cost first.
  * @param {{totalCostUsd: number, bySource: Record<string, number>}} cost
  * @returns {string}
  */
@@ -391,7 +395,7 @@ function renderCostMarkdown(cost) {
   const lines = [
     `### 💰 Run cost: $${cost.totalCostUsd.toFixed(4)}`,
     "",
-    "Summed across every participant (agent, supervisor, judge, named profiles).",
+    "This total covers every participant (agent, supervisor, judge, named profiles).",
   ];
   const sources = Object.entries(cost.bySource).sort((a, b) => b[1] - a[1]);
   if (sources.length > 0) {
@@ -492,21 +496,27 @@ export async function runCompareCommand(ctx) {
 
 // --- Split command ---
 
-/** Valid source name pattern: lowercase letter, then lowercase alphanumeric or hyphen. */
+/**
+ * A valid source name starts with a lowercase letter. The rest uses lowercase
+ * alphanumeric characters or hyphens.
+ */
 const VALID_SOURCE_NAME = /^[a-z][a-z0-9-]*$/;
 
-/** Sources whose name is itself a structural role; classified into the role they represent. */
+/**
+ * Sources whose name is itself a structural role. The splitter classifies
+ * each one into the role it represents.
+ */
 const STRUCTURAL_ROLES = new Set(["agent", "supervisor", "facilitator"]);
 
 /**
- * Split a combined NDJSON trace into per-source files using the
- * `trace--<case>--<participant>.<role>.ndjson` convention.
+ * Split a combined NDJSON trace into per-source files. The output names
+ * follow the `trace--<case>--<participant>.<role>.ndjson` convention.
  *
  * Each valid envelope source becomes one output file. Structural sources
- * (`agent`, `supervisor`, `facilitator`) classify into the matching role and
- * use their own name as participant; profile-named sources (e.g.
+ * (`agent`, `supervisor`, `facilitator`) classify into the matching role.
+ * They use their own name as participant. Profile-named sources (e.g.
  * `staff-engineer`) classify as agents with the profile in the participant
- * slot. Orchestrator events and invalid source names are dropped.
+ * slot. The command drops orchestrator events and invalid source names.
  *
  * @param {import("@forwardimpact/libcli").InvocationContext} ctx
  */
@@ -515,9 +525,10 @@ export async function runSplitCommand(ctx) {
   const file = ctx.args.file;
   if (!file) return { ok: false, code: 1, error: "split: missing input file" };
 
-  // `discuss` has the same lead + N-participants shape as `facilitate`, and the
-  // splitter buckets purely by envelope `source` (mode-independent), so it is
-  // accepted alongside the structural modes — the CLI owns this, not callers.
+  // `discuss` has the same lead + N-participants shape as `facilitate`. The
+  // splitter buckets purely by envelope `source`, which is mode-independent.
+  // So the CLI accepts `discuss` alongside the structural modes. The CLI owns
+  // this rule. Callers do not.
   const mode = ctx.options.mode;
   if (!mode) return { ok: false, code: 1, error: "split: --mode is required" };
   if (!["run", "supervise", "facilitate", "discuss"].includes(mode)) {
@@ -578,8 +589,9 @@ function parseBuckets(content) {
 
 /**
  * Compute total + per-source cost from raw file content. A structured JSON
- * trace (from `gemba-trace download`) carries its total in `summary.totalCostUsd`
- * but no per-source split; raw NDJSON is summed via `sumTraceCost`.
+ * trace (from `gemba-trace download`) carries its total in
+ * `summary.totalCostUsd` but no per-source split. `sumTraceCost` sums raw
+ * NDJSON.
  * @param {string} content - Raw file content (structured JSON or NDJSON).
  * @returns {{totalCostUsd: number, bySource: Record<string, number>}}
  */
@@ -590,7 +602,7 @@ function computeTraceCost(content) {
       return { totalCostUsd: parsed.summary.totalCostUsd, bySource: {} };
     }
   } catch {
-    // Not a single JSON object — treat as NDJSON below.
+    // Not a single JSON object. Treat it as NDJSON below.
   }
   return sumTraceCost(content.split("\n"));
 }
@@ -610,7 +622,7 @@ export function loadTrace(runtime, file) {
       return createTraceQuery(parsed);
     }
   } catch {
-    // Not valid JSON — fall through to NDJSON.
+    // Not valid JSON. Fall through to NDJSON.
   }
 
   const collector = createTraceCollector({
@@ -623,9 +635,10 @@ export function loadTrace(runtime, file) {
 }
 
 /**
- * Write JSON output to stdout. By default strips `thinking.signature`
- * base64 blobs from the payload so they don't dominate terminal output;
- * pass `--signatures` (surfaced as `values.signatures`) to keep them.
+ * Write JSON output to stdout. By default the function strips
+ * `thinking.signature` base64 blobs from the payload so they do not dominate
+ * terminal output. Pass `--signatures` (surfaced as `values.signatures`) to
+ * keep them.
  * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  * @param {*} data
  * @param {object} [values]

package/src/commands/work-tracker.js

@@ -1,7 +1,7 @@
 /**
  * The active work-item tracker selects which column of the work-trackers
  * matrix realizes each coordination operation (see the agent reference
- * `work-trackers.md`). `github` is the production binding; the offline
+ * `work-trackers.md`). `github` is the production binding. The offline
  * coordination benchmark runs under `filesystem`.
  */
 export const DEFAULT_WORK_TRACKER = "github";
@@ -14,10 +14,11 @@ export const KNOWN_WORK_TRACKERS = ["github", "filesystem"];
  * flag, then an inherited `LIBHARNESS_WORK_TRACKER` on the environment (so a CI
  * job or harness can select it without the flag), then the `github` default.
  * The harness writes the result to `LIBHARNESS_WORK_TRACKER` on the agent
- * environment, mirroring `--agent-profile` → `LIBHARNESS_AGENT_PROFILE`.
+ * environment. This mirrors `--agent-profile` → `LIBHARNESS_AGENT_PROFILE`.
  * @param {Record<string, string|undefined>} values - Parsed option values
  * @param {Record<string, string|undefined>} [env] - Process environment
- *   (e.g. `runtime.proc.env`); read for the `LIBHARNESS_WORK_TRACKER` fallback.
+ *   (e.g. `runtime.proc.env`). The function reads it for the
+ *   `LIBHARNESS_WORK_TRACKER` fallback.
  * @returns {string}
  * @throws {Error} if the resolved tracker is unknown
  */