@visa/cli 4.1.0-rc.16 → 4.1.0-rc.161

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

@@ -26,15 +26,51 @@ 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 — the only kind since #7348 retired the
+     * single-purchase plane: `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.
+     */
+    budget: true;
+    /**
+     * Exact current request-key thumbprint receiving the budget; the
+     * authenticated page resolves it to the owner's stable agent before
+     * displaying or signing.
+     */
+    agentJkt: string;
+    /** Max draws the ceiling intent may fulfil — carried onto the token. */
+    maxDraws: number;
+    /**
+     * Per-purchase cap (decimal string, <= the ceiling) — shown on the approval
+     * page as a worst-case term and carried onto the mint token so the displayed
+     * cap is the enforced cap.
+     */
+    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 +79,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;
 /**
- * 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.
+ * 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 const DEFAULT_APPROVAL_BASE_URL = "https://v4-verify-web-visa-code-preview.up.railway.app";
+export declare function resolveApprovalTimeoutMs(): number;
+/**
+ * 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://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 —
@@ -75,4 +139,57 @@ export declare function assertApprovalBaseUrl(value: string): string;
  */
 export declare function runHostedApproval(opts: HostedApprovalOptions): Promise<PurchaseAssurance & {
     mintToken?: string;
+    validUntil?: number;
 }>;
+/**
+ * A panel-initiated mandate handoff, released by its single-use pickup code.
+ * The context here is SERVER truth (an owner-authenticated panel session parked
+ * it, and the code is the credential that releases it) — the runner had no part
+ * in registering it, so unlike {@link runHostedApproval} the fields are
+ * returned for the caller to act on rather than compared against a local run.
+ * What IS verified here is the binding: the entry must be a budget approval
+ * minted for exactly THIS runtime's request key and THIS device's card token.
+ */
+export type MandatePickupClaim = {
+    /** Null only when {@link assuranceExempt} — a code-verified card runs no ceremony. */
+    assuranceData: unknown;
+    assuranceExempt: boolean;
+    mintToken: string;
+    /** Unix seconds — the mandate lapse the owner approved in the panel. */
+    validUntil: number;
+    /** Decimal ceiling string exactly as approved (the context's `amount`). */
+    ceiling: string;
+    currency: string;
+    maxDraws: number;
+    perTransaction?: string;
+    merchant: {
+        name: string;
+        url: string;
+        countryCode: string;
+    };
+};
+export type ClaimMandatePickupOptions = {
+    /** The enrollment web deployment origin (apps/web). */
+    baseUrl: string;
+    /** Single-use pickup code (the approval verifier) the owner handed over. */
+    pickupCode: string;
+    /** This runtime's exact current request-key JKT — the only key the code may fund. */
+    agentJkt: string;
+    /**
+     * The agent handoff this runtime just redeemed, when the code came from one.
+     * A budget minted in the Add-agent dialog exists before the agent does, so it
+     * pins the handoff rather than a key; this is the value that pin is compared
+     * against. Absent for the panel flow, whose budgets pin a key instead.
+     */
+    expectedHandoffId?: string;
+    /** The card token id this runtime's card authority points at. */
+    tokenId: string;
+    fetchImpl?: typeof fetch;
+    /** Injectable for tests — never wall-clock-sleep in a unit test. */
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    /** Bounded retries for transient 429/5xx; the claim itself is single-use. */
+    attempts?: number;
+    retryDelayMs?: number;
+};
+export declare function claimMandatePickup(opts: ClaimMandatePickupOptions): Promise<MandatePickupClaim>;

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,16 +128,36 @@ 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, agentJkt, 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 canonicalJkt = typeof agentJkt === 'string' && /^[A-Za-z0-9_-]{43}$/.test(agentJkt);
+    if (!canonicalJkt) {
+        throw new Error('a budget approval requires the exact current agent request-key JKT');
+    }
     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;
-    const timeoutError = () => new Error(`no passkey approval within ${Math.round(timeoutMs / 1000)}s — ` +
+    // Verification-neutral: what the page asks the human for is a per-card
+    // property (passkey ceremony, issuer one-time code, or nothing beyond the
+    // signed-in approval) that this runner never learns. Naming a passkey here
+    // told operators on code-verified cards to wait for a device prompt that was
+    // never coming, and then blamed the timeout on the step they never saw.
+    const timeoutError = () => new Error(`no approval within ${Math.round(timeoutMs / 1000)}s — ` +
         'the checkout was cancelled; run again to retry');
     // Bound EVERY request by the remaining deadline: race the fetch against the
     // (injectable) sleep and abort the request when the deadline wins, so a
@@ -107,6 +191,11 @@ export async function runHostedApproval(opts) {
                 amount: target.transactionAmount,
                 currency,
                 ...(consumerEmail ? { consumerEmail } : {}),
+                budget: true,
+                agentJkt,
+                maxDraws,
+                ...(perTransaction !== undefined ? { perTransaction } : {}),
+                ...(intentSanitized !== undefined ? { intent: intentSanitized } : {}),
             },
         }),
     });
@@ -115,57 +204,293 @@ 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}`);
+    log(`budget recipient request key: ${agentJkt.slice(0, 8)}…${agentJkt.slice(-6)}`);
     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') {
+                    // A passkey-exempt token ('otp' cardholder ID&V / 'none') runs no
+                    // ceremony and produces no assurance — the approval server marks the
+                    // claim explicitly (derived from the owner's verified card record at
+                    // complete-time). Only that marker excuses a null assuranceData; a
+                    // silently dropped payload still fails exactly as before.
+                    const assuranceExempt = doc.cardholderVerification === 'otp' || doc.cardholderVerification === 'none';
+                    if ((doc.assuranceData === undefined || doc.assuranceData === null) && !assuranceExempt) {
+                        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 did not complete OUR registration. Compare the
+                    // boolean explicitly (it is not a string, so it lives outside the
+                    // string-map loop above).
+                    if (doc.context?.budget !== true) {
+                        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');
                     }
+                    if (doc.context?.agentJkt !== agentJkt) {
+                        throw new Error('hosted approval context mismatch on agentJkt — the approval was not for this ' +
+                            'exact request key; run the checkout again for a fresh link');
+                    }
+                    // The 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. Compare exactly,
+                    // the omitted/undefined case included, so a silently dropped value is
+                    // caught the same as a mutated one.
+                    if (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 (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');
+                    }
+                    if (!Number.isSafeInteger(doc.validUntil) ||
+                        doc.validUntil <= Math.floor(now() / 1000)) {
+                        throw new Error('hosted budget approval completed without a valid future expiry');
+                    }
+                    log(assuranceExempt
+                        ? 'approval received from the hosted page (code-verified card, no passkey).'
+                        : 'approval received from the hosted page (passkey-verified card).');
+                    return {
+                        ...assuranceFromCeremony(target, doc.assuranceData ?? null),
+                        ...(assuranceExempt ? { assuranceExempt: true } : {}),
+                        ...(typeof doc.mintToken === 'string' && doc.mintToken
+                            ? { mintToken: doc.mintToken }
+                            : {}),
+                        validUntil: doc.validUntil,
+                    };
                 }
-                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.
+            }
+            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');
             }
-            // status 'pending' — the operator is still signing in / tapping.
+            // 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);
+        }
+    }
+    finally {
+        clearInterval(keepAlive);
+    }
+}
+const PICKUP_CODE_SHAPE = /^[A-Za-z0-9_-]{43}$/;
+const DECIMAL_AMOUNT_SHAPE = /^[0-9]+(\.[0-9]{1,2})?$/;
+function pickupMismatch(field, detail) {
+    return new Error(`mandate pickup code mismatch on ${field} — ${detail}. Ask the owner to start a fresh ` +
+        'mandate in the panel for this agent');
+}
+export async function claimMandatePickup(opts) {
+    const { baseUrl, pickupCode, agentJkt, expectedHandoffId, tokenId, fetchImpl = fetch, sleep = defaultSleep, now = Date.now, attempts = 3, retryDelayMs = 1_000, } = opts;
+    // Both producers (runHostedApproval and the panel initiate route) mint the
+    // verifier as randomBytes(32).base64url = 43 chars; refuse anything else
+    // before it travels.
+    if (!PICKUP_CODE_SHAPE.test(pickupCode)) {
+        throw new Error('that does not look like a mandate pickup code (43 URL-safe characters) — ' +
+            'paste the code exactly as the panel displayed it');
+    }
+    if (!/^[A-Za-z0-9_-]{43}$/.test(agentJkt)) {
+        throw new Error('claiming a mandate pickup requires the exact current agent request-key JKT');
+    }
+    if (!tokenId.trim()) {
+        throw new Error('claiming a mandate pickup requires the provisioned card token id');
+    }
+    const base = stripTrailingSlashes(assertApprovalBaseUrl(baseUrl));
+    let res = null;
+    for (let attempt = 1;; attempt++) {
+        res = await fetchImpl(`${base}/api/vgs/agent-approval/claim`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ verifier: pickupCode }),
+        });
+        // 4xx other than 404/429 is a terminal shape/validation answer; 404 is the
+        // single-use/TTL answer. Only rate-limit and 5xx are worth a bounded retry —
+        // the entry is durable until claimed or expired.
+        if (res.ok || res.status === 404 || (res.status < 500 && res.status !== 429))
+            break;
+        if (attempt >= attempts)
+            break;
+        await sleep(retryDelayMs);
+    }
+    if (res.status === 404) {
+        throw new Error('this pickup code has expired or was already used — codes are single-use and live ' +
+            'about 10 minutes. Ask the owner to start a fresh mandate in the panel');
+    }
+    if (!res.ok) {
+        const body = (await res.json().catch(() => ({})));
+        throw new Error(`could not redeem the pickup code (${res.status})` + (body.error ? `: ${body.error}` : ''));
+    }
+    const doc = (await res.json().catch(() => null));
+    if (doc?.status === 'declined')
+        throw new HostedApprovalDeclinedError();
+    if (doc?.status !== 'completed') {
+        // A panel-issued pickup code is parked already-completed (the owner approved
+        // in the panel before the code existed). `pending` means this verifier came
+        // from an in-flight runner ceremony, not a mandate handoff — redeeming it
+        // here would race the runner that owns it.
+        throw new Error('this code is not a completed mandate handoff — it looks like an in-progress approval. ' +
+            'Use the pickup code the panel displayed after the owner approved the mandate');
+    }
+    const ctx = doc.context ?? {};
+    if (ctx.budget !== true) {
+        throw pickupMismatch('budget', 'the approval is a one-purchase approval, not a spend budget');
+    }
+    // A budget names exactly ONE agent, by one of two pins.
+    //
+    //  - `agentJkt` — the panel flow: the owner picked an agent that already
+    //    existed, so the approval names its key and this runtime compares keys.
+    //  - `handoffId` — the Add-agent dialog: the budget was minted before any
+    //    agent existed, so it names the handoff the agent would go on to redeem.
+    //    This runtime redeemed one moments ago and knows which, so the comparison
+    //    is just as concrete — it is simply a different identifier.
+    //
+    // EXACTLY one, enforced before either is compared. Neither pin is an unbound
+    // budget, and "no pin" must never be the quiet way past a binding check.
+    // BOTH pins is worse: it names two agents, and checking whichever one happens
+    // to match would let the weaker claim decide. The signer refuses to mint such
+    // a context and the approval store refuses to hold one, so this is the third
+    // and last place to say it — the one that runs on material already in hand.
+    const hasHandoffPin = typeof ctx.handoffId === 'string';
+    const hasAgentPin = typeof ctx.agentJkt === 'string';
+    if (hasHandoffPin === hasAgentPin) {
+        throw pickupMismatch('agentJkt', hasHandoffPin
+            ? 'this budget names two different agents at once — it binds to a handoff or to a key, never both'
+            : 'this budget names no agent at all, so nothing can prove it belongs to this runtime');
+    }
+    if (hasHandoffPin) {
+        if (!expectedHandoffId || ctx.handoffId !== expectedHandoffId) {
+            throw pickupMismatch('handoffId', 'this budget belongs to a different agent handoff than the one this runtime just claimed');
         }
-        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 (ctx.agentJkt !== agentJkt) {
+        throw pickupMismatch('agentJkt', 'the owner approved this mandate for a different agent key than this runtime holds');
+    }
+    if (ctx.tokenId !== tokenId) {
+        throw pickupMismatch('tokenId', "the mandate was approved against a different enrolled card than this runtime's card " +
+            'authority points at (the owner may have re-enrolled a card — re-run grant-card first)');
+    }
+    const ceiling = ctx.amount;
+    if (typeof ceiling !== 'string' || !DECIMAL_AMOUNT_SHAPE.test(ceiling) || Number(ceiling) <= 0) {
+        throw pickupMismatch('amount', 'the approved ceiling is missing or malformed');
+    }
+    const currency = ctx.currency;
+    if (typeof currency !== 'string' || !/^[A-Z]{3}$/.test(currency)) {
+        throw pickupMismatch('currency', 'the approved currency is missing or malformed');
+    }
+    const maxDraws = ctx.maxDraws;
+    if (!Number.isSafeInteger(maxDraws) || maxDraws < 1) {
+        throw pickupMismatch('maxDraws', 'the approved purchase count is missing or malformed');
+    }
+    const perTransaction = ctx.perTransaction;
+    if (perTransaction !== undefined) {
+        if (typeof perTransaction !== 'string' ||
+            !DECIMAL_AMOUNT_SHAPE.test(perTransaction) ||
+            Number(perTransaction) <= 0 ||
+            Number(perTransaction) > Number(ceiling)) {
+            throw pickupMismatch('perTransaction', 'the approved per-purchase cap is malformed');
         }
-        // Any other status (429 rate bucket, transient 5xx) polls through.
-        if (now() >= deadline)
-            throw timeoutError();
-        await sleep(pollIntervalMs);
     }
+    const merchantName = ctx.merchantName;
+    const merchantUrl = ctx.merchantUrl;
+    const merchantCountryCode = ctx.merchantCountryCode;
+    if (typeof merchantName !== 'string' ||
+        !merchantName.trim() ||
+        typeof merchantUrl !== 'string' ||
+        !merchantUrl.trim() ||
+        typeof merchantCountryCode !== 'string' ||
+        !merchantCountryCode.trim()) {
+        throw pickupMismatch('merchant', 'the approved budget target is missing or malformed');
+    }
+    if (typeof doc.mintToken !== 'string' || !doc.mintToken) {
+        throw new Error('the mandate handoff carried no mint token — the deployment that parked it ran the ' +
+            'dev-auth stub, which cannot mint draw authority. Re-initiate against a real deployment');
+    }
+    if (!Number.isSafeInteger(doc.validUntil) ||
+        doc.validUntil <= Math.floor(now() / 1000)) {
+        throw new Error('the mandate handoff carried no valid future expiry — ask the owner to re-initiate');
+    }
+    // Same exemption contract as runHostedApproval: only the server's explicit
+    // code-verified-card marker excuses a missing assurance payload.
+    const assuranceExempt = doc.cardholderVerification === 'otp' || doc.cardholderVerification === 'none';
+    if ((doc.assuranceData === undefined || doc.assuranceData === null) && !assuranceExempt) {
+        throw new Error('the mandate handoff completed but carried no assuranceData');
+    }
+    return {
+        assuranceData: doc.assuranceData ?? null,
+        assuranceExempt,
+        mintToken: doc.mintToken,
+        validUntil: doc.validUntil,
+        ceiling,
+        currency,
+        maxDraws: maxDraws,
+        ...(perTransaction !== undefined ? { perTransaction: perTransaction } : {}),
+        merchant: {
+            name: merchantName,
+            url: merchantUrl,
+            countryCode: merchantCountryCode,
+        },
+    };
 }