@codespar/cli 0.18.1 → 0.21.0

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

@@ -2,15 +2,18 @@
  * The terminal channel: what `codespar-agent start` opens. No account, no
  * server. It shows what the core decided, asks the person when an execution
  * is awaiting approval, and prints where the sealed outcome landed. The
- * words are the agent's (`kit.labels`, `kit.describeExecution`); the order
- * of the gates is the runner's and is the same for every agent.
+ * words are the agent's (`kit.strings`, `kit.describeExecution`) and the
+ * shared ones (`CORE_STRINGS`), in the run's locale; the order of the gates
+ * is the runner's and is the same for every agent, and so is what an answer
+ * decides: the parsers below read both languages whatever the locale.
  */
 import { createInterface } from "node:readline/promises";
 import { stdin, stderr, stdout } from "node:process";
 import { relative } from "node:path";
-import type { AgentRuntime, BatchGesture, BatchPresentation, ChargeInstrument, Execution } from "@codespar/agent-core";
+import { formatBRL, railErrorOf, type AgentRuntime, type BatchGesture, type BatchPresentation, type ChargeInstrument, type Execution, type NotRunLine } from "@codespar/agent-core";
 import { pollUntilClosed, type PollResult } from "./poll.js";
-import type { Setup } from "./setup.js";
+import { draftRefusals, refusalLine, sayOutcome } from "./outcome.js";
+import { inLocaleOf, type Setup } from "./setup.js";
 
 export interface TerminalOptions {
   setup: Setup;
@@ -69,7 +72,7 @@ export async function followUp(execution: Execution, setup: Setup, say: (line: s
 
 function receiptLines(execution: Execution, setup: Setup, say: (line: string) => void): void {
   for (const outcome of execution.outcomes) {
-    if (outcome.receipt_id) say(`  ${setup.kit.labels.receiptWord}: ${relative(process.cwd(), `${setup.bundle.dir}/receipts/${outcome.receipt_id}.json`)}`);
+    if (outcome.receipt_id) say(`  ${setup.strings.receiptWord}: ${relative(process.cwd(), `${setup.bundle.dir}/receipts/${outcome.receipt_id}.json`)}`);
   }
 }
 
@@ -78,7 +81,8 @@ export async function handleExecution(execution: Execution, options: TerminalOpt
   const { setup, approver } = options;
   const say = options.say ?? ((l: string) => stderr.write(l + "\n"));
   const tell = options.tell ?? ((l: string) => stdout.write(l + "\n"));
-  const labels = setup.kit.labels;
+  const words = setup.strings;
+  const text = setup.coreStrings;
   const engine = setup.engine;
 
   for (const line of describeExecution(execution, setup)) say(line);
@@ -91,42 +95,43 @@ export async function handleExecution(execution: Execution, options: TerminalOpt
     } else {
       let decision = options.decision;
       if (!decision) {
-        if (current.blocking_reasons.length > 0) say("  (o unico desfecho possivel e negar; aperte Enter)");
+        if (current.blocking_reasons.length > 0) say(text.onlyDeny);
         const ask = options.ask ?? defaultAsk;
-        const answer = (await ask(labels.approveQuestion)).trim().toLowerCase();
-        decision = answer === "s" || answer === "sim" || answer === "y" || answer === "yes" ? "approve" : "deny";
+        decision = parseApproval(await ask(words.approveQuestion));
       }
       if (decision === "approve") current = engine.approve(current.id, approver);
       else if (decision === "deny") current = engine.deny(current.id, approver);
       else {
-        say("  deixado em awaiting_approval (rode de novo com --approve ou --deny)");
+        say(text.leftAwaiting);
         return current;
       }
     }
-    say(`  -> ${current.state}${current.reason ? ` (${current.reason})` : ""}`);
+    say(transitionLine(current));
   }
 
   // An agent that issues on request (`executeOnApproval: false`) leaves the approved execution for its own tool to issue.
   if (current.state === "approved" && setup.kit.executeOnApproval !== false) {
     current = await engine.execute(current.id);
-    say(`  -> ${current.state}${current.reason ? ` (${current.reason})` : ""}`);
+    say(transitionLine(current));
     if (setup.settlement === "immediate") {
       receiptLines(current, setup, say);
-      if (current.state === "executing") say(labels.uncertainDispatch);
+      if (current.state === "executing") say(words.uncertainDispatch);
     }
   }
 
   if (setup.settlement === "await-payer") {
+    // The counterparty is spoken to in the locale of the run that proposed this execution (`npm run approve` is a later command); the operator's lines stay in this one's.
+    const counterparty = inLocaleOf(setup, current);
     if (current.state === "executing" && current.reason === "awaiting_settlement") {
-      const result = await waitForPayer(current.id, options);
+      const result = await waitForPayer(current.id, { ...options, setup: counterparty });
       current = result.execution;
-      say(`  -> ${current.state}${current.reason ? ` (${current.reason})` : ""} apos ${result.rounds} consulta(s), ${result.seconds}s${result.timed_out ? " (tempo esgotado; `npm run poll` continua de onde parou)" : ""}`);
+      say(`${transitionLine(current)}${text.afterLooks(result.rounds, result.seconds, result.timed_out)}`);
       receiptLines(current, setup, say);
     } else if (current.state === "executing") {
-      say(labels.uncertainDispatch);
+      say(words.uncertainDispatch);
     }
     const told = current;
-    announceOutcome(told, setup, (line) => tell(line, told));
+    announceOutcome(told, counterparty, (line) => tell(line, told));
     await followUp(current, setup, say);
   }
   return current;
@@ -150,6 +155,16 @@ function decideByGesture(execution: Execution, gesture: BatchGestureRecord, setu
   return engine.approve(execution.id, approver);
 }
 
+/**
+ * What the person answered to the per-line question. Yes is s, sim, y or yes,
+ * in any locale; anything else is no, which is the default the `[s/N]` and
+ * `[y/N]` prompts show.
+ */
+export function parseApproval(answer: string): "approve" | "deny" {
+  const text = answer.trim().toLowerCase();
+  return text === "s" || text === "sim" || text === "y" || text === "yes" ? "approve" : "deny";
+}
+
 /**
  * What the person answered to a whole list, or `undefined` when the answer
  * cannot be read as one. Lines are numbered from 1, as they were shown.
@@ -181,28 +196,30 @@ export async function presentBatch(batch: BatchPresentation, options: TerminalOp
   const { setup, approver } = options;
   const say = options.say ?? ((l: string) => stderr.write(l + "\n"));
   const ask = options.ask ?? defaultAsk;
-  say(`  lote ${batch.ref} — ${batch.label}: ${batch.count} linha(s), total ${batch.total}, batch_hash ${batch.batch_hash.slice(0, 19)}…`);
+  const text = setup.coreStrings;
+  // The amounts are formatted here from their minor units, in the run's locale; the presentation's own strings are the model's.
+  say(text.batchHeader(batch.ref, batch.label, batch.count, formatBRL(batch.total_minor, setup.locale), batch.batch_hash.slice(0, 19)));
   for (const line of batch.lines) {
     const note =
       line.status === "already_settled"
-        ? " (ja paga; nao roda de novo)"
+        ? text.batchAlreadySettled
         : line.status === "in_progress"
-          ? " (em andamento; nao roda de novo)"
+          ? text.batchInProgress
           : line.status === "attempt_id_conflict"
-            ? " (tentativa presa a outro pagamento; nao roda de novo)"
+            ? text.batchAttemptConflict
             : "";
-    say(`    ${line.index + 1}. ${line.beneficiary}: ${line.amount}${note}`);
+    say(`    ${line.index + 1}. ${line.beneficiary}: ${formatBRL(line.amount_minor, setup.locale)}${note}`);
   }
   let parsed: { vetoed: number[] } | undefined;
   while (!parsed) {
-    parsed = parseBatchGesture(await ask("  Aprovar a lista? [todas / todas exceto 3,7 / nenhuma] "), batch.count);
-    if (!parsed) say(`  nao entendi; responda todas, todas exceto <numeros de 1 a ${batch.count}> ou nenhuma`);
+    parsed = parseBatchGesture(await ask(text.batchQuestion), batch.count);
+    if (!parsed) say(text.batchUnreadable(batch.count));
   }
   const vetoed = new Set(parsed.vetoed);
   const gesture: BatchGesture = { batch_hash: batch.batch_hash, approved: batch.lines.map((l) => l.index).filter((i) => !vetoed.has(i)), vetoed: parsed.vetoed };
   options.gestures.set(batch.ref, { batch_hash: batch.batch_hash, count: batch.count, vetoed });
   setup.engine.note("batch.gesture", null, { batch_ref: batch.ref, batch_hash: batch.batch_hash, count: batch.count, total_minor: batch.total_minor, approved: gesture.approved, vetoed: gesture.vetoed, approver: { type: "human", id: approver.id, channel: approver.channel } });
-  say(`  -> lista ${gesture.vetoed.length === 0 ? "aprovada inteira" : gesture.approved.length === 0 ? "negada inteira" : `aprovada exceto ${gesture.vetoed.map((i) => i + 1).join(", ")}`}`);
+  say(gesture.vetoed.length === 0 ? text.batchApprovedAll : gesture.approved.length === 0 ? text.batchDeniedAll : text.batchApprovedExcept(gesture.vetoed.map((i) => i + 1).join(", ")));
   return gesture;
 }
 
@@ -215,9 +232,9 @@ export async function waitForPayer(executionId: string, options: TerminalOptions
     intervalMs: setup.pollIntervalMs,
     timeoutMs: waitSeconds * 1000,
     payer: options.simulatePayer ? setup.payer : undefined,
-    onInstrument: (e, n, id, instrument) => (options.presentInstrument ?? setup.kit.presentInstrument)?.(e, n, id, instrument, tell),
+    onInstrument: (e, n, id, instrument) => (options.presentInstrument ?? setup.kit.presentInstrument)?.(e, n, id, instrument, tell, setup.locale),
     onWait: (_e, round) => {
-      const line = setup.kit.labels.waitingForPayer?.(round);
+      const line = setup.strings.waitingForPayer?.(round);
       if (setup.railKind === "api" && line !== undefined && round % 5 === 0) say(line);
     },
   });
@@ -238,18 +255,20 @@ export function closeTerminal(): void {
 export async function interactive(options: TerminalOptions & { runtime: AgentRuntime }): Promise<void> {
   const { setup } = options;
   const say = options.say ?? ((l: string) => stderr.write(l + "\n"));
-  const labels = setup.kit.labels;
+  const words = setup.strings;
   // Interactive only: a person at the keyboard can decide a list in one go. The one-shot and the scenario runner pass one decision to every line and never reach this.
   const gestures: BatchGestures = new Map();
   const withGestures = { ...options, gestures };
   const loop = setup.makeLoop(options.runtime, (execution) => handleExecution(execution, withGestures), (batch) => presentBatch(batch, withGestures));
-  say(`${setup.manifest.manifest.name} ${setup.manifest.manifest.version} — approval: ${setup.mode} — trilho: ${setup.railKind} — ${labels.mandateWord} ${setup.mandate.id}`);
-  say(`run ${setup.runId} — bundle em ${relative(process.cwd(), setup.bundle.dir)}`);
-  say(labels.intro);
+  say(setup.coreStrings.banner(setup.manifest.manifest.name, setup.manifest.manifest.version, setup.mode, setup.railKind, words.mandateWord, setup.mandate.id));
+  say(setup.coreStrings.bundleAt(setup.runId, relative(process.cwd(), setup.bundle.dir)));
+  say(words.intro);
+  const notRun: NotRunLine[] = [];
+  let refusalsSaid = 0;
   for (;;) {
     let text: string;
     try {
-      text = await defaultAsk(labels.prompt);
+      text = await defaultAsk(words.prompt);
     } catch {
       break;
     }
@@ -257,7 +276,26 @@ export async function interactive(options: TerminalOptions & { runtime: AgentRun
     if (!trimmed) continue;
     if (["sair", "exit", "quit"].includes(trimmed.toLowerCase())) break;
     const result = await loop.turn(trimmed);
-    stdout.write(result.reply + "\n");
+    stdout.write(`${result.reply}\n`);
+    // The line counts the run so far, and is said only after a turn that paid, tried to, or skipped a line: a greeting or a read moved nothing.
+    notRun.push(...result.not_run);
+    // A request refused before a draft: said with the engine's own reason, once, in the turn that met it.
+    const refused = draftRefusals(setup.store, setup.runId).slice(refusalsSaid);
+    refusalsSaid += refused.length;
+    for (const refusal of refused) say(refusalLine(refusal));
+    if (result.executions.length > 0 || result.not_run.length > 0 || refused.length > 0) sayOutcome(setup, notRun, (line) => stdout.write(`${line}\n`));
   }
   closeTerminal();
 }
+
+/**
+ * `  -> failed (rail_failed): insufficient_funds — wallet cannot reserve the requested amount`.
+ * The reason says which gate closed the execution; on a failure, or an answer
+ * that left an attempt unknown, the rail's own code and message follow it,
+ * verbatim, so the first failure explains itself (#50).
+ */
+export function transitionLine(execution: Execution): string {
+  const failure = execution.state === "failed" || execution.state === "executing" ? railErrorOf(execution) : null;
+  const answer = failure ? `: ${failure.code}${failure.message && failure.message !== failure.code ? ` — ${failure.message}` : ""}` : "";
+  return `  -> ${execution.state}${execution.reason ? ` (${execution.reason})` : ""}${answer}`;
+}

package/templates/bills-agent/packages/agent-runtime/test/env-names.test.ts

@@ -0,0 +1,56 @@
+/**
+ * The kit reads `CODESPAR_API_URL` and `CODESPAR_PROJECT_ID`; the CodeSpar CLI
+ * reads `CODESPAR_BASE_URL` and `CODESPAR_PROJECT`. A shell set up for one
+ * must not send the other to production in silence: the kit takes the CLI's
+ * names as aliases, and refuses to start when the two names disagree.
+ */
+import { describe, expect, it } from "vitest";
+import { EnvNamesDisagreeError, reconcileEnvNames } from "../src/env.js";
+
+const STAGING = "https://api.staging.codespar.dev";
+
+describe("reconcileEnvNames", () => {
+  it("fills the kit's names from the CLI's when only the CLI's are set", () => {
+    const env: NodeJS.ProcessEnv = { CODESPAR_BASE_URL: STAGING, CODESPAR_PROJECT: "prj_cli" };
+    reconcileEnvNames(env);
+    expect(env["CODESPAR_API_URL"]).toBe(STAGING);
+    expect(env["CODESPAR_PROJECT_ID"]).toBe("prj_cli");
+  });
+
+  it("fills the CLI's names from the kit's too, so a .env read later cannot reopen a pair the shell closed", () => {
+    const env: NodeJS.ProcessEnv = { CODESPAR_API_URL: STAGING, CODESPAR_PROJECT_ID: "prj_kit" };
+    reconcileEnvNames(env);
+    expect(env["CODESPAR_BASE_URL"]).toBe(STAGING);
+    expect(env["CODESPAR_PROJECT"]).toBe("prj_kit");
+  });
+
+  it("leaves the kit's names alone when the CLI's are unset or empty", () => {
+    const env: NodeJS.ProcessEnv = { CODESPAR_API_URL: STAGING, CODESPAR_BASE_URL: "", CODESPAR_PROJECT_ID: "prj_kit" };
+    reconcileEnvNames(env);
+    expect(env["CODESPAR_API_URL"]).toBe(STAGING);
+    expect(env["CODESPAR_PROJECT_ID"]).toBe("prj_kit");
+  });
+
+  it("treats an empty kit name as unset, as the CLI does with its own", () => {
+    const env: NodeJS.ProcessEnv = { CODESPAR_API_URL: "", CODESPAR_BASE_URL: STAGING };
+    reconcileEnvNames(env);
+    expect(env["CODESPAR_API_URL"]).toBe(STAGING);
+  });
+
+  it("accepts both names when they say the same thing, a trailing slash aside", () => {
+    const env: NodeJS.ProcessEnv = { CODESPAR_API_URL: STAGING, CODESPAR_BASE_URL: `${STAGING}/`, CODESPAR_PROJECT_ID: "prj_1", CODESPAR_PROJECT: "prj_1" };
+    expect(() => reconcileEnvNames(env)).not.toThrow();
+    expect(env["CODESPAR_API_URL"]).toBe(STAGING);
+  });
+
+  it("refuses two URLs that disagree, naming both", () => {
+    const env: NodeJS.ProcessEnv = { CODESPAR_API_URL: "https://api.codespar.dev", CODESPAR_BASE_URL: STAGING };
+    expect(() => reconcileEnvNames(env)).toThrow(EnvNamesDisagreeError);
+    expect(() => reconcileEnvNames(env)).toThrow(/CODESPAR_API_URL=https:\/\/api\.codespar\.dev.*CODESPAR_BASE_URL=https:\/\/api\.staging\.codespar\.dev/);
+  });
+
+  it("refuses two projects that disagree, naming both", () => {
+    const env: NodeJS.ProcessEnv = { CODESPAR_PROJECT_ID: "prj_kit", CODESPAR_PROJECT: "prj_cli" };
+    expect(() => reconcileEnvNames(env)).toThrow(/CODESPAR_PROJECT_ID=prj_kit.*CODESPAR_PROJECT=prj_cli/);
+  });
+});

package/templates/bills-agent/packages/agent-runtime/test/inspect-mandate-status.test.ts

@@ -0,0 +1,80 @@
+/**
+ * The header of `inspect` and the mandate's status. The snapshot in the
+ * bundle is the local copy at the start of the run and says `active` for a
+ * mandate the API answered was revoked two lines below; the header says what
+ * a gate of the run heard, when that is the last word the run has.
+ */
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { ProofBundle } from "@codespar/agent-core";
+import { assembleTimeline, renderHtml, renderText } from "../src/inspect.js";
+
+const AGENT = { type: "agent", agent: "bills-agent@0.1.0", on_behalf_of: "usr_demo_titular" };
+const SNAPSHOT = "active in the snapshot at the start of the run";
+
+type Step = { execution: string | null; to?: string; reason?: string; detail?: string; at: string };
+
+function bundleOf(steps: Step[]): ProofBundle {
+  const bundle = new ProofBundle(mkdtempSync(join(tmpdir(), "inspect-mandate-status-")), "run_status_mandate_abc123");
+  bundle.meta({ run_id: bundle.runId, agent: "bills-agent@0.1.0", mode: "mandate", rail: "api", mandate_id: "cm_fixture", mandate_version: 1, started_at: "2026-09-23T18:00:00.000Z" });
+  writeFileSync(join(bundle.dir, "mandate.snapshot.json"), JSON.stringify({ id: "cm_fixture", version: 1, status: "active", currency: "BRL", cap_minor: 7200000, per_tx_cap_minor: 250000, expires_at: "2027-09-23T00:00:00.000Z", beneficiaries: [] }));
+  steps.forEach((step, i) => {
+    const payload = { ...(step.to ? { from: "approved", to: step.to, at: step.at, actor: AGENT } : {}), ...(step.reason ? { reason: step.reason } : {}), ...(step.detail ? { detail: step.detail } : {}) };
+    bundle.event({ seq: i + 1, run_id: bundle.runId, execution_id: step.execution, type: step.to ? "execution.transition" : "execution.refused_before_draft", payload, at: step.at, actor: AGENT });
+  });
+  return bundle;
+}
+
+const header = (bundle: ProofBundle) => renderText(assembleTimeline(bundle)).split("\n")[2];
+
+describe("inspect: the mandate's status in the header", () => {
+  it("is the snapshot's when no gate of the run heard otherwise", () => {
+    const bundle = bundleOf([
+      { execution: "exe_a", to: "executing", at: "2026-09-23T18:00:10.000Z" },
+      { execution: "exe_a", to: "settled", at: "2026-09-23T18:00:12.000Z" },
+    ]);
+    expect(assembleTimeline(bundle).mandate?.status_seen).toBeNull();
+    expect(header(bundle)).toMatch(/^ {2}mandate active, expires 2027-09-23T00:00:00.000Z · /);
+  });
+
+  it("is what the API answered at the gate, with the source, the time and what the snapshot had said", () => {
+    const bundle = bundleOf([{ execution: "exe_a", to: "denied", reason: "mandate_revoked", detail: "mandate cm_fixture was revoked (source: api)", at: "2026-09-23T18:00:13.000Z" }]);
+    const report = assembleTimeline(bundle);
+    expect(report.mandate).toMatchObject({ status: "active", status_seen: { status: "revoked", source: "api", at: "2026-09-23T18:00:13.000Z" } });
+    expect(header(bundle)).toContain(`mandate revoked (source: api, 18:00:13; ${SNAPSHOT}), expires `);
+    expect(header(bundle)).not.toContain("mandate active,");
+    // The page says the same thing as the terminal.
+    expect(renderHtml(report)).toContain(`mandate revoked (source: api, 18:00:13; ${SNAPSHOT}), expires `);
+    expect(renderHtml(report)).not.toContain("mandate active,");
+  });
+
+  it("reads a refusal before a draft the same way, and a paused mandate, and the stub", () => {
+    const refused = bundleOf([{ execution: null, reason: "mandate_revoked", detail: "mandate cm_fixture was revoked (source: stub)", at: "2026-09-23T18:02:00.000Z" }]);
+    expect(header(refused)).toContain(`mandate revoked (source: stub, 18:02:00; ${SNAPSHOT})`);
+    const paused = bundleOf([{ execution: "exe_a", to: "denied", reason: "mandate_paused", detail: "mandate cm_fixture is paused (source: api)", at: "2026-09-23T18:00:13.000Z" }]);
+    expect(header(paused)).toContain(`mandate paused (source: api, 18:00:13; ${SNAPSHOT})`);
+  });
+
+  it("an expiry the run's own clock found names the clock, not a source that never answered it", () => {
+    const bundle = bundleOf([{ execution: "exe_a", to: "expired", reason: "mandate_expired", detail: "mandate cm_fixture expired at 2027-09-23T00:00:00.000Z", at: "2027-09-23T00:00:05.000Z" }]);
+    expect(assembleTimeline(bundle).mandate?.status_seen).toMatchObject({ status: "expired", source: null });
+    expect(header(bundle)).toContain(`mandate expired (by the run's clock, 00:00:05; ${SNAPSHOT})`);
+  });
+
+  it("a payment that executed after a pause is the last word: the mandate was resumed, and the header is the snapshot's again", () => {
+    const bundle = bundleOf([
+      { execution: "exe_a", to: "denied", reason: "mandate_paused", detail: "mandate cm_fixture is paused (source: api)", at: "2026-09-23T18:00:13.000Z" },
+      { execution: "exe_b", to: "executing", at: "2026-09-23T18:05:00.000Z" },
+      { execution: "exe_b", to: "settled", at: "2026-09-23T18:05:02.000Z" },
+    ]);
+    expect(assembleTimeline(bundle).mandate?.status_seen).toBeNull();
+    expect(header(bundle)).toContain("mandate active, expires ");
+  });
+
+  it("a refusal that is not about the mandate's status leaves the header alone", () => {
+    const bundle = bundleOf([{ execution: "exe_a", to: "denied", reason: "cap_exceeded", detail: "300000 is above the cap per payment", at: "2026-09-23T18:00:13.000Z" }]);
+    expect(assembleTimeline(bundle).mandate?.status_seen).toBeNull();
+  });
+});

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

@@ -9,7 +9,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { describe, expect, it } from "vitest";
 import { ProofBundle } from "@codespar/agent-core";
-import { assembleTimeline, redactorFor, renderHtml, renderText, VERIFY_NOTE } from "../src/inspect.js";
+import { assembleTimeline, redactorFor, renderHtml, renderText, REPLAY_NOTE, VERIFY_NOTE } from "../src/inspect.js";
 
 const ESCOLA = "financeiro@escola-aurora.example.com.br";
 const MASKED = "fi***@escola-aurora.example.com.br";
@@ -150,7 +150,7 @@ describe("the timeline `inspect` assembles from a bundle", () => {
 
   it("lists the receipts that came back, and the events that belong to no execution", () => {
     const report = assembleTimeline(fixtureBundle());
-    expect(report.receipts).toEqual([{ receipt_id: "rcpt_one", file: "receipts/rcpt_one.json", state: "paid", amount_minor: 185000, payee: MASKED, money_moved: false, sandbox: true, at: "2026-09-23T18:00:22.000Z" }]);
+    expect(report.receipts).toEqual([{ receipt_id: "rcpt_one", file: "receipts/rcpt_one.json", state: "paid", amount_minor: 185000, payee: MASKED, money_moved: false, sandbox: true, at: "2026-09-23T18:00:22.000Z", replayed: false }]);
     expect(report.executions.find((e) => e.execution_id === "exe_one")!.receipts).toEqual(["rcpt_one"]);
     expect(report.run_events.map((e) => e.type)).toEqual(["execution.refused_before_draft", "tool.refused"]);
   });
@@ -168,6 +168,67 @@ describe("the timeline `inspect` assembles from a bundle", () => {
   });
 });
 
+/**
+ * Issue #60: the rail answered a dispatch from an earlier presentation of the
+ * same attempt. Settled, and paid by somebody else. An attempt closed by a
+ * later look is the other case: the look cannot say whose payment it read, so
+ * it is never counted as a replay.
+ */
+function withReplays(): ProofBundle {
+  const bundle = fixtureBundle();
+  const run = "run_fixture_human_abc123";
+  for (const event of [
+    { run_id: run, execution_id: "exe_three", type: "execution.drafted", payload: { items: [{ alias: "escola", beneficiary: "Escola Aurora", payee: ESCOLA, amount: 185000, currency: "BRL" }], total: 185000, mode: "mandate", batch: { ref: "folha", batch_hash: "sha256:abc", index: 0, count: 2 } }, at: "2026-09-23T18:03:00.000Z", actor: AGENT },
+    { run_id: run, execution_id: "exe_three", type: "rail.dispatch", payload: { attempt_id: "ska_three", payee: ESCOLA, amount: 185000, rail: "stub", idempotency_key: "idk_three" }, at: "2026-09-23T18:03:01.000Z", actor: AGENT },
+    { run_id: run, execution_id: "exe_three", type: "rail.outcome", payload: { attempt_id: "ska_three", status: "settled", transaction_id: "tx_earlier", receipt_id: "rcpt_earlier", money_moved: false, sandbox: true, idempotent_replay: true }, at: "2026-09-23T18:03:02.000Z", actor: AGENT },
+    { run_id: run, execution_id: "exe_three", type: "execution.transition", payload: { from: "executing", to: "settled", at: "2026-09-23T18:03:03.000Z", actor: AGENT }, at: "2026-09-23T18:03:03.000Z", actor: AGENT },
+    { run_id: run, execution_id: "exe_four", type: "execution.drafted", payload: { items: [{ alias: "escola", beneficiary: "Escola Aurora", payee: ESCOLA, amount: 185000, currency: "BRL" }], total: 185000, mode: "mandate", batch: { ref: "folha", batch_hash: "sha256:abc", index: 1, count: 2 } }, at: "2026-09-23T18:04:00.000Z", actor: AGENT },
+    { run_id: run, execution_id: "exe_four", type: "rail.dispatch", payload: { attempt_id: "ska_four", payee: ESCOLA, amount: 185000, rail: "stub", idempotency_key: "idk_four" }, at: "2026-09-23T18:04:01.000Z", actor: AGENT },
+    { run_id: run, execution_id: "exe_four", type: "rail.outcome", payload: { attempt_id: "ska_four", status: "uncertain", code: "psp_dispatch_uncertain", message: "timeout" }, at: "2026-09-23T18:04:02.000Z", actor: AGENT },
+    { run_id: run, execution_id: "exe_four", type: "rail.reconcile", payload: { attempt_id: "ska_four", found: "settled" }, at: "2026-09-23T18:05:00.000Z", actor: AGENT },
+    { run_id: run, execution_id: "exe_four", type: "execution.transition", payload: { from: "executing", to: "settled", at: "2026-09-23T18:05:01.000Z", actor: AGENT }, at: "2026-09-23T18:05:01.000Z", actor: AGENT },
+  ]) {
+    bundle.event(event as Record<string, unknown>);
+  }
+  writeFileSync(join(bundle.dir, "receipts", "rcpt_earlier.json"), JSON.stringify({ receipt_id: "rcpt_earlier", state: "paid", payment: { amount_minor: 185000, payee: MASKED, money_moved: false, sandbox: true, at: "2026-09-23T17:00:00.000Z" }, actor: AGENT }));
+  return bundle;
+}
+
+describe("inspect says which settlements this run did not pay (#60)", () => {
+  it("a dispatch answered as a replay is settled and replayed; one closed by a later look is settled and not", () => {
+    const report = assembleTimeline(withReplays());
+    const byId = new Map(report.executions.map((e) => [e.execution_id, e]));
+    expect(byId.get("exe_one")!.replayed).toBe(false);
+    expect(byId.get("exe_three")).toMatchObject({ final_state: "settled", replayed: true });
+    expect(byId.get("exe_three")!.attempts[0]!.answer).toMatchObject({ status: "settled", receipt_id: "rcpt_earlier", idempotent_replay: true });
+    expect(byId.get("exe_four")).toMatchObject({ final_state: "settled", replayed: false });
+    expect(report.batches[0]!.lines.map((l) => [l.execution_id, l.replayed])).toEqual([
+      ["exe_three", true],
+      ["exe_four", false],
+    ]);
+    expect(report.receipts.map((r) => [r.receipt_id, r.replayed])).toEqual([
+      ["rcpt_earlier", true],
+      ["rcpt_one", false],
+    ]);
+  });
+
+  it("the text and the HTML say it where a reader looks: the rail line, the heading, the batch header and the receipt", () => {
+    const report = assembleTimeline(withReplays());
+    const text = renderText(report);
+    expect(text).toContain("execution exe_three — settled (replayed, not paid by this run)");
+    expect(text).toContain("rail says   settled (replayed)");
+    expect(text).toContain(REPLAY_NOTE);
+    expect(text).toContain("1 replayed, paid before and not by this run");
+    expect(text).toContain("rcpt_earlier  paid  R$ 1.850,00");
+    expect(text).toMatch(/rcpt_earlier .*read back from a replay, not paid by this run/);
+    expect(text).not.toMatch(/rcpt_one .*read back from a replay/);
+    expect(text).toContain("execution exe_four — settled · folha");
+    const html = renderHtml(report);
+    expect(html).toContain("replayed, not paid by this run");
+    expect(html).toContain(REPLAY_NOTE);
+  });
+});
+
 describe("masking: inspect never un-masks and never leaks a key it read raw", () => {
   it("no raw payee survives into the report, the text or the HTML", () => {
     const report = assembleTimeline(fixtureBundle());

package/templates/bills-agent/packages/agent-runtime/test/outcome.test.ts

@@ -0,0 +1,72 @@
+/**
+ * The count the terminal prints and the one-shot exits by, on the cases a
+ * process test cannot stage cheaply: which reasons read as declined, and
+ * which exit code wins.
+ */
+import { describe, expect, it } from "vitest";
+import { isDeclinedReason, type Execution, type NotRunLine } from "@codespar/agent-core";
+import { outcomeExitCode, runOutcome } from "../src/outcome.js";
+
+function execution(state: Execution["state"], over: Partial<Pick<Execution, "reason" | "outcomes">> = {}): Execution {
+  return { id: `exec_${Math.random().toString(36).slice(2)}`, state, outcomes: [], ...over } as unknown as Execution;
+}
+
+const outcome = (status: "settled" | "failed" | "accepted", over: Record<string, unknown> = {}) => ({ index: 0, attempt_id: "att", status, ...over }) as Execution["outcomes"][number];
+
+describe("isDeclinedReason", () => {
+  it("is true of a charge nobody paid, a charge withdrawn and the organization's pause, and of nothing else", () => {
+    for (const reason of ["charge_expired", "charge_cancelled", "org_paused"]) expect(isDeclinedReason(reason)).toBe(true);
+    for (const reason of ["charge_issuer_error", "rail_failed", "psp_dispatch_failed", undefined, null]) expect(isDeclinedReason(reason)).toBe(false);
+  });
+});
+
+describe("runOutcome", () => {
+  it("counts a multi-item execution by payment: three paid and one failed", () => {
+    const e = execution("failed", { reason: "rail_failed", outcomes: [outcome("settled"), outcome("failed", { code: "psp_dispatch_failed" }), outcome("settled"), outcome("settled")] });
+    expect(runOutcome([e], [])).toEqual({ settled: 3, failed: 1, declined: 0, already_paid: 0, open: 0 });
+  });
+
+  it("counts a replayed settlement as already paid, attempt by attempt", () => {
+    const e = execution("settled", { outcomes: [outcome("settled", { replayed: true }), outcome("settled")] });
+    expect(runOutcome([e], [])).toMatchObject({ settled: 1, already_paid: 1 });
+  });
+
+  it("reads charge_expired, charge_cancelled and org_paused as declined, and charge_issuer_error as failed", () => {
+    const declined = ["charge_expired", "charge_cancelled", "org_paused"].map((code) => execution("failed", { reason: code as Execution["reason"], outcomes: [outcome("failed", { code })] }));
+    expect(runOutcome(declined, [])).toEqual({ settled: 0, failed: 0, declined: 3, already_paid: 0, open: 0 });
+    expect(runOutcome([execution("failed", { reason: "charge_issuer_error", outcomes: [outcome("failed", { code: "charge_issuer_error" })] })], [])).toMatchObject({ failed: 1, declined: 0 });
+  });
+
+  it("reads an execution closed with no attempt by its own reason", () => {
+    expect(runOutcome([execution("failed", { reason: "org_paused" }), execution("failed", { reason: "rail_failed" }), execution("denied"), execution("expired")], [])).toEqual({ settled: 0, failed: 1, declined: 3, already_paid: 0, open: 0 });
+  });
+
+  it("counts a line an earlier run holds as open, whatever that run's verdict, and a refused line as failed", () => {
+    const notRun: NotRunLine[] = [
+      { ref: "a", why: "in_progress", detail: "attempt_id_conflict" },
+      { ref: "b", why: "in_progress", detail: "in_progress" },
+      { ref: "c", why: "already_settled" },
+      { ref: "d", why: "refused", detail: "unreadable_line" },
+    ];
+    expect(runOutcome([], notRun)).toEqual({ settled: 0, failed: 1, declined: 0, already_paid: 1, open: 2 });
+  });
+});
+
+describe("outcomeExitCode", () => {
+  const executing = execution("executing");
+
+  it("1 wins over 3: something failed and something else was left executing", () => {
+    const failed = execution("failed", { reason: "rail_failed", outcomes: [outcome("failed")] });
+    const counted = runOutcome([failed, executing], []);
+    expect(counted).toMatchObject({ failed: 1, open: 1 });
+    expect(outcomeExitCode(counted, [failed, executing])).toBe(1);
+  });
+
+  it("3 when nothing failed and an execution of this run was left executing", () => {
+    expect(outcomeExitCode(runOutcome([executing], []), [executing])).toBe(3);
+  });
+
+  it("0 when a line is held by an earlier run and this run left nothing executing", () => {
+    expect(outcomeExitCode(runOutcome([], [{ ref: "a", why: "in_progress" }]), [])).toBe(0);
+  });
+});

package/templates/bills-agent/packages/agent-runtime/test/poll-payer.test.ts

@@ -0,0 +1,64 @@
+/**
+ * The sandbox payer in the poll pays a receivable only once it is payable.
+ * It used to also pay "after a few looks", whatever it found, and on staging
+ * that paid a charge the issuer had ended in ERROR: the order read `settled`
+ * with no QR ever shown (OPEN_QUESTIONS §63, ent#1816). These drive the poll
+ * with a rail that stays unpayable for longer than the old patience.
+ */
+import { describe, expect, it } from "vitest";
+import type { ChargeInstrument, Execution, ExecutionEngine } from "@codespar/agent-core";
+import { pollUntilClosed } from "../src/poll.js";
+
+function instrument(payable: boolean): ChargeInstrument {
+  return { payable, status: payable ? "PENDING" : "PROCESSING", pix_copy_paste: payable ? "000201..." : null, boleto_bank_line: payable ? "2".repeat(47) : null, boleto_bar_code: null, due_date: "2026-09-30" };
+}
+
+/** An engine that answers one executing receivable, payable from look `payableFrom` on (never when undefined). */
+function engineWith(payableFrom?: number) {
+  let looks = 0;
+  const execution = (): Execution =>
+    ({
+      id: "exe_1",
+      state: "executing",
+      outcomes: [{ index: 0, attempt_id: "att_1_0", status: "accepted", transaction_id: "chg_1", instrument: instrument(payableFrom !== undefined && looks >= payableFrom) }],
+    }) as unknown as Execution;
+  const engine = {
+    get: () => execution(),
+    reconcile: async () => ((looks += 1), execution()),
+    markShown: () => true,
+    note: () => undefined,
+  } as unknown as ExecutionEngine;
+  return { engine, looks: () => looks };
+}
+
+function payerSpy() {
+  const calls: string[] = [];
+  return {
+    calls,
+    payer: {
+      kind: "stub" as const,
+      pay: async (chargeId: string) => (calls.push(chargeId), { ok: true as const, detail: "paid" }),
+      behave: () => undefined,
+    },
+  };
+}
+
+describe("the poll's sandbox payer pays only what is payable", () => {
+  it("a receivable that never becomes payable is never paid, however many looks the wait allows", async () => {
+    const { engine, looks } = engineWith(undefined);
+    const { payer, calls } = payerSpy();
+    const result = await pollUntilClosed(engine, "exe_1", { intervalMs: 0, timeoutMs: 0, maxRounds: 12, payer });
+    expect(looks()).toBe(12);
+    expect(calls).toEqual([]);
+    expect(result.payer_calls).toEqual([]);
+    expect(result.timed_out).toBe(true);
+  });
+
+  it("the payer plays once, on the first look that finds it payable", async () => {
+    const { engine } = engineWith(7);
+    const { payer, calls } = payerSpy();
+    const result = await pollUntilClosed(engine, "exe_1", { intervalMs: 0, timeoutMs: 0, maxRounds: 12, payer });
+    expect(calls).toEqual(["chg_1"]);
+    expect(result.payer_calls).toEqual(["paid"]);
+  });
+});

package/templates/bills-agent/packages/agent-runtime/test/rerun-not-replayed.test.ts

@@ -0,0 +1,46 @@
+/**
+ * `notReplayed` reads a bundle's events for what only the world can do. These
+ * are the events as the engine writes them, by hand, so the reading is held
+ * to the shape and not to whatever a scenario happens to produce.
+ */
+import { describe, expect, it } from "vitest";
+import { notReplayed } from "../src/commands/rerun.js";
+
+const transition = (execution: string, to: string, reason?: string) => ({ type: "execution.transition", execution_id: execution, payload: { to, ...(reason ? { reason } : {}) } });
+const outcome = (execution: string, status: string) => ({ type: "rail.outcome", execution_id: execution, payload: { status } });
+
+describe("what a rerun does not replay", () => {
+  it("nothing, in a run that settled, failed on the rail or was denied by a person", () => {
+    expect(notReplayed([transition("a", "approved"), transition("a", "executing"), outcome("a", "settled"), transition("a", "settled")])).toEqual([]);
+    expect(notReplayed([transition("a", "executing"), outcome("a", "failed"), transition("a", "failed", "rail_failed")])).toEqual([]);
+    expect(notReplayed([transition("a", "awaiting_approval"), transition("a", "denied", "denied_by_approver")])).toEqual([]);
+    // A reason that is a key of every object is not one of the three this reads.
+    expect(notReplayed([transition("a", "denied", "constructor"), transition("b", "denied", "toString")])).toEqual([]);
+    // Left awaiting approval is the person not deciding, and a rerun does replay that.
+    expect(notReplayed([transition("a", "awaiting_approval")])).toEqual([]);
+  });
+
+  it("a mandate revoked or paused, and the organization's kill switch, at a gate or before a draft", () => {
+    expect(notReplayed([transition("a", "denied", "mandate_revoked")])).toEqual(["a mandate that was revoked"]);
+    expect(notReplayed([transition("a", "denied", "mandate_paused")])).toEqual(["a mandate that was paused"]);
+    expect(notReplayed([transition("a", "denied", "org_paused")])).toEqual(["an organization that paused every mandate"]);
+    expect(notReplayed([{ type: "execution.refused_before_draft", execution_id: null, payload: { reason: "mandate_revoked" } }])).toEqual(["a mandate that was revoked"]);
+  });
+
+  it("an uncertain answer from the rail, even one a later reconciliation settled", () => {
+    expect(notReplayed([transition("a", "executing"), outcome("a", "uncertain"), transition("a", "settled")])).toEqual(["an uncertain answer from the rail"]);
+    // Whichever of the engine's three events for it the bundle holds.
+    expect(notReplayed([{ type: "rail.uncertain", execution_id: "a", payload: {} }])).toEqual(["an uncertain answer from the rail"]);
+    expect(notReplayed([{ type: "execution.uncertain", execution_id: "a", payload: { detail: "attempt att_1: psp_dispatch_uncertain" } }])).toEqual(["an uncertain answer from the rail"]);
+  });
+
+  it("a charge issued and still out when the run ended, and not one that was paid", () => {
+    expect(notReplayed([transition("a", "executing"), outcome("a", "accepted")])).toEqual(["a payer who had not paid when it ended"]);
+    expect(notReplayed([transition("a", "executing"), outcome("a", "accepted"), transition("a", "settled")])).toEqual([]);
+  });
+
+  it("each thing once, in the order the run met them", () => {
+    const events = [transition("a", "executing"), outcome("a", "uncertain"), transition("b", "denied", "mandate_revoked"), { type: "execution.refused_before_draft", execution_id: null, payload: { reason: "mandate_revoked" } }];
+    expect(notReplayed(events)).toEqual(["an uncertain answer from the rail", "a mandate that was revoked"]);
+  });
+});