@codespar/cli 0.14.0 → 0.16.0

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

@@ -0,0 +1,206 @@
+/**
+ * The seam between the shared runner and one agent. Everything the runner
+ * cannot know — which rail the agent drives, what the person at the keyboard
+ * is called, which tools the model may reach, what a one-shot prints as JSON —
+ * comes from the `kit` the agent exports; everything else is here and is the
+ * same for every agent.
+ *
+ * An agent that needs none of it ships no kit at all: `defaultKit` drives the
+ * stub payment rail with the example mandate, which is what a read-only agent
+ * wants.
+ */
+import type {
+  ChargeInstrument,
+  Execution,
+  LoadedManifest,
+  LocalMandateStatusStub,
+  Guardrails,
+  Mandate,
+  MandateStatusSource,
+  PaymentRail,
+  PolicyExtension,
+  StateStore,
+  StubPayerBehaviour,
+  StubRailOptions,
+  StubChargeRailOptions,
+  ToolHandler,
+} from "@codespar/agent-core";
+import type { ApiClient } from "@codespar/sdk";
+import type { Setup } from "./setup.js";
+import type { ScenarioCheck } from "./scenarios.js";
+import type { AdversarialResult } from "./adversarial.js";
+
+export type RailKind = "stub" | "api";
+
+/**
+ * How an execution reaches a terminal state. `immediate`: the rail answers
+ * and the execution is settled or failed (money out). `await-payer`: the rail
+ * accepts and somebody else has to act, so the run looks at the receivable
+ * until it closes (money in).
+ */
+export type Settlement = "immediate" | "await-payer";
+
+/**
+ * Who plays the counterparty in the sandbox. With the stub rail it is the
+ * fixture inside the rail; with a test key it is the API's own test route.
+ */
+export interface SandboxPayer {
+  kind: RailKind;
+  /** Pays a receivable this run issued. Returns what the payer reported, or the refusal. */
+  pay(chargeId: string, attemptId: string): Promise<{ ok: true; detail: string } | { ok: false; detail: string }>;
+  /** Stub only: what the fixture does with receivables issued from now on. */
+  behave(behaviour: StubPayerBehaviour): void;
+  /**
+   * Stub only: what the fixture does with ONE receivable that was already
+   * issued and looked at.
+   *
+   * It is separate from `behave` because they answer different questions, and
+   * a poll needs the second one. `behave` sets the default for receivables
+   * the rail has not seen yet; by the time a poll resumes a conversation the
+   * rail HAS seen this one, and its fate is a row in state.db that only this
+   * rewrites. It is separate from `pay` because `pay` means pay — the
+   * scenario runner's late payer calls it after telling the fixture to sit on
+   * everything, and it has to pay anyway.
+   *
+   * The API's payer is a route and has no equivalent, so this is optional.
+   */
+  decideFor?(attemptId: string, behaviour: StubPayerBehaviour): void;
+}
+
+export interface RailContext {
+  kind: RailKind;
+  env: NodeJS.ProcessEnv;
+  agentDir: string;
+  stateDir: string;
+  manifest: LoadedManifest;
+  store: StateStore;
+  gate: LocalMandateStatusStub;
+  now: (() => Date) | undefined;
+  /** The mandate a caller pinned (a scenario, a test), if any. */
+  mandate: Mandate | undefined;
+  /** Stub-rail overrides a caller pinned (rerun, a scenario). */
+  stubRail: StubRailOptions | StubChargeRailOptions | undefined;
+  /** Reads `<PREFIX>_<NAME>` from the environment, the prefix being the agent's own. */
+  envVar(name: string): string | undefined;
+}
+
+export interface RailBuild {
+  rail: PaymentRail;
+  mandate: Mandate;
+  /** The section 4.7 source. Defaults to the local stub gate. */
+  status?: MandateStatusSource;
+  api?: ApiClient | undefined;
+  payer?: SandboxPayer;
+  /** Milliseconds between two looks at an issued receivable. */
+  pollIntervalMs?: number;
+}
+
+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`. */
+  mandateWord: string;
+  /** The word for a sealed outcome in the console: `recibo`, `registro`. */
+  receiptWord: string;
+  /** What the interactive loop prints under the banner. */
+  intro: string;
+  /** The interactive prompt. */
+  prompt: string;
+  /** The question an `awaiting_approval` execution asks at the keyboard. */
+  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;
+  /** `await-payer` only: the line printed every few looks while the payer has not acted. */
+  waitingForPayer?(round: number): string;
+}
+
+export interface OneShotContext {
+  setup: Setup;
+  reply: string;
+  toolCalls: Array<{ name: string; refused: boolean }>;
+  executions: Execution[];
+  /** `Date.now()` when the turn started, for an agent that reports its cycle. */
+  startedAt: number;
+}
+
+export interface ConsentContext {
+  agentDir: string;
+  argv: string[];
+  say(line: string): void;
+}
+
+export interface EnsureMandateContext extends ConsentContext {
+  railKind: RailKind;
+  /** True when the run has no conversation to fall back on (a one-shot). */
+  oneShot: boolean;
+  ask(question: string): Promise<string>;
+}
+
+export interface AgentKit {
+  /** `immediate` (money out) or `await-payer` (money in). Default `immediate`. */
+  settlement?: Settlement;
+  /**
+   * Which rail a `--scenario` run uses: the stub always, or the one the
+   * environment resolved. An agent whose packs declare `rails` wants
+   * `requested`; one whose packs are offline fixtures wants `stub`.
+   */
+  scenarioRail?: "stub" | "requested";
+  labels: RuntimeLabels;
+  /** The usage text `--help`, a bad flag and a bad `--now` print. */
+  usage(manifest: LoadedManifest): string;
+  buildRail(ctx: RailContext): RailBuild;
+  handlers(setup: Setup): Record<string, ToolHandler>;
+  /** The deterministic policy the core runs as its `policyExtension`. */
+  policyExtension?(ctx: { agentDir: string; manifest: LoadedManifest; guardrails: Guardrails }): 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;
+  /** `await-payer` only: the one message per outcome the counterparty receives. */
+  announceOutcome?(execution: Execution, setup: Setup, tell: (line: string) => void): boolean;
+  /**
+   * The SAME outcome as `announceOutcome`, carried as an approved template.
+   *
+   * It exists because a channel can have a rule about WHEN free text may be
+   * sent, and WhatsApp does: outside the 24 hours after the person's last
+   * message only a template Meta approved goes out. A collection reaches that
+   * state as its normal case — agreed Tuesday, paid Friday — so an agent that
+   * closes its cycle on a channel owns a template for each outcome it can
+   * 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
+   * 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;
+  /** Runs before a one-shot or an interactive session, when the mandate may have to be born first. Returns false to stop the run. */
+  ensureMandate?(ctx: EnsureMandateContext): Promise<boolean>;
+  /** `codespar-agent consent`. Absent means the agent has no consent step. */
+  consent?(ctx: ConsentContext): Promise<number>;
+  /** The prior settled executions an adversarial case asks for, so a velocity window has history. */
+  warmUp?(setup: Setup, aliases: string[], approver: { id: string; channel: string }): Promise<Set<string>>;
+  /** The `kind: events` adversarial case: duplicated and out-of-order deliveries. */
+  runEventsCase?(setup: Setup, tell: (line: string) => void): Promise<void>;
+  /**
+   * What a `rerun` has to reproduce from the recorded events, beyond the
+   * model's own outputs: a payee the rail refused, a receivable the payer let
+   * expire. The rail's and the counterparty's answers are part of the recording.
+   */
+  rerunPlan?(events: Array<Record<string, unknown>>): { stubRail?: StubRailOptions | StubChargeRailOptions; simulatePayer?: boolean };
+  /** Whether `rerun` compares the rail's outcomes as well as the state trail. */
+  rerunComparesOutcomes?: boolean;
+  /** The one line `eval` prints per scenario run and per adversarial case. */
+  evalScenarioLine?(check: ScenarioCheck): string;
+  evalAdversarialLine?(result: AdversarialResult): string;
+}

package/templates/{collections-agent/agents/collections-agent → bills-agent/packages/agent-runtime}/src/poll.ts

@@ -8,11 +8,16 @@
  * number of looks or events that carried it.
  */
 import type { ChargeInstrument, Execution, ExecutionEngine } from "@codespar/agent-core";
-import type { SandboxPayer } from "./setup.js";
+import type { SandboxPayer } from "./kit.js";
 
 export interface PollHooks {
-  /** A receivable became payable: show the payer how to pay. Called once per instalment. */
-  onInstrument?: (execution: Execution, instalment: number, chargeId: string, instrument: ChargeInstrument) => void;
+  /**
+   * A receivable became payable: show the payer how to pay. Called once per
+   * instalment, and AWAITED — on a console the lines are on the screen by the
+   * time the call returns, but on a channel the message still has to go out,
+   * and a payer told how to pay after the poll already closed was not told.
+   */
+  onInstrument?: (execution: Execution, instalment: number, chargeId: string, instrument: ChargeInstrument) => void | Promise<void>;
   /** The execution reached a terminal state. Called once. */
   onClosed?: (execution: Execution) => void;
   /** Called before each look after the first. */
@@ -25,8 +30,9 @@ 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 as soon as every instalment is payable (a scenario, `--simulate-payer`). */
+  /** When set, the payer plays once every instalment is payable, or after `payerAfterRounds` looks (a scenario, `--simulate-payer`). */
   payer?: SandboxPayer | undefined;
+  payerAfterRounds?: number;
   clock?: () => Date;
   sleep?: (ms: number) => Promise<void>;
 }
@@ -60,15 +66,15 @@ export async function pollUntilClosed(engine: ExecutionEngine, executionId: stri
   let rounds = 0;
   let paidRequested = false;
 
-  const present = (e: Execution) => {
+  const present = async (e: Execution) => {
     for (const outcome of e.outcomes) {
       if (outcome.status !== "accepted" || !outcome.instrument?.payable || !outcome.transaction_id) continue;
       if (!engine.markShown(e.id, outcome.attempt_id)) continue;
-      options.onInstrument?.(e, outcome.index + 1, outcome.transaction_id, outcome.instrument);
+      await options.onInstrument?.(e, outcome.index + 1, outcome.transaction_id, outcome.instrument);
     }
   };
 
-  present(execution);
+  await present(execution);
   while (execution.state === "executing") {
     if (rounds > 0) {
       // A zero-interval loop (the stub) is bounded by looks; a real one by the wall clock.
@@ -78,11 +84,16 @@ export async function pollUntilClosed(engine: ExecutionEngine, executionId: stri
     }
     rounds += 1;
     execution = await engine.reconcile(execution.id);
-    present(execution);
-    const payable = execution.outcomes.filter((o) => o.status === "accepted" && o.instrument?.payable && o.transaction_id);
-    if (options.payer && !paidRequested && execution.state === "executing" && payable.length > 0 && payable.length === execution.outcomes.filter((o) => o.status === "accepted").length) {
+    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.
+    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)) {
       paidRequested = true;
-      for (const outcome of payable) {
+      for (const outcome of issued) {
         const result = await options.payer.pay(outcome.transaction_id!, outcome.attempt_id);
         payerCalls.push(result.detail);
         engine.note("sandbox_payer", execution.id, { charge_id: outcome.transaction_id, ok: result.ok, detail: result.detail });

package/templates/{collections-agent/agents/collections-agent → bills-agent/packages/agent-runtime}/src/scenarios.ts

@@ -1,48 +1,51 @@
 /**
- * Section 12: scenario packs. A scenario is a JSON file with the payer's
- * turns, the decision the operator gives, what the payer does with the
- * receivable (pays, lets it expire, nothing), the hooks that make the world
- * change mid-run (revocation) and what the trail must look like at the end.
- * The model's outputs come from a recorded transcript, so the same file
- * feeds the CI, the live demo and the docs. On the stub rail the payer is the
- * fixture inside the rail; with a test key it is the sandbox pay route, and
- * `cycle_seconds` is the measured time from issuance to `settled`.
+ * Section 12: scenario packs. A scenario is a JSON file with the person's
+ * turns, the decision the approver gives, what the counterparty does with what
+ * the run produced, the hooks that make the world change mid-run (revocation,
+ * an uncertain rail answer) and what the trail must look like at the end. The
+ * model's outputs come from a recorded transcript, so the same file feeds the
+ * CI, the live demo and the docs.
  */
 import { existsSync, mkdtempSync, readdirSync, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, join, resolve } from "node:path";
 import { z } from "zod";
 import type { ApprovalMode, Execution } from "@codespar/agent-core";
-import { AGENT_DIR, RUNS_DIR, setup, type RailKind, type Setup } from "./setup.js";
-import { announceOutcome, handleExecution } from "../channels/terminal/index.js";
+import type { Agent } from "./agent.js";
+import type { RailKind } from "./kit.js";
+import { setup, type Setup } from "./setup.js";
+import { announceOutcome, handleExecution } from "./terminal.js";
 
 const TurnSchema = z
   .object({
     input: z.string().min(1),
     decision: z.enum(["approve", "deny", "none"]).default("approve"),
-    /** What the payer does with the receivable(s) this turn issues: pays during the turn, pays only after the last turn (`late`), lets it expire (stub-only), or nothing. */
+    /** `await-payer` only: what the payer does with what this turn issued — pays during the turn, pays only after the last turn (`late`), lets it expire (stub-only), or nothing. */
     payer: z.enum(["pays", "late", "expires", "never"]).default("pays"),
     /** Runs after the execution is drafted and before the decision is taken. */
     before_decision: z.enum(["revoke_mandate", "pause_all"]).optional(),
     /** Runs after approval, before the rail is called; the core must catch it. */
     before_execute: z.enum(["revoke_mandate", "pause_all"]).optional(),
-    /** The stub issuer loses its answer to the create once; the run reconciles. */
+    /** The stub rail answers `uncertain` to the next attempt; the run ends with a reconcile. */
     rail_uncertain: z.boolean().default(false),
   })
   .strict();
 
 const ExpectSchema = z
   .object({
+    /** Final states of the executions, in order. */
     states: z.array(z.string()).optional(),
+    /** History of each execution (the `to` of every transition). */
     trails: z.array(z.array(z.string())).optional(),
     reasons: z.array(z.string().nullable()).optional(),
     triggers: z.array(z.string().nullable()).optional(),
     receipts: z.number().int().nonnegative().optional(),
     refused_before_draft: z.number().int().nonnegative().optional(),
+    /** Sum of the totals that reached `settled`. */
     settled_total: z.number().int().nonnegative().optional(),
     /** Receivables the rail issued (one per instalment; a retry never adds one). */
     charges_issued: z.number().int().nonnegative().optional(),
-    /** Messages the payer received about outcomes: one per outcome, never two. */
+    /** Messages the counterparty received about outcomes: one per outcome, never two. */
     debtor_messages: z.number().int().nonnegative().optional(),
     /** With a real key: the happy path closes inside this many seconds from issuance. */
     max_cycle_seconds: z.number().positive().optional(),
@@ -54,9 +57,18 @@ export const ScenarioSchema = z
     name: z.string().regex(/^[a-z0-9-]+$/),
     description: z.string(),
     modes: z.array(z.enum(["human", "mandate"])).nonempty(),
-    /** Which rails can run it. `expires` needs the fixture; the API's payer only pays. */
+    /** Which rails can run it. A fixture-only outcome (`expires`) needs the stub. */
     rails: z.array(z.enum(["stub", "api"])).nonempty().default(["stub", "api"]),
     now: z.string().datetime().default("2026-09-23T18:00:00.000Z"),
+    /**
+     * Payees the stub rail refuses for the whole run, by their pinned key.
+     * The rail's answer is the only part of a partial failure a pack cannot
+     * script from the mandate: an allowlist refusal never reaches the rail,
+     * and a payout that the provider itself declines is what a batch has to
+     * survive. Empty by default, so a pack that does not name one runs
+     * exactly as before.
+     */
+    stub_refuse_payees: z.array(z.string()).default([]),
     transcript: z.string(),
     turns: z.array(TurnSchema).nonempty(),
     expect: z.record(z.enum(["human", "mandate", "both"]), ExpectSchema),
@@ -90,20 +102,20 @@ export interface ScenarioCheck {
   run: ScenarioRun;
 }
 
-export function scenariosDir(): string {
-  return join(AGENT_DIR, "scenarios");
+export function scenariosDir(agent: Agent): string {
+  return join(agent.dir, "scenarios");
 }
 
-export function listScenarios(): string[] {
-  return readdirSync(scenariosDir())
+export function listScenarios(agent: Agent): string[] {
+  return readdirSync(scenariosDir(agent))
     .filter((f) => f.endsWith(".json"))
     .map((f) => basename(f, ".json"))
     .sort();
 }
 
-export function loadScenario(name: string): Scenario {
-  const path = join(scenariosDir(), `${name}.json`);
-  if (!existsSync(path)) throw new Error(`unknown scenario ${name}; available: ${listScenarios().join(", ")}`);
+export function loadScenario(agent: Agent, name: string): Scenario {
+  const path = join(scenariosDir(agent), `${name}.json`);
+  if (!existsSync(path)) throw new Error(`unknown scenario ${name}; available: ${listScenarios(agent).join(", ")}`);
   return ScenarioSchema.parse(JSON.parse(readFileSync(path, "utf8")));
 }
 
@@ -117,30 +129,33 @@ export interface RunScenarioOptions {
   waitSeconds?: number | undefined;
 }
 
-export async function runScenario(scenario: Scenario, options: RunScenarioOptions): Promise<ScenarioRun> {
+export async function runScenario(agent: Agent, scenario: Scenario, options: RunScenarioOptions): Promise<ScenarioRun> {
   const say = options.say ?? (() => undefined);
   const tell = options.tell ?? (() => undefined);
   const rail = options.rail ?? "stub";
+  const awaitsPayer = agent.settlement === "await-payer";
   // On the stub the clock is the scenario's and ticks a second per read; on the API it is the wall clock, so the cycle is measured for real.
   let clock = new Date(scenario.now);
   const tick = () => {
     clock = new Date(clock.getTime() + 1000);
     return clock;
   };
-  const stateDir = options.stateDir ?? mkdtempSync(join(tmpdir(), `collections-${scenario.name}-${options.mode}-`));
-  const s: Setup = setup({
+  const stateDir = options.stateDir ?? mkdtempSync(join(tmpdir(), `${agent.slug}-${scenario.name}-${options.mode}-`));
+  const s: Setup = setup(agent, {
     mode: options.mode,
     rail,
     provider: "replay",
-    transcript: resolve(scenariosDir(), scenario.transcript),
-    runsDir: options.runsDir ?? RUNS_DIR,
+    transcript: resolve(scenariosDir(agent), scenario.transcript),
+    runsDir: options.runsDir ?? join(agent.dir, "runs"),
     stateDir,
     ...(rail === "stub" ? { now: tick } : {}),
+    ...(scenario.stub_refuse_payees.length > 0 ? { stubRail: { refusePayees: scenario.stub_refuse_payees } } : {}),
     say,
   });
+  const stub = s.rail as { armUncertainOnce?: () => void };
   const runtime = s.makeRuntime();
   const replies: string[] = [];
-  const approver = { id: "usr_operator", channel: "terminal" };
+  const approver = { id: s.kit.labels.evalUser, channel: "terminal" };
   let refusedBeforeDraft = 0;
   const payerCalls: string[] = [];
   const late: string[] = [];
@@ -149,7 +164,8 @@ export async function runScenario(scenario: Scenario, options: RunScenarioOption
 
   try {
     for (const turn of scenario.turns) {
-      s.payer.behave(turn.payer === "late" ? "never" : turn.payer);
+      if (turn.rail_uncertain) stub.armUncertainOnce?.();
+      s.payer?.behave(turn.payer === "late" ? "never" : turn.payer);
       const before = new Set(s.engine.list().map((e) => e.id));
       const loop = s.makeLoop(runtime, async (execution: Execution) => {
         applyHook(s, turn.before_decision);
@@ -160,8 +176,7 @@ export async function runScenario(scenario: Scenario, options: RunScenarioOption
           say,
           tell,
           ask: async () => (turn.decision === "approve" ? "s" : "n"),
-          simulatePayer: turn.payer === "pays",
-          waitSeconds: options.waitSeconds ?? (rail === "api" ? 60 : 0),
+          ...(awaitsPayer ? { simulatePayer: turn.payer === "pays", waitSeconds: options.waitSeconds ?? (rail === "api" ? 60 : 0) } : {}),
         });
         if (turn.before_execute && decided.state === "approved") {
           applyHook(s, turn.before_execute);
@@ -179,17 +194,17 @@ export async function runScenario(scenario: Scenario, options: RunScenarioOption
       for (const o of s.engine.get(id)?.outcomes ?? []) {
         if (o.status !== "accepted" || !o.transaction_id) continue;
         if (rail === "stub") await s.engine.reconcile(id); // the fixture registers the instrument on the first look
-        const r = await s.payer.pay(o.transaction_id, o.attempt_id);
+        const r = await s.payer!.pay(o.transaction_id, o.attempt_id);
         s.engine.note("sandbox_payer", id, { charge_id: o.transaction_id, ok: r.ok, detail: r.detail });
       }
     }
-    // Section 10: what is still executing is reconciled, never repeated. A payer that answers late needs more than one look.
+    // Section 10: what is still executing is reconciled, never repeated. A rail that answers late needs more than one look.
     for (let round = 0; round < (rail === "api" ? 20 : 3) && s.engine.list({ state: "executing" }).length > 0; round += 1) {
       if (rail === "api" && round > 0) await new Promise((r) => setTimeout(r, s.pollIntervalMs));
       for (const stuck of s.engine.list({ state: "executing" })) await s.engine.reconcile(stuck.id);
     }
-    // Whatever closed after the conversation is told to the payer once, as the poll or the webhook would.
-    for (const e of s.engine.list()) if (e.run_id === s.runId) announceOutcome(e, s, tell);
+    // Whatever closed after the conversation is told to the counterparty once, as the poll or the webhook would.
+    if (awaitsPayer) for (const e of s.engine.list()) if (e.run_id === s.runId) announceOutcome(e, s, tell);
 
     const events = s.store.listEvents({ run_id: s.runId });
     for (const e of events) {
@@ -248,5 +263,6 @@ export function checkScenario(scenario: Scenario, run: ScenarioRun): ScenarioChe
     if (expect.debtor_messages !== undefined && run.debtor_messages !== expect.debtor_messages) failures.push(`debtor_messages ${run.debtor_messages} != ${expect.debtor_messages}`);
     if (expect.max_cycle_seconds !== undefined && run.rail === "api" && run.cycle_seconds > expect.max_cycle_seconds) failures.push(`cycle_seconds ${run.cycle_seconds} > ${expect.max_cycle_seconds}`);
   }
+  // Every run, every mode: nothing reaches executing without an approval artifact carrying its hash.
   return { ok: failures.length === 0, mode: run.mode, failures, run };
 }