@visa/cli 4.1.0-rc.28 → 4.1.0-rc.281

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

@@ -10,17 +10,17 @@
 //
 // Every browser/network primitive is injectable (CliEngineDeps) so the session/
 // timer/store lifecycle is unit-testable without launching Chromium.
-import { homedir } from 'node:os';
-import { join } from 'node:path';
 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 { runHostedApproval as realRunHostedApproval } from './hosted-approval.js';
-import { VgsAssuranceInstrument, VgsLiveInstrument, decimalToMinor, } from './vgs-live-instrument.js';
-import { serverCreateIntent, serverFetchCryptogram, serverPostConfirmation, } from './vgs-gateway/server-mint-client.js';
-import { createCardMandate, drawFromMandate, MandateDrawDeclinedError, } from './mandate/card-mandate.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 { 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.
@@ -33,6 +33,21 @@ 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;
@@ -46,26 +61,309 @@ export function isTransientDrawFailure(err) {
     // 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(' '));
 }
-const RECEIPT_DIR = join(homedir(), '.visa-mcp', 'checkout-receipts');
+/**
+ * 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 };
+    }
+    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) {
@@ -85,6 +383,154 @@ export function createCliCheckoutEngine(deps = {}) {
             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
@@ -95,6 +541,9 @@ export function createCliCheckoutEngine(deps = {}) {
             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) {
@@ -102,25 +551,27 @@ export function createCliCheckoutEngine(deps = {}) {
                         'must be a positive amount at or under the ceiling');
                 }
             }
-            // BUDGET mandate: not tied to a merchant. The approval screen shows the
-            // any-merchant label so the owner sees the broader scope they're granting;
-            // the URL is a stable sentinel (advisory on the intent, ignored on draw).
-            const anyMerchant = input.anyMerchant === true;
-            if (!anyMerchant && !input.url) {
-                throw new Error('a merchant url is required unless anyMerchant (budget mandate) is set');
+            // 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');
             }
-            const merchant = anyMerchant
-                ? {
-                    name: 'spend budget mandate',
-                    url: 'https://any-merchant.visa/budget',
-                    countryCode: input.merchantCountryCode ?? 'US',
-                }
-                : {
-                    name: input.merchantName ?? new URL(input.url).hostname,
-                    url: input.url,
-                    countryCode: input.merchantCountryCode ?? 'US',
-                };
-            const credential = JSON.parse(await readFile(input.credentialPath, 'utf8'));
+            // 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 = {
@@ -132,16 +583,16 @@ export function createCliCheckoutEngine(deps = {}) {
             };
             // 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 (the single-purchase fresh-tap
-            // path below stays non-budget).
+            // 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,
-                onApprovalUrl: deps.onApprovalUrl,
-                ...(input.maxDraws !== undefined ? { maxDraws: input.maxDraws } : {}),
+                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 } : {}),
             });
@@ -150,69 +601,153 @@ export function createCliCheckoutEngine(deps = {}) {
                 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.');
             }
-            const expiresAt = input.expiresAt ?? new Date(now().getTime() + 24 * 60 * 60 * 1000).toISOString();
-            const facts = await createCardMandate({
-                tokenId: credential.tokenId,
+            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,
-                currencyCode: input.currency,
                 expiresAt,
-                ...(input.maxDraws !== undefined ? { maxDraws: input.maxDraws } : {}),
-                ...(anyMerchant ? { crossMerchant: true } : {}),
+                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, mintToken, i),
+                createIntent: (i) => serverCreateIntent(input.approvalBaseUrl, claim.mintToken, i),
                 ledger,
                 approvalBaseUrl: input.approvalBaseUrl,
-                mintToken,
                 now,
             });
-            // #5942 CONVERGE: seed the auth-side cumulative store keyed by the VGS INTENT
-            // id (`facts.mandateId`) so a later delegated draw resolves the mandate. This
-            // is BEST-EFFORT: a failure is logged, never fatal — the bearer mint-token
-            // path still works, only the delegated draw needs the register row. Skipped
-            // entirely when no mode='card' delegated binding is present.
-            const registerCap = cardMandateRegister?.loadCapability() ?? null;
-            let registerFailed = false;
-            if (registerCap && cardMandateRegister) {
-                const reg = await cardMandateRegister
-                    .register({
-                    authBaseUrl: registerCap.authBaseUrl,
-                    agentKey: registerCap.agentKey,
-                    mandateId: facts.mandateId,
-                    mintToken,
-                    ceiling: input.ceiling,
-                    currency: input.currency,
-                })
-                    .catch((err) => ({
-                    ok: false,
-                    reason: err instanceof Error ? err.message : String(err),
-                }));
-                if (!reg.ok) {
-                    registerFailed = true;
-                    // 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 and
-                    // the owner's next checkout falls through to a fresh per-purchase tap,
-                    // rather than silently selecting a mandate that can't be drawn. Marking
-                    // is best-effort too — a failure here must not abort mandate-start.
-                    const marked = await ledger
-                        .markRegisterFailed(facts.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 tap-free draws; your next checkout will use a fresh ` +
-                            `per-purchase passkey tap. 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=${facts.mandateId}\n`);
-                }
-            }
-            return { ...facts, merchantHost: new URL(merchant.url).hostname, registerFailed };
+            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);
@@ -223,6 +758,7 @@ export function createCliCheckoutEngine(deps = {}) {
             try {
                 const prep = await prepareCheckout({
                     url: input.url,
+                    checkoutRoute: input.checkoutRoute,
                     mandate: {
                         maxAmountMinor: amountMinor,
                         currency: input.currency,
@@ -232,22 +768,62 @@ export function createCliCheckoutEngine(deps = {}) {
                     amountMinor,
                     currency: input.currency,
                     browser,
+                    contact: input.contact,
+                    ...(input.trustedMerchantIdentity
+                        ? { trustedMerchantIdentity: input.trustedMerchantIdentity }
+                        : {}),
                 }, store);
                 if (prep.status !== 'ready') {
-                    await browser.close();
-                    throw new Error(`review refused: ${prep.result.outcome} — ${prep.result.detail ?? ''}`);
+                    // 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,
-                    target: buildTarget(input),
+                    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 {
@@ -264,8 +840,43 @@ export function createCliCheckoutEngine(deps = {}) {
                 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',
@@ -275,6 +886,83 @@ export function createCliCheckoutEngine(deps = {}) {
                     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
@@ -292,6 +980,7 @@ export function createCliCheckoutEngine(deps = {}) {
                     vicConfirmation: null,
                     source: null,
                     remainingMinor: null,
+                    ...noCredentialFacts,
                 };
             }
             // Reject an expired prepared checkout BEFORE running the hosted passkey
@@ -307,112 +996,93 @@ export function createCliCheckoutEngine(deps = {}) {
                     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 {
-                const credential = JSON.parse(await readFile(input.credentialPath, 'utf8'));
+                // 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 fall back to today's
-                // 1:1 fresh-tap flow. `mintToken` requirement means a mandate with no
-                // persisted token can never silently short-circuit the tap.
+                // 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;
-                let confirmToken;
+                // 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 && covering.mintToken) {
+                if (covering) {
                     // --- Tap-free mandate draw ------------------------------------------
                     source = 'mandate';
                     confirmBase = covering.approvalBaseUrl;
-                    // The bearer mint token stays the auth for the VIC confirmation POST
-                    // (the confirmation route accepts only the mint token). The CRYPTOGRAM
-                    // mint, however, may use a delegated verdict token — see below.
-                    confirmToken = covering.mintToken;
                     const mandateId = covering.mandateId;
-                    // #5923 delegated card-draw: when the agent holds a local mode='card'
-                    // binding, mint the cryptogram with a PoP-signed VERDICT token (the
-                    // verify-web tryVerdictAuth path) INSTEAD of the bearer mint token. No
-                    // binding (or seam not injected) → `drawToken` stays the bearer token:
-                    // today's #5917 draw, byte-for-byte unchanged (converge-not-break).
+                    // 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.
-                    let drawToken = confirmToken;
-                    const capability = cardDrawVerdict?.loadCapability() ?? null;
-                    if (capability && cardDrawVerdict) {
-                        try {
-                            const { verdict } = await cardDrawVerdict.fetchVerdict({
-                                authBaseUrl: capability.authBaseUrl,
-                                agentKey: capability.agentKey,
-                                mandateId,
-                                // One draw per review; the reviewId is the server-side 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,
-                                },
-                            });
-                            drawToken = verdict;
-                        }
-                        catch (err) {
-                            // The verdict gate refused (or a transient error) BEFORE the cryptogram
-                            // mint. This point is OUTSIDE the submitApprovedCheckout catch that
-                            // gracefully handles later draw errors, so an un-caught throw here
-                            // escapes pay() raw — making an agent WITH a card binding strictly more
-                            // fragile than one without (breaks converge-not-break). Convert it into
-                            // a graceful FAILED result instead. We do NOT silently fall back to the
-                            // bearer mint token: on an over_ceiling/reserve_refused refusal that
-                            // would DODGE the server-side ceiling the verdict path exists to enforce.
-                            //
-                            // Definitive gate refusal (no_mandate, over_ceiling, reserve_refused,
-                            // checkout_access_revoked, token_mismatch, …): the mandate cannot be
-                            // drawn, so disable it — findCovering then skips it and the NEXT
-                            // pay_merchant falls through to a fresh per-purchase tap. Transient
-                            // (503 card_draw_disabled, challenge hiccup, network): leave the mandate
-                            // healthy and surface a retryable message. Duck-typed: the engine cannot
-                            // import CardDrawRefusedError (it lives in @visa/cli, above this seam).
-                            const reasons = Array.isArray(err.reasons)
-                                ? err.reasons
-                                : [];
-                            const status = typeof err.status === 'number'
-                                ? err.status
-                                : 0;
-                            const TRANSIENT = new Set([
-                                'challenge_failed',
-                                'challenge_malformed',
-                                'verdict_refused',
-                            ]);
-                            const transient = status === 503 || reasons.length === 0 || reasons.every((r) => TRANSIENT.has(r));
-                            if (!transient) {
-                                // Best-effort: a mark failure must not turn a clean refusal into a throw.
-                                await ledger.markUnhonored(mandateId, now()).catch(() => { });
-                            }
-                            return {
-                                outcome: 'failed',
-                                confirmationRef: null,
-                                receiptPath: null,
-                                detail: transient
-                                    ? `the card-mandate draw could not be authorized right now (${reasons.join(', ') || 'temporary error'}) — retry shortly`
-                                    : `this card mandate can no longer be drawn (${reasons.join(', ') || 'refused'}); it has been disabled — retry the checkout to use a fresh per-purchase passkey tap`,
-                                vicConfirmation: null,
-                                source,
-                                remainingMinor: null,
-                            };
-                        }
+                    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
@@ -435,7 +1105,36 @@ export function createCliCheckoutEngine(deps = {}) {
                                 amountMinor: session.amountMinor,
                                 transaction: { ...transaction, transactionCurrencyCode: session.currency },
                             }, {
-                                fetchCryptogram: (i) => fetchMandateCryptogram(confirmBase, drawToken, i),
+                                // 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,
                             });
@@ -445,7 +1144,8 @@ export function createCliCheckoutEngine(deps = {}) {
                             // (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 take a fresh per-purchase tap. We do
+                            // 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
@@ -463,9 +1163,28 @@ export function createCliCheckoutEngine(deps = {}) {
                             // 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 &&
-                                !isTransientDrawFailure(err.cause ?? err)) {
-                                await ledger.markUnhonored(mandateId, now());
+                            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.
@@ -479,48 +1198,31 @@ export function createCliCheckoutEngine(deps = {}) {
                     instrument = new VgsLiveInstrument(reference, session.contact.fullName ?? '', fetchCredential);
                 }
                 else {
-                    // --- 1:1 fresh-tap flow (unchanged) ---------------------------------
-                    source = 'fresh-tap';
-                    const assurance = await runHostedApproval({
-                        baseUrl: input.approvalBaseUrl,
-                        tokenId: credential.tokenId,
-                        target: session.target,
-                        consumerEmail: session.contact.email,
-                        onApprovalUrl: input.onApprovalUrl ?? deps.onApprovalUrl,
-                    });
-                    // Server-side mint (Phase 1): the approval claim releases a scoped mint
-                    // token; the credential is minted by the verify-web deployment (which
-                    // holds the VGS secret), never on this machine. No token means the
-                    // deployment ran the dev-auth stub — refuse loudly rather than reach for
-                    // a client-held secret (there is none anymore).
-                    const mintToken = assurance.mintToken;
-                    if (!mintToken) {
-                        return {
-                            outcome: 'failed',
-                            confirmationRef: null,
-                            receiptPath: null,
-                            detail: '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.',
-                            vicConfirmation: null,
-                            source: 'fresh-tap',
-                            remainingMinor: null,
-                        };
-                    }
-                    confirmBase = input.approvalBaseUrl;
-                    confirmToken = mintToken;
-                    instrument = new VgsAssuranceInstrument(credential, assurance, session.target, session.contact.fullName ?? '', async (mintInput) => {
-                        const { intentId, status } = await serverCreateIntent(confirmBase, confirmToken, mintInput);
-                        try {
-                            const payment = await serverFetchCryptogram(confirmBase, confirmToken, {
-                                tokenId: mintInput.tokenId,
-                                intentId,
-                                transaction: mintInput.transaction,
-                            });
-                            return { payment, intentId };
-                        }
-                        catch (err) {
-                            throw new Error(`${err.message} (intent status at creation: ${status ?? 'unknown'})`);
-                        }
+                    // #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';
@@ -529,24 +1231,33 @@ export function createCliCheckoutEngine(deps = {}) {
                     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: instrument.confirmationTarget(),
+                        target: confirmationTarget,
                         outcome: result.outcome,
                         transaction: {
                             transactionAmount: session.target.transactionAmount,
                             transactionCurrencyCode: session.currency,
                         },
-                        post: (confInput) => serverPostConfirmation(confirmBase, confirmToken, confInput),
+                        post: (confInput) => {
+                            if (!confirmationAuthority) {
+                                throw new Error('confirmation authority missing for the consumed VIC intent');
+                            }
+                            return postServerConfirmation(confirmBase, confirmationAuthority, confInput);
+                        },
                     });
                 }
                 let receiptPath = null;
-                const report = await writeReceipt(RECEIPT_DIR, buildReceipt({
+                const receiptWrite = await writeObservedReceipt(mode, buildReceipt({
                     mode,
                     reviewId: input.reviewId,
                     // Derive BOTH name and host from the reviewed session target (not
@@ -555,6 +1266,7 @@ export function createCliCheckoutEngine(deps = {}) {
                     merchant: {
                         name: session.target.merchantName,
                         host: new URL(session.target.merchantUrl).hostname,
+                        url: session.target.merchantUrl,
                     },
                     transaction: {
                         amount: session.target.transactionAmount,
@@ -563,10 +1275,12 @@ export function createCliCheckoutEngine(deps = {}) {
                     },
                     result,
                     vicConfirmation,
+                    agentName: input.agentName,
+                    cardLast4: input.cardLast4,
                 }));
-                if (report.written)
-                    receiptPath = report.path;
-                return {
+                if (receiptWrite.report.written)
+                    receiptPath = receiptWrite.report.path;
+                return finishAttempt({
                     outcome: result.outcome,
                     confirmationRef: result.confirmationRef ?? null,
                     receiptPath,
@@ -574,10 +1288,34 @@ export function createCliCheckoutEngine(deps = {}) {
                     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?.();
+                }
             }
         },
     };