callx402 1.0.2 → 1.0.4

package/.github/workflows/npm-publish.yml

@@ -15,14 +15,14 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - run: npm install -g npm@latest
       - uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '22'
           registry-url: 'https://registry.npmjs.org'
-
-      - run: npm install
+      - run: npm install -g npm@latest
+      - run: npm ci --no-audit --no-fund
       - run: npm test
+      - run: npm pack --dry-run
 
 
       - name: Publish to npm via Trusted Publishing (OIDC, no token)

package/.github/workflows/review-ci.yml

@@ -0,0 +1,24 @@
+name: callx402 Review Tests (no live payments)
+on:
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - run: npm ci
+      - run: npm test
+      - run: node --check core/rail.js
+      - run: node --check core/payer-auth.js
+      - run: node --check bin/callx402.js
+      - name: Validate package/lockfile version parity
+        run: node -e "const p=require('./package.json');const l=require('./package-lock.json');if(p.version!==l.version||p.version!==l.packages[''].version)process.exit(1)"
+      - name: Verify npm release archive without publishing
+        run: npm pack --dry-run

package/README.md

@@ -301,30 +301,106 @@ read-only diagnostic server-side and returns the result**. No local setup, no
 separate tree, no keys. The rail never fakes execution: every result is
 produced by the diagnostic modules over the evidence you supply.
 
-The quote-before-payment flow, verified live:
+The hosted quote-before-payment flow:
 
 ```sh
-# 1. Free quote: exact price before anything is paid
+# 1. Obtain a free quote. No money moves.
 curl "https://payload-rail.fly.dev/v1/callx402/quote?action=resolve&path=x402"
-# -> {"quote_id":"...","quoted_price_usd":"0.25", ...}
 
-# 2. Invoke unauthenticated -> x402 v2 402 with the exact payment terms
-curl -X POST https://payload-rail.fly.dev/v1/callx402/actions/resolve \
-  -H 'Content-Type: application/json' -d '{"evidence":"{...}"}'
-# -> HTTP 402: exact USDC amount on Base, pay-to address, 300s window, quote_id
+# 2. Run the interactive client. Pay explicitly by card or with USDC.
+#    For USDC redemption, the paying wallet must EIP-191-sign the exact
+#    authorization message displayed by the CLI.
+callx402 resolve --evidence '{"txHash":"0x..."}'
 
-# 3. Pay deliberately from an authorized wallet, then retry with {txHash, quote_id}
+# 3. Agents with an external wallet-produced signature can redeem the
+#    ORIGINAL canonical quote with a signed authorization file:
+callx402 resolve --evidence '{"txHash":"0x..."}' \
+  --tx-hash 0xYOUR_SETTLED_PAYMENT_HASH \
+  --payer-auth @signed-auth.json --approve
 ```
 
+A public transaction hash alone never authorizes an action. The signed authorization
+binds the paying wallet, action, transaction hash, quote, recipient, network,
+and request inputs. Keep the original `quote_inputs` with the signed authorization;
+requesting a new quote does not authorize an older payment. **Never give Payload
+a private key, seed phrase, or wallet recovery phrase.** EIP-1271 contract-wallet
+redemption is not currently enabled. Stripe credits use a separate redemption path.
+
 Live fee schedule: `GET https://payload-rail.fly.dev/v1/callx402/actions`
 (responds `"model":"paid on-demand per action; no subscription required"`).
-The x402-path price is the Stripe-path fee divided by 20 — for example
-`resolve` is $5.00 via Stripe, $0.25 via the x402 path. Never blind-retry a
-payment to reach a paid action: get the quote first.
+There are two prices per action, and they are not interchangeable: the
+**card price** is the Stripe schedule fee; the **USDC price** on the x402
+path is exactly that fee divided by 20 (the free quote endpoint is the
+source of truth for the USDC column). Both, side by side:
+
+| Action | Card (Stripe) | USDC (x402 path) |
+|---|---|---|
+| `diagnose` | $2.00 | $0.10 |
+| `explain` | $1.00 | $0.05 |
+| `evidence` | $2.00 | $0.10 |
+| `recover` | $10.00 | $0.50 |
+| `resolve` | $5.00 | $0.25 |
+| `preflight` | $3.00 | $0.15 |
+| `settlement_interpretation` | $3.00 | $0.15 |
+| `failure_classification` | $2.00 | $0.10 |
+| `duplicate_payment_risk` | $5.00 | $0.25 |
+
+Rail `evidence` and `explain` read back a prior paid invocation (the
+request carries that invocation's `invocation_id`), so they cannot be used
+cold; the free local forms read your local operation ledger instead.
+
+**Not sold on the rail:** `safe_retry`, `rescue`, `monitor`, and `execute`
+are local-only. They run in the self-hosted runtime (v2.0.0 tree), are
+absent from the rail catalog above, and the rail refuses them with
+`422 HOSTED_ACTION_UNAVAILABLE` — there is no Stripe or x402 purchase path
+for them. For the "is this retry safe?" question, the free local `recover`
+verdict is the available read-only answer.
+
+Never blind-retry a payment to reach a paid action: get the quote first.
 
 Problem to action map (which paid action answers which failure, with the free
 CLI/MCP path for each): [`docs/problem-map.md`](docs/problem-map.md).
 
+## Public RevRule evaluation (0.01 USDC)
+
+The rail also exposes one public RevRule evaluation endpoint. It is a
+RevRule demo, not a callx402 diagnostic action:
+`POST https://payload-rail.fly.dev/v1/x402/public/evaluate` evaluates one
+economic event against the fixed, transparent public demo graph (platform
+5% of gross; creator 70% of the remainder; referrer 25% of the remainder
+when a referrer is named in the event) for 0.01 USDC on Base.
+
+The full, correct request body is:
+
+```json
+{
+  "event": {
+    "eventId": "my-event-001",
+    "type": "SALE_COMPLETED",
+    "rail": "stripe",
+    "amountMicros": 100000000,
+    "currency": "USD",
+    "occurredAt": "2026-10-13T00:00:00.000Z"
+  },
+  "txHash": "0x<your settled 0.01 USDC payment on Base>"
+}
+```
+
+- `event.eventId` (any unique non-empty string) and `event.rail` are
+  **required**, even though the 402's advertised bazaar schema omits both.
+  Valid `rail` values: `stripe`, `ach`, `x402`, `manual`, `stablecoin`.
+- `event.type` must be one of: `SALE_COMPLETED`, `API_PAYMENT`,
+  `LICENSE_PAID`, `SUBSCRIPTION_PAYMENT`, `REFERRAL_CONVERTED`,
+  `ROYALTY_RECEIVED`, `CAMPAIGN_MILESTONE`, `MARKETPLACE_TRANSACTION`,
+  `TOUCH`.
+- The event is validated **before** payment: a malformed body gets
+  `400 INVALID_EVENT`, not a 402 (verified live: the body above, minus
+  `txHash`, returns the 402). The endpoint fills in the rest itself —
+  `graphId` is fixed to the public demo graph, and `currency` defaults to
+  `"USD"` and `occurredAt` to now when omitted.
+- Omit `txHash` to receive the x402 v2 `402` challenge; pay 0.01 USDC,
+  then retry the same body with the hash. Each txHash is single-use.
+
 ## Integrations
 
 Working entry points for agent frameworks, automation, MCP clients, and x402

package/bin/callx402.js

@@ -222,9 +222,11 @@ never executes, never repays. Requires PAYLOAD_VEYLINE_RECOVERY=1.
 
 This is the read-only answer to "is a retry safe?" — a SAFE_RETRY verdict
 here is advisory; performing the safe action stays with your own adapters.
-For the paid one-off verdict on a specific retry plan, use the 'safe_retry'
-rail action (quote first, then pay; see docs/problem-map.md). The MCP tool
-x402_recover covers the same free diagnostic.
+There is NO paid rail form of 'safe_retry': the hosted rail refuses it as
+local-only (it is absent from the rail catalog and cannot be bought via
+Stripe or x402). This free recover verdict is the read-only answer
+available without the self-hosted runtime tree (see docs/problem-map.md).
+The MCP tool x402_recover covers the same free diagnostic.
 
 Exit codes: 0 ok · 1 failure · 2 usage (missing identity/evidence) ·
 3 disabled/unreachable · 4 budget refused ·
@@ -256,14 +258,16 @@ Usage:
   callx402 "natural language intent"        intent mode (plans, never executes blindly)
   callx402 --help | --version
 
-Commands (hosted by default — zero setup):
+Commands (rail actions hosted by default — zero setup; local-only
+commands marked, they need the v2.0.0 runtime tree and are NOT sold on
+the hosted rail):
   diagnose    run the x402 doctor over supplied evidence        [--target <url|json>] [--evidence <json|@file>]
-  rescue      incident triage (auth-gated; read-only without auth) --incident <id>
+  rescue      incident triage, local only (auth-gated; read-only without auth) --incident <id>
   route       select a tool/route for a goal                   --goal <text>
   resolve     resolve settlement state from evidence           --evidence <json|@file>
   doctor      alias of diagnose
-  execute     run the intent pipeline                          --intent <text> [--max-budget N] [--dry-run] [--idempotency-key K]
-  monitor     sentinel snapshot [--once] or stream [--watch]
+  execute     run the intent pipeline, local only              --intent <text> [--max-budget N] [--dry-run] [--idempotency-key K]
+  monitor     sentinel snapshot, local only [--once] or stream [--watch]
   status      per-subsystem reachable/enabled/version report
   preflight   run MCP preflight checks
   inspect     capability-graph lookup/stats                    [--query <text>]
@@ -305,6 +309,7 @@ function parseArgv(argv) {
   const KNOWN_FLAGS = new Set([
     'help', 'version', 'json', 'timeout', 'maxBudget', 'approvalThreshold',
     'idempotencyKey', 'evidence', 'incident', 'goal', 'intent', 'query',
+    'txHash', 'payerAuth', 'creditId',
     'target', 'speed', 'interval', 'network', 'networks', 'asset', 'assets',
     'providers', 'deadline', 'risk',
     'dryRun', 'approve', 'forceRetry', 'retry', 'auth', 'watch', 'once',
@@ -324,7 +329,8 @@ function parseArgv(argv) {
         i += 1;
         continue;
       }
-      const NEEDS_VALUE = new Set(['timeout', 'maxBudget', 'approvalThreshold', 'idempotencyKey', 'evidence', 'incident', 'goal', 'intent', 'query', 'target', 'speed', 'interval', 'network', 'networks', 'asset', 'assets', 'providers', 'deadline', 'risk', 'dir', 'operationId', 'identity']);
+      const NEEDS_VALUE = new Set(['timeout', 'maxBudget', 'approvalThreshold', 'idempotencyKey', 'evidence', 'incident', 'goal', 'intent', 'query', 'target',
+        'txHash', 'payerAuth', 'creditId', 'speed', 'interval', 'network', 'networks', 'asset', 'assets', 'providers', 'deadline', 'risk', 'dir', 'operationId', 'identity']);
       if (NEEDS_VALUE.has(name)) {
         if (val !== null) out.flags[name] = val;
         else if (i + 1 < argv.length && !argv[i + 1].startsWith('-')) out.flags[name] = argv[++i];
@@ -503,7 +509,9 @@ async function main() {
     // payment/authorization -> result. Set CALLX402_LOCAL=1 to prefer the
     // local v2.0.0 runtime tree instead (advanced self-hosted mode).
     if (rail.isRailCommand(actionName) && !rail.preferLocal()) {
-      const railResult = await rail.invokeRail(actionName, args, { yes: args.approve, json: args.json });
+      const railResult = await rail.invokeRail(actionName,
+        { ...args, txHash: flags.txHash, payerAuth: flags.payerAuth, creditId: flags.creditId },
+        { yes: args.approve, json: args.json });
       if (args.json) {
         console.log(JSON.stringify(railResult, null, 2));
       } else if (railResult.ok) {

package/core/payer-auth.js

@@ -0,0 +1,59 @@
+'use strict';
+
+/**
+ * The client never signs messages or accepts wallet private keys.
+ * An external wallet signs the EIP-191 message and supplies a 65-byte signature.
+ * This canonical message MUST remain in lockstep with Rail payer-auth.ts.
+ */
+const fs = require('node:fs');
+const { createHash } = require('node:crypto');
+const path = require('node:path');
+
+function actionRequestHash(action, body) {
+  const data = {
+    action,
+    evidence: body.evidence ?? null,
+    invocation_id: body.invocation_id ?? null,
+    context: body.context ?? null,
+    operation_id: body.operation_id ?? null,
+    target: body.target ?? null,
+    identity: body.identity ?? null,
+  };
+  return '0x' + createHash('sha256').update(JSON.stringify(data), 'utf8').digest('hex');
+}
+
+function buildAuthMessage(auth) {
+  return [
+    'Payload x402 Authorization',
+    `wallet:${String(auth.wallet).toLowerCase()}`,
+    `action:${auth.action}`,
+    `txHash:${String(auth.txHash).toLowerCase()}`,
+    `quote_id:${auth.quote_id}`,
+    `request_hash:${auth.request_hash}`,
+    `network:${auth.network}`,
+    `recipient:${String(auth.recipient).toLowerCase()}`,
+    `nonce:${auth.nonce}`,
+    `expiry:${auth.expiry}`,
+  ].join('\n');
+}
+
+function readSignedAuthorization(value) {
+  if (!value || typeof value !== 'string') throw new Error('payer authorization JSON or @file required');
+  const raw = value.startsWith('@') ?
+    fs.readFileSync(path.resolve(value.slice(1)), 'utf8') : value;
+  const obj = JSON.parse(raw);
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) throw new Error('expected an object');
+  if (!/^0x[0-9a-fA-F]{40}$/.test(obj.wallet || '')) throw new Error('invalid wallet');
+  if (!/^0x[0-9a-fA-F]{64}$/.test(obj.txHash || '')) throw new Error('invalid txHash');
+  if (!/^0x[0-9a-fA-F]{40}$/.test(obj.recipient || '')) throw new Error('invalid recipient');
+  if (!/^0x[0-9a-fA-F]{64}$/.test(obj.request_hash || '')) throw new Error('invalid action request hash');
+  if (!/^0x[0-9a-fA-F]{130}$/.test(obj.signature || '')) throw new Error('invalid EIP-191 signature');
+  if (typeof obj.action !== 'string' || typeof obj.network !== 'string' ||
+      typeof obj.quote_id !== 'string' || typeof obj.nonce !== 'string' ||
+      !Number.isSafeInteger(obj.expiry) || obj.expiry <= Math.floor(Date.now() / 1000)) {
+    throw new Error('malformed or expired authorization fields');
+  }
+  return obj;
+}
+
+module.exports = { buildAuthMessage, actionRequestHash, readSignedAuthorization };

package/core/rail.js

@@ -18,12 +18,13 @@
  * Nothing here signs, holds keys, or moves money.
  */
 
+const { randomBytes } = require('node:crypto');
+const { buildAuthMessage, actionRequestHash, readSignedAuthorization } = require('./payer-auth.js');
 const RAIL_BASE = process.env.CALLX402_RAIL || 'https://payload-rail.fly.dev';
 const RAIL_ACTIONS = [
-  'diagnose', 'doctor', 'rescue', 'route', 'resolve', 'execute', 'monitor',
-  'preflight', 'inspect', 'evidence', 'explain', 'recover',
-  'settlement_interpretation', 'safe_retry', 'failure_classification',
-  'duplicate_payment_risk',
+  'diagnose', 'doctor', 'resolve', 'preflight',
+  'evidence', 'explain', 'recover',
+  'settlement_interpretation', 'failure_classification', 'duplicate_payment_risk',
 ];
 
 // Map CLI command names to rail action names.
@@ -120,12 +121,27 @@ async function invokeRail(command, args, opts = {}) {
   const evidence = buildEvidence(action, args);
   const interactive = process.stdin.isTTY && !opts.yes;
 
-  // 1. Free quote first.
+  // 1. Fresh quote for new actions; previously paid agent redemptions
+  // must reuse their ORIGINAL signed quote. A fresh quote has a different
+  // issuedAt/quote_id and would invalidate an otherwise authentic signature.
   let quote;
+  let signedAuthorization = null;
   try {
-    quote = await getQuote(action);
+    if (args.txHash && args.payerAuth) {
+      signedAuthorization = readSignedAuthorization(String(args.payerAuth));
+      if (!signedAuthorization.quote_inputs || typeof signedAuthorization.quote_inputs !== 'object') {
+        throw new Error('Signed authorization file must include the canonical quote_inputs from the original quote.');
+      }
+      quote = {
+        quote_id: signedAuthorization.quote_id,
+        quote_inputs: signedAuthorization.quote_inputs,
+        quoted_price_usd: signedAuthorization.quoted_price_usd ?? 'see signed quote',
+      };
+    } else {
+      quote = await getQuote(action);
+    }
   } catch (err) {
-    return { ok: false, error: `Could not reach the hosted rail for a free quote: ${err.message}` };
+    return { ok: false, error: `Unable to load a valid payment quote: ${err.message}` };
   }
   const price = quote.quoted_price_usd;
   const quoteId = quote.quote_id;
@@ -140,8 +156,8 @@ async function invokeRail(command, args, opts = {}) {
     if (!interactive) {
       return {
         ok: false,
-        error: `Payment of $${price} required. Re-run with --yes to approve non-interactively, or run interactively.`,
-        quote: { action, price_usd: price, quote_id: quoteId },
+        error: `Payment of $${price} required. Re-run with --approve to approve non-interactively, or run interactively.`,
+        quote: { action, price_usd: price, quote_id: quoteId, quote_inputs: quote.quote_inputs },
       };
     }
     const approve = await prompt(`  Approve $${price} for '${action}'? [y/N] `);
@@ -151,17 +167,52 @@ async function invokeRail(command, args, opts = {}) {
   }
 
   // 3. Payment: x402 (paste tx hash) or card (browser checkout -> credit ID).
-  let payBody = { evidence, quote_id: quoteId, quote };
-  if (!interactive) {
+  let payBody = { evidence, quote_id: quoteId, quote: quote.quote_inputs || {} };
+  if ((action === 'evidence' || action === 'explain') && args.operationId) {
+    payBody.invocation_id = String(args.operationId);
+  }
+  // Agents can supply a wallet-produced EIP-191 signature through a file;
+  // private keys are never requested or handled by callx402.
+  if (args.creditId) {
+    payBody = { ...payBody, credit_id: String(args.creditId) };
+  } else if (args.txHash && args.payerAuth) {
+    if (!quote.quote_inputs) return { ok: false, error: 'Rail must return canonical quote_inputs before signed redemption.' };
+    const auth = signedAuthorization;
+    if (auth.txHash?.toLowerCase() !== String(args.txHash).toLowerCase() ||
+        auth.action !== action || auth.quote_id !== quoteId ||
+        auth.request_hash !== actionRequestHash(action, payBody)) {
+      return { ok: false, error: 'Signed authorization does not match the transaction, action, and current quote.' };
+    }
+    payBody = { ...payBody, txHash: String(args.txHash).toLowerCase(), payer_auth: auth };
+  }
+  if (!payBody.credit_id && !payBody.payer_auth && !interactive) {
     return {
       ok: false,
-      error: 'Interactive payment required.',
+      error: 'Non-interactive payment requires --credit-id or --tx-hash with --payer-auth @file.',
       quote: { action, price_usd: price, quote_id: quoteId },
-      payment_instructions: `POST ${RAIL_BASE}/v1/callx402/actions/${action} with { evidence, quote_id, quote } to receive a 402, pay, then re-POST with { txHash } or { credit_id }.`,
+      payment_instructions: `Use --credit-id or --tx-hash plus --payer-auth @signed-auth.json after an authorized wallet signature; a bare txHash is never enough.`,
     };
   }
+  if (!payBody.credit_id && !payBody.payer_auth) {
   const method = await prompt('  Pay with [1] USDC on Base (paste tx hash after paying) or [2] card via browser? [1/2] ');
   if (method === '2') {
+    // Stripe is a distinct price path; never imply its fee equals the
+    // previously displayed micropayment quote.
+    let cardPrice;
+    try {
+      const catalog = await railFetch('/v1/callx402/actions');
+      const item = catalog.body?.actions?.find(a => a.action === action);
+      if (catalog.status !== 200 || !Number.isSafeInteger(item?.amount_cents) || item.amount_cents <= 0) {
+        throw new Error('card fee not available');
+      }
+      cardPrice = (item.amount_cents / 100).toFixed(2);
+    } catch {
+      return { ok: false, error: 'Could not confirm the exact card price. Checkout cancelled before payment.' };
+    }
+    const cardApproval = await prompt(`  Card checkout total $ ${cardPrice} USD for '${action}'. Continue? [y/N] `);
+    if (!/^y(es)?$/i.test(cardApproval)) {
+      return { ok: false, error: 'Card checkout cancelled before payment.' };
+    }
     // Stripe checkout path.
     const { status, body } = await railFetch('/v1/callx402/checkout', {
       method: 'POST',
@@ -179,10 +230,11 @@ async function invokeRail(command, args, opts = {}) {
     if (!creditId) return { ok: false, error: 'No credit ID provided.' };
     payBody = { ...payBody, credit_id: creditId };
   } else {
+    if (!quote.quote_inputs) return { ok: false, error: 'Rail must return canonical quote_inputs before USDC payment.' };
     // x402 path: get exact payment terms from the 402, then user pays.
     const { status, body } = await railFetch(`/v1/callx402/actions/${action}`, {
       method: 'POST',
-      body: JSON.stringify({ evidence, quote_id: quoteId, quote }),
+      body: JSON.stringify({ evidence, quote_id: quoteId, quote: quote.quote_inputs }),
     });
     if (status !== 402) {
       return { ok: false, error: `Expected a 402 payment challenge, got HTTP ${status}.` };
@@ -196,7 +248,33 @@ async function invokeRail(command, args, opts = {}) {
     if (!/^0x[0-9a-fA-F]{64}$/.test(txHash)) {
       return { ok: false, error: 'Invalid transaction hash format.' };
     }
-    payBody = { ...payBody, txHash: txHash.toLowerCase() };
+    const wallet = await prompt('  Payer wallet address (0x...): ');
+    if (!/^0x[0-9a-fA-F]{40}$/.test(wallet)) {
+      return { ok: false, error: 'A valid Ethereum payer wallet address is required.' };
+    }
+    const auth = {
+      wallet, action, txHash: txHash.toLowerCase(), quote_id: quoteId,
+      request_hash: actionRequestHash(action, payBody),
+      network: accept.network || 'eip155:8453',
+      recipient: accept.payTo,
+      nonce: '0x' + randomBytes(16).toString('hex'),
+      expiry: Math.floor(Date.now() / 1000) + 300,
+    };
+    if (!/^0x[0-9a-fA-F]{40}$/.test(auth.recipient || '')) {
+      return { ok: false, error: 'The payment challenge omitted a valid recipient; refusing redemption.' };
+    }
+    const signingMessage = buildAuthMessage(auth);
+    console.log('\n  Sign the exact message below using your paying wallet (EIP-191 personal_sign).');
+    console.log('  NEVER paste a seed phrase, private key, or recovery code.\n');
+    console.log(signingMessage);
+    console.log();
+    const signature = await prompt('  Paste wallet signature (0x...): ');
+    if (!/^0x[0-9a-fA-F]{130}$/.test(signature)) {
+      return { ok: false, error: 'Expected a 65-byte Ethereum personal_sign signature.' };
+    }
+    payBody = { ...payBody, txHash: txHash.toLowerCase(),
+      payer_auth: { ...auth, signature } };
+  }
   }
 
   // 4. Submit payment proof -> verified, executed, metered -> result.
@@ -207,6 +285,12 @@ async function invokeRail(command, args, opts = {}) {
   if (status === 402) {
     return { ok: false, error: 'Payment not yet recognized. The quote may have expired — re-run to get a fresh quote.' };
   }
+  if (status === 401) {
+    return { ok: false, error: `Wallet authorization rejected: ${body?.error?.message || 'check signed message and wallet'}` };
+  }
+  if (status === 422) {
+    return { ok: false, error: `Action could not execute: ${body?.error?.message || body?.execution?.error || 'not available'}` };
+  }
   if (status === 409) {
     return { ok: false, error: `Already used: ${body?.error?.message || 'this payment was already consumed'}.` };
   }

package/core/subsystems.js

@@ -52,6 +52,14 @@ const NOTES = {
   recovery: 'File-backed idempotency store used for duplicate-idempotencyKey dedupe.',
 };
 
+/** First line only: Node require errors append a multi-line "Require stack:"
+ * dump that helps nobody in a status report or an MCP tool result. The short
+ * form still names the missing module and stays actionable. */
+function briefError(err) {
+  const msg = err && err.message ? String(err.message) : String(err || 'unknown error');
+  return msg.split('\n')[0].trim();
+}
+
 function defaultV2Root() {
   return path.resolve(__dirname, '../../x402-paid-api-starter-kit/v2.0.0');
 }
@@ -98,7 +106,7 @@ function getSubsystem(name, { config = {}, deps = {} } = {}) {
   try {
     mod = requireFiles(v2Root, MODULE_FILES[name]);
   } catch (err) {
-    return { name, reachable: false, module: null, enabled: false, flag: null, version: null, note: NOTES[name] || null, subsystemStatus: 'unreachable', error: `require failed: ${err.message}` };
+    return { name, reachable: false, module: null, enabled: false, flag: null, version: null, note: NOTES[name] || null, subsystemStatus: 'unreachable', error: `require failed: ${briefError(err)}` };
   }
 
   let flag = null;
@@ -107,7 +115,7 @@ function getSubsystem(name, { config = {}, deps = {} } = {}) {
     flag = typeof mod.FLAG === 'string' ? mod.FLAG : null;
     enabled = typeof mod.enabled === 'function' ? mod.enabled() : false;
   } catch (err) {
-    return { name, reachable: true, module: mod, enabled: false, flag, version: null, note: NOTES[name] || null, subsystemStatus: 'disabled', error: `enabled() check failed: ${err.message}` };
+    return { name, reachable: true, module: mod, enabled: false, flag, version: null, note: NOTES[name] || null, subsystemStatus: 'disabled', error: `enabled() check failed: ${briefError(err)}` };
   }
 
   const version = mod.version || mod.RESCUE_VERSION || mod.EFFECT_PROOF_VERSION || null;

package/docs/problem-map.md

@@ -25,7 +25,13 @@ 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.
+exists only as a paid rail action. "Local only" means the opposite: the action
+exists ONLY locally (self-hosted runtime tree). The hosted rail refuses it
+with `422 HOSTED_ACTION_UNAVAILABLE`, it is absent from the rail catalog
+(`GET /v1/callx402/actions` lists nine actions), and there is no Stripe or
+x402 purchase path for it. Four actions are local-only: `safe_retry`,
+`rescue`, `monitor`, `execute`. Their fee cells below show the schedule
+figure for reference only — it cannot be paid on the rail.
 
 **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
@@ -40,16 +46,16 @@ deterministic, not an estimate.
 | 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 |
+| 4 | Retry uncertainty, narrowed — is THIS specific retry safe to sign? | `safe_retry` | $5.00 (local only — not purchasable on the rail) | local only (self-hosted runtime; no CLI command in this package and no rail purchase path — 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 |
+| 11 | Rescue a failed transaction — triage and recover the incident end to end | `rescue` | $15.00 (local only — not purchasable on the rail) | `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 (local only — not purchasable on the rail) | `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 (local only — not purchasable on the rail) | `callx402 execute --intent ... --dry-run` (plans only) | Over-budget intents refused with zero side effects |
 
 ## Where each surface consumes this map
 
@@ -70,9 +76,14 @@ deterministic, not an estimate.
 ## Notes
 
 - Action names are canonical in `snake_case`. The rail also accepts the
-  hyphenated aliases shown in the OpenAPI enum (`safe-retry`,
-  `duplicate-payment-risk`, `settlement-interpretation`,
-  `failure-classification`); both forms resolve identically (verified live).
+  hyphenated aliases shown in the OpenAPI enum (`duplicate-payment-risk`,
+  `settlement-interpretation`, `failure-classification`); both forms resolve
+  identically (verified live). `safe-retry` is not a rail action in either
+  spelling — it is local-only (see the two-tiers note above).
+- Rail `evidence` / `explain` read back a PRIOR paid invocation: the request
+  must carry that invocation's `invocation_id`, and the rail returns
+  `400 MISSING_INPUT` without one, so they cannot be used cold. The free
+  local forms in the map read your local operation ledger instead.
 - The x402-path quote is the valuation-layer quote, not the raw schedule;
   the fixed schedule above is the Stripe-path floor.
 - Local CLI / MCP-stdio diagnostics are free and read-only — no payment, no

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/integrations/core.py

@@ -5,7 +5,7 @@ Plain functions (no framework imports) so LangChain, CrewAI, AutoGen, or any
 agent framework can wrap them directly. stdlib only.
 
 The rail's public endpoints:
-  GET  /v1/callx402/actions            free — live 13-action fee schedule
+  GET  /v1/callx402/actions            free — live fee schedule (9 hosted actions)
   GET  /v1/callx402/quote              free — deterministic pre-execution quote
   POST /v1/callx402/actions/{action}   paid — unauthenticated -> x402 v2 402
                                        (USDC on Base); credit_id / txHash /
@@ -30,6 +30,13 @@ RAIL = os.environ.get("CALLX402_RAIL", "https://payload-rail.fly.dev").rstrip("/
 
 # Canonical action names (snake_case), verified live 2026-10-07.
 # Hyphenated aliases are also accepted by the rail; these are canonical.
+# AVAILABILITY (verified live 2026-10-13): only 9 of these 13 are hosted and
+# purchasable on the rail — diagnose, explain, evidence, recover, resolve,
+# preflight, settlement_interpretation, failure_classification,
+# duplicate_payment_risk. The other four (safe_retry, rescue, monitor,
+# execute) are LOCAL-ONLY: the rail refuses them with
+# 422 HOSTED_ACTION_UNAVAILABLE, they are absent from the rail catalog, and
+# they cannot be bought via Stripe or x402.
 ACTIONS = (
     "diagnose", "explain", "evidence", "recover", "resolve", "preflight",
     "monitor", "execute", "rescue", "settlement_interpretation", "safe_retry",
@@ -303,7 +310,9 @@ FREE_LOCAL_ALTERNATIVE = (
     "Local CLI / MCP-stdio diagnostics are free and read-only "
     "(git clone https://github.com/Payloadhq/callx402; "
     "node mcp/index.js as an MCP server). The paid rail actions above are "
-    "for hosted on-demand invocation with payment."
+    "for hosted on-demand invocation with payment. Note: safe_retry, "
+    "rescue, monitor, and execute are local-only and are NOT purchasable "
+    "on the hosted rail."
 )
 
 

package/integrations/langchain/callx402_tools.py

@@ -125,8 +125,11 @@ def callx402_explain(operation_id: str) -> str:
 def callx402_safe_retry(retry_plan: str) -> str:
     """Go/no-go verdict on ONE specific retry plan before anything is signed.
     Use when a retry is being considered and must be proven safe first.
-    Paid on-demand ($5.00 via Stripe). A retry that would double-pay is
-    refused."""
+    AVAILABILITY: safe_retry is LOCAL-ONLY — the hosted rail refuses it
+    (422 HOSTED_ACTION_UNAVAILABLE) and it cannot be bought via Stripe or
+    x402, so this tool currently surfaces that refusal. For the
+    retry-safety question today, use callx402_recover's read-only verdict.
+    A retry that would double-pay is refused."""
     return _render(invoke("safe_retry", {"retry_plan": retry_plan}, **_auth()))
 
 

package/mcp/index.js

@@ -18,13 +18,21 @@
  * Only read-only / diagnostic actions are exposed. Actions with side effects
  * (execute, rescue mutations) are intentionally NOT tools here.
  *
+ * Honest surface: ONLY x402_status works on a bare install of this package.
+ * The other five tools dispatch into the v2.0.0 subsystem tree (the x402
+ * Paid API Starter Kit — a separate product that is NOT bundled here) and
+ * return `subsystem_unreachable` until CALLX402_V2_ROOT points at that tree
+ * and the matching feature flag is enabled. These tools never call the
+ * hosted rail; paid hosted equivalents live at
+ * https://payloadhq.github.io/agents.json.
+ *
  * Usage (Claude Desktop / MCP client config):
  *   { "command": "node", "args": ["/path/to/callx402/mcp/index.js"] }
  * Env: CALLX402_CONFIG, CALLX402_V2_ROOT, CALLX402_TIMEOUT_MS (default 30000).
  */
 const readline = require('node:readline');
 
-const VERSION = '1.0.2';
+const VERSION = '1.0.4';
 const PROTOCOL_VERSION = '2024-11-05';
 const SERVER_NAME = 'callx402';
 const TIMEOUT_MS = Number(process.env.CALLX402_TIMEOUT_MS || 30000);
@@ -34,7 +42,29 @@ const core = require(process.env.CALLX402_CORE_PATH ||
 
 /* ------------------------------------------------------------------ */
 /* Tool definitions: name, description, input schema, core action.     */
+/*                                                                     */
+/* Requirement trailers, stated in every description because the       */
+/* description is what an MCP client actually shows the user:          */
+/*   TREE_REQUIRED — dispatches into the v2.0.0 subsystem tree, which  */
+/*     is NOT part of this package.                                    */
+/*   LEDGER_REQUIRED — reads the local Veyline operation ledger via    */
+/*     modules that are likewise not bundled here.                     */
 /* ------------------------------------------------------------------ */
+const TREE_REQUIRED =
+  ' Requires the v2.0.0 subsystem tree (x402 Paid API Starter Kit, a separate ' +
+  'product that is NOT included in this package): set CALLX402_V2_ROOT to the ' +
+  'tree and enable the subsystem flag, or this tool returns ' +
+  'subsystem_unreachable and does nothing. With the tree configured it is free ' +
+  'and read-only: no payment, no auth. A paid hosted equivalent runs on the ' +
+  'Payload rail — see https://payloadhq.github.io/agents.json.';
+const ledgerRequired = (flag) =>
+  ' Requires the local Veyline ledger modules (NOT included in this package; ' +
+  `enable with ${flag}=1 where the ledger lives) and reads ` +
+  'operations recorded on THIS machine — it cannot read back hosted rail ' +
+  'invocations. Until configured it returns subsystem_unreachable and does ' +
+  'nothing. When configured it is free and read-only: no payment, no auth.';
+const LEDGER_REQUIRED = ledgerRequired('PAYLOAD_VEYLINE_LEDGER');
+
 const TOOLS = [
   {
     name: 'x402_diagnose',
@@ -43,8 +73,8 @@ const TOOLS = [
       'Run the x402 doctor over supplied evidence. Use when something went ' +
       'wrong with an x402 payment or MCP/x402 interaction and you need a ' +
       'diagnosis. Input: evidence as a JSON string or object describing the ' +
-      'failure (error strings, responses, tx hashes). Read-only. ' +
-      ' Free read-only diagnostic surface: no payment, no auth, never Veyline-gated. For the paid on-demand callx402 action path, see https://payloadhq.github.io/agents.json.', 
+      'failure (error strings, responses, tx hashes). Read-only.' +
+      TREE_REQUIRED,
     inputSchema: {
       type: 'object',
       properties: {
@@ -66,8 +96,8 @@ const TOOLS = [
     description:
       'Show recorded ledger evidence for an operation: event trail, latest ' +
       'per-plane states (payment / execution / delivery), protocols involved. ' +
-      'Use FIRST in any incident — establishes ground truth before acting. Read-only. ' +
-      ' Free read-only diagnostic surface: no payment, no auth, never Veyline-gated. For the paid on-demand callx402 action path, see https://payloadhq.github.io/agents.json.', 
+      'Use FIRST in any incident — establishes ground truth before acting. Read-only.' +
+      LEDGER_REQUIRED,
     inputSchema: {
       type: 'object',
       properties: {
@@ -84,8 +114,8 @@ const TOOLS = [
       'Explain an operation\'s state in plain language from recorded evidence. ' +
       'Returns an assessment: NO_BASIS, INCOMPLETE (do not retry, do not repay), ' +
       'KNOWN_SAFE, RECOVERY_CANDIDATE, or PARTIAL. Use to understand an incident ' +
-      'before deciding whether to retry, refund, or escalate. Read-only. ' +
-      ' Free read-only diagnostic surface: no payment, no auth, never Veyline-gated. For the paid on-demand callx402 action path, see https://payloadhq.github.io/agents.json.', 
+      'before deciding whether to retry, refund, or escalate. Read-only.' +
+      LEDGER_REQUIRED,
     inputSchema: {
       type: 'object',
       properties: {
@@ -102,8 +132,8 @@ const TOOLS = [
       'Report the safe recovery decision for an operation whose result was lost ' +
       '(paid but no result). READ-ONLY: nothing is charged, nothing is executed. ' +
       'Returns RECOVERABLE/SAFE_RETRY -> KNOWN_SAFE, or HUMAN_REVIEW. Use for ' +
-      'the exact situation where blind retry would double-pay or double-execute. ' +
-      ' Free read-only diagnostic surface: no payment, no auth, never Veyline-gated. For the paid on-demand callx402 action path, see https://payloadhq.github.io/agents.json.',
+      'the exact situation where blind retry would double-pay or double-execute.' +
+      ledgerRequired('PAYLOAD_VEYLINE_RECOVERY'),
     inputSchema: {
       type: 'object',
       properties: {
@@ -119,8 +149,8 @@ const TOOLS = [
     action: 'resolve',
     description:
       'Resolve settlement state from evidence (e.g. settlement_pending: was the ' +
-      'broadcast transaction confirmed on chain?). Use instead of blind retry. Read-only. ' +
-      ' Free read-only diagnostic surface: no payment, no auth, never Veyline-gated. For the paid on-demand callx402 action path, see https://payloadhq.github.io/agents.json.', 
+      'broadcast transaction confirmed on chain?). Use instead of blind retry. Read-only.' +
+      TREE_REQUIRED,
     inputSchema: {
       type: 'object',
       properties: {
@@ -137,8 +167,11 @@ const TOOLS = [
     action: 'status',
     description:
       'Check callx402 subsystem reachability (which diagnostic subsystems are ' +
-      'available). Use to verify the tool is operational before diagnosing. Read-only. ' +
-      ' Free read-only diagnostic surface: no payment, no auth, never Veyline-gated. For the paid on-demand callx402 action path, see https://payloadhq.github.io/agents.json.', 
+      'available). Use to verify the tool is operational before diagnosing. ' +
+      'Read-only. This is the one tool that works with zero setup in any ' +
+      'install — no key, no tree, no payment. On a bare npm install it ' +
+      'honestly reports 0/15 subsystems reachable: the other five tools need ' +
+      'the v2.0.0 subsystem tree (CALLX402_V2_ROOT) before they can answer.',
     inputSchema: { type: 'object', properties: {} },
   },
 ];

package/package.json

@@ -27,6 +27,6 @@
     "smoke": "node bin/callx402.js status --json",
     "test": "node --test test/*.test.js"
   },
-  "version": "1.0.2",
+  "version": "1.0.4",
   "mcpName": "io.github.payload-tools/callx402"
-}
+}

package/server.json

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

package/test/payer-auth.test.js

@@ -0,0 +1,92 @@
+'use strict';
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { buildAuthMessage, actionRequestHash, readSignedAuthorization } = require('../core/payer-auth.js');
+const { invokeRail, isRailCommand } = require('../core/rail.js');
+
+const txHash = '0x' + '22'.repeat(32);
+const wallet = '0x' + '11'.repeat(20);
+const recipient = '0x' + '33'.repeat(20);
+const signature = '0x' + '44'.repeat(65);
+const authorization = () => ({
+  wallet, action: 'resolve', txHash, quote_id: 'q_test',
+  quote_inputs: { action: 'resolve', path: 'x402', issuedAt: 1 }, quoted_price_usd: '0.25',
+  request_hash: actionRequestHash('resolve', { evidence: '{}' }),
+  network: 'eip155:8453', recipient, nonce: 'nonce_unique_1234',
+  expiry: Math.floor(Date.now() / 1000) + 300, signature,
+});
+
+test('client and Rail use canonical EIP-191 signer message', () => {
+  const expected = [
+    'Payload x402 Authorization',
+    'wallet:' + wallet,
+    'action:resolve',
+    'txHash:' + txHash,
+    'quote_id:q_test',
+    'request_hash:' + authorization().request_hash,
+    'network:eip155:8453',
+    'recipient:' + recipient,
+    'nonce:nonce_unique_1234',
+    'expiry:' + authorization().expiry,
+  ].join('\n');
+  assert.equal(buildAuthMessage(authorization()), expected);
+});
+
+test('unsigned, malformed and expired authorizations are rejected before network payment', () => {
+  assert.throws(() => readSignedAuthorization('{}'), /wallet/);
+  const bad = { ...authorization(), expiry: Math.floor(Date.now()/1000) - 1 };
+  assert.throws(() => readSignedAuthorization(JSON.stringify(bad)), /expired/);
+});
+
+test('hosted CLI does not route local-only actions to paid Rail', () => {
+  assert.equal(isRailCommand('execute'), false);
+  assert.equal(isRailCommand('rescue'), false);
+  assert.equal(isRailCommand('resolve'), true);
+});
+
+test('signed noninteractive redemption sends signature, never wallet secrets', async () => {
+  const previous = global.fetch;
+  const requests = [];
+  global.fetch = async (url, init = {}) => {
+    requests.push({ url, init });
+    const quote = String(url).includes('/quote?');
+    const body = quote ? { quoted_price_usd: '0.25', quote_id: 'q_test', quote_inputs: { action: 'resolve', path: 'x402' } } :
+      { ok: true, invocation_id: 'invo_mock', via: 'x402', execution: { executed: true, result: { state: 'UNKNOWN' } } };
+    return { status: 200, text: async () => JSON.stringify(body) };
+  };
+  try {
+    const result = await invokeRail('resolve', {
+      evidence: '{}', txHash, payerAuth: JSON.stringify(authorization()),
+    }, { yes: true, json: true });
+    assert.equal(result.ok, true);
+    assert.equal(requests.length, 1);
+    const body = JSON.parse(requests[0].init.body);
+    assert.deepEqual(body.quote, authorization().quote_inputs);
+    assert.equal(body.txHash, txHash);
+    assert.equal(body.payer_auth.wallet, wallet);
+    assert.equal(body.payer_auth.signature, signature);
+    assert.equal(body.payer_auth.quote_id, 'q_test');
+    assert.equal('privateKey' in body, false);
+  } finally {
+    global.fetch = previous;
+  }
+});
+
+test('stale signature for a different quote fails without submitting a payment proof', async () => {
+  const previous = global.fetch;
+  const requests = [];
+  global.fetch = async (url, init = {}) => {
+    requests.push({ url, init });
+    return { status: 200, text: async () => JSON.stringify({ quoted_price_usd: '0.25', quote_id: 'q_changed', quote_inputs: { action: 'resolve', path: 'x402' } }) };
+  };
+  try {
+    const result = await invokeRail('resolve', {
+      txHash, payerAuth: JSON.stringify({ ...authorization(), action: 'recover' }),
+    }, { yes: true, json: true });
+    assert.equal(result.ok, false);
+    assert.match(result.error, /current quote/);
+    assert.equal(requests.length, 0);
+  } finally {
+    global.fetch = previous;
+  }
+});