@codespar/cli 0.18.1 → 0.20.0

package/templates/bills-agent/packages/agent-runtime/src/commands/verify.ts

@@ -18,12 +18,17 @@
  * party, payee unmasked; checked with no credential at all — or a copy from a
  * run's `runs/<run-id>/receipts/`, which masks the payee and carries none of
  * the links. A copy reaches check 2 only with `--from-api`: the tenant's
- * `CODESPAR_API_KEY` (the environment, or the `.env` of the agent the copy
- * sits in) reads the receipt from the API, in memory, and nothing unmasked is
+ * `CODESPAR_API_KEY`, against the deployment `CODESPAR_API_URL` names (each
+ * from the environment, or else from the `.env` of the agent the copy sits
+ * in), reads the receipt from the API, in memory, and nothing unmasked is
  * written anywhere. Without it a copy answers `signature_only`, which is the
  * truth about what a masked copy can prove. The approval artifact of a copy
  * is the one its `approval_id` names in the run's own `approval.json`.
  *
+ * Of the read, the output carries only `sealed_payment` (`sandbox`,
+ * `money_moved`) off a body that bound. The tenant's read still carries
+ * `mandate.sig`, a spend credential, and it is never printed.
+ *
  * It is the one command here that does NOT need an agent — `cli.ts`
  * dispatches it before it looks for an `agent.yaml` — because the file it
  * reads has usually been copied off the machine that produced it.
@@ -40,6 +45,7 @@ import { stderr, stdout } from "node:process";
 import {
   DEFAULT_BASE_URL,
   DEFAULT_RECEIPT_KEYS_URL,
+  NotATestKeyError,
   VERDICT_EXIT_CODES,
   copyDisagreesWithRead,
   createCodeSparClient,
@@ -55,7 +61,8 @@ import {
   type ReceiptVerification,
 } from "@codespar/agent-core";
 import { findAgentDir } from "../agent.js";
-import { readDotEnv } from "../setup.js";
+import { readAgentEnv } from "../env.js";
+import { envFileOf } from "../setup.js";
 
 const USAGE =
   "usage: npm run verify <receipt-file> [--json] [--keys <key-set.json> | --url <https://.../.well-known/codespar-receipt-keys.json>] [--approval <approval.json> [--approval-id <apr_...>]] [--from-api]";
@@ -109,7 +116,7 @@ export async function verify(argv: string[]): Promise<number> {
       say(`the key set is public and needs no credential; its default is ${DEFAULT_RECEIPT_KEYS_URL}`);
       say("--keys reads a saved copy of that document instead, so the check runs with no network at all");
       say("the receipt file is the API's read (GET /v1/consumers/receipts/{id}), whose body is recomputed against the signed chain, or a run's copy, which proves the signature only");
-      say("--from-api reads a run's copy from the API with CODESPAR_API_KEY (in memory, nothing written), so its body and its approval are checked too; the key set then defaults to that deployment's");
+      say("--from-api reads a run's copy from the API with CODESPAR_API_KEY (in memory, nothing written), so its body and its approval are checked too; the key set then defaults to that deployment's. CODESPAR_API_KEY and CODESPAR_API_URL come from the environment, or else from the .env of the agent the copy sits in; the CodeSpar CLI's name CODESPAR_BASE_URL is read too, and the two must agree");
       say("--approval holds a v4 receipt's sealed approval link against an approval artifact (a run's copy uses its own approval.json)");
       return 0;
     } else if (a.startsWith("-")) {
@@ -139,6 +146,20 @@ export async function verify(argv: string[]): Promise<number> {
   const receipt = readJson(args.receiptFile, say);
   if (receipt === undefined) return 2;
 
+  // Before the deployment is chosen, not only before the key is read: a
+  // staging key in that `.env` sits next to the staging URL, and a read sent
+  // to production with it is a 401 (#66). Only `--from-api` touches it; the
+  // other paths are the verifier who holds nothing.
+  const agentDir = args.fromApi ? findAgentDir(dirname(resolve(args.receiptFile))) : undefined;
+  // `--from-api` is also the one path that reads the deployment and the project, so it is the one that reconciles the CLI's names for them; a check against `--keys` or the default key set holds no opinion on either. Two names that disagree are a usage error (2), never 1: 1 means the receipt does not verify.
+  if (args.fromApi) {
+    const disagreement = readAgentEnv(agentDir);
+    if (disagreement) {
+      say(`${disagreement.message}\n${USAGE}`);
+      return 2;
+    }
+  }
+
   // The read and the key set must come from ONE deployment: the recipe that
   // binds the body is the key document's, and a staging read checked under
   // production's document is the §47 trap again.
@@ -161,14 +182,14 @@ export async function verify(argv: string[]): Promise<number> {
     if (keysDocument === undefined) return 2;
   }
 
-  const report = await check(receipt, args, apiBase, approval, keysDocument);
+  const report = await check(receipt, args, apiBase, agentDir, approval, keysDocument);
   if (args.json) stdout.write(JSON.stringify(report) + "\n");
   else stdout.write(render(report));
   say(report.message);
   return VERDICT_EXIT_CODES[report.verdict];
 }
 
-async function check(receipt: unknown, args: Args, apiBase: string, approval: ApprovalClaim | undefined, keysDocument: unknown): Promise<ReceiptVerification> {
+async function check(receipt: unknown, args: Args, apiBase: string, agentDir: string | undefined, approval: ApprovalClaim | undefined, keysDocument: unknown): Promise<ReceiptVerification> {
   // Answered before the network is touched, as before: an unsigned or
   // malformed file needs no key set, and fetching one to check a signature
   // that is not there would turn an offline answer into an outage.
@@ -202,7 +223,7 @@ async function check(receipt: unknown, args: Args, apiBase: string, approval: Ap
     return signatureOnly(signature, "read_required", "this is a run's copy, which masks the payee and carries none of the chain's links. Recompute from the API's read: run this again with --from-api (the tenant's key, read-only, nothing written), or verify the read itself");
   }
 
-  const read = await readFromApi(signed.fields.receipt_id, args.receiptFile!, apiBase);
+  const read = await readFromApi(signed.fields.receipt_id, apiBase, agentDir);
   if (!read.ok) return signatureOnly(signature, "read_unavailable", `the API's read of it could not be fetched (${read.detail}), so nothing is proved and nothing is disproved about the body`);
   const differs = copyDisagreesWithRead(receipt as Record<string, unknown>, read.body);
   if (differs.includes("chain")) {
@@ -229,18 +250,18 @@ function unreachable(receiptId: string, label: string, message: string): Receipt
 /**
  * The receipt as the API reads it, for a copy, with the tenant's key. The key
  * is the environment's, or the `.env` of the agent the copy sits in — the
- * same place `npm start` reads it from — and only a `csk_test_` key is
- * accepted, like everywhere else in this repository.
+ * same place `npm start` reads it from, loaded by `verify` before it chose
+ * `apiBase` — and only a `csk_test_` key is accepted, like everywhere else in
+ * this repository.
  */
-async function readFromApi(receiptId: string, receiptFile: string, apiBase: string): Promise<{ ok: true; body: Record<string, unknown> } | { ok: false; detail: string }> {
-  const agentDir = findAgentDir(dirname(resolve(receiptFile)));
-  if (agentDir) readDotEnv(agentDir);
+async function readFromApi(receiptId: string, apiBase: string, agentDir: string | undefined): Promise<{ ok: true; body: Record<string, unknown> } | { ok: false; detail: string }> {
   try {
     const api = createCodeSparClient({ apiKey: process.env["CODESPAR_API_KEY"], baseUrl: apiBase, projectId: process.env["CODESPAR_PROJECT_ID"], timeoutMs: 15_000 });
     const body: unknown = await api.get("/v1/consumers/receipts/{id}", { path: { id: receiptId } });
     if (!isReceiptRead(body)) return { ok: false, detail: "the API answered something that is not a receipt read" };
     return { ok: true, body };
   } catch (err) {
+    if (err instanceof NotATestKeyError) return { ok: false, detail: new NotATestKeyError(err.problem, agentDir ? envFileOf(agentDir) : undefined).message };
     const failure = describeApiError(err);
     return { ok: false, detail: `${failure.code}: ${failure.message}` };
   }
@@ -325,6 +346,10 @@ function render(report: ReceiptVerification): string {
     lines.push(`  approval     ${a.status}: sealed ${a.sealed.items_hash}${a.sealed.batch_hash ? ` batch ${a.sealed.batch_hash}` : ""}`);
     if (a.artifact) lines.push(`               artifact ${a.artifact.approval_id} ${a.artifact.items_hash}${a.artifact.batch_hash ? ` batch ${a.artifact.batch_hash}` : ""}`);
   }
+  if (report.sealed_payment) {
+    const shown = (v: boolean | null) => (v === null ? "not sealed" : String(v));
+    lines.push(`  payment      sandbox ${shown(report.sealed_payment.sandbox)}, money_moved ${shown(report.sealed_payment.money_moved)}`);
+  }
   lines.push(`  reason       ${report.reason}`);
   return lines.join("\n") + "\n";
 }

package/templates/bills-agent/packages/agent-runtime/src/commands/webhook.ts

@@ -7,7 +7,7 @@
  */
 import { stderr, stdout } from "node:process";
 import { envName, type Agent } from "../agent.js";
-import { setup } from "../setup.js";
+import { inLocaleOf, localeFlag, setup } from "../setup.js";
 import { announceOutcome, followUp } from "../terminal.js";
 import { startWebhookServer } from "../webhook.js";
 
@@ -15,14 +15,22 @@ export async function webhook(agent: Agent, argv: string[]): Promise<number> {
   const port = Number(argv.includes("--port") ? argv[argv.indexOf("--port") + 1] : process.env[envName(agent, "WEBHOOK_PORT")] ?? "8787");
   const secret = argv.includes("--secret") ? argv[argv.indexOf("--secret") + 1] : process.env[envName(agent, "TRIGGER_SECRET")];
   const say = (l: string) => stderr.write(l + "\n");
-  const s = setup(agent, { say, runId: `run_webhook_${Date.now().toString(36)}` });
+  let locale;
+  try {
+    locale = localeFlag(argv);
+  } catch (err) {
+    say(err instanceof Error ? err.message : String(err));
+    return 2;
+  }
+  const s = setup(agent, { say, runId: `run_webhook_${Date.now().toString(36)}`, locale });
   const server = startWebhookServer(
     port,
     {
       engine: s.engine,
       secret,
       onClosed: async (execution) => {
-        announceOutcome(execution, s, (l) => void stdout.write(l + "\n"));
+        // Told in the locale of the run that issued the charge, whatever this receiver's own is.
+        announceOutcome(execution, inLocaleOf(s, execution), (l) => void stdout.write(l + "\n"));
         await followUp(execution, s, say);
       },
     },

package/templates/bills-agent/packages/agent-runtime/src/default-kit.ts

@@ -3,9 +3,32 @@
  * example mandate, the generic console words, and no tools. A read-only agent
  * spreads this and adds its handlers; a payer or a collector replaces the rail.
  */
-import { StubRail, loadMandate, type Execution } from "@codespar/agent-core";
+import { StubRail, formatBRL, isReplayedSettlement, loadMandate, railErrorOf, type Execution, type LocaleTable } from "@codespar/agent-core";
 import { relative } from "node:path";
-import type { AgentKit } from "./kit.js";
+import type { AgentKit, KitStrings } from "./kit.js";
+import type { Setup } from "./setup.js";
+
+/**
+ * The lines a payment execution reads as on the console, in the run's locale:
+ * the default kit's, and the bills and supplier agents', which pay the same
+ * way and describe it the same way.
+ */
+export function describePayment(execution: Execution, setup: Setup): string[] {
+  const text = setup.coreStrings;
+  const words = setup.strings;
+  const lines: string[] = [];
+  lines.push(`  ${text.execution} ${execution.id}: ${execution.state}${execution.reason ? ` (${execution.reason})` : ""}`);
+  for (const item of execution.items) lines.push(`    - ${item.beneficiary}: ${formatBRL(item.amount, setup.locale)}${item.description ? ` — ${item.description}` : ""}`);
+  lines.push(`    ${text.totalByCore}: ${formatBRL(execution.total, setup.locale)}`);
+  if (execution.escalation) lines.push(`    ${text.escalatedBy}: ${execution.escalation.trigger} — ${execution.escalation.detail}`);
+  if (execution.blocking_reasons.length) lines.push(`    ${text.blocked(execution.blocking_reasons.join(", "), words.notAuthorized)}`);
+  if (execution.detail && execution.state !== "awaiting_approval") lines.push(`    ${execution.detail}`);
+  if (isReplayedSettlement(execution)) lines.push(`    ${text.replayedSettlement}`);
+  for (const outcome of execution.outcomes) {
+    if (outcome.receipt_id) lines.push(`    ${words.receiptWord}: ${relative(process.cwd(), `${setup.bundle.dir}/receipts/${outcome.receipt_id}.json`)}`);
+  }
+  return lines;
+}
 
 export function formatMinor(minor: number): string {
   const sign = minor < 0 ? "-" : "";
@@ -13,28 +36,45 @@ export function formatMinor(minor: number): string {
   return `${sign}R$ ${Math.floor(abs / 100).toLocaleString("pt-BR")},${String(abs % 100).padStart(2, "0")}`;
 }
 
+export const DEFAULT_STRINGS: LocaleTable<KitStrings> = {
+  "pt-BR": {
+    mandateWord: "mandato",
+    receiptWord: "recibo",
+    intro: 'Diga o que precisa. Ctrl+D ou "sair" encerra.',
+    prompt: "> ",
+    approveQuestion: "  Aprovar? [s/N] ",
+    uncertainDispatch: "  desfecho desconhecido no trilho; rode `npm run resume` para reconciliar (nunca repita a operação)",
+    notAuthorized: "o mandato não autoriza",
+  },
+  en: {
+    mandateWord: "mandate",
+    receiptWord: "receipt",
+    intro: 'Say what you need. Ctrl+D or "exit" ends.',
+    prompt: "> ",
+    approveQuestion: "  Approve? [y/N] ",
+    uncertainDispatch: "  outcome unknown on the rail; run `npm run resume` to reconcile (never repeat the operation)",
+    notAuthorized: "the mandate does not authorize it",
+  },
+};
+
 export const defaultKit: AgentKit = {
   settlement: "immediate",
   scenarioRail: "stub",
   labels: {
     defaultUser: "usr_terminal",
     evalUser: "usr_demo_titular",
-    mandateWord: "mandato",
-    receiptWord: "recibo",
-    intro: 'Diga o que precisa. Ctrl+D ou "sair" encerra.',
-    prompt: "> ",
-    approveQuestion: "  Aprovar? [s/N] ",
-    uncertainDispatch: "  desfecho desconhecido no trilho; rode `npm run resume` para reconciliar (nunca repita a operacao)",
     missingReceiptKind: "receipt_missing_locally",
     missingReceiptDetail: (receiptId, runId) => `receipt ${receiptId} is not in runs/${runId}/receipts`,
     stillExecuting: (e) => `${e.id}: still executing — ${e.detail}; nothing was re-sent`,
   },
+  strings: DEFAULT_STRINGS,
   usage: (manifest) => `${manifest.manifest.name}
   npm start                              interactive terminal
   npm start -- --input "..."             one turn (add --approve/--deny to decide, --json for machine output)
   npm start -- --scenario <name>         run a scenario pack (see scenarios/)
 options: --mode human|mandate  --provider anthropic|replay  --transcript <file>  --rail stub|api  --user <id>  --json
-         --now <ISO 8601>  pin the run to that instant; env CODESPAR_AGENT_NOW is the same thing`,
+         --now <ISO 8601>  pin the run to that instant; env CODESPAR_AGENT_NOW is the same thing
+         --locale pt-BR|en  the language of what the code prints; default: agent.yaml \`locale\`, else pt-BR`,
   buildRail: (ctx) => {
     // A read-only agent has no rail to reach: the stub answers offline, whatever key the environment carries.
     const killAfterDispatch = ctx.envVar("KILL_AFTER_DISPATCH") === "1" ? { afterDispatch: () => process.exit(137) } : {};
@@ -45,19 +85,7 @@ options: --mode human|mandate  --provider anthropic|replay  --transcript <file>
     };
   },
   handlers: () => ({}),
-  describeExecution: (execution, setup) => {
-    const lines: string[] = [];
-    lines.push(`  execucao ${execution.id}: ${execution.state}${execution.reason ? ` (${execution.reason})` : ""}`);
-    for (const item of execution.items) lines.push(`    - ${item.beneficiary}: ${formatMinor(item.amount)}${item.description ? ` — ${item.description}` : ""}`);
-    lines.push(`    total (calculado pelo core): ${formatMinor(execution.total)}`);
-    if (execution.escalation) lines.push(`    escalado por: ${execution.escalation.trigger} — ${execution.escalation.detail}`);
-    if (execution.blocking_reasons.length) lines.push(`    bloqueado: ${execution.blocking_reasons.join(", ")} — o mandato nao autoriza; nao ha o que aprovar`);
-    if (execution.detail && execution.state !== "awaiting_approval") lines.push(`    ${execution.detail}`);
-    for (const outcome of execution.outcomes) {
-      if (outcome.receipt_id) lines.push(`    recibo: ${relative(process.cwd(), `${setup.bundle.dir}/receipts/${outcome.receipt_id}.json`)}`);
-    }
-    return lines;
-  },
+  describeExecution: (execution, setup) => describePayment(execution, setup),
   oneShotPayload: ({ setup: s, reply, toolCalls, executions }) => ({
     run_id: s.runId,
     agent: `${s.manifest.manifest.name}@${s.manifest.manifest.version}`,
@@ -71,11 +99,13 @@ options: --mode human|mandate  --provider anthropic|replay  --transcript <file>
       id: e.id,
       state: e.state,
       reason: e.reason ?? null,
+      rail_error: railErrorOf(e),
       escalation: e.escalation ?? null,
       total_minor: e.total,
       items: e.items.map((i) => ({ beneficiary: i.beneficiary, amount_minor: i.amount })),
       approval_id: e.approval_id ?? null,
       receipt_ids: e.outcomes.filter((o) => o.receipt_id).map((o) => o.receipt_id),
+      replayed: isReplayedSettlement(e),
     })),
     receipts: s.bundle.listReceipts().map((f) => relative(process.cwd(), `${s.bundle.dir}/receipts/${f}`)),
     bundle_dir: relative(process.cwd(), s.bundle.dir),

package/templates/bills-agent/packages/agent-runtime/src/env.ts

@@ -0,0 +1,64 @@
+/**
+ * Two names for the same two settings. The kit reads `CODESPAR_API_URL` and
+ * `CODESPAR_PROJECT_ID`; the CodeSpar CLI (`@codespar/cli`) reads
+ * `CODESPAR_BASE_URL` and `CODESPAR_PROJECT`. A shell prepared for one of them
+ * left the other on its default, production, with nothing said: a staging key
+ * then meets the wrong deployment.
+ *
+ * The kit takes the CLI's names as aliases of its own, and a command that
+ * talks to the API refuses to start when the two disagree. Only the
+ * environment and the agent's `.env` are read: the CLI's own config file
+ * (`~/.codespar/config.json`, what `codespar login` writes) is not.
+ */
+import { readDotEnv } from "./setup.js";
+
+const PAIRS: ReadonlyArray<{ kit: string; cli: string; same: (a: string, b: string) => boolean }> = [
+  { kit: "CODESPAR_API_URL", cli: "CODESPAR_BASE_URL", same: (a, b) => a.replace(/\/+$/, "") === b.replace(/\/+$/, "") },
+  { kit: "CODESPAR_PROJECT_ID", cli: "CODESPAR_PROJECT", same: (a, b) => a === b },
+];
+
+export class EnvNamesDisagreeError extends Error {
+  constructor(kit: string, kitValue: string, cli: string, cliValue: string) {
+    super(`${kit}=${kitValue} and ${cli}=${cliValue} disagree. The kit reads ${kit} and the CodeSpar CLI reads ${cli}; they must name the same thing. Set one of them, or both to the same value.`);
+    this.name = "EnvNamesDisagreeError";
+  }
+}
+
+/**
+ * Makes the two names of each pair say one thing: whichever is set fills the
+ * other, and two that are set and differ throw. Both are left set, so a later
+ * reader of either name, and a later `.env`, finds the pair already decided.
+ * An empty value counts as unset, as it does in the CLI.
+ */
+export function reconcileEnvNames(env: NodeJS.ProcessEnv = process.env): void {
+  for (const { kit, cli, same } of PAIRS) {
+    const kitValue = env[kit]?.trim() || undefined;
+    const cliValue = env[cli]?.trim() || undefined;
+    if (kitValue && cliValue && !same(kitValue, cliValue)) throw new EnvNamesDisagreeError(kit, kitValue, cli, cliValue);
+    const value = kitValue ?? cliValue;
+    if (value !== undefined) env[kit] = env[cli] = value;
+  }
+}
+
+/**
+ * The agent's `.env` under the rule `readDotEnv` already has, extended to the
+ * aliases: what the shell exported wins, and the file fills only what is
+ * unset. The shell is reconciled first, so a name it set under either spelling
+ * closes the pair before the file is read; then the file's own names are.
+ *
+ * It returns the disagreement instead of throwing it: only a command that is
+ * about to use the URL or the project should stop on it.
+ */
+export function readAgentEnv(agentDir: string | undefined): EnvNamesDisagreeError | undefined {
+  try {
+    reconcileEnvNames();
+    if (agentDir) readDotEnv(agentDir);
+    reconcileEnvNames();
+    return undefined;
+  } catch (err) {
+    if (!(err instanceof EnvNamesDisagreeError)) throw err;
+    // The shell disagreed with itself before the file was read: the file is still owed, for the key it may hold.
+    if (agentDir) readDotEnv(agentDir);
+    return err;
+  }
+}

package/templates/bills-agent/packages/agent-runtime/src/index.ts

@@ -2,6 +2,7 @@ export * from "./agent.js";
 export * from "./kit.js";
 export * from "./default-kit.js";
 export * from "./setup.js";
+export * from "./runs.js";
 export * from "./terminal.js";
 export * from "./channels/index.js";
 export * from "./poll.js";
@@ -10,4 +11,5 @@ export * from "./scenarios.js";
 export * from "./adversarial.js";
 export * from "./inspect.js";
 export { main } from "./cli.js";
+export { checkStrings } from "./commands/check.js";
 export { pollWhatsApp, type PollWhatsAppOptions } from "./commands/poll-whatsapp.js";

package/templates/bills-agent/packages/agent-runtime/src/inspect.ts

@@ -57,6 +57,8 @@ export interface InspectAttempt {
     receipt_id: string | null;
     money_moved: boolean | null;
     sandbox: boolean | null;
+    /** The rail answered from its record of an earlier presentation: the payment it names was not made by this call. */
+    idempotent_replay: boolean;
   } | null;
   /** The attempt's outcome as last known, from the call, a later look or a settlement event. */
   status: string | null;
@@ -71,6 +73,13 @@ export interface InspectAttempt {
 export interface InspectExecution {
   execution_id: string;
   final_state: string;
+  /**
+   * Settled, and every attempt that settled was answered at dispatch as a
+   * replay: the money moved, and this run did not move it. An attempt closed
+   * by a later look is never counted as one, because a look re-presents an
+   * attempt this run already sent and cannot say whose payment it reads.
+   */
+  replayed: boolean;
   mode: string | null;
   proposed_at: string | null;
   items: InspectItem[];
@@ -108,6 +117,8 @@ export interface InspectReceipt {
   money_moved: boolean | null;
   sandbox: boolean | null;
   at: string | null;
+  /** Every attempt naming this receipt got it back as a replay: the receipt of an earlier payment, read back by this run. */
+  replayed: boolean;
 }
 
 /**
@@ -128,7 +139,7 @@ export interface InspectBatch {
   /** Lines the list held when it was presented. */
   count: number;
   /** The lines this bundle holds an execution for, by their position in the list. */
-  lines: Array<{ index: number; execution_id: string; final_state: string; attested: boolean }>;
+  lines: Array<{ index: number; execution_id: string; final_state: string; replayed: boolean; attested: boolean }>;
   /** How many of the lines carry an approval artifact. The "3" of "3 of 4". */
   attested: number;
   /** Positions of the presented list this bundle holds no execution for at all. */
@@ -149,7 +160,10 @@ export interface InspectReport {
   mandate: {
     id: string;
     version: number;
+    /** The status in `mandate.snapshot.json`: what the local copy said when the run started. */
     status: string;
+    /** What the status source answered at a gate of this run, when that is the last word the run has on the mandate; null when no gate refused for it, or when a payment executed after the refusal. */
+    status_seen: MandateStatusSeen | null;
     expires_at: string;
     currency: string;
     per_tx_cap_minor: number;
@@ -309,6 +323,7 @@ export function assembleTimeline(bundle: ProofBundle): InspectReport {
   const executions = new Map<string, InspectExecution>();
   const attemptsBy = new Map<string, Map<string, InspectAttempt>>();
   const runEvents: InspectReport["run_events"] = [];
+  let statusSeen: MandateStatusSeen | null = null;
 
   const executionOf = (id: string): InspectExecution => {
     const existing = executions.get(id);
@@ -316,6 +331,7 @@ export function assembleTimeline(bundle: ProofBundle): InspectReport {
     const fresh: InspectExecution = {
       execution_id: id,
       final_state: "unknown",
+      replayed: false,
       mode: null,
       proposed_at: null,
       items: [],
@@ -340,6 +356,7 @@ export function assembleTimeline(bundle: ProofBundle): InspectReport {
     const p = payload(event);
 
     if (!executionId) {
+      if (type === "execution.refused_before_draft") statusSeen = mandateStatusSeen(str(p["reason"]), str(p["detail"]), at) ?? statusSeen;
       const detail = str(p["detail"]) ?? str(p["reason"]) ?? str(event["reason"]) ?? str(event["tool"]) ?? str(event["message"]) ?? "";
       const tool = str(event["tool"]);
       runEvents.push({ at, type, detail: redact(tool ? `${tool}: ${detail || String(event["reason"] ?? "")}` : detail) ?? "" });
@@ -363,6 +380,8 @@ export function assembleTimeline(bundle: ProofBundle): InspectReport {
         const to = str(p["to"]) ?? "unknown";
         execution.transitions.push({ at: str(p["at"]) ?? at, from: str(p["from"]), to, actor: actorLabel(p["actor"] ?? event["actor"]), reason: str(p["reason"]), detail: redact(str(p["detail"])) });
         execution.final_state = to;
+        // A gate that let a payment through read `active` after whatever an earlier gate saw (a mandate paused and resumed).
+        statusSeen = to === "executing" ? null : (mandateStatusSeen(str(p["reason"]), str(p["detail"]), str(p["at"]) ?? at) ?? statusSeen);
         break;
       }
       case "approval.created":
@@ -392,6 +411,7 @@ export function assembleTimeline(bundle: ProofBundle): InspectReport {
           receipt_id: str(p["receipt_id"]),
           money_moved: bool(p["money_moved"]),
           sandbox: bool(p["sandbox"]),
+          idempotent_replay: p["idempotent_replay"] === true,
         };
         attempt.status = attempt.answer.status;
         attempt.transaction_id = attempt.answer.transaction_id ?? attempt.transaction_id;
@@ -465,6 +485,15 @@ export function assembleTimeline(bundle: ProofBundle): InspectReport {
   }
 
   for (const [id, attempts] of attemptsBy) executionOf(id).attempts = [...attempts.values()];
+  for (const execution of executions.values()) {
+    const settled = execution.attempts.filter((a) => a.status === "settled");
+    execution.replayed = execution.final_state === "settled" && settled.length > 0 && settled.every((a) => a.answer?.idempotent_replay === true);
+  }
+  const replayedReceipts = new Set<string>();
+  const paidReceipts = new Set<string>();
+  for (const execution of executions.values()) {
+    for (const a of execution.attempts) if (a.receipt_id) (a.answer?.idempotent_replay ? replayedReceipts : paidReceipts).add(a.receipt_id);
+  }
 
   const receipts: InspectReceipt[] = bundle.listReceipts().map((file) => {
     const raw = bundle.readReceipt(file) ?? {};
@@ -478,8 +507,10 @@ export function assembleTimeline(bundle: ProofBundle): InspectReport {
       money_moved: bool(payment["money_moved"]),
       sandbox: bool(payment["sandbox"]),
       at: str(payment["at"]),
+      replayed: false,
     };
   });
+  for (const receipt of receipts) receipt.replayed = replayedReceipts.has(receipt.receipt_id) && !paidReceipts.has(receipt.receipt_id);
 
   const transcript = bundle.readTranscript();
   const toolCalls = transcript.filter((l) => l.kind === "tool_call");
@@ -501,6 +532,7 @@ export function assembleTimeline(bundle: ProofBundle): InspectReport {
           id: str(snapshot["id"]) ?? "unknown",
           version: num(snapshot["version"]) ?? 0,
           status: str(snapshot["status"]) ?? "unknown",
+          status_seen: statusSeen,
           expires_at: str(snapshot["expires_at"]) ?? "unknown",
           currency,
           per_tx_cap_minor: num(snapshot["per_tx_cap_minor"]) ?? 0,
@@ -538,7 +570,7 @@ function assembleBatches(executions: InspectExecution[]): InspectBatch[] {
     if (!binding) continue;
     const key = `${binding.ref}\u0000${binding.batch_hash}`;
     const entry = batches.get(key) ?? { ref: binding.ref, batch_hash: binding.batch_hash, count: binding.count, lines: [], attested: 0, missing: [] };
-    entry.lines.push({ index: binding.index, execution_id: execution.execution_id, final_state: execution.final_state, attested: execution.approval !== null });
+    entry.lines.push({ index: binding.index, execution_id: execution.execution_id, final_state: execution.final_state, replayed: execution.replayed, attested: execution.approval !== null });
     batches.set(key, entry);
   }
   for (const entry of batches.values()) {
@@ -597,7 +629,9 @@ function executionLines(execution: InspectExecution): Array<{ at: string; label:
     if (answer) {
       const bits = [answer.transaction_id ? `tx ${answer.transaction_id}` : "", answer.receipt_id ? `receipt ${answer.receipt_id}` : "", answer.money_moved !== null ? `money_moved ${answer.money_moved}` : "", answer.sandbox ? "sandbox" : ""].filter(Boolean);
       const why = [answer.code, answer.message].filter(Boolean).join(": ");
-      lines.push({ at: answer.at, label: "rail says", text: `${answer.status}${why ? `  ${why}` : ""}`, wrapped: bits.length ? [bits.join(" · ")] : [] });
+      const wrapped = bits.length ? [bits.join(" · ")] : [];
+      if (answer.idempotent_replay) wrapped.push(REPLAY_NOTE);
+      lines.push({ at: answer.at, label: "rail says", text: `${answer.status}${answer.idempotent_replay ? " (replayed)" : ""}${why ? `  ${why}` : ""}`, wrapped });
     }
     for (const i of a.instrument) lines.push({ at: i.at, label: "instrument", text: `${a.attempt_id}  ${i.status}${i.payable ? ", payable" : ", not payable yet"}${i.due_date ? `, due ${i.due_date}` : ""}`, wrapped: [] });
     for (const r of a.reconciles) lines.push({ at: r.at, label: "look again", text: `${a.attempt_id}  the rail says ${r.found}`, wrapped: [] });
@@ -616,6 +650,8 @@ function executionLines(execution: InspectExecution): Array<{ at: string; label:
  */
 export function batchSummary(batch: InspectBatch): string {
   const bits = [`${batch.attested} of ${batch.count} line(s) attested`];
+  const replayed = batch.lines.filter((l) => l.replayed).length;
+  if (replayed) bits.push(`${replayed} replayed, paid before and not by this run`);
   if (batch.lines.length !== batch.attested) bits.push(`${batch.lines.length} with an execution`);
   if (batch.missing.length) bits.push(`no execution for line(s) ${batch.missing.map((i) => i + 1).join(", ")}`);
   return bits.join(" · ");
@@ -628,14 +664,48 @@ export function batchLineRows(batch: InspectBatch): string[] {
     const line = byIndex.get(i);
     const where = `line ${i + 1} of ${batch.count}`;
     if (!line) return `${where}  — no execution in this bundle: approved as part of this list, and nothing here says it ran`;
-    return `${where}  ${line.execution_id}  ${line.final_state}  ${line.attested ? "approval artifact present" : "no approval artifact"}`;
+    return `${where}  ${line.execution_id}  ${line.final_state}${line.replayed ? " (replayed)" : ""}  ${line.attested ? "approval artifact present" : "no approval artifact"}`;
   });
 }
 
+/** The mandate's status as a gate of the run saw it, and who answered. */
+export interface MandateStatusSeen {
+  status: "revoked" | "paused" | "expired";
+  /** `api` or `stub`: the status source that answered. Null when the refusal names none: the run's own clock passed `expires_at`, or the bundle predates the source on the detail. */
+  source: "api" | "stub" | null;
+  at: string;
+}
+
+const SEEN_BY_REASON: Record<string, MandateStatusSeen["status"]> = { mandate_revoked: "revoked", mandate_paused: "paused", mandate_expired: "expired" };
+
+/** A refusal the mandate gate recorded (`mandateGate` in the core): the reason is the status, and the detail ends with the source that answered. */
+function mandateStatusSeen(reason: string | null, detail: string | null, at: string): MandateStatusSeen | undefined {
+  const status = reason ? SEEN_BY_REASON[reason] : undefined;
+  if (!status) return undefined;
+  const source = /\(source: (api|stub)\)/.exec(detail ?? "")?.[1] as "api" | "stub" | undefined;
+  return { status, source: source ?? null, at };
+}
+
+/**
+ * The header's word for the mandate. The snapshot is the local copy at the
+ * start of the run, and it goes on saying `active` under a mandate the API
+ * answered was revoked; where a gate of the run heard otherwise, the header
+ * says what it heard, from whom, and what the snapshot had said.
+ */
+function mandateStatusLabel(m: NonNullable<InspectReport["mandate"]>): string {
+  const seen = m.status_seen;
+  if (!seen || seen.status === m.status) return m.status;
+  const by = seen.source ? `source: ${seen.source}` : seen.status === "expired" ? "by the run's clock" : "source not recorded";
+  return `${seen.status} (${by}, ${clock(seen.at)}; ${m.status} in the snapshot at the start of the run)`;
+}
+
+/** What a replayed answer means, in the one sentence both renderings print under it. */
+export const REPLAY_NOTE = "idempotent_replay: the rail answered with an earlier payment of this attempt; this run moved no money for it";
+
 /** `execution exe_x — settled` gains ` · folha-2026-10 line 2 of 3` when it is one line of a batch. */
 function executionHeading(execution: InspectExecution): string {
   const b = execution.batch;
-  return `execution ${execution.execution_id} — ${execution.final_state}${b ? ` · ${b.ref} line ${b.index + 1} of ${b.count}` : ""}`;
+  return `execution ${execution.execution_id} — ${execution.final_state}${execution.replayed ? " (replayed, not paid by this run)" : ""}${b ? ` · ${b.ref} line ${b.index + 1} of ${b.count}` : ""}`;
 }
 
 export function renderText(report: InspectReport): string {
@@ -646,7 +716,7 @@ export function renderText(report: InspectReport): string {
   const m = report.mandate;
   if (m) {
     const caps = [`per payment ${formatMinor(m.per_tx_cap_minor)}`, m.periodic_cap ? `per ${m.periodic_cap.window} ${formatMinor(m.periodic_cap.cap_minor)}` : "", `lifetime ${formatMinor(m.cap_minor)}`].filter(Boolean);
-    out.push(`  mandate ${m.status}, expires ${m.expires_at} · ${caps.join(" · ")}`);
+    out.push(`  mandate ${mandateStatusLabel(m)}, expires ${m.expires_at} · ${caps.join(" · ")}`);
     if (m.beneficiaries.length) out.push(`  named payees: ${m.beneficiaries.map((b) => `${b.name} <${b.payee}>`).join(", ")}`);
   }
 
@@ -675,7 +745,7 @@ export function renderText(report: InspectReport): string {
   out.push("");
   out.push(`receipts (${report.receipts.length})`);
   for (const receipt of report.receipts) {
-    const bits = [receipt.state ?? "?", receipt.amount_minor !== null ? formatMinor(receipt.amount_minor) : "", receipt.payee ?? "", receipt.sandbox ? "sandbox" : "", receipt.money_moved === false ? "no money moved" : ""].filter(Boolean);
+    const bits = [receipt.state ?? "?", receipt.amount_minor !== null ? formatMinor(receipt.amount_minor) : "", receipt.payee ?? "", receipt.sandbox ? "sandbox" : "", receipt.money_moved === false ? "no money moved" : "", receipt.replayed ? "read back from a replay, not paid by this run" : ""].filter(Boolean);
     out.push(`  ${receipt.receipt_id}  ${bits.join("  ")}`);
     out.push(`    ${receipt.file}`);
   }
@@ -708,7 +778,7 @@ export function renderHtml(report: InspectReport): string {
     `<h1>${esc(r.run_id)}</h1>`,
     `<p class="lede">${esc(r.agent ?? "unknown agent")} · mode <b>${esc(r.mode ?? "?")}</b> · rail <b>${esc(r.rail ?? "?")}</b> · mandate <b>${esc(r.mandate_id ?? "?")}</b>${r.mandate_version !== null ? ` v${r.mandate_version}` : ""}${r.started_at ? ` · started ${esc(r.started_at)}` : ""}</p>`,
     m
-      ? `<p class="lede">mandate ${esc(m.status)}, expires ${esc(m.expires_at)} · per payment ${esc(formatMinor(m.per_tx_cap_minor))}${m.periodic_cap ? ` · per ${esc(m.periodic_cap.window)} ${esc(formatMinor(m.periodic_cap.cap_minor))}` : ""} · lifetime ${esc(formatMinor(m.cap_minor))}</p>`
+      ? `<p class="lede">mandate ${esc(mandateStatusLabel(m))}, expires ${esc(m.expires_at)} · per payment ${esc(formatMinor(m.per_tx_cap_minor))}${m.periodic_cap ? ` · per ${esc(m.periodic_cap.window)} ${esc(formatMinor(m.periodic_cap.cap_minor))}` : ""} · lifetime ${esc(formatMinor(m.cap_minor))}</p>`
       : "",
     m && m.beneficiaries.length ? `<p class="lede">named payees: ${m.beneficiaries.map((b) => `${esc(b.name)} <code>${esc(b.payee)}</code>`).join(", ")}</p>` : "",
   ].join("\n");
@@ -734,7 +804,8 @@ export function renderHtml(report: InspectReport): string {
         .join("\n");
       const b = execution.batch;
       const where = b ? `<span class="state">${esc(`${b.ref} line ${b.index + 1} of ${b.count}`)}</span>` : "";
-      return `<section><h2>execution ${esc(execution.execution_id)} <span class="state state-${esc(execution.final_state)}">${esc(execution.final_state)}</span> ${where}</h2><table>${rows}</table></section>`;
+      const replayed = execution.replayed ? ` <span class="state">replayed, not paid by this run</span>` : "";
+      return `<section><h2>execution ${esc(execution.execution_id)} <span class="state state-${esc(execution.final_state)}">${esc(execution.final_state)}</span>${replayed} ${where}</h2><table>${rows}</table></section>`;
     })
     .join("\n");
 
@@ -745,7 +816,7 @@ export function renderHtml(report: InspectReport): string {
   const receipts = report.receipts.length
     ? `<table>${report.receipts
         .map((receipt) => {
-          const bits = [receipt.state ?? "?", receipt.amount_minor !== null ? formatMinor(receipt.amount_minor) : "", receipt.payee ?? "", receipt.sandbox ? "sandbox" : "", receipt.money_moved === false ? "no money moved" : ""].filter(Boolean).join(" · ");
+          const bits = [receipt.state ?? "?", receipt.amount_minor !== null ? formatMinor(receipt.amount_minor) : "", receipt.payee ?? "", receipt.sandbox ? "sandbox" : "", receipt.money_moved === false ? "no money moved" : "", receipt.replayed ? "read back from a replay, not paid by this run" : ""].filter(Boolean).join(" · ");
           return `<tr><td class="k"><code>${esc(receipt.receipt_id)}</code></td><td>${esc(bits)}<div class="sub">${esc(receipt.file)}</div></td></tr>`;
         })
         .join("")}</table>`