@codespar/cli 0.14.1 → 0.17.0

package/templates/hello-agent/packages/agent-runtime/src/channels/whatsapp/present.ts

@@ -0,0 +1,47 @@
+/**
+ * How a payable receivable is put into a conversation.
+ *
+ * It is here, and not inside the run loop, because two commands now present
+ * one: the run that issues the charge, and the poll that comes back to it
+ * later. A payer told how to pay by a poll must be told the same way as a
+ * payer told by a run, and the only way to guarantee that is for both to
+ * build the same messages from the same place.
+ *
+ * The shape is the point. The QR goes as an IMAGE and the copy-and-paste as
+ * its OWN message underneath, because a code inside a picture cannot be
+ * copied and a code inside a paragraph cannot be tapped.
+ */
+import type { ChargeInstrument, Execution } from "@codespar/agent-core";
+import type { OutboundBody } from "../types.js";
+
+export function instrumentBodies(execution: Execution, instalment: number, chargeId: string, instrument: ChargeInstrument, currency: string): OutboundBody[] {
+  const money = new Intl.NumberFormat("pt-BR", { style: "currency", currency });
+  const item = execution.items[instalment - 1];
+  const count = execution.items.length;
+  const bodies: OutboundBody[] = [
+    {
+      kind: "text",
+      text: [
+        count > 1 ? `Parcela ${instalment}/${count}: ` : "",
+        item ? money.format(item.amount / 100) : "",
+        instrument.due_date ? `, vence ${formatDate(instrument.due_date)}` : "",
+        ` — cobranca ${chargeId}`,
+      ].join(""),
+    },
+  ];
+  if (instrument.pix_copy_paste) {
+    bodies.push({ kind: "media", media: "qr", data: instrument.pix_copy_paste });
+    bodies.push({ kind: "instrument", instrument: "pix_copy_paste", value: instrument.pix_copy_paste });
+  }
+  if (instrument.boleto_bank_line) {
+    bodies.push({ kind: "text", text: "Ou pelo boleto, linha digitavel:" });
+    bodies.push({ kind: "instrument", instrument: "boleto_bank_line", value: instrument.boleto_bank_line });
+  }
+  return bodies;
+}
+
+/** `2026-09-30` -> `30/09/2026`. */
+export function formatDate(iso: string): string {
+  const [y, m, d] = iso.split("-");
+  return `${d}/${m}/${y}`;
+}

package/templates/hello-agent/packages/agent-runtime/src/channels/whatsapp/run.ts

@@ -0,0 +1,113 @@
+/**
+ * The conversation loop: the WhatsApp equivalent of `interactive()`, and the
+ * same gates in the same order. The person writes, the model answers, the
+ * core decides, and what the core produced goes back into the conversation.
+ *
+ * The one difference from the terminal, and it is the whole reason the
+ * channel exists as its own thing: on a terminal the operator and the
+ * counterparty are the same pair of eyes, and here they are not. The
+ * approval question and the console go to stderr; only `tell` reaches the
+ * person. Nothing checks that — it is the wiring: `ask` and `say` are
+ * functions this module never hands to the channel.
+ *
+ * The payable artifact is sent the way a person can actually use it: the QR
+ * as an image, and the copy-and-paste as its OWN message underneath, because
+ * a code inside a picture cannot be copied and a code inside a paragraph
+ * cannot be tapped.
+ */
+import type { ChargeInstrument, Execution } from "@codespar/agent-core";
+import { handleExecution, type TerminalOptions } from "../../terminal.js";
+import type { Setup } from "../../setup.js";
+import type { OutboundBody } from "../types.js";
+import { instrumentBodies } from "./present.js";
+import type { WhatsAppChannel } from "./index.js";
+
+export interface ConverseOptions {
+  setup: Setup;
+  channel: WhatsAppChannel;
+  approver: { id: string; channel: string };
+  /** The operator's decision when nobody is at a keyboard. The gate runs `mandate`, where there is none to take. */
+  decision?: "approve" | "deny" | "none";
+  waitSeconds?: number | undefined;
+  simulatePayer?: boolean | undefined;
+  /** The operator's console. Never the conversation. */
+  say: (line: string) => void;
+  /** The operator's keyboard, when there is one. Never the conversation. */
+  ask?: ((question: string) => Promise<string>) | undefined;
+}
+
+export interface ConverseResult {
+  turns: number;
+  replies: string[];
+  toolCalls: Array<{ name: string; refused: boolean }>;
+  executions: Execution[];
+}
+
+/** Keeps outbound messages in the order the run produced them, across await points. */
+class Outbox {
+  private chain: Promise<void> = Promise.resolve();
+
+  constructor(private readonly channel: WhatsAppChannel) {}
+
+  push(body: OutboundBody): void {
+    this.chain = this.chain.then(async () => {
+      await this.channel.send(body);
+    });
+  }
+
+  drain(): Promise<void> {
+    return this.chain;
+  }
+}
+
+export async function converse(options: ConverseOptions): Promise<ConverseResult> {
+  const { setup: s, channel, approver, say } = options;
+  const outbox = new Outbox(channel);
+  const replies: string[] = [];
+  const toolCalls: Array<{ name: string; refused: boolean }> = [];
+  let turns = 0;
+
+  const presentInstrument = (execution: Execution, instalment: number, chargeId: string, instrument: ChargeInstrument): Promise<void> => {
+    for (const body of instrumentBodies(execution, instalment, chargeId, instrument, s.mandate.currency)) outbox.push(body);
+    // Awaited by the poll: the person has the code in hand before the next look, not after the cycle closed.
+    return outbox.drain();
+  };
+
+  const terminalOptions: TerminalOptions = {
+    setup: s,
+    approver,
+    say,
+    tell: (line: string) => outbox.push({ kind: "text", text: line }),
+    presentInstrument,
+    ...(options.decision ? { decision: options.decision } : {}),
+    ...(options.ask ? { ask: options.ask } : {}),
+    ...(options.waitSeconds !== undefined ? { waitSeconds: options.waitSeconds } : {}),
+    ...(options.simulatePayer !== undefined ? { simulatePayer: options.simulatePayer } : {}),
+  };
+
+  // The channel is opened by the caller, which is where an emulator that is not
+  // running has to be reported: by here the run has already started.
+  const runtime = s.makeRuntime();
+  const loop = s.makeLoop(runtime, (execution) => handleExecution(execution, terminalOptions));
+
+  say(`${s.manifest.manifest.name} ${s.manifest.manifest.version} — canal: whatsapp (${channel.backend}) — approval: ${s.mode} — trilho: ${s.railKind} — ${s.kit.labels.mandateWord} ${s.mandate.id}`);
+
+  try {
+    for (;;) {
+      const message = await channel.next();
+      if (!message) break;
+      turns += 1;
+      const result = await loop.turn(message.text);
+      toolCalls.push(...result.tool_calls);
+      // Whatever the execution put in the conversation goes first: the QR before the sentence that explains it.
+      await outbox.drain();
+      if (result.reply.trim()) await channel.say(result.reply);
+      replies.push(result.reply);
+    }
+    await outbox.drain();
+  } finally {
+    await channel.close();
+  }
+
+  return { turns, replies, toolCalls, executions: s.engine.list().filter((e) => e.run_id === s.runId) };
+}

package/templates/hello-agent/packages/agent-runtime/src/channels/whatsapp/session.ts

@@ -0,0 +1,113 @@
+/**
+ * WhatsApp's own rule, which is not ours and which the simulator obeys
+ * anyway: outside the 24 hours that follow the person's last message, a
+ * business may only send a TEMPLATE that Meta approved in advance. Inside
+ * the window it may write freely.
+ *
+ * The simulator enforces it for the reason a simulator exists: something that
+ * only fails against the real provider is something you discover in
+ * production. A collections agent hits this constantly — the debtor answers
+ * on Tuesday, the charge is paid on Friday, and "recebemos, acordo quitado"
+ * falls outside the window.
+ *
+ * Template APPROVAL is a STUB and cannot be anything else from here: a
+ * template is registered in a Meta Business account, reviewed by Meta, and
+ * given a status we have no way to read without that account. What this holds
+ * is the LOCAL registry — the templates the agent declares it uses, from
+ * `channels/whatsapp/templates.json` — so sending one that was never declared
+ * is refused here instead of 400-ing at Meta. Whether Meta approved it is the
+ * developer's to check, and the README says so.
+ */
+import { templateArity, type WhatsAppTemplate } from "@codespar/agent-core";
+
+export const SESSION_WINDOW_SECONDS = 24 * 60 * 60;
+
+export interface SessionState {
+  /** Unix seconds of the last message the PERSON sent, on the provider's clock. */
+  lastInboundAt?: number | undefined;
+}
+
+/** Why a template send would be refused. `undefined` means it may go. */
+export type TemplateRefusal = { rule: string; detail: string } | undefined;
+
+export class SessionWindow {
+  private readonly templates: Map<string, WhatsAppTemplate>;
+  private lastInboundAt: number | undefined;
+
+  constructor(templates: readonly WhatsAppTemplate[], initial?: SessionState) {
+    this.templates = new Map(templates.map((t) => [t.name, t]));
+    this.lastInboundAt = initial?.lastInboundAt;
+  }
+
+  observeInbound(timestamp: number): void {
+    if (this.lastInboundAt === undefined || timestamp > this.lastInboundAt) this.lastInboundAt = timestamp;
+  }
+
+  /** Seconds left before free-form messages stop being allowed; 0 when the window is shut or was never opened. */
+  remainingSeconds(now: Date): number {
+    if (this.lastInboundAt === undefined) return 0;
+    return Math.max(0, this.lastInboundAt + SESSION_WINDOW_SECONDS - Math.floor(now.getTime() / 1000));
+  }
+
+  open(now: Date): boolean {
+    return this.remainingSeconds(now) > 0;
+  }
+
+  /** The declaration, for a caller that has to build a send: the language is the registry's, never the caller's guess. */
+  declared(name: string): WhatsAppTemplate | undefined {
+    return this.templates.get(name);
+  }
+
+  /**
+   * What the Cloud API would refuse about this template send, decided against
+   * the declaration. Three things are visible to a registry: a name nobody
+   * declared, a language the template was not registered in, and a variable
+   * count the body has no placeholders for. Meta answers each with a 4xx and
+   * delivers nothing, so each is refused here instead.
+   */
+  refuse(body: { template: string; language: string; variables: readonly string[] }): TemplateRefusal {
+    const declared = this.templates.get(body.template);
+    if (!declared) {
+      return {
+        rule: "template_unknown",
+        detail: `the agent declares no template named ${body.template}; Meta only delivers templates it approved, and this one was never registered here`,
+      };
+    }
+    if (declared.language !== body.language) {
+      return {
+        rule: "template_language_unknown",
+        detail: `${body.template} is declared in ${declared.language}, not ${body.language}; a template approved in one language does not exist in another`,
+      };
+    }
+    const expected = templateArity(declared.body);
+    if (body.variables.length !== expected) {
+      return { rule: "template_variables_mismatch", detail: `${body.template} takes ${expected} variable(s) and this send carries ${body.variables.length}` };
+    }
+    return undefined;
+  }
+}
+
+/**
+ * Where a conversation's window stood, read back from a bundle's
+ * `channel.jsonl`. This is what lets a later process — a poll, days after the
+ * run that opened the conversation — know whether it may still write freely,
+ * instead of assuming the worst and always sending a template.
+ *
+ * It reads the PROVIDER's timestamp and never the line's `at`, which is the
+ * run's own clock: the 24 hours are counted by WhatsApp on WhatsApp's clock,
+ * and a record written by a machine whose clock drifted is not evidence about
+ * theirs. A log carrying no provider timestamp on any inbound line yields no
+ * state, and the window then reads as SHUT — the safe direction, because a
+ * template is deliverable in both halves of the rule and a free-form message
+ * is deliverable in one.
+ */
+export function sessionStateFromChannelLog(lines: ReadonlyArray<Record<string, unknown>>): SessionState {
+  let lastInboundAt: number | undefined;
+  for (const line of lines) {
+    if (line["direction"] !== "in") continue;
+    const at = line["provider_timestamp"];
+    if (typeof at !== "number" || !Number.isFinite(at)) continue;
+    if (lastInboundAt === undefined || at > lastInboundAt) lastInboundAt = at;
+  }
+  return { lastInboundAt };
+}

package/templates/hello-agent/packages/agent-runtime/src/cli.ts

@@ -0,0 +1,98 @@
+/**
+ * `codespar-agent <command> [args]`. The agent is the working directory; the
+ * command is this runner's, the same for every agent. What differs between
+ * agents is behind `kit`.
+ */
+import { stderr } from "node:process";
+import { loadAgent, type Agent } from "./agent.js";
+import { readDotEnv } from "./setup.js";
+import { check } from "./commands/check.js";
+import { decide } from "./commands/decide.js";
+import { runEval } from "./commands/eval.js";
+import { inspect } from "./commands/inspect.js";
+import { poll } from "./commands/poll.js";
+import { reconcile } from "./commands/reconcile.js";
+import { rerun } from "./commands/rerun.js";
+import { resume } from "./commands/resume.js";
+import { start } from "./commands/start.js";
+import { verify } from "./commands/verify.js";
+import { webhook } from "./commands/webhook.js";
+
+const COMMANDS = ["start", "consent", "approve", "deny", "resume", "rerun", "reconcile", "inspect", "poll", "webhook", "check", "eval", "verify"] as const;
+
+/** Commands that are not about an agent. `verify` reads a receipt file and a
+ *  public key set, which is all a party outside CodeSpar has: requiring an
+ *  `agent.yaml` above the working directory would mean the verifier needed the
+ *  agent that produced the receipt, and the whole point is that it does not. */
+const AGENTLESS: readonly string[] = ["verify"];
+
+export async function main(argv: string[] = process.argv.slice(2)): Promise<number> {
+  const rest = [...argv];
+  let dir: string | undefined;
+  const at = rest.indexOf("--agent");
+  if (at >= 0) {
+    dir = rest[at + 1];
+    rest.splice(at, dir === undefined ? 1 : 2);
+  }
+  const first = rest[0];
+  const command = first !== undefined && !first.startsWith("-") ? rest.shift()! : "start";
+  if (!(COMMANDS as readonly string[]).includes(command)) {
+    stderr.write(`unknown command ${command}; one of: ${COMMANDS.join(", ")}\n`);
+    return 2;
+  }
+  if (AGENTLESS.includes(command)) return verify(rest);
+  const agent = await loadAgent(dir);
+  readDotEnv(agent.dir);
+  return run(agent, command, rest);
+}
+
+async function run(agent: Agent, command: string, argv: string[]): Promise<number> {
+  const awaitsPayer = agent.settlement === "await-payer";
+  switch (command) {
+    case "start":
+      return start(agent, argv);
+    case "consent": {
+      if (!agent.kit.consent) {
+        stderr.write(`${agent.slug}: this agent has no consent step (its policy is its own file, not a signed mandate)\n`);
+        return 2;
+      }
+      return agent.kit.consent({ agentDir: agent.dir, argv, say: (l) => void stderr.write(l + "\n") });
+    }
+    case "approve":
+      return decide(agent, "approve", argv);
+    case "deny":
+      return decide(agent, "deny", argv);
+    case "resume":
+      return resume(agent, argv);
+    case "rerun":
+      return rerun(agent, argv);
+    case "reconcile":
+      return reconcile(agent, argv);
+    case "inspect":
+      return inspect(agent, argv);
+    case "check":
+      return check(agent, argv);
+    case "eval":
+      return runEval(agent, argv);
+    case "poll":
+    case "webhook": {
+      if (!awaitsPayer) {
+        stderr.write(`${agent.slug}: ${command} is for an agent that waits for a payer; this one settles on the rail's answer\n`);
+        return 2;
+      }
+      return command === "poll" ? poll(agent, argv) : webhook(agent, argv);
+    }
+    default:
+      stderr.write(`unknown command ${command}\n`);
+      return 2;
+  }
+}
+
+if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) {
+  main()
+    .then((code) => process.exit(code))
+    .catch((err) => {
+      stderr.write(`${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+      process.exit(1);
+    });
+}

package/templates/hello-agent/packages/agent-runtime/src/commands/check.ts

@@ -0,0 +1,15 @@
+/**
+ * `codespar-agent check [--json]`: the manifest-coherence gate of section 4.3.
+ */
+import { stderr, stdout } from "node:process";
+import { checkAgent } from "@codespar/agent-core";
+import type { Agent } from "../agent.js";
+
+export function check(agent: Agent, argv: string[]): number {
+  const json = argv.includes("--json");
+  const report = checkAgent(agent.dir);
+  if (json) stdout.write(JSON.stringify(report) + "\n");
+  for (const f of report.findings) stderr.write(`${f.level === "error" ? "ERROR" : "warn "} ${f.code}: ${f.message}\n`);
+  stderr.write(report.ok ? `check ok: ${report.agent} agrees with its agent.yaml\n` : `check FAILED for ${report.agent ?? "agent"}\n`);
+  return report.ok ? 0 : 1;
+}

package/templates/hello-agent/packages/agent-runtime/src/commands/decide.ts

@@ -0,0 +1,63 @@
+/**
+ * `codespar-agent approve|deny <execution-id> [--user <id>] [--json]`:
+ * decides an execution left in `awaiting_approval` (a `--input` run without
+ * `--approve`, a restart). Produces the section 4.2 artifact and runs the
+ * execution through the same last gate `start` uses.
+ */
+import { relative } from "node:path";
+import { stderr, stdout } from "node:process";
+import type { Agent } from "../agent.js";
+import { setup } from "../setup.js";
+import { handleExecution } from "../terminal.js";
+
+export async function decide(agent: Agent, decision: "approve" | "deny", argv: string[]): Promise<number> {
+  const awaitsPayer = agent.settlement === "await-payer";
+  const json = argv.includes("--json");
+  const user = argv.includes("--user") ? argv[argv.indexOf("--user") + 1] : undefined;
+  const wait = awaitsPayer && argv.includes("--wait") ? Number(argv[argv.indexOf("--wait") + 1]) : undefined;
+  const simulatePayer = awaitsPayer && argv.includes("--simulate-payer");
+  const executionId = argv.find((a, i) => !a.startsWith("--") && argv[i - 1] !== "--user" && (!awaitsPayer || argv[i - 1] !== "--wait"));
+  const say = (l: string) => stderr.write(l + "\n");
+  if (!executionId) {
+    say(`usage: npm run ${decision} <execution-id> [--user <id>]${awaitsPayer ? " [--wait <seconds>] [--simulate-payer]" : ""} [--json]`);
+    return 2;
+  }
+  const s = setup(agent, { say, runId: `run_${decision}_${Date.now().toString(36)}` });
+  try {
+    const execution = s.engine.get(executionId);
+    if (!execution) {
+      say(`unknown execution ${executionId}`);
+      return 1;
+    }
+    if (execution.state !== "awaiting_approval") {
+      say(`${executionId} is ${execution.state}, not awaiting_approval; nothing to decide`);
+      return 1;
+    }
+    const final = await handleExecution(execution, {
+      setup: s,
+      approver: { id: user ?? s.kit.labels.defaultUser, channel: "terminal" },
+      decision,
+      say,
+      ...(json ? { tell: say } : {}),
+      waitSeconds: wait,
+      simulatePayer,
+    });
+    if (json) {
+      stdout.write(
+        JSON.stringify({
+          execution_id: final.id,
+          state: final.state,
+          reason: final.reason ?? null,
+          approval_id: final.approval_id ?? null,
+          ...(awaitsPayer ? { charge_ids: final.outcomes.map((o) => o.transaction_id ?? null) } : {}),
+          receipt_ids: final.outcomes.filter((o) => o.receipt_id).map((o) => o.receipt_id),
+          bundle_dir: relative(process.cwd(), s.bundle.dir),
+        }) + "\n",
+      );
+    }
+    if (awaitsPayer) return final.state === "executing" && final.reason !== "awaiting_settlement" ? 3 : 0;
+    return final.state === "executing" ? 3 : 0;
+  } finally {
+    s.close();
+  }
+}

package/templates/hello-agent/packages/agent-runtime/src/commands/eval.ts

@@ -0,0 +1,58 @@
+/**
+ * `codespar-agent eval [--json] [--case <name>]`: the adversarial suite of
+ * section 9 plus every scenario of section 12 in every mode it declares. Runs
+ * on the replay provider and the stub rail, with no model and no network. A
+ * regression blocks merge.
+ */
+import { stderr, stdout } from "node:process";
+import type { Agent } from "../agent.js";
+import { listAdversarialCases, loadAdversarialCase, runAdversarialCase, type AdversarialResult } from "../adversarial.js";
+import { checkScenario, listScenarios, loadScenario, runScenario, type ScenarioCheck } from "../scenarios.js";
+
+export async function runEval(agent: Agent, argv: string[]): Promise<number> {
+  const json = argv.includes("--json");
+  const only = argv.includes("--case") ? argv[argv.indexOf("--case") + 1] : undefined;
+  const say = (l: string) => stderr.write(l + "\n");
+  const awaitsPayer = agent.settlement === "await-payer";
+
+  const adversarial = [];
+  for (const name of listAdversarialCases(agent)) {
+    if (only && only !== name) continue;
+    const result = await runAdversarialCase(agent, loadAdversarialCase(agent, name));
+    adversarial.push(result);
+    say(agent.kit.evalAdversarialLine?.(result) ?? adversarialLine(result));
+  }
+
+  const scenarios = [];
+  for (const name of listScenarios(agent)) {
+    if (only && only !== name) continue;
+    const scenario = loadScenario(agent, name);
+    if (!scenario.rails.includes("stub")) continue;
+    for (const mode of scenario.modes) {
+      const check = checkScenario(scenario, await runScenario(agent, scenario, { mode, rail: "stub" }));
+      scenarios.push({
+        name,
+        mode,
+        ok: check.ok,
+        failures: check.failures,
+        states: check.run.executions.map((e) => e.state),
+        receipts: check.run.receipts,
+        ...(awaitsPayer ? { charges_issued: check.run.charges_issued, debtor_messages: check.run.debtor_messages } : {}),
+      });
+      say(agent.kit.evalScenarioLine?.(check) ?? scenarioLine(check));
+    }
+  }
+
+  const ok = adversarial.every((r) => r.ok) && scenarios.every((r) => r.ok);
+  if (json) stdout.write(JSON.stringify({ ok, adversarial, scenarios }) + "\n");
+  say(ok ? `eval ok: ${adversarial.length} adversarial case(s), ${scenarios.length} scenario run(s)` : "eval FAILED");
+  return ok ? 0 : 1;
+}
+
+function adversarialLine(result: AdversarialResult): string {
+  return `${result.ok ? "ok  " : "FAIL"} adversarial/${result.name} — ${result.attack} — states ${JSON.stringify(result.states)}${result.failures.length ? ` — ${result.failures.join("; ")}` : ""}`;
+}
+
+function scenarioLine(check: ScenarioCheck): string {
+  return `${check.ok ? "ok  " : "FAIL"} scenario/${check.run.scenario} [${check.mode}] — states ${JSON.stringify(check.run.executions.map((e) => e.state))}, ${check.run.receipts} receipt(s)${check.failures.length ? ` — ${check.failures.join("; ")}` : ""}`;
+}

package/templates/hello-agent/packages/agent-runtime/src/commands/inspect.ts

@@ -0,0 +1,100 @@
+/**
+ * `codespar-agent inspect <run-id> [--json] [--html <path>]`: the proof bundle
+ * of section 11 read back as a timeline. Defaults to the terminal rendering;
+ * `--json` follows the rule of section 14.5 — machine data on stdout, valid
+ * JSON and nothing else, human messages on stderr.
+ *
+ * It reads the bundle and nothing else, so it works on any agent's run, and
+ * on a folder copied off the machine that produced it.
+ */
+import { existsSync, readdirSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { stderr, stdout } from "node:process";
+import { ProofBundle } from "@codespar/agent-core";
+import type { Agent } from "../agent.js";
+import { runsDir } from "../setup.js";
+import { assembleTimeline, renderHtml, renderText } from "../inspect.js";
+
+const USAGE = "usage: npm run inspect <run-id> [--json] [--html <file>]";
+
+export function inspect(agent: Agent, argv: string[]): number {
+  const say = (line: string) => stderr.write(line + "\n");
+  let json = false;
+  let html: string | undefined;
+  let runId: string | undefined;
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i]!;
+    if (a === "--json") json = true;
+    else if (a === "--html") {
+      const value = argv[i + 1];
+      if (value === undefined || value.startsWith("--")) {
+        say(`--html needs a file path\n${USAGE}`);
+        return 2;
+      }
+      html = value;
+      i += 1;
+    } else if (a === "--help" || a === "-h") {
+      say(USAGE);
+      return 0;
+    } else if (a.startsWith("-")) {
+      say(`unknown argument ${a}\n${USAGE}`);
+      return 2;
+    } else if (runId === undefined) runId = a;
+    else {
+      say(`inspect takes one run id (got ${runId} and ${a})\n${USAGE}`);
+      return 2;
+    }
+  }
+
+  const runs = runsDir(agent);
+  if (!runId) {
+    say(USAGE);
+    say(available(runs));
+    return 2;
+  }
+
+  // An unknown run id is a refusal a person can act on, never a stack trace.
+  const bundle = ProofBundle.open(runs, runId);
+  if (!bundle) {
+    say(`no proof bundle for run ${runId}: nothing at ${resolve(runs, runId)}`);
+    say(available(runs));
+    return 1;
+  }
+
+  // A bundle half-written by a run that was killed is exactly when somebody looks at it: say which file is unreadable, do not throw a stack at them.
+  let report;
+  try {
+    report = assembleTimeline(bundle);
+  } catch (err) {
+    say(`the bundle at ${bundle.dir} could not be read: ${err instanceof Error ? err.message : String(err)}`);
+    say("a file in it is missing or not valid JSON; the folder is the run's own output and is safe to delete and re-run");
+    return 1;
+  }
+
+  if (html) {
+    try {
+      writeFileSync(html, renderHtml(report));
+    } catch (err) {
+      say(`could not write ${resolve(html)}: ${err instanceof Error ? err.message : String(err)}`);
+      return 1;
+    }
+    say(`wrote ${resolve(html)} — one file, no network, opens from disk`);
+  }
+  if (json) stdout.write(JSON.stringify(report) + "\n");
+  else stdout.write(renderText(report));
+  return 0;
+}
+
+/** What the person can inspect instead. Bounded: a long-lived agent has many runs and this is an error message, not a listing command. */
+function available(runs: string): string {
+  if (!existsSync(runs)) return `no runs yet: ${runs} does not exist. Run the agent once, then inspect the run id it printed.`;
+  const ids = readdirSync(runs, { withFileTypes: true })
+    .filter((e) => e.isDirectory())
+    .map((e) => e.name)
+    .sort()
+    .reverse();
+  if (!ids.length) return `no runs yet in ${runs}. Run the agent once, then inspect the run id it printed.`;
+  const shown = ids.slice(0, 10);
+  return `runs in ${runs}${ids.length > shown.length ? ` (newest ${shown.length} of ${ids.length})` : ""}:\n${shown.map((id) => `  ${id}`).join("\n")}`;
+}