@forwardimpact/libharness 2.0.0 → 3.0.1

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 `fit-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
  */

package/src/cost.js

@@ -1,20 +1,20 @@
 /**
- * Cost aggregation over Claude Code NDJSON traces — the single source of
- * truth for "how much did this run cost, across every participant?".
+ * Cost totals over Claude Code NDJSON traces — the single source of truth for
+ * the cost of a run across every participant.
  *
  * The SDK reports the cumulative session cost on each `result` event as
  * `total_cost_usd`. Supervised, facilitated, and discuss sessions interleave
- * one runner's events with another's in a single combined trace, wrapping
- * each in a `{source, seq, event}` envelope; a plain `run` trace carries bare
- * events with no envelope. A judge runs as its own session in a separate
- * trace. In every case the rule is the same: sum the `total_cost_usd` of each
- * `result` event, and keep a per-source breakdown so callers can attribute
- * spend to the agent, supervisor, judge, or any named participant.
+ * one runner's events with another's in a single combined trace. They wrap
+ * each event in a `{source, seq, event}` envelope. A plain `run` trace carries
+ * bare events with no envelope. A judge runs as its own session in a separate
+ * trace. In every case the rule is the same. Sum the `total_cost_usd` of each
+ * `result` event. Keep a per-source breakdown so callers can attribute spend
+ * to the agent, supervisor, judge, or any named participant.
  *
  * This mirrors `TraceCollector.handleResult`, which accumulates the same
- * figure for its summary footer — kept as a standalone pure helper so the
- * benchmark runner, the callback command, and `fit-trace cost` share one
- * implementation rather than each re-deriving it (and drifting).
+ * figure for its summary footer. This module stays a standalone pure helper.
+ * The benchmark runner, the callback command, and `gemba-trace cost` then
+ * share one implementation instead of each one re-deriving it and drifting.
  */
 
 /** Bucket key for bare (un-enveloped) `run`-mode events: a lone agent session. */
@@ -24,9 +24,9 @@ export const UNSOURCED = "agent";
  * Sum `total_cost_usd` across every `result` event in an NDJSON trace.
  *
  * @param {Iterable<string>} lines - NDJSON lines (e.g. `content.split("\n")`).
- *   Blank and malformed lines are skipped.
+ *   The function skips blank and malformed lines.
  * @returns {{totalCostUsd: number, bySource: Record<string, number>}}
- *   `totalCostUsd` is the sum across all participants; `bySource` maps each
+ *   `totalCostUsd` is the sum across all participants. `bySource` maps each
  *   envelope `source` (or {@link UNSOURCED} for bare events) to its subtotal.
  */
 export function sumTraceCost(lines) {
@@ -46,9 +46,9 @@ export function sumTraceCost(lines) {
 }
 
 /**
- * Parse a single NDJSON line and return its `result`-event cost contribution,
- * or null when the line is blank, malformed, not a result event, or carries
- * no numeric `total_cost_usd`.
+ * Parse a single NDJSON line. Return its `result`-event cost contribution.
+ * Return null when the line is blank, malformed, not a result event, or
+ * carries no numeric `total_cost_usd`.
  *
  * @param {string} line
  * @returns {{source: string, cost: number} | null}
@@ -64,7 +64,7 @@ function parseCostLine(line) {
     return null;
   }
 
-  // Unwrap the combined-trace envelope {source, seq, event}; bare events
+  // Unwrap the combined-trace envelope {source, seq, event}. Bare events
   // (plain `run` traces) have a `type` and no `source`.
   let source = UNSOURCED;
   if (event.event && !event.type && typeof event.source === "string") {

package/src/discuss-tools.js

@@ -5,15 +5,15 @@
  * - `Recess` suspends the session with a resumption trigger.
  * - `Adjourn` ends the discussion with a verdict.
  *
- * `Conclude` is absent — discuss mode ends via Adjourn or Recess.
+ * `Conclude` is absent. Discuss mode ends through Adjourn or Recess.
  *
- * `RequestForComment` is an agent-level coordination tool — available on
+ * `RequestForComment` is an agent-level coordination tool. It is available on
  * discuss agents and facilitated agents (not leads). It opens a new
  * Discussion thread for long-horizon coordination on open questions.
  *
- * In discuss mode, each agent Answer routed to the lead is captured as a
- * thread reply delivered via the bridge callback — no explicit reply tool
- * is needed on the lead surface.
+ * In discuss mode, each agent Answer routed to the lead becomes a thread
+ * reply. The bridge callback delivers that reply. The lead surface needs no
+ * explicit reply tool.
  */
 
 import { tool } from "@anthropic-ai/claude-agent-sdk";
@@ -30,13 +30,13 @@ import {
   requireNoUnprocessedInbox,
 } from "./orchestration-toolkit.js";
 
-/** System prompt for discuss-mode agent participants. L0 mechanics only per COALIGNED. */
+/** System prompt for discuss-mode agent participants. L0 mechanics only per JIDOKA. */
 export const DISCUSS_AGENT_SYSTEM_PROMPT =
   "You are a participant in a discussion.\n" +
   "Each question arrives as `[ask#N] <name>: <text>` in your inbox.\n" +
   "Quote N as askId on your `Answer` to route the reply correctly.\n" +
-  "Your `Answer` is posted to the discussion thread as a separate reply.\n" +
-  "If the task already contains a completed response with no new human input after it, `Answer` that no further action is needed.\n" +
+  "The system posts your `Answer` to the discussion thread as a separate reply.\n" +
+  "The task can already contain a completed response with no new human input after it. In that case, `Answer` that no further action is needed.\n" +
   "Do not redo completed work.";
 
 const RESUME_TRIGGER_SCHEMA = z.discriminatedUnion("kind", [
@@ -66,7 +66,7 @@ export function createDiscussLeadToolServer(ctx) {
     ...baseTools(ctx, { from: "lead", defaultTo: undefined, broadcast: true }),
     tool(
       "Acknowledge",
-      "Post a brief message directly to the discussion thread. Use when responding to a human follow-up or providing a status update while participants are working.",
+      "Post a brief message directly to the discussion thread. Use it to respond to a human follow-up. Use it to give a status update while participants work.",
       {
         message: z.string().describe("Message to post on the thread"),
       },
@@ -104,7 +104,7 @@ export function createDiscussLeadToolServer(ctx) {
 }
 
 const ACKNOWLEDGE_DESC =
-  "Acknowledge an Ask before starting work. Posts a visible comment on the thread. Does not discharge the Ask — you still owe an Answer.";
+  "Acknowledge an Ask before you start work. Posts a visible comment on the thread. Does not discharge the Ask. You still owe an Answer.";
 
 /** Discuss-mode agent tool server. */
 export function createDiscussAgentToolServer(ctx, { from, extraTools = [] }) {
@@ -118,7 +118,7 @@ export function createDiscussAgentToolServer(ctx, { from, extraTools = [] }) {
         message: z
           .string()
           .describe("Brief acknowledgement to post on the thread"),
-        askId: z.number().optional().describe("The ask being acknowledged"),
+        askId: z.number().optional().describe("The ask you acknowledge"),
       },
       async ({ message }) => {
         const seq =
@@ -138,11 +138,11 @@ export function createDiscussAgentToolServer(ctx, { from, extraTools = [] }) {
 }
 
 /**
- * Recess handler — ends the run with a structured pause + resumption
- * trigger; cancels any open Asks so askers see a synthetic null answer.
- * `concluded` flips true (same as Adjourn); the `recessed` verdict
- * distinguishes them, and `recessTrigger` carries the resume shape for
- * the bridge.
+ * Recess handler — ends the run with a structured pause and a resumption
+ * trigger. It cancels any open Asks so askers see a synthetic null answer.
+ * `concluded` flips true, the same as Adjourn. The `recessed` verdict
+ * distinguishes them. `recessTrigger` carries the resume shape for the
+ * bridge.
  */
 export function createRecessHandler(ctx) {
   return async ({ reason, trigger }) => {

package/src/discusser.js

@@ -3,14 +3,14 @@
  * `OrchestrationLoop`. The lead role uses `DiscussTools` (Adjourn / Recess)
  * instead of the facilitator's Conclude.
  *
- * Discuss mode is a sibling of facilitate mode, not a subset of it. The
- * within-run turn loop is shared via `OrchestrationLoop`, but the lead
- * role, tool set, system prompts, and participant naming all stay
- * mode-local.
+ * Discuss mode is a sibling of facilitate mode. It is not a subset of it.
+ * The two modes share the within-run turn loop through `OrchestrationLoop`.
+ * The lead role, the tool set, the system prompts, and the participant names
+ * all stay mode-local.
  *
- * Each agent Answer routed to the lead is captured as a thread reply
- * delivered via the bridge callback — no explicit reply tool is needed
- * on the lead surface.
+ * Each agent Answer routed to the lead becomes a thread reply. The bridge
+ * callback delivers that reply. The lead surface needs no explicit reply
+ * tool.
  */
 
 import { Writable } from "node:stream";
@@ -40,20 +40,20 @@ import {
 import { OrchestrationLoop } from "./orchestration-loop.js";
 import { AGENT_MODEL, LEAD_MODEL } from "@forwardimpact/libutil/models";
 
-/** System prompt for the discuss-mode lead. L0 mechanics only per COALIGNED. */
+/** System prompt for the discuss-mode lead. L0 mechanics only per JIDOKA. */
 export const DISCUSS_SYSTEM_PROMPT =
   "You lead a discussion.\n" +
   "You have no tools to perform work yourself.\n" +
   "Use `RollCall` to list participants.\n" +
   "Use `Ask` to delegate work to the best-suited participant.\n" +
-  "Participants are domain experts; state the task, not how to do it.\n" +
-  "Each participant's `Answer` is posted to the discussion thread as a separate reply.\n" +
+  "Participants are domain experts. State the task. Do not state how to do it.\n" +
+  "The system posts each participant's `Answer` to the discussion thread as a separate reply.\n" +
   "`Ask` is async and returns {askIds:[N,…]} immediately.\n" +
   "Answers arrive on your next turn as `[answer#N] <participant>: <text>` in your inbox.\n" +
   "End your turn while Asks are pending. The system resumes you when answers arrive.\n" +
   "Multiple `Ask` calls in one turn run participants in parallel.\n" +
-  "Use `Acknowledge` to post a brief message directly to the discussion thread — use it to respond to human follow-ups or give status updates while participants are working.\n" +
-  "End the discussion by calling `Adjourn` with a verdict and summary, or `Recess` only to wait on an external reply or duration.";
+  "Use `Acknowledge` to post a brief message directly to the discussion thread. Use it to respond to human follow-ups. Use it to give status updates while participants work.\n" +
+  "To end the discussion, call `Adjourn` with a verdict and summary. Call `Recess` instead only to wait on an external reply or duration.";
 
 /**
  * Augment a base orchestration context with discuss-mode fields.
@@ -78,8 +78,8 @@ const devNull = new Writable({
 });
 
 /**
- * Async orchestrator for the `discuss` mode. Composes an
- * `OrchestrationLoop` for the within-run turns but owns the discussion id,
+ * Async orchestrator for the `discuss` mode. It composes an
+ * `OrchestrationLoop` for the within-run turns. It owns the discussion id,
  * the resumption trigger, and the discuss-augmented terminal summary.
  */
 export class Discusser {
@@ -115,10 +115,11 @@ export class Discusser {
   }
 
   /**
-   * Run the discussion. Emits the meta header first (when a discussion_id
-   * is set), delegates the within-run loop to `OrchestrationLoop`, then
-   * emits the discuss-augmented summary (overrides the loop's earlier
-   * summary; trace consumers keep the last summary they see).
+   * Run the discussion. This method emits the meta header first, when a
+   * discussion_id is set. It then delegates the within-run loop to
+   * `OrchestrationLoop`. It then emits the discuss-augmented summary, which
+   * overrides the loop's earlier summary. Trace consumers keep the last
+   * summary they see.
    *
    * @param {string} task
    * @returns {Promise<{success: boolean, verdict: string, turns: number, replies: object[], trigger: object|null}>}
@@ -127,7 +128,7 @@ export class Discusser {
     this.#emitMeta();
 
     // The loop owns within-run turns. Its emitSummary fires once before
-    // run() returns; ours replaces it as the last summary line.
+    // run() returns. Ours replaces it as the last summary line.
     await this.loop.run(task);
 
     const verdict = this.ctx.verdict ?? "failed";
@@ -187,15 +188,15 @@ export class Discusser {
 }
 
 /**
- * Factory — wires the lead and agent runners with `DiscussTools`, builds
- * the `OrchestrationLoop` (with `leadName: "lead"` and discuss-mode
- * protocol tagging) and the wrapping `Discusser`.
+ * Factory — wires the lead and agent runners with `DiscussTools`. It builds
+ * the `OrchestrationLoop` with `leadName: "lead"` and a discuss-mode protocol
+ * tag. It then builds the `Discusser` that wraps the loop.
  *
- * Resume semantics: Recess ends the run, cancels any open Asks via
- * `cancelPendingAsks`, and emits a synthetic null answer per cancelled
- * ask so nothing dangles in the trace. The bridge later re-dispatches
- * the workflow against a fresh context; the human reads the trail of
- * events to decide what to re-ask.
+ * Resume semantics: Recess ends the run. It cancels any open Asks through
+ * `cancelPendingAsks`. It emits a synthetic null answer for each cancelled
+ * ask so nothing dangles in the trace. The bridge later re-dispatches the
+ * workflow against a fresh context. The human reads the trail of events to
+ * decide what to re-ask.
  *
  * @param {object} deps
  * @param {string} [deps.leadProfile]
@@ -215,8 +216,8 @@ export class Discusser {
  * @param {string|null} [deps.callbackUrl]
  * @param {string|null} [deps.inboxUrl]
  * @param {string|null} [deps.correlationId]
- * @param {string} [deps.advisorModel] - Claude model for advisor consults; absent means no Advisor tool is offered.
- * @param {number} [deps.advisorMaxUses] - Session-wide consult budget shared by all agent participants (default 3).
+ * @param {string} [deps.advisorModel] - Claude model for advisor consults. When absent, the factory offers no Advisor tool.
+ * @param {number} [deps.advisorMaxUses] - Session-wide consult budget that all agent participants share (default 3).
  * @returns {Discusser}
  */
 // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: factory wires N runners + resume hydration paths
@@ -254,9 +255,9 @@ export function createDiscusser({
     discussionId ?? null,
   );
 
-  // Hydrate resume context — participants, replies, counters. `pendingAsks`
-  // is intentionally not restored: Recess cancelled every in-flight Ask
-  // with a synthetic null answer, so there's nothing meaningful to carry
+  // Hydrate resume context: participants, replies, counters. The code does
+  // not restore `pendingAsks` on purpose. Recess cancelled every in-flight
+  // Ask with a synthetic null answer, so nothing meaningful remains to carry
   // forward.
   if (resumeContext) {
     if (Array.isArray(resumeContext.participants))
@@ -292,7 +293,7 @@ export function createDiscusser({
       })
     : null;
 
-  // Intercept answers routed to the lead — each becomes a discussion reply.
+  // Intercept answers routed to the lead. Each one becomes a discussion reply.
   const originalAnswer = messageBus.answer.bind(messageBus);
   messageBus.answer = (from, to, text, askId) => {
     if (to === "lead" && from !== "@orchestrator") {
@@ -319,12 +320,12 @@ export function createDiscusser({
   let discusser;
   const leadServer = createDiscussLeadToolServer(ctx);
 
-  // One budget per session, shared by every agent's Advisor handler.
+  // One budget per session. Every agent's Advisor handler shares it.
   const budget = advisorModel ? createAdvisorBudget(advisorMaxUses ?? 3) : null;
 
   const agents = resolvedConfigs.map((config) => {
-    // Everything advisor-shaped is gated on advisorModel; with it unset the
-    // composed prompt and tool surface are byte-identical to today's.
+    // `advisorModel` gates everything advisor-shaped. When it is unset, the
+    // composed prompt and tool surface stay byte-identical to today's.
     const systemPrompt = composeSystemPrompt({
       role: "agent",
       profile: config.agentProfile,
@@ -338,8 +339,8 @@ export function createDiscusser({
     let extraTools;
     if (advisorModel) {
       recorder = createTranscriptRecorder({ systemPrompt, redactor });
-      // Late-bound through the `let discusser` closure — the instance does
-      // not exist yet when the advisor and tool are built.
+      // Late-bound through the `let discusser` closure. The instance does
+      // not exist yet when the factory builds the advisor and the tool.
       const advisor = createAdvisor({
         model: advisorModel,
         cwd: config.cwd ?? resolvedLeadCwd,