@codespar/cli 0.14.1 → 0.16.0

package/templates/collections-agent/agents/collections-agent/README.md

@@ -1,17 +1,26 @@
 # collections-agent
 
-The merchant's agent that collects. The payer answers the message about an open agreement; the agent proposes terms inside a negotiation envelope (discount ceiling, instalments, due-date window, collection hours); on acceptance the code issues one bolepix per instalment with an idempotency key, shows the QR and the copy-and-paste in the conversation, and closes the cycle when `commerce.charge.paid` or `commerce.charge.expired` arrives: "recebemos, acordo quitado". Terminal first; WhatsApp later.
+[![rail: bolepix](https://img.shields.io/badge/rail-bolepix-2E8B57)](agent.yaml) [![maturity: sandbox](https://img.shields.io/badge/maturity-sandbox-orange)](agent.yaml) [![approval: human | mandate](https://img.shields.io/badge/approval-human_%7C_mandate-555)](agent.yaml) [![charge → settled: 10 s](https://img.shields.io/badge/charge_%E2%86%92_settled-10_s-8A2BE2)](#quickstart)
 
-```
+The merchant's collections agent. A customer replies about an open debt; the agent proposes terms inside a negotiation envelope (maximum discount, number of instalments, due-date window, collection hours), and once the customer accepts, the code issues one bolepix per instalment, shows the QR code and the copy-and-paste Pix code in the chat, and closes the loop when the charge is paid or expires. Two channels: the terminal, and WhatsApp against a local Cloud API emulator that needs no Meta account.
+
+## Quickstart
+
+Node 22.13+ and a sandbox key (`csk_test_...`) from [codespar.dev/auth/signup](https://codespar.dev/auth/signup). No money moves: a sandbox payer plays the customer's bank.
+
+```sh
 git clone https://github.com/codespar/agent-starter-kits && cd agent-starter-kits
-cp agents/collections-agent/.env.example agents/collections-agent/.env   # CODESPAR_API_KEY (csk_test_...) and ANTHROPIC_API_KEY
-npm install && npm start --workspace=agents/collections-agent
+cp agents/collections-agent/.env.example agents/collections-agent/.env   # paste your csk_test_ key
+npm install                                                              # at the repo root (npm workspace)
+npm run start:collections
 pagador> oi, recebi a mensagem sobre o acordo do pedido 1042
 ```
 
-`npm install` runs at the repository root (it is an npm workspace). You type as the payer; the operator's approval, in `human` mode, is asked on the same keyboard and labelled `[operador]`.
+You type as the customer. In `human` mode the operator's approval is asked on the same keyboard, labelled `[operador]`. Without a real `ANTHROPIC_API_KEY` (empty or the `.env.example` placeholder) the agent replays the recorded scenario.
 
-## What it proves
+Scaffold instead of cloning: `npx -y @codespar/cli@0.14.0 init my-agent --template collections-agent`.
+
+## What it shows
 
 | Contract | How |
 |---|---|
@@ -22,13 +31,159 @@ pagador> oi, recebi a mensagem sobre o acordo do pedido 1042
 | Two modes, one envelope | `approval: human` (default): the operator approves each issuance. `approval: mandate`: the agent issues alone inside the envelope and asks the operator above R$ 3.000,00. Same code, same states, same records. |
 | Readable refusal | Discount, instalments, due date, hours, cap, unknown debtor, revoked policy: each names itself in the trail and in the chat. |
 | Survives a restart | Kill the process after the issuance, run `npm run resume` then `npm run poll`: one charge, one settlement. |
+| Closes days later, on the channel | `npm run poll -- --channel whatsapp` comes back to a conversation whose run ended, and confirms by approved template once the 24-hour window has shut. |
 | Sandbox by construction | A key that does not start with `csk_test_` fails before any network call. The sandbox payer is a test-environment route the API refuses to a live key. |
 
 ## How the loop closes: poll, and a webhook when you have one
 
 The API delivers `commerce.charge.*` through triggers to a URL. A terminal has none, so the kit's default is to LOOK: `GET /v1/charges/{id}` every three seconds (the stub's fixture, offline) through the core's `reconcile`, which is read-only on the rail and never re-issues. The first look that finds the instrument payable prints the QR (as an image, in the terminal) with the copy-and-paste under it; the look that finds it paid or expired closes the execution and tells the payer once. `npm run poll` continues after a restart or a timeout; nothing shown twice, nothing said twice, because both marks live in `state.db`.
 
-`channels/webhook/` is the other closer, a documented stub: the receiving contract of a trigger delivery (`X-CodeSpar-Signature: t=..,v1=..`, body `{ id, type, data: { payment_id } }`), signature verification with the trigger's secret, dedup by event id, and `npm run webhook` to run it on localhost. Registering the trigger and exposing the URL are the developer's steps (`codespar triggers create`). See `docs/OPEN_QUESTIONS.md` section 21.
+The webhook is the other closer, a documented stub (`packages/agent-runtime/src/webhook.ts`, `npm run webhook`; there is no `channels/webhook/` directory, and since wave 4 `channels/` means something specific): the receiving contract of a trigger delivery (`X-CodeSpar-Signature: t=..,v1=..`, body `{ id, type, data: { payment_id } }`), signature verification with the trigger's secret, dedup by event id, and `npm run webhook` to run it on localhost. Registering the trigger and exposing the URL are the developer's steps (`codespar triggers create`). See `docs/OPEN_QUESTIONS.md` section 21.
+
+## The WhatsApp channel
+
+This is the agent WhatsApp is for: the debtor answers a message, the agent
+proposes terms, the payable code goes into the conversation, and "recebemos,
+acordo quitado" closes it. The channel has two backends behind one interface,
+and they are **the same code with a different base URL**.
+
+The house simulator is [`dyvit-wa-sim`](https://github.com/fabianocruz/whatsapp-simulator)
+(MIT), a local emulator of the WhatsApp Cloud API, published to npm as
+`@dyvit/whatsapp-simulator-cli`. It is not ours and it is not a dependency:
+`npm run whatsapp:emulator` fetches the pinned version with `npx` and runs it on
+`127.0.0.1:4290`. Start it in one terminal, run the agent in another:
+
+```sh
+npm run whatsapp:emulator                                 # terminal 1
+npm run start:collections -- --channel whatsapp --conversation acordo-1042
+npm run start:collections -- --channel whatsapp --conversation acordo-1042 --scripted --mode mandate --simulate-payer --now 2026-09-23T14:00:00-03:00
+```
+
+`--conversation` is required because the agent ships two, and which person you
+are messaging is not a default: `acordo-1042` is Joana and ends paid,
+`acordo-1103` is Ana Paula and ends expired (add `--payer expires`).
+
+**Why somebody else's emulator instead of a fake in this repo.** A mock we
+wrote would agree with us by construction — it would accept our payloads
+because we wrote both sides, and the day Meta refused one we would find out in
+production. This one answers `POST /v22.0/{phone-number-id}/messages` with the
+Cloud API's own response shape and posts back the same signed
+`x-hub-signature-256` webhooks, so what runs against it is the adapter itself.
+It also has a clock we can move (`POST /_sim/clock`), which a replay finishing
+in seconds cannot otherwise have. No Meta account, no credential, and no
+traffic that leaves the machine. What it does NOT cover is measured, with the
+exact payloads, in `docs/OPEN_QUESTIONS.md` §46 — chief among them that it
+prices the 24-hour window but does not enforce it.
+
+`--scripted` replays the debtor's turns from `channels/whatsapp/<name>.json`,
+which is what an agent ships for this channel: the contact the conversation is
+bound to, the agreement it may be about, and the person's turns. Each turn is
+pushed through the emulator's `POST /_sim/inbound`, so a scripted turn takes
+the same path a real one would — including the signature check on the way
+back. The behaviour is the runner's (`packages/agent-runtime/src/channels/`);
+the conversations are the agent's, and `npm run check` fails if the two
+disagree in either direction.
+
+**The rules are above the backend, so a backend is not a way around one.**
+Every outbound message is checked before anything carries it: nothing outside
+the collection hours (`guardrails.envelope.collection_hours`), nothing to a
+contact other than the one the conversation is bound to, nothing naming
+another debtor's agreement (by its alias, which is what the agent's own book calls it), and no CPF or CNPJ in a message. A refused message
+is not a failed delivery — it never left the process — and it is recorded as
+such in the conversation log. A Pix copy-and-paste and a boleto line are their
+own message kind and are not read as prose, which is why the document rule does
+not refuse the thing that pays.
+
+**The operator is not on WhatsApp.** In `approval: human` the question is asked
+on the operator's console and never in the conversation; that is not a check,
+it is the wiring. One caveat, and it is a real one: an INTERACTIVE simulator
+run reads both the debtor's turns and the operator's answer from the same
+keyboard, so one person plays both parts. `--scripted` has no such problem,
+and a scripted `human` run without `--approve` is refused rather than left
+waiting.
+
+**Going live is a base URL.** `--backend cloud-api` reads
+`WHATSAPP_PHONE_NUMBER_ID`, `WHATSAPP_ACCESS_TOKEN`, `WHATSAPP_VERIFY_TOKEN`
+and `WHATSAPP_APP_SECRET` from your `.env` (commented out and empty in
+`.env.example`) and refuses to open without them, by name. It is the same
+class the emulator runs, pointed at `graph.facebook.com` instead — which is
+also how the channel decides it is live, and therefore how the
+consent-evidence builder decides an act was observed by somebody.
+**This repo has never run one against Meta**: the shapes are written from
+Meta's published documentation, and the first live run is yours. Two pieces
+are stubs and say so: template APPROVAL (a Meta Business account reviews
+templates; the channel only knows the names this agent declares) and sending
+the QR as an IMAGE (that needs a media upload or a public URL, and this repo
+hosts neither, so the copy-and-paste goes as its own text message — which is
+the string that pays; the emulator would accept the image, so that gap is
+ours).
+
+**The conversation is part of the proof.** Each run writes `channel.jsonl` into
+its bundle: every message in and out, in order, with the delivery state and any
+refusal, and the contact masked, because the bundle travels. Inbound lines also
+carry the PROVIDER's timestamp, which is what a later process counts the
+24-hour window from — see the poll below.
+
+### Agreed on Tuesday, paid on Friday
+
+The ordinary collection does not close inside the turn that issued the charge.
+The debtor agrees now and pays days later, and by then WhatsApp's 24-hour
+customer-service window has shut: the only thing a business may send is a
+template Meta approved in advance.
+
+```sh
+npm run poll -- --channel whatsapp --conversation acordo-1042
+```
+
+It comes back to the conversation from the RECORD — the bundle's
+`channel.jsonl` plus `state.db` — looks at the receivable the way the terminal
+poll does, and puts the outcome back into that same conversation, appended
+under the QR it confirms rather than into a second folder. **Free-form while
+the window is open, template once it has shut**, and which of the two is the
+window's decision, not the command's.
+
+Three things it will not do. Nothing waiting for a payer is a clean no-op that
+exits 0 and never opens the channel — a cron that fails on an empty queue is a
+cron somebody turns off. Polling twice tells the person once, because the
+cursor that says so lives in `state.db` and outlives the process. And a charge
+that expired gets the expiry template, never the paid one.
+
+Which executions belong to the conversation is decided by its `subject` — the
+agreement alias it is allowed to name. That is the same rule that keeps one
+debtor's agreement out of another's chat, used in the other direction.
+
+**The templates are the agent's**, declared in
+[`channels/whatsapp/templates.json`](channels/whatsapp/templates.json) with the
+name, the language and the body as submitted. `npm run check` validates it, and
+the channel refuses a name nobody declared, a language the template was not
+registered in, and a variable count the body has no placeholders for — the
+three things a local registry can see that Meta answers with a 4xx. Whether
+Meta APPROVED a template is not knowable from here and stays yours.
+
+**Consent in the conversation is wired and deliberately unused here.**
+`attestation.evidence` on the consent submit accepts four keys on this channel
+(`contact`, `message_id`, `session_id`, `provider_ts`) and the channel builds
+exactly those — but only from a backend that talked to a real provider, which
+is decided by the base URL being Meta's. An act the emulator observed was
+observed by nobody, so the builder refuses and says why. This agent has no
+consent step to carry it either: the collection policy is the merchant's own
+file. See `docs/OPEN_QUESTIONS.md` section 43.
+
+### The gate
+
+`npm run whatsapp:gate` runs the whole cycle three times from a clean state,
+with nobody at a keyboard, and asserts the final state and the shape of the
+conversation each time — not the wording. It needs the emulator running and
+FAILS rather than skips when it is not, so the gate never passes against
+nothing. It runs in the CI, which starts the emulator in its own step.
+
+A fourth run covers the case the other three cannot reach: agree, move the
+conversation's clock 26 hours, let the sandbox payer pay, poll. It asserts the
+execution settled and the confirmation went out as a TEMPLATE. Read that
+precisely: the emulator PRICES the 24-hour window and does not ENFORCE it
+(`docs/OPEN_QUESTIONS.md` §46a), so what passes is OUR choice of carrier and
+not the provider refusing the alternative. The day the emulator enforces the
+window, that run gets stronger without changing.
 
 ## The sandbox payer
 
@@ -41,27 +196,30 @@ Read from `agent.yaml`, field `maturity`:
 | Capability | Maturity | Meaning |
 |---|---|---|
 | `bolepix-receivables` | sandbox | Cobranca com vencimento through the CodeSpar sandbox, paid by the sandbox payer. No real money. |
-| `receipt-verification` | blocked | Waits for Ed25519; and the API seals no record for a paid charge today (the paid charge as the API reports it is what the bundle keeps, marked `kind: "charge"`, unsealed). |
+| `receipt-verification` | blocked | Ed25519 landed on the API's payment receipts, and this agent mints none: the API still seals no record for a paid charge, so what the bundle keeps is the paid charge as the API reports it, marked `kind: "charge"`, with no chain and no signature to check. |
 
 What the agent applies on its own (`guardrails.json`): the envelope (15% maximum discount, up to 3 instalments, due dates within 90 days, R$ 50,00 minimum instalment, collection hours 08:00–20:00 in America/Sao_Paulo), the escalation threshold (R$ 3.000,00 per agreement in `mandate`), and "the core's total wins" when the model states another.
 
-Out of this delivery: WhatsApp, a policy signed by the API for the receiving side (section 16 of the spec: candidate to product), `npm run inspect`, the `codespar init --template` scaffold.
+Not in this kit yet: a policy signed by the API for the receiving side (section 16 of the spec, candidate to product), and a mandate born in the conversation (see the channel section below).
 
 ## Commands
 
 | Command | Does |
 |---|---|
 | `npm start` | Interactive terminal. You are the payer; the operator's approval is asked on the same keyboard. |
-| `npm start -- --input "oi, recebi a mensagem sobre o acordo do pedido 1042" [--approve] [--simulate-payer] [--wait 60] [--json]` | One turn, no prompt. Without `ANTHROPIC_API_KEY` it replays the recorded scenario whose first turn is that input. `--json`: machine data on stdout, people on stderr (add npm's `-s` when piping). Exit code 3 when a receivable is still waiting. |
+| `npm start -- --input "oi, recebi a mensagem sobre o acordo do pedido 1042" [--approve] [--simulate-payer] [--wait 60] [--json] [--now <ISO>]` | One turn, no prompt. Without `ANTHROPIC_API_KEY` it replays the recorded scenario whose first turn is that input. `--json`: machine data on stdout, people on stderr (add npm's `-s` when piping). Exit code 3 when a receivable is still waiting. `--now 2026-09-23T14:00:00-03:00` pins the clock the guardrails read (collection hours `08:00-20:00`, the due-date window, every timestamp) instead of the wall clock; the CI gate passes it so the fixture is inside collection hours at any hour. `CODESPAR_AGENT_NOW` in the environment is the same pin and reaches every command (`approve`, `resume`, `poll`, `rerun`, `reconcile`); the flag wins when both are set. |
+| `npm start -- --channel whatsapp [--scripted] [--conversation <name>] [--backend simulator\|cloud-api]` | The conversation channel. The default backend is the local emulator (`npm run whatsapp:emulator`, no Meta account and no credential); `--scripted` replays the debtor's turns from `channels/whatsapp/`. See [The WhatsApp channel](#the-whatsapp-channel). |
 | `npm start -- --scenario <name> [--mode human\|mandate] [--rail stub\|api]` | A scenario pack from `scenarios/`. With `--rail api` and a test key the charge, the poll and the sandbox payer are real, and `cycle_seconds` is measured. |
 | `npm run check` | The manifest gate: fails if the prompt, tools or guardrails contradict `agent.yaml`, if `AGENTS.md` and `CLAUDE.md` differ, or if `mcp`, `cli` or `schema` are missing. |
 | `npm run eval` | The adversarial suite (`evals/adversarial/`) and every scenario in every mode, on the replay provider and the stub rail. |
 | `npm run approve <execution-id>` / `npm run deny <execution-id>` | The operator's decision as its own command: decides an execution left in `awaiting_approval`, writes the section 4.2 artifact, runs it through the same last gate `npm start` uses, and waits for the payer (`--wait`, `--simulate-payer`). |
-| `npm run poll [--wait <s>] [--simulate-payer]` | Keeps looking at every receivable still waiting for its payer. Shows an instrument not shown yet, tells the payer the outcome once, fetches the paid record. |
-| `npm run webhook [--port 8787] [--secret <trigger secret>]` | The receiving end of `channels/webhook` on localhost. A stub: you register the trigger and expose the URL. |
+| `npm run poll [--wait <s>] [--simulate-payer] [--payer pays\|expires\|never]` | Keeps looking at every receivable still waiting for its payer. Shows an instrument not shown yet, tells the payer the outcome once, fetches the paid record. `--payer` scripts the stub's fixture, which is how "nobody paid and it expired" is reachable at all: a due date passes between two runs, never inside one. |
+| `npm run poll -- --channel whatsapp --conversation <name>` | The same, back in the conversation. Free-form while the 24-hour window is open, an approved template once it has shut. Nothing waiting is a clean no-op; polling twice tells the person once. See [Agreed on Tuesday, paid on Friday](#agreed-on-tuesday-paid-on-friday). |
+| `npm run webhook [--port 8787] [--secret <trigger secret>]` | The receiving end of a trigger delivery, on localhost. A stub: you register the trigger and expose the URL. |
 | `npm run resume` | After a crash: dispatches only what the outbox proves was never sent, reconciles the rest from the rail. Never issues twice. |
 | `npm run rerun <run-id>` | Replays a recorded run with no network and checks the state sequence matches; the payer's behaviour (paid, expired) is read from the recording. |
 | `npm run reconcile` | Compares local state with the rail. One look, read-only; names what is waiting for a payer, what is uncertain, what record is missing locally. |
+| `npm run inspect <run-id> [--json] [--html <file>]` | The proof bundle of that run read back as a timeline: who proposed what, who approved it and when (with the `items_hash` and the escalation trigger when one fired), under which version of the mandate, every state transition with its actor, which call went out under which idempotency key, what the rail answered, and which receipts came back. `--json` puts the whole report on stdout and nothing else; `--html` writes one self-contained page that opens from disk with nothing fetched. Payees are masked the way the bundle masks them, and the conversation is reported as counts, not text. |
 
 ## The proof bundle
 
@@ -73,19 +231,29 @@ approval.json           the approval artifacts of the run (section 4.2 of the sp
 mandate.snapshot.json   the collection policy as it was, debtors' documents masked
 events.jsonl            every transition, every look, every charge event, every message to the payer, each with its actor
 receipts/               the paid charges as the API reports them, each stamped with the actor (kind: charge, unsealed)
-run.json                mode, rail, policy id
+run.json                mode, rail, policy id and the version it ran under
 ```
 
 No key and no secret is written there. Documents are masked; the payer's document is never in a message.
 
-## What this README declares
+`verify.json` is the one file section 11 names and this repository does not
+write: it is the output of `codespar audit replay`, which is not a registered
+command of `@codespar/cli`, and the spec forbids a second implementation of
+the hash-chain check. `npm run inspect` says so in as many words instead of
+leaving the absence to be guessed at.
+
+Read the bundle back with `npm run inspect <run-id>`: the negotiated terms,
+who approved them, each receivable the rail accepted, the instrument the payer
+was shown as it became payable, and what closed the cycle.
+
+## Limits and stubs
 
 - A policy for the receiving side, signed by the organization, does not exist in the API; the collection policy is the merchant's own file (`mandate.example.json`, in the shape of the consumer mandate, where the named entries are the debtors with an open agreement) and the envelope is the kit's code. Candidate to product (section 16 of the spec).
 - 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 API seals no record for a paid charge. The bundle keeps the paid charge as the API reports it, with `simulated: true` when the sandbox payer paid it. Nothing here is proof to anyone outside the merchant.
-- Revocation and the kill switch run against a **local stub** of the AgentGate (`packages/agent-core/src/stubs/agentgate.ts`); the collection policy has no API-side status to read.
+- Revocation and the kill switch run against a **local stub** (`LocalMandateStatusStub` in `packages/agent-core/src/stubs/mandate-status.ts`); the collection policy has no API-side status to read.
 - The `actor` of every call is carried locally on every event, approval and record copy. The API has no `actor` field on the wire today.
-- Collection over WhatsApp has rules: hours, secrecy of the debt, no embarrassment, LGPD. The prompt codifies them; the envelope enforces the hours; the code never sends a document.
+- Collection over WhatsApp has rules: hours, secrecy of the debt, no embarrassment, LGPD. Two of them are decidable and are code above the channel, on every backend: nothing is sent outside the collection hours, a message goes to the bound contact and to no other number, a message may not name another debtor's agreement, and a CPF or CNPJ in a message is refused. The other two are the prompt's and the operator's: no code reads a sentence and tells whether it shames somebody.
 - CodeSpar does not host or run this agent. The repository delivers it; whoever runs it, runs it.
 - What the agent issues inside the policy was authorized by the merchant, and the approval artifact proves what. The split of loss between partner, institution and CodeSpar on an authorized but wrong receivable is contractual and not yet written.
 

package/templates/collections-agent/agents/collections-agent/agent.yaml

@@ -12,17 +12,17 @@ escalate_above:
   # the first charge to a debtor is the normal case, not a risk. No `outside_hours` either: collection hours are a LEGAL
   # rule the envelope refuses in both modes (guardrails.envelope.collection_hours), not an escalation.
 mcp: "@codespar/mcp@0.5.8"
-cli: "@codespar/cli@0.13.0"   # the published version on 2026-09-23 (docs/OPEN_QUESTIONS.md section 1)
+cli: "@codespar/cli@0.14.0"   # the published version on 2026-09-23 (docs/OPEN_QUESTIONS.md section 1)
 tools: ./tools.json
 guardrails: ./guardrails.json
 mandate_schema: ./mandate.example.json
 # The API's own names (plan of 2026-09-23, section 1). `paid` and `expired` close the cycle; `cancelled` closes it as failed;
 # `created` is when a cobranca com vencimento becomes payable (the kit reads that from the status poll).
 events: [commerce.charge.created, commerce.charge.paid, commerce.charge.expired, commerce.charge.cancelled]
-channels: [terminal]
+channels: [terminal, whatsapp]   # the second channel is the one this agent is FOR; `npm run check` confirms channels/whatsapp/ ships a conversation
 maturity:
   bolepix-receivables: sandbox
-  receipt-verification: blocked   # waits for Ed25519; and the API seals no record for a paid charge today
+  receipt-verification: blocked   # Ed25519 landed, but the API still seals no record for a paid charge: no chain, no signature to verify
 scenarios: ./scenarios/
 evals: ./evals/
 agents_md: ./AGENTS.md

package/templates/collections-agent/agents/collections-agent/channels/whatsapp/README.md

@@ -0,0 +1,111 @@
+# channels/whatsapp
+
+What this agent ships for the WhatsApp channel: the CONVERSATIONS. One JSON
+file each, and the file is the whole thing a runner cannot know — which
+number, which debtor, which agreement, and what the person said.
+
+The behaviour is the runner's, in
+[`packages/agent-runtime/src/channels/`](../../../../packages/agent-runtime/src/channels):
+the adapter, the rules, the Cloud API backend. Nothing about WhatsApp lives
+here, and the emulator the backend talks to is somebody else's repository
+(`npm run whatsapp:emulator`).
+
+## One file
+
+```json
+{
+  "name": "acordo-1042",
+  "description": "what this conversation is",
+  "channel": "whatsapp",
+  "contact": "+5511987654321",
+  "subject": "acordo-1042",
+  "turns": [{ "text": "oi, recebi a mensagem sobre o acordo do pedido 1042" }]
+}
+```
+
+`contact` is the only number this conversation may reach: the channel refuses
+an outbound message addressed anywhere else, which is how the debt stays
+between the store and the person who owes it. `subject` is the only agreement
+it may name, which is the same rule in the other direction. `turns` are the
+PERSON's, and only the person's — what the agent answers comes from the model
+or from a recorded transcript, never from here, for the same reason a scenario
+pack asserts a final state rather than a wording.
+
+`name` must match the file name, and `npm run check` fails on a file that no
+longer parses, on a declared channel with no conversation, and on a
+conversation the manifest does not declare.
+
+## And one file that is not a conversation
+
+`templates.json` is the reserved name in this directory: the LOCAL registry of
+the templates this agent sends. A conversation therefore cannot be called
+`templates`.
+
+```json
+{
+  "channel": "whatsapp",
+  "templates": [
+    {
+      "name": "acordo_quitado",
+      "language": "pt_BR",
+      "description": "what this template is for and what {{1}} means",
+      "body": "Oi! Recebemos o pagamento do {{1}} e ele esta quitado. Obrigado!"
+    }
+  ]
+}
+```
+
+Outside the 24 hours that follow the person's last message WhatsApp carries an
+approved template and nothing else, so an agent that ever speaks after that —
+and a collections agent does it constantly, because the debtor agrees on
+Tuesday and pays on Friday — has to own one per outcome. `npm run poll --
+--channel whatsapp` is what sends them; `src/kit.ts` maps an outcome to a name
+in `outcomeTemplate`, and the language comes from here rather than from the
+kit, so there is one source for it.
+
+What this file PROVES is narrow and worth stating exactly: the agent declared
+the name, so a send of a name nobody declared is refused here instead of
+400-ing at Meta, along with a language the template was not registered in and a
+variable count the body has no placeholders for. Whether **Meta approved it**
+is a status inside a Business account and is not knowable from this repository.
+Registering the template and getting it approved is yours. `body` is here for a
+reader — nothing composes a message from it, Meta holds the approved copy — but
+its `{{n}}` placeholders are counted, and `npm run check` refuses a body that
+skips a number.
+
+## The numbers and the people here are fixtures
+
+Like `src/agreements.ts`. `+5511987654321` reaches nobody, Joana Ribeiro is
+invented, and the documents in the book have valid check digits because the
+clearing house validates them. Never put a real contact or a real document in
+one of these files: they are committed, and the simulator does not need one.
+
+## Running it
+
+```sh
+npm run whatsapp:emulator                                               # once, at the repo root
+npm start -- --channel whatsapp --conversation acordo-1042              # you type as Joana
+npm start -- --channel whatsapp --conversation acordo-1042 --scripted   # the turns above, replayed
+npm start -- --channel whatsapp --conversation acordo-1103 --scripted --payer expires
+```
+
+`--conversation` is required: this agent ships two, and which person you are
+messaging is not a default. `acordo-1042` ends paid; `acordo-1103` is the other
+ending, where nobody pays and the charge expires.
+
+To close a cycle whose payment landed after the run ended — the ordinary case,
+and the one the commands above cannot reach:
+
+```sh
+npm run poll -- --channel whatsapp --conversation acordo-1042
+```
+
+It resumes the conversation from the bundle plus `state.db` and confirms the
+outcome: free-form while the 24-hour window is open, an approved template from
+`templates.json` once it has shut.
+
+The default backend is the local Cloud API emulator: no Meta account, no
+credential, nothing leaving the machine. `npm run whatsapp:gate` at the
+repository root runs the whole cycle over it three times from a clean state
+and asserts the final state each time, plus a fourth run that agrees now, moves
+the conversation's clock past 24 hours, pays, and polls.

package/templates/collections-agent/agents/collections-agent/channels/whatsapp/acordo-1042.json

@@ -0,0 +1,11 @@
+{
+  "name": "acordo-1042",
+  "description": "The runbook over WhatsApp: Joana answers the message about order #1042, the agent proposes terms inside the envelope, she accepts in full, the bolepix is issued, the QR goes into the conversation with the copy-and-paste as its own message underneath, the sandbox payer pays, and the agent writes 'recebemos, acordo quitado'. The debtor's turns are here; what the agent answers is the model's, never this file.",
+  "channel": "whatsapp",
+  "contact": "+5511987654321",
+  "subject": "acordo-1042",
+  "turns": [
+    { "text": "oi, recebi a mensagem sobre o acordo do pedido 1042" },
+    { "text": "fechado, pago à vista", "after_seconds": 20 }
+  ]
+}

package/templates/collections-agent/agents/collections-agent/channels/whatsapp/acordo-1103.json

@@ -0,0 +1,11 @@
+{
+  "name": "acordo-1103",
+  "description": "The other ending, over WhatsApp: Ana Paula asks to settle order #1103, the bolepix is issued and the QR goes into the conversation, and nobody pays it. The charge expires, the execution closes as failed with reason charge_expired, no record is written, and she is told once and offered a new one. Needs the stub rail's fixture payer (`--payer expires`): the API's sandbox payer only pays.",
+  "channel": "whatsapp",
+  "contact": "+5511976543210",
+  "subject": "acordo-1103",
+  "turns": [
+    { "text": "oi, sou a Ana Paula, do pedido 1103, quero quitar" },
+    { "text": "pode emitir", "after_seconds": 15 }
+  ]
+}

package/templates/collections-agent/agents/collections-agent/channels/whatsapp/templates.json

@@ -0,0 +1,23 @@
+{
+  "channel": "whatsapp",
+  "templates": [
+    {
+      "name": "acordo_quitado",
+      "language": "pt_BR",
+      "description": "The cycle closed with the receivable paid, told outside the 24-hour window. The normal collections case: the debtor agrees on Tuesday and pays on Friday, and by then this is the only message WhatsApp will carry. {{1}} is the agreement alias, which is also the only agreement this conversation may name.",
+      "body": "Oi! Recebemos o pagamento do {{1}} e ele esta quitado. Obrigado!"
+    },
+    {
+      "name": "acordo_cobranca_vencida",
+      "language": "pt_BR",
+      "description": "The receivable reached its due date unpaid. The same message the terminal sends free-form, and it has to be its own template: a debtor whose charge expired must not be told the agreement is settled. {{1}} is the agreement alias.",
+      "body": "Oi! A cobranca do {{1}} venceu sem pagamento. Se quiser, emito uma nova dentro das mesmas condicoes."
+    },
+    {
+      "name": "acordo_cobranca_cancelada",
+      "language": "pt_BR",
+      "description": "The receivable was cancelled, so nothing was paid and nothing is owed on it. {{1}} is the agreement alias.",
+      "body": "Oi! A cobranca do {{1}} foi cancelada e nada foi pago. Qualquer coisa, e so falar por aqui."
+    }
+  ]
+}

package/templates/collections-agent/agents/collections-agent/package.json

@@ -6,21 +6,23 @@
   "license": "MIT",
   "type": "module",
   "scripts": {
-    "start": "node --disable-warning=ExperimentalWarning --import tsx src/main.ts",
-    "check": "node --disable-warning=ExperimentalWarning --import tsx src/commands/check.ts",
-    "eval": "node --disable-warning=ExperimentalWarning --import tsx src/commands/eval.ts",
-    "resume": "node --disable-warning=ExperimentalWarning --import tsx src/commands/resume.ts",
-    "rerun": "node --disable-warning=ExperimentalWarning --import tsx src/commands/rerun.ts",
-    "reconcile": "node --disable-warning=ExperimentalWarning --import tsx src/commands/reconcile.ts",
-    "poll": "node --disable-warning=ExperimentalWarning --import tsx src/commands/poll.ts",
-    "webhook": "node --disable-warning=ExperimentalWarning --import tsx src/commands/webhook.ts",
-    "approve": "node --disable-warning=ExperimentalWarning --import tsx src/commands/approve.ts",
-    "deny": "node --disable-warning=ExperimentalWarning --import tsx src/commands/deny.ts",
+    "start": "codespar-agent start",
+    "check": "codespar-agent check",
+    "inspect": "codespar-agent inspect",
+    "eval": "codespar-agent eval",
+    "resume": "codespar-agent resume",
+    "rerun": "codespar-agent rerun",
+    "reconcile": "codespar-agent reconcile",
+    "poll": "codespar-agent poll",
+    "webhook": "codespar-agent webhook",
+    "approve": "codespar-agent approve",
+    "deny": "codespar-agent deny",
     "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "vitest run --pool=forks --maxWorkers=1 --root ../.. agents/collections-agent"
   },
   "dependencies": {
     "@codespar/agent-core": "0.1.0",
+    "@codespar/agent-runtime": "0.1.0",
     "qrcode-terminal": "0.12.0"
   },
   "devDependencies": {

package/templates/collections-agent/agents/collections-agent/runbook.md

@@ -18,9 +18,60 @@ Then flip the key: `npm start --workspace=agents/collections-agent -- --mode man
 
 Without a key: `npm start --workspace=agents/collections-agent -- --scenario happy-path` runs the same script on the stub rail and the recorded model, in both modes, in under a second. `--scenario charge-expired` shows the other ending.
 
+## The same scene on WhatsApp
+
+The terminal is where the runbook is timed, because the five-minute contract
+is a terminal contract and WhatsApp is deliberately outside it. But the scene
+above is a WhatsApp scene — a debtor replying to a message — so it is worth
+filming on the channel it is written for:
+
+```sh
+npm run whatsapp:emulator                                               # terminal 1
+npm run start:collections -- --channel whatsapp --conversation acordo-1042 --simulate-payer
+```
+
+The conversation goes through a local emulator of the WhatsApp Cloud API
+(`dyvit-wa-sim`, MIT, at a pinned npm version): you type as Joana, the store
+answers, the copy-and-paste arrives as its own message (which is how a person
+actually pays — a code inside a picture cannot be copied), and "recebemos,
+acordo quitado" closes it. No Meta account, no credential. For the phone frame,
+run the emulator's own web app and point it at `http://127.0.0.1:4290`. In
+`approval: human` the operator's question is still on the console, labelled
+`[operador]`, and never in the conversation.
+
+The scene above closes inside one run, which is the demo and not the ordinary
+week. The ordinary week is that Joana agrees today and pays on Friday, and by
+then WhatsApp carries only an approved template. That take is two commands:
+
+```sh
+npm run start:collections -- --channel whatsapp --conversation acordo-1042    # she agrees; nobody pays yet
+npm run poll:collections -- --channel whatsapp --conversation acordo-1042     # days later: the payment landed
+```
+
+The poll comes back to the conversation from the bundle plus `state.db` and
+sends the confirmation as a template from
+`channels/whatsapp/templates.json` — because the 24-hour window has shut. Run
+it while the window is still open and it writes freely instead; which of the
+two is the window's decision, not the command's. Run it twice and nothing is
+sent the second time.
+
+For a take with no typing at all, and for the CI:
+
+```sh
+npm run whatsapp:gate     # three runs from a clean state, plus the one across a shut window
+```
+
+Measured 2026-09-24, against the emulator: three runs, `settled` each time,
+one receivable, one record, two messages in and eight out, the same shape
+every run. That is the
+wave-4 gate — "três execuções do zero sem intervenção" — and it runs on every
+pull request. The fourth run is the week above, compressed: agree, move the
+conversation's clock 26 hours, pay, poll, `settled` with the confirmation
+carried by the `acordo_quitado` template.
+
 ## Measured
 
-First real attempt on staging, 2026-09-23 15:10:49Z, `org_demo`: the conversation, the approval and the dispatch were real; `POST /v1/charges` answered `no_eligible_providers (eligibility_empty)` in 1.15 s because the demo org has no Celcoin connection, the only issuer of the bolepix the sandbox payer can pay. The forty seconds are proven on the stub rail and the fixture payer, not on staging. Details, request ids and the three probes in `docs/OPEN_QUESTIONS.md` section 22.
+Second real run on staging, 2026-09-23 18:03:16Z, `org_demo`, replay provider, `--scenario happy-path --mode human --rail api`: **10 s from the issuance to `settled`** (create answered in 4.1 s, the instrument registered on the second look, the sandbox payer paid, the next look found `settlement: confirmed`), 15 s for the whole scenario. Charge `9fa7974e-9d1c-452e-aa01-64e9272f4f52`, execution `exe_624615ee1de452c5`. The first run of the day stopped at the issuance (no Celcoin on the demo org until ent#1613). Details, request ids and the three walls in `docs/OPEN_QUESTIONS.md` sections 22 and 31.
 
 ## Going to production