@forwardimpact/libharness 0.1.22 → 1.0.0

package/src/commands/discuss.js

@@ -0,0 +1,132 @@
+import { resolve } from "node:path";
+import { isoTimestamp } from "@forwardimpact/libutil";
+import { createDiscusser } from "../discusser.js";
+import { createRedactor } from "../redaction.js";
+import { createTeeWriter } from "../tee-writer.js";
+import { resolveTaskContent } from "./task-input.js";
+import { resolveWorkTracker } from "./work-tracker.js";
+import { AGENT_MODEL, LEAD_MODEL } from "@forwardimpact/libutil/models";
+
+function parseAgentProfiles(raw, cwd, maxTurns) {
+  if (!raw) return [];
+  return raw.split(",").map((entry) => {
+    const name = entry.trim();
+    return { name, role: name, cwd, agentProfile: name, maxTurns };
+  });
+}
+
+/**
+ * Parse and validate discuss command options. Exported so tests can verify
+ * defaults and the legacy-flag clean break.
+ * @param {object} values - Parsed option values
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
+ * @returns {object}
+ */
+export function parseDiscussOptions(values, runtime) {
+  const { task: taskContent, amend: taskAmend } = resolveTaskContent(
+    values,
+    runtime,
+  );
+
+  const profilesRaw = values["agent-profiles"];
+  const agentCwd = resolve(values["agent-cwd"] ?? ".");
+
+  const maxTurnsRaw = values["max-turns"] ?? "40";
+  const maxTurns = maxTurnsRaw === "0" ? 0 : parseInt(maxTurnsRaw, 10);
+
+  const agentConfigs = parseAgentProfiles(profilesRaw, agentCwd, maxTurns);
+
+  const resumeContextRaw = values["resume-context"];
+  let resumeContext = null;
+  if (resumeContextRaw) {
+    try {
+      resumeContext = JSON.parse(resumeContextRaw);
+    } catch (err) {
+      throw new Error(`--resume-context is not valid JSON: ${err.message}`);
+    }
+  }
+
+  const maxLeadTurnsRaw = values["max-lead-turns"] ?? "200";
+  const maxLeadTurns = parseInt(maxLeadTurnsRaw, 10);
+
+  return {
+    taskContent,
+    taskAmend,
+    agentConfigs,
+    leadProfile: values["lead-profile"] ?? undefined,
+    leadModel: values["lead-model"] || LEAD_MODEL,
+    agentModel: values["agent-model"] || AGENT_MODEL,
+    maxTurns,
+    maxLeadTurns,
+    outputPath: values.output,
+    workTracker: resolveWorkTracker(values, runtime?.proc?.env),
+    discussionId: values["discussion-id"] ?? null,
+    resumeContext,
+    callbackUrl: runtime.proc.env.CALLBACK_URL ?? null,
+    inboxUrl: runtime.proc.env.INBOX_URL ?? null,
+    correlationId: runtime.proc.env.CORRELATION_ID ?? null,
+  };
+}
+
+/**
+ * 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.
+ *
+ * @param {import("@forwardimpact/libcli").InvocationContext} ctx
+ * @returns {Promise<{ok: boolean, code?: number, error?: string}>}
+ */
+export async function runDiscussCommand(ctx) {
+  const runtime = ctx.deps.runtime;
+  const opts = parseDiscussOptions(ctx.options, runtime);
+
+  const redactor = createRedactor({ runtime });
+
+  const fileStream = opts.outputPath
+    ? runtime.fs.createWriteStream(opts.outputPath)
+    : null;
+  const output = fileStream
+    ? createTeeWriter({
+        fileStream,
+        textStream: runtime.proc.stdout,
+        mode: "supervised",
+        now: () => isoTimestamp(runtime.clock.now()),
+      })
+    : runtime.proc.stdout;
+
+  if (opts.leadProfile) {
+    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.
+  runtime.proc.env.LIBHARNESS_WORK_TRACKER = opts.workTracker;
+
+  const { query } = await import("@anthropic-ai/claude-agent-sdk");
+  const discusser = createDiscusser({
+    leadProfile: opts.leadProfile,
+    leadModel: opts.leadModel,
+    agentModel: opts.agentModel,
+    agentConfigs: opts.agentConfigs,
+    discussionId: opts.discussionId,
+    resumeContext: opts.resumeContext,
+    query,
+    output,
+    maxTurns: opts.maxTurns,
+    maxLeadTurns: opts.maxLeadTurns,
+    taskAmend: opts.taskAmend,
+    redactor,
+    callbackUrl: opts.callbackUrl,
+    inboxUrl: opts.inboxUrl,
+    correlationId: opts.correlationId,
+    runtime,
+  });
+
+  const result = await discusser.run(opts.taskContent);
+
+  if (fileStream) {
+    await new Promise((r) => output.end(r));
+    await new Promise((r) => fileStream.end(r));
+  }
+
+  return result.success ? { ok: true } : { ok: false, code: 1, error: "" };
+}

package/src/commands/facilitate.js

@@ -0,0 +1,123 @@
+import { resolve } from "node:path";
+import { isoTimestamp } from "@forwardimpact/libutil";
+import { createFacilitator } from "../facilitator.js";
+import { createRedactor } from "../redaction.js";
+import { createTeeWriter } from "../tee-writer.js";
+import { resolveTaskContent } from "./task-input.js";
+import { resolveWorkTracker } from "./work-tracker.js";
+import { AGENT_MODEL, LEAD_MODEL } from "@forwardimpact/libutil/models";
+
+/**
+ * Parse comma-separated agent profile names into structured configs.
+ * @param {string} raw - Comma-separated profile names
+ * @param {string} cwd - Shared working directory for all agents
+ * @returns {Array<{name: string, role: string, cwd: string, agentProfile: string}>}
+ */
+function parseAgentProfiles(raw, cwd, maxTurns) {
+  return raw.split(",").map((entry) => {
+    const name = entry.trim();
+    return { name, role: name, cwd, agentProfile: name, 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.
+ * @param {object} values - Parsed option values
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
+ * @returns {object} Parsed options
+ */
+export function parseFacilitateOptions(values, runtime) {
+  const { task: taskContent, amend: taskAmend } = resolveTaskContent(
+    values,
+    runtime,
+  );
+
+  const profilesRaw = values["agent-profiles"];
+  if (!profilesRaw) throw new Error("--agent-profiles is required");
+  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.
+  const agentConfigs = parseAgentProfiles(profilesRaw, agentCwd, maxTurns);
+
+  return {
+    taskContent,
+    taskAmend,
+    agentConfigs,
+    facilitatorCwd: resolve(values["facilitator-cwd"] ?? "."),
+    agentModel: values["agent-model"] || AGENT_MODEL,
+    facilitatorModel: values["lead-model"] || LEAD_MODEL,
+    maxTurns,
+    outputPath: values.output,
+    facilitatorProfile: values["lead-profile"] ?? undefined,
+    workTracker: resolveWorkTracker(values, runtime?.proc?.env),
+  };
+}
+
+/**
+ * Facilitate command — run a facilitated multi-agent session.
+ *
+ * Usage: fit-harness facilitate [options]
+ *
+ * @param {import("@forwardimpact/libcli").InvocationContext} ctx
+ * @returns {Promise<{ok: boolean, code?: number, error?: string}>}
+ */
+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).
+  const redactor = createRedactor({ runtime });
+
+  const fileStream = opts.outputPath
+    ? runtime.fs.createWriteStream(opts.outputPath)
+    : null;
+  const output = fileStream
+    ? createTeeWriter({
+        fileStream,
+        textStream: runtime.proc.stdout,
+        mode: "supervised",
+        now: () => isoTimestamp(runtime.clock.now()),
+      })
+    : runtime.proc.stdout;
+
+  if (opts.facilitatorProfile) {
+    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.
+  runtime.proc.env.LIBHARNESS_WORK_TRACKER = opts.workTracker;
+
+  const { query } = await import("@anthropic-ai/claude-agent-sdk");
+  const facilitator = createFacilitator({
+    facilitatorCwd: opts.facilitatorCwd,
+    agentConfigs: opts.agentConfigs,
+    query,
+    output,
+    agentModel: opts.agentModel,
+    facilitatorModel: opts.facilitatorModel,
+    maxTurns: opts.maxTurns,
+    facilitatorProfile: opts.facilitatorProfile,
+    taskAmend: opts.taskAmend,
+    redactor,
+    runtime,
+  });
+
+  const result = await facilitator.run(opts.taskContent);
+
+  if (fileStream) {
+    await new Promise((r) => output.end(r));
+    await new Promise((r) => fileStream.end(r));
+  }
+
+  return result.success ? { ok: true } : { ok: false, code: 1, error: "" };
+}

package/src/commands/output.js

@@ -0,0 +1,36 @@
+import { isoTimestamp } from "@forwardimpact/libutil";
+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
+ *
+ * @param {import("@forwardimpact/libcli").InvocationContext} ctx
+ * @returns {Promise<{ok: true}>}
+ */
+export async function runOutputCommand(ctx) {
+  const values = ctx.options;
+  const runtime = ctx.deps.runtime;
+  const format =
+    values.format === "text" || values.format === "json"
+      ? values.format
+      : "json";
+  const collector = createTraceCollector({
+    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.
+  for await (const line of runtime.proc.stdin) {
+    collector.addLine(line);
+  }
+
+  if (format === "text") {
+    runtime.proc.stdout.write(collector.toText() + "\n");
+  } else {
+    runtime.proc.stdout.write(JSON.stringify(collector.toJSON()) + "\n");
+  }
+  return { ok: true };
+}

package/src/commands/run.js

@@ -0,0 +1,152 @@
+import { Writable } from "node:stream";
+import { resolve } from "node:path";
+import { isoTimestamp } from "@forwardimpact/libutil";
+import { createAgentRunner } from "../agent-runner.js";
+import { composeProfilePrompt } from "../profile-prompt.js";
+import { createRedactor } from "../redaction.js";
+import { createTeeWriter } from "../tee-writer.js";
+import { SequenceCounter } from "../sequence-counter.js";
+import { resolveWorkTracker } from "./work-tracker.js";
+import { resolveTaskContent } from "./task-input.js";
+import { createServiceConfig } from "@forwardimpact/libconfig";
+import { AGENT_MODEL } from "@forwardimpact/libutil/models";
+
+/**
+ * Parse and validate run command options from parsed values.
+ * @param {object} values - Parsed option values from cli.parse()
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
+ * @returns {{ taskContent: string, cwd: string, model: string, maxTurns: number, outputPath: string|undefined, agentProfile: string|undefined, workTracker: string, allowedTools: string[] }}
+ */
+export function parseRunOptions(values, runtime) {
+  const { task: taskContent, amend: taskAmend } = resolveTaskContent(
+    values,
+    runtime,
+  );
+  const maxTurnsRaw = values["max-turns"] ?? "50";
+
+  return {
+    taskContent,
+    taskAmend,
+    cwd: resolve(values.cwd ?? "."),
+    agentModel: values["agent-model"] || AGENT_MODEL,
+    maxTurns: maxTurnsRaw === "0" ? 0 : parseInt(maxTurnsRaw, 10),
+    outputPath: values.output,
+    agentProfile: values["agent-profile"] ?? undefined,
+    workTracker: resolveWorkTracker(values, runtime?.proc?.env),
+    allowedTools: (
+      values["allowed-tools"] ??
+      "Bash,Read,Glob,Grep,Write,Edit,Agent,TodoWrite"
+    ).split(","),
+    mcpServer: values["mcp-server"] ?? undefined,
+  };
+}
+
+/**
+ * Run command — execute a single agent via the Claude Agent SDK.
+ *
+ * Usage: fit-harness run [options]
+ *
+ * @param {import("@forwardimpact/libcli").InvocationContext} ctx
+ * @returns {Promise<{ok: boolean, code?: number, error?: string}>}
+ */
+export async function runRunCommand(ctx) {
+  const runtime = ctx.deps.runtime;
+  const {
+    taskContent,
+    taskAmend,
+    cwd,
+    agentModel,
+    maxTurns,
+    outputPath,
+    agentProfile,
+    workTracker,
+    allowedTools,
+    mcpServer,
+  } = 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).
+  const redactor = createRedactor({ runtime });
+
+  // When --output is specified, stream text to stdout while writing NDJSON to file.
+  // Otherwise, write NDJSON directly to stdout (backwards-compatible).
+  const fileStream = outputPath
+    ? runtime.fs.createWriteStream(outputPath)
+    : null;
+  const output = fileStream
+    ? createTeeWriter({
+        fileStream,
+        textStream: runtime.proc.stdout,
+        mode: "raw",
+        now: () => isoTimestamp(runtime.clock.now()),
+      })
+    : runtime.proc.stdout;
+
+  const counter = new SequenceCounter();
+  const devNull = new Writable({
+    write(_chunk, _enc, cb) {
+      cb();
+    },
+  });
+  const onLine = (line) => {
+    const event = JSON.parse(line);
+    const tagged = { source: "agent", seq: counter.next(), event };
+    output.write(JSON.stringify(redactor.redactValue(tagged)) + "\n");
+  };
+
+  let mcpServers = null;
+  if (mcpServer) {
+    const mcpConfig = await createServiceConfig("mcp");
+    mcpServers = {
+      [mcpServer]: {
+        type: "http",
+        url: mcpConfig.url,
+        headers: { Authorization: `Bearer ${mcpConfig.mcpToken()}` },
+      },
+    };
+    allowedTools.push(`mcp__${mcpServer}__*`);
+  }
+
+  if (agentProfile) {
+    runtime.proc.env.LIBHARNESS_AGENT_PROFILE = agentProfile;
+  }
+  // Unconditional so the default "github" is observable to the agent's
+  // active-tracker resolution, mirroring --agent-profile's env write above.
+  runtime.proc.env.LIBHARNESS_WORK_TRACKER = workTracker;
+
+  const systemPrompt = agentProfile
+    ? composeProfilePrompt(agentProfile, {
+        profilesDir: resolve(cwd, ".claude/agents"),
+        runtime,
+      })
+    : undefined;
+
+  const { query } = await import("@anthropic-ai/claude-agent-sdk");
+  const runner = createAgentRunner({
+    cwd,
+    query,
+    output: devNull,
+    model: agentModel,
+    maxTurns,
+    allowedTools,
+    onLine,
+    settingSources: ["project"],
+    systemPrompt,
+    taskAmend,
+    mcpServers,
+    redactor,
+    runtime,
+  });
+
+  const result = await runner.run(taskContent);
+
+  if (fileStream) {
+    await new Promise((r) => output.end(r));
+    await new Promise((r) => fileStream.end(r));
+  }
+
+  return result.success
+    ? { ok: true }
+    : { ok: false, code: 1, error: result.error?.message ?? "" };
+}

package/src/commands/supervise.js

@@ -0,0 +1,136 @@
+import { resolve, join } from "node:path";
+import { isoTimestamp } from "@forwardimpact/libutil";
+import { createSupervisor } from "../supervisor.js";
+import { createRedactor } from "../redaction.js";
+import { createTeeWriter } from "../tee-writer.js";
+import { resolveTaskContent } from "./task-input.js";
+import { resolveWorkTracker } from "./work-tracker.js";
+import { createServiceConfig } from "@forwardimpact/libconfig";
+import { AGENT_MODEL, LEAD_MODEL } from "@forwardimpact/libutil/models";
+
+/**
+ * Parse all supervise flags from parsed values into an options object.
+ * @param {object} values - Parsed option values from cli.parse()
+ * @param {import("@forwardimpact/libutil/runtime").Runtime} runtime
+ * @returns {Promise<object>}
+ */
+export async function parseSuperviseOptions(values, runtime) {
+  const { task: taskContent, amend: taskAmend } = resolveTaskContent(
+    values,
+    runtime,
+  );
+  const supervisorAllowedToolsRaw = values["supervisor-allowed-tools"];
+
+  const tmpRoot = runtime.proc.env.TMPDIR ?? "/tmp";
+  const agentCwd = resolve(
+    values["agent-cwd"] ??
+      (await runtime.fs.mkdtemp(join(tmpRoot, "fit-harness-agent-"))),
+  );
+
+  return {
+    taskContent,
+    taskAmend,
+    supervisorCwd: resolve(values["supervisor-cwd"] ?? "."),
+    agentCwd,
+    agentModel: values["agent-model"] || AGENT_MODEL,
+    supervisorModel: values["lead-model"] || LEAD_MODEL,
+    maxTurns: (() => {
+      const raw = values["max-turns"] ?? "200";
+      return raw === "0" ? 0 : parseInt(raw, 10);
+    })(),
+    outputPath: values.output,
+    supervisorProfile: values["lead-profile"] ?? undefined,
+    agentProfile: values["agent-profile"] ?? undefined,
+    workTracker: resolveWorkTracker(values, runtime?.proc?.env),
+    allowedTools: (
+      values["allowed-tools"] ??
+      "Bash,Read,Glob,Grep,Write,Edit,Agent,TodoWrite"
+    ).split(","),
+    supervisorAllowedTools: supervisorAllowedToolsRaw
+      ? supervisorAllowedToolsRaw.split(",")
+      : undefined,
+    mcpServer: values["mcp-server"] ?? undefined,
+  };
+}
+
+/**
+ * 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.
+ *
+ * Usage: fit-harness supervise [options]
+ *
+ * @param {import("@forwardimpact/libcli").InvocationContext} ctx
+ * @returns {Promise<{ok: boolean, code?: number, error?: string}>}
+ */
+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).
+  const redactor = createRedactor({ runtime });
+
+  // When --output is specified, stream text to stdout while writing NDJSON to file.
+  // Otherwise, write NDJSON directly to stdout (backwards-compatible).
+  const fileStream = opts.outputPath
+    ? runtime.fs.createWriteStream(opts.outputPath)
+    : null;
+  const output = fileStream
+    ? createTeeWriter({
+        fileStream,
+        textStream: runtime.proc.stdout,
+        mode: "supervised",
+        now: () => isoTimestamp(runtime.clock.now()),
+      })
+    : runtime.proc.stdout;
+
+  let agentMcpServers = null;
+  if (opts.mcpServer) {
+    const mcpConfig = await createServiceConfig("mcp");
+    agentMcpServers = {
+      [opts.mcpServer]: {
+        type: "http",
+        url: mcpConfig.url,
+        headers: { Authorization: `Bearer ${mcpConfig.mcpToken()}` },
+      },
+    };
+    opts.allowedTools.push(`mcp__${opts.mcpServer}__*`);
+  }
+
+  if (opts.agentProfile) {
+    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.
+  runtime.proc.env.LIBHARNESS_WORK_TRACKER = opts.workTracker;
+
+  const { query } = await import("@anthropic-ai/claude-agent-sdk");
+  const supervisor = createSupervisor({
+    supervisorCwd: opts.supervisorCwd,
+    agentCwd: opts.agentCwd,
+    query,
+    output,
+    agentModel: opts.agentModel,
+    supervisorModel: opts.supervisorModel,
+    maxTurns: opts.maxTurns,
+    allowedTools: opts.allowedTools,
+    supervisorAllowedTools: opts.supervisorAllowedTools,
+    supervisorProfile: opts.supervisorProfile,
+    agentProfile: opts.agentProfile,
+    taskAmend: opts.taskAmend,
+    agentMcpServers,
+    redactor,
+    runtime,
+  });
+
+  const result = await supervisor.run(opts.taskContent);
+
+  if (fileStream) {
+    await new Promise((r) => output.end(r));
+    await new Promise((r) => fileStream.end(r));
+  }
+
+  return result.success ? { ok: true } : { ok: false, code: 1, error: "" };
+}

package/src/commands/task-input.js

@@ -0,0 +1,54 @@
+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.
+ *
+ * @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`.
+ * @returns {{ task: string, amend: string | undefined }}
+ */
+export function resolveTaskContent(values, runtime) {
+  const taskFile = values["task-file"];
+  const taskText = values["task-text"];
+  const taskEvent = values["task-event"];
+
+  const set = [taskFile, taskText, taskEvent].filter(Boolean).length;
+  if (set === 0) {
+    throw new Error(
+      "one of --task-file, --task-text, --task-event is required",
+    );
+  }
+  if (set > 1) {
+    throw new Error(
+      "--task-file, --task-text, --task-event are mutually exclusive",
+    );
+  }
+
+  const amendFlag = values["task-amend"] ?? undefined;
+
+  if (taskFile) {
+    return {
+      task: runtime.fsSync.readFileSync(taskFile, "utf8"),
+      amend: amendFlag,
+    };
+  }
+  if (taskText) {
+    return { task: taskText, amend: amendFlag };
+  }
+
+  const eventName = runtime.proc.env.GITHUB_EVENT_NAME;
+  if (!eventName) {
+    throw new Error("--task-event requires GITHUB_EVENT_NAME to be set");
+  }
+  const payload = JSON.parse(runtime.fsSync.readFileSync(taskEvent, "utf8"));
+  const composed = composeTaskFromGitHubEvent(payload, eventName);
+  return { task: composed.task, amend: amendFlag ?? composed.amend };
+}

package/src/commands/tee.js

@@ -0,0 +1,53 @@
+import { PassThrough } from "node:stream";
+import { pipeline } from "node:stream/promises";
+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.
+ *
+ * Usage: fit-harness tee [output.ndjson] < trace.ndjson
+ *
+ * @param {import("@forwardimpact/libcli").InvocationContext} ctx
+ * @returns {Promise<{ok: boolean, code?: number, error?: string}>}
+ */
+export async function runTeeCommand(ctx) {
+  const runtime = ctx.deps.runtime;
+  const outputPath = ctx.args.output ?? null;
+  const fileStream = outputPath
+    ? 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).
+  const sink = fileStream ?? new PassThrough();
+  const tee = createTeeWriter({
+    fileStream: sink,
+    textStream: runtime.proc.stdout,
+    mode: "raw",
+    now: () => isoTimestamp(runtime.clock.now()),
+  });
+
+  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.
+    const lines = (async function* () {
+      for await (const line of runtime.proc.stdin) yield `${line}\n`;
+    })();
+    await pipeline(lines, tee);
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, code: 1, error: error.message };
+  } finally {
+    if (fileStream) {
+      await new Promise((resolve, reject) => {
+        fileStream.end(() => resolve());
+        fileStream.on("error", reject);
+      });
+    }
+  }
+}