@codespar/cli 0.18.0 → 0.20.0

package/templates/checkout-agent/packages/agent-runtime/test/inspect.test.ts

@@ -9,7 +9,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { describe, expect, it } from "vitest";
 import { ProofBundle } from "@codespar/agent-core";
-import { assembleTimeline, redactorFor, renderHtml, renderText, VERIFY_NOTE } from "../src/inspect.js";
+import { assembleTimeline, redactorFor, renderHtml, renderText, REPLAY_NOTE, VERIFY_NOTE } from "../src/inspect.js";
 
 const ESCOLA = "financeiro@escola-aurora.example.com.br";
 const MASKED = "fi***@escola-aurora.example.com.br";
@@ -150,7 +150,7 @@ describe("the timeline `inspect` assembles from a bundle", () => {
 
   it("lists the receipts that came back, and the events that belong to no execution", () => {
     const report = assembleTimeline(fixtureBundle());
-    expect(report.receipts).toEqual([{ receipt_id: "rcpt_one", file: "receipts/rcpt_one.json", state: "paid", amount_minor: 185000, payee: MASKED, money_moved: false, sandbox: true, at: "2026-09-23T18:00:22.000Z" }]);
+    expect(report.receipts).toEqual([{ receipt_id: "rcpt_one", file: "receipts/rcpt_one.json", state: "paid", amount_minor: 185000, payee: MASKED, money_moved: false, sandbox: true, at: "2026-09-23T18:00:22.000Z", replayed: false }]);
     expect(report.executions.find((e) => e.execution_id === "exe_one")!.receipts).toEqual(["rcpt_one"]);
     expect(report.run_events.map((e) => e.type)).toEqual(["execution.refused_before_draft", "tool.refused"]);
   });
@@ -168,6 +168,67 @@ describe("the timeline `inspect` assembles from a bundle", () => {
   });
 });
 
+/**
+ * Issue #60: the rail answered a dispatch from an earlier presentation of the
+ * same attempt. Settled, and paid by somebody else. An attempt closed by a
+ * later look is the other case: the look cannot say whose payment it read, so
+ * it is never counted as a replay.
+ */
+function withReplays(): ProofBundle {
+  const bundle = fixtureBundle();
+  const run = "run_fixture_human_abc123";
+  for (const event of [
+    { run_id: run, execution_id: "exe_three", type: "execution.drafted", payload: { items: [{ alias: "escola", beneficiary: "Escola Aurora", payee: ESCOLA, amount: 185000, currency: "BRL" }], total: 185000, mode: "mandate", batch: { ref: "folha", batch_hash: "sha256:abc", index: 0, count: 2 } }, at: "2026-09-23T18:03:00.000Z", actor: AGENT },
+    { run_id: run, execution_id: "exe_three", type: "rail.dispatch", payload: { attempt_id: "ska_three", payee: ESCOLA, amount: 185000, rail: "stub", idempotency_key: "idk_three" }, at: "2026-09-23T18:03:01.000Z", actor: AGENT },
+    { run_id: run, execution_id: "exe_three", type: "rail.outcome", payload: { attempt_id: "ska_three", status: "settled", transaction_id: "tx_earlier", receipt_id: "rcpt_earlier", money_moved: false, sandbox: true, idempotent_replay: true }, at: "2026-09-23T18:03:02.000Z", actor: AGENT },
+    { run_id: run, execution_id: "exe_three", type: "execution.transition", payload: { from: "executing", to: "settled", at: "2026-09-23T18:03:03.000Z", actor: AGENT }, at: "2026-09-23T18:03:03.000Z", actor: AGENT },
+    { run_id: run, execution_id: "exe_four", type: "execution.drafted", payload: { items: [{ alias: "escola", beneficiary: "Escola Aurora", payee: ESCOLA, amount: 185000, currency: "BRL" }], total: 185000, mode: "mandate", batch: { ref: "folha", batch_hash: "sha256:abc", index: 1, count: 2 } }, at: "2026-09-23T18:04:00.000Z", actor: AGENT },
+    { run_id: run, execution_id: "exe_four", type: "rail.dispatch", payload: { attempt_id: "ska_four", payee: ESCOLA, amount: 185000, rail: "stub", idempotency_key: "idk_four" }, at: "2026-09-23T18:04:01.000Z", actor: AGENT },
+    { run_id: run, execution_id: "exe_four", type: "rail.outcome", payload: { attempt_id: "ska_four", status: "uncertain", code: "psp_dispatch_uncertain", message: "timeout" }, at: "2026-09-23T18:04:02.000Z", actor: AGENT },
+    { run_id: run, execution_id: "exe_four", type: "rail.reconcile", payload: { attempt_id: "ska_four", found: "settled" }, at: "2026-09-23T18:05:00.000Z", actor: AGENT },
+    { run_id: run, execution_id: "exe_four", type: "execution.transition", payload: { from: "executing", to: "settled", at: "2026-09-23T18:05:01.000Z", actor: AGENT }, at: "2026-09-23T18:05:01.000Z", actor: AGENT },
+  ]) {
+    bundle.event(event as Record<string, unknown>);
+  }
+  writeFileSync(join(bundle.dir, "receipts", "rcpt_earlier.json"), JSON.stringify({ receipt_id: "rcpt_earlier", state: "paid", payment: { amount_minor: 185000, payee: MASKED, money_moved: false, sandbox: true, at: "2026-09-23T17:00:00.000Z" }, actor: AGENT }));
+  return bundle;
+}
+
+describe("inspect says which settlements this run did not pay (#60)", () => {
+  it("a dispatch answered as a replay is settled and replayed; one closed by a later look is settled and not", () => {
+    const report = assembleTimeline(withReplays());
+    const byId = new Map(report.executions.map((e) => [e.execution_id, e]));
+    expect(byId.get("exe_one")!.replayed).toBe(false);
+    expect(byId.get("exe_three")).toMatchObject({ final_state: "settled", replayed: true });
+    expect(byId.get("exe_three")!.attempts[0]!.answer).toMatchObject({ status: "settled", receipt_id: "rcpt_earlier", idempotent_replay: true });
+    expect(byId.get("exe_four")).toMatchObject({ final_state: "settled", replayed: false });
+    expect(report.batches[0]!.lines.map((l) => [l.execution_id, l.replayed])).toEqual([
+      ["exe_three", true],
+      ["exe_four", false],
+    ]);
+    expect(report.receipts.map((r) => [r.receipt_id, r.replayed])).toEqual([
+      ["rcpt_earlier", true],
+      ["rcpt_one", false],
+    ]);
+  });
+
+  it("the text and the HTML say it where a reader looks: the rail line, the heading, the batch header and the receipt", () => {
+    const report = assembleTimeline(withReplays());
+    const text = renderText(report);
+    expect(text).toContain("execution exe_three — settled (replayed, not paid by this run)");
+    expect(text).toContain("rail says   settled (replayed)");
+    expect(text).toContain(REPLAY_NOTE);
+    expect(text).toContain("1 replayed, paid before and not by this run");
+    expect(text).toContain("rcpt_earlier  paid  R$ 1.850,00");
+    expect(text).toMatch(/rcpt_earlier .*read back from a replay, not paid by this run/);
+    expect(text).not.toMatch(/rcpt_one .*read back from a replay/);
+    expect(text).toContain("execution exe_four — settled · folha");
+    const html = renderHtml(report);
+    expect(html).toContain("replayed, not paid by this run");
+    expect(html).toContain(REPLAY_NOTE);
+  });
+});
+
 describe("masking: inspect never un-masks and never leaks a key it read raw", () => {
   it("no raw payee survives into the report, the text or the HTML", () => {
     const report = assembleTimeline(fixtureBundle());

package/templates/checkout-agent/packages/agent-runtime/test/outcome.test.ts

@@ -0,0 +1,72 @@
+/**
+ * The count the terminal prints and the one-shot exits by, on the cases a
+ * process test cannot stage cheaply: which reasons read as declined, and
+ * which exit code wins.
+ */
+import { describe, expect, it } from "vitest";
+import { isDeclinedReason, type Execution, type NotRunLine } from "@codespar/agent-core";
+import { outcomeExitCode, runOutcome } from "../src/outcome.js";
+
+function execution(state: Execution["state"], over: Partial<Pick<Execution, "reason" | "outcomes">> = {}): Execution {
+  return { id: `exec_${Math.random().toString(36).slice(2)}`, state, outcomes: [], ...over } as unknown as Execution;
+}
+
+const outcome = (status: "settled" | "failed" | "accepted", over: Record<string, unknown> = {}) => ({ index: 0, attempt_id: "att", status, ...over }) as Execution["outcomes"][number];
+
+describe("isDeclinedReason", () => {
+  it("is true of a charge nobody paid, a charge withdrawn and the organization's pause, and of nothing else", () => {
+    for (const reason of ["charge_expired", "charge_cancelled", "org_paused"]) expect(isDeclinedReason(reason)).toBe(true);
+    for (const reason of ["charge_issuer_error", "rail_failed", "psp_dispatch_failed", undefined, null]) expect(isDeclinedReason(reason)).toBe(false);
+  });
+});
+
+describe("runOutcome", () => {
+  it("counts a multi-item execution by payment: three paid and one failed", () => {
+    const e = execution("failed", { reason: "rail_failed", outcomes: [outcome("settled"), outcome("failed", { code: "psp_dispatch_failed" }), outcome("settled"), outcome("settled")] });
+    expect(runOutcome([e], [])).toEqual({ settled: 3, failed: 1, declined: 0, already_paid: 0, open: 0 });
+  });
+
+  it("counts a replayed settlement as already paid, attempt by attempt", () => {
+    const e = execution("settled", { outcomes: [outcome("settled", { replayed: true }), outcome("settled")] });
+    expect(runOutcome([e], [])).toMatchObject({ settled: 1, already_paid: 1 });
+  });
+
+  it("reads charge_expired, charge_cancelled and org_paused as declined, and charge_issuer_error as failed", () => {
+    const declined = ["charge_expired", "charge_cancelled", "org_paused"].map((code) => execution("failed", { reason: code as Execution["reason"], outcomes: [outcome("failed", { code })] }));
+    expect(runOutcome(declined, [])).toEqual({ settled: 0, failed: 0, declined: 3, already_paid: 0, open: 0 });
+    expect(runOutcome([execution("failed", { reason: "charge_issuer_error", outcomes: [outcome("failed", { code: "charge_issuer_error" })] })], [])).toMatchObject({ failed: 1, declined: 0 });
+  });
+
+  it("reads an execution closed with no attempt by its own reason", () => {
+    expect(runOutcome([execution("failed", { reason: "org_paused" }), execution("failed", { reason: "rail_failed" }), execution("denied"), execution("expired")], [])).toEqual({ settled: 0, failed: 1, declined: 3, already_paid: 0, open: 0 });
+  });
+
+  it("counts a line an earlier run holds as open, whatever that run's verdict, and a refused line as failed", () => {
+    const notRun: NotRunLine[] = [
+      { ref: "a", why: "in_progress", detail: "attempt_id_conflict" },
+      { ref: "b", why: "in_progress", detail: "in_progress" },
+      { ref: "c", why: "already_settled" },
+      { ref: "d", why: "refused", detail: "unreadable_line" },
+    ];
+    expect(runOutcome([], notRun)).toEqual({ settled: 0, failed: 1, declined: 0, already_paid: 1, open: 2 });
+  });
+});
+
+describe("outcomeExitCode", () => {
+  const executing = execution("executing");
+
+  it("1 wins over 3: something failed and something else was left executing", () => {
+    const failed = execution("failed", { reason: "rail_failed", outcomes: [outcome("failed")] });
+    const counted = runOutcome([failed, executing], []);
+    expect(counted).toMatchObject({ failed: 1, open: 1 });
+    expect(outcomeExitCode(counted, [failed, executing])).toBe(1);
+  });
+
+  it("3 when nothing failed and an execution of this run was left executing", () => {
+    expect(outcomeExitCode(runOutcome([executing], []), [executing])).toBe(3);
+  });
+
+  it("0 when a line is held by an earlier run and this run left nothing executing", () => {
+    expect(outcomeExitCode(runOutcome([], [{ ref: "a", why: "in_progress" }]), [])).toBe(0);
+  });
+});

package/templates/checkout-agent/packages/agent-runtime/test/poll-payer.test.ts

@@ -0,0 +1,64 @@
+/**
+ * The sandbox payer in the poll pays a receivable only once it is payable.
+ * It used to also pay "after a few looks", whatever it found, and on staging
+ * that paid a charge the issuer had ended in ERROR: the order read `settled`
+ * with no QR ever shown (OPEN_QUESTIONS §63, ent#1816). These drive the poll
+ * with a rail that stays unpayable for longer than the old patience.
+ */
+import { describe, expect, it } from "vitest";
+import type { ChargeInstrument, Execution, ExecutionEngine } from "@codespar/agent-core";
+import { pollUntilClosed } from "../src/poll.js";
+
+function instrument(payable: boolean): ChargeInstrument {
+  return { payable, status: payable ? "PENDING" : "PROCESSING", pix_copy_paste: payable ? "000201..." : null, boleto_bank_line: payable ? "2".repeat(47) : null, boleto_bar_code: null, due_date: "2026-09-30" };
+}
+
+/** An engine that answers one executing receivable, payable from look `payableFrom` on (never when undefined). */
+function engineWith(payableFrom?: number) {
+  let looks = 0;
+  const execution = (): Execution =>
+    ({
+      id: "exe_1",
+      state: "executing",
+      outcomes: [{ index: 0, attempt_id: "att_1_0", status: "accepted", transaction_id: "chg_1", instrument: instrument(payableFrom !== undefined && looks >= payableFrom) }],
+    }) as unknown as Execution;
+  const engine = {
+    get: () => execution(),
+    reconcile: async () => ((looks += 1), execution()),
+    markShown: () => true,
+    note: () => undefined,
+  } as unknown as ExecutionEngine;
+  return { engine, looks: () => looks };
+}
+
+function payerSpy() {
+  const calls: string[] = [];
+  return {
+    calls,
+    payer: {
+      kind: "stub" as const,
+      pay: async (chargeId: string) => (calls.push(chargeId), { ok: true as const, detail: "paid" }),
+      behave: () => undefined,
+    },
+  };
+}
+
+describe("the poll's sandbox payer pays only what is payable", () => {
+  it("a receivable that never becomes payable is never paid, however many looks the wait allows", async () => {
+    const { engine, looks } = engineWith(undefined);
+    const { payer, calls } = payerSpy();
+    const result = await pollUntilClosed(engine, "exe_1", { intervalMs: 0, timeoutMs: 0, maxRounds: 12, payer });
+    expect(looks()).toBe(12);
+    expect(calls).toEqual([]);
+    expect(result.payer_calls).toEqual([]);
+    expect(result.timed_out).toBe(true);
+  });
+
+  it("the payer plays once, on the first look that finds it payable", async () => {
+    const { engine } = engineWith(7);
+    const { payer, calls } = payerSpy();
+    const result = await pollUntilClosed(engine, "exe_1", { intervalMs: 0, timeoutMs: 0, maxRounds: 12, payer });
+    expect(calls).toEqual(["chg_1"]);
+    expect(result.payer_calls).toEqual(["paid"]);
+  });
+});

package/templates/checkout-agent/packages/agent-runtime/test/rerun-not-replayed.test.ts

@@ -0,0 +1,46 @@
+/**
+ * `notReplayed` reads a bundle's events for what only the world can do. These
+ * are the events as the engine writes them, by hand, so the reading is held
+ * to the shape and not to whatever a scenario happens to produce.
+ */
+import { describe, expect, it } from "vitest";
+import { notReplayed } from "../src/commands/rerun.js";
+
+const transition = (execution: string, to: string, reason?: string) => ({ type: "execution.transition", execution_id: execution, payload: { to, ...(reason ? { reason } : {}) } });
+const outcome = (execution: string, status: string) => ({ type: "rail.outcome", execution_id: execution, payload: { status } });
+
+describe("what a rerun does not replay", () => {
+  it("nothing, in a run that settled, failed on the rail or was denied by a person", () => {
+    expect(notReplayed([transition("a", "approved"), transition("a", "executing"), outcome("a", "settled"), transition("a", "settled")])).toEqual([]);
+    expect(notReplayed([transition("a", "executing"), outcome("a", "failed"), transition("a", "failed", "rail_failed")])).toEqual([]);
+    expect(notReplayed([transition("a", "awaiting_approval"), transition("a", "denied", "denied_by_approver")])).toEqual([]);
+    // A reason that is a key of every object is not one of the three this reads.
+    expect(notReplayed([transition("a", "denied", "constructor"), transition("b", "denied", "toString")])).toEqual([]);
+    // Left awaiting approval is the person not deciding, and a rerun does replay that.
+    expect(notReplayed([transition("a", "awaiting_approval")])).toEqual([]);
+  });
+
+  it("a mandate revoked or paused, and the organization's kill switch, at a gate or before a draft", () => {
+    expect(notReplayed([transition("a", "denied", "mandate_revoked")])).toEqual(["a mandate that was revoked"]);
+    expect(notReplayed([transition("a", "denied", "mandate_paused")])).toEqual(["a mandate that was paused"]);
+    expect(notReplayed([transition("a", "denied", "org_paused")])).toEqual(["an organization that paused every mandate"]);
+    expect(notReplayed([{ type: "execution.refused_before_draft", execution_id: null, payload: { reason: "mandate_revoked" } }])).toEqual(["a mandate that was revoked"]);
+  });
+
+  it("an uncertain answer from the rail, even one a later reconciliation settled", () => {
+    expect(notReplayed([transition("a", "executing"), outcome("a", "uncertain"), transition("a", "settled")])).toEqual(["an uncertain answer from the rail"]);
+    // Whichever of the engine's three events for it the bundle holds.
+    expect(notReplayed([{ type: "rail.uncertain", execution_id: "a", payload: {} }])).toEqual(["an uncertain answer from the rail"]);
+    expect(notReplayed([{ type: "execution.uncertain", execution_id: "a", payload: { detail: "attempt att_1: psp_dispatch_uncertain" } }])).toEqual(["an uncertain answer from the rail"]);
+  });
+
+  it("a charge issued and still out when the run ended, and not one that was paid", () => {
+    expect(notReplayed([transition("a", "executing"), outcome("a", "accepted")])).toEqual(["a payer who had not paid when it ended"]);
+    expect(notReplayed([transition("a", "executing"), outcome("a", "accepted"), transition("a", "settled")])).toEqual([]);
+  });
+
+  it("each thing once, in the order the run met them", () => {
+    const events = [transition("a", "executing"), outcome("a", "uncertain"), transition("b", "denied", "mandate_revoked"), { type: "execution.refused_before_draft", execution_id: null, payload: { reason: "mandate_revoked" } }];
+    expect(notReplayed(events)).toEqual(["an uncertain answer from the rail", "a mandate that was revoked"]);
+  });
+});

package/templates/checkout-agent/packages/agent-runtime/test/transition-line.test.ts

@@ -0,0 +1,29 @@
+/**
+ * #50: the line a person reads after an execution moves carries the rail's own
+ * code and message, verbatim, after the reason — on a failure and on an answer
+ * that left an attempt unknown — and nothing more when there is none.
+ */
+import type { Execution } from "@codespar/agent-core";
+import { describe, expect, it } from "vitest";
+import { transitionLine } from "../src/terminal.js";
+
+function execution(over: Partial<Execution>): Execution {
+  return { state: "settled", outcomes: [], ...over } as Execution;
+}
+
+describe("transitionLine", () => {
+  it("a failure: the reason, then the API's code and message", () => {
+    const failed = execution({ state: "failed", reason: "rail_failed", outcomes: [{ index: 0, attempt_id: "att_0", status: "failed", code: "insufficient_funds", message: "wallet cannot reserve the requested amount" }] });
+    expect(transitionLine(failed)).toBe("  -> failed (rail_failed): insufficient_funds — wallet cannot reserve the requested amount");
+  });
+
+  it("an unknown outcome: the reason, then what the API answered", () => {
+    const open = execution({ state: "executing", reason: "rail_uncertain", uncertain_answers: [{ attempt_id: "att_0", code: "provider_error", message: "no receiving identity" }] });
+    expect(transitionLine(open)).toBe("  -> executing (rail_uncertain): provider_error — no receiving identity");
+  });
+
+  it("nothing to add when nothing failed", () => {
+    expect(transitionLine(execution({ state: "settled" }))).toBe("  -> settled");
+    expect(transitionLine(execution({ state: "denied", reason: "cap_exceeded" as Execution["reason"] }))).toBe("  -> denied (cap_exceeded)");
+  });
+});

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

@@ -9,7 +9,7 @@
  */
 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 { mkdirSync, mkdtempSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { createServer, type Server } from "node:http";
 import type { AddressInfo } from "node:net";
 import { tmpdir } from "node:os";
@@ -46,11 +46,11 @@ function fixture(over: Record<string, unknown> = {}) {
   return { dir, receiptPath, keysPath };
 }
 
-function run(args: string[], cwd: string) {
+function run(args: string[], cwd: string, env: Record<string, string> = {}) {
   const result = spawnSync(process.execPath, [BIN, "verify", ...args], {
     cwd,
     // No CodeSpar key, no model key: a verifier holds nothing.
-    env: { ...process.env, CODESPAR_API_KEY: "", ANTHROPIC_API_KEY: "" },
+    env: { ...process.env, CODESPAR_API_KEY: "", ANTHROPIC_API_KEY: "", ...env },
     encoding: "utf8",
     timeout: 60_000,
   });
@@ -64,6 +64,10 @@ describe("codespar-agent verify", () => {
     expect(out.code).toBe(7);
     expect(out.stdout).toContain("SIGNATURE_ONLY");
     expect(out.stdout).toContain(RECEIPT_ID);
+    // The offline check reads neither the deployment nor the project, so two names for them that disagree are none of its business.
+    const disagreeing = run([receiptPath, "--keys", keysPath], dir, { CODESPAR_API_URL: "https://api.codespar.dev", CODESPAR_BASE_URL: "https://api.staging.codespar.dev" });
+    expect(disagreeing.code).toBe(7);
+    expect(disagreeing.stderr).not.toContain("disagree");
     expect(out.stdout).toContain("read_required");
     expect(out.stderr).toContain("carries CodeSpar's signature");
     expect(out.stderr).toContain("--from-api");
@@ -268,12 +272,12 @@ describe("codespar-agent verify --from-api", () => {
   });
 
   /** 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 }> {
+  function runAsync(args: string[], cwd: string, env?: NodeJS.ProcessEnv): 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: "" },
+        // Not the placeholder, which the guard refuses (#50); the underscore keeps it below the secret scan's key shape.
+        env: env ?? { ...process.env, CODESPAR_API_KEY: "csk_test_unit_0000", CODESPAR_API_URL: baseUrl, ANTHROPIC_API_KEY: "" },
       });
       let stdout = "";
       let stderr = "";
@@ -294,6 +298,20 @@ describe("codespar-agent verify --from-api", () => {
     expect(readFileSync(f.paths.copy, "utf8")).not.toContain(PAYEE);
   });
 
+  it("never prints or writes the mandate's signature a tenant's read carries, and shows what the chain sealed about the money", async () => {
+    const f = v4Fixture();
+    const mandateSig = "s".repeat(64);
+    served = { read: { ...f.read, mandate: { ...f.read.mandate, sig: mandateSig } }, keys: f.keys };
+    const human = await runAsync([f.paths.copy, "--from-api"], f.dir);
+    const json = await runAsync([f.paths.copy, "--from-api", "--json"], f.dir);
+    expect([human.code, json.code]).toEqual([0, 0]);
+    expect(human.stdout).toContain("payment      sandbox true, money_moved false");
+    expect(JSON.parse(json.stdout).sealed_payment).toEqual({ sandbox: true, money_moved: false });
+    for (const out of [human, json]) expect(out.stdout + out.stderr).not.toContain(mandateSig);
+    const files = readdirSync(f.dir, { recursive: true, encoding: "utf8" }).map((name) => join(f.dir, name)).filter((path) => statSync(path).isFile());
+    for (const path of files) expect(readFileSync(path, "utf8")).not.toContain(mandateSig);
+  });
+
   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 };
@@ -320,6 +338,81 @@ describe("codespar-agent verify --from-api", () => {
     expect(JSON.parse(out.stdout)).toMatchObject({ verdict: "signature_only", reason: "read_unavailable" });
   });
 
+  /*
+   * #66: the copy sits in its agent, and that agent's `.env` names the
+   * deployment as well as the key. A shell that exported neither must still
+   * read from the deployment the `.env` names, under `readDotEnv`'s rule: the
+   * environment wins, the file fills only what is unset.
+   */
+  function inAgent(dir: string, dotEnv: Record<string, string>): void {
+    writeFileSync(join(dir, "agent.yaml"), 'name: "verify-fixture-agent"\n');
+    writeFileSync(join(dir, ".env"), Object.entries(dotEnv).map(([k, v]) => `${k}=${v}\n`).join(""));
+  }
+
+  function bareEnv(over: Record<string, string> = {}): NodeJS.ProcessEnv {
+    const env: NodeJS.ProcessEnv = { ...process.env, ANTHROPIC_API_KEY: "", ...over };
+    for (const name of ["CODESPAR_API_KEY", "CODESPAR_API_URL", "CODESPAR_PROJECT_ID", "CODESPAR_BASE_URL", "CODESPAR_PROJECT"]) if (!(name in over)) delete env[name];
+    return env;
+  }
+
+  it("reads the receipt from the deployment the agent's .env names when the shell exported nothing", async () => {
+    const f = v4Fixture();
+    inAgent(f.dir, { CODESPAR_API_KEY: "csk_test_unit_0000", CODESPAR_API_URL: baseUrl });
+    served = { read: f.read, keys: f.keys };
+    asked.length = 0;
+    const out = await runAsync([f.paths.copy, "--from-api", "--json"], f.dir, bareEnv());
+    expect(out.code).toBe(0);
+    expect(JSON.parse(out.stdout)).toMatchObject({ verdict: "verified", keys_from: `${baseUrl}/.well-known/codespar-receipt-keys.json` });
+    expect(asked).toEqual([`GET /.well-known/codespar-receipt-keys.json anon`, `GET /v1/consumers/receipts/${RECEIPT_ID} auth`]);
+    expect(out.stdout + out.stderr).not.toContain("csk_test_unit_0000");
+  });
+
+  it("keeps an exported CODESPAR_API_URL over the one in the agent's .env, which still fills the unset key", async () => {
+    const f = v4Fixture();
+    inAgent(f.dir, { CODESPAR_API_KEY: "csk_test_unit_0000", CODESPAR_API_URL: "http://127.0.0.1:9" });
+    served = { read: f.read, keys: f.keys };
+    asked.length = 0;
+    const out = await runAsync([f.paths.copy, "--from-api", "--json"], f.dir, bareEnv({ CODESPAR_API_URL: baseUrl }));
+    expect(out.code).toBe(0);
+    expect(asked).toEqual([`GET /.well-known/codespar-receipt-keys.json anon`, `GET /v1/consumers/receipts/${RECEIPT_ID} auth`]);
+  });
+
+  const BOTH_ASKED = () => [`GET /.well-known/codespar-receipt-keys.json anon`, `GET /v1/consumers/receipts/${RECEIPT_ID} auth`];
+
+  it("reads from the deployment the .env names under the CLI's name, CODESPAR_BASE_URL", async () => {
+    const f = v4Fixture();
+    inAgent(f.dir, { CODESPAR_API_KEY: "csk_test_unit_0000", CODESPAR_BASE_URL: baseUrl });
+    served = { read: f.read, keys: f.keys };
+    asked.length = 0;
+    const out = await runAsync([f.paths.copy, "--from-api", "--json"], f.dir, bareEnv());
+    expect(out.code).toBe(0);
+    expect(asked).toEqual(BOTH_ASKED());
+  });
+
+  it("keeps the shell's deployment over the .env's when each uses the other name, either way round", async () => {
+    for (const [shellName, fileName] of [["CODESPAR_BASE_URL", "CODESPAR_API_URL"], ["CODESPAR_API_URL", "CODESPAR_BASE_URL"]] as const) {
+      const f = v4Fixture();
+      inAgent(f.dir, { CODESPAR_API_KEY: "csk_test_unit_0000", [fileName]: "http://127.0.0.1:9" });
+      served = { read: f.read, keys: f.keys };
+      asked.length = 0;
+      const out = await runAsync([f.paths.copy, "--from-api", "--json"], f.dir, bareEnv({ [shellName]: baseUrl }));
+      expect(out.stderr).not.toContain("disagree");
+      expect(out.code).toBe(0);
+      expect(asked).toEqual(BOTH_ASKED());
+    }
+  });
+
+  it("refuses two names that disagree as a usage error (2), before any request, and never as a failed verification (1)", async () => {
+    const f = v4Fixture();
+    inAgent(f.dir, { CODESPAR_API_KEY: "csk_test_unit_0000", CODESPAR_API_URL: baseUrl, CODESPAR_BASE_URL: "http://127.0.0.1:9" });
+    asked.length = 0;
+    const out = await runAsync([f.paths.copy, "--from-api"], f.dir, bareEnv());
+    expect(out.code).toBe(2);
+    expect(out.stderr).toContain(`CODESPAR_API_URL=${baseUrl}`);
+    expect(out.stderr).toContain("CODESPAR_BASE_URL=http://127.0.0.1:9");
+    expect(asked).toEqual([]);
+  });
+
   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);

package/templates/checkout-agent/packages/agent-runtime/test/whatsapp-rules.test.ts

@@ -71,6 +71,14 @@ describe("the collection rules, tried through the channel", () => {
     expect(backend.delivered).toHaveLength(0);
   });
 
+  it("refuses outside the hours in either locale, for the same rule, and only the detail is translated (#64)", () => {
+    const at = (locale: "pt-BR" | "en" | undefined) =>
+      checkOutbound(CONTACT, { kind: "text", text: "Oi, Joana!" }, { conversation: { contact: CONTACT }, hours: HOURS, now: () => OUTSIDE, ...(locale ? { locale } : {}) });
+    expect(at(undefined)).toEqual({ rule: "collection_hours", detail: "fora do horário de cobrança (08:00-20:00 America/Sao_Paulo); agora são 22:30" });
+    expect(at("pt-BR")).toEqual(at(undefined));
+    expect(at("en")).toEqual({ rule: "collection_hours", detail: "outside collection hours (08:00-20:00 America/Sao_Paulo); it is 22:30 now" });
+  });
+
   it("refuses a message to any contact but the one the conversation is bound to", () => {
     const refusal = checkOutbound("+5511900000000", { kind: "text", text: "sobre a sua divida" }, {
       conversation: { contact: CONTACT, subject: "acordo-1042" },

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

@@ -165,3 +165,80 @@ describe("the local registry refuses what Meta would refuse", () => {
     expect(templateArity("Oi {{ 1 }}.")).toBe(1);
   });
 });
+
+describe("a conversation speaks one locale, and its templates and taps are that locale's copies (#64)", () => {
+  const VENCIDA_PT: WhatsAppTemplate = {
+    name: "acordo_cobranca_vencida",
+    language: "pt_BR",
+    description: "expired",
+    body: "A cobrança do {{1}} venceu.",
+    buttons: [{ id: "emitir_nova", title: "Emitir nova", intent: "quero uma nova cobrança" }],
+  };
+  const VENCIDA_EN: WhatsAppTemplate = {
+    name: "acordo_cobranca_vencida",
+    language: "en_US",
+    description: "expired",
+    body: "The charge for {{1}} expired.",
+    buttons: [{ id: "emitir_nova", title: "Issue a new one", intent: "I want a new charge" }],
+  };
+
+  class Tapper extends Recorder {
+    private tapped = false;
+    override async next(): Promise<InboundMessage | undefined> {
+      if (this.tapped) return undefined;
+      this.tapped = true;
+      return { id: "wamid.tap", from: CONTACT, text: "Emitir nova", timestamp: Math.floor(FRIDAY.getTime() / 1000), reply: { type: "button", id: "emitir_nova", title: "Emitir nova" } };
+    }
+  }
+
+  function localized(locale: "pt-BR" | "en", backend: Recorder = new Recorder()) {
+    const c = new WhatsAppChannel({
+      backend,
+      conversation: { contact: CONTACT, subject: "acordo-1042" },
+      now: () => FRIDAY,
+      templates: [VENCIDA_PT, VENCIDA_EN],
+      session: { lastInboundAt: Math.floor(TUESDAY.getTime() / 1000) },
+      locale,
+    });
+    return { channel: c, backend };
+  }
+
+  it("an English conversation declares, and sends, the en_US copy with its own buttons", async () => {
+    const { channel: c, backend } = localized("en");
+    expect(c.language).toBe("en_US");
+    const declared = c.declaredTemplate("acordo_cobranca_vencida")!;
+    expect(declared.language).toBe("en_US");
+    const sent = await c.send({ kind: "template", template: declared.name, language: declared.language, variables: ["acordo-1042"] });
+    expect(sent.refused).toBeUndefined();
+    expect(backend.delivered).toEqual([{ kind: "template", template: "acordo_cobranca_vencida", language: "en_US", variables: ["acordo-1042"], buttons: [{ id: "emitir_nova", title: "Issue a new one" }] }]);
+  });
+
+  it("the default locale is pt-BR and picks the pt_BR copy", () => {
+    const c = new WhatsAppChannel({ backend: new Recorder(), conversation: { contact: CONTACT }, now: () => FRIDAY, templates: [VENCIDA_PT, VENCIDA_EN] });
+    expect(c.language).toBe("pt_BR");
+    expect(c.declaredTemplate("acordo_cobranca_vencida")?.body).toBe("A cobrança do {{1}} venceu.");
+  });
+
+  it("a tap is read as the intent its locale's copy declares: the same button id, the model handed that conversation's language", async () => {
+    const en = localized("en", new Tapper());
+    const pt = localized("pt-BR", new Tapper());
+    expect((await en.channel.next())?.text).toBe("I want a new charge");
+    expect((await pt.channel.next())?.text).toBe("quero uma nova cobrança");
+  });
+
+  it("refuses a language nobody registered, naming the ones that were", async () => {
+    const { channel: c, backend } = localized("en");
+    const sent = await c.send({ kind: "template", template: "acordo_cobranca_vencida", language: "es_MX", variables: ["acordo-1042"] });
+    expect(sent.refused?.rule).toBe("template_language_unknown");
+    expect(sent.refused?.detail).toContain("pt_BR, en_US");
+    expect(backend.delivered).toHaveLength(0);
+  });
+
+  it("an English conversation's refusal reaches the operator in English, and the rule it names is the same", async () => {
+    const said: string[] = [];
+    const c = new WhatsAppChannel({ backend: new Recorder(), conversation: { contact: CONTACT }, now: () => FRIDAY, templates: [VENCIDA_EN], session: { lastInboundAt: Math.floor(TUESDAY.getTime() / 1000) }, locale: "en", say: (l) => void said.push(l) });
+    const sent = await c.say("free text after the window");
+    expect(sent.refused?.rule).toBe("session_window_closed");
+    expect(said).toEqual([`  [whatsapp] refused (session_window_closed): ${sent.refused!.detail}`]);
+  });
+});

package/templates/checkout-agent/packages/agent-runtime/test/whatsapp-status-replies.test.ts

@@ -88,7 +88,7 @@ describe("1. a status webhook is read, and a failed outcome is an outcome not to
     const status = ch.log().find((l) => l.direction === "status")!;
     expect(status).toMatchObject({ kind: "status", message_id: sent.id, state: "failed", about: { execution_id: "exe_1", state: "settled" }, errors: [{ code: 131026, details: "not on whatsapp" }] });
     expect(failed).toEqual([status]);
-    expect(said.join("\n")).toContain("a pessoa NAO foi avisada");
+    expect(said.join("\n")).toContain("a pessoa NÃO foi avisada");
   });
 
   it("a read is recorded and nothing more: not consent, not an acknowledgement, not a reply", async () => {
@@ -121,6 +121,32 @@ describe("1. a status webhook is read, and a failed outcome is an outcome not to
     expect(failed.map((l) => l.about)).toEqual([{ execution_id: "exe_2", state: "settled" }]);
   });
 
+  it("a delivered that lands AFTER the failed does not un-fail the message, and a late sent does not rewind a read (#63)", async () => {
+    // The emulator's own order when a failure is posted while the send is still dispatching its sent/delivered webhooks.
+    class Interleaved extends Scripted {
+      override async deliver(to: string, body: OutboundBody): Promise<SentMessage> {
+        const sent = await super.deliver(to, body);
+        this.report({ message_id: sent.id, status: "sent", timestamp: 1, errors: [] });
+        this.report({ message_id: sent.id, status: "failed", timestamp: 2, errors: [{ code: 131026 }] });
+        this.report({ message_id: sent.id, status: "delivered", timestamp: 2, errors: [] });
+        return sent;
+      }
+    }
+    const backend = new Interleaved();
+    const failed: ChannelLogLine[] = [];
+    const ch = new WhatsAppChannel({ backend, conversation: { contact: CONTACT }, now: () => NOW, templates: TEMPLATES, onDeliveryFailed: (l) => failed.push(l) });
+    await ch.open();
+    const sent = await ch.send({ kind: "template", template: "acordo_quitado", language: "pt_BR", variables: ["acordo-1042"], about: { execution_id: "exe_3", state: "settled" } });
+    expect(ch.deliveryOf(sent.id)).toBe("failed");
+    expect(failed.map((l) => l.about)).toEqual([{ execution_id: "exe_3", state: "settled" }]);
+    // Every status is still in the conversation's log, in the order it arrived.
+    expect(ch.log().filter((l) => l.direction === "status").map((l) => l.state)).toEqual(["sent", "failed", "delivered"]);
+
+    backend.report({ message_id: "wamid.other", status: "read", timestamp: 3, errors: [] });
+    backend.report({ message_id: "wamid.other", status: "sent", timestamp: 1, errors: [] });
+    expect(ch.deliveryOf("wamid.other")).toBe("read");
+  });
+
   it("a status about a message an EARLIER run sent is tied back to the outcome that run recorded", async () => {
     const prior: ChannelLogLine = { at: NOW.toISOString(), direction: "out", contact: "+55*****4321", kind: "template", message_id: "wamid.old", state: "sent", about: { execution_id: "exe_old", state: "settled" } };
     const backend = new Scripted();

package/templates/collections-agent/README.md

@@ -1,7 +1,7 @@
 # {{name}}
 
 Scaffolded by `codespar init --template collections-agent` from the `collections-agent` starter kit
-(https://github.com/codespar/agent-starter-kits at `b766575306a71c9135c0d70e23d591e6523dc2f8`, agent 0.1.0).
+(https://github.com/codespar/agent-starter-kits at `d50c3d2fbb8707a4de67a6f8db5ee0bfb1b33794`, agent 0.1.0).
 
 The merchant's agent that collects: agrees terms with the payer inside a negotiation envelope, issues one bolepix per instalment with an idempotency key, presents the QR and the copy-and-paste in the conversation, and closes the cycle on commerce.charge.paid or commerce.charge.expired.
 
@@ -25,4 +25,4 @@ run at this root as they do in the kits repo:
 
 The agent's guide is [`agents/collections-agent/README.md`](agents/collections-agent/README.md); its commands run at this root
 (`npm run check`, `npm run eval`, `npm test`) or inside `agents/collections-agent/`. The manifest pins
-`cli: "@codespar/cli@0.14.0"`, the CLI version whose `agent run`/`eval` this agent was written for.
+`cli: "@codespar/cli@0.18.1"`, the CLI version whose `agent run`/`eval` this agent was written for.

package/templates/collections-agent/agents/collections-agent/.env.example

@@ -1,7 +1,10 @@
-# Test key from https://dashboard.codespar.dev (starts with csk_test_). A live key is refused.
+# Copy to agents/collections-agent/.env. `npm install` runs at the repository ROOT (npm workspace), then `npm start`.
+# Test key from https://codespar.dev/auth/signup (starts with csk_test_). A live key is refused.
 CODESPAR_API_KEY=csk_test_your_key_here
-# https://console.anthropic.com. Without it, `npm start` replays the recorded happy-path.
-ANTHROPIC_API_KEY=sk-ant-your_key_here
+# https://console.anthropic.com. Leave empty to replay the recorded happy path (the old placeholder sk-ant-your_key_here also counts as empty).
+ANTHROPIC_API_KEY=
+# Staging only (docs/OPEN_QUESTIONS.md, item 12): a staging test key also needs the staging base URL. A production key needs nothing here. The CodeSpar CLI calls the same setting CODESPAR_BASE_URL (and the project CODESPAR_PROJECT, here CODESPAR_PROJECT_ID): the kit reads either name, and a command that talks to the API refuses to start if the two disagree. A CLI login kept in ~/.codespar/config.json is not read by the kit: only the environment and this file are.
+# CODESPAR_API_URL=https://api.staging.codespar.dev
 
 # --- WhatsApp, the official Cloud API backend. Commented out and empty on purpose. ---
 # The default backend needs NONE of these: it talks to a local Cloud API emulator