@forwardimpact/libharness 2.0.0 → 3.0.1

package/src/commands/discuss.js

@@ -17,8 +17,8 @@ function parseAgentProfiles(raw, cwd, maxTurns) {
 }
 
 /**
- * Parse and validate discuss command options. Exported so tests can verify
- * defaults and the legacy-flag clean break.
+ * Parse and validate discuss command options. This function is exported so a
+ * test can verify the defaults and the legacy-flag clean break.
  * @param {object} values - Parsed option values
  * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  * @returns {object}
@@ -30,8 +30,8 @@ export function parseDiscussOptions(values, runtime) {
   );
 
   const profilesRaw = values["agent-profiles"];
-  // `||` (not `??`) so an empty-string flag from a CI forwarder falls back to
-  // the default rather than overriding it with "".
+  // `||` (not `??`) so an empty-string flag from a CI forwarder falls back
+  // to the default. The empty string does not override the default.
   const agentCwd = resolve(values["agent-cwd"] || ".");
 
   const maxTurnsRaw = values["max-turns"] || "40";
@@ -74,8 +74,8 @@ export function parseDiscussOptions(values, runtime) {
 
 /**
  * Discuss command — run a discusser-led session with suspend/resume
- * semantics, threading `discussion_id` through the trace so multi-run
- * conversations are queryable as one.
+ * semantics. The session threads `discussion_id` through the trace, so
+ * you can query multi-run conversations as one.
  *
  * @param {import("@forwardimpact/libcli").InvocationContext} ctx
  * @returns {Promise<{ok: boolean, code?: number, error?: string}>}
@@ -102,7 +102,8 @@ export async function runDiscussCommand(ctx) {
     runtime.proc.env.LIBHARNESS_AGENT_PROFILE = opts.leadProfile;
   }
   // Unconditional so the default "github" is observable to the agent's
-  // active-tracker resolution, mirroring --agent-profile's env write above.
+  // active-tracker resolution. This mirrors --agent-profile's env write
+  // above.
   runtime.proc.env.LIBHARNESS_WORK_TRACKER = opts.workTracker;
 
   const { query } = await import("@anthropic-ai/claude-agent-sdk");

package/src/commands/facilitate.js

@@ -22,9 +22,9 @@ function parseAgentProfiles(raw, cwd, maxTurns) {
 }
 
 /**
- * Parse and validate facilitate command options. Exported for test
- * coverage of the `--max-turns` → per-agent threading contract; not part
- * of the package's public API.
+ * Parse and validate facilitate command options. This function is exported
+ * so a test can cover the contract that threads `--max-turns` to each
+ * agent. It is not part of the package's public API.
  * @param {object} values - Parsed option values
  * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
  * @returns {object} Parsed options
@@ -37,17 +37,18 @@ export function parseFacilitateOptions(values, runtime) {
 
   const profilesRaw = values["agent-profiles"];
   if (!profilesRaw) throw new Error("--agent-profiles is required");
-  // `||` (not `??`) so an empty-string flag from a CI forwarder falls back to
-  // the default rather than overriding it with "".
+  // `||` (not `??`) so an empty-string flag from a CI forwarder falls back
+  // to the default. The empty string does not override the default.
   const agentCwd = resolve(values["agent-cwd"] || ".");
 
   const maxTurnsRaw = values["max-turns"] || "20";
   const maxTurns = maxTurnsRaw === "0" ? 0 : parseInt(maxTurnsRaw, 10);
 
-  // Thread --max-turns into each participant: without this, every facilitated
-  // agent silently falls back to the 50-turn default in facilitator.js even
-  // when the caller raises the budget. Observed in run 26078312414 where
-  // staff-engineer terminated at 51 turns despite --max-turns=200.
+  // Thread --max-turns into each participant. Without this, every
+  // facilitated agent silently falls back to the 50-turn default in
+  // facilitator.js, even when the caller raises the budget. Run
+  // 26078312414 showed this. In it, staff-engineer terminated at 51
+  // turns despite --max-turns=200.
   const agentConfigs = parseAgentProfiles(profilesRaw, agentCwd, maxTurns);
 
   return {
@@ -68,7 +69,7 @@ export function parseFacilitateOptions(values, runtime) {
 /**
  * Facilitate command — run a facilitated multi-agent session.
  *
- * Usage: fit-harness facilitate [options]
+ * Usage: gemba-harness facilitate [options]
  *
  * @param {import("@forwardimpact/libcli").InvocationContext} ctx
  * @returns {Promise<{ok: boolean, code?: number, error?: string}>}
@@ -77,9 +78,9 @@ export async function runFacilitateCommand(ctx) {
   const runtime = ctx.deps.runtime;
   const opts = parseFacilitateOptions(ctx.options, runtime);
 
-  // Build the redactor as the first observable side-effect after option
-  // parsing — the env snapshot must freeze BEFORE any in-process
-  // env writes the command performs (e.g. LIBHARNESS_AGENT_PROFILE).
+  // Build the redactor as the first observable side-effect after the parser
+  // reads the options. The env snapshot must freeze BEFORE any in-process
+  // env write the command performs (e.g. LIBHARNESS_AGENT_PROFILE).
   const redactor = createRedactor({ runtime });
 
   const fileStream = opts.outputPath
@@ -98,7 +99,8 @@ export async function runFacilitateCommand(ctx) {
     runtime.proc.env.LIBHARNESS_AGENT_PROFILE = opts.facilitatorProfile;
   }
   // Unconditional so the default "github" is observable to the agent's
-  // active-tracker resolution, mirroring --agent-profile's env write above.
+  // active-tracker resolution. This mirrors --agent-profile's env write
+  // above.
   runtime.proc.env.LIBHARNESS_WORK_TRACKER = opts.workTracker;
 
   const { query } = await import("@anthropic-ai/claude-agent-sdk");

package/src/commands/output.js

@@ -5,7 +5,7 @@ import { createTraceCollector } from "@forwardimpact/libharness";
  * Output command — process a complete NDJSON trace from stdin and write
  * formatted output to stdout.
  *
- * Usage: fit-harness output [--format=json|text] < trace.ndjson
+ * Usage: gemba-harness output [--format=json|text] < trace.ndjson
  *
  * @param {import("@forwardimpact/libcli").InvocationContext} ctx
  * @returns {Promise<{ok: true}>}
@@ -21,8 +21,9 @@ export async function runOutputCommand(ctx) {
     now: () => isoTimestamp(runtime.clock.now()),
   });
 
-  // `runtime.proc.stdin` is an AsyncIterable of UTF-8 lines (newline-split by
-  // the runtime), so each yielded value is exactly one NDJSON record.
+  // `runtime.proc.stdin` is an AsyncIterable of UTF-8 lines. The runtime
+  // splits them on newlines. So each yielded value is exactly one NDJSON
+  // record.
   for await (const line of runtime.proc.stdin) {
     collector.addLine(line);
   }

package/src/commands/run.js

@@ -34,8 +34,8 @@ export function parseRunOptions(values, runtime) {
     values,
     runtime,
   );
-  // `||` (not `??`) so an empty-string flag from a CI forwarder falls back to
-  // the default, rather than overriding it with "".
+  // `||` (not `??`) so an empty-string flag from a CI forwarder falls back
+  // to the default. The empty string does not override the default.
   const maxTurnsRaw = values["max-turns"] || "50";
 
   return {
@@ -64,10 +64,10 @@ const devNull = new Writable({
 
 /**
  * Wire the run-mode agent session: external MCP entry, `LIBHARNESS_*` env
- * writes, system-prompt composition, and — when an advisor model is set —
- * the advisor wiring (budget, recorder, advisor session, dedicated MCP
- * server holding only the `Advisor` tool). Extracted from `runRunCommand`
- * so tests can inject a fake `query`.
+ * writes, and system-prompt composition. When an advisor model is set, also
+ * wire the advisor (budget, recorder, advisor session, and a dedicated MCP
+ * server that holds only the `Advisor` tool). This function is extracted
+ * from `runRunCommand` so a test can inject a fake `query`.
  *
  * Run mode has no stop path (the command simply awaits the runner), so the
  * consult timeout is deliberately the advisor's only guard.
@@ -120,9 +120,9 @@ export async function wireRunSession({
   runtime.proc.env.LIBHARNESS_WORK_TRACKER = opts.workTracker;
 
   // With a profile, the consult guidance rides the profile composer's
-  // amendment parameter; with no profile, a preset-append prompt carries
+  // amendment parameter. With no profile, a preset-append prompt carries
   // the guidance as its only session-protocol fragment. Advisor off and no
-  // profile means no system prompt — today's behavior, unchanged.
+  // profile means no system prompt. That is today's behavior, unchanged.
   let systemPrompt;
   if (opts.agentProfile) {
     systemPrompt = composeProfilePrompt(opts.agentProfile, {
@@ -161,7 +161,7 @@ export async function wireRunSession({
       budget,
       model: opts.advisorModel,
     });
-    // No allowlist push: in-process SDK MCP servers work under
+    // No allowlist push. In-process SDK MCP servers work under
     // bypassPermissions without allowlist entries (loop-mode precedent).
     mcpServers = {
       ...mcpServers,
@@ -195,9 +195,9 @@ export async function wireRunSession({
 }
 
 /**
- * Run command — execute a single agent via the Claude Agent SDK.
+ * Run command — execute a single agent through the Claude Agent SDK.
  *
- * Usage: fit-harness run [options]
+ * Usage: gemba-harness run [options]
  *
  * @param {import("@forwardimpact/libcli").InvocationContext} ctx
  * @returns {Promise<{ok: boolean, code?: number, error?: string}>}
@@ -206,12 +206,12 @@ export async function runRunCommand(ctx) {
   const runtime = ctx.deps.runtime;
   const opts = parseRunOptions(ctx.options, runtime);
 
-  // Build the redactor as the first observable side-effect after option
-  // parsing — the env snapshot must freeze BEFORE any in-process
-  // env writes the command performs (e.g. LIBHARNESS_AGENT_PROFILE).
+  // Build the redactor as the first observable side-effect after the parser
+  // reads the options. The env snapshot must freeze BEFORE any in-process
+  // env write the command performs (e.g. LIBHARNESS_AGENT_PROFILE).
   const redactor = createRedactor({ runtime });
 
-  // When --output is specified, stream text to stdout while writing NDJSON to file.
+  // With --output, stream text to stdout and write NDJSON to the file.
   // Otherwise, write NDJSON directly to stdout (backwards-compatible).
   const fileStream = opts.outputPath
     ? runtime.fs.createWriteStream(opts.outputPath)

package/src/commands/scan-logs.js

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

package/src/commands/selfedit.js

@@ -0,0 +1,124 @@
+/**
+ * Safeguard-and-write logic behind the `gemba-selfedit` bin. It writes
+ * content to a path that .claude/settings.json permits Edit on. The write
+ * happens only on a non-main git branch. See
+ * libraries/libharness/README.md § gemba-selfedit for the full rationale.
+ */
+
+import { resolve, relative, dirname } from "node:path";
+
+import { minimatch } from "minimatch";
+
+/** A safeguard violation. Callers map it to exit code 2. */
+export class SelfeditError extends Error {
+  /** @param {string} message failure description */
+  constructor(message) {
+    super(message);
+    this.name = "SelfeditError";
+  }
+}
+
+/**
+ * Check every safeguard for a selfedit write, then perform it.
+ *
+ * The function checks these safeguards in order:
+ * 1. The nearest .claude/settings.json must contain an Edit(<glob>) rule in
+ *    permissions.allow[] that resolves to the target path.
+ * 2. HEAD must not be detached and the current branch must not be 'main'.
+ * 3. The target's parent directory must exist.
+ *
+ * @param {string} targetArg target path from the command line
+ * @param {Buffer} content bytes to write
+ * @param {{ runtime: object }} deps runtime bag (fsSync, proc, subprocess,
+ *   finder). targetArg resolves against `runtime.proc.cwd()`
+ * @returns {{ bytes: number, relativeTarget: string, matchedPattern: string,
+ *   branch: string }} what the function wrote and which rule allowed it
+ * @throws {SelfeditError} on any safeguard violation
+ */
+export function runSelfeditCommand(targetArg, content, { runtime }) {
+  const { fsSync, proc, subprocess, finder } = runtime;
+  const cwd = proc.cwd();
+  const absoluteTarget = resolve(cwd, targetArg);
+
+  // Safeguard 1: settings.json must grant Edit() on this path. Resolve the
+  // finder off the runtime bag. Do not construct a Finder here.
+  const settingsPath = finder.findUpward(
+    dirname(absoluteTarget),
+    ".claude/settings.json",
+    20,
+  );
+  if (!settingsPath) {
+    throw new SelfeditError(
+      `no .claude/settings.json found walking upward from ${dirname(absoluteTarget)}`,
+    );
+  }
+
+  const projectRoot = dirname(dirname(settingsPath));
+  const relativeTarget = relative(projectRoot, absoluteTarget);
+
+  let settings;
+  try {
+    settings = JSON.parse(fsSync.readFileSync(settingsPath, "utf8"));
+  } catch (err) {
+    throw new SelfeditError(`failed to parse ${settingsPath}: ${err.message}`);
+  }
+
+  const allowRules = settings?.permissions?.allow;
+  if (!Array.isArray(allowRules)) {
+    throw new SelfeditError(`${settingsPath} has no permissions.allow[] array`);
+  }
+
+  const editPatterns = allowRules
+    .filter((rule) => typeof rule === "string")
+    .map((rule) => rule.match(/^Edit\((.+)\)$/)?.[1])
+    .filter(Boolean);
+
+  if (editPatterns.length === 0) {
+    throw new SelfeditError(
+      `${settingsPath} has no Edit() rules in permissions.allow[]`,
+    );
+  }
+
+  const matchedPattern = editPatterns.find((pattern) =>
+    minimatch(relativeTarget, pattern, { dot: true }),
+  );
+  if (!matchedPattern) {
+    throw new SelfeditError(
+      `no Edit() rule in ${relative(projectRoot, settingsPath)} matches '${relativeTarget}' ` +
+        `(tried: ${editPatterns.map((p) => `Edit(${p})`).join(", ")})`,
+    );
+  }
+
+  // Safeguard 2: the branch must not be main and HEAD must not be detached.
+  const git = subprocess.runSync("git", ["rev-parse", "--abbrev-ref", "HEAD"], {
+    cwd,
+  });
+  if (git.exitCode !== 0) {
+    throw new SelfeditError(
+      "failed to read the current git branch (this may not be a git repository)",
+    );
+  }
+  const branch = git.stdout.trim();
+
+  if (branch === "HEAD") {
+    throw new SelfeditError(
+      "will not write while HEAD is detached. Check out a non-main branch first",
+    );
+  }
+  if (branch === "main") {
+    throw new SelfeditError(
+      "will not write while on branch 'main'. Switch to a feature branch",
+    );
+  }
+
+  const parent = dirname(absoluteTarget);
+  if (!fsSync.existsSync(parent)) {
+    throw new SelfeditError(
+      `parent directory '${relative(projectRoot, parent)}' does not exist`,
+    );
+  }
+
+  fsSync.writeFileSync(absoluteTarget, content);
+
+  return { bytes: content.length, relativeTarget, matchedPattern, branch };
+}

package/src/commands/supervise.js

@@ -23,11 +23,12 @@ export async function parseSuperviseOptions(values, runtime) {
   const supervisorAllowedToolsRaw = values["supervisor-allowed-tools"];
 
   // `||` (not `??`) throughout so an empty-string flag from a CI forwarder
-  // falls back to the default rather than overriding it with "".
+  // falls back to the default. The empty string does not override the
+  // default.
   const tmpRoot = runtime.proc.env.TMPDIR ?? "/tmp";
   const agentCwd = resolve(
     values["agent-cwd"] ||
-      (await runtime.fs.mkdtemp(join(tmpRoot, "fit-harness-agent-"))),
+      (await runtime.fs.mkdtemp(join(tmpRoot, "gemba-harness-agent-"))),
   );
 
   return {
@@ -58,11 +59,11 @@ export async function parseSuperviseOptions(values, runtime) {
 }
 
 /**
- * Supervise command — run one agent under a supervisor via the
- * orchestration loop. The supervisor delegates work through Ask, sees
- * each reply on its next turn, and ends with Conclude.
+ * Supervise command — run one agent under a supervisor through the
+ * orchestration loop. The supervisor delegates work through Ask. It sees
+ * each reply on its next turn. It ends with Conclude.
  *
- * Usage: fit-harness supervise [options]
+ * Usage: gemba-harness supervise [options]
  *
  * @param {import("@forwardimpact/libcli").InvocationContext} ctx
  * @returns {Promise<{ok: boolean, code?: number, error?: string}>}
@@ -71,12 +72,12 @@ export async function runSuperviseCommand(ctx) {
   const runtime = ctx.deps.runtime;
   const opts = await parseSuperviseOptions(ctx.options, runtime);
 
-  // Build the redactor as the first observable side-effect after option
-  // parsing — the env snapshot must freeze BEFORE any in-process
-  // env writes the command performs (e.g. LIBHARNESS_AGENT_PROFILE).
+  // Build the redactor as the first observable side-effect after the parser
+  // reads the options. The env snapshot must freeze BEFORE any in-process
+  // env write the command performs (e.g. LIBHARNESS_AGENT_PROFILE).
   const redactor = createRedactor({ runtime });
 
-  // When --output is specified, stream text to stdout while writing NDJSON to file.
+  // With --output, stream text to stdout and write NDJSON to the file.
   // Otherwise, write NDJSON directly to stdout (backwards-compatible).
   const fileStream = opts.outputPath
     ? runtime.fs.createWriteStream(opts.outputPath)
@@ -107,7 +108,8 @@ export async function runSuperviseCommand(ctx) {
     runtime.proc.env.LIBHARNESS_AGENT_PROFILE = opts.agentProfile;
   }
   // Unconditional so the default "github" is observable to the agent's
-  // active-tracker resolution, mirroring --agent-profile's env write above.
+  // active-tracker resolution. This mirrors --agent-profile's env write
+  // above.
   runtime.proc.env.LIBHARNESS_WORK_TRACKER = opts.workTracker;
 
   const { query } = await import("@anthropic-ai/claude-agent-sdk");

package/src/commands/task-input.js

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

package/src/commands/tee.js

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