@codespar/cli 0.17.0 → 0.18.0

package/templates/bills-agent/packages/agent-core/src/api/rail.ts

@@ -2,8 +2,10 @@
  * The CodeSpar sandbox rail. With the signed envelope the consent returned
  * (`mandate.canonical` + `mandate.signature`) it spends through
  * `POST /v1/consumer-payments/execute`; without it, by mandate id through
- * `POST /v1/consumers/mandates/{id}/spend`. Both are idempotent on
- * `attempt_id`. The by-id route answered `bad_signature` on staging for a
+ * `POST /v1/consumers/mandates/{id}/spend`. Idempotence on both is OPT-IN
+ * and keyed on an explicit `attempt_id`, which every payment here carries: a
+ * spend without one is a fresh payment on every request (ent#1671, #1683).
+ * What a repeat of an attempt answers is in `lookup` below. The by-id route answered `bad_signature` on staging for a
  * mandate carrying `periodic_cap` (OPEN_QUESTIONS §14), which is why the
  * envelope is preferred when it exists. Receipts come back from
  * `GET /v1/consumers/receipts/{id}`.
@@ -14,19 +16,19 @@
  */
 import type { ApiClient } from "@codespar/sdk";
 import type { Mandate } from "../mandate.js";
-import type { PaymentRail, RailLookup, RailOutcome, RailPayment, RailReceipt } from "../rail.js";
+import { checkQuote } from "../quote.js";
+import { checkSpendApproval, type PaymentRail, type RailLookup, type RailOutcome, type RailPayment, type RailReceipt } from "../rail.js";
 import type { Actor } from "../types.js";
-import { describeApiError, isUncertain } from "./client.js";
+import { describeApiError, isUncertain, type SpendErrorCode } from "./client.js";
 
-/** The asymmetric seal as the API serves it, or nulls when this deployment
- *  does not serve one. Never throws on a shape it does not recognise: a
- *  receipt is evidence of a payment that already happened, and refusing to
- *  record it over an unexpected field would trade the record for the proof. */
-function readEd25519Seal(body: unknown): { receipt_sig_ed25519: string | null; receipt_sig_kid: string | null } {
-  const r = body as { receipt_sig_ed25519?: unknown; receipt_sig_kid?: unknown };
-  const str = (v: unknown): string | null => (typeof v === "string" && v.length > 0 ? v : null);
-  return { receipt_sig_ed25519: str(r.receipt_sig_ed25519), receipt_sig_kid: str(r.receipt_sig_kid) };
-}
+/** Another presentation of this attempt is claimed and has no recorded outcome yet: it may be moving money right now. */
+const ATTEMPT_IN_FLIGHT: SpendErrorCode = "psp_attempt_in_flight";
+/** This attempt failed, moved no money and was compensated; the API will never run this id again. */
+const ATTEMPT_SPENT: SpendErrorCode = "psp_attempt_conflict";
+/** This attempt id was already used for a DIFFERENT payment (checked before its state); nothing was held or sent. */
+const ATTEMPT_ID_CONFLICT: SpendErrorCode = "attempt_id_conflict";
+/** Another project of this organization holds this attempt id; opaque by design, nothing was held or sent. */
+const ATTEMPT_ID_UNAVAILABLE: SpendErrorCode = "attempt_id_unavailable";
 
 export class CodeSparRail implements PaymentRail {
   readonly name = "codespar" as const;
@@ -37,6 +39,12 @@ export class CodeSparRail implements PaymentRail {
   ) {}
 
   async pay(payment: RailPayment): Promise<RailOutcome> {
+    // Without the quote the sealed receipt names no payee (OPEN_QUESTIONS §18), and the API pays a quote that disagrees. Neither goes out.
+    const quoted = checkQuote(payment);
+    if (!quoted.ok) return { status: "failed", code: quoted.code, message: `${quoted.detail}; nothing was sent` };
+    // Without it the receipt seals no link to what was approved (OPEN_QUESTIONS §3), and the API refuses a malformed one with 400 anyway.
+    const approval = checkSpendApproval(payment);
+    if (!approval.ok) return { status: "failed", code: approval.code, message: `${approval.detail}; nothing was sent` };
     try {
       const outcome =
         this.envelope?.canonical && this.envelope.signature
@@ -49,11 +57,13 @@ export class CodeSparRail implements PaymentRail {
                 agent_id: payment.agent_id,
                 payee: payment.payee,
                 attempt_id: payment.attempt_id,
+                quote: quoted.quote,
+                approval: approval.approval,
               },
             })
           : await this.api.post("/v1/consumers/mandates/{id}/spend", {
               path: { id: payment.mandate_id },
-              body: { amount_minor: payment.amount_minor, payee: payment.payee, agent_id: payment.agent_id, attempt_id: payment.attempt_id },
+              body: { amount_minor: payment.amount_minor, payee: payment.payee, agent_id: payment.agent_id, attempt_id: payment.attempt_id, quote: quoted.quote, approval: approval.approval },
             });
       return {
         status: "settled",
@@ -61,24 +71,50 @@ export class CodeSparRail implements PaymentRail {
         receipt_id: outcome.receipt?.id ?? null,
         money_moved: outcome.payment.moneyMoved,
         sandbox: !outcome.payment.moneyMoved,
+        ...(outcome.idempotent_replay ? { replayed: true as const } : {}),
         raw: outcome,
       };
     } catch (err) {
       const failure = describeApiError(err);
+      // Not a refusal: the other presentation may already have reached the provider, so "nothing moved" would be a claim nobody can make.
+      if (failure.code === ATTEMPT_IN_FLIGHT) return { status: "uncertain", code: failure.code, message: failure.message };
       if (isUncertain(failure)) return { status: "uncertain", code: failure.code, message: failure.message };
+      if (failure.code === ATTEMPT_SPENT) return { status: "failed", code: failure.code, message: failure.message, spent: true };
+      // Held, never spent: the id belongs to another payment or another project, so no generation may be derived past it.
+      if (failure.code === ATTEMPT_ID_CONFLICT) return { status: "failed", code: failure.code, message: failure.message, held: "conflict" };
+      if (failure.code === ATTEMPT_ID_UNAVAILABLE) return { status: "failed", code: failure.code, message: failure.message, held: "unavailable" };
       return { status: "failed", code: failure.code, message: failure.message };
     }
   }
 
   /**
-   * There is no read route for an attempt. The documented way is to present
-   * the same `attempt_id` again: the lifecycle is idempotent on it and
-   * answers the state it reached. `psp_attempt_in_flight` means the first
-   * presentation is still running.
+   * There is no read route for an attempt: the way to learn what became of
+   * one is to present the same `attempt_id`, with the same payment, again.
+   * Against the deployed API (ent#1671, #1683) that call never moves money
+   * for an attempt it already holds, and each answer maps to one reading:
+   *
+   * - settled: `200` with the ORIGINAL body verbatim (same `transactionId`,
+   *   same stored `receipt.id`, which the receipt route resolves) plus
+   *   `idempotent_replay: true`. Read as `settled`, exactly as the first
+   *   answer, and marked `replayed`.
+   * - `psp_attempt_in_flight` (409): claimed, no outcome yet, on every rail.
+   *   Read as `in_flight`; the next reconcile asks again with the SAME id.
+   * - `psp_attempt_uncertain` (409): pinned, dispatch outcome unknown. Read as
+   *   `uncertain`, which leaves the execution open for a person.
+   * - `psp_attempt_conflict` (409): failed, compensated, no money. Read as
+   *   `failed` and `spent`.
+   * - `attempt_id_conflict` / `attempt_id_unavailable` (409): the id is held for
+   *   a different payment, or by another project. Read as `failed` and `held`,
+   *   never `spent`: nothing was held or sent by this call. Neither can come from re-presenting the
+   *   payment this execution sent, whose tuple is the one the id was claimed
+   *   with, so seeing one here is a defect worth its readable failure.
+   * - an attempt the API never took: there is no record to answer from, so
+   *   this call IS the payment. Reconcile runs only after the outbox row
+   *   flipped to `sent`, so an attempt it looks up was presented once already.
    */
   async lookup(_attemptId: string, payment: RailPayment): Promise<RailLookup> {
     const outcome = await this.pay(payment);
-    if (outcome.status === "failed" && outcome.code === "psp_attempt_in_flight") return { status: "in_flight" };
+    if (outcome.status === "uncertain" && outcome.code === ATTEMPT_IN_FLIGHT) return { status: "in_flight" };
     return outcome;
   }
 
@@ -88,7 +124,9 @@ export class CodeSparRail implements PaymentRail {
       return {
         receipt_id: r.receipt_id,
         state: r.state,
-        mandate: { id: r.mandate.id },
+        mandate: { id: r.mandate.id, sig_sha256: r.mandate.sig_sha256 },
+        chain_version: r.chain_version,
+        approval: r.approval ?? null,
         payment: {
           amount_minor: r.payment.amount_minor,
           payee: r.quote?.payee ?? null,
@@ -99,12 +137,10 @@ export class CodeSparRail implements PaymentRail {
         },
         chain: r.chain,
         receipt_sig: r.receipt_sig,
-        // ent#1633 landed after `@codespar/sdk@0.16.6` was generated, so the
-        // typed response does not carry these two yet. Read off the body
-        // defensively rather than pinning a new SDK for two nullable strings:
-        // a deployment that predates the change answers null, which is the
-        // same answer the columns hold and reads as `unsigned`.
-        ...readEd25519Seal(r),
+        // `||`, not `??`: a deployment older than ent#1633 omits both fields,
+        // and an empty string is no signature either. Both read as `unsigned`.
+        receipt_sig_ed25519: r.receipt_sig_ed25519 || null,
+        receipt_sig_kid: r.receipt_sig_kid || null,
         actor,
         raw: r,
       };

package/templates/bills-agent/packages/agent-core/src/api/sandbox-payer.ts

@@ -12,27 +12,12 @@
  * `fetch`, see docs/OPEN_QUESTIONS.md section 31c. The key is checked for
  * the `csk_test_` prefix before a client exists, like every other call.
  */
-import { ApiClient } from "@codespar/sdk";
+import { ApiClient, type ApiOperation, type ApiSuccess } from "@codespar/sdk";
 import type { ApiFailure } from "./client.js";
 import { createCodeSparClient, describeApiError } from "./client.js";
 
-export interface SandboxPaidState {
-  charge_id: string;
-  status: "paid";
-  local_status: string;
-  currency: string;
-  quoted_minor: number;
-  paid_minor: number;
-  payment: "full" | "partial" | "over";
-  paid_via: string;
-  wallet_id: string;
-  ledger_entry_id: string | null;
-  event: { id: string; type: string } | null;
-  simulated: boolean;
-  settled_against: string | null;
-  money_moved: false;
-  idempotent_replay: boolean;
-}
+/** What the payer route answers, as the SDK's generated OpenAPI types it. */
+export type SandboxPaidState = ApiSuccess<ApiOperation<"/v1/test/charges/{chargeId}/pay", "post">>;
 
 export type SandboxPayResult = { ok: true; state: SandboxPaidState } | { ok: false; failure: ApiFailure };
 

package/templates/bills-agent/packages/agent-core/src/approval.ts

@@ -13,7 +13,7 @@ import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "n
 import { dirname, join } from "node:path";
 import { canonicalJson, hexEqual, hmacSha256Hex, itemsHash } from "./hash.js";
 import type { Execution } from "./state-machine.js";
-import type { Actor, ApprovalArtifact, EscalationTrigger, ExecutionBatch } from "./types.js";
+import type { Actor, ApprovalArtifact, EscalationTrigger, ExecutionBatch, ExecutionComposition } from "./types.js";
 import { newId } from "./ids.js";
 
 export const APPROVAL_KEY_ID = "local-dev-stub";
@@ -78,6 +78,8 @@ export function createApprovalArtifact(signer: ApprovalSigner, input: CreateAppr
     // null — on an execution that is not part of a batch, so the payload a
     // bills-agent artifact signs is unchanged by this field existing.
     ...(execution.batch ? { batch: execution.batch } : {}),
+    // What the single amount was composed of, when it was composed of lines. Same rule as `batch`: omitted, never null.
+    ...(execution.composition ? { composition: execution.composition } : {}),
     ...(input.escalation ? { escalation: input.escalation } : {}),
     actor: input.actor,
   };
@@ -89,7 +91,7 @@ export function createApprovalArtifact(signer: ApprovalSigner, input: CreateAppr
 
 export type ApprovalCheck =
   | { ok: true }
-  | { ok: false; problem: "signature_invalid" | "items_hash_mismatch" | "expired" | "wrong_execution" | "wrong_mandate" | "batch_mismatch" };
+  | { ok: false; problem: "signature_invalid" | "items_hash_mismatch" | "expired" | "wrong_execution" | "wrong_mandate" | "batch_mismatch" | "composition_mismatch" };
 
 /** Two batch bindings are the same binding, or one is absent and so is the other. */
 function sameBatch(a: ExecutionBatch | undefined, b: ExecutionBatch | undefined): boolean {
@@ -97,6 +99,12 @@ function sameBatch(a: ExecutionBatch | undefined, b: ExecutionBatch | undefined)
   return a.ref === b.ref && a.batch_hash === b.batch_hash && a.index === b.index && a.count === b.count;
 }
 
+/** Two compositions are the same binding, or one is absent and so is the other. */
+function sameComposition(a: ExecutionComposition | undefined, b: ExecutionComposition | undefined): boolean {
+  if (a === undefined || b === undefined) return a === b;
+  return a.ref === b.ref && a.composition_hash === b.composition_hash && a.line_count === b.line_count;
+}
+
 /**
  * The rule that makes the artifact proof: before `executing`, recompute the
  * hash of what is about to be executed and compare it with the artifact.
@@ -118,6 +126,10 @@ export function checkApprovalArtifact(
   // line was one OF. An execution that gained, lost or moved its place in a
   // batch after approval is not the one that was approved.
   if (!sameBatch(artifact.batch, execution.batch)) return { ok: false, problem: "batch_mismatch" };
+  // The item's amount is attested above; this is what that amount was made of.
+  // A cart recomposed at a constant total leaves `items_hash` unchanged and
+  // this hash changed, and that is the only thing that sees it.
+  if (!sameComposition(artifact.composition, execution.composition)) return { ok: false, problem: "composition_mismatch" };
   if (new Date(artifact.expires_at).getTime() <= now.getTime()) return { ok: false, problem: "expired" };
   return { ok: true };
 }

package/templates/bills-agent/packages/agent-core/src/bundle.ts

@@ -5,6 +5,7 @@
  */
 import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, join } from "node:path";
+import { canonicalJson } from "./hash.js";
 import type { Mandate } from "./mandate.js";
 import type { RailReceipt } from "./rail.js";
 import type { ApprovalArtifact } from "./types.js";
@@ -97,11 +98,18 @@ export class ProofBundle {
     writeFileSync(join(this.dir, "mandate.snapshot.json"), JSON.stringify({ ...safe, beneficiaries: safe.beneficiaries.map((b) => ({ ...b, payee: maskPayee(b.payee) })), merchant_allowlist: safe.merchant_allowlist.map(maskPayee) }, null, 2) + "\n");
   }
 
-  /** Returns the path INSIDE the bundle (`receipts/<id>.json`): a bundle travels, and an absolute path names the machine that wrote it. */
-  receipt(receipt: RailReceipt): string {
+  /**
+   * Returns the path INSIDE the bundle (`receipts/<id>.json`): a bundle travels, and an absolute path names the machine that wrote it.
+   *
+   * `approval_id` names the artifact in `approval.json` whose hashes the spend carried, so `npm run verify` holds the receipt's sealed
+   * approval link against THAT artifact, found by identity and never by looking for one whose hash happens to match. The copy stays
+   * masked: binding its body to the chain needs the unmasked read, which `verify --from-api` takes from the API and writes nowhere.
+   */
+  receipt(receipt: RailReceipt, context: { approval_id?: string | undefined } = {}): string {
     const relative = join("receipts", `${receipt.receipt_id}.json`);
     const { raw: _raw, ...safe } = receipt;
-    writeFileSync(join(this.dir, relative), JSON.stringify({ ...safe, payment: { ...safe.payment, payee: safe.payment.payee ? maskPayee(safe.payment.payee) : null } }, null, 2) + "\n");
+    const copy = { ...safe, payment: { ...safe.payment, payee: safe.payment.payee ? maskPayee(safe.payment.payee) : null }, ...(context.approval_id ? { approval_id: context.approval_id } : {}) };
+    writeFileSync(join(this.dir, relative), JSON.stringify(copy, null, 2) + "\n");
     return relative;
   }
 
@@ -149,6 +157,30 @@ function readdirSorted(dir: string): string[] {
     .sort();
 }
 
+/**
+ * Where the bundle's masked copy of a receipt says something the API's read of the same receipt does not. The copy is not what the
+ * signature covers, so a copy edited after the fact still verifies at the signature level; this is what catches it once the read is
+ * in hand. The payee is compared masked, the only form the copy holds. An empty list means the copy is a faithful mask of the read.
+ */
+export function copyDisagreesWithRead(copy: Record<string, unknown>, read: Record<string, unknown>): string[] {
+  const field = (o: unknown, k: string): unknown => (o && typeof o === "object" ? (o as Record<string, unknown>)[k] : undefined);
+  const readPayee = field(read["quote"], "payee");
+  const expected: Array<[string, unknown, unknown]> = [
+    ["receipt_id", copy["receipt_id"], read["receipt_id"]],
+    ["chain", copy["chain"], read["chain"]],
+    ["mandate.id", field(copy["mandate"], "id"), field(read["mandate"], "id")],
+    ["payment.amount_minor", field(copy["payment"], "amount_minor"), field(read["payment"], "amount_minor")],
+    ["payment.attempt_id", field(copy["payment"], "attempt_id"), field(read["payment"], "attempt_id")],
+    ["payment.money_moved", field(copy["payment"], "money_moved"), field(read["payment"], "money_moved")],
+    ["payment.at", field(copy["payment"], "at"), field(read["payment"], "at")],
+    ["payment.payee", field(copy["payment"], "payee"), typeof readPayee === "string" ? maskPayee(readPayee) : null],
+  ];
+  // Written onto the copy since the rail reads them through the SDK's types (0.16.10); a copy from before carries neither, and is not faulted for it.
+  if ("chain_version" in copy) expected.push(["chain_version", copy["chain_version"], read["chain_version"]]);
+  if ("approval" in copy) expected.push(["approval", canonicalJson(copy["approval"] ?? null), canonicalJson(read["approval"] ?? null)]);
+  return expected.filter(([, a, b]) => a !== b).map(([name]) => name);
+}
+
 /** `escola@exemplo.com.br` -> `es***@exemplo.com.br`; `+5511999998888` -> `+55***8888`; a UUID keeps its first and last 4. */
 export function maskPayee(payee: string): string {
   if (payee === "*") return payee;

package/templates/bills-agent/packages/agent-core/src/channels.ts

@@ -47,16 +47,22 @@ export const ConversationScriptSchema = z
      * different one, which is the secrecy rule as code rather than as prose.
      */
     subject: z.string().min(1).optional(),
-    /** The person's turns, in order. */
+    /**
+     * The person's turns, in order: something they TYPED (`text`), or a quick
+     * reply they TAPPED (`reply`, the id of a button a declared template
+     * offers). Exactly one of the two.
+     */
     turns: z
       .array(
         z
           .object({
-            text: z.string().min(1),
+            text: z.string().min(1).optional(),
+            reply: z.object({ id: z.string().min(1), title: z.string().min(1).optional() }).strict().optional(),
             /** Seconds after the previous inbound turn, on the run's clock. Keeps a scripted run deterministic. */
             after_seconds: z.number().int().nonnegative().default(0),
           })
-          .strict(),
+          .strict()
+          .refine((t) => (t.text === undefined) !== (t.reply === undefined), { message: "a turn is either text the person typed or a reply they tapped, exactly one" }),
       )
       .nonempty(),
   })
@@ -86,6 +92,26 @@ export const TEMPLATE_REGISTRY_FILE = "templates.json";
  * match is a `132000` from the Cloud API and there is no reason to learn that
  * in production.
  */
+/**
+ * A quick-reply button a template offers, and what tapping it MEANS.
+ *
+ * `intent` is the turn the model receives when the person taps it — written
+ * here, by whoever wrote the template, and never by the model. A tap carries
+ * an id and a title; the title is copy and can change, the id cannot, and the
+ * intent is what the id stands for. An id this registry does not declare is
+ * not a turn at all.
+ */
+export const QuickReplySchema = z
+  .object({
+    id: z.string().regex(/^[a-z0-9_]{1,64}$/, "a reply id is lower-case letters, digits and underscores"),
+    /** What the button says. Meta caps a quick reply at 20 characters. */
+    title: z.string().min(1).max(20),
+    intent: z.string().min(1),
+  })
+  .strict();
+
+export type QuickReply = z.infer<typeof QuickReplySchema>;
+
 export const WhatsAppTemplateSchema = z
   .object({
     /** Meta's own naming rule for a template. */
@@ -94,6 +120,15 @@ export const WhatsAppTemplateSchema = z
     language: z.string().regex(/^[a-z]{2}(_[A-Z]{2})?$/, 'expected a language code, e.g. "pt_BR"'),
     description: z.string().min(1),
     body: z.string().min(1),
+    /** Quick replies the template carries (Meta allows up to three on a template). */
+    buttons: z.array(QuickReplySchema).max(3).optional(),
+    /**
+     * The template a poll sends when the outcome it must tell has no copy of
+     * its own: it says there is news and asks the person to answer, and states
+     * nothing about the outcome — so it can never be the wrong news. Exactly
+     * one per registry, taking no variables (`npm run check`).
+     */
+    fallback: z.boolean().optional(),
   })
   .strict();
 
@@ -120,12 +155,23 @@ export const TemplateRegistrySchema = z
   .strict()
   .superRefine((registry, ctx) => {
     const seen = new Set<string>();
+    const replyIds = new Set<string>();
     for (const [i, template] of registry.templates.entries()) {
       if (seen.has(template.name)) ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["templates", i, "name"], message: `${template.name} is declared twice` });
       seen.add(template.name);
+      // A tap is resolved by its id alone, so one id means one intent across the whole registry.
+      for (const [j, button] of (template.buttons ?? []).entries()) {
+        if (replyIds.has(button.id)) ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["templates", i, "buttons", j, "id"], message: `reply id ${button.id} is declared twice` });
+        replyIds.add(button.id);
+      }
     }
   });
 
+/** Every quick reply the registry declares, by id: the only taps that can become a turn. */
+export function declaredReplies(templates: readonly WhatsAppTemplate[]): Map<string, QuickReply> {
+  return new Map(templates.flatMap((t) => t.buttons ?? []).map((b) => [b.id, b]));
+}
+
 export type TemplateRegistry = z.infer<typeof TemplateRegistrySchema>;
 
 export function parseTemplateRegistry(text: string): TemplateRegistry {

package/templates/bills-agent/packages/agent-core/src/check.ts

@@ -8,7 +8,7 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { parse as parseYaml } from "yaml";
-import { ConversationScriptSchema, TemplateRegistrySchema, TEMPLATE_REGISTRY_FILE, templateArity } from "./channels.js";
+import { ConversationScriptSchema, TemplateRegistrySchema, TEMPLATE_REGISTRY_FILE, declaredReplies, templateArity, type TemplateRegistry } from "./channels.js";
 import { GuardrailsSchema } from "./guardrails.js";
 import { loadManifest, ManifestSchema, type LoadedManifest } from "./manifest.js";
 import { MandateSchema } from "./mandate.js";
@@ -121,12 +121,35 @@ export function checkAgent(agentDir: string): CheckReport {
   if (!manifest.channels.includes("whatsapp") && scripts.length > 0) {
     error("channels_undeclared", `channels/whatsapp/ ships ${scripts.length} conversation(s) but agent.yaml does not declare the whatsapp channel`);
   }
+  const registryPath = join(whatsappDir, TEMPLATE_REGISTRY_FILE);
+  let registry: TemplateRegistry | undefined;
+  if (existsSync(registryPath)) {
+    const parsed = TemplateRegistrySchema.safeParse(JSON.parse(readFileSync(registryPath, "utf8")));
+    if (parsed.success) registry = parsed.data;
+  }
+  const replies = declaredReplies(registry?.templates ?? []);
   for (const file of scripts) {
     const parsed = ConversationScriptSchema.safeParse(JSON.parse(readFileSync(join(whatsappDir, file), "utf8")));
     if (!parsed.success) error("channels_script_invalid", `channels/whatsapp/${file}: ${parsed.error.message}`);
     else if (parsed.data.name !== file.replace(/\.json$/, "")) error("channels_script_invalid", `channels/whatsapp/${file} declares name ${parsed.data.name}`);
+    else {
+      // A scripted tap must be one a declared template offers: the channel drops any other, so the script would test nothing.
+      for (const turn of parsed.data.turns) {
+        if (turn.reply && !replies.has(turn.reply.id)) error("channels_script_invalid", `channels/whatsapp/${file} taps ${turn.reply.id}, which no template in ${TEMPLATE_REGISTRY_FILE} offers`);
+      }
+    }
+  }
+  // An agent on WhatsApp closes outcomes days later, outside the window, where
+  // only a template goes. One it has no copy for still has to reach the
+  // person, so the registry declares a fallback that states no outcome.
+  if (manifest.channels.includes("whatsapp")) {
+    if (!existsSync(registryPath)) error("channels_templates_missing", `agent.yaml declares the whatsapp channel and channels/whatsapp/${TEMPLATE_REGISTRY_FILE} does not exist`);
+    else if (registry) {
+      const fallbacks = registry.templates.filter((t) => t.fallback);
+      if (fallbacks.length !== 1) error("channels_templates_fallback", `channels/whatsapp/${TEMPLATE_REGISTRY_FILE} declares ${fallbacks.length} fallback template(s); it must declare exactly one, for an outcome the agent has no template for`);
+      else if (templateArity(fallbacks[0]!.body) !== 0) error("channels_templates_fallback", `the fallback template ${fallbacks[0]!.name} takes variables; it is sent when nothing specific can be said, so it takes none`);
+    }
   }
-  const registryPath = join(whatsappDir, TEMPLATE_REGISTRY_FILE);
   if (existsSync(registryPath)) {
     const parsed = TemplateRegistrySchema.safeParse(JSON.parse(readFileSync(registryPath, "utf8")));
     if (!parsed.success) error("channels_templates_invalid", `channels/whatsapp/${TEMPLATE_REGISTRY_FILE}: ${parsed.error.message}`);