@visa/cli 4.1.0-rc.153 → 4.1.0-rc.155

package/README.md

@@ -180,6 +180,7 @@ is required so the CLI never guesses which agent can spend.
 | `wallet_directory_pay` | Directory find + pay in one call, same policy path |
 | `wallet_history` | Journaled payment receipts |
 | `wallet_fund` | Funding instructions for the wallet address |
+| `checkout_merchants` | Read-only: merchants where your card has completed real checkouts, from this device's receipts |
 | `get_status` | Account and wallet state summary |
 | `feedback` | Submit feedback on a tool result |
 | `reset` | Clear local auth state and credentials |

package/dist/checkout-engine/adapters/generic.d.ts

@@ -10,6 +10,16 @@ export interface CheckoutAdapter {
 }
 export declare function resolveLocator(page: Page, entry: FieldEntry): Locator;
 export declare function scrubFillErrorMessage(message: string, value: string): string;
+/**
+ * The contact record and the page rarely agree on name shape: the record may
+ * carry fullName while the page wants first/last inputs, or vice versa. Derive
+ * the missing shape so either page can be filled from either record.
+ */
+export declare function contactNameShapes(contact: Contact, cardholderName?: string): {
+    fullName?: string;
+    first?: string;
+    last?: string;
+};
 export declare function fillContactFieldMap(page: Page, fields: FieldMap, contact: Contact, opts?: {
     fillTimeoutMs?: number;
 }): Promise<FilledField[]>;

package/dist/checkout-engine/adapters/generic.js

@@ -97,12 +97,24 @@ async function fillOne(page, role, entry, value, displayValue, fillTimeoutMs) {
         return { ...base, ok: false, error: scrubFillErrorMessage(err.message, value) };
     }
 }
+/**
+ * The contact record and the page rarely agree on name shape: the record may
+ * carry fullName while the page wants first/last inputs, or vice versa. Derive
+ * the missing shape so either page can be filled from either record.
+ */
+export function contactNameShapes(contact, cardholderName) {
+    const fullName = contact.fullName ??
+        (contact.firstName && contact.lastName
+            ? `${contact.firstName} ${contact.lastName}`
+            : cardholderName);
+    const first = contact.firstName ?? (fullName?.split(/\s+/)[0] || undefined);
+    const last = contact.lastName ?? (fullName?.split(/\s+/).slice(1).join(' ') || undefined);
+    return { fullName, first, last };
+}
 async function fillFields(page, fields, credential, contact, opts = {}) {
     const fillTimeoutMs = opts.fillTimeoutMs ?? DEFAULT_FILL_TIMEOUT_MS;
     const filled = [];
-    const fullName = contact.fullName ?? credential?.cardholderName;
-    const first = contact.firstName ?? fullName?.split(/\s+/)[0];
-    const last = contact.lastName ?? fullName?.split(/\s+/).slice(1).join(' ');
+    const { fullName, first, last } = contactNameShapes(contact, credential?.cardholderName);
     // Order matters a little: contact/name before card is harmless, but we fill
     // card fields explicitly per role so order is not load-bearing.
     const jobs = [];

package/dist/checkout-engine/adapters/shopify.d.ts

@@ -2,7 +2,7 @@ import type { Page } from 'playwright-core';
 import { type PageAmountRead } from '../amount.js';
 import { type DetectResult, type FieldMap } from '../detect.js';
 import type { CardCredential } from '../instrument.js';
-import type { Contact, FillResult } from '../types.js';
+import type { Contact, FillResult, FilledField } from '../types.js';
 import { type CheckoutAdapter } from './generic.js';
 type ShopifySummary = {
     subtotalMinor: number | null;
@@ -20,6 +20,30 @@ export declare function isShopifyCheckoutPage(page: Page): Promise<boolean>;
 export declare function detectShopifyChallenge(page: Page): Promise<{
     signal: string;
 } | null>;
+/**
+ * The en-US variant of a localized Shopify checkout URL, or null when it is
+ * already English (or not locale-suffixed). Shopify renders the checkout in
+ * the URL's trailing locale segment, and amount reconciliation reads the
+ * order summary by its ENGLISH labels — a store whose primary market is not
+ * English serves /checkouts/cn/<token>/<locale> and the total never parses
+ * (observed live 2026-08-16: /es-us rendered "Precio total" and the review
+ * refused fail-closed on a good checkout). The locale segment is
+ * presentation-only: swapping it keeps the same checkout session and token.
+ */
+export declare function shopifyEnglishCheckoutUrl(current: string): string | null;
+export declare function missingContactRoles(filled: FilledField[], expected: string[]): string[];
+/**
+ * The contact surface to prefill. Shipping fields when the checkout has them —
+ * but a digital-goods (no-shipping) Shopify checkout renders exactly one
+ * address block and marks every field autocomplete="billing ..." (observed
+ * live 2026-08-16: all 18 candidates billing-classified, so the shipping map
+ * came back empty and the prefill reported every role missing). That billing
+ * block IS the primary contact surface, under its base roles.
+ */
+export declare function contactPrefillFieldMap(detected: DetectResult): {
+    fields: FieldMap;
+    surface: 'shipping' | 'billing-only';
+};
 export declare class ShopifyAdapter implements CheckoutAdapter {
     private readonly detected;
     name: string;

package/dist/checkout-engine/adapters/shopify.js

@@ -43,11 +43,23 @@ export function parseShopifySummary(text) {
     const discountMinor = parse(uniqueValue('discount', 'discounts')) ?? 0;
     const totalText = uniqueValue('total');
     const totalMinor = parse(totalText);
-    const verified = subtotalMinor != null &&
-        shippingMinor != null &&
-        taxMinor != null &&
-        totalMinor != null &&
-        subtotalMinor + shippingMinor + taxMinor - discountMinor === totalMinor;
+    // A digital-goods checkout renders no component rows at all — just a total
+    // ("Cost summary / Total / USD $6.00", observed live 2026-08-16), so there
+    // is nothing to reconcile against and a parsed total stands on its own. The
+    // moment ANY component label parsed by SUMMARY_LABELS appears — including a
+    // pending "Calculated at next step" — the full reconciliation is required again,
+    // so a mid-render pre-tax total still refuses.
+    // The discount-code entry form puts a bare "Discount" label on every
+    // checkout, value or not, and discount already defaults to 0 — only the
+    // additive components force reconciliation.
+    const componentLabelPresent = [...values.keys()].some((key) => key !== 'total' && key !== 'discount' && key !== 'discounts');
+    const verified = componentLabelPresent
+        ? subtotalMinor != null &&
+            shippingMinor != null &&
+            taxMinor != null &&
+            totalMinor != null &&
+            subtotalMinor + shippingMinor + taxMinor - discountMinor === totalMinor
+        : totalMinor != null;
     return {
         subtotalMinor,
         shippingMinor,
@@ -145,6 +157,30 @@ export async function detectShopifyChallenge(page) {
     }
     return null;
 }
+/**
+ * The en-US variant of a localized Shopify checkout URL, or null when it is
+ * already English (or not locale-suffixed). Shopify renders the checkout in
+ * the URL's trailing locale segment, and amount reconciliation reads the
+ * order summary by its ENGLISH labels — a store whose primary market is not
+ * English serves /checkouts/cn/<token>/<locale> and the total never parses
+ * (observed live 2026-08-16: /es-us rendered "Precio total" and the review
+ * refused fail-closed on a good checkout). The locale segment is
+ * presentation-only: swapping it keeps the same checkout session and token.
+ */
+export function shopifyEnglishCheckoutUrl(current) {
+    let url;
+    try {
+        url = new URL(current);
+    }
+    catch {
+        return null;
+    }
+    const match = url.pathname.match(/^(\/checkouts\/[^?#]+\/)([a-z]{2,3}(?:-[a-z0-9]+)*)(\/?)$/i);
+    if (!match || match[2].toLowerCase().startsWith('en'))
+        return null;
+    url.pathname = `${match[1]}en-us${match[3]}`;
+    return url.toString();
+}
 const BILLING_ROLES = new Set([
     'name',
     'nameFirst',
@@ -370,10 +406,62 @@ function requiredAddressRoles(address, prefix = '') {
         ...(address.country ? [role('country')] : []),
     ];
 }
-function missingRoles(filled, expected) {
-    const successful = new Set(filled.filter((field) => field.ok).map((field) => field.role));
+/**
+ * A checkout renders ONE name shape (a single full-name input, or first/last)
+ * while the contact record may carry the other, so the expected role and the
+ * filled role can disagree while the page is completely filled. Either shape
+ * satisfies the name requirement; same for the billing-prefixed variants.
+ */
+function withNameEquivalence(successful) {
+    const out = new Set(successful);
+    for (const [full, first, last] of [
+        ['name', 'nameFirst', 'nameLast'],
+        ['billingName', 'billingNameFirst', 'billingNameLast'],
+    ]) {
+        if (out.has(first) && out.has(last))
+            out.add(full);
+        if (out.has(full)) {
+            out.add(first);
+            out.add(last);
+        }
+    }
+    return out;
+}
+export function missingContactRoles(filled, expected) {
+    const successful = withNameEquivalence(new Set(filled.filter((field) => field.ok).map((field) => field.role)));
     return expected.filter((role) => !successful.has(role));
 }
+function hasAddressRole(fields) {
+    return Boolean(fields.addressLine1 ?? fields.city ?? fields.postalCode);
+}
+/**
+ * The contact surface to prefill. Shipping fields when the checkout has them —
+ * but a digital-goods (no-shipping) Shopify checkout renders exactly one
+ * address block and marks every field autocomplete="billing ..." (observed
+ * live 2026-08-16: all 18 candidates billing-classified, so the shipping map
+ * came back empty and the prefill reported every role missing). That billing
+ * block IS the primary contact surface, under its base roles.
+ */
+export function contactPrefillFieldMap(detected) {
+    const shipping = shippingFieldMap(detected);
+    if (hasAddressRole(shipping))
+        return { fields: shipping, surface: 'shipping' };
+    const fields = {};
+    for (const candidate of detected.candidates) {
+        const role = candidate.role;
+        if (!role || !CONTACT_ROLES.has(role) || !candidate.meta.visible)
+            continue;
+        if (isPaymentCandidate(candidate))
+            continue;
+        const entry = entryFromCandidate(candidate);
+        if (!entry)
+            continue;
+        const existing = fields[role];
+        if (!existing || entry.confidence > existing.confidence)
+            fields[role] = entry;
+    }
+    return { fields, surface: 'billing-only' };
+}
 export class ShopifyAdapter {
     detected;
     name = 'shopify';
@@ -384,15 +472,18 @@ export class ShopifyAdapter {
         return detected.candidates.some(isShopifyCandidate);
     }
     async prepareContact(page, contact) {
-        const shippingFilled = await fillContactFieldMap(page, shippingFieldMap(this.detected), contact);
+        const { fields: contactFields, surface } = contactPrefillFieldMap(this.detected);
+        const shippingFilled = await fillContactFieldMap(page, contactFields, contact);
         const shippingExpected = [...requiredAddressRoles(contact), ...(contact.phone ? ['phone'] : [])];
-        const shippingMissing = missingRoles(shippingFilled, shippingExpected);
-        if (!contact.billingAddress) {
+        const shippingMissing = missingContactRoles(shippingFilled, shippingExpected);
+        if (surface === 'billing-only' || !contact.billingAddress) {
             return {
                 ok: shippingMissing.length === 0,
                 filled: shippingFilled,
                 ...(shippingMissing.length
-                    ? { detail: `Shopify shipping prefill incomplete: missing ${shippingMissing.join(', ')}` }
+                    ? {
+                        detail: `Shopify ${surface === 'billing-only' ? 'contact' : 'shipping'} prefill incomplete: missing ${shippingMissing.join(', ')}`,
+                    }
                     : {}),
             };
         }
@@ -406,7 +497,7 @@ export class ShopifyAdapter {
         const billingFields = billingFieldMap(await detectFields(page));
         const billingFilled = labelBillingEvidence(await fillContactFieldMap(page, billingFields, billingContact(contact.billingAddress)));
         const billingExpected = requiredAddressRoles(contact.billingAddress, 'billing');
-        const missing = [...shippingMissing, ...missingRoles(billingFilled, billingExpected)];
+        const missing = [...shippingMissing, ...missingContactRoles(billingFilled, billingExpected)];
         return {
             ok: missing.length === 0,
             filled: [...shippingFilled, ...billingFilled],

package/dist/checkout-engine/cli-engine.d.ts

@@ -34,6 +34,10 @@ export type CliReviewInput = {
     cardTokenId?: string;
     /** Exact request-key identity selected by the caller. */
     agentJkt?: string;
+    /** Owner-facing selected-agent label for the compact local receipt. */
+    agentName?: string;
+    /** Safe display suffix derived from the selected card grant label. */
+    cardLast4?: string;
     contact: Contact;
     approvalBaseUrl: string;
     merchantName?: string;

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

@@ -10,10 +10,9 @@
 //
 // 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 { launchCheckoutBrowser } from './browser-launch.js';
+import { RECEIPT_DIR } from './receipt-dir.js';
 import { prepareCheckout as realPrepareCheckout, submitApprovedCheckout as realSubmitApprovedCheckout, InMemoryPreparedCheckoutStore, } from './executor.js';
 import { claimMandatePickup as realClaimMandatePickup, runHostedApproval as realRunHostedApproval, } from './hosted-approval.js';
 import { VgsLiveInstrument, decimalToMinor, minorToDecimal, } from './vgs-live-instrument.js';
@@ -100,6 +99,9 @@ export function classifyCardDrawVerdictFailure(err) {
  * 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 {
@@ -111,9 +113,6 @@ async function resolveCardInstrument(input) {
     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 ' +
@@ -147,7 +146,6 @@ function failedPay(detail) {
         credentialDisclosed: false,
     };
 }
-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;
@@ -919,6 +917,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,
@@ -927,6 +926,8 @@ export function createCliCheckoutEngine(deps = {}) {
                     },
                     result,
                     vicConfirmation,
+                    agentName: input.agentName,
+                    cardLast4: input.cardLast4,
                 }));
                 if (report.written)
                     receiptPath = report.path;

package/dist/checkout-engine/confirmed-merchants.d.ts

@@ -0,0 +1,31 @@
+/** One confirmed charge, in the receipt's own terms. */
+export type ConfirmedCharge = {
+    recordedAt: string;
+    amount: string;
+    currency: string;
+    /** Receipt file basename, so an operator can open the evidence log. */
+    receiptFile: string;
+};
+export type ConfirmedMerchant = {
+    /** The checkout page the card went through. */
+    url: string;
+    host: string;
+    /**
+     * Curated human identity (known-merchants.ts), present only when someone has
+     * identified who is behind this checkout URL. Hosted payment links carry an
+     * opaque path on the PSP's host, so without this a row names nobody.
+     */
+    name?: string;
+    category?: string;
+    website?: string;
+    confirmedCount: number;
+    lastConfirmedAt: string;
+    charges: ConfirmedCharge[];
+};
+/**
+ * Merchants this device has completed a real card checkout at, newest first.
+ *
+ * Never throws: a missing directory (nothing has ever been checked out here)
+ * and an unreadable one both read as an empty registry.
+ */
+export declare function readConfirmedMerchants(receiptDir?: string): Promise<ConfirmedMerchant[]>;

package/dist/checkout-engine/confirmed-merchants.js

@@ -0,0 +1,165 @@
+// "Where can I use my card?", the merchant registry derived from this
+// device's checkout receipts.
+//
+// Receipts (receipt.ts) are the only local record that a real merchant
+// checkout completed on this box. This module reads them back and answers one
+// question: which checkout pages has this card actually gone through?
+//
+// A merchant only counts when BOTH halves agree. The engine's own outcome must
+// be 'confirmed' (the merchant showed a definitive success) AND the VIC
+// confirmation must have posted APPROVED (the network side of the same
+// purchase). Either half alone is a claim, not a completion: a 'confirmed' with
+// no posted confirmation is exactly the reconciliation case receipt.ts flags,
+// and a posted DECLINED is a completed report of a failure.
+//
+// Reading is best-effort by construction. The receipts directory is an operator
+// artifact that anything on the box can touch, so an unreadable or malformed
+// file is skipped rather than failing the whole read. One bad file must not
+// hide every merchant behind it.
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { KNOWN_MERCHANT_IDENTITIES } from './known-merchants.js';
+import { RECEIPT_DIR } from './receipt-dir.js';
+/**
+ * The URL a receipt's charge happened at.
+ *
+ * A compact v2 receipt carries an exact checkout URL only when it is already in
+ * the curated identity map; otherwise it carries the host. Legacy v1 receipts
+ * keep the URL in the evidence log (the executor's first 'navigation' step is
+ * the page the run opened), so recover it there and fall back to the host when
+ * that evidence is absent or shaped differently.
+ */
+function checkoutUrlOf(receipt) {
+    if (receipt.schema === 'checkout-agent-receipt/v2') {
+        const checkoutUrl = receipt.merchant.checkoutUrl;
+        return checkoutUrl && KNOWN_MERCHANT_IDENTITIES[checkoutUrl]
+            ? checkoutUrl
+            : `https://${receipt.merchant.host}/`;
+    }
+    const navigation = receipt.evidence.steps.find((step) => step?.type === 'navigation');
+    const data = navigation?.data;
+    const url = typeof data === 'object' && data !== null ? data.url : undefined;
+    return typeof url === 'string' && url.length > 0 ? url : `https://${receipt.merchant.host}/`;
+}
+function isConfirmedCompletion(receipt) {
+    if (receipt.schema === 'checkout-agent-receipt/v2') {
+        return receipt.outcome === 'confirmed' && receipt.network.confirmation === 'APPROVED';
+    }
+    return (receipt.outcome === 'confirmed' &&
+        receipt.vicConfirmation?.posted === true &&
+        receipt.vicConfirmation.transactionStatus === 'APPROVED');
+}
+/**
+ * Parse one supported receipt file, or null when its fields cannot safely feed
+ * the registry. Deliberately permissive about everything the grouping does not
+ * touch: older and newer engines only have to carry the fields read below.
+ */
+function parseReceipt(json) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return null;
+    const receipt = parsed;
+    if (receipt.schema === 'checkout-agent-receipt/v1') {
+        const v1 = receipt;
+        if (typeof v1.recordedAt !== 'string')
+            return null;
+        if (typeof v1.merchant?.host !== 'string')
+            return null;
+        if (typeof v1.transaction?.amount !== 'string')
+            return null;
+        if (typeof v1.transaction?.currency !== 'string')
+            return null;
+        if (!Array.isArray(v1.evidence?.steps))
+            return null;
+        return v1;
+    }
+    if (receipt.schema === 'checkout-agent-receipt/v2') {
+        const v2 = receipt;
+        if (typeof v2.recordedAt !== 'string')
+            return null;
+        if (typeof v2.merchant?.host !== 'string')
+            return null;
+        if (v2.merchant.checkoutUrl !== null && typeof v2.merchant.checkoutUrl !== 'string')
+            return null;
+        if (typeof v2.transaction?.amount !== 'string')
+            return null;
+        if (typeof v2.transaction?.currency !== 'string')
+            return null;
+        if (v2.network?.confirmation !== null &&
+            v2.network?.confirmation !== 'APPROVED' &&
+            v2.network?.confirmation !== 'DECLINED') {
+            return null;
+        }
+        return v2;
+    }
+    return null;
+}
+/**
+ * Merchants this device has completed a real card checkout at, newest first.
+ *
+ * Never throws: a missing directory (nothing has ever been checked out here)
+ * and an unreadable one both read as an empty registry.
+ */
+export async function readConfirmedMerchants(receiptDir = RECEIPT_DIR) {
+    let names;
+    try {
+        names = await readdir(receiptDir);
+    }
+    catch {
+        return [];
+    }
+    const byUrl = new Map();
+    for (const name of names) {
+        if (!name.endsWith('.json'))
+            continue;
+        let raw;
+        try {
+            raw = await readFile(join(receiptDir, name), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const receipt = parseReceipt(raw);
+        if (!receipt || !isConfirmedCompletion(receipt))
+            continue;
+        const url = checkoutUrlOf(receipt);
+        const charge = {
+            recordedAt: receipt.recordedAt,
+            amount: receipt.transaction.amount,
+            currency: receipt.transaction.currency,
+            receiptFile: name,
+        };
+        const existing = byUrl.get(url);
+        if (existing) {
+            existing.confirmedCount += 1;
+            existing.charges.push(charge);
+            if (charge.recordedAt > existing.lastConfirmedAt) {
+                existing.lastConfirmedAt = charge.recordedAt;
+            }
+            continue;
+        }
+        const identity = KNOWN_MERCHANT_IDENTITIES[url];
+        byUrl.set(url, {
+            url,
+            host: receipt.merchant.host,
+            // Conditional spread on purpose: an unidentified merchant carries no
+            // identity keys at all, rather than keys holding undefined.
+            ...(identity ?? {}),
+            confirmedCount: 1,
+            lastConfirmedAt: charge.recordedAt,
+            charges: [charge],
+        });
+    }
+    const merchants = [...byUrl.values()];
+    for (const merchant of merchants) {
+        merchant.charges.sort((left, right) => (left.recordedAt < right.recordedAt ? 1 : -1));
+    }
+    merchants.sort((left, right) => (left.lastConfirmedAt < right.lastConfirmedAt ? 1 : -1));
+    return merchants;
+}

package/dist/checkout-engine/executor.js

@@ -24,7 +24,7 @@ import { observeOutcome } from './outcome.js';
 import { selectAdapter } from './adapters/index.js';
 import { traceHandleFields } from './trace-handles.js';
 import { readGenericPageAmount } from './amount.js';
-import { detectShopifyChallenge, isShopifyCheckoutPage, readShopifyAmount, readStableShopifyAmount, } from './adapters/shopify.js';
+import { detectShopifyChallenge, isShopifyCheckoutPage, readShopifyAmount, readStableShopifyAmount, shopifyEnglishCheckoutUrl, } from './adapters/shopify.js';
 export { minorFromDecimal, pageCurrency } from './amount.js';
 const SUBMIT_TEXT = /pay|place order|complete|buy|submit|checkout/i;
 const REVEAL_TEXT = /continue|next|proceed|review|go to payment/i;
@@ -674,7 +674,12 @@ export async function prepareCheckout(opts, store = defaultPreparedCheckoutStore
         mandate: { ...opts.mandate },
     };
     const evidence = new EvidenceLog();
-    const context = await options.browser.newContext();
+    // Pin an English locale: amount reconciliation reads the order summary by
+    // its visible labels (Subtotal/Taxes/Total), and merchants localize by
+    // Accept-Language (observed live 2026-08-16: a Shopify checkout redirected
+    // to /es-us and rendered "Impuestos estimados", so the total never parsed
+    // and the review refused fail-closed on a perfectly good checkout).
+    const context = await options.browser.newContext({ locale: 'en-US' });
     // Bound every action so a mis-detected or hidden element fails fast instead
     // of stalling on Playwright's long default timeout.
     context.setDefaultTimeout(6000);
@@ -732,6 +737,19 @@ export async function prepareCheckout(opts, store = defaultPreparedCheckoutStore
         // Instrument.getCredential() call can occur before an explicit approval.
         let detected = await detectFields(page);
         const shopifyPage = await isShopifyCheckoutPage(page);
+        if (shopifyPage) {
+            // Same checkout session, English presentation — the amount reader needs
+            // the English summary labels (see shopifyEnglishCheckoutUrl).
+            const englishUrl = shopifyEnglishCheckoutUrl(page.url());
+            if (englishUrl) {
+                await page.goto(englishUrl, { waitUntil: 'domcontentloaded' }).catch(() => { });
+                await waitForStableDom(page);
+                if (await isShopifyCheckoutPage(page)) {
+                    evidence.step('navigation', { url: page.url(), reason: 'shopify-locale-normalized' });
+                    detected = await detectFields(page);
+                }
+            }
+        }
         let adapter = selectAdapter(detected, { shopify: shopifyPage });
         if (options.contact && adapter.prepareContact) {
             const preparedContact = await adapter.prepareContact(page, options.contact);
@@ -799,6 +817,26 @@ export async function prepareCheckout(opts, store = defaultPreparedCheckoutStore
                 evidence.step('psp-detected', { psp: p.psp, requiresAdapter: p.requiresAdapter });
             }
         }
+        // A checkout the runner cannot put a card INTO is not reviewable. Without a
+        // detected card-number field a later pay would fill nothing and dispatch
+        // whatever control the review happened to bind (observed live 2026-08-16:
+        // a Payhip storefront SEARCH form, a FastSpring "PayPal Checkout" label,
+        // and a Shopify discount-form "Submit" all reviewed clean this way — the
+        // real card fields sat in unreachable PSP iframes or an unrendered payment
+        // section). Every adapter fills from this same detection, so a missing
+        // number field here means no pay can ever succeed: refuse while it is
+        // still free.
+        if (!fields.number) {
+            const found = Object.keys(fields);
+            const reason = `no card number field detected (roles found: ${found.length ? found.join(', ') : 'none'}) — ` +
+                'the card form is likely inside a PSP iframe or behind a later step, so a credential cannot be entered on this page';
+            evidence.step('detect', { phase: 'review', missingCardNumber: true, reason });
+            evidence.setSnapshotSummary(await snapshotSummary(page));
+            return {
+                status: 'finished',
+                result: makeResult('failed', fields, evidence, requiresAdapter, reason),
+            };
+        }
         const facts = await readTransactionFacts(page, options, 'review');
         recordTransactionFacts(evidence, 'review', facts);
         if (!facts.ok) {

package/dist/checkout-engine/index.d.ts

@@ -1,6 +1,9 @@
 export { createCliCheckoutEngine, type CliReviewInput, type CliReviewFacts, type CliPayInput, type CliReceiptFacts, type CliStartMandateInput, type CliMandateFacts, type CliEngineDeps, } from './cli-engine.js';
 export { prepareCheckout, submitApprovedCheckout, runCheckout, InMemoryPreparedCheckoutStore, } from './executor.js';
 export type { CheckoutResult, CheckoutReview, CheckoutOutcome } from './executor.js';
+export { readConfirmedMerchants, type ConfirmedMerchant, type ConfirmedCharge, } from './confirmed-merchants.js';
+export { KNOWN_MERCHANT_IDENTITIES, type MerchantIdentity } from './known-merchants.js';
+export { RECEIPT_DIR } from './receipt-dir.js';
 export { HostedApprovalDeclinedError, sanitizeApprovalIntent, APPROVAL_INTENT_MAX_CHARS, } from './hosted-approval.js';
 export { createCardMandate, drawFromMandate, MandateDrawDeclinedError, DEFAULT_MANDATE_MAX_DRAWS, type CreateCardMandateInput, type CreateCardMandateDeps, type CardMandateFacts, type DrawFromMandateInput, type DrawFromMandateDeps, type DrawResult, type CardMandateMerchant, } from './mandate/card-mandate.js';
 export { MandateLedger, remainingMinor, defaultLedgerPath, CARD_MANDATE_LEDGER_VERSION, type CardMandateRecord, type CardMandateLedgerFile, type CardMandateDraw, type CardMandateReservation, } from './mandate/mandate-ledger.js';

package/dist/checkout-engine/index.js

@@ -3,6 +3,9 @@
 // primitives are re-exported for direct/embedded use.
 export { createCliCheckoutEngine, } from './cli-engine.js';
 export { prepareCheckout, submitApprovedCheckout, runCheckout, InMemoryPreparedCheckoutStore, } from './executor.js';
+export { readConfirmedMerchants, } from './confirmed-merchants.js';
+export { KNOWN_MERCHANT_IDENTITIES } from './known-merchants.js';
+export { RECEIPT_DIR } from './receipt-dir.js';
 export { HostedApprovalDeclinedError, sanitizeApprovalIntent, APPROVAL_INTENT_MAX_CHARS, } from './hosted-approval.js';
 export { createCardMandate, drawFromMandate, MandateDrawDeclinedError, DEFAULT_MANDATE_MAX_DRAWS, } from './mandate/card-mandate.js';
 export { MandateLedger, remainingMinor, defaultLedgerPath, CARD_MANDATE_LEDGER_VERSION, } from './mandate/mandate-ledger.js';

package/dist/checkout-engine/known-merchants.d.ts

@@ -0,0 +1,10 @@
+export type MerchantIdentity = {
+    /** Human-recognizable merchant name. */
+    name: string;
+    /** What the merchant is, e.g. "charity (animal rescue)". */
+    category: string;
+    /** The merchant's own site, when known — not the checkout URL. */
+    website?: string;
+};
+/** Checkout URL → who is actually behind it. Confirmed live 2026-07/2026-08. */
+export declare const KNOWN_MERCHANT_IDENTITIES: Readonly<Record<string, MerchantIdentity>>;