@visa/cli 4.1.0-rc.25 → 4.1.0-rc.27

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

@@ -2,7 +2,7 @@ import type { Browser, BrowserContext, Page } from 'playwright-core';
 import { type FieldMap } from './detect.js';
 import { type Mandate } from './mandate.js';
 import type { Instrument } from './instrument.js';
-import type { Contact } from './types.js';
+import type { Contact, OtpResolver } from './types.js';
 import { EvidenceLog } from './evidence.js';
 import { type ObservedOutcome } from './outcome.js';
 export type CheckoutMode = 'dry-run' | 'submit';
@@ -37,6 +37,7 @@ export type RunCheckoutOptions = PrepareCheckoutOptions & {
     contact: Contact;
     mode: CheckoutMode;
     outcomeDeadlineMs?: number;
+    resolveEmailOtp?: OtpResolver;
 };
 export type CheckoutReview = {
     id: string;
@@ -86,6 +87,7 @@ export type SubmitApprovedCheckoutOptions = {
     outcomeDeadlineMs?: number;
     challengeHoldMs?: number;
     onChallengeHold?: (signal: string | null) => void;
+    resolveEmailOtp?: OtpResolver;
 };
 export declare function minorFromDecimal(text: string): number | null;
 export declare function pageCurrency(text: string): string | null;

package/dist/checkout-engine/executor.js

@@ -18,7 +18,7 @@ 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';
 const SUBMIT_TEXT = /pay|place order|complete|buy|submit|checkout/i;
@@ -1118,6 +1118,13 @@ 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);
@@ -1142,6 +1149,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);
@@ -1167,6 +1225,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', {
@@ -1219,7 +1291,7 @@ 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 { instrument, contact, mode, outcomeDeadlineMs, resolveEmailOtp, ...prepareOptions } = opts;
     const preparation = await prepareCheckout(prepareOptions, store);
     if (preparation.status === 'finished')
         return preparation.result;
@@ -1229,5 +1301,6 @@ export async function runCheckout(opts, store = defaultPreparedCheckoutStore) {
         contact,
         mode,
         outcomeDeadlineMs,
+        ...(resolveEmailOtp ? { resolveEmailOtp } : {}),
     }, store);
 }

package/dist/checkout-engine/hosted-approval.d.ts

@@ -26,15 +26,44 @@ import type { PurchaseAssurance, VgsCheckoutTarget } from './vgs-live-instrument
  * hang the runner past the advertised timeout.
  */
 export type HostedApprovalOptions = {
-    /** The verify-web deployment origin, e.g. https://v4-verify-web-….up.railway.app */
+    /** The enrollment web deployment origin (apps/web), e.g. https://web-….up.railway.app */
     baseUrl: string;
     /** Durable agentic token id from the CLI agent credential. */
     tokenId: string;
     target: VgsCheckoutTarget;
     /** Prefills the approval page's enrollment-email field (optional). */
     consumerEmail?: string;
+    /**
+     * BUDGET/mandate approval: `target.transactionAmount` is the approved spend
+     * CEILING (not one charge), so the server mints a BUDGET mint token that later
+     * accepts many sub-ceiling draws tap-free. Omit for a single-purchase approval.
+     */
+    budget?: boolean;
+    /** Advisory max draws the ceiling intent may fulfil — carried onto the token. */
+    maxDraws?: number;
+    /**
+     * Per-purchase cap (decimal string, <= the ceiling) on a BUDGET approval —
+     * shown on the approval page as a worst-case term and carried onto the mint
+     * token so the displayed cap is the enforced cap. Budget mode only.
+     */
+    perTransaction?: string;
+    /**
+     * Agent-supplied one-liner describing what this approval is for. Sanitized
+     * here (control chars stripped, trimmed, capped) and rendered by the approval
+     * page in a clearly-labeled "written by the agent" block — provenance for the
+     * human to cross-check, never a trusted field.
+     */
+    intent?: string;
     log?: (line: string) => void;
-    /** Injectable for tests; default opens the operator's default browser (macOS). */
+    /**
+     * Called once with the approval URL as DATA (not a log line) the instant it is
+     * known — before any polling. A headless agent (OpenClaw/Hermes) has no browser
+     * and no passkey; its whole job is to relay this URL to its human operator, so
+     * the URL must be capturable as a value, not just printed. The interactive CLI
+     * leaves this unset and relies on `log` + `openUrl`.
+     */
+    onApprovalUrl?: (url: string) => void;
+    /** Injectable for tests; default opens the operator's default browser, best-effort. */
     openUrl?: (url: string) => void;
     fetchImpl?: typeof fetch;
     /** Injectable for tests — never wall-clock-sleep in a unit test. */
@@ -43,15 +72,43 @@ export type HostedApprovalOptions = {
     pollIntervalMs?: number;
     timeoutMs?: number;
 };
+/** One short sentence — must match the relay's cap (agent-approval.ts). */
+export declare const APPROVAL_INTENT_MAX_CHARS = 200;
+/**
+ * Sanitize an agent-supplied intent to what the relay will accept and the page
+ * will display: control chars (and JS line separators) stripped, trimmed,
+ * TRUNCATED to the cap (the runner is the agent's own side, so truncating here
+ * beats a failed registration; the server still rejects an over-cap value).
+ * Returns undefined when nothing displayable remains.
+ */
+export declare function sanitizeApprovalIntent(value: string | undefined): string | undefined;
+/**
+ * The operator saw the request and said NO. Terminal and non-retryable: the
+ * relay entry is consumed, re-running would only re-ask a human who already
+ * refused. Callers must not classify this as transient.
+ */
+export declare class HostedApprovalDeclinedError extends Error {
+    constructor();
+}
 export declare const HOSTED_APPROVAL_TIMEOUT_MS: number;
 export declare const HOSTED_APPROVAL_POLL_MS = 3000;
+/** Emit a "still waiting" heartbeat roughly every this-many ms during the poll. */
+export declare const HOSTED_APPROVAL_HEARTBEAT_MS = 30000;
+/**
+ * Resolve the approval timeout: `CHECKOUT_APPROVAL_TIMEOUT_MS` (seconds*1000, an
+ * integer ms) overrides the default when it parses to a positive integer.
+ * Lets an operator widen the window for separate-device / headless approval
+ * without threading a flag through every caller. Invalid values fall back.
+ */
+export declare function resolveApprovalTimeoutMs(): number;
 /**
- * The one deployed verify site — hosted approval is the NORMAL path (no local
- * certs, no vendored SDK, no localhost anywhere), so its origin is a built-in
- * default rather than per-machine config. Not a secret: it's the public page
- * the operator's browser opens anyway.
+ * The staging apps/web deploy (which now hosts the /agent/enroll/approve page
+ * after the v4-verify-web GA graduation) — hosted approval is the NORMAL path
+ * (no local certs, no vendored SDK, no localhost anywhere), so its origin is a
+ * built-in default rather than per-machine config. Not a secret: it's the
+ * public page the operator's browser opens anyway.
  */
-export declare const DEFAULT_APPROVAL_BASE_URL = "https://v4-verify-web-visa-code-preview.up.railway.app";
+export declare const DEFAULT_APPROVAL_BASE_URL = "https://web-visa-code-preview.up.railway.app";
 /**
  * Flag > environment > built-in default. An explicitly EMPTY value
  * (CHECKOUT_APPROVAL_BASE_URL='') opts out of hosted approval entirely —

package/dist/checkout-engine/hosted-approval.js

@@ -1,25 +1,89 @@
 import { createHash, randomBytes } from 'node:crypto';
 import { exec } from 'node:child_process';
 import { assuranceFromCeremony } from './ceremony.js';
+/** One short sentence — must match the relay's cap (agent-approval.ts). */
+export const APPROVAL_INTENT_MAX_CHARS = 200;
+/**
+ * Sanitize an agent-supplied intent to what the relay will accept and the page
+ * will display: control chars (and JS line separators) stripped, trimmed,
+ * TRUNCATED to the cap (the runner is the agent's own side, so truncating here
+ * beats a failed registration; the server still rejects an over-cap value).
+ * Returns undefined when nothing displayable remains.
+ */
+export function sanitizeApprovalIntent(value) {
+    if (value === undefined)
+        return undefined;
+    const cleaned = value
+        .replace(/[\p{Cc}\u2028\u2029]/gu, '')
+        .trim()
+        .slice(0, APPROVAL_INTENT_MAX_CHARS)
+        .trim();
+    return cleaned.length > 0 ? cleaned : undefined;
+}
+/**
+ * The operator saw the request and said NO. Terminal and non-retryable: the
+ * relay entry is consumed, re-running would only re-ask a human who already
+ * refused. Callers must not classify this as transient.
+ */
+export class HostedApprovalDeclinedError extends Error {
+    constructor() {
+        super('The approver declined this request — the checkout was cancelled and nothing was charged');
+        this.name = 'HostedApprovalDeclinedError';
+    }
+}
 export const HOSTED_APPROVAL_TIMEOUT_MS = 4 * 60 * 1000;
 export const HOSTED_APPROVAL_POLL_MS = 3_000;
+/** Emit a "still waiting" heartbeat roughly every this-many ms during the poll. */
+export const HOSTED_APPROVAL_HEARTBEAT_MS = 30_000;
+/**
+ * Resolve the approval timeout: `CHECKOUT_APPROVAL_TIMEOUT_MS` (seconds*1000, an
+ * integer ms) overrides the default when it parses to a positive integer.
+ * Lets an operator widen the window for separate-device / headless approval
+ * without threading a flag through every caller. Invalid values fall back.
+ */
+export function resolveApprovalTimeoutMs() {
+    const raw = process.env.CHECKOUT_APPROVAL_TIMEOUT_MS;
+    if (raw !== undefined) {
+        const n = Number(raw);
+        if (Number.isSafeInteger(n) && n > 0)
+            return n;
+    }
+    return HOSTED_APPROVAL_TIMEOUT_MS;
+}
 /** Unref'd so a raced-and-abandoned deadline timer can never hold the process open. */
 const defaultSleep = (ms) => new Promise((r) => {
     const t = setTimeout(r, ms);
     t.unref?.();
 });
 function defaultOpenUrl(url) {
-    // Quoting: the URL is server-origin + our own base64url challenge — no
-    // shell-hostile characters — but single-quote anyway.
-    exec(`open '${url.replaceAll("'", "'\\''")}'`);
+    // Best-effort convenience only — the URL is always surfaced via `log`/
+    // `onApprovalUrl`, so this must never throw or hang if there is no browser.
+    // `CHECKOUT_SKIP_BROWSER_OPEN=1` disables it (headless/agent hosts where
+    // launching a browser on the WRONG machine is pointless or noisy).
+    if (process.env.CHECKOUT_SKIP_BROWSER_OPEN === '1')
+        return;
+    // Platform-appropriate opener; unknown platforms just skip (the URL is logged).
+    const opener = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start ""' : 'xdg-open';
+    if (process.platform !== 'darwin' && process.platform !== 'win32' && process.platform !== 'linux')
+        return;
+    const quoted = `'${url.replaceAll("'", "'\\''")}'`;
+    try {
+        // exec is async and fire-and-forget; swallow the callback error so a missing
+        // opener binary (common on headless Linux) can never surface as a failure.
+        exec(`${opener} ${quoted}`, () => { });
+    }
+    catch {
+        // Spawn failure (no shell, sandboxed) — ignore; the printed URL is the path.
+    }
 }
 /**
- * The one deployed verify site — hosted approval is the NORMAL path (no local
- * certs, no vendored SDK, no localhost anywhere), so its origin is a built-in
- * default rather than per-machine config. Not a secret: it's the public page
- * the operator's browser opens anyway.
+ * The staging apps/web deploy (which now hosts the /agent/enroll/approve page
+ * after the v4-verify-web GA graduation) — hosted approval is the NORMAL path
+ * (no local certs, no vendored SDK, no localhost anywhere), so its origin is a
+ * built-in default rather than per-machine config. Not a secret: it's the
+ * public page the operator's browser opens anyway.
  */
-export const DEFAULT_APPROVAL_BASE_URL = 'https://v4-verify-web-visa-code-preview.up.railway.app';
+export const DEFAULT_APPROVAL_BASE_URL = 'https://web-visa-code-preview.up.railway.app';
 /**
  * Flag > environment > built-in default. An explicitly EMPTY value
  * (CHECKOUT_APPROVAL_BASE_URL='') opts out of hosted approval entirely —
@@ -64,12 +128,23 @@ function stripTrailingSlashes(value) {
  * rather than falling back to a client-held secret.
  */
 export async function runHostedApproval(opts) {
-    const { baseUrl, tokenId, target, consumerEmail, log = () => { }, openUrl = defaultOpenUrl, fetchImpl = fetch, sleep = defaultSleep, now = Date.now, pollIntervalMs = HOSTED_APPROVAL_POLL_MS, timeoutMs = HOSTED_APPROVAL_TIMEOUT_MS, } = opts;
+    const { baseUrl, tokenId, target, consumerEmail, budget, maxDraws, perTransaction, intent, 
+    // Default to stderr, NOT a no-op: the approval URL is the one thing a remote /
+    // SSH / headless-terminal human needs to proceed, and swallowing it (the old
+    // `() => {}` default) left it emitted nowhere readable. Tests inject their own.
+    log = (line) => void process.stderr.write(`${line}\n`), onApprovalUrl, openUrl = defaultOpenUrl, fetchImpl = fetch, sleep = defaultSleep, now = Date.now, pollIntervalMs = HOSTED_APPROVAL_POLL_MS, 
+    // A human approving on a SEPARATE device (open the link, sign in, tap the
+    // passkey) needs more than the interactive 4-minute window; allow an env
+    // override without threading a flag through every caller.
+    timeoutMs = resolveApprovalTimeoutMs(), } = opts;
     const base = stripTrailingSlashes(assertApprovalBaseUrl(baseUrl));
     // The server's currency map is uppercase ISO 4217; the loader normalizes the
     // target once, but normalize here too so a direct caller with a lowercase
     // code registers (and verifies) the same value the relay stores.
     const currency = target.transactionCurrencyCode.toUpperCase();
+    // Sanitize once, register + verify the SAME value: the relay stores the
+    // sanitized form, so equality below must compare against it, not the raw input.
+    const intentSanitized = sanitizeApprovalIntent(intent);
     const verifier = randomBytes(32).toString('base64url');
     const challenge = createHash('sha256').update(verifier, 'utf8').digest('base64url');
     const deadline = now() + timeoutMs;
@@ -107,6 +182,10 @@ export async function runHostedApproval(opts) {
                 amount: target.transactionAmount,
                 currency,
                 ...(consumerEmail ? { consumerEmail } : {}),
+                ...(budget ? { budget: true } : {}),
+                ...(budget && maxDraws !== undefined ? { maxDraws } : {}),
+                ...(budget && perTransaction !== undefined ? { perTransaction } : {}),
+                ...(intentSanitized !== undefined ? { intent: intentSanitized } : {}),
             },
         }),
     });
@@ -115,57 +194,118 @@ export async function runHostedApproval(opts) {
         throw new Error(`could not register the hosted approval (${registerRes.status})` +
             (body.error ? `: ${body.error}` : ''));
     }
-    const approveUrl = `${base}/approve?req=${challenge}`;
+    // GA graduation: the approval page moved into apps/web under /agent/enroll
+    // (the /api/vgs/** routes above kept their paths verbatim).
+    const approveUrl = `${base}/agent/enroll/approve?req=${challenge}`;
+    // Surface the URL as DATA first (headless relay), then as a log line + best-
+    // effort browser open for the interactive case.
+    onApprovalUrl?.(approveUrl);
     log(`approve the purchase in your browser: ${approveUrl}`);
     openUrl(approveUrl);
-    for (;;) {
-        const res = await fetchWithDeadline(`${base}/api/vgs/agent-approval/claim`, {
-            method: 'POST',
-            headers: { 'content-type': 'application/json' },
-            body: JSON.stringify({ verifier }),
-        });
-        if (res.ok) {
-            const doc = (await res.json().catch(() => null));
-            if (doc?.status === 'completed') {
-                if (doc.assuranceData === undefined || doc.assuranceData === null) {
-                    throw new Error('hosted approval completed but carried no assuranceData');
-                }
-                // The context the approval was COMPLETED against must be exactly this
-                // run's checkout target — a divergent field means the relay entry was
-                // not ours (corruption, or a mutated registration) and the assurance
-                // is scoped to something else. Fail naming the field; no secrets here
-                // (merchant facts only).
-                const expected = {
-                    tokenId,
-                    merchantName: target.merchantName,
-                    merchantUrl: target.merchantUrl,
-                    merchantCountryCode: target.merchantCountryCode,
-                    amount: target.transactionAmount,
-                    currency,
-                };
-                for (const [field, want] of Object.entries(expected)) {
-                    if (doc.context?.[field] !== want) {
-                        throw new Error(`hosted approval context mismatch on ${field} — the approval was not for this ` +
+    let lastHeartbeat = now();
+    // Keep the event loop alive for the whole poll wait. `defaultSleep` unref()'s
+    // its timer (so the deadline race can't hang the process past the timeout), but
+    // that means the ONLY pending work between polls is an unref'd timer — in a bare
+    // CLI invocation (no stdin/other handles) node would exit 0 mid-poll, after the
+    // first `pending` claim and before the operator finishes the passkey, so the
+    // minted token is parked but never claimed. A ref'd keepalive, cleared on every
+    // exit, holds the process open until the poll loop returns/throws.
+    const keepAlive = setInterval(() => { }, 60_000);
+    try {
+        for (;;) {
+            const res = await fetchWithDeadline(`${base}/api/vgs/agent-approval/claim`, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ verifier }),
+            });
+            if (res.ok) {
+                const doc = (await res.json().catch(() => null));
+                // The operator refused — terminal and immediate. Exit the wait now
+                // rather than polling out the timeout; retrying cannot help.
+                if (doc?.status === 'declined')
+                    throw new HostedApprovalDeclinedError();
+                if (doc?.status === 'completed') {
+                    if (doc.assuranceData === undefined || doc.assuranceData === null) {
+                        throw new Error('hosted approval completed but carried no assuranceData');
+                    }
+                    // The context the approval was COMPLETED against must be exactly this
+                    // run's checkout target — a divergent field means the relay entry was
+                    // not ours (corruption, or a mutated registration) and the assurance
+                    // is scoped to something else. Fail naming the field; no secrets here
+                    // (merchant facts only).
+                    const expected = {
+                        tokenId,
+                        merchantName: target.merchantName,
+                        merchantUrl: target.merchantUrl,
+                        merchantCountryCode: target.merchantCountryCode,
+                        amount: target.transactionAmount,
+                        currency,
+                    };
+                    for (const [field, want] of Object.entries(expected)) {
+                        if (doc.context?.[field] !== want) {
+                            throw new Error(`hosted approval context mismatch on ${field} — the approval was not for this ` +
+                                'exact purchase; run the checkout again for a fresh link');
+                        }
+                    }
+                    // A budget approval must complete AS a budget approval — a relay that
+                    // dropped the flag would mint a single-purchase token that then rejects
+                    // the first sub-ceiling draw. Compare the boolean explicitly (it is not a
+                    // string, so it lives outside the string-map loop above).
+                    if (Boolean(doc.context?.budget) !== Boolean(budget)) {
+                        throw new Error('hosted approval context mismatch on budget — the approval was not for this ' +
+                            'exact purchase; run the checkout again for a fresh link');
+                    }
+                    // The advisory draw ceiling must survive the relay intact too — a relay
+                    // that dropped or altered maxDraws would mint a budget token whose draw
+                    // count no longer matches what the operator approved. Only the budget
+                    // path registers maxDraws, so only enforce it there; compare exactly,
+                    // the omitted/undefined case included, so a silently dropped value is
+                    // caught the same as a mutated one.
+                    if (budget && doc.context?.maxDraws !== maxDraws) {
+                        throw new Error('hosted approval context mismatch on maxDraws — the approval was not for this ' +
+                            'exact purchase; run the checkout again for a fresh link');
+                    }
+                    // Same drop-or-mutate rule for the per-purchase cap: the term the
+                    // operator read must be the term the token enforces.
+                    if (budget && doc.context?.perTransaction !== perTransaction) {
+                        throw new Error('hosted approval context mismatch on perTransaction — the approval was not for ' +
+                            'this exact purchase; run the checkout again for a fresh link');
+                    }
+                    // The intent is display-only, but a relay that altered it showed the
+                    // operator different words than the agent sent — refuse, either way.
+                    if (doc.context?.intent !== intentSanitized) {
+                        throw new Error('hosted approval context mismatch on intent — the approval was not for this ' +
                             'exact purchase; run the checkout again for a fresh link');
                     }
+                    log('passkey approval received from the hosted page.');
+                    return {
+                        ...assuranceFromCeremony(target, doc.assuranceData),
+                        ...(typeof doc.mintToken === 'string' && doc.mintToken
+                            ? { mintToken: doc.mintToken }
+                            : {}),
+                    };
                 }
-                log('passkey approval received from the hosted page.');
-                return {
-                    ...assuranceFromCeremony(target, doc.assuranceData),
-                    ...(typeof doc.mintToken === 'string' && doc.mintToken
-                        ? { mintToken: doc.mintToken }
-                        : {}),
-                };
+                // status 'pending' — the operator is still signing in / tapping.
             }
-            // status 'pending' — the operator is still signing in / tapping.
-        }
-        else if (res.status === 404) {
-            // Registered moments ago, so absent now means expired or already claimed.
-            throw new Error('the hosted approval expired or was already used — run the checkout again for a fresh link');
+            else if (res.status === 404) {
+                // Registered moments ago, so absent now means expired or already claimed.
+                throw new Error('the hosted approval expired or was already used — run the checkout again for a fresh link');
+            }
+            // Any other status (429 rate bucket, transient 5xx) polls through.
+            if (now() >= deadline)
+                throw timeoutError();
+            // Heartbeat so a human staring at a terminal (or an agent tailing logs)
+            // knows the wait is live and where to approve — the loop is otherwise silent
+            // for up to the full timeout between the open and the completed claim.
+            if (now() - lastHeartbeat >= HOSTED_APPROVAL_HEARTBEAT_MS) {
+                lastHeartbeat = now();
+                const leftS = Math.max(0, Math.round((deadline - now()) / 1000));
+                log(`still waiting for approval (~${leftS}s left) — approve at ${approveUrl}`);
+            }
+            await sleep(pollIntervalMs);
         }
-        // Any other status (429 rate bucket, transient 5xx) polls through.
-        if (now() >= deadline)
-            throw timeoutError();
-        await sleep(pollIntervalMs);
+    }
+    finally {
+        clearInterval(keepAlive);
     }
 }

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

@@ -1,3 +1,6 @@
-export { createCliCheckoutEngine, type CliReviewInput, type CliReviewFacts, type CliPayInput, type CliReceiptFacts, } from './cli-engine.js';
+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 { 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,3 +3,6 @@
 // primitives are re-exported for direct/embedded use.
 export { createCliCheckoutEngine, } from './cli-engine.js';
 export { prepareCheckout, submitApprovedCheckout, runCheckout, InMemoryPreparedCheckoutStore, } from './executor.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/instrument.d.ts

@@ -24,6 +24,7 @@ export declare const OFFICIAL_TEST_PANS: {
     readonly visaSlowConfirm: "4000000000000069";
     readonly visaUnknownOutcome: "4000000000000044";
     readonly visaChallenge: "4000000000000010";
+    readonly visaEmailOtp: "4000000000000077";
 };
 export type TestCardOptions = {
     pan?: string;

package/dist/checkout-engine/instrument.js

@@ -22,6 +22,10 @@ export const OFFICIAL_TEST_PANS = {
     // page embedding an ACS challenge iframe that never completes — exercises
     // the observer's action-required (issuer challenge) path.
     visaChallenge: '4000000000000010',
+    // Ending 0077: the fixture acquirer emails a one-time code to the agent
+    // inbox and shows a 'check your email for a code' page with a one-time-code
+    // field — exercises the executor's agent-resolvable email-OTP subroutine.
+    visaEmailOtp: '4000000000000077',
 };
 function futureExpiry() {
     const now = new Date();

package/dist/checkout-engine/live-fill-approval.d.ts

@@ -16,15 +16,6 @@ export declare function parseCheckoutMode(value: string | undefined, env?: Recor
  * review id; the passkey is a FIDO ceremony on the verify site).
  */
 export declare function assertSubmitAllowed(mode: CheckoutMode, env?: Record<string, string | undefined>, isInteractive?: boolean): void;
-export declare const LEGACY_REFERENCE_ENV_FLAG = "CHECKOUT_AGENT_ALLOW_LEGACY_REFERENCE";
-/**
- * The legacy --reference-file path replays a PRE-CREATED intent, so the
- * purchase-assurance gate (#5709) cannot vet the ceremony that backed it —
- * scope/freshness problems surface only as the opaque cryptogram failure the
- * gate exists to prevent. Default-off escape hatch, same shape as the submit
- * gate: fail fast before any file is read.
- */
-export declare function assertLegacyReferenceAllowed(usingReferenceFile: boolean, env?: Record<string, string | undefined>): void;
 /** Distinct phrases per mode so dry-run muscle memory can never authorize a payment. */
 export declare function approvalPhrase(mode: CheckoutMode, reviewId: string): string;
 /** Integer-only minor→display formatting (two-decimal currencies, the same assumption as decimalToMinor). */

package/dist/checkout-engine/live-fill-approval.js

@@ -46,23 +46,6 @@ export function assertSubmitAllowed(mode, env = process.env, isInteractive = pro
         `require ${SUBMIT_ENV_FLAG}=1. The gate is default-off so automation cannot ` +
         'reach a live charge by accident.');
 }
-export const LEGACY_REFERENCE_ENV_FLAG = 'CHECKOUT_AGENT_ALLOW_LEGACY_REFERENCE';
-/**
- * The legacy --reference-file path replays a PRE-CREATED intent, so the
- * purchase-assurance gate (#5709) cannot vet the ceremony that backed it —
- * scope/freshness problems surface only as the opaque cryptogram failure the
- * gate exists to prevent. Default-off escape hatch, same shape as the submit
- * gate: fail fast before any file is read.
- */
-export function assertLegacyReferenceAllowed(usingReferenceFile, env = process.env) {
-    if (!usingReferenceFile)
-        return;
-    if (env[LEGACY_REFERENCE_ENV_FLAG] !== '1') {
-        throw new Error(`--reference-file refused: this legacy path bypasses purchase-assurance validation ` +
-            `(#5709) — prefer --checkout-file with --purchase-assurance-file. Set ` +
-            `${LEGACY_REFERENCE_ENV_FLAG}=1 to proceed anyway.`);
-    }
-}
 /** Distinct phrases per mode so dry-run muscle memory can never authorize a payment. */
 export function approvalPhrase(mode, reviewId) {
     return `${mode === 'submit' ? 'PAY' : 'FILL'} ${reviewId}`;