@codespar/cli 0.14.1 → 0.16.0

package/templates/bills-agent/packages/agent-core/src/api/sandbox-payer.ts

@@ -6,11 +6,15 @@
  * project's triggers, and every record it leaves carries `simulated: true`
  * plus `settled_against: "sandbox_fixture"`. No money moves anywhere. A
  * live-environment key is refused with `sandbox_pay_not_permitted` before
- * anything is read. The route is not in the SDK's typed operations yet
- * (merged 2026-09-23), so it is called by path.
+ * anything is read. Since `@codespar/sdk@0.16.5` the route is in the SDK's
+ * OpenAPI document, so this is the client's own typed call (same base URL,
+ * key and project header as every other call); until 0.16.4 it was a plain
+ * `fetch`, see docs/OPEN_QUESTIONS.md section 31c. The key is checked for
+ * the `csk_test_` prefix before a client exists, like every other call.
  */
-import type { ApiClient } from "@codespar/sdk";
-import { describeApiError, type ApiFailure } from "./client.js";
+import { ApiClient } from "@codespar/sdk";
+import type { ApiFailure } from "./client.js";
+import { createCodeSparClient, describeApiError } from "./client.js";
 
 export interface SandboxPaidState {
   charge_id: string;
@@ -32,12 +36,21 @@ export interface SandboxPaidState {
 
 export type SandboxPayResult = { ok: true; state: SandboxPaidState } | { ok: false; failure: ApiFailure };
 
-export async function paySandboxCharge(api: ApiClient, chargeRef: string, amountMinor?: number): Promise<SandboxPayResult> {
+/** Where the payer route lives when no client exists yet: the same three things `createCodeSparClient` takes. */
+export interface SandboxPayerTarget {
+  apiKey: string | undefined;
+  baseUrl?: string | undefined;
+  projectId?: string | undefined;
+  timeoutMs?: number;
+}
+
+export async function paySandboxCharge(target: ApiClient | SandboxPayerTarget, chargeRef: string, amountMinor?: number): Promise<SandboxPayResult> {
+  const api = target instanceof ApiClient ? target : createCodeSparClient(target);
   try {
-    const state = (await api.request("post", "/v1/test/charges/{chargeId}/pay" as never, {
+    const state = await api.post("/v1/test/charges/{chargeId}/pay", {
       path: { chargeId: chargeRef },
       body: amountMinor !== undefined ? { amount_minor: amountMinor } : {},
-    } as never)) as SandboxPaidState;
+    });
     return { ok: true, state };
   } catch (err) {
     return { ok: false, failure: describeApiError(err) };

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

@@ -13,7 +13,7 @@ import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "n
 import { dirname, join } from "node:path";
 import { canonicalJson, hexEqual, hmacSha256Hex, itemsHash } from "./hash.js";
 import type { Execution } from "./state-machine.js";
-import type { Actor, ApprovalArtifact, EscalationTrigger } from "./types.js";
+import type { Actor, ApprovalArtifact, EscalationTrigger, ExecutionBatch } from "./types.js";
 import { newId } from "./ids.js";
 
 export const APPROVAL_KEY_ID = "local-dev-stub";
@@ -74,6 +74,10 @@ export function createApprovalArtifact(signer: ApprovalSigner, input: CreateAppr
     mandate: execution.mandate,
     items: execution.items,
     items_hash: itemsHash(execution.items),
+    // The SET this line belongs to, when it belongs to one. Omitted — never
+    // null — on an execution that is not part of a batch, so the payload a
+    // bills-agent artifact signs is unchanged by this field existing.
+    ...(execution.batch ? { batch: execution.batch } : {}),
     ...(input.escalation ? { escalation: input.escalation } : {}),
     actor: input.actor,
   };
@@ -85,7 +89,13 @@ export function createApprovalArtifact(signer: ApprovalSigner, input: CreateAppr
 
 export type ApprovalCheck =
   | { ok: true }
-  | { ok: false; problem: "signature_invalid" | "items_hash_mismatch" | "expired" | "wrong_execution" | "wrong_mandate" };
+  | { ok: false; problem: "signature_invalid" | "items_hash_mismatch" | "expired" | "wrong_execution" | "wrong_mandate" | "batch_mismatch" };
+
+/** Two batch bindings are the same binding, or one is absent and so is the other. */
+function sameBatch(a: ExecutionBatch | undefined, b: ExecutionBatch | undefined): boolean {
+  if (a === undefined || b === undefined) return a === b;
+  return a.ref === b.ref && a.batch_hash === b.batch_hash && a.index === b.index && a.count === b.count;
+}
 
 /**
  * The rule that makes the artifact proof: before `executing`, recompute the
@@ -104,6 +114,10 @@ export function checkApprovalArtifact(
     return { ok: false, problem: "wrong_mandate" };
   }
   if (itemsHash(execution.items) !== artifact.items_hash) return { ok: false, problem: "items_hash_mismatch" };
+  // The line's own list is attested by the hash above; this is the list the
+  // line was one OF. An execution that gained, lost or moved its place in a
+  // batch after approval is not the one that was approved.
+  if (!sameBatch(artifact.batch, execution.batch)) return { ok: false, problem: "batch_mismatch" };
   if (new Date(artifact.expires_at).getTime() <= now.getTime()) return { ok: false, problem: "expired" };
   return { ok: true };
 }

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

@@ -4,7 +4,7 @@
  * payee keys are masked the way a bank statement masks them.
  */
 import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import type { Mandate } from "./mandate.js";
 import type { RailReceipt } from "./rail.js";
 import type { ApprovalArtifact } from "./types.js";
@@ -47,6 +47,29 @@ export class ProofBundle {
     appendFileSync(join(this.dir, "events.jsonl"), JSON.stringify(event) + "\n");
   }
 
+  /**
+   * The conversation, when the run had one: every message in and out of a
+   * channel, in order, with what the channel did with it. Separate from the
+   * transcript, which is the MODEL's side, because on a channel the two are
+   * not the same thing — a message the channel refused never reached the
+   * person, and the QR and the copy-and-paste were sent by the runner.
+   *
+   * It carries no contact in the clear: the channel masks it before it gets
+   * here, because the bundle travels.
+   */
+  channel(line: Record<string, unknown>): void {
+    appendFileSync(join(this.dir, "channel.jsonl"), JSON.stringify(line) + "\n");
+  }
+
+  readChannel(): Record<string, unknown>[] {
+    const path = join(this.dir, "channel.jsonl");
+    if (!existsSync(path)) return [];
+    return readFileSync(path, "utf8")
+      .split("\n")
+      .filter(Boolean)
+      .map((l) => JSON.parse(l) as Record<string, unknown>);
+  }
+
   readEvents(): Record<string, unknown>[] {
     const path = join(this.dir, "events.jsonl");
     if (!existsSync(path)) return [];
@@ -74,11 +97,34 @@ export class ProofBundle {
     writeFileSync(join(this.dir, "mandate.snapshot.json"), JSON.stringify({ ...safe, beneficiaries: safe.beneficiaries.map((b) => ({ ...b, payee: maskPayee(b.payee) })), merchant_allowlist: safe.merchant_allowlist.map(maskPayee) }, null, 2) + "\n");
   }
 
+  /** Returns the path INSIDE the bundle (`receipts/<id>.json`): a bundle travels, and an absolute path names the machine that wrote it. */
   receipt(receipt: RailReceipt): string {
-    const path = join(this.dir, "receipts", `${receipt.receipt_id}.json`);
+    const relative = join("receipts", `${receipt.receipt_id}.json`);
     const { raw: _raw, ...safe } = receipt;
-    writeFileSync(path, JSON.stringify({ ...safe, payment: { ...safe.payment, payee: safe.payment.payee ? maskPayee(safe.payment.payee) : null } }, null, 2) + "\n");
-    return path;
+    writeFileSync(join(this.dir, relative), JSON.stringify({ ...safe, payment: { ...safe.payment, payee: safe.payment.payee ? maskPayee(safe.payment.payee) : null } }, null, 2) + "\n");
+    return relative;
+  }
+
+  /** The masked mandate as it stood when the run started. Absent on a bundle whose run never got that far. */
+  readMandateSnapshot(): Record<string, unknown> | undefined {
+    const path = join(this.dir, "mandate.snapshot.json");
+    return existsSync(path) ? (JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>) : undefined;
+  }
+
+  /** One receipt by its file name, as `listReceipts()` returns it. */
+  readReceipt(file: string): Record<string, unknown> | undefined {
+    const path = join(this.dir, "receipts", basename(file));
+    return existsSync(path) ? (JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>) : undefined;
+  }
+
+  /**
+   * Section 11: `verify.json` is the output of `codespar audit replay`, which
+   * is not a registered command of the CLI, so nothing here writes it and
+   * nothing here reimplements the hash-chain check. The reader exists so a
+   * bundle that gains one later is noticed rather than ignored.
+   */
+  hasVerify(): boolean {
+    return existsSync(join(this.dir, "verify.json"));
   }
 
   listReceipts(): string[] {

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

@@ -0,0 +1,140 @@
+/**
+ * The channels an agent can be reached on, and the one artifact an agent
+ * ships per channel.
+ *
+ * The NAMES live here because `agent.yaml` declares them and `npm run check`
+ * has to confirm the declaration against what the agent ships; the BEHAVIOUR
+ * lives in `@codespar/agent-runtime`, which owns the runner. That split is
+ * the same one `tools.json` and `guardrails.json` already have: the core
+ * owns the shape, the runtime owns what happens.
+ *
+ * `terminal` is every agent's: `npm start` opens it and needs no account.
+ * `whatsapp` is the second channel, and an agent that declares it ships the
+ * conversations the local Cloud API emulator drives, under
+ * `channels/whatsapp/`.
+ */
+import { z } from "zod";
+
+export const CHANNELS = ["terminal", "whatsapp"] as const;
+export type ChannelName = (typeof CHANNELS)[number];
+
+/** E.164, the only contact shape WhatsApp addresses. */
+export const E164 = /^\+[1-9]\d{6,14}$/;
+
+/**
+ * A scripted conversation, which is what an agent ships for a channel whose
+ * other side is a person rather than a keyboard.
+ *
+ * It exists for two readers. A local emulator of the Cloud API drives it with
+ * no Meta account, which is what makes the WhatsApp gate runnable in the CI;
+ * and `npm run check` parses it, so a conversation that no longer names a
+ * contact or an agreement fails the manifest gate instead of failing a run.
+ *
+ * It scripts ONE side. What the agent answers comes from the model or from a
+ * recorded transcript, never from here, for the same reason a scenario pack
+ * asserts a final state and not a wording.
+ */
+export const ConversationScriptSchema = z
+  .object({
+    name: z.string().regex(/^[a-z0-9-]+$/),
+    description: z.string().min(1),
+    channel: z.literal("whatsapp"),
+    /** The contact the conversation is bound to: the person who owes, and nobody else. */
+    contact: z.string().regex(E164, "contact must be E.164, e.g. +5511987654321"),
+    /**
+     * What this conversation is allowed to be about — an agreement alias for a
+     * collections agent. The channel refuses an outbound message that names a
+     * different one, which is the secrecy rule as code rather than as prose.
+     */
+    subject: z.string().min(1).optional(),
+    /** The person's turns, in order. */
+    turns: z
+      .array(
+        z
+          .object({
+            text: z.string().min(1),
+            /** Seconds after the previous inbound turn, on the run's clock. Keeps a scripted run deterministic. */
+            after_seconds: z.number().int().nonnegative().default(0),
+          })
+          .strict(),
+      )
+      .nonempty(),
+  })
+  .strict();
+
+export type ConversationScript = z.infer<typeof ConversationScriptSchema>;
+
+export function parseConversationScript(text: string): ConversationScript {
+  return ConversationScriptSchema.parse(JSON.parse(text));
+}
+
+/**
+ * The reserved file name inside `channels/whatsapp/`: the template registry,
+ * which is not a conversation. Everything else in that directory is one, so
+ * a conversation may not be called `templates`.
+ */
+export const TEMPLATE_REGISTRY_FILE = "templates.json";
+
+/**
+ * One template the agent declares it sends.
+ *
+ * `body` is here for a reader, not for a sender: it is the text AS SUBMITTED
+ * to Meta, and it is the only way somebody opening this repository can tell
+ * what `{{1}}` means. Nothing composes a message from it — Meta holds the
+ * approved copy and renders it — but the number of placeholders in it IS
+ * checked against the variables a send carries, because a count that does not
+ * match is a `132000` from the Cloud API and there is no reason to learn that
+ * in production.
+ */
+export const WhatsAppTemplateSchema = z
+  .object({
+    /** Meta's own naming rule for a template. */
+    name: z.string().regex(/^[a-z0-9_]+$/, "a template name is lower-case letters, digits and underscores"),
+    /** Meta's language code, e.g. `pt_BR`. A template approved in one language does not exist in another. */
+    language: z.string().regex(/^[a-z]{2}(_[A-Z]{2})?$/, 'expected a language code, e.g. "pt_BR"'),
+    description: z.string().min(1),
+    body: z.string().min(1),
+  })
+  .strict();
+
+export type WhatsAppTemplate = z.infer<typeof WhatsAppTemplateSchema>;
+
+/**
+ * `channels/whatsapp/templates.json`: the LOCAL registry of the templates an
+ * agent uses.
+ *
+ * Outside the 24 hours that follow the person's last message WhatsApp carries
+ * an approved template and nothing else, so an agent that ever speaks after
+ * that has to own one. Whether META approved it is NOT knowable from here —
+ * it is a status inside a Business account, and this repository has none — so
+ * what this file proves is narrower and worth stating exactly: the agent
+ * declared the name, so a send of a name nobody declared is refused here
+ * instead of 400-ing at Meta. Registering the template and getting it approved
+ * stays the developer's, and the README says so.
+ */
+export const TemplateRegistrySchema = z
+  .object({
+    channel: z.literal("whatsapp"),
+    templates: z.array(WhatsAppTemplateSchema).nonempty(),
+  })
+  .strict()
+  .superRefine((registry, ctx) => {
+    const seen = new Set<string>();
+    for (const [i, template] of registry.templates.entries()) {
+      if (seen.has(template.name)) ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["templates", i, "name"], message: `${template.name} is declared twice` });
+      seen.add(template.name);
+    }
+  });
+
+export type TemplateRegistry = z.infer<typeof TemplateRegistrySchema>;
+
+export function parseTemplateRegistry(text: string): TemplateRegistry {
+  return TemplateRegistrySchema.parse(JSON.parse(text));
+}
+
+/** The highest `{{n}}` in a template body, which is how many variables a send of it must carry. */
+export function templateArity(body: string): number {
+  let highest = 0;
+  for (const match of body.matchAll(/\{\{\s*(\d+)\s*\}\}/g)) highest = Math.max(highest, Number(match[1]));
+  return highest;
+}

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;
+}