@poolzin/pool-bot 2026.2.25 → 2026.2.26

package/dist/cli/daemon-cli/lifecycle.js

@@ -1,6 +1,24 @@
+import { loadConfig, resolveGatewayPort } from "../../config/config.js";
 import { resolveGatewayService } from "../../daemon/service.js";
+import { defaultRuntime } from "../../runtime.js";
+import { theme } from "../../terminal/theme.js";
+import { formatCliCommand } from "../command-format.js";
 import { runServiceRestart, runServiceStart, runServiceStop, runServiceUninstall, } from "./lifecycle-core.js";
-import { renderGatewayServiceStartHints } from "./shared.js";
+import { renderRestartDiagnostics, terminateStaleGatewayPids, waitForGatewayHealthyRestart, } from "./restart-health.js";
+import { parsePortFromArgs, renderGatewayServiceStartHints } from "./shared.js";
+const POST_RESTART_HEALTH_ATTEMPTS = 8;
+const POST_RESTART_HEALTH_DELAY_MS = 450;
+async function resolveGatewayRestartPort() {
+    const service = resolveGatewayService();
+    const command = await service.readCommand(process.env).catch(() => null);
+    const serviceEnv = command?.environment ?? undefined;
+    const mergedEnv = {
+        ...process.env,
+        ...(serviceEnv ?? undefined),
+    };
+    const portFromArgs = parsePortFromArgs(command?.programArguments);
+    return portFromArgs ?? resolveGatewayPort(loadConfig(), mergedEnv);
+}
 export async function runDaemonUninstall(opts = {}) {
     return await runServiceUninstall({
         serviceNoun: "Gateway",
@@ -31,11 +49,55 @@ export async function runDaemonStop(opts = {}) {
  * Throws/exits on check or restart failures.
  */
 export async function runDaemonRestart(opts = {}) {
+    const json = Boolean(opts.json);
+    const service = resolveGatewayService();
+    const restartPort = await resolveGatewayRestartPort().catch(() => resolveGatewayPort(loadConfig(), process.env));
     return await runServiceRestart({
         serviceNoun: "Gateway",
-        service: resolveGatewayService(),
+        service,
         renderStartHints: renderGatewayServiceStartHints,
         opts,
         checkTokenDrift: true,
+        postRestartCheck: async ({ warnings, fail, stdout }) => {
+            let health = await waitForGatewayHealthyRestart({
+                service,
+                port: restartPort,
+                attempts: POST_RESTART_HEALTH_ATTEMPTS,
+                delayMs: POST_RESTART_HEALTH_DELAY_MS,
+            });
+            if (!health.healthy && health.staleGatewayPids.length > 0) {
+                const staleMsg = `Found stale gateway process(es): ${health.staleGatewayPids.join(", ")}.`;
+                warnings.push(staleMsg);
+                if (!json) {
+                    defaultRuntime.log(theme.warn(staleMsg));
+                    defaultRuntime.log(theme.muted("Stopping stale process(es) and retrying restart..."));
+                }
+                await terminateStaleGatewayPids(health.staleGatewayPids);
+                await service.restart({ env: process.env, stdout });
+                health = await waitForGatewayHealthyRestart({
+                    service,
+                    port: restartPort,
+                    attempts: POST_RESTART_HEALTH_ATTEMPTS,
+                    delayMs: POST_RESTART_HEALTH_DELAY_MS,
+                });
+            }
+            if (health.healthy) {
+                return;
+            }
+            const diagnostics = renderRestartDiagnostics(health);
+            if (!json) {
+                defaultRuntime.log(theme.warn("Gateway did not become healthy after restart."));
+                for (const line of diagnostics) {
+                    defaultRuntime.log(theme.muted(line));
+                }
+            }
+            else {
+                warnings.push(...diagnostics);
+            }
+            fail("Gateway restart failed health checks.", [
+                formatCliCommand("poolbot gateway status --probe --deep"),
+                formatCliCommand("poolbot doctor"),
+            ]);
+        },
     });
 }

package/dist/cli/daemon-cli/restart-health.js

@@ -0,0 +1,126 @@
+import { classifyPortListener, formatPortDiagnostics, inspectPortUsage, } from "../../infra/ports.js";
+import { sleep } from "../../utils.js";
+export const DEFAULT_RESTART_HEALTH_ATTEMPTS = 8;
+export const DEFAULT_RESTART_HEALTH_DELAY_MS = 450;
+export async function inspectGatewayRestart(params) {
+    const env = params.env ?? process.env;
+    let runtime = { status: "unknown" };
+    try {
+        runtime = await params.service.readRuntime(env);
+    }
+    catch (err) {
+        runtime = { status: "unknown", detail: String(err) };
+    }
+    let portUsage;
+    try {
+        portUsage = await inspectPortUsage(params.port);
+    }
+    catch (err) {
+        portUsage = {
+            port: params.port,
+            status: "unknown",
+            listeners: [],
+            hints: [],
+            errors: [String(err)],
+        };
+    }
+    const gatewayListeners = portUsage.status === "busy"
+        ? portUsage.listeners.filter((listener) => classifyPortListener(listener, params.port) === "gateway")
+        : [];
+    const running = runtime.status === "running";
+    const ownsPort = runtime.pid != null
+        ? portUsage.listeners.some((listener) => listener.pid === runtime.pid)
+        : gatewayListeners.length > 0 ||
+            (portUsage.status === "busy" && portUsage.listeners.length === 0);
+    const healthy = running && ownsPort;
+    const staleGatewayPids = Array.from(new Set(gatewayListeners
+        .map((listener) => listener.pid)
+        .filter((pid) => Number.isFinite(pid))
+        .filter((pid) => runtime.pid == null || pid !== runtime.pid || !running)));
+    return {
+        runtime,
+        portUsage,
+        healthy,
+        staleGatewayPids,
+    };
+}
+export async function waitForGatewayHealthyRestart(params) {
+    const attempts = params.attempts ?? DEFAULT_RESTART_HEALTH_ATTEMPTS;
+    const delayMs = params.delayMs ?? DEFAULT_RESTART_HEALTH_DELAY_MS;
+    let snapshot = await inspectGatewayRestart({
+        service: params.service,
+        port: params.port,
+        env: params.env,
+    });
+    for (let attempt = 0; attempt < attempts; attempt += 1) {
+        if (snapshot.healthy) {
+            return snapshot;
+        }
+        if (snapshot.staleGatewayPids.length > 0 && snapshot.runtime.status !== "running") {
+            return snapshot;
+        }
+        await sleep(delayMs);
+        snapshot = await inspectGatewayRestart({
+            service: params.service,
+            port: params.port,
+            env: params.env,
+        });
+    }
+    return snapshot;
+}
+export function renderRestartDiagnostics(snapshot) {
+    const lines = [];
+    const runtimeSummary = [
+        snapshot.runtime.status ? `status=${snapshot.runtime.status}` : null,
+        snapshot.runtime.state ? `state=${snapshot.runtime.state}` : null,
+        snapshot.runtime.pid != null ? `pid=${snapshot.runtime.pid}` : null,
+        snapshot.runtime.lastExitStatus != null ? `lastExit=${snapshot.runtime.lastExitStatus}` : null,
+    ]
+        .filter(Boolean)
+        .join(", ");
+    if (runtimeSummary) {
+        lines.push(`Service runtime: ${runtimeSummary}`);
+    }
+    if (snapshot.portUsage.status === "busy") {
+        lines.push(...formatPortDiagnostics(snapshot.portUsage));
+    }
+    else {
+        lines.push(`Gateway port ${snapshot.portUsage.port} status: ${snapshot.portUsage.status}.`);
+    }
+    if (snapshot.portUsage.errors?.length) {
+        lines.push(`Port diagnostics errors: ${snapshot.portUsage.errors.join("; ")}`);
+    }
+    return lines;
+}
+export async function terminateStaleGatewayPids(pids) {
+    const killed = [];
+    for (const pid of pids) {
+        try {
+            process.kill(pid, "SIGTERM");
+            killed.push(pid);
+        }
+        catch (err) {
+            const code = err?.code;
+            if (code !== "ESRCH") {
+                throw err;
+            }
+        }
+    }
+    if (killed.length === 0) {
+        return killed;
+    }
+    await sleep(400);
+    for (const pid of killed) {
+        try {
+            process.kill(pid, 0);
+            process.kill(pid, "SIGKILL");
+        }
+        catch (err) {
+            const code = err?.code;
+            if (code !== "ESRCH") {
+                throw err;
+            }
+        }
+    }
+    return killed;
+}

package/dist/cli/daemon-cli/status.gather.js

@@ -1,19 +1,20 @@
 import { createConfigIO, resolveConfigPath, resolveGatewayPort, resolveStateDir, } from "../../config/config.js";
 import { readLastGatewayErrorLine } from "../../daemon/diagnostics.js";
 import { findExtraGatewayServices } from "../../daemon/inspect.js";
-import { findLegacyGatewayServices } from "../../daemon/legacy.js";
-import { resolveGatewayService } from "../../daemon/service.js";
 import { auditGatewayServiceConfig } from "../../daemon/service-audit.js";
+import { resolveGatewayService } from "../../daemon/service.js";
 import { resolveGatewayBindHost } from "../../gateway/net.js";
 import { formatPortDiagnostics, inspectPortUsage, } from "../../infra/ports.js";
 import { pickPrimaryTailnetIPv4 } from "../../infra/tailnet.js";
 import { probeGatewayStatus } from "./probe.js";
 import { normalizeListenerAddress, parsePortFromArgs, pickProbeHostForBind } from "./shared.js";
 function shouldReportPortUsage(status, rpcOk) {
-    if (status !== "busy")
+    if (status !== "busy") {
         return false;
-    if (rpcOk === true)
+    }
+    if (rpcOk === true) {
         return false;
+    }
     return true;
 }
 export async function gatherDaemonStatus(opts) {
@@ -73,7 +74,7 @@ export async function gatherDaemonStatus(opts) {
     const probeUrlOverride = typeof opts.rpc.url === "string" && opts.rpc.url.trim().length > 0 ? opts.rpc.url.trim() : null;
     const probeUrl = probeUrlOverride ?? `ws://${probeHost}:${daemonPort}`;
     const probeNote = !probeUrlOverride && bindMode === "lan"
-        ? "Local probe uses loopback (127.0.0.1). bind=lan listens on 0.0.0.0 (all interfaces); use a LAN IP for remote clients."
+        ? `bind=lan listens on 0.0.0.0 (all interfaces); probing via ${probeHost}.`
         : !probeUrlOverride && bindMode === "loopback"
             ? "Loopback-only gateway; only local clients can connect."
             : undefined;
@@ -98,20 +99,15 @@ export async function gatherDaemonStatus(opts) {
             hints: portCliDiagnostics.hints,
         }
         : undefined;
-    const legacyServices = await findLegacyGatewayServices(process.env).catch(() => []);
     const extraServices = await findExtraGatewayServices(process.env, { deep: Boolean(opts.deep) }).catch(() => []);
     const timeoutMsRaw = Number.parseInt(String(opts.rpc.timeout ?? "10000"), 10);
     const timeoutMs = Number.isFinite(timeoutMsRaw) && timeoutMsRaw > 0 ? timeoutMsRaw : 10_000;
     const rpc = opts.probe
         ? await probeGatewayStatus({
             url: probeUrl,
-            token: opts.rpc.token ||
-                mergedDaemonEnv.POOLBOT_GATEWAY_TOKEN ||
-                mergedDaemonEnv.CLAWDBOT_GATEWAY_TOKEN ||
-                daemonCfg.gateway?.auth?.token,
+            token: opts.rpc.token || mergedDaemonEnv.POOLBOT_GATEWAY_TOKEN || daemonCfg.gateway?.auth?.token,
             password: opts.rpc.password ||
                 mergedDaemonEnv.POOLBOT_GATEWAY_PASSWORD ||
-                mergedDaemonEnv.CLAWDBOT_GATEWAY_PASSWORD ||
                 daemonCfg.gateway?.auth?.password,
             timeoutMs,
             json: opts.rpc.json,
@@ -150,13 +146,13 @@ export async function gatherDaemonStatus(opts) {
         ...(portCliStatus ? { portCli: portCliStatus } : {}),
         lastError,
         ...(rpc ? { rpc: { ...rpc, url: probeUrl } } : {}),
-        legacyServices,
         extraServices,
     };
 }
 export function renderPortDiagnosticsForCli(status, rpcOk) {
-    if (!status.port || !shouldReportPortUsage(status.port.status, rpcOk))
+    if (!status.port || !shouldReportPortUsage(status.port.status, rpcOk)) {
         return [];
+    }
     return formatPortDiagnostics({
         port: status.port.port,
         status: status.port.status,

package/dist/cli/daemon-cli/status.print.js

@@ -42,7 +42,7 @@ export function printDaemonStatus(status, opts) {
     const warnText = (value) => colorize(rich, theme.warn, value);
     const errorText = (value) => colorize(rich, theme.error, value);
     const spacer = () => defaultRuntime.log("");
-    const { service, rpc, legacyServices, extraServices } = status;
+    const { service, rpc, extraServices } = status;
     const serviceStatus = service.loaded
         ? okText(service.loadedText)
         : warnText(service.notLoadedText);
@@ -213,14 +213,6 @@ export function printDaemonStatus(status, opts) {
         }
         spacer();
     }
-    if (legacyServices.length > 0) {
-        defaultRuntime.error(errorText("Legacy gateway services detected:"));
-        for (const svc of legacyServices) {
-            defaultRuntime.error(`- ${errorText(svc.label)} (${svc.detail})`);
-        }
-        defaultRuntime.error(errorText(`Cleanup: ${formatCliCommand("poolbot doctor")}`));
-        spacer();
-    }
     if (extraServices.length > 0) {
         defaultRuntime.error(errorText("Other gateway-like services detected (best effort):"));
         for (const svc of extraServices) {
@@ -231,7 +223,7 @@ export function printDaemonStatus(status, opts) {
         }
         spacer();
     }
-    if (legacyServices.length > 0 || extraServices.length > 0) {
+    if (extraServices.length > 0) {
         defaultRuntime.error(errorText("Recommendation: run a single gateway per machine for most setups. One gateway supports multiple agents (see docs: /gateway#multiple-gateways-same-host)."));
         defaultRuntime.error(errorText("If you need multiple gateways (e.g., a rescue bot on the same host), isolate ports + config/state (see docs: /gateway#multiple-gateways-same-host)."));
         spacer();

package/dist/cli/deps.js

@@ -1,28 +1,33 @@
-import { logWebSelfId, sendMessageWhatsApp } from "../channels/web/index.js";
-import { sendMessageDiscord } from "../discord/send.js";
-import { sendMessageIMessage } from "../imessage/send.js";
-import { sendMessageSignal } from "../signal/send.js";
-import { sendMessageSlack } from "../slack/send.js";
-import { sendMessageTelegram } from "../telegram/send.js";
+import { createOutboundSendDepsFromCliSource } from "./outbound-send-mapping.js";
 export function createDefaultDeps() {
     return {
-        sendMessageWhatsApp,
-        sendMessageTelegram,
-        sendMessageDiscord,
-        sendMessageSlack,
-        sendMessageSignal,
-        sendMessageIMessage,
+        sendMessageWhatsApp: async (...args) => {
+            const { sendMessageWhatsApp } = await import("../channels/web/index.js");
+            return await sendMessageWhatsApp(...args);
+        },
+        sendMessageTelegram: async (...args) => {
+            const { sendMessageTelegram } = await import("../telegram/send.js");
+            return await sendMessageTelegram(...args);
+        },
+        sendMessageDiscord: async (...args) => {
+            const { sendMessageDiscord } = await import("../discord/send.js");
+            return await sendMessageDiscord(...args);
+        },
+        sendMessageSlack: async (...args) => {
+            const { sendMessageSlack } = await import("../slack/send.js");
+            return await sendMessageSlack(...args);
+        },
+        sendMessageSignal: async (...args) => {
+            const { sendMessageSignal } = await import("../signal/send.js");
+            return await sendMessageSignal(...args);
+        },
+        sendMessageIMessage: async (...args) => {
+            const { sendMessageIMessage } = await import("../imessage/send.js");
+            return await sendMessageIMessage(...args);
+        },
     };
 }
-// Provider docking: extend this mapping when adding new outbound send deps.
 export function createOutboundSendDeps(deps) {
-    return {
-        sendWhatsApp: deps.sendMessageWhatsApp,
-        sendTelegram: deps.sendMessageTelegram,
-        sendDiscord: deps.sendMessageDiscord,
-        sendSlack: deps.sendMessageSlack,
-        sendSignal: deps.sendMessageSignal,
-        sendIMessage: deps.sendMessageIMessage,
-    };
+    return createOutboundSendDepsFromCliSource(deps);
 }
-export { logWebSelfId };
+export { logWebSelfId } from "../web/auth-store.js";

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

@@ -1,5 +1,6 @@
 import { acquireGatewayLock } from "../../infra/gateway-lock.js";
-import { consumeGatewaySigusr1RestartAuthorization, isGatewaySigusr1RestartExternallyAllowed, } from "../../infra/restart.js";
+import { restartGatewayProcessWithFreshPid } from "../../infra/process-respawn.js";
+import { consumeGatewaySigusr1RestartAuthorization, isGatewaySigusr1RestartExternallyAllowed, markGatewaySigusr1RestartHandled, } from "../../infra/restart.js";
 import { createSubsystemLogger } from "../../logging/subsystem.js";
 import { getActiveTaskCount, resetAllLanes, waitForActiveTasks, } from "../../process/command-queue.js";
 import { createRestartIterationHook } from "../../process/restart-recovery.js";
@@ -60,9 +61,25 @@ export async function runGatewayLoop(params) {
                 clearTimeout(forceExitTimer);
                 server = null;
                 if (isRestart) {
-                    // In-process restart (no process-respawn in pool-bot).
-                    shuttingDown = false;
-                    restartResolver?.();
+                    const respawn = restartGatewayProcessWithFreshPid();
+                    if (respawn.mode === "spawned" || respawn.mode === "supervised") {
+                        const modeLabel = respawn.mode === "spawned"
+                            ? `spawned pid ${respawn.pid ?? "unknown"}`
+                            : "supervisor restart";
+                        gatewayLog.info(`restart mode: full process restart (${modeLabel})`);
+                        cleanupSignals();
+                        params.runtime.exit(0);
+                    }
+                    else {
+                        if (respawn.mode === "failed") {
+                            gatewayLog.warn(`full process restart failed (${respawn.detail ?? "unknown error"}); falling back to in-process restart`);
+                        }
+                        else {
+                            gatewayLog.info("restart mode: in-process restart (POOLBOT_NO_RESPAWN)");
+                        }
+                        shuttingDown = false;
+                        restartResolver?.();
+                    }
                 }
                 else {
                     cleanupSignals();
@@ -83,9 +100,10 @@ export async function runGatewayLoop(params) {
         gatewayLog.info("signal SIGUSR1 received");
         const authorized = consumeGatewaySigusr1RestartAuthorization();
         if (!authorized && !isGatewaySigusr1RestartExternallyAllowed()) {
-            gatewayLog.warn("SIGUSR1 restart ignored (not authorized; enable commands.restart or use gateway tool).");
+            gatewayLog.warn("SIGUSR1 restart ignored (not authorized; commands.restart=false or use gateway tool).");
             return;
         }
+        markGatewaySigusr1RestartHandled();
         request("restart", "SIGUSR1");
     };
     process.on("SIGTERM", onSigterm);

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

@@ -1,9 +1,10 @@
-import { formatDocsLink } from "../../terminal/links.js";
-import { theme } from "../../terminal/theme.js";
 import { loadNodeHostConfig } from "../../node-host/config.js";
 import { runNodeHost } from "../../node-host/runner.js";
-import { runNodeDaemonInstall, runNodeDaemonRestart, runNodeDaemonStatus, runNodeDaemonStop, runNodeDaemonUninstall, } from "./daemon.js";
+import { formatDocsLink } from "../../terminal/links.js";
+import { theme } from "../../terminal/theme.js";
 import { parsePort } from "../daemon-cli/shared.js";
+import { formatHelpExamples } from "../help-format.js";
+import { runNodeDaemonInstall, runNodeDaemonRestart, runNodeDaemonStatus, runNodeDaemonStop, runNodeDaemonUninstall, } from "./daemon.js";
 function parsePortWithFallback(value, fallback) {
     const parsed = parsePort(value);
     return parsed ?? fallback;
@@ -11,8 +12,16 @@ function parsePortWithFallback(value, fallback) {
 export function registerNodeCli(program) {
     const node = program
         .command("node")
-        .description("Run a headless node host (system.run/system.which)")
-        .addHelpText("after", () => `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/node", "docs.molt.bot/cli/node")}\n`);
+        .description("Run and manage the headless node host service")
+        .addHelpText("after", () => `\n${theme.heading("Examples:")}\n${formatHelpExamples([
+        [
+            "poolbot node run --host 127.0.0.1 --port 18789",
+            "Run the node host in the foreground.",
+        ],
+        ["poolbot node status", "Check node host service status."],
+        ["poolbot node install", "Install the node host service."],
+        ["poolbot node restart", "Restart the installed node host service."],
+    ])}\n\n${theme.muted("Docs:")} ${formatDocsLink("/cli/node", "docs.molt.bot/cli/node")}\n`);
     node
         .command("run")
         .description("Run the headless node host (foreground)")

package/dist/cli/nodes-media-utils.js

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
-import * as os from "node:os";
+import fs from "node:fs";
+import { resolvePreferredPoolbotTmpDir } from "../infra/tmp-poolbot-dir.js";
 export function asRecord(value) {
     return typeof value === "object" && value !== null ? value : {};
 }
@@ -13,8 +14,12 @@ export function asBoolean(value) {
     return typeof value === "boolean" ? value : undefined;
 }
 export function resolveTempPathParts(opts) {
+    const tmpDir = opts.tmpDir ?? resolvePreferredPoolbotTmpDir();
+    if (!opts.tmpDir) {
+        fs.mkdirSync(tmpDir, { recursive: true, mode: 0o700 });
+    }
     return {
-        tmpDir: opts.tmpDir ?? os.tmpdir(),
+        tmpDir,
         id: opts.id ?? randomUUID(),
         ext: opts.ext.startsWith(".") ? opts.ext : `.${opts.ext}`,
     };

package/dist/cli/outbound-send-deps.js

@@ -1,11 +1,4 @@
-// Provider docking: extend this mapping when adding new outbound send deps.
+import { createOutboundSendDepsFromCliSource, } from "./outbound-send-mapping.js";
 export function createOutboundSendDeps(deps) {
-    return {
-        sendWhatsApp: deps.sendMessageWhatsApp,
-        sendTelegram: deps.sendMessageTelegram,
-        sendDiscord: deps.sendMessageDiscord,
-        sendSlack: deps.sendMessageSlack,
-        sendSignal: deps.sendMessageSignal,
-        sendIMessage: deps.sendMessageIMessage,
-    };
+    return createOutboundSendDepsFromCliSource(deps);
 }

package/dist/cli/outbound-send-mapping.js

@@ -0,0 +1,11 @@
+// Provider docking: extend this mapping when adding new outbound send deps.
+export function createOutboundSendDepsFromCliSource(deps) {
+    return {
+        sendWhatsApp: deps.sendMessageWhatsApp,
+        sendTelegram: deps.sendMessageTelegram,
+        sendDiscord: deps.sendMessageDiscord,
+        sendSlack: deps.sendMessageSlack,
+        sendSignal: deps.sendMessageSignal,
+        sendIMessage: deps.sendMessageIMessage,
+    };
+}

package/dist/cli/pairing-cli.js

@@ -1,5 +1,5 @@
-import { listPairingChannels, notifyPairingApproved } from "../channels/plugins/pairing.js";
 import { normalizeChannelId } from "../channels/plugins/index.js";
+import { listPairingChannels, notifyPairingApproved } from "../channels/plugins/pairing.js";
 import { loadConfig } from "../config/config.js";
 import { resolvePairingIdLabel } from "../pairing/pairing-labels.js";
 import { approveChannelPairingCode, listChannelPairingRequests, } from "../pairing/pairing-store.js";
@@ -17,8 +17,9 @@ function parseChannel(raw, channels) {
             : "")
         .trim()
         .toLowerCase();
-    if (!value)
+    if (!value) {
         throw new Error("Channel required");
+    }
     const normalized = normalizeChannelId(value);
     if (normalized) {
         if (!channels.includes(normalized)) {
@@ -27,8 +28,9 @@ function parseChannel(raw, channels) {
         return normalized;
     }
     // Allow extension channels: validate format but don't require registry
-    if (/^[a-z][a-z0-9_-]{0,63}$/.test(value))
+    if (/^[a-z][a-z0-9_-]{0,63}$/.test(value)) {
         return value;
+    }
     throw new Error(`Invalid channel: ${value}`);
 }
 async function notifyApproved(channel, id) {
@@ -40,20 +42,24 @@ export function registerPairingCli(program) {
     const pairing = program
         .command("pairing")
         .description("Secure DM pairing (approve inbound requests)")
-        .addHelpText("after", () => `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/pairing", "docs.molt.bot/cli/pairing")}\n`);
+        .addHelpText("after", () => `\n${theme.muted("Docs:")} ${formatDocsLink("/cli/pairing", "docs.poolbot.ai/cli/pairing")}\n`);
     pairing
         .command("list")
         .description("List pending pairing requests")
         .option("--channel <channel>", `Channel (${channels.join(", ")})`)
+        .option("--account <accountId>", "Account id (for multi-account channels)")
         .argument("[channel]", `Channel (${channels.join(", ")})`)
         .option("--json", "Print JSON", false)
         .action(async (channelArg, opts) => {
-        const channelRaw = opts.channel ?? channelArg;
+        const channelRaw = opts.channel ?? channelArg ?? (channels.length === 1 ? channels[0] : "");
         if (!channelRaw) {
             throw new Error(`Channel required. Use --channel <channel> or pass it as the first argument (expected one of: ${channels.join(", ")})`);
         }
         const channel = parseChannel(channelRaw, channels);
-        const requests = await listChannelPairingRequests(channel);
+        const accountId = String(opts.account ?? "").trim();
+        const requests = accountId
+            ? await listChannelPairingRequests(channel, process.env, accountId)
+            : await listChannelPairingRequests(channel);
         if (opts.json) {
             defaultRuntime.log(JSON.stringify({ channel, requests }, null, 2));
             return;
@@ -85,29 +91,49 @@ export function registerPairingCli(program) {
         .command("approve")
         .description("Approve a pairing code and allow that sender")
         .option("--channel <channel>", `Channel (${channels.join(", ")})`)
+        .option("--account <accountId>", "Account id (for multi-account channels)")
         .argument("<codeOrChannel>", "Pairing code (or channel when using 2 args)")
         .argument("[code]", "Pairing code (when channel is passed as the 1st arg)")
         .option("--notify", "Notify the requester on the same channel", false)
         .action(async (codeOrChannel, code, opts) => {
-        const channelRaw = opts.channel ?? codeOrChannel;
-        const resolvedCode = opts.channel ? codeOrChannel : code;
-        if (!opts.channel && !code) {
+        const defaultChannel = channels.length === 1 ? channels[0] : "";
+        const usingExplicitChannel = Boolean(opts.channel);
+        const hasPositionalCode = code != null;
+        const channelRaw = usingExplicitChannel
+            ? opts.channel
+            : hasPositionalCode
+                ? codeOrChannel
+                : defaultChannel;
+        const resolvedCode = usingExplicitChannel
+            ? codeOrChannel
+            : hasPositionalCode
+                ? code
+                : codeOrChannel;
+        if (!channelRaw || !resolvedCode) {
             throw new Error(`Usage: ${formatCliCommand("poolbot pairing approve <channel> <code>")} (or: ${formatCliCommand("poolbot pairing approve --channel <channel> <code>")})`);
         }
         if (opts.channel && code != null) {
             throw new Error(`Too many arguments. Use: ${formatCliCommand("poolbot pairing approve --channel <channel> <code>")}`);
         }
         const channel = parseChannel(channelRaw, channels);
-        const approved = await approveChannelPairingCode({
-            channel,
-            code: String(resolvedCode),
-        });
+        const accountId = String(opts.account ?? "").trim();
+        const approved = accountId
+            ? await approveChannelPairingCode({
+                channel,
+                code: String(resolvedCode),
+                accountId,
+            })
+            : await approveChannelPairingCode({
+                channel,
+                code: String(resolvedCode),
+            });
         if (!approved) {
             throw new Error(`No pending pairing request found for code: ${String(resolvedCode)}`);
         }
         defaultRuntime.log(`${theme.success("Approved")} ${theme.muted(channel)} sender ${theme.command(approved.id)}.`);
-        if (!opts.notify)
+        if (!opts.notify) {
             return;
+        }
         await notifyApproved(channel, approved.id).catch((err) => {
             defaultRuntime.log(theme.warn(`Failed to notify requester: ${String(err)}`));
         });