@poolzin/pool-bot 2026.2.20 → 2026.2.22

package/dist/cli/gateway-cli/register.js

@@ -4,50 +4,18 @@ import { loadConfig } from "../../config/config.js";
 import { discoverGatewayBeacons } from "../../infra/bonjour-discovery.js";
 import { resolveWideAreaDiscoveryDomain } from "../../infra/widearea-dns.js";
 import { defaultRuntime } from "../../runtime.js";
+import { styleHealthChannelLine } from "../../terminal/health-style.js";
 import { formatDocsLink } from "../../terminal/links.js";
 import { colorize, isRich, theme } from "../../terminal/theme.js";
 import { formatTokenCount, formatUsd } from "../../utils/usage-format.js";
 import { runCommandWithRuntime } from "../cli-utils.js";
-import { runDaemonInstall, runDaemonRestart, runDaemonStart, runDaemonStatus, runDaemonStop, runDaemonUninstall, } from "../daemon-cli.js";
+import { inheritOptionFromParent } from "../command-options.js";
+import { addGatewayServiceCommands } from "../daemon-cli.js";
+import { formatHelpExamples } from "../help-format.js";
 import { withProgress } from "../progress.js";
 import { callGatewayCli, gatewayCallOpts } from "./call.js";
 import { dedupeBeacons, parseDiscoverTimeoutMs, pickBeaconHost, pickGatewayPort, renderBeaconLines, } from "./discover.js";
 import { addGatewayRunCommand } from "./run.js";
-function styleHealthChannelLine(line, rich) {
-    if (!rich) {
-        return line;
-    }
-    const colon = line.indexOf(":");
-    if (colon === -1) {
-        return line;
-    }
-    const label = line.slice(0, colon + 1);
-    const detail = line.slice(colon + 1).trimStart();
-    const normalized = detail.toLowerCase();
-    const applyPrefix = (prefix, color) => `${label} ${color(detail.slice(0, prefix.length))}${detail.slice(prefix.length)}`;
-    if (normalized.startsWith("failed")) {
-        return applyPrefix("failed", theme.error);
-    }
-    if (normalized.startsWith("ok")) {
-        return applyPrefix("ok", theme.success);
-    }
-    if (normalized.startsWith("linked")) {
-        return applyPrefix("linked", theme.success);
-    }
-    if (normalized.startsWith("configured")) {
-        return applyPrefix("configured", theme.success);
-    }
-    if (normalized.startsWith("not linked")) {
-        return applyPrefix("not linked", theme.warn);
-    }
-    if (normalized.startsWith("not configured")) {
-        return applyPrefix("not configured", theme.muted);
-    }
-    if (normalized.startsWith("unknown")) {
-        return applyPrefix("unknown", theme.warn);
-    }
-    return line;
-}
 function runGatewayCommand(action, label) {
     return runCommandWithRuntime(defaultRuntime, action, (err) => {
         const message = String(err);
@@ -67,6 +35,15 @@ function parseDaysOption(raw, fallback = 30) {
     }
     return fallback;
 }
+function resolveGatewayRpcOptions(opts, command) {
+    const parentToken = inheritOptionFromParent(command, "token");
+    const parentPassword = inheritOptionFromParent(command, "password");
+    return {
+        ...opts,
+        token: opts.token ?? parentToken,
+        password: opts.password ?? parentPassword,
+    };
+}
 function renderCostUsageSummary(summary, days, rich) {
     const totalCost = formatUsd(summary.totals.totalCost) ?? "$0.00";
     const totalTokens = formatTokenCount(summary.totals.totalTokens) ?? "0";
@@ -88,76 +65,28 @@ function renderCostUsageSummary(summary, days, rich) {
 export function registerGatewayCli(program) {
     const gateway = addGatewayRunCommand(program
         .command("gateway")
-        .description("Run the WebSocket Gateway")
-        .addHelpText("after", () => `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/gateway", "docs.molt.bot/cli/gateway")}\n`));
+        .description("Run, inspect, and query the WebSocket Gateway")
+        .addHelpText("after", () => `\n${theme.heading("Examples:")}\n${formatHelpExamples([
+        ["poolbot gateway run", "Run the gateway in the foreground."],
+        ["poolbot gateway status", "Show service status and probe reachability."],
+        ["poolbot gateway discover", "Find local and wide-area gateway beacons."],
+        ["poolbot gateway call health", "Call a gateway RPC method directly."],
+    ])}\n\n${theme.muted("Docs:")} ${formatDocsLink("/cli/gateway", "docs.poolbot.ai/cli/gateway")}\n`));
     addGatewayRunCommand(gateway.command("run").description("Run the WebSocket Gateway (foreground)"));
-    gateway
-        .command("status")
-        .description("Show gateway service status + probe the Gateway")
-        .option("--url <url>", "Gateway WebSocket URL (defaults to config/remote/local)")
-        .option("--token <token>", "Gateway token (if required)")
-        .option("--password <password>", "Gateway password (password auth)")
-        .option("--timeout <ms>", "Timeout in ms", "10000")
-        .option("--no-probe", "Skip RPC probe")
-        .option("--deep", "Scan system-level services", false)
-        .option("--json", "Output JSON", false)
-        .action(async (opts) => {
-        await runDaemonStatus({
-            rpc: opts,
-            probe: Boolean(opts.probe),
-            deep: Boolean(opts.deep),
-            json: Boolean(opts.json),
-        });
-    });
-    gateway
-        .command("install")
-        .description("Install the Gateway service (launchd/systemd/schtasks)")
-        .option("--port <port>", "Gateway port")
-        .option("--runtime <runtime>", "Daemon runtime (node|bun). Default: node")
-        .option("--token <token>", "Gateway token (token auth)")
-        .option("--force", "Reinstall/overwrite if already installed", false)
-        .option("--json", "Output JSON", false)
-        .action(async (opts) => {
-        await runDaemonInstall(opts);
-    });
-    gateway
-        .command("uninstall")
-        .description("Uninstall the Gateway service (launchd/systemd/schtasks)")
-        .option("--json", "Output JSON", false)
-        .action(async (opts) => {
-        await runDaemonUninstall(opts);
-    });
-    gateway
-        .command("start")
-        .description("Start the Gateway service (launchd/systemd/schtasks)")
-        .option("--json", "Output JSON", false)
-        .action(async (opts) => {
-        await runDaemonStart(opts);
-    });
-    gateway
-        .command("stop")
-        .description("Stop the Gateway service (launchd/systemd/schtasks)")
-        .option("--json", "Output JSON", false)
-        .action(async (opts) => {
-        await runDaemonStop(opts);
-    });
-    gateway
-        .command("restart")
-        .description("Restart the Gateway service (launchd/systemd/schtasks)")
-        .option("--json", "Output JSON", false)
-        .action(async (opts) => {
-        await runDaemonRestart(opts);
+    addGatewayServiceCommands(gateway, {
+        statusDescription: "Show gateway service status + probe the Gateway",
     });
     gatewayCallOpts(gateway
         .command("call")
         .description("Call a Gateway method")
         .argument("<method>", "Method name (health/status/system-presence/cron.*)")
         .option("--params <json>", "JSON object string for params", "{}")
-        .action(async (method, opts) => {
+        .action(async (method, opts, command) => {
         await runGatewayCommand(async () => {
+            const rpcOpts = resolveGatewayRpcOptions(opts, command);
             const params = JSON.parse(String(opts.params ?? "{}"));
-            const result = await callGatewayCli(method, opts, params);
-            if (opts.json) {
+            const result = await callGatewayCli(method, rpcOpts, params);
+            if (rpcOpts.json) {
                 defaultRuntime.log(JSON.stringify(result, null, 2));
                 return;
             }
@@ -170,11 +99,12 @@ export function registerGatewayCli(program) {
         .command("usage-cost")
         .description("Fetch usage cost summary from session logs")
         .option("--days <days>", "Number of days to include", "30")
-        .action(async (opts) => {
+        .action(async (opts, command) => {
         await runGatewayCommand(async () => {
+            const rpcOpts = resolveGatewayRpcOptions(opts, command);
             const days = parseDaysOption(opts.days);
-            const result = await callGatewayCli("usage.cost", opts, { days });
-            if (opts.json) {
+            const result = await callGatewayCli("usage.cost", rpcOpts, { days });
+            if (rpcOpts.json) {
                 defaultRuntime.log(JSON.stringify(result, null, 2));
                 return;
             }
@@ -188,10 +118,11 @@ export function registerGatewayCli(program) {
     gatewayCallOpts(gateway
         .command("health")
         .description("Fetch Gateway health")
-        .action(async (opts) => {
+        .action(async (opts, command) => {
         await runGatewayCommand(async () => {
-            const result = await callGatewayCli("health", opts);
-            if (opts.json) {
+            const rpcOpts = resolveGatewayRpcOptions(opts, command);
+            const result = await callGatewayCli("health", rpcOpts);
+            if (rpcOpts.json) {
                 defaultRuntime.log(JSON.stringify(result, null, 2));
                 return;
             }
@@ -218,9 +149,10 @@ export function registerGatewayCli(program) {
         .option("--password <password>", "Gateway password (applies to all probes)")
         .option("--timeout <ms>", "Overall probe budget in ms", "3000")
         .option("--json", "Output JSON", false)
-        .action(async (opts) => {
+        .action(async (opts, command) => {
         await runGatewayCommand(async () => {
-            await gatewayStatusCommand(opts, defaultRuntime);
+            const rpcOpts = resolveGatewayRpcOptions(opts, command);
+            await gatewayStatusCommand(rpcOpts, defaultRuntime);
         });
     });
     gateway

package/dist/cli/gateway-cli/run.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
-import { CONFIG_PATH, loadConfig, readConfigFileSnapshot, resolveGatewayPort, } from "../../config/config.js";
+import path from "node:path";
+import { CONFIG_PATH, loadConfig, readConfigFileSnapshot, resolveStateDir, resolveGatewayPort, } from "../../config/config.js";
 import { resolveGatewayAuth } from "../../gateway/auth.js";
 import { startGatewayServer } from "../../gateway/server.js";
 import { setGatewayWsLogStyle } from "../../gateway/ws-logging.js";
@@ -10,13 +11,52 @@ import { setConsoleSubsystemFilter, setConsoleTimestampPrefix } from "../../logg
 import { createSubsystemLogger } from "../../logging/subsystem.js";
 import { defaultRuntime } from "../../runtime.js";
 import { formatCliCommand } from "../command-format.js";
+import { inheritOptionFromParent } from "../command-options.js";
 import { forceFreePortAndWait } from "../ports.js";
 import { ensureDevGatewayConfig } from "./dev.js";
 import { runGatewayLoop } from "./run-loop.js";
 import { describeUnknownError, extractGatewayMiskeys, maybeExplainGatewayServiceStop, parsePort, toOptionString, } from "./shared.js";
 const gatewayLog = createSubsystemLogger("gateway");
+const GATEWAY_RUN_VALUE_KEYS = [
+    "port",
+    "bind",
+    "token",
+    "auth",
+    "password",
+    "tailscale",
+    "wsLog",
+    "rawStreamPath",
+];
+const GATEWAY_RUN_BOOLEAN_KEYS = [
+    "tailscaleResetOnExit",
+    "allowUnconfigured",
+    "dev",
+    "reset",
+    "force",
+    "verbose",
+    "claudeCliLogs",
+    "compact",
+    "rawStream",
+];
+function resolveGatewayRunOptions(opts, command) {
+    const resolved = { ...opts };
+    for (const key of GATEWAY_RUN_VALUE_KEYS) {
+        const inherited = inheritOptionFromParent(command, key);
+        if (key === "wsLog") {
+            // wsLog has a child default ("auto"), so prefer inherited parent CLI value when present.
+            resolved[key] = inherited ?? resolved[key];
+            continue;
+        }
+        resolved[key] = resolved[key] ?? inherited;
+    }
+    for (const key of GATEWAY_RUN_BOOLEAN_KEYS) {
+        const inherited = inheritOptionFromParent(command, key);
+        resolved[key] = Boolean(resolved[key] || inherited);
+    }
+    return resolved;
+}
 async function runGatewayCommand(opts) {
-    const isDevProfile = (process.env.POOLBOT_PROFILE || process.env.CLAWDBOT_PROFILE)?.trim().toLowerCase() === "dev";
+    const isDevProfile = process.env.POOLBOT_PROFILE?.trim().toLowerCase() === "dev";
     const devMode = Boolean(opts.dev) || isDevProfile;
     if (opts.reset && !devMode) {
         defaultRuntime.error("Use --reset with --dev.");
@@ -28,7 +68,6 @@ async function runGatewayCommand(opts) {
     if (opts.claudeCliLogs) {
         setConsoleSubsystemFilter(["agent/claude-cli"]);
         process.env.POOLBOT_CLAUDE_CLI_LOG_OUTPUT = "1";
-        process.env.CLAWDBOT_CLAUDE_CLI_LOG_OUTPUT = "1";
     }
     const wsLogRaw = (opts.compact ? "compact" : opts.wsLog);
     const wsLogStyle = wsLogRaw === "compact" ? "compact" : wsLogRaw === "full" ? "full" : "auto";
@@ -42,12 +81,10 @@ async function runGatewayCommand(opts) {
     setGatewayWsLogStyle(wsLogStyle);
     if (opts.rawStream) {
         process.env.POOLBOT_RAW_STREAM = "1";
-        process.env.CLAWDBOT_RAW_STREAM = "1";
     }
     const rawStreamPath = toOptionString(opts.rawStreamPath);
     if (rawStreamPath) {
         process.env.POOLBOT_RAW_STREAM_PATH = rawStreamPath;
-        process.env.CLAWDBOT_RAW_STREAM_PATH = rawStreamPath;
     }
     if (devMode) {
         await ensureDevGatewayConfig({ reset: Boolean(opts.reset) });
@@ -95,7 +132,6 @@ async function runGatewayCommand(opts) {
         const token = toOptionString(opts.token);
         if (token) {
             process.env.POOLBOT_GATEWAY_TOKEN = token;
-            process.env.CLAWDBOT_GATEWAY_TOKEN = token;
         }
     }
     const authModeRaw = toOptionString(opts.auth);
@@ -116,7 +152,9 @@ async function runGatewayCommand(opts) {
     }
     const passwordRaw = toOptionString(opts.password);
     const tokenRaw = toOptionString(opts.token);
-    const configExists = fs.existsSync(CONFIG_PATH);
+    const snapshot = await readConfigFileSnapshot().catch(() => null);
+    const configExists = snapshot?.exists ?? fs.existsSync(CONFIG_PATH);
+    const configAuditPath = path.join(resolveStateDir(process.env), "logs", "config-audit.jsonl");
     const mode = cfg.gateway?.mode;
     if (!opts.allowUnconfigured && mode !== "local") {
         if (!configExists) {
@@ -124,6 +162,7 @@ async function runGatewayCommand(opts) {
         }
         else {
             defaultRuntime.error(`Gateway start blocked: set gateway.mode=local (current: ${mode ?? "unset"}) or pass --allow-unconfigured.`);
+            defaultRuntime.error(`Config write audit: ${configAuditPath}`);
         }
         defaultRuntime.exit(1);
         return;
@@ -141,7 +180,6 @@ async function runGatewayCommand(opts) {
         defaultRuntime.exit(1);
         return;
     }
-    const snapshot = await readConfigFileSnapshot().catch(() => null);
     const miskeys = extractGatewayMiskeys(snapshot?.parsed);
     const authConfig = {
         ...cfg.gateway?.auth,
@@ -189,7 +227,7 @@ async function runGatewayCommand(opts) {
         defaultRuntime.exit(1);
         return;
     }
-    if (bind !== "loopback" && !hasSharedSecret) {
+    if (bind !== "loopback" && !hasSharedSecret && resolvedAuthMode !== "trusted-proxy") {
         defaultRuntime.error([
             `Refusing to bind gateway to ${bind} without auth.`,
             "Set gateway.auth.token/password (or POOLBOT_GATEWAY_TOKEN/POOLBOT_GATEWAY_PASSWORD) or pass --token/--password.",
@@ -264,7 +302,7 @@ export function addGatewayRunCommand(cmd) {
         .option("--compact", 'Alias for "--ws-log compact"', false)
         .option("--raw-stream", "Log raw model stream events to jsonl", false)
         .option("--raw-stream-path <path>", "Raw stream jsonl path")
-        .action(async (opts) => {
-        await runGatewayCommand(opts);
+        .action(async (opts, command) => {
+        await runGatewayCommand(resolveGatewayRunOptions(opts, command));
     });
 }

package/dist/cli/nodes-camera.js

@@ -3,6 +3,7 @@ import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
 import { resolveCliName } from "./cli-name.js";
+const MAX_CAMERA_URL_DOWNLOAD_BYTES = 250 * 1024 * 1024;
 function asRecord(value) {
     return typeof value === "object" && value !== null ? value : {};
 }
@@ -19,23 +20,25 @@ export function parseCameraSnapPayload(value) {
     const obj = asRecord(value);
     const format = asString(obj.format);
     const base64 = asString(obj.base64);
+    const url = asString(obj.url);
     const width = asNumber(obj.width);
     const height = asNumber(obj.height);
-    if (!format || !base64 || width === undefined || height === undefined) {
+    if (!format || (!base64 && !url) || width === undefined || height === undefined) {
         throw new Error("invalid camera.snap payload");
     }
-    return { format, base64, width, height };
+    return { format, ...(base64 ? { base64 } : {}), ...(url ? { url } : {}), width, height };
 }
 export function parseCameraClipPayload(value) {
     const obj = asRecord(value);
     const format = asString(obj.format);
     const base64 = asString(obj.base64);
+    const url = asString(obj.url);
     const durationMs = asNumber(obj.durationMs);
     const hasAudio = asBoolean(obj.hasAudio);
-    if (!format || !base64 || durationMs === undefined || hasAudio === undefined) {
+    if (!format || (!base64 && !url) || durationMs === undefined || hasAudio === undefined) {
         throw new Error("invalid camera.clip payload");
     }
-    return { format, base64, durationMs, hasAudio };
+    return { format, ...(base64 ? { base64 } : {}), ...(url ? { url } : {}), durationMs, hasAudio };
 }
 export function cameraTempPath(opts) {
     const tmpDir = opts.tmpDir ?? os.tmpdir();
@@ -45,6 +48,58 @@ export function cameraTempPath(opts) {
     const cliName = resolveCliName();
     return path.join(tmpDir, `${cliName}-camera-${opts.kind}${facingPart}-${id}${ext}`);
 }
+export async function writeUrlToFile(filePath, url) {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "https:") {
+        throw new Error(`writeUrlToFile: only https URLs are allowed, got ${parsed.protocol}`);
+    }
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new Error(`failed to download ${url}: ${res.status} ${res.statusText}`);
+    }
+    const contentLengthRaw = res.headers.get("content-length");
+    const contentLength = contentLengthRaw ? Number.parseInt(contentLengthRaw, 10) : undefined;
+    if (typeof contentLength === "number" &&
+        Number.isFinite(contentLength) &&
+        contentLength > MAX_CAMERA_URL_DOWNLOAD_BYTES) {
+        throw new Error(`writeUrlToFile: content-length ${contentLength} exceeds max ${MAX_CAMERA_URL_DOWNLOAD_BYTES}`);
+    }
+    const body = res.body;
+    if (!body) {
+        throw new Error(`failed to download ${url}: empty response body`);
+    }
+    const fileHandle = await fs.open(filePath, "w");
+    let bytes = 0;
+    let thrown;
+    try {
+        const reader = body.getReader();
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done) {
+                break;
+            }
+            if (!value || value.byteLength === 0) {
+                continue;
+            }
+            bytes += value.byteLength;
+            if (bytes > MAX_CAMERA_URL_DOWNLOAD_BYTES) {
+                throw new Error(`writeUrlToFile: downloaded ${bytes} bytes, exceeds max ${MAX_CAMERA_URL_DOWNLOAD_BYTES}`);
+            }
+            await fileHandle.write(value);
+        }
+    }
+    catch (err) {
+        thrown = err;
+    }
+    finally {
+        await fileHandle.close();
+    }
+    if (thrown) {
+        await fs.unlink(filePath).catch(() => { });
+        throw thrown;
+    }
+    return { path: filePath, bytes };
+}
 export async function writeBase64ToFile(filePath, base64) {
     const buf = Buffer.from(base64, "base64");
     await fs.writeFile(filePath, buf);

package/dist/cli/nodes-cli/register.camera.js

@@ -1,17 +1,17 @@
-import { randomIdempotencyKey } from "../../gateway/call.js";
 import { defaultRuntime } from "../../runtime.js";
-import { cameraTempPath, parseCameraClipPayload, parseCameraSnapPayload, writeBase64ToFile, } from "../nodes-camera.js";
-import { parseDurationMs } from "../parse-duration.js";
-import { getNodesTheme, runNodesCommand } from "./cli-utils.js";
-import { callGatewayCli, nodesCallOpts, resolveNodeId } from "./rpc.js";
 import { renderTable } from "../../terminal/table.js";
 import { shortenHomePath } from "../../utils.js";
+import { cameraTempPath, parseCameraClipPayload, parseCameraSnapPayload, writeBase64ToFile, writeUrlToFile, } from "../nodes-camera.js";
+import { parseDurationMs } from "../parse-duration.js";
+import { getNodesTheme, runNodesCommand } from "./cli-utils.js";
+import { buildNodeInvokeParams, callGatewayCli, nodesCallOpts, resolveNodeId } from "./rpc.js";
 const parseFacing = (value) => {
     const v = String(value ?? "")
         .trim()
         .toLowerCase();
-    if (v === "front" || v === "back")
+    if (v === "front" || v === "back") {
         return v;
+    }
     throw new Error(`invalid facing: ${value} (expected front|back)`);
 };
 export function registerNodesCameraCommands(nodes) {
@@ -23,11 +23,10 @@ export function registerNodesCameraCommands(nodes) {
         .action(async (opts) => {
         await runNodesCommand("camera list", async () => {
             const nodeId = await resolveNodeId(opts, String(opts.node ?? ""));
-            const raw = (await callGatewayCli("node.invoke", opts, {
+            const raw = await callGatewayCli("node.invoke", opts, buildNodeInvokeParams({
                 nodeId,
                 command: "camera.list",
                 params: {},
-                idempotencyKey: randomIdempotencyKey(),
             }));
             const res = typeof raw === "object" && raw !== null ? raw : {};
             const payload = typeof res.payload === "object" && res.payload !== null
@@ -94,7 +93,7 @@ export function registerNodesCameraCommands(nodes) {
                 : undefined;
             const results = [];
             for (const facing of facings) {
-                const invokeParams = {
+                const invokeParams = buildNodeInvokeParams({
                     nodeId,
                     command: "camera.snap",
                     params: {
@@ -105,12 +104,9 @@ export function registerNodesCameraCommands(nodes) {
                         delayMs: Number.isFinite(delayMs) ? delayMs : undefined,
                         deviceId: deviceId || undefined,
                     },
-                    idempotencyKey: randomIdempotencyKey(),
-                };
-                if (typeof timeoutMs === "number" && Number.isFinite(timeoutMs)) {
-                    invokeParams.timeoutMs = timeoutMs;
-                }
-                const raw = (await callGatewayCli("node.invoke", opts, invokeParams));
+                    timeoutMs,
+                });
+                const raw = await callGatewayCli("node.invoke", opts, invokeParams);
                 const res = typeof raw === "object" && raw !== null ? raw : {};
                 const payload = parseCameraSnapPayload(res.payload);
                 const filePath = cameraTempPath({
@@ -118,7 +114,12 @@ export function registerNodesCameraCommands(nodes) {
                     facing,
                     ext: payload.format === "jpeg" ? "jpg" : payload.format,
                 });
-                await writeBase64ToFile(filePath, payload.base64);
+                if (payload.url) {
+                    await writeUrlToFile(filePath, payload.url);
+                }
+                else if (payload.base64) {
+                    await writeBase64ToFile(filePath, payload.base64);
+                }
                 results.push({
                     facing,
                     path: filePath,
@@ -152,7 +153,7 @@ export function registerNodesCameraCommands(nodes) {
                 ? Number.parseInt(String(opts.invokeTimeout), 10)
                 : undefined;
             const deviceId = opts.deviceId ? String(opts.deviceId).trim() : undefined;
-            const invokeParams = {
+            const invokeParams = buildNodeInvokeParams({
                 nodeId,
                 command: "camera.clip",
                 params: {
@@ -162,12 +163,9 @@ export function registerNodesCameraCommands(nodes) {
                     format: "mp4",
                     deviceId: deviceId || undefined,
                 },
-                idempotencyKey: randomIdempotencyKey(),
-            };
-            if (typeof timeoutMs === "number" && Number.isFinite(timeoutMs)) {
-                invokeParams.timeoutMs = timeoutMs;
-            }
-            const raw = (await callGatewayCli("node.invoke", opts, invokeParams));
+                timeoutMs,
+            });
+            const raw = await callGatewayCli("node.invoke", opts, invokeParams);
             const res = typeof raw === "object" && raw !== null ? raw : {};
             const payload = parseCameraClipPayload(res.payload);
             const filePath = cameraTempPath({
@@ -175,7 +173,12 @@ export function registerNodesCameraCommands(nodes) {
                 facing,
                 ext: payload.format,
             });
-            await writeBase64ToFile(filePath, payload.base64);
+            if (payload.url) {
+                await writeUrlToFile(filePath, payload.url);
+            }
+            else if (payload.base64) {
+                await writeBase64ToFile(filePath, payload.base64);
+            }
             if (opts.json) {
                 defaultRuntime.log(JSON.stringify({
                     file: {

package/dist/cli/nodes-cli/rpc.js

@@ -1,4 +1,5 @@
-import { callGateway } from "../../gateway/call.js";
+import { callGateway, randomIdempotencyKey } from "../../gateway/call.js";
+import { resolveNodeIdFromCandidates } from "../../shared/node-match.js";
 import { GATEWAY_CLIENT_MODES, GATEWAY_CLIENT_NAMES } from "../../utils/message-channel.js";
 import { withProgress } from "../progress.js";
 import { parseNodeList, parsePairingList } from "./format.js";
@@ -7,7 +8,7 @@ export const nodesCallOpts = (cmd, defaults) => cmd
     .option("--token <token>", "Gateway token (if required)")
     .option("--timeout <ms>", "Timeout in ms", String(defaults?.timeoutMs ?? 10_000))
     .option("--json", "Output JSON", false);
-export const callGatewayCli = async (method, opts, params) => withProgress({
+export const callGatewayCli = async (method, opts, params, callOpts) => withProgress({
     label: `Nodes ${method}`,
     indeterminate: true,
     enabled: opts.json !== true,
@@ -16,10 +17,22 @@ export const callGatewayCli = async (method, opts, params) => withProgress({
     token: opts.token,
     method,
     params,
-    timeoutMs: Number(opts.timeout ?? 10_000),
+    timeoutMs: callOpts?.transportTimeoutMs ?? Number(opts.timeout ?? 10_000),
     clientName: GATEWAY_CLIENT_NAMES.CLI,
     mode: GATEWAY_CLIENT_MODES.CLI,
 }));
+export function buildNodeInvokeParams(params) {
+    const invokeParams = {
+        nodeId: params.nodeId,
+        command: params.command,
+        params: params.params,
+        idempotencyKey: params.idempotencyKey ?? randomIdempotencyKey(),
+    };
+    if (typeof params.timeoutMs === "number" && Number.isFinite(params.timeoutMs)) {
+        invokeParams.timeoutMs = params.timeoutMs;
+    }
+    return invokeParams;
+}
 export function unauthorizedHintForMessage(message) {
     const haystack = message.toLowerCase();
     if (haystack.includes("unauthorizedclient") ||
@@ -33,24 +46,18 @@ export function unauthorizedHintForMessage(message) {
     }
     return null;
 }
-function normalizeNodeKey(value) {
-    return value
-        .toLowerCase()
-        .replace(/[^a-z0-9]+/g, "-")
-        .replace(/^-+/, "")
-        .replace(/-+$/, "");
-}
 export async function resolveNodeId(opts, query) {
     const q = String(query ?? "").trim();
-    if (!q)
+    if (!q) {
         throw new Error("node required");
+    }
     let nodes = [];
     try {
-        const res = (await callGatewayCli("node.list", opts, {}));
+        const res = await callGatewayCli("node.list", opts, {});
         nodes = parseNodeList(res);
     }
     catch {
-        const res = (await callGatewayCli("node.pair.list", opts, {}));
+        const res = await callGatewayCli("node.pair.list", opts, {});
         const { paired } = parsePairingList(res);
         nodes = paired.map((n) => ({
             nodeId: n.nodeId,
@@ -60,29 +67,5 @@ export async function resolveNodeId(opts, query) {
             remoteIp: n.remoteIp,
         }));
     }
-    const qNorm = normalizeNodeKey(q);
-    const matches = nodes.filter((n) => {
-        if (n.nodeId === q)
-            return true;
-        if (typeof n.remoteIp === "string" && n.remoteIp === q)
-            return true;
-        const name = typeof n.displayName === "string" ? n.displayName : "";
-        if (name && normalizeNodeKey(name) === qNorm)
-            return true;
-        if (q.length >= 6 && n.nodeId.startsWith(q))
-            return true;
-        return false;
-    });
-    if (matches.length === 1)
-        return matches[0].nodeId;
-    if (matches.length === 0) {
-        const known = nodes
-            .map((n) => n.displayName || n.remoteIp || n.nodeId)
-            .filter(Boolean)
-            .join(", ");
-        throw new Error(`unknown node: ${q}${known ? ` (known: ${known})` : ""}`);
-    }
-    throw new Error(`ambiguous node: ${q} (matches: ${matches
-        .map((n) => n.displayName || n.remoteIp || n.nodeId)
-        .join(", ")})`);
+    return resolveNodeIdFromCandidates(nodes, q);
 }

package/dist/cli/qr-cli.js

@@ -114,14 +114,14 @@ export function registerQrCli(program) {
             }
             const lines = [
                 theme.heading("Pairing QR"),
-                "Scan this with the OpenClaw iOS app (Onboarding -> Scan QR).",
+                "Scan this with the Pool Bot iOS app (Onboarding -> Scan QR).",
                 "",
             ];
             if (opts.ascii !== false) {
                 const qrAscii = await renderQrAscii(setupCode);
                 lines.push(qrAscii.trimEnd(), "");
             }
-            lines.push(`${theme.muted("Setup code:")} ${setupCode}`, `${theme.muted("Gateway:")} ${resolved.payload.url}`, `${theme.muted("Auth:")} ${resolved.authLabel}`, `${theme.muted("Source:")} ${resolved.urlSource}`, "", "Approve after scan with:", `  ${theme.command("openclaw devices list")}`, `  ${theme.command("openclaw devices approve <requestId>")}`);
+            lines.push(`${theme.muted("Setup code:")} ${setupCode}`, `${theme.muted("Gateway:")} ${resolved.payload.url}`, `${theme.muted("Auth:")} ${resolved.authLabel}`, `${theme.muted("Source:")} ${resolved.urlSource}`, "", "Approve after scan with:", `  ${theme.command("poolbot devices list")}`, `  ${theme.command("poolbot devices approve <requestId>")}`);
             defaultRuntime.log(lines.join("\n"));
         }
         catch (err) {