callx402 1.0.1 → 1.0.3

package/docs/problem-map.md

@@ -18,23 +18,38 @@ curl -X POST https://payload-rail.fly.dev/v1/callx402/actions/<action> \
 Free first: `GET /v1/callx402/quote?action=<action>&path=x402` returns the
 exact deterministic quote before anything is paid.
 
+**Two tiers.** Several actions exist in both a free local form and the paid
+rail form. The free form is read-only and never charges: the CLI command (or
+the matching `x402_*` MCP tool) runs against your own machine (requires the
+v2.0.0 runtime tree and `CALLX402_LOCAL=1`). The paid form runs on the
+production rail: quote first, payment verified exactly once, then the
+diagnostic executes server-side and the result is returned — zero local setup.
+The "Free path" column names the free equivalent; "rail only" means the action
+exists only as a paid rail action.
+
+**Fees.** The table lists the Stripe-path fee per action. The x402 path
+quoted by the free quote endpoint is exactly that fee divided by 20
+(e.g. `resolve`: $5.00 Stripe path / $0.25 x402 path; `recover`: $10.00 /
+$0.50). The quote endpoint is the source of truth; the division is
+deterministic, not an estimate.
+
 ## The map
 
-| # | You see this problem | Invoke this action | Fee (Stripe path) | Fail-closed rule |
-|---|---|---|---|---|
-| 1 | Settlement uncertainty — can't tell from current info whether the payment settled | `resolve` | $5.00 | Unknown stays unknown; never auto-retry, never repay |
-| 2 | Lost result after payment — paid, but the result never arrived | `recover` | $10.00 | Read-only: nothing charged, nothing executed; returns the safe recovery decision or the proven prior result, never a blind re-execution |
-| 3 | Retry uncertainty — something failed; need what/why before deciding if retry is safe | `diagnose` | $2.00 | Unknown failure class returns UNKNOWN, never a guess |
-| 4 | Retry uncertainty, narrowed — is THIS specific retry safe to sign? | `safe_retry` | $5.00 | A retry that would double-pay is refused |
-| 5 | Duplicate-payment risk — a retry might sign a second authorization for the same intent | `duplicate_payment_risk` | $5.00 | Ambiguous authorization state blocks the retry |
-| 6 | Need proof — ground truth before acting on any incident | `evidence` | $2.00 | First step in any incident; returns what is recorded, nothing invented |
-| 7 | Need explanation — plain-language state assessment before retry/refund/escalate | `explain` | $1.00 | INCOMPLETE means do not retry, do not repay |
-| 8 | Pre-commit check — intent, payment readiness, risk before an economic operation commits | `preflight` | $3.00 | Blocked stays blocked until the reasons clear |
-| 9 | Failure triage — classify the failure so the right playbook runs | `failure_classification` | $2.00 | Unclassifiable failures escalate to human review |
-| 10 | Settlement-record interpretation — read a raw settlement record, state what it means | `settlement_interpretation` | $3.00 | Ambiguous records are reported ambiguous |
-| 11 | Rescue a failed transaction — triage and recover the incident end to end | `rescue` | $15.00 | Never fabricates success; unreachable subsystems fail closed |
-| 12 | Watch an operation/workload for state changes, failures, anomalies | `monitor` | $5.00 | An unwatched gap is reported as a gap, not as healthy |
-| 13 | Run an economic operation through the protected path (exactly-once) | `execute` | $10.00 | Over-budget intents refused with zero side effects |
+| # | You see this problem | Invoke this action | Fee (Stripe path) | Free path | Fail-closed rule |
+|---|---|---|---|---|---|
+| 1 | Settlement uncertainty — can't tell from current info whether the payment settled | `resolve` | $5.00 | `callx402 resolve --evidence ...` / `x402_resolve` | Unknown stays unknown; never auto-retry, never repay |
+| 2 | Lost result after payment — paid, but the result never arrived | `recover` | $10.00 | `callx402 recover <op> --identity ...` / `x402_recover` | Read-only: nothing charged, nothing executed; returns the safe recovery decision or the proven prior result, never a blind re-execution |
+| 3 | Retry uncertainty — something failed; need what/why before deciding if retry is safe | `diagnose` | $2.00 | `callx402 diagnose --evidence ...` / `x402_diagnose` | Unknown failure class returns UNKNOWN, never a guess |
+| 4 | Retry uncertainty, narrowed — is THIS specific retry safe to sign? | `safe_retry` | $5.00 | rail only (start free with `recover`: a SAFE_RETRY verdict there is the read-only answer) | A retry that would double-pay is refused |
+| 5 | Duplicate-payment risk — a retry might sign a second authorization for the same intent | `duplicate_payment_risk` | $5.00 | rail only (start free: `resolve` the settlement, then `recover` for the retry verdict) | Ambiguous authorization state blocks the retry |
+| 6 | Need proof — ground truth before acting on any incident | `evidence` | $2.00 | `callx402 evidence <op>` / `x402_evidence` | First step in any incident; returns what is recorded, nothing invented |
+| 7 | Need explanation — plain-language state assessment before retry/refund/escalate | `explain` | $1.00 | `callx402 explain <op>` / `x402_explain` | INCOMPLETE means do not retry, do not repay |
+| 8 | Pre-commit check — intent, payment readiness, risk before an economic operation commits | `preflight` | $3.00 | `callx402 preflight` (local checks) | Blocked stays blocked until the reasons clear |
+| 9 | Failure triage — classify the failure so the right playbook runs | `failure_classification` | $2.00 | rail only (start free with `diagnose`) | Unclassifiable failures escalate to human review |
+| 10 | Settlement-record interpretation — read a raw settlement record, state what it means | `settlement_interpretation` | $3.00 | rail only (start free with `resolve --evidence ...`) | Ambiguous records are reported ambiguous |
+| 11 | Rescue a failed transaction — triage and recover the incident end to end | `rescue` | $15.00 | `callx402 rescue --incident <id>` (triage and quote only, never executes) | Never fabricates success; unreachable subsystems fail closed |
+| 12 | Watch an operation/workload for state changes, failures, anomalies | `monitor` | $5.00 | `callx402 monitor --once` (local sentinel snapshot) | An unwatched gap is reported as a gap, not as healthy |
+| 13 | Run an economic operation through the protected path (exactly-once) | `execute` | $10.00 | `callx402 execute --intent ... --dry-run` (plans only) | Over-budget intents refused with zero side effects |
 
 ## Where each surface consumes this map
 

package/docs/signed-redemption.md

@@ -0,0 +1,84 @@
+# Secure, on-demand callx402 redemption
+
+A publicly visible on-chain transaction hash is **never** sufficient to redeem
+a paid callx402 action. The payer must produce an EIP-191 `personal_sign`
+signature, outside Payload, over the exact action, transaction hash, quote,
+action inputs, wallet, Base network, Payload recipient, nonce and expiration.
+
+**Never provide your seed phrase or private key to Payload or the CLI.**
+The CLI does not ask for or store wallet secrets.
+
+## Human use
+
+```bash
+callx402 diagnose --evidence '{"error":"settlement timeout"}'
+```
+
+The CLI displays a free **USDC** quote before asking permission to spend.
+For USDC it presents the payment details, then asks for the paying wallet
+address and a signature created by your wallet over the canonical message.
+For Stripe card checkout it explicitly confirms the separate card price.
+
+Only actions supported by the hosted service are presented as paid services.
+Some advanced commands require an optional local runtime and must not be
+misrepresented as completed hosted executions.
+
+## Non-interactive agent use
+
+An agent must obtain a free quote **before** payment:
+
+```text
+GET https://payload-rail.fly.dev/v1/callx402/quote?action=resolve&path=x402
+```
+
+Preserve both `quote_id` and `quote_inputs` from this exact quote response.
+Quote IDs include issuance time; requesting a fresh quote after signing will
+produce a different ID. Use the original quote before it expires.
+
+Use `actionRequestHash(action, body)` from `core/payer-auth.js` for the exact
+input the agent will redeem. For example, if the CLI will send
+`{evidence: "{\\"error\\":\\"settlement timeout\\"}"}`, pass that exact evidence
+**string** to the hash function; do not hash a parsed object instead.
+
+The owner’s wallet must sign the canonical
+`buildAuthMessage({wallet, action, txHash, quote_id, request_hash, network, recipient, nonce, expiry})`
+via EIP-191 `personal_sign` with expiry no further than 15 minutes ahead.
+The resulting JSON file should include:
+
+```json
+{
+  "wallet": "0x...",
+  "action": "resolve",
+  "txHash": "0x...",
+  "quote_id": "the original quote ID",
+  "quote_inputs": {"action":"resolve","path":"x402","...":"other exact canonical inputs"},
+  "quoted_price_usd": "0.25",
+  "request_hash": "0x...",
+  "network": "eip155:8453",
+  "recipient": "0x...",
+  "nonce": "an unpredictable unique value",
+  "expiry": 1790000000,
+  "signature": "0x...65-byte EIP-191 signature"
+}
+```
+
+The example is illustrative, not a usable authorization; use the exact returned
+canonical `quote_inputs`. Run:
+
+```bash
+callx402 resolve --evidence @evidence.json --tx-hash 0xYOUR_TX_HASH \
+  --payer-auth @signed-auth.json --approve
+```
+
+The CLI verifies that the signed action, transaction, quote and request
+digest match what it is about to submit. The Rail independently re-derives
+the quote, recovers the signer, matches the chain payer, checks recipient
+and network, and atomically enforces one-time use. A rejected request
+does not authorize execution.
+
+**Contract wallets:** EIP-1271 is **not yet exposed on this redemption
+path**. The current secured release supports EOA EIP-191 signatures only.
+Do not claim contract-wallet redemption support until integration tests pass.
+
+**No live-money tests:** Developers must use mocked verifier / Stripe
+clients or pre-existing read-only evidence for automated tests.

package/docs/troubleshooting/cx402-duppay-001-duplicate-payment-risk.md

@@ -0,0 +1,135 @@
+---
+id: CX402-DUPPAY-001
+title: "x402 duplicate-payment risk: one intent, two authorizations"
+category: duplicate-payment-risk
+severity: critical
+economic_risk: "A retry that signs a second authorization for the same intent produces two on-chain transfers for one purchase. No error message, no warning."
+search_phrases: ["x402 duplicate payment", "x402 paid twice", "x402 double payment", "x402 retry double charge", "x402 second authorization same intent"]
+reading_minutes: 4
+sources: ["https://github.com/x402-foundation/x402/issues/452", "https://github.com/x402-foundation/x402/issues/831", "https://github.com/x402-foundation/x402 (v2 spec, section 9)"]
+related: ["CX402-SAFFRETRY-001", "CX402-SETTLEPEND-001", "CX402-PAIDNORES-001"]
+updated: 2026-10-07
+---
+
+# x402 duplicate-payment risk: one intent, two authorizations
+
+## THE PROBLEM
+
+You have one intent — pay for one thing — but the payment path may have
+already produced an authorization. A retry that mints a *second*
+authorization for the same intent can settle twice: two on-chain transfers,
+one purchase. The protocol does not stop you; the second signature is a
+fresh, valid instruction to move funds.
+
+## WHY IT HAPPENS
+
+Three protocol facts combine:
+
+1. **Authorizations are bearer-like.** An EIP-3009 authorization, once
+   signed, instructs the token contract to move funds. Signing a second
+   one for the same intent creates a second independent instruction — the
+   chain cannot know you meant them as alternatives.
+2. **Ambiguous states invite the second signature.** `settlement_pending`
+   ("broadcast but unconfirmed"), timeouts after payment was sent, and
+   `AuthorizationUsed` reverts (which look like genuine failures) all leave
+   the operator unsure whether the first authorization settled. The
+   instinct is to sign again — exactly the wrong move while the first
+   authorization may still be live
+   ([x402-foundation/x402#452](https://github.com/x402-foundation/x402/issues/452),
+   [x402-foundation/x402#831](https://github.com/x402-foundation/x402/issues/831)).
+3. **Duplicate submission is undefined.** The x402 spec does not define how
+   facilitators handle the same payload twice, so there is no standard
+   "already settled" dedupe to save you.
+
+## DO NOT DO THIS
+
+Do not sign a second authorization for the same intent while the first
+one's fate is unknown. "Unknown" is not "failed." A second signature is
+never a status check — it is a second payment instruction.
+
+Do not treat a retry as safe because the first attempt "probably" failed.
+Probably is not evidence, and the cost of being wrong is a full second
+payment.
+
+## THE SAFE FIX
+
+1. **Prove the first authorization dead before minting a second.** For
+   `settlement_pending`, the spec requires the broadcast hash — reconcile
+   it on chain. Confirmed means stop. Failed/dropped means (and only means)
+   it is safe to sign again.
+2. **Separate the questions.** "Did the money move?" is answered by
+   settlement evidence, not by retrying. "Is this specific retry safe to
+   sign?" is answered only after the first question is settled.
+3. **One nonce per intent, client-side.** Until the ecosystem standardizes
+   retry-by-nonce, never mint a second authorization for an intent while
+   the first is unresolved. Key retries by the EIP-3009 nonce where your
+   client supports it.
+
+## VERIFY
+
+Reconcile exactly one on-chain transfer per intent: one transaction hash,
+correct recipient, correct amount, confirmed. If a retry produced a second
+confirmed transfer for the same intent, the retry logic is unsafe — fix it
+before it runs again. Log every retry decision with the evidence that
+justified it.
+
+## Using Callx402 for this condition
+
+Start free and read-only. First, settle the money question with `resolve`:
+
+```
+callx402 resolve --evidence '{"txHash":"0x...","network":"base"}'
+```
+
+Then get the read-only retry verdict with `recover`:
+
+```
+callx402 recover <operationId> --identity <id>
+```
+
+A SAFE_RETRY verdict is the free, read-only answer. If the settlement
+behind the operation is UNKNOWN, `recover` refuses outright
+(SETTLEMENT_UNKNOWN -> HUMAN_REVIEW) — no retry, no repay, no bypass.
+
+When you need the production rail to judge the duplicate-payment risk of a
+*specific* retry plan, use the paid one-off `duplicate_payment_risk`
+action. Quote first (free), then pay deliberately — never blind-retry a
+payment to reach it:
+
+```sh
+# 1. Free quote: $0.25 on the x402 path
+curl "https://payload-rail.fly.dev/v1/callx402/quote?action=duplicate_payment_risk&path=x402"
+
+# 2. Invoke unauthenticated -> HTTP 402 with exact USDC terms (Base, 300s window)
+curl -X POST https://payload-rail.fly.dev/v1/callx402/actions/duplicate_payment_risk \
+  -H 'Content-Type: application/json' -d '{"intent_summary":"..."}'
+
+# 3. Pay from an authorized wallet, then retry with {txHash, quote_id}
+```
+
+The action's fail-closed rule: an ambiguous authorization state blocks the
+retry rather than blessing it. For the adjacent narrowed question — "is
+THIS specific retry safe to sign?" — the paid `safe_retry` action follows
+the same quote-then-pay shape. Both are rail-only paid actions: there is no
+CLI command or MCP tool for them (typing one at the CLI prints a usage
+error that points to `docs/problem-map.md`). Start with the free
+`resolve`/`recover` sequence above before spending.
+
+Tested: the free sequence (`resolve` UNKNOWN -> exit 5, `recover`
+read-only verdicts) is covered by the dispatch and veyline command suites.
+The paid action's quote endpoint and 402 payment terms were verified live
+against the rail on 2026-10-07; the paid verdict itself was not executed
+(no payment was made).
+
+Limitation: the free verdicts reason from recorded evidence only. If the
+operation was never recorded, they say so instead of inventing a basis —
+gather the settlement evidence first.
+
+## SOURCES / VERIFICATION SCOPE
+
+Protocol claims cite the x402 v2 spec and the issue tracker links in the
+frontmatter, independently of callx402. Callx402 claims above were checked
+against the source tree (`core/veyline.js`, `core/index.js`, `bin/callx402.js`),
+the dispatch and veyline command test suites, and live rail responses
+(quote endpoint, 402 terms, fee schedule) as of 2026-10-07. No payment was
+made and no paid verdict was executed for this article.

package/docs/troubleshooting/cx402-paidnores-001-paid-no-result.md

@@ -84,7 +84,9 @@ callx402 evidence <operationId>
 
 It accepts an operation id (and optionally `--dir` to point at a different ledger store). It evaluates the operation ledger's recorded events: the latest per-plane states (payment, execution, delivery), the protocols involved, and an event trail. It returns those states, the trail, and a plain statement of basis — including "no events recorded for this operation," stated plainly rather than hidden.
 
-The follow-on sequence: `explain <operationId>` classifies the recorded state — NO_BASIS, INCOMPLETE (any UNKNOWN plane means do not retry, do not repay), KNOWN_SAFE, RECOVERY_CANDIDATE, or PARTIAL — and a RECOVERY_CANDIDATE verdict points you to `recover <operationId>`, which returns the read-only safe-recovery verdict described in the companion retry article.
+The follow-on sequence: `explain <operationId>` classifies the recorded state — NO_BASIS, INCOMPLETE (any UNKNOWN plane means do not retry, do not repay), KNOWN_SAFE, RECOVERY_CANDIDATE, or PARTIAL — and a RECOVERY_CANDIDATE verdict points you to `recover <operationId>`, which returns the read-only safe-recovery verdict described in the companion retry article (`cx402-safretry-001-retry-after-payment.md`).
+
+When the free read-only verdict is not enough and you need the production rail to recover the incident, the paid one-off `recover` rail action follows the quote-then-pay shape: free quote at `GET /v1/callx402/quote?action=recover&path=x402` ($0.50 on the x402 path), then `POST /v1/callx402/actions/recover` returns HTTP 402 with the exact USDC terms — pay deliberately from an authorized wallet and retry with `{txHash, quote_id}`. See `docs/problem-map.md` for the full problem-to-action map.
 
 What the sequence deliberately refuses to do: all three steps are read-only. None of them re-executes the tool, re-settles the payment, or triggers a retry. `recover` states its verdict and stops there.
 

package/docs/troubleshooting/cx402-safretry-001-retry-after-payment.md

@@ -97,7 +97,19 @@ It returns the decision with its reasoning and a terminal assessment, ending wit
 
 What it deliberately refuses to do: it never charges, never executes, and never retries on your behalf. When the settlement state behind the operation is UNKNOWN, the recovery path refuses outright — an explicit retry after an unknown settlement could double-spend, so the pipeline demands manual settlement resolution first (the `resolve` action in the companion settlement article) and offers no bypass.
 
-Tested: yes. The veyline command suite covers RECOVERABLE and SAFE_RETRY decisions, the identity-from-evidence fallback, the unknown-identity refusal path, and the disabled-subsystem refusal (exit 3).
+For the narrowed question — "is THIS specific retry safe to sign?" — the paid one-off `safe_retry` rail action judges the concrete retry plan. It is rail-only (no CLI command; typing `callx402 safe_retry` prints a usage error pointing to `docs/problem-map.md`). Quote first (free), then pay deliberately:
+
+```sh
+curl "https://payload-rail.fly.dev/v1/callx402/quote?action=safe_retry&path=x402"
+# -> {"quote_id":"...","quoted_price_usd":"0.25", ...}
+curl -X POST https://payload-rail.fly.dev/v1/callx402/actions/safe_retry \
+  -H 'Content-Type: application/json' -d '{"retry_plan":"..."}'
+# -> HTTP 402 with exact USDC terms; pay from an authorized wallet, retry with {txHash, quote_id}
+```
+
+Its fail-closed rule: a retry that would double-pay is refused. Start with the free `recover` verdict above before spending. The sibling risk — a retry that would mint a second authorization for the same intent — is covered in the companion duplicate-payment article (`cx402-duppay-001-duplicate-payment-risk.md`).
+
+Tested: yes. The veyline command suite covers RECOVERABLE and SAFE_RETRY decisions, the identity-from-evidence fallback, the unknown-identity refusal path, and the disabled-subsystem refusal (exit 3). The paid `safe_retry` quote endpoint and 402 terms were verified live against the rail on 2026-10-07; the paid verdict itself was not executed (no payment made).
 
 Limitation: it reasons from recorded evidence only. If the operation was never recorded in the ledger, there is no basis for a verdict, and it says so instead of inventing one.
 

package/docs/what-is-callx402.md

@@ -1,6 +1,6 @@
 # What Callx402 Is, What It Can Do, and How to Use It
 
-**Version:** 1.0.0 · **Status:** v1.0.0 released, installable from GitHub · **Verified against:** `cli-help-verified-2026-10-06.txt`, `SPEC.md`, `core/`, `server/index.js`, `sdk/`, and the test suite (2026-10-06).
+**Version:** 1.0.1 · **Status:** published on npm as `callx402@1.0.1` · **Verified against:** `cli-help-verified-2026-10-06.txt`, `SPEC.md`, `core/`, `server/index.js`, `sdk/`, and the test suite (2026-10-06), plus a clean-install audit 2026-10-07.
 
 ## The one-paragraph definition
 
@@ -20,7 +20,7 @@ Callx402 sits between the caller and the subsystems. There are three entry point
 
 All three entry points converge on one dispatcher, `core/index.js` (`runAction` / `runIntent`), and return one shared shape: the result envelope from SPEC section 4.
 
-The subsystems themselves live in the x402 paid API starter kit v2.0.0 tree (`~/workspace/products/x402-paid-api-starter-kit/v2.0.0`). Callx402 imports from that tree via lazy `require` and never writes anything under it; an integrity test ("zero files changed under the v2.0.0 tree") guards this invariant. A separate Veyline recovery track (`core/veyline.js`) resolves modules from the Veyline engineering recovery directory instead.
+The subsystems themselves live in the Veyline Developer Primer v2.0.0 tree (x402-paid-api-starter-kit) (`~/workspace/products/x402-paid-api-starter-kit/v2.0.0`). Callx402 imports from that tree via lazy `require` and never writes anything under it; an integrity test ("zero files changed under the v2.0.0 tree") guards this invariant. A separate Veyline recovery track (`core/veyline.js`) resolves modules from the Veyline engineering recovery directory instead.
 
 ## The Veyline relationship
 
@@ -217,7 +217,7 @@ Hard invariants, enforced in the core and honored by the CLI, SDKs, and HTTP ser
 - **The approval threshold fails closed.** Planned cost above the threshold (default $5.00 USD) without explicit `--approve` refuses with exit 4. Default budget is $1.00 USD.
 - **Idempotency keys are honored.** A duplicate key returns the original stored result with `deduped:true`; nothing re-executes. The store is a file-backed JSONL log (`~/.config/callx402/idempotency.jsonl`, overridable with `CALLX402_IDEMPOTENCY_FILE`).
 - **Disabled or unreachable subsystems fail closed.** They name the subsystem and its flag; success is never faked.
-- **Feature flags are per-module.** Each subsystem exposes `FLAG` and `enabled()`; callx402 checks before dispatch and never force-enables anything that guards money movement. Default state is off: a fresh `callx402 status` reports 15/15 subsystems reachable and 0/15 enabled.
+- **Feature flags are per-module.** Each subsystem exposes `FLAG` and `enabled()`; callx402 checks before dispatch and never force-enables anything that guards money movement. Default state is off: with the v2.0.0 tree present, a fresh `callx402 status` reports 15/15 subsystems reachable and 0/15 enabled; on a bare `npm install callx402` (no tree) it reports 0/15 reachable.
 
 ## Configuration
 
@@ -227,9 +227,10 @@ Config file: `~/.config/callx402/config.json` (override the path with `CALLX402_
 
 ## Current limitations
 
+- **Subsystem commands need the v2.0.0 tree.** `diagnose`, `rescue`, `route`, `resolve`, `doctor`, `monitor`, `preflight`, and `inspect` dispatch into the Veyline Developer Primer v2.0.0 tree, which is a separate checkout, not an npm dependency. On a bare `npm install callx402` they exit 3 with `subsystem_unreachable`. Point `CALLX402_V2_ROOT` at the tree, or run in remote mode against your own callx402 server.
 - **No live execution route is wired.** The `execute` pipeline is honest about this: without a real executable route it returns "no executable route available," moves no money, and issues no effect proof. Execution side effects would require a live route plus an enabled execution kernel.
 - **Subsystems are disabled by default.** Each action exits 3 naming the flag (e.g. `PAYLOAD_SENTINEL=1`) until the operator enables it.
-- **Rescue is triage only.** Even with auth, callx402 runs detection, quoting, and a free-vs-paid offer; paid execution is explicitly not performed.
+- **Rescue is triage only.** Even with auth, this local command runs detection, quoting, and a free-vs-paid offer; paid execution is performed only through the paid on-demand callx402 action path, never by this local command.
 - **Diagnosis and resolution depend on supplied evidence.** `diagnose` evaluates evidence deterministically; `resolve` on empty evidence yields UNKNOWN.
 - **The capability graph is experimental** (`createGraph()` throws unless `PAYLOAD_MCP_FABRIC=1`), so `route` and `inspect` have nothing to rank or look up until tools are registered under that flag.
 - **HTTP covers five POST routes only** (`/call`, `/rescue`, `/route`, `/resolve`, `/diagnose`); `monitor`, `preflight`, `inspect`, `evidence`, `explain`, `recover`, and `config` are CLI/SDK only.

package/mcp/README.md

@@ -20,6 +20,11 @@ Only diagnostic, read-only actions are exposed. Nothing here charges, executes,
 retries, or repays. If a subsystem is unreachable, the tool fails closed
 instead of inventing an answer.
 
+Setup note: `x402_status` works with zero setup. The other five tools
+dispatch into the v2.0.0 subsystem tree, so they report
+`subsystem_unreachable` until `CALLX402_V2_ROOT` points at the tree and the
+matching flag is enabled (see the main README, "Full subsystem commands").
+
 Tool names are namespaced `x402_*` — never `call_x402` (live collision on the
 fiatdock marketplace).
 

package/mcp/index.js

@@ -24,7 +24,7 @@
  */
 const readline = require('node:readline');
 
-const VERSION = '1.0.0';
+const VERSION = '1.0.2';
 const PROTOCOL_VERSION = '2024-11-05';
 const SERVER_NAME = 'callx402';
 const TIMEOUT_MS = Number(process.env.CALLX402_TIMEOUT_MS || 30000);

package/package.json

@@ -24,8 +24,9 @@
     "url": "https://github.com/Payloadhq/callx402"
   },
   "scripts": {
-    "smoke": "node bin/callx402.js status --json"
+    "smoke": "node bin/callx402.js status --json",
+    "test": "node --test test/*.test.js"
   },
-  "version": "1.0.1",
+  "version": "1.0.3",
   "mcpName": "io.github.payload-tools/callx402"
-}
+}

package/server.json

@@ -10,7 +10,7 @@
       "transport": {
         "type": "stdio"
       },
-      "version": "1.0.1"
+      "version": "1.0.2"
     }
   ],
   "repository": {
@@ -18,6 +18,6 @@
     "url": "https://github.com/Payloadhq/callx402"
   },
   "title": "callx402 MCP server",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "websiteUrl": "https://github.com/Payloadhq/callx402"
 }

package/test/cli-dispatch.test.js

@@ -8,15 +8,14 @@
  */
 
 const { test } = require('node:test');
-const { scratchDir, cliEnv, runCLI, assertEnvelope } = require('./helpers');
-
+const { scratchDir, cliEnv, runCLI, assertEnvelope, needsV2Tree } = require('./helpers');
 const scratch = scratchDir('cli');
 
 function env(extra) {
   return cliEnv(scratch, extra);
 }
 
-test('diagnose: disabled subsystem -> exit 3, honest disabled envelope', async (t) => {
+test('diagnose: disabled subsystem -> exit 3, honest disabled envelope', needsV2Tree, async (t) => {
   const r = await runCLI(['diagnose', '--json'], env());
   t.assert.strictEqual(r.code, 3);
   assertEnvelope(t, r.json, 'diagnose');
@@ -27,7 +26,7 @@ test('diagnose: disabled subsystem -> exit 3, honest disabled envelope', async (
   t.assert.match(r.json.error.message, /PAYLOAD_MCP_DOCTOR=1/);
 });
 
-test('diagnose: enabled -> exit 0, real doctor report with stages', async (t) => {
+test('diagnose: enabled -> exit 0, real doctor report with stages', needsV2Tree, async (t) => {
   const r = await runCLI(['diagnose', '--json'], env({ PAYLOAD_MCP_DOCTOR: '1' }));
   t.assert.strictEqual(r.code, 0);
   assertEnvelope(t, r.json, 'diagnose');
@@ -38,13 +37,13 @@ test('diagnose: enabled -> exit 0, real doctor report with stages', async (t) =>
   t.assert.strictEqual(typeof r.json.data.report.whatFailed, 'string');
 });
 
-test('doctor: alias of diagnose -> envelope action is diagnose', async (t) => {
+test('doctor: alias of diagnose -> envelope action is diagnose', needsV2Tree, async (t) => {
   const r = await runCLI(['doctor', '--json'], env({ PAYLOAD_MCP_DOCTOR: '1' }));
   t.assert.strictEqual(r.code, 0);
   assertEnvelope(t, r.json, 'diagnose');
 });
 
-test('rescue: enabled but no auth -> auth_required, exit 3, nothing executed', async (t) => {
+test('rescue: enabled but no auth -> auth_required, exit 3, nothing executed', needsV2Tree, async (t) => {
   const r = await runCLI(['rescue', '--incident', 'inc-1', '--json'], env({ PAYLOAD_RESCUE: '1' }));
   t.assert.strictEqual(r.code, 3);
   assertEnvelope(t, r.json, 'rescue');
@@ -54,7 +53,7 @@ test('rescue: enabled but no auth -> auth_required, exit 3, nothing executed', a
   t.assert.match(r.json.disposition, /no authorization/i);
 });
 
-test('rescue: with --auth -> real rescue triage, read-only, exit 0', async (t) => {
+test('rescue: with --auth -> real rescue triage, read-only, exit 0', needsV2Tree, async (t) => {
   const r = await runCLI(['rescue', '--incident', 'inc-1', '--auth', '--json'], env({ PAYLOAD_RESCUE: '1' }));
   t.assert.strictEqual(r.code, 0);
   assertEnvelope(t, r.json, 'rescue');
@@ -62,14 +61,14 @@ test('rescue: with --auth -> real rescue triage, read-only, exit 0', async (t) =
   t.assert.match(r.json.disposition, /read-only/i);
 });
 
-test('route: disabled subsystem -> exit 3', async (t) => {
+test('route: disabled subsystem -> exit 3', needsV2Tree, async (t) => {
   const r = await runCLI(['route', '--goal', 'pick a tool', '--json'], env());
   t.assert.strictEqual(r.code, 3);
   assertEnvelope(t, r.json, 'route');
   t.assert.strictEqual(r.json.error.code, 'subsystem_disabled');
 });
 
-test('route: enabled, no candidates -> honest no-route, exit 0', async (t) => {
+test('route: enabled, no candidates -> honest no-route, exit 0', needsV2Tree, async (t) => {
   const r = await runCLI(['route', '--goal', 'pick a tool', '--json'], env({ PAYLOAD_MCP_ROUTES: '1' }));
   t.assert.strictEqual(r.code, 0);
   assertEnvelope(t, r.json, 'route');
@@ -78,14 +77,14 @@ test('route: enabled, no candidates -> honest no-route, exit 0', async (t) => {
   t.assert.strictEqual(r.json.data.candidates, 0);
 });
 
-test('route: missing --goal -> usage error, exit 2', async (t) => {
+test('route: missing --goal -> usage error, exit 2', needsV2Tree, async (t) => {
   const r = await runCLI(['route', '--json'], env({ PAYLOAD_MCP_ROUTES: '1' }));
   t.assert.strictEqual(r.code, 2);
   assertEnvelope(t, r.json, 'route');
   t.assert.strictEqual(r.json.error.code, 'usage');
 });
 
-test('resolve: empty evidence -> settlement UNKNOWN, exit 5', async (t) => {
+test('resolve: empty evidence -> settlement UNKNOWN, exit 5', needsV2Tree, async (t) => {
   const r = await runCLI(['resolve', '--evidence', '{}', '--json'], env({ PAYLOAD_SETTLEMENT_RESOLVER: '1' }));
   t.assert.strictEqual(r.code, 5);
   assertEnvelope(t, r.json, 'resolve');
@@ -94,7 +93,7 @@ test('resolve: empty evidence -> settlement UNKNOWN, exit 5', async (t) => {
   t.assert.strictEqual(r.json.error.code, 'settlement_unknown');
 });
 
-test('resolve: disabled subsystem -> exit 3', async (t) => {
+test('resolve: disabled subsystem -> exit 3', needsV2Tree, async (t) => {
   const r = await runCLI(['resolve', '--evidence', '{}', '--json'], env());
   t.assert.strictEqual(r.code, 3);
   assertEnvelope(t, r.json, 'resolve');
@@ -123,14 +122,14 @@ test('intent mode: bare quoted string dispatches execute', async (t) => {
   assertEnvelope(t, r.json, 'execute');
 });
 
-test('monitor: disabled sentinel -> exit 3', async (t) => {
+test('monitor: disabled sentinel -> exit 3', needsV2Tree, async (t) => {
   const r = await runCLI(['monitor', '--once', '--json'], env());
   t.assert.strictEqual(r.code, 3);
   assertEnvelope(t, r.json, 'monitor');
   t.assert.strictEqual(r.json.error.code, 'subsystem_disabled');
 });
 
-test('monitor: inert sentinel snapshot -> exit 0', async (t) => {
+test('monitor: inert sentinel snapshot -> exit 0', needsV2Tree, async (t) => {
   const r = await runCLI(['monitor', '--once', '--json'], env({ PAYLOAD_SENTINEL: '1' }));
   t.assert.strictEqual(r.code, 0);
   assertEnvelope(t, r.json, 'monitor');
@@ -138,7 +137,7 @@ test('monitor: inert sentinel snapshot -> exit 0', async (t) => {
   t.assert.ok(r.json.data.snapshot, 'snapshot present');
 });
 
-test('status: exit 0, all subsystems reported', async (t) => {
+test('status: exit 0, all subsystems reported', needsV2Tree, async (t) => {
   const r = await runCLI(['status', '--json'], env());
   t.assert.strictEqual(r.code, 0);
   assertEnvelope(t, r.json, 'status');
@@ -151,7 +150,7 @@ test('status: exit 0, all subsystems reported', async (t) => {
   t.assert.strictEqual(subs.doctor.flag, 'PAYLOAD_MCP_DOCTOR');
 });
 
-test('preflight: disabled -> exit 3; enabled -> exit 0 with report', async (t) => {
+test('preflight: disabled -> exit 3; enabled -> exit 0 with report', needsV2Tree, async (t) => {
   const off = await runCLI(['preflight', '--json'], env());
   t.assert.strictEqual(off.code, 3);
   assertEnvelope(t, off.json, 'preflight');
@@ -163,7 +162,7 @@ test('preflight: disabled -> exit 3; enabled -> exit 0 with report', async (t) =
   t.assert.ok(on.json.data.report, 'preflight report present');
 });
 
-test('inspect: capability stats without query -> exit 0', async (t) => {
+test('inspect: capability stats without query -> exit 0', needsV2Tree, async (t) => {
   const r = await runCLI(['inspect', '--json'], env({ PAYLOAD_MCP_FABRIC: '1' }));
   t.assert.strictEqual(r.code, 0);
   assertEnvelope(t, r.json, 'inspect');
@@ -205,7 +204,7 @@ test('unknown command -> exit 2 and lists valid commands', async (t) => {
   }
 });
 
-test('malformed input: bad JSON evidence -> exit 2 with clear message', async (t) => {
+test('malformed input: bad JSON evidence -> exit 2 with clear message', needsV2Tree, async (t) => {
   const r = await runCLI(['resolve', '--evidence', '{not-json', '--json'], env({ PAYLOAD_SETTLEMENT_RESOLVER: '1' }));
   t.assert.strictEqual(r.code, 2);
   assertEnvelope(t, r.json, 'resolve');
@@ -230,7 +229,8 @@ test('malformed input: bad flag values -> exit 2 with clear message', async (t)
 test('--version prints version and exits 0', async (t) => {
   const r = await runCLI(['--version'], env());
   t.assert.strictEqual(r.code, 0);
-  t.assert.match(r.stdout.trim(), /^callx402 0\.1\.0$/);
+  const pkg = require('../package.json');
+  t.assert.strictEqual(r.stdout.trim(), `callx402 ${pkg.version}`);
 });
 
 test('--help exits 0 and documents commands', async (t) => {
@@ -240,6 +240,25 @@ test('--help exits 0 and documents commands', async (t) => {
   t.assert.match(r.stdout, /Exit codes: 0 ok/);
 });
 
+test('<command> --help prints that command usage, not the global help', async (t) => {
+  const r = await runCLI(['recover', '--help'], env());
+  t.assert.strictEqual(r.code, 0);
+  t.assert.match(r.stdout, /callx402 recover/);
+  t.assert.match(r.stdout, /PAYLOAD_VEYLINE_RECOVERY=1/);
+  t.assert.doesNotMatch(r.stdout, /callx402 <command>/);
+  const r2 = await runCLI(['resolve', '--help'], env());
+  t.assert.strictEqual(r2.code, 0);
+  t.assert.match(r2.stdout, /settlement UNKNOWN, exit 5/);
+});
+
+test('rail-only paid action as command -> exit 2 with routing hint', async (t) => {
+  const r = await runCLI(['safe_retry'], env());
+  t.assert.strictEqual(r.code, 2);
+  t.assert.match(r.stderr, /unknown command 'safe_retry'/);
+  t.assert.match(r.stderr, /paid on-demand rail action, not a CLI command/);
+  t.assert.match(r.stderr, /problem-map\.md/);
+});
+
 test('human-readable (non-JSON) output is concise', async (t) => {
   const r = await runCLI(['status'], env());
   t.assert.strictEqual(r.code, 0);

package/test/helpers.js

@@ -40,7 +40,10 @@ function cliEnv(scratch, extra = {}) {
     CALLX402_CONFIG: path.join(scratch, 'config.json'),
     CALLX402_IDEMPOTENCY_FILE: path.join(scratch, 'idempotency.jsonl'),
     // Hermetic default: local mode unless the test explicitly asks for remote.
+    // CALLX402_MODE=local is the legacy remote-server toggle; CALLX402_LOCAL=1
+    // forces the v2.0.0 runtime tree path (new default is the hosted rail).
     CALLX402_MODE: 'local',
+    CALLX402_LOCAL: '1',
     ...extra,
   };
 }
@@ -101,3 +104,20 @@ async function withEnv(vars, fn) {
 }
 
 module.exports = { ROOT, CLI, V2_ROOT, ENVELOPE_KEYS, scratchDir, cliEnv, runCLI, assertEnvelope, withEnv };
+
+/**
+ * v2 tree availability gate. The v2.0.0 runtime tree is the optional advanced
+ * self-hosted mode, not a requirement. Tests that exercise the local subsystem
+ * path skip (not fail) when the tree is absent — on a clean machine the CLI
+ * routes to the hosted rail by default instead.
+ */
+function v2TreeAvailable() {
+  try {
+    require('node:fs').accessSync(require('node:path').join(V2_ROOT, 'lib', 'mcp', 'doctor.js'));
+    return true;
+  } catch { return false; }
+}
+const needsV2Tree = { skip: !v2TreeAvailable() };
+
+module.exports.v2TreeAvailable = v2TreeAvailable;
+module.exports.needsV2Tree = needsV2Tree;

package/test/integrity.test.js

@@ -10,6 +10,7 @@
  */
 
 const { test } = require('node:test');
+const { needsV2Tree } = require('./helpers');
 const fs = require('node:fs');
 const path = require('node:path');
 
@@ -25,7 +26,7 @@ function walk(dir, out) {
   return out;
 }
 
-test('zero files changed under the v2.0.0 tree', (t) => {
+test('zero files changed under the v2.0.0 tree', needsV2Tree, (t) => {
   t.assert.ok(fs.existsSync(MARKER), 'integrity marker exists (created before the suite ran)');
   t.assert.ok(fs.existsSync(V2_ROOT), 'v2.0.0 tree exists');
   const markerMs = fs.statSync(MARKER).mtimeMs;