callx402 1.0.1 → 1.0.2

package/core/rail.js

@@ -0,0 +1,233 @@
+'use strict';
+
+/**
+ * core/rail.js — lightweight client for the hosted Payload Rail.
+ *
+ * When the v2.0.0 runtime tree is not available locally (or unless
+ * CALLX402_LOCAL=1), subsystem commands route here automatically:
+ *
+ *   invoke -> free quote -> user approves -> payment/authorization -> result
+ *
+ * Payment paths (no wallet required in the CLI):
+ *   - x402: user pays USDC on Base from their own wallet, pastes the tx hash.
+ *   - card: CLI opens the Stripe checkout in a browser; user pastes the
+ *     single-use credit ID from the success page.
+ *
+ * The rail verifies payment exactly once, executes read-only diagnostic
+ * actions server-side, meters the invocation, and returns the result.
+ * Nothing here signs, holds keys, or moves money.
+ */
+
+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',
+];
+
+// Map CLI command names to rail action names.
+const ACTION_ALIASES = { doctor: 'diagnose' };
+
+function railActionFor(command) {
+  return ACTION_ALIASES[command] || command;
+}
+
+function isRailCommand(command) {
+  return RAIL_ACTIONS.includes(command);
+}
+
+/** True when the caller explicitly prefers the local v2 tree. */
+function preferLocal() {
+  return process.env.CALLX402_LOCAL === '1';
+}
+
+async function railFetch(path, opts = {}) {
+  const res = await fetch(`${RAIL_BASE}${path}`, {
+    ...opts,
+    headers: { 'Content-Type': 'application/json', ...(opts.headers || {}) },
+  });
+  const text = await res.text();
+  let body = null;
+  try { body = text ? JSON.parse(text) : null; } catch { body = { _raw: text }; }
+  return { status: res.status, body };
+}
+
+async function getQuote(action) {
+  const { status, body } = await railFetch(
+    `/v1/callx402/quote?action=${encodeURIComponent(action)}&path=x402`,
+  );
+  if (status !== 200 || !body || !body.quoted_price_usd) {
+    throw new Error(`quote unavailable (HTTP ${status})`);
+  }
+  return body;
+}
+
+function prompt(question) {
+  return new Promise((resolve) => {
+    const rl = require('node:readline').createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+function openBrowser(url) {
+  const { execSync } = require('node:child_process');
+  const platform = process.platform;
+  try {
+    if (platform === 'darwin') execSync(`open "${url}"`, { stdio: 'ignore' });
+    else if (platform === 'win32') execSync(`start "" "${url}"`, { stdio: 'ignore' });
+    else execSync(`xdg-open "${url}"`, { stdio: 'ignore' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function buildEvidence(action, args) {
+  // Prefer explicit --evidence JSON (or @file); otherwise assemble from args.
+  if (args.evidence) {
+    const raw = String(args.evidence);
+    if (raw.startsWith('@')) {
+      const fs = require('node:fs');
+      const path = require('node:path');
+      return fs.readFileSync(path.resolve(raw.slice(1)), 'utf8');
+    }
+    return raw;
+  }
+  const ev = {};
+  if (args.target) ev.target = args.target;
+  if (args.incident) ev.incident = args.incident;
+  if (args.goal) ev.goal = args.goal;
+  if (args.intent) ev.intent = args.intent;
+  if (args.query) ev.query = args.query;
+  if (args.operationId) ev.operationId = args.operationId;
+  if (args.identity) ev.identity = args.identity;
+  return ev;
+}
+
+/**
+ * Invoke a paid action via the hosted rail.
+ * Returns { ok, result } for display by the caller.
+ */
+async function invokeRail(command, args, opts = {}) {
+  const action = railActionFor(command);
+  const evidence = buildEvidence(action, args);
+  const interactive = process.stdin.isTTY && !opts.yes;
+
+  // 1. Free quote first.
+  let quote;
+  try {
+    quote = await getQuote(action);
+  } catch (err) {
+    return { ok: false, error: `Could not reach the hosted rail for a free quote: ${err.message}` };
+  }
+  const price = quote.quoted_price_usd;
+  const quoteId = quote.quote_id;
+
+  if (!opts.json) {
+    console.log(`callx402 (hosted) — action '${action}'`);
+    console.log(`  Free quote: $${price} (quote ${String(quoteId).slice(0, 8)}…)`);
+  }
+
+  // 2. User approves the spend.
+  if (!opts.yes) {
+    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 },
+      };
+    }
+    const approve = await prompt(`  Approve $${price} for '${action}'? [y/N] `);
+    if (!/^y(es)?$/i.test(approve)) {
+      return { ok: false, error: 'Cancelled by user before payment.' };
+    }
+  }
+
+  // 3. Payment: x402 (paste tx hash) or card (browser checkout -> credit ID).
+  let payBody = { evidence, quote_id: quoteId, quote };
+  if (!interactive) {
+    return {
+      ok: false,
+      error: 'Interactive payment required.',
+      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 }.`,
+    };
+  }
+  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 checkout path.
+    const { status, body } = await railFetch('/v1/callx402/checkout', {
+      method: 'POST',
+      body: JSON.stringify({ action }),
+    });
+    if (status !== 200 && status !== 201) {
+      return { ok: false, error: `Checkout creation failed (HTTP ${status}).` };
+    }
+    const url = body.checkout_url || body.url;
+    if (!url) return { ok: false, error: 'Checkout URL not returned by rail.' };
+    console.log(`  Opening checkout in your browser…`);
+    if (!openBrowser(url)) console.log(`  Open this URL manually: ${url}`);
+    console.log('  Complete the payment, then paste the single-use credit ID from the success page.');
+    const creditId = await prompt('  Credit ID: ');
+    if (!creditId) return { ok: false, error: 'No credit ID provided.' };
+    payBody = { ...payBody, credit_id: creditId };
+  } else {
+    // 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 }),
+    });
+    if (status !== 402) {
+      return { ok: false, error: `Expected a 402 payment challenge, got HTTP ${status}.` };
+    }
+    const accept = (body.accepts && body.accepts[0]) || {};
+    const amountUsdc = accept.amount ? (Number(accept.amount) / 1e6).toFixed(2) : price;
+    console.log(`  Send ${amountUsdc} USDC on Base (eip155:8453) to:`);
+    console.log(`    ${accept.payTo || '(see 402 response)'}`);
+    console.log('  Then paste the transaction hash:');
+    const txHash = await prompt('  Tx hash: ');
+    if (!/^0x[0-9a-fA-F]{64}$/.test(txHash)) {
+      return { ok: false, error: 'Invalid transaction hash format.' };
+    }
+    payBody = { ...payBody, txHash: txHash.toLowerCase() };
+  }
+
+  // 4. Submit payment proof -> verified, executed, metered -> result.
+  const { status, body } = await railFetch(`/v1/callx402/actions/${action}`, {
+    method: 'POST',
+    body: JSON.stringify(payBody),
+  });
+  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 === 409) {
+    return { ok: false, error: `Already used: ${body?.error?.message || 'this payment was already consumed'}.` };
+  }
+  if (status !== 200 || !body || !body.ok) {
+    return { ok: false, error: `Rail error (HTTP ${status}): ${body?.error?.message || 'unknown'}` };
+  }
+  return {
+    ok: true,
+    action,
+    invocation_id: body.invocation_id,
+    via: body.via,
+    execution: body.execution || null,
+    notice: body.notice,
+  };
+}
+
+module.exports = {
+  RAIL_BASE,
+  isRailCommand,
+  preferLocal,
+  railActionFor,
+  invokeRail,
+  getQuote,
+};

package/core/veyline.js

@@ -0,0 +1,240 @@
+'use strict';
+
+/**
+ * core/veyline.js — dispatch handlers for the Veyline Recovery track:
+ *   callx402 evidence <operationId> [--dir <path>] [--evidence <json|@file>]
+ *   callx402 explain  <operationId> [--dir <path>] [--evidence <json|@file>]
+ *   callx402 recover  <operationId> [--dir <path>] [--evidence <json|@file>]
+ *                     [--identity <id>]
+ *
+ * ADDITIVE-ONLY: this file is new; no existing command is touched. It
+ * resolves the Veyline recovery modules from the recovery dir
+ * (CALLX402_VEYLINE_ROOT env, config veylineRoot, or the default relative
+ * path) — it does NOT go through core/subsystems.js, whose hard rule
+ * limits requires to the v2.0.0 tree.
+ *
+ * All three commands are read-only. `recover` reports the recovery
+ * decision the network would make (RECOVERABLE / SAFE_RETRY /
+ * EXECUTED_BUT_UNRECOVERABLE / SETTLEMENT_UNKNOWN); it never charges,
+ * never executes, never repays. Performing the approved safe action stays
+ * with the operator's own adapters.
+ *
+ * Gate: PAYLOAD_VEYLINE_LEDGER=1 for evidence/explain,
+ *       PAYLOAD_VEYLINE_RECOVERY=1 for recover. Default OFF.
+ */
+
+const path = require('path');
+const { EXIT, ok, fail } = require('./envelope');
+
+function veylineRoot(config = {}) {
+  return config.veylineRoot
+    || process.env.CALLX402_VEYLINE_ROOT
+    || path.resolve(__dirname, '..', '..', 'veyline', 'engineering', 'recovery');
+}
+
+function loadVeyline(config, deps) {
+  if (deps && deps.veyline) {
+    return { modules: deps.veyline, flag: '(test override)', overridden: true };
+  }
+  const root = veylineRoot(config);
+  try {
+    const modules = {
+      ledger: require(path.join(root, 'operation-ledger.js')),
+      recovery: require(path.join(root, 'recovery-state.js')),
+      planner: require(path.join(root, 'rescue-planner.js')),
+      trust: require(path.join(root, 'trust-graph.js')),
+      intel: require(path.join(root, 'incident-intel.js')),
+      continuity: require(path.join(root, 'continuity.js')),
+      root,
+    };
+    return { modules, flag: null, overridden: false };
+  } catch (err) {
+    return { modules: null, error: err.message };
+  }
+}
+
+function readJsonInput(input) {
+  if (input === undefined || input === null || input === '') return {};
+  if (typeof input !== 'string') return input;
+  const s = input.trim();
+  if (s.startsWith('@')) {
+    const fs = require('fs');
+    return JSON.parse(fs.readFileSync(path.resolve(s.slice(1)), 'utf8'));
+  }
+  return JSON.parse(s);
+}
+
+function disabledEnvelope(action, flag) {
+  return {
+    result: fail(action, {
+      subsystem: 'veyline', subsystemStatus: 'disabled',
+      code: 'subsystem_disabled',
+      message: `veyline recovery subsystem is disabled. Set ${flag}=1 to enable it. Nothing was executed.`,
+      disposition: 'veyline disabled: nothing executed.',
+      data: { flag },
+    }),
+    exitCode: EXIT.UNAVAILABLE,
+  };
+}
+
+function gate(modules, action, flag) {
+  if (!modules) {
+    return {
+      result: fail(action, { subsystem: 'veyline', code: 'subsystem_unreachable', message: 'veyline recovery modules could not be loaded. Nothing was executed.' }),
+      exitCode: EXIT.UNAVAILABLE,
+    };
+  }
+  const mod = action === 'recover' ? modules.recovery : modules.ledger;
+  const on = typeof mod.enabled === 'function' ? mod.enabled() : false;
+  if (!on) return disabledEnvelope(action, flag);
+  return null;
+}
+
+function ledgerFor(modules, dir) {
+  const d = dir || path.join(process.cwd(), '.veyline');
+  return modules.ledger.createOperationLedger({ dir: d });
+}
+
+async function actEvidence(args, ctx) {
+  const { modules, error } = loadVeyline(ctx.config, ctx.deps);
+  if (error || !modules) {
+    return { result: fail('evidence', { subsystem: 'veyline', code: 'subsystem_unreachable', message: `veyline modules unreachable: ${error || 'unknown'}` }), exitCode: EXIT.UNAVAILABLE };
+  }
+  const g = gate(modules, 'evidence', modules.ledger.FLAG);
+  if (g) return g;
+  try {
+    const operationId = args.operationId;
+    if (!operationId) {
+      return { result: fail('evidence', { subsystem: 'veyline', code: 'usage', message: 'operationId is required: callx402 evidence <operationId>' }), exitCode: EXIT.USAGE };
+    }
+    const ledger = ledgerFor(modules, args.dir);
+    const events = ledger.events(operationId);
+    const states = ledger.latestStates(operationId);
+    const protocols = ledger.protocols(operationId);
+    const data = {
+      operationId, events, states, protocols,
+      eventCount: events.length,
+      basis: events.length > 0 ? 'recorded ledger evidence' : 'no_basis: no events recorded for this operation',
+    };
+    return {
+      result: ok('evidence', {
+        subsystem: 'veyline',
+        disposition: events.length > 0
+          ? `Evidence for ${operationId}: ${events.length} event(s) across ${protocols.join(', ') || 'no protocols'}.`
+          : `No evidence recorded for ${operationId}.`,
+        data,
+      }),
+      exitCode: EXIT.OK,
+    };
+  } catch (err) {
+    const isMalformed = err instanceof SyntaxError;
+    return { result: fail('evidence', { subsystem: 'veyline', code: isMalformed ? 'usage' : 'failed', message: err.message }), exitCode: isMalformed ? EXIT.USAGE : EXIT.FAIL };
+  }
+}
+
+async function actExplain(args, ctx) {
+  const { modules, error } = loadVeyline(ctx.config, ctx.deps);
+  if (error || !modules) {
+    return { result: fail('explain', { subsystem: 'veyline', code: 'subsystem_unreachable', message: `veyline modules unreachable: ${error || 'unknown'}` }), exitCode: EXIT.UNAVAILABLE };
+  }
+  const g = gate(modules, 'explain', modules.ledger.FLAG);
+  if (g) return g;
+  try {
+    const operationId = args.operationId;
+    if (!operationId) {
+      return { result: fail('explain', { subsystem: 'veyline', code: 'usage', message: 'operationId is required: callx402 explain <operationId>' }), exitCode: EXIT.USAGE };
+    }
+    const ledger = ledgerFor(modules, args.dir);
+    const events = ledger.events(operationId);
+    const states = ledger.latestStates(operationId);
+    let assessment;
+    if (events.length === 0) {
+      assessment = 'NO_BASIS: nothing recorded; no claim can be made about this operation.';
+    } else if (states.payment === 'UNKNOWN' || states.execution === 'UNKNOWN') {
+      assessment = 'INCOMPLETE: a plane is UNKNOWN — do not retry, do not repay; gather fresh evidence or escalate to human review.';
+    } else if (states.payment === 'SETTLED' && states.execution === 'SUCCEEDED' && (states.delivery === 'DELIVERED' || states.delivery === 'ACKED')) {
+      assessment = 'KNOWN_SAFE: paid, executed, delivered.';
+    } else if (states.delivery === 'LOST') {
+      assessment = 'RECOVERY_CANDIDATE: delivery lost — run `callx402 recover <operationId>` to see the safe recovery decision.';
+    } else {
+      assessment = 'PARTIAL: some planes resolved, some not — see states; safe action depends on the unresolved plane.';
+    }
+    const trail = events.map((e) => `[${e.seq}] ${e.at} ${e.kind}${e.protocol ? `/${e.protocol}` : ''}: ${e.summary || ''}`.trim());
+    return {
+      result: ok('explain', {
+        subsystem: 'veyline',
+        disposition: `Explanation for ${operationId}: ${assessment}`,
+        data: { operationId, states, assessment, trail, eventCount: events.length },
+      }),
+      exitCode: EXIT.OK,
+    };
+  } catch (err) {
+    const isMalformed = err instanceof SyntaxError;
+    return { result: fail('explain', { subsystem: 'veyline', code: isMalformed ? 'usage' : 'failed', message: err.message }), exitCode: isMalformed ? EXIT.USAGE : EXIT.FAIL };
+  }
+}
+
+async function actRecover(args, ctx) {
+  const { modules, error } = loadVeyline(ctx.config, ctx.deps);
+  if (error || !modules) {
+    return { result: fail('recover', { subsystem: 'veyline', code: 'subsystem_unreachable', message: `veyline modules unreachable: ${error || 'unknown'}` }), exitCode: EXIT.UNAVAILABLE };
+  }
+  const g = gate(modules, 'recover', modules.recovery.FLAG);
+  if (g) return g;
+  try {
+    const operationId = args.operationId;
+    if (!operationId) {
+      return { result: fail('recover', { subsystem: 'veyline', code: 'usage', message: 'operationId is required: callx402 recover <operationId>' }), exitCode: EXIT.USAGE };
+    }
+    const evidence = readJsonInput(args.evidence);
+    const dir = args.dir || path.join(process.cwd(), '.veyline');
+    const ledger = ledgerFor(modules, args.dir);
+    // File-backed cache shared via --dir: the CLI reads the same recovery
+    // substrate a server wrote. Without --dir the cache is in-memory.
+    const cache = args.dir && typeof modules.recovery.createFileBackedCache === 'function'
+      ? modules.recovery.createFileBackedCache({ file: path.join(dir, 'recovery-cache.jsonl') })
+      : undefined;
+    const network = modules.recovery.createRecoveryNetwork({ ledger, cache });
+    let identity = args.identity || evidence.identity || null;
+    if (!identity && evidence.toolName && evidence.payer && evidence.paymentAuthFingerprint) {
+      identity = network.buildOperationIdentity({
+        toolName: evidence.toolName,
+        args: evidence.args,
+        payer: evidence.payer,
+        paymentAuthFingerprint: evidence.paymentAuthFingerprint,
+        traceId: evidence.traceId,
+        operationId,
+      });
+    }
+    if (!identity) {
+      return {
+        result: fail('recover', {
+          subsystem: 'veyline', code: 'usage',
+          message: 'an operation identity is required: pass --identity <id> or --evidence with toolName/payer/paymentAuthFingerprint (+args/traceId).',
+        }),
+        exitCode: EXIT.USAGE,
+      };
+    }
+    const decision = network.onLostResult({
+      operationId,
+      identity,
+      credentials: { payer: evidence.payer, paymentAuthFingerprint: evidence.paymentAuthFingerprint },
+      evidence,
+    });
+    const terminal = decision.recoveryState === 'RECOVERABLE' || decision.recoveryState === 'SAFE_RETRY'
+      ? 'KNOWN_SAFE' : 'HUMAN_REVIEW';
+    return {
+      result: ok('recover', {
+        subsystem: 'veyline',
+        disposition: `Recovery decision for ${operationId}: ${decision.recoveryState} -> ${terminal}. Read-only: nothing charged, nothing executed.`,
+        data: { operationId, decision, terminal },
+      }),
+      exitCode: EXIT.OK,
+    };
+  } catch (err) {
+    const isMalformed = err instanceof SyntaxError;
+    return { result: fail('recover', { subsystem: 'veyline', code: isMalformed ? 'usage' : 'failed', message: err.message }), exitCode: isMalformed ? EXIT.USAGE : EXIT.FAIL };
+  }
+}
+
+module.exports = { actEvidence, actExplain, actRecover, veylineRoot, loadVeyline };

package/docs/README.md

@@ -4,8 +4,8 @@
 action and entry-point layer for x402 infrastructure: you state an intent in
 plain language (or call an HTTP endpoint), and callx402 dispatches into the
 existing x402 subsystems that do the real work. It dispatches only. It never
-moves money by itself. The flagship product keeps a separate, forthcoming
-brand; callx402 is how you access it.
+moves money by itself. The flagship product is Veyline; callx402 is how you
+access it. **Positioning: callx402 is the action layer of Veyline.**
 
 Status of this docs set: landing index is live. Pages and assets marked
 "planned" below are not published yet. Nothing here is aspirational: every
@@ -46,18 +46,20 @@ Check subsystem reachability and feature flags:
 callx402 status
 ```
 
-Run an intent in plain language:
+Run an intent in plain language (single quotes: in double quotes your shell
+would expand `$1` to nothing):
 
 ```sh
-callx402 "complete this job for under $1"
+callx402 'complete this job for under $1'
 ```
 
-Diagnose, rescue, route, resolve:
+Diagnose, rescue, route, resolve (need the v2.0.0 tree plus each
+subsystem's flag; see the main README, "Full subsystem commands"):
 
 ```sh
-callx402 diagnose --target "https://api.example.com/x402/pay"
+callx402 diagnose --target 'https://api.example.com/x402/pay'
 callx402 rescue --incident inc_123
-callx402 route --goal "fetch 100 product prices for under $0.50"
+callx402 route --goal 'fetch 100 product prices for under 0.50 USD'
 callx402 resolve --evidence '{"txHash":"0xabc..."}'
 ```
 
@@ -123,7 +125,7 @@ Planned. No recipes published yet.
 The subsystem tree callx402 dispatches into: Sentinel, Rescue, Doctor,
 Router, Valuator, SpendGuard, Settlement Resolver, Intent Engine, Capability
 Graph, Economic Planner, MCP fabric, and RevRule. Every dispatch goes
-through the real subsystem in the x402 paid API starter kit v2.0.0 tree,
+through the real subsystem in the Veyline Developer Primer v2.0.0 tree (x402-paid-api-starter-kit),
 which callx402 imports but never modifies. If a subsystem is disabled or
 unreachable, callx402 reports that plainly and fails closed. It never fakes
 success.
@@ -288,7 +290,7 @@ guards real money movement is ever force-enabled by callx402.
 
 ### Subsystem docs
 
-callx402 dispatches into the x402 paid API starter kit v2.0.0 tree. Its docs
+callx402 dispatches into the Veyline Developer Primer v2.0.0 tree (x402-paid-api-starter-kit). Its docs
 are the reference for subsystem behavior:
 
 - `../x402-paid-api-starter-kit/v2.0.0/README.md` — kit overview

package/docs/action-reference.md

@@ -67,7 +67,7 @@ Shared notes for all actions:
 - **CAN IT MOVE MONEY?** No.
 - **CAN IT CREATE OR RETRY AN AUTHORIZATION?** No.
 - **FAIL-CLOSED CONDITIONS:** Missing `--goal` → exit 2; router disabled or unreachable → exit 3. With no candidates at all, the action is honest ("No candidate tools available... No route selected; nothing executed.") and still exits 0.
-- **EXAMPLE:** `callx402 route --goal "fetch 100 product prices for under $0.50" --speed cheap --json`
+- **EXAMPLE:** `callx402 route --goal 'fetch 100 product prices for under 0.50 USD' --speed cheap --json`
 - **CURRENT LIMITATIONS:** Without registered tools in the capability graph (experimental; requires `PAYLOAD_MCP_FABRIC=1`) there is nothing to rank, so routing returns an honest no-route result. Route selects; it never executes.
 - **VERIFICATION STATUS:** Tested. `test/cli-dispatch.test.js`: "route: disabled subsystem -> exit 3", "route: enabled, no candidates -> honest no-route, exit 0", "route: missing --goal -> usage error, exit 2", "router dispatch honors the fast speed policy", "router dispatch runs real selectTool/rankTools over candidates".
 
@@ -97,7 +97,7 @@ Shared notes for all actions:
 - **CAN IT MOVE MONEY?** It is the only action designed with execution side effects, and it is budget-gated, dry-run capable, and idempotent. In the current build it cannot move money: no live executable route is wired, so execution honestly does not happen. [implementation, tested]
 - **CAN IT CREATE OR RETRY AN AUTHORIZATION?** No in the current build. `--force-retry` after a stored run whose settlement is UNKNOWN is explicitly refused (`unsafe_retry_refused`, exit 5) to prevent double-spend.
 - **FAIL-CLOSED CONDITIONS:** Missing `--intent` → exit 2; over budget → exit 4, zero side effects; above approval threshold without `--approve` → exit 4; retry after UNKNOWN → exit 5; individual stages (intent engine, planner, router, kernel) disabled or unreachable are recorded in `data.stages` and planning continues honestly.
-- **EXAMPLE:** `callx402 execute --intent "complete this job for under $1" --max-budget 1.00 --dry-run --idempotency-key job-42 --json`
+- **EXAMPLE:** `callx402 execute --intent 'complete this job for under $1' --max-budget 1.00 --dry-run --idempotency-key job-42 --json`
 - **CURRENT LIMITATIONS:** No live executable route is wired in this build; `execute` currently plans honestly and stops. Effect proofs, settlement resolution, and receipts are only populated on real execution. Live execution would require a wired route plus an enabled execution kernel.
 - **VERIFICATION STATUS:** Tested. `test/intent-pipeline.test.js` (8 tests, incl. "execute: dry-run intent -> exit 0, honest no-route disposition", "cost above approval threshold without --approve fails closed, exit 4", "explicit --approve passes the threshold gate", "over-budget intent -> budget_refused, exit 4, zero side effects", "duplicate idempotencyKey: second call deduped with ORIGINAL result", "unsafe retry refusal", "intent pipeline walks stages in order", "networks/assets/providers constrain planner, router and spendguard"). `test/safety.test.js` (7 tests) covers the money-safety invariants end to end. Real CLI run verified 2026-10-06: intent-mode dispatch returns the honest "no executable route available" disposition with per-stage detail.
 

package/docs/cli-help-verified-2026-10-06.txt

@@ -37,3 +37,39 @@ Options:
 
 Exit codes: 0 ok · 1 failure · 2 usage · 3 disabled/unreachable ·
 4 budget refused · 5 settlement unknown (never auto-retry, never repay).
+
+================================================================================
+ADDENDUM 2026-10-07 — per-command help and rail-only routing hint
+================================================================================
+Change: `callx402 <command> --help` now prints that command's own usage
+instead of the global help (bin/callx402.js COMMAND_HELP). Bare
+`callx402 --help` output is unchanged (verified identical above). Unknown
+commands matching a rail-only paid action (safe_retry, duplicate_payment_risk,
+failure_classification, settlement_interpretation, hyphenated aliases) now get
+a routing hint to docs/problem-map.md instead of a bare usage error.
+
+$ callx402 recover --help   (exit 0)
+callx402 recover — report the safe recovery decision (read-only).
+
+Usage:
+  callx402 recover <operationId> [--identity <id> | --evidence <json>]
+
+Evaluates recorded history against the operation identity and returns the
+recovery decision: RECOVERABLE, SAFE_RETRY, EXECUTED_BUT_UNRECOVERABLE, or
+SETTLEMENT_UNKNOWN, mapped to KNOWN_SAFE or HUMAN_REVIEW. Never charges,
+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.
+
+Exit codes: 0 ok · 1 failure · 2 usage (missing identity/evidence) ·
+3 disabled/unreachable · 4 budget refused ·
+5 settlement unknown (never auto-retry, never repay).
+
+$ callx402 safe_retry   (exit 2, stderr)
+callx402: unknown command 'safe_retry' — 'safe_retry' is a paid on-demand rail action, not a CLI command. Get the free quote, then pay deliberately: see docs/problem-map.md
+Valid commands: diagnose, rescue, route, resolve, doctor, execute, monitor, status, preflight, inspect, config, evidence, explain, recover
+Run 'callx402 --help' for usage, or 'callx402 <command> --help' for one command.

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