@codespar/cli 0.18.0 → 0.20.0

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>`

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

@@ -15,6 +15,8 @@ import type {
   LoadedManifest,
   LocalMandateStatusStub,
   Guardrails,
+  Locale,
+  LocaleTable,
   Mandate,
   MandateStatusSource,
   PaymentRail,
@@ -95,12 +97,30 @@ export interface RailBuild {
   pollIntervalMs?: number;
 }
 
+/**
+ * What an agent calls the people and the records of a run. None of it is
+ * localized, on purpose: who approved is an id in a signed artifact, and an
+ * approver that changed with the language would be a different approver.
+ */
 export interface RuntimeLabels {
   /** Who decides when no `--user` is given: `usr_terminal`, `usr_operator`. */
   defaultUser: string;
   /** Who decides inside a scenario or an adversarial case. */
   evalUser: string;
-  /** The word for the signed instrument in the banner: `mandato`, `politica`. */
+  /** `reconcile`'s finding kind and detail for a sealed outcome the bundle does not hold. */
+  missingReceiptKind: string;
+  missingReceiptDetail(receiptId: string, runId: string): string;
+  /** `resume`'s line for an execution it could not close. */
+  stillExecuting(execution: Execution): string;
+}
+
+/**
+ * The words the runner prints on an agent's behalf, one entry per locale
+ * (`kit.strings`). A kit adds keys of its own to the same entries; every key
+ * must exist in every locale, which `npm run check` verifies.
+ */
+export interface KitStrings {
+  /** The word for the signed instrument in the banner: `mandato`, `política`. */
   mandateWord: string;
   /** The word for a sealed outcome in the console: `recibo`, `registro`. */
   receiptWord: string;
@@ -108,15 +128,12 @@ export interface RuntimeLabels {
   intro: string;
   /** The interactive prompt. */
   prompt: string;
-  /** The question an `awaiting_approval` execution asks at the keyboard. */
+  /** The question an `awaiting_approval` execution asks at the keyboard. Its answers are read the same in every locale. */
   approveQuestion: string;
   /** What the console says when a dispatch ended with an unknown outcome. */
   uncertainDispatch: string;
-  /** `reconcile`'s finding kind and detail for a sealed outcome the bundle does not hold. */
-  missingReceiptKind: string;
-  missingReceiptDetail(receiptId: string, runId: string): string;
-  /** `resume`'s line for an execution it could not close. */
-  stillExecuting(execution: Execution): string;
+  /** Who refuses a blocked execution: "o mandato não autoriza", "the policy does not authorize". */
+  notAuthorized: string;
   /** `await-payer` only: the line printed every few looks while the payer has not acted. */
   waitingForPayer?(round: number): string;
 }
@@ -132,6 +149,8 @@ export interface OneShotContext {
 
 export interface ConsentContext {
   agentDir: string;
+  /** The run's locale: the consent summary and its question are printed in it. */
+  locale: Locale;
   argv: string[];
   say(line: string): void;
 }
@@ -153,6 +172,8 @@ export interface AgentKit {
    */
   scenarioRail?: "stub" | "requested";
   labels: RuntimeLabels;
+  /** The words the runner prints for this agent, per locale. */
+  strings: LocaleTable<KitStrings>;
   /** The usage text `--help`, a bad flag and a bad `--now` print. */
   usage(manifest: LoadedManifest): string;
   buildRail(ctx: RailContext): RailBuild;
@@ -169,13 +190,13 @@ export interface AgentKit {
    */
   executeOnApproval?: boolean;
   /** The deterministic policy the core runs as its `policyExtension`. `store` is the run's state.db, for a policy that judges durable state of the agent's own (a cart). */
-  policyExtension?(ctx: { agentDir: string; manifest: LoadedManifest; guardrails: Guardrails; store: StateStore }): PolicyExtension | undefined;
+  policyExtension?(ctx: { agentDir: string; manifest: LoadedManifest; guardrails: Guardrails; store: StateStore; locale: () => Locale }): PolicyExtension | undefined;
   /** The console lines that describe one execution. */
   describeExecution(execution: Execution, setup: Setup): string[];
   /** The `--json` body of a one-shot. */
   oneShotPayload(ctx: OneShotContext): Record<string, unknown>;
   /** `await-payer` only: what the payer reads when a receivable becomes payable. */
-  presentInstrument?(execution: Execution, instalment: number, chargeId: string, instrument: ChargeInstrument, tell: (line: string) => void): void;
+  presentInstrument?(execution: Execution, instalment: number, chargeId: string, instrument: ChargeInstrument, tell: (line: string) => void, locale: Locale): void;
   /** `await-payer` only: the one message per outcome the counterparty receives. */
   announceOutcome?(execution: Execution, setup: Setup, tell: (line: string) => void): boolean;
   /**
@@ -189,12 +210,13 @@ export interface AgentKit {
    * close on, or it cannot tell the person at all.
    *
    * The name must be one the agent declares in
-   * `channels/whatsapp/templates.json`; the language is the registry's and is
-   * not repeated here. `undefined` means this agent has no approved copy for
+   * `channels/whatsapp/templates.json`; the language is the conversation's
+   * locale's, and the registry declares every template in each. `locale` is
+   * there for the variables, which are display text too (a formatted total). `undefined` means this agent has no approved copy for
    * that outcome, which the caller REPORTS rather than papers over: a person
    * who was not told was not told.
    */
-  outcomeTemplate?(execution: Execution): { template: string; variables: string[] } | undefined;
+  outcomeTemplate?(execution: Execution, locale: Locale): { template: string; variables: string[] } | undefined;
   /**
    * Work that FOLLOWS an outcome and is not part of it: a sale's service
    * invoice once the order is `settled`. Runs after `announceOutcome`,

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

@@ -0,0 +1,118 @@
+/**
+ * What a run did, counted from what the engine holds and not from what the
+ * model said. A reply is the model's (or a recording's) and may claim a
+ * payroll ran when every line was already paid or every line failed; this is
+ * the line the terminal prints after it, and the one-shot's exit code.
+ *
+ * The unit is the payment, not the execution: an execution that paid three
+ * bills and failed the fourth closes `failed`, and counts three settled and
+ * one failed.
+ */
+import { isDeclinedReason, isTerminal, type CoreStrings, type Execution, type ExecutionEngine, type NotRunLine, type StateStore } from "@codespar/agent-core";
+
+export interface RunOutcome {
+  /** Payments this run settled. */
+  settled: number;
+  /** Payments the rail failed, executions that failed before any, and lines refused before a draft existed. */
+  failed: number;
+  /** Denied or expired, or closed by a declined reason (`isDeclinedReason`): somebody said no, or nobody answered or paid in time. */
+  declined: number;
+  /** Payments an earlier run already made: skipped here, or answered by the API with the earlier payment. */
+  already_paid: number;
+  /** Executions not yet terminal, plus lines an earlier execution still holds. */
+  open: number;
+}
+
+/** A request the engine refused before a draft existed (`execution.refused_before_draft`): the gate's own reason and detail. */
+export interface DraftRefusal {
+  reason: string;
+  detail: string;
+}
+
+/**
+ * Every refusal before a draft the engine recorded for this run, in order,
+ * for the sentence on the terminal and for `--json`. It is NOT what the count
+ * is taken from: each tool reports its refused request through `onNotRun`,
+ * and that is the one source of the count.
+ */
+export function draftRefusals(store: StateStore, runId: string): DraftRefusal[] {
+  return store
+    .listEvents({ run_id: runId })
+    .filter((e) => e.type === "execution.refused_before_draft")
+    .map((e) => {
+      const payload = e.payload as { reason?: unknown; detail?: unknown };
+      return { reason: String(payload.reason ?? "unknown"), detail: String(payload.detail ?? "") };
+    });
+}
+
+export function refusalLine(refusal: DraftRefusal): string {
+  return `  -> refused_before_draft (${refusal.reason}): ${refusal.detail}`;
+}
+
+export function runOutcome(executions: readonly Execution[], notRun: readonly NotRunLine[]): RunOutcome {
+  const out: RunOutcome = { settled: 0, failed: 0, declined: 0, already_paid: 0, open: 0 };
+  for (const e of executions) {
+    if (!isTerminal(e.state)) out.open += 1;
+    else if (e.state === "denied" || e.state === "expired") out.declined += 1;
+    // Closed with no attempt on record: the execution is the one thing to count.
+    else if (e.outcomes.length === 0) out[e.state === "settled" ? "settled" : isDeclinedReason(e.reason) ? "declined" : "failed"] += 1;
+    else {
+      for (const o of e.outcomes) {
+        if (o.status === "settled") out[o.replayed === true ? "already_paid" : "settled"] += 1;
+        else if (o.status === "failed") out[isDeclinedReason(o.code) ? "declined" : "failed"] += 1;
+        else out.open += 1;
+      }
+    }
+  }
+  for (const line of notRun) {
+    if (line.why === "already_settled") out.already_paid += 1;
+    else if (line.why === "refused") out.failed += 1;
+    else out.open += 1;
+  }
+  return out;
+}
+
+export function outcomeLine(text: CoreStrings, outcome: RunOutcome): string {
+  return text.runOutcome(outcome.settled, outcome.failed, outcome.declined, outcome.already_paid, outcome.open);
+}
+
+/** The executions of one run as the engine holds them now, each once. */
+export function runExecutions(engine: ExecutionEngine, runId: string): Execution[] {
+  const byId = new Map<string, Execution>();
+  for (const e of engine.list()) if (e.run_id === runId) byId.set(e.id, e);
+  return [...byId.values()];
+}
+
+/**
+ * The one place the terminal and the one-shot count a run: the engine's
+ * executions of this run plus the lines that created none. The refusals
+ * before a draft come back with it, to be said and listed. `say`, when given,
+ * receives the count line.
+ */
+export function sayOutcome(
+  source: { engine: ExecutionEngine; store: StateStore; runId: string; coreStrings: CoreStrings },
+  notRun: readonly NotRunLine[],
+  say?: (line: string) => void,
+): { executions: Execution[]; refusals: DraftRefusal[]; outcome: RunOutcome; line: string } {
+  const executions = runExecutions(source.engine, source.runId);
+  const refusals = draftRefusals(source.store, source.runId);
+  const outcome = runOutcome(executions, notRun);
+  const line = outcomeLine(source.coreStrings, outcome);
+  say?.(line);
+  return { executions, refusals, outcome, line };
+}
+
+/**
+ * The one-shot's exit code. 1 when a payment failed or a line was refused
+ * before a draft, and it wins over 3: a run that failed something and left
+ * something else `executing` is a failed run, and the line still counts what
+ * is open. 3 when nothing failed and an execution OF THIS RUN was left
+ * `executing`, whose outcome the rail did not say. 0 otherwise: settled,
+ * already paid, still open, and also denied or expired, which are the agent
+ * doing its job and are named on the line. A line an earlier run still holds
+ * (`in_progress`) is open and exits 0: this run left nothing behind.
+ */
+export function outcomeExitCode(outcome: RunOutcome, executions: readonly Execution[] = []): 0 | 1 | 3 {
+  if (outcome.failed > 0) return 1;
+  return executions.some((e) => e.state === "executing") ? 3 : 0;
+}

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

@@ -30,9 +30,8 @@ export interface PollOptions extends PollHooks {
   timeoutMs: number;
   /** Cap on looks, for a zero-interval (stub) loop: the fixture payer acts within two looks; a third proves nothing changes. */
   maxRounds?: number;
-  /** When set, the payer plays once every instalment is payable, or after `payerAfterRounds` looks (a scenario, `--simulate-payer`). */
+  /** When set, the payer plays once every instalment is payable (a scenario, `--simulate-payer`), and never before. */
   payer?: SandboxPayer | undefined;
-  payerAfterRounds?: number;
   clock?: () => Date;
   sleep?: (ms: number) => Promise<void>;
 }
@@ -85,13 +84,14 @@ export async function pollUntilClosed(engine: ExecutionEngine, executionId: stri
     rounds += 1;
     execution = await engine.reconcile(execution.id);
     await present(execution);
-    // The sandbox payer plays once every receivable is payable (the QR was shown first, as in the scene), or after a few looks if the
-    // clearing house is still registering: the API's test route settles a PROCESSING charge too, and on the shared sandbox the
-    // registration can take minutes. A real payer is not this hook.
+    // The sandbox payer plays once every receivable is payable, the QR shown first, as in the scene, and never before. It used to
+    // play after a few looks whatever it found, because the API's test route settles a charge still registering; on staging on
+    // 2026-09-27 that route settled a charge the issuer had ended in ERROR, with no QR at all, and the scenario called the order
+    // settled (OPEN_QUESTIONS §63, ent#1816). A payer can only pay what it can see, so a registration that never ends payable
+    // leaves the order open until the wait runs out, or closes it with the issuer's own failure.
     const issued = execution.outcomes.filter((o) => o.status === "accepted" && o.transaction_id);
     const allPayable = issued.length > 0 && issued.every((o) => o.instrument?.payable);
-    const patienceOver = rounds >= (options.payerAfterRounds ?? 5);
-    if (options.payer && !paidRequested && execution.state === "executing" && issued.length > 0 && issued.length === execution.outcomes.filter((o) => o.status === "accepted").length && (allPayable || patienceOver)) {
+    if (options.payer && !paidRequested && execution.state === "executing" && issued.length > 0 && issued.length === execution.outcomes.filter((o) => o.status === "accepted").length && allPayable) {
       paidRequested = true;
       for (const outcome of issued) {
         const result = await options.payer.pay(outcome.transaction_id!, outcome.attempt_id);

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

@@ -0,0 +1,51 @@
+/**
+ * Where a run's proof bundle lives. A run a person made (`npm start`, a
+ * scenario pack run by name) is `runs/<run-id>`. `npm run eval` writes dozens
+ * per pass, and they used to land beside the person's own, so the folder a
+ * person looks in was mostly the suite's. They go to `runs/eval/<run-id>`.
+ *
+ * A run id is still all `inspect` and `rerun` take: an eval run is found by
+ * its id alone, and `eval/<run-id>` is accepted too.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { ProofBundle } from "@codespar/agent-core";
+import type { Agent } from "./agent.js";
+import { runsDir } from "./setup.js";
+
+/** The folder name under `runs/` that holds what the eval suite wrote. Never a run id: every run id starts with `run_`. */
+export const EVAL_RUNS = "eval";
+
+export function evalRunsDir(agent: Agent, env: NodeJS.ProcessEnv = process.env): string {
+  return join(runsDir(agent, env), EVAL_RUNS);
+}
+
+/** The bundle of a run by its id, a person's or the eval suite's, and the folder it was found in. */
+export function openRun(agent: Agent, runId: string, env: NodeJS.ProcessEnv = process.env): { bundle: ProofBundle; runsDir: string } | undefined {
+  const own = runsDir(agent, env);
+  const id = runId.startsWith(`${EVAL_RUNS}/`) ? runId.slice(EVAL_RUNS.length + 1) : runId;
+  // The folder itself is not a run, and neither is a path that climbs out of the runs folder.
+  if (id === "" || id === EVAL_RUNS || id.includes("/") || id.includes("\\") || id === "." || id === "..") return undefined;
+  for (const dir of runId === id ? [own, evalRunsDir(agent, env)] : [evalRunsDir(agent, env)]) {
+    const bundle = ProofBundle.open(dir, id);
+    if (bundle) return { bundle, runsDir: dir };
+  }
+  return undefined;
+}
+
+/** Run ids in a folder, newest first. Run ids start with a timestamp or a case name, so the order is by name. */
+function idsIn(dir: string): string[] {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && e.name !== EVAL_RUNS)
+    .map((e) => e.name)
+    .sort()
+    .reverse();
+}
+
+/** The runs a person made, and how many the eval suite left beside them. */
+export function listRuns(agent: Agent, env: NodeJS.ProcessEnv = process.env): { dir: string; ids: string[]; evalDir: string; evalCount: number } {
+  const dir = runsDir(agent, env);
+  const evalDir = evalRunsDir(agent, env);
+  return { dir, ids: idsIn(dir), evalDir, evalCount: idsIn(evalDir).length };
+}