callx402 1.0.1 → 1.0.2

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.2",
   "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;

package/test/intent-pipeline.test.js

@@ -16,8 +16,7 @@
 const { test } = require('node:test');
 const path = require('node:path');
 const { runIntent, runAction } = require('../core/index.js');
-const { scratchDir, withEnv } = require('./helpers');
-
+const { scratchDir, withEnv, needsV2Tree } = require('./helpers');
 const scratch = scratchDir('pipeline');
 const hermetic = {
   CALLX402_CONFIG: path.join(scratch, 'config.json'),
@@ -169,7 +168,7 @@ test('networks/assets/providers constrain planner, router and spendguard', async
   });
 });
 
-test('real end-to-end run (no doubles, all flags off): honest no-route', async (t) => {
+test('real end-to-end run (no doubles, all flags off): honest no-route', needsV2Tree, async (t) => {
   await withEnv(hermetic, async () => {
     const { result, exitCode } = await runIntent('summarize this for under 1 dollar', { maxBudget: 1 });
     t.assert.strictEqual(exitCode, 0);

package/test/remote.test.js

@@ -14,8 +14,7 @@ const { test } = require('node:test');
 const path = require('node:path');
 const { runAction, runIntent } = require('../core/index.js');
 const { createServer } = require('../server/index.js');
-const { scratchDir, cliEnv, runCLI, assertEnvelope, withEnv } = require('./helpers');
-
+const { scratchDir, cliEnv, runCLI, assertEnvelope, withEnv, needsV2Tree } = require('./helpers');
 const scratch = scratchDir('remote');
 
 /** Start a real callx402 server on an ephemeral port. */
@@ -148,7 +147,7 @@ test('remote auth: server with token rejects missing/wrong bearer, accepts the r
   }
 });
 
-test('remote money-safety: settlement UNKNOWN envelope crosses the wire unchanged (exit 5)', async (t) => {
+test('remote money-safety: settlement UNKNOWN envelope crosses the wire unchanged (exit 5)', needsV2Tree, async (t) => {
   // The server runs in-process, so the subsystem flag belongs to the parent
   // env; the CLI subprocess only carries the remote-mode config.
   await withEnv({ PAYLOAD_SETTLEMENT_RESOLVER: '1' }, async () => {

package/test/safety.test.js

@@ -15,8 +15,7 @@
 const { test } = require('node:test');
 const path = require('node:path');
 const { runIntent, runAction } = require('../core/index.js');
-const { scratchDir, cliEnv, runCLI, assertEnvelope, withEnv } = require('./helpers');
-
+const { scratchDir, cliEnv, runCLI, assertEnvelope, withEnv, needsV2Tree } = require('./helpers');
 const scratch = scratchDir('safety');
 const hermetic = {
   CALLX402_CONFIG: path.join(scratch, 'config.json'),
@@ -99,7 +98,7 @@ function walkPairs(o, prefix = '') {
   return out;
 }
 
-test('settlement UNKNOWN: exit 5, fail-closed, no retry/repay instruction', async (t) => {
+test('settlement UNKNOWN: exit 5, fail-closed, no retry/repay instruction', needsV2Tree, async (t) => {
   const r = await runCLI(
     ['resolve', '--evidence', '{}', '--json'],
     cliEnv(scratch, { PAYLOAD_SETTLEMENT_RESOLVER: '1' })
@@ -164,7 +163,7 @@ test('unsafe retry refusal: stored UNKNOWN + --force-retry -> refused, exit 5',
   });
 });
 
-test('unsafe retry refusal via real CLI + file-backed store', async (t) => {
+test('unsafe retry refusal via real CLI + file-backed store', needsV2Tree, async (t) => {
   const idemFile = path.join(scratch, 'idem-unsafe.jsonl');
   const env = cliEnv(scratch, { CALLX402_IDEMPOTENCY_FILE: idemFile });
   const seeded = {
@@ -222,7 +221,7 @@ test('timeout: slow subsystem + tiny timeoutMs -> timeout error, exit 1, no hang
   });
 });
 
-test('timeout via CLI --timeout: monitor --watch is cut off -> exit 1', async (t) => {
+test('timeout via CLI --timeout: monitor --watch is cut off -> exit 1', needsV2Tree, async (t) => {
   // --watch streams forever; --timeout 200ms must win the race and exit 1.
   const r = await runCLI(
     ['monitor', '--watch', '--interval', '50', '--timeout', '200'],

package/test/sdk.test.js

@@ -13,8 +13,7 @@
 const { test } = require('node:test');
 const path = require('node:path');
 const { execFile } = require('node:child_process');
-const { ENVELOPE_KEYS, scratchDir, withEnv } = require('./helpers');
-
+const { ENVELOPE_KEYS, scratchDir, withEnv, needsV2Tree } = require('./helpers');
 const scratch = scratchDir('sdk');
 const hermetic = {
   CALLX402_CONFIG: path.join(scratch, 'config.json'),
@@ -45,7 +44,7 @@ test('JS SDK: callx402({intent}) returns a full envelope (in-process)', async (t
   });
 });
 
-test('JS SDK: version, status(), and sub-actions', async (t) => {
+test('JS SDK: version, status(), and sub-actions', needsV2Tree, async (t) => {
   await withEnv(hermetic, async () => {
     t.assert.strictEqual(sdk.version, '1.0.0');
     t.assert.strictEqual(require('../sdk/js/index.js').callx402.version, '1.0.0');
@@ -74,7 +73,7 @@ test('JS SDK: invalid opts throw TypeError (fail fast, no dispatch)', async (t)
   });
 });
 
-test('JS SDK: action dispatch through runAction', async (t) => {
+test('JS SDK: action dispatch through runAction', needsV2Tree, async (t) => {
   await withEnv(hermetic, async () => {
     const r = await sdk({ action: 'resolve', args: { evidence: '{}' } });
     // Settlement subsystem disabled without its flag: honest failure.

package/test/server.test.js

@@ -15,8 +15,7 @@ const { test } = require('node:test');
 const http = require('node:http');
 const path = require('node:path');
 const { createServer } = require('../server/index.js');
-const { ENVELOPE_KEYS, scratchDir, withEnv } = require('./helpers');
-
+const { ENVELOPE_KEYS, scratchDir, withEnv, needsV2Tree } = require('./helpers');
 // The in-process server's core reads the parent env: keep the idempotency
 // store hermetic for the whole file (each test file is its own process).
 const serverScratch = scratchDir('server');
@@ -59,7 +58,7 @@ function assertEnvelopeShape(t, env, action) {
   if (action !== undefined) t.assert.strictEqual(env.action, action);
 }
 
-test('GET /health -> 200 with version and subsystem map', async (t) => {
+test('GET /health -> 200 with version and subsystem map', needsV2Tree, async (t) => {
   const { server, port } = await startServer();
   try {
     const r = await request(port, 'GET', '/health');
@@ -134,7 +133,7 @@ test('unknown route -> 404', async (t) => {
   }
 });
 
-test('disabled subsystem over HTTP -> 503, honest envelope', async (t) => {
+test('disabled subsystem over HTTP -> 503, honest envelope', needsV2Tree, async (t) => {
   const { server, port } = await startServer();
   try {
     const r = await request(port, 'POST', '/resolve', { body: { evidence: {} } });
@@ -147,7 +146,7 @@ test('disabled subsystem over HTTP -> 503, honest envelope', async (t) => {
   }
 });
 
-test('settlement UNKNOWN over HTTP -> 409 with fail-closed envelope', async (t) => {
+test('settlement UNKNOWN over HTTP -> 409 with fail-closed envelope', needsV2Tree, async (t) => {
   await withEnv({ PAYLOAD_SETTLEMENT_RESOLVER: '1' }, async () => {
     const { server, port } = await startServer();
     try {