@forwardimpact/libeval 0.1.17 → 0.1.19

package/bin/fit-trace.js

@@ -2,6 +2,7 @@
 
 import { readFileSync } from "node:fs";
 import { createCli } from "@forwardimpact/libcli";
+import { createScriptConfig } from "@forwardimpact/libconfig";
 import { createLogger } from "@forwardimpact/libtelemetry";
 
 import {
@@ -188,7 +189,8 @@ async function main() {
     process.exit(2);
   }
 
-  await handler(values, args);
+  const config = await createScriptConfig("eval");
+  await handler(values, args, { config });
 }
 
 main().catch((error) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libeval",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "Process Claude Code stream-json output into structured traces",
   "license": "Apache-2.0",
   "author": "D. Olsson <hi@senzilla.io>",

package/src/agent-runner.js

@@ -8,6 +8,11 @@
 
 const DEFAULT_ALLOWED_TOOLS = ["Bash", "Read", "Glob", "Grep", "Write", "Edit"];
 
+// fit-eval and kata-action run headless in CI/CD with no human to answer
+// permission prompts. The SDK is always launched in bypass mode — not
+// overridable — so a future caller can't accidentally reduce permissions.
+const PERMISSION_MODE = "bypassPermissions";
+
 function applyDefaults(deps) {
   return {
     cwd: deps.cwd,
@@ -16,12 +21,10 @@ function applyDefaults(deps) {
     model: deps.model ?? "opus",
     maxTurns: deps.maxTurns ?? 50,
     allowedTools: deps.allowedTools ?? DEFAULT_ALLOWED_TOOLS,
-    permissionMode: deps.permissionMode ?? "bypassPermissions",
     onLine: deps.onLine ?? null,
     onBatch: deps.onBatch ?? null,
     batchSize: deps.batchSize ?? 3,
     settingSources: deps.settingSources ?? [],
-    agentProfile: deps.agentProfile ?? null,
     systemPrompt: deps.systemPrompt ?? null,
     disallowedTools: deps.disallowedTools ?? [],
     mcpServers: deps.mcpServers ?? null,
@@ -37,12 +40,10 @@ export class AgentRunner {
    * @param {string} [deps.model] - Claude model identifier
    * @param {number} [deps.maxTurns] - Maximum agentic turns
    * @param {string[]} [deps.allowedTools] - Tools the agent may use
-   * @param {string} [deps.permissionMode] - SDK permission mode
    * @param {function} [deps.onLine] - Callback invoked with each NDJSON line as it's produced
    * @param {function} [deps.onBatch] - Async callback invoked with a batch of NDJSON lines at flush boundaries: every `batchSize` assistant text blocks, the terminal `result` message, and — on iterator crash/abort — once more in a final flush carrying any lines that never reached a boundary. Receives `(lines, { abort })` where calling `abort()` stops the in-flight SDK session via the AbortController. Optional; assignable at runtime so the Supervisor can swap it per turn.
    * @param {number} [deps.batchSize] - Assistant text-block messages to accumulate before firing onBatch. Tool-only assistant messages ride along without counting. Default 3: the supervisor reviews the agent every three text turns instead of every turn. The terminal `result` always flushes regardless of count.
    * @param {string[]} [deps.settingSources] - SDK setting sources (e.g. ['project'] to load CLAUDE.md)
-   * @param {string} [deps.agentProfile] - Agent profile name to pass as --agent to the Claude CLI
    * @param {string|object} [deps.systemPrompt] - SDK system prompt (string replaces default; {type:'preset', preset:'claude_code', append} appends)
    * @param {string[]} [deps.disallowedTools] - Tools to explicitly remove from the model's context
    * @param {Record<string, object>} [deps.mcpServers] - MCP server configs to pass to the SDK query
@@ -74,7 +75,7 @@ export class AgentRunner {
           allowedTools: this.allowedTools,
           ...(this.maxTurns > 0 && { maxTurns: this.maxTurns }),
           model: this.model,
-          permissionMode: this.permissionMode,
+          permissionMode: PERMISSION_MODE,
           allowDangerouslySkipPermissions: true,
           settingSources: this.settingSources,
           abortController,
@@ -82,7 +83,6 @@ export class AgentRunner {
             disallowedTools: this.disallowedTools,
           }),
           ...(this.systemPrompt && { systemPrompt: this.systemPrompt }),
-          ...(this.agentProfile && { extraArgs: { agent: this.agentProfile } }),
           ...(this.mcpServers && { mcpServers: this.mcpServers }),
         },
       });
@@ -105,7 +105,7 @@ export class AgentRunner {
         prompt,
         options: {
           resume: this.sessionId,
-          permissionMode: this.permissionMode,
+          permissionMode: PERMISSION_MODE,
           allowDangerouslySkipPermissions: true,
           abortController,
           ...(this.mcpServers && { mcpServers: this.mcpServers }),

package/src/commands/run.js

@@ -2,6 +2,7 @@ import { readFileSync, createWriteStream } from "node:fs";
 import { Writable } from "node:stream";
 import { resolve } from "node:path";
 import { createAgentRunner } from "../agent-runner.js";
+import { composeProfilePrompt } from "../profile-prompt.js";
 import { createTeeWriter } from "../tee-writer.js";
 import { SequenceCounter } from "../sequence-counter.js";
 
@@ -76,6 +77,12 @@ export async function runRunCommand(values, _args) {
     );
   };
 
+  const systemPrompt = agentProfile
+    ? composeProfilePrompt(agentProfile, {
+        profilesDir: resolve(cwd, ".claude/agents"),
+      })
+    : undefined;
+
   const { query } = await import("@anthropic-ai/claude-agent-sdk");
   const runner = createAgentRunner({
     cwd,
@@ -86,7 +93,7 @@ export async function runRunCommand(values, _args) {
     allowedTools,
     onLine,
     settingSources: ["project"],
-    agentProfile,
+    systemPrompt,
   });
 
   const result = await runner.run(taskContent);

package/src/commands/trace.js

@@ -10,9 +10,13 @@ import { createTraceGitHub } from "../trace-github.js";
  * List recent workflow runs matching a pattern.
  * @param {object} values - Parsed option values
  * @param {string[]} args - [pattern?]
+ * @param {{config: import("@forwardimpact/libconfig").Config}} ctx
  */
-export async function runRunsCommand(values, args) {
-  const gh = await createTraceGitHub({ repo: values.repo });
+export async function runRunsCommand(values, args, ctx) {
+  const gh = await createTraceGitHub({
+    token: ctx.config.ghToken(),
+    repo: values.repo,
+  });
   const pattern = args[0] ?? "agent";
   const lookback = values.lookback ?? "7d";
   const runs = await gh.listRuns({ pattern, lookback });
@@ -23,9 +27,13 @@ export async function runRunsCommand(values, args) {
  * Download a trace artifact and auto-convert to structured JSON.
  * @param {object} values - Parsed option values
  * @param {string[]} args - [run-id]
+ * @param {{config: import("@forwardimpact/libconfig").Config}} ctx
  */
-export async function runDownloadCommand(values, args) {
-  const gh = await createTraceGitHub({ repo: values.repo });
+export async function runDownloadCommand(values, args, ctx) {
+  const gh = await createTraceGitHub({
+    token: ctx.config.ghToken(),
+    repo: values.repo,
+  });
   const result = await gh.downloadTrace(args[0], {
     dir: values.dir,
     name: values.artifact,

package/src/facilitator.js

@@ -7,7 +7,9 @@
  */
 
 import { Writable } from "node:stream";
+import { resolve } from "node:path";
 import { createAgentRunner } from "./agent-runner.js";
+import { composeProfilePrompt } from "./profile-prompt.js";
 import { SequenceCounter } from "./sequence-counter.js";
 import { createMessageBus } from "./message-bus.js";
 import {
@@ -415,7 +417,8 @@ const devNull = new Writable({
  * @param {import("stream").Writable} deps.output
  * @param {string} [deps.model]
  * @param {number} [deps.maxTurns]
- * @param {string} [deps.facilitatorProfile]
+ * @param {string} [deps.facilitatorProfile] - Facilitator profile name; resolved into the main-thread system prompt via `composeProfilePrompt`.
+ * @param {string} [deps.profilesDir] - Directory containing `<name>.md` profile files. Defaults to `<facilitatorCwd>/.claude/agents`. Resolved once from the facilitator's cwd so profiles travel with the project, not with per-agent sandboxes.
  * @returns {Facilitator}
  */
 export function createFacilitator({
@@ -426,7 +429,19 @@ export function createFacilitator({
   model,
   maxTurns,
   facilitatorProfile,
+  profilesDir,
 }) {
+  const resolvedProfilesDir =
+    profilesDir ?? resolve(facilitatorCwd, ".claude/agents");
+  const systemPromptFor = (profile, trailer) => {
+    if (!trailer) throw new Error("trailer is required");
+    return profile
+      ? composeProfilePrompt(profile, {
+          profilesDir: resolvedProfilesDir,
+          trailer,
+        })
+      : { type: "preset", preset: "claude_code", append: trailer };
+  };
   const ctx = createOrchestrationContext();
   const messageBus = createMessageBus({
     participants: ["facilitator", ...agentConfigs.map((a) => a.name)],
@@ -471,12 +486,10 @@ export function createFacilitator({
       onLine: (line) => facilitator.emitLine(config.name, line),
       mcpServers: { orchestration: agentServer },
       settingSources: ["project"],
-      agentProfile: config.agentProfile,
-      systemPrompt: {
-        type: "preset",
-        preset: "claude_code",
-        append: FACILITATED_AGENT_SYSTEM_PROMPT,
-      },
+      systemPrompt: systemPromptFor(
+        config.agentProfile,
+        FACILITATED_AGENT_SYSTEM_PROMPT,
+      ),
     });
 
     return { name: config.name, role: config.role, runner };
@@ -491,12 +504,10 @@ export function createFacilitator({
     onLine: (line) => facilitator.emitLine("facilitator", line),
     mcpServers: { orchestration: facilitatorServer },
     settingSources: ["project"],
-    agentProfile: facilitatorProfile,
-    systemPrompt: {
-      type: "preset",
-      preset: "claude_code",
-      append: FACILITATOR_SYSTEM_PROMPT,
-    },
+    systemPrompt: systemPromptFor(
+      facilitatorProfile,
+      FACILITATOR_SYSTEM_PROMPT,
+    ),
   });
 
   facilitator = new Facilitator({

package/src/index.js

@@ -6,6 +6,7 @@ export {
   parseGitRemote,
 } from "./trace-github.js";
 export { AgentRunner, createAgentRunner } from "./agent-runner.js";
+export { composeProfilePrompt } from "./profile-prompt.js";
 export {
   Supervisor,
   createSupervisor,

package/src/profile-prompt.js

@@ -0,0 +1,41 @@
+/**
+ * Compose an SDK `systemPrompt` value from a `.claude/agents/<name>.md` file.
+ *
+ * Pure function. Reads the profile file, strips YAML frontmatter, and returns
+ * the SDK-shaped `{ type: "preset", preset: "claude_code", append }` object
+ * with the profile body — plus an optional mode-specific trailer — in the
+ * `append` slot. Callers in libeval pass the result straight into an
+ * `AgentRunner`'s `systemPrompt` input so the profile reaches the main-thread
+ * system prompt without going through the SDK's top-level `agent` option.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * @param {string} name - Profile basename (no `.md` suffix)
+ * @param {object} opts
+ * @param {string} opts.profilesDir - Directory containing `<name>.md`
+ * @param {string} [opts.trailer] - Optional mode-specific trailer appended after a blank line
+ * @returns {{type: "preset", preset: "claude_code", append: string}}
+ */
+export function composeProfilePrompt(name, { profilesDir, trailer }) {
+  const path = join(profilesDir, `${name}.md`);
+  const raw = readFileSync(path, "utf8");
+  const body = stripFrontmatter(raw).trim();
+  const append = trailer && trailer.length > 0 ? `${body}\n\n${trailer}` : body;
+  return { type: "preset", preset: "claude_code", append };
+}
+
+/**
+ * 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/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,26 @@
+/**
+ * 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",
+  "ask_received",
+  "ask_answered",
+  "redirect",
+  "summary",
+]);
+
+/**
+ * @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;
+}

package/src/render/tool-hints.js

@@ -0,0 +1,185 @@
+/**
+ * Tool hints — pure one-line formatters for tool-call arguments and
+ * 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.
+ *
+ * `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.
+ */
+
+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
+ * string, never null/undefined.
+ * @param {unknown} raw
+ * @returns {string}
+ */
+function sanitize(raw) {
+  if (raw === null || raw === undefined) return "";
+  const str = String(raw);
+  const firstLine = str.split(/\r?\n/)[0] ?? "";
+  const stripped = firstLine.replace(/[{}"]/g, "");
+  const collapsed = stripped.replace(/\s+/g, " ").trim();
+  if (collapsed.length <= MAX_HINT_CHARS) return collapsed;
+  return collapsed.slice(0, MAX_HINT_CHARS - 3) + "...";
+}
+
+/**
+ * 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.
+ * @param {string} str
+ * @returns {string}
+ */
+function truncate(str) {
+  return str.length <= MAX_HINT_CHARS
+    ? str
+    : str.slice(0, MAX_HINT_CHARS - 3) + "...";
+}
+
+/**
+ * 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.
+ */
+const HINT_HANDLERS = {
+  Bash: (i) => sanitize(i.command),
+  Read: (i) => sanitize(i.file_path),
+  Write: (i) => sanitize(i.file_path),
+  Edit: (i) => {
+    const base = sanitize(i.file_path);
+    return i.replace_all
+      ? (base + " (replace_all)").slice(0, MAX_HINT_CHARS)
+      : base;
+  },
+  Glob: (i) => sanitize(i.pattern),
+  Grep: (i) => {
+    const pattern = sanitize(i.pattern);
+    return i.path ? truncate(`${pattern} in ${sanitize(i.path)}`) : pattern;
+  },
+  WebFetch: (i) => sanitize(i.url),
+  WebSearch: (i) => sanitize(i.query),
+  ToolSearch: (i) => sanitize(i.query),
+  TodoWrite: (i) => {
+    const count = Array.isArray(i.todos) ? i.todos.length : 0;
+    return `${count} todos`;
+  },
+  NotebookEdit: (i) => sanitize(i.notebook_path),
+  Skill: (i) => sanitize(i.skill),
+  Agent: (i) => sanitize(i.prompt ?? i.description),
+  Task: (i) => sanitize(i.prompt ?? i.description),
+};
+
+/**
+ * Strip the `mcp__<server>__` prefix from MCP-namespaced tool names so logs
+ * show the bare method (e.g. `mcp__orchestration__Tell` → `Tell`). Non-MCP
+ * names and malformed inputs pass through unchanged.
+ * @param {string} name
+ * @returns {string}
+ */
+export function simplifyToolName(name) {
+  if (!name) return "";
+  if (!name.startsWith("mcp__")) return name;
+  const parts = name.split("__");
+  if (parts.length < 3) return name;
+  return parts.slice(2).join("__");
+}
+
+/**
+ * MCP-prefixed tool names (e.g. `mcp__orchestration__Tell`) take a different
+ * handler path. The method name itself is surfaced via `simplifyToolName`,
+ * so this only adds the `to/from` decorators for orchestration calls.
+ * Returns null if the name does not match any MCP prefix.
+ * @param {string} name
+ * @param {object} input
+ * @returns {string|null}
+ */
+function hintForMcp(name, input) {
+  if (name.startsWith("mcp__orchestration__")) {
+    const parts = [];
+    if (input.to) parts.push(`to ${sanitize(input.to)}`);
+    if (input.from) parts.push(`from ${sanitize(input.from)}`);
+    return truncate(parts.join(" "));
+  }
+  if (name.startsWith("mcp__")) {
+    return "";
+  }
+  return null;
+}
+
+/**
+ * Map a tool name and input to a one-line human hint.
+ *
+ * Unknown tools return an empty hint — the caller still shows the tool
+ * name, just without extra detail. Sanitization is uniform: every branch
+ * ends with `sanitize`, so the output is guaranteed free of `{`, `}`, `"`
+ * from the input object (success criterion #2).
+ *
+ * @param {string} name - Tool name (e.g. "Bash", "Read", "mcp__orchestration__Tell")
+ * @param {object|null|undefined} input - Raw tool input object from the trace
+ * @returns {string} One-line hint, or "" when no rule matches
+ */
+export function hintForCall(name, input) {
+  if (!name) return "";
+  const safeInput = input && typeof input === "object" ? input : {};
+
+  const handler = HINT_HANDLERS[name];
+  if (handler) return handler(safeInput);
+
+  const mcp = hintForMcp(name, safeInput);
+  if (mcp !== null) return mcp;
+
+  return "";
+}
+
+/**
+ * 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.
+ *
+ * @param {string|object|null|undefined} content - Tool result content
+ * @param {boolean} isError - Whether the tool call failed
+ * @returns {{text: string, isError: boolean}}
+ */
+export function previewForResult(content, isError) {
+  const normalized =
+    content === null || content === undefined
+      ? ""
+      : typeof content === "string"
+        ? content
+        : JSON.stringify(content);
+  const lines = normalized.split(/\r?\n/);
+  let firstNonBlank = "";
+  for (const line of lines) {
+    if (line.trim().length > 0) {
+      firstNonBlank = line.trim();
+      break;
+    }
+  }
+
+  if (isError) {
+    const body = firstNonBlank || "(no output)";
+    return {
+      text:
+        body.length <= MAX_HINT_CHARS
+          ? body
+          : body.slice(0, MAX_HINT_CHARS - 3) + "...",
+      isError: true,
+    };
+  }
+
+  if (!firstNonBlank) return { text: "(ok)", isError: false };
+  return {
+    text:
+      firstNonBlank.length <= MAX_HINT_CHARS
+        ? firstNonBlank
+        : firstNonBlank.slice(0, MAX_HINT_CHARS - 3) + "...",
+    isError: false,
+  };
+}

package/src/supervisor.js

@@ -11,7 +11,9 @@
  */
 
 import { Writable } from "node:stream";
+import { resolve } from "node:path";
 import { createAgentRunner } from "./agent-runner.js";
+import { composeProfilePrompt } from "./profile-prompt.js";
 import { TraceCollector } from "./trace-collector.js";
 import { SequenceCounter } from "./sequence-counter.js";
 import {
@@ -355,8 +357,9 @@ const devNull = new Writable({
  * @param {string[]} [deps.allowedTools]
  * @param {string[]} [deps.supervisorAllowedTools]
  * @param {string[]} [deps.supervisorDisallowedTools]
- * @param {string} [deps.supervisorProfile]
- * @param {string} [deps.agentProfile]
+ * @param {string} [deps.supervisorProfile] - Supervisor profile name; resolved into the main-thread system prompt via `composeProfilePrompt`.
+ * @param {string} [deps.agentProfile] - Agent profile name; resolved into the main-thread system prompt via `composeProfilePrompt`.
+ * @param {string} [deps.profilesDir] - Directory containing `<name>.md` profile files. Defaults to `<supervisorCwd>/.claude/agents`. Resolved once from the orchestrator's cwd so profiles travel with the project, not with a per-agent sandbox.
  * @returns {Supervisor}
  */
 export function createSupervisor({
@@ -371,7 +374,19 @@ export function createSupervisor({
   supervisorAllowedTools,
   supervisorProfile,
   agentProfile,
+  profilesDir,
 }) {
+  const resolvedProfilesDir =
+    profilesDir ?? resolve(supervisorCwd, ".claude/agents");
+  const systemPromptFor = (profile, trailer) => {
+    if (!trailer) throw new Error("trailer is required");
+    return profile
+      ? composeProfilePrompt(profile, {
+          profilesDir: resolvedProfilesDir,
+          trailer,
+        })
+      : { type: "preset", preset: "claude_code", append: trailer };
+  };
   let supervisor;
   let supervisorRunner;
 
@@ -402,12 +417,7 @@ export function createSupervisor({
     allowedTools,
     onLine,
     settingSources: ["project"],
-    agentProfile,
-    systemPrompt: {
-      type: "preset",
-      preset: "claude_code",
-      append: AGENT_SYSTEM_PROMPT,
-    },
+    systemPrompt: systemPromptFor(agentProfile, AGENT_SYSTEM_PROMPT),
     mcpServers: { orchestration: agentServer },
   });
 
@@ -433,12 +443,7 @@ export function createSupervisor({
     disallowedTools,
     onLine,
     settingSources: ["project"],
-    agentProfile: supervisorProfile,
-    systemPrompt: {
-      type: "preset",
-      preset: "claude_code",
-      append: SUPERVISOR_SYSTEM_PROMPT,
-    },
+    systemPrompt: systemPromptFor(supervisorProfile, SUPERVISOR_SYSTEM_PROMPT),
     mcpServers: { orchestration: supervisorServer },
   });
 

package/src/tee-writer.js

@@ -7,11 +7,27 @@
  * parameter controls display formatting: multi-participant modes show
  * source labels on content lines.
  *
+ * Human text rendering is delegated to the pure modules under `./render/`
+ * so the live stream and the offline `TraceCollector.toText()` replay share
+ * one formatting path (spec 540). The NDJSON going to `fileStream` is
+ * untouched — only what reaches `textStream` changes.
+ *
  * Follows OO+DI: constructor injection, factory function, tests bypass factory.
  */
 
 import { Writable } from "node:stream";
 import { TraceCollector } from "./trace-collector.js";
+import {
+  renderTextLine,
+  renderToolCallLine,
+  renderToolResultLine,
+} from "./render/line-renderer.js";
+import {
+  hintForCall,
+  previewForResult,
+  simplifyToolName,
+} from "./render/tool-hints.js";
+import { isSuppressedOrchestratorEvent } from "./render/orchestrator-filter.js";
 
 export class TeeWriter extends Writable {
   /**
@@ -29,8 +45,6 @@ export class TeeWriter extends Writable {
     this.mode = mode ?? "raw";
     this.collector = new TraceCollector();
     this.turnsEmitted = 0;
-    this.lastSource = null;
-    this.partial = "";
   }
 
   /**
@@ -39,7 +53,7 @@ export class TeeWriter extends Writable {
    * @param {function} callback
    */
   _write(chunk, encoding, callback) {
-    const str = this.partial + chunk.toString();
+    const str = (this.partial ?? "") + chunk.toString();
     const lines = str.split("\n");
     this.partial = lines.pop() ?? "";
 
@@ -55,16 +69,25 @@ export class TeeWriter extends Writable {
    * @param {function} callback
    */
   _final(callback) {
-    if (this.partial.trim()) {
+    if (this.partial && this.partial.trim()) {
       this.fileStream.write(this.partial + "\n");
       this.processLine(this.partial);
     }
 
-    if (this.mode === "raw" && this.collector.result) {
+    // Emit the trailing `--- Result: ... ---` footer — the one summary line
+    // humans want (spec 540). This is the same tail TraceCollector.toText()
+    // appends, so the live stream and the offline replay stay in sync
+    // (spec 540 criterion #6). The superseded `--- Evaluation ... ---`
+    // footer is gone in every mode.
+    if (this.collector.result) {
       const text = this.collector.toText();
       const idx = text.lastIndexOf("\n---");
       if (idx !== -1) {
-        this.textStream.write(text.slice(idx) + "\n");
+        // Slice past the leading `\n` — the previously-streamed body
+        // already ended with its own newline, so re-emitting `\n---` here
+        // would produce a blank line before the footer and desync from
+        // the offline replay (spec 540 #6).
+        this.textStream.write(text.slice(idx + 1) + "\n");
       }
     }
 
@@ -85,19 +108,15 @@ export class TeeWriter extends Writable {
 
     // Universal envelope: { source, seq, event }
     if (parsed.event) {
-      // Orchestrator summary event
-      if (parsed.source === "orchestrator" && parsed.event.type === "summary") {
-        const status = parsed.event.success ? "completed" : "incomplete";
-        this.textStream.write(
-          `\n--- Evaluation ${status} after ${parsed.event.turns} turns ---\n`,
-        );
+      // Orchestrator lifecycle events are suppressed from the text stream
+      // entirely (spec 540). They still reached fileStream above.
+      if (
+        parsed.source === "orchestrator" &&
+        isSuppressedOrchestratorEvent(parsed.event)
+      ) {
         return;
       }
-
-      if (parsed.source && parsed.source !== this.lastSource) {
-        this.lastSource = parsed.source;
-      }
-      this.collector.addLine(JSON.stringify(parsed.event));
+      this.collector.addLine(line);
       this.flushTurns();
       return;
     }
@@ -112,38 +131,43 @@ export class TeeWriter extends Writable {
    */
   flushTurns() {
     const turns = this.collector.turns;
-    const prefix =
-      this.mode === "supervised" && this.lastSource
-        ? `[${this.lastSource}] `
-        : "";
+    const withPrefix = this.mode !== "raw";
     while (this.turnsEmitted < turns.length) {
       const turn = turns[this.turnsEmitted++];
       if (turn.role === "assistant") {
         for (const block of turn.content) {
           if (block.type === "text") {
-            this.textStream.write(`${prefix}${block.text}\n`);
+            this.textStream.write(
+              renderTextLine({
+                source: turn.source,
+                text: block.text,
+                withPrefix,
+              }),
+            );
           } else if (block.type === "tool_use") {
-            const input = summarizeInput(block.input);
-            this.textStream.write(`${prefix}> Tool: ${block.name} ${input}\n`);
+            this.textStream.write(
+              renderToolCallLine({
+                source: turn.source,
+                toolName: simplifyToolName(block.name),
+                hint: hintForCall(block.name, block.input),
+                withPrefix,
+              }),
+            );
           }
         }
+      } else if (turn.role === "tool_result") {
+        this.textStream.write(
+          renderToolResultLine({
+            source: turn.source,
+            preview: previewForResult(turn.content, turn.isError),
+            withPrefix,
+          }),
+        );
       }
     }
   }
 }
 
-/**
- * Summarize tool input for text display, truncated to keep logs readable.
- * @param {object} input - Tool input object
- * @returns {string} Truncated summary
- */
-function summarizeInput(input) {
-  if (!input || typeof input !== "object") return "";
-  const json = JSON.stringify(input);
-  if (json.length <= 200) return json;
-  return json.slice(0, 197) + "...";
-}
-
 /**
  * Factory function — wires a TeeWriter with the given streams.
  * @param {object} deps - Same as TeeWriter constructor

package/src/trace-collector.js

@@ -3,7 +3,24 @@
  *
  * Accepts one NDJSON line at a time via addLine(), then produces either a
  * structured JSON trace (toJSON) or human-readable text (toText).
+ *
+ * Human text rendering is delegated to the pure modules under `./render/`
+ * so the live `TeeWriter` stream and the offline `toText()` replay share
+ * one formatting path (spec 540).
  */
+
+import {
+  renderTextLine,
+  renderToolCallLine,
+  renderToolResultLine,
+} from "./render/line-renderer.js";
+import {
+  hintForCall,
+  previewForResult,
+  simplifyToolName,
+} from "./render/tool-hints.js";
+import { isSuppressedOrchestratorEvent } from "./render/orchestrator-filter.js";
+
 export class TraceCollector {
   /**
    * @param {object} [deps]
@@ -38,22 +55,31 @@ export class TraceCollector {
       return;
     }
 
-    // Unwrap combined supervised trace format {source, turn, event}.
-    // The Supervisor emits this wrapper; when replayed through addLine the
-    // inner event is the one we need.
+    // Unwrap combined supervised trace format {source, seq, event}. The
+    // Supervisor / Facilitator emits this wrapper; when replayed through
+    // addLine the inner event is the one we care about. Carry the envelope
+    // `source` onto each new turn so the renderer can color it correctly.
+    let source = null;
     if (event.event && !event.type && typeof event.source === "string") {
+      source = event.source;
       event = event.event;
     }
 
+    // Orchestrator lifecycle events carry no content and are suppressed
+    // from turns entirely — the NDJSON artifact keeps them separately.
+    if (source === "orchestrator" && isSuppressedOrchestratorEvent(event)) {
+      return;
+    }
+
     switch (event.type) {
       case "system":
         this.handleSystem(event);
         break;
       case "assistant":
-        this.handleAssistant(event);
+        this.handleAssistant(event, source);
         break;
       case "user":
-        this.handleUser(event);
+        this.handleUser(event, source);
         break;
       case "result":
         this.handleResult(event);
@@ -81,8 +107,9 @@ export class TraceCollector {
 
   /**
    * @param {object} event
+   * @param {string|null} source
    */
-  handleAssistant(event) {
+  handleAssistant(event, source) {
     const message = event.message;
     if (!message) return;
 
@@ -114,6 +141,7 @@ export class TraceCollector {
     this.turns.push({
       index: this.turnIndex++,
       role: "assistant",
+      source,
       content,
       usage,
     });
@@ -121,8 +149,9 @@ export class TraceCollector {
 
   /**
    * @param {object} event
+   * @param {string|null} source
    */
-  handleUser(event) {
+  handleUser(event, source) {
     const message = event.message;
     if (!message) return;
 
@@ -134,6 +163,7 @@ export class TraceCollector {
         this.turns.push({
           index: this.turnIndex++,
           role: "tool_result",
+          source,
           toolUseId: item.tool_use_id ?? null,
           content:
             typeof item.content === "string"
@@ -197,50 +227,73 @@ export class TraceCollector {
   }
 
   /**
-   * Return human-readable text for workflow logs.
-   * @returns {string} Formatted text output
+   * Render the accumulated turns as human-readable text — the same path the
+   * live `TeeWriter` stream uses, so `fit-eval output --format=text` over a
+   * captured trace reproduces what the live workflow log showed.
+   *
+   * Source prefixes are emitted whenever at least one turn has a non-null
+   * source (supervised / facilitated traces). A pure `run` trace has no
+   * envelope, all turn sources are null, and the renderer drops the prefix.
+   *
+   * @returns {string} Formatted text output including ANSI escapes
    */
   toText() {
-    const lines = [];
+    const withPrefix = this.turns.some((t) => t.source);
+    const out = [];
 
     for (const turn of this.turns) {
       if (turn.role === "assistant") {
         for (const block of turn.content) {
           if (block.type === "text") {
-            lines.push(block.text);
+            out.push(
+              renderTextLine({
+                source: turn.source,
+                text: block.text,
+                withPrefix,
+              }),
+            );
           } else if (block.type === "tool_use") {
-            const inputSummary = summarizeInput(block.input);
-            lines.push(`> Tool: ${block.name} ${inputSummary}`);
+            out.push(
+              renderToolCallLine({
+                source: turn.source,
+                toolName: simplifyToolName(block.name),
+                hint: hintForCall(block.name, block.input),
+                withPrefix,
+              }),
+            );
           }
         }
+      } else if (turn.role === "tool_result") {
+        out.push(
+          renderToolResultLine({
+            source: turn.source,
+            preview: previewForResult(turn.content, turn.isError),
+            withPrefix,
+          }),
+        );
       }
     }
 
+    // Trailing result block — the one summary line humans want (spec 540).
+    let tail = "";
     if (this.result) {
       const duration = formatDuration(this.result.durationMs);
       const cost = Number(this.result.totalCostUsd).toFixed(4);
-      lines.push("");
-      lines.push(
-        `--- Result: ${this.result.result} | Turns: ${this.result.numTurns} | Cost: $${cost} | Duration: ${duration} ---`,
-      );
+      tail =
+        "\n" +
+        `--- Result: ${this.result.result} | Turns: ${this.result.numTurns} | Cost: $${cost} | Duration: ${duration} ---`;
     }
 
-    return lines.join("\n");
+    // Each rendered line already ends with `\n`; concatenate, drop the
+    // trailing newline, then append the tail so the output shape stays
+    // compatible with existing consumers (no double-blank line before
+    // the result footer when there are turns, no leading blank when there
+    // are not).
+    const body = out.join("").replace(/\n$/, "");
+    return body + tail;
   }
 }
 
-/**
- * Summarize tool input for text display, truncated to keep logs readable.
- * @param {object} input - Tool input object
- * @returns {string} Truncated summary
- */
-function summarizeInput(input) {
-  if (!input || typeof input !== "object") return "";
-  const json = JSON.stringify(input);
-  if (json.length <= 200) return json;
-  return json.slice(0, 197) + "...";
-}
-
 /**
  * Format milliseconds into a human-readable duration.
  * @param {number} ms - Duration in milliseconds

package/src/trace-github.js

@@ -186,21 +186,30 @@ export function parseGitRemote(remote) {
 }
 
 /**
- * Create a TraceGitHub instance using libconfig for the token and
- * git remote for the repo.
+ * Create a TraceGitHub instance. The caller is responsible for resolving
+ * the GitHub token — typically via `Config.ghToken()` — so credential
+ * loading stays at the CLI entry point.
  *
- * @param {object} [opts]
+ * Breaking change from the prior signature: `token` is now a required
+ * caller input. Construct a `Config` via `@forwardimpact/libconfig` and
+ * pass `config.ghToken()`.
+ *
+ * @param {object} opts
+ * @param {string} opts.token - GitHub token (e.g. from `Config.ghToken()`)
  * @param {string} [opts.repo] - "owner/repo" override (default: detect from git remote)
  * @returns {Promise<TraceGitHub>}
  */
 export async function createTraceGitHub(opts = {}) {
-  const { createScriptConfig } = await import("@forwardimpact/libconfig");
-  const config = await createScriptConfig("eval");
-  const token = config.ghToken();
+  const { token, repo: repoOverride } = opts;
+  if (!token) {
+    throw new Error(
+      "createTraceGitHub: token is required (pass Config.ghToken())",
+    );
+  }
 
   let owner, repo;
-  if (opts.repo) {
-    ({ owner, repo } = parseGitRemote(opts.repo));
+  if (repoOverride) {
+    ({ owner, repo } = parseGitRemote(repoOverride));
   } else {
     const { execSync } = await import("node:child_process");
     const remote = execSync("git remote get-url origin", {