callx402 1.0.1 → 1.0.3

package/bin/callx402.js

@@ -17,25 +17,247 @@ const path = require('path');
 
 const ROOT = path.resolve(__dirname, '..');
 const core = require(path.join(ROOT, 'core'));
+const rail = require(path.join(ROOT, 'core', 'rail'));
 const { loadConfig, getConfig, setConfig, listConfig } = require(path.join(ROOT, 'core', 'config'));
 const { EXIT } = require(path.join(ROOT, 'core', 'envelope'));
 
 const PKG = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8'));
 const VERSION = PKG.version || '1.0.0';
 
-const COMMANDS = ['diagnose', 'rescue', 'route', 'resolve', 'doctor', 'execute', 'monitor', 'status', 'preflight', 'inspect', 'config'];
+const COMMANDS = ['diagnose', 'rescue', 'route', 'resolve', 'doctor', 'execute', 'monitor', 'status', 'preflight', 'inspect', 'config', 'evidence', 'explain', 'recover'];
+
+// Paid on-demand rail actions that have no CLI command (architecture: the CLI
+// is the free local tier; these run on the paid rail via the quote-then-pay
+// invocation in docs/problem-map.md). Named here so a mistyped/rail-action
+// command gets a routing hint instead of a dead-end usage error.
+const RAIL_ONLY_ACTIONS = {
+  safe_retry: 'safe_retry', 'safe-retry': 'safe_retry',
+  duplicate_payment_risk: 'duplicate_payment_risk', 'duplicate-payment-risk': 'duplicate_payment_risk',
+  failure_classification: 'failure_classification', 'failure-classification': 'failure_classification',
+  settlement_interpretation: 'settlement_interpretation', 'settlement-interpretation': 'settlement_interpretation',
+};
+
+// Per-command help: `callx402 <command> --help` prints the command's own usage
+// instead of the global help. Free local tier; paid rail counterparts (where
+// they exist) are named with their docs pointer.
+const COMMAND_HELP = {
+  diagnose: `callx402 diagnose — run the x402 doctor over supplied evidence.
+
+Usage:
+  callx402 diagnose --target <url> [--evidence <json|@file>]
+  callx402 diagnose --evidence '{"txHash":"0x..."}'
+
+Read-only: classifies the failure stage from evidence you supply; performs no
+live probing and changes no state. Requires PAYLOAD_MCP_DOCTOR=1 (exit 3 names
+the flag when it is off).
+
+Paid one-off counterpart: the 'diagnose' rail action (quote first, then pay;
+see docs/problem-map.md). The MCP tool x402_diagnose covers the same free
+diagnostic.
+
+Exit codes: 0 ok · 1 failure · 2 usage · 3 disabled/unreachable ·
+4 budget refused · 5 settlement unknown (never auto-retry, never repay).
+`,
+  rescue: `callx402 rescue — incident triage for stuck or failed x402 transactions.
+
+Usage:
+  callx402 rescue --incident <id> [--network <net>] [--auth]
+
+Read-only triage: detects the incident, quotes the rescue, presents the
+free-vs-paid offer. Paid execution is NEVER performed by this command.
+Without --auth (or CALLX402_AUTH_TOKEN / config rescueAuth) it refuses with
+exit 3. Requires PAYLOAD_RESCUE=1.
+
+Paid one-off counterpart: the 'rescue' rail action (see docs/problem-map.md).
+
+Exit codes: 0 ok · 1 failure · 2 usage · 3 disabled/unreachable or auth_required ·
+4 budget refused · 5 settlement unknown (never auto-retry, never repay).
+`,
+  route: `callx402 route — select a tool/route for a goal under a routing policy.
+
+Usage:
+  callx402 route --goal <text> [--speed fast|balanced|cheap]
+                 [--networks a,b] [--assets a,b]
+
+Selection only: nothing executed, no money moved. Requires PAYLOAD_MCP_ROUTES=1.
+
+Exit codes: 0 ok · 1 failure · 2 usage (missing --goal) · 3 disabled/unreachable ·
+4 budget refused · 5 settlement unknown (never auto-retry, never repay).
+`,
+  resolve: `callx402 resolve — resolve the settlement state of a payment from evidence.
+
+Usage:
+  callx402 resolve --evidence '{"txHash":"0x...","network":"base"}'
+  callx402 resolve --evidence @evidence.json
+
+Read-only analysis: maps evidence to DEFINITELY_PAID, DEFINITELY_NOT_PAID,
+AUTHORIZED_NOT_SETTLED, SETTLEMENT_PENDING, CONFLICT, or UNKNOWN. Never
+queries the chain, never signs, never retries, never repays. Requires
+PAYLOAD_SETTLEMENT_RESOLVER=1.
+
+Thin evidence -> settlement UNKNOWN, exit 5. That is the stop sign: do not
+retry, do not repay; gather fresh evidence or escalate.
+
+Paid one-off counterpart: the 'resolve' rail action (quote first, then pay;
+see docs/problem-map.md). The MCP tool x402_resolve covers the same free
+diagnostic.
+
+Exit codes: 0 ok · 1 failure · 2 usage (malformed evidence JSON) ·
+3 disabled/unreachable · 4 budget refused ·
+5 settlement unknown (never auto-retry, never repay).
+`,
+  doctor: `callx402 doctor — alias of diagnose.
+
+Usage:
+  callx402 doctor --target <url> [--evidence <json|@file>]
+
+Identical to diagnose (the envelope's action field reads "diagnose").
+Requires PAYLOAD_MCP_DOCTOR=1.
+
+Exit codes: 0 ok · 1 failure · 2 usage · 3 disabled/unreachable ·
+4 budget refused · 5 settlement unknown (never auto-retry, never repay).
+`,
+  execute: `callx402 execute — run the intent pipeline under an explicit budget.
+
+Usage:
+  callx402 execute --intent <text> [--max-budget N] [--dry-run]
+                   [--idempotency-key K] [--approve] [--force-retry]
+
+Budget-gated and idempotent. --dry-run plans only. Over-budget plans refuse
+with exit 4 and zero side effects. --force-retry after a stored run whose
+settlement is UNKNOWN is refused (exit 5): it could double-spend.
+
+Exit codes: 0 ok · 1 failure · 2 usage (missing --intent) ·
+3 disabled/unreachable · 4 budget refused ·
+5 settlement unknown (never auto-retry, never repay).
+`,
+  monitor: `callx402 monitor — Sentinel snapshot of x402 incident state.
+
+Usage:
+  callx402 monitor --once            single snapshot (default)
+  callx402 monitor --watch [--interval <ms>]
+
+Read-only. The default sentinel is inert ("no live tracking") unless
+PAYLOAD_SENTINEL=1 enables the live tracker.
+
+Exit codes: 0 ok · 1 failure · 2 usage · 3 disabled/unreachable ·
+4 budget refused · 5 settlement unknown (never auto-retry, never repay).
+`,
+  status: `callx402 status — per-subsystem reachability report.
+
+Usage:
+  callx402 status [--json]
+
+Requires nothing; works even when every subsystem is disabled. Reports
+reachable/enabled/version/flag for all 15 subsystem handles. Always exits 0
+on success.
+`,
+  preflight: `callx402 preflight — preflight checks over a supplied context.
+
+Usage:
+  callx402 preflight [--json]
+
+Read-only: validates setup before a paid run; provisions or repairs nothing.
+Requires PAYLOAD_MCP_PREFLIGHT=1.
+
+Paid one-off counterpart: the 'preflight' rail action (see docs/problem-map.md).
+
+Exit codes: 0 ok · 1 failure · 2 usage · 3 disabled/unreachable ·
+4 budget refused · 5 settlement unknown (never auto-retry, never repay).
+`,
+  inspect: `callx402 inspect — capability-graph lookup or stats.
+
+Usage:
+  callx402 inspect [--query <text>]
+
+Lookups only. Requires PAYLOAD_MCP_FABRIC=1; without registered tools it
+returns zero candidates honestly.
+
+Exit codes: 0 ok · 1 failure · 2 usage · 3 disabled/unreachable ·
+4 budget refused · 5 settlement unknown (never auto-retry, never repay).
+`,
+  evidence: `callx402 evidence — show recorded evidence for an operation.
+
+Usage:
+  callx402 evidence <operationId> [--dir <path>]
+
+Reads the Veyline operation ledger: events, latest per-plane states (payment,
+execution, delivery), protocols. Unknown operations are honest ("no events
+recorded"), still exit 0. Requires PAYLOAD_VEYLINE_LEDGER=1. First step in any
+incident: returns what is recorded, nothing invented.
+
+Paid one-off counterpart: the 'evidence' rail action (quote first, then pay;
+see docs/problem-map.md). The MCP tool x402_evidence covers the same free
+diagnostic.
+
+Exit codes: 0 ok · 1 failure · 2 usage (missing operationId) ·
+3 disabled/unreachable · 4 budget refused ·
+5 settlement unknown (never auto-retry, never repay).
+`,
+  explain: `callx402 explain — explain an operation's state in plain language.
+
+Usage:
+  callx402 explain <operationId> [--dir <path>]
+
+Assessments from recorded ledger evidence: NO_BASIS, INCOMPLETE (do not retry,
+do not repay), KNOWN_SAFE, RECOVERY_CANDIDATE (run 'recover'), PARTIAL.
+Requires PAYLOAD_VEYLINE_LEDGER=1.
+
+Paid one-off counterpart: the 'explain' rail action (see docs/problem-map.md).
+The MCP tool x402_explain covers the same free diagnostic.
+
+Exit codes: 0 ok · 1 failure · 2 usage (missing operationId) ·
+3 disabled/unreachable · 4 budget refused ·
+5 settlement unknown (never auto-retry, never repay).
+`,
+  recover: `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).
+`,
+  config: `callx402 config — manage local configuration.
+
+Usage:
+  callx402 config list
+  callx402 config get <key>
+  callx402 config set <key> <value>
+
+Valid keys: mode, remoteUrl, authToken, v2Root, defaultNetwork, defaultAsset,
+defaultBudgetUsd, approvalThresholdUsd, rescueAuth. Values persist to
+~/.config/callx402/config.json (CALLX402_CONFIG overrides the path);
+CALLX402_* environment variables override file values at runtime.
+
+Exit codes: 0 ok · 2 usage (unknown key or subcommand).
+`,
+};
 
 const HELP = `callx402 ${VERSION} — universal action layer for x402 infrastructure.
-callx402 is the ACTION, not the product name; every command dispatches into
-the existing v2.0.0 subsystems. Nothing here executes payments by itself.
+Install it and it works: subsystem commands route to the hosted Payload Rail
+by default (free quote first, then pay-per-action). Nothing here executes
+payments by itself.
 
 Usage:
   callx402 <command> [args] [options]
   callx402 "natural language intent"        intent mode (plans, never executes blindly)
   callx402 --help | --version
 
-Commands:
-  diagnose    run the x402 doctor over supplied evidence        [--target ...]
+Commands (hosted by default — zero setup):
+  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>
   route       select a tool/route for a goal                   --goal <text>
   resolve     resolve settlement state from evidence           --evidence <json|@file>
@@ -45,12 +267,15 @@ Commands:
   status      per-subsystem reachable/enabled/version report
   preflight   run MCP preflight checks
   inspect     capability-graph lookup/stats                    [--query <text>]
-  config      list | get <key> | set <key> <value>
+  evidence    show recorded evidence for an operation          <operationId> [--dir <path>]
+  explain     explain an operation's state in plain language   <operationId> [--dir <path>]
+  recover     report the safe recovery decision (read-only)    <operationId> [--identity <id> | --evidence <json>]
+  config      list | get <key> | set <key> <v>
 
 Options:
   --json                 print the full result envelope as JSON
   --timeout <ms>         fail the action if it exceeds <ms>
-  --approve              authorize costs above the approval threshold
+  --approve              approve the quoted price non-interactively
   --force-retry          explicit retry flag (REFUSED when prior settlement is UNKNOWN)
   --dry-run              plan only; no execution side effects
   --speed fast|balanced|cheap   routing policy hint
@@ -61,6 +286,15 @@ Options:
 
 Exit codes: 0 ok · 1 failure · 2 usage · 3 disabled/unreachable ·
 4 budget refused · 5 settlement unknown (never auto-retry, never repay).
+
+First run (no setup):  callx402 diagnose --evidence '{"txHash":"0x..."}'
+                        free quote first, then pay-per-action on the hosted rail.
+                        callx402 status        honest subsystem reachability report
+                        callx402 'plain words'  plans only; nothing executes, no money moves
+Execution modes: hosted rail by default. Set CALLX402_LOCAL=1 to prefer the
+local v2.0.0 runtime tree instead (advanced self-hosted mode): set
+CALLX402_V2_ROOT to its path and enable each subsystem's flag
+(run 'callx402 status' to see flag names).
 `;
 
 function parseArgv(argv) {
@@ -71,9 +305,11 @@ 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',
+    'dir', 'operationId', 'identity',
   ]);
   let i = 0;
   while (i < argv.length) {
@@ -89,7 +325,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']);
+      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];
@@ -111,8 +348,15 @@ function parseArgv(argv) {
   return out;
 }
 
-function usageError(message) {
-  console.error(`callx402: ${message}\nValid commands: ${COMMANDS.join(', ')}\nRun 'callx402 --help' for usage.`);
+function usageError(message, first) {
+  let msg = message;
+  // A rail-only paid action typed as a command is a routing hint, not a
+  // dead end: point at the quote-then-pay invocation instead.
+  if (first && RAIL_ONLY_ACTIONS[first] && /^unknown command /.test(message)) {
+    msg = `${message} — '${RAIL_ONLY_ACTIONS[first]}' is a paid on-demand rail action, not a CLI command. ` +
+      `Get the free quote, then pay deliberately: see docs/problem-map.md`;
+  }
+  console.error(`callx402: ${msg}\nValid commands: ${COMMANDS.join(', ')}\nRun 'callx402 --help' for usage, or 'callx402 <command> --help' for one command.`);
   process.exit(EXIT.USAGE);
 }
 
@@ -132,17 +376,30 @@ function summarize(envelope) {
 function statusSummary(envelope) {
   const lines = [envelope.disposition || 'status'];
   const subs = (envelope.data && envelope.data.subsystems) || {};
+  let reachable = 0;
   for (const [name, s] of Object.entries(subs)) {
+    if (s.reachable) reachable += 1;
     const mark = !s.reachable ? 'UNREACHABLE' : s.enabled ? 'enabled' : `disabled (${s.flag || 'no FLAG export'})`;
     lines.push(`  ${name.padEnd(12)} ${mark}${s.version ? `  v${s.version}` : ''}`);
   }
+  if (reachable === 0 && Object.keys(subs).length > 0) {
+    lines.push('');
+    lines.push('  No subsystems reachable: subsystem commands need the v2.0.0 tree.');
+    lines.push('  Set CALLX402_V2_ROOT to its path (see README "Full subsystem commands").');
+  }
   return lines.join('\n');
 }
 
 async function main() {
   const { flags, positionals, errors } = parseArgv(process.argv.slice(2));
 
-  if (flags.help) { process.stdout.write(HELP); process.exit(EXIT.OK); }
+  // Per-command help: `callx402 <command> --help` prints that command's own
+  // usage. Bare `--help` (or --help with an unknown word) prints the global help.
+  if (flags.help) {
+    const cmd = positionals[0];
+    if (cmd && COMMAND_HELP[cmd]) { process.stdout.write(COMMAND_HELP[cmd]); process.exit(EXIT.OK); }
+    process.stdout.write(HELP); process.exit(EXIT.OK);
+  }
   if (flags.version) { process.stdout.write(`callx402 ${VERSION}\n`); process.exit(EXIT.OK); }
   if (errors.length > 0) usageError(errors[0]);
 
@@ -152,8 +409,8 @@ async function main() {
   // like natural language (more than one word). A single unknown word is an
   // unknown command (exit 2), per the CLI contract.
   const isCommand = first && COMMANDS.includes(first);
-  if (!isCommand && first && first.startsWith('-')) usageError(`unknown input '${first}'`);
-  if (!isCommand && positionals.length === 1 && !/\s/.test(first)) usageError(`unknown command '${first}'`);
+  if (!isCommand && first && first.startsWith('-')) usageError(`unknown input '${first}'`, first);
+  if (!isCommand && positionals.length === 1 && !/\s/.test(first)) usageError(`unknown command '${first}'`, first);
   const command = isCommand ? first : (first === undefined ? null : '__intent__');
 
   // config handled directly (not a subsystem dispatch)
@@ -214,6 +471,9 @@ async function main() {
     once: !!flags.once,
     interval: toNum(flags.interval),
     network: flags.network,
+    dir: flags.dir,
+    operationId: flags.operationId,
+    identity: flags.identity,
     deadline: flags.deadline,
     risk: flags.risk,
     networks: toList(flags.networks) || (flags.network ? [flags.network] : undefined),
@@ -232,6 +492,7 @@ async function main() {
     if (command === 'execute' && !args.intent && rest.length > 0) args.intent = rest.join(' ');
     if (command === 'inspect' && !args.query && rest.length > 0) args.query = rest.join(' ');
     if (command === 'rescue' && !args.incident && rest.length > 0) args.incident = rest[0];
+    if ((command === 'evidence' || command === 'explain' || command === 'recover') && !args.operationId && rest.length > 0) args.operationId = rest[0];
   }
 
   if (Number.isNaN(args.timeoutMs)) usageError('--timeout must be a number (ms)');
@@ -239,6 +500,32 @@ async function main() {
   if (args.approvalThreshold !== undefined && Number.isNaN(args.approvalThreshold)) usageError('--approval-threshold must be a number');
 
   try {
+    // Hosted rail routing (default): subsystem commands run against the live
+    // Payload Rail with zero local setup — invoke -> free quote ->
+    // 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, 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) {
+        console.log(`\nResult (via ${railResult.via}, invocation ${railResult.invocation_id}):`);
+        const ex = railResult.execution;
+        if (ex && ex.executed) {
+          if (ex.disposition) console.log(ex.disposition);
+          if (ex.result !== undefined) console.log(JSON.stringify(ex.result, null, 2));
+        } else if (ex && ex.error) {
+          console.log(`Note: ${ex.error}`);
+        }
+        if (railResult.notice) console.log(railResult.notice);
+      } else {
+        console.error(`callx402: ${railResult.error}`);
+        if (railResult.quote) console.error(`Quote was: $${railResult.quote.price_usd} (${railResult.quote.quote_id})`);
+      }
+      process.exit(railResult.ok ? EXIT.OK : EXIT.FAIL);
+    }
     const { result, exitCode } = await core.runAction(actionName, args, { version: VERSION });
     if (args.json) {
       console.log(JSON.stringify(result, null, 2));

package/core/index.js

@@ -14,10 +14,11 @@ const { loadConfig } = require('./config');
 const { getSubsystem, getStatus: statusOf, SUBSYSTEMS } = require('./subsystems');
 const { runIntent } = require('./pipeline');
 const { dispatchRemote } = require('./remote');
+const { actEvidence, actExplain, actRecover } = require('./veyline');
 
-const ACTIONS = ['diagnose', 'rescue', 'route', 'resolve', 'doctor', 'execute', 'monitor', 'status', 'preflight', 'inspect'];
+const ACTIONS = ['diagnose', 'rescue', 'route', 'resolve', 'doctor', 'execute', 'monitor', 'status', 'preflight', 'inspect', 'evidence', 'explain', 'recover'];
 
-/** Parse --evidence style input: JSON string or @file. */
+/** Parse --evidence style input: JSON string or @file. Strict: bad JSON is a usage error. */
 function readEvidenceInput(input, fs, path) {
   if (input === undefined || input === null || input === '') return {};
   if (typeof input !== 'string') return input;
@@ -30,6 +31,29 @@ function readEvidenceInput(input, fs, path) {
   return JSON.parse(s);
 }
 
+/**
+ * Parse diagnose input. --evidence stays strict JSON (or @file). --target
+ * accepts a plain URL or identifier string: when it is not valid JSON it is
+ * wrapped as { target } evidence so the documented
+ * `diagnose --target <url>` example works as printed.
+ */
+function readDiagnoseInput(args, fs, path) {
+  const ev = args.evidence;
+  if (ev !== undefined && ev !== null && ev !== '') return readEvidenceInput(ev, fs, path);
+  const t = args.target;
+  if (t === undefined || t === null || t === '') return {};
+  const s = String(t).trim();
+  if (s.startsWith('@')) {
+    const raw = fs.readFileSync(path.resolve(s.slice(1)), 'utf8');
+    return JSON.parse(raw);
+  }
+  try {
+    return JSON.parse(s);
+  } catch {
+    return { target: s };
+  }
+}
+
 function disabledResult(action, subsystem, handle) {
   return {
     result: fail(action, {
@@ -48,7 +72,9 @@ function unreachableResult(action, subsystem, handle) {
     result: fail(action, {
       subsystem, subsystemStatus: 'unreachable',
       code: 'subsystem_unreachable',
-      message: `${subsystem} subsystem could not be loaded (${handle.error || 'unknown error'}). Nothing was executed.`,
+      message: `${subsystem} subsystem could not be loaded (${handle.error || 'unknown error'}). Nothing was executed. ` +
+        `To enable: set CALLX402_V2_ROOT to the v2.0.0 subsystem tree path (see README "Full subsystem commands"), ` +
+        `or run in remote mode (CALLX402_MODE=remote, CALLX402_REMOTE_URL=<your callx402 server>).`,
       disposition: `${subsystem} unreachable: nothing executed.`,
       data: { error: handle.error },
     }),
@@ -67,7 +93,7 @@ async function actDiagnose(args, ctx) {
   const g = requireSubsystem('diagnose', 'doctor', ctx);
   if (!g.handle) return g;
   try {
-    const evidence = readEvidenceInput(args.evidence ?? args.target, require('fs'), require('path'));
+    const evidence = readDiagnoseInput(args, require('fs'), require('path'));
     const report = g.handle.module.runMcpDoctor(evidence);
     const whatFailed = report.whatFailed || 'unknown';
     return {
@@ -269,7 +295,7 @@ async function actStatus(args, ctx) {
     result: ok('status', {
       subsystem: null,
       disposition: `callx402 status: ${reachable}/${all.length} subsystems reachable, ${enabledCount}/${all.length} enabled.`,
-      data: { version: ctx.version || '0.1.0', v2Root: require('./subsystems').getV2Root(ctx.config || {}), subsystems },
+      data: { version: ctx.version || '1.0.0', v2Root: require('./subsystems').getV2Root(ctx.config || {}), subsystems },
     }),
     exitCode: EXIT.OK,
   };
@@ -314,7 +340,7 @@ async function actInspect(args, ctx) {
  */
 async function runAction(name, args = {}, opts = {}) {
   const config = opts.config || loadConfig();
-  const ctx = { deps: opts.deps || {}, config, timeoutMs: opts.timeoutMs, version: opts.version || '0.1.0' };
+  const ctx = { deps: opts.deps || {}, config, timeoutMs: opts.timeoutMs, version: opts.version || '1.0.0' };
 
   // SPEC §5: remote mode dispatches over HTTP to a callx402 server. The deps
   // seam is local-only: an explicit subsystem override means local dispatch.
@@ -334,6 +360,9 @@ async function runAction(name, args = {}, opts = {}) {
       case 'status': return actStatus(args, ctx);
       case 'preflight': return actPreflight(args, ctx);
       case 'inspect': return actInspect(args, ctx);
+      case 'evidence': return actEvidence(args, ctx);
+      case 'explain': return actExplain(args, ctx);
+      case 'recover': return actRecover(args, ctx);
       default:
         return {
           result: fail(name, {

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 };