@codespar/cli 0.14.0 → 0.16.0

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

@@ -1,12 +1,14 @@
 /**
  * `npm run check`: the manifest is the index, and the files it points to
  * must agree with it. Fails on a contradiction between `agent.yaml` and
- * `SYSTEM_PROMPT.md`, `tools.json` or `guardrails.json`, on `AGENTS.md`
- * and `CLAUDE.md` diverging, and on a missing `mcp`, `cli` or `schema`.
+ * `SYSTEM_PROMPT.md`, `tools.json`, `guardrails.json` or `channels/`, on
+ * `AGENTS.md` and `CLAUDE.md` diverging, and on a missing `mcp`, `cli` or
+ * `schema`.
  */
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { parse as parseYaml } from "yaml";
+import { ConversationScriptSchema, TemplateRegistrySchema, TEMPLATE_REGISTRY_FILE, templateArity } from "./channels.js";
 import { GuardrailsSchema } from "./guardrails.js";
 import { loadManifest, ManifestSchema, type LoadedManifest } from "./manifest.js";
 import { MandateSchema } from "./mandate.js";
@@ -58,6 +60,9 @@ export function checkAgent(agentDir: string): CheckReport {
 
   // tools.json
   let toolNames: string[] = [];
+  // Hoisted: the receipt-verification rule below needs it, and only a payment
+  // seals a receipt.
+  let hasPayment = false;
   const toolsPath = loaded.resolvePath(manifest.tools);
   if (!existsSync(toolsPath)) error("tools_missing", `${manifest.tools} does not exist`);
   else {
@@ -65,7 +70,7 @@ export function checkAgent(agentDir: string): CheckReport {
     if (!parsed.success) error("tools_invalid", parsed.error.message);
     else {
       toolNames = [...parsed.data.meta_tools, ...parsed.data.local_tools].map((t) => t.name);
-      const hasPayment = parsed.data.meta_tools.some((t) => t.effect === "payment");
+      hasPayment = parsed.data.meta_tools.some((t) => t.effect === "payment");
       const declaresPixOut = manifest.maturity["pix-out"] !== undefined;
       if (declaresPixOut && !hasPayment) error("tools_contradict_manifest", "agent.yaml declares pix-out maturity but tools.json has no payment meta-tool");
       if (!declaresPixOut && hasPayment) error("tools_contradict_manifest", "tools.json has a payment meta-tool but agent.yaml declares no pix-out maturity");
@@ -92,6 +97,55 @@ export function checkAgent(agentDir: string): CheckReport {
     }
   }
 
+  // channels: the declaration and what the agent ships, checked BOTH ways.
+  //
+  // A channel is the runner's, but the conversations are the agent's, so
+  // `channels: [terminal, whatsapp]` is a claim about files. Declaring
+  // whatsapp without shipping a conversation gives a reader a channel that
+  // cannot be driven; shipping one without declaring it hides a surface the
+  // agent answers on. Both are errors, and a script that no longer parses is
+  // one too, because the simulator and this check read the same schema.
+  if (!manifest.channels.includes("terminal")) {
+    error("channels_terminal_missing", "agent.yaml must declare the terminal channel: `npm start` opens it and it needs no account");
+  }
+  // `templates.json` is the one file in there that is NOT a conversation: it
+  // is the local registry of the templates the agent declares it sends, which
+  // is what makes "this name was never registered here" a refusal the channel
+  // can make instead of a 400 from Meta. A conversation therefore cannot be
+  // called `templates`, and this is the only place that says so.
+  const whatsappDir = join(agentDir, "channels", "whatsapp");
+  const scripts = existsSync(whatsappDir) ? readdirSync(whatsappDir).filter((f) => f.endsWith(".json") && f !== TEMPLATE_REGISTRY_FILE).sort() : [];
+  if (manifest.channels.includes("whatsapp") && scripts.length === 0) {
+    error("channels_not_shipped", "agent.yaml declares the whatsapp channel but channels/whatsapp/ ships no conversation for the simulator to drive");
+  }
+  if (!manifest.channels.includes("whatsapp") && scripts.length > 0) {
+    error("channels_undeclared", `channels/whatsapp/ ships ${scripts.length} conversation(s) but agent.yaml does not declare the whatsapp channel`);
+  }
+  for (const file of scripts) {
+    const parsed = ConversationScriptSchema.safeParse(JSON.parse(readFileSync(join(whatsappDir, file), "utf8")));
+    if (!parsed.success) error("channels_script_invalid", `channels/whatsapp/${file}: ${parsed.error.message}`);
+    else if (parsed.data.name !== file.replace(/\.json$/, "")) error("channels_script_invalid", `channels/whatsapp/${file} declares name ${parsed.data.name}`);
+  }
+  const registryPath = join(whatsappDir, TEMPLATE_REGISTRY_FILE);
+  if (existsSync(registryPath)) {
+    const parsed = TemplateRegistrySchema.safeParse(JSON.parse(readFileSync(registryPath, "utf8")));
+    if (!parsed.success) error("channels_templates_invalid", `channels/whatsapp/${TEMPLATE_REGISTRY_FILE}: ${parsed.error.message}`);
+    else {
+      // A body with no placeholder takes no variables, and one with `{{3}}`
+      // and no `{{2}}` cannot be filled: Meta numbers them from 1 without
+      // gaps, and a send that skips one is a 132000 nobody sees until the
+      // first real message goes out.
+      for (const template of parsed.data.templates) {
+        const arity = templateArity(template.body);
+        for (let n = 1; n <= arity; n += 1) {
+          if (!new RegExp(`\\{\\{\\s*${n}\\s*\\}\\}`).test(template.body)) {
+            error("channels_templates_invalid", `channels/whatsapp/${TEMPLATE_REGISTRY_FILE}: ${template.name} uses {{${arity}}} but never {{${n}}}; Meta numbers variables from 1 with no gaps`);
+          }
+        }
+      }
+    }
+  }
+
   // mandate.example.json
   const mandatePath = loaded.resolvePath(manifest.mandate_schema);
   if (!existsSync(mandatePath)) error("mandate_missing", `${manifest.mandate_schema} does not exist`);
@@ -139,7 +193,23 @@ export function checkAgent(agentDir: string): CheckReport {
     }
   }
 
-  // Wording the README must not carry (section 6).
+  // Wording the docs must not carry UNQUALIFIED (section 6).
+  //
+  // Until ent#1633 the phrase was forbidden outright, because nothing in the
+  // product supported it. A receipt sealed since then carries an Ed25519
+  // signature over `codespar-receipt:v1:<id>:<chain>` that anybody can check
+  // against the published key set, so the claim is now true — of that, and of
+  // nothing else here. Every receipt sealed BEFORE the change carries no such
+  // signature and never will, and the approval artifact is still HMAC with a
+  // local development key.
+  //
+  // So the rule is no longer "never write it". It is two conditions, and an
+  // agent has to meet both. The agent must actually MINT a receipt that
+  // carries the seal — only a payment does, and `maturity` is where the agent
+  // says so — and the doc must NAME the mechanism, which is the word that
+  // tells a reader which of the two claims is being made.
+  const verificationMaturity = manifest.maturity["receipt-verification"];
+  const sealsVerifiableReceipts = hasPayment && verificationMaturity !== undefined && verificationMaturity !== "blocked";
   for (const file of ["README.md", "runbook.md", "SYSTEM_PROMPT.md"]) {
     const path = join(agentDir, file);
     if (!existsSync(path)) {
@@ -147,8 +217,12 @@ export function checkAgent(agentDir: string): CheckReport {
       continue;
     }
     const text = readFileSync(path, "utf8").toLowerCase();
-    if (text.includes("verificável por terceiro") || text.includes("verifiable by a third party") || text.includes("third-party verifiable")) {
-      error("doc_overclaims", `${file} claims third-party verifiability; the receipt is HMAC until Ed25519`);
+    const claims = text.includes("verificável por terceiro") || text.includes("verifiable by a third party") || text.includes("third-party verifiable");
+    if (!claims) continue;
+    if (!sealsVerifiableReceipts) {
+      error("doc_overclaims", `${file} claims third-party verifiability, and this agent seals nothing that carries it: only a payment receipt gets an Ed25519 signature, and agent.yaml declares receipt-verification as \`${verificationMaturity ?? "absent"}\``);
+    } else if (!text.includes("ed25519")) {
+      error("doc_overclaims", `${file} claims third-party verifiability without naming Ed25519; the receipt's asymmetric seal is the only thing here a third party can check, and receipts sealed before it — and the approval artifact — are HMAC`);
     }
   }
 
@@ -165,7 +239,15 @@ export function checkAgent(agentDir: string): CheckReport {
     if (!keys.includes("CODESPAR_API_KEY") || !keys.includes("ANTHROPIC_API_KEY")) error("env_example_incomplete", ".env.example must declare CODESPAR_API_KEY and ANTHROPIC_API_KEY");
   }
 
-  if (manifest.maturity["receipt-verification"] === "live") warning("maturity_overclaims", "receipt-verification cannot be live before Ed25519");
+  // `receipt-verification` used to be a warning at `live`, because Ed25519 did
+  // not exist. It does (ent#1633), so what is left to check is the coherence
+  // the other maturity rules check: only a PAYMENT seals a receipt. A paid
+  // charge is reported by the API with no chain and no signature, so an agent
+  // that issues receivables and declares this capability beyond `blocked` is
+  // claiming a verification its records cannot carry.
+  if (verificationMaturity !== undefined && verificationMaturity !== "blocked" && !hasPayment) {
+    error("maturity_overclaims", "agent.yaml declares receipt-verification beyond `blocked` and tools.json has no payment meta-tool; only a payment seals a receipt, and a paid charge carries no signature to verify");
+  }
 
   return { ok: findings.every((f) => f.level !== "error"), agent: manifest.name, findings };
 }

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

@@ -0,0 +1,42 @@
+/**
+ * A clock pinned to an instant the caller chose, for a run whose outcome must
+ * not depend on the hour it happens to execute at (the CI, a demo, a test).
+ * `ExecutionEngine`, the stubs, the status gate and the loop all take a
+ * `clock` dependency; this is the one the one-shot runner hands them when
+ * `--now` or `CODESPAR_AGENT_NOW` is set. The scenario runner freezes its own
+ * clock the same way.
+ *
+ * The clock advances one second per read so no two events share an instant,
+ * which is what the scenario runner does too.
+ */
+
+export const FIXED_CLOCK_ENV = "CODESPAR_AGENT_NOW";
+
+export class InvalidFixedClockError extends Error {
+  constructor(value: string, source: string) {
+    super(`${source} must be an ISO 8601 instant (e.g. 2026-09-23T14:00:00-03:00), got "${value}"`);
+    this.name = "InvalidFixedClockError";
+  }
+}
+
+/** A clock that starts at `iso` and ticks one second per read. Throws on a value `Date` cannot parse. */
+export function fixedClock(iso: string, source = "--now"): () => Date {
+  const start = new Date(iso);
+  if (!/^\d{4}-\d{2}-\d{2}T/.test(iso.trim()) || Number.isNaN(start.getTime())) throw new InvalidFixedClockError(iso, source);
+  let current = start.getTime() - 1000;
+  return () => {
+    current += 1000;
+    return new Date(current);
+  };
+}
+
+/**
+ * The clock a command runs with: the `--now` flag, else `CODESPAR_AGENT_NOW`
+ * from the environment, else `undefined` (the wall clock, the caller's default).
+ */
+export function resolveFixedClock(flag: string | undefined, env: NodeJS.ProcessEnv = process.env): (() => Date) | undefined {
+  if (flag !== undefined) return fixedClock(flag, "--now");
+  const fromEnv = env[FIXED_CLOCK_ENV];
+  if (fromEnv !== undefined && fromEnv.trim() !== "") return fixedClock(fromEnv, FIXED_CLOCK_ENV);
+  return undefined;
+}

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

@@ -20,11 +20,11 @@ import { itemsHash, sha256Hex } from "./hash.js";
 import { newId } from "./ids.js";
 import { mandateExpired, payeeAllowed, resolveBeneficiary, windowCap, windowStart, type Mandate } from "./mandate.js";
 import type { Manifest } from "./manifest.js";
-import type { PaymentRail, RailPayment } from "./rail.js";
+import type { PaymentRail, RailOutcome, RailPayment } from "./rail.js";
 import type { MandateStatusReport, MandateStatusSource } from "./revocation.js";
 import { isTerminal, transition, type Execution, type ExecutionState } from "./state-machine.js";
 import type { StateStore } from "./state/store.js";
-import type { Actor, ApprovalArtifact, ApprovalMode, ExecutionItem, ExecutionReason, ItemOutcome } from "./types.js";
+import type { Actor, ApprovalArtifact, ApprovalMode, ExecutionBatch, ExecutionItem, ExecutionReason, ItemOutcome } from "./types.js";
 
 export interface ProposedItem {
   /** An alias from the mandate's named payees, or a raw payee key. */
@@ -54,6 +54,13 @@ export interface Proposal {
   items: ProposedItem[];
   /** What the model said the total was. Recorded; never used to pay. */
   claimed_total?: number;
+  /**
+   * The batch this proposal is one line of, when it is one. The kit computes
+   * it once over the whole ordered list before drafting any of it; the core
+   * stamps it on the execution and every artifact of that execution carries
+   * it. The core never invents one and never fills one in.
+   */
+  batch?: ExecutionBatch;
 }
 
 export type DraftResult =
@@ -119,6 +126,7 @@ export class ExecutionEngine {
 
     const items = proposal.items.map((p) => this.resolveItem(p));
     const total = items.reduce((sum, i) => sum + i.amount, 0);
+    if (proposal.batch) assertBatchBinding(proposal.batch);
     const id = newId("exe");
     const execution: Execution<"drafted"> = {
       id,
@@ -131,6 +139,7 @@ export class ExecutionEngine {
       currency: this.deps.mandate.currency,
       ...(proposal.claimed_total !== undefined ? { model_claimed_total: proposal.claimed_total } : {}),
       items_hash: itemsHash(items),
+      ...(proposal.batch ? { batch: proposal.batch } : {}),
       mandate: { id: this.deps.mandate.id, version: this.deps.mandate.version },
       idempotency_key: `idk_${sha256Hex(`${this.deps.runId}:${id}`).slice(0, 32)}`,
       blocking_reasons: [],
@@ -140,7 +149,7 @@ export class ExecutionEngine {
       updated_at: now.toISOString(),
     };
     this.deps.store.saveExecution(execution);
-    this.record("execution.drafted", id, { items: execution.items, total, model_claimed_total: proposal.claimed_total ?? null, mode: this.deps.mode });
+    this.record("execution.drafted", id, { items: execution.items, total, model_claimed_total: proposal.claimed_total ?? null, mode: this.deps.mode, batch: execution.batch ?? null });
 
     return { ok: true, execution: await this.evaluateDraft(execution) };
   }
@@ -333,20 +342,26 @@ export class ExecutionEngine {
    */
   private async dispatch(execution: Execution<"executing">, payments: RailPayment[]): Promise<Execution> {
     const outcomes: ItemOutcome[] = [...execution.outcomes];
+    const unknown: string[] = [];
     this.deps.store.updateOutbox(execution.idempotency_key, "sent", undefined, this.clock().toISOString());
 
     for (const [index, payment] of payments.entries()) {
       if (outcomes.some((o) => o.index === index)) continue;
-      this.record("rail.dispatch", execution.id, { attempt_id: payment.attempt_id, payee: payment.payee, amount: payment.amount_minor, rail: this.deps.rail.name });
+      // The dispatch line is the request. `idempotency_key` is what makes a retry the same payment, so the bundle names it next to the attempt.
+      this.record("rail.dispatch", execution.id, { attempt_id: payment.attempt_id, payee: payment.payee, amount: payment.amount_minor, rail: this.deps.rail.name, idempotency_key: execution.idempotency_key });
       const outcome = await this.deps.rail.pay(payment);
-      this.record("rail.outcome", execution.id, { attempt_id: payment.attempt_id, status: outcome.status, ...(outcome.status === "failed" || outcome.status === "uncertain" ? { code: outcome.code } : {}) });
+      this.record("rail.outcome", execution.id, { attempt_id: payment.attempt_id, status: outcome.status, ...railAnswer(outcome) });
       if (outcome.status === "uncertain") {
         this.record("rail.uncertain", execution.id, { attempt_id: payment.attempt_id, code: outcome.code, message: outcome.message });
-        return this.leaveUnresolved({ ...execution, outcomes }, `attempt ${payment.attempt_id}: ${outcome.code} — outcome unknown, kept for reconciliation`);
+        // No outcome is recorded because there is none. The siblings are still
+        // sent: an unknown answer about THIS payee says nothing about the next
+        // one, and the execution stays open until reconciliation settles it.
+        unknown.push(`attempt ${payment.attempt_id}: ${outcome.code} — outcome unknown, kept for reconciliation`);
+        continue;
       }
       if (outcome.status === "failed") {
         outcomes.push({ index, attempt_id: payment.attempt_id, status: "failed", code: outcome.code, error: `${outcome.code}: ${outcome.message}` });
-        break;
+        continue;
       }
       if (outcome.status === "accepted") {
         // A receivable was issued; the payer decides the rest. Nothing settles here.
@@ -357,21 +372,29 @@ export class ExecutionEngine {
       outcomes.push({ index, attempt_id: payment.attempt_id, status: "settled", transaction_id: outcome.transaction_id, ...(outcome.receipt_id ? { receipt_id: outcome.receipt_id } : {}) });
       await this.ingestSettlement(execution, index, payment, outcome.receipt_id, PAYMENT_SUCCEEDED);
     }
-    return this.close({ ...execution, outcomes }, payments.length);
+    return this.close({ ...execution, outcomes }, payments.length, unknown.join("; ") || undefined);
   }
 
   /**
    * Closes an `executing` execution from its recorded outcomes: stays while a
-   * receivable is accepted and unpaid, failed if any attempt failed, settled
-   * when every attempt settled, otherwise unresolved.
+   * receivable is accepted and unpaid, stays while any attempt has no outcome
+   * at all, failed if any attempt failed, settled when every attempt settled.
+   *
+   * The order matters. An execution does not close while one of its attempts
+   * is unknown, even when another one failed: "some of this moved and one of
+   * them we cannot see" is not a closed outcome, and closing it as `failed`
+   * would report a batch as finished while a payment may still be in flight.
    */
-  private close(execution: Execution<"executing">, attempts: number): Execution {
+  private close(execution: Execution<"executing">, attempts: number, unknownDetail?: string): Execution {
     const at = this.clock().toISOString();
     const updated: Execution<"executing"> = { ...execution, updated_at: at };
     const accepted = execution.outcomes.filter((o) => o.status === "accepted");
     if (accepted.length > 0) {
       return this.leaveAwaiting(updated, `${accepted.length} receivable(s) issued and unpaid: ${accepted.map((o) => o.transaction_id ?? o.attempt_id).join(", ")}`);
     }
+    if (execution.outcomes.length < attempts) {
+      return this.leaveUnresolved(updated, unknownDetail ?? `${execution.outcomes.length} of ${attempts} attempt(s) have an outcome`);
+    }
     const failed = execution.outcomes.find((o) => o.status === "failed");
     if (failed) {
       this.deps.store.updateOutbox(execution.idempotency_key, "failed", execution.outcomes, at);
@@ -438,6 +461,7 @@ export class ExecutionEngine {
     }
   }
 
+
   /**
    * Fetches into the bundle the receipts of settled attempts the bundle does
    * not hold yet (a settlement that arrived by event names a receipt id and
@@ -480,7 +504,7 @@ export class ExecutionEngine {
       const prior = outcomes.find((o) => o.index === index);
       // Settled and failed are final. An accepted receivable is looked at again: its payer may have acted.
       if (prior && prior.status !== "accepted") continue;
-      const seen = await this.deps.rail.lookup(payment.attempt_id, payment);
+      const seen = await this.deps.rail.lookup(payment.attempt_id, payment, prior?.transaction_id);
       const found = seen ? seen.status : "absent";
       const stored = this.deps.store.appendEvent({
         run_id: this.deps.runId,
@@ -494,8 +518,12 @@ export class ExecutionEngine {
       if (stored) this.deps.bundle.event({ ...stored, actor: this.agentActor });
       if (!seen || seen.status === "uncertain" || seen.status === "in_flight") {
         if (prior) continue; // the receivable is known to exist; the rail just did not answer this time
-        unresolved = `attempt ${payment.attempt_id}: ${seen ? seen.status : "unknown to the rail"}; a human decides, nothing is re-sent`;
-        break;
+        // One attempt the rail cannot answer for does not stop us learning
+        // about the others. A lookup moves no money, so there is nothing to
+        // be careful about here, and stopping would mean a later attempt's
+        // settlement is never recorded at all.
+        unresolved ??= `attempt ${payment.attempt_id}: ${seen ? seen.status : "unknown to the rail"}; a human decides, nothing is re-sent`;
+        continue;
       }
       const replace = (outcome: ItemOutcome) => {
         const at = outcomes.findIndex((o) => o.index === index);
@@ -509,7 +537,6 @@ export class ExecutionEngine {
       }
       if (seen.status === "failed") {
         replace({ index, attempt_id: payment.attempt_id, status: "failed", code: seen.code, error: `${seen.code}: ${seen.message}` });
-        if (!prior) break;
         continue;
       }
       replace({ index, attempt_id: payment.attempt_id, status: "settled", transaction_id: seen.transaction_id, ...(seen.receipt_id ? { receipt_id: seen.receipt_id } : {}) });
@@ -643,6 +670,27 @@ export class ExecutionEngine {
     return true;
   }
 
+  /**
+   * A durable claim for work whose unit is bigger than one execution: a batch
+   * line, a scheduled instruction. `claimed` reads which execution covers a
+   * key, `claim` records it. Same cursor table as `markShown`, which is this
+   * with a boolean answer.
+   *
+   * It exists because a tool handler's only durable surface is this engine,
+   * and a batch that must not pay the same payee twice across runs has to
+   * remember which execution already covers each line. What a held claim
+   * MEANS is the kit's to decide: the engine records the pairing and reads
+   * nothing into it, because "settled, so skip" and "denied, so retry" are
+   * the batch's rules and not the state machine's.
+   */
+  claimed(key: string): string | undefined {
+    return this.deps.store.getCursor(`claim:${key}`);
+  }
+
+  claim(key: string, executionId: string): void {
+    this.deps.store.setCursor(`claim:${key}`, executionId);
+  }
+
   // ---- reads --------------------------------------------------------------
 
   get(executionId: string): Execution | undefined {
@@ -653,6 +701,22 @@ export class ExecutionEngine {
     return this.deps.store.listExecutions({ ...filter, mandate_id: this.deps.mandate.id });
   }
 
+  /**
+   * The items `draft()` would build from these proposals, resolved against
+   * the mandate and WITHOUT the validation that refuses one. It exists for a
+   * caller that must hash a whole list before it drafts any of it — a batch
+   * computing its `batch_hash` — and it does not throw on purpose: a line the
+   * core will refuse is still a line of the presented list, and dropping it
+   * from the hash would make a batch holding a broken line hash the same as
+   * the shorter batch without it, which is the hole `batch_hash` closes.
+   *
+   * It resolves nothing the draft will not resolve identically, which is what
+   * makes the hash computed here the hash the drafts below carry.
+   */
+  preview(items: readonly ProposedItem[]): ExecutionItem[] {
+    return items.map((p) => this.previewItem(p));
+  }
+
   // ---- helpers ------------------------------------------------------------
 
   /**
@@ -687,15 +751,19 @@ export class ExecutionEngine {
   }
 
   private resolveItem(proposed: ProposedItem): ExecutionItem {
-    const known = resolveBeneficiary(this.deps.mandate, proposed.payee);
     const amount = Math.trunc(proposed.amount);
     if (!Number.isFinite(amount) || amount <= 0) throw new Error(`amount must be a positive integer in minor units, got ${proposed.amount}`);
     if (proposed.due_date !== undefined && !/^\d{4}-\d{2}-\d{2}$/.test(proposed.due_date)) throw new Error(`due_date must be YYYY-MM-DD, got ${proposed.due_date}`);
+    return this.previewItem(proposed);
+  }
+
+  private previewItem(proposed: ProposedItem): ExecutionItem {
+    const known = resolveBeneficiary(this.deps.mandate, proposed.payee);
     return {
       ...(known ? { alias: known.alias } : {}),
       beneficiary: known?.name ?? proposed.payee,
       payee: known?.payee ?? proposed.payee,
-      amount,
+      amount: Math.trunc(proposed.amount),
       currency: this.deps.mandate.currency,
       ...(proposed.description ? { description: proposed.description } : {}),
       ...(proposed.due_date ? { due_date: proposed.due_date } : {}),
@@ -712,6 +780,7 @@ export class ExecutionEngine {
       beneficiary: item.beneficiary,
       purpose: this.deps.mandate.purpose,
       agent_id: this.deps.mandate.agent_id,
+      consumer_id: this.deps.mandate.consumer_id,
       ...(item.description ? { description: item.description } : {}),
       ...(item.due_date ? { due_date: item.due_date } : {}),
       actor: this.agentActor,
@@ -758,7 +827,7 @@ export class ExecutionEngine {
   private storeApproval(artifact: ApprovalArtifact): void {
     this.deps.store.saveApproval(artifact);
     this.deps.bundle.approval(artifact);
-    this.record("approval.created", artifact.execution_id, { approval_id: artifact.approval_id, approver: artifact.approver, items_hash: artifact.items_hash, escalation: artifact.escalation ?? null });
+    this.record("approval.created", artifact.execution_id, { approval_id: artifact.approval_id, approver: artifact.approver, items_hash: artifact.items_hash, batch: artifact.batch ?? null, escalation: artifact.escalation ?? null });
   }
 
   private persist<S extends ExecutionState>(execution: Execution<S>): Execution<S> {
@@ -782,3 +851,35 @@ export class ExecutionEngine {
     return execution;
   }
 }
+
+/**
+ * A batch binding is the kit's to compute and the core's to refuse when it
+ * cannot be true. `index` outside `count`, or a `count` of zero, would let a
+ * bundle say "line 5 of 3" and make the "N of M" an artifact reader sees
+ * meaningless, so it is rejected where the execution is minted rather than
+ * carried into the signature.
+ */
+function assertBatchBinding(batch: ExecutionBatch): void {
+  if (!batch.ref.trim()) throw new Error("batch.ref must name the batch");
+  if (!batch.batch_hash.trim()) throw new Error("batch.batch_hash must be the hash of the presented lines");
+  if (!Number.isInteger(batch.count) || batch.count < 1) throw new Error(`batch.count must be a positive integer, got ${batch.count}`);
+  if (!Number.isInteger(batch.index) || batch.index < 0 || batch.index >= batch.count) {
+    throw new Error(`batch.index must be a position inside the batch (0..${batch.count - 1}), got ${batch.index}`);
+  }
+}
+
+/**
+ * What the rail answered about one attempt, as the bundle records it: the
+ * identifiers a reader follows the money by, and never `raw`, which carries
+ * whatever the provider chose to echo back.
+ */
+function railAnswer(outcome: RailOutcome): Record<string, unknown> {
+  switch (outcome.status) {
+    case "accepted":
+      return { transaction_id: outcome.transaction_id, sandbox: outcome.sandbox };
+    case "settled":
+      return { transaction_id: outcome.transaction_id, receipt_id: outcome.receipt_id, money_moved: outcome.money_moved, sandbox: outcome.sandbox };
+    default:
+      return { code: outcome.code, message: outcome.message };
+  }
+}

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

@@ -39,6 +39,19 @@ export function itemsHash(items: readonly ExecutionItem[]): string {
   return `sha256:${sha256Hex(canonicalJson(canonical))}`;
 }
 
+/**
+ * The hash of a batch's ordered lines, bound into every artifact of that
+ * batch. It IS `itemsHash` over the whole list and deliberately not a second
+ * canonicalisation: the same fields decide the set that decide the line, so a
+ * reader who concatenates the batch's lines in order and hashes them gets the
+ * batch's hash back, and any line moved, re-priced, added or dropped changes
+ * it. Order is part of it — `index` names a position, and a position only
+ * means something in a list whose order is fixed.
+ */
+export function batchHash(lines: readonly ExecutionItem[]): string {
+  return itemsHash(lines);
+}
+
 export function hmacSha256Hex(key: Buffer, payload: string): string {
   return createHmac("sha256", key).update(payload).digest("hex");
 }

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

@@ -5,11 +5,14 @@ export * from "./ids.js";
 export * from "./approval.js";
 export * from "./manifest.js";
 export * from "./guardrails.js";
+export * from "./channels.js";
 export * from "./mandate.js";
 export * from "./escalate.js";
+export * from "./clock.js";
 export * from "./secrets.js";
 export * from "./revocation.js";
 export * from "./rail.js";
+export * from "./receipt-verification.js";
 export * from "./tools.js";
 export * from "./bundle.js";
 export * from "./engine.js";

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

@@ -34,7 +34,7 @@ export const ManifestSchema = z
     default_approval: z.enum(["human", "mandate"]),
     escalate_above: EscalateAboveSchema.optional(),
     mcp: z.string().regex(PINNED_PACKAGE, "mcp must pin an exact version, e.g. @codespar/mcp@0.5.8"),
-    cli: z.string().regex(PINNED_PACKAGE, "cli must pin an exact version, e.g. @codespar/cli@0.13.0"),
+    cli: z.string().regex(PINNED_PACKAGE, "cli must pin an exact version, e.g. @codespar/cli@0.14.0"),
     tools: z.string(),
     guardrails: z.string(),
     mandate_schema: z.string(),

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

@@ -15,6 +15,8 @@ export interface RailPayment {
   payee: string;
   purpose: string;
   agent_id: string;
+  /** The principal the agent acts for (the mandate's `consumer_id`). A receivable settles into THIS identity's account; `POST /v1/charges` needs it on the wire. */
+  consumer_id?: string;
   description?: string;
   /** Display name of the counterparty (a receivable's debtor). The rail that issues a charge needs it; a payout rail ignores it. */
   beneficiary?: string;
@@ -70,6 +72,14 @@ export interface RailReceipt {
   /** Null when the API seals nothing for this kind of record. */
   chain: string | null;
   receipt_sig: string | null;
+  /** The Ed25519 signature CodeSpar seals alongside the HMAC (base64url) and
+   *  the published key that made it. Null on a receipt sealed before the API
+   *  had the capability, on a record the API seals nothing for (a paid
+   *  charge), and on the stub rail, which is not CodeSpar and must not look
+   *  like it. Carried onto the bundle's copy so THAT copy is what a third
+   *  party checks: `npm run verify runs/<run-id>/receipts/<id>.json`. */
+  receipt_sig_ed25519: string | null;
+  receipt_sig_kid: string | null;
   /** Section 4.5: the kit stamps the actor onto the local copy of every receipt. */
   actor: Actor;
   raw: unknown;
@@ -81,7 +91,11 @@ export type RailLookup = RailOutcome | { status: "in_flight" } | undefined;
 export interface PaymentRail {
   readonly name: "stub" | "codespar" | "stub-charge" | "codespar-charge";
   pay(payment: RailPayment): Promise<RailOutcome>;
-  /** Answers the outcome of an attempt already presented, `in_flight` while the rail is still on it, or `undefined` when the rail never saw it. */
-  lookup(attemptId: string, payment: RailPayment): Promise<RailLookup>;
+  /**
+   * Answers the outcome of an attempt already presented, `in_flight` while the rail is still on it, or `undefined` when the rail
+   * never saw it. `transactionId` is the rail's own id for the attempt when the core recorded one (an accepted receivable): a rail
+   * whose read is keyed on its id and not on the caller's key looks it up by that.
+   */
+  lookup(attemptId: string, payment: RailPayment, transactionId?: string): Promise<RailLookup>;
   receipt(receiptId: string, actor: Actor): Promise<RailReceipt | undefined>;
 }