@visa/cli 4.1.0-rc.29 → 4.1.0-rc.291

package/README.md

@@ -1,21 +1,23 @@
 # @visa/cli
 
-Visa CLI v4 gives an AI agent a **Visa Verified Agent** identity and a scoped,
-human-capped signer for a Turnkey-managed wallet. Agents discover paid
-x402/MPP services and pay with USDC over MCP (Model Context Protocol); the
-human approves the limits and every payment is checked against on-device policy
-before anything is signed. Larger browser purchases use a separately approved
-VIC credential and card mandate.
-
-The v4 flow has three parts, always in this order:
-
-1. **Identity** — the human enrolls in the browser (email or Google sign-in, card on file, bank verification) and mints a `.visa` name bound to the agent.
-2. **Delegation** — a pairing ceremony gives the runtime a scoped, revocable
-   Turnkey signer with human-approved per-transaction and daily caps. The
-   runtime never receives the human wallet's root key.
-3. **Payment** — `find → inspect → pay` handles x402/MPP purchases with gasless
-   USDC and explicit maxima; `checkout` / `mandate` handles larger VIC browser
-   purchases.
+Visa CLI v4 pairs an AI runtime to a human-approved **Visa agent identity**.
+The pairing ceremony creates one stable agent ID and activates one
+runtime-custodied Ed25519 identity key. It does not create payment authority,
+a mailbox, or a `.visa` name. New paired agents request publication of their
+public key to the TAP directory by default; owners can durably remove it with
+`visa agent tap-opt-out <agent-id>`.
+
+The product flow has three explicit parts:
+
+1. **Identity** — `setup_start` (or `visa setup start`) opens ONE browser
+   review that covers the exact runtime, its public-key fingerprint, and every
+   requested rail in a single owner approval. The private key stays on the
+   runtime device. The older identity-only doors remain callable for an
+   already-started integration but are hidden from normal discovery.
+2. **Capabilities** — payment methods, spend grants, email and directory
+   bindings are configured separately, each with its own human-visible terms.
+3. **Use** — when a separately provisioned capability exists, the wallet and
+   VIC commands enforce that capability's own policy and approval boundary.
 
 ## Install
 
@@ -31,7 +33,17 @@ Windows PowerShell:
 iwr -useb https://app.visacli.sh/install.ps1 | iex
 ```
 
-Node.js 18+ is required. macOS, Windows, and Linux are supported for the v4 wallet flow.
+Node.js 20+ is required. macOS, Windows, and Linux are supported for the v4 wallet flow.
+
+### Managed runtime convergence
+
+The RC package also installs `visa-runtime-converge` for supervisor-owned
+OpenClaw/Hermes/Telegram deployments. A scheduled invocation resolves the
+preview server's recommended exact RC, stages and integrity-checks it, restarts
+through the configured supervisor, verifies the loaded version/environment, and
+rolls back a failed activation. It never updates an interactive owner-managed
+installation. Configuration and readiness contracts are documented in
+[`packages/visa-cli-openclaw/RUNTIMES.md`](https://github.com/Visa-Crypto-Labs/Visa-mono/blob/staging/packages/visa-cli-openclaw/RUNTIMES.md).
 
 ## MCP setup
 
@@ -65,44 +77,170 @@ args = ["<npm root -g>/@visa/cli/dist/mcp-server/index.js"]
 
 There is no CLI subcommand for starting the MCP server directly — the MCP server is the bundled `dist/mcp-server/index.js` entrypoint, which `visa-cli connect <client>` registers for you.
 
-## Enroll a Verified Agent
+### UCP commerce bundle
+
+Install the Visa pairing skill, discovery-first UCP shopping skill, bounded
+Shopify checkout skill, and both Visa and Shopify UCP MCP entries in one step:
+
+```bash
+visa agent skill --commerce --runtime codex
+# runtimes with writable MCP config: codex, openclaw, hermes
+
+# Inspect the installed local bundle without changing skills or MCP config:
+visa agent skill --commerce --runtime codex --check
+```
+
+The shopping skill turns broad requests into a short seller/variant list and
+requires an exact selection plus an all-in ceiling before checkout. The pinned
+Shopify UCP server requires Node.js 22 or newer. A successful run
+reports both MCP entries as mounted or already mounted; restart or reload the
+agent before using the new tools. The installer never performs discovery or a
+checkout itself. The install-only command exits successfully after writing the
+bundle, but reports `commerceReady: false` / `ucp_check_required` until the
+explicit `--check` gate passes. `commerceReady` is a compatibility alias for
+local bundle readiness only; it never proves that a merchant purchase can be
+completed. The JSON result keeps `purchase.ready: false` until a separate live
+checkout preflight is performed.
+
+Checked readiness is read-only: missing or modified skills and missing,
+conflicting, or malformed MCP entries are reported without installing or
+rewriting anything. It parses the active local profile and its pinned Shopify
+profile contract directly from disk, without starting `npx`, and reports the
+exact profile initialization command if local state is missing or invalid. It
+also refuses to claim local natural-language shopping readiness when a
+top-level `ucp` or `shop` skill with a `SKILL.md` is present in the same runtime
+directory. The installer reports those paths but never deletes or disables
+user-owned skills.
+
+If the selected runtime already has a non-equivalent `shopify-ucp` entry, the
+command fails without changing that entry or its environment, authentication,
+timeout, or filtering fields. Rename or remove the existing entry explicitly
+before rerunning; the installer does not silently replace or downgrade it.
+
+### MCP 2026-07-28 compatibility
+
+This release speaks the modern, stateless MCP `2026-07-28` protocol over stdio and deliberately rejects the legacy `initialize` handshake. Your client must support per-request protocol envelopes and `server/discover`; update the client before upgrading Visa CLI if it still sends MCP `2025-*` traffic. `visa-cli connect` can write configuration for every listed client, but configuration support does not imply that an older installed client understands the new wire revision.
+
+The server now exposes:
+
+- JSON Schema 2020-12 tool inputs and outputs, `structuredContent`, namespaced result metadata, cache hints, and receipt `resource_link` blocks.
+- Resources for agent status, capabilities, recent activity, and canonical `visa://receipt/{transactionId}` receipts.
+- Prompts for pairing/funding, spend inspection, safe purchasing, and receipt reconciliation, with completion support.
+- The `io.modelcontextprotocol/tasks` extension for durable, pollable `pay_merchant` approval work. Task lifecycle is owner-scoped in the auth service; an MCP-process restart fails an in-flight checkout closed instead of replaying it.
+- Multi-round-trip `input_required` URL elicitation with HMAC-protected, client-bound request state when the client supports URL elicitation but not Tasks.
+- The `io.modelcontextprotocol/ui` Visa Control Center MCP App at `ui://visa/control-center`.
+
+Visa sidebands no longer pollute business JSON. Clients receive keys such as `io.visa/visa-receipt` and `io.visa/update-available` in result `_meta`.
+
+## Setup doors
+
+There is one blessed door for each transition. Recovery commands are kept
+discoverable only where a shipped flow prints them; legacy starts remain callable
+for compatibility but do not appear in normal CLI or MCP discovery.
+
+| Transition | Blessed door | Status |
+|---|---|---|
+| New agent from an AI runtime or terminal | `setup_start` / `visa setup start` | Canonical: identity and requested rails on one review page |
+| Agent already created in Console | `agent_handoff_claim` / `visa agent handoff-claim <code>` | Canonical Console handoff |
+| Existing owner account on this device | `agent_login` / `visa agent login` | Canonical sign-in |
+| Resume the canonical setup after restart | `setup_status`, then `setup_resume` / `visa setup status`, then `visa setup open` | Canonical recovery |
+| Finish an already-started legacy pairing | `enroll_agent` action `claim` / `visa agent enroll-claim`, `claim`, or `pairing-resume` as printed | Recovery compatibility only |
+| Resume a paused agent | `visa agent resume <agent-id>` | Live lifecycle control, not enrollment |
+| Start an identity-only legacy pairing | `enroll_agent` / `visa agent enroll`, `pair`, `create`, `verify` | Hidden compatibility; do not start here |
+
+## Pair an agent identity
+
+For a NEW agent, call **`setup_start`** with the name the human chooses: one
+resumable setup covers identity plus every requested rail in a single owner
+approval on one review page, and `setup_status` / `setup_resume` carry it
+across restarts. From a terminal, `visa setup start "<name>"` begins the same
+operation.
+
+For a wallet setup, `completed` on the server is necessary but not sufficient
+for the runtime to report ready. `setup_status` first verifies the exact-agent
+local signing path used by wallet preflight and payments; managed runtimes make
+one bounded recovery attempt. Until that evidence is readable, the result is
+`wallet_runtime_not_ready`, no payment is attempted, and the setup record stays
+available for a later resume.
+
+The identity-only legacy handler remains callable for an existing integration or
+an already-started ceremony, but it is deliberately absent from normal discovery.
+Do not start a new agent there.
+
+```bash
+visa setup start "Name"    # one review page, one approval, every rail
+visa agent list
+visa agent show <agent-id>
+```
+
+The advanced `create` → `claim` → `verify` → `pairing-resume` commands are the
+split-device choreography of this same v2 ceremony, not a second enrollment
+system. The review shows the runtime, context, stable agent ID, full public-key
+fingerprint, and expiry. It grants identity only; no spend limits or instruments
+are implied.
 
-Enrollment starts from the agent, not the terminal: the agent calls the **`enroll_agent`** MCP tool, which opens the enrollment page in the browser and prints a 6-character confirmation code in the terminal. The human signs in with **email or Google**, chooses the agent's `.visa` name, adds a card, completes the bank's verification step, and types the confirmation code. When the browser reports the credential was sent to the CLI, the agent calls `enroll_agent` with `{"action":"claim"}` to park the credential on the device.
+On macOS and Linux, the private identity key is stored under
+`~/.visa-cli/agents` in an owner-only directory with file mode `0600`. It is
+currently an exportable local file: copying it transfers identity proof, and
+losing it blocks new proofs because same-agent key recovery is not yet
+available. Protocol-v2 identity pairing fails closed on Windows until the CLI
+can apply and verify an owner-only Windows ACL. The pairing link contains no
+credential or private key.
 
-Only enter a confirmation code you watched your own terminal print. Enrollment
-must begin with `enroll_agent` and present Turnkey email or Google sign-in.
+## Recover an existing account session
 
-## Connect an agent runtime (pairing)
+`visa agent login` opens the Turnkey-first web sign-in for an existing v4
+account, then `visa agent login-claim` stores the returned account session in
+the OS keychain. `--wait` keeps the first command polling for the full
+15-minute browser window.
 
-Enrollment mints identity; **pairing is what lets a runtime sign payments.**
+```bash
+visa agent login          # sign in and display the terminal confirmation code
+visa agent login-claim    # resume pickup after returning from the browser
+```
+
+This is account-session recovery, not agent pairing. It does not create or
+replace an identity key, delegate a wallet, select a card, set a budget, or
+grant spend authority. The pending PKCE verifier is kept under
+`~/.visa-cli/session-recovery/` in owner-only local state and is pinned to the
+exact web origin that started the flow.
+Session recovery currently fails closed on Windows until the CLI can apply and
+verify an owner-only ACL for this pending verifier.
+
+## Wallet capability: grant, caps, then funding
+
+Pairing never creates or repairs payment authority — the owner delegates it in
+a separate grant ceremony, and re-pairing is not a substitute:
 
 ```bash
-visa agent create                                                # in the human's terminal — prints the pairing id
-visa agent claim <pairing-id> --runtime <name> --context "<one-line purpose>"
-visa agent verify <pairing-id> <code>                            # verifies the channel, opens the authorization page
-visa agent list                                                  # shows the activated runtime
+visa agent login                                          # owner account session, once
+visa agent grant-wallet <agent-id> --ceiling 25 --per-transaction 1 --wait
 ```
 
-The browser authorization is the human gate: it shows the runtime and context and sets the **per-transaction and daily spend caps**. If the runtime lost its network response, `visa agent resume <pairing-id>` reprints the code and resumes delivery; `visa agent cancel [pairing-id]` abandons an unapproved request. Pairing credentials are stored on the agent machine with mode `0600`; the pairing link contains no credential.
+The owner approves once in the browser; the runtime polls to activation and
+receives a delegated, capped, revocable signer (it can never mint one itself).
+`visa agent pause <agent-id>` temporarily blocks new Visa CLI card and wallet payments at the canonical authority service (mandates remain intact; resume with `visa agent resume <agent-id>`). `visa agent revoke <agent-id>` withdraws the current server grant without touching identity; provider-credential removal is a separate lifecycle.
 
-## Caps, then funding — strict order
+With a wallet delegated, set caps before funding:
 
 ```bash
-visa wallet limits --per-transaction 0.25 --daily 2.00   # BEFORE any funds arrive
-visa wallet show                                          # address, network, policy
-visa wallet fund                                          # funding instructions
+visa wallet limits --agent <agent-id> --per-transaction 0.25 --daily 2.00
+visa wallet show --agent <agent-id>                       # address, network, policy
+visa wallet fund --agent <agent-id>                       # funding instructions
 ```
 
 Fund the wallet with USDC only after limits are set. Payments are gasless — no ETH is ever needed. Mainnet (Base) is the production default; set `VISA_V4_NETWORK=base-sepolia` for testnet, where `visa wallet fund` points at the faucet.
 
+Updating wallet limits preserves the active session budget window and its spent exposure. Reapplying the same limits is a no-op; `wallet limits` does not provide an implicit session-spend reset.
+
 ## Discover and pay
 
 ```bash
 visa find "current weather by city" --max 0.10   # discovery; spends nothing
 visa inspect <listing-id>                        # fetches the live 402 challenge; spends nothing
-visa pay <listing-id> --max 0.05                 # policy check → sign → settle
-visa activity                                    # recent payments
-visa receipt <receipt-id>                        # journaled proof with on-chain tx
+visa pay <listing-id> --agent <agent-id> --max 0.05 # policy check → sign → settle
+visa activity --agent <agent-id>                    # recent payments
+visa receipt <receipt-id> --agent <agent-id>        # journaled proof with on-chain tx
 
 # Advanced direct-URL mode uses the same probe, policy, and receipt path.
 visa inspect --url https://provider.example/paid
@@ -116,12 +254,25 @@ owned by `apps/mpp`, and VIC uses the checkout/mandate surface. Unsupported
 rails are refused before signing. The wallet exposes no agent key-export
 command.
 
+Each wallet-enabled agent has an isolated Turnkey credential, policy, journal,
+receipts, and paid-response directory. `--agent` / the MCP `agent` field may be
+omitted while exactly one wallet authority exists; with multiple authorities it
+is required so the CLI never guesses which agent can spend.
+
 ## MCP tools (v4 surface)
 
 | Tool | Description |
 |------|-------------|
-| `enroll_agent` | Two-step Verified Agent enrollment: default opens the browser flow with a hand-off challenge; `{"action":"claim"}` stores the enrollment credential on this device |
-| `wallet_status` | Wallet address, network, policy, and pairing state |
+| `agent_capabilities` | Derived live capability map (identity, wallet, card, mail, tap, subway) with upgrade paths |
+| `setup_agent` | Next-step resolver for the wallet rail: `{state, nextAction, blockedBy, steps}`; never spends |
+| `agent_login` | Start/claim the owner's device account session (required before a grant) |
+| `setup_start` | Start ONE resumable setup (identity + rails) in a single human approval; returns the review link and this device's half of the compare code |
+| `setup_status` | Read the server's one `nextAction` and polling cadence; terminal wallet results additionally require exact-agent local signing evidence before reporting ready |
+| `setup_resume` | Put the review link and compare code back in front of the human after a restart or a closed tab |
+| `setup_cancel` | Abandon a setup still waiting on the human; never undoes an approval |
+| `agent_connect` | Initiate an owner-approved spending grant for a paired agent |
+| `agent_connect_poll` | Poll that grant ceremony to activation (returns caps, and the funding address for wallet) |
+| `wallet_status` | Delegated wallet address, network, and policy state |
 | `wallet_policy_set` | Set per-transaction / daily caps (with human approval) |
 | `wallet_discover` | Sweep x402 directories for services, with live re-probing |
 | `wallet_probe` | Fetch a service's live 402 challenge without paying |
@@ -129,6 +280,7 @@ command.
 | `wallet_directory_pay` | Directory find + pay in one call, same policy path |
 | `wallet_history` | Journaled payment receipts |
 | `wallet_fund` | Funding instructions for the wallet address |
+| `checkout_merchants` | Read-only: merchants where your card has completed real checkouts, from this device's receipts |
 | `get_status` | Account and wallet state summary |
 | `feedback` | Submit feedback on a tool result |
 | `reset` | Clear local auth state and credentials |
@@ -163,11 +315,19 @@ visa pay <listing-id> --max <usd>
 visa activity
 visa receipt <receipt-id>
 
-# Human-approved agent runtime pairing
+# Primary same-machine setup
+visa setup start "Name" --rails card,wallet
+visa setup status
+
+# Existing-account session recovery (separate from identity pairing)
+visa agent login
+visa agent login-claim
+
+# Recovery compatibility for a legacy split-device ceremony already in flight
 visa agent create
 visa agent claim <pairing-id> --runtime <name> --context "<purpose>"
 visa agent verify <pairing-id> <code>
-visa agent resume <pairing-id>
+visa agent pairing-resume <pairing-id>
 visa agent cancel [pairing-id]
 visa agent list
 
@@ -200,14 +360,19 @@ visa-cli feedback                   # submit feedback
 
 | Path | Contents |
 |------|----------|
-| `~/.visa-mcp/agent-credential.json` | Verified Agent enrollment credential (mode 0600) |
-| `~/.visa-cli/` | Pairing / delegated signer credentials (mode 0600) |
-| `~/.visa-v4/policy.json` | Wallet spend policy — never edit by hand; use `visa wallet limits` |
+| `~/.visa-cli/pairings/` | Pending ceremony verifier or runtime identity key (owner-only mode 0600 on macOS/Linux; v2 pairing currently disabled on Windows) |
+| `~/.visa-cli/agents/` | Activated agent identity, runtime private key, and signed activation credentials (owner-only mode 0600 on macOS/Linux; v2 pairing currently disabled on Windows) |
+| `~/.visa-cli/session-recovery/` | Pending login-only PKCE verifier and pinned web origin (owner-only mode 0600 on macOS/Linux) |
+| `~/.visa-cli/removed-agents/` | Records of agents deleted on the server, kept 30 days then dropped. Written automatically; nothing reads it |
+| `~/.visa-mcp/agent-credential.json` | Legacy checkout-credential compatibility record (mode 0600) |
+| `~/.visa-v4/agents/<agentId>/` | Per-agent Turnkey credential, spend policy, reservation journal, receipts, and paid responses — never edit by hand |
 
 ## Troubleshooting
 
-**Wallet commands report pairing is required**
-Payments on a production network require the paired delegated credential — complete enrollment and pairing first. There is no local fallback wallet on mainnet, by design.
+**Wallet commands report that payment setup is required**
+Identity pairing deliberately grants no payment authority. Complete the
+separate wallet/instrument and spend-policy setup when available; pairing again
+will not upgrade an identity into a signer.
 
 **`policy refused` from `pay`**
 A cap or allowlist said no; nothing was signed. Raise caps only via `visa wallet limits` with the human's approval.
@@ -215,12 +380,111 @@ A cap or allowlist said no; nothing was signed. Raise caps only via `visa wallet
 **`expected 402 from <url>`**
 That URL isn't payment-gated — probe the service's actual paid route (`wallet_probe` / `visa find`).
 
-**Pairing ended `expired` or `cancelled`**
-The ceremony timed out — re-run `visa agent create` and claim the new pairing id.
+**Setup ended `expired` or `cancelled`**
+The ceremony timed out — restart with `visa setup start "Name"`, then follow
+`visa setup status` until it reports the next action.
 
 **Tools don't appear in the AI client**
 Restart the client or reconnect the MCP server (`/mcp` → `visa-cli` → reconnect in Claude Code). Re-run `visa-cli connect <client>` to rewrite the config.
 
+**Branching on failures from `--format json`**
+Every failure envelope carries `code`, `kind`, `fix`, and `nextAction`. Branch on
+`code` (stable, append-only) and `kind` (`caller` = fix it yourself and retry;
+`platform` = stop and escalate to a human), never on the English `error` text.
+Deterministic preconditions always resolve to a specific code:
+
+| Condition | `code` | `kind` |
+|-----------|--------|--------|
+| Not logged in (`find`, `activity`, `receipt`) | `session_required` | `caller` |
+| No wallet grant on this runtime (`wallet show\|fund\|limits`, `pay`, `--local` reads) | `wallet_credential_required` | `platform` |
+| Wallet grant approved but not fully delivered (`pay`) | `wallet_delivery_required` | `platform` |
+| Local identity record missing for the selected agent (`pay`) | `identity_required` | `caller` |
+| Identity root migrated; direct signing retired (`pay`) | `universal_required_managed_only` | `platform` |
+| Managed wallet limits are owner-set (`wallet limits` with caps) | `managed_limits_owner_controlled` | `platform` |
+| Listing is not x402 (`pay <listing-id>`) | `invalid_argument` | `caller` |
+| Activity id not found or not attributable (`receipt`) | `activity_entry_not_found` | `caller` |
+
+`unspecified_error` (`platform`) is reserved for failures the CLI cannot
+classify and is intentionally kept on two guards: a wallet binding that does not
+match the signed-in owner profile (an integrity refusal, not a caller state),
+and a `wallet limits` change that would broaden policy without the operator's
+`VISA_V4_WALLET_ALLOW_POLICY_RAISE=1`. Both need a human; escalate rather than retry.
+
 ## Monorepo context
 
 Request routing (MCP vs MPP vs web): [docs/agents/ARCHITECTURE.md](../../docs/agents/ARCHITECTURE.md). Branches and deploy: [docs/agents/PIPELINE.md](../../docs/agents/PIPELINE.md). Contributor workflow: [AGENTS.md](../../AGENTS.md), doc index: [docs/agents/README.md](../../docs/agents/README.md).
+
+### Native device TAP lifecycle
+
+`visa agent keychain connect-device --agent <name-or-id>` selects this device for
+identity-only TAP signing after the existing browser owner ceremony verifies its
+certificate, delegation, Gate authorization and native key binding. The selected
+native profile serves actual TAP consumers; unavailable custody or invalid selected
+metadata fails closed. Wallet/card keys and payment authority remain separate.
+
+`--agent` accepts either a locally paired agent or the stable UUID of a protected
+agent created by `visa agent enroll-protected`; the latter has no Auth-paired record
+and resolves its owner root from the independently claimed selection. The device
+ceremonies (`connect-device`, `renew`, `resume`, `revoke --purpose tap`) travel the
+public identity-device relay with native possession proofs, so a missing or expired
+`visa agent login` never blocks them; the owner approval and owner revocation pages
+remain required. Hosted purposes (`card:vic`, `wallet:x402`, hosted `tap`, `subway`)
+still need a locally paired agent and its Auth session.
+
+`visa agent keychain renew --agent <name-or-id> --purpose tap` creates an independently
+addressed successor for the same runtime and opens the owner review page. Both keys
+survive interruption. `visa agent keychain resume --agent <name-or-id>` resumes the
+exact pending operation, including a locked-keychain cleanup retry. `--no-open`
+prints the owner URL. Expired locators require another owner ceremony using the
+preserved successor key. `keychain status` reports the selected profile and local
+renewal phase; it is a local projection, not a live authority check.
+
+Only public certificates/proposals and opaque native handles enter the durable
+renewal journal. Selection changes after verified owner activation. The previous
+handle is deleted only after possession-authenticated protected readback proves
+that exact prior generation retired; uncertain readback preserves it. Native
+custody uses the configured OS store or explicit headless KEK descriptor.
+
+`visa agent keychain revoke --agent <name-or-id> --purpose tap` opens an independent
+owner review for the selected native runtime. The protected owner action stops current
+and pending TAP authority, including an interrupted renewal. Local locks or unreadable
+recovery journals do not prevent opening the owner review. The CLI preserves every known
+handle until exact terminal readback, then deletes keys idempotently; `keychain resume`
+retries locked cleanup. A public revoked selection tombstone prevents legacy TAP fallback.
+After cleanup completes, `connect-device` explicitly enrolls a new runtime.
+
+### Native Subway owner certificates
+
+New `agent keychain renew --purpose subway --advanced` requests keep the Subway
+child key in native custody. Complete the existing offline browser owner certificate
+review and import its response with `--response <file>`. Repeating the response
+command resumes interrupted certification, prior-runtime revocation, or locked-key
+cleanup. An expired unsigned request keeps its native key and produces a fresh
+owner request. `keychain status` reports pending work and the selected native profile.
+
+Register the Subway name again after renewal so its peer key matches the selected
+child. WebSocket messages and direct libp2p Noise authentication use structured
+native signing operations. Invalid, expired, revoked, or unavailable native selection
+fails closed. Existing unpaired mesh usage retains its current behavior.
+
+The public renewal journal preserves both generations until the runtime service
+confirms revocation of the exact previous child. Only then does cleanup remove its
+native handle or isolated legacy Subway key file. `keychain revoke --purpose subway`
+revokes the selected child before deleting its key; repeat it to retry locked cleanup.
+Wallet and card custody are separate.
+
+### Protected managed-wallet rollout
+
+Protected authority onboarding is opt-in with `visa config set wallet.protectedAuthority true` until its deployment is ready. The default retains the existing fresh-enrollment and locally verified legacy managed-wallet path. This setting never downgrades saved protected devices: native pending/active/history records and protected wallet bindings always require protected recovery, including when the authority is unavailable. Existing direct configurations retain their scoped local-credential checks.
+
+A managed reconnect without verifiable local enrollment history requires recovery; restore the saved device records or complete independent owner classification through the protected authority deployment. Auth's execution-mode response alone cannot classify that missing history. No automatic retry through legacy setup occurs after an authority error.
+
+### Fresh protected native agent
+
+An operator must supply the independently trusted HTTPS authority origin. Start from an empty CLI home with:
+
+```sh
+visa agent enroll-protected --authority-url https://YOUR-TRUSTED-AUTHORITY --wait
+```
+
+Enter the terminal code in the existing browser owner ceremony, then approve the native device and its spending limits. Repeat the same command to resume after interruption; use `--no-open` to print links. `--url` selects the browser origin independently. `--auth-url` selects the HTTPS policy transport (default: local Auth configuration); its exact origin is saved with enrollment and cannot change on resume. Signing uses the existing bearer-free policy/slip adapter at that origin, while identity pickup and protected wallet recovery use the independently trusted authority. No Auth login is needed, but the policy transport must be reachable to authorize a new purchase. An unclaimed expired request can be replaced with `--restart`. This path creates a new authority-owned namespace and preserves any existing Auth login profile. It requires the protected authority's CLI-claim migration and direct HTTPS routes to be deployed; an Auth-supplied origin is not a trusted substitute.

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

@@ -5,13 +5,82 @@ import type { Contact, FillResult, FilledField } from '../types.js';
 export interface CheckoutAdapter {
     name: string;
     matches(detected: DetectResult): boolean;
+    prepareContact?: (page: Page, contact: Contact) => Promise<FillResult>;
     fill(page: Page, fields: FieldMap, credential: CardCredential, contact: Contact): Promise<FillResult>;
 }
 export declare function resolveLocator(page: Page, entry: FieldEntry): Locator;
 export declare function scrubFillErrorMessage(message: string, value: string): string;
+/**
+ * A fill failure in a few words, for a message a human reads.
+ *
+ * Playwright's error is a multi-line call log — useful in the evidence file,
+ * unreadable in a refusal message and in the receipt an operator opens a week
+ * later. The refusal names WHICH fields refused; without this it never says
+ * WHY, so diagnosing a merchant we cannot drive means either reproducing it or
+ * reading someone's evidence JSON. Each cause maps to a different fix:
+ *
+ *   not editable      — the input exists but is readonly/disabled at fill time
+ *                       (a custom widget owning the value, or a not-yet-ready
+ *                       form). Typing will not help; the field needs an adapter
+ *                       or a longer wait.
+ *   not a text field  — a non-input element pretending to be one. Needs an
+ *                       adapter that drives the widget.
+ *   not visible /
+ *   detached          — a re-render race. The reveal loop is the lever.
+ *
+ * Input is already scrubbed by scrubFillErrorMessage; this only ever shortens.
+ */
+export declare function summarizeFillFailure(error: string | undefined): string;
+/**
+ * The contact record and the page rarely agree on name shape: the record may
+ * carry fullName while the page wants first/last inputs, or vice versa. Derive
+ * the missing shape so either page can be filled from either record.
+ */
+export declare function contactNameShapes(contact: Contact, cardholderName?: string): {
+    fullName?: string;
+    first?: string;
+    last?: string;
+};
+export declare function fillContactFieldMap(page: Page, fields: FieldMap, contact: Contact, opts?: {
+    fillTimeoutMs?: number;
+    detect?: (page: Page) => Promise<DetectResult>;
+}): Promise<FilledField[]>;
 export declare function fillFieldMap(page: Page, fields: FieldMap, credential: CardCredential, contact: Contact, opts?: {
     fillTimeoutMs?: number;
+    detect?: (page: Page) => Promise<DetectResult>;
 }): Promise<FilledField[]>;
+/**
+ * Re-detect and adopt fresh entries for every card field after the panel is
+ * unfolded. Injected for tests; the executor's own detector is used in
+ * production.
+ */
+export declare function refreshCardGroupFromPage(page: Page, fields: FieldMap, detect?: (page: Page) => Promise<DetectResult>): Promise<string[]>;
+/**
+ * Reveal card fields that a checkout keeps collapsed until a payment method is
+ * chosen.
+ *
+ * `fillFields` skips any entry with `visible === false`, so a card-number input
+ * sitting inside a folded panel is never even attempted — the generic adapter
+ * then reports `ok: false` ("fill incomplete") without having typed anything.
+ * That is the correct default: filling an invisible input is how a credential
+ * gets typed into the wrong place. But a payment-method `<select>` guarding the
+ * card panel is common enough to be worth handling, and the recovery is a
+ * single deterministic interaction rather than a guess.
+ *
+ * We only ever SELECT a card option — never a wallet, bank transfer, or
+ * anything else — and we only act when the card field is already detected but
+ * hidden. If nothing changes, the caller proceeds exactly as before and still
+ * fails closed.
+ *
+ * Mutates `fields.number.visible` on success so the subsequent fill attempts
+ * the field it just revealed.
+ */
+export declare function revealCollapsedCardSection(page: Page, fields: FieldMap, opts?: {
+    timeoutMs?: number;
+}): Promise<{
+    revealed: boolean;
+    via: string | null;
+}>;
 export declare class GenericAdapter implements CheckoutAdapter {
     name: string;
     matches(_detected: DetectResult): boolean;