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

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,20 @@
 //     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 { traceHandleFields } from './trace-handles.js';
+import { readGenericPageAmount } from './amount.js';
+import { detectShopifyChallenge, isShopifyCheckoutPage, readShopifyAmount, readStableShopifyAmount, } 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 +40,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 +145,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 +166,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
@@ -444,8 +376,19 @@ function makeResult(outcome, fields, evidence, requiresAdapter, detail, confirma
         ...(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 +417,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 +573,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 +598,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.
@@ -745,7 +730,62 @@ 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);
+        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 +799,7 @@ export async function prepareCheckout(opts, store = defaultPreparedCheckoutStore
                 evidence.step('psp-detected', { psp: p.psp, requiresAdapter: p.requiresAdapter });
             }
         }
-        const facts = await readTransactionFacts(page, options);
+        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 +910,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 +965,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 +984,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 +1020,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,
@@ -1014,7 +1071,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,16 +1114,9 @@ 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));
@@ -1076,6 +1126,41 @@ export async function submitApprovedCheckout(reviewId, opts, store = defaultPrep
             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,
+            });
+        }
         evidence.step('submit', { clicked: true, target: submit.desc });
         await submit.click();
         await settle(page);
@@ -1096,6 +1181,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 +1257,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', {
@@ -1173,8 +1323,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 +1333,6 @@ export async function runCheckout(opts, store = defaultPreparedCheckoutStore) {
         contact,
         mode,
         outcomeDeadlineMs,
+        ...(resolveEmailOtp ? { resolveEmailOtp } : {}),
     }, store);
 }