@forwardimpact/libharness 0.1.20 → 1.0.0

package/src/profile-prompt.js

@@ -0,0 +1,266 @@
+/**
+ * System prompt composition for agent runners.
+ *
+ * libharness assembles every agent system prompt from up to two parallel,
+ * sibling-tagged sections (see COALIGNED.md § L0):
+ *
+ *     <agent_profile>
+ *     …persona body…
+ *     </agent_profile>
+ *
+ *     <session_protocol>
+ *     …orchestration mechanics, then any amendment…
+ *     </session_protocol>
+ *
+ * The two tags are siblings joined by a blank line — 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
+ * carry no tags.
+ *
+ * The `<session_protocol>` body is assembled 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
+ * `## 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>`).
+ *
+ * Helpers:
+ *
+ * - `composeProfilePrompt(name, opts)` — profile + `claude_code` preset.
+ *   Used by agent participants that need the full Claude Code tool surface.
+ *
+ * - `composeLeadPrompt(opts)` — plain string, no preset. Used by lead
+ *   roles (supervisor, facilitator, discuss lead) that 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`.
+ */
+
+import { join } from "node:path";
+
+/** Sibling section tags. Neither nests inside the other. */
+const AGENT_PROFILE_TAG = "agent_profile";
+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.
+ */
+const SESSION_PROTOCOL_HEADING = /^##[ \t]+session protocol[ \t]*$/i;
+
+/** A level-1 or level-2 heading — the boundary that ends a hoisted section. */
+const SECTION_BOUNDARY = /^#{1,2}[ \t]+\S/;
+
+/** Wrap content in a semantic section tag, each on its own line. */
+function wrapSection(tag, content) {
+  return `<${tag}>\n${content}\n</${tag}>`;
+}
+
+/**
+ * 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.
+ *
+ * @param {object} parts
+ * @param {string} [parts.body] - Profile body, frontmatter-stripped and with
+ *   any `## Session Protocol` section already hoisted out.
+ * @param {Array<string | undefined>} [parts.protocolParts] - Ordered session
+ *   protocol fragments: trailer, hoisted profile section, run amendment.
+ * @returns {string}
+ */
+function assembleSections({ body, protocolParts = [] }) {
+  const sections = [];
+  if (body) sections.push(wrapSection(AGENT_PROFILE_TAG, body));
+  const protocol = protocolParts.filter(Boolean).join("\n\n");
+  if (protocol) sections.push(wrapSection(SESSION_PROTOCOL_TAG, protocol));
+  return sections.join("\n\n");
+}
+
+/**
+ * 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`.
+ *
+ * @param {string} body - Frontmatter-stripped, trimmed profile body.
+ * @returns {{ persona: string, protocol: string | undefined }}
+ */
+function splitSessionProtocol(body) {
+  const lines = body.split("\n");
+  const start = lines.findIndex((line) => SESSION_PROTOCOL_HEADING.test(line));
+  if (start === -1) return { persona: body, protocol: undefined };
+
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (SECTION_BOUNDARY.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+
+  const protocol = lines
+    .slice(start + 1, end)
+    .join("\n")
+    .trim();
+  const before = lines.slice(0, start).join("\n").trim();
+  const after = lines.slice(end).join("\n").trim();
+  const persona = [before, after].filter(Boolean).join("\n\n");
+  return { persona, protocol: protocol || undefined };
+}
+
+/**
+ * Read a profile `.md`, strip its frontmatter, and split off any hoisted
+ * `## Session Protocol` section. Reads synchronously off the injected
+ * `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.
+ *
+ * @param {string} name - Profile basename (no `.md` suffix)
+ * @param {string} profilesDir - Directory containing `<name>.md`
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
+ * @returns {{ persona: string, protocol: string | undefined }}
+ */
+function readProfileSections(name, profilesDir, runtime) {
+  const path = join(profilesDir, `${name}.md`);
+  const raw = runtime.fsSync.readFileSync(path, "utf8");
+  return splitSessionProtocol(stripFrontmatter(raw).trim());
+}
+
+/**
+ * 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>`.
+ *
+ * @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.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`.
+ * @returns {{type: "preset", preset: "claude_code", append: string}}
+ */
+export function composeProfilePrompt(
+  name,
+  { profilesDir, trailer, amend, runtime },
+) {
+  const { persona, protocol } = readProfileSections(name, profilesDir, runtime);
+  return {
+    type: "preset",
+    preset: "claude_code",
+    append: assembleSections({
+      body: persona,
+      protocolParts: [trailer, protocol, amend],
+    }),
+  };
+}
+
+/**
+ * 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.
+ *
+ * @param {object} opts
+ * @param {string} [opts.profile] - Profile basename (no `.md` suffix)
+ * @param {string} [opts.profilesDir] - Directory containing 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`.
+ * @returns {string}
+ */
+export function composeLeadPrompt({
+  profile,
+  profilesDir,
+  trailer,
+  amend,
+  runtime,
+}) {
+  if (!trailer) throw new Error("trailer is required");
+  const { persona, protocol } = profile
+    ? readProfileSections(profile, profilesDir, runtime)
+    : { persona: undefined, protocol: undefined };
+  return assembleSections({
+    body: persona,
+    protocolParts: [trailer, protocol, amend],
+  });
+}
+
+/**
+ * Unified entry point for composing system prompts. Threads an optional
+ * amendment through as the run-specific fragment of `<session_protocol>`
+ * (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;
+ *   `"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`.
+ * @returns {string | {type: "preset", preset: "claude_code", append: string}}
+ */
+export function composeSystemPrompt({
+  role,
+  profile,
+  profilesDir,
+  trailer,
+  amend,
+  runtime,
+}) {
+  if (!trailer) throw new Error("trailer is required");
+  if (role === "lead") {
+    return composeLeadPrompt({ profile, profilesDir, trailer, amend, runtime });
+  }
+  if (profile) {
+    return composeProfilePrompt(profile, {
+      profilesDir,
+      trailer,
+      amend,
+      runtime,
+    });
+  }
+  return {
+    type: "preset",
+    preset: "claude_code",
+    append: assembleSections({ protocolParts: [trailer, amend] }),
+  };
+}
+
+/**
+ * Strip a leading YAML frontmatter fence (`---\n…\n---\n`) from a markdown
+ * string. Returns the input unchanged when no frontmatter is present.
+ * @param {string} raw
+ * @returns {string}
+ */
+function stripFrontmatter(raw) {
+  if (!raw.startsWith("---\n")) return raw;
+  const end = raw.indexOf("\n---\n", 4);
+  if (end === -1) return raw;
+  return raw.slice(end + 5);
+}

package/src/redaction.js

@@ -0,0 +1,253 @@
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * 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.
+ */
+
+export const DEFAULT_ENV_ALLOWLIST = Object.freeze([
+  "ANTHROPIC_API_KEY",
+  "AWS_ACCESS_KEY_ID",
+  "AWS_SECRET_ACCESS_KEY",
+  "DATABASE_PASSWORD",
+  "GH_TOKEN",
+  "GITHUB_TOKEN",
+  "JWT_SECRET",
+  "MCP_TOKEN",
+  "MICROSOFT_APP_ID",
+  "MICROSOFT_APP_PASSWORD",
+  "MICROSOFT_APP_TENANT_ID",
+  "PRODUCT_LANDMARK_TOKEN",
+  "SERVICE_SECRET",
+  "SUPABASE_ANON_KEY",
+  "SUPABASE_SERVICE_ROLE_KEY",
+]);
+
+// 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
+// defence for Anthropic keys.
+export const DEFAULT_PATTERNS = Object.freeze([
+  { kind: "anthropic", regex: /sk-ant-[A-Za-z0-9_-]{80,}/g },
+  { kind: "gh-pat", regex: /\bghp_[A-Za-z0-9]{36}\b/g },
+  { kind: "gh-installation", regex: /\bghs_[A-Za-z0-9]{36}\b/g },
+  { 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.
+  {
+    kind: "gh-b64-basic-credential",
+    regex: /\beC1hY2Nlc3MtdG9rZW46[A-Za-z0-9+/]{8,}={0,2}/g,
+  },
+]);
+
+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.
+ */
+const MIN_ENCODED_SECRET_BYTES = 9;
+
+// Leading base64 chars contaminated by the k filler bytes, 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.
+ * @param {string} secret
+ * @returns {string[]}
+ */
+function encodedNeedles(secret) {
+  if (Buffer.byteLength(secret, "utf8") < MIN_ENCODED_SECRET_BYTES) return [];
+  const needles = [];
+  for (let k = 0; k < 3; k++) {
+    const enc = Buffer.from("\0".repeat(k) + secret, "utf8")
+      .toString("base64")
+      .replace(/=+$/, "");
+    needles.push(enc.slice(ENCODED_LEAD_STRIP[k], enc.length - 4));
+  }
+  return needles;
+}
+
+/**
+ * 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).
+ */
+function snapshotEnv(env, allowlist) {
+  const snap = {};
+  for (const name of allowlist) {
+    const v = env[name];
+    if (typeof v === "string" && v.length > 0) {
+      snap[name] = { secret: v, needles: encodedNeedles(v) };
+    }
+  }
+  return Object.freeze(snap);
+}
+
+/** Recursively walk and redact a JSON-serialisable value in place-free style. */
+function walk(value, redactString) {
+  if (typeof value === "string") return redactString(value);
+  if (Array.isArray(value)) return value.map((v) => walk(v, redactString));
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const k of Object.keys(value)) out[k] = walk(value[k], redactString);
+    return out;
+  }
+  return value;
+}
+
+/** Stateless secret redactor — composes env-allowlist and pattern layers. */
+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 {boolean} deps.enabled - When false, `redactValue` returns its input by reference.
+   */
+  constructor({ envSnapshot, patterns, enabled }) {
+    this.envSnapshot = envSnapshot;
+    this.patterns = patterns;
+    this.enabled = enabled;
+  }
+
+  /**
+   * Redact any JSON-serialisable value by deep-walking and replacing secrets
+   * in every primitive string. Identity on the input when disabled.
+   * @param {unknown} value
+   * @returns {unknown}
+   */
+  redactValue(value) {
+    if (!this.enabled) return value;
+    return walk(value, (s) => this.#redactString(s));
+  }
+
+  /**
+   * Apply the env-allowlist and pattern layers to a single string.
+   * @param {string} s
+   * @returns {string}
+   */
+  #redactString(s) {
+    let out = s;
+    for (const [name, { secret, needles }] of Object.entries(
+      this.envSnapshot,
+    )) {
+      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.
+      for (const needle of needles) {
+        if (out.includes(needle)) {
+          out = out.split(needle).join(ENV_PLACEHOLDER(name));
+        }
+      }
+    }
+    for (const { kind, regex } of this.patterns) {
+      out = out.replace(regex, PATTERN_PLACEHOLDER(kind));
+    }
+    return out;
+  }
+}
+
+/**
+ * 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.
+ * @param {object} [opts]
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} [opts.runtime] - Ambient collaborators; `proc.env`/`proc.stderr` are used.
+ * @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`.
+ * @returns {Redactor}
+ */
+export function createRedactor({
+  runtime,
+  env,
+  allowlist,
+  patterns = DEFAULT_PATTERNS,
+  enabled,
+} = {}) {
+  if (!runtime) throw new Error("runtime is required");
+  const proc = runtime.proc;
+  const resolvedEnv = env ?? proc.env;
+  const envDisabled = resolvedEnv.LIBHARNESS_REDACTION_DISABLED === "1";
+  const resolvedEnabled = enabled ?? !envDisabled;
+  const resolvedAllowlist = allowlist ?? resolveAllowlistFromEnv(resolvedEnv);
+  const envSnapshot = resolvedEnabled
+    ? snapshotEnv(resolvedEnv, resolvedAllowlist)
+    : Object.freeze({});
+  if (!resolvedEnabled) {
+    proc.stderr.write(
+      "libharness: trace redaction DISABLED via LIBHARNESS_REDACTION_DISABLED — secrets may appear in trace artifact\n",
+    );
+  }
+  return new Redactor({ envSnapshot, patterns, enabled: resolvedEnabled });
+}
+
+/**
+ * Parse `LIBHARNESS_REDACTION_ENV_VARS` into a trimmed, non-empty name list.
+ * Falls back to `DEFAULT_ENV_ALLOWLIST` when unset or empty.
+ * @param {Record<string, string|undefined>} env
+ * @returns {string[]}
+ */
+function resolveAllowlistFromEnv(env) {
+  const override = env.LIBHARNESS_REDACTION_ENV_VARS;
+  if (typeof override !== "string" || override.length === 0) {
+    return DEFAULT_ENV_ALLOWLIST;
+  }
+  return override
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+/**
+ * Build a disabled redactor whose `redactValue` is the identity function.
+ * Test-fixture form — bypasses `createRedactor` so no stderr warning
+ * fires regardless of env state.
+ * @returns {Redactor}
+ */
+export function createNoopRedactor() {
+  return new Redactor({
+    envSnapshot: Object.freeze({}),
+    patterns: [],
+    enabled: false,
+  });
+}

package/src/render/line-renderer.js

@@ -0,0 +1,54 @@
+/**
+ * Line renderer — composes prefix + color + body + reset into a single
+ * terminal line. Pure; 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.
+ */
+
+import { colorForSource, ERROR_COLOR, RESET } from "./palette.js";
+
+/**
+ * @param {string|null} source
+ * @param {boolean} withPrefix
+ * @returns {string}
+ */
+function prefix(source, withPrefix) {
+  if (!withPrefix || !source) return "";
+  return `${source}: `;
+}
+
+/**
+ * @param {{source: string|null, text: string, withPrefix: boolean}} args
+ * @returns {string}
+ */
+export function renderTextLine({ source, text, withPrefix }) {
+  const color = colorForSource(source);
+  return `${prefix(source, withPrefix)}${color}${text}${RESET}\n`;
+}
+
+/**
+ * @param {{source: string|null, toolName: string, hint: string, withPrefix: boolean}} args
+ * @returns {string}
+ */
+export function renderToolCallLine({ source, toolName, hint, withPrefix }) {
+  const color = colorForSource(source);
+  const body = hint ? `${toolName}: ${hint}` : `${toolName}`;
+  return `${prefix(source, withPrefix)}${color}${body}${RESET}\n`;
+}
+
+/**
+ * @param {{source: string|null, preview: {text: string, isError: boolean}, withPrefix: boolean}} args
+ * @returns {string}
+ */
+export function renderToolResultLine({ source, preview, withPrefix }) {
+  const color = preview.isError ? ERROR_COLOR : colorForSource(source);
+  const label = preview.isError ? "Error" : "Result";
+  const body = `${label}: ${preview.text}`;
+  return `${prefix(source, withPrefix)}${color}${body}${RESET}\n`;
+}

package/src/render/orchestrator-filter.js

@@ -0,0 +1,19 @@
+/**
+ * Orchestrator filter — predicate for the orchestrator lifecycle events that
+ * should be suppressed from the human-readable log.
+ *
+ * NDJSON artifacts still carry every orchestrator event; this module only
+ * controls what the live `textStream` and offline `toText()` show.
+ */
+
+const SUPPRESSED = new Set(["session_start", "agent_start", "summary", "meta"]);
+
+/**
+ * @param {{type?: string}|null|undefined} event
+ * @returns {boolean} true when the event's type is one we hide from text output
+ */
+export function isSuppressedOrchestratorEvent(event) {
+  return Boolean(
+    event && typeof event === "object" && SUPPRESSED.has(event.type),
+  );
+}

package/src/render/palette.js

@@ -0,0 +1,63 @@
+/**
+ * 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.
+ *
+ * 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
+ * mustard/olive tones GHA applies to `ESC[93m` etc. Eight slots cover the
+ * largest concurrent cast in any existing workflow (five domain agents plus
+ * the facilitator) with headroom.
+ */
+
+const PALETTE = [
+  "\u001b[38;2;79;195;247m", // sky blue    #4FC3F7
+  "\u001b[38;2;129;199;132m", // bright green #81C784
+  "\u001b[38;2;255;202;40m", // amber       #FFCA28
+  "\u001b[38;2;236;64;122m", // magenta     #EC407A
+  "\u001b[38;2;38;198;218m", // cyan        #26C6DA
+  "\u001b[38;2;186;104;200m", // lavender    #BA68C8
+  "\u001b[38;2;255;167;38m", // orange      #FFA726
+  "\u001b[38;2;66;165;245m", // blue        #42A5F5
+];
+
+/** 24-bit SGR foreground code reserved for tool-result errors (#F14C4C). */
+export const ERROR_COLOR = "\u001b[38;2;241;76;76m";
+
+/** ANSI SGR reset sequence. */
+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.
+ *
+ * @param {string|null|undefined} name
+ * @returns {string} ANSI SGR escape, never equal to `ERROR_COLOR`
+ */
+export function colorForSource(name) {
+  if (!name) return RESET;
+  let h = 0x811c9dc5;
+  for (let i = 0; i < name.length; i++) {
+    h ^= name.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  // Length mixer: 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;
+  return PALETTE[h % PALETTE.length];
+}
+
+/**
+ * Expose the palette size so tests can assert distinctness on the full set.
+ * @returns {number}
+ */
+export function paletteSize() {
+  return PALETTE.length;
+}