@visa/cli 5.0.0-rc.416 → 5.0.0-rc.417

package/README.md

@@ -12,7 +12,7 @@ It speaks the Visa agent API, `/agent/v1`, and nothing else.
 macOS and Linux:
 
 ```bash
-curl -fsSL https://app.visacli.sh/cli | bash
+bash -o pipefail -c 'curl -fsSL https://app.visacli.sh/cli | bash'
 ```
 
 Windows PowerShell:
@@ -23,6 +23,14 @@ iwr -useb https://app.visacli.sh/install.ps1 | iex
 
 Node.js 20+ is required.
 
+Deployment installers save their server with `visa config target <url>`. Later
+shells and MCP processes reuse that target, including after reinstalling the
+CLI. `VISA_AUTH_URL` overrides it for one environment; an unconfigured RC keeps
+its existing preview default. Official servers and local loopback work directly;
+custom origins require `--allow-custom-server`. Saving a target does not sign in
+or approve an agent. Restart the AI app after changing a saved target so its
+running MCP process uses that server for both requests and owner links.
+
 Managed updates certify the installed MCP bundle with `node dist/mcp-server/index.js --self-check`. It emits one JSON build result without opening a transport or running startup work. Restart readiness compares that version and environment with the loaded server; commerce readiness stays false until separately certified.
 
 ## Connect
@@ -37,38 +45,32 @@ agent:
 1. It makes an Ed25519 installation key in this machine's key store (macOS
    Keychain, Windows DPAPI, Linux Secret Service, or a 0600 file on a headless
    host with `VISA_RUNTIME_CUSTODY_PROFILE=headless`).
-2. It starts a setup and opens the owner's approval page. The owner signs in
-   to the Visa Console and approves. The agent connects with no spending limit:
-   its wallet key can sign for the owner and can never spend until the owner
-   sets a limit in the Console. The CLI never sees an owner key.
-3. It claims the approved setup with the installation key. A finite background
-   pickup continues after the terminal or MCP host exits, so approval does not
-   need a second `connect` call. `status` reports pickup progress and fresh
-   Authority truth; connecting does not mean payments or TAP are ready.
-
-Connection is separate from spending:
+2. It starts a setup, sends this computer's name, and opens the owner's
+   approval page. The owner signs in to the Visa Console, sees which app and
+   computer is asking, and presses **Approve**. Approve asks nothing else: the
+   agent starts on **Ask me each time**, and the sheet shows Visa's backstop
+   under Details. The CLI never sees an owner key.
+3. The owner's Approve makes this computer's key live. `visa connect` waits in
+   the foreground and links the approved setup; if it is closed first, the next
+   `visa connect` or MCP tool call links it. Nothing runs in the background.
+   After linking, connect names the Visa account that approved it ("Approved
+   by … Not you? Run visa disconnect."). `status` reports fresh Authority
+   truth; connecting does not mean payments or TAP are ready.
+
+Connect ends on what the agent can do:
 
 ```text
-Connected.
-Next: add funds and set a limit.
+Connected as Claude Code.
+Can spend up to $100 more, asking you each time.
 ```
 
-A funded wallet needs only a limit. Status exposes the current connection and spending step in `connection`.
+or, for an agent connected to earn only, `Can earn.` A remaining spending step (such as adding funds) follows the limit. Status exposes the current connection and spending step in `connection`.
 
-New spending limits start on **Ask me each time**. On a connected computer, the owner can choose **Pay within my budget**, with suggested limits of $25 per payment and $100 in total. App connections ask before each payment.
+Every connect result, and an unfinished setup in status, carries the one connect `status`: a word (`Connected`, `Finishing…`, `Needs you`, `Didn’t finish` or `Visa needs to look`), at most one owner action (`Continue`, `Remove`, `Retry` or `Contact support`) with its link, and a stable `agent` code. The terminal, MCP and Console say the same word.
 
-Before presenting a saved approval link, connect and status read the setup's current server state, including while another process owns pickup. Ended or already approved setups expose no approval URL. Status never claims a setup; unknown server state stays recoverable.
+Limits set at connect start on **Ask me each time**. The owner can change them later in the Console. App connections ask before each payment.
 
-Pickup stays bound to this setup and key. Its bound covers the setup's initial
-expiry plus Authority's one-hour approved completion window (including the
-24-hour emergency setup), with the previous 33-minute minimum and two minutes
-for startup and an in-flight safe point. It exits on completion, refusal,
-disconnect, supersession or its bound. It is not a daemon or restart service.
-OS sleep consumes the saved bound; on wake pickup continues only while time
-remains. A hard stop is not automatically restarted. A locked/unavailable key
-store refuses without a fallback or extra prompt. The original setup remains available
-for recovery on the next invocation. A missing pickup bundle or failed launch
-is reported as interrupted, rather than promising automatic completion.
+Before presenting a saved approval link, connect and status read the setup's current server state. Ended or already approved setups expose no approval URL. Status never claims a setup; unknown server state stays recoverable. A locked or unavailable key store refuses without a fallback or extra prompt, and the original setup stays available on the next invocation.
 
 Reconnecting the same app keeps its agent. Connecting a different app starts
 a separate setup, with its own name, mark, key and limits. Older connections
@@ -86,13 +88,18 @@ wallet account. Agents connected before this update save it on their next
 successful connect or status read. Until then they keep the previous behaviour.
 Replacing the same agent on this computer keeps its saved wallet identity.
 
-Every step resumes. Pickup continues after the terminal closes; if it is interrupted,
-run `visa connect` again to recover the same setup.
+Every step resumes. If the terminal closes before the owner approves, run
+`visa connect` again to recover the same setup.
 `--wait 0` starts the setup and returns; `--no-open` prints the link instead.
+If Visa does not answer, `visa connect` says so at once and exits 1: run it
+again later. A wait for the owner slows down through an outage and keeps the
+same setup.
 
 - **A new key for the same agent** (same limits): `visa connect --replace`.
 - **A setup the owner started in the Console** (including replacing a lost
-  laptop): `visa connect --setup <key>`.
+  laptop): `visa connect --setup <key>`. Where that app is already connected
+  on this computer, this reconnects it and adds nothing; add `--another` to
+  add a second agent of that app here, or to move another agent onto it.
 - **After the owner revokes this computer's agent**: `visa connect` sets up a
   new agent here. Visa's own "removed" answer retires the old agent on this
   computer first (its key stays only while an unsettled purchase may need it).
@@ -103,9 +110,12 @@ run `visa connect` again to recover the same setup.
   Active purchase calls retain their installation credential even before the
   first journal exists. `--force` can forget unsettled purchases after active
   calls finish; disconnect cannot erase a key while a call can still admit or sign.
-  `--all` also cancels unfinished local setups and automatic pickup. If an
+  `--all` also cancels unfinished local setups. If an
   unsettled purchase keeps a connected key, its pending replacement is still cancelled.
 - **Update**: `visa update` (RC stays on `@visa/cli@rc`).
+  When Visa names a newer release for this channel, `status` answers `update`
+  (at most once a day per computer): the agent runs `visa update`, then the owner
+  restarts the app; with `visa-tool` the next call already runs it.
   Updates check a separate release before switching all entry points; interrupted
   downloads keep the previous release usable. Activation rechecks the current release,
   so an overlapping update keeps the active CLI, shell tools and MCP available.
@@ -131,7 +141,7 @@ visa-tool --skill    # the Visa skill: recovery after a rebuilt VM, and the rule
 visa-tool --list     # the server's rules and the tools with their inputs (JSON)
 visa-tool status     # one call: the tool's answer as JSON, exit 1 on a refusal
 visa-tool discover '{"target":"https://…"}'   # the live price, read only: nothing is paid
-visa-tool pay '{"target":"https://…","max":"0.05","request_id":"<new UUID>"}'   # pays at most max
+visa-tool pay '{"target":"https://…","max":"0.05","idempotency_key":"<new UUID>"}'   # pays at most max
 ```
 
 On a computer with no keyring, every command needs
@@ -145,6 +155,8 @@ Console's Muse message.
 
 A delivered answer stays available from `payment_status` during a temporary read outage. Settlement stays unconfirmed until Visa can read the original purchase again.
 
+An outage answer carries `retry_after_seconds` when one was named; wait that long, then repeat the call. A local file that can no longer be read is refused with the step that repairs it.
+
 ## MCP tools
 
 Concurrent calls stay bound to their selected agent for every payment phase;
@@ -158,12 +170,12 @@ stable launcher) serves the laptop column of the one Visa tool catalogue:
 | `status`         | Who this agent is, what is ready, and who takes the next step. Call first.                                                         |
 | `connect`        | Connect this computer (or replace its key). Returns the owner link; picks up approval automatically.                               |
 | `discover`       | Search paid services or probe one URL with GET and no body. Answers `unavailable` until the discovery source is live.                                   |
-| `pay`            | Pay a URL that answers HTTP 402 with a Tempo charge (OUSD). Needs `max` including the network fee and a new `request_id` per purchase. Optional `userRequest`: the person's words, kept by Visa for product analysis. **Moves real money.** |
-| `task_post`      | Post a claim task with a reward in USD and a `request_id`; uses the existing payment limits and approval. |
-| `task_action`    | Claim, submit, accept or release a task. Claim and submit need the owner's approval of the signature, then the same call again; submit and accept pay and need `max`. Every action first needs Visa's clearance of that task. **Moves real money.** |
+| `pay`            | Pay a URL that answers HTTP 402 with a Tempo charge (OUSD). Needs `max` including the network fee and a new `idempotency_key` per purchase. Optional `userRequest`: the person's words, kept by Visa for product analysis. **Moves real money.** |
+| `task_post`      | Post a claim task with a reward in USD and an `idempotency_key`; uses the existing payment limits and approval. |
+| `task_action`    | Claim, submit, accept or release a task. Claim and submit show the owner the task and reward; submission also binds the work fingerprint and shows a work preview. Approve once, then repeat the same call; submitting requires a merchant receipt for the reviewed work. Submit and accept pay and need `max`. Every action first needs Visa's clearance of that task. **Moves real money.** |
 | `task_list`      | List open screened tasks (or one named task with `task_id`) and short-lived clearances for task actions. Never pays. |
 | `task_status`    | Read a task’s status, reward and available claimant or submission. Never pays. |
-| `payment_status` | Read one purchase by its `request_id`, optionally waiting for it to change.                                                        |
+| `payment_status` | Read one purchase by its `idempotency_key`: a plain read. To wait, repeat the call that started it (it holds on your turn).          |
 | `payment_cancel` | Cancel a purchase awaiting owner approval.                                                                                           |
 | `history`        | This agent's purchases, newest first.                                                                                              |
 
@@ -171,20 +183,25 @@ stable launcher) serves the laptop column of the one Visa tool catalogue:
 
 Each tool advertises an extensible object `outputSchema`. Local and hosted MCP
 return that object in `structuredContent`, with a two-line summary first in
-`content` and the complete serialized JSON in a second text block. Text-only
+`content` and the same object as one line of JSON in a second text block. Text-only
 clients should read the JSON block; display clients should show the summary.
-Existing payload fields and refusal references remain available in the object.
+A purchase answer carries `idempotency_key` and a compact `payment` (no
+`attempts[]`); `payment_status` with `full: true` returns the whole purchase.
+Each deadline has a relative twin (`owner.in_seconds`, `deadline_in_seconds`).
+For a purchase, the summary is the answer's `message` on two lines (the result,
+then what to do), the same on every surface; it never repeats server or merchant
+text. Other payload fields and refusal references remain available in the object.
 The shell adapter, `visa-tool`, prints the object as JSON and appends a
 `Reference: <id>` line on refusals; it does not print the MCP display summary.
 
 When a `discover` query finds no services, its `next` hint offers `task_post` with
 the query as the suggested description. Posting requires an explicit `reward`
-(USD decimal), `request_id`, optional `duration_seconds` (default 3600) and an
+(USD decimal), `idempotency_key`, optional `duration_seconds` (default 3600) and an
 optional documented `terms_preset` (`standard`, `fast` or `flexible`; a staked task
 names one). Unknown fields are refused. Local rules give fast feedback; the edge must allow the exact draft before paying.
 Tasks needing review are not posted. The CLI obtains fresh clearance before each
 task action; callers do not supply it to `task_action`. Submit needs `text` and
-`max`; accept needs `max`. A missing or invalid `max` is corrected on the same task action with the same `request_id`. Reuse the same arguments and request ID to resume; a task response
+`max`; accept needs `max`. A missing or invalid `max` is corrected on the same task action with the same `idempotency_key`. Reuse the same arguments and idempotency key to resume; a task response
 does not prove payment settlement. Listed tasks show `net_reward` and any stake;
 a task that pays the worker nothing is never listed. A task outage or malformed task answer is named in
 `task_screening`, while successful service results remain available. `task_status` reads `/api/tasks/:id` without paying.
@@ -192,16 +209,30 @@ Taskmarket defaults to its testnet on Tempo Moderato and to `api.taskmarket.dev`
 on mainnet; `VISA_TASKMARKET_URL=off` turns tasks off. The live testnet currently refuses access-key signatures;
 the harness models requested support separately.
 
+`task_post` accepts `require_verified: "tap:identity:verified"` (verified workers),
+`"tap:identity:known"` (known or verified), or `"none"`. This is Tempo-only.
+Listings and status expose `verified_by` and `tap_verifier`; screening binds the
+requirement. Testnet creation returns `tap_simulated`: its directory proves only
+possession of a key enrolled with Taskmarket. Mainnet worker actions refuse with
+`verifier_unavailable` while Taskmarket's verifier is disconnected.
+Hosted requesters can post required tasks; hosted workers cannot claim or submit
+them. Device workers use the protected identity signer for claim, upload request
+and submission, retaining separate wallet approval and payment controls. The key
+must resolve with matching public bytes and sufficient trust in Taskmarket's
+selected directory. Visa directory publication alone does not enroll a key in
+Taskmarket's simulated directory. Automatic simulated enrollment and task updates
+are not offered by these tools. No private key is exported to Taskmarket's CLI.
+
 How `pay` works: the CLI builds the exact Tempo charge from the merchant's 402,
 asks Visa to admit it with this installation's proof, and, when the wallet
 provider needs this laptop's own approval, reads the signing activity from the
 provider itself, checks it against its own charge and votes. The paid request
 carries the agent's TAP signature; with no TAP key the CLI refuses before
 anything is signed. Each paying merchant request and its paid retry send `Idempotency-Key` with the same
-`request_id`. Unpaid price previews send no idempotency header. Reusing a `request_id` never pays twice: Visa's record
+`idempotency_key`. Unpaid price previews send no idempotency header. Reusing an `idempotency_key` never pays twice: Visa's record
 answers. When Visa verifies that the old execution was unpaid and explicitly
 returns the agent's `resume_payment` continuation, `payment_status` directs this
-computer to call `pay` with the same arguments and `request_id`. It prepares a
+computer to call `pay` with the same arguments and `idempotency_key`. It prepares a
 fresh unsigned quote and execution for the original purchase; Visa rechecks
 current authority and limits. Admission is recorded before its HTTP request;
 a missing server row during the original 120-second observation window does
@@ -215,13 +246,27 @@ An authorized purchase without a signing continuation remains unknown and read-o
 
 When Visa reconciles a merchant-wallet hold, the settled purchase remains paid and cannot be retried. `pay` preserves Visa's guidance, and `payment_status` exposes its existing owner support continuation. Recovery depends on the merchant's settings; this continuation does not authorize a claim. A missing receipt, unavailable answer or client delivery report does not establish a merchant hold.
 
-A native payment awaiting approval resumes with `pay`, the same `request_id` and arguments after the owner approves.
-
-Only Visa’s canonical settled state is reported as paid; a merchant answer does not prove settlement. An unknown outcome is never reported as "nothing was paid". Free merchant answers are returned as a preview up to 1 MiB without payment or a kept file; the cap ends the read without waiting for EOF. If a paid answer file or its final journal cannot be saved, the original call still returns its bounded preview and canonical payment result; retries never pay again. A preview with no file does not promise local retention. If a payment read fails through a network interruption or a body interruption after a successful HTTP response, or returns retryable `503 unavailable`, a verified delivered answer remains available locally with settlement unknown; prepared, sending and incomplete receiving attempts still require the original read to succeed. Explicit HTTP refusals and complete malformed Visa responses remain errors. Kept paid answers are checked against the digest recorded as they arrived. A missing, changed, or previously undigested answer is unavailable; its purchase history remains and the paid request is never resent.
-
-Refusals are JSON with a `code` from the Visa error families (for example
-`setup_required`, `limit_reached`, `not_enabled`), a `message` and a `fix`.
-For an OUSD charge, allow up to $0.01 above the quoted price for the network fee; a USDC.e swap also needs its funding ceiling.
+When a Tempo payment needs the owner's approval, `pay` answers at once with the
+approval link. The agent shows it once, then calls `pay` again with the same
+`idempotency_key` and arguments: that call holds on the purchase's turn (Visa's
+hold, 25 s, or the whole decision window when the MCP client takes progress)
+and, once the owner approves, resumes and pays in the same call, under the
+same purchase lock, so a second call never pays twice. A decline or expiry
+inside the hold answers at once and signs nothing. Nothing runs in the
+background and nothing of the request is written to disk: the agent's own
+call holds the arguments. A Taskmarket signature the owner approves is
+finished the same way, by the repeated `sign_action` or `task_action` call.
+
+A native payment awaiting approval resumes with `pay`, the same `idempotency_key` and arguments after the owner approves.
+
+Only Visa’s canonical settled state is reported as paid; a merchant answer does not prove settlement. A finishing payment (on its way, or being checked) is never reported as "nothing was paid". Free merchant answers are returned as a preview up to 1 MiB without payment or a kept file; the cap ends the read without waiting for EOF. If a paid answer file or its final journal cannot be saved, the original call still returns its bounded preview and canonical payment result; retries never pay again. A preview with no file does not promise local retention. If a payment read fails through a network interruption or a body interruption after a successful HTTP response, or returns retryable `503 unavailable`, a verified delivered answer remains available locally with settlement unknown; prepared, sending and incomplete receiving attempts still require the original read to succeed. Explicit HTTP refusals and complete malformed Visa responses remain errors. Kept paid answers are checked against the digest recorded as they arrived. A missing, changed, or previously undigested answer is unavailable; its purchase history remains and the paid request is never resent.
+
+Every answer carries `turn` (`owner`, `agent`, `visa`, `done`) and `next`
+(`none`, `call_again`, `new_request`, `stop`, `connect`, `update_cli`). Do
+what `next` says. When `turn` is `owner`, first give the owner `owner.say`,
+once. A refusal adds `code` (branch on it) and `detail` (diagnostic). `code` is one of the Visa error families (for example
+`setup_required`, `limit_reached`, `not_enabled`).
+For an OUSD charge, allow up to $0.01 above the quoted price for the network fee; when the quote names a funding ceiling, the `max` covers that too.
 When the charge plus network fee ceiling exceeds `pay.max`, the local `limit_reached` refusal
 names the price above max; budget and cap refusals keep their own diagnostics.
 A saved merchant challenge that differs from its prepared payment is refused
@@ -237,7 +282,7 @@ Live status refreshes a renamed agent’s name on this computer. Owner steps for
 It draws from a cache a background read refreshes at most every 30 seconds:
 
 ```
-◆ VISA │ claude 2 ● ready │ wallet $3.20 left of $50/day ▰▰▰▰▰▰ auto up to $5 │ last $0.25 fal.ai 4m │ staging
+◆ VISA │ claude 2 ● ready │ wallet $3.20 left of $50/day ▰▰▰▰▰▰ auto up to $5 │ last $0.25 fal.ai 4m
 Visa-mono │ Opus 5.5 │ context 34% ▰▰▱▱▱▱ │ 5h limit 24%
 ```
 
@@ -248,6 +293,7 @@ Visa-mono │ Opus 5.5 │ context 34% ▰▰▱▱▱▱ │ 5h limit 24%
   how close it is, and whether the agent pays automatically or asks each time.
 - **Freshness:** facts older than ten minutes say `as of`, and a failed read
   says `offline` with their age; a failed read never shows `ready` or `$0` as if live.
+- **A server other than Visa's own** is named last (`staging`, `local` or its host).
 - **This Claude session** (second line): folder, model, context used and the
   5-hour window.
 
@@ -264,7 +310,7 @@ and honours `NO_COLOR`.
 | `VISA_SUPPRESS_BROWSER=1`      | Print links instead of opening a browser.                                                       |
 | `VISA_TASKMARKET_URL` | Task service base URL; defaults to the Taskmarket testnet on Moderato and `https://api.taskmarket.dev` on mainnet. `off` disables tasks. |
 | `VISA_TEMPO_RPC_URL`           | A Tempo RPC for building charges (https, or this machine).                                      |
-| `VISA_RC_CODE`                 | The access code a release-candidate build asks for.                                             |
+| `VISA_RC_CODE`                 | The access code a release-candidate build asks for. A build from this repository (`pnpm --filter @visa/cli build`, or `pnpm turbo run build --filter=@visa/cli...`) made with it set accepts that code. |
 | `VISA_CLI_HUD_THEME`           | `light` or `dark` status line colours, when the terminal does not say (`COLORFGBG`).            |
 
 ## Data on this machine
@@ -279,25 +325,24 @@ and honours `NO_COLOR`.
 ### Managed runtime convergence
 
 The package also installs `visa-runtime-converge` for supervisor-owned
-OpenClaw/Hermes deployments. See
-[`packages/visa-cli-openclaw/RUNTIMES.md`](https://github.com/Visa-Crypto-Labs/Visa-mono/blob/staging/packages/visa-cli-openclaw/RUNTIMES.md).
+OpenClaw/Hermes deployments. See `RUNTIMES.md` in the
+`@visa/visa-cli-openclaw` package.
 
-### Cutover B hosted approval context
+### Hosted approval context
 
-The target hosted REST and MCP `pay` input accepts optional `original`, using the
+The hosted REST and MCP `pay` input accepts optional `original`, using the
 same canonical v1 terms and transient confidential replay request as payment prepare.
 Supply the actual original signing intent; a description or commitment hash
-cannot reconstruct it. Reuse the existing `request_id` to resume the purchase.
+cannot reconstruct it. Reuse the existing `idempotency_key` to resume the purchase.
 
-The existing owner-session `GET /owner/v1/approvals/:id` may return `detail` with
+The owner-session `GET /owner/v1/approvals/:id` may return `detail` with
 exact `requestedTerms` and an optional prepared payment. Null or absent detail
-means no available retained context. The private approval-page purpose may retain
-original signing intent under its configurable, initially enabled product policy;
-HTTP replay bodies and headers remain transient and context never goes to logs
-or telemetry. The owner and original payment/approval/deadline bindings remain
-required. Hosted Tempo payments ask the owner each time and resume the same
-approved purchase. Internal admission and current spending checks still apply.
-This source contract does not establish deployed availability.
+means no retained context. The approval page may retain the original signing
+intent under a configurable product policy, on by default; HTTP replay bodies
+and headers remain transient and context never goes to logs or telemetry. The
+owner and original payment/approval/deadline bindings remain required. Hosted
+Tempo payments ask the owner each time and resume the same approved purchase.
+Current spending checks still apply.
 
 ### Protected message signing
 
@@ -307,9 +352,9 @@ Status separates deployment `message_signing.configured` from this agent's
 service admission and separate owner consent still apply. Older status answers
 without readiness do not establish it from connection or configuration alone.
 
-`visa-tool sign_action` and the local/hosted MCP tool accept `request_id`,
+`visa-tool sign_action` and the local/hosted MCP tool accept `idempotency_key`,
 `scheme: "personal_sign"`, the original UTF-8 `message` and an HTTPS-origin
-`audience`. Use the same request ID and original inputs to resume. The selected
+`audience`. Use the same idempotency key and original inputs to resume. The selected
 agent determines the wallet and Tempo access key. The signature is an
 account-bound Tempo keychain V2 envelope; a service must support that envelope.
 Audience and network metadata constrain issuance. The external signature binds
@@ -320,8 +365,16 @@ exact message or, on a device, an explicit literal prefix using
 `permission_scope`. Matching device requests name that `permission_id`.
 Permissions currently last at most five minutes and the current key expiry;
 renewal needs new owner consent. Hosted signatures require exact owner consent
-and an independent owner vote each time. Signing may authorize escrow or other
-financial effects at a service even though no new payment occurs.
+and an independent owner vote each time; a hosted repeat of the request waits up
+to 40 seconds for the owner. A hosted Taskmarket claim, submit or release needs
+no clearance from the agent: Visa screens the task on every call and at the
+owner's approval, and refuses a changed or missing task before signing. A
+hosted connector is also served `task_status`, `task_action` and `task_post`:
+Visa sends the Taskmarket requests for it, each signature through hosted
+`sign_action` (a submission is one owner approval for both signatures) and each
+payment through hosted `pay`, so the owner approves every one. Signing
+may authorize escrow or other financial effects at a service even though no new
+payment occurs.
 
 `GET /agent/v1/signatures/:request_id` reports metadata only. Repeating the
 original `sign_action` recovers a known provider activity and verifies the
@@ -363,15 +416,14 @@ on recovery. They are independent of Visa's purchase UUID. Permitted names are
 case-insensitive, values stay exact, and request commitments detect changes.
 Reserved transport, wallet/payment authorization and Visa headers are refused.
 Raw values stay transient and do not enter logs or public history. Redirects are
-not followed with these headers. Native ATUM currently refuses caller-supplied
-headers before funding because its closed plan does not bind them.
+not followed with these headers.
 
 Registry documentation follows the package release channel: prerelease builds use preview docs; stable builds use production docs.
 
 `status` accepts only the optional `agent` selector. Unknown arguments are refused;
 correct them on the same tool.
 
-Correct a malformed request_id on the same tool that refused it. Resuming an existing operation keeps its original request_id.
+Correct a malformed idempotency_key on the same tool that refused it. Resuming an existing operation keeps its original idempotency_key.
 
 Hosted discover searches by query. To price a URL, use discover with target in Visa CLI on a connected computer.
 
@@ -379,7 +431,9 @@ A validation refusal describes the rejected input. It does not establish an earl
 
 A refused or unavailable task directs the agent to another permitted task. A task needing review directs it to Visa support; these refusals do not direct purchase-status reads.
 
-For a signing input conflict, repeat sign_action with its original inputs and request_id. The repeat_original_sign_action continuation refers to signing; payment_status retrieves purchases.
+For a signing input conflict, repeat sign_action with its original inputs and idempotency_key. The repeat_original_sign_action continuation refers to signing; payment_status retrieves purchases.
+
+A wrong computer clock is refused as `agent_clock_skew` (or `agent_signature_signature_stale` when minting a token) with the owner's `fix_clock` step: nothing was signed or sent. Once the clock updates automatically, retry the same request; reconnecting does not help.
 
 An account-wide daily limit offers a smaller payment, a later attempt or Visa
 support. Raising an agent's spending limit cannot change that account limit.

package/bin/update.cjs

@@ -57,12 +57,7 @@ module.exports = async function update(bootstrap, tag, logger) {
       }
     )
     const installed = path.join(release, 'node_modules', '@visa', 'cli')
-    const reported = execFileSync(
-      process.execPath,
-      [path.join(installed, 'bin', 'visa-cli.js'), '--version'],
-      options
-    ).trim()
-    if (reported !== version) throw new Error('Staged CLI version did not match')
+    checkStagedRelease(installed, version, options)
     const checked = JSON.parse(
       execFileSync(
         process.execPath,
@@ -79,8 +74,6 @@ server.startMcpServer();`,
     )
     if (checked.ok !== true || checked.build?.version !== version)
       throw new Error('Staged MCP server did not load')
-    fs.accessSync(path.join(installed, 'dist', 'cli.js'))
-    fs.accessSync(path.join(installed, 'dist', 'tool-call.js'))
     // Readers see the complete old release or the complete new release. The
     // old package and every previous release remain usable after interruption.
     const next = path.join(root, `.active-${id}.json`)
@@ -90,3 +83,40 @@ server.startMcpServer();`,
     unlock()
   }
 }
+
+/**
+ * Loads a staged release's bundles, not only its version line (`--version`
+ * answers before any bundle loads): a release whose CLI, tool or MCP bundle
+ * fails to load is never activated, so `visa update` always stays reachable.
+ */
+function checkStagedRelease(installed, version, options) {
+  let loaded
+  try {
+    loaded = JSON.parse(
+      execFileSync(
+        process.execPath,
+        [path.join(installed, 'bin', 'visa-cli.js'), '--self-check'],
+        options
+      ).trim()
+    )
+  } catch (error) {
+    throw new Error('Staged CLI did not load', { cause: error })
+  }
+  if (loaded?.ok !== true || loaded.version !== version)
+    throw new Error('Staged CLI version did not match')
+  execFileSync(
+    process.execPath,
+    [
+      '-e',
+      `const tool = require(process.argv[1]);
+const answers = require(process.argv[2]);
+if (typeof tool.main !== 'function' || typeof answers.answerToolCall !== 'function')
+throw new Error('Incompatible tool bundle');`,
+      path.join(installed, 'dist', 'tool-call.js'),
+      path.join(installed, 'dist', 'mcp-server', 'tool-answers.js'),
+    ],
+    options
+  )
+}
+
+module.exports.checkStagedRelease = checkStagedRelease

package/bin/visa-cli.js

@@ -1,4 +1,13 @@
 #!/usr/bin/env node
+// Compiled code is cached on disk (Node's own cache), so a repeat start skips
+// recompiling the bundles (L7-4). Older Nodes without it start as before.
+try {
+  require('node:module').enableCompileCache?.()
+} catch {}
 const path = require('node:path')
 const active = require('./active-package.cjs')(path.dirname(__dirname))
-require(path.join(active, 'dist', 'cli.js'))
+const argv = process.argv.slice(2)
+// The version answers before any bundle loads (L7-4).
+if (argv.length === 1 && (argv[0] === '--version' || argv[0] === '-V'))
+  process.stdout.write(`${require(path.join(active, 'package.json')).version}\n`)
+else require(path.join(active, 'dist', 'cli.js'))

package/bin/visa-tool.js

@@ -1,8 +1,20 @@
 #!/usr/bin/env node
+// Compiled code is cached on disk (Node's own cache), so a repeat start skips
+// recompiling the bundles (L7-4). Older Nodes without it start as before.
+try {
+  require('node:module').enableCompileCache?.()
+} catch {}
 const path = require('node:path')
 const active = require('./active-package.cjs')(path.dirname(__dirname))
+// After the answer, background work (its failure report) gets a short grace, then the call ends.
+const EXIT_GRACE_MS = 3_000
 require(path.join(active, 'dist', 'tool-call.js'))
   .main(process.argv.slice(2))
   .then((code) => {
     process.exitCode = code
+    // The grace starts once the answer has left: a slow pipe never gets a
+    // truncated answer (Sentinel #12136).
+    const end = () => setTimeout(() => process.exit(code), EXIT_GRACE_MS).unref()
+    if (process.stdout.writableNeedDrain) process.stdout.once('drain', end)
+    else end()
   })