@visa/cli 4.1.0-rc.298 → 4.1.0-rc.299

package/dist/checkout-engine/cli-engine.js

@@ -1,1331 +0,0 @@
-// createCliCheckoutEngine — the review()/pay() adapter consumed by @visa/cli's
-// pay_merchant tool. It COMPOSES prepareCheckout, runHostedApproval, the
-// server-side mint (serverCreateIntent/serverFetchCryptogram — the credential is
-// minted by the verify-web deployment, not this machine), submitApprovedCheckout,
-// reportVicOutcome, and receipts into a two-call API.
-//
-// A live browser + prepared-checkout session is held in-process between review
-// and pay, keyed by reviewId, so the submitted checkout is the exact one the
-// human approved. Passkey approval uses the hosted /approve page only.
-//
-// Every browser/network primitive is injectable (CliEngineDeps) so the session/
-// timer/store lifecycle is unit-testable without launching Chromium.
-import { readFile } from 'node:fs/promises';
-import { randomBytes, randomUUID } from 'node:crypto';
-import { launchCheckoutBrowser } from './browser-launch.js';
-import { RECEIPT_DIR } from './receipt-dir.js';
-import { prepareCheckout as realPrepareCheckout, submitApprovedCheckout as realSubmitApprovedCheckout, InMemoryPreparedCheckoutStore, } from './executor.js';
-import { claimMandatePickup as realClaimMandatePickup, runHostedApproval as realRunHostedApproval, } from './hosted-approval.js';
-import { VgsLiveInstrument, decimalToMinor, minorToDecimal, } from './vgs-live-instrument.js';
-import { serverCreateIntent, serverReadIntentBootstrap, ServerIntentError, serverFetchCryptogram, serverPostConfirmation, } from './vgs-gateway/server-mint-client.js';
-import { createCardMandate, DEFAULT_MANDATE_MAX_DRAWS, drawFromMandate, MandateDrawDeclinedError, } from './mandate/card-mandate.js';
-import { MandateLedger } from './mandate/mandate-ledger.js';
-import { buildReceipt, writeReceipt as realWriteReceipt, } from './receipt.js';
-import { reportVicOutcome as realReportVicOutcome, } from './vic-confirmation.js';
-/**
- * A card-mandate draw failed transiently (retryable) rather than definitively.
- * Gateway 5xx, "server cryptogram not completed / try again", and network
- * reset/timeout errors are transient: the mandate stays healthy and must NOT be
- * disabled. Walks the error's cause chain so a wrapped MandateDrawDeclinedError
- * is classified by its underlying gateway error. Exported for tests.
- */
-export function isTransientDrawFailure(err) {
-    const msgs = [];
-    let e = err;
-    for (let i = 0; i < 5 && e; i++) {
-        // A refusal that declared itself TERMINAL wins outright, before any message
-        // matching. Message text is not a safe carrier for this decision: the mint
-        // client interpolates provider-supplied `upstream_codes` into its message
-        // for diagnosability, and an identifier like `request_timeout` would match
-        // the unanchored `tim(e|ed)-out` alternative below and silently reclassify
-        // a permanent 422 as transient — skipping markUnhonored and stranding the
-        // mandate in the retry-forever loop this classifier exists to prevent.
-        // Duck-typed rather than instanceof so it survives bundling and any
-        // re-wrapping across package boundaries. Optional chaining rather than an
-        // explicit null guard: the loop condition already proved `e` truthy, so a
-        // `e !== null` test is dead code, and `?.` stays safe on a primitive or a
-        // nullish link if that guard ever changes.
-        if (e?.terminal === true) {
-            return false;
-        }
-        if (e instanceof Error && typeof e.message === 'string')
-            msgs.push(e.message);
-        e = e.cause;
-    }
-    // Transient = a gateway 5xx / 429 in the mint client's "(last: <status>: …)"
-    // framing, or an unambiguous network reset/timeout error name. The status is
-    // ANCHORED to `(last:` so a bare 3-digit token elsewhere (an amount, a ref id,
-    // an attempt count) can never be mistaken for a status code, and so the
-    // advisory DRAW_REMEDY wrapper text ("gateway 5xx / try again") cannot
-    // self-classify a hard decline as transient. A hard decline (4xx / a
-    // card-decline reason) matches nothing here → the mandate is correctly disabled.
-    return /\(last:\s*(?:5\d\d|429)\b|\bETIMEDOUT\b|\bECONNRESET\b|\bECONNREFUSED\b|\bEAI_AGAIN\b|socket hang up|tim(?:e|ed)[ -]?out/i.test(msgs.join(' '));
-}
-/**
- * Refusals that are about the OUTER card GRANT's remaining capacity, not about
- * this mandate and not about the card network (#7491).
- *
- * The atomic reserve (#7233) charges the grant's shared `agent_grant_usage`
- * epoch, so an exhausted or replaced grant refuses BEFORE any credential is
- * minted: no cryptogram is issued, no processor intent is created, no money
- * moves. Treating that as a mandate decline burned the budget the human had
- * just approved and told the caller to create another mandate — which, over the
- * same exhausted grant, is guaranteed to fail identically. The honest remedy is
- * a new/replacement card grant, and the mandate must stay honored so it can
- * draw once the owner supplies one.
- */
-// Deliberately NARROW. `grant_aggregate_no_mandate` is NOT here: that refusal
-// means the mandate row itself vanished between the read and the reserve, which
-// is a statement about the mandate, not about the grant's capacity.
-const GRANT_CAPACITY_REASONS = new Set([
-    'over_grant_aggregate',
-    'no_active_grant',
-    'no_active_grant_or_card_scope',
-    'card_grant_exhausted',
-]);
-function isGrantCapacityReason(reason) {
-    return GRANT_CAPACITY_REASONS.has(reason);
-}
-/**
- * A verdict refusal may be wrapped by drawFromMandate after its local
- * reservation is released. Walk the cause chain so the original auth status +
- * reasons still decide whether the mandate is permanently disabled.
- */
-// Exported for the cross-package pin in test/cli-engine.test.ts: the CLI's
-// card-draw client decides the `status` this reads, so the two move together
-// and a test that spans the boundary is the only one that would catch a drift.
-// Not re-exported from index.ts — the public @visa/checkout-engine surface is
-// the explicit allowlist there, same as isTransientDrawFailure above.
-export function classifyCardDrawVerdictFailure(err) {
-    const transientReasons = new Set(['challenge_failed', 'challenge_malformed', 'verdict_refused']);
-    let current = err;
-    for (let i = 0; i < 5 && current; i++) {
-        const candidate = current;
-        const status = typeof candidate.status === 'number' ? candidate.status : 0;
-        const reasons = Array.isArray(candidate.reasons)
-            ? candidate.reasons.filter((reason) => typeof reason === 'string')
-            : [];
-        if (status !== 0 || reasons.length > 0) {
-            const transient = status === 503 ||
-                reasons.length === 0 ||
-                reasons.every((reason) => transientReasons.has(reason));
-            return {
-                transient,
-                // A capacity refusal is NEITHER transient nor a decline. Retrying now
-                // fails identically (so it is not transient), but nothing about the
-                // MANDATE was refused (so it is not a decline). Only a refusal that is
-                // exclusively about the outer grant qualifies: a mixed reason list
-                // still carries a real mandate/network refusal and stays a decline.
-                grantCapacity: !transient && reasons.length > 0 && reasons.every(isGrantCapacityReason),
-                reasons,
-            };
-        }
-        current = candidate.cause;
-    }
-    return null;
-}
-/**
- * Resolve the card instrument for one flow. Fail-closed: an unusable legacy file
- * with no grant token rethrows (never silently proceeds), and the ONLY thing the
- * fallback contributes is a token id — a non-secret handle the server
- * re-authorizes against the owner (`requireTokenOwnership`) and against the live
- * grant on every draw. Nothing here authorizes anything.
- */
-async function resolveCardInstrument(input) {
-    if (typeof input.cardTokenId === 'string' && input.cardTokenId.trim()) {
-        return { tokenId: input.cardTokenId.trim(), source: 'card-grant' };
-    }
-    let credential = null;
-    let readError = null;
-    try {
-        credential = JSON.parse(await readFile(input.credentialPath, 'utf8'));
-    }
-    catch (err) {
-        readError = err;
-    }
-    if (credential && typeof credential.tokenId === 'string' && credential.tokenId.trim()) {
-        return credential;
-    }
-    throw new Error('no card instrument is available to this runtime: there is no usable credential at ' +
-        `${input.credentialPath} and no activated card:vic grant token was supplied. Run ` +
-        '`visa agent grant-card <agent-id> --ceiling <usd> --per-transaction <usd> --wait` to ' +
-        'attach one, or use a pre-provisioned VIC runtime.', readError instanceof Error ? { cause: readError } : undefined);
-}
-/**
- * A checkout was inspected successfully but cannot be reviewed safely.
- *
- * The explicit fields survive the CLI's copied-engine boundary structurally,
- * so MCP callers do not have to parse the human-readable message.
- */
-export class CheckoutReviewRefusedError extends Error {
-    code = 'CHECKOUT_REVIEW_REFUSED';
-    checkoutOutcome;
-    failureCode;
-    /** Bounded mandate/trusted-identity reason (#8669); absent for other outcomes. */
-    refusalCode;
-    requiresAdapter;
-    detectedRoles;
-    receiptWrite;
-    detail;
-    constructor(result, receiptWrite) {
-        super(result.detail
-            ? `review refused: ${result.outcome} — ${result.detail}`
-            : `review refused: ${result.outcome}`);
-        this.name = 'CheckoutReviewRefusedError';
-        this.checkoutOutcome = result.outcome;
-        this.failureCode = result.failureCode;
-        this.refusalCode = result.refusalCode;
-        this.requiresAdapter = [...result.requiresAdapter];
-        this.detectedRoles = Object.keys(result.fields);
-        this.receiptWrite = receiptWrite;
-        this.detail = result.detail;
-    }
-}
-function payAttemptFingerprint(input) {
-    return JSON.stringify([
-        input.url,
-        input.checkoutRoute,
-        input.amount,
-        input.currency,
-        input.credentialPath,
-        input.cardTokenId ?? null,
-        input.agentJkt ?? null,
-        input.contact,
-        input.approvalBaseUrl,
-        input.merchantName ?? null,
-        input.merchantCountryCode ?? null,
-        input.submit,
-    ]);
-}
-function failedPay(detail) {
-    return {
-        outcome: 'failed',
-        confirmationRef: null,
-        receiptPath: null,
-        detail,
-        vicConfirmation: null,
-        source: null,
-        remainingMinor: null,
-        credentialIssued: false,
-        credentialDisclosed: false,
-    };
-}
-export class CardMandateActivationError extends Error {
-    facts;
-    code = 'CARD_MANDATE_ACTIVATION_INCOMPLETE';
-    constructor(message, facts) {
-        super(message);
-        this.facts = facts;
-        this.name = 'CardMandateActivationError';
-    }
-}
-/**
- * Sort a budget-intent route failure into resume semantics. Exported for the
- * regression net; the truth table is the product contract of #8470.
- */
-export function classifyServerIntentFailure(err) {
-    const { status, errorCode, retryable, bootstrapState, outcome } = err.facts;
-    if (bootstrapState === 'created')
-        return { outcome: 'not_created', resumable: true };
-    if (bootstrapState === 'ambiguous' || errorCode === 'budget_intent_creation_ambiguous') {
-        return { outcome: 'uncertain', resumable: true };
-    }
-    if (bootstrapState === 'pending' || errorCode === 'budget_intent_creation_pending') {
-        return { outcome: 'uncertain', resumable: true };
-    }
-    // An explicit uncertain or unknown outcome wins over retry advice: a
-    // retryable failure of the STATUS read says nothing about whether the
-    // original dispatch created the intent, so it must not read as not_created.
-    // A terminal refusal of the read itself (the approval credential is no
-    // longer accepted, or is not a budget token) is still uncertain about the
-    // intent but cannot be resumed under that credential.
-    if (outcome === 'uncertain' || outcome === 'unknown') {
-        const terminalRead = status === 401 || status === 403 || status === 404;
-        return { outcome: 'uncertain', resumable: !terminalRead };
-    }
-    // #8981: this exact admission refusal is known to precede provider dispatch.
-    // Never generalize retryable:false or a 503 into evidence of non-creation.
-    if (status === 503 &&
-        errorCode === 'LEGACY_AGENT_ADMISSION_STOPPED' &&
-        retryable === false &&
-        bootstrapState === 'none' &&
-        outcome === 'not_created') {
-        return { outcome: 'not_created', resumable: false };
-    }
-    if (retryable)
-        return { outcome: 'not_created', resumable: true };
-    if (status === 0 || status >= 500) {
-        return { outcome: 'uncertain', resumable: true };
-    }
-    // A completed 4xx refusal (claims, binding, conflict, already registered)
-    // proves no intent exists and no resume can change the answer.
-    return { outcome: 'not_created', resumable: false };
-}
-function mintTokenExpiryMs(mintToken, fallbackMs) {
-    try {
-        const payload = mintToken.split('.')[1];
-        if (!payload)
-            return fallbackMs;
-        const claims = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
-        return typeof claims.exp === 'number' && Number.isFinite(claims.exp)
-            ? claims.exp * 1000
-            : fallbackMs;
-    }
-    catch {
-        return fallbackMs;
-    }
-}
-function boundedReceiptWriteErrorCode(reason) {
-    return reason.match(/\b(?:EACCES|EEXIST|ENOSPC|ENOTDIR|EPERM|EROFS)\b/)?.[0] ?? 'UNKNOWN';
-}
-// Must match the prepared-checkout store TTL so a session and its store entry
-// expire together — an abandoned review can't leak the browser + state.
-const PREPARED_TTL_MS = 5 * 60 * 1000;
-const defaultStore = new InMemoryPreparedCheckoutStore({ ttlMs: PREPARED_TTL_MS });
-const defaultSessions = new Map();
-const defaultPayAttempts = new Map();
-const defaultLedger = new MandateLedger();
-export function createCliCheckoutEngine(deps = {}) {
-    const store = deps.store ?? defaultStore;
-    const sessions = deps.sessions ?? defaultSessions;
-    const payAttempts = deps.payAttempts ?? defaultPayAttempts;
-    const ttlMs = deps.ttlMs ?? PREPARED_TTL_MS;
-    // #8470: process-bound resume handles for a budget whose intent bootstrap
-    // did not complete after owner approval. Holds the one-use bootstrap
-    // credential in memory only, for at most its own lifetime.
-    const pendingActivations = new Map();
-    function dropActivation(token) {
-        const pending = pendingActivations.get(token);
-        if (!pending)
-            return;
-        clearTimeout(pending.cleanupTimer);
-        pendingActivations.delete(token);
-    }
-    function parkActivation(pending) {
-        const token = `act_${randomBytes(18).toString('base64url')}`;
-        const cleanupTimer = setTimeout(() => dropActivation(token), Math.max(0, pending.expiresAtMs - now().getTime()));
-        cleanupTimer.unref?.();
-        pendingActivations.set(token, { ...pending, cleanupTimer });
-        return token;
-    }
-    function activationFailure(err, pending, existingToken) {
-        if (!(err instanceof ServerIntentError))
-            throw err;
-        const classified = classifyServerIntentFailure(err);
-        const resumeToken = classified.resumable
-            ? (existingToken ?? parkActivation(pending))
-            : undefined;
-        if (!classified.resumable && existingToken)
-            dropActivation(existingToken);
-        throw new CardMandateActivationError(err.message, {
-            phase: 'intent',
-            outcome: classified.outcome,
-            resumable: classified.resumable,
-            status: err.facts.status,
-            errorCode: err.facts.errorCode,
-            requestId: err.facts.requestId,
-            bootstrapState: err.facts.bootstrapState,
-            ...(resumeToken ? { resumeToken } : {}),
-            ...(resumeToken ? { resumeExpiresAt: new Date(pending.expiresAtMs).toISOString() } : {}),
-        });
-    }
-    const launchBrowser = deps.launchBrowser ?? (() => launchCheckoutBrowser());
-    const prepareCheckout = deps.prepareCheckout ?? realPrepareCheckout;
-    const submitApprovedCheckout = deps.submitApprovedCheckout ?? realSubmitApprovedCheckout;
-    const runHostedApproval = deps.runHostedApproval ?? realRunHostedApproval;
-    const claimMandatePickup = deps.claimMandatePickup ?? realClaimMandatePickup;
-    const reportVicOutcome = deps.reportVicOutcome ?? realReportVicOutcome;
-    const writeReceipt = deps.writeReceipt ?? realWriteReceipt;
-    const ledger = deps.ledger ?? defaultLedger;
-    const now = deps.now ?? (() => new Date());
-    const fetchMandateCryptogram = deps.serverFetchCryptogram ?? serverFetchCryptogram;
-    const postServerConfirmation = deps.serverPostConfirmation ?? serverPostConfirmation;
-    const createObservationId = deps.createObservationId ?? randomUUID;
-    async function writeObservedReceipt(mode, receipt) {
-        let report;
-        try {
-            report = await writeReceipt(RECEIPT_DIR, receipt);
-        }
-        catch (err) {
-            // The real writer is fail-open already. Keep that invariant even for an
-            // injected writer so a filesystem or test-double failure cannot replace
-            // the checkout result after a charge may have completed.
-            report = { written: false, reason: err instanceof Error ? err.message : String(err) };
-        }
-        const event = {
-            event: 'checkout_receipt_write',
-            status: report.written ? 'written' : 'failed',
-            mode,
-            checkoutOutcome: receipt.outcome,
-            merchantHost: receipt.merchant.host,
-            observationId: receipt.observationId ?? receipt.receiptId ?? createObservationId(),
-            failureCode: receipt.capability?.failureCode ?? null,
-            errorCode: report.written ? null : boundedReceiptWriteErrorCode(report.reason),
-            panRedactions: report.written ? report.panRedactions : null,
-        };
-        try {
-            const observerResult = deps.onReceiptWrite?.(event);
-            if (observerResult)
-                void Promise.resolve(observerResult).catch(() => undefined);
-        }
-        catch {
-            // Observability is non-authoritative and must not affect payment state.
-        }
-        return { report, event };
-    }
-    const cardDrawVerdict = deps.cardDrawVerdict ?? null;
-    const cardMandateRegister = deps.cardMandateRegister ?? null;
-    async function closeSession(reviewId) {
-        const session = sessions.get(reviewId);
-        if (!session)
-            return;
-        clearTimeout(session.cleanupTimer);
-        sessions.delete(reviewId);
-        await session.browser.close().catch(() => { });
-    }
-    function buildTarget(input) {
-        return {
-            merchantName: input.merchantName ?? new URL(input.url).hostname,
-            merchantUrl: input.url,
-            merchantCountryCode: input.merchantCountryCode ?? 'US',
-            transactionAmount: input.amount,
-            transactionCurrencyCode: input.currency,
-        };
-    }
-    /**
-     * Restate the facts at the ceiling the SERVER approved, when it lowered the
-     * one that was requested. Nothing has been spent or reserved on a mandate this
-     * new, so its remaining headroom IS its ceiling — see `createCardMandate`,
-     * which records `spentMinor: 0` with no reservations.
-     *
-     * Only ever lowers, mirroring `applyApprovedCeiling`: the server clamps
-     * downward, so a higher number means an unexpected response and is ignored
-     * rather than reported as headroom no human approved.
-     */
-    function approvedCeilingFacts(facts, approvedCeilingMinor) {
-        if (approvedCeilingMinor === undefined || approvedCeilingMinor >= facts.ceilingMinor)
-            return {};
-        return { ceilingMinor: approvedCeilingMinor, remainingMinor: approvedCeilingMinor };
-    }
-    // Seed the one server-authoritative cumulative store keyed by the VGS intent
-    // ID (#5942). On failure the local record is marked register-failed so
-    // findCovering() SKIPS it — the mandate exists but is never drawn tap-free —
-    // and the caller reports the failure honestly. Shared by mandate-start and
-    // pickup-claim; both refuse before their ceremony/claim when no capability
-    // can register, so registerCap is always present here.
-    async function registerMandateOrDisable(args) {
-        if (!cardMandateRegister)
-            return { registerFailed: true, registerFailureReason: 'no_seam' };
-        const reg = await cardMandateRegister
-            .register({
-            authBaseUrl: args.registerCap.authBaseUrl,
-            agentKey: args.registerCap.agentKey,
-            ...(args.registerCap.runtimeCertificate
-                ? { runtimeCertificate: args.registerCap.runtimeCertificate }
-                : {}),
-            mandateId: args.mandateId,
-            mintToken: args.mintToken,
-            ceiling: args.ceiling,
-            currency: args.currency,
-        })
-            .catch((err) => ({
-            ok: false,
-            reason: err instanceof Error ? err.message : String(err),
-        }));
-        if (reg.ok) {
-            // ONE SPENDING LIMIT: auth just clamped the requested ceiling to the
-            // owner's live grant cap and told us what it committed. Adopt it, so the
-            // local record — which findCovering() selects on and `mandate list`
-            // prints — states the budget the owner actually approved. Best-effort:
-            // the mandate is registered and drawable either way, and auth's verdict
-            // remains the enforcing cap, so a failed local write must not abort the
-            // ceremony. It leaves the record overstating headroom, which is exactly
-            // the pre-existing behaviour.
-            //
-            // If that write fails the returned facts still carry the approved figure —
-            // telling the human the truth beats echoing a ceiling their grant refused,
-            // and the ledger is left exactly as overstated as it was before this
-            // existed. But the two then disagree, so say so out loud rather than let
-            // `mandate list` quietly contradict what `mandate start` just printed.
-            // Same posture as the mark-failed escalation below.
-            if (reg.approvedCeilingMinor !== undefined) {
-                const applied = await ledger
-                    .applyApprovedCeiling(args.mandateId, reg.approvedCeilingMinor)
-                    .then(() => true)
-                    .catch(() => false);
-                if (!applied) {
-                    // Rendered through minorToDecimal, never raw /100 — and only when the
-                    // value is a sane integer, because THIS branch is also where an
-                    // unusable value lands (applyApprovedCeiling rejects it). A warning
-                    // must not throw on its way out. The currency is omitted deliberately:
-                    // both mandate paths refuse anything but USD long before register, so
-                    // it is known, and passing it would let a non-2-decimal code throw here.
-                    const approved = Number.isSafeInteger(reg.approvedCeilingMinor) && reg.approvedCeilingMinor > 0
-                        ? ` (${args.currency} ${minorToDecimal(reg.approvedCeilingMinor)})`
-                        : '';
-                    process.stderr.write(`warning: your owner's approved limit for this budget${approved} could NOT be saved ` +
-                        `locally — 'mandate list' will overstate the remaining balance until you re-run ` +
-                        `'mandate start'. Spending is still capped at the approved limit; a draw over it ` +
-                        `is refused. mandateId=${args.mandateId}\n`);
-                }
-            }
-            return {
-                registerFailed: false,
-                ...(reg.approvedCeilingMinor !== undefined
-                    ? { approvedCeilingMinor: reg.approvedCeilingMinor }
-                    : {}),
-            };
-        }
-        // Register failed: the server `card_mandate_spend` row was never created, so
-        // a delegated draw against this mandate would 404 `no_mandate`. Mark it
-        // register-failed so findCovering() SKIPS it rather than silently selecting
-        // a mandate that can't be drawn. A v4 grant then refuses until a usable
-        // mandate exists; only a legacy credential-file runtime can still use the
-        // old per-purchase approval. Marking is best-effort too.
-        const marked = await ledger
-            .markRegisterFailed(args.mandateId, now())
-            .then(() => true)
-            .catch(() => false);
-        process.stderr.write(marked
-            ? `warning: card-mandate register failed (${reg.reason ?? 'unknown'}) — this mandate ` +
-                `will NOT be used for draws. A v4 card grant cannot spend until a usable mandate ` +
-                `is registered. Re-run 'mandate start' to try again.\n`
-            : // Escalate: the mark write ALSO failed, so the mandate is persisted but
-                // NOT disabled — findCovering could still select an undrawable mandate.
-                // Tell the owner loudly not to rely on it and how to recover.
-                `warning: card-mandate register failed (${reg.reason ?? 'unknown'}) AND the mandate ` +
-                    `could NOT be disabled locally — do not rely on it. Run 'mandate list' and re-run ` +
-                    `'mandate start'. mandateId=${args.mandateId}\n`);
-        return {
-            registerFailed: true,
-            ...(reg.reason !== undefined ? { registerFailureReason: reg.reason } : {}),
-        };
-    }
-    // Shared by mandate-start and resume: mint (or adopt) the ceiling intent,
-    // persist the owner-only ledger entry, and register server-side.
-    async function activateBudget(pending, createIntent) {
-        const facts = await createCardMandate({
-            agentJkt: pending.registerCap.agentJkt,
-            tokenId: pending.tokenId,
-            assuranceData: pending.assuranceData,
-            ceilingMinor: pending.ceilingMinor,
-            merchant: pending.merchant,
-            currencyCode: pending.currency,
-            expiresAt: pending.expiresAt,
-            maxDraws: DEFAULT_MANDATE_MAX_DRAWS,
-            crossMerchant: true,
-        }, {
-            createIntent,
-            ledger,
-            approvalBaseUrl: pending.approvalBaseUrl,
-            now,
-        });
-        // Seed the one server-authoritative cumulative store keyed by the VGS
-        // intent ID. A later draw requires its PoP verdict; the budget token never
-        // falls back as payable authority.
-        const registered = await registerMandateOrDisable({
-            registerCap: pending.registerCap,
-            mandateId: facts.mandateId,
-            mintToken: pending.mintToken,
-            ceiling: pending.ceiling,
-            currency: pending.currency,
-        });
-        return {
-            ...facts,
-            ...approvedCeilingFacts(facts, registered.approvedCeilingMinor),
-            merchantHost: new URL(pending.merchant.url).hostname,
-            registerFailed: registered.registerFailed,
-            ...(registered.registerFailureReason !== undefined
-                ? { registerFailureReason: registered.registerFailureReason }
-                : {}),
-        };
-    }
-    return {
-        // BUDGET step: one passkey approves a CEILING; a VGS intent is minted with
-        // that ceiling as its decline threshold and the owner-only ledger records
-        // the cumulative budget. No browser checkout is prepared — this is purely
-        // the passkey ceremony + intent, so later pay() draws need no fresh tap.
-        async startCardMandate(input) {
-            const ceilingMinor = decimalToMinor(input.ceiling);
-            if (ceilingMinor === null || ceilingMinor <= 0) {
-                throw new Error(`invalid mandate ceiling ${JSON.stringify(input.ceiling)}`);
-            }
-            if (input.currency.toUpperCase() !== 'USD') {
-                throw new Error('card spend budgets currently support USD only');
-            }
-            if (input.perTransaction !== undefined) {
-                const perTxMinor = decimalToMinor(input.perTransaction);
-                if (perTxMinor === null || perTxMinor <= 0 || perTxMinor > ceilingMinor) {
-                    throw new Error(`invalid mandate perTransaction ${JSON.stringify(input.perTransaction)} — ` +
-                        'must be a positive amount at or under the ceiling');
-                }
-            }
-            // A budget token can bootstrap one VGS intent and its register handshake,
-            // but it is never payable draw authority. Refuse before the passkey
-            // ceremony unless this runtime can both prove the separately provisioned
-            // card capability and register the resulting intent server-side.
-            const registerCap = cardMandateRegister?.loadCapability(input.agentRef) ?? null;
-            if (!cardMandateRegister || !registerCap) {
-                throw new Error('startCardMandate requires separately provisioned card authority in this runtime; ' +
-                    'identity pairing alone does not grant a card mandate');
-            }
-            // There is one budget product: eligible retail merchants under the
-            // provider's required Retail/5999 network category, with total,
-            // per-purchase, count, and time bounds stated on the approval page. The
-            // sentinel is provider metadata, never a user-entered merchant route.
-            const merchant = {
-                name: 'retail spend budget',
-                url: 'https://retail-budget.visa/budget',
-                countryCode: 'US',
-            };
-            // Legacy credential file OR the activated card:vic grant's token — see
-            // resolveCardInstrument. A v2-paired runtime only ever has the latter.
-            const credential = await resolveCardInstrument(input);
-            // The passkey ceremony is scoped to the CEILING + merchant (not one
-            // charge) — that scope is the unproven part of the spike.
-            const ceilingTarget = {
-                merchantName: merchant.name,
-                merchantUrl: merchant.url,
-                merchantCountryCode: merchant.countryCode,
-                transactionAmount: input.ceiling,
-                transactionCurrencyCode: input.currency,
-            };
-            // BUDGET mode: the ceiling target's amount IS the approved ceiling, so the
-            // server mints a budget mint token bound to that ceiling — later draws pull
-            // sub-ceiling amounts against it tap-free.
-            const assurance = await runHostedApproval({
-                baseUrl: input.approvalBaseUrl,
-                tokenId: credential.tokenId,
-                target: ceilingTarget,
-                consumerEmail: input.contact.email,
-                budget: true,
-                agentJkt: registerCap.agentJkt,
-                onApprovalUrl: input.onApprovalUrl ?? deps.onApprovalUrl,
-                maxDraws: DEFAULT_MANDATE_MAX_DRAWS,
-                ...(input.perTransaction !== undefined ? { perTransaction: input.perTransaction } : {}),
-                ...(input.intent !== undefined ? { intent: input.intent } : {}),
-            });
-            const mintToken = assurance.mintToken;
-            if (!mintToken) {
-                throw new Error('the approval server issued no mint token — server-side minting requires the ' +
-                    'verify-web deployment to run real/turnkey auth (not the dev stub). Retry once it does.');
-            }
-            if (!Number.isSafeInteger(assurance.validUntil) ||
-                assurance.validUntil <= Math.floor(now().getTime() / 1000)) {
-                throw new Error('the approval server issued no valid budget expiry');
-            }
-            const expiresAt = new Date(assurance.validUntil * 1000).toISOString();
-            const pending = {
-                mintToken,
-                assuranceData: assurance.assuranceData,
-                ceiling: input.ceiling,
-                ceilingMinor,
-                currency: input.currency,
-                merchant,
-                expiresAt,
-                tokenId: credential.tokenId,
-                approvalBaseUrl: input.approvalBaseUrl,
-                registerCap,
-                expiresAtMs: mintTokenExpiryMs(mintToken, now().getTime() + 10 * 60 * 1000),
-            };
-            return activateBudget(pending, (i) => serverCreateIntent(input.approvalBaseUrl, mintToken, i)).catch((err) => activationFailure(err, pending));
-        },
-        // RESUME leg (#8470): the owner already approved, but the intent bootstrap
-        // did not complete. Read the server's durable state under the SAME one-use
-        // credential: a created intent is registered as-is, nothing-dispatched is
-        // dispatched once, pending/ambiguous stays uncertain. No approval page, no
-        // passkey, and never a sibling intent.
-        async resumeCardMandate(input) {
-            const pending = pendingActivations.get(input.resumeToken);
-            if (!pending || pending.expiresAtMs <= now().getTime()) {
-                if (pending)
-                    dropActivation(input.resumeToken);
-                throw new CardMandateActivationError('no resumable budget activation for this operation — its approval credential expired; start a fresh approval', {
-                    phase: 'intent',
-                    outcome: 'not_created',
-                    resumable: false,
-                    status: null,
-                    errorCode: 'activation_resume_expired',
-                    requestId: null,
-                    bootstrapState: 'unknown',
-                });
-            }
-            let read;
-            try {
-                read = await serverReadIntentBootstrap(pending.approvalBaseUrl, pending.mintToken);
-            }
-            catch (err) {
-                return activationFailure(err, pending, input.resumeToken);
-            }
-            if (read.state === 'created' && read.intentId) {
-                const intentId = read.intentId;
-                const facts = await activateBudget(pending, async () => ({
-                    intentId,
-                    status: read.intentStatus,
-                }));
-                dropActivation(input.resumeToken);
-                return facts;
-            }
-            if (read.state === 'none') {
-                return activateBudget(pending, (i) => serverCreateIntent(pending.approvalBaseUrl, pending.mintToken, i))
-                    .then((facts) => {
-                    dropActivation(input.resumeToken);
-                    return facts;
-                })
-                    .catch((err) => activationFailure(err, pending, input.resumeToken));
-            }
-            throw new CardMandateActivationError(read.state === 'ambiguous'
-                ? 'the card network never confirmed this budget intent and its outcome cannot be verified; this approval cannot be reused'
-                : read.state === 'pending'
-                    ? 'this budget intent is still being created; check again shortly'
-                    : 'the budget activation state could not be read; check again shortly', {
-                phase: 'intent',
-                outcome: 'uncertain',
-                // Stays parked and queryable: a further resume only re-reads state
-                // and can never redispatch under this token.
-                resumable: true,
-                status: null,
-                errorCode: read.state === 'ambiguous'
-                    ? 'budget_intent_creation_ambiguous'
-                    : read.state === 'pending'
-                        ? 'budget_intent_creation_pending'
-                        : 'budget_intent_state_unavailable',
-                requestId: read.requestId,
-                bootstrapState: read.state,
-                resumeToken: input.resumeToken,
-                resumeExpiresAt: new Date(pending.expiresAtMs).toISOString(),
-            });
-        },
-        // PICKUP leg: the owner already approved the ceiling in the account panel
-        // and handed this runtime a single-use pickup code. Claim it, verify it was
-        // minted for exactly this runtime's request key + card token, then run the
-        // same intent → register → ledger sequence as startCardMandate. No approval
-        // page, no passkey, no contact profile — the human side already happened.
-        async claimCardMandate(input) {
-            const registerCap = cardMandateRegister?.loadCapability(input.agentRef) ?? null;
-            if (!cardMandateRegister || !registerCap) {
-                throw new Error('claimCardMandate requires separately provisioned card authority in this runtime; ' +
-                    'identity pairing alone does not grant a card mandate');
-            }
-            const credential = await resolveCardInstrument(input);
-            const claim = await claimMandatePickup({
-                baseUrl: input.approvalBaseUrl,
-                pickupCode: input.pickupCode,
-                agentJkt: registerCap.agentJkt,
-                ...(input.expectedHandoffId ? { expectedHandoffId: input.expectedHandoffId } : {}),
-                tokenId: credential.tokenId,
-            });
-            const ceilingMinor = decimalToMinor(claim.ceiling);
-            if (ceilingMinor === null || ceilingMinor <= 0) {
-                throw new Error(`the handoff carried an invalid ceiling ${JSON.stringify(claim.ceiling)}`);
-            }
-            // Same single-product bound as mandate-start (the panel initiate route
-            // enforces it too; a divergent store entry must not widen it here).
-            if (claim.currency.toUpperCase() !== 'USD') {
-                throw new Error('card spend budgets currently support USD only');
-            }
-            const expiresAt = new Date(claim.validUntil * 1000).toISOString();
-            const facts = await createCardMandate({
-                agentJkt: registerCap.agentJkt,
-                tokenId: credential.tokenId,
-                assuranceData: claim.assuranceData,
-                ceilingMinor,
-                merchant: claim.merchant,
-                currencyCode: claim.currency,
-                expiresAt,
-                maxDraws: claim.maxDraws,
-                crossMerchant: true,
-            }, {
-                createIntent: (i) => serverCreateIntent(input.approvalBaseUrl, claim.mintToken, i),
-                ledger,
-                approvalBaseUrl: input.approvalBaseUrl,
-                now,
-            });
-            const registered = await registerMandateOrDisable({
-                registerCap,
-                mandateId: facts.mandateId,
-                mintToken: claim.mintToken,
-                ceiling: claim.ceiling,
-                currency: claim.currency,
-            });
-            return {
-                ...facts,
-                ...approvedCeilingFacts(facts, registered.approvedCeilingMinor),
-                merchantHost: new URL(claim.merchant.url).hostname,
-                registerFailed: registered.registerFailed,
-                ...(registered.registerFailureReason !== undefined
-                    ? { registerFailureReason: registered.registerFailureReason }
-                    : {}),
-            };
-        },
-        async review(input) {
-            const amountMinor = decimalToMinor(input.amount);
-            if (amountMinor === null)
-                throw new Error(`invalid amount ${JSON.stringify(input.amount)}`);
-            const host = new URL(input.url).hostname;
-            const browser = await launchBrowser();
-            try {
-                const prep = await prepareCheckout({
-                    url: input.url,
-                    checkoutRoute: input.checkoutRoute,
-                    mandate: {
-                        maxAmountMinor: amountMinor,
-                        currency: input.currency,
-                        merchantHost: host,
-                        expiresAt: new Date(Date.now() + 15 * 60 * 1000).toISOString(),
-                    },
-                    amountMinor,
-                    currency: input.currency,
-                    browser,
-                    contact: input.contact,
-                    ...(input.trustedMerchantIdentity
-                        ? { trustedMerchantIdentity: input.trustedMerchantIdentity }
-                        : {}),
-                }, store);
-                if (prep.status !== 'ready') {
-                    // A terminal review is still a capability observation. Persist the
-                    // same compact, owner-only artifact as a pay attempt so the local
-                    // ledger records unsupported merchant surfaces and the safe card
-                    // display identity instead of retaining successes only.
-                    const observationId = createObservationId();
-                    const receiptWrite = await writeObservedReceipt('dry-run', buildReceipt({
-                        mode: 'dry-run',
-                        reviewId: null,
-                        observationId,
-                        merchant: {
-                            name: input.merchantName ?? host,
-                            host,
-                            url: input.url,
-                        },
-                        transaction: {
-                            amount: input.amount,
-                            amountMinor,
-                            currency: input.currency,
-                        },
-                        result: prep.result,
-                        vicConfirmation: null,
-                        agentName: input.agentName,
-                        cardLast4: input.cardLast4,
-                        recordedAt: now(),
-                    }));
-                    throw new CheckoutReviewRefusedError(prep.result, receiptWrite.event);
-                }
-                const r = prep.checkout.review;
-                // Expire the companion session on the SAME schedule as the store entry
-                // (unref'd so a pending timer never keeps the process alive).
-                const cleanupTimer = setTimeout(() => void closeSession(r.id), ttlMs);
-                cleanupTimer.unref?.();
-                const target = buildTarget(input);
-                if (r.merchantOrigin) {
-                    // The credential and mandate bind to the exact origin the browser
-                    // actually reviewed, not the Shopify service continuation that led
-                    // there. Keep the latter separately for review/pay replay binding.
-                    target.merchantUrl = r.merchantOrigin;
-                    target.merchantName = input.merchantName ?? r.merchantHost;
-                }
-                sessions.set(r.id, {
-                    browser,
-                    requestUrl: new URL(input.url).toString(),
-                    checkoutRoute: input.checkoutRoute,
-                    target,
-                    amountMinor,
-                    currency: input.currency,
-                    contact: input.contact,
-                    ...(input.agentJkt ? { agentJkt: input.agentJkt } : {}),
-                    ...(input.intentNarrative ? { intentNarrative: input.intentNarrative } : {}),
-                    cleanupTimer,
-                });
-                return {
-                    reviewId: r.id,
-                    merchantHost: r.merchantHost,
-                    amountMinor: r.amountMinor,
-                    currency: r.currency,
-                    submitTargetFingerprint: JSON.stringify(r.submitTargetFingerprint ?? null),
-                    detectedRoles: [...r.detectedRoles],
-                };
-            }
-            catch (err) {
-                await browser.close().catch(() => { });
-                throw err;
-            }
-        },
-        /**
-         * Give up a prepared review without paying it (#7100).
-         *
-         * The retained browser is what lets a same-process MCP `review` → `pay`
-         * draw against the checkout it already inspected. A TERMINAL review-only
-         * run has no such second call — that process tells the operator to re-RUN
-         * with `--submit`, and the new process cannot reach this one's in-memory
-         * session. So the browser sat open for the full TTL, and because a live
-         * browser connection keeps the event loop alive, a command that had already
-         * succeeded looked hung until Ctrl-C.
-         *
-         * Idempotent and non-throwing: an unknown or already-released id is a
-         * no-op, so it is safe on an error path that may not have prepared anything
-         * and safe to call twice.
-         */
-        async releaseReview(reviewId) {
-            await closeSession(reviewId);
-            payAttempts.delete(reviewId);
-        },
-        async pay(input) {
-            const noCredentialFacts = {
-                credentialIssued: false,
-                credentialDisclosed: false,
-            };
-            const fingerprint = payAttemptFingerprint(input);
-            const priorAttempt = payAttempts.get(input.reviewId);
-            if (priorAttempt) {
-                return priorAttempt.fingerprint === fingerprint
-                    ? priorAttempt.promise
-                    : failedPay(`review ${input.reviewId} is already executing with different payment facts — wait for that exact attempt and inspect its receipt`);
-            }
-            const session = sessions.get(input.reviewId);
-            // One signal for the whole pay lifecycle. `cardTokenId` is populated only
-            // by the resolved v4 card-grant authority; legacy credential-file calls
-            // omit it. Keeping the classification here prevents copy and fallback
-            // behavior from drifting onto different grant detectors.
-            const isV4CardGrant = typeof input.cardTokenId === 'string' && input.cardTokenId.trim() !== '';
-            if (!session) {
-                return {
-                    outcome: 'failed',
-                    confirmationRef: null,
-                    receiptPath: null,
-                    detail: `no prepared review ${input.reviewId} — call review first (a review does not survive a restart)`,
-                    vicConfirmation: null,
-                    source: null,
-                    remainingMinor: null,
-                    ...noCredentialFacts,
-                };
-            }
-            // The reviewId selects the prepared browser session, but the pay call also
-            // repeats the target facts. Refuse if any repeated fact disagrees so the
-            // caller cannot submit one reviewed checkout while labeling the result or
-            // telemetry as another. Never echo the full URLs: payment links can carry
-            // claimable secrets in their path/query.
-            let payUrl;
-            let reviewedUrl;
-            try {
-                payUrl = new URL(input.url).toString();
-                reviewedUrl = session.requestUrl;
-            }
-            catch {
-                await closeSession(input.reviewId);
-                return {
-                    outcome: 'failed',
-                    confirmationRef: null,
-                    receiptPath: null,
-                    detail: 'pay merchant URL is invalid or does not match the reviewed checkout — start a fresh review',
-                    vicConfirmation: null,
-                    source: null,
-                    remainingMinor: null,
-                    ...noCredentialFacts,
-                };
-            }
-            if (payUrl !== reviewedUrl) {
-                await closeSession(input.reviewId);
-                return {
-                    outcome: 'failed',
-                    confirmationRef: null,
-                    receiptPath: null,
-                    detail: 'pay merchant URL does not match the reviewed checkout — start a fresh review',
-                    vicConfirmation: null,
-                    source: null,
-                    remainingMinor: null,
-                    ...noCredentialFacts,
-                };
-            }
-            if (input.currency.toUpperCase() !== session.currency.toUpperCase()) {
-                await closeSession(input.reviewId);
-                return {
-                    outcome: 'failed',
-                    confirmationRef: null,
-                    receiptPath: null,
-                    detail: `pay currency ${JSON.stringify(input.currency)} does not match the reviewed currency (${session.currency}) — start a fresh review`,
-                    vicConfirmation: null,
-                    source: null,
-                    remainingMinor: null,
-                    ...noCredentialFacts,
-                };
-            }
-            if (input.agentJkt !== session.agentJkt) {
-                await closeSession(input.reviewId);
-                return {
-                    outcome: 'failed',
-                    confirmationRef: null,
-                    receiptPath: null,
-                    detail: 'pay agent authority does not match the reviewed request key — start a fresh review',
-                    vicConfirmation: null,
-                    source: null,
-                    remainingMinor: null,
-                    ...noCredentialFacts,
-                };
-            }
-            if (input.checkoutRoute !== session.checkoutRoute) {
-                await closeSession(input.reviewId);
-                return {
-                    outcome: 'failed',
-                    confirmationRef: null,
-                    receiptPath: null,
-                    detail: 'pay checkout route does not match the reviewed guest-card route — start a fresh review',
-                    vicConfirmation: null,
-                    source: null,
-                    remainingMinor: null,
-                    ...noCredentialFacts,
-                };
-            }
-            // Amount-bind the confirmation: the pay-call amount must match the
-            // reviewed amount. The reviewId already locks the immutable mandate, but
-            // re-checking here makes the confirmation explicitly amount-bound so a
-            // caller cannot pay a different figure than the human reviewed.
-            const payAmountMinor = decimalToMinor(input.amount);
-            if (payAmountMinor !== session.amountMinor) {
-                await closeSession(input.reviewId);
-                return {
-                    outcome: 'failed',
-                    confirmationRef: null,
-                    receiptPath: null,
-                    detail: `pay amount ${JSON.stringify(input.amount)} does not match the reviewed amount (${session.amountMinor} minor units) — start a fresh review`,
-                    vicConfirmation: null,
-                    source: null,
-                    remainingMinor: null,
-                    ...noCredentialFacts,
-                };
-            }
-            // Reject an expired prepared checkout BEFORE running the hosted passkey
-            // approval — the store may have expired/closed the entry while the review
-            // waited. Peeking here avoids minting a credential we can't submit.
-            if (!store.peek(input.reviewId)) {
-                await closeSession(input.reviewId);
-                return {
-                    outcome: 'failed',
-                    confirmationRef: null,
-                    receiptPath: null,
-                    detail: `prepared review ${input.reviewId} expired — start a fresh review`,
-                    vicConfirmation: null,
-                    source: null,
-                    remainingMinor: null,
-                    ...noCredentialFacts,
-                };
-            }
-            let resolveAttempt;
-            let rejectAttempt;
-            const sharedResult = new Promise((resolve, reject) => {
-                resolveAttempt = resolve;
-                rejectAttempt = reject;
-            });
-            // The first caller still receives the direct execution result below; this
-            // retained promise exists for overlapping and bounded late duplicates.
-            // Mark its rejection handled even when there is no duplicate consumer.
-            void sharedResult.catch(() => undefined);
-            payAttempts.set(input.reviewId, { fingerprint, promise: sharedResult });
-            let completedAttempt;
-            const finishAttempt = (result) => {
-                completedAttempt = result;
-                resolveAttempt(result);
-                return result;
-            };
-            clearTimeout(session.cleanupTimer);
-            try {
-                // NO instrument read here. A tap-free mandate draw spends `covering
-                // .tokenId` (frozen into the mandate at start) and needs neither the
-                // legacy credential file nor a grant token, so a grant-only device with
-                // an as-yet-unrefreshed token can still draw on a mandate it already
-                // holds.
-                const host = new URL(session.target.merchantUrl).hostname;
-                // Does an ACTIVE card mandate already cover this exact purchase? If so,
-                // draw against it TAP-FREE (no hosted passkey). Else refuse with the
-                // mandate remedy (#7348). Mandates no longer persist the bootstrap
-                // token: it is consumed by intent creation + register and has no draw
-                // power.
-                const covering = await ledger.findCovering({
-                    merchantHost: host,
-                    currencyCode: session.currency,
-                    amountMinor: session.amountMinor,
-                    agentJkt: session.agentJkt,
-                    now: now(),
-                });
-                let source;
-                let confirmBase;
-                // Mandate draws set this only after the local reserve succeeds and auth
-                // returns the exact per-draw verdict used to mint the credential.
-                let confirmationAuthority = null;
-                let drawnRemaining = null;
-                let instrument;
-                if (covering) {
-                    // --- Tap-free mandate draw ------------------------------------------
-                    source = 'mandate';
-                    confirmBase = covering.approvalBaseUrl;
-                    const mandateId = covering.mandateId;
-                    // A mandate cryptogram is authorized only by a PoP-signed verdict.
-                    // The budget mint token is bootstrap-only and cannot bypass the
-                    // server reserve/commit ledger when local draw authority is absent.
-                    //
-                    // #5928 CRITICAL-2: the CLI does NOT settle the reservation. verify-web
-                    // (which knows whether the cryptogram was payable) commits it on a
-                    // payable mint and releases it on a decline, server-authoritatively, so
-                    // the drawer can never release after a payable mint to dodge the ceiling.
-                    const verdictSeam = cardDrawVerdict;
-                    const capability = verdictSeam?.loadCapability(covering.agentJkt) ?? null;
-                    if (!capability || !verdictSeam) {
-                        return finishAttempt({
-                            outcome: 'failed',
-                            confirmationRef: null,
-                            receiptPath: null,
-                            detail: 'this mandate cannot draw because its delegated card authority is unavailable; ' +
-                                're-pair this runtime to restore the binding, or start a new mandate for this agent',
-                            vicConfirmation: null,
-                            source,
-                            remainingMinor: null,
-                            ...noCredentialFacts,
-                        });
-                    }
-                    if (covering.agentJkt && capability.agentJkt !== covering.agentJkt) {
-                        return finishAttempt({
-                            outcome: 'failed',
-                            confirmationRef: null,
-                            receiptPath: null,
-                            detail: 'this budget belongs to a different request key than the selected card capability; ' +
-                                'restore that exact runtime key, or start a new mandate from the current runtime',
-                            vicConfirmation: null,
-                            source,
-                            remainingMinor: null,
-                            ...noCredentialFacts,
-                        });
-                    }
-                    // VgsLiveInstrument mints against an EXISTING intent (the mandate) with
-                    // no fresh assurance — exactly the draw semantics. The fetchCredential
-                    // seam routes through drawFromMandate so the ledger accounting (reserve
-                    // -> commit on payable, release on reject) wraps the cryptogram pull.
-                    const reference = {
-                        tokenId: covering.tokenId,
-                        intentId: mandateId,
-                        merchantName: session.target.merchantName,
-                        merchantUrl: session.target.merchantUrl,
-                        merchantCountryCode: session.target.merchantCountryCode,
-                        transactionAmount: session.target.transactionAmount,
-                        transactionCurrencyCode: session.currency,
-                    };
-                    const fetchCredential = async ({ transaction }) => {
-                        let draw;
-                        try {
-                            draw = await drawFromMandate({
-                                mandateId,
-                                amountMinor: session.amountMinor,
-                                transaction: { ...transaction, transactionCurrencyCode: session.currency },
-                            }, {
-                                // Ordering matters: reserve the local ledger FIRST, then ask
-                                // auth to reserve the server-authoritative budget immediately
-                                // before the payable mint. A local reserve race/expiry/file
-                                // failure therefore makes zero auth/verdict calls and cannot
-                                // strand a server reservation until its sweep.
-                                fetchCryptogram: async (i) => {
-                                    const { verdict } = await verdictSeam.fetchVerdict({
-                                        authBaseUrl: capability.authBaseUrl,
-                                        agentKey: capability.agentKey,
-                                        ...(capability.runtimeCertificate
-                                            ? { runtimeCertificate: capability.runtimeCertificate }
-                                            : {}),
-                                        mandateId,
-                                        // One draw per review; the reviewId is auth's idempotency key.
-                                        drawId: input.reviewId,
-                                        draw: {
-                                            tokenId: covering.tokenId,
-                                            amount: session.target.transactionAmount,
-                                            currency: session.currency,
-                                            merchantName: session.target.merchantName,
-                                            merchantUrl: session.target.merchantUrl,
-                                            merchantCountryCode: session.target.merchantCountryCode,
-                                        },
-                                        ...(session.intentNarrative
-                                            ? { intentNarrative: session.intentNarrative }
-                                            : {}),
-                                    });
-                                    confirmationAuthority = verdict;
-                                    return fetchMandateCryptogram(confirmBase, verdict, i);
-                                },
-                                ledger,
-                                now,
-                            });
-                        }
-                        catch (err) {
-                            // Disable the mandate ONLY for a post-reservation NETWORK decline
-                            // (MandateDrawDeclinedError). That case leaves the mandate
-                            // active+covering, so a naive retry would re-select it and fail
-                            // identically — trapping the caller; marking it unhonored makes the
-                            // next pay_merchant skip it and surface the no-covering-mandate refusal
-                            // (#7348) instead of re-failing identically. We do
-                            // NOT attempt an unsafe same-call browser fallback mid-submit.
-                            //
-                            // A PRE-network failure — reserve() failing closed on a concurrent
-                            // over-budget race or expiry, or commit() throwing on file I/O —
-                            // is NOT a network decline: the mandate is HEALTHY, so we must
-                            // rethrow WITHOUT disabling it (michaelyang1 M1). drawFromMandate
-                            // has already released any reservation, so the budget is intact.
-                            // Only a DEFINITIVE (hard) decline disables the mandate. A TRANSIENT
-                            // failure — a gateway 5xx / "not completed, try again" / network
-                            // reset/timeout — must NOT permanently kill the budget: the mandate
-                            // may be perfectly healthy (it can have committed a draw seconds
-                            // earlier) and the rails may recover on retry. Over-disabling on a
-                            // transient 502 threw away good budgets and forced a fresh passkey
-                            // every time.
-                            // Classify on the underlying gateway CAUSE, not the MandateDrawDeclinedError
-                            // wrapper — the wrapper's own advisory text mentions "try again"/"network",
-                            // which would otherwise self-classify every decline as transient.
-                            if (err instanceof MandateDrawDeclinedError) {
-                                const verdictFailure = classifyCardDrawVerdictFailure(err);
-                                if (verdictFailure) {
-                                    // #7491: a GRANT-capacity refusal is pre-credential and says
-                                    // nothing about this mandate, so it must NOT disable it. The
-                                    // mandate is healthy and becomes drawable again the moment the
-                                    // owner supplies a grant with room; disabling it here threw
-                                    // away a just-approved budget and pointed the caller at a new
-                                    // mandate that would die on the same wall.
-                                    if (!verdictFailure.transient && !verdictFailure.grantCapacity) {
-                                        await ledger.markUnhonored(mandateId, now()).catch(() => { });
-                                    }
-                                    if (verdictFailure.grantCapacity) {
-                                        throw new Error(`this agent's card grant has no remaining capacity (${verdictFailure.reasons.join(', ') || 'grant exhausted'}) — nothing was charged and the mandate is still valid; ask the owner for a new or replenished card grant (visa agent grant-card) before retrying this checkout`, { cause: err });
-                                    }
-                                    throw new Error(verdictFailure.transient
-                                        ? `the card-mandate draw could not be authorized right now (${verdictFailure.reasons.join(', ') || 'temporary error'}) — retry shortly`
-                                        : `this card mandate can no longer be drawn (${verdictFailure.reasons.join(', ') || 'refused'}); it has been disabled — create and claim a new mandate before retrying this checkout`, { cause: err });
-                                }
-                                if (!isTransientDrawFailure(err.cause ?? err)) {
-                                    await ledger.markUnhonored(mandateId, now());
-                                }
-                            }
-                            // #5928 CRITICAL-2: the server-side reservation is released by
-                            // verify-web (it saw the mint fail), not here — the CLI never settles.
-                            throw err;
-                        }
-                        drawnRemaining = draw.remainingMinor;
-                        // #5928 CRITICAL-2: the reservation is committed by verify-web on the
-                        // payable mint (server-authoritative); the CLI does not settle.
-                        return draw.payment;
-                    };
-                    instrument = new VgsLiveInstrument(reference, session.contact.fullName ?? '', fetchCredential);
-                }
-                else {
-                    // #7348 single-purchase retirement: card spend is mandate-only for
-                    // EVERY runtime. The legacy 1:1 single-purchase flow here minted a
-                    // payable credential outside the grant/mandate ledger — invisible to
-                    // spending controls. The server now refuses non-budget approvals at
-                    // registration and non-budget mint tokens at verification; this
-                    // client refusal exists to give the honest remedy up front instead
-                    // of a mid-flow server error.
-                    return finishAttempt({
-                        outcome: 'failed',
-                        confirmationRef: null,
-                        receiptPath: null,
-                        detail: isV4CardGrant
-                            ? 'this v4 card grant has no active mandate covering the purchase; run ' +
-                                '`visa mandate start --ceiling <usd> --per-transaction <usd>` for the selected ' +
-                                'agent, approve and claim the mandate, then retry this checkout. No payment ' +
-                                'credential was requested and no charge was made.'
-                            : 'one-off card approvals are retired (#7348): card spending always runs through ' +
-                                'an owner-approved mandate now. Attach card authority to this agent ' +
-                                '(`visa agent grant-card <agent-id> --ceiling <usd> --per-transaction <usd> --wait`), ' +
-                                'then start and claim a mandate (`visa mandate start <usd> --per-transaction <usd>`), ' +
-                                'and retry the checkout. No payment credential was requested and no charge was made.',
-                        vicConfirmation: null,
-                        source: null,
-                        remainingMinor: null,
-                        ...noCredentialFacts,
-                    });
-                }
-                const mode = input.submit ? 'submit' : 'dry-run';
-                const result = await submitApprovedCheckout(input.reviewId, {
-                    approval: { approved: true, reviewId: input.reviewId },
-                    instrument,
-                    contact: session.contact,
-                    mode,
-                    ...(deps.resolveEmailOtp ? { resolveEmailOtp: deps.resolveEmailOtp } : {}),
-                }, store);
-                // Report the observed submit outcome to VIC for the consumed intent
-                // (APPROVED/DECLINED). Only definitive submit answers post. Mirrors
-                // run-live-fill.ts.
-                let vicConfirmation = null;
-                let processorIntentId = null;
-                if (mode === 'submit') {
-                    const confirmationTarget = instrument.confirmationTarget();
-                    processorIntentId = confirmationTarget?.intentId ?? null;
-                    vicConfirmation = await reportVicOutcome({
-                        target: confirmationTarget,
-                        outcome: result.outcome,
-                        transaction: {
-                            transactionAmount: session.target.transactionAmount,
-                            transactionCurrencyCode: session.currency,
-                        },
-                        post: (confInput) => {
-                            if (!confirmationAuthority) {
-                                throw new Error('confirmation authority missing for the consumed VIC intent');
-                            }
-                            return postServerConfirmation(confirmBase, confirmationAuthority, confInput);
-                        },
-                    });
-                }
-                let receiptPath = null;
-                const receiptWrite = await writeObservedReceipt(mode, buildReceipt({
-                    mode,
-                    reviewId: input.reviewId,
-                    // Derive BOTH name and host from the reviewed session target (not
-                    // pay()'s input.url), so the receipt always reflects the checkout
-                    // the human actually reviewed + that reviewId bound for submit.
-                    merchant: {
-                        name: session.target.merchantName,
-                        host: new URL(session.target.merchantUrl).hostname,
-                        url: session.target.merchantUrl,
-                    },
-                    transaction: {
-                        amount: session.target.transactionAmount,
-                        amountMinor: session.amountMinor,
-                        currency: session.currency,
-                    },
-                    result,
-                    vicConfirmation,
-                    agentName: input.agentName,
-                    cardLast4: input.cardLast4,
-                }));
-                if (receiptWrite.report.written)
-                    receiptPath = receiptWrite.report.path;
-                return finishAttempt({
-                    outcome: result.outcome,
-                    confirmationRef: result.confirmationRef ?? null,
-                    receiptPath,
-                    detail: result.detail ?? null,
-                    vicConfirmation,
-                    source,
-                    remainingMinor: drawnRemaining,
-                    processorIntentId,
-                    credentialIssued: result.credentialLifecycle !== 'not-requested',
-                    credentialDisclosed: result.credentialLifecycle === 'partially-exposed' ||
-                        result.credentialLifecycle === 'fully-filled',
-                    receiptWrite: receiptWrite.event,
-                });
-            }
-            catch (error) {
-                rejectAttempt(error);
-                throw error;
-            }
-            finally {
-                await closeSession(input.reviewId);
-                if (!completedAttempt ||
-                    completedAttempt.outcome === 'failed' ||
-                    completedAttempt.outcome === 'declined') {
-                    if (payAttempts.get(input.reviewId)?.promise === sharedResult) {
-                        payAttempts.delete(input.reviewId);
-                    }
-                }
-                else {
-                    const expiry = setTimeout(() => {
-                        if (payAttempts.get(input.reviewId)?.promise === sharedResult) {
-                            payAttempts.delete(input.reviewId);
-                        }
-                    }, ttlMs);
-                    expiry.unref?.();
-                }
-            }
-        },
-    };
-}