@codespar/cli 0.16.0 → 0.18.0

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

@@ -0,0 +1,182 @@
+/**
+ * §46's three product gaps, as the channel now answers them, with no network:
+ * a status webhook is read (a `failed` of an outcome's message is that
+ * outcome NOT told), a tapped quick reply becomes a turn only as the intent a
+ * declared template gave it, and the registry carries a fallback for an
+ * outcome the kit has no copy for. The same behaviour against the emulator is
+ * in the repository's `test/whatsapp-emulator.integration.test.ts`, and the
+ * `check` rule that requires the fallback, asked of the shipped agents, in
+ * `test/whatsapp-fallback-check.test.ts`: both read this repository's other
+ * agents and scripts, which a template made from one agent does not carry.
+ */
+import { describe, expect, it } from "vitest";
+import type { WhatsAppTemplate } from "@codespar/agent-core";
+import { WhatsAppChannel } from "../src/channels/whatsapp/index.js";
+import { buildSendRequest, parseInbound, type CloudApiConfig } from "../src/channels/whatsapp/cloud-api.js";
+import type { ChannelBackend, ChannelLogLine, InboundMessage, OutboundBody, SentMessage, StatusUpdate } from "../src/channels/types.js";
+
+const CONTACT = "+5511987654321";
+const NOW = new Date("2026-09-23T17:00:00Z");
+
+/** A backend the test drives: it queues what the person does and hands the channel the statuses the test reports. */
+class Scripted implements ChannelBackend {
+  readonly name = "scripted";
+  readonly live = false;
+  readonly delivered: OutboundBody[] = [];
+  private listener: ((s: StatusUpdate) => void) | undefined;
+  constructor(private readonly inbox: InboundMessage[] = []) {}
+  async open(): Promise<void> {}
+  async next(): Promise<InboundMessage | undefined> {
+    return this.inbox.shift();
+  }
+  async deliver(_to: string, body: OutboundBody): Promise<SentMessage> {
+    this.delivered.push(body);
+    return { id: `wamid.test.${this.delivered.length}`, state: "sent" };
+  }
+  onStatus(listener: (s: StatusUpdate) => void): void {
+    this.listener = listener;
+  }
+  report(status: StatusUpdate): void {
+    this.listener?.(status);
+  }
+  async close(): Promise<void> {}
+}
+
+const TEMPLATES: WhatsAppTemplate[] = [
+  { name: "acordo_quitado", language: "pt_BR", description: "paid", body: "Oi! {{1}} quitado." },
+  {
+    name: "acordo_cobranca_vencida",
+    language: "pt_BR",
+    description: "expired",
+    body: "Oi! A cobranca do {{1}} venceu.",
+    buttons: [
+      { id: "emitir_nova", title: "Emitir nova", intent: "quero que voce emita uma nova cobranca para o meu acordo" },
+      { id: "agora_nao", title: "Agora nao", intent: "agora nao quero uma nova cobranca" },
+    ],
+  },
+  { name: "atendimento_atualizacao", language: "pt_BR", description: "fallback", body: "Oi! Temos uma atualizacao.", fallback: true },
+];
+
+function channel(inbox: InboundMessage[] = []) {
+  const backend = new Scripted(inbox);
+  const said: string[] = [];
+  const failed: ChannelLogLine[] = [];
+  const ch = new WhatsAppChannel({ backend, conversation: { contact: CONTACT, subject: "acordo-1042" }, now: () => NOW, templates: TEMPLATES, say: (l) => said.push(l), onDeliveryFailed: (l) => failed.push(l) });
+  return { ch, backend, said, failed };
+}
+
+const tap = (id: string, extra: Partial<InboundMessage["reply"]> = {}): InboundMessage => ({ id: `wamid.in.${id}`, from: CONTACT, text: "Emitir nova", timestamp: 1790190000, reply: { type: "button_reply", id, title: "Emitir nova", ...extra } });
+
+describe("1. a status webhook is read, and a failed outcome is an outcome not told", () => {
+  it("parses statuses, with Meta's errors, out of the same delivery that carries messages", () => {
+    const parsed = parseInbound({
+      entry: [{ changes: [{ value: { statuses: [{ id: "wamid.a", status: "failed", timestamp: "1790190000", errors: [{ code: 131026, title: "Message undeliverable", error_data: { details: "not on whatsapp" } }] }, { id: "wamid.b", status: "read", timestamp: "1790190001" }, { id: "wamid.c", status: "deleted" }] } }] }],
+    });
+    expect(parsed.statuses).toEqual([
+      { message_id: "wamid.a", status: "failed", timestamp: 1790190000, errors: [{ code: 131026, title: "Message undeliverable", details: "not on whatsapp" }] },
+      { message_id: "wamid.b", status: "read", timestamp: 1790190001, errors: [] },
+    ]);
+  });
+
+  it("a failed status of a message that told an outcome is recorded, reaches the operator and the outcome's owner, and names the outcome", async () => {
+    const { ch, backend, said, failed } = channel();
+    await ch.open();
+    (ch as unknown as { session: { observeInbound(t: number): void } }).session.observeInbound(Math.floor(NOW.getTime() / 1000));
+    const sent = await ch.send({ kind: "text", text: "Recebemos, acordo quitado.", about: { execution_id: "exe_1", state: "settled" } });
+    backend.report({ message_id: sent.id, status: "failed", timestamp: 1790190100, errors: [{ code: 131026, details: "not on whatsapp" }] });
+    expect(ch.deliveryOf(sent.id)).toBe("failed");
+    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");
+  });
+
+  it("a read is recorded and nothing more: not consent, not an acknowledgement, not a reply", async () => {
+    const { ch, backend, said, failed } = channel();
+    await ch.open();
+    (ch as unknown as { session: { observeInbound(t: number): void } }).session.observeInbound(Math.floor(NOW.getTime() / 1000));
+    const sent = await ch.send({ kind: "text", text: "Recebemos.", about: { execution_id: "exe_1", state: "settled" } });
+    backend.report({ message_id: sent.id, status: "read", timestamp: 1790190100, errors: [] });
+    expect(ch.log().filter((l) => l.direction === "status").map((l) => l.state)).toEqual(["read"]);
+    expect(failed).toEqual([]);
+    expect(said).toEqual([]);
+    // A read is not a turn either.
+    expect(await ch.next()).toBeUndefined();
+  });
+
+  it("a failure the provider reports BEFORE the send answered (the emulator posts statuses synchronously) is still tied to its outcome", async () => {
+    class Eager 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: "failed", timestamp: 1, errors: [{ code: 131026 }] });
+        return sent;
+      }
+    }
+    const backend = new Eager();
+    const failed: ChannelLogLine[] = [];
+    const ch = new WhatsAppChannel({ backend, conversation: { contact: CONTACT }, now: () => NOW, templates: TEMPLATES, onDeliveryFailed: (l) => failed.push(l) });
+    await ch.open();
+    await ch.send({ kind: "template", template: "acordo_quitado", language: "pt_BR", variables: ["acordo-1042"], about: { execution_id: "exe_2", state: "settled" } });
+    await new Promise((r) => setTimeout(r, 0));
+    expect(failed.map((l) => l.about)).toEqual([{ execution_id: "exe_2", state: "settled" }]);
+  });
+
+  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();
+    const failed: ChannelLogLine[] = [];
+    const ch = new WhatsAppChannel({ backend, conversation: { contact: CONTACT }, now: () => NOW, templates: TEMPLATES, priorLines: [prior], onDeliveryFailed: (l) => failed.push(l) });
+    await ch.open();
+    backend.report({ message_id: "wamid.old", status: "failed", timestamp: 1, errors: [{ code: 131026 }] });
+    expect(failed[0]?.about).toEqual({ execution_id: "exe_old", state: "settled" });
+  });
+});
+
+describe("2. a tapped quick reply is a turn, as the intent a declared template gave it", () => {
+  it("parses a button_reply, a list_reply and a template's quick-reply button, id and context kept", () => {
+    const msg = (m: Record<string, unknown>) => ({ entry: [{ changes: [{ value: { messages: [{ from: "5511987654321", timestamp: "1", ...m }] } }] }] });
+    expect(parseInbound(msg({ id: "a", type: "interactive", interactive: { type: "button_reply", button_reply: { id: "emitir_nova", title: "Emitir nova" } }, context: { id: "wamid.offer" } })).messages[0]?.reply).toEqual({ type: "button_reply", id: "emitir_nova", title: "Emitir nova", context_id: "wamid.offer" });
+    expect(parseInbound(msg({ id: "b", type: "interactive", interactive: { type: "list_reply", list_reply: { id: "3x", title: "3x", description: "tres" } } })).messages[0]?.reply).toEqual({ type: "list_reply", id: "3x", title: "3x" });
+    expect(parseInbound(msg({ id: "c", type: "button", button: { payload: "emitir_nova", text: "Emitir nova" } })).messages[0]?.reply).toEqual({ type: "button", id: "emitir_nova", title: "Emitir nova" });
+    // What this channel cannot read is still named, not turned into an empty message.
+    expect(parseInbound(msg({ id: "d", type: "image" })).ignored).toEqual([{ id: "d", type: "image" }]);
+    expect(parseInbound(msg({ id: "e", type: "interactive", interactive: { type: "nfm_reply" } })).ignored).toEqual([{ id: "e", type: "interactive:nfm_reply" }]);
+  });
+
+  it("a declared id is a turn whose text is the declared intent, never the title", async () => {
+    const { ch } = channel([tap("emitir_nova")]);
+    const turn = await ch.next();
+    expect(turn?.text).toBe("quero que voce emita uma nova cobranca para o meu acordo");
+    const line = ch.log().at(-1)!;
+    expect(line).toMatchObject({ direction: "in", kind: "reply", reply: { id: "emitir_nova", title: "Emitir nova" }, text: "quero que voce emita uma nova cobranca para o meu acordo" });
+  });
+
+  it("an id no template declares is not a turn: recorded, told to the operator, and the next real turn is what comes back", async () => {
+    const typed: InboundMessage = { id: "wamid.in.text", from: CONTACT, text: "oi", timestamp: 1790190001 };
+    const { ch, said } = channel([tap("pagar_tudo", { title: "Pagar tudo" }), typed]);
+    const turn = await ch.next();
+    expect(turn?.text).toBe("oi");
+    expect(ch.log()[0]).toMatchObject({ kind: "reply", refused: { rule: "reply_not_offered" }, reply: { id: "pagar_tudo" } });
+    expect(said.join("\n")).toContain("reply_not_offered");
+  });
+
+  it("a tap that names a message this conversation did not send with that reply is not a turn either", async () => {
+    const { ch } = channel([tap("emitir_nova", { context_id: "wamid.somebody_else" })]);
+    expect(await ch.next()).toBeUndefined();
+    expect(ch.log()[0]?.refused?.rule).toBe("reply_not_offered");
+  });
+
+  it("a template goes out with the quick replies its declaration offers, and the log says which", async () => {
+    const { ch, backend } = channel();
+    await ch.send({ kind: "template", template: "acordo_cobranca_vencida", language: "pt_BR", variables: ["acordo-1042"] });
+    expect((backend.delivered[0] as { buttons?: unknown }).buttons).toEqual([{ id: "emitir_nova", title: "Emitir nova" }, { id: "agora_nao", title: "Agora nao" }]);
+    expect(ch.log()[0]?.offered).toEqual(["emitir_nova", "agora_nao"]);
+    const config: CloudApiConfig = { baseUrl: "http://sim", phoneNumberId: "1", accessToken: "t", verifyToken: "v", appSecret: "s", apiVersion: "v22.0", webhookPort: 0 };
+    const request = buildSendRequest(config, CONTACT, backend.delivered[0]!) as { body: string };
+    expect(JSON.parse(request.body).template.components).toEqual([
+      { type: "body", parameters: [{ type: "text", text: "acordo-1042" }] },
+      { type: "button", sub_type: "quick_reply", index: "0", parameters: [{ type: "payload", payload: "emitir_nova" }] },
+      { type: "button", sub_type: "quick_reply", index: "1", parameters: [{ type: "payload", payload: "agora_nao" }] },
+    ]);
+  });
+});

package/templates/kits.lock.json

@@ -1,8 +1,8 @@
 {
   "format": 1,
   "kits_repo": "https://github.com/codespar/agent-starter-kits",
-  "kits_ref": "8f130b7cdc30510c929e6f7ebb07184f763e6ce4",
-  "commit": "8f130b7cdc30510c929e6f7ebb07184f763e6ce4",
+  "kits_ref": "b766575306a71c9135c0d70e23d591e6523dc2f8",
+  "commit": "b766575306a71c9135c0d70e23d591e6523dc2f8",
   "vendored_packages": [
     {
       "name": "@codespar/agent-core",
@@ -32,7 +32,27 @@
         "npm run consent -- --yes",
         "npm start"
       ],
-      "hash": "sha256:e75c5293ae7d576fa5263b9f7bc8accbd4b83d781a5220f4bbc4368f8746abc3"
+      "hash": "sha256:bd44befa0b4626949ec753c8f472994e4fb2819b637cc92d1c7f943386e50ad2"
+    },
+    "checkout-agent": {
+      "source": "agents/checkout-agent",
+      "description": "The merchant's agent that sells in the conversation: the customer builds a cart the code prices, the attendant (or the sales policy) confirms the order, one bolepix is issued with an idempotency key, the QR and the copy-and-paste go to the customer, and the order closes on commerce.charge.paid.",
+      "version": "0.1.0",
+      "cli": "@codespar/cli@0.14.0",
+      "mcp": "@codespar/mcp@0.5.8",
+      "vendored": {
+        "@codespar/agent-core": "0.1.0",
+        "@codespar/agent-runtime": "0.1.0"
+      },
+      "root_scripts": {
+        "whatsapp:emulator": "node scripts/whatsapp-emulator.mjs"
+      },
+      "next_steps": [
+        "cp agents/checkout-agent/.env.example agents/checkout-agent/.env   # then fill in your keys",
+        "npm install",
+        "npm start"
+      ],
+      "hash": "sha256:6f3ce0270015c774e879304b18ee55d8a9592e58815b0921ec51f973879c50d0"
     },
     "collections-agent": {
       "source": "agents/collections-agent",
@@ -44,12 +64,15 @@
         "@codespar/agent-core": "0.1.0",
         "@codespar/agent-runtime": "0.1.0"
       },
+      "root_scripts": {
+        "whatsapp:emulator": "node scripts/whatsapp-emulator.mjs"
+      },
       "next_steps": [
         "cp agents/collections-agent/.env.example agents/collections-agent/.env   # then fill in your keys",
         "npm install",
         "npm start"
       ],
-      "hash": "sha256:0588aa52d737058375f5a617844071998a5db3147bddd73447577f756cd11c10"
+      "hash": "sha256:2461b06b9d985c430679dd6012ec050e38bb8ad6f5f636ef9af281e65d180fc5"
     },
     "hello-agent": {
       "source": "agents/hello-agent",
@@ -66,7 +89,7 @@
         "npm install",
         "npm start"
       ],
-      "hash": "sha256:f75d8ddb2d1808e337e7c785a3801bbce127a6822de9b761f5c57c28ce1848b9"
+      "hash": "sha256:aeef951a3f3725cb11ac19b55cf11997d7621633514b32663c7f2f373c7758c2"
     },
     "supplier-payments-agent": {
       "source": "agents/supplier-payments-agent",
@@ -83,7 +106,7 @@
         "npm install",
         "npm start"
       ],
-      "hash": "sha256:a89cb114242eb0f5e3114801341dbf90ea54e7665f73d24bb68a9fdf452b2753"
+      "hash": "sha256:58a9b44a7a4aae130124fc45708237207fc91ad9165298c44b0eb48ef6172dc3"
     }
   }
 }

package/templates/supplier-payments-agent/README.md

@@ -1,7 +1,7 @@
 # {{name}}
 
 Scaffolded by `codespar init --template supplier-payments-agent` from the `supplier-payments-agent` starter kit
-(https://github.com/codespar/agent-starter-kits at `8f130b7cdc30510c929e6f7ebb07184f763e6ce4`, agent 0.1.0).
+(https://github.com/codespar/agent-starter-kits at `b766575306a71c9135c0d70e23d591e6523dc2f8`, agent 0.1.0).
 
 A company delegates its suppliers, commissions and payroll to an agent that pays them in batches under one signed mandate. A batch is a loop of executions: one refusal does not stop the others, and re-running it pays nobody twice.
 

package/templates/supplier-payments-agent/agents/supplier-payments-agent/AGENTS.md

@@ -15,7 +15,7 @@ You are editing a reference agent of the CodeSpar Agent Starter Kits. These rule
 11. **Sandbox by construction.** Only `csk_test_` keys. Never commit `.env`, `.codespar/` or `runs/`. The pre-commit secret scan and the CI both refuse a key-shaped string.
 12. **Before you say a task is done:** `npm run check`, `npm run eval` (adversarial suite plus scenarios, on the replay provider, no model needed) and `npm test` at the repository root. All green, or it is not done.
 13. **Use the CodeSpar MCP and skills** (`@codespar/mcp@0.5.8`, pinned in `agent.yaml`) to learn the real API. When the spec in `docs/spec-v5.1.1.md` and the API diverge, follow the API and log it in `docs/OPEN_QUESTIONS.md`.
-14. **Say which signature you mean.** A receipt sealed since the API added Ed25519 carries a signature anybody can check against the published key set, with no credential — that is what `npm run verify -- <receipt-file>` does. "Verifiable by a third party" is true of THAT and of nothing else here: a receipt sealed before the change carries no Ed25519 signature and never will, and the approval artifact is still HMAC with a local development key. Write the phrase only where `Ed25519` is written too; `npm run check` fails otherwise.
+14. **Say which signature you mean.** A receipt sealed since the API added Ed25519 carries a signature anybody can check against the published key set, with no credential — that is what `npm run verify -- <receipt-file>` does. "Verifiable by a third party" is true of THAT and of nothing else here: a receipt sealed before the change carries no Ed25519 signature and never will, and the approval artifact is still HMAC with a local development key: what reaches a third party is its hash, sealed into a v4 receipt, which proves what was approved and never who. Write the phrase only where `Ed25519` is written too; `npm run check` fails otherwise.
 15. **No telemetry.** Nothing in this repository phones home.
 
 `AGENTS.md` and `CLAUDE.md` are the same file; the CI fails if they diverge. Edit both or neither.

package/templates/supplier-payments-agent/agents/supplier-payments-agent/CLAUDE.md

@@ -15,7 +15,7 @@ You are editing a reference agent of the CodeSpar Agent Starter Kits. These rule
 11. **Sandbox by construction.** Only `csk_test_` keys. Never commit `.env`, `.codespar/` or `runs/`. The pre-commit secret scan and the CI both refuse a key-shaped string.
 12. **Before you say a task is done:** `npm run check`, `npm run eval` (adversarial suite plus scenarios, on the replay provider, no model needed) and `npm test` at the repository root. All green, or it is not done.
 13. **Use the CodeSpar MCP and skills** (`@codespar/mcp@0.5.8`, pinned in `agent.yaml`) to learn the real API. When the spec in `docs/spec-v5.1.1.md` and the API diverge, follow the API and log it in `docs/OPEN_QUESTIONS.md`.
-14. **Say which signature you mean.** A receipt sealed since the API added Ed25519 carries a signature anybody can check against the published key set, with no credential — that is what `npm run verify -- <receipt-file>` does. "Verifiable by a third party" is true of THAT and of nothing else here: a receipt sealed before the change carries no Ed25519 signature and never will, and the approval artifact is still HMAC with a local development key. Write the phrase only where `Ed25519` is written too; `npm run check` fails otherwise.
+14. **Say which signature you mean.** A receipt sealed since the API added Ed25519 carries a signature anybody can check against the published key set, with no credential — that is what `npm run verify -- <receipt-file>` does. "Verifiable by a third party" is true of THAT and of nothing else here: a receipt sealed before the change carries no Ed25519 signature and never will, and the approval artifact is still HMAC with a local development key: what reaches a third party is its hash, sealed into a v4 receipt, which proves what was approved and never who. Write the phrase only where `Ed25519` is written too; `npm run check` fails otherwise.
 15. **No telemetry.** Nothing in this repository phones home.
 
 `AGENTS.md` and `CLAUDE.md` are the same file; the CI fails if they diverge. Edit both or neither.

package/templates/supplier-payments-agent/agents/supplier-payments-agent/README.md

@@ -15,7 +15,7 @@ npm run start:supplier
 > roda a folha de outubro
 ```
 
-Three lines, three approvals, three receipts under `runs/<run-id>/receipts/`. Run it again and every line answers `already_settled`.
+Three lines, one question ("3 linha(s), total R$ …, batch_hash sha256:…" — answer `todas`, `todas exceto 2` or `nenhuma`), three approval artifacts, three receipts under `runs/<run-id>/receipts/`. Run it again and every line answers `already_settled`.
 
 - `ANTHROPIC_API_KEY` can stay empty: the agent then replays a recorded transcript. The old placeholder `sk-ant-your_key_here` counts as empty.
 - One-shot form: `npm start -- --input "roda a folha de outubro" --approve --json`.
@@ -31,10 +31,11 @@ Both shapes deliver it, now that the core dispatches every attempt and names eve
 | Property | Where it comes from |
 |---|---|
 | One refusal does not stop the others | The loop in `src/modules/batch-payout.ts` `continue`s and never breaks. Each line reaches its own terminal state. |
-| One `attempt_id` per call | The core derives it from each execution's own `idempotency_key`, so the rail's own idempotence covers each line separately. |
-| Repeating pays nobody twice | A durable claim pairs (mandate, batch, line) with the execution covering it. Settled is skipped, still-open is never re-opened, and only an execution that ended without moving money is retried. |
+| One `attempt_id` per call | The core derives it from the line itself — mandate, `batch_hash`, position — so the same line of the same list is the same attempt on any machine, and the quote it presents carries no approval time that would make it a different payment. |
+| Repeating pays nobody twice | A durable claim pairs (mandate, batch, line) with the execution covering it. Settled is skipped, still-open is never re-opened, and only an execution that ended without moving money is retried. Behind the claim, the API answers a repeated `attempt_id` from its record of that attempt (ent#1671): a settled line replays its original receipt (marked `replayed`), one in flight stays open, and only a line the provider refused is paid again, under the next generation of its id. A line whose id the API holds for a different payment is reported `attempt_id_conflict` and never re-drafted. |
 | Each approved line stays attested | One approval artifact per line, each with its own `items_hash` bound to the mandate version. `runs/<run-id>/approval.json` holds them in approval order. |
 | The approved list is bound as a set | The list is hashed once, before any line is drafted, and every artifact of the batch carries that `batch_hash` with the line's own position and the list's length. So a bundle of three artifacts says "1, 2 and 4 of 4" and not "three payments". A line the human denied has an execution and no artifact; a line that left the list after it was approved has neither, and the run that would drop it is refused before it drafts anything. |
+| One gesture approves the list, with a veto per line | In the interactive terminal a batch is put in front of the operator once: every line, the total and the `batch_hash` prefix. `todas` approves the list, `todas exceto 3,7` vetoes those positions, `nenhuma` denies it. The gesture decides each line as it arrives and approves nothing by itself: every approved line still mints its own artifact carrying the `batch_hash` the gesture was taken on, and the gesture is a `batch.gesture` event in the bundle naming what was approved and vetoed. A vetoed line is a denied execution with no artifact and appears in the report's `denied`; a line that claims another list under the same ref is not covered by the gesture and is denied. The one-shot and the scenario runner still pass one decision to every line. |
 
 The claim is taken **before** the channel can run the execution. Claiming afterwards would leave a settled payout unclaimed if the process died in between, and that is exactly the double payment. A crash the other way round leaves a claim on an open execution, which the next run reports as `in_progress` and refuses to duplicate — the operator closes it with `npm run approve`, `npm run resume` or `npm run reconcile`.
 
@@ -45,7 +46,7 @@ The claim is taken **before** the channel can run the execution. Claiming afterw
 | The model proposes, the code executes | `codespar_pay` creates executions in `drafted`. Only `ExecutionEngine` in `@codespar/agent-core` checks mandate, caps, allowlist, `escalate_above` and `items_hash`, and only it reaches `executing`. |
 | A batch cannot be fractioned | The lines come from `payables.ts`, never from the tool call. `codespar_pay` refuses `batch_ref` sent together with `items` or `total_minor`, so a model being steered cannot add a payee to a payroll or split one line into five. |
 | Partial failure is visible | `scenarios/partial-batch-failure`: the rail declines one supplier, the other two settle, and the report names which line failed and why. |
-| Two modes, one trail | `approval: human` (default): the operator approves each line. `approval: mandate`: the agent runs what the signed allowance covers and asks above `escalate_above`. Same code, same states, same receipts. |
+| Two modes, one trail | `approval: human` (default): the operator approves the list, with a veto per line. `approval: mandate`: the agent runs what the signed allowance covers and asks above `escalate_above`. Same code, same states, same receipts. |
 | Readable refusal | Cap per payout, cap per month, payee outside the mandate, revoked mandate, outside hours: each names itself in the trail and in the chat. |
 | Sandbox by construction | A key that does not start with `csk_test_` fails before any network call. |
 
@@ -76,7 +77,7 @@ Not in this kit: WhatsApp, `embedded-consent` (see above), scheduling a batch fo
 | `npm run resume` | After a crash: dispatches only what the outbox proves was never sent, reconciles the rest from the rail, expires what went stale. Never pays twice. |
 | `npm run rerun <run-id>` | Replays a recorded run with no network and checks the state sequence matches. |
 | `npm run inspect <run-id> [--json] [--html <file>]` | Reads a run's proof bundle back as a timeline. On a batch it prints the header once — the `batch_hash`, how many lines the approved list held, how many are attested here — and then one timeline per line. `2 of 4 line(s) attested · 3 with an execution · no execution for line(s) 3` is what a batch that did not all run looks like when you read it back. |
-| `npm run verify -- <receipt-file> [--json] [--keys <file>] [--url <url>]` | Checks a receipt's Ed25519 signature against CodeSpar's published key set. No key and no agent needed: it runs on a receipt file copied to another machine. The exit code is the verdict — 0 verified, 1 tampered, 3 unsigned, 4 unknown key, 5 the key set could not be read, 6 not a receipt. |
+| `npm run verify -- <receipt-file> [--json] [--keys <file>] [--url <url>] [--approval <file>] [--from-api]` | Checks a receipt's Ed25519 signature against CodeSpar's published key set, then recomputes its chain from the API's receipt read under the published recipe, then holds the sealed approval hashes against the approval artifact. The read needs no key and no agent; a run's masked copy proves the signature only, unless `--from-api` reads the receipt with this agent's key (nothing is written). The exit code is the verdict — 0 verified, 1 tampered, 3 unsigned, 4 unknown key, 5 the key set could not be read, 6 not a receipt, 7 signature only (the body was not bound), 8 the body is not the sealed one, 9 the sealed approval is not the artifact's. |
 | `npm run reconcile` | Compares local state with the rail. Closes an `executing` execution only from a recorded rail outcome; what the rail has not answered stays `executing` with an `execution.uncertain` event, for a human. Never dispatches. |
 
 ## The proof bundle
@@ -88,7 +89,7 @@ transcript.jsonl        the conversation and the tool calls
 approval.json           the approval artifacts of the run — for a batch, one per line, in approval order
 mandate.snapshot.json   the mandate as it was, keys masked
 events.jsonl            every transition and every rail event, each with its actor
-receipts/               the receipts the rail returned, each stamped with the actor
+receipts/               the receipts the rail returned, each stamped with the actor; the payee is the one the receipt sealed
 run.json                mode, rail, mandate id
 ```
 
@@ -100,13 +101,14 @@ The receipt copies carry both of the API's seals. `receipt_sig` is the HMAC, whi
 npm run verify -- runs/<run-id>/receipts/<receipt-id>.json
 ```
 
-That reads the public key set from `/.well-known/codespar-receipt-keys.json`, picks the key the receipt names, rebuilds `codespar-receipt:v1:<receipt_id>:<chain>` and checks it with stock `node:crypto` — no key, no API key, no CodeSpar call that could be refused. `--keys <file>` uses a saved copy of the key set instead and touches no network at all; `--json` puts the verdict on stdout. `--url` names another deployment's key set: the default is production, and every deployment publishes its own key under the same `kid`, so a sandbox receipt checked against the production keys reads `tampered`. The signature covers the receipt id and the chain, so the masking above does not disturb it, and the file verifies on a machine that has never seen this repository. A receipt sealed before the API had the capability answers `unsigned`, which is not a failure: it has no Ed25519 signature and never will, and its HMAC seal is unaffected.
+That reads the public key set from `/.well-known/codespar-receipt-keys.json`, picks the key the receipt names, rebuilds `codespar-receipt:v1:<receipt_id>:<chain>` and checks it with stock `node:crypto` — no key, no API key, no CodeSpar call that could be refused. `--keys <file>` uses a saved copy of the key set instead and touches no network at all; `--json` puts the verdict on stdout. `--url` names another deployment's key set: the default is production. The signature covers the receipt id and the chain, so the masking above does not disturb it, and the file verifies on a machine that has never seen this repository; on its own the copy answers `signature_only`, because it masks the payee the chain sealed. `npm run verify -- runs/<run-id>/receipts/<receipt-id>.json --from-api` reads the unmasked receipt from the API with this agent's key, recomputes the chain from it, and holds its sealed approval hashes against the artifact the copy names in `approval.json`: `verified` then means this payment was made against the list that artifact approved. Nothing unmasked is written. A receipt sealed before the API had the capability answers `unsigned`, which is not a failure: it has no Ed25519 signature and never will, and its HMAC seal is unaffected. A receipt sealed before chain v4 answers `signature_only`: its chain seals the mandate's own signature, which the verifier does not take. [`docs/OPEN_QUESTIONS.md`](../../docs/OPEN_QUESTIONS.md) §47.
 
 ## Limits and stubs
 
 - The receipt carries two signatures. The HMAC one proves the payout to whoever runs this agent, because verifying it means holding the secret that also mints it. The Ed25519 one, sealed by CodeSpar's platform issuer key since the API added it, proves it to anybody with `npm run verify`. A receipt sealed before that carries no Ed25519 signature and never will — there is no backfill, and signing an old receipt with today's key would attest to what the database says now, not to what happened then.
-- The approval artifact is signed by HMAC with a **local development key** (`.codespar/approval.key`). This is a stub: the CodeSpar API does not sign approval lists today. It proves what was approved to whoever runs the agent.
-- The claim that makes a re-run safe is **local**, in `.codespar/state.db`. Delete that file and the agent has no memory that a batch already ran. The rail's own idempotence still covers a re-sent `attempt_id`, but the executions would be new ones with new attempt ids, so it would not catch them. This is the honest limit of a kit that runs on one machine; see `docs/OPEN_QUESTIONS.md`.
+- The receipt names the payee because every spend presents the approved line as a `quote`; without one the API seals no payee anywhere in the chain. The API only records a quote that disagrees with what settled and pays anyway, so the kit refuses the disagreement before the call, and a receipt that seals a different payee, or none, stops the run with `ReceiptSealMismatchError` instead of a warning. [`docs/OPEN_QUESTIONS.md`](../../docs/OPEN_QUESTIONS.md) §18.
+- The approval artifact is signed by HMAC with a **local development key** (`.codespar/approval.key`). This is a stub: the CodeSpar API does not sign approval lists today, so WHO approved is proved to whoever runs the agent and nobody else. WHAT was approved reaches further: every spend carries the artifact's `items_hash` (and a batch line its `batch_hash`), the API seals them into the receipt's chain (v4), and `npm run verify` holds that sealed link against the artifact. [`docs/OPEN_QUESTIONS.md`](../../docs/OPEN_QUESTIONS.md) §3.
+- The claim is **local**, in `.codespar/state.db`. Delete that file, or run the same batch from a second machine, and the claim knows nothing. What still holds is the API: the re-run presents the same attempt ids with the same quotes, and the API pays each of them at most once. That rests on the server honouring an explicit `attempt_id`, which it does since ent#1671; it does not make the second machine's report complete (a line still in flight there is `uncertain` until reconciled), and a list that changed in any line is a different list with different ids. See `docs/OPEN_QUESTIONS.md` §39c.
 - The batch is not atomic and does not try to be. Lines settle independently, so a batch can end part paid. That is the point, and the report says which lines those are.
 - `batch_hash` binds the list; it does not bind the list to the payables file it came from. A batch whose lines changed is refused on the next run of the SAME `batch_ref`, because that is when there is an approved set to contradict. A list edited before it was ever presented is simply the list, and the mandate's allowlist and caps are what stand between it and a payment.
 - The hash is over the resolved payees, so re-signing the mandate with a different Pix key for a payee moves it too, and the next run of an already-approved batch is refused. That is correct — where the money goes did change — but the refusal cannot see WHY, so it names what it measured and offers both ways out rather than guessing.

package/templates/supplier-payments-agent/agents/supplier-payments-agent/src/kit.ts

@@ -62,7 +62,7 @@ const kit: AgentKit = {
   npm start -- --scenario <name>                    run a scenario pack (${"see scenarios/"})
 options: --mode human|mandate  --provider anthropic|replay  --transcript <file>  --rail stub|api  --user <id>  --json
          --now <ISO 8601>  pin the run to that instant (escalation hours, timestamps); env CODESPAR_AGENT_NOW is the same thing
-a batch runs one execution per line: in \`human\` the operator decides each one, and every artifact carries the batch_hash of the list it was one of`,
+a batch runs one execution per line: in \`human\` the terminal asks once for the list (todas / todas exceto 3,7 / nenhuma), and every artifact carries the batch_hash of the list it was one of`,
 
   buildRail: (ctx) => {
     if (ctx.kind === "api") {

package/templates/supplier-payments-agent/agents/supplier-payments-agent/src/modules/batch-payout.ts

@@ -28,24 +28,33 @@
  *   one refusal does not stop the others  -> the loop `continue`s, never
  *                                            breaks, and never throws past
  *                                            the line it is on
- *   one attempt_id per call               -> the core derives it from each
- *                                            execution's own idempotency key
- *   repeating pays nobody twice           -> the per-line claim below
+ *   one attempt_id per call               -> the core derives it from the
+ *                                            line itself: mandate, batch_hash,
+ *                                            position (`batchAttemptId`)
+ *   repeating pays nobody twice           -> the per-line claim below, and
+ *                                            behind it the API's record of
+ *                                            that attempt id
  *   the approved list is bound as a set   -> `batch_hash`, and the set claim
  *                                            that refuses a run whose list
  *                                            changed after it was approved
  *
- * The claim is what survives a re-run. Execution ids are random, so a second
- * run of the same batch would mint fresh ids, fresh idempotency keys and
- * fresh attempt ids, and the rail's own idempotence — which is keyed on
- * `attempt_id` — would not recognise them. The claim pairs (mandate, batch,
- * line) with the execution that covers it, durably, and the rules for
- * reading one back are the same posture the enterprise money paths take: a
- * line whose execution SETTLED is done, a line whose execution is still open
- * is in progress and is never re-opened, and only a line whose execution
- * ended without moving money is retried.
+ * The claim is the first line of defence on a re-run, and it is local. The
+ * claim pairs (mandate, batch, line) with the execution that covers it,
+ * durably, and the rules for reading one back are the same posture the
+ * enterprise money paths take: a line whose execution SETTLED is done, a line
+ * whose execution is still open is in progress and is never re-opened, and
+ * only a line whose execution ended without moving money is retried.
+ *
+ * The second line is the API, and it holds wherever the batch runs. A batch
+ * line's attempt id and quote come from the line and not from the execution,
+ * so a run on a machine with no claim at all presents the attempt the API
+ * already holds, and the API answers it from its record (ent#1671): settled
+ * lines replay with their original receipt, a line still in flight stays open
+ * here, and only a line the provider refused is paid again, under the next
+ * generation of its id. OPEN_QUESTIONS §39c says what that does and does not
+ * cover.
  */
-import { batchHash, isTerminal, type Execution, type ExecutionItem, type ProposedItem, type ToolContext } from "@codespar/agent-core";
+import { batchHash, isTerminal, type BatchGesture, type Execution, type ExecutionItem, type ProposedItem, type ToolContext } from "@codespar/agent-core";
 import { batchTotal, formatBRL, type Batch, type PayableLine } from "../payables.js";
 
 /** What happened to one line of the batch. `dispatch` is the part an operator reads first. */
@@ -59,8 +68,15 @@ export interface BatchLineReport {
   execution_id: string | null;
   state: string;
   reason: string | null;
-  /** Whether this line's money moved, could not move, or was deliberately not attempted again. */
-  dispatch: "settled" | "refused" | "awaiting_decision" | "uncertain" | "already_settled" | "in_progress";
+  /**
+   * Whether this line's money moved, could not move, or was deliberately not
+   * attempted again. `attempt_id_conflict`: the API holds this line's attempt
+   * id for a DIFFERENT payment (another amount, payee, mandate, rail or
+   * quote). Nothing was held or sent, the id is not spent, and presenting it
+   * again answers the same, so the line is never re-drafted under it and never
+   * moved to another id: a person decides what that other payment is.
+   */
+  dispatch: "settled" | "refused" | "awaiting_decision" | "uncertain" | "already_settled" | "in_progress" | "attempt_id_conflict";
 }
 
 /**
@@ -91,6 +107,10 @@ export interface BatchReport {
   failed: string[];
   /** Lines a previous run of this batch already covers. */
   skipped: string[];
+  /** Lines a person denied, by alias: a decision, reported, and a subset of `failed`. */
+  denied: string[];
+  /** Present when the channel took ONE gesture for the whole list: what it approved and vetoed, by position. */
+  gesture?: BatchGesture;
   total_minor: number;
   total: string;
   /** Present when the SET was refused: nothing was drafted, nothing was sent, no line moved. */
@@ -143,7 +163,7 @@ function presentedItems(batch: Batch, ctx: ToolContext): ExecutionItem[] {
  * What a claim already held means for this line: skip it, or drop it and
  * pay. `undefined` means nothing is held and the line is paid normally.
  */
-function priorVerdict(prior: Execution | undefined): "already_settled" | "in_progress" | undefined {
+function priorVerdict(prior: Execution | undefined): "already_settled" | "in_progress" | "attempt_id_conflict" | undefined {
   // A claim naming an execution the store does not have is a claim taken by a
   // run that died before it drafted. Nothing moved, so the line is open.
   if (!prior) return undefined;
@@ -152,13 +172,20 @@ function priorVerdict(prior: Execution | undefined): "already_settled" | "in_pro
   // for the same line is how a payee gets paid twice; the operator closes the
   // first one with `npm run approve`, `npm run resume` or `npm run reconcile`.
   if (!isTerminal(prior.state)) return "in_progress";
+  // Held for another payment: a retry presents the same derived id and gets the same refusal, so it is not retried.
+  if (heldForAnotherPayment(prior)) return "attempt_id_conflict";
   // `denied`, `expired`, `failed`: the core refused it or the rail declined
   // it, and in every one of those the money provably did not move. Retry.
   return undefined;
 }
 
+function heldForAnotherPayment(execution: Execution): boolean {
+  return execution.state === "failed" && execution.outcomes.some((o) => o.held === "conflict");
+}
+
 function dispatchOf(execution: Execution): BatchLineReport["dispatch"] {
   if (execution.state === "settled") return "settled";
+  if (heldForAnotherPayment(execution)) return "attempt_id_conflict";
   if (execution.state === "awaiting_approval") return "awaiting_decision";
   // Still `executing` after the channel ran it: the rail did not say. Never
   // re-sent here; `npm run reconcile` is what closes it.
@@ -200,6 +227,24 @@ export async function runBatch(batch: Batch, ctx: ToolContext): Promise<BatchRep
     );
   }
 
+  // One gesture for the list, when the channel can take one (section 3, v5.3:
+  // "o humano aprova a lista, com veto por linha"). Asked after the set
+  // refusal, so a person is never asked about a list that is not going to run,
+  // and before any draft, so what they see is the list the hash covers. It
+  // decides nothing here: every line below is still drafted and still reaches
+  // `onExecution`, which is where the channel applies it line by line.
+  const gesture = ctx.onBatch
+    ? await ctx.onBatch({
+        ref: batch.ref,
+        label: batch.label,
+        batch_hash: presented,
+        count: batch.lines.length,
+        total_minor: batchTotal(batch),
+        total: formatBRL(batchTotal(batch)),
+        lines: batch.lines.map((line, index) => ({ index, beneficiary: line.name, amount_minor: line.amount_minor, amount: formatBRL(line.amount_minor), status: lineStatus(batch, line, ctx) })),
+      })
+    : undefined;
+
   for (const [index, line] of batch.lines.entries()) {
     const key = claimKey(mandateId, batch.ref, line.alias);
     const held = ctx.engine.claimed(key);
@@ -272,7 +317,7 @@ export async function runBatch(batch: Batch, ctx: ToolContext): Promise<BatchRep
     }
   }
 
-  return summarise(batch, presented, lines);
+  return summarise(batch, presented, lines, undefined, gesture);
 }
 
 /**
@@ -310,7 +355,7 @@ function setRefusal(batch: Batch, presented: string, ctx: ToolContext, setKey: s
   };
 }
 
-function summarise(batch: Batch, presented: string, lines: BatchLineReport[], refused?: BatchSetRefusal): BatchReport {
+function summarise(batch: Batch, presented: string, lines: BatchLineReport[], refused?: BatchSetRefusal, gesture?: BatchGesture): BatchReport {
   const settledMinor = lines.filter((l) => l.dispatch === "settled").reduce((sum, l) => sum + l.amount_minor, 0);
   const total = batchTotal(batch);
   return {
@@ -321,11 +366,13 @@ function summarise(batch: Batch, presented: string, lines: BatchLineReport[], re
     lines,
     settled_minor: settledMinor,
     settled: formatBRL(settledMinor),
-    failed: lines.filter((l) => l.dispatch === "refused" || l.dispatch === "uncertain").map((l) => l.alias),
+    failed: lines.filter((l) => l.dispatch === "refused" || l.dispatch === "uncertain" || l.dispatch === "attempt_id_conflict").map((l) => l.alias),
     skipped: lines.filter((l) => l.dispatch === "already_settled" || l.dispatch === "in_progress").map((l) => l.alias),
+    denied: lines.filter((l) => l.state === "denied" && l.reason === "denied_by_approver").map((l) => l.alias),
     total_minor: total,
     total: formatBRL(total),
     ...(refused ? { refused } : {}),
+    ...(gesture ? { gesture } : {}),
   };
 }
 
@@ -338,7 +385,7 @@ function describe(line: PayableLine, index: number): Pick<BatchLineReport, "inde
  * same claim the loop reads, so what the model is told and what the loop
  * would do cannot drift.
  */
-export function lineStatus(batch: Batch, line: PayableLine, ctx: ToolContext): "open" | "already_settled" | "in_progress" {
+export function lineStatus(batch: Batch, line: PayableLine, ctx: ToolContext): "open" | "already_settled" | "in_progress" | "attempt_id_conflict" {
   const held = ctx.engine.claimed(claimKey(ctx.engine.mandate.id, batch.ref, line.alias));
   if (!held) return "open";
   return priorVerdict(ctx.engine.get(held)) ?? "open";