@forwardimpact/libharness 3.0.0 → 3.0.1

package/README.md

@@ -8,22 +8,23 @@ worked.
 
 <!-- END:description -->
 
-`libharness` provides the runtime and tool surface for multi-LLM coordination —
-an agent talks to a supervisor, a facilitator chairs a meeting, a lead drives
-an asynchronous discussion — plus a CLI suite that runs evals, queries the
-traces they produce, and edits skill files under controlled conditions.
+`libharness` provides the runtime and tool surface for multi-LLM coordination.
+An agent talks to a supervisor. A facilitator chairs a meeting. A lead drives
+an asynchronous discussion. `libharness` also provides a CLI suite. The suite
+runs evals, queries the traces they produce, and edits skill files under
+controlled conditions.
 
 ## CLIs
 
 | CLI             | Purpose                                                                |
 | --------------- | ---------------------------------------------------------------------- |
 | `gemba-harness`      | Run agents in `run`/`supervise`/`facilitate`/`discuss` subcommands.    |
-| `gemba-trace`     | Download, query, and analyze NDJSON traces produced by `gemba-harness`.     |
+| `gemba-trace`     | Download, query, and analyze the NDJSON traces `gemba-harness` produces.     |
 | `gemba-benchmark` | Run task families for N runs each and aggregate pass@k.                |
-| `gemba-selfedit`  | Write stdin to `.claude/**` paths, gated by settings.json + branch.    |
+| `gemba-selfedit`  | Write stdin to `.claude/**` paths behind settings.json and branch gates.    |
 
 `gemba-harness`'s subcommands share one orchestration loop and one async tool
-surface, below. The `judge` role is a profile passed to `supervise`.
+surface, below. The `judge` role is a profile you pass to `supervise`.
 
 ## Modes
 
@@ -36,8 +37,8 @@ surface, below. The `judge` role is a profile passed to `supervise`.
 | `judge`      | `judge`       | (none)        | `Conclude`             |
 
 `run` and `judge` are one-shot. The other three share `OrchestrationLoop`
-plus an async Ask/Answer/Announce/RollCall tool surface; the loop fans
-messages out over an in-memory bus and emits a `{source, seq, event}`
+plus an async Ask/Answer/Announce/RollCall tool surface. The loop fans
+messages out over an in-memory bus. It emits a `{source, seq, event}`
 NDJSON envelope for every line.
 
 ## Async Ask / Answer / Announce
@@ -48,10 +49,10 @@ Answer({ message, askId? })  →  routed to the asker
 Announce({ message })        →  broadcast, no reply expected
 ```
 
-Every Ask returns immediately and registers a pending entry keyed by an
+Every Ask returns immediately. It registers a pending entry under an
 `askId`. The reply arrives later on the asker's inbox as `[answer#N]
 <participant>: <text>`. Broadcast: omit `to` on a multi-participant
-lead. Answer's `askId` is optional — the handler is forgiving:
+lead. Answer's `askId` is optional. The handler is forgiving:
 
 - **Provided + matches an ask owed by the caller** → routes to that asker.
 - **Provided but unknown or wrong addressee** → `isError` with a pointed
@@ -69,34 +70,35 @@ Inbox lines on resume:
 ```
 
 Async means the lead can issue Asks, end its turn, and plan in the gap
-while participants work in parallel — nothing blocks the LLM thread.
+while participants work in parallel. Nothing blocks the LLM thread.
 
 ### Discuss-mode replies
 
-In discussion mode, Answer calls routed to the lead are streamed to
-the discussion thread as they are produced — each agent's Answer becomes
-a separate reply posted immediately, not batched at session end. The
-lead and agents can also call `Acknowledge` to post brief messages
-directly to the thread (status updates, human follow-up responses).
-The message bus intercepts answers and appends them to `ctx.replies[]`.
+In discussion mode, Answer calls routed to the lead stream to the
+discussion thread as the agents produce them. Each agent's Answer becomes
+a separate reply. The thread receives it immediately. The session does not
+batch the replies at its end. The lead and agents can also call
+`Acknowledge` to post brief messages directly to the thread (status
+updates, human follow-up responses). The message bus intercepts answers
+and appends them to `ctx.replies[]`.
 
 `RequestForComment` is a separate coordination tool available on agent
 roles (facilitated agents and discuss agents). It queues an intent to
 open a new Discussion thread for long-horizon coordination on open
-questions; these are accumulated in `ctx.rfcs[]`, separate from the
-thread replies in `ctx.replies[]`.
+questions. These intents accumulate in `ctx.rfcs[]`. They stay separate
+from the thread replies in `ctx.replies[]`.
 
 ## Orchestration loop
 
-Each participant drains the bus (or waits), runs/resumes the LLM with
-drained messages as tagged lines, and on an unanswered owed Ask injects
-one synthetic reminder before emitting `protocol_violation` and
-unblocking the asker with a synthetic null answer.
+Each participant drains the bus, or waits. It then runs or resumes the LLM
+with the drained messages as tagged lines. On an unanswered owed Ask, the
+participant injects one synthetic reminder. It then emits
+`protocol_violation`. It unblocks the asker with a synthetic null answer.
 
 Termination uses two flags. `ctx.concluded` is explicit
-`Conclude`/`Adjourn`/`Recess` — also cancels in-flight Asks so askers
-see why their question won't be answered. `stopped` is broader: lead
-error, agent crash, abort path. Loops watch `stopped`; `ctx.concluded`
+`Conclude`/`Adjourn`/`Recess`. It also cancels in-flight Asks, so askers
+see why nobody will answer their question. `stopped` is broader: lead
+error, agent crash, abort path. Loops watch `stopped`. `ctx.concluded`
 only feeds the summary's `success`/`verdict`.
 
 ## Tool surface, by role
@@ -113,7 +115,7 @@ only feeds the summary's `success`/`verdict`.
 
 Ask's `to` accepts a participant name on multi-participant roles
 (facilitator, discuss lead, all participants). The supervise pair has
-only one possible target so `to` is rejected there.
+only one possible target, so it rejects `to`.
 
 ## Minimal example: two-participant facilitator
 
@@ -137,14 +139,14 @@ const result = await facilitator.run("Run a kata storyboard meeting.");
 // result.success / result.turns / NDJSON trace on process.stdout
 ```
 
-The facilitator gets `Ask`/`Answer`/`Announce`/`RollCall`/`Conclude`;
-each agent gets the same minus `Conclude`. Every tool call, bus
+The facilitator gets `Ask`/`Answer`/`Announce`/`RollCall`/`Conclude`.
+Each agent gets the same minus `Conclude`. Every tool call, bus
 message, and orchestrator event becomes one trace line.
 
 ## Trace format and redaction
 
 Each line is `{ "source": "<participant|orchestrator>", "seq": N, "event":
-{…} }`. `seq` is monotonic across the whole trace; `orchestrator` emits
+{…} }`. `seq` is monotonic across the whole trace. `orchestrator` emits
 `session_start`, `agent_start`, `protocol_violation`, `lead_turn_limit`,
 and `summary`. `event` is the SDK event verbatim or the orchestrator
 payload. `gemba-trace` consumes this format.
@@ -153,61 +155,62 @@ Redaction is on by default for `gemba-harness run`/`supervise`/`facilitate`
 and composes two layers:
 
 - **Env-var allowlist** — `ANTHROPIC_API_KEY`, `GH_TOKEN`, `GITHUB_TOKEN`
-  by default; override with `LIBHARNESS_REDACTION_ENV_VARS=NAME1,…`
-  (replaces, not extends). Runtime values become `[REDACTED:env:NAME]`
-  everywhere they appear.
+  by default. Override the list with
+  `LIBHARNESS_REDACTION_ENV_VARS=NAME1,…`. The variable replaces the
+  default list. It does not extend the list. Runtime values become
+  `[REDACTED:env:NAME]` everywhere they appear.
 - **Credential-shape patterns** — `sk-ant-`, `ghp_`, `ghs_`, `gho_`,
   `github_pat_`. Hits become `[REDACTED:pattern:KIND]`.
 
-Set `LIBHARNESS_REDACTION_DISABLED=1` to disable (one stderr warning per
-run). Never on CI for a public repo — workflow artifacts are
-downloadable through retention.
+Set `LIBHARNESS_REDACTION_DISABLED=1` to disable it (one stderr warning
+per run). Never disable it on CI for a public repo. Workflow artifacts
+stay downloadable through retention.
 
 ## Module map
 
 | Module                                                      | Purpose                                                              |
 | ----------------------------------------------------------- | -------------------------------------------------------------------- |
-| `agent-runner.js`                                           | One Claude Agent SDK session; emits NDJSON via the redactor.         |
+| `agent-runner.js`                                           | One Claude Agent SDK session. Emits NDJSON through the redactor.         |
 | `message-bus.js`                                            | Per-participant queues + `waitForMessages` Promise wakeup.           |
 | `orchestration-toolkit.js`                                  | Shared Ask/Answer/Announce/Conclude/RollCall/RequestForComment handlers + builders. |
-| `orchestration-loop.js`                                     | Unified lead+participant loop; reminder/violation handling.          |
+| `orchestration-loop.js`                                     | Unified lead+participant loop. Handles reminders and violations.          |
 | `facilitator.js` / `supervisor.js` / `discusser.js` / `judge.js` | Per-mode class + factory + system prompt.                       |
 | `discuss-tools.js`                                          | Discuss-only `Recess`/`Adjourn`/`Acknowledge`.                       |
 | `reply-emitter.js`                                          | Fire-and-forget POST of reply/ack events to the callback URL.        |
 | `inbox-poller.js`                                           | Long-poll the bridge inbox for injected human messages.              |
-| `trace-collector.js` / `trace-query.js` / `trace-github.js` | Trace ingestion / querying / GitHub-attachment helpers.              |
+| `trace-collector.js` / `trace-query.js` / `trace-github.js` | Trace ingestion / query / GitHub-attachment helpers.              |
 | `redaction.js`                                              | Env-var allowlist + credential-shape pattern redaction.              |
 
 ## gemba-selfedit
 
-A narrow, audited bypass for sessions where `Edit`/`Write` (and bash
-writes) are blocked against paths the project's own allowlist permits.
-Reads stdin, writes the target, exits 0 / 2 (safeguard violation) / 1
-(I/O error).
+A narrow, audited bypass for sessions that block `Edit`/`Write` (and bash
+writes) against paths the project's own allowlist permits. It reads stdin.
+It writes the target. It exits 0, 2 (safeguard violation), or 1 (I/O
+error).
 
 ```sh
 echo "<content>" | bunx gemba-selfedit <path>
 ```
 
-Two safeguards, checked in order:
+The CLI checks two safeguards in order:
 
 1. **Settings-allow.** Walk upward from the target with
    [`Finder.findUpward`](../libutil/src/finder.js) to find the nearest
    `.claude/settings.json`. The target relative to its grandparent
    directory must match at least one `Edit(<glob>)` rule in
-   `permissions.allow[]` (matched with
-   [`minimatch`](https://github.com/isaacs/minimatch), `dot: true`).
-   Settings.json is the single source of truth — widen the project
-   allowlist and the CLI follows. Traversal like `.claude/../README.md`
-   is rejected as a side effect: `path.resolve` collapses `..` first,
-   then the resolved path tests against the rules.
+   `permissions.allow[]`. The CLI matches with
+   [`minimatch`](https://github.com/isaacs/minimatch) and `dot: true`.
+   Settings.json is the single source of truth. Widen the project
+   allowlist and the CLI follows. The CLI also rejects traversal like
+   `.claude/../README.md` as a side effect. `path.resolve` collapses
+   `..` first. The resolved path then tests against the rules.
 
 2. **Branch scope.** `git rev-parse --abbrev-ref HEAD` must not be
    `HEAD` (detached) or `main`. Edits ride a feature branch through
-   whatever merge gates the project has configured.
+   whatever merge gates the project configured.
 
-Failure messages name the safeguard that rejected; safeguard 1 also
-lists the `Edit()` rules that were tried.
+Failure messages name the safeguard that rejected the write. Safeguard 1
+also lists the `Edit()` rules it tried.
 
 ## Documentation
 
@@ -216,10 +219,10 @@ lists the `Edit()` rules that were tried.
   facilitate / discuss) with Ask/Answer/Announce and a single NDJSON trace.
 - [Run an Eval](https://www.forwardimpact.team/docs/libraries/prove-changes/run-eval/index.md)
   — author a judge profile, run an eval locally, wire it into CI, and inspect
-  the resulting trace.
+  the trace it produces.
 - [Prove Agent Changes](https://www.forwardimpact.team/docs/libraries/prove-changes/index.md)
-  — end-to-end workflow from dataset generation through evaluation to trace
-  analysis, including multi-agent collaboration sessions.
+  — the end-to-end workflow from dataset generation through evaluation to
+  trace analysis, with multi-agent collaboration sessions.
 - [Analyze Traces](https://www.forwardimpact.team/docs/libraries/prove-changes/trace-analysis/index.md)
   — read the NDJSON traces produced by `gemba-harness` with `gemba-trace`.
 - [Agent Teams](https://www.forwardimpact.team/docs/products/agent-teams/index.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libharness",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "Autonomous agent team harness — coordinate a lead and participant agents in one async session, with eval, benchmark, and trace tooling to prove the changes worked.",
   "keywords": [
     "orchestration",
@@ -69,7 +69,7 @@
     "@forwardimpact/libtelemetry": "^0.1.22",
     "@forwardimpact/libutil": "^0.1.0",
     "jmespath": "^0.16.0",
-    "minimatch": "^10.0.0",
+    "minimatch": "^10.2.6",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/src/advisor.js

@@ -1,15 +1,15 @@
 /**
- * Advisor — the judge's mid-loop sibling: a solo, tool-restricted, one-shot
- * `AgentRunner` session on a stronger model whose final text is the advice.
- * Each consult forwards the caller's whole recorded context (system prompt,
- * delivered prompts, transcript so far) plus a focused question; the advisor
- * can inspect files read-only but holds no write, execute, subagent, or
- * orchestration tools and never appears on the message bus.
+ * Advisor — the judge's mid-loop sibling. It is a solo, tool-restricted,
+ * one-shot `AgentRunner` session on a stronger model. Its final text is the
+ * advice. Each consult forwards the caller's whole recorded context (system
+ * prompt, delivered prompts, transcript so far) plus a focused question. The
+ * advisor can inspect files read-only. It holds no write, execute, subagent,
+ * or orchestration tools. It never appears on the message bus.
  *
- * Consults are stateless — one fresh session per call, re-reading the
- * caller's context as it stands — and fail-open: timeout, error, and abort
- * all resolve to an in-band `{unavailable}` result so the caller's session
- * never stalls or crashes on a consult.
+ * Consults are stateless. Each call runs one fresh session that reads the
+ * caller's context as it stands. Consults also fail open. A timeout, an
+ * error, and an abort all resolve to an in-band `{unavailable}` result, so
+ * the caller's session never stalls or crashes on a consult.
  *
  * Follows OO+DI: factory function, tests inject a fake `query`.
  */
@@ -20,39 +20,42 @@ import { createAgentRunner } from "./agent-runner.js";
 import { composeSystemPrompt } from "./profile-prompt.js";
 
 /**
- * System-prompt trailer for the advisor session. Fixes the response
- * contract (spec criterion "Advice is bounded"): assessment,
- * recommendation, unsolicited findings, with a stated length ceiling.
+ * System-prompt trailer for the advisor session. It fixes the response
+ * contract (spec criterion "Advice is bounded"). The contract is an
+ * assessment, a recommendation, and unsolicited findings, with a stated
+ * length ceiling.
  */
 export const ADVISOR_SYSTEM_PROMPT =
-  "You are a consulted specialist, not a worker. " +
-  "Another agent paused its work to ask you one question; its full session context and the question are in the task. " +
-  "You may Read, Glob, and Grep the files the transcript names to ground your advice; never modify anything. " +
-  "Respond in one turn of prose — your final text is delivered to the caller verbatim. " +
+  "You are a consulted specialist. You are not a worker. " +
+  "Another agent paused its work to ask you one question. Its full session context and the question are in the task. " +
+  "You may Read, Glob, and Grep the files the transcript names to ground your advice. You must never modify anything. " +
+  "Respond in one turn of prose. The caller receives your final text verbatim. " +
   "Structure the response as: assessment (what you see), recommendation (what to do and why), and unsolicited findings (anything important the caller did not ask about). " +
   "Keep the whole response to at most three short paragraphs. " +
-  "Do not ask follow-up questions — the caller cannot reply.";
+  "Do not ask follow-up questions. The caller cannot reply.";
 
 /**
  * Consult-guidance fragment for caller system prompts, present only when
- * the session runs with an advisor model. Steers the caller's judgment; it
- * mandates nothing.
+ * the session runs with an advisor model. It steers the caller's judgment.
+ * It mandates nothing.
  * @param {number} maxUses - The session-wide consult budget.
  * @returns {string}
  */
 export function advisorGuidance(maxUses) {
   return (
-    "An `Advisor` tool is available: one focused question per call, answered by a stronger model that sees your full session context. " +
-    "A consult pays off at hard decision points — architectural forks, unclear root causes, trade-offs you cannot rank — and early, before work builds on an unvalidated assumption. " +
+    "An `Advisor` tool is available. It takes one focused question per call. A stronger model that sees your full session context answers it. " +
+    "A consult pays off at hard decision points, such as architectural forks, unclear root causes, and trade-offs you cannot rank. " +
+    "A consult also pays off early, before work builds on an unvalidated assumption. " +
     "It does not pay off for routine reads, writes, or searches. " +
-    `The session-wide budget is ${maxUses} consult${maxUses === 1 ? "" : "s"}, shared across all participants. ` +
-    "Consulting is your judgment, never mandatory."
+    `The session-wide budget is ${maxUses} consult${maxUses === 1 ? "" : "s"}, which all participants share. ` +
+    "A consult is your judgment. It is never mandatory."
   );
 }
 
 /**
- * Create the session-wide consult budget, shared by every caller's tool
- * handler. Enforced in code by the tool handler, not in the prompt.
+ * Create the session-wide consult budget. Every caller's tool handler
+ * shares it. The tool handler enforces the budget in code. The prompt does
+ * not enforce it.
  * @param {number} maxUses
  * @returns {{maxUses: number, used: number}}
  */
@@ -62,7 +65,7 @@ export function createAdvisorBudget(maxUses) {
 
 /**
  * Fold the consult guidance into an existing run-specific amendment when
- * the advisor is enabled (budget present); return the amendment unchanged
+ * the advisor is enabled (budget present). Return the amendment unchanged
  * otherwise, so advisor-off prompts stay byte-identical.
  * @param {string|undefined} amend - The existing amendment, if any.
  * @param {{maxUses: number}|null} budget
@@ -73,16 +76,19 @@ export function withAdvisorGuidance(amend, budget) {
   return [amend, advisorGuidance(budget.maxUses)].filter(Boolean).join("\n\n");
 }
 
-/** Consult timeout — generous for a read-a-few-files-and-answer session, and the universal guard in modes with no stop path. */
+/**
+ * Consult timeout. It is generous for a read-a-few-files-and-answer
+ * session. It is also the universal guard in modes with no stop path.
+ */
 export const DEFAULT_CONSULT_TIMEOUT_MS = 300_000;
 
 const ADVISOR_ALLOWED_TOOLS = ["Read", "Glob", "Grep"];
 
 // Under the harness's always-on bypassPermissions, `allowedTools` alone is
-// not structural — `disallowedTools` is what removes tools from the model's
-// context, the same treatment the lead runners get. The advisor's contract
-// is stricter than the leads' (read-only inspection, nothing else), so the
-// list also removes the write-capable and non-inspection built-ins the
+// not structural. `disallowedTools` removes tools from the model's context.
+// The lead runners get the same treatment. The advisor's contract is
+// stricter than the leads' (read-only inspection, nothing else). So the
+// list also removes the write-capable and non-inspection built-ins that the
 // lead convention leaves in.
 const ADVISOR_DISALLOWED_TOOLS = [
   "Bash",
@@ -105,18 +111,18 @@ const devNull = new Writable({
 });
 
 /**
- * Create a per-caller advisor closed over that caller's transcript
+ * Create a per-caller advisor that closes over that caller's transcript
  * recorder.
  *
  * @param {object} deps
  * @param {string} deps.model - Advisor model id.
- * @param {string} deps.cwd - The caller's working directory, so read-only inspection sees the caller's files.
- * @param {function} deps.query - SDK query function (injected for testing).
+ * @param {string} deps.cwd - The caller's working directory, so the read-only tools see the caller's files.
+ * @param {function} deps.query - SDK query function (tests inject it).
  * @param {{render: () => string}} deps.recorder - The caller's transcript recorder.
  * @param {import("./redaction.js").Redactor} deps.redactor
  * @param {import("@forwardimpact/libutil/runtime").Runtime} deps.runtime - Clock surface for timeout and duration.
- * @param {function} deps.onLine - Re-emitter for the advisor session's NDJSON lines (tagged `source: "advisor"` by the caller).
- * @param {number} [deps.maxTurns] - Default 5 — single-digit per the spec criterion.
+ * @param {function} deps.onLine - Re-emitter for the advisor session's NDJSON lines (the caller tags them `source: "advisor"`).
+ * @param {number} [deps.maxTurns] - Default 5, which is single-digit per the spec criterion.
  * @param {number} [deps.timeoutMs] - Default `DEFAULT_CONSULT_TIMEOUT_MS`.
  * @returns {{consult: (question: string) => Promise<{advice?: string, unavailable?: boolean, reason?: string, durationMs: number}>, abort: () => void}}
  */
@@ -147,7 +153,7 @@ export function createAdvisor({
   return {
     /**
      * Run one fresh advisor session over the caller's context as it
-     * stands plus the question. Never rejects — every failure shape
+     * stands plus the question. It never rejects. Every failure shape
      * resolves to `{unavailable, reason}` (fail-open).
      * @param {string} question
      */
@@ -207,9 +213,9 @@ export function createAdvisor({
     },
 
     /**
-     * Abort the in-flight consult, if any. A consult is a blocking tool
-     * call, so one caller cannot overlap its own consults; advisors are
-     * per-caller, so at most one runner is ever tracked.
+     * Abort the in-flight consult, if any. A consult is a tool call that
+     * blocks, so one caller cannot overlap its own consults. Each advisor
+     * belongs to one caller, so the code tracks at most one runner.
      */
     abort() {
       currentRunner?.currentAbortController?.abort();

package/src/agent-runner.js

@@ -1,7 +1,8 @@
 /**
  * AgentRunner — runs a single Claude Agent SDK session and emits raw
- * NDJSON events to an output stream. Building block for `gemba-harness run`,
- * `gemba-harness supervise`, `gemba-harness facilitate`, and `gemba-harness discuss`.
+ * NDJSON events to an output stream. `gemba-harness run`,
+ * `gemba-harness supervise`, `gemba-harness facilitate`, and
+ * `gemba-harness discuss` build on it.
  *
  * Follows OO+DI: constructor injection, factory function, tests bypass factory.
  */
@@ -12,15 +13,16 @@ import { resolveClaudeCodeExecutable } from "./claude-code-executable.js";
 const DEFAULT_ALLOWED_TOOLS = ["Bash", "Read", "Glob", "Grep", "Write", "Edit"];
 
 /**
- * Did the session actually invoke the model? A genuine run always bills
+ * Report whether the session invoked the model. A genuine run always bills
  * tokens (the system prompt alone is thousands of input tokens) and costs
- * more than zero. A `result` message with `subtype: "success"` but zero
- * token usage and zero cost means the model was never reached — the
- * canonical signature of a Claude Code init/auth failure (e.g. an invalid
- * `ANTHROPIC_API_KEY`), which the SDK otherwise reports as a clean success.
+ * more than zero. A `result` message can carry `subtype: "success"` with
+ * zero token usage and zero cost. That combination means the run never
+ * reached the model. It is the canonical signature of a Claude Code init or
+ * auth failure (e.g. an invalid `ANTHROPIC_API_KEY`). The SDK otherwise
+ * reports that failure as a clean success.
  *
  * If the SDK gave us neither a `usage` object nor `total_cost_usd`, don't
- * second-guess the subtype — trust the reported success.
+ * second-guess the subtype. Trust the reported success.
  * @param {object|null} result - The SDK `result` message, or null.
  * @returns {boolean}
  */
@@ -38,8 +40,9 @@ function modelDidWork(result) {
 }
 
 // gemba-harness and kata-action run headless in CI/CD with no human to answer
-// permission prompts. The SDK is always launched in bypass mode — not
-// overridable — so a future caller can't accidentally reduce permissions.
+// permission prompts. The runner always launches the SDK in bypass mode. No
+// caller can override that mode, so a future caller can't accidentally
+// reduce permissions.
 const PERMISSION_MODE = "bypassPermissions";
 
 /** Run a single Claude Agent SDK session and emit raw NDJSON events to an output stream. */
@@ -47,25 +50,27 @@ export class AgentRunner {
   /**
    * @param {object} deps
    * @param {string} deps.cwd - Agent working directory
-   * @param {function} deps.query - SDK query function (injected for testing)
+   * @param {function} deps.query - SDK query function (tests inject it)
    * @param {import("stream").Writable} deps.output - Stream to emit NDJSON to
    * @param {string} [deps.model] - Claude model identifier
-   * @param {number} [deps.maxTurns] - Maximum agentic turns; 0 means unlimited
+   * @param {number} [deps.maxTurns] - Maximum agentic turns. 0 means unlimited
    * @param {string[]} [deps.allowedTools] - Tools the agent may use
-   * @param {function} [deps.onLine] - Callback invoked with each NDJSON line as it's produced
-   * @param {function} [deps.onPrompt] - Callback invoked with the effective (amend-applied) prompt of each run/resume
+   * @param {function} [deps.onLine] - Callback that receives each NDJSON line as the runner produces it
+   * @param {function} [deps.onPrompt] - Callback that receives the effective (amend-applied) prompt of each run/resume
    * @param {string[]} [deps.settingSources] - SDK setting sources (e.g. ['project'] to load CLAUDE.md)
-   * @param {string|object} [deps.systemPrompt] - SDK system prompt (string replaces default; {type:'preset', preset:'claude_code', append} appends)
+   * @param {string|object} [deps.systemPrompt] - SDK system prompt. A string replaces the default. The preset form {type:'preset', preset:'claude_code', append} appends
    * @param {string[]} [deps.disallowedTools] - Tools to explicitly remove from the model's context
    * @param {Record<string, object>} [deps.mcpServers] - MCP server configs to pass to the SDK query
    * @param {string} [deps.pathToClaudeCodeExecutable] - Absolute path to the
-   *   native `claude` CLI the SDK should spawn. Set for compiled fit-* binaries,
-   *   which can't self-resolve the SDK's platform optional dependency; omitted
-   *   from source runs so the SDK resolves its own version-matched binary.
+   *   native `claude` CLI the SDK should spawn. Set it for compiled fit-*
+   *   binaries, which can't self-resolve the SDK's platform optional
+   *   dependency. Omit it from source runs so the SDK resolves its own
+   *   version-matched binary.
    * @param {object} deps.redactor
    * @param {import("@forwardimpact/libutil/runtime").Runtime} [deps.runtime] -
-   *   Ambient collaborators. Only `proc.env` is read (to record Skill
-   *   invocations into `LIBHARNESS_SKILL`); when absent the write is skipped.
+   *   Ambient collaborators. The runner reads only `proc.env`, to record Skill
+   *   invocations into `LIBHARNESS_SKILL`. When `runtime` is absent, the
+   *   runner skips the write.
    */
   constructor(deps) {
     if (!deps.cwd) throw new Error("cwd is required");
@@ -81,15 +86,17 @@ export class AgentRunner {
     this.maxTurns = deps.maxTurns ?? 50;
     this.allowedTools = deps.allowedTools ?? DEFAULT_ALLOWED_TOOLS;
     this.onLine = deps.onLine ?? null;
-    // Optional; read only through a truthy guard in run()/resume(), so an
-    // absent value stays undefined rather than needing a `?? null` default.
+    // Optional. The code reads it only through a truthy guard in
+    // run()/resume(), so an absent value stays undefined and needs no
+    // `?? null` default.
     this.onPrompt = deps.onPrompt;
     this.settingSources = deps.settingSources ?? [];
     this.systemPrompt = deps.systemPrompt ?? null;
     this.disallowedTools = deps.disallowedTools ?? [];
     this.mcpServers = deps.mcpServers ?? null;
-    // Optional; read only through a truthy guard in #callOptions, so an absent
-    // value stays undefined rather than needing a `?? null` default.
+    // Optional. The code reads it only through a truthy guard in
+    // #callOptions, so an absent value stays undefined and needs no
+    // `?? null` default.
     this.pathToClaudeCodeExecutable = deps.pathToClaudeCodeExecutable;
     this.taskAmend = deps.taskAmend ?? null;
     this.sessionId = null;
@@ -146,16 +153,17 @@ export class AgentRunner {
   }
 
   /**
-   * Build the options passed to every SDK query() call. Shared by run()
-   * and resume() so the agent's configuration — cwd, tools, prompt,
-   * setting sources, turn budget — is identical across the session's
-   * lifetime. Only resume() layers `resume: this.sessionId` on top.
+   * Build the options for every SDK query() call. run() and resume()
+   * share this method, so the agent's configuration stays identical
+   * across the session's lifetime. That configuration is the cwd, the
+   * tools, the prompt, the setting sources, and the turn budget. Only
+   * resume() layers `resume: this.sessionId` on top.
    *
-   * SDK options are call-attached, not session-attached: the resumed
-   * call loads the prior conversation but otherwise uses whatever
-   * options this call passes. Omitting tool/prompt/setting options on
-   * resume causes the agent to silently lose its restrictions and
-   * persona between turns.
+   * SDK options attach to the call. They do not attach to the session.
+   * The resumed call loads the prior conversation. It otherwise uses
+   * whatever options this call passes. If you omit the tool, prompt, or
+   * setting options on resume, the agent silently loses its restrictions
+   * and persona between turns.
    */
   #callOptions(abortController) {
     return {
@@ -179,14 +187,14 @@ export class AgentRunner {
   }
 
   /**
-   * Iterate the SDK query iterator, mirroring every message to the
-   * output stream and the `onLine` callback. Captures `sessionId` from
-   * the SDK's `system/init` message and tracks Skill invocations into
+   * Iterate the SDK query iterator. Mirror every message to the output
+   * stream and to the `onLine` callback. Capture `sessionId` from the
+   * SDK's `system/init` message. Track Skill invocations into
    * `LIBHARNESS_SKILL` for downstream metrics.
    *
    * If the iterator throws and we triggered the abort ourselves
    * (`currentAbortController.signal.aborted`), we report `aborted:
-   * true`; otherwise the error propagates as `error`.
+   * true`. Otherwise the error propagates as `error`.
    */
   async #consumeQuery(iterator) {
     let text = "";
@@ -212,10 +220,10 @@ export class AgentRunner {
       }
     }
 
-    // A "success" subtype is necessary but not sufficient: the SDK reports a
-    // failed init (e.g. an invalid API key) as success with zero model work.
-    // Require evidence the model actually ran, and surface a clear error when
-    // it didn't, so the masked failure can't be reported as a green run.
+    // A "success" subtype is necessary. It is not sufficient. The SDK reports
+    // a failed init (e.g. an invalid API key) as success with zero model work.
+    // Require evidence that the model ran. Surface a clear error when it did
+    // not, so nobody reports the masked failure as a green run.
     const reportedSuccess = stopReason === "success";
     const success =
       reportedSuccess &&
@@ -223,7 +231,7 @@ export class AgentRunner {
       modelDidWork(resultMessage);
     if (reportedSuccess && !success && !error) {
       error = new Error(
-        "agent reported success but performed no model work (zero token usage) — likely a Claude Code init or authentication failure",
+        "agent reported success but did no model work (zero token usage), which is likely a Claude Code init or authentication failure",
       );
     }
 
@@ -251,8 +259,9 @@ export class AgentRunner {
   #trackSkillInvocation(message) {
     const content = message.message?.content ?? message.content;
     if (!Array.isArray(content)) return;
-    // Skill metric is recorded into the env map; without a runtime there is
-    // no env surface to write to, so the side-effect is simply skipped.
+    // The runner records the Skill metric into the env map. Without a
+    // runtime there is no env surface to write to, so the code simply skips
+    // the side-effect.
     const env = this.runtime?.proc?.env ?? null;
     if (!env) return;
     for (const block of content) {
@@ -268,9 +277,10 @@ export class AgentRunner {
 }
 
 /**
- * Factory function — wires real dependencies. Resolves the native `claude`
- * executable for compiled fit-* binaries so the SDK doesn't fail to find its
- * own platform optional dependency; an explicit `deps` value overrides it.
+ * Factory function — wires real dependencies. It resolves the native
+ * `claude` executable for compiled fit-* binaries, so the SDK doesn't fail
+ * to find its own platform optional dependency. An explicit `deps` value
+ * overrides it.
  */
 export function createAgentRunner(deps) {
   return new AgentRunner({