@visa/cli 4.1.0-rc.237 → 4.1.0-rc.239

package/dist/skills/pair-visa-agent/RUNTIMES.md

@@ -87,14 +87,30 @@ mcp_servers:
       # PATH: /usr/local/bin:/usr/bin:/bin
 ```
 
+### Keep one local-state namespace
+
+The gateway shell and the Visa MCP subprocess must resolve the same `HOME` and
+`VISA_CLI_HOME`. Set that boundary before pairing and keep it stable. Changing
+`VISA_CLI_HOME` later also changes where paired identity and grant records are
+read; it is not a safe way to make an old contact file visible.
+
+For example, with `HOME=/opt/data/home` and no `VISA_CLI_HOME`, identity lives
+under `/opt/data/home/.visa-cli` and checkout contact under
+`/opt/data/home/.visa-mcp`. A profile at `/opt/data/.visa-mcp` belongs to a
+different state namespace. Do not scan, copy, or auto-adopt it: contact files
+contain owner PII. Save the profile explicitly through `checkout_profile` in
+the running MCP process, or run the CLI command with the exact same environment.
+`visa agent preflight --format json` reports the non-secret path and source it
+checked.
+
 ## Runtime setup map
 
-| Runtime       | Setup surface                                                                                                                                                                     |
-| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| OpenClaw      | Install `@visa/visa-cli-openclaw` for the bundled skill. The plugin auto-mounts the Visa MCP server, which serves `setup_start` / `setup_status`.                                  |
+| Runtime       | Setup surface                                                                                                                                                                                                    |
+| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| OpenClaw      | Install `@visa/visa-cli-openclaw` for the bundled skill. The plugin auto-mounts the Visa MCP server, which serves `setup_start` / `setup_status`.                                                                |
 | Hermes        | Run `visa-cli connect hermes`, install the skill with `visa agent skill --runtime hermes` (it resolves the per-profile dir), and use `setup_start`. `hermes claw migrate` can import an existing OpenClaw setup. |
-| Codex         | Run `visa agent skill --runtime codex`. It plants the skill under `~/.codex/skills/` and mounts the Visa MCP server into `~/.codex/config.toml` in the same step.                  |
-| Other runtime | Put `visa` on `PATH`, mount the same MCP server if supported, or use the raw `visa setup start` and `visa setup status` commands as the universal fallback.                        |
+| Codex         | Run `visa agent skill --runtime codex`. It plants the skill under `~/.codex/skills/` and mounts the Visa MCP server into `~/.codex/config.toml` in the same step.                                                |
+| Other runtime | Put `visa` on `PATH`, mount the same MCP server if supported, or use the raw `visa setup start` and `visa setup status` commands as the universal fallback.                                                      |
 
 The skill itself can be installed with `visa agent skill`. Pass `--runtime <name>` or
 `--dir <path>` when auto-detection is not appropriate, then reload the runtime.

package/dist/skills/pair-visa-agent/SKILL.md

@@ -356,7 +356,7 @@ asking them to approve a second time.
 ## Already connected — do NOT connect again
 
 If this device already holds an agent, a fresh setup is not needed and creates a
-*second, separate* agent. Do this instead:
+_second, separate_ agent. Do this instead:
 
 1. **Tell the user plainly:** "This device is already connected as `<name>.visa`." Read
    the name from the response. Start another setup only if they explicitly want a second
@@ -398,7 +398,7 @@ against its **exact `agentId`** — never a name, never "the most recent one":
       shorten, or guess a Visa URL, and never open it yourself.
 - [ ] **The owner approves once** on the v4 agent dashboard, confirming the caps.
 - [ ] **Poll to activation** with `agent_connect_poll` (`{"attachId":"<from
-      agent_connect>"}`) — one bounded poll per call, until
+    agent_connect>"}`) — one bounded poll per call, until
       `{"ok":true,"state":"grant_activated"}`.
 - [ ] **Confirm the rail is live.** Wallet: `wallet_status` / `visa wallet show`
       (`agent_capabilities.wallet.available`). Card: `agent_capabilities.card.available`.
@@ -472,6 +472,13 @@ once card authority exists and `checkout_agent_access` is enabled. Collect every
 from the human before the first review; never infer or invent identity or address data.
 Write the file with mode `0600`.
 
+Create and inspect this profile through the `checkout_profile` MCP tool whenever the
+payment flow runs through MCP. Do not shell `visa agent preflight` as a substitute unless
+the shell has the exact same `HOME` and `VISA_CLI_HOME` as the MCP subprocess. A profile
+found under another root is owner PII, not a migration candidate: never scan, copy, or
+auto-adopt it. If the roots drifted, keep the root holding the paired identity and have the
+owner save the profile again through `checkout_profile` in that runtime.
+
 ```jsonc
 {
   "fullName": "Ada Lovelace",

package/dist/skills/visa-shopify-checkout/SKILL.md

@@ -56,7 +56,17 @@ Preserve the merchant origin, checkout id, continuation, currency, line items, f
 
 For a checkout in `requires_escalation`, call `ucp_checkout_handoff`. It is read-only and should return the exact `pay_merchant` review request. Copy its checkout fields unchanged. Do not claim direct UCP payment-handler support merely because UCP constructed the checkout.
 
-If the UCP status is not accepted by the handoff tool, stop with `unsupported_checkout_state`. Do not reinterpret another state as payable.
+Treat the handoff or reconcile result's typed `route` as the server's routing decision. Render `route.stage`, `route.moneyState`, and the single `route.nextAction` in Telegram or other chat status. Retain the opaque `route.resumePoint` only as transient resumable state; never replace it with a checkout URL, checkout id, credential, token, PII, or raw tool output. Never calculate a different next action from a handler namespace or an advertised profile capability.
+
+Follow the lifecycle exactly:
+
+- `incomplete` / `update_checkout`: update the same checkout;
+- `requires_escalation` / `escalate_continue_url`: proceed only through the validated HTTPS continuation already held in the handoff tool result;
+- `complete_in_progress` / `get_checkout`: poll the same checkout without submitting again;
+- `completed` / `reconcile_checkout`: reconcile the same checkout and Visa receipt;
+- `canceled`, an unknown state, or `blocked`: stop fail-closed.
+
+A profile-only payment handler is advertised but unproven. Even a response-confirmed handler and selected instrument do not authorize `complete_checkout` unless the server has an exact production adapter allowlist; this bundle currently has none, so `native_complete` is unreachable. If the UCP status is not accepted by the handoff tool, stop with `unsupported_checkout_state`. Do not reinterpret another state as payable.
 
 ## Review before payment
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@visa/cli",
-  "version": "4.1.0-rc.237",
+  "version": "4.1.0-rc.239",
   "description": "Visa CLI runtime for stable agent identity and separately authorized payment capabilities",
   "bin": {
     "visa-cli": "./bin/visa-cli.js",

package/server.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.visa-crypto-labs/visa-cli",
-  "version": "4.1.0-rc.237",
+  "version": "4.1.0-rc.239",
   "title": "Visa CLI",
   "description": "Pair a human-approved agent identity, configure payment capabilities separately, and discover and pay x402 services from your AI coding assistant.",
   "websiteUrl": "https://github.com/Visa-Crypto-Labs/Visa-mono/tree/main/packages/cli#readme",
@@ -9,7 +9,7 @@
     {
       "registryType": "npm",
       "identifier": "@visa/cli",
-      "version": "4.1.0-rc.237",
+      "version": "4.1.0-rc.239",
       "transport": {
         "type": "stdio"
       },