@codespar/cli 0.18.1 → 0.20.0

package/templates/checkout-agent/packages/agent-core/src/locale.ts

@@ -0,0 +1,88 @@
+/**
+ * The language of the strings the CODE prints: the approval question, the
+ * batch gesture, the execution lines, the consent summary, the WhatsApp
+ * templates and the refusal details a kit writes. No model writes these.
+ *
+ * It is not the reply language (`language.ts`). That one is read from each
+ * turn the person types and only tells the model how to answer. The locale is
+ * fixed for a run and for a conversation, because the question that proposes
+ * a payment and the question that approves it must not change language
+ * between the two.
+ *
+ * Resolution: `--locale` on the command, else `locale:` in `agent.yaml`, else
+ * `pt-BR`. A conversation a later command comes back to keeps the locale its
+ * bundle recorded.
+ */
+import { z } from "zod";
+
+export const LOCALES = ["pt-BR", "en"] as const;
+export type Locale = (typeof LOCALES)[number];
+export const DEFAULT_LOCALE: Locale = "pt-BR";
+export const LocaleSchema = z.enum(LOCALES);
+
+export function isLocale(value: unknown): value is Locale {
+  return typeof value === "string" && (LOCALES as readonly string[]).includes(value);
+}
+
+/** A `--locale` value, or the error the command prints next to its usage. */
+export function parseLocale(value: string): Locale {
+  if (!isLocale(value)) throw new Error(`--locale must be ${LOCALES.join(" or ")}`);
+  return value;
+}
+
+export function resolveLocale(flag: Locale | undefined, manifest: { locale?: Locale | undefined }): Locale {
+  return flag ?? manifest.locale ?? DEFAULT_LOCALE;
+}
+
+/**
+ * The language code Meta approves a template in. Meta approves a template per
+ * (name, language) pair, so an English conversation sends the `en_US` copy of
+ * a template and never the `pt_BR` one.
+ */
+export const WHATSAPP_LANGUAGE: { readonly [L in Locale]: string } = { "pt-BR": "pt_BR", en: "en_US" };
+
+/** One entry per locale. A table missing a locale does not type-check; a key missing from one entry fails `npm run check`. */
+export type LocaleTable<T> = { readonly [L in Locale]: T };
+
+/**
+ * What differs between the entries of a string table: a key one locale has and
+ * another lacks, a string where the other has a function, or a function that
+ * takes a different number of arguments. Empty means every key exists in every
+ * locale with the same shape. The check reads this at runtime because a kit is
+ * TypeScript that `npm run check` does not compile.
+ */
+export function tableGaps(name: string, table: Partial<Record<Locale, object>>): string[] {
+  const gaps: string[] = [];
+  const entry = (l: Locale) => table[l] as Record<string, unknown> | undefined;
+  for (const locale of LOCALES) if (!entry(locale)) gaps.push(`${name} has no ${locale} entry`);
+  const keys = new Set(LOCALES.flatMap((l) => Object.keys(entry(l) ?? {})));
+  for (const key of [...keys].sort()) {
+    const shapes = LOCALES.map((l) => {
+      const value = entry(l)?.[key];
+      if (value === undefined) return "missing";
+      if (typeof value === "function") return `function/${value.length}`;
+      return typeof value === "string" && value.length > 0 ? "string" : `empty ${typeof value}`;
+    });
+    for (const [i, shape] of shapes.entries()) {
+      if (shape === "missing" || shape.startsWith("empty")) gaps.push(`${name}.${key} is ${shape} in ${LOCALES[i]}`);
+    }
+    if (new Set(shapes.filter((s) => s !== "missing")).size > 1) gaps.push(`${name}.${key} differs in shape across locales: ${LOCALES.map((l, i) => `${l} ${shapes[i]}`).join(", ")}`);
+  }
+  return gaps;
+}
+
+/** `185000` -> `R$ 1.850,00` in pt-BR, `R$1,850.00` in English: the two forms the prompts give the model since #62. */
+export function formatBRL(minor: number, locale: Locale): string {
+  const sign = minor < 0 ? "-" : "";
+  const abs = Math.abs(minor);
+  const cents = String(abs % 100).padStart(2, "0");
+  if (locale === "en") return `${sign}R$${Math.floor(abs / 100).toLocaleString("en-US")}.${cents}`;
+  return `${sign}R$ ${Math.floor(abs / 100).toLocaleString("pt-BR")},${cents}`;
+}
+
+/** `2026-09-30` -> `30/09/2026` in pt-BR; English keeps the ISO date, which reads the same on either side of the Atlantic. */
+export function formatDay(iso: string, locale: Locale): string {
+  if (locale === "en") return iso;
+  const [y, m, d] = iso.split("-");
+  return `${d}/${m}/${y}`;
+}

package/templates/checkout-agent/packages/agent-core/src/manifest.ts

@@ -8,6 +8,7 @@ import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { parse as parseYaml } from "yaml";
 import { z } from "zod";
+import { LocaleSchema } from "./locale.js";
 
 const PINNED_PACKAGE = /^@codespar\/(mcp|cli)@\d+\.\d+\.\d+$/;
 const HOURS_WINDOW = /^([01]\d|2[0-3]):[0-5]\d-([01]\d|2[0-3]):[0-5]\d$/;
@@ -34,12 +35,14 @@ export const ManifestSchema = z
     default_approval: z.enum(["human", "mandate"]),
     escalate_above: EscalateAboveSchema.optional(),
     mcp: z.string().regex(PINNED_PACKAGE, "mcp must pin an exact version, e.g. @codespar/mcp@0.5.8"),
-    cli: z.string().regex(PINNED_PACKAGE, "cli must pin an exact version, e.g. @codespar/cli@0.14.0"),
+    cli: z.string().regex(PINNED_PACKAGE, "cli must pin an exact version, e.g. @codespar/cli@0.18.1"),
     tools: z.string(),
     guardrails: z.string(),
     mandate_schema: z.string(),
     events: z.array(z.string().regex(/^commerce\.[a-z_.]+$/)),
     channels: z.array(z.enum(["terminal", "whatsapp"])).nonempty(),
+    /** The language of the strings the code prints (not of the model's replies). Optional: absent is `pt-BR`, which is what every agent printed before the field existed. */
+    locale: LocaleSchema.optional(),
     maturity: z.record(z.string(), MaturitySchema),
     scenarios: z.string(),
     evals: z.string(),

package/templates/checkout-agent/packages/agent-core/src/rail.ts

@@ -75,7 +75,7 @@ export interface RailPayment {
    * its shape and never its content. A charge rail ignores it.
    */
   approval?: SpendApproval;
-  /** Section 4.5: carried on every call. The API has no wire field for it yet; see OPEN_QUESTIONS. */
+  /** Section 4.5: carried on every call, on the wire as `PaymentActor` (`wireActorOf`) since @codespar/sdk 0.16.10; see OPEN_QUESTIONS §2. */
   actor: Actor;
 }
 
@@ -167,9 +167,37 @@ export interface RailReceipt {
   receipt_sig_kid: string | null;
   /** Section 4.5: the kit stamps the actor onto the local copy of every receipt. */
   actor: Actor;
+  /**
+   * The actor the API RECORDED for the spend and read back (`PaymentActor`,
+   * @codespar/sdk 0.16.10): `null` when it recorded none — an API that did not
+   * take the field, or a spend that sent none. Absent when the rail cannot
+   * say: a charge, which records no actor.
+   */
+  sealed_actor?: WireActor | null;
   raw: unknown;
 }
 
+/**
+ * Who triggered a spend, in the API's own shape (`PaymentActor`,
+ * @codespar/sdk 0.16.10): the agent by its identifier and the consumer it acts
+ * for, or the person by id and the channel they acted from. The kit's `Actor`
+ * names the agent under `agent`; the wire names it under `id`, and that is the
+ * only difference.
+ */
+export type WireActor = { type: "agent"; id: string; on_behalf_of: string } | { type: "human"; id: string; channel?: string };
+
+export function wireActorOf(actor: Actor): WireActor {
+  return actor.type === "agent" ? { type: "agent", id: actor.agent, on_behalf_of: actor.on_behalf_of } : { type: "human", id: actor.id, channel: actor.channel };
+}
+
+/** The same actor, field for field. A human's channel counts: the same person on WhatsApp and on a dashboard are two events. */
+export function sameWireActor(a: WireActor | null, b: WireActor | null): boolean {
+  if (a === null || b === null) return a === b;
+  if (a.type === "agent" && b.type === "agent") return a.id === b.id && a.on_behalf_of === b.on_behalf_of;
+  if (a.type === "human" && b.type === "human") return a.id === b.id && (a.channel ?? null) === (b.channel ?? null);
+  return false;
+}
+
 /** What a reconcile learns: a recorded outcome, "still running", or nothing. Never a new payment. */
 export type RailLookup = RailOutcome | { status: "in_flight" } | undefined;
 

package/templates/checkout-agent/packages/agent-core/src/receipt-verification.ts

@@ -53,7 +53,7 @@
  */
 import { createPublicKey, verify as verifyDetached } from "node:crypto";
 import { itemsHash } from "./hash.js";
-import { readChainRecipe, readSealedApproval, recomputeChain, sameApprovalHash, type SealedApproval } from "./receipt-chain.js";
+import { readChainRecipe, readSealedApproval, recomputeChain, sameApprovalHash, type ChainRecipe, type SealedApproval } from "./receipt-chain.js";
 import type { ExecutionItem } from "./types.js";
 
 /** The domain tag. A receipt names the version it was sealed under through
@@ -123,6 +123,16 @@ export interface ChainCheck {
   reason: string;
 }
 
+/**
+ * Whether the sealed payment was a sandbox one and whether money moved, read off a body that recomputed to the signed chain. A field
+ * is `null` when the recipe's payment link for that version does not seal it: a value the chain does not cover is not reported as one
+ * it does. Only these two, so a verdict never carries the rest of the read (the tenant's read also carries `mandate.sig`).
+ */
+export interface SealedPayment {
+  sandbox: boolean | null;
+  money_moved: boolean | null;
+}
+
 /** What the sealed approval link was held against. Present on a v4 chain that recomputed. */
 export interface ApprovalLinkCheck {
   /** `matched`: the artifact's hashes are the sealed ones. `mismatch`: they are not. `not_compared`: no artifact was given. */
@@ -161,6 +171,8 @@ export interface ReceiptVerification {
   /** The body check, when one was attempted: only `verifyReceiptRead` attempts it, and only on a signature that verified. */
   chain_check?: ChainCheck;
   approval_check?: ApprovalLinkCheck;
+  /** Present exactly when the body recomputed to the signed chain. */
+  sealed_payment?: SealedPayment;
 }
 
 /** One published key, RFC 8037 shape, as the JWKS serves it. */
@@ -531,12 +543,13 @@ export function verifyReceiptRead(read: unknown, keyDocument: unknown, options:
     };
   }
   const chainCheck: ChainCheck = { status: "recomputed", version: recomputed.version, recomputed: recomputed.chain, reason: "body_recomputes" };
+  const sealedPayment = sealedPaymentOf(read, recipe.recipe, recomputed.version);
   const bound = `the body recomputes to the signed chain under the published recipe (v${recomputed.version})`;
 
   const sealed = readSealedApproval(read);
   if (!sealed) {
     // Unreachable through the published recipe (v4 seals the link, and a read without it fails the recomputation above), kept so a future version is not misread.
-    return { ...signature, reason: "body_recomputes", message: `receipt ${signature.receipt_id} was sealed by CodeSpar and ${bound}; it seals no approval link`, chain_check: chainCheck };
+    return { ...signature, reason: "body_recomputes", message: `receipt ${signature.receipt_id} was sealed by CodeSpar and ${bound}; it seals no approval link`, chain_check: chainCheck, sealed_payment: sealedPayment };
   }
   const approval = options.approval;
   if (!approval) {
@@ -546,6 +559,7 @@ export function verifyReceiptRead(read: unknown, keyDocument: unknown, options:
       message: `receipt ${signature.receipt_id} was sealed by CodeSpar and ${bound}. It seals the approval ${sealed.items_hash}${sealed.batch_hash ? ` (batch ${sealed.batch_hash})` : ""}; no approval artifact was given to hold it against`,
       chain_check: chainCheck,
       approval_check: { status: "not_compared", sealed, artifact: null, reason: "no_artifact" },
+      sealed_payment: sealedPayment,
     };
   }
 
@@ -557,6 +571,7 @@ export function verifyReceiptRead(read: unknown, keyDocument: unknown, options:
     message: `receipt ${signature.receipt_id} was sealed by CodeSpar and ${bound}, and ${why}: this payment was not sealed against the list artifact ${approval.approval_id} approved`,
     chain_check: chainCheck,
     approval_check: { status: "mismatch", sealed, artifact, reason },
+    sealed_payment: sealedPayment,
   });
   if (approval.items && itemsHash(approval.items) !== approval.items_hash) {
     return mismatch("artifact_items_hash_inconsistent", `the artifact's items_hash ${approval.items_hash} is not the hash of the items it lists (${itemsHash(approval.items)})`);
@@ -573,5 +588,18 @@ export function verifyReceiptRead(read: unknown, keyDocument: unknown, options:
     message: `receipt ${signature.receipt_id} was sealed by CodeSpar, ${bound}, and it was paid against the list artifact ${approval.approval_id} approved (${sealed.items_hash}${sealed.batch_hash ? `, batch ${sealed.batch_hash}` : ""}). WHO approved it is in the artifact, under a local key, and nowhere in the seal`,
     chain_check: chainCheck,
     approval_check: { status: "matched", sealed, artifact, reason: "approval_matches" },
+    sealed_payment: sealedPayment,
+  };
+}
+
+function sealedPaymentOf(read: Record<string, unknown>, recipe: ChainRecipe, version: number): SealedPayment {
+  const spec = recipe.links.find((l) => l.from === "payment");
+  const fields = spec?.fields ?? spec?.fields_by_version?.[String(version)] ?? [];
+  const payment = read["payment"];
+  const pick = (name: string): boolean | null => {
+    if (!fields.includes(name) && !fields.includes(`${name}${recipe.optional_marker}`)) return null;
+    const value = isRecord(payment) ? payment[name] : undefined;
+    return typeof value === "boolean" ? value : null;
   };
+  return { sandbox: pick("sandbox"), money_moved: pick("money_moved") };
 }

package/templates/checkout-agent/packages/agent-core/src/secrets.ts

@@ -1,26 +1,71 @@
 /**
  * Sandbox by construction: a key outside the `csk_test_` pattern fails
  * before any network call. Nothing in this repository ever holds a live key.
+ *
+ * Three different mistakes land here and each has its own fix, so each has
+ * its own message (#50): no key at all (the `.env` was never copied, or sits
+ * where the agent does not read it), the `.env.example` placeholder left in
+ * place, and a key that is not a test key. Telling a newcomer who has no key
+ * that their key is LIVE sends them looking for the wrong thing.
  */
 export const TEST_KEY_PREFIX = "csk_test_";
 
+/** The value `.env.example` ships with. It has the test prefix and is nobody's key. */
+export const CODESPAR_KEY_PLACEHOLDER = "csk_test_your_key_here";
+
+/** Why a `CODESPAR_API_KEY` cannot be used: absent or empty, the placeholder, or not a test key. */
+export type TestKeyProblem = "missing" | "placeholder" | "not_test";
+
+export function testKeyProblem(key: string | undefined): TestKeyProblem | undefined {
+  const value = key?.trim() ?? "";
+  if (value === "") return "missing";
+  if (value === CODESPAR_KEY_PLACEHOLDER) return "placeholder";
+  if (!value.startsWith(TEST_KEY_PREFIX) || value.length <= TEST_KEY_PREFIX.length) return "not_test";
+  return undefined;
+}
+
+/**
+ * `envFile` is the `.env` the agent actually reads, as the runner resolves it
+ * (`agents/<agent>/.env`, relative to where the command ran). The core does
+ * not know which agent it runs for, so without it the message names the
+ * pattern instead of the path.
+ */
+export function testKeyMessage(problem: TestKeyProblem, envFile?: string): string {
+  const file = envFile ?? "agents/<agent>/.env";
+  switch (problem) {
+    case "missing":
+      return (
+        `CODESPAR_API_KEY is not set: copy ${file}.example to ${file} and paste a ${TEST_KEY_PREFIX} key from https://codespar.dev/auth/signup. ` +
+        `${file} is the file this agent reads; a .env anywhere else, the repository root included, is not read.`
+      );
+    case "placeholder":
+      return `CODESPAR_API_KEY is still the placeholder from .env.example (${CODESPAR_KEY_PLACEHOLDER}): replace it in ${file} with your own ${TEST_KEY_PREFIX} key from https://codespar.dev/auth/signup.`;
+    case "not_test":
+      return (
+        `CODESPAR_API_KEY must be a test key (prefix "${TEST_KEY_PREFIX}"). ` +
+        `This kit runs in the sandbox only; a live key is refused before any call is made. It is read from the environment, or from ${file}.`
+      );
+  }
+}
+
 export class NotATestKeyError extends Error {
-  constructor() {
-    super(
-      `CODESPAR_API_KEY must be a test key (prefix "${TEST_KEY_PREFIX}"). ` +
-        "This kit runs in the sandbox only; a live key is refused before any call is made.",
-    );
+  constructor(
+    readonly problem: TestKeyProblem = "not_test",
+    readonly envFile?: string,
+  ) {
+    super(testKeyMessage(problem, envFile));
     this.name = "NotATestKeyError";
   }
 }
 
 export function isTestKey(key: string | undefined): key is string {
-  return typeof key === "string" && key.startsWith(TEST_KEY_PREFIX) && key.length > TEST_KEY_PREFIX.length;
+  return testKeyProblem(key) === undefined;
 }
 
 export function assertTestKey(key: string | undefined): string {
-  if (!isTestKey(key)) throw new NotATestKeyError();
-  return key;
+  const problem = testKeyProblem(key);
+  if (problem) throw new NotATestKeyError(problem);
+  return key!.trim();
 }
 
 /** For logs and bundles: the prefix and the last four characters, nothing else. */

package/templates/checkout-agent/packages/agent-core/src/state-machine.ts

@@ -62,6 +62,13 @@ export interface TransitionRecord {
   actor: Actor;
 }
 
+/** The code and message a rail answered for one attempt, as the rail gave them. */
+export interface RailAnswer {
+  attempt_id: string;
+  code: string;
+  message: string;
+}
+
 export interface Execution<S extends ExecutionState = ExecutionState> {
   id: string;
   run_id: string;
@@ -97,6 +104,13 @@ export interface Execution<S extends ExecutionState = ExecutionState> {
   reason?: ExecutionReason;
   detail?: string;
   outcomes: ItemOutcome[];
+  /**
+   * What the rail answered, verbatim, for attempts whose outcome it left
+   * UNKNOWN (a timeout, a 5xx such as `provider_error`): no outcome exists for
+   * them, so their code and message would otherwise live only in the event
+   * log. An entry whose attempt later gains an outcome is superseded by it.
+   */
+  uncertain_answers?: RailAnswer[];
   history: TransitionRecord[];
   created_at: string;
   updated_at: string;

package/templates/checkout-agent/packages/agent-core/src/strings.ts

@@ -0,0 +1,175 @@
+/**
+ * The strings every agent shares, in each locale: the approval path's lines
+ * (the batch gesture, the per-line question's hint, the waits), the words of
+ * an execution's description, how a payable instrument is shown, and the
+ * operator's lines on the WhatsApp channel. A kit's own words are in its
+ * kit's `strings`.
+ *
+ * DISPLAY ONLY. What a person may ANSWER is not here and does not depend on
+ * the locale: `[s/N]` takes s, sim, y and yes in both, and the batch gesture
+ * takes todas / all, todas exceto / all except, nenhuma / none in both
+ * (`parseBatchGesture`). A prompt shown in English and answered in Portuguese
+ * decides exactly what the same answer decides under a Portuguese prompt.
+ */
+import type { LocaleTable } from "./locale.js";
+
+const pt = {
+  // How an execution reads on the console.
+  execution: "execução",
+  totalByCore: "total (calculado pelo core)",
+  escalatedBy: "escalado por",
+  blocked: (reasons: string, notAuthorized: string) => `bloqueado: ${reasons} — ${notAuthorized}; não há o que aprovar`,
+  replayedSettlement: "já estava pago: a API respondeu com um pagamento anterior desta mesma tentativa; esta execução não moveu dinheiro",
+
+  // The approval path at the keyboard.
+  onlyDeny: "  (o único desfecho possível é negar; aperte Enter)",
+  leftAwaiting: "  deixado em awaiting_approval (rode de novo com --approve ou --deny)",
+  afterLooks: (rounds: number, seconds: number, timedOut: boolean) =>
+    ` após ${rounds} consulta(s), ${seconds}s${timedOut ? " (tempo esgotado; `npm run poll` continua de onde parou)" : ""}`,
+  banner: (name: string, version: string, mode: string, rail: string, mandateWord: string, mandateId: string) => `${name} ${version} — approval: ${mode} — trilho: ${rail} — ${mandateWord} ${mandateId}`,
+  bundleAt: (runId: string, dir: string) => `run ${runId} — bundle em ${dir}`,
+
+  // The batch gesture: one question for a whole list.
+  batchHeader: (ref: string, label: string, count: number, total: string, hash: string) => `  lote ${ref} — ${label}: ${count} linha(s), total ${total}, batch_hash ${hash}…`,
+  batchAlreadySettled: " (já paga; não roda de novo)",
+  batchInProgress: " (em andamento; não roda de novo)",
+  batchAttemptConflict: " (tentativa presa a outro pagamento; não roda de novo)",
+  batchQuestion: "  Aprovar a lista? [todas / todas exceto 3,7 / nenhuma] ",
+  batchUnreadable: (count: number) => `  não entendi; responda todas, todas exceto <números de 1 a ${count}> ou nenhuma`,
+  batchApprovedAll: "  -> lista aprovada inteira",
+  batchDeniedAll: "  -> lista negada inteira",
+  batchApprovedExcept: (positions: string) => `  -> lista aprovada exceto ${positions}`,
+
+  // A payable instrument, on the terminal and on WhatsApp.
+  instalmentOf: (instalment: number, count: number) => `Parcela ${instalment}/${count}: `,
+  dueOn: (date: string) => `, vence ${date}`,
+  chargeRef: (chargeId: string) => ` — cobrança ${chargeId}`,
+  pixCopyPaste: "Pix copia e cola:",
+  boletoLine: "Ou pelo boleto, linha digitável:",
+
+  // The collection-hours rule: the envelope refuses to draft outside it, the channel refuses to speak.
+  outsideCollectionHours: (window: string, timezone: string, clock: string) => `fora do horário de cobrança (${window} ${timezone}); agora são ${clock}`,
+
+  // The scenario runner.
+  scenarioReply: (text: string) => `agente: ${text}`,
+  scenarioOk: (cycleSeconds: number | null | undefined, dir: string) =>
+    `== ok — ${cycleSeconds === undefined ? "" : cycleSeconds === null ? "sem ciclo medido — " : `${cycleSeconds}s — `}bundle em ${dir}`,
+
+  // The WhatsApp channel, on the operator's console. None of these reach the person.
+  waBanner: (name: string, version: string, backend: string, mode: string, rail: string, mandateWord: string, mandateId: string) =>
+    `${name} ${version} — canal: whatsapp (${backend}) — approval: ${mode} — trilho: ${rail} — ${mandateWord} ${mandateId}`,
+  waTapIgnored: (rule: string, detail: string) => `  [whatsapp] toque ignorado (${rule}): ${detail}`,
+  waRefused: (rule: string, detail: string) => `  [whatsapp] recusado (${rule}): ${detail}`,
+  waRefusedByBackend: (rule: string, detail: string) => `  [whatsapp] recusado pelo backend (${rule}): ${detail}`,
+  waDeliveryFailed: (messageId: string, codes: string, told: string | undefined) =>
+    `  [operador] ENTREGA FALHOU da mensagem ${messageId} (${codes})${told ? ` — era o aviso de ${told}: a pessoa NÃO foi avisada` : ""}`,
+  waShop: "loja:",
+  waTap: (title: string) => `[toque: ${title}]`,
+  waTapIgnoredMark: (rule: string) => ` (ignorado: ${rule})`,
+  waNotSent: (rule: string) => `(não enviada: ${rule})`,
+  waCopyPaste: "[copia e cola]",
+  waQrImage: "[imagem: QR Pix]",
+  waYou: "  │ você> ",
+  waEmulatorOpen: "  ┌─ WhatsApp (dyvit-wa-sim, emulador local da Cloud API — sem rede externa, sem conta Meta)",
+  waEmulatorClosed: "  └─ fim da conversa",
+  waConversationSummary: (log: string, received: number | undefined, sent: number, refused: number) =>
+    `conversa em ${log} — ${received === undefined ? "" : `${received} recebida(s), `}${sent} enviada(s)${refused ? `, ${refused} recusada(s)` : ""}`,
+  waSimulatedCost: (total: string, currency: string) => `custo simulado desta conversa nas regras da Meta: ${total} ${currency} (conta do emulador, não nossa)`,
+
+  // `poll --channel whatsapp`.
+  pollNoSubject: (conversation: string) =>
+    `a conversa ${conversation} não declara subject: não dá para dizer quais execuções são dela, e mandar o desfecho de outra pessoa nesta conversa é exatamente o que a regra de sigilo proíbe`,
+  pollNothingWaiting: (conversation: string) => `nada aguardando pagador em ${conversation}`,
+  pollLocaleConflict: (conversation: string, recorded: string, asked: string) =>
+    `a conversa ${conversation} foi registrada em ${recorded}; um poll continua a conversa no idioma em que ela começou, e --locale ${asked} a mudaria no meio`,
+  pollNoBundle: (runIds: string) => `nenhum bundle encontrado para ${runIds}: a conversa não pode ser retomada sem o registro dela`,
+  pollBanner: (name: string, version: string, backend: string, conversation: string, openMinutes: number | undefined) =>
+    `${name} ${version} — poll no canal whatsapp (${backend}) — conversa ${conversation} — janela de 24h ${openMinutes === undefined ? "FECHADA: só template aprovado" : `ABERTA (${openMinutes} min restantes): mensagem livre`}`,
+  pollToldByText: "avisado por mensagem livre",
+  pollToldByTemplate: (template: string, fallback: boolean) => `avisado por template ${template}${fallback ? " (reserva: o kit não tem cópia para este desfecho)" : ""}`,
+  pollNotTold: (reason: string, detail: string | undefined) => `não avisado (${reason}${detail ? `: ${detail}` : ""})`,
+  pollNoTemplateForOutcome: (outcome: string) => `a janela de 24h está fechada e o agente não declara template para ${outcome}, nem um template de reserva`,
+  pollTemplateNotDeclared: (template: string) => `o kit pediu o template ${template}, que channels/whatsapp/templates.json não declara`,
+  pollProviderRefused: "o provedor não aceitou a mensagem",
+
+  // What a run did, counted from its executions: printed after the reply, whatever the reply says.
+  runOutcome: (settled: number, failed: number, declined: number, alreadyPaid: number, open: number) =>
+    settled + failed + declined + alreadyPaid + open === 0
+      ? "resultado deste run: nenhuma execução; nada foi pago"
+      : `resultado deste run: ${settled} liquidada(s), ${failed} com falha ou recusada(s), ${declined} negada(s) ou expirada(s), ${alreadyPaid} pulada(s) por já paga(s), ${open} em aberto`,
+};
+
+export type CoreStrings = typeof pt;
+
+const en: CoreStrings = {
+  execution: "execution",
+  totalByCore: "total (computed by the core)",
+  escalatedBy: "escalated by",
+  blocked: (reasons, notAuthorized) => `blocked: ${reasons} — ${notAuthorized}; there is nothing to approve`,
+  replayedSettlement: "already paid: the API answered with an earlier payment of this same attempt; this execution moved no money",
+
+  onlyDeny: "  (the only possible outcome is to deny; press Enter)",
+  leftAwaiting: "  left in awaiting_approval (run again with --approve or --deny)",
+  afterLooks: (rounds, seconds, timedOut) => ` after ${rounds} look(s), ${seconds}s${timedOut ? " (timed out; `npm run poll` picks up where this stopped)" : ""}`,
+  banner: (name, version, mode, rail, mandateWord, mandateId) => `${name} ${version} — approval: ${mode} — rail: ${rail} — ${mandateWord} ${mandateId}`,
+  bundleAt: (runId, dir) => `run ${runId} — bundle in ${dir}`,
+
+  batchHeader: (ref, label, count, total, hash) => `  batch ${ref} — ${label}: ${count} line(s), total ${total}, batch_hash ${hash}…`,
+  batchAlreadySettled: " (already paid; does not run again)",
+  batchInProgress: " (in progress; does not run again)",
+  batchAttemptConflict: " (attempt bound to another payment; does not run again)",
+  batchQuestion: "  Approve the list? [all / all except 3,7 / none] ",
+  batchUnreadable: (count) => `  I did not understand; answer all, all except <numbers from 1 to ${count}> or none`,
+  batchApprovedAll: "  -> list approved in full",
+  batchDeniedAll: "  -> list denied in full",
+  batchApprovedExcept: (positions) => `  -> list approved except ${positions}`,
+
+  instalmentOf: (instalment, count) => `Instalment ${instalment}/${count}: `,
+  dueOn: (date) => `, due ${date}`,
+  chargeRef: (chargeId) => ` — charge ${chargeId}`,
+  pixCopyPaste: "Pix copy and paste:",
+  boletoLine: "Or pay the boleto with this line:",
+
+  outsideCollectionHours: (window, timezone, clock) => `outside collection hours (${window} ${timezone}); it is ${clock} now`,
+
+  scenarioReply: (text) => `agent: ${text}`,
+  scenarioOk: (cycleSeconds, dir) => `== ok — ${cycleSeconds === undefined ? "" : cycleSeconds === null ? "no cycle measured — " : `${cycleSeconds}s — `}bundle in ${dir}`,
+
+  waBanner: (name, version, backend, mode, rail, mandateWord, mandateId) => `${name} ${version} — channel: whatsapp (${backend}) — approval: ${mode} — rail: ${rail} — ${mandateWord} ${mandateId}`,
+  waTapIgnored: (rule, detail) => `  [whatsapp] tap ignored (${rule}): ${detail}`,
+  waRefused: (rule, detail) => `  [whatsapp] refused (${rule}): ${detail}`,
+  waRefusedByBackend: (rule, detail) => `  [whatsapp] refused by the backend (${rule}): ${detail}`,
+  waDeliveryFailed: (messageId, codes, told) => `  [operator] DELIVERY FAILED for message ${messageId} (${codes})${told ? ` — it told ${told}: the person was NOT told` : ""}`,
+  waShop: "shop:",
+  waTap: (title) => `[tap: ${title}]`,
+  waTapIgnoredMark: (rule) => ` (ignored: ${rule})`,
+  waNotSent: (rule) => `(not sent: ${rule})`,
+  waCopyPaste: "[copy and paste]",
+  waQrImage: "[image: Pix QR]",
+  waYou: "  │ you> ",
+  waEmulatorOpen: "  ┌─ WhatsApp (dyvit-wa-sim, a local Cloud API emulator — no external network, no Meta account)",
+  waEmulatorClosed: "  └─ end of conversation",
+  waConversationSummary: (log, received, sent, refused) => `conversation in ${log} — ${received === undefined ? "" : `${received} received, `}${sent} sent${refused ? `, ${refused} refused` : ""}`,
+  waSimulatedCost: (total, currency) => `simulated cost of this conversation under Meta's rules: ${total} ${currency} (the emulator's figure, not ours)`,
+
+  pollNoSubject: (conversation) =>
+    `conversation ${conversation} declares no subject: there is no telling which executions are its own, and sending somebody else's outcome into this conversation is exactly what the secrecy rule forbids`,
+  pollNothingWaiting: (conversation) => `nothing waiting for a payer in ${conversation}`,
+  pollLocaleConflict: (conversation, recorded, asked) => `conversation ${conversation} was recorded in ${recorded}; a poll continues a conversation in the language it started in, and --locale ${asked} would switch it midway`,
+  pollNoBundle: (runIds) => `no bundle found for ${runIds}: the conversation cannot be resumed without its record`,
+  pollBanner: (name, version, backend, conversation, openMinutes) =>
+    `${name} ${version} — poll on the whatsapp channel (${backend}) — conversation ${conversation} — 24h window ${openMinutes === undefined ? "SHUT: approved template only" : `OPEN (${openMinutes} min left): free-form message`}`,
+  pollToldByText: "told by free-form message",
+  pollToldByTemplate: (template, fallback) => `told by template ${template}${fallback ? " (fallback: the kit has no copy for this outcome)" : ""}`,
+  pollNotTold: (reason, detail) => `not told (${reason}${detail ? `: ${detail}` : ""})`,
+  pollNoTemplateForOutcome: (outcome) => `the 24h window is shut and the agent declares no template for ${outcome}, nor a fallback template`,
+  pollTemplateNotDeclared: (template) => `the kit asked for template ${template}, which channels/whatsapp/templates.json does not declare`,
+  pollProviderRefused: "the provider did not accept the message",
+
+  runOutcome: (settled, failed, declined, alreadyPaid, open) =>
+    settled + failed + declined + alreadyPaid + open === 0
+      ? "result of this run: no execution; nothing was paid"
+      : `result of this run: ${settled} settled, ${failed} failed or refused, ${declined} denied or expired, ${alreadyPaid} skipped as already paid, ${open} open`,
+};
+
+export const CORE_STRINGS: LocaleTable<CoreStrings> = { "pt-BR": pt, en };

package/templates/checkout-agent/packages/agent-core/src/stubs/charge-rail.ts

@@ -6,7 +6,7 @@
  * "the charge was issued" finds it again on `resume`.
  *
  * The fixture payer lives in the lookups: the first look after issuance
- * finds the instrument registered (a cobranca com vencimento answers
+ * finds the instrument registered (a cobrança com vencimento answers
  * PROCESSING at create and PENDING once the clearing house has it), the
  * second look finds what the payer did: paid (default), let it expire, or
  * nothing yet. With a real key the scenario runner calls the sandbox pay
@@ -29,6 +29,13 @@ export interface StubChargeRailOptions {
   uncertainOnce?: string[];
   /** Test hook: called after the issuance is persisted and before the outcome is returned. */
   afterDispatch?: (attemptId: string) => void;
+  /** Debtor documents whose registration the issuer ends in `ERROR` at the first look: no instrument, ever (staging, 2026-09-27, OPEN_QUESTIONS §63). */
+  issuerErrorPayees?: string[];
+  /**
+   * Debtor documents whose charge never becomes payable and is settled anyway at the second look: what the API's test
+   * pay route did to a charge in `ERROR` on staging (ent#1816). Here so the scenario gate can be shown refusing it.
+   */
+  settlesUnpayablePayees?: string[];
 }
 
 interface PayerState {
@@ -100,8 +107,14 @@ export class StubChargeRail implements PaymentRail {
     const looks = state.looks + 1;
     this.savePayerState(attemptId, { ...state, looks });
 
+    if (this.options.issuerErrorPayees?.includes(payment.payee)) {
+      const failed: RailOutcome = { status: "failed", code: "charge_issuer_error", message: `stub: the issuer ended charge ${outcome.transaction_id}'s registration in ERROR: no Pix, no boleto, nothing a payer can pay`, raw: { stub: true } };
+      this.replace(attemptId, payment, failed);
+      return failed;
+    }
+    if (this.options.settlesUnpayablePayees?.includes(payment.payee) && looks === 1) return this.update(attemptId, payment, "PROCESSING", false);
     // First look: the clearing house registered the instrument. It is payable from here.
-    if (looks === 1 || !outcome.instrument.payable) {
+    if ((looks === 1 || !outcome.instrument.payable) && !this.options.settlesUnpayablePayees?.includes(payment.payee)) {
       return this.update(attemptId, payment, "PENDING", true);
     }
     if (state.fate === "pays") {

package/templates/checkout-agent/packages/agent-core/src/stubs/rail.ts

@@ -12,7 +12,7 @@
  */
 import { canonicalJson, sha256Hex } from "../hash.js";
 import { checkQuote } from "../quote.js";
-import { checkSpendApproval, type PaymentRail, type RailLookup, type RailOutcome, type RailPayment, type RailReceipt } from "../rail.js";
+import { checkSpendApproval, wireActorOf, type PaymentRail, type RailLookup, type RailOutcome, type RailPayment, type RailReceipt, type WireActor } from "../rail.js";
 import type { StateStore } from "../state/store.js";
 import type { Actor } from "../types.js";
 
@@ -98,9 +98,11 @@ export class StubRail implements PaymentRail {
     if (!quoted.ok) return { status: "failed", code: quoted.code, message: `${quoted.detail}; nothing was sent` };
     const approval = checkSpendApproval(payment);
     if (!approval.ok) return { status: "failed", code: approval.code, message: `${approval.detail}; nothing was sent` };
-    const { actor: _actor, ...request } = payment;
+    const { actor, ...asked } = payment;
+    // Like the API: the actor the spend declared is recorded with it and read back on the receipt, and is not part of the attempt tuple.
+    const request = { ...asked, sealed_actor: wireActorOf(actor) };
     const existing = this.store.stubRailGet(payment.attempt_id);
-    if (existing) return this.repeat(payment.attempt_id, existing.request as Omit<RailPayment, "actor">, existing.outcome as Recorded, request);
+    if (existing) return this.repeat(payment.attempt_id, existing.request as Omit<RailPayment, "actor">, existing.outcome as Recorded, asked);
 
     const uncertainPayee = this.options.uncertainPayees?.includes(payment.payee) === true && !this.uncertainAnswered.has(payment.attempt_id);
     if (this.uncertainArmed || this.uncertainPending.has(payment.attempt_id) || uncertainPayee) {
@@ -169,7 +171,7 @@ export class StubRail implements PaymentRail {
   async receipt(receiptId: string, actor: Actor): Promise<RailReceipt | undefined> {
     const sealed = this.store.stubRailFindByReceipt(receiptId);
     if (!sealed) return undefined;
-    const req = sealed.request as Omit<RailPayment, "actor">;
+    const req = sealed.request as Omit<RailPayment, "actor"> & { sealed_actor?: WireActor };
     const out = sealed.outcome as Extract<RailOutcome, { status: "settled" }>;
     // Like the API: the payee on the receipt is the one the quote sealed, and none when the spend carried no quote.
     const body = {
@@ -192,6 +194,7 @@ export class StubRail implements PaymentRail {
       receipt_sig_ed25519: null,
       receipt_sig_kid: null,
       actor,
+      sealed_actor: req.sealed_actor ?? null,
       raw: { stub: true, transaction_id: out.transaction_id },
     };
   }

package/templates/checkout-agent/packages/agent-core/src/types.ts

@@ -122,6 +122,11 @@ export type ExecutionReason =
   | "awaiting_settlement"
   | "charge_expired"
   | "charge_cancelled"
+  /**
+   * The issuer ended the receivable's registration in an error state (`ERROR`): no Pix, no boleto, nothing a payer can
+   * pay, and nothing will be. Terminal, and nothing was collected. Measured on staging on 2026-09-27 (OPEN_QUESTIONS §63).
+   */
+  | "charge_issuer_error"
   /**
    * An ISSUED receivable whose read now answers that its reference matches more than one charge. Terminal for the
    * execution, but not "nothing moved": the charge exists and may still be paid. Reconcile it by the charge id; never
@@ -166,16 +171,24 @@ export interface ItemOutcome {
   transaction_id?: string;
   /** The rail's code on a failed outcome (`charge_expired`, `charge_cancelled`, a provider code). */
   code?: string;
+  /** The rail's own message on a failed outcome, verbatim: for the CodeSpar rail, the API's `error.message`. */
+  message?: string;
   /** A failed outcome because the attempt id is held for another payment or another project (`RailOutcome.held`). */
   held?: "conflict" | "unavailable";
-  /** A settled outcome the rail answered from its record of an earlier presentation (`RailOutcome.replayed`). */
+  /**
+   * A settled outcome the rail answered, at dispatch, from its record of an
+   * earlier presentation (`RailOutcome.replayed`): the first time THIS
+   * execution presented the attempt, it was already paid, so this execution
+   * moved nothing for it. Never set by reconcile, whose lookup re-presents an
+   * attempt this execution already sent and cannot tell whose payment it reads.
+   */
   replayed?: true;
   error?: string;
   /** What the payer is shown for an accepted receivable, as the rail handed it back. Presentation only; nothing here decides money. */
   instrument?: ChargeInstrument;
 }
 
-/** The payable legs of a receivable. Null until the issuer registers the instrument (a cobranca com vencimento answers PROCESSING first). */
+/** The payable legs of a receivable. Null until the issuer registers the instrument (a cobrança com vencimento answers PROCESSING first). */
 export interface ChargeInstrument {
   payable: boolean;
   pix_copy_paste: string | null;