@forwardimpact/libharness 3.0.0 → 3.0.2

package/src/profile-prompt.js

@@ -1,8 +1,8 @@
 /**
- * System prompt composition for agent runners.
+ * Compose system prompts for agent runners.
  *
  * libharness assembles every agent system prompt from up to two parallel,
- * sibling-tagged sections (see COALIGNED.md § L0):
+ * sibling-tagged sections (see JIDOKA.md § L0):
  *
  *     <agent_profile>
  *     …persona body…
@@ -12,39 +12,40 @@
  *     …orchestration mechanics, then any amendment…
  *     </session_protocol>
  *
- * The two tags are siblings joined by a blank line — neither nests inside
+ * The two tags are siblings. A blank line joins them. Neither nests inside
  * the other. A section appears only when its content is present. The tag
- * convention lives entirely here: profile `.md` files and trailer constants
+ * convention lives entirely here. Profile `.md` files and trailer constants
  * carry no tags.
  *
- * The `<session_protocol>` body is assembled from up to three fragments, in
- * order of decreasing generality:
+ * The composer assembles the `<session_protocol>` body from up to three
+ * fragments, in order of decreasing generality:
  *
  *   1. the role-invariant orchestration trailer (libharness-owned);
  *   2. the profile's own hoisted `## Session Protocol` section, if present;
  *   3. a run-specific amendment, if supplied.
  *
- * Fragment 2 is the convention-based hoist: a profile may carry a level-2
+ * Fragment 2 is the convention-based hoist. A profile may carry a level-2
  * `## Session Protocol` markdown heading whose body is the role's work
- * routine. When present, that section is lifted out of `<agent_profile>` and
- * folded into `<session_protocol>` next to the orchestration mechanics, so
- * the harness comms protocol and the role's work routine read as one
- * coherent block. The heading line itself is dropped — the tag already names
- * the section. Profiles with no such heading are unaffected (the entire body
- * stays in `<agent_profile>`).
+ * routine. When the heading is present, the composer lifts that section out
+ * of `<agent_profile>`. It folds the section into `<session_protocol>` next
+ * to the orchestration mechanics. The harness comms protocol and the role's
+ * work routine then read as one coherent block. The composer drops the
+ * heading line itself, because the tag already names the section. A profile
+ * with no such heading is unaffected. Its entire body stays in
+ * `<agent_profile>`.
  *
  * Helpers:
  *
  * - `composeProfilePrompt(name, opts)` — profile + `claude_code` preset.
- *   Used by agent participants that need the full Claude Code tool surface.
+ *   Agent participants that need the full Claude Code tool surface use it.
  *
- * - `composeLeadPrompt(opts)` — plain string, no preset. Used by lead
- *   roles (supervisor, facilitator, discuss lead) that should only see
+ * - `composeLeadPrompt(opts)` — plain string, no preset. Lead roles
+ *   (supervisor, facilitator, discuss lead) use it. They should only see
  *   the orchestration instructions and optionally a profile body.
  *
  * - `composeSystemPrompt(opts)` — unified entry point. Threads `amend` into
- *   the protocol section as the run-specific fragment, then delegates to one
- *   of the above based on `opts.role`.
+ *   the protocol section as the run-specific fragment. Then delegates to one
+ *   of the above by `opts.role`.
  */
 
 import { join } from "node:path";
@@ -55,13 +56,13 @@ const SESSION_PROTOCOL_TAG = "session_protocol";
 
 /**
  * A level-2 heading that names the profile's hoisted session-protocol
- * section. Case-insensitive, tolerant of trailing whitespace, but the level
- * is fixed at two `#` so a `### Session Protocol` subsection does not trip
- * the hoist.
+ * section. The match ignores case. It tolerates trailing whitespace. The
+ * level is fixed at two `#`, so a `### Session Protocol` subsection does
+ * not trip the hoist.
  */
 const SESSION_PROTOCOL_HEADING = /^##[ \t]+session protocol[ \t]*$/i;
 
-/** A level-1 or level-2 heading — the boundary that ends a hoisted section. */
+/** A level-1 or level-2 heading. This boundary ends a hoisted section. */
 const SECTION_BOUNDARY = /^#{1,2}[ \t]+\S/;
 
 /** Wrap content in a semantic section tag, each on its own line. */
@@ -71,11 +72,11 @@ function wrapSection(tag, content) {
 
 /**
  * Assemble the parallel `<agent_profile>` / `<session_protocol>` sections.
- * The profile section is emitted only when `body` is non-empty. The protocol
- * section is built by joining its fragments (in the order given) with a
- * blank-line separator, dropping any that are empty, and is emitted only
- * when at least one fragment survives. The two tags are siblings joined by a
- * blank line and never nest.
+ * This function emits the profile section only when `body` is non-empty. It
+ * builds the protocol section from the fragments in the order given. It
+ * joins them with a blank-line separator and drops any empty fragment. It
+ * emits the protocol section only when at least one fragment survives. The
+ * two tags are siblings. A blank line joins them. They never nest.
  *
  * @param {object} parts
  * @param {string} [parts.body] - Profile body, frontmatter-stripped and with
@@ -95,10 +96,10 @@ function assembleSections({ body, protocolParts = [] }) {
 /**
  * Split a frontmatter-stripped profile body into its persona and an optional
  * hoisted `## Session Protocol` section. The section runs from its heading to
- * the next level-1/level-2 heading (or end of body); the heading line is
- * dropped. Anything before and after the section is rejoined into `persona`.
- * When the body carries no `## Session Protocol` heading, the whole body is
- * returned as `persona` and `protocol` is `undefined`.
+ * the next level-1/level-2 heading (or end of body). This function drops the
+ * heading line. It rejoins anything before and after the section into
+ * `persona`. When the body carries no `## Session Protocol` heading, the
+ * whole body returns as `persona` and `protocol` is `undefined`.
  *
  * @param {string} body - Frontmatter-stripped, trimmed profile body.
  * @returns {{ persona: string, protocol: string | undefined }}
@@ -127,14 +128,14 @@ function splitSessionProtocol(body) {
 }
 
 /**
- * Read a profile `.md`, strip its frontmatter, and split off any hoisted
+ * Read a profile `.md`. Strip its frontmatter. Split off any hoisted
  * `## Session Protocol` section. Reads synchronously off the injected
- * `runtime.fsSync` surface — this composer runs inside the synchronous
+ * `runtime.fsSync` surface. This composer runs inside the synchronous
  * SDK-option builders of the supervisor / facilitator / discusser / judge
- * factories, so it cannot go async without an unbounded cascade.
+ * factories. So it cannot go async without an unbounded cascade.
  *
  * @param {string} name - Profile basename (no `.md` suffix)
- * @param {string} profilesDir - Directory containing `<name>.md`
+ * @param {string} profilesDir - Directory that contains `<name>.md`
  * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  * @returns {{ persona: string, protocol: string | undefined }}
  */
@@ -145,19 +146,19 @@ function readProfileSections(name, profilesDir, runtime) {
 }
 
 /**
- * Compose a `claude_code`-preset system prompt from a profile file. The
- * persona is wrapped in `<agent_profile>`; the protocol trailer, the
- * profile's hoisted `## Session Protocol` section, and any amendment are
- * joined (in that order) into a sibling `<session_protocol>`.
+ * Compose a `claude_code`-preset system prompt from a profile file. This
+ * function wraps the persona in `<agent_profile>`. It joins the protocol
+ * trailer, the profile's hoisted `## Session Protocol` section, and any
+ * amendment into a sibling `<session_protocol>`, in that order.
  *
  * @param {string} name - Profile basename (no `.md` suffix)
  * @param {object} opts
- * @param {string} opts.profilesDir - Directory containing `<name>.md`
- * @param {string} [opts.trailer] - Session protocol orchestration mechanics,
- *   the first fragment of the `<session_protocol>` section.
+ * @param {string} opts.profilesDir - Directory that contains `<name>.md`
+ * @param {string} [opts.trailer] - Orchestration mechanics for the session
+ *   protocol, the first fragment of the `<session_protocol>` section.
  * @param {string} [opts.amend] - Run-specific amendment, the last fragment of
  *   the `<session_protocol>` section.
- * @param {import("@forwardimpact/libutil/runtime").Runtime} opts.runtime - Ambient collaborators; uses `fsSync.readFileSync`.
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} opts.runtime - Ambient collaborators. Uses `fsSync.readFileSync`.
  * @returns {{type: "preset", preset: "claude_code", append: string}}
  */
 export function composeProfilePrompt(
@@ -177,18 +178,18 @@ export function composeProfilePrompt(
 
 /**
  * Compose a plain-string system prompt for a lead role (no Claude Code
- * preset). The protocol trailer, an optional profile's hoisted
- * `## Session Protocol` section, and any amendment are joined into
- * `<session_protocol>`; an optional persona is wrapped in a sibling
- * `<agent_profile>` before it.
+ * preset). This function joins the protocol trailer, an optional profile's
+ * hoisted `## Session Protocol` section, and any amendment into
+ * `<session_protocol>`. It wraps an optional persona in a sibling
+ * `<agent_profile>` before that section.
  *
  * @param {object} opts
  * @param {string} [opts.profile] - Profile basename (no `.md` suffix)
- * @param {string} [opts.profilesDir] - Directory containing profile files
+ * @param {string} [opts.profilesDir] - Directory that contains profile files
  * @param {string} opts.trailer - Session protocol (orchestration instructions)
  * @param {string} [opts.amend] - Run-specific amendment, the last fragment of
  *   the `<session_protocol>` section.
- * @param {import("@forwardimpact/libutil/runtime").Runtime} opts.runtime - Ambient collaborators; uses `fsSync.readFileSync`.
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} opts.runtime - Ambient collaborators. Uses `fsSync.readFileSync`.
  * @returns {string}
  */
 export function composeLeadPrompt({
@@ -209,20 +210,20 @@ export function composeLeadPrompt({
 }
 
 /**
- * Unified entry point for composing system prompts. Threads an optional
+ * Unified entry point that composes a system prompt. Threads an optional
  * amendment through as the run-specific fragment of `<session_protocol>`
- * (after the trailer and any hoisted profile section), then delegates by
+ * (after the trailer and any hoisted profile section). Then delegates by
  * role.
  *
  * @param {object} opts
- * @param {"lead"|"agent"} opts.role - `"lead"` produces a plain string;
+ * @param {"lead"|"agent"} opts.role - `"lead"` produces a plain string.
  *   `"agent"` produces a `claude_code` preset object.
  * @param {string} [opts.profile] - Profile basename
  * @param {string} [opts.profilesDir]
  * @param {string} opts.trailer - Session protocol (orchestration instructions)
  * @param {string} [opts.amend] - Caller-supplied amendment, the last fragment
  *   inside `<session_protocol>`, joined with a blank-line separator.
- * @param {import("@forwardimpact/libutil/runtime").Runtime} opts.runtime - Ambient collaborators; uses `fsSync.readFileSync`.
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} opts.runtime - Ambient collaborators. Uses `fsSync.readFileSync`.
  * @returns {string | {type: "preset", preset: "claude_code", append: string}}
  */
 export function composeSystemPrompt({

package/src/redaction.js

@@ -1,19 +1,20 @@
 /**
  * Redactor — replaces secrets in JSON-serialisable values before they reach
- * the trace artifact. Composes two layers: an env-var value allowlist and a
- * set of credential-shape regexes. Both run on every primitive string.
+ * the trace artifact. It composes two layers: an env-var value allowlist and
+ * a set of credential-shape regexes. Both run on every primitive string.
  *
- * Coverage includes encoded credential forms, not only raw bytes: the env
- * layer matches each allowlisted secret both raw and in its **standard
- * base64** form at any byte offset within the encoded plaintext, and the
- * pattern layer covers the git `extraheader` basic-auth wrapper. Boundary:
- * **standard base64 only** — URL-safe base64, hex, and percent-encoding are
- * not covered — and the **trace-write sink only**; content an agent authors
- * into a wiki commit is never passed through this redactor.
+ * Coverage includes encoded credential forms as well as raw bytes. The env
+ * layer matches each allowlisted secret raw. It also matches the secret in
+ * its **standard base64** form at any byte offset within the encoded
+ * plaintext. The pattern layer covers the git `extraheader` basic-auth
+ * wrapper. Two limits apply. The redactor covers **standard base64 only**,
+ * so it does not cover URL-safe base64, hex, or percent-encoding. It also
+ * covers the **trace-write sink only**. Content an agent authors into a wiki
+ * commit never passes through this redactor.
  *
- * Stateless after construction: `env` is captured once so in-process
- * `process.env` writes (e.g. agent-runner.js LIBHARNESS_SKILL, commands/run.js
- * LIBHARNESS_AGENT_PROFILE) cannot smuggle a value past the redactor.
+ * The redactor is stateless after construction. It captures `env` once, so
+ * in-process `process.env` writes (e.g. agent-runner.js LIBHARNESS_SKILL,
+ * commands/run.js LIBHARNESS_AGENT_PROFILE) cannot smuggle a value past it.
  */
 
 export const DEFAULT_ENV_ALLOWLIST = Object.freeze([
@@ -36,7 +37,7 @@ export const DEFAULT_ENV_ALLOWLIST = Object.freeze([
 
 // Anchored prefixes per
 // https://github.blog/security/application-security/behind-githubs-new-authentication-token-formats/
-// Anthropic prefix is heuristic — the env-allowlist layer is the primary
+// The Anthropic prefix is heuristic. The env-allowlist layer is the primary
 // defence for Anthropic keys.
 export const DEFAULT_PATTERNS = Object.freeze([
   { kind: "anthropic", regex: /sk-ant-[A-Za-z0-9_-]{80,}/g },
@@ -45,11 +46,11 @@ export const DEFAULT_PATTERNS = Object.freeze([
   { kind: "gh-oauth", regex: /\bgho_[A-Za-z0-9]{36}\b/g },
   { kind: "gh-fine-grained", regex: /\bgithub_pat_[A-Za-z0-9_]{82}\b/g },
   // git persists HTTP basic-auth credentials base64-encoded in
-  // `http.<url>.extraheader` as `AUTHORIZATION: basic <b64>` where the
-  // plaintext is `x-access-token:<token>` (actions/checkout form) — a shape
-  // the raw-byte layers above cannot see. The plaintext prefix is 15 bytes
-  // — five whole base64 triplets — so every encoding starts with the same
-  // 20 chars no matter which token follows.
+  // `http.<url>.extraheader` as `AUTHORIZATION: basic <b64>`. There the
+  // plaintext is `x-access-token:<token>` (actions/checkout form). The
+  // raw-byte layers above cannot see that shape. The plaintext prefix is 15
+  // bytes, which is five whole base64 triplets. So every encoded form starts
+  // with the same 20 chars, whatever token follows.
   {
     kind: "gh-b64-basic-credential",
     regex: /\beC1hY2Nlc3MtdG9rZW46[A-Za-z0-9+/]{8,}={0,2}/g,
@@ -60,27 +61,29 @@ const ENV_PLACEHOLDER = (name) => `[REDACTED:env:${name}]`;
 const PATTERN_PLACEHOLDER = (kind) => `[REDACTED:pattern:${kind}]`;
 
 /**
- * Minimum secret byte length for encoded-form matching. At 9 bytes the
- * shortest offset core is exactly 8 chars; below 9 it drops under 8 — too
- * short to be a sound needle against ordinary base64 trace content (margin of
- * safety, false positives). Every DEFAULT_ENV_ALLOWLIST value (token, key,
- * password) far exceeds it.
+ * The minimum byte length a secret needs before the redactor matches its
+ * encoded form. At 9 bytes the shortest offset core is exactly 8 chars.
+ * Below 9 bytes it drops under 8 chars. That is too short for a sound needle
+ * against ordinary base64 trace content (margin of safety, false positives).
+ * Every DEFAULT_ENV_ALLOWLIST value (token, key, password) far exceeds it.
  */
 const MIN_ENCODED_SECRET_BYTES = 9;
 
-// Leading base64 chars contaminated by the k filler bytes, per alignment.
+// The k filler bytes contaminate this many base64 chars at the start, per
+// alignment.
 const ENCODED_LEAD_STRIP = [0, 2, 3];
 
 /**
- * The three offset-invariant standard-base64 core substrings of `secret`, one
- * per byte alignment (k = 0/1/2). base64 maps disjoint 3-byte groups to 4 chars
- * independently, so the chars covering a secret's interior groups depend only
- * on the secret's bytes — never on the bytes surrounding it. Only the partial
- * groups at each edge are neighbour-dependent; stripping them leaves a core
- * that appears in the base64 of any plaintext placing `secret` at that
- * alignment. Padding lives only in the final partial group, which is stripped,
- * so each core is padding-free and one needle matches padded and unpadded
- * haystack content. Returns [] below MIN_ENCODED_SECRET_BYTES.
+ * Return the three standard-base64 core substrings of `secret`, one per byte
+ * alignment (k = 0/1/2). Each core is offset-invariant. base64 maps disjoint
+ * 3-byte groups to 4 chars independently. So the chars that cover a secret's
+ * interior groups depend only on the secret's bytes. They never depend on the
+ * bytes around it. Only the partial groups at each edge depend on the
+ * neighbours. This function strips those groups. The core that remains
+ * appears in the base64 of any plaintext that puts `secret` at that
+ * alignment. Padding lives only in the final partial group, and this function
+ * strips that group. So each core is padding-free. One needle matches padded
+ * and unpadded haystack content. Returns [] below MIN_ENCODED_SECRET_BYTES.
  * @param {string} secret
  * @returns {string[]}
  */
@@ -98,9 +101,10 @@ function encodedNeedles(secret) {
 
 /**
  * Build a frozen { name → { secret, needles } } snapshot of the requested env
- * vars. Empty strings are skipped — a leaked empty env var would otherwise
- * cause every empty string in the trace to be replaced. `needles` are the
- * precomputed standard-base64 cores (empty for sub-floor secrets).
+ * vars. This function skips empty strings. A leaked empty env var would
+ * otherwise make the redactor replace every empty string in the trace.
+ * `needles` are the precomputed standard-base64 cores (empty for sub-floor
+ * secrets).
  */
 function snapshotEnv(env, allowlist) {
   const snap = {};
@@ -129,8 +133,8 @@ function walk(value, redactString) {
 export class Redactor {
   /**
    * @param {object} deps
-   * @param {Readonly<Record<string, {secret: string, needles: string[]}>>} deps.envSnapshot - Frozen { name → { secret, needles } } map captured at construction time; `needles` are the precomputed standard-base64 cores of `secret`.
-   * @param {ReadonlyArray<{kind: string, regex: RegExp}>} deps.patterns - Credential-shape regexes; each match becomes `[REDACTED:pattern:KIND]`.
+   * @param {Readonly<Record<string, {secret: string, needles: string[]}>>} deps.envSnapshot - Frozen { name → { secret, needles } } map captured at construction time. `needles` are the precomputed standard-base64 cores of `secret`.
+   * @param {ReadonlyArray<{kind: string, regex: RegExp}>} deps.patterns - Credential-shape regexes. Each match becomes `[REDACTED:pattern:KIND]`.
    * @param {boolean} deps.enabled - When false, `redactValue` returns its input by reference.
    */
   constructor({ envSnapshot, patterns, enabled }) {
@@ -140,8 +144,9 @@ export class Redactor {
   }
 
   /**
-   * Redact any JSON-serialisable value by deep-walking and replacing secrets
-   * in every primitive string. Identity on the input when disabled.
+   * Redact any JSON-serialisable value. This method deep-walks the value and
+   * replaces secrets in every primitive string. When disabled, it returns its
+   * input by reference.
    * @param {unknown} value
    * @returns {unknown}
    */
@@ -163,10 +168,11 @@ export class Redactor {
       if (out.includes(secret)) {
         out = out.split(secret).join(ENV_PLACEHOLDER(name));
       }
-      // Standard-base64 form at any byte offset. Order among the three needles
-      // is irrelevant: once a region is replaced by the placeholder (which
-      // shares no base64 run with any needle) those bytes are gone, so a later
-      // needle cannot re-match them. The floor keeps every needle ≥ 8 chars.
+      // Standard-base64 form at any byte offset. The order among the three
+      // needles does not matter. The placeholder shares no base64 run with
+      // any needle. Once a replacement puts the placeholder over a region,
+      // those bytes are gone, so a later needle cannot re-match them. The
+      // floor keeps every needle ≥ 8 chars.
       for (const needle of needles) {
         if (out.includes(needle)) {
           out = out.split(needle).join(ENV_PLACEHOLDER(name));
@@ -181,20 +187,20 @@ export class Redactor {
 }
 
 /**
- * Build a redactor. Reads `LIBHARNESS_REDACTION_DISABLED` and
- * `LIBHARNESS_REDACTION_ENV_VARS` from the supplied env. The env and the stderr
- * sink are sourced from an injected `runtime` (`runtime.proc.env` /
- * `runtime.proc.stderr`); when no runtime is supplied a default one is
- * constructed so existing callers keep working. An explicit `opts.env`
- * override still wins for the snapshot. Fires a one-shot stderr warning when
- * constructed disabled — bypass via `createNoopRedactor()` for silent
- * fixtures.
+ * Build a redactor. It reads `LIBHARNESS_REDACTION_DISABLED` and
+ * `LIBHARNESS_REDACTION_ENV_VARS` from the supplied env. An injected
+ * `runtime` supplies the env and the stderr sink (`runtime.proc.env` /
+ * `runtime.proc.stderr`). When a caller supplies no runtime, the function
+ * constructs a default one so current callers keep working. An explicit
+ * `opts.env` override still wins for the snapshot. The function fires a
+ * one-shot stderr warning when a caller constructs it disabled. Use
+ * `createNoopRedactor()` for silent fixtures to bypass that warning.
  * @param {object} [opts]
- * @param {import("@forwardimpact/libutil/runtime").Runtime} [opts.runtime] - Ambient collaborators; `proc.env`/`proc.stderr` are used.
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} [opts.runtime] - Ambient collaborators. The factory uses `proc.env` and `proc.stderr`.
  * @param {Record<string, string|undefined>} [opts.env] - Environment to snapshot. Defaults to `runtime.proc.env`.
  * @param {string[]} [opts.allowlist] - Override the env-var name list. Defaults to `DEFAULT_ENV_ALLOWLIST` or the parsed `LIBHARNESS_REDACTION_ENV_VARS` value.
  * @param {ReadonlyArray<{kind: string, regex: RegExp}>} [opts.patterns] - Credential-shape regexes. Defaults to `DEFAULT_PATTERNS`.
- * @param {boolean} [opts.enabled] - Force enabled/disabled; bypasses `LIBHARNESS_REDACTION_DISABLED`.
+ * @param {boolean} [opts.enabled] - Force enabled or disabled. It bypasses `LIBHARNESS_REDACTION_DISABLED`.
  * @returns {Redactor}
  */
 export function createRedactor({
@@ -215,7 +221,7 @@ export function createRedactor({
     : Object.freeze({});
   if (!resolvedEnabled) {
     proc.stderr.write(
-      "libharness: trace redaction DISABLED via LIBHARNESS_REDACTION_DISABLED — secrets may appear in trace artifact\n",
+      "libharness: trace redaction DISABLED through LIBHARNESS_REDACTION_DISABLED. Secrets may appear in the trace artifact\n",
     );
   }
   return new Redactor({ envSnapshot, patterns, enabled: resolvedEnabled });
@@ -240,8 +246,8 @@ function resolveAllowlistFromEnv(env) {
 
 /**
  * Build a disabled redactor whose `redactValue` is the identity function.
- * Test-fixture form — bypasses `createRedactor` so no stderr warning
- * fires regardless of env state.
+ * Use this form in test fixtures. It bypasses `createRedactor`, so no stderr
+ * warning fires whatever the env state.
  * @returns {Redactor}
  */
 export function createNoopRedactor() {

package/src/render/line-renderer.js

@@ -1,14 +1,14 @@
 /**
  * Line renderer — composes prefix + color + body + reset into a single
- * terminal line. Pure; no side effects.
+ * terminal line. Pure, with no side effects.
  *
  * Every renderer returns a `\n`-terminated string:
  *     <source>: <ESC><color><body><RESET>\n
  *
- * The `<source>: ` prefix lives outside the color escape so grep and
- * color-stripping terminals preserve the participant tag. Colons separate
- * the source label and the kind label (`Bash:`, `Result:`, `Error:`) for a
- * tighter line on narrow viewports without losing structure.
+ * The `<source>: ` prefix lives outside the color escape, so grep and
+ * terminals that strip color preserve the participant tag. Colons separate
+ * the source label and the kind label (`Bash:`, `Result:`, `Error:`). The
+ * line then stays tight on narrow viewports and keeps its structure.
  */
 
 import { colorForSource, ERROR_COLOR, RESET } from "./palette.js";

package/src/render/orchestrator-filter.js

@@ -1,8 +1,8 @@
 /**
- * Orchestrator filter — predicate for the orchestrator lifecycle events that
- * should be suppressed from the human-readable log.
+ * Orchestrator filter — predicate that names the orchestrator lifecycle
+ * events to suppress from the human-readable log.
  *
- * NDJSON artifacts still carry every orchestrator event; this module only
+ * NDJSON artifacts still carry every orchestrator event. This module only
  * controls what the live `textStream` and offline `toText()` show.
  */
 

package/src/render/palette.js

@@ -1,15 +1,16 @@
 /**
  * Palette — pure profile-name → ANSI SGR foreground color function.
  *
- * Assignment is a FNV-1a hash of the source name modulo the palette size, so
- * the same name maps to the same color in every process. Red is reserved for
- * tool-result errors and is never in the palette.
+ * The module assigns a color from a FNV-1a hash of the source name modulo
+ * the palette size. So the same name maps to the same color in every
+ * process. The module reserves red for tool-result errors. The palette never
+ * contains red.
  *
  * Colors use the 24-bit truecolor SGR escape (`ESC[38;2;R;G;Bm`) rather than
  * the 16-color table. GitHub Actions' log viewer and most modern terminals
- * render truecolor as the exact hex requested, avoiding the washed-out
+ * render truecolor as the exact hex requested. This avoids the washed-out
  * mustard/olive tones GHA applies to `ESC[93m` etc. Eight slots cover the
- * largest concurrent cast in any existing workflow (five domain agents plus
+ * largest concurrent cast in any current workflow (five domain agents plus
  * the facilitator) with headroom.
  */
 
@@ -33,9 +34,10 @@ export const RESET = "\u001b[0m";
 /**
  * Map a source name to a stable ANSI foreground color.
  *
- * The mapping is a pure function of the name via FNV-1a 32-bit hash — same
- * name, same color, every call, in every process. Returns `RESET` for
- * missing/empty names so callers never emit a stray escape.
+ * This function is pure. A FNV-1a 32-bit hash of the name decides the color.
+ * The same name gives the same color on every call, in every process.
+ * Returns `RESET` for absent or empty names so callers never emit a stray
+ * escape.
  *
  * @param {string|null|undefined} name
  * @returns {string} ANSI SGR escape, never equal to `ERROR_COLOR`
@@ -47,7 +49,7 @@ export function colorForSource(name) {
     h ^= name.charCodeAt(i);
     h = Math.imul(h, 0x01000193) >>> 0;
   }
-  // Length mixer: reduces FNV's intrinsic birthday collisions on short
+  // Length mixer. It reduces FNV's intrinsic birthday collisions on short
   // names with shared affixes (e.g. `staff-engineer`/`facilitator`).
   h ^= name.length;
   h = Math.imul(h, 0x01000193) >>> 0;

package/src/render/tool-hints.js

@@ -3,24 +3,25 @@
  * tool-result previews.
  *
  * `hintForCall(name, input)` renders the human-meaningful field for each
- * tool (file path, command, pattern, …) sanitized to strip JSON punctuation
- * (`{`, `}`, `"`) and collapsed to a single line ≤ 80 chars.
+ * tool (file path, command, pattern, …). It strips JSON punctuation
+ * (`{`, `}`, `"`) from that field. It collapses the field to a single line
+ * ≤ 80 chars.
  *
- * MCP-prefixed tools (`mcp__*`) are an intentional carve-out: their hint is
+ * MCP-prefixed tools (`mcp__*`) are an intentional carve-out. Their hint is
  * the full input rendered as compact single-line JSON, so `{` and `"` do
  * appear on those lines. Readers of GitHub workflow logs need the full MCP
- * payload to know what was actually sent across the protocol.
+ * payload to know what the caller actually sent across the protocol.
  *
  * `previewForResult(content, isError)` collapses a tool result to a single
- * line ≤ 80 chars and flags errors so the renderer can apply the reserved
- * error color and the `Error:` label.
+ * line ≤ 80 chars. It also flags errors. The flag lets the renderer apply
+ * the reserved error color and the `Error:` label.
  */
 
 const MAX_HINT_CHARS = 80;
 
 /**
  * Strip `{`, `}`, `"`, collapse whitespace, and truncate to MAX_HINT_CHARS.
- * First line only — anything past a newline is dropped. Always returns a
+ * Use the first line only. Drop anything past a newline. Always returns a
  * string, never null/undefined.
  * @param {unknown} raw
  * @returns {string}
@@ -36,9 +37,10 @@ function sanitize(raw) {
 }
 
 /**
- * Truncate an already-sanitized string to MAX_HINT_CHARS with a trailing
- * ellipsis when it overflows. Shared by the few handlers that concatenate
- * multiple sanitized pieces before deciding on truncation.
+ * Truncate an already-sanitized string to MAX_HINT_CHARS, with an ellipsis
+ * at the end when it overflows. The few handlers that concatenate multiple
+ * sanitized pieces share this helper. They concatenate first, then decide
+ * whether to truncate.
  * @param {string} str
  * @returns {string}
  */
@@ -50,8 +52,9 @@ function truncate(str) {
 
 /**
  * Per-tool hint handlers. Each entry takes the sanitized input object
- * (never null) and returns the hint string. Kept as a flat table so adding
- * a new tool is one entry, not a new branch in a growing switch.
+ * (never null) and returns the hint string. This table stays flat. A new
+ * tool then needs one entry. It does not need a new branch in a switch that
+ * grows.
  */
 const HINT_HANDLERS = {
   Bash: (i) => sanitize(i.command),
@@ -104,7 +107,7 @@ export function simplifyToolName(name) {
  *    `{` / `"` from the input (built-in tool hints stay free of JSON
  *    punctuation so readers see clean one-liners).
  *  - An MCP-prefixed tool (`mcp__*`) → full input rendered as compact
- *    single-line JSON; `{` and `"` intentionally appear so readers see
+ *    single-line JSON. `{` and `"` intentionally appear so readers see
  *    the actual MCP payload.
  *  - Anything else → "" (the caller still shows the bare tool name).
  *
@@ -126,8 +129,8 @@ export function hintForCall(name, input) {
 
 /**
  * Render a tool result as a single preview line plus an `isError` flag.
- * The flag lets the line-renderer pick the reserved error color without
- * re-inspecting the content.
+ * The flag lets the line-renderer pick the reserved error color. The
+ * line-renderer does not re-inspect the content.
  *
  * @param {string|object|null|undefined} content - Tool result content
  * @param {boolean} isError - Whether the tool call failed

package/src/render/turn-renderer.js

@@ -1,8 +1,8 @@
 /**
  * Turn renderer — maps a structured turn into formatted text lines.
  *
- * Shared by `TeeWriter.flushTurns()` (live stream) and
- * `TraceCollector.toText()` (offline replay) so both emit identical output.
+ * `TeeWriter.flushTurns()` (live stream) and `TraceCollector.toText()`
+ * (offline replay) share it, so both emit identical output.
  */
 
 import {
@@ -51,8 +51,8 @@ function renderAssistantTurn(turn, withPrefix) {
 
 /** @param {object} turn @param {boolean} withPrefix @returns {string[]} */
 function renderToolResultTurn(turn, withPrefix) {
-  // Successful tool results emit no preview line — the trace document keeps
-  // the structured turn, but readers of the streamed log only see errors.
+  // Successful tool results emit no preview line. The trace document keeps
+  // the structured turn. Readers of the streamed log see errors only.
   if (!turn.isError) return [];
   return [
     renderToolResultLine({

package/src/reply-emitter.js

@@ -1,7 +1,7 @@
 /**
  * ReplyEmitter — POST reply/ack events to the callback URL as they
- * happen. Each emission is fire-and-forget so the message bus is never
- * blocked on network I/O.
+ * happen. Each emission is fire-and-forget, so network I/O never blocks
+ * the message bus.
  */
 export class ReplyEmitter {
   #callbackUrl;