@forwardimpact/libharness 2.0.0 → 3.0.1

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;

package/src/sequence-counter.js

@@ -1,6 +1,7 @@
 /**
- * SequenceCounter — global monotonic counter shared across all participants
- * in a session. Single-threaded JS means no synchronization needed.
+ * SequenceCounter — global monotonic counter. All participants in a session
+ * share one counter. Single-threaded JS means the counter needs no
+ * synchronization.
  */
 /** Monotonic counter that assigns globally ordered sequence numbers within a session. */
 export class SequenceCounter {
@@ -15,7 +16,7 @@ export class SequenceCounter {
   }
 }
 
-/** Create a new SequenceCounter starting at zero. */
+/** Create a new SequenceCounter that starts at zero. */
 export function createSequenceCounter() {
   return new SequenceCounter();
 }

package/src/signature-filter.js

@@ -1,13 +1,14 @@
 /**
  * Strip `thinking.signature` base64 blobs from a JSON-serializable value.
  *
- * Applied at the CLI output boundary — the stored structured trace keeps
- * signatures intact (lossless storage), and the display filter drops them
- * by default because they dominate output without helping analysis.
+ * The CLI applies this filter at the output boundary. The stored structured
+ * trace keeps signatures intact (lossless storage). The display filter drops
+ * them by default, because they dominate the output and do not help
+ * analysis.
  *
- * Recursively walks the input. For any object whose `type === "thinking"`,
- * the `signature` field is removed after copying. Signatures on objects of
- * any other type are preserved.
+ * This function walks the input recursively. For any object whose
+ * `type === "thinking"`, it copies the object and then removes the
+ * `signature` field. It keeps signatures on objects of any other type.
  *
  * @param {*} value - Any JSON-serializable value
  * @returns {*} A deep-copy with thinking signatures removed

package/src/supervisor.js

@@ -1,14 +1,14 @@
 /**
- * Supervisor — supervise-mode wrapper around `OrchestrationLoop`. One
- * named participant (`"agent"`) coordinated by a lead participant
- * (`"supervisor"`). Structurally the same as `Facilitator` with a
- * single agent; differs only in role names, prompts, and pass-through
- * accessors.
+ * Supervisor — supervise-mode wrapper around `OrchestrationLoop`. A lead
+ * participant (`"supervisor"`) coordinates one named participant
+ * (`"agent"`). The structure is the same as `Facilitator` with a single
+ * agent. Only the role names, the prompts, and the pass-through accessors
+ * differ.
  *
- * Ask is async (same contract as facilitate / discuss): returns
- * `{askIds:[N]}` immediately; the agent's reply arrives on the
+ * Ask is async, with the same contract as facilitate and discuss. It
+ * returns `{askIds:[N]}` immediately. The agent's reply arrives on the
  * supervisor's next turn as `[answer#N] agent: <text>`. The supervisor
- * sees the agent at each Ask boundary, plans the next step, and
+ * sees the agent at each Ask boundary. It plans the next step. It
  * eventually calls Conclude.
  *
  * For tighter feedback loops, size the agent's per-turn budget down
@@ -34,7 +34,7 @@ import {
 } from "./advisor.js";
 import { createTranscriptRecorder } from "./transcript-recorder.js";
 
-/** System prompt for the supervisor lead. L0 mechanics only per COALIGNED. */
+/** System prompt for the supervisor lead. L0 mechanics only per JIDOKA. */
 export const SUPERVISOR_SYSTEM_PROMPT =
   "You supervise one agent.\n" +
   "Use `Ask` to delegate the agent's task to the agent.\n" +
@@ -42,9 +42,9 @@ export const SUPERVISOR_SYSTEM_PROMPT =
   "The reply arrives on your next turn as `[answer#N] agent: <text>` in your inbox.\n" +
   "End your turn while Asks are pending. The system resumes you when an answer arrives.\n" +
   "If the agent goes off-track, send a corrective `Ask`.\n" +
-  "End every session by calling `Conclude` with a verdict and summary.";
+  "Call `Conclude` with a verdict and summary to end every session.";
 
-/** System prompt for the supervised agent. L0 mechanics only per COALIGNED. */
+/** System prompt for the supervised agent. L0 mechanics only per JIDOKA. */
 export const AGENT_SYSTEM_PROMPT =
   "A supervisor directs your work.\n" +
   "Each question arrives as `[ask#N] supervisor: <text>` in your inbox.\n" +
@@ -54,7 +54,8 @@ export const AGENT_SYSTEM_PROMPT =
 
 /**
  * Supervise-mode wrapper around `OrchestrationLoop`. The lead is
- * `"supervisor"`, one participant is `"agent"`, mode tag is `"supervised"`.
+ * `"supervisor"`. One participant is `"agent"`. The mode tag is
+ * `"supervised"`.
  */
 export class Supervisor extends OrchestrationLoop {
   /**
@@ -135,7 +136,7 @@ const devNull = new Writable({
  * @param {string} [deps.profilesDir]
  * @param {string} [deps.taskAmend]
  * @param {Record<string, object>} [deps.agentMcpServers]
- * @param {string} [deps.advisorModel] - Claude model for advisor consults; absent means no Advisor tool is offered.
+ * @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 (default 3).
  * @returns {Supervisor}
  */
@@ -181,9 +182,9 @@ export function createSupervisor({
   const perRunBudget = maxTurns ?? 200;
   const abortController = new AbortController();
 
-  // Advisor wiring — everything below is gated on advisorModel being set;
-  // with it unset the composed prompt and tool surface are byte-identical
-  // to today's.
+  // Everything below wires the advisor. It runs only when advisorModel is
+  // set. When advisorModel is unset, the composed prompt and the tool
+  // surface stay byte-identical to today's.
   const budget = advisorModel ? createAdvisorBudget(advisorMaxUses ?? 3) : null;
   const agentSystemPrompt = composeSystemPrompt({
     role: "agent",
@@ -201,8 +202,8 @@ export function createSupervisor({
       systemPrompt: agentSystemPrompt,
       redactor,
     });
-    // Late-bound through the `let supervisor` closure — the instance does
-    // not exist yet when the advisor and tool are built.
+    // The `let supervisor` closure binds this late. The instance does not
+    // exist yet when the factory builds the advisor and the tool.
     const advisor = createAdvisor({
       model: advisorModel,
       cwd: agentCwd,