@visa/cli 4.1.0-rc.17 → 4.1.0-rc.171

package/dist/checkout-engine/executor.js

@@ -2,7 +2,8 @@
 //   prepareCheckout(): navigate -> stabilize -> mandate gate -> resolve the
 //   review facts. No credential is requested or filled in this phase.
 //   submitApprovedCheckout(): verify the approval is bound to that review ->
-//   revalidate -> mint credential -> fill -> revalidate -> submit.
+//   revalidate -> in dry-run stop without requesting a credential; in submit
+//   mode mint -> fill -> revalidate -> submit.
 //
 // runCheckout() remains the one-shot, auto-approved compatibility wrapper.
 //
@@ -11,16 +12,22 @@
 //     runs before instrument.getCredential(). No credential is minted and no
 //     field is filled on a page the mandate does not cover.
 //   - The PRE-SUBMIT gate re-runs the full check with the resolved amount and
-//     currency. No submit ever happens without it passing. Dry-run never
-//     clicks submit.
+//     currency. No submit ever happens without it passing. Dry-run requests no
+//     credential and neither fills fields nor clicks submit.
 import { randomUUID } from 'node:crypto';
 import { mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { detectFields } from './detect.js';
 import { checkMandate, checkMandatePreFill } from './mandate.js';
-import { EvidenceLog } from './evidence.js';
+import { EvidenceLog, maskOtp } from './evidence.js';
 import { observeOutcome } from './outcome.js';
 import { selectAdapter } from './adapters/index.js';
+import { summarizeFillFailure } from './adapters/generic.js';
+import { traceHandleFields } from './trace-handles.js';
+import { readGenericPageAmount } from './amount.js';
+import { webBotAuthHeadersOrNone } from './web-bot-auth.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;
 // Post-submit confirmed/declined/challenge signals live in outcome.ts
@@ -35,92 +42,6 @@ async function settle(page) {
     await page.waitForTimeout(200);
     await page.waitForLoadState('networkidle', { timeout: 1500 }).catch(() => { });
 }
-// Convert a human decimal like "$50.00" to integer minor units without
-// floats. Fail-closed on separator ambiguity: only layouts with exactly one
-// reading are parsed; anything else returns null and the caller refuses. The
-// dangerous direction is UNDER-reading (an EU "1.234,56" read as 1.23 lets an
-// over-cap total pass the gate), so no layout is ever guessed.
-// Only 2-decimal currencies are supported (see pageCurrency's ISO allowlist).
-export function minorFromDecimal(text) {
-    const m = text.match(/\d[\d.,]*/);
-    if (!m)
-        return null;
-    const token = m[0].replace(/[.,]+$/, '');
-    // "1234" — plain integer major units.
-    if (/^\d+$/.test(token))
-        return Number.parseInt(token, 10) * 100;
-    // "1,234.56" — thousands groups of exactly 3 plus a 2-digit decimal.
-    if (/^\d{1,3}(,\d{3})+\.\d{2}$/.test(token)) {
-        const [whole, frac] = token.replace(/,/g, '').split('.');
-        return Number.parseInt(whole, 10) * 100 + Number.parseInt(frac, 10);
-    }
-    // "1.234,56" — the EU mirror: dot thousands, comma decimal.
-    if (/^\d{1,3}(\.\d{3})+,\d{2}$/.test(token)) {
-        const [whole, frac] = token.replace(/\./g, '').split(',');
-        return Number.parseInt(whole, 10) * 100 + Number.parseInt(frac, 10);
-    }
-    // "49.99" / "49.9" — dot decimal. A 3-digit dot group ("1.234") is EU
-    // thousands, not a decimal, so only 1-2 fraction digits qualify.
-    if (/^\d+\.\d{1,2}$/.test(token)) {
-        const [whole, frac] = token.split('.');
-        return Number.parseInt(whole, 10) * 100 + Number.parseInt(frac.padEnd(2, '0'), 10);
-    }
-    // "49,99" / "49,9" — comma decimal. Unambiguous: a thousands group is
-    // always exactly 3 digits, so a 1-2 digit comma tail can only be a decimal.
-    if (/^\d+,\d{1,2}$/.test(token)) {
-        const [whole, frac] = token.split(',');
-        return Number.parseInt(whole, 10) * 100 + Number.parseInt(frac.padEnd(2, '0'), 10);
-    }
-    // Everything else ("1,234" thousands-or-3-decimals, "1.2.3", ...) is
-    // ambiguous: refuse rather than guess.
-    return null;
-}
-// Currency stated by the page's total text, when unambiguous. "$" is shared
-// by USD/CAD/AUD/... and never qualifies. The ISO allowlist is 2-decimal
-// currencies only, matching minorFromDecimal's scaling.
-const ISO_CURRENCIES = ['USD', 'EUR', 'GBP', 'CAD', 'AUD', 'CHF', 'NZD'];
-export function pageCurrency(text) {
-    const iso = text.match(/\b([A-Z]{3})\b/);
-    if (iso && ISO_CURRENCIES.includes(iso[1]))
-        return iso[1];
-    if (text.includes('€'))
-        return 'EUR';
-    if (text.includes('£'))
-        return 'GBP';
-    return null;
-}
-// Read the order total from the page. Prefers an explicit data-total-minor
-// attribute (machine-readable), else parses a labelled total from the page.
-// Either way the currency comes from the element's text, or stays null. A
-// total that is present but ambiguous is 'unreadable' — the executor refuses
-// rather than falling back to the caller amount, because the page is showing
-// the user a number we cannot verify against the mandate.
-async function readPageAmount(page) {
-    const explicitLoc = page.locator('[data-total-minor]').first();
-    if ((await explicitLoc.count().catch(() => 0)) > 0) {
-        const explicit = await explicitLoc.getAttribute('data-total-minor').catch(() => null);
-        if (explicit && /^\d+$/.test(explicit)) {
-            const text = (await explicitLoc.textContent().catch(() => null)) ?? '';
-            return {
-                kind: 'ok',
-                amountMinor: Number.parseInt(explicit, 10),
-                currency: pageCurrency(text),
-                source: 'page-attr',
-            };
-        }
-    }
-    const totalLoc = page.locator('#order-total, .order-total, [data-testid="order-total"]').first();
-    if ((await totalLoc.count().catch(() => 0)) > 0) {
-        const totalText = await totalLoc.textContent().catch(() => null);
-        if (totalText && /\d/.test(totalText)) {
-            const amountMinor = minorFromDecimal(totalText);
-            if (amountMinor == null)
-                return { kind: 'unreadable' };
-            return { kind: 'ok', amountMinor, currency: pageCurrency(totalText), source: 'page-text' };
-        }
-    }
-    return { kind: 'none' };
-}
 async function tryReveal(page, evidence, clicked) {
     // 1) A payment-method radio for card/credit/debit (accordion layouts).
     const radios = page.locator('input[type="radio"]');
@@ -226,6 +147,19 @@ async function findSubmit(page) {
     }
     return null;
 }
+// The diagnostic snapshot records the page ORIGIN only, never the full URL: a
+// payment-session path/query (e.g. a live Stripe `cs_live_...` checkout-session
+// id) must not be retained in the local receipt, which elsewhere promises
+// "hostname only" (#7101). Falls back to the raw value only if it does not parse
+// as a URL (never a real page.url()).
+export function snapshotOrigin(rawUrl) {
+    try {
+        return new URL(rawUrl).origin;
+    }
+    catch {
+        return '';
+    }
+}
 async function snapshotSummary(page) {
     const info = await page
         .evaluate(() => {
@@ -234,7 +168,7 @@ async function snapshotSummary(page) {
         return { title: document.title, heading: heading?.textContent?.trim() || '', body };
     })
         .catch(() => ({ title: '', heading: '', body: '' }));
-    return `url=${page.url()} title="${info.title}" heading="${info.heading}" body="${info.body}"`;
+    return `url=${snapshotOrigin(page.url())} title="${info.title}" heading="${info.heading}" body="${info.body}"`;
 }
 async function readConfirmationRef(page) {
     const ref = await page
@@ -408,7 +342,7 @@ function unknownPreparedCheckoutResult(reviewId) {
     evidence.step('approval', { approved: false, reviewId, reason: detail });
     return makeResult('failed', {}, evidence, [], detail);
 }
-function makeResult(outcome, fields, evidence, requiresAdapter, detail, confirmationRef) {
+function makeResult(outcome, fields, evidence, requiresAdapter, detail, confirmationRef, failureCode) {
     const steps = evidence.getSteps();
     const approved = steps.find((step) => step.type === 'approval' && step.data.approved === true);
     const minted = steps.find((step) => step.type === 'credential-minted');
@@ -426,6 +360,12 @@ function makeResult(outcome, fields, evidence, requiresAdapter, detail, confirma
             : filledRoles.has('number') || filledRoles.has('cvc')
                 ? 'partially-exposed'
                 : 'minted-not-exposed';
+    const terminalFailureCode = failureCode ??
+        (outcome === 'action-required'
+            ? 'human-action-required'
+            : outcome === 'blocked-by-mandate'
+                ? 'mandate-blocked'
+                : undefined);
     return {
         outcome,
         fields,
@@ -440,12 +380,24 @@ function makeResult(outcome, fields, evidence, requiresAdapter, detail, confirma
                 : {}),
             ...(completed ? { fillCompletedAt: completed.ts } : {}),
         },
+        ...(terminalFailureCode ? { failureCode: terminalFailureCode } : {}),
         ...(detail ? { detail } : {}),
         ...(confirmationRef ? { confirmationRef } : {}),
     };
 }
-async function readTransactionFacts(page, opts) {
-    const pageAmount = await readPageAmount(page);
+async function readTransactionFacts(page, opts, phase) {
+    const shopify = await isShopifyCheckoutPage(page);
+    const amountRead = shopify
+        ? phase === 'review'
+            ? await readStableShopifyAmount(page)
+            : await readShopifyAmount(page, true)
+        : await readGenericPageAmount(page);
+    const pageAmount = shopify && amountRead.kind === 'none'
+        ? {
+            kind: 'unreadable',
+            reason: 'Shopify final tax and total summary is not available',
+        }
+        : amountRead;
     const amountMinor = pageAmount.kind === 'ok'
         ? pageAmount.amountMinor
         : pageAmount.kind === 'none'
@@ -474,10 +426,10 @@ async function readTransactionFacts(page, opts) {
             currency,
             source,
             reason: pageAmount.kind === 'unreadable'
-                ? 'page total is displayed but cannot be parsed unambiguously'
+                ? (pageAmount.reason ?? 'page total is displayed but cannot be parsed unambiguously')
                 : 'transaction amount could not be determined',
             detail: pageAmount.kind === 'unreadable'
-                ? 'transaction amount could not be determined (page total present but ambiguous, e.g. separator layout); refusing fail-closed'
+                ? `transaction amount could not be determined (${pageAmount.reason ?? 'page total present but ambiguous'}); refusing fail-closed`
                 : 'transaction amount could not be determined (no readable page total, no amountMinor provided); refusing fail-closed',
         };
     }
@@ -630,11 +582,17 @@ async function captureDebugShot(page, dir, reviewId, label, evidence, fields) {
 export function isStripeLinkConsumerRequest(url) {
     return /(?:^|\/\/)([a-z0-9.-]*\.)?stripe\.com\/v1\/consumers\/sessions\/(?:lookup|start_verification)\b/i.test(url);
 }
-async function suppressStripeLink(page, evidence) {
-    let suppressed = 0;
+// Keyed by Page so the tracker installed at prepare time is reachable from the
+// approved-submit leg without threading through the session store types.
+const linkSuppressionByPage = new WeakMap();
+// Exported for the link-quiet unit tests (a fake Page captures the route
+// handler); production callers stay inside this module.
+export async function suppressStripeLink(page, evidence) {
+    const state = { suppressed: 0, waiters: [] };
+    linkSuppressionByPage.set(page, state);
     await page.route((u) => isStripeLinkConsumerRequest(typeof u === 'string' ? u : u.href), (route) => {
-        suppressed += 1;
-        if (suppressed === 1) {
+        state.suppressed += 1;
+        if (state.suppressed === 1) {
             // origin + pathname only — never the full URL. The lookup carries the
             // email in the POST body today, but keep an operator email out of the
             // evidence log even if Stripe moves a param to the query string (#5708).
@@ -649,9 +607,45 @@ async function suppressStripeLink(page, evidence) {
             }
             evidence.step('note', { linkSuppressed: safe });
         }
+        for (const wake of state.waiters.splice(0))
+            wake();
         return route.abort();
     });
 }
+/**
+ * Wait for the suppressed Stripe Link lookup to fire and settle BEFORE the
+ * submit click. Stripe debounces its consumer-session lookup ~300ms after the
+ * email input changes; our fill→click gap is single-digit ms, so the (aborted)
+ * lookup used to land INSIDE Stripe's in-flight submit chain and kill it
+ * silently — the click looked accepted but tokenization never ran and the page
+ * sat on the form until the outcome deadline (#5879: three identical live
+ * stalls at donate.stripe.com). Verified live A/B on that page: instant click →
+ * dead submit, no /v1/payment_methods; lookup settled first → tokenization and
+ * the confirm step both reached.
+ *
+ * If the lookup already fired, only the short settle applies (lets Stripe's
+ * abort handling unwind). If it never fires — non-Link page variants, no email
+ * field — the bound expires and the click proceeds as before.
+ */
+export async function waitForLinkLookupQuiet(page, opts = {}) {
+    const boundMs = opts.boundMs ?? 1500;
+    const settleMs = opts.settleMs ?? 250;
+    const delay = opts.delay ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const state = linkSuppressionByPage.get(page);
+    if (!state)
+        return { fired: false, waitedMs: 0 };
+    const started = Date.now();
+    if (state.suppressed === 0) {
+        await Promise.race([
+            new Promise((resolve) => state.waiters.push(resolve)),
+            delay(boundMs),
+        ]);
+    }
+    const fired = state.suppressed > 0;
+    if (fired)
+        await delay(settleMs);
+    return { fired, waitedMs: Date.now() - started };
+}
 // Payer-chosen amount inputs. Deliberately payment-link-specific (Stripe's
 // customUnitAmount): on an ordinary checkout the total is merchant-controlled
 // and typing into anything price-like must never happen.
@@ -689,7 +683,21 @@ 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).
+    // Present Web Bot Auth (RFC 9421) credentials when, and only when, an
+    // operator directory is configured to resolve them. Off by default: an
+    // unresolvable signature fails verification and is worse than none. The
+    // signature covers @authority, so it is bound to the checkout host — a
+    // cross-origin redirect simply arrives unverified, never wrongly verified.
+    const webBotAuthHeaders = webBotAuthHeadersOrNone(options.webBotAuth ?? null, options.url, Date.now() / 1000);
+    const context = await options.browser.newContext({
+        locale: 'en-US',
+        ...(webBotAuthHeaders ? { extraHTTPHeaders: webBotAuthHeaders } : {}),
+    });
     // Bound every action so a mis-detected or hidden element fails fast instead
     // of stalling on Playwright's long default timeout.
     context.setDefaultTimeout(6000);
@@ -745,7 +753,75 @@ export async function prepareCheckout(opts, store = defaultPreparedCheckoutStore
         }
         // Detection is read-only here. In particular, no adapter fill and no
         // Instrument.getCredential() call can occur before an explicit approval.
-        const detected = await detectFields(page);
+        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);
+            for (const field of preparedContact.filled) {
+                evidence.step('contact-prefill', {
+                    role: field.role,
+                    confidence: field.confidence,
+                    source: field.source,
+                    frame: field.frame,
+                    value: field.value,
+                    ok: field.ok,
+                    error: field.error,
+                });
+            }
+            const challenge = await detectShopifyChallenge(page);
+            if (challenge) {
+                evidence.step('outcome', {
+                    outcome: 'action-required',
+                    signal: challenge.signal,
+                    phase: 'contact-prefill',
+                });
+                evidence.setSnapshotSummary(await snapshotSummary(page));
+                return {
+                    status: 'finished',
+                    result: makeResult('action-required', fields, evidence, requiresAdapter, `Shop Pay verification requires a human before review (${challenge.signal}); no payment credential was requested`),
+                };
+            }
+            if (!preparedContact.ok) {
+                evidence.setSnapshotSummary(await snapshotSummary(page));
+                return {
+                    status: 'finished',
+                    result: makeResult('failed', fields, evidence, requiresAdapter, preparedContact.detail ??
+                        'Shopify contact prefill did not complete; no payment credential was requested'),
+                };
+            }
+            await settle(page);
+            const prefillHost = new URL(page.url()).hostname;
+            if (prefillHost !== merchantHost) {
+                const reason = `merchant changed during contact prefill: ${merchantHost} -> ${prefillHost}`;
+                evidence.step('mandate-verdict', {
+                    phase: 'contact-prefill',
+                    ok: false,
+                    reason,
+                });
+                evidence.setSnapshotSummary(await snapshotSummary(page));
+                return {
+                    status: 'finished',
+                    result: makeResult('blocked-by-mandate', fields, evidence, requiresAdapter, reason),
+                };
+            }
+            detected = await detectFields(page);
+            adapter = selectAdapter(detected, { shopify: shopifyPage });
+            evidence.step('adapter-selected', { adapter: adapter.name, phase: 'review' });
+        }
         fields = detected.fields;
         evidence.step('detect', {
             phase: 'review',
@@ -759,7 +835,27 @@ export async function prepareCheckout(opts, store = defaultPreparedCheckoutStore
                 evidence.step('psp-detected', { psp: p.psp, requiresAdapter: p.requiresAdapter });
             }
         }
-        const facts = await readTransactionFacts(page, options);
+        // 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, undefined, 'card-number-field-unavailable'),
+            };
+        }
+        const facts = await readTransactionFacts(page, options, 'review');
         recordTransactionFacts(evidence, 'review', facts);
         if (!facts.ok) {
             evidence.step('mandate-verdict', { phase: 'review', ok: false, reason: facts.reason });
@@ -870,7 +966,7 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
             evidence.setSnapshotSummary(await snapshotSummary(page));
             return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, preFill.reason);
         }
-        const approvedFacts = await readTransactionFacts(page, options);
+        const approvedFacts = await readTransactionFacts(page, options, 'approval');
         recordTransactionFacts(evidence, 'approval', approvedFacts);
         if (!approvedFacts.ok) {
             evidence.step('mandate-verdict', {
@@ -925,6 +1021,16 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
             return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, reason);
         }
         evidence.step('approval', { approved: true, reviewId: checkout.review.id });
+        if (opts.mode === 'dry-run') {
+            evidence.step('credential-skipped', {
+                reason: 'dry-run stops before credential mint or merchant-page disclosure',
+            });
+            evidence.step('submit', { would: true, target: approvalSubmit?.desc ?? 'none found' });
+            evidence.setSnapshotSummary(await snapshotSummary(page));
+            return makeResult('reviewed-dry-run', state.fields, evidence, requiresAdapter, approvalSubmit
+                ? `validated the reviewed checkout; would click ${approvalSubmit.desc}`
+                : 'validated the reviewed checkout; no submit control detected');
+        }
         const credential = await opts.instrument.getCredential({
             merchantHost,
             amountMinor: approvedFacts.amountMinor,
@@ -934,11 +1040,14 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
             ...(credential.credentialExpiresAt
                 ? { credentialExpiresAt: credential.credentialExpiresAt }
                 : {}),
+            ...traceHandleFields(credential),
         });
         // Reveal + fill loop: fills whatever is present, then reveals the next
         // surface (card radio / next step) until the card number is filled.
         const clicked = new Set();
         let adapterName = null;
+        let adapterFillOk = true;
+        let adapterFillDetail = null;
         for (let attempt = 0; attempt < 4; attempt++) {
             // A reveal/continue action can navigate between attempts. Never expose
             // the credential to a host other than the one the human reviewed.
@@ -967,12 +1076,16 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
                     evidence.step('psp-detected', { psp: p.psp, requiresAdapter: p.requiresAdapter });
                 }
             }
-            const adapter = selectAdapter(detected);
+            const adapter = selectAdapter(detected, {
+                shopify: await isShopifyCheckoutPage(page),
+            });
             if (adapter.name !== adapterName) {
                 adapterName = adapter.name;
                 evidence.step('adapter-selected', { adapter: adapter.name });
             }
             const fill = await adapter.fill(page, detected.fields, credential, opts.contact);
+            adapterFillOk = fill.ok;
+            adapterFillDetail = fill.detail ?? null;
             for (const f of fill.filled) {
                 evidence.step('field-fill', {
                     role: f.role,
@@ -1004,9 +1117,30 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
                 ? []
                 : ['expiry']),
         ];
+        // Roles the adapter TRIED to fill and never landed, across every reveal
+        // attempt. A job only exists when the field was detected, was visible, and
+        // we held a value for it (see `add()` in adapters/generic.ts) — so a failure
+        // here is never "the page didn't ask for it". It means the page asked, we
+        // answered, and the element refused.
+        //
+        // Roles that failed on an early attempt and succeeded after a reveal are
+        // excluded: `successfulRoles` spans all four attempts, same as above.
+        const failedFillRoles = [
+            ...new Set(evidence
+                .getSteps()
+                .filter((step) => step.type === 'field-fill' && step.data.ok === false)
+                .map((step) => String(step.data.role))),
+        ]
+            .filter((role) => !successfulRoles.has(role))
+            .sort();
         evidence.step('fill-complete', {
-            ok: missingCredentialRoles.length === 0,
+            // "Ready to submit", not "the card fields landed". Before 2026-08-17 this
+            // read only the credential roles, so a whop.com run whose city/state/
+            // postalCode all timed out recorded `ok: true` and clicked Get access on
+            // a form it knew was incomplete.
+            ok: missingCredentialRoles.length === 0 && failedFillRoles.length === 0,
             missingCredentialRoles,
+            failedFillRoles,
         });
         if (options.debugShotsDir) {
             await captureDebugShot(page, options.debugShotsDir, checkout.review.id, '2-filled', evidence, state.fields);
@@ -1014,7 +1148,7 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
         // Re-run the full gate after fill as well. Contact/shipping fields can
         // change the total; any drift from the approved review refuses before a
         // submit click and requires the caller to prepare a new review.
-        const submitFacts = await readTransactionFacts(page, options);
+        const submitFacts = await readTransactionFacts(page, options, 'pre-submit');
         recordTransactionFacts(evidence, 'pre-submit', submitFacts);
         if (!submitFacts.ok) {
             evidence.step('mandate-verdict', {
@@ -1057,25 +1191,89 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
             evidence.setSnapshotSummary(await snapshotSummary(page));
             return makeResult('blocked-by-mandate', state.fields, evidence, requiresAdapter, submitChangedBeforeClick);
         }
-        if (opts.mode === 'dry-run') {
-            evidence.step('submit', { would: true, target: submit?.desc ?? 'none found' });
+        if (!adapterFillOk) {
             evidence.setSnapshotSummary(await snapshotSummary(page));
-            if (missingCredentialRoles.length > 0) {
-                const adapterRequired = requiresAdapter.size > 0;
-                return makeResult(adapterRequired ? 'adapter-required' : 'partial-fill', state.fields, evidence, requiresAdapter, adapterRequired
-                    ? `credential fields require adapter: ${[...requiresAdapter].join(', ')}; missing ${missingCredentialRoles.join(', ')}`
-                    : `credential fill incomplete: missing ${missingCredentialRoles.join(', ')}`);
-            }
-            return makeResult('filled-dry-run', state.fields, evidence, requiresAdapter, submit ? `would click ${submit.desc}` : 'no submit control detected');
+            return makeResult('failed', state.fields, evidence, requiresAdapter, adapterFillDetail ?? `${adapterName ?? 'checkout'} adapter fill incomplete`);
         }
         if (missingCredentialRoles.length > 0) {
             evidence.setSnapshotSummary(await snapshotSummary(page));
             return makeResult('failed', state.fields, evidence, requiresAdapter, `credential fill incomplete: missing ${missingCredentialRoles.join(', ')}`);
         }
+        // STOP BEFORE THE CLICK when any field we tried to fill refused. Submitting
+        // a form we know is incomplete is how a PSP ends up holding a charge we
+        // cannot then confirm or account for: the 2026-08-17 whop.com run filled the
+        // card into Basis Theory iframes, watched city/state/postalCode time out at
+        // 5s each, clicked Get access anyway, and could never observe an outcome.
+        //
+        // This refusal happens BEFORE the submit click, so nothing can be charged by
+        // it — the safe direction, and the reason it is allowed to be strict. A
+        // merchant whose address widget we cannot drive now fails cleanly and
+        // retryably instead of dangerously.
+        if (failedFillRoles.length > 0) {
+            evidence.setSnapshotSummary(await snapshotSummary(page));
+            // Name the CAUSE per field, not just the field. The refusal is the only
+            // artifact that survives to the operator (a v2 receipt carries no evidence
+            // log), and "city, postalCode refused" without a reason means the next
+            // person has to reproduce a live merchant to learn anything. Each cause
+            // points at a different fix — see summarizeFillFailure.
+            //
+            // Last attempt wins: a role that failed differently across reveal passes
+            // is best described by how it failed when we finally gave up on it.
+            const lastFillError = (role) => {
+                const errors = evidence
+                    .getSteps()
+                    .filter((step) => step.type === 'field-fill' && step.data.ok === false && step.data.role === role)
+                    .map((step) => (typeof step.data.error === 'string' ? step.data.error : undefined));
+                return errors[errors.length - 1];
+            };
+            const reasons = failedFillRoles.map((role) => `${role} (${summarizeFillFailure(lastFillError(role))})`);
+            return makeResult('partial-fill', state.fields, evidence, requiresAdapter, `required field fill failed: ${reasons.join(', ')} — not submitting an incomplete form. Nothing was charged.`, undefined, 'required-field-unfillable');
+        }
         if (!submit) {
             evidence.setSnapshotSummary(await snapshotSummary(page));
             return makeResult('failed', state.fields, evidence, requiresAdapter, 'no submit control detected');
         }
+        // Capture the OTP poll watermark BEFORE the click. The click is what
+        // triggers the merchant's verification email, so the watermark must precede
+        // it — otherwise a fast OTP could arrive before we start looking (the 5s
+        // waitForMessage skew is a second line of defence, but ordering matters).
+        // This is just a timestamp — no PII — so it is safe to record.
+        const otpWatermark = new Date().toISOString();
+        evidence.step('note', { otpWatermarkCaptured: true });
+        // The suppressed Link lookup must settle before the click or it breaks
+        // Stripe's submit chain mid-flight (#5879) — see waitForLinkLookupQuiet.
+        const linkQuiet = await waitForLinkLookupQuiet(page);
+        evidence.step('note', { linkQuiet });
+        // This is deliberately the last await before the irreversible click.
+        // Mint-time validation is not enough: reveal/fill and Link suppression can
+        // consume a short-lived DAVV. Refuse malformed or <60s credentials so an
+        // expiry decline cannot masquerade as a form-fill failure.
+        const credentialExpiresAt = credential.credentialExpiresAt;
+        const expiryMissing = opts.instrument.kind === 'agentic-token' && credentialExpiresAt === undefined;
+        const expiresMs = credentialExpiresAt === undefined ? Number.NaN : Date.parse(credentialExpiresAt);
+        if (expiryMissing ||
+            (credentialExpiresAt !== undefined &&
+                (!Number.isFinite(expiresMs) || expiresMs - Date.now() < 60_000))) {
+            evidence.step('credential-expiry-check', {
+                ok: false,
+                reason: expiryMissing ? 'missing' : 'invalid-or-expiring',
+                ...(credentialExpiresAt !== undefined ? { credentialExpiresAt } : {}),
+            });
+            evidence.setSnapshotSummary(await snapshotSummary(page));
+            return makeResult('failed', state.fields, evidence, requiresAdapter, 'credential expired before submit; obtain a fresh intent and re-review');
+        }
+        if (credentialExpiresAt !== undefined) {
+            evidence.step('credential-expiry-check', {
+                ok: true,
+                credentialExpiresAt,
+            });
+        }
+        // ORDER IS LOAD-BEARING: record the click BEFORE performing it. The catch
+        // block classifies a throw by whether this step exists — recorded means
+        // "we may have charged" (`unverified`), absent means "retry is safe"
+        // (`failed`). Recording after `submit.click()` would let a throw raised by
+        // the click itself look retry-safe, which is the double-charge direction.
+        // Pinned by "a throw AFTER the pay control was clicked reports unverified".
         evidence.step('submit', { clicked: true, target: submit.desc });
         await submit.click();
         await settle(page);
@@ -1096,6 +1294,57 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
             });
             observed = reconcileHeldOutcome(observed, held);
         }
+        // Agent-resolvable email OTP subroutine (SINGLE-USE). Fires only on a
+        // 'verification-required' verdict (the merchant emailed a code to the
+        // agent's own inbox) AND when a resolver is injected. Fills the code EXACTLY
+        // ONCE, re-submits, and re-observes. Merchants invalidate a code on first
+        // use, so a stale code is NEVER retried. On no resolver / timeout / missing
+        // code field it falls through to the action-required (human) path below —
+        // it never hangs and never re-fills credential material.
+        if (observed.status === 'verification-required' && opts.resolveEmailOtp) {
+            const otpDetect = await detectFields(page);
+            const codeField = otpDetect.fields.oneTimeCode;
+            if (!codeField) {
+                evidence.step('note', { emailOtp: 'no one-time-code field detected' });
+            }
+            else {
+                const resolution = await opts.resolveEmailOtp({
+                    after: otpWatermark,
+                    merchantHost: submitMerchantHost,
+                });
+                if (!resolution) {
+                    // Fail CLEAN: no code retrieved before the resolver's timeout.
+                    evidence.step('note', { emailOtp: 'not retrieved before timeout' });
+                }
+                else {
+                    // Fill once. maskOtp() ensures the code NEVER enters the evidence log
+                    // (receipt.ts's PAN backstop does not catch a 4-8 digit OTP). The
+                    // sender domain is a non-PII trust signal, safe to record.
+                    await page.locator(codeField.locator).fill(resolution.code);
+                    evidence.step('field-fill', {
+                        role: 'oneTimeCode',
+                        confidence: codeField.confidence,
+                        source: codeField.source,
+                        frame: codeField.frame,
+                        value: maskOtp(),
+                        ok: true,
+                        fromDomain: resolution.fromDomain,
+                    });
+                    const otpSubmit = await findSubmit(page);
+                    if (!otpSubmit) {
+                        evidence.step('note', { emailOtp: 'code filled but no submit control found' });
+                    }
+                    else {
+                        const otpLinkQuiet = await waitForLinkLookupQuiet(page);
+                        evidence.step('note', { linkQuiet: otpLinkQuiet, phase: 'post-otp' });
+                        evidence.step('submit', { clicked: true, target: otpSubmit.desc, phase: 'post-otp' });
+                        await otpSubmit.click();
+                        await settle(page);
+                        observed = await observeOutcome(page, { deadlineMs: opts.outcomeDeadlineMs });
+                    }
+                }
+            }
+        }
         evidence.setSnapshotSummary(await snapshotSummary(page));
         if (options.debugShotsDir) {
             await captureDebugShot(page, options.debugShotsDir, checkout.review.id, '3-outcome', evidence, state.fields);
@@ -1121,6 +1370,20 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
             });
             return makeResult('action-required', state.fields, evidence, requiresAdapter, `issuer verification required (${observed.signal}) — a human must complete the challenge; no charge exists until it is completed`);
         }
+        if (observed.status === 'verification-required') {
+            // Still needing an email code after the subroutine (no resolver injected,
+            // the code never arrived, or no code field) — hand off to a human. Mapped
+            // to the same action-required outcome; the code is single-use so we never
+            // retry here.
+            evidence.step('outcome', {
+                outcome: 'action-required',
+                signal: observed.signal,
+                reason: 'email verification code required but not auto-resolved',
+                attempts: observed.attempts,
+                elapsedMs: observed.elapsedMs,
+            });
+            return makeResult('action-required', state.fields, evidence, requiresAdapter, `email verification required (${observed.signal}) — a human must enter the code sent to the inbox`);
+        }
         if (observed.status === 'confirmed') {
             const confirmationRef = await readConfirmationRef(page);
             evidence.step('outcome', {
@@ -1132,19 +1395,35 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
             });
             return makeResult('confirmed', state.fields, evidence, requiresAdapter, undefined, confirmationRef);
         }
+        // The pay control was clicked and the observer reached its deadline with no
+        // definitive answer. This is NOT a failure — it is the absence of an answer,
+        // and the charge may well have captured. Reporting it as `failed` is what
+        // let a caller re-run the 2026-08-17 whop.com purchase and draw a second $5.
         evidence.step('outcome', {
-            outcome: 'failed',
+            outcome: 'unverified',
             reason: 'no confirmation or decline signal',
             lastSeen: observed.lastSeen,
             attempts: observed.attempts,
             elapsedMs: observed.elapsedMs,
         });
-        return makeResult('failed', state.fields, evidence, requiresAdapter, observed.lastSeen === 'processing'
-            ? 'submitted but outcome unknown (page still processing at deadline)'
-            : 'submitted but outcome unknown');
+        return makeResult('unverified', state.fields, evidence, requiresAdapter, observed.lastSeen === 'processing'
+            ? 'submitted but outcome unknown (page still processing at deadline) — the charge may have gone through; verify with the merchant before any retry'
+            : 'submitted but outcome unknown — the charge may have gone through; verify with the merchant before any retry');
     }
     catch (err) {
         const detail = err.message;
+        // A throw AFTER the pay control was clicked (browser teardown, navigation
+        // race, evidence I/O) leaves the same open question as the deadline path: we
+        // clicked, and we do not know what happened. It must not report `failed`
+        // either. A throw before the click never disclosed a payable form, so it
+        // stays a clean, retry-safe failure.
+        const submitted = evidence
+            .getSteps()
+            .some((step) => step.type === 'submit' && step.data.clicked === true);
+        if (submitted) {
+            evidence.step('outcome', { outcome: 'unverified', error: detail });
+            return makeResult('unverified', state.fields, evidence, requiresAdapter, `${detail} — the pay control was already clicked; the charge may have gone through, so verify with the merchant before any retry`);
+        }
         evidence.step('outcome', { outcome: 'failed', error: detail });
         return makeResult('failed', state.fields, evidence, requiresAdapter, detail);
     }
@@ -1173,8 +1452,8 @@ export async function cancelPreparedCheckout(reviewId, detail = 'checkout cancel
 // approves that exact review ID. Human-in-the-loop callers should use the
 // explicit prepareCheckout()/submitApprovedCheckout() pair instead.
 export async function runCheckout(opts, store = defaultPreparedCheckoutStore) {
-    const { instrument, contact, mode, outcomeDeadlineMs, ...prepareOptions } = opts;
-    const preparation = await prepareCheckout(prepareOptions, store);
+    const { instrument, contact, mode, outcomeDeadlineMs, resolveEmailOtp, ...prepareOptions } = opts;
+    const preparation = await prepareCheckout({ ...prepareOptions, contact }, store);
     if (preparation.status === 'finished')
         return preparation.result;
     return submitApprovedCheckout(preparation.checkout.review.id, {
@@ -1183,5 +1462,6 @@ export async function runCheckout(opts, store = defaultPreparedCheckoutStore) {
         contact,
         mode,
         outcomeDeadlineMs,
+        ...(resolveEmailOtp ? { resolveEmailOtp } : {}),
     }, store);
 }