@codespar/cli 0.14.1 → 0.17.0

package/templates/bills-agent/agents/bills-agent/test/check.test.ts

@@ -57,10 +57,27 @@ describe("npm run check: the manifest is the index", () => {
     }
   });
 
-  it("fails when a README claims third-party verifiability or .env.example grows a third key", () => {
+  it("fails when a doc claims third-party verifiability and never says which signature it means", () => {
     const dir = copyAgent();
-    writeFileSync(join(dir, "README.md"), readFileSync(join(dir, "README.md"), "utf8") + "\nO recibo é verificável por terceiro.\n");
+    // The claim with no mechanism named: true of the Ed25519 seal on a receipt, false of the approval artifact and of every receipt sealed before it.
+    writeFileSync(join(dir, "README.md"), "# bills-agent\n\nO recibo é verificável por terceiro.\n");
     expect(codes(dir)).toContain("doc_overclaims");
+    // The same claim, with the mechanism named: allowed, and what the shipped README does.
+    writeFileSync(join(dir, "README.md"), "# bills-agent\n\nO recibo é verificável por terceiro: a assinatura Ed25519 confere contra as chaves públicas.\n");
+    expect(codes(dir)).not.toContain("doc_overclaims");
+  });
+
+
+  it("refuses the claim, mechanism named and all, when the agent itself says receipt-verification is blocked", () => {
+    const dir = copyAgent();
+    writeFileSync(join(dir, "README.md"), readFileSync(join(dir, "README.md"), "utf8") + "\nThe receipt is third-party verifiable: the Ed25519 signature checks against the published keys.\n");
+    expect(codes(dir)).not.toContain("doc_overclaims");
+    writeFileSync(join(dir, "agent.yaml"), readFileSync(join(dir, "agent.yaml"), "utf8").replace("receipt-verification: sandbox", "receipt-verification: blocked"));
+    expect(codes(dir)).toContain("doc_overclaims");
+  });
+
+  it("fails when .env.example grows a third key", () => {
+    const dir = copyAgent();
     writeFileSync(join(dir, ".env.example"), readFileSync(join(dir, ".env.example"), "utf8") + "APPROVAL_KEY=x\n");
     expect(codes(dir)).toContain("env_example_extra");
   });

package/templates/bills-agent/agents/bills-agent/test/cli.test.ts

@@ -11,9 +11,10 @@ import { describe, expect, it } from "vitest";
 
 const AGENT_DIR = resolve(import.meta.dirname, "..");
 const NODE = process.execPath;
+const BIN = resolve(AGENT_DIR, "../../packages/agent-runtime/bin.mjs");
 
-function run(script: string, args: string[], env: Record<string, string>) {
-  const result = spawnSync(NODE, ["--disable-warning=ExperimentalWarning", "--import", "tsx", script, ...args], {
+function run(command: string, args: string[], env: Record<string, string>) {
+  const result = spawnSync(NODE, [BIN, command, ...args], {
     cwd: AGENT_DIR,
     env: { ...process.env, ANTHROPIC_API_KEY: "", CODESPAR_API_KEY: "", ...env },
     encoding: "utf8",
@@ -25,7 +26,7 @@ function run(script: string, args: string[], env: Record<string, string>) {
 describe("npm start -- --input ... --json", () => {
   it("prints valid JSON on stdout and nothing else; people go to stderr", () => {
     const stateDir = mkdtempSync(join(tmpdir(), "bills-json-"));
-    const out = run("src/main.ts", ["--input", "pague a escola de outubro", "--approve", "--json"], { BILLS_STATE_DIR: stateDir, BILLS_RUNS_DIR: join(stateDir, "runs") });
+    const out = run("start", ["--input", "pague a escola de outubro", "--approve", "--json"], { BILLS_STATE_DIR: stateDir, BILLS_RUNS_DIR: join(stateDir, "runs") });
     expect(out.code).toBe(0);
     const lines = out.stdout.split("\n").filter(Boolean);
     expect(lines).toHaveLength(1);
@@ -37,22 +38,66 @@ describe("npm start -- --input ... --json", () => {
     expect(out.stderr).toContain("replay");
   });
 
+  it("replays when ANTHROPIC_API_KEY still holds the .env.example placeholder", () => {
+    const stateDir = mkdtempSync(join(tmpdir(), "bills-placeholder-"));
+    const out = run("start", ["--input", "pague a escola de outubro", "--approve", "--json"], { BILLS_STATE_DIR: stateDir, BILLS_RUNS_DIR: join(stateDir, "runs"), ANTHROPIC_API_KEY: "sk-ant-your_key_here" });
+    expect(out.code).toBe(0);
+    expect(out.stderr).toContain("[replay] no ANTHROPIC_API_KEY");
+    const payload = JSON.parse(out.stdout.trim()) as { executions: Array<{ state: string }> };
+    expect(payload.executions.map((e) => e.state)).toEqual(["settled"]);
+  });
+
   it("refuses a key outside csk_test_ before anything else", () => {
     const stateDir = mkdtempSync(join(tmpdir(), "bills-live-"));
-    const out = run("src/main.ts", ["--input", "pague a escola de outubro", "--json"], { BILLS_STATE_DIR: stateDir, CODESPAR_API_KEY: ["csk", "live", "0000000000"].join("_") });
+    const out = run("start", ["--input", "pague a escola de outubro", "--json"], { BILLS_STATE_DIR: stateDir, CODESPAR_API_KEY: ["csk", "live", "0000000000"].join("_") });
     expect(out.code).toBe(1);
     expect(out.stdout).toBe("");
     expect(out.stderr).toContain("csk_test_");
   });
 });
 
+// #16: `escalate_above.outside_hours` (22:00-07:00) reads the engine clock too. The escalation order is amount, new_beneficiary,
+// outside_hours, so the hour can only be the trigger on a payee the mandate already knows, below the amount threshold: the
+// state is seeded with one settled payment to the school first, in its own process, the way a real day would.
+describe("--now pins the clock the mandate-mode escalation reads", () => {
+  function seedKnownPayee(label: string): Record<string, string> {
+    const stateDir = mkdtempSync(join(tmpdir(), `bills-now-${label}-`));
+    const env = { BILLS_STATE_DIR: stateDir, BILLS_RUNS_DIR: join(stateDir, "runs") };
+    const seed = run("start", ["--mode", "mandate", "--input", "paga 400 reais pra escola (material)", "--transcript", "test/fixtures/material-400.transcript.jsonl", "--approve", "--json", "--now", "2026-09-23T14:00:00-03:00"], env);
+    expect(seed.code).toBe(0);
+    const payload = JSON.parse(seed.stdout.trim()) as { executions: Array<{ state: string; escalation: { trigger: string } | null }> };
+    expect(payload.executions[0]).toMatchObject({ state: "settled", escalation: { trigger: "new_beneficiary" } });
+    return env;
+  }
+  const EXCURSAO = ["--mode", "mandate", "--input", "e mais 300 reais pra escola, a excursao", "--transcript", "test/fixtures/excursao-300.transcript.jsonl", "--json"];
+  type Payload = { executions: Array<{ state: string; escalation: { trigger: string; detail: string } | null; receipt_ids: string[] }> };
+
+  it("at 23:00 America/Sao_Paulo a payment inside the mandate is escalated (outside_hours) and waits for a human", () => {
+    const out = run("start", [...EXCURSAO, "--now", "2026-09-23T23:00:00-03:00"], seedKnownPayee("night"));
+    expect(out.code).toBe(0);
+    const payload = JSON.parse(out.stdout.trim()) as Payload;
+    expect(payload.executions).toHaveLength(1);
+    expect(payload.executions[0]).toMatchObject({ state: "awaiting_approval", escalation: { trigger: "outside_hours" } });
+    expect(payload.executions[0]?.escalation?.detail).toContain("23:00");
+    expect(payload.executions[0]?.receipt_ids).toEqual([]);
+  });
+
+  it("at 14:00 America/Sao_Paulo the same payment runs alone: no trigger, one receipt", () => {
+    const out = run("start", [...EXCURSAO, "--now", "2026-09-23T14:00:00-03:00"], seedKnownPayee("day"));
+    expect(out.code).toBe(0);
+    const payload = JSON.parse(out.stdout.trim()) as Payload;
+    expect(payload.executions[0]).toMatchObject({ state: "settled", escalation: null });
+    expect(payload.executions[0]?.receipt_ids).toHaveLength(1);
+  });
+});
+
 describe("section 10: restart in executing, then resume", () => {
   it("one payment, one receipt, never two", () => {
     const stateDir = mkdtempSync(join(tmpdir(), "bills-restart-"));
     const runsDir = join(stateDir, "runs");
     const env = { BILLS_STATE_DIR: stateDir, BILLS_RUNS_DIR: runsDir };
 
-    const killed = run("src/main.ts", ["--input", "pague a escola de outubro", "--approve", "--json"], { ...env, BILLS_KILL_AFTER_DISPATCH: "1" });
+    const killed = run("start", ["--input", "pague a escola de outubro", "--approve", "--json"], { ...env, BILLS_KILL_AFTER_DISPATCH: "1" });
     expect(killed.code).toBe(137);
     expect(killed.stdout).toBe("");
 
@@ -62,7 +107,7 @@ describe("section 10: restart in executing, then resume", () => {
     expect((db.prepare("SELECT COUNT(*) AS n FROM stub_rail_attempts").get() as { n: number }).n).toBe(1);
     db.close();
 
-    const resumed = run("src/commands/resume.ts", ["--json"], env);
+    const resumed = run("resume", ["--json"], env);
     expect(resumed.code).toBe(0);
     const payload = JSON.parse(resumed.stdout.trim()) as { resumed: Array<{ state: string; receipt_ids: string[] }> };
     expect(payload.resumed).toHaveLength(1);
@@ -78,7 +123,7 @@ describe("section 10: restart in executing, then resume", () => {
     const receipts = readdirSync(runsDir).flatMap((r) => (existsSync(join(runsDir, r, "receipts")) ? readdirSync(join(runsDir, r, "receipts")) : []));
     expect(receipts).toHaveLength(1);
 
-    const again = run("src/commands/resume.ts", ["--json"], env);
+    const again = run("resume", ["--json"], env);
     expect(JSON.parse(again.stdout.trim())).toMatchObject({ resumed: [] });
   });
 });
@@ -88,10 +133,10 @@ describe("npm run rerun <run-id>", () => {
     const stateDir = mkdtempSync(join(tmpdir(), "bills-rerun-"));
     const runsDir = join(stateDir, "runs");
     const env = { BILLS_STATE_DIR: stateDir, BILLS_RUNS_DIR: runsDir };
-    const first = run("src/main.ts", ["--input", "pague a escola de outubro", "--approve", "--json"], env);
+    const first = run("start", ["--input", "pague a escola de outubro", "--approve", "--json"], env);
     expect(first.code).toBe(0);
     const { run_id } = JSON.parse(first.stdout.trim()) as { run_id: string };
-    const rerun = run("src/commands/rerun.ts", [run_id, "--json"], env);
+    const rerun = run("rerun", [run_id, "--json"], env);
     expect(rerun.code).toBe(0);
     const payload = JSON.parse(rerun.stdout.trim()) as { same_states: boolean; original: string[]; rerun: string[] };
     expect(payload.same_states).toBe(true);
@@ -102,7 +147,7 @@ describe("npm run rerun <run-id>", () => {
 
 describe("npm run check", () => {
   it("is green for the shipped agent and prints JSON with --json", () => {
-    const out = run("src/commands/check.ts", ["--json"], {});
+    const out = run("check", ["--json"], {});
     expect(out.code).toBe(0);
     const report = JSON.parse(out.stdout.trim()) as { ok: boolean; agent: string; findings: unknown[] };
     expect(report).toMatchObject({ ok: true, agent: "bills-agent" });
@@ -115,16 +160,16 @@ describe("npm run approve / deny <execution-id>", () => {
     const stateDir = mkdtempSync(join(tmpdir(), "bills-decide-"));
     const runsDir = join(stateDir, "runs");
     const env = { BILLS_STATE_DIR: stateDir, BILLS_RUNS_DIR: runsDir };
-    const left = run("src/main.ts", ["--input", "pague a escola de outubro", "--json"], env);
+    const left = run("start", ["--input", "pague a escola de outubro", "--json"], env);
     expect(left.code).toBe(0);
     const payload = JSON.parse(left.stdout.trim()) as { executions: Array<{ id: string; state: string }> };
     expect(payload.executions[0]?.state).toBe("awaiting_approval");
     const id = payload.executions[0]!.id;
 
-    const denied = run("src/commands/deny.ts", ["nope_unknown", "--json"], env);
+    const denied = run("deny", ["nope_unknown", "--json"], env);
     expect(denied.code).toBe(1);
 
-    const approved = run("src/commands/approve.ts", [id, "--user", "usr_titular", "--json"], env);
+    const approved = run("approve", [id, "--user", "usr_titular", "--json"], env);
     expect(approved.code).toBe(0);
     const out = JSON.parse(approved.stdout.trim()) as { state: string; approval_id: string | null; receipt_ids: string[]; bundle_dir: string };
     expect(out.state).toBe("settled");
@@ -133,7 +178,7 @@ describe("npm run approve / deny <execution-id>", () => {
     const artifacts = JSON.parse(readFileSync(join(AGENT_DIR, out.bundle_dir, "approval.json"), "utf8")) as Array<{ approver: { type: string; id: string } }>;
     expect(artifacts[0]?.approver).toEqual({ type: "person", id: "usr_titular", channel: "terminal" });
 
-    const again = run("src/commands/approve.ts", [id, "--json"], env);
+    const again = run("approve", [id, "--json"], env);
     expect(again.code).toBe(1);
     expect(again.stderr).toContain("not awaiting_approval");
   });
@@ -141,9 +186,9 @@ describe("npm run approve / deny <execution-id>", () => {
   it("deny leaves a terminal denied execution and sends nothing", () => {
     const stateDir = mkdtempSync(join(tmpdir(), "bills-deny-"));
     const env = { BILLS_STATE_DIR: stateDir, BILLS_RUNS_DIR: join(stateDir, "runs") };
-    const left = run("src/main.ts", ["--input", "pague a escola de outubro", "--json"], env);
+    const left = run("start", ["--input", "pague a escola de outubro", "--json"], env);
     const id = (JSON.parse(left.stdout.trim()) as { executions: Array<{ id: string }> }).executions[0]!.id;
-    const denied = run("src/commands/deny.ts", [id, "--json"], env);
+    const denied = run("deny", [id, "--json"], env);
     expect(denied.code).toBe(0);
     expect(JSON.parse(denied.stdout.trim())).toMatchObject({ state: "denied", reason: "denied_by_approver", receipt_ids: [] });
     const db = new DatabaseSync(join(stateDir, "state.db"));
@@ -153,25 +198,28 @@ describe("npm run approve / deny <execution-id>", () => {
 });
 
 describe("partial failure of a multi-item execution, and rerun reproducing it", () => {
-  it("names what settled and what failed, and rerun replays the rail's refusal", () => {
+  it("pays every bill the rail accepted, names the one it refused, and rerun replays the refusal", () => {
     const stateDir = mkdtempSync(join(tmpdir(), "bills-partial-"));
     const runsDir = join(stateDir, "runs");
     const env = { BILLS_STATE_DIR: stateDir, BILLS_RUNS_DIR: runsDir, BILLS_STUB_REFUSE: "+5511999990001" };
-    const first = run("src/main.ts", ["--input", "libera o lote do mes", "--transcript", "evals/adversarial/false-authority.transcript.jsonl", "--approve", "--json"], env);
+    const first = run("start", ["--input", "libera o lote do mes", "--transcript", "evals/adversarial/false-authority.transcript.jsonl", "--approve", "--json"], env);
     expect(first.code).toBe(0);
     const payload = JSON.parse(first.stdout.trim()) as { run_id: string; executions: Array<{ state: string; receipt_ids: string[] }>; receipts: string[] };
+    // Four bills, the SECOND refused by the rail. The execution closes `failed`
+    // because one attempt failed, and the two bills after the refused one are
+    // paid all the same: an attempt's outcome is that attempt's business.
     expect(payload.executions[0]?.state).toBe("failed");
-    expect(payload.executions[0]?.receipt_ids).toHaveLength(1);
-    expect(payload.receipts).toHaveLength(1);
+    expect(payload.executions[0]?.receipt_ids).toHaveLength(3);
+    expect(payload.receipts).toHaveLength(3);
     const events = readFileSync(join(runsDir, payload.run_id, "events.jsonl"), "utf8").split("\n").filter(Boolean).map((l) => JSON.parse(l) as { type: string; payload: { status?: string } });
-    expect(events.filter((e) => e.type === "rail.outcome").map((e) => e.payload.status)).toEqual(["settled", "failed"]);
+    expect(events.filter((e) => e.type === "rail.outcome").map((e) => e.payload.status)).toEqual(["settled", "failed", "settled", "settled"]);
 
-    const rerun = run("src/commands/rerun.ts", [payload.run_id, "--json"], { BILLS_STATE_DIR: stateDir, BILLS_RUNS_DIR: runsDir });
+    const rerun = run("rerun", [payload.run_id, "--json"], { BILLS_STATE_DIR: stateDir, BILLS_RUNS_DIR: runsDir });
     expect(rerun.code).toBe(0);
     const r = JSON.parse(rerun.stdout.trim()) as { same_states: boolean; original: string[]; rerun: string[]; original_outcomes: string[]; rerun_outcomes: string[] };
     expect(r.same_states).toBe(true);
     expect(r.original).toEqual(["awaiting_approval", "approved", "executing", "failed"]);
-    expect(r.original_outcomes).toEqual(["settled", "failed"]);
-    expect(r.rerun_outcomes).toEqual(["settled", "failed"]);
+    expect(r.original_outcomes).toEqual(["settled", "failed", "settled", "settled"]);
+    expect(r.rerun_outcomes).toEqual(["settled", "failed", "settled", "settled"]);
   });
 });

package/templates/bills-agent/agents/bills-agent/test/fixtures/excursao-300.transcript.jsonl

@@ -0,0 +1,2 @@
+{"kind":"assistant_step","tool_calls":[{"id":"tc_4","name":"codespar_pay","input":{"action":"pix","items":[{"payee":"escola","amount_minor":30000,"description":"excursao"}]}}]}
+{"kind":"assistant_step","reply":"Paguei R$ 300,00 para a Escola Aurora (excursao) dentro da alcada; o recibo esta no terminal."}

package/templates/bills-agent/agents/bills-agent/test/fixtures/material-400.transcript.jsonl

@@ -0,0 +1,2 @@
+{"kind":"assistant_step","tool_calls":[{"id":"tc_1","name":"codespar_pay","input":{"action":"pix","items":[{"payee":"escola","amount_minor":40000,"description":"material"}]}}]}
+{"kind":"assistant_step","reply":"Propus R$ 400,00 para a Escola Aurora (material). Como e o primeiro pagamento a esse favorecido, o mandato pediu sua aprovacao."}

package/templates/bills-agent/agents/bills-agent/test/inspect.test.ts

@@ -0,0 +1,124 @@
+/**
+ * `inspect` through a real process: the section 14.5 rule (`--json` puts valid
+ * JSON on stdout and nothing else), the refusal on a run id that is not there,
+ * and the HTML file that opens from disk with nothing fetched.
+ */
+import { spawnSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { beforeAll, describe, expect, it } from "vitest";
+
+const AGENT_DIR = resolve(import.meta.dirname, "..");
+const NODE = process.execPath;
+const BIN = resolve(AGENT_DIR, "../../packages/agent-runtime/bin.mjs");
+
+function run(command: string, args: string[], env: Record<string, string>) {
+  const result = spawnSync(NODE, [BIN, command, ...args], {
+    cwd: AGENT_DIR,
+    env: { ...process.env, ANTHROPIC_API_KEY: "", CODESPAR_API_KEY: "", ...env },
+    encoding: "utf8",
+    timeout: 60_000,
+  });
+  return { code: result.status, stdout: result.stdout, stderr: result.stderr };
+}
+
+describe("codespar-agent inspect", () => {
+  let env: Record<string, string>;
+  let runId: string;
+  let runs: string;
+
+  beforeAll(() => {
+    const stateDir = mkdtempSync(join(tmpdir(), "bills-inspect-"));
+    runs = join(stateDir, "runs");
+    env = { BILLS_STATE_DIR: stateDir, BILLS_RUNS_DIR: runs };
+    const paid = run("start", ["--input", "pague a escola de outubro", "--approve", "--json", "--now", "2026-09-23T14:00:00-03:00"], env);
+    expect(paid.code).toBe(0);
+    runId = (JSON.parse(paid.stdout.trim()) as { run_id: string }).run_id;
+  });
+
+  it("--json puts valid JSON on stdout and nothing else", () => {
+    const out = run("inspect", [runId, "--json"], env);
+    expect(out.code).toBe(0);
+    const lines = out.stdout.split("\n").filter(Boolean);
+    expect(lines).toHaveLength(1);
+    const report = JSON.parse(lines[0]!) as {
+      run: { run_id: string; mode: string; rail: string; mandate_id: string; mandate_version: number };
+      executions: Array<{ final_state: string; approval: { items_hash: string } | null; transitions: Array<{ to: string; actor: string }>; attempts: Array<{ idempotency_key: string; answer: { status: string; receipt_id: string } }> }>;
+      receipts: Array<{ receipt_id: string }>;
+      verify: { present: boolean; note: string };
+    };
+    expect(report.run).toMatchObject({ run_id: runId, mode: "human", rail: "stub" });
+    expect(report.run.mandate_version).toBe(1);
+    const execution = report.executions[0]!;
+    expect(execution.final_state).toBe("settled");
+    expect(execution.transitions.map((t) => t.to)).toEqual(["awaiting_approval", "approved", "executing", "settled"]);
+    expect(execution.approval?.items_hash).toMatch(/^sha256:/);
+    expect(execution.attempts[0]?.idempotency_key).toMatch(/^idk_/);
+    expect(execution.attempts[0]?.answer.status).toBe("settled");
+    expect(report.receipts).toHaveLength(1);
+    expect(report.verify.present).toBe(false);
+  });
+
+  it("the default rendering is for a person and names the approver, the hash and the receipt", () => {
+    const out = run("inspect", [runId], env);
+    expect(out.code).toBe(0);
+    expect(out.stdout).toContain(runId);
+    expect(out.stdout).toContain("bills-agent@0.1.0");
+    expect(out.stdout).toContain("items_hash sha256:");
+    expect(out.stdout).toContain("rail says");
+    expect(out.stdout).toContain("receipts/rcpt_");
+    // Masked exactly as the bundle masks it.
+    expect(out.stdout).toContain("fi***@escola-aurora.example.com.br");
+    expect(out.stdout).not.toContain("financeiro@escola-aurora.example.com.br");
+  });
+
+  it("refuses a run id that is not there, cleanly, and says which ones are", () => {
+    const out = run("inspect", ["run_does_not_exist"], env);
+    expect(out.code).toBe(1);
+    expect(out.stdout).toBe("");
+    expect(out.stderr).toContain("no proof bundle for run run_does_not_exist");
+    expect(out.stderr).toContain(runId);
+    expect(out.stderr).not.toMatch(/at Object\.|at async |Error:/);
+  });
+
+  it("refuses with a usage line when no run id is given", () => {
+    const out = run("inspect", [], env);
+    expect(out.code).toBe(2);
+    expect(out.stdout).toBe("");
+    expect(out.stderr).toContain("usage: npm run inspect <run-id>");
+  });
+
+  it("--html writes one standalone file: no script, no external src or href", () => {
+    const target = join(mkdtempSync(join(tmpdir(), "bills-inspect-html-")), "run.html");
+    const out = run("inspect", [runId, "--html", target], env);
+    expect(out.code).toBe(0);
+    const html = readFileSync(target, "utf8");
+    expect(html).toMatch(/^<!doctype html>/);
+    expect(html).not.toMatch(/<script/i);
+    expect(html).not.toMatch(/(src|href)\s*=\s*["']?(https?:)?\/\//i);
+    expect(html).not.toMatch(/https?:\/\//i);
+    expect(html).not.toMatch(/<link\b/i);
+    expect(html).toContain(runId);
+    expect(html).toContain("items_hash sha256:");
+    expect(html).not.toContain("financeiro@escola-aurora.example.com.br");
+  });
+
+  it("a bundle a killed run left half-written is a message, not a stack trace", () => {
+    const broken = join(runs, "run_broken_bundle");
+    mkdirSync(join(broken, "receipts"), { recursive: true });
+    writeFileSync(join(broken, "approval.json"), "{ this is not json");
+    const out = run("inspect", ["run_broken_bundle"], env);
+    expect(out.code).toBe(1);
+    expect(out.stdout).toBe("");
+    expect(out.stderr).toContain("could not be read");
+    expect(out.stderr).not.toMatch(/at Object\.|at async |\.ts:\d+/);
+    rmSync(broken, { recursive: true, force: true });
+  });
+
+  it("works on any bundle in the runs folder, whatever produced it", () => {
+    const ids = readdirSync(runs, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name);
+    expect(ids).toContain(runId);
+    for (const id of ids) expect(run("inspect", [id, "--json"], env).code).toBe(0);
+  });
+});

package/templates/bills-agent/agents/bills-agent/test/provider.test.ts

@@ -0,0 +1,25 @@
+/**
+ * Which model runs: the Anthropic provider only with a real key. The
+ * `.env.example` placeholder, an empty value and an absent variable all
+ * mean "replay the recorded transcript", so a copied example never calls
+ * Anthropic with a fake key (issue #8).
+ */
+import { describe, expect, it } from "vitest";
+import { ANTHROPIC_KEY_PLACEHOLDER, resolveProvider } from "@codespar/agent-runtime";
+
+const REAL_LOOKING_KEY = ["sk", "ant", "x".repeat(24)].join("-");
+
+describe("resolveProvider", () => {
+  it("treats the .env.example placeholder, an empty value and an absent variable as no key", () => {
+    expect(resolveProvider({ ANTHROPIC_API_KEY: ANTHROPIC_KEY_PLACEHOLDER }, undefined)).toBe("replay");
+    expect(resolveProvider({ ANTHROPIC_API_KEY: "" }, undefined)).toBe("replay");
+    expect(resolveProvider({ ANTHROPIC_API_KEY: "   " }, undefined)).toBe("replay");
+    expect(resolveProvider({}, undefined)).toBe("replay");
+  });
+
+  it("picks Anthropic on a real-looking key, and an explicit --provider wins over the environment", () => {
+    expect(resolveProvider({ ANTHROPIC_API_KEY: REAL_LOOKING_KEY }, undefined)).toBe("anthropic");
+    expect(resolveProvider({ ANTHROPIC_API_KEY: REAL_LOOKING_KEY }, "replay")).toBe("replay");
+    expect(resolveProvider({}, "anthropic")).toBe("anthropic");
+  });
+});

package/templates/bills-agent/agents/bills-agent/test/scenarios.test.ts

@@ -2,7 +2,8 @@ import { existsSync, mkdtempSync, readFileSync, readdirSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { describe, expect, it } from "vitest";
-import { checkScenario, listScenarios, loadScenario, runScenario, type ScenarioRun } from "../src/scenarios.js";
+import { checkScenario, listScenarios, loadScenario, runScenario, type ScenarioRun } from "@codespar/agent-runtime";
+import { agent } from "../src/kit.js";
 
 const runsDir = mkdtempSync(join(tmpdir(), "bills-runs-"));
 
@@ -10,14 +11,14 @@ describe("section 12: scenario packs, on the replay provider", () => {
   const required = ["happy-path", "cap-exceeded", "beneficiary-not-allowed", "prompt-injection", "escalated-above-threshold", "mandate-revoked"];
 
   it("ships every scenario the spec asks for", () => {
-    for (const name of required) expect(listScenarios()).toContain(name);
+    for (const name of required) expect(listScenarios(agent)).toContain(name);
   });
 
   for (const name of required) {
-    const scenario = loadScenario(name);
+    const scenario = loadScenario(agent, name);
     for (const mode of scenario.modes) {
       it(`${name} [${mode}] ends in the states the pack declares`, async () => {
-        const run = await runScenario(scenario, { mode, runsDir });
+        const run = await runScenario(agent, scenario, { mode, runsDir });
         const check = checkScenario(scenario, run);
         expect(check.failures).toEqual([]);
         expect(check.ok).toBe(true);
@@ -36,9 +37,9 @@ describe("section 12: scenario packs, on the replay provider", () => {
   }
 
   it("happy-path: the same trail and the same receipts in human and in mandate", async () => {
-    const scenario = loadScenario("happy-path");
-    const human = await runScenario(scenario, { mode: "human", runsDir });
-    const mandate = await runScenario(scenario, { mode: "mandate", runsDir });
+    const scenario = loadScenario(agent, "happy-path");
+    const human = await runScenario(agent, scenario, { mode: "human", runsDir });
+    const mandate = await runScenario(agent, scenario, { mode: "mandate", runsDir });
     expect(human.executions.map((e) => e.trail)).toEqual(mandate.executions.map((e) => e.trail));
     expect(normalizeReceipts(human)).toEqual(normalizeReceipts(mandate));
     // In human, the artifact is a person's; in mandate the person still decided because the amount escalated.
@@ -51,9 +52,9 @@ describe("section 12: scenario packs, on the replay provider", () => {
 
   it("nothing reaches executing without an approval artifact carrying its items_hash", async () => {
     for (const name of required) {
-      const scenario = loadScenario(name);
+      const scenario = loadScenario(agent, name);
       for (const mode of scenario.modes) {
-        const run = await runScenario(scenario, { mode, runsDir });
+        const run = await runScenario(agent, scenario, { mode, runsDir });
         const approvalPath = join(run.bundle_dir, "approval.json");
         const artifacts = existsSync(approvalPath) ? (JSON.parse(readFileSync(approvalPath, "utf8")) as Array<{ execution_id: string; items_hash: string }>) : [];
         for (const e of run.executions) {

package/templates/bills-agent/agents/bills-agent/tsconfig.json

@@ -5,7 +5,6 @@
   },
   "include": [
     "src/**/*.ts",
-    "channels/**/*.ts",
     "test/**/*.ts"
   ]
 }

package/templates/bills-agent/package.json

@@ -7,20 +7,23 @@
   "type": "module",
   "workspaces": [
     "packages/agent-core",
+    "packages/agent-runtime",
     "agents/bills-agent"
   ],
   "scripts": {
     "start": "npm start --workspace=agents/bills-agent --",
     "check": "npm run check --workspaces --if-present --",
     "test": "vitest run --pool=forks --maxWorkers=1",
-    "typecheck": "tsc --noEmit -p packages/agent-core/tsconfig.json && tsc --noEmit -p agents/bills-agent/tsconfig.json",
+    "typecheck": "tsc --noEmit -p packages/agent-core/tsconfig.json && tsc --noEmit -p packages/agent-runtime/tsconfig.json && tsc --noEmit -p agents/bills-agent/tsconfig.json",
     "approve": "npm run approve --workspace=agents/bills-agent --",
     "consent": "npm run consent --workspace=agents/bills-agent --",
     "deny": "npm run deny --workspace=agents/bills-agent --",
     "eval": "npm run eval --workspace=agents/bills-agent --",
+    "inspect": "npm run inspect --workspace=agents/bills-agent --",
     "reconcile": "npm run reconcile --workspace=agents/bills-agent --",
     "rerun": "npm run rerun --workspace=agents/bills-agent --",
-    "resume": "npm run resume --workspace=agents/bills-agent --"
+    "resume": "npm run resume --workspace=agents/bills-agent --",
+    "verify": "npm run verify --workspace=agents/bills-agent --"
   },
   "devDependencies": {
     "@types/node": "22.20.4",

package/templates/bills-agent/packages/agent-core/README.md

@@ -2,6 +2,8 @@
 
 The primitives every CodeSpar starter-kit agent inherits (spec v5.1.1, section 4): the execution state machine, the approval artifact, the `agent.yaml` manifest, `escalate_above`, `actor`, local state in SQLite, the proof bundle, the rail contract and the two providers.
 
+This package is the decisions. The RUNNER around them — the terminal channel, `codespar-agent start|consent|approve|deny|resume|rerun|reconcile|poll|webhook|check|eval`, the setup that wires this package to an agent directory, and the scenario and adversarial runners — is [`@codespar/agent-runtime`](../agent-runtime), which depends on this one and is what an agent's `package.json` scripts call (#13). Nothing here knows an agent's name.
+
 ## The state machine, and what the types do and do not prove
 
 `transition(execution, to, input)` accepts only a `to` that the table in `state-machine.ts` lists for `execution.state`. On a **narrowed** value (`Execution<"drafted">`, `Execution<"executing">`, ...) a transition outside the table is a compile error, and `test/transitions.type-test.ts` keeps that true with `@ts-expect-error` lines that `tsc` refuses to leave unused. An **un-narrowed** `Execution` (the union, which is what a row read back from SQLite is) compiles for any target; the engine narrows with casts at its call sites. So the guard that always holds is the runtime one: `transition()` throws `IllegalTransitionError` on any pair the table does not list, whatever the static type said. The type test proves the table is closed; the runtime check enforces it.

package/templates/bills-agent/packages/agent-core/package.json

@@ -17,7 +17,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sdk": "0.128.0",
-    "@codespar/sdk": "0.16.4",
+    "@codespar/sdk": "0.16.6",
     "yaml": "2.9.1",
     "zod": "3.25.76"
   }

package/templates/bills-agent/packages/agent-core/src/api/charge-rail.ts

@@ -79,10 +79,12 @@ export class CodeSparChargeRail implements PaymentRail {
 
   async pay(payment: RailPayment): Promise<RailOutcome> {
     if (!payment.due_date) return { status: "failed", code: "due_date_required", message: "a receivable needs a due_date; the immediate Pix charge cannot be read back or replayed" };
+    if (!payment.consumer_id) return { status: "failed", code: "consumer_id_required", message: "a receivable settles into the principal's account; the policy names no consumer_id" };
     let view: ChargeView;
     try {
       view = (await this.api.post("/v1/charges", {
         body: {
+          consumer_id: payment.consumer_id,
           amount: payment.amount_minor / 100,
           currency: payment.currency,
           method: "boleto",
@@ -108,15 +110,32 @@ export class CodeSparChargeRail implements PaymentRail {
     return outcome.status === "in_flight" ? { status: "uncertain", code: "issuance_unconfirmed", message: "the create answered no readable state" } : outcome;
   }
 
-  async lookup(attemptId: string, _payment: RailPayment): Promise<RailLookup> {
+  /**
+   * By the charge id when the create handed one back; by our idempotency key only when it did not (the create's answer was lost).
+   * The route's doc says the read accepts the caller's key as the id; on staging (2026-09-23) it answered `charge_not_found` for
+   * the key and the charge for the id, so the id comes first and the key is the fallback, not the other way round.
+   */
+  async lookup(attemptId: string, _payment: RailPayment, transactionId?: string): Promise<RailLookup> {
+    const byId = transactionId ? await this.read(transactionId) : { kind: "missing" as const };
+    if (byId.kind === "view") return outcomeOf(byId.view);
+    if (byId.kind === "in_flight") return { status: "in_flight" };
+    if (byId.kind === "uncertain") return byId.outcome;
+    const byKey = await this.read(attemptId);
+    if (byKey.kind === "view") return outcomeOf(byKey.view);
+    if (byKey.kind === "in_flight") return { status: "in_flight" };
+    if (byKey.kind === "uncertain") return byKey.outcome;
+    return undefined;
+  }
+
+  private async read(chargeRef: string): Promise<{ kind: "view"; view: ChargeView } | { kind: "missing" } | { kind: "in_flight" } | { kind: "uncertain"; outcome: Extract<RailOutcome, { status: "uncertain" }> }> {
     try {
-      const view = (await this.api.get("/v1/charges/{chargeId}", { path: { chargeId: attemptId } })) as ChargeView;
-      return outcomeOf(view);
+      const view = (await this.api.get("/v1/charges/{chargeId}", { path: { chargeId: chargeRef } })) as ChargeView;
+      return { kind: "view", view };
     } catch (err) {
       const failure = describeApiError(err);
-      if (failure.status === 404) return undefined;
-      if (failure.status === 409) return { status: "in_flight" };
-      return { status: "uncertain", code: failure.code, message: failure.message };
+      if (failure.status === 404) return { kind: "missing" };
+      if (failure.status === 409) return { kind: "in_flight" };
+      return { kind: "uncertain", outcome: { status: "uncertain", code: failure.code, message: failure.message } };
     }
   }
 
@@ -133,6 +152,8 @@ export class CodeSparChargeRail implements PaymentRail {
         payment: { amount_minor: view.amount_minor, payee: null, attempt_id: chargeId, money_moved: false, sandbox: true, at: raw.settled_at ?? new Date().toISOString() },
         chain: null,
         receipt_sig: null,
+        receipt_sig_ed25519: null,
+        receipt_sig_kid: null,
         actor,
         raw: view,
       };

package/templates/bills-agent/packages/agent-core/src/api/rail.ts

@@ -18,6 +18,16 @@ import type { PaymentRail, RailLookup, RailOutcome, RailPayment, RailReceipt } f
 import type { Actor } from "../types.js";
 import { describeApiError, isUncertain } from "./client.js";
 
+/** The asymmetric seal as the API serves it, or nulls when this deployment
+ *  does not serve one. Never throws on a shape it does not recognise: a
+ *  receipt is evidence of a payment that already happened, and refusing to
+ *  record it over an unexpected field would trade the record for the proof. */
+function readEd25519Seal(body: unknown): { receipt_sig_ed25519: string | null; receipt_sig_kid: string | null } {
+  const r = body as { receipt_sig_ed25519?: unknown; receipt_sig_kid?: unknown };
+  const str = (v: unknown): string | null => (typeof v === "string" && v.length > 0 ? v : null);
+  return { receipt_sig_ed25519: str(r.receipt_sig_ed25519), receipt_sig_kid: str(r.receipt_sig_kid) };
+}
+
 export class CodeSparRail implements PaymentRail {
   readonly name = "codespar" as const;
 
@@ -89,6 +99,12 @@ export class CodeSparRail implements PaymentRail {
         },
         chain: r.chain,
         receipt_sig: r.receipt_sig,
+        // ent#1633 landed after `@codespar/sdk@0.16.6` was generated, so the
+        // typed response does not carry these two yet. Read off the body
+        // defensively rather than pinning a new SDK for two nullable strings:
+        // a deployment that predates the change answers null, which is the
+        // same answer the columns hold and reads as `unsigned`.
+        ...readEd25519Seal(r),
         actor,
         raw: r,
       };