@codespar/cli 0.14.1 → 0.17.0

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

@@ -0,0 +1,174 @@
+/**
+ * The rules of collecting over a conversation, tried and refused.
+ *
+ * Every case here is an ATTEMPT: the message is handed to the channel the way
+ * the runner hands it one, and what is asserted is that nothing left the
+ * process. The backend under the channel is a recorder, so "refused" is not a
+ * claim about a return value — it is the recorder having seen nothing.
+ *
+ * The last case is the one that matters most: the same attempts through a
+ * DIFFERENT backend. The rules live above the backend, so choosing one cannot
+ * be a way around them.
+ */
+import { describe, expect, it } from "vitest";
+import { WhatsAppChannel } from "../src/channels/whatsapp/index.js";
+import { checkOutbound } from "../src/channels/rules.js";
+import type { ChannelBackend, InboundMessage, OutboundBody, SentMessage } from "../src/channels/types.js";
+
+/** A backend that carries nothing and remembers everything it was asked to carry. */
+class Recorder implements ChannelBackend {
+  readonly delivered: Array<{ to: string; body: OutboundBody }> = [];
+  constructor(
+    readonly name = "recorder",
+    readonly live = false,
+    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({ to, body });
+    return { id: `rec_${this.delivered.length}`, state: "sent" };
+  }
+  async close(): Promise<void> {}
+}
+
+const CONTACT = "+5511987654321";
+const INSIDE = new Date("2026-09-23T14:00:00-03:00");
+const OUTSIDE = new Date("2026-09-23T22:30:00-03:00");
+const HOURS = { window: "08:00-20:00", timezone: "America/Sao_Paulo" };
+
+function channelAt(now: Date, backend = new Recorder(), openSession = true) {
+  const channel = new WhatsAppChannel({
+    backend,
+    conversation: { contact: CONTACT, subject: "acordo-1042" },
+    now: () => now,
+    hours: HOURS,
+    knownSubjects: ["acordo-1042", "acordo-1077", "acordo-1103"],
+    templates: [{ name: "cobranca_lembrete", language: "pt_BR", description: "a reminder", body: "Oi {{1}}, sobre o acordo." }],
+  });
+  // A session is open because the person wrote; the window is WhatsApp's rule, not ours, and has its own test below.
+  if (openSession) {
+    (channel as unknown as { session: { observeInbound(t: number): void } }).session.observeInbound(Math.floor(now.getTime() / 1000));
+  }
+  return { channel, backend };
+}
+
+describe("the collection rules, tried through the channel", () => {
+  it("sends inside the collection hours", async () => {
+    const { channel, backend } = channelAt(INSIDE);
+    const sent = await channel.say("Oi, Joana! Sobre o pedido #1042.");
+    expect(sent.refused).toBeUndefined();
+    expect(backend.delivered).toHaveLength(1);
+  });
+
+  it("refuses everything outside the collection hours, and the backend never sees it", async () => {
+    const { channel, backend } = channelAt(OUTSIDE);
+    const sent = await channel.say("Oi, Joana! Sobre o pedido #1042.");
+    expect(sent.refused?.rule).toBe("collection_hours");
+    expect(sent.state).toBe("failed");
+    expect(backend.delivered).toHaveLength(0);
+  });
+
+  it("refuses a message to any contact but the one the conversation is bound to", () => {
+    const refusal = checkOutbound("+5511900000000", { kind: "text", text: "sobre a sua divida" }, {
+      conversation: { contact: CONTACT, subject: "acordo-1042" },
+      hours: HOURS,
+      now: () => INSIDE,
+    });
+    expect(refusal?.rule).toBe("bound_contact");
+  });
+
+  it("refuses a message that names another debtor's agreement", async () => {
+    const { channel, backend } = channelAt(INSIDE);
+    const sent = await channel.say("O acordo-1077 do Carlos tambem esta em aberto, voces podem combinar.");
+    expect(sent.refused?.rule).toBe("subject_scope");
+    expect(backend.delivered).toHaveLength(0);
+  });
+
+  it("refuses a CPF or a CNPJ in a message, formatted or bare", async () => {
+    for (const text of ["confirma o CPF 111.444.777-35?", "o CPF do titular e 11144477735", "CNPJ 12.345.678/0001-95", "CNPJ 12345678000195"]) {
+      const { channel, backend } = channelAt(INSIDE);
+      const sent = await channel.say(text);
+      expect(sent.refused?.rule, text).toBe("no_document");
+      expect(backend.delivered).toHaveLength(0);
+    }
+  });
+
+  it("does NOT read a Pix copy-and-paste or a boleto line as a document", async () => {
+    const { channel, backend } = channelAt(INSIDE);
+    const brcode = "00020126580014br.gov.bcb.pix0136stub-chg_abc5204000053039865802BR5909CODESPAR6009SAO PAULO62070503***6304STUB";
+    const bankLine = "78517596684364082005302425802108566187285620000";
+    expect((await channel.send({ kind: "instrument", instrument: "pix_copy_paste", value: brcode })).refused).toBeUndefined();
+    expect((await channel.send({ kind: "instrument", instrument: "boleto_bank_line", value: bankLine })).refused).toBeUndefined();
+    expect(backend.delivered).toHaveLength(2);
+  });
+
+  it("refuses an empty message", async () => {
+    const { channel } = channelAt(INSIDE);
+    expect((await channel.say("   ")).refused?.rule).toBe("empty_message");
+  });
+
+  it("masks the contact everywhere it is written down", async () => {
+    const { channel } = channelAt(INSIDE);
+    await channel.say("Oi!");
+    for (const line of channel.log()) {
+      expect(line.contact).not.toContain("987654321");
+      expect(line.contact).toContain("****");
+    }
+  });
+
+  it("applies the same rules through a different backend: a backend is not a way around one", async () => {
+    const other = new Recorder("another-backend", true);
+    const { channel, backend } = channelAt(OUTSIDE, other);
+    expect((await channel.say("boa noite, sobre a sua divida")).refused?.rule).toBe("collection_hours");
+    expect((await channelAt(INSIDE, new Recorder("another-backend", true)).channel.say("CPF 11144477735")).refused?.rule).toBe("no_document");
+    expect(backend.delivered).toHaveLength(0);
+  });
+});
+
+describe("WhatsApp's own rule: the 24-hour session window", () => {
+  it("carries a free-form message while the window is open", async () => {
+    const { channel, backend } = channelAt(INSIDE);
+    expect((await channel.say("Oi, Joana!")).refused).toBeUndefined();
+    expect(backend.delivered).toHaveLength(1);
+  });
+
+  it("refuses a free-form message once the window has shut, and says what would carry", async () => {
+    const { channel, backend } = channelAt(INSIDE, new Recorder(), false);
+    const sent = await channel.say("Recebemos, acordo quitado.");
+    expect(sent.refused?.rule).toBe("session_window_closed");
+    expect(sent.refused?.detail).toContain("template");
+    expect(backend.delivered).toHaveLength(0);
+  });
+
+  it("carries a declared template with the window shut", async () => {
+    const { channel, backend } = channelAt(INSIDE, new Recorder(), false);
+    const sent = await channel.send({ kind: "template", template: "cobranca_lembrete", language: "pt_BR", variables: ["Joana"] });
+    expect(sent.refused).toBeUndefined();
+    expect(backend.delivered).toHaveLength(1);
+  });
+
+  it("refuses a template the agent never declared: Meta only delivers the ones it approved", async () => {
+    const { channel, backend } = channelAt(INSIDE, new Recorder(), false);
+    const sent = await channel.send({ kind: "template", template: "nao_registrado", language: "pt_BR", variables: [] });
+    expect(sent.refused?.rule).toBe("template_unknown");
+    expect(backend.delivered).toHaveLength(0);
+  });
+
+  it("holds a template to the house rules too: an approved template is not a way past the hours", async () => {
+    const { channel, backend } = channelAt(OUTSIDE, new Recorder(), false);
+    const sent = await channel.send({ kind: "template", template: "cobranca_lembrete", language: "pt_BR", variables: ["Joana"] });
+    expect(sent.refused?.rule).toBe("collection_hours");
+    expect(backend.delivered).toHaveLength(0);
+  });
+
+  it("reopens the window when the person writes again", async () => {
+    const backend = new Recorder("recorder", false, [{ id: "in_1", from: CONTACT, text: "oi", timestamp: Math.floor(INSIDE.getTime() / 1000) }]);
+    const { channel } = channelAt(INSIDE, backend, false);
+    expect((await channel.say("antes")).refused?.rule).toBe("session_window_closed");
+    await channel.next();
+    expect((await channel.say("depois")).refused).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,135 @@
+/**
+ * The 24-hour window, read back and reasoned about.
+ *
+ * Two things are under test and they are the two halves of issue #25. A
+ * conversation that a later process comes back to has to know where its
+ * window stood, and the only honest source for that is the PROVIDER's
+ * timestamp in the record — not the run's own clock, which belongs to a
+ * machine WhatsApp never consulted. And a message that may only go as a
+ * template has to be held to what the agent actually declared, because a
+ * template Meta never approved is not a message, it is a 4xx.
+ *
+ * None of it needs the emulator: every refusal here happens above the
+ * backend, which is the whole claim `channels/` makes.
+ */
+import { describe, expect, it } from "vitest";
+import { templateArity, type WhatsAppTemplate } from "@codespar/agent-core";
+import { WhatsAppChannel } from "../src/channels/whatsapp/index.js";
+import { SessionWindow, sessionStateFromChannelLog, SESSION_WINDOW_SECONDS } from "../src/channels/whatsapp/session.js";
+import type { ChannelBackend, InboundMessage, OutboundBody, SentMessage } from "../src/channels/types.js";
+
+class Recorder implements ChannelBackend {
+  readonly name = "recorder";
+  readonly live = false;
+  readonly delivered: OutboundBody[] = [];
+  async open(): Promise<void> {}
+  async next(): Promise<InboundMessage | undefined> {
+    return undefined;
+  }
+  async deliver(_to: string, body: OutboundBody): Promise<SentMessage> {
+    this.delivered.push(body);
+    return { id: `rec_${this.delivered.length}`, state: "sent" };
+  }
+  async close(): Promise<void> {}
+}
+
+const CONTACT = "+5511987654321";
+const TUESDAY = new Date("2026-09-23T14:00:00-03:00");
+const FRIDAY = new Date("2026-09-25T14:00:00-03:00");
+const QUITADO: WhatsAppTemplate = { name: "acordo_quitado", language: "pt_BR", description: "paid", body: "Recebemos o pagamento do {{1}}." };
+
+function channel(now: Date, lastInboundAt?: number, backend = new Recorder()) {
+  const c = new WhatsAppChannel({
+    backend,
+    conversation: { contact: CONTACT, subject: "acordo-1042" },
+    now: () => now,
+    templates: [QUITADO],
+    ...(lastInboundAt !== undefined ? { session: { lastInboundAt } } : {}),
+  });
+  return { channel: c, backend };
+}
+
+describe("where the window stood, read back from the record", () => {
+  it("takes the provider's timestamp and never the line's own `at`", () => {
+    const state = sessionStateFromChannelLog([
+      { direction: "in", at: "2020-01-01T00:00:00.000Z", provider_timestamp: 1790182801 },
+      { direction: "out", at: "2026-09-23T17:00:10.000Z" },
+      { direction: "in", at: "2020-01-01T00:00:00.000Z", provider_timestamp: 1790182821 },
+    ]);
+    expect(state.lastInboundAt).toBe(1790182821);
+  });
+
+  it("yields nothing from a log whose inbound lines carry no provider timestamp, and the window then reads as shut", () => {
+    // A bundle written before the timestamp was recorded. Shut is the safe
+    // direction: a template is deliverable in both halves of the rule.
+    const state = sessionStateFromChannelLog([{ direction: "in", at: "2026-09-23T17:00:00.000Z", text: "oi" }]);
+    expect(state.lastInboundAt).toBeUndefined();
+    expect(new SessionWindow([], state).open(TUESDAY)).toBe(false);
+  });
+
+  it("ignores outbound lines: the window is opened by the PERSON writing, not by us", () => {
+    expect(sessionStateFromChannelLog([{ direction: "out", provider_timestamp: 1790182801 }]).lastInboundAt).toBeUndefined();
+  });
+});
+
+describe("a conversation a later process comes back to", () => {
+  it("writes freely when the restored window is still open", async () => {
+    const { channel: c, backend } = channel(TUESDAY, Math.floor(TUESDAY.getTime() / 1000) - 3600);
+    expect(c.sessionOpen).toBe(true);
+    expect(c.sessionRemainingSeconds).toBe(SESSION_WINDOW_SECONDS - 3600);
+    const sent = await c.say("Recebemos, acordo quitado.");
+    expect(sent.refused).toBeUndefined();
+    expect(backend.delivered).toHaveLength(1);
+  });
+
+  it("refuses free text once the restored window has shut, which is the case the poll exists for", async () => {
+    const { channel: c, backend } = channel(FRIDAY, Math.floor(TUESDAY.getTime() / 1000));
+    expect(c.sessionOpen).toBe(false);
+    const sent = await c.say("Recebemos, acordo quitado.");
+    expect(sent.refused?.rule).toBe("session_window_closed");
+    expect(backend.delivered).toHaveLength(0);
+  });
+
+  it("carries the declared template in the same breath, with the language the registry holds", async () => {
+    const { channel: c, backend } = channel(FRIDAY, Math.floor(TUESDAY.getTime() / 1000));
+    const declared = c.declaredTemplate("acordo_quitado");
+    expect(declared?.language).toBe("pt_BR");
+    const sent = await c.send({ kind: "template", template: declared!.name, language: declared!.language, variables: ["acordo-1042"] });
+    expect(sent.refused).toBeUndefined();
+    expect(backend.delivered).toEqual([{ kind: "template", template: "acordo_quitado", language: "pt_BR", variables: ["acordo-1042"] }]);
+  });
+
+  it("reads as shut when nothing restored it: a process with no record of the conversation assumes the worst", () => {
+    expect(channel(TUESDAY).channel.sessionOpen).toBe(false);
+  });
+});
+
+describe("the local registry refuses what Meta would refuse", () => {
+  it("a name the agent never declared", async () => {
+    const { channel: c, backend } = channel(FRIDAY, Math.floor(TUESDAY.getTime() / 1000));
+    const sent = await c.send({ kind: "template", template: "nao_registrado", language: "pt_BR", variables: [] });
+    expect(sent.refused?.rule).toBe("template_unknown");
+    expect(backend.delivered).toHaveLength(0);
+  });
+
+  it("a language the template was not registered in: an approved template does not exist in another", async () => {
+    const { channel: c, backend } = channel(FRIDAY, Math.floor(TUESDAY.getTime() / 1000));
+    const sent = await c.send({ kind: "template", template: "acordo_quitado", language: "es_MX", variables: ["acordo-1042"] });
+    expect(sent.refused?.rule).toBe("template_language_unknown");
+    expect(backend.delivered).toHaveLength(0);
+  });
+
+  it("a variable count the body has no placeholders for", async () => {
+    const { channel: c, backend } = channel(FRIDAY, Math.floor(TUESDAY.getTime() / 1000));
+    const sent = await c.send({ kind: "template", template: "acordo_quitado", language: "pt_BR", variables: ["acordo-1042", "a mais"] });
+    expect(sent.refused?.rule).toBe("template_variables_mismatch");
+    expect(sent.refused?.detail).toContain("takes 1 variable(s)");
+    expect(backend.delivered).toHaveLength(0);
+  });
+
+  it("counts the placeholders the way Meta numbers them", () => {
+    expect(templateArity("nenhuma")).toBe(0);
+    expect(templateArity("Oi {{1}}, sobre o {{2}}.")).toBe(2);
+    expect(templateArity("Oi {{ 1 }}.")).toBe(1);
+  });
+});

package/templates/bills-agent/packages/agent-runtime/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "."
+  },
+  "include": [
+    "src/**/*.ts"
+  ]
+}

package/templates/bills-agent/vitest.config.ts

@@ -2,7 +2,7 @@ import { defineConfig } from "vitest/config";
 
 export default defineConfig({
   test: {
-    include: ["packages/*/test/**/*.test.ts", "agents/*/test/**/*.test.ts"],
+    include: ["packages/*/test/**/*.test.ts", "agents/*/test/**/*.test.ts", "test/**/*.test.ts"],
     pool: "forks",
     maxWorkers: 1,
     minWorkers: 1,

package/templates/collections-agent/README.md

@@ -1,13 +1,16 @@
 # {{name}}
 
 Scaffolded by `codespar init --template collections-agent` from the `collections-agent` starter kit
-(https://github.com/codespar/agent-starter-kits at `778223274a5df3521d9ef9f33a21446868482391`, agent 0.1.0).
+(https://github.com/codespar/agent-starter-kits at `8f130b7cdc30510c929e6f7ebb07184f763e6ce4`, agent 0.1.0).
 
 The merchant's agent that collects: agrees terms with the payer inside a negotiation envelope, issues one bolepix per instalment with an idempotency key, presents the QR and the copy-and-paste in the conversation, and closes the cycle on commerce.charge.paid or commerce.charge.expired.
 
-`@codespar/agent-core` is not published on npm yet, so the copy this agent was built
-against (0.1.0) is vendored under `packages/agent-core/` and linked as an npm workspace;
-the agent's own `package.json` pin resolves to it unchanged.
+`@codespar/agent-core` and `@codespar/agent-runtime` are not published on npm, so the copies this agent was built
+against are vendored here and linked as npm workspaces; the agent's own
+`package.json` pins resolve to them unchanged:
+
+  - `packages/agent-core/` — @codespar/agent-core 0.1.0
+  - `packages/agent-runtime/` — @codespar/agent-runtime 0.1.0
 
 ```
   cp agents/collections-agent/.env.example agents/collections-agent/.env   # then fill in your keys
@@ -17,4 +20,4 @@ the agent's own `package.json` pin resolves to it unchanged.
 
 The agent's guide is [`agents/collections-agent/README.md`](agents/collections-agent/README.md); its commands run at this root
 (`npm run check`, `npm run eval`, `npm test`) or inside `agents/collections-agent/`. The manifest pins
-`cli: "@codespar/cli@0.13.0"`, the CLI version whose `agent run`/`eval` this agent was written for.
+`cli: "@codespar/cli@0.14.0"`, the CLI version whose `agent run`/`eval` this agent was written for.

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

@@ -2,3 +2,17 @@
 CODESPAR_API_KEY=csk_test_your_key_here
 # https://console.anthropic.com. Without it, `npm start` replays the recorded happy-path.
 ANTHROPIC_API_KEY=sk-ant-your_key_here
+
+# --- WhatsApp, the official Cloud API backend. Commented out and empty on purpose. ---
+# The default backend needs NONE of these: it talks to a local Cloud API emulator
+# (`npm run whatsapp:emulator` at the repo root), with no Meta account and nothing
+# leaving the machine. Uncomment these only if you have your own Meta Business
+# account and want `--backend cloud-api`, which is the same code pointed at
+# graph.facebook.com. This repo has never run one; the shapes are written from
+# Meta's published documentation. Nothing in the tests or the CI reads them.
+# WHATSAPP_PHONE_NUMBER_ID=
+# WHATSAPP_ACCESS_TOKEN=
+# WHATSAPP_VERIFY_TOKEN=
+# WHATSAPP_APP_SECRET=
+# WHATSAPP_API_VERSION=v21.0
+# WHATSAPP_WEBHOOK_PORT=3111

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

@@ -9,11 +9,13 @@ You are editing a reference agent of the CodeSpar Agent Starter Kits. These rule
 5. **`actor` on everything.** Every event, approval and receipt copy carries who acted. A record without an actor fails the CI.
 6. **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. The sandbox payer (`POST /v1/test/charges/{id}/pay`) is test-environment only and the code never calls it with anything else.
 7. **One receivable per instalment, one `idempotency_key` per receivable.** The key is the attempt id; a retry must return the same charge, never a second one the same debtor could pay twice. Do not touch that.
-8. **The cycle closes on the state machine, not on prose.** `commerce.charge.paid` settles; `expired` and `cancelled` fail. By poll (`GET /v1/charges/{id}`) or by webhook (`channels/webhook`), once and only once. A duplicate event never sends the debtor a second message.
+8. **The cycle closes on the state machine, not on prose.** `commerce.charge.paid` settles; `expired` and `cancelled` fail. By poll (`GET /v1/charges/{id}`) or by webhook (`packages/agent-runtime/src/webhook.ts`, `npm run webhook`), once and only once. A duplicate event never sends the debtor a second message.
 9. **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.
 10. **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`.
-11. **Do not write "verifiable by a third party"** anywhere. The approval artifact is HMAC with a local key, and the API seals no record for a paid charge today.
-12. **Collection has rules** (hours, secrecy of the debt, no embarrassment, LGPD). The prompt codifies them and the envelope enforces the hours. Do not loosen either.
-13. **No telemetry.** Nothing in this repository phones home.
+11. **Do not write "verifiable by a third party"** anywhere in this agent. The Ed25519 seal a third party can check exists on a PAYMENT receipt; this agent mints receivables, and the API seals no record for a paid charge — no chain, no signature, nothing to verify. The approval artifact is HMAC with a local key.
+12. **Collection has rules** (hours, secrecy of the debt, no embarrassment, LGPD). The prompt codifies them, the envelope enforces the hours at the gate, and the channel enforces them again on every outbound message (`packages/agent-runtime/src/channels/rules.ts`): nothing outside the collection hours, nothing to a contact other than the bound one, nothing naming another debtor's agreement, no CPF or CNPJ in a message. Do not loosen any of them, and do not add a path that sends a message without going through `channel.send`.
+13. **A channel is the runner's, the conversations are this agent's.** `channels/whatsapp/<name>.json` names the contact, the agreement and the debtor's turns; `agent.yaml` declares the channel; `npm run check` fails if the two disagree in either direction. Never put a real phone number or a real document in one — the shipped conversation is a fixture, like `src/agreements.ts`.
+14. **The official WhatsApp backend is never called from a test or the CI.** The credentials are absent by default and commented out in `.env.example`. What the tests drive are the pure functions (signature, webhook parse, handshake, request builder); a test that reaches Meta is a bug, not coverage.
+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/collections-agent/agents/collections-agent/CLAUDE.md

@@ -9,11 +9,13 @@ You are editing a reference agent of the CodeSpar Agent Starter Kits. These rule
 5. **`actor` on everything.** Every event, approval and receipt copy carries who acted. A record without an actor fails the CI.
 6. **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. The sandbox payer (`POST /v1/test/charges/{id}/pay`) is test-environment only and the code never calls it with anything else.
 7. **One receivable per instalment, one `idempotency_key` per receivable.** The key is the attempt id; a retry must return the same charge, never a second one the same debtor could pay twice. Do not touch that.
-8. **The cycle closes on the state machine, not on prose.** `commerce.charge.paid` settles; `expired` and `cancelled` fail. By poll (`GET /v1/charges/{id}`) or by webhook (`channels/webhook`), once and only once. A duplicate event never sends the debtor a second message.
+8. **The cycle closes on the state machine, not on prose.** `commerce.charge.paid` settles; `expired` and `cancelled` fail. By poll (`GET /v1/charges/{id}`) or by webhook (`packages/agent-runtime/src/webhook.ts`, `npm run webhook`), once and only once. A duplicate event never sends the debtor a second message.
 9. **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.
 10. **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`.
-11. **Do not write "verifiable by a third party"** anywhere. The approval artifact is HMAC with a local key, and the API seals no record for a paid charge today.
-12. **Collection has rules** (hours, secrecy of the debt, no embarrassment, LGPD). The prompt codifies them and the envelope enforces the hours. Do not loosen either.
-13. **No telemetry.** Nothing in this repository phones home.
+11. **Do not write "verifiable by a third party"** anywhere in this agent. The Ed25519 seal a third party can check exists on a PAYMENT receipt; this agent mints receivables, and the API seals no record for a paid charge — no chain, no signature, nothing to verify. The approval artifact is HMAC with a local key.
+12. **Collection has rules** (hours, secrecy of the debt, no embarrassment, LGPD). The prompt codifies them, the envelope enforces the hours at the gate, and the channel enforces them again on every outbound message (`packages/agent-runtime/src/channels/rules.ts`): nothing outside the collection hours, nothing to a contact other than the bound one, nothing naming another debtor's agreement, no CPF or CNPJ in a message. Do not loosen any of them, and do not add a path that sends a message without going through `channel.send`.
+13. **A channel is the runner's, the conversations are this agent's.** `channels/whatsapp/<name>.json` names the contact, the agreement and the debtor's turns; `agent.yaml` declares the channel; `npm run check` fails if the two disagree in either direction. Never put a real phone number or a real document in one — the shipped conversation is a fixture, like `src/agreements.ts`.
+14. **The official WhatsApp backend is never called from a test or the CI.** The credentials are absent by default and commented out in `.env.example`. What the tests drive are the pure functions (signature, webhook parse, handshake, request builder); a test that reaches Meta is a bug, not coverage.
+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.