@codespar/cli 0.13.0 → 0.14.0

package/templates/bills-agent/agents/bills-agent/src/main.ts

@@ -0,0 +1,185 @@
+/**
+ * `npm start`                                  interactive terminal
+ * `npm start -- --input "pague a escola de outubro"`   one turn, no prompt
+ * `npm start -- --scenario happy-path`         a scenario pack, both modes it declares
+ *
+ * `--json` puts machine data on stdout (valid JSON, nothing else) and the
+ * human messages on stderr.
+ */
+import { stderr, stdout } from "node:process";
+import { relative, resolve } from "node:path";
+import { NotATestKeyError, isTestKey } from "@codespar/agent-core";
+import { closeTerminal, defaultAsk, handleExecution, interactive } from "../channels/terminal/index.js";
+import { runEmbeddedConsent, loadLocalMandate } from "./modules/embedded-consent.js";
+import { checkScenario, listScenarios, loadScenario, runScenario, scenariosDir } from "./scenarios.js";
+import { AGENT_DIR, MANDATE_PATH, NoMandateError, readDotEnv, resolveRailKind, setup, type RailKind } from "./setup.js";
+import { loadMandate, createCodeSparClient } from "@codespar/agent-core";
+
+interface Args {
+  input?: string;
+  scenario?: string;
+  mode?: "human" | "mandate";
+  json: boolean;
+  decision?: "approve" | "deny";
+  provider?: "anthropic" | "replay";
+  transcript?: string;
+  rail?: RailKind;
+  user: string;
+  help: boolean;
+}
+
+export function parseArgs(argv: string[]): Args {
+  const args: Args = { json: false, user: "usr_terminal", help: false };
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i]!;
+    const next = () => {
+      const v = argv[i + 1];
+      if (v === undefined) throw new Error(`${a} needs a value`);
+      i += 1;
+      return v;
+    };
+    if (a === "--input") args.input = next();
+    else if (a === "--scenario") args.scenario = next();
+    else if (a === "--mode") {
+      const v = next();
+      if (v !== "human" && v !== "mandate") throw new Error("--mode must be human or mandate");
+      args.mode = v;
+    } else if (a === "--json") args.json = true;
+    else if (a === "--approve") args.decision = "approve";
+    else if (a === "--deny") args.decision = "deny";
+    else if (a === "--provider") {
+      const v = next();
+      if (v !== "anthropic" && v !== "replay") throw new Error("--provider must be anthropic or replay");
+      args.provider = v;
+    } else if (a === "--transcript") args.transcript = next();
+    else if (a === "--rail") {
+      const v = next();
+      if (v !== "stub" && v !== "api") throw new Error("--rail must be stub or api");
+      args.rail = v;
+    } else if (a === "--user") args.user = next();
+    else if (a === "--help" || a === "-h") args.help = true;
+    else throw new Error(`unknown argument ${a}`);
+  }
+  return args;
+}
+
+const USAGE = `bills-agent
+  npm start                                         interactive terminal
+  npm start -- --input "pague a escola de outubro"  one turn (add --approve/--deny to decide, --json for machine output)
+  npm start -- --scenario <name>                    run a scenario pack (${"see scenarios/"})
+options: --mode human|mandate  --provider anthropic|replay  --transcript <file>  --rail stub|api  --user <id>  --json`;
+
+export async function main(argv = process.argv.slice(2)): Promise<number> {
+  let args: Args;
+  try {
+    args = parseArgs(argv);
+  } catch (err) {
+    stderr.write(`${err instanceof Error ? err.message : String(err)}\n${USAGE}\n`);
+    return 2;
+  }
+  if (args.help) {
+    stderr.write(USAGE + "\n");
+    return 0;
+  }
+  readDotEnv();
+  const say = (line: string) => stderr.write(line + "\n");
+
+  if (args.scenario) return runScenarioCommand(args, say);
+
+  // Sandbox by construction: a live key dies here, before anything else runs.
+  const railKind = resolveRailKind(process.env, args.rail);
+  if (railKind === "api" && !isTestKey(process.env["CODESPAR_API_KEY"])) {
+    say(new NotATestKeyError().message);
+    return 1;
+  }
+
+  // Embedded consent: with a test key and no signed mandate, the mandate is born first.
+  if (railKind === "api" && !loadLocalMandate(MANDATE_PATH)) {
+    if (args.input) {
+      say(new NoMandateError().message);
+      return 1;
+    }
+    const api = createCodeSparClient({ apiKey: process.env["CODESPAR_API_KEY"], baseUrl: process.env["CODESPAR_API_URL"], projectId: process.env["CODESPAR_PROJECT_ID"] });
+    const example = loadMandate(resolve(AGENT_DIR, "mandate.example.json"));
+    await runEmbeddedConsent({ api, example, mandatePath: MANDATE_PATH, say, confirm: async (q: string) => /^(s|sim|y|yes)$/i.test((await defaultAsk(q)).trim()) });
+  }
+
+  // One-shot without a model: replay the recorded happy-path when the input is its first turn.
+  let transcript = args.transcript;
+  const provider = args.provider ?? (process.env["ANTHROPIC_API_KEY"] && process.env["ANTHROPIC_API_KEY"] !== "sk-ant-your_key_here" ? "anthropic" : "replay");
+  if (provider === "replay" && !transcript && args.input) {
+    const match = listScenarios().map(loadScenario).find((s) => s.turns[0].input === args.input);
+    if (match) transcript = resolve(scenariosDir(), match.transcript);
+    else {
+      say(`no ANTHROPIC_API_KEY and no recorded transcript for that input. Set the key, pass --transcript, or use one of: ${listScenarios().map((n) => `"${loadScenario(n).turns[0].input}"`).join(", ")}`);
+      return 1;
+    }
+  }
+
+  const s = setup({ mode: args.mode, rail: railKind, provider, transcript, say });
+  const approver = { id: args.user, channel: "terminal" };
+  try {
+    const runtime = s.makeRuntime();
+    if (!args.input) {
+      await interactive({ setup: s, approver, runtime, say });
+      return 0;
+    }
+    const loop = s.makeLoop(runtime, (execution) => handleExecution(execution, { setup: s, approver, decision: args.decision ?? "none", say }));
+    const result = await loop.turn(args.input);
+    const executions = s.engine.list().filter((e) => e.run_id === s.runId);
+    const payload = {
+      run_id: s.runId,
+      agent: `${s.manifest.manifest.name}@${s.manifest.manifest.version}`,
+      mode: s.mode,
+      rail: s.railKind,
+      mandate_id: s.mandate.id,
+      actor: s.engine.agentActor,
+      reply: result.reply,
+      tool_calls: result.tool_calls,
+      executions: executions.map((e) => ({
+        id: e.id,
+        state: e.state,
+        reason: e.reason ?? null,
+        escalation: e.escalation ?? null,
+        total_minor: e.total,
+        items: e.items.map((i) => ({ beneficiary: i.beneficiary, amount_minor: i.amount })),
+        approval_id: e.approval_id ?? null,
+        receipt_ids: e.outcomes.filter((o) => o.receipt_id).map((o) => o.receipt_id),
+      })),
+      receipts: s.bundle.listReceipts().map((f) => relative(process.cwd(), `${s.bundle.dir}/receipts/${f}`)),
+      bundle_dir: relative(process.cwd(), s.bundle.dir),
+    };
+    if (args.json) stdout.write(JSON.stringify(payload) + "\n");
+    else stdout.write(result.reply + "\n");
+    return executions.some((e) => e.state === "executing") ? 3 : 0;
+  } finally {
+    closeTerminal();
+    s.close();
+  }
+}
+
+async function runScenarioCommand(args: Args, say: (l: string) => void): Promise<number> {
+  const scenario = loadScenario(args.scenario!);
+  const modes = args.mode ? [args.mode] : scenario.modes;
+  const results = [];
+  for (const mode of modes) {
+    say(`== scenario ${scenario.name} — approval: ${mode}`);
+    say(scenario.description);
+    const run = await runScenario(scenario, { mode, say: args.json ? () => undefined : say });
+    const check = checkScenario(scenario, run);
+    for (const reply of run.replies) say(`agente: ${reply}`);
+    say(check.ok ? `== ok — bundle em ${relative(process.cwd(), run.bundle_dir)}` : `== FAIL: ${check.failures.join("; ")}`);
+    results.push({ mode, ok: check.ok, failures: check.failures, run });
+  }
+  if (args.json) stdout.write(JSON.stringify({ scenario: scenario.name, results }) + "\n");
+  return results.every((r) => r.ok) ? 0 : 1;
+}
+
+if (process.argv[1] && import.meta.url === new URL(`file://${process.argv[1]}`).href) {
+  main()
+    .then((code) => process.exit(code))
+    .catch((err) => {
+      stderr.write(`${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
+      process.exit(1);
+    });
+}

package/templates/bills-agent/agents/bills-agent/src/modules/embedded-consent.ts

@@ -0,0 +1,125 @@
+/**
+ * Module `embedded-consent`: the mandate is born at a consent the CONSUMER
+ * authorizes. In the sandbox the kit runs the `partner` surface: it is the
+ * partner's backend, the titular is at the keyboard, and the submit carries
+ * an `in_person` attestation. That is what hands the kit the signed envelope
+ * `{ mandate, signature }`, which `POST /v1/consumer-payments/execute`
+ * presents on every spend. The `hosted` surface (a page the consumer opens)
+ * returns the envelope to a `callback_url` a terminal kit does not have;
+ * see docs/OPEN_QUESTIONS.md.
+ *
+ * With a test key and no `.codespar/mandate.json`, `npm start` runs this
+ * first. The stored file carries the signature: mode 0600, never in the
+ * bundle, never committed.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import type { ApiClient } from "@codespar/sdk";
+import { MandateSchema, windowCap, type Mandate, describeApiError } from "@codespar/agent-core";
+
+export interface ConsentOptions {
+  api: ApiClient;
+  example: Mandate;
+  mandatePath: string;
+  /** Where to write the lines the person reads. */
+  say: (line: string) => void;
+  /** Asks the titular to authorize. Returns true on yes. */
+  confirm: (question: string) => Promise<boolean>;
+  /** The consumer this mandate is for. Defaults to the example's. */
+  consumerId?: string;
+  now?: () => Date;
+}
+
+const YEAR_SECONDS = 365 * 24 * 3600;
+
+export function loadLocalMandate(path: string): Mandate | undefined {
+  if (!existsSync(path)) return undefined;
+  return MandateSchema.parse(JSON.parse(readFileSync(path, "utf8")));
+}
+
+export async function runEmbeddedConsent(options: ConsentOptions): Promise<Mandate> {
+  const { api, example, say } = options;
+  const now = options.now ?? (() => new Date());
+  const consumerId = options.consumerId ?? example.consumer_id;
+
+  const init = await api.post("/v1/consents/init", {
+    body: {
+      agent_id: example.agent_id,
+      intent: {
+        purpose: example.purpose,
+        cap_minor: example.cap_minor,
+        per_tx_cap_minor: example.per_tx_cap_minor,
+        currency: "BRL",
+        mandate_ttl_seconds: YEAR_SECONDS,
+        merchant_allowlist: example.beneficiaries.map((b) => b.payee),
+        merchant_pin_kind: "pix-key",
+        ...(example.periodic_cap ? { periodic_cap: example.periodic_cap } : {}),
+        display_name: "bills-agent: contas do mes",
+        intent_note: `Pagar as contas do mes aos favorecidos nomeados: ${example.beneficiaries.map((b) => b.name).join(", ")}.`,
+      },
+      surface: "partner",
+    },
+  });
+
+  say("");
+  say("O mandato ainda nao existe. Este e o consentimento que o titular assina (sandbox):");
+  say(`  agente: ${example.agent_id}    finalidade: ${example.purpose}`);
+  say(`  teto por pagamento: ${example.per_tx_cap_minor} centavos    teto do mes: ${windowCap(example)} centavos    vitalicio: ${example.cap_minor} centavos`);
+  for (const b of example.beneficiaries) say(`  favorecido: ${b.name} (${b.alias})`);
+  say(`  validade: 1 ano    (o token do consentimento vale ate ${init.expires_at})`);
+  const yes = await options.confirm("  Voce e o titular e autoriza este mandato? [s/N] ");
+  if (!yes) throw new Error("consent not authorized by the titular; nothing was created");
+
+  // The consumer's "browser" is this terminal: the submit is the same call the hosted page makes,
+  // plus the attestation the partner surface requires. Sandbox rails accept a placeholder token.
+  const submitted = (await api.request("post", "/v1/consents/{token}/submit" as never, {
+    path: { token: init.token },
+    body: {
+      consumer_id: consumerId,
+      rail: "pix-consent",
+      provider_token: `sandbox-pix-consent-${consumerId}`,
+      display_label: "bills-agent (sandbox)",
+      attestation: { method: "in_person", asserted_at: Math.floor(now().getTime() / 1000), reference: "terminal" },
+    },
+  } as never)) as { mandate_id: string; mandate: Record<string, unknown>; signature: string };
+
+  const signed = submitted.mandate;
+  const mandate = MandateSchema.parse({
+    id: submitted.mandate_id,
+    version: 1,
+    consumer_id: String(signed["consumer_id"]),
+    agent_id: String(signed["agent_id"]),
+    purpose: String(signed["purpose"]),
+    currency: String(signed["currency"]),
+    cap_minor: Number(signed["cap_minor"]),
+    per_tx_cap_minor: Number(signed["per_tx_cap_minor"]),
+    ...(signed["periodic_cap"] ? { periodic_cap: signed["periodic_cap"] } : {}),
+    merchant_pin_kind: String(signed["merchant_pin_kind"]),
+    merchant_allowlist: signed["merchant_allowlist"],
+    beneficiaries: example.beneficiaries.filter((b) => (signed["merchant_allowlist"] as string[]).includes(b.payee)),
+    status: "active",
+    expires_at: new Date(Number(signed["expires_at"]) * 1000).toISOString(),
+    signature: submitted.signature,
+    canonical: signed,
+    source: "consent",
+  });
+
+  mkdirSync(dirname(options.mandatePath), { recursive: true });
+  writeFileSync(options.mandatePath, JSON.stringify(mandate, null, 2) + "\n", { mode: 0o600 });
+  chmodSync(options.mandatePath, 0o600);
+  say(`Mandato assinado: ${mandate.id} (consumidor ${mandate.consumer_id}).`);
+
+  await fundSandbox(api, mandate, say);
+  return mandate;
+}
+
+/** Best effort: the sandbox account is credited with one window's cap. A `pix-consent` source has no Celcoin account to credit, and the sandbox spend does not need one. */
+export async function fundSandbox(api: ApiClient, mandate: Mandate, say: (line: string) => void): Promise<void> {
+  try {
+    const funded = await api.post("/v1/test/fund", { body: { consumer_id: mandate.consumer_id, amount_minor: windowCap(mandate) } });
+    say(`Sandbox creditado: ${funded.amount_minor} centavos em ${funded.account} (deposit ${funded.deposit_id}).`);
+  } catch (err) {
+    const f = describeApiError(err);
+    say(`Sandbox nao creditado (${f.code}); o gasto de teste sob pix-consent nao depende disso.`);
+  }
+}

package/templates/bills-agent/agents/bills-agent/src/modules/pix-out.ts

@@ -0,0 +1,73 @@
+/**
+ * Module `pix-out`: the tool handlers the model can reach. `codespar_pay`
+ * hands the proposal to the engine and gets an execution in `drafted` (then
+ * whatever the core decided); it cannot pay. `codespar_ledger` and
+ * `list_bills` are reads.
+ */
+import type { ToolHandler } from "@codespar/agent-core";
+import { formatBRL } from "../bills.js";
+import { BILLS, MONTH } from "../bills.js";
+
+interface PayInput {
+  action?: unknown;
+  items?: unknown;
+  total_minor?: unknown;
+}
+
+export const listBills: ToolHandler = async (_input, ctx) => {
+  const settled = ctx.engine.list({ state: "settled" });
+  const paidAliases = new Set(settled.flatMap((e) => e.items.map((i) => i.alias)).filter(Boolean));
+  return {
+    month: MONTH,
+    bills: BILLS.map((b) => ({ ...b, amount: formatBRL(b.amount_minor), paid_this_window: paidAliases.has(b.alias) })),
+    payees: ctx.engine.mandate.beneficiaries.map((b) => ({ alias: b.alias, name: b.name })),
+  };
+};
+
+export const codesparPay: ToolHandler = async (raw, ctx) => {
+  const input = raw as PayInput;
+  if (input.action !== "pix") throw new Error(`codespar_pay: unsupported action ${String(input.action)}; this agent only does pix`);
+  if (!Array.isArray(input.items) || input.items.length === 0) throw new Error("codespar_pay: items must be a non-empty array");
+  const items = input.items.map((item, i) => {
+    const it = item as { payee?: unknown; amount_minor?: unknown; description?: unknown };
+    if (typeof it.payee !== "string" || !it.payee.trim()) throw new Error(`codespar_pay: items[${i}].payee must be a payee alias`);
+    if (typeof it.amount_minor !== "number" || !Number.isInteger(it.amount_minor) || it.amount_minor <= 0) throw new Error(`codespar_pay: items[${i}].amount_minor must be a positive integer`);
+    return { payee: it.payee, amount: it.amount_minor, ...(typeof it.description === "string" ? { description: it.description } : {}) };
+  });
+  const claimed = typeof input.total_minor === "number" ? { claimed_total: input.total_minor } : {};
+
+  const draft = await ctx.engine.draft({ items, ...claimed });
+  if (!draft.ok) {
+    return { status: "refused", reason: draft.reason, message: draft.message, paid: false };
+  }
+  const execution = await ctx.onExecution(draft.execution);
+  return {
+    status: execution.state,
+    execution_id: execution.id,
+    total_minor: execution.total,
+    total: formatBRL(execution.total),
+    items: execution.items.map((i) => ({ payee: i.beneficiary, amount: formatBRL(i.amount) })),
+    ...(execution.reason ? { reason: execution.reason, detail: execution.detail } : {}),
+    ...(execution.escalation ? { escalated_by: execution.escalation.trigger } : {}),
+    receipt_ids: execution.outcomes.filter((o) => o.receipt_id).map((o) => o.receipt_id),
+    paid: execution.state === "settled",
+  };
+};
+
+export const codesparLedger: ToolHandler = async (raw, ctx) => {
+  const input = raw as { action?: unknown; receipt_id?: unknown };
+  if (input.action === "executions") {
+    return {
+      executions: ctx.engine.list().map((e) => ({ id: e.id, state: e.state, total: formatBRL(e.total), reason: e.reason ?? null, receipt_ids: e.outcomes.filter((o) => o.receipt_id).map((o) => o.receipt_id) })),
+    };
+  }
+  if (input.action === "receipt") {
+    if (typeof input.receipt_id !== "string") throw new Error("codespar_ledger: receipt_id is required for action=receipt");
+    const owner = ctx.engine.list().find((e) => e.outcomes.some((o) => o.receipt_id === input.receipt_id));
+    if (!owner) return { found: false, message: "no receipt with that id in this mandate's executions" };
+    const outcome = owner.outcomes.find((o) => o.receipt_id === input.receipt_id)!;
+    const item = owner.items[outcome.index];
+    return { found: true, receipt_id: outcome.receipt_id, state: owner.state, payee: item?.beneficiary, amount: item ? formatBRL(item.amount) : null, mandate_id: owner.mandate.id };
+  }
+  throw new Error(`codespar_ledger: unsupported action ${String(input.action)}`);
+};

package/templates/bills-agent/agents/bills-agent/src/scenarios.ts

@@ -0,0 +1,196 @@
+/**
+ * Section 12: scenario packs. A scenario is a JSON file with the person's
+ * turns, the decision the approver gives, 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 { StubRail, type ApprovalMode, type Execution } from "@codespar/agent-core";
+import { AGENT_DIR, RUNS_DIR, setup, type Setup } from "./setup.js";
+import { handleExecution } from "../channels/terminal/index.js";
+
+const TurnSchema = z
+  .object({
+    input: z.string().min(1),
+    decision: z.enum(["approve", "deny", "none"]).default("approve"),
+    /** 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(),
+  })
+  .strict();
+
+export const ScenarioSchema = z
+  .object({
+    name: z.string().regex(/^[a-z0-9-]+$/),
+    description: z.string(),
+    modes: z.array(z.enum(["human", "mandate"])).nonempty(),
+    now: z.string().datetime().default("2026-09-23T18:00:00.000Z"),
+    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;
+  run_id: string;
+  bundle_dir: string;
+  replies: string[];
+  executions: Array<{ id: string; state: string; reason: string | null; trigger: string | null; total: number; trail: string[]; receipt_ids: string[] }>;
+  refused_before_draft: number;
+  receipts: number;
+  settled_total: number;
+}
+
+export interface ScenarioCheck {
+  ok: boolean;
+  mode: ApprovalMode;
+  failures: string[];
+  run: ScenarioRun;
+}
+
+export function scenariosDir(): string {
+  return join(AGENT_DIR, "scenarios");
+}
+
+export function listScenarios(): string[] {
+  return readdirSync(scenariosDir())
+    .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(", ")}`);
+  return ScenarioSchema.parse(JSON.parse(readFileSync(path, "utf8")));
+}
+
+export interface RunScenarioOptions {
+  mode: ApprovalMode;
+  runsDir?: string;
+  stateDir?: string;
+  say?: (line: string) => void;
+}
+
+export async function runScenario(scenario: Scenario, options: RunScenarioOptions): Promise<ScenarioRun> {
+  const say = options.say ?? (() => undefined);
+  let clock = new Date(scenario.now);
+  const tick = () => {
+    clock = new Date(clock.getTime() + 1000);
+    return clock;
+  };
+  const stateDir = options.stateDir ?? mkdtempSync(join(tmpdir(), `bills-${scenario.name}-${options.mode}-`));
+  const s: Setup = setup({
+    mode: options.mode,
+    rail: "stub",
+    provider: "replay",
+    transcript: resolve(scenariosDir(), scenario.transcript),
+    runsDir: options.runsDir ?? RUNS_DIR,
+    stateDir,
+    now: tick,
+    say,
+  });
+  const stub = s.rail as StubRail;
+  const runtime = s.makeRuntime();
+  const replies: string[] = [];
+  const approver = { id: "usr_demo_titular", channel: "terminal" };
+  let refusedBeforeDraft = 0;
+
+  try {
+    for (const turn of scenario.turns) {
+      if (turn.rail_uncertain) stub.armUncertainOnce();
+      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,
+          ask: async () => (turn.decision === "approve" ? "s" : "n"),
+        });
+        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;
+    }
+    // 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 < 3 && s.engine.list({ state: "executing" }).length > 0; round += 1) {
+      for (const stuck of s.engine.list({ state: "executing" })) await s.engine.reconcile(stuck.id);
+    }
+
+    const executions = s.engine.list().filter((e) => e.run_id === s.runId);
+    return {
+      scenario: scenario.name,
+      mode: options.mode,
+      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),
+        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),
+    };
+  } 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}`);
+  }
+  // Every run, every mode: nothing reaches executing without an approval artifact carrying its hash.
+  return { ok: failures.length === 0, mode: run.mode, failures, run };
+}