@iicp/client 0.7.76 → 0.7.78

package/README.md

@@ -39,7 +39,7 @@ 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.76 or newer
+iicp-node --version    # prints iicp-node 0.7.78 or newer
 ```
 
 The query command contacts the public directory, discovers a matching live node,
@@ -88,17 +88,18 @@ base URL. Full guide: <https://iicp.network/docs/proxy>
 
 ## Provider upgrade note
 
-> **Upgrade note (0.7.76)** — 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
-> public `/iicp/health` verifies; supervised services and Docker containers now
-> fail visibly so launchd/systemd/Docker can restart instead of staying stuck.
-> This release also paces accountless Cloudflare Quick Tunnel creation across
-> local nodes, serializes concurrent tunnel starts, persists `429` / `1015`
-> cooldowns, and falls back to the previous reachability method while the
-> tunnel budget recovers. Persistent relays should use a named tunnel or
-> `IICP_PUBLIC_ENDPOINT`.
+> **Upgrade note (0.7.78)** — upgrade relay-capable and provider nodes so relay
+> services do not disappear during temporary public-tunnel recovery. Relay-capable
+> nodes now keep their role as relay infrastructure: if their own Quick Tunnel is
+> cooling down or unavailable, they do **not** fall back through another relay or
+> accidentally self-elect as a relay worker. Supervised services fail visibly so
+> launchd/systemd/Docker can retry the public route, while ordinary provider nodes
+> can still use relay fallback as the last-resort path.
+>
+> This keeps the 0.7.77 tunnel hardening intact: Quick Tunnel endpoints still
+> recover safely after sleep, idle, Cloudflare edge drops, local DNS propagation
+> lag, and `429` / `1015` cooldowns. Persistent relays should use a named tunnel
+> or `IICP_PUBLIC_ENDPOINT`.
 
 ### Keeping provider nodes current
 
@@ -112,7 +113,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.76 can intentionally exit from a confirmed tunnel-dead state and let Docker
+0.7.78 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

package/dist/cli.d.ts

@@ -49,6 +49,7 @@ export type TunnelDeadPolicy = "auto" | "retry" | "exit" | "log-only";
 export type TunnelDeadBehavior = "exit" | "retry" | "log-only";
 export declare function tunnelDeadPolicyFromEnv(): TunnelDeadPolicy;
 export declare function tunnelDeadBehavior(policy: TunnelDeadPolicy, supervised: boolean): TunnelDeadBehavior;
+export declare function relayWorkerFallbackAllowed(relayCapable: boolean | undefined): boolean;
 /**
  * Pure reachability escalation planner (tunnel-FIRST, relay = last resort; maintainer
  * 2026-06-13). Returns the ordered attempt sequence for a tier-≥3 node with no explicitly

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;AAqfD,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":"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"}

package/dist/cli.js

@@ -5,6 +5,7 @@ exports.TUNNEL_DEAD_EXIT_CODE = void 0;
 exports.startProviderAutoUpdate = startProviderAutoUpdate;
 exports.tunnelDeadPolicyFromEnv = tunnelDeadPolicyFromEnv;
 exports.tunnelDeadBehavior = tunnelDeadBehavior;
+exports.relayWorkerFallbackAllowed = relayWorkerFallbackAllowed;
 exports.planReachability = planReachability;
 exports.endpointIsLocalOrPrivate = endpointIsLocalOrPrivate;
 exports.directTunnelFallbackReason = directTunnelFallbackReason;
@@ -46,6 +47,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");
 /**
@@ -132,17 +134,34 @@ function tunnelDeadBehavior(policy, supervised) {
         return supervised ? "exit" : "retry";
     return policy;
 }
+function relayWorkerFallbackAllowed(relayCapable) {
+    // A relay-capable node is relay infrastructure. If its own public route is
+    // unavailable, supervised services should restart and retry the public route
+    // instead of turning into a relay worker and removing relay capacity.
+    return relayCapable !== true;
+}
+async function exitIfSupervisedPublicFallbackUnrecovered() {
+    if (tunnelDeadBehavior(tunnelDeadPolicyFromEnv(), envBool("IICP_SUPERVISED")) !== "exit")
+        return;
+    // eslint-disable-next-line no-console
+    console.error(`[iicp-node] public fallback is still unavailable after tunnel/relay attempts. ` +
+        `Exiting with code ${exports.TUNNEL_DEAD_EXIT_CODE} so the supervisor can retry instead of ` +
+        `advertising an unverified direct route.`);
+    process.exit(exports.TUNNEL_DEAD_EXIT_CODE);
+}
 function printHelp() {
     process.stdout.write(`usage: iicp-node <command> [options]\n\n` +
         `Commands:\n` +
         `  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 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 +206,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 +498,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`);
@@ -491,7 +573,7 @@ async function _autoElectRelay(directoryUrl, intent, nodeId) {
         if (!resp.ok)
             return null;
         const data = await resp.json();
-        const candidates = (data.nodes ?? []).filter((n) => n.relay_capable && n.endpoint);
+        const candidates = (data.nodes ?? []).filter((n) => n.relay_capable && n.endpoint && n.node_id !== nodeId);
         if (!candidates.length)
             return null;
         const { createHash } = await import("node:crypto");
@@ -757,6 +839,12 @@ async function runServe(opts) {
                     }
                 }
                 else if (step === "relay") {
+                    if (!relayWorkerFallbackAllowed(opts.relayCapable)) {
+                        // eslint-disable-next-line no-console
+                        console.warn(`[iicp-node] NAT tier=${natProfile.tier}: no tunnel for relay-capable node — ` +
+                            "not falling back through another relay; supervisor will retry the public route.");
+                        break;
+                    }
                     // eslint-disable-next-line no-console
                     console.log(`[iicp-node] NAT tier=${natProfile.tier}: no tunnel — auto-electing a relay from directory (last resort)…`);
                     const elected = await _autoElectRelay(opts.directoryUrl ?? "https://iicp.network/api", opts.intent, nodeId);
@@ -814,7 +902,7 @@ async function runServe(opts) {
             if (tunnelHandle) {
                 publicEndpoint = tunnelHandle.url;
             }
-            else {
+            else if (relayWorkerFallbackAllowed(opts.relayCapable)) {
                 // eslint-disable-next-line no-console
                 console.log("[iicp-node] no tunnel available — auto-electing a relay from directory (last resort)…");
                 const elected = await _autoElectRelay(opts.directoryUrl ?? "https://iicp.network/api", opts.intent, nodeId);
@@ -825,6 +913,12 @@ async function runServe(opts) {
                     console.log(`[iicp-node] auto-elected relay (last resort): ${relayHost}:${relayPort}`);
                 }
             }
+            else {
+                // eslint-disable-next-line no-console
+                console.warn("[iicp-node] no tunnel available for relay-capable node — not falling back through " +
+                    "another relay; supervisor will retry the public route.");
+                await exitIfSupervisedPublicFallbackUnrecovered();
+            }
         }
     }
     const backendFlavor = await detectBackendFlavor(opts.backendUrl, opts.backendApiKey, opts.backendType);
@@ -1646,6 +1740,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
@@ -1738,16 +1929,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();
@@ -2073,7 +2294,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);
@@ -2150,11 +2382,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")
@@ -2162,7 +2396,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") {
@@ -2205,7 +2439,7 @@ async function dispatch(argv) {
         allowPositionals: false,
     });
     if (values.help) {
-        printHelp();
+        printServeHelp();
         return 0;
     }
     const opts = {