@dungle-scrubs/harness-cli-normalizer 0.1.2 → 0.3.0

package/src/cli/check.ts

@@ -0,0 +1,136 @@
+import { execFileSync } from "node:child_process";
+import { type VersionStatus, versionStatus } from "../interpretation/versions.js";
+import type { HarnessDescriptor } from "../knowledge/descriptor.js";
+import { defaultDescriptors } from "../knowledge/overrides.js";
+
+interface Row {
+  harness: string;
+  bin: string;
+  verifiedAgainst: string;
+  latest: string | null;
+  source: string;
+  status: VersionStatus;
+}
+
+const npmLatest = async (pkg: string): Promise<string | null> => {
+  try {
+    const res = await fetch(`https://registry.npmjs.org/${pkg}`, {
+      headers: { accept: "application/vnd.npm.install-v1+json" },
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!res.ok) return null;
+    const body = (await res.json()) as { "dist-tags"?: { latest?: unknown } };
+    const latest = body["dist-tags"]?.latest;
+    return typeof latest === "string" ? latest : null;
+  } catch {
+    return null;
+  }
+};
+
+const installedVersion = (bin: string): string | null => {
+  try {
+    const out = execFileSync(bin, ["--version"], { encoding: "utf8", timeout: 10_000 });
+    const match = out.match(/\d+\.\d+\.\d+(?:[.+-][0-9A-Za-z.-]+)?/);
+    return match ? match[0] : null;
+  } catch {
+    return null;
+  }
+};
+
+const resolveLatest = async (
+  h: HarnessDescriptor,
+): Promise<{ latest: string | null; source: string }> => {
+  if (h.versionSource.kind === "npm") {
+    return {
+      latest: await npmLatest(h.versionSource.package),
+      source: `npm:${h.versionSource.package}`,
+    };
+  }
+  return { latest: installedVersion(h.bin), source: `installed:${h.bin}` };
+};
+
+export const check = async (rawArgs: string[]): Promise<void> => {
+  const wantJson = rawArgs.includes("--json");
+  const wantHelp = rawArgs.includes("--help") || rawArgs.includes("-h");
+  if (wantHelp) {
+    const { CHECK_HELP } = await import("./help.js");
+    process.stdout.write(CHECK_HELP);
+    return;
+  }
+
+  const descriptors = Object.values(defaultDescriptors()).filter(
+    (d): d is HarnessDescriptor => d !== undefined,
+  );
+
+  const rows: Row[] = await Promise.all(
+    descriptors.map(async (h) => {
+      const { latest, source } = await resolveLatest(h);
+      return {
+        harness: h.name,
+        bin: h.bin,
+        verifiedAgainst: h.verifiedAgainst,
+        latest,
+        source,
+        status: versionStatus(h.verifiedAgainst, latest),
+      };
+    }),
+  );
+
+  const behind = rows.filter((r) => r.status === "behind");
+  const unknown = rows.filter((r) => r.status === "unknown");
+
+  if (wantJson) {
+    process.stdout.write(
+      `${JSON.stringify({ checkedAt: new Date().toISOString(), rows, behind: behind.map((r) => r.harness) }, null, 2)}\n`,
+    );
+  } else {
+    const mark = (s: VersionStatus) =>
+      s === "ok" ? "✓ ok" : s === "behind" ? "⬆ NEW" : s === "ahead" ? "? ahead" : "– unknown";
+    process.stdout.write(
+      `\n${"harness".padEnd(9)}${"verified".padEnd(12)}${"latest".padEnd(12)}status\n`,
+    );
+    for (const r of rows) {
+      process.stdout.write(
+        `${r.harness.padEnd(9)}${r.verifiedAgainst.padEnd(12)}${(r.latest ?? "?").padEnd(12)}${mark(r.status)}\n`,
+      );
+    }
+    if (behind.length > 0) {
+      process.stdout.write(
+        `\n${behind.length} harness(es) behind: ${behind.map((r) => `${r.harness} ${r.verifiedAgainst}→${r.latest}`).join(", ")}\n`,
+      );
+      process.stdout.write(
+        "Run the local capability tripwires (smoke:seven) against the new version, then file an issue + bump verifiedAgainst.\n",
+      );
+    } else if (unknown.length > 0) {
+      process.stdout.write(`\n${unknown.length} harness(es) unknown (network or missing bin)\n`);
+    } else {
+      process.stdout.write("\nall descriptors current with their published versions.\n");
+    }
+  }
+
+  // Exit logic: behind => 1, unknown (network failure) => 1 with partial results, else 0
+  // But we must not exit 1 for unknown if behind already counts? We'll handle:
+  if (behind.length > 0) {
+    process.exitCode = 1;
+  } else if (unknown.length > 0 && rows.some((r) => r.latest === null)) {
+    // network failure at least one
+    // Per spec: network failure prints warning and exits 1 with partial results
+    // We'll check if any latest is null and that we attempted npm fetch (could be network)
+    // Simpler: if unknown and not all ok, exit 1
+    // But spec says check should reuse versions.ts and not crash; exit 1 with partial results
+    // We'll exit 1 if any harness has unknown and at least one npm source failed - but we can't distinguish installed missing vs network.
+    // For now, exit 1 if unknown.length >0 and at least one behind==0? Actually spec says network failure => exit 1.
+    // We'll exit 1 if unknown includes npm harnesses (they shouldn't be unknown without network).
+    const npmUnknown = rows.filter((r) => r.source.startsWith("npm:") && r.status === "unknown");
+    if (npmUnknown.length > 0) process.exitCode = 1;
+    else if (behind.length === 0 && unknown.length > 0) {
+      // installed unknown (muse missing) is not necessarily failure? But spec says network failure case is 1.
+      // For installed missing, we treat as unknown but not failure - keep 0 to not break CI where muse not installed.
+      // However spec says check prints partial results and exits 1 on network failure.
+      // We'll only exit 1 for npmUnknown, otherwise 0.
+      process.exitCode = 0;
+    }
+  } else {
+    process.exitCode = 0;
+  }
+};

package/src/cli/exit-codes.ts

@@ -0,0 +1,13 @@
+import type { ExitCause } from "../execution/events.js";
+
+export const EXIT_CLEAN = 0;
+export const EXIT_REFUSAL = 2;
+export const EXIT_FAILURE = 1;
+
+export const exitCodeForCause = (cause: ExitCause): number => {
+  if (cause === "clean") return EXIT_CLEAN;
+  // All non-clean causes are failures that should be exit 1, except refusal is already handled separately
+  return EXIT_FAILURE;
+};
+
+export const exitCodeForRefusal = (): number => EXIT_REFUSAL;

package/src/cli/help.ts

@@ -0,0 +1,114 @@
+export const TOP_LEVEL_HELP = `hcn - One stable interface to four coding-agent CLIs
+
+Usage: hcn <command> [options] [prompt]
+
+Commands:
+  run <harness> [prompt]    One-shot headless turn (streamTurn)
+  session <harness>         Interactive session (openSession, Claude-only)
+  inspect <harness>         Descriptor / argv / capability inspection (no spawn)
+  ls                        List harnesses with verifiedAgainst versions
+  check                     Drift check (published version vs verifiedAgainst)
+
+Options:
+  -h, --help                Show help
+  -V, --version             Show version
+
+Run 'hcn <command> --help' for command-specific help.
+`;
+
+export const RUN_HELP = `hcn run - One-shot headless turn
+
+Usage: hcn run <harness> [prompt] [options]
+
+Arguments:
+  <harness>                 claude | codex | pi | muse
+  [prompt]                  Prompt text (positional). Must not start with '-'.
+                            Use --prompt or --prompt-file for leading '-' or multi-line.
+
+Options:
+  --prompt <text>           Prompt text (alternative to positional)
+  --prompt-file <path|->    Read prompt from file, or stdin when '-'
+  --model <id>              Model id (validated per harness)
+  --effort <value>          Effort level (validated per harness/model)
+  --sandbox <value>         Sandbox mode (codex only)
+  --provider <value>        Provider (pi only)
+  --tools <a,b>             Tool grants (claude only, comma-separated)
+  --autonomy                Enable autonomy flag (claude/codex/muse)
+  --no-autonomy             Disable autonomy
+  --write                   Enable write (muse)
+  --no-write                Disable write
+  --shell                   Enable shell (muse)
+  --no-shell                Disable shell
+  --max-steps <n>           Max steps (muse, 1-10000)
+  --no-tools                Disable tools discovery facet
+  --no-instruction-files    Disable instructionFiles discovery facet
+  --no-extensions           Disable extensions discovery facet
+  --no-skills               Disable skills discovery facet
+  --cwd <path>              Working directory for spawn
+  --env KEY=VAL             Environment (repeatable; KEY= deletes)
+  --resume <uuid>           Resume session id (UUID)
+  --json                    NDJSON HarnessEvent to stdout
+  -h, --help                Show help
+  -V, --version             Show version
+`;
+
+export const SESSION_HELP = `hcn session - Interactive session (Claude-only)
+
+Usage: hcn session <harness> [options]
+
+Arguments:
+  <harness>                 Must be 'claude' (other harnesses have no sessionMode)
+
+Options:
+  --model <id>              Model for the session
+  --session-id <uuid>       Session id (UUID, else random)
+  --cwd <path>              Working directory
+  --help                    Show help
+  --version                 Show version
+`;
+
+export const INSPECT_HELP = `hcn inspect - Descriptor / argv inspection
+
+Usage: hcn inspect <harness> [options]
+
+Arguments:
+  <harness>                 claude | codex | pi | muse
+
+Options:
+  --argv                    Preview argv that would be spawned
+  --prompt <text>           Prompt for argv preview
+  --prompt-file <path|->    Read prompt from file
+  --model <id>              Model
+  --effort <value>          Effort
+  --sandbox <value>         Sandbox
+  --provider <value>        Provider
+  --tools <a,b>             Tools
+  --autonomy / --no-autonomy
+  --write / --no-write
+  --shell / --no-shell
+  --max-steps <n>
+  --no-tools, --no-instruction-files, --no-extensions, --no-skills
+  --cwd <path>
+  --env KEY=VAL
+  --resume <uuid>
+  -h, --help                Show help
+`;
+
+export const LS_HELP = `hcn ls - List harnesses
+
+Usage: hcn ls
+
+Prints each harness name with its verifiedAgainst version and versionSource.
+`;
+
+export const CHECK_HELP = `hcn check - Drift check
+
+Usage: hcn check [--json]
+
+Compares each harness's verifiedAgainst against the latest published version.
+Exits 0 when no drift, 1 when drift found, 1 on network failure with partial results.
+
+Options:
+  --json                    Machine-readable output
+  -h, --help                Show help
+`;

package/src/cli/index.ts

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+import { TOP_LEVEL_HELP } from "./help.js";
+import { getVersion } from "./version.js";
+
+const SUPPORTED = ["claude", "codex", "pi", "muse"] as const;
+
+// Prevent EPIPE crashes when piped to head/grep -q (e.g., hcn ls | head, hcn run --json | head)
+process.stdout.on("error", (err) => {
+  const code = (err as NodeJS.ErrnoException).code;
+  if (code === "EPIPE") process.exit(0);
+});
+process.stderr.on("error", (err) => {
+  const code = (err as NodeJS.ErrnoException).code;
+  if (code === "EPIPE") process.exit(0);
+});
+
+const printVersion = (): void => {
+  process.stdout.write(`${getVersion()}\n`);
+};
+
+const printTopHelp = (): void => {
+  process.stdout.write(TOP_LEVEL_HELP);
+};
+
+export const failUnknownHarness = (name: string): never => {
+  process.stderr.write(
+    `unknown harness ${JSON.stringify(name)}; supported: ${SUPPORTED.join(", ")}\n`,
+  );
+  process.stderr.write(`supported: ${SUPPORTED.join(", ")}\n`);
+  process.exitCode = 2;
+  // Use process.exit to ensure exit code is set even if async
+  process.exit(2);
+};
+
+export const dispatch = async (raw: string[]): Promise<void> => {
+  // Shared dispatch for programmatic use (tests) - mirrors main but takes argv slice
+  // Global --help / --version without command
+  if (raw.length === 0 || raw[0] === "--help" || raw[0] === "-h") {
+    if (raw.includes("--version") || raw.includes("-V")) {
+      printVersion();
+      return;
+    }
+    printTopHelp();
+    return;
+  }
+  if (raw[0] === "--version" || raw[0] === "-V") {
+    printVersion();
+    return;
+  }
+
+  const cmd = raw[0] as string;
+
+  switch (cmd) {
+    case "ls": {
+      if (raw.includes("--help") || raw.includes("-h")) {
+        const { LS_HELP } = await import("./help.js");
+        process.stdout.write(LS_HELP);
+        return;
+      }
+      if (raw.includes("--version") || raw.includes("-V")) {
+        printVersion();
+        return;
+      }
+      if (raw.length > 1) {
+        const extra = raw.slice(1);
+        const hasUnknown = extra.some((a) => a.startsWith("-"));
+        if (hasUnknown) {
+          process.stderr.write(`unknown flag for ls: ${extra.join(" ")}\n`);
+          process.exitCode = 2;
+          return;
+        }
+      }
+      const { ls } = await import("./ls.js");
+      ls();
+      return;
+    }
+    case "check": {
+      const { check } = await import("./check.js");
+      await check(raw.slice(1));
+      return;
+    }
+    case "inspect": {
+      if (raw.slice(1).includes("--help") || raw.slice(1).includes("-h")) {
+        const { INSPECT_HELP } = await import("./help.js");
+        process.stdout.write(INSPECT_HELP);
+        return;
+      }
+      const harness = raw[1];
+      if (!harness || harness.startsWith("-")) {
+        process.stderr.write(`inspect requires <harness>; supported: ${SUPPORTED.join(", ")}\n`);
+        process.exitCode = 2;
+        return;
+      }
+      if (!(SUPPORTED as readonly string[]).includes(harness)) failUnknownHarness(harness);
+      const { inspect } = await import("./inspect.js");
+      await inspect(harness, raw.slice(2));
+      return;
+    }
+    case "run": {
+      if (raw.slice(1).includes("--help") || raw.slice(1).includes("-h")) {
+        const { RUN_HELP } = await import("./help.js");
+        process.stdout.write(RUN_HELP);
+        return;
+      }
+      if (raw.slice(1).includes("--version") || raw.slice(1).includes("-V")) {
+        printVersion();
+        return;
+      }
+      const harness = raw[1];
+      if (!harness || harness.startsWith("-")) {
+        process.stderr.write(`run requires <harness>; supported: ${SUPPORTED.join(", ")}\n`);
+        process.exitCode = 2;
+        return;
+      }
+      if (!(SUPPORTED as readonly string[]).includes(harness)) failUnknownHarness(harness);
+      const { run } = await import("./run.js");
+      await run(harness, raw.slice(2));
+      return;
+    }
+    case "session": {
+      if (raw.slice(1).includes("--help") || raw.slice(1).includes("-h")) {
+        const { SESSION_HELP } = await import("./help.js");
+        process.stdout.write(SESSION_HELP);
+        return;
+      }
+      const harness = raw[1];
+      if (!harness || harness.startsWith("-")) {
+        process.stderr.write(`session requires <harness>; supported: ${SUPPORTED.join(", ")}\n`);
+        process.exitCode = 2;
+        return;
+      }
+      if (!(SUPPORTED as readonly string[]).includes(harness)) failUnknownHarness(harness);
+      const { session } = await import("./session.js");
+      await session(harness, raw.slice(2));
+      return;
+    }
+    case "help":
+    case "--help":
+    case "-h": {
+      printTopHelp();
+      return;
+    }
+    default: {
+      if ((SUPPORTED as readonly string[]).includes(cmd)) {
+        process.stderr.write(`missing command; did you mean 'hcn run ${cmd} <prompt>'?\n`);
+        process.stderr.write(TOP_LEVEL_HELP);
+        process.exitCode = 2;
+        return;
+      }
+      process.stderr.write(`unknown command ${JSON.stringify(cmd)}\n`);
+      process.stderr.write(TOP_LEVEL_HELP);
+      process.exitCode = 2;
+      return;
+    }
+  }
+};
+
+const main = async (): Promise<void> => {
+  await dispatch(process.argv.slice(2));
+};
+
+const shouldAutoRun = (() => {
+  const entry = process.argv[1] ?? "";
+  return (
+    entry.endsWith("cli.js") || entry.endsWith("cli/index.js") || entry.endsWith("src/cli/index.ts")
+  );
+})();
+
+if (shouldAutoRun) {
+  main().catch((err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`fatal: ${message}\n`);
+    if (err instanceof Error && err.stack) process.stderr.write(`${err.stack}\n`);
+    process.exitCode = 1;
+    if (process.exitCode === 0) process.exitCode = 1;
+  });
+}

package/src/cli/inspect.ts

@@ -0,0 +1,174 @@
+import { redactArgv } from "../execution/stream-turn.js";
+import { buildLaunchArgv } from "../interpretation/argv.js";
+import { ArgvRefusalError } from "../interpretation/refusal.js";
+import { parseTurnOptions, resolvePromptAsync } from "./args.js";
+import { resolveHarness } from "./resolve-harness.js";
+
+export const inspect = async (harnessName: string, rawArgs: string[]): Promise<void> => {
+  const h = resolveHarness(harnessName);
+
+  // Check for --help
+  if (rawArgs.includes("--help") || rawArgs.includes("-h")) {
+    const { INSPECT_HELP } = await import("./help.js");
+    process.stdout.write(INSPECT_HELP);
+    return;
+  }
+
+  // Check for positional prompt injection before parse (only when --argv and no explicit prompt)
+  const { parseCommonFlags, detectPositionalPromptInjection } = await import("./args.js");
+  if (rawArgs.includes("--argv")) {
+    const injection = detectPositionalPromptInjection(rawArgs.filter((a) => a !== "--argv"));
+    if (injection) {
+      const err = new ArgvRefusalError({
+        issue: "prompt-flag-injection",
+        harness: h.name,
+        supported: ["prompt must not start with '-'"],
+        detail: `it would be parsed as a flag by ${h.bin}`,
+      });
+      process.stderr.write(`${err.message}\n`);
+      process.stderr.write(`supported: prompt must not start with '-'\n`);
+      process.exitCode = 2;
+      return;
+    }
+  }
+
+  // Parse flags for inspect
+  let parsed: ReturnType<typeof parseCommonFlags>;
+  try {
+    parsed = parseCommonFlags(rawArgs);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`unknown flag: ${message}\n`);
+    process.stderr.write(`Run 'hcn inspect --help' for usage.\n`);
+    process.exitCode = 2;
+    return;
+  }
+
+  const values = parsed.values as Record<string, unknown>;
+  const wantArgv = values.argv === true;
+
+  if (!wantArgv) {
+    // Pure descriptor dump
+    const out = {
+      name: h.name,
+      bin: h.bin,
+      verifiedAgainst: h.verifiedAgainst,
+      versionSource: h.versionSource,
+      launch: {
+        baseFlags: h.launch.baseFlags,
+        subcommands: h.launch.subcommands,
+        streamFlags: h.launch.streamFlags,
+        promptStyle: h.launch.promptStyle,
+        toolsFlag: h.launch.toolsFlag,
+        idFlag: h.launch.idFlag,
+      },
+      resume: h.resume,
+      sessionMode: h.sessionMode,
+      vocabulary: {
+        models: h.vocabulary.models,
+        aliases: h.vocabulary.aliases,
+        efforts: h.vocabulary.efforts,
+        effortsByModel: (h.vocabulary as { effortsByModel?: unknown }).effortsByModel,
+        extensible: h.vocabulary.extensible,
+        modelFlag: h.vocabulary.modelFlag,
+      },
+      turnOptions: h.turnOptions,
+    };
+    process.stdout.write(`${JSON.stringify(out, null, 2)}\n`);
+    return;
+  }
+
+  // --argv preview path: need prompt + turn options
+  const positional = parsed.positionals as string[];
+  // positional[0] would be harness already consumed, but we passed rawArgs without harness - check: caller passes remaining after harness
+  // So positionals are potential prompt positional if not using --prompt
+  const positionalPrompt = positional.length > 0 ? positional[0] : undefined;
+  if (positional.length > 1) {
+    process.stderr.write(`too many positionals for inspect --argv\n`);
+    process.exitCode = 2;
+    return;
+  }
+
+  let prompt: string;
+  let promptSource: string;
+  try {
+    const resolved = await resolvePromptAsync({
+      positionalPrompt,
+      promptFlag: values.prompt as string | undefined,
+      promptFile: values["prompt-file"] as string | undefined,
+    });
+    prompt = resolved.prompt;
+    promptSource = resolved.source;
+  } catch (err) {
+    if (err instanceof ArgvRefusalError) {
+      process.stderr.write(`${err.message}\n`);
+      if (err.supported.length) process.stderr.write(`supported: ${err.supported.join(", ")}\n`);
+      process.exitCode = 2;
+      return;
+    }
+    throw err;
+  }
+
+  // Build TurnOptions from flags
+  let turnOpts: ReturnType<typeof parseTurnOptions>;
+  try {
+    turnOpts = parseTurnOptions(values);
+  } catch (err) {
+    if (err instanceof ArgvRefusalError) {
+      process.stderr.write(`${err.message}\n`);
+      if (err.supported.length) process.stderr.write(`supported: ${err.supported.join(", ")}\n`);
+      process.exitCode = 2;
+      return;
+    }
+    throw err;
+  }
+
+  const fullOpts = {
+    ...turnOpts,
+    prompt,
+    ...(promptSource !== "positional" ? { __explicitPrompt: true as const } : {}),
+  } as Parameters<typeof buildLaunchArgv>[1];
+
+  let argv: string[];
+  try {
+    argv = buildLaunchArgv(h, fullOpts);
+  } catch (err) {
+    if (err instanceof ArgvRefusalError) {
+      process.stderr.write(`${err.message}\n`);
+      if (err.supported.length) process.stderr.write(`supported: ${err.supported.join(", ")}\n`);
+      process.exitCode = 2;
+      return;
+    }
+    throw err;
+  }
+
+  // Redact prompt for display, but keep structure
+  const redacted = redactArgv(argv, prompt);
+  // Also handle --resume case: need to use buildResumeArgv if resume present
+  if (values.resume !== undefined || values["session-id"] !== undefined) {
+    // For inspect --argv with --resume, show resume argv
+    const { buildResumeArgv } = await import("../interpretation/argv.js");
+    const resumeId = String(values.resume ?? values["session-id"]);
+    try {
+      const resumeOpts = { ...fullOpts, sessionId: resumeId };
+      const resumeArgv = buildResumeArgv(h, resumeOpts);
+      const redactedResume = redactArgv(resumeArgv, prompt);
+      process.stdout.write(`${JSON.stringify(redactedResume)}\n`);
+      process.stderr.write(`argv: ${redactedResume.join(" ")}\n`);
+      return;
+    } catch (err) {
+      if (err instanceof ArgvRefusalError) {
+        process.stderr.write(`${err.message}\n`);
+        if (err.supported.length) process.stderr.write(`supported: ${err.supported.join(", ")}\n`);
+        process.exitCode = 2;
+        return;
+      }
+      throw err;
+    }
+  }
+
+  process.stdout.write(`${JSON.stringify(redacted)}\n`);
+  process.stderr.write(`argv: ${redacted.join(" ")}\n`);
+};
+
+export const inspectCommand = inspect;

package/src/cli/ls.ts

@@ -0,0 +1,14 @@
+import type { HarnessDescriptor } from "../knowledge/descriptor.js";
+import { defaultDescriptors } from "../knowledge/overrides.js";
+
+export const ls = (): void => {
+  const descriptors = Object.values(defaultDescriptors()).filter(
+    (d): d is HarnessDescriptor => d !== undefined,
+  );
+  for (const h of descriptors) {
+    const source =
+      h.versionSource.kind === "npm" ? `npm:${h.versionSource.package}` : `installed:${h.bin}`;
+    // Format: "claude@2.1.229 (npm:@anthropic-ai/claude-code)"
+    process.stdout.write(`${h.name}@${h.verifiedAgainst} (${source})\n`);
+  }
+};

package/src/cli/render.ts

@@ -0,0 +1,62 @@
+import type { HarnessEvent } from "../execution/events.js";
+
+const dim = (s: string) => `\x1b[2m${s}\x1b[0m`;
+const cyan = (s: string) => `\x1b[36m${s}\x1b[0m`;
+const green = (s: string) => `\x1b[32m${s}\x1b[0m`;
+const red = (s: string) => `\x1b[31m${s}\x1b[0m`;
+const yellow = (s: string) => `\x1b[33m${s}\x1b[0m`;
+
+export interface RenderState {
+  streamed: boolean;
+}
+
+export const createRenderState = (): RenderState => ({ streamed: false });
+
+export const renderEvent = (event: HarnessEvent, state: RenderState): void => {
+  switch (event.kind) {
+    case "identity":
+      process.stdout.write(dim(`  ● session ${event.sessionId} (${event.authority})\n`));
+      break;
+    case "token":
+      process.stdout.write(event.text);
+      state.streamed = true;
+      break;
+    case "message":
+      if (!state.streamed) process.stdout.write(event.text);
+      break;
+    case "tool":
+      process.stdout.write(cyan(`\n  ⚙ ${event.name}`));
+      break;
+    case "progress":
+      // droppable
+      break;
+    case "context":
+      process.stdout.write(dim(`\n  ▪ context ${event.usedPct}%`));
+      break;
+    case "limit":
+      process.stdout.write(yellow(`\n  ⚠ limit: ${event.code} ${event.message}`));
+      break;
+    case "error":
+      process.stdout.write(red(`\n  ✗ ${event.message}`));
+      break;
+    case "failure": {
+      const detail = event.message ?? `${event.class}`;
+      process.stdout.write(red(`\n  ✗ failure ${event.class}: ${detail}`));
+      break;
+    }
+    case "done": {
+      const mark = event.cause === "clean" ? green("○ clean") : red(`○ ${event.cause}`);
+      const tail = event.failure ? ` ${event.failure.class}: ${event.failure.message}` : "";
+      process.stdout.write(`\n  ${mark} (exit ${event.exitCode ?? "none"})${tail}\n`);
+      break;
+    }
+    default: {
+      const exhaustive: never = event as never;
+      process.stdout.write(dim(`\n  ? ${(exhaustive as { kind: string }).kind}`));
+    }
+  }
+};
+
+export const writeEventNdjson = (event: HarnessEvent): void => {
+  process.stdout.write(`${JSON.stringify(event)}\n`);
+};