@codespar/cli 0.16.0 → 0.18.0

package/templates/bills-agent/packages/agent-runtime/src/terminal.ts

@@ -8,7 +8,7 @@
 import { createInterface } from "node:readline/promises";
 import { stdin, stderr, stdout } from "node:process";
 import { relative } from "node:path";
-import type { AgentRuntime, ChargeInstrument, Execution } from "@codespar/agent-core";
+import type { AgentRuntime, BatchGesture, BatchPresentation, ChargeInstrument, Execution } from "@codespar/agent-core";
 import { pollUntilClosed, type PollResult } from "./poll.js";
 import type { Setup } from "./setup.js";
 
@@ -23,8 +23,12 @@ export interface TerminalOptions {
   simulatePayer?: boolean | undefined;
   say?: ((line: string) => void) | undefined;
   ask?: ((question: string) => Promise<string>) | undefined;
-  /** Where the lines for the counterparty go (the conversation); `say` is the operator's console. */
-  tell?: ((line: string) => void) | undefined;
+  /**
+   * Where the lines for the counterparty go (the conversation); `say` is the
+   * operator's console. `about` is the execution whose OUTCOME the line tells,
+   * so a channel can tie a failed delivery of it back to that outcome.
+   */
+  tell?: ((line: string, about?: Execution) => void) | undefined;
   /**
    * How a payable receivable is put in front of the counterparty. Defaults to
    * the kit's own, which writes lines to a console. A channel overrides it,
@@ -32,8 +36,18 @@ export interface TerminalOptions {
    * message, and neither of those is a line of text.
    */
   presentInstrument?: ((execution: Execution, instalment: number, chargeId: string, instrument: ChargeInstrument, tell: (line: string) => void) => void | Promise<void>) | undefined;
+  /**
+   * The gestures taken on whole batches in this session, by batch ref. When a
+   * line of a batch arrives and its ref is here, the line is decided by the
+   * gesture instead of by a question; see `presentBatch`.
+   */
+  gestures?: BatchGestures | undefined;
 }
 
+/** One gesture per batch ref: the list it was taken on, and the positions vetoed. */
+export type BatchGestures = Map<string, BatchGestureRecord>;
+type BatchGestureRecord = { batch_hash: string; count: number; vetoed: Set<number> };
+
 export function describeExecution(execution: Execution, setup: Setup): string[] {
   return setup.kit.describeExecution(execution, setup);
 }
@@ -43,6 +57,16 @@ export function announceOutcome(execution: Execution, setup: Setup, tell: (line:
   return setup.kit.announceOutcome?.(execution, setup, tell) ?? false;
 }
 
+/** The kit's follow-up to an outcome. Never throws: what follows a paid order cannot un-pay it. */
+export async function followUp(execution: Execution, setup: Setup, say: (line: string) => void): Promise<void> {
+  if (!setup.kit.followUp) return;
+  try {
+    await setup.kit.followUp(execution, setup, say);
+  } catch (err) {
+    say(`  follow-up of ${execution.id} failed and changed nothing about it: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
 function receiptLines(execution: Execution, setup: Setup, say: (line: string) => void): void {
   for (const outcome of execution.outcomes) {
     if (outcome.receipt_id) say(`  ${setup.kit.labels.receiptWord}: ${relative(process.cwd(), `${setup.bundle.dir}/receipts/${outcome.receipt_id}.json`)}`);
@@ -61,23 +85,29 @@ export async function handleExecution(execution: Execution, options: TerminalOpt
 
   let current = execution;
   if (current.state === "awaiting_approval") {
-    let decision = options.decision;
-    if (!decision) {
-      if (current.blocking_reasons.length > 0) say("  (o unico desfecho possivel e negar; aperte Enter)");
-      const ask = options.ask ?? defaultAsk;
-      const answer = (await ask(labels.approveQuestion)).trim().toLowerCase();
-      decision = answer === "s" || answer === "sim" || answer === "y" || answer === "yes" ? "approve" : "deny";
-    }
-    if (decision === "approve") current = engine.approve(current.id, approver);
-    else if (decision === "deny") current = engine.deny(current.id, approver);
-    else {
-      say("  deixado em awaiting_approval (rode de novo com --approve ou --deny)");
-      return current;
+    const gesture = options.decision === undefined && current.batch ? options.gestures?.get(current.batch.ref) : undefined;
+    if (gesture) {
+      current = decideByGesture(current, gesture, setup, approver);
+    } else {
+      let decision = options.decision;
+      if (!decision) {
+        if (current.blocking_reasons.length > 0) say("  (o unico desfecho possivel e negar; aperte Enter)");
+        const ask = options.ask ?? defaultAsk;
+        const answer = (await ask(labels.approveQuestion)).trim().toLowerCase();
+        decision = answer === "s" || answer === "sim" || answer === "y" || answer === "yes" ? "approve" : "deny";
+      }
+      if (decision === "approve") current = engine.approve(current.id, approver);
+      else if (decision === "deny") current = engine.deny(current.id, approver);
+      else {
+        say("  deixado em awaiting_approval (rode de novo com --approve ou --deny)");
+        return current;
+      }
     }
     say(`  -> ${current.state}${current.reason ? ` (${current.reason})` : ""}`);
   }
 
-  if (current.state === "approved") {
+  // An agent that issues on request (`executeOnApproval: false`) leaves the approved execution for its own tool to issue.
+  if (current.state === "approved" && setup.kit.executeOnApproval !== false) {
     current = await engine.execute(current.id);
     say(`  -> ${current.state}${current.reason ? ` (${current.reason})` : ""}`);
     if (setup.settlement === "immediate") {
@@ -95,11 +125,87 @@ export async function handleExecution(execution: Execution, options: TerminalOpt
     } else if (current.state === "executing") {
       say(labels.uncertainDispatch);
     }
-    announceOutcome(current, setup, tell);
+    const told = current;
+    announceOutcome(told, setup, (line) => tell(line, told));
+    await followUp(current, setup, say);
   }
   return current;
 }
 
+/**
+ * A line of a batch the person already decided on as a list. The gesture
+ * approves or vetoes a POSITION in ONE list: a line that names another list
+ * under the same ref is not covered by it, and "todas" must not become a yes
+ * to a list nobody was shown. `approve` still runs the policy and still mints
+ * this line's own artifact, which carries the `batch_hash` the gesture was
+ * taken on — that is what makes the gesture attested rather than asserted.
+ */
+function decideByGesture(execution: Execution, gesture: BatchGestureRecord, setup: Setup, approver: TerminalOptions["approver"]): Execution {
+  const engine = setup.engine;
+  const { batch_hash, index, count } = execution.batch!;
+  if (batch_hash !== gesture.batch_hash || count !== gesture.count) {
+    return engine.deny(execution.id, approver, `the list changed after the gesture: it was taken on ${gesture.count} line(s) hashing to ${gesture.batch_hash}, and this line belongs to ${count} hashing to ${batch_hash}`);
+  }
+  if (gesture.vetoed.has(index)) return engine.deny(execution.id, approver, `vetoed in the batch gesture (line ${index + 1} of ${count})`);
+  return engine.approve(execution.id, approver);
+}
+
+/**
+ * What the person answered to a whole list, or `undefined` when the answer
+ * cannot be read as one. Lines are numbered from 1, as they were shown.
+ * "todas" / "all", "todas exceto 3,7" / "all except 3,7", and "nenhuma" /
+ * "none" (also an empty answer: the default is no, as it is per line). A
+ * number outside the list is unreadable rather than ignored, because a typo
+ * that silently vetoed nothing would pay the line the person meant to stop.
+ */
+export function parseBatchGesture(answer: string, count: number): { vetoed: number[] } | undefined {
+  const text = answer.trim().toLowerCase();
+  const all = Array.from({ length: count }, (_, i) => i);
+  if (text === "" || text === "nenhuma" || text === "none" || text === "n" || text === "nao") return { vetoed: all };
+  if (text === "todas" || text === "all") return { vetoed: [] };
+  const except = /^(?:todas|all)\s+(?:exceto|except)\s+([\d\s,]+)$/.exec(text);
+  if (!except) return undefined;
+  const numbers = except[1]!.split(/[\s,]+/).filter(Boolean).map(Number);
+  if (numbers.length === 0 || numbers.some((n) => !Number.isInteger(n) || n < 1 || n > count)) return undefined;
+  return { vetoed: [...new Set(numbers.map((n) => n - 1))].sort((a, b) => a - b) };
+}
+
+/**
+ * Section 3, for a list: the person sees every line, the total and the hash
+ * prefix, and answers once. What they answer is recorded in the bundle as a
+ * `batch.gesture` event and kept for the lines that follow; each line is then
+ * decided by `decideByGesture` when it arrives, and each one it approves mints
+ * its own artifact as before.
+ */
+export async function presentBatch(batch: BatchPresentation, options: TerminalOptions & { gestures: BatchGestures }): Promise<BatchGesture> {
+  const { setup, approver } = options;
+  const say = options.say ?? ((l: string) => stderr.write(l + "\n"));
+  const ask = options.ask ?? defaultAsk;
+  say(`  lote ${batch.ref} — ${batch.label}: ${batch.count} linha(s), total ${batch.total}, batch_hash ${batch.batch_hash.slice(0, 19)}…`);
+  for (const line of batch.lines) {
+    const note =
+      line.status === "already_settled"
+        ? " (ja paga; nao roda de novo)"
+        : line.status === "in_progress"
+          ? " (em andamento; nao roda de novo)"
+          : line.status === "attempt_id_conflict"
+            ? " (tentativa presa a outro pagamento; nao roda de novo)"
+            : "";
+    say(`    ${line.index + 1}. ${line.beneficiary}: ${line.amount}${note}`);
+  }
+  let parsed: { vetoed: number[] } | undefined;
+  while (!parsed) {
+    parsed = parseBatchGesture(await ask("  Aprovar a lista? [todas / todas exceto 3,7 / nenhuma] "), batch.count);
+    if (!parsed) say(`  nao entendi; responda todas, todas exceto <numeros de 1 a ${batch.count}> ou nenhuma`);
+  }
+  const vetoed = new Set(parsed.vetoed);
+  const gesture: BatchGesture = { batch_hash: batch.batch_hash, approved: batch.lines.map((l) => l.index).filter((i) => !vetoed.has(i)), vetoed: parsed.vetoed };
+  options.gestures.set(batch.ref, { batch_hash: batch.batch_hash, count: batch.count, vetoed });
+  setup.engine.note("batch.gesture", null, { batch_ref: batch.ref, batch_hash: batch.batch_hash, count: batch.count, total_minor: batch.total_minor, approved: gesture.approved, vetoed: gesture.vetoed, approver: { type: "human", id: approver.id, channel: approver.channel } });
+  say(`  -> lista ${gesture.vetoed.length === 0 ? "aprovada inteira" : gesture.approved.length === 0 ? "negada inteira" : `aprovada exceto ${gesture.vetoed.map((i) => i + 1).join(", ")}`}`);
+  return gesture;
+}
+
 export async function waitForPayer(executionId: string, options: TerminalOptions): Promise<PollResult> {
   const { setup } = options;
   const say = options.say ?? ((l: string) => stderr.write(l + "\n"));
@@ -133,7 +239,10 @@ export async function interactive(options: TerminalOptions & { runtime: AgentRun
   const { setup } = options;
   const say = options.say ?? ((l: string) => stderr.write(l + "\n"));
   const labels = setup.kit.labels;
-  const loop = setup.makeLoop(options.runtime, (execution) => handleExecution(execution, options));
+  // Interactive only: a person at the keyboard can decide a list in one go. The one-shot and the scenario runner pass one decision to every line and never reach this.
+  const gestures: BatchGestures = new Map();
+  const withGestures = { ...options, gestures };
+  const loop = setup.makeLoop(options.runtime, (execution) => handleExecution(execution, withGestures), (batch) => presentBatch(batch, withGestures));
   say(`${setup.manifest.manifest.name} ${setup.manifest.manifest.version} — approval: ${setup.mode} — trilho: ${setup.railKind} — ${labels.mandateWord} ${setup.mandate.id}`);
   say(`run ${setup.runId} — bundle em ${relative(process.cwd(), setup.bundle.dir)}`);
   say(labels.intro);

package/templates/bills-agent/packages/agent-runtime/test/verify-cli.test.ts

@@ -7,12 +7,15 @@
  * verifier is someone who has the receipt file and nothing else. The key set
  * is a local copy, so no test opens a socket.
  */
-import { spawnSync } from "node:child_process";
-import { generateKeyPairSync, sign as signDetached } from "node:crypto";
-import { mkdtempSync, writeFileSync } from "node:fs";
+import { spawn, spawnSync } from "node:child_process";
+import { createHash, generateKeyPairSync, sign as signDetached } from "node:crypto";
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { createServer, type Server } from "node:http";
+import type { AddressInfo } from "node:net";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
-import { describe, expect, it } from "vitest";
+import { canonicalize, itemsHash, maskPayee, type ExecutionItem } from "@codespar/agent-core";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
 
 const BIN = resolve(import.meta.dirname, "../bin.mjs");
 const KID = "did:web:id.codespar.dev#1";
@@ -55,13 +58,15 @@ function run(args: string[], cwd: string) {
 }
 
 describe("codespar-agent verify", () => {
-  it("verifies a sealed receipt from a directory with no agent and no key", () => {
+  it("checks a run's copy from a directory with no agent and no key, and says it proves the signature only (exit 7)", () => {
     const { dir, receiptPath, keysPath } = fixture();
     const out = run([receiptPath, "--keys", keysPath], dir);
-    expect(out.code).toBe(0);
-    expect(out.stdout).toContain("VERIFIED");
+    expect(out.code).toBe(7);
+    expect(out.stdout).toContain("SIGNATURE_ONLY");
     expect(out.stdout).toContain(RECEIPT_ID);
-    expect(out.stderr).toContain("was sealed by CodeSpar");
+    expect(out.stdout).toContain("read_required");
+    expect(out.stderr).toContain("carries CodeSpar's signature");
+    expect(out.stderr).toContain("--from-api");
   });
 
   it("puts valid JSON and nothing else on stdout with --json; the sentence goes to stderr", () => {
@@ -70,7 +75,7 @@ describe("codespar-agent verify", () => {
     const lines = out.stdout.split("\n").filter(Boolean);
     expect(lines).toHaveLength(1);
     const report = JSON.parse(lines[0]!) as { verdict: string; kid: string; signing_string: string; message: string };
-    expect(report.verdict).toBe("verified");
+    expect(report.verdict).toBe("signature_only");
     expect(report.kid).toBe(KID);
     expect(report.signing_string).toBe(`codespar-receipt:v1:${RECEIPT_ID}:${CHAIN}`);
     expect(out.stderr).toContain(report.message);
@@ -125,3 +130,200 @@ describe("codespar-agent verify", () => {
     expect(run(["--help"], dir).code).toBe(0);
   });
 });
+
+/*
+ * The body and the approval (OPEN_QUESTIONS §3, §47). A v4 receipt read, its
+ * chain written out link by link and signed with a key generated here, under
+ * the recipe production published on 2026-09-26.
+ */
+const PUBLISHED = JSON.parse(readFileSync(resolve(import.meta.dirname, "../../agent-core/test/fixtures/production-receipt-keys.json"), "utf8")) as Record<string, unknown>;
+const V4_KID = "did:web:id.codespar.dev#production-2";
+const PAYEE = "escola@exemplo.com.br";
+const ITEMS: ExecutionItem[] = [{ alias: "escola", beneficiary: "Escola Aurora", payee: PAYEE, amount: 185000, currency: "BRL", description: "outubro" }];
+const sha256 = (v: string) => createHash("sha256").update(v, "utf8").digest("hex");
+
+function v4Fixture(sealedItemsHash = itemsHash(ITEMS)) {
+  const dir = mkdtempSync(join(tmpdir(), "verify-cli-v4-"));
+  const { privateKey, publicKey } = generateKeyPairSync("ed25519");
+  const x = Buffer.from(publicKey.export({ format: "der", type: "spki" }).subarray(-32)).toString("base64url");
+  const mandate = { id: "cm_test_1", nonce: "nonce-1", scope: "contas do mes", currency: "BRL", sig_sha256: sha256("s".repeat(64)) };
+  const quote = { seller: "Escola Aurora", resource: "outubro", price_minor: 185000, payee: PAYEE, session_id: null, sig: "q".repeat(64), at: "2026-09-26T18:00:00.000Z" };
+  const approval = { items_hash: sealedItemsHash, batch_hash: null };
+  const payment = { rail: "pix-consent", provider: "pix", tx_id: "tx_1", amount_minor: 185000, amount_atomic: null, sandbox: true, attempt_id: "att_1_0", money_moved: false, at: "2026-09-26T18:00:01.000Z" };
+  const chain = sha256(
+    canonicalize({
+      v: 4,
+      links: [
+        mandate,
+        quote,
+        approval,
+        { rail: payment.rail, provider: payment.provider, tx_id: payment.tx_id, amount_minor: payment.amount_minor, sandbox: true, attempt_id: payment.attempt_id, money_moved: false, at: payment.at },
+      ],
+    }),
+  );
+  const signature = signDetached(null, Buffer.from(`codespar-receipt:v1:${RECEIPT_ID}:${chain}`, "utf8"), privateKey).toString("base64url");
+  const read = { receipt_id: RECEIPT_ID, state: "paid", chain_version: 4, mandate, quote, approval, payment, delivery: null, chain, receipt_sig: "hmac-not-read-here", receipt_sig_ed25519: signature, receipt_sig_kid: V4_KID, exceptions: [] };
+  const keys = { ...PUBLISHED, keys: [{ kid: V4_KID, kty: "OKP", crv: "Ed25519", x, alg: "EdDSA", use: "sig", status: "active" }] };
+  const artifact = { approval_id: "apr_1", execution_id: "exe_1", items: ITEMS, items_hash: itemsHash(ITEMS), approved_at: "2026-09-26T18:00:00.000Z" };
+
+  // A run's bundle, as the engine writes it: the masked copy naming its artifact, and approval.json beside receipts/.
+  const run = join(dir, "runs", "run_1");
+  mkdirSync(join(run, "receipts"), { recursive: true });
+  const copy = {
+    receipt_id: RECEIPT_ID,
+    state: "paid",
+    mandate: { id: mandate.id },
+    payment: { amount_minor: 185000, payee: maskPayee(PAYEE), attempt_id: payment.attempt_id, money_moved: false, sandbox: true, at: payment.at },
+    chain,
+    receipt_sig: "hmac-not-read-here",
+    receipt_sig_ed25519: signature,
+    receipt_sig_kid: V4_KID,
+    actor: { type: "agent", agent: "bills-agent@0.1.0", on_behalf_of: "usr_demo" },
+    approval_id: artifact.approval_id,
+  };
+  const paths = {
+    read: join(dir, "receipt-read.json"),
+    keys: join(dir, "codespar-receipt-keys.json"),
+    artifact: join(dir, "approval.json"),
+    copy: join(run, "receipts", `${RECEIPT_ID}.json`),
+    runApprovals: join(run, "approval.json"),
+  };
+  writeFileSync(paths.read, JSON.stringify(read, null, 2) + "\n");
+  writeFileSync(paths.keys, JSON.stringify(keys, null, 2) + "\n");
+  writeFileSync(paths.artifact, JSON.stringify([artifact], null, 2) + "\n");
+  writeFileSync(paths.copy, JSON.stringify(copy, null, 2) + "\n");
+  writeFileSync(paths.runApprovals, JSON.stringify([artifact], null, 2) + "\n");
+  return { dir, read, keys, copy, artifact, paths };
+}
+
+describe("codespar-agent verify, the body and the approval of a v4 receipt read", () => {
+  it("exits 0 when the chain recomputes from the read and the sealed approval is the artifact's", () => {
+    const f = v4Fixture();
+    const out = run([f.paths.read, "--keys", f.paths.keys, "--approval", f.paths.artifact], f.dir);
+    expect(out.code).toBe(0);
+    expect(out.stdout).toContain("VERIFIED");
+    expect(out.stdout).toContain("body         recomputed (chain v4)");
+    expect(out.stdout).toContain("approval     matched");
+    expect(out.stderr).toContain("paid against the list artifact apr_1 approved");
+  });
+
+  it("exits 9, approval_mismatch, when the receipt sealed another list than the artifact's", () => {
+    const f = v4Fixture(`sha256:${"9".repeat(64)}`);
+    const out = run([f.paths.read, "--keys", f.paths.keys, "--approval", f.paths.artifact, "--json"], f.dir);
+    expect(out.code).toBe(9);
+    const report = JSON.parse(out.stdout) as { verdict: string; reason: string; approval_check: { status: string } };
+    expect(report).toMatchObject({ verdict: "approval_mismatch", reason: "items_hash_differs", approval_check: { status: "mismatch" } });
+  });
+
+  it("exits 8, chain_mismatch, when the payee beside a genuine signature was changed", () => {
+    const f = v4Fixture();
+    writeFileSync(f.paths.read, JSON.stringify({ ...f.read, quote: { ...f.read.quote, payee: "outra@exemplo.com.br" } }));
+    const out = run([f.paths.read, "--keys", f.paths.keys, "--approval", f.paths.artifact], f.dir);
+    expect(out.code).toBe(8);
+    expect(out.stdout).toContain("CHAIN_MISMATCH");
+  });
+
+  it("exits 7 for a v2 read, and says the chain is not recomputable without the mandate signature", () => {
+    const f = v4Fixture();
+    writeFileSync(f.paths.read, JSON.stringify({ ...f.read, chain_version: 2 }));
+    const out = run([f.paths.read, "--keys", f.paths.keys], f.dir);
+    expect(out.code).toBe(7);
+    expect(out.stderr).toContain("not recomputable without the mandate signature");
+  });
+
+  it("refuses an --approval file with more than one artifact unless --approval-id names one", () => {
+    const f = v4Fixture();
+    writeFileSync(f.paths.artifact, JSON.stringify([f.artifact, { ...f.artifact, approval_id: "apr_2" }]));
+    expect(run([f.paths.read, "--keys", f.paths.keys, "--approval", f.paths.artifact], f.dir).code).toBe(2);
+    expect(run([f.paths.read, "--keys", f.paths.keys, "--approval", f.paths.artifact, "--approval-id", "apr_1"], f.dir).code).toBe(0);
+    expect(run([f.paths.read, "--keys", f.paths.keys, "--approval-id", "apr_1"], f.dir).code).toBe(2);
+  });
+});
+
+/*
+ * `--from-api`: a run's masked copy, bound through the API's read. A local
+ * server plays the deployment — the receipt route and its well-known key set —
+ * so the read and the key set come from ONE origin, as the command requires.
+ */
+describe("codespar-agent verify --from-api", () => {
+  let server: Server;
+  let baseUrl: string;
+  let served: { read: unknown; keys: unknown } = { read: {}, keys: {} };
+  const asked: string[] = [];
+
+  beforeAll(async () => {
+    server = createServer((req, res) => {
+      asked.push(`${req.method} ${req.url} ${req.headers["authorization"] ? "auth" : "anon"}`);
+      const body = req.url === "/.well-known/codespar-receipt-keys.json" ? served.keys : req.url === `/v1/consumers/receipts/${RECEIPT_ID}` ? served.read : undefined;
+      res.writeHead(body === undefined ? 404 : 200, { "content-type": "application/json" });
+      res.end(JSON.stringify(body ?? { error: { code: "not_found", message: "no" } }));
+    });
+    await new Promise<void>((ok) => server.listen(0, "127.0.0.1", ok));
+    baseUrl = `http://127.0.0.1:${(server.address() as AddressInfo).port}`;
+  });
+
+  afterAll(async () => {
+    server.closeAllConnections();
+    await new Promise<void>((ok) => server.close(() => ok()));
+  });
+
+  /** The server answers while the command runs, so the process is awaited, never spawned synchronously. */
+  function runAsync(args: string[], cwd: string): Promise<{ code: number | null; stdout: string; stderr: string }> {
+    return new Promise((done) => {
+      const child = spawn(process.execPath, [BIN, "verify", ...args], {
+        cwd,
+        // The placeholder passes the csk_test_ guard and is the one test-key-shaped string the secret scan allows.
+        env: { ...process.env, CODESPAR_API_KEY: "csk_test_your_key_here", CODESPAR_API_URL: baseUrl, ANTHROPIC_API_KEY: "" },
+      });
+      let stdout = "";
+      let stderr = "";
+      child.stdout.on("data", (d: Buffer) => (stdout += d.toString()));
+      child.stderr.on("data", (d: Buffer) => (stderr += d.toString()));
+      child.on("close", (code) => done({ code, stdout, stderr }));
+    });
+  }
+
+  it("binds the copy's body through the read and checks the run's own artifact: exit 0, and nothing unmasked is written", async () => {
+    const f = v4Fixture();
+    served = { read: f.read, keys: f.keys };
+    asked.length = 0;
+    const out = await runAsync([f.paths.copy, "--from-api"], f.dir);
+    expect(out.code).toBe(0);
+    expect(out.stdout).toContain("approval     matched");
+    expect(asked).toEqual([`GET /.well-known/codespar-receipt-keys.json anon`, `GET /v1/consumers/receipts/${RECEIPT_ID} auth`]);
+    expect(readFileSync(f.paths.copy, "utf8")).not.toContain(PAYEE);
+  });
+
+  it("exits 9 when the run's artifact is not the list the receipt sealed", async () => {
+    const f = v4Fixture();
+    served = { read: f.read, keys: f.keys };
+    writeFileSync(f.paths.runApprovals, JSON.stringify([{ ...f.artifact, items: [{ ...ITEMS[0]!, amount: 1 }], items_hash: itemsHash([{ ...ITEMS[0]!, amount: 1 }]) }]));
+    const out = await runAsync([f.paths.copy, "--from-api", "--json"], f.dir);
+    expect(out.code).toBe(9);
+    expect(JSON.parse(out.stdout)).toMatchObject({ verdict: "approval_mismatch", reason: "items_hash_differs" });
+  });
+
+  it("exits 8 when the copy was edited after it was written: the signature does not cover its body, the read does", async () => {
+    const f = v4Fixture();
+    served = { read: f.read, keys: f.keys };
+    writeFileSync(f.paths.copy, JSON.stringify({ ...f.copy, payment: { ...f.copy.payment, amount_minor: 1 } }));
+    const out = await runAsync([f.paths.copy, "--from-api", "--json"], f.dir);
+    expect(out.code).toBe(8);
+    expect(JSON.parse(out.stdout)).toMatchObject({ verdict: "chain_mismatch", reason: "copy_differs_from_read" });
+  });
+
+  it("answers signature_only, never a failure, when the read cannot be fetched", async () => {
+    const f = v4Fixture();
+    served = { read: undefined as unknown, keys: f.keys };
+    const out = await runAsync([f.paths.copy, "--from-api", "--json"], f.dir);
+    expect(out.code).toBe(7);
+    expect(JSON.parse(out.stdout)).toMatchObject({ verdict: "signature_only", reason: "read_unavailable" });
+  });
+
+  it("refuses a key set from another deployment than the read", async () => {
+    const f = v4Fixture();
+    const out = await runAsync([f.paths.copy, "--from-api", "--url", "https://api.codespar.dev/.well-known/codespar-receipt-keys.json"], f.dir);
+    expect(out.code).toBe(2);
+    expect(out.stderr).toContain("same deployment");
+  });
+});

package/templates/bills-agent/packages/agent-runtime/test/whatsapp-cloud-api.test.ts

@@ -20,6 +20,7 @@ import {
   isMetaBaseUrl,
   loadCloudApiConfig,
   parseInbound,
+  providerRefusal,
   verifyChallenge,
   verifyWebhookSignature,
   WhatsAppCloudApi,
@@ -230,3 +231,47 @@ describe("deliver, with the network replaced by an assertion", () => {
     expect(sent.refused?.rule).toBe("provider_refused");
   });
 });
+
+describe("what Meta's error body says, read rather than collapsed into a status", () => {
+  const body = (error: unknown) => JSON.stringify({ error });
+
+  it("reads 131047 as the window rule it is, so a caller can answer it with a template", () => {
+    const refusal = providerRefusal(400, body({ code: 131047, message: "(#131047) Message failed to send", error_data: { details: "the 24h customer service window closed" } }));
+    expect(refusal.rule).toBe("session_window_closed");
+    expect(refusal.detail).toContain("400/131047");
+    expect(refusal.detail).toContain("the 24h customer service window closed");
+  });
+
+  it("keeps any other code a provider refusal, with the code named", () => {
+    expect(providerRefusal(400, body({ code: 131026, message: "Message undeliverable" }))).toEqual({ rule: "provider_refused", detail: "400/131026 from the Cloud API" });
+  });
+
+  it("does not mistake a body without Meta's envelope for anything but the status", () => {
+    expect(providerRefusal(502, "<html>bad gateway</html>")).toEqual({ rule: "provider_refused", detail: "502 from the Cloud API" });
+  });
+});
+
+describe("a redelivered message is the same message", () => {
+  it("hands a message on once however many times it arrives, and says it dropped the rest", async () => {
+    const lines: string[] = [];
+    const port = 40000 + Math.floor(Math.random() * 20000);
+    const backend = new WhatsAppCloudApi({ config: { ...CONFIG, webhookPort: port }, conversation: { contact: "+5511987654321" }, say: (l) => lines.push(l) });
+    await backend.open();
+    try {
+      const raw = JSON.stringify({
+        entry: [{ changes: [{ value: { messages: [{ id: "wamid.ONCE", from: "5511987654321", timestamp: "1758643200", type: "text", text: { body: "fechado" } }] } }] }],
+      });
+      for (let i = 0; i < 2; i++) {
+        const response = await fetch(`http://127.0.0.1:${port}/`, { method: "POST", headers: { "x-hub-signature-256": sign(raw) }, body: raw });
+        // Still 200: Meta retries anything else, and a duplicate is not an error.
+        expect(response.status).toBe(200);
+      }
+      expect((await backend.next())?.id).toBe("wamid.ONCE");
+      const second = await Promise.race([backend.next(), new Promise((resolve) => setTimeout(() => resolve("nothing"), 200))]);
+      expect(second).toBe("nothing");
+      expect(lines).toContain("[whatsapp] duplicate delivery of wamid.ONCE dropped");
+    } finally {
+      await backend.close();
+    }
+  });
+});

package/templates/bills-agent/packages/agent-runtime/test/whatsapp-session.test.ts

@@ -104,6 +104,38 @@ describe("a conversation a later process comes back to", () => {
   });
 });
 
+describe("when the provider's clock disagrees with ours", () => {
+  /** A provider whose window is shut whatever ours says: free text is refused the way Meta refuses it, templates go. */
+  class ShutProvider extends Recorder {
+    override async deliver(to: string, body: OutboundBody): Promise<SentMessage> {
+      if (body.kind === "template") return super.deliver(to, body);
+      return { id: "", state: "failed", refused: { rule: "session_window_closed", detail: "the provider refused the free-form message (400/131047)" } };
+    }
+  }
+
+  it("believes the provider: after a 131047 the window reads shut, and a template still goes", async () => {
+    const { channel: c, backend } = channel(TUESDAY, Math.floor(TUESDAY.getTime() / 1000) - 3600, new ShutProvider());
+    expect(c.sessionOpen).toBe(true);
+    const sent = await c.say("Recebemos, acordo quitado.");
+    expect(sent.refused?.rule).toBe("session_window_closed");
+    expect(c.sessionOpen).toBe(false);
+    expect(c.sessionRemainingSeconds).toBe(0);
+    // Refused by our own rule from here, so a second free-form message never reaches the provider.
+    expect((await c.say("de novo")).refused?.detail).toContain("more than 24h");
+    const template = await c.send({ kind: "template", template: "acordo_quitado", language: "pt_BR", variables: ["acordo-1042"] });
+    expect(template.refused).toBeUndefined();
+    expect(backend.delivered).toHaveLength(1);
+  });
+
+  it("reopens when the person writes again, because that is what opens a window at Meta too", () => {
+    const window = new SessionWindow([], { lastInboundAt: Math.floor(TUESDAY.getTime() / 1000) - 3600 });
+    window.observeProviderShut();
+    expect(window.open(TUESDAY)).toBe(false);
+    window.observeInbound(Math.floor(TUESDAY.getTime() / 1000));
+    expect(window.open(TUESDAY)).toBe(true);
+  });
+});
+
 describe("the local registry refuses what Meta would refuse", () => {
   it("a name the agent never declared", async () => {
     const { channel: c, backend } = channel(FRIDAY, Math.floor(TUESDAY.getTime() / 1000));