@iicp/client 0.7.75 → 0.7.77

package/README.md

@@ -5,7 +5,11 @@
 [![Protocol](https://img.shields.io/badge/IICP-v1.7-indigo.svg)](https://iicp.network/spec)
 [![npm](https://img.shields.io/badge/npm-%40iicp%2Fclient-red?logo=npm)](https://www.npmjs.com/package/@iicp/client)
 
-Official TypeScript client library for the [IICP protocol](https://iicp.network) — route AI agent tasks by intent across a self-organising mesh of provider nodes. No central broker. No hardcoded endpoints.
+Use the open AI mesh from your TypeScript or JavaScript app. Install the
+client, send an intent, and get a routed response from an IICP node.
+
+You do **not** need to run a node to try the client path. Consume first,
+provide later.
 
 Works in **Node.js ≥ 18**, Deno, Bun, and modern browsers with the native Fetch API.
 
@@ -23,7 +27,68 @@ npm install @iicp/client@latest
 # pnpm add @iicp/client@latest
 ```
 
-> **Upgrade note (0.7.75)** — upgrade provider nodes so Quick Tunnel endpoints
+## One-line test
+
+```bash
+npm install -g @iicp/client@latest
+iicp-node query "Hello, mesh."
+```
+
+What good looks like:
+
+```bash
+iicp-node --help       # shows query, serve, proxy, mcp-gateway, credits, ...
+which iicp-node        # points to your Node/npm environment
+iicp-node --version    # prints iicp-node 0.7.77 or newer
+```
+
+The query command contacts the public directory, discovers a matching live node,
+routes your prompt, and prints the response. No account, API key, or local node
+is required for this consumer path.
+
+## Use from TypeScript
+
+```typescript
+import { IicpClient } from "@iicp/client";
+
+const reply = await new IicpClient().chat([
+  { role: "user", content: "Hello, mesh." },
+]);
+
+console.log(reply.choices[0].message.content);
+```
+
+## Do I need to run a node?
+
+No. Running a node is only needed when you want to provide compute or tools to
+the mesh. Start as a client; run a node later when you want to contribute.
+
+## Migrate from existing AI tools
+
+Direct call:
+
+```typescript
+// Before: call one vendor endpoint directly.
+// After: ask IICP to discover and route by capability.
+const reply = await new IicpClient().chat([
+  { role: "user", content: "Summarize this document." },
+]);
+```
+
+Existing OpenAI-compatible tools:
+
+```bash
+npm install -g @iicp/client@latest
+iicp-node proxy
+export OPENAI_BASE_URL=http://127.0.0.1:9483/v1
+```
+
+Then point LangChain, Cursor, liteLLM or another OpenAI-compatible tool at that
+base URL. Full guide: <https://iicp.network/docs/proxy>
+
+## Provider upgrade note
+
+> **Upgrade note (0.7.77)** — upgrade provider nodes so Quick Tunnel endpoints
 > recover safely after sleep, idle, Cloudflare edge drops, and local DNS
 > propagation lag on freshly-created `trycloudflare.com` URLs. Tunnel
 > twilight/recovery still heartbeats as unavailable and only re-registers once
@@ -47,7 +112,7 @@ If a node is older than 0.7.67, perform one manual upgrade/restart first,
 especially for Dockerized Python or TypeScript providers: early updater wiring
 did not reliably cover every normal `serve` path. For Docker, use a Compose
 `restart: unless-stopped` policy (or `docker run --restart unless-stopped`) so
-0.7.75 can intentionally exit from a confirmed tunnel-dead state and let Docker
+0.7.77 can intentionally exit from a confirmed tunnel-dead state and let Docker
 bring it back cleanly.
 
 > **Upgrade note (0.5.3)** — if you operate a node and use the native IICP
@@ -71,7 +136,7 @@ Consumer and provider can run in the same process. For production provider nodes
 
 ---
 
-## Quickstart
+## Library quickstart
 
 ```typescript
 import { IicpClient } from "@iicp/client";

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA2CA,OAAO,EAeL,KAAK,YAAY,EAClB,MAAM,eAAe,CAAC;AAGvB,KAAK,aAAa,GAAG,cAAc,cAAc,CAAC,CAAC;AAEnD,MAAM,WAAW,yBAAyB;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC,CAAC;IAC3C,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,yBAA8B,GAAG,MAAM,IAAI,CA+C3F;AAED,MAAM,WAAW,SAAS;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,qGAAqG;IACrG,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,EAAE,OAAO,CAAC;IAC1B,KAAK,EAAE,OAAO,CAAC;IACf,aAAa,EAAE,OAAO,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,iGAAiG;IACjG,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAoBD,eAAO,MAAM,qBAAqB,KAAK,CAAC;AACxC,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,CAAC;AACtE,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,CAAC;AAE/D,wBAAgB,uBAAuB,IAAI,gBAAgB,CAM1D;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,gBAAgB,EAAE,UAAU,EAAE,OAAO,GAAG,kBAAkB,CAGpG;AA6UD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,OAAO,EACxB,aAAa,EAAE,OAAO,GACrB,KAAK,CAAC,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC,CAGtC;AAED,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAWlE;AAED,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,MAAM,EAEhB,OAAO,CAAC,EAAE,GAAG,GACZ,MAAM,GAAG,IAAI,CAUf;AAiFD,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,GAAG,SAAS,CAsB9E;AAo0BD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CA+D5D;AA8dD,wBAAsB,IAAI,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,MAAM,CAAC,CAmBlF"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAiDA,OAAO,EAeL,KAAK,YAAY,EAClB,MAAM,eAAe,CAAC;AAGvB,KAAK,aAAa,GAAG,cAAc,cAAc,CAAC,CAAC;AAEnD,MAAM,WAAW,yBAAyB;IACxC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC,CAAC;IAC3C,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,yBAA8B,GAAG,MAAM,IAAI,CA+C3F;AAED,MAAM,WAAW,SAAS;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,qGAAqG;IACrG,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,EAAE,OAAO,CAAC;IAC1B,KAAK,EAAE,OAAO,CAAC;IACf,aAAa,EAAE,OAAO,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,mBAAmB,EAAE,MAAM,CAAC;IAC5B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,0EAA0E;IAC1E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,iGAAiG;IACjG,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAoBD,eAAO,MAAM,qBAAqB,KAAK,CAAC;AACxC,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,UAAU,CAAC;AACtE,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,CAAC;AAE/D,wBAAgB,uBAAuB,IAAI,gBAAgB,CAM1D;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,gBAAgB,EAAE,UAAU,EAAE,OAAO,GAAG,kBAAkB,CAGpG;AAwZD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,OAAO,EACxB,aAAa,EAAE,OAAO,GACrB,KAAK,CAAC,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC,CAGtC;AAED,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAWlE;AAED,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,MAAM,EAEhB,OAAO,CAAC,EAAE,GAAG,GACZ,MAAM,GAAG,IAAI,CAUf;AAiFD,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,YAAY,GAAG,SAAS,CAsB9E;AAo0BD;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CA+D5D;AAmoBD,wBAAsB,IAAI,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,OAAO,CAAC,MAAM,CAAC,CAmBlF"}

package/dist/cli.js

@@ -46,6 +46,7 @@ const cip_policy_js_1 = require("./cip_policy.js");
 const index_js_1 = require("./proxy/index.js");
 const instance_lock_js_1 = require("./instance_lock.js");
 const index_js_2 = require("./backends/index.js");
+const recovery_js_1 = require("./recovery.js");
 const identity_js_1 = require("./identity.js");
 const delegation_js_1 = require("./delegation.js");
 /**
@@ -138,11 +139,13 @@ function printHelp() {
         `  init                       Interactive wizard — set up operator + first node config\n` +
         `  list                       List node configs saved under ~/.iicp/nodes/\n` +
         `  serve                      Register and serve a node\n` +
+        `  doctor                     Check local health, directory presence, and recovery action\n` +
         `  query <prompt>             Discover mesh nodes and submit a chat task\n` +
-        `  credits                    Show this node's earned / spent / balance credits\n` +
+        `  credits                    Show your operator wallet plus this node's credit ledger\n` +
         `  proxy                      Run the local OpenAI/Ollama/Anthropic-compat gateway (loopback; no registration)\n` +
         `  mcp-gateway                Bridge a local MCP server as an IICP provider node (registers + serves)\n` +
         `  service                    Generate/install OS supervisor units for unattended node serving\n` +
+        `  update                     Check whether a newer @iicp/client release is available\n` +
         `  operator rename <name>     Change your public display_name (signed by your operator key)\n` +
         `  operator encrypt           Password-encrypt the operator secret at rest ($IICP_OPERATOR_PASSPHRASE)\n` +
         `  operator decrypt           Remove at-rest encryption of the operator secret\n\n` +
@@ -187,6 +190,58 @@ function printHelp() {
         `  --max-tokens N             Limit response length\n` +
         `  --timeout-ms N             Request timeout (default 60000)\n`);
 }
+function argsHaveHelp(argv) {
+    return argv.includes("--help") || argv.includes("-h");
+}
+function printListHelp() {
+    process.stdout.write(`usage: iicp-node list\n\n` +
+        `List saved node configs under ~/.iicp/nodes/ without contacting the directory.\n\n` +
+        `Options:\n` +
+        `  -h, --help                 Show this help and exit without listing nodes\n`);
+}
+function printUpdateHelp() {
+    process.stdout.write(`usage: iicp-node update\n\n` +
+        `Check whether a newer @iicp/client release is available. Read-only: this command never installs or restarts anything.\n\n` +
+        `Exit codes:\n` +
+        `  0   current, unreachable registry, or help\n` +
+        `  10  newer release available\n\n` +
+        `Options:\n` +
+        `  -h, --help                 Show this help and exit without contacting npm\n`);
+}
+function printServeHelp() {
+    process.stdout.write(`usage: iicp-node serve [options]\n\n` +
+        `Register and serve an IICP provider node backed by an OpenAI-compatible backend.\n` +
+        `Use \`iicp-node init\` first for the lowest-friction saved-node path, then run:\n` +
+        `  iicp-node serve --node <NAME>\n\n` +
+        `Required (flag/env/saved node):\n` +
+        `  --model NAME               IICP_BACKEND_MODEL — model name (e.g. qwen2.5:0.5b)\n` +
+        `  --node NAME                load ~/.iicp/nodes/<NAME>.json from \`iicp-node init\`\n\n` +
+        `Core options:\n` +
+        `  --backend-url URL          IICP_BACKEND_URL — Ollama / vLLM / LM Studio (default http://localhost:11434; anthropic → https://api.anthropic.com)\n` +
+        `  --backend-type TYPE        IICP_BACKEND_TYPE — openai_compat | vllm | llamacpp | anthropic\n` +
+        `  --backend-api-key KEY      IICP_BACKEND_API_KEY — Bearer key for auth'd backends\n` +
+        `  --public-endpoint URL      IICP_PUBLIC_ENDPOINT — externally reachable URL of this node\n` +
+        `  --directory-url URL        IICP_DIRECTORY_URL (default https://iicp.network/api)\n` +
+        `  --region REGION            IICP_REGION (e.g. eu-central)\n` +
+        `  --intent URN               IICP_INTENT (default urn:iicp:intent:llm:chat:v1)\n` +
+        `  --max-concurrent N         IICP_MAX_CONCURRENT (default 4)\n` +
+        `  --node-id ID               IICP_NODE_ID (auto-generated if absent)\n` +
+        `  --port N                   IICP_PORT (default 9484)\n` +
+        `  --host HOST                IICP_HOST (default :: — dual-stack IPv4+IPv6)\n` +
+        `  --skip-registration        IICP_SKIP_REGISTRATION — register-free dev mode\n` +
+        `  --force                    IICP_FORCE — take over the single-instance lock for this node_id\n\n` +
+        `Reachability and resilience:\n` +
+        `  --auto-detect-nat          IICP_AUTO_DETECT_NAT — run NAT detection at startup (default on)\n` +
+        `  --no-auto-detect-nat       disable NAT detection at startup\n` +
+        `  --external-ip-probe-url U  IICP_EXTERNAL_IP_PROBE_URL — fallback IPv4 probe\n` +
+        `  --tunnel / --no-tunnel     IICP_TUNNEL — auto Cloudflare Quick Tunnel fallback when direct reachability fails\n` +
+        `  --relay-worker-endpoint H  IICP_RELAY_WORKER_ENDPOINT — <host>:<port> of a relay node\n` +
+        `  --relay-capable            IICP_RELAY_CAPABLE — advertise as relay server\n` +
+        `  --relay-accept-port N      IICP_RELAY_ACCEPT_PORT — relay accept TCP port (default 9485)\n` +
+        `  --log-dir DIR              IICP_LOG_DIR — directory for persistent log files\n` +
+        `  --with-proxy               IICP_WITH_PROXY — also run the loopback compat proxy (127.0.0.1:9483)\n` +
+        `  -h, --help                 Show this focused serve help\n`);
+}
 /**
  * Thrown by safeParseArgs / port parsing to signal a clean, user-facing CLI error.
  * main() catches it and prints a one-line `ERROR:` (exit 2) — never a raw stack trace.
@@ -427,7 +482,18 @@ async function runInit() {
         rl.close();
     }
 }
-function runList() {
+function runList(argv = []) {
+    const { values } = safeParseArgs({
+        args: argv,
+        options: {
+            help: { type: "boolean", short: "h" },
+        },
+        allowPositionals: false,
+    });
+    if (values.help) {
+        printListHelp();
+        return 0;
+    }
     const nodes = (0, identity_js_1.listNodes)();
     if (nodes.length === 0) {
         process.stdout.write(`No saved node configs. Run \`iicp-node init\` first.\n`);
@@ -1406,14 +1472,14 @@ async function verifyCreditAwards(directoryUrl, nodeId) {
     return { sum, verified, failed };
 }
 /**
- * `iicp-node credits` (#456) — earned / spent / balance from the directory's
+ * `iicp-node credits` (#456) — operator wallet + node ledger from the directory's
  * reconcile-checked GET /v1/credits/summary. Figures come authenticated from the
  * directory (not the local config), so editing the saved file cannot inflate them;
  * `reconciles` flags a ledger that does not add up.
  */
 function printCreditsHelp() {
     process.stdout.write(`usage: iicp-node credits [options]\n\n` +
-        `Show this node's earned / spent / balance credits (authenticated from the directory).\n\n` +
+        `Show your operator wallet plus this node's credit ledger (authenticated from the directory).\n\n` +
         `options:\n` +
         `  --node NAME                Load token + node_id from ~/.iicp/nodes/<NAME>.json\n` +
         `  --node-id ID               Node id (if not using --node)\n` +
@@ -1478,11 +1544,12 @@ async function runCredits(argv) {
                         // One node failing must not hide the others — show every node,
                         // then exit non-zero if any failed (2026-06-11).
                         let failed = 0;
+                        const walletState = { shown: false };
                         for (let i = 0; i < withToken.length; i++) {
                             if (i > 0)
                                 process.stdout.write("\n");
                             const n = withToken[i];
-                            const rc = await fetchAndDisplayCredits(n.directory_url ?? dir, n.node_id, n.node_token, n.name, Boolean(values["json"]), Boolean(values["verify"]));
+                            const rc = await fetchAndDisplayCredits(n.directory_url ?? dir, n.node_id, n.node_token, n.name, Boolean(values["json"]), Boolean(values["verify"]), walletState);
                             if (rc !== 0) {
                                 process.stderr.write(`ERROR: credits fetch failed for node '${n.name}' — continuing with remaining nodes\n`);
                                 failed++;
@@ -1528,7 +1595,7 @@ async function runCredits(argv) {
     return fetchAndDisplayCredits(directoryUrl, nodeId, token, label, Boolean(values["json"]), Boolean(values["verify"]));
 }
 /** Shared fetch+display logic for one node's credits summary. */
-async function fetchAndDisplayCredits(directoryUrl, nodeId, token, label, asJson, verify) {
+async function fetchAndDisplayCredits(directoryUrl, nodeId, token, label, asJson, verify, walletState) {
     const url = `${directoryUrl.replace(/\/+$/, "")}/v1/credits/summary?node_id=${encodeURIComponent(nodeId)}`;
     // Transient failures (network error, 5xx, undecodable body) get ONE retry
     // after a short pause — shared-hosting blips and deploy windows otherwise
@@ -1586,7 +1653,32 @@ async function fetchAndDisplayCredits(directoryUrl, nodeId, token, label, asJson
     const tpc = Number(body["tokens_per_credit"] ?? 1000);
     const pad = (n) => n.toFixed(3).padStart(12);
     const check = reconciles ? "✓ reconciles" : "✗ DOES NOT RECONCILE";
-    process.stdout.write(`IICP credits — ${label}\n`);
+    const wallet = body["operator_wallet"];
+    if (wallet && typeof wallet === "object") {
+        const showWallet = !walletState?.shown;
+        const fingerprint = typeof wallet["operator_fingerprint"] === "string" ? ` · operator ${wallet["operator_fingerprint"]}` : "";
+        const walletBalance = Number(wallet["total_balance"] ?? balance);
+        const walletNodes = Number(wallet["node_count"] ?? 0);
+        if (showWallet) {
+            process.stdout.write(`IICP operator wallet${fingerprint}\n`);
+            if (wallet["total_earned"] !== undefined)
+                process.stdout.write(`  Total earned     ${pad(Number(wallet["total_earned"] ?? 0))}\n`);
+            if (wallet["total_spent"] !== undefined)
+                process.stdout.write(`  Total spent      ${pad(Number(wallet["total_spent"] ?? 0))}\n`);
+            process.stdout.write("  ─────────────────────────────\n");
+            const wr = wallet["reconciles"];
+            const walletCheck = wr === true ? "✓ reconciles" : wr === false ? "✗ DOES NOT RECONCILE" : "rollup";
+            process.stdout.write(`  Wallet balance   ${pad(walletBalance)}   ${walletCheck}   (≈ ${Math.trunc(walletBalance * tpc)} tokens)\n`);
+            process.stdout.write(`  ${walletNodes} linked node(s) · per-node audit below\n\n`);
+            if (walletState)
+                walletState.shown = true;
+        }
+        process.stdout.write(`Node ledger — ${label}\n`);
+    }
+    else {
+        process.stdout.write(`IICP credits — ${label}\n`);
+        process.stdout.write("  Node-local ledger  bind an operator identity to combine nodes\n");
+    }
     process.stdout.write(`  Earned (income) ${pad(earned)}\n`);
     process.stdout.write(`  Spent           ${pad(spent)}\n`);
     process.stdout.write("  ─────────────────────────────\n");
@@ -1620,6 +1712,103 @@ async function fetchAndDisplayCredits(directoryUrl, nodeId, token, label, asJson
     }
     return 0;
 }
+function printDoctorHelp() {
+    process.stdout.write(`usage: iicp-node doctor [options]\n\n` +
+        `Check local health, directory presence, and deterministic recovery action.\n\n` +
+        `options:\n` +
+        `  --node NAME                Load saved node config (~/.iicp/nodes/<NAME>.json)\n` +
+        `  --directory-url URL        Override the saved IICP directory base URL\n` +
+        `  --json                     Print machine-readable recovery state\n` +
+        `  -h, --help                 Show this help and exit\n`);
+}
+function doctorLoopbackHost(host) {
+    const h = (host || "").trim();
+    if (h === "" || h === "::" || h === "0.0.0.0")
+        return "127.0.0.1";
+    return h;
+}
+function doctorUrl(host, port) {
+    const h = doctorLoopbackHost(host);
+    return h.includes(":") && !h.startsWith("[")
+        ? `http://[${h}]:${port}/iicp/health`
+        : `http://${h}:${port}/iicp/health`;
+}
+async function runDoctor(argv) {
+    const { values } = safeParseArgs({
+        args: argv,
+        options: {
+            node: { type: "string" },
+            "directory-url": { type: "string" },
+            json: { type: "boolean" },
+            help: { type: "boolean", short: "h" },
+        },
+        allowPositionals: false,
+    });
+    if (values.help) {
+        printDoctorHelp();
+        return 0;
+    }
+    const nodeName = values.node ?? process.env.IICP_NODE_NAME ?? "default";
+    const saved = (0, identity_js_1.loadNode)(nodeName);
+    if (!saved) {
+        process.stderr.write(`ERROR: no saved config at ~/.iicp/nodes/${nodeName}.json — run \`iicp-node init\` first.\n`);
+        return 1;
+    }
+    const directoryUrl = values["directory-url"] ?? saved.directory_url ?? process.env.IICP_DIRECTORY_URL ?? "https://iicp.network/api";
+    const localHealthUrl = doctorUrl(saved.host ?? "0.0.0.0", saved.port ?? 8020);
+    let localHealthOk = false;
+    let health = null;
+    let healthError = null;
+    try {
+        const resp = await fetch(localHealthUrl, { signal: AbortSignal.timeout(2_000) });
+        if (!resp.ok)
+            throw new Error(`HTTP ${resp.status}`);
+        health = (await resp.json());
+        localHealthOk = true;
+    }
+    catch (err) {
+        healthError = err instanceof Error ? err.message : String(err);
+    }
+    const presence = await (0, recovery_js_1.registryNodePresence)(directoryUrl, saved.node_id, 5_000);
+    const stability = (health?.["backend_stability"] ?? {});
+    const backendAttention = stability["backend_state"] === "draining";
+    const failures = !localHealthOk || presence === "absent" ? 1 : 0;
+    const { state, action } = (0, recovery_js_1.classifyRecovery)({
+        localHealthOk,
+        publicAvailable: localHealthOk,
+        directoryPresence: presence,
+        consecutiveFailures: failures,
+        graceChecks: (0, recovery_js_1.envGraceChecks)(),
+        backendAttention,
+    });
+    const prefix = (0, recovery_js_1.nodeRegistryPrefix)(saved.node_id);
+    if (values.json) {
+        process.stdout.write(JSON.stringify({
+            node: saved.name,
+            node_id: saved.node_id,
+            prefix,
+            directory_url: directoryUrl,
+            local_health_url: localHealthUrl,
+            local_health_ok: localHealthOk,
+            local_health_error: healthError,
+            directory_presence: presence,
+            recovery_state: state,
+            recommended_action: action,
+            health,
+        }, null, 2) + "\n");
+        return 0;
+    }
+    process.stdout.write(`IICP node doctor — ${saved.name}\n`);
+    process.stdout.write(`  Local health            ${localHealthOk ? "ok" : "failed"} (${localHealthUrl})\n`);
+    if (healthError)
+        process.stdout.write(`  Local health detail     ${healthError}\n`);
+    process.stdout.write(`  Directory prefix        ${prefix}\n`);
+    process.stdout.write(`  Directory presence      ${presence}\n`);
+    process.stdout.write(`  Recovery state          ${state}\n`);
+    process.stdout.write(`  Recommended action      ${action}\n`);
+    process.stdout.write("  Note                    restart is automatic only when supervised services set IICP_SUPERVISED=1\n");
+    return 0;
+}
 /**
  * Resolve a passphrase: $IICP_OPERATOR_PASSPHRASE if set (headless/CI), else an interactive
  * readline prompt (this command is operator-run, so a prompt is fine here — only `serve` must
@@ -1712,16 +1901,46 @@ function printOperatorHelp() {
         `  --directory-url URL        IICP directory base URL (defaults to env / iicp.network)\n` +
         `  -h, --help                 Show this help and exit\n`);
 }
+function printOperatorEncryptHelp() {
+    process.stdout.write(`usage: iicp-node operator encrypt\n\n` +
+        `Password-encrypt the operator secret at rest. The command prompts for a passphrase\n` +
+        `unless $IICP_OPERATOR_PASSPHRASE is set for headless use.\n\n` +
+        `Options:\n` +
+        `  -h, --help                 Show this help and exit without prompting\n`);
+}
+function printOperatorDecryptHelp() {
+    process.stdout.write(`usage: iicp-node operator decrypt\n\n` +
+        `Remove at-rest encryption and store the operator secret in plaintext again. The\n` +
+        `command prompts for the passphrase unless $IICP_OPERATOR_PASSPHRASE is set.\n\n` +
+        `Options:\n` +
+        `  -h, --help                 Show this help and exit without prompting\n`);
+}
 async function runOperator(argv) {
     const sub = argv[0];
     if (sub === undefined || sub === "--help" || sub === "-h") {
         printOperatorHelp();
         return sub === undefined ? 2 : 0;
     }
-    if (sub === "encrypt")
+    if (sub === "encrypt") {
+        const rest = argv.slice(1);
+        if (argsHaveHelp(rest)) {
+            printOperatorEncryptHelp();
+            return 0;
+        }
+        if (rest.length > 0)
+            throw new CliError(`unknown operator encrypt option '${rest[0]}'`);
         return runOperatorEncrypt();
-    if (sub === "decrypt")
+    }
+    if (sub === "decrypt") {
+        const rest = argv.slice(1);
+        if (argsHaveHelp(rest)) {
+            printOperatorDecryptHelp();
+            return 0;
+        }
+        if (rest.length > 0)
+            throw new CliError(`unknown operator decrypt option '${rest[0]}'`);
         return runOperatorDecrypt();
+    }
     if (sub !== "rename") {
         process.stderr.write(`unknown operator subcommand: ${sub}\n`);
         printOperatorHelp();
@@ -2047,7 +2266,18 @@ async function runMcpGateway(argv) {
 /** Command dispatch — separated so main() can wrap parse failures as clean CliError output. */
 // #521 P1 — read-only version check. Exit 10 when a newer release exists
 // (so cron/scripts can act), 0 when current/unreachable. Never installs.
-async function runUpdate() {
+async function runUpdate(argv = []) {
+    const { values } = safeParseArgs({
+        args: argv,
+        options: {
+            help: { type: "boolean", short: "h" },
+        },
+        allowPositionals: false,
+    });
+    if (values.help) {
+        printUpdateHelp();
+        return 0;
+    }
     const { checkUpdate, latestNpmVersion } = await import("./updater.js");
     const latest = await latestNpmVersion();
     const v = checkUpdate(SDK_VERSION, latest);
@@ -2124,11 +2354,13 @@ async function dispatch(argv) {
     if (cmd === "init")
         return runInit();
     if (cmd === "list")
-        return runList();
+        return runList(argv.slice(1));
     if (cmd === "query")
         return runQuery(argv.slice(1));
     if (cmd === "credits")
         return runCredits(argv.slice(1));
+    if (cmd === "doctor")
+        return runDoctor(argv.slice(1));
     if (cmd === "operator")
         return runOperator(argv.slice(1));
     if (cmd === "proxy")
@@ -2136,7 +2368,7 @@ async function dispatch(argv) {
     if (cmd === "mcp-gateway")
         return runMcpGateway(argv.slice(1));
     if (cmd === "update")
-        return runUpdate();
+        return runUpdate(argv.slice(1));
     if (cmd === "service")
         return runService(argv.slice(1));
     if (cmd !== "serve") {
@@ -2179,7 +2411,7 @@ async function dispatch(argv) {
         allowPositionals: false,
     });
     if (values.help) {
-        printHelp();
+        printServeHelp();
         return 0;
     }
     const opts = {