@visa/cli 4.1.0-rc.13 → 4.1.0-rc.130

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

@@ -1,8 +1,8 @@
 // createCliCheckoutEngine — the review()/pay() adapter consumed by @visa/cli's
-// pay_merchant tool. It COMPOSES the same primitives the `pnpm fill:live` runner
-// uses (prepareCheckout, runHostedApproval, the createIntent/fetchCryptogram
-// mint, submitApprovedCheckout, reportVicOutcome, receipts) into a two-call API,
-// WITHOUT touching run-live-fill.ts — so the proven CLI flow keeps working.
+// 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
@@ -15,17 +15,97 @@ import { join } from 'node:path';
 import { readFile } from 'node:fs/promises';
 import { launchCheckoutBrowser } from './browser-launch.js';
 import { prepareCheckout as realPrepareCheckout, submitApprovedCheckout as realSubmitApprovedCheckout, InMemoryPreparedCheckoutStore, } from './executor.js';
-import { runHostedApproval as realRunHostedApproval } from './hosted-approval.js';
-import { VgsAssuranceInstrument, decimalToMinor, } from './vgs-live-instrument.js';
-import { createIntent, fetchCryptogram, postConfirmation } from './vgs-gateway/fetch-credential.mjs';
+import { claimMandatePickup as realClaimMandatePickup, runHostedApproval as realRunHostedApproval, } from './hosted-approval.js';
+import { VgsAssuranceInstrument, VgsLiveInstrument, decimalToMinor, minorToDecimal, } from './vgs-live-instrument.js';
+import { serverCreateIntent, 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++) {
+        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(' '));
+}
+/**
+ * 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.
+ */
+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) {
+            return {
+                transient: status === 503 ||
+                    reasons.length === 0 ||
+                    reasons.every((reason) => transientReasons.has(reason)),
+                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) {
+    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;
+    }
+    if (typeof input.cardTokenId === 'string' && input.cardTokenId.trim()) {
+        return { tokenId: input.cardTokenId, source: 'card-grant' };
+    }
+    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);
+}
 const RECEIPT_DIR = join(homedir(), '.visa-mcp', 'checkout-receipts');
 // 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 defaultLedger = new MandateLedger();
 export function createCliCheckoutEngine(deps = {}) {
     const store = deps.store ?? defaultStore;
     const sessions = deps.sessions ?? defaultSessions;
@@ -34,8 +114,15 @@ export function createCliCheckoutEngine(deps = {}) {
     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 cardDrawVerdict = deps.cardDrawVerdict ?? null;
+    const cardMandateRegister = deps.cardMandateRegister ?? null;
     async function closeSession(reviewId) {
         const session = sessions.get(reviewId);
         if (!session)
@@ -53,7 +140,286 @@ 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,
+            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 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 the flow.
+        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 tap-free draws; your next checkout will interrupt the owner ` +
+                `for a fresh per-purchase approval. 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 } : {}),
+        };
+    }
     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 (the single-purchase fresh-tap
+            // path below stays non-budget).
+            const assurance = await runHostedApproval({
+                baseUrl: input.approvalBaseUrl,
+                tokenId: credential.tokenId,
+                target: ceilingTarget,
+                consumerEmail: input.contact.email,
+                budget: true,
+                agentJkt: registerCap.agentJkt,
+                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 facts = await createCardMandate({
+                agentJkt: registerCap.agentJkt,
+                tokenId: credential.tokenId,
+                assuranceData: assurance.assuranceData,
+                ceilingMinor,
+                merchant,
+                currencyCode: input.currency,
+                expiresAt,
+                maxDraws: DEFAULT_MANDATE_MAX_DRAWS,
+                crossMerchant: true,
+            }, {
+                createIntent: (i) => serverCreateIntent(input.approvalBaseUrl, mintToken, i),
+                ledger,
+                approvalBaseUrl: input.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,
+                mandateId: facts.mandateId,
+                mintToken,
+                ceiling: input.ceiling,
+                currency: input.currency,
+            });
+            return {
+                ...facts,
+                ...approvedCeilingFacts(facts, registered.approvedCeilingMinor),
+                merchantHost: new URL(merchant.url).hostname,
+                registerFailed: registered.registerFailed,
+                ...(registered.registerFailureReason !== undefined
+                    ? { registerFailureReason: registered.registerFailureReason }
+                    : {}),
+            };
+        },
+        // 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)
@@ -72,6 +438,7 @@ export function createCliCheckoutEngine(deps = {}) {
                     amountMinor,
                     currency: input.currency,
                     browser,
+                    contact: input.contact,
                 }, store);
                 if (prep.status !== 'ready') {
                     await browser.close();
@@ -88,6 +455,7 @@ export function createCliCheckoutEngine(deps = {}) {
                     amountMinor,
                     currency: input.currency,
                     contact: input.contact,
+                    ...(input.agentJkt ? { agentJkt: input.agentJkt } : {}),
                     cleanupTimer,
                 });
                 return {
@@ -104,6 +472,24 @@ 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);
+        },
         async pay(input) {
             const session = sessions.get(input.reviewId);
             if (!session) {
@@ -113,6 +499,67 @@ export function createCliCheckoutEngine(deps = {}) {
                     receiptPath: null,
                     detail: `no prepared review ${input.reviewId} — call review first (a review does not survive a restart)`,
                     vicConfirmation: null,
+                    source: null,
+                    remainingMinor: null,
+                };
+            }
+            // 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 = new URL(session.target.merchantUrl).toString();
+            }
+            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,
+                };
+            }
+            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,
+                };
+            }
+            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,
+                };
+            }
+            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,
                 };
             }
             // Amount-bind the confirmation: the pay-call amount must match the
@@ -128,6 +575,8 @@ export function createCliCheckoutEngine(deps = {}) {
                     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,
                 };
             }
             // Reject an expired prepared checkout BEFORE running the hosted passkey
@@ -141,51 +590,249 @@ export function createCliCheckoutEngine(deps = {}) {
                     receiptPath: null,
                     detail: `prepared review ${input.reviewId} expired — start a fresh review`,
                     vicConfirmation: null,
+                    source: null,
+                    remainingMinor: null,
                 };
             }
             clearTimeout(session.cleanupTimer);
             try {
-                const credential = JSON.parse(await readFile(input.credentialPath, 'utf8'));
-                const assurance = await runHostedApproval({
-                    baseUrl: input.approvalBaseUrl,
-                    tokenId: credential.tokenId,
-                    target: session.target,
-                    consumerEmail: session.contact.email,
+                // 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; only the fresh-tap branch
+                // below needs one, and it resolves lazily 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. 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(),
                 });
-                const instrument = new VgsAssuranceInstrument(credential, assurance, session.target, session.contact.fullName ?? '', async (mintInput) => {
-                    const { intentId, status } = await createIntent(mintInput);
-                    try {
-                        const payment = await fetchCryptogram({
-                            tokenId: mintInput.tokenId,
-                            intentId,
-                            transaction: mintInput.transaction,
-                        });
-                        return { payment, intentId };
+                let source;
+                let confirmBase;
+                // Fresh purchases confirm with their one-purchase mint token. 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 {
+                            outcome: 'failed',
+                            confirmationRef: null,
+                            receiptPath: null,
+                            detail: 'this mandate cannot draw because its delegated card authority is unavailable; ' +
+                                'restore the runtime binding or use a fresh per-purchase approval',
+                            vicConfirmation: null,
+                            source,
+                            remainingMinor: null,
+                        };
                     }
-                    catch (err) {
-                        throw new Error(`${err.message} (intent status at creation: ${status ?? 'unknown'})`);
+                    if (covering.agentJkt && capability.agentJkt !== covering.agentJkt) {
+                        return {
+                            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 use a fresh per-purchase approval',
+                            vicConfirmation: null,
+                            source,
+                            remainingMinor: null,
+                        };
                     }
-                });
+                    // 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,
+                                        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,
+                                        },
+                                    });
+                                    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 take a fresh per-purchase tap. 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) {
+                                    if (!verdictFailure.transient) {
+                                        await ledger.markUnhonored(mandateId, now()).catch(() => { });
+                                    }
+                                    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 — retry the checkout to use a fresh per-purchase approval`, { 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 {
+                    // --- 1:1 fresh-tap flow (unchanged) ---------------------------------
+                    source = 'fresh-tap';
+                    // Legacy credential file OR the activated card:vic grant's token.
+                    const credential = await resolveCardInstrument(input);
+                    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;
+                    confirmationAuthority = mintToken;
+                    instrument = new VgsAssuranceInstrument(credential, assurance, session.target, session.contact.fullName ?? '', async (mintInput) => {
+                        const { intentId, status } = await serverCreateIntent(confirmBase, mintToken, mintInput);
+                        try {
+                            const payment = await serverFetchCryptogram(confirmBase, mintToken, {
+                                tokenId: mintInput.tokenId,
+                                intentId,
+                                transaction: mintInput.transaction,
+                            });
+                            return { payment, intentId };
+                        }
+                        catch (err) {
+                            throw new Error(`${err.message} (intent status at creation: ${status ?? 'unknown'})`);
+                        }
+                    });
+                }
                 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: instrument.confirmationTarget(),
+                        target: confirmationTarget,
                         outcome: result.outcome,
                         transaction: {
                             transactionAmount: session.target.transactionAmount,
                             transactionCurrencyCode: session.currency,
                         },
-                        post: postConfirmation,
+                        post: (confInput) => {
+                            if (!confirmationAuthority) {
+                                throw new Error('confirmation authority missing for the consumed VIC intent');
+                            }
+                            return postServerConfirmation(confirmBase, confirmationAuthority, confInput);
+                        },
                     });
                 }
                 let receiptPath = null;
@@ -215,6 +862,9 @@ export function createCliCheckoutEngine(deps = {}) {
                     receiptPath,
                     detail: result.detail ?? null,
                     vicConfirmation,
+                    source,
+                    remainingMinor: drawnRemaining,
+                    processorIntentId,
                 };
             }
             finally {