@codespar/cli 0.14.0 → 0.16.0

package/templates/hello-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/hello-agent/packages/agent-runtime/src/poll.ts

@@ -0,0 +1,105 @@
+/**
+ * How the cycle closes without a webhook: the kit LOOKS at the receivable
+ * (`GET /v1/charges/{id}` through the rail's `lookup`, the stub's fixture
+ * offline) until the payer acted or the wait ran out. Each look is a
+ * `reconcile`, which is read-only on the rail and never re-issues. The
+ * instrument (QR, copy-and-paste, bank line) is presented the first time a
+ * look finds it payable; the debtor is told the outcome once, whatever the
+ * number of looks or events that carried it.
+ */
+import type { ChargeInstrument, Execution, ExecutionEngine } from "@codespar/agent-core";
+import type { SandboxPayer } from "./kit.js";
+
+export interface PollHooks {
+  /**
+   * 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. */
+  onWait?: (execution: Execution, round: number) => void;
+}
+
+export interface PollOptions extends PollHooks {
+  intervalMs: number;
+  /** Wall-clock budget for the wait. */
+  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`). */
+  payer?: SandboxPayer | undefined;
+  payerAfterRounds?: number;
+  clock?: () => Date;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+export interface PollResult {
+  execution: Execution;
+  rounds: number;
+  /** Seconds from the first look to the terminal state, or to the end of the wait. */
+  seconds: number;
+  timed_out: boolean;
+  payer_calls: string[];
+}
+
+const defaultSleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+
+/**
+ * Presents each instalment once, records `message.debtor` once per outcome,
+ * and returns when the execution is terminal or the wait is over. Safe to
+ * call again on the same execution (a restart): what was already shown is
+ * remembered in the state.db cursor table, not in memory.
+ */
+export async function pollUntilClosed(engine: ExecutionEngine, executionId: string, options: PollOptions): Promise<PollResult> {
+  const clock = options.clock ?? (() => new Date());
+  const sleep = options.sleep ?? defaultSleep;
+  const startedWall = Date.now();
+  const started = clock().getTime();
+  const maxRounds = options.maxRounds ?? (options.intervalMs === 0 ? 3 : Number.POSITIVE_INFINITY);
+  const payerCalls: string[] = [];
+  let execution = engine.get(executionId);
+  if (!execution) throw new Error(`unknown execution ${executionId}`);
+  let rounds = 0;
+  let paidRequested = false;
+
+  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;
+      await options.onInstrument?.(e, outcome.index + 1, outcome.transaction_id, outcome.instrument);
+    }
+  };
+
+  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.
+      if (rounds >= maxRounds || (options.intervalMs > 0 && Date.now() - startedWall >= options.timeoutMs)) break;
+      options.onWait?.(execution, rounds);
+      if (options.intervalMs > 0) await sleep(options.intervalMs);
+    }
+    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.
+    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 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 });
+      }
+    }
+  }
+  if (execution.state !== "executing") options.onClosed?.(execution);
+  return { execution, rounds, seconds: Math.round(((clock().getTime() - started) / 1000) * 10) / 10, timed_out: execution.state === "executing", payer_calls: payerCalls };
+}

package/templates/hello-agent/packages/agent-runtime/src/scenarios.ts

@@ -0,0 +1,268 @@
+/**
+ * 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 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"),
+    /** `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 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 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(),
+  })
+  .strict();
+
+export const ScenarioSchema = z
+  .object({
+    name: z.string().regex(/^[a-z0-9-]+$/),
+    description: z.string(),
+    modes: z.array(z.enum(["human", "mandate"])).nonempty(),
+    /** 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),
+  })
+  .strict();
+
+export type Scenario = z.infer<typeof ScenarioSchema>;
+
+export interface ScenarioRun {
+  scenario: string;
+  mode: ApprovalMode;
+  rail: RailKind;
+  run_id: string;
+  bundle_dir: string;
+  replies: string[];
+  executions: Array<{ id: string; state: string; reason: string | null; trigger: string | null; total: number; trail: string[]; charge_ids: string[]; receipt_ids: string[] }>;
+  refused_before_draft: number;
+  receipts: number;
+  settled_total: number;
+  charges_issued: number;
+  debtor_messages: number;
+  /** Seconds from the first issuance to the last terminal state (wall clock on the API; the fake clock's ticks on the stub). */
+  cycle_seconds: number;
+  payer_calls: string[];
+}
+
+export interface ScenarioCheck {
+  ok: boolean;
+  mode: ApprovalMode;
+  failures: string[];
+  run: ScenarioRun;
+}
+
+export function scenariosDir(agent: Agent): string {
+  return join(agent.dir, "scenarios");
+}
+
+export function listScenarios(agent: Agent): string[] {
+  return readdirSync(scenariosDir(agent))
+    .filter((f) => f.endsWith(".json"))
+    .map((f) => basename(f, ".json"))
+    .sort();
+}
+
+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")));
+}
+
+export interface RunScenarioOptions {
+  mode: ApprovalMode;
+  rail?: RailKind;
+  runsDir?: string;
+  stateDir?: string;
+  say?: (line: string) => void;
+  tell?: (line: string) => void;
+  waitSeconds?: number | undefined;
+}
+
+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(), `${agent.slug}-${scenario.name}-${options.mode}-`));
+  const s: Setup = setup(agent, {
+    mode: options.mode,
+    rail,
+    provider: "replay",
+    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: s.kit.labels.evalUser, channel: "terminal" };
+  let refusedBeforeDraft = 0;
+  const payerCalls: string[] = [];
+  const late: string[] = [];
+  let firstIssued: number | undefined;
+  let lastClosed: number | undefined;
+
+  try {
+    for (const turn of scenario.turns) {
+      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);
+        const decided = await handleExecution(execution, {
+          setup: s,
+          approver,
+          decision: turn.decision,
+          say,
+          tell,
+          ask: async () => (turn.decision === "approve" ? "s" : "n"),
+          ...(awaitsPayer ? { simulatePayer: turn.payer === "pays", waitSeconds: options.waitSeconds ?? (rail === "api" ? 60 : 0) } : {}),
+        });
+        if (turn.before_execute && decided.state === "approved") {
+          applyHook(s, turn.before_execute);
+          return s.engine.execute(decided.id);
+        }
+        return decided;
+      });
+      const result = await loop.turn(turn.input);
+      replies.push(result.reply);
+      refusedBeforeDraft += s.store.listEvents({ run_id: s.runId }).filter((e) => e.type === "execution.refused_before_draft").length - refusedBeforeDraft;
+      if (turn.payer === "late") for (const e of s.engine.list({ state: "executing" })) if (!before.has(e.id)) late.push(e.id);
+    }
+    // A late payer pays after the conversation ended (the receivable was in flight while the world changed).
+    for (const id of late) {
+      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);
+        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 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 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) {
+      if (e.type === "rail.outcome" && (e.payload as { status: string }).status === "accepted" && firstIssued === undefined) firstIssued = new Date(e.at).getTime();
+      if (e.type === "execution.transition" && ["settled", "failed"].includes((e.payload as { to: string }).to)) lastClosed = new Date(e.at).getTime();
+      if (e.type === "sandbox_payer") payerCalls.push(String((e.payload as { detail: string }).detail));
+    }
+    const executions = s.engine.list().filter((e) => e.run_id === s.runId);
+    return {
+      scenario: scenario.name,
+      mode: options.mode,
+      rail,
+      run_id: s.runId,
+      bundle_dir: s.bundle.dir,
+      replies,
+      executions: executions.map((e) => ({
+        id: e.id,
+        state: e.state,
+        reason: e.reason ?? null,
+        trigger: e.escalation?.trigger ?? null,
+        total: e.total,
+        trail: e.history.map((h) => h.to),
+        charge_ids: e.outcomes.map((o) => o.transaction_id).filter((x): x is string => typeof x === "string"),
+        receipt_ids: e.outcomes.filter((o) => o.receipt_id).map((o) => o.receipt_id as string),
+      })),
+      refused_before_draft: refusedBeforeDraft,
+      receipts: s.bundle.listReceipts().length,
+      settled_total: executions.filter((e) => e.state === "settled").reduce((sum, e) => sum + e.total, 0),
+      charges_issued: events.filter((e) => e.type === "rail.outcome" && (e.payload as { status: string }).status === "accepted").length,
+      debtor_messages: events.filter((e) => e.type === "message.debtor").length,
+      cycle_seconds: firstIssued !== undefined && lastClosed !== undefined ? Math.round(((lastClosed - firstIssued) / 1000) * 10) / 10 : 0,
+      payer_calls: payerCalls,
+    };
+  } finally {
+    s.close();
+  }
+}
+
+function applyHook(s: Setup, hook: "revoke_mandate" | "pause_all" | undefined): void {
+  if (hook === "revoke_mandate") s.gate.revoke(s.mandate.id, "revoked mid-run by the scenario");
+  if (hook === "pause_all") s.gate.pauseAll();
+}
+
+export function checkScenario(scenario: Scenario, run: ScenarioRun): ScenarioCheck {
+  const failures: string[] = [];
+  const expectations = [scenario.expect["both"], scenario.expect[run.mode]].filter((e): e is z.infer<typeof ExpectSchema> => e !== undefined);
+  for (const expect of expectations) {
+    if (expect.states && JSON.stringify(run.executions.map((e) => e.state)) !== JSON.stringify(expect.states)) failures.push(`states ${JSON.stringify(run.executions.map((e) => e.state))} != ${JSON.stringify(expect.states)}`);
+    if (expect.trails && JSON.stringify(run.executions.map((e) => e.trail)) !== JSON.stringify(expect.trails)) failures.push(`trails ${JSON.stringify(run.executions.map((e) => e.trail))} != ${JSON.stringify(expect.trails)}`);
+    if (expect.reasons && JSON.stringify(run.executions.map((e) => e.reason)) !== JSON.stringify(expect.reasons)) failures.push(`reasons ${JSON.stringify(run.executions.map((e) => e.reason))} != ${JSON.stringify(expect.reasons)}`);
+    if (expect.triggers && JSON.stringify(run.executions.map((e) => e.trigger)) !== JSON.stringify(expect.triggers)) failures.push(`triggers ${JSON.stringify(run.executions.map((e) => e.trigger))} != ${JSON.stringify(expect.triggers)}`);
+    if (expect.receipts !== undefined && run.receipts !== expect.receipts) failures.push(`receipts ${run.receipts} != ${expect.receipts}`);
+    if (expect.refused_before_draft !== undefined && run.refused_before_draft !== expect.refused_before_draft) failures.push(`refused_before_draft ${run.refused_before_draft} != ${expect.refused_before_draft}`);
+    if (expect.settled_total !== undefined && run.settled_total !== expect.settled_total) failures.push(`settled_total ${run.settled_total} != ${expect.settled_total}`);
+    if (expect.charges_issued !== undefined && run.charges_issued !== expect.charges_issued) failures.push(`charges_issued ${run.charges_issued} != ${expect.charges_issued}`);
+    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 };
+}