@codespar/cli 0.18.1 → 0.20.0

package/templates/bills-agent/agents/bills-agent/test/consent-money.test.ts

@@ -0,0 +1,25 @@
+/**
+ * The consent is what a person reads before signing a mandate, so its caps
+ * are money as a person writes it, not the minor units the API takes.
+ */
+import { describe, expect, it } from "vitest";
+import { STRINGS } from "../src/strings.js";
+
+describe("the consent summary says its amounts in reais", () => {
+  it("the three caps, in pt-BR and in English", () => {
+    expect(STRINGS["pt-BR"].consentCaps(250000, 600000, 7200000)).toBe("  teto por pagamento: R$ 2.500,00    teto do mês: R$ 6.000,00    vitalício: R$ 72.000,00");
+    expect(STRINGS.en.consentCaps(250000, 600000, 7200000)).toBe("  cap per payment: R$2,500.00    cap per month: R$6,000.00    lifetime: R$72,000.00");
+  });
+
+  it("the sandbox credit too", () => {
+    expect(STRINGS["pt-BR"].consentFunded(600000, "acc_1", "dep_1")).toBe("Sandbox creditado: R$ 6.000,00 em acc_1 (deposit dep_1).");
+    expect(STRINGS.en.consentFunded(600000, "acc_1", "dep_1")).toBe("Sandbox credited: R$6,000.00 to acc_1 (deposit dep_1).");
+  });
+
+  it("no line of the consent counts in cents", () => {
+    for (const locale of ["pt-BR", "en"] as const) {
+      const lines = [STRINGS[locale].consentCaps(250000, 600000, 7200000), STRINGS[locale].consentFunded(600000, "acc_1", "dep_1")];
+      for (const line of lines) expect(line).not.toMatch(/centavos|cents|250000|600000|7200000/);
+    }
+  });
+});

package/templates/bills-agent/agents/bills-agent/test/dates-and-approval.test.ts

@@ -0,0 +1,98 @@
+/**
+ * What the first real-model runs showed (docs/OPEN_QUESTIONS.md §64): with no
+ * date of its own, the model called a bill due next week "venceu dia 05"; told
+ * both approval modes exist and not which one ran, it said a payment the
+ * titular approved needed "no extra approval". The tools now carry both facts.
+ */
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { daysUntil, fixedClock, localDate, type Execution, type ToolContext } from "@codespar/agent-core";
+import { setup, type Setup } from "@codespar/agent-runtime";
+import { agent } from "../src/kit.js";
+import { codesparPay, listBills } from "../src/modules/pix-out.js";
+
+function open(mode: "human" | "mandate", now: string): Setup {
+  return setup(agent, {
+    mode,
+    rail: "stub",
+    provider: "replay",
+    runsDir: mkdtempSync(join(tmpdir(), "bills-dates-runs-")),
+    stateDir: mkdtempSync(join(tmpdir(), "bills-dates-state-")),
+    now: fixedClock(now),
+    say: () => undefined,
+  });
+}
+
+function context(s: Setup, decide: boolean): ToolContext {
+  return {
+    engine: s.engine,
+    onExecution: async (execution: Execution) => {
+      let current = execution;
+      if (decide && current.state === "awaiting_approval") current = s.engine.approve(current.id, { id: "usr_demo", channel: "terminal" });
+      if (current.state === "approved") current = await s.engine.execute(current.id);
+      return current;
+    },
+  };
+}
+
+describe("the calendar the model reads", () => {
+  it("localDate is the day in the timezone, not in UTC", () => {
+    // 23:30 in Sao Paulo on the 28th is already the 29th in UTC.
+    expect(localDate(new Date("2026-09-29T02:30:00Z"), "America/Sao_Paulo")).toBe("2026-09-28");
+    expect(localDate(new Date("2026-09-29T02:30:00Z"), "UTC")).toBe("2026-09-29");
+  });
+
+  it("daysUntil counts whole days, negative once past", () => {
+    expect(daysUntil("2026-09-28", "2026-10-05")).toBe(7);
+    expect(daysUntil("2026-10-05", "2026-10-05")).toBe(0);
+    expect(daysUntil("2026-10-06", "2026-10-05")).toBe(-1);
+  });
+
+  it("list_bills carries today, from the pinned clock, and days_until_due per bill", async () => {
+    const s = open("human", "2026-09-28T14:00:00-03:00");
+    try {
+      const out = (await listBills({}, context(s, false))) as { today: string; bills: Array<{ alias: string; due: string; days_until_due: number }> };
+      expect(out.today).toBe("2026-09-28");
+      const mercado = out.bills.find((b) => b.alias === "mercado")!;
+      expect(mercado.due).toBe("2026-10-05");
+      expect(mercado.days_until_due).toBe(7);
+    } finally {
+      s.close();
+    }
+  });
+});
+
+describe("codespar_pay says who approved, so the model does not guess", () => {
+  const PIX = { action: "pix", items: [{ payee: "mercado", amount_minor: 64000 }] };
+
+  it("a person's approval is `human`", async () => {
+    const s = open("human", "2026-09-28T14:00:00-03:00");
+    try {
+      expect(await codesparPay(PIX, context(s, true))).toMatchObject({ status: "settled", approved_by: "human" });
+    } finally {
+      s.close();
+    }
+  });
+
+  it("nobody has approved an execution still waiting: `null`", async () => {
+    const s = open("human", "2026-09-28T14:00:00-03:00");
+    try {
+      expect(await codesparPay(PIX, context(s, false))).toMatchObject({ status: "awaiting_approval", approved_by: null });
+    } finally {
+      s.close();
+    }
+  });
+
+  it("the signed allowance's approval is `mandate`", async () => {
+    const s = open("mandate", "2026-09-28T14:00:00-03:00");
+    try {
+      // Warm the payee so `new_beneficiary` does not send it to a person.
+      await s.kit.warmUp!(s, ["mercado"], { id: "usr_demo", channel: "terminal" });
+      expect(await codesparPay(PIX, context(s, false))).toMatchObject({ status: "settled", approved_by: "mandate" });
+    } finally {
+      s.close();
+    }
+  });
+});

package/templates/bills-agent/agents/bills-agent/test/eval-runs.test.ts

@@ -0,0 +1,81 @@
+/**
+ * `npm run eval` writes a proof bundle per case and per scenario run, dozens a
+ * pass. They go to `runs/eval/`, so `runs/` holds what the person ran, and
+ * `inspect` and `rerun` still find an eval run by its id.
+ */
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, readdirSync } 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 BIN = resolve(AGENT_DIR, "../../packages/agent-runtime/bin.mjs");
+
+describe("npm run eval beside a person's own runs", () => {
+  const stateDir = mkdtempSync(join(tmpdir(), "bills-eval-runs-"));
+  const runsDir = join(stateDir, "runs");
+  const run = (command: string, args: string[]) => {
+    const result = spawnSync(process.execPath, [BIN, command, ...args], {
+      cwd: AGENT_DIR,
+      env: { ...process.env, ANTHROPIC_API_KEY: "", CODESPAR_API_KEY: "", BILLS_STATE_DIR: stateDir, BILLS_RUNS_DIR: runsDir },
+      encoding: "utf8",
+      timeout: 120_000,
+    });
+    return { code: result.status, stdout: result.stdout, stderr: result.stderr };
+  };
+  let mine = "";
+  let evalRuns: string[] = [];
+
+  beforeAll(() => {
+    const own = run("start", ["--input", "pague a escola de outubro", "--approve", "--json"]);
+    mine = (JSON.parse(own.stdout.trim()) as { run_id: string }).run_id;
+    expect(run("eval", []).code).toBe(0);
+    evalRuns = readdirSync(join(runsDir, "eval")).sort();
+  }, 120_000);
+
+  it("leaves runs/ with the person's run and one folder for the suite's", () => {
+    expect(readdirSync(runsDir).sort()).toEqual(["eval", mine].sort());
+    // 8 adversarial cases and 11 scenario runs.
+    expect(evalRuns).toHaveLength(19);
+    expect(evalRuns.some((id) => id.startsWith("run_adv_"))).toBe(true);
+  });
+
+  it("inspect finds an eval run by its id alone, and by eval/<id>", () => {
+    const id = evalRuns.find((r) => r.startsWith("run_adv_prompt-injection"))!;
+    for (const arg of [id, `eval/${id}`]) {
+      const out = run("inspect", [arg, "--json"]);
+      expect(out.code).toBe(0);
+      expect((JSON.parse(out.stdout.trim()) as { run: { run_id: string } }).run.run_id).toBe(id);
+    }
+    expect(run("inspect", [mine, "--json"]).code).toBe(0);
+  });
+
+  it("an unknown id lists the person's runs and counts the suite's, without listing them", () => {
+    const out = run("inspect", ["run_nope"]);
+    expect(out.code).toBe(1);
+    expect(out.stderr).toContain(`  ${mine}`);
+    expect(out.stderr).toContain(`19 more from \`npm run eval\` in ${join(runsDir, "eval")}`);
+    expect(out.stderr).not.toContain("run_adv_");
+    expect(out.stderr).not.toMatch(/^ {2}eval$/m);
+  });
+
+  it("the folder itself is not a run, and a path out of runs/ is not one either", () => {
+    for (const arg of ["eval", "eval/", "eval/../..", "../runs"]) {
+      const out = run("inspect", [arg]);
+      expect([arg, out.code]).toEqual([arg, 1]);
+      expect(out.stderr).toContain(`no proof bundle for run ${arg}`);
+      expect(out.stderr).not.toMatch(/^\s+at /m);
+    }
+  });
+
+  it("rerun replays an eval run by its id and leaves the rerun beside it, not among the person's", () => {
+    const id = evalRuns.find((r) => r.startsWith("run_adv_prompt-injection"))!;
+    const out = run("rerun", [id, "--json"]);
+    expect(out.code).toBe(0);
+    const report = JSON.parse(out.stdout.trim()) as { same_states: boolean; rerun_id: string };
+    expect(report.same_states).toBe(true);
+    expect(readdirSync(join(runsDir, "eval"))).toContain(report.rerun_id);
+    expect(readdirSync(runsDir).sort()).toEqual(["eval", mine].sort());
+  });
+});

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

@@ -1,2 +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."}
+{"kind":"assistant_step","tool_calls":[{"id":"tc_4","name":"codespar_pay","input":{"action":"pix","items":[{"payee":"escola","amount_minor":30000,"description":"excursão"}]}}]}
+{"kind":"assistant_step","reply":"Propus R$ 300,00 para a Escola Aurora (excursão). O resultado está no terminal."}

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

@@ -1,2 +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."}
+{"kind":"assistant_step","reply":"Propus R$ 400,00 para a Escola Aurora (material). Como é o primeiro pagamento a esse favorecido, o mandato pediu sua aprovação."}

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

@@ -0,0 +1,161 @@
+/**
+ * #64 on the approval path: the locale changes what the titular READS and
+ * nothing about what their answer DECIDES. The same answer to the pt-BR
+ * question and to the English one ends in the same state, and the approval
+ * artifact names the same approver.
+ *
+ * And the resolution, end to end: `--locale` beats `agent.yaml`, which beats
+ * the default, and the run's bundle records the locale it ran in.
+ */
+import { spawnSync } from "node:child_process";
+import { cpSync, mkdtempSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+import { fixedClock, type Locale } from "@codespar/agent-core";
+import { handleExecution, parseApproval, setup, type Setup } from "@codespar/agent-runtime";
+import { agent } from "../src/kit.js";
+
+const AGENT_DIR = resolve(import.meta.dirname, "..");
+const NODE = process.execPath;
+const BIN = resolve(AGENT_DIR, "../../packages/agent-runtime/bin.mjs");
+const APPROVER = { id: "usr_demo_titular", channel: "terminal" };
+/** Every answer the `[s/N]` parser has a rule for, both languages, plus what falls through to no. */
+const ANSWERS = ["s", "sim", "y", "yes", " SIM ", "Yes", "n", "nao", "não", "no", "", "talvez", "si"];
+
+function open(locale: Locale | undefined, dir = AGENT_DIR): Setup {
+  return setup(dir === AGENT_DIR ? agent : { ...agent, dir }, {
+    mode: "human",
+    rail: "stub",
+    provider: "replay",
+    runsDir: mkdtempSync(join(tmpdir(), "bills-locale-runs-")),
+    stateDir: mkdtempSync(join(tmpdir(), "bills-locale-state-")),
+    now: fixedClock("2026-09-23T14:00:00-03:00"),
+    say: () => undefined,
+    ...(locale ? { locale } : {}),
+  });
+}
+
+/** Proposes one payment and answers the approval question with `answer`; returns the final state, the question asked and the console. */
+async function decideOnce(locale: Locale, answer: string) {
+  const s = open(locale);
+  const asked: string[] = [];
+  const said: string[] = [];
+  try {
+    const draft = await s.engine.draft({ items: [{ payee: "escola", amount: 185000, description: "mensalidade de outubro" }] });
+    if (!draft.ok) throw new Error(draft.reason);
+    const final = await handleExecution(draft.execution, {
+      setup: s,
+      approver: APPROVER,
+      ask: async (q) => {
+        asked.push(q);
+        return answer;
+      },
+      say: (l) => void said.push(l),
+    });
+    const approvers = s.bundle.readApprovals().map((a) => a.approver);
+    return { state: final.state, asked, said, approvers };
+  } finally {
+    s.close();
+  }
+}
+
+describe("the approval question decides the same in both locales", () => {
+  it.each(ANSWERS)("answer %j", async (answer) => {
+    const pt = await decideOnce("pt-BR", answer);
+    const en = await decideOnce("en", answer);
+    // What was shown differs...
+    expect(pt.asked).toEqual(["  Aprovar este pagamento? [s/N] "]);
+    expect(en.asked).toEqual(["  Approve this payment? [y/N] "]);
+    // ...and what was decided does not.
+    expect(en.state).toBe(pt.state);
+    expect(en.approvers).toEqual(pt.approvers);
+    expect(pt.state).toBe(parseApproval(answer) === "approve" ? "settled" : "denied");
+  });
+
+  it("prints the execution in the run's locale, accents included", async () => {
+    const pt = await decideOnce("pt-BR", "s");
+    const en = await decideOnce("en", "y");
+    expect(pt.said.join("\n")).toContain("execução exe_");
+    expect(pt.said.join("\n")).toContain("total (calculado pelo core): R$ 1.850,00");
+    expect(pt.said.join("\n")).toMatch(/recibo: /);
+    expect(en.said.join("\n")).toContain("execution exe_");
+    expect(en.said.join("\n")).toContain("total (computed by the core): R$1,850.00");
+    expect(en.said.join("\n")).toMatch(/receipt: /);
+  });
+});
+
+describe("which locale a run speaks", () => {
+  function copyWithLocale(locale: string | undefined): string {
+    const dir = mkdtempSync(join(tmpdir(), "bills-locale-agent-"));
+    cpSync(AGENT_DIR, dir, { recursive: true, filter: (src) => !/node_modules|\/runs|\.codespar/.test(src) });
+    const yaml = readFileSync(join(dir, "agent.yaml"), "utf8").replace(/^locale:.*\n/m, locale ? `locale: ${locale}\n` : "");
+    writeFileSync(join(dir, "agent.yaml"), yaml);
+    return dir;
+  }
+
+  it("is --locale, else agent.yaml's locale, else pt-BR; and the bundle records it", () => {
+    const cases: Array<[string | undefined, Locale | undefined, Locale]> = [
+      [undefined, undefined, "pt-BR"],
+      ["en", undefined, "en"],
+      ["en", "pt-BR", "pt-BR"],
+      ["pt-BR", "en", "en"],
+    ];
+    for (const [manifest, flag, expected] of cases) {
+      const s = open(flag, copyWithLocale(manifest));
+      try {
+        expect(s.locale).toBe(expected);
+        expect(s.bundle.readMeta()?.["locale"]).toBe(expected);
+        expect(s.strings).toBe(agent.kit.strings[expected]);
+      } finally {
+        s.close();
+      }
+    }
+  });
+
+  function run(args: string[]) {
+    const stateDir = mkdtempSync(join(tmpdir(), "bills-locale-cli-"));
+    const result = spawnSync(NODE, [BIN, "start", ...args], {
+      cwd: AGENT_DIR,
+      env: { ...process.env, ANTHROPIC_API_KEY: "", CODESPAR_API_KEY: "", BILLS_STATE_DIR: stateDir, BILLS_RUNS_DIR: join(stateDir, "runs") },
+      encoding: "utf8",
+      timeout: 60_000,
+    });
+    const runs = join(stateDir, "runs");
+    let meta: Record<string, unknown> | undefined;
+    try {
+      const [dir] = readdirSync(runs);
+      meta = JSON.parse(readFileSync(join(runs, dir!, "run.json"), "utf8")) as Record<string, unknown>;
+    } catch {
+      meta = undefined;
+    }
+    return { code: result.status, stdout: result.stdout, stderr: result.stderr, meta };
+  }
+
+  it("`npm start -- --locale en` prints the code's lines in English and pays the same", () => {
+    const pt = run(["--input", "pague a escola de outubro", "--approve", "--json"]);
+    const en = run(["--input", "pague a escola de outubro", "--approve", "--json", "--locale", "en"]);
+    expect(pt.code).toBe(0);
+    expect(en.code).toBe(0);
+    expect(pt.stderr).toContain("execução");
+    expect(pt.stderr).toContain("calculado pelo core");
+    expect(en.stderr).toContain("execution");
+    expect(en.stderr).toContain("computed by the core");
+    expect(en.stderr).not.toContain("execução");
+    expect(pt.meta?.["locale"]).toBe("pt-BR");
+    expect(en.meta?.["locale"]).toBe("en");
+    // The machine output is the same contract in both: same states, same receipts, no locale-dependent field.
+    const shape = (o: string) => {
+      const p = JSON.parse(o) as { executions: Array<{ state: string; total_minor: number; receipt_ids: string[] }> };
+      return p.executions.map((e) => ({ state: e.state, total_minor: e.total_minor, receipts: e.receipt_ids.length }));
+    };
+    expect(shape(en.stdout)).toEqual(shape(pt.stdout));
+  });
+
+  it("an unknown --locale is a usage error, before anything runs", () => {
+    const out = run(["--input", "pague a escola de outubro", "--locale", "es"]);
+    expect(out.code).toBe(2);
+    expect(out.stderr).toContain("--locale must be pt-BR or en");
+    expect(out.meta).toBeUndefined();
+  });
+});

package/templates/bills-agent/agents/bills-agent/test/mandate-state.test.ts

@@ -0,0 +1,108 @@
+/**
+ * What the kit says about a mandate after it was revoked: `inspect` on the
+ * run that met the revocation, and the consent that replaces the mandate.
+ */
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, relative, resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+import type { ApiClient } from "@codespar/sdk";
+import { ProofBundle, loadMandate, type Mandate } from "@codespar/agent-core";
+import { assembleTimeline, loadScenario, renderText, runScenario } from "@codespar/agent-runtime";
+import { agent } from "../src/kit.js";
+import { runEmbeddedConsent } from "../src/modules/embedded-consent.js";
+
+const AGENT_DIR = resolve(import.meta.dirname, "..");
+
+describe("npm run inspect on the run that met a revocation", () => {
+  it("the header says revoked, from the source that answered, and no longer says active", async () => {
+    const runsDir = mkdtempSync(join(tmpdir(), "bills-inspect-revoked-"));
+    const run = await runScenario(agent, loadScenario(agent, "mandate-revoked"), { mode: "human", runsDir });
+    const text = renderText(assembleTimeline(ProofBundle.open(runsDir, run.run_id)!));
+    const header = text.split("\n")[2]!;
+
+    // The line two below it, which the header used to contradict.
+    expect(text).toMatch(/was revoked \(source: stub\)/);
+    expect(header).toMatch(/^ {2}mandate revoked \(source: stub, \d\d:\d\d:\d\d; active in the snapshot at the start of the run\), expires /);
+    expect(text).not.toMatch(/^ {2}mandate active,/m);
+  });
+
+  it("a run that met none still says active", async () => {
+    const runsDir = mkdtempSync(join(tmpdir(), "bills-inspect-active-"));
+    const run = await runScenario(agent, loadScenario(agent, "happy-path"), { mode: "human", runsDir });
+    expect(renderText(assembleTimeline(ProofBundle.open(runsDir, run.run_id)!)).split("\n")[2]).toMatch(/^ {2}mandate active, expires /);
+  });
+});
+
+/** The four calls a consent makes, answered as the sandbox answers them; `status` is what `GET /v1/mandates/{id}` says of the mandate the file already holds. */
+function fakeApi(example: Mandate, status: string | Error): { api: ApiClient; reads: string[] } {
+  const reads: string[] = [];
+  const api = {
+    post: async (path: string) => {
+      if (path === "/v1/consents/init") return { token: "tok_test", expires_at: "2026-09-23T18:30:00.000Z" };
+      if (path === "/v1/consents/{token}/submit") {
+        return {
+          mandate_id: "cm_new",
+          signature: "0".repeat(64),
+          mandate: { consumer_id: example.consumer_id, agent_id: example.agent_id, purpose: example.purpose, currency: "BRL", cap_minor: example.cap_minor, per_tx_cap_minor: example.per_tx_cap_minor, merchant_pin_kind: "pix-key", merchant_allowlist: example.beneficiaries.map((b) => b.payee), expires_at: 1821312000 },
+        };
+      }
+      return { amount_minor: 600000, account: "acc_test", deposit_id: "dep_test" };
+    },
+    get: async (_path: string, options: { path: { id: string } }) => {
+      reads.push(options.path.id);
+      if (status instanceof Error) throw status;
+      return { status, expires_at: "2027-09-23T00:00:00.000Z", org_paused: false };
+    },
+  };
+  return { api: api as unknown as ApiClient, reads };
+}
+
+describe("npm run consent", () => {
+  const example = loadMandate(join(AGENT_DIR, "mandate.example.json"));
+  const NOT_YET = "O mandato ainda não existe.";
+
+  async function consent(options: { previous?: Mandate; status?: string | Error; locale?: "pt-BR" | "en" }) {
+    const dir = mkdtempSync(join(tmpdir(), "bills-consent-"));
+    const mandatePath = join(dir, ".codespar", "mandate.json");
+    if (options.previous) {
+      mkdirSync(join(dir, ".codespar"));
+      writeFileSync(mandatePath, JSON.stringify(options.previous));
+    }
+    const said: string[] = [];
+    const { api, reads } = fakeApi(example, options.status ?? "active");
+    const mandate = await runEmbeddedConsent({ api, example, mandatePath, say: (l) => said.push(l), confirm: async () => true, now: () => new Date("2026-09-23T18:00:00.000Z"), ...(options.locale ? { locale: options.locale } : {}) });
+    return { said, reads, mandate, mandatePath, file: relative(process.cwd(), mandatePath) };
+  }
+
+  it("with no mandate in the file, says it does not exist yet and reads no status", async () => {
+    const out = await consent({});
+    expect(out.said[1]).toContain(NOT_YET);
+    expect(out.reads).toEqual([]);
+  });
+
+  it("after a revocation, names the revoked mandate the file holds instead of saying none exists", async () => {
+    const previous = { ...example, id: "cm_old" };
+    const out = await consent({ previous, status: "revoked" });
+    expect(out.reads).toEqual(["cm_old"]);
+    expect(out.said[1]).toBe(`Já existe um mandato em ${out.file}: cm_old, revogado na API. Este é o consentimento de um mandato novo, que passa a ser o do arquivo (sandbox):`);
+    expect(out.said.join("\n")).not.toContain(NOT_YET);
+    // And the file is the new mandate's afterwards, as the line said.
+    expect((JSON.parse(readFileSync(out.mandatePath, "utf8")) as { id: string }).id).toBe("cm_new");
+    expect(out.mandate.id).toBe("cm_new");
+  });
+
+  it("says the state the API answers, whatever it is, and says so when it does not answer", async () => {
+    const previous = { ...example, id: "cm_old" };
+    expect((await consent({ previous, status: "active" })).said[1]).toContain("cm_old, ativo na API.");
+    expect((await consent({ previous, status: "paused" })).said[1]).toContain("cm_old, pausado na API.");
+    expect((await consent({ previous, status: new Error("ECONNRESET") })).said[1]).toContain("cm_old, com estado que a API não respondeu.");
+    expect((await consent({ previous, status: "revoked", locale: "en" })).said[1]).toContain("already holds a mandate: cm_old, revoked on the API.");
+  });
+
+  it("a file it cannot read does not stop a new consent", async () => {
+    const out = await consent({ previous: { id: "not a mandate" } as unknown as Mandate });
+    expect(out.said[1]).toContain(NOT_YET);
+    expect(out.mandate.id).toBe("cm_new");
+  });
+});

package/templates/bills-agent/agents/bills-agent/test/refused-before-draft.test.ts

@@ -0,0 +1,81 @@
+/**
+ * A request made under a revoked mandate creates no execution: the engine
+ * refuses it before a draft. The terminal used to say nothing about it (the
+ * recorded reply even says "see the result on the terminal"), and only
+ * `inspect` showed the event. Driven as real processes, over a scratch state
+ * whose stub mandate is revoked between two runs.
+ */
+import { spawn, spawnSync } from "node:child_process";
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import { describe, expect, it } from "vitest";
+
+const AGENT_DIR = resolve(import.meta.dirname, "..");
+const BIN = resolve(AGENT_DIR, "../../packages/agent-runtime/bin.mjs");
+const SCHOOL = "pague a escola de outubro";
+const BASE_ENV = { ANTHROPIC_API_KEY: "", CODESPAR_API_KEY: "", CODESPAR_AGENT_NOW: "2026-10-07T14:00:00-03:00" };
+
+function run(args: string[], env: Record<string, string>) {
+  const result = spawnSync(process.execPath, [BIN, "start", ...args], { cwd: AGENT_DIR, env: { ...process.env, ...BASE_ENV, ...env }, encoding: "utf8", timeout: 60_000 });
+  return { code: result.status, stdout: result.stdout, stderr: result.stderr };
+}
+
+/** A scratch state holding one settled payment, with the stub mandate then revoked: what `codespar mandate revoke` leaves behind. */
+function revoked(label: string): Record<string, string> {
+  const stateDir = mkdtempSync(join(tmpdir(), `bills-refused-${label}-`));
+  const env = { BILLS_STATE_DIR: stateDir, BILLS_RUNS_DIR: join(stateDir, "runs") };
+  const first = run(["--input", SCHOOL, "--approve", "--json"], env);
+  expect(first.code).toBe(0);
+  const mandateId = (JSON.parse(first.stdout.trim()) as { mandate_id: string }).mandate_id;
+  const db = new DatabaseSync(join(stateDir, "state.db"));
+  db.prepare("INSERT OR REPLACE INTO stub_mandate_status (mandate_id, status, reason, updated_at) VALUES (?, 'revoked', 'revoked by the test', ?)").run(mandateId, new Date().toISOString());
+  db.close();
+  return env;
+}
+
+describe("a request under a revoked mandate, one-shot", () => {
+  it("names the refusal and its reason on the terminal, counts it, and exits 1", () => {
+    const out = run(["--input", SCHOOL, "--approve"], revoked("text"));
+    expect(out.stderr).toContain("-> refused_before_draft (mandate_revoked)");
+    expect(out.stdout).toContain("resultado deste run: 0 liquidada(s), 1 com falha ou recusada(s)");
+    expect(out.code).toBe(1);
+  });
+
+  it("carries the same refusal in --json, with no execution", () => {
+    const out = run(["--input", SCHOOL, "--approve", "--json"], revoked("json"));
+    const payload = JSON.parse(out.stdout.trim()) as { executions: unknown[]; run_outcome: { failed: number }; refused_before_draft: Array<{ reason: string; detail: string }> };
+    expect(payload.executions).toHaveLength(0);
+    expect(payload.refused_before_draft).toHaveLength(1);
+    expect(payload.refused_before_draft[0]).toMatchObject({ reason: "mandate_revoked" });
+    expect(payload.refused_before_draft[0]?.detail).not.toBe("");
+    expect(payload.run_outcome.failed).toBe(1);
+    expect(out.code).toBe(1);
+  });
+});
+
+describe("a request under a revoked mandate, interactive", () => {
+  it("names the refusal under the turn that made it", async () => {
+    const env = revoked("interactive");
+    const out = await new Promise<{ stdout: string; stderr: string }>((done, fail) => {
+      const child = spawn(process.execPath, [BIN, "start", "--transcript", "scenarios/mandate-revoked.transcript.jsonl"], { cwd: AGENT_DIR, env: { ...process.env, ...BASE_ENV, ...env } });
+      let stdout = "";
+      let stderr = "";
+      let typed = false;
+      // Typed when the prompt shows: readline drops a line that arrives before the question.
+      const feed = () => {
+        if (!typed && stderr.includes("> ")) {
+          typed = true;
+          child.stdin.end(SCHOOL + "\n");
+        }
+      };
+      child.stdout.on("data", (chunk: Buffer) => { stdout += chunk.toString(); });
+      child.stderr.on("data", (chunk: Buffer) => { stderr += chunk.toString(); feed(); });
+      child.on("error", fail);
+      child.on("close", () => done({ stdout, stderr }));
+    });
+    expect(out.stderr).toContain("-> refused_before_draft (mandate_revoked)");
+    expect(out.stdout).toContain("1 com falha ou recusada(s)");
+  });
+});

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

@@ -0,0 +1,76 @@
+/**
+ * Issue #60 on the one-off payment: `codespar_pay` says `paid: true` only for
+ * a payment this call made. A bill's attempt id comes from its own execution,
+ * so the rail cannot replay one at dispatch today; the rail is scripted to
+ * answer the way the API answers a repeat, so the report is pinned before
+ * anything makes that reachable.
+ */
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { fixedClock, type Execution, type StubRail, type ToolContext } from "@codespar/agent-core";
+import { setup, type Setup } from "@codespar/agent-runtime";
+import { agent } from "../src/kit.js";
+import { codesparPay } from "../src/modules/pix-out.js";
+
+const APPROVER = { id: "usr_demo", channel: "terminal" };
+
+function open(): Setup {
+  return setup(agent, {
+    mode: "human",
+    rail: "stub",
+    provider: "replay",
+    runsDir: mkdtempSync(join(tmpdir(), "bills-replay-runs-")),
+    stateDir: mkdtempSync(join(tmpdir(), "bills-replay-state-")),
+    now: fixedClock("2026-09-23T14:00:00-03:00"),
+    say: () => undefined,
+  });
+}
+
+function context(s: Setup): ToolContext {
+  return {
+    engine: s.engine,
+    onExecution: async (execution: Execution) => {
+      let current = execution;
+      if (current.state === "awaiting_approval") current = s.engine.approve(current.id, APPROVER);
+      if (current.state === "approved") current = await s.engine.execute(current.id);
+      return current;
+    },
+  };
+}
+
+const PIX = { action: "pix", items: [{ payee: "mercado", amount_minor: 64000, description: "compras da semana" }] };
+
+describe("codespar_pay: a settlement this call did not make is not reported as paid (#60)", () => {
+  it("a payment this call made is paid, and not replayed", async () => {
+    const s = open();
+    try {
+      const result = await codesparPay(PIX, context(s));
+      expect(result).toMatchObject({ status: "settled", paid: true, replayed: false });
+    } finally {
+      s.close();
+    }
+  });
+
+  it("a payment the rail answered from an earlier presentation is settled, replayed, and not paid by this call", async () => {
+    const s = open();
+    try {
+      const rail = s.rail as StubRail;
+      const pay = rail.pay.bind(rail);
+      rail.pay = async (payment) => {
+        const outcome = await pay(payment);
+        return outcome.status === "settled" ? { ...outcome, replayed: true } : outcome;
+      };
+      const result = (await codesparPay(PIX, context(s))) as { status: string; paid: boolean; replayed: boolean; receipt_ids: string[] };
+      expect(result).toMatchObject({ status: "settled", paid: false, replayed: true });
+      expect(result.receipt_ids).toHaveLength(1);
+
+      const oneShot = agent.kit.oneShotPayload({ setup: s, reply: "", toolCalls: [], executions: s.engine.list(), startedAt: 0 }) as { executions: Array<{ state: string; replayed: boolean }> };
+      expect(oneShot.executions).toEqual([expect.objectContaining({ state: "settled", replayed: true })]);
+      expect(agent.kit.describeExecution(s.engine.list()[0]!, s).join("\n")).toContain("esta execução não moveu dinheiro");
+    } finally {
+      s.close();
+    }
+  });
+});