@poolzin/pool-bot 2026.2.23 → 2026.2.25

package/dist/gateway/startup-auth.js

@@ -0,0 +1,126 @@
+import crypto from "node:crypto";
+import { writeConfigFile } from "../config/config.js";
+import { resolveGatewayAuth } from "./auth.js";
+export function mergeGatewayAuthConfig(base, override) {
+    const merged = { ...base };
+    if (!override) {
+        return merged;
+    }
+    if (override.mode !== undefined) {
+        merged.mode = override.mode;
+    }
+    if (override.token !== undefined) {
+        merged.token = override.token;
+    }
+    if (override.password !== undefined) {
+        merged.password = override.password;
+    }
+    if (override.allowTailscale !== undefined) {
+        merged.allowTailscale = override.allowTailscale;
+    }
+    if (override.rateLimit !== undefined) {
+        merged.rateLimit = override.rateLimit;
+    }
+    if (override.trustedProxy !== undefined) {
+        merged.trustedProxy = override.trustedProxy;
+    }
+    return merged;
+}
+export function mergeGatewayTailscaleConfig(base, override) {
+    const merged = { ...base };
+    if (!override) {
+        return merged;
+    }
+    if (override.mode !== undefined) {
+        merged.mode = override.mode;
+    }
+    if (override.resetOnExit !== undefined) {
+        merged.resetOnExit = override.resetOnExit;
+    }
+    return merged;
+}
+function resolveGatewayAuthFromConfig(params) {
+    const tailscaleConfig = mergeGatewayTailscaleConfig(params.cfg.gateway?.tailscale, params.tailscaleOverride);
+    return resolveGatewayAuth({
+        authConfig: params.cfg.gateway?.auth,
+        authOverride: params.authOverride,
+        env: params.env,
+        tailscaleMode: tailscaleConfig.mode ?? "off",
+    });
+}
+function shouldPersistGeneratedToken(params) {
+    if (!params.persistRequested) {
+        return false;
+    }
+    // Keep CLI/runtime mode overrides ephemeral: startup should not silently
+    // mutate durable auth policy when mode was chosen by an override flag.
+    if (params.resolvedAuth.modeSource === "override") {
+        return false;
+    }
+    return true;
+}
+export async function ensureGatewayStartupAuth(params) {
+    const env = params.env ?? process.env;
+    const persistRequested = params.persist === true;
+    const resolved = resolveGatewayAuthFromConfig({
+        cfg: params.cfg,
+        env,
+        authOverride: params.authOverride,
+        tailscaleOverride: params.tailscaleOverride,
+    });
+    if (resolved.mode !== "token" || (resolved.token?.trim().length ?? 0) > 0) {
+        assertHooksTokenSeparateFromGatewayAuth({ cfg: params.cfg, auth: resolved });
+        return { cfg: params.cfg, auth: resolved, persistedGeneratedToken: false };
+    }
+    const generatedToken = crypto.randomBytes(24).toString("hex");
+    const nextCfg = {
+        ...params.cfg,
+        gateway: {
+            ...params.cfg.gateway,
+            auth: {
+                ...params.cfg.gateway?.auth,
+                mode: "token",
+                token: generatedToken,
+            },
+        },
+    };
+    const persist = shouldPersistGeneratedToken({
+        persistRequested,
+        resolvedAuth: resolved,
+    });
+    if (persist) {
+        await writeConfigFile(nextCfg);
+    }
+    const nextAuth = resolveGatewayAuthFromConfig({
+        cfg: nextCfg,
+        env,
+        authOverride: params.authOverride,
+        tailscaleOverride: params.tailscaleOverride,
+    });
+    assertHooksTokenSeparateFromGatewayAuth({ cfg: nextCfg, auth: nextAuth });
+    return {
+        cfg: nextCfg,
+        auth: nextAuth,
+        generatedToken,
+        persistedGeneratedToken: persist,
+    };
+}
+export function assertHooksTokenSeparateFromGatewayAuth(params) {
+    if (params.cfg.hooks?.enabled !== true) {
+        return;
+    }
+    const hooksToken = typeof params.cfg.hooks.token === "string" ? params.cfg.hooks.token.trim() : "";
+    if (!hooksToken) {
+        return;
+    }
+    const gatewayToken = params.auth.mode === "token" && typeof params.auth.token === "string"
+        ? params.auth.token.trim()
+        : "";
+    if (!gatewayToken) {
+        return;
+    }
+    if (hooksToken !== gatewayToken) {
+        return;
+    }
+    throw new Error("Invalid config: hooks.token must not match gateway auth token. Set a distinct hooks.token for hook ingress.");
+}

package/dist/gateway/test-helpers.agent-results.js

@@ -0,0 +1,15 @@
+export function extractPayloadText(result) {
+    const record = result;
+    const payloads = Array.isArray(record.payloads) ? record.payloads : [];
+    const texts = payloads
+        .map((p) => (p && typeof p === "object" ? p.text : undefined))
+        .filter((t) => typeof t === "string" && t.trim().length > 0);
+    return texts.join("\n").trim();
+}
+export function buildAssistantDeltaResult(params) {
+    const runId = params.opts?.runId ?? "";
+    for (const delta of params.deltas) {
+        params.emit({ runId, stream: "assistant", data: { delta } });
+    }
+    return { payloads: [{ text: params.text }] };
+}

package/dist/gateway/test-helpers.mocks.js

@@ -1,6 +1,6 @@
 import crypto from "node:crypto";
-import fs from "node:fs/promises";
 import fsSync from "node:fs";
+import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { vi } from "vitest";
@@ -147,6 +147,7 @@ const hoisted = vi.hoisted(() => ({
         waitCalls: [],
         waitResults: new Map(),
     },
+    testTailscaleWhois: { value: null },
     getReplyFromConfig: vi.fn().mockResolvedValue(undefined),
     sendWhatsAppMock: vi.fn().mockResolvedValue({ messageId: "msg-1", toJid: "jid-1" }),
 }));
@@ -168,9 +169,9 @@ const testConfigRoot = {
 export const setTestConfigRoot = (root) => {
     testConfigRoot.value = root;
     process.env.POOLBOT_CONFIG_PATH = path.join(root, "poolbot.json");
-    process.env.CLAWDBOT_CONFIG_PATH = path.join(root, "poolbot.json");
 };
 export const testTailnetIPv4 = hoisted.testTailnetIPv4;
+export const testTailscaleWhois = hoisted.testTailscaleWhois;
 export const piSdkMock = hoisted.piSdkMock;
 export const cronIsolatedRun = hoisted.cronIsolatedRun;
 export const agentCommand = hoisted.agentCommand;
@@ -222,6 +223,13 @@ vi.mock("../infra/tailnet.js", () => ({
     pickPrimaryTailnetIPv4: () => testTailnetIPv4.value,
     pickPrimaryTailnetIPv6: () => undefined,
 }));
+vi.mock("../infra/tailscale.js", async () => {
+    const actual = await vi.importActual("../infra/tailscale.js");
+    return {
+        ...actual,
+        readTailscaleWhoisIdentity: async () => testTailscaleWhois.value,
+    };
+});
 vi.mock("../config/sessions.js", async () => {
     const actual = await vi.importActual("../config/sessions.js");
     return {
@@ -350,8 +358,8 @@ vi.mock("../config/config.js", async () => {
                 ? fileAgents.defaults
                 : {};
             const defaults = {
-                model: { primary: "anthropic/claude-opus-4-5" },
-                workspace: path.join(os.tmpdir(), "clawd-gateway-test"),
+                model: { primary: "anthropic/claude-opus-4-6" },
+                workspace: path.join(os.tmpdir(), "poolbot-gateway-test"),
                 ...fileDefaults,
                 ...testState.agentConfig,
             };
@@ -391,38 +399,46 @@ vi.mock("../config/config.js", async () => {
                 ...fileSession,
                 mainKey: fileSession.mainKey ?? "main",
             };
-            if (typeof testState.sessionStorePath === "string")
+            if (typeof testState.sessionStorePath === "string") {
                 session.store = testState.sessionStorePath;
-            if (testState.sessionConfig)
+            }
+            if (testState.sessionConfig) {
                 Object.assign(session, testState.sessionConfig);
+            }
             const fileGateway = fileConfig.gateway &&
                 typeof fileConfig.gateway === "object" &&
                 !Array.isArray(fileConfig.gateway)
                 ? { ...fileConfig.gateway }
                 : {};
-            if (testState.gatewayBind)
+            if (testState.gatewayBind) {
                 fileGateway.bind = testState.gatewayBind;
-            if (testState.gatewayAuth)
+            }
+            if (testState.gatewayAuth) {
                 fileGateway.auth = testState.gatewayAuth;
-            if (testState.gatewayControlUi)
+            }
+            if (testState.gatewayControlUi) {
                 fileGateway.controlUi = testState.gatewayControlUi;
+            }
             const gateway = Object.keys(fileGateway).length > 0 ? fileGateway : undefined;
             const fileCanvasHost = fileConfig.canvasHost &&
                 typeof fileConfig.canvasHost === "object" &&
                 !Array.isArray(fileConfig.canvasHost)
                 ? { ...fileConfig.canvasHost }
                 : {};
-            if (typeof testState.canvasHostPort === "number")
+            if (typeof testState.canvasHostPort === "number") {
                 fileCanvasHost.port = testState.canvasHostPort;
+            }
             const canvasHost = Object.keys(fileCanvasHost).length > 0 ? fileCanvasHost : undefined;
             const hooks = testState.hooksConfig ?? fileConfig.hooks;
             const fileCron = fileConfig.cron && typeof fileConfig.cron === "object" && !Array.isArray(fileConfig.cron)
                 ? { ...fileConfig.cron }
                 : {};
-            if (typeof testState.cronEnabled === "boolean")
+            if (typeof testState.cronEnabled === "boolean") {
                 fileCron.enabled = testState.cronEnabled;
-            if (typeof testState.cronStorePath === "string")
+            }
+            if (typeof testState.cronStorePath === "string") {
                 fileCron.store = testState.cronStorePath;
+            }
             const cron = Object.keys(fileCron).length > 0 ? fileCron : undefined;
             const config = {
                 ...fileConfig,
@@ -503,7 +519,14 @@ vi.mock("../cli/deps.js", async () => {
         }),
     };
 });
+vi.mock("../plugins/loader.js", async () => {
+    const actual = await vi.importActual("../plugins/loader.js");
+    return {
+        ...actual,
+        loadPoolBotPlugins: () => pluginRegistryState.registry,
+    };
+});
+process.env.POOLBOT_SKIP_CHANNELS = "1";
+process.env.POOLBOT_SKIP_CRON = "1";
 process.env.POOLBOT_SKIP_CHANNELS = "1";
-process.env.CLAWDBOT_SKIP_CHANNELS = "1";
 process.env.POOLBOT_SKIP_CRON = "1";
-process.env.CLAWDBOT_SKIP_CRON = "1";

package/dist/gateway/test-helpers.server.js

@@ -11,15 +11,19 @@ import { drainSystemEvents, peekSystemEvents } from "../infra/system-events.js";
 import { rawDataToString } from "../infra/ws.js";
 import { resetLogger, setLoggerOverride } from "../logging.js";
 import { DEFAULT_AGENT_ID, toAgentStoreSessionKey } from "../routing/session-key.js";
-import { getDeterministicFreePortBlock } from "../test-utils/ports.js";
 import { captureEnv } from "../test-utils/env.js";
+import { getDeterministicFreePortBlock } from "../test-utils/ports.js";
 import { GATEWAY_CLIENT_MODES, GATEWAY_CLIENT_NAMES } from "../utils/message-channel.js";
-import { PROTOCOL_VERSION } from "./protocol/index.js";
 import { buildDeviceAuthPayload } from "./device-auth.js";
-import { agentCommand, cronIsolatedRun, embeddedRunMock, piSdkMock, sessionStoreSaveDelayMs, setTestConfigRoot, testIsNixMode, testState, testTailnetIPv4, } from "./test-helpers.mocks.js";
-// Preload the gateway server module once per worker.
-// Important: `test-helpers.mocks` must run before importing the server so vi.mock hooks apply.
-const serverModulePromise = import("./server.js");
+import { PROTOCOL_VERSION } from "./protocol/index.js";
+import { agentCommand, cronIsolatedRun, embeddedRunMock, piSdkMock, sessionStoreSaveDelayMs, setTestConfigRoot, testIsNixMode, testTailscaleWhois, testState, testTailnetIPv4, } from "./test-helpers.mocks.js";
+// Import lazily after test env/home setup so config/session paths resolve to test dirs.
+// Keep one cached module per worker for speed.
+let serverModulePromise;
+async function getServerModule() {
+    serverModulePromise ??= import("./server.js");
+    return await serverModulePromise;
+}
 let previousHome;
 let previousUserProfile;
 let previousStateDir;
@@ -28,12 +32,17 @@ let previousSkipBrowserControl;
 let previousSkipGmailWatcher;
 let previousSkipCanvasHost;
 let previousBundledPluginsDir;
+let previousSkipChannels;
+let previousSkipProviders;
+let previousSkipCron;
+let previousMinimalGateway;
 let tempHome;
 let tempConfigRoot;
 export async function writeSessionStore(params) {
     const storePath = params.storePath ?? testState.sessionStorePath;
-    if (!storePath)
+    if (!storePath) {
         throw new Error("writeSessionStore requires testState.sessionStorePath");
+    }
     const agentId = params.agentId ?? DEFAULT_AGENT_ID;
     const store = {};
     for (const [requestKey, entry] of Object.entries(params.entries)) {
@@ -53,37 +62,33 @@ export async function writeSessionStore(params) {
 async function setupGatewayTestHome() {
     previousHome = process.env.HOME;
     previousUserProfile = process.env.USERPROFILE;
-    previousStateDir = process.env.POOLBOT_STATE_DIR ?? process.env.CLAWDBOT_STATE_DIR;
-    previousConfigPath = process.env.POOLBOT_CONFIG_PATH ?? process.env.CLAWDBOT_CONFIG_PATH;
-    previousSkipBrowserControl =
-        process.env.POOLBOT_SKIP_BROWSER_CONTROL_SERVER ??
-            process.env.CLAWDBOT_SKIP_BROWSER_CONTROL_SERVER;
-    previousSkipGmailWatcher =
-        process.env.POOLBOT_SKIP_GMAIL_WATCHER ?? process.env.CLAWDBOT_SKIP_GMAIL_WATCHER;
-    previousSkipCanvasHost =
-        process.env.POOLBOT_SKIP_CANVAS_HOST ?? process.env.CLAWDBOT_SKIP_CANVAS_HOST;
-    previousBundledPluginsDir =
-        process.env.POOLBOT_BUNDLED_PLUGINS_DIR ?? process.env.CLAWDBOT_BUNDLED_PLUGINS_DIR;
+    previousStateDir = process.env.POOLBOT_STATE_DIR;
+    previousConfigPath = process.env.POOLBOT_CONFIG_PATH;
+    previousSkipBrowserControl = process.env.POOLBOT_SKIP_BROWSER_CONTROL_SERVER;
+    previousSkipGmailWatcher = process.env.POOLBOT_SKIP_GMAIL_WATCHER;
+    previousSkipCanvasHost = process.env.POOLBOT_SKIP_CANVAS_HOST;
+    previousBundledPluginsDir = process.env.POOLBOT_BUNDLED_PLUGINS_DIR;
+    previousSkipChannels = process.env.POOLBOT_SKIP_CHANNELS;
+    previousSkipProviders = process.env.POOLBOT_SKIP_PROVIDERS;
+    previousSkipCron = process.env.POOLBOT_SKIP_CRON;
+    previousMinimalGateway = process.env.POOLBOT_TEST_MINIMAL_GATEWAY;
     tempHome = await fs.mkdtemp(path.join(os.tmpdir(), "poolbot-gateway-home-"));
     process.env.HOME = tempHome;
     process.env.USERPROFILE = tempHome;
     process.env.POOLBOT_STATE_DIR = path.join(tempHome, ".poolbot");
-    process.env.CLAWDBOT_STATE_DIR = path.join(tempHome, ".poolbot");
     delete process.env.POOLBOT_CONFIG_PATH;
-    delete process.env.CLAWDBOT_CONFIG_PATH;
 }
 function applyGatewaySkipEnv() {
     process.env.POOLBOT_SKIP_BROWSER_CONTROL_SERVER = "1";
-    process.env.CLAWDBOT_SKIP_BROWSER_CONTROL_SERVER = "1";
     process.env.POOLBOT_SKIP_GMAIL_WATCHER = "1";
-    process.env.CLAWDBOT_SKIP_GMAIL_WATCHER = "1";
     process.env.POOLBOT_SKIP_CANVAS_HOST = "1";
-    process.env.CLAWDBOT_SKIP_CANVAS_HOST = "1";
-    const bundledDir = tempHome
+    process.env.POOLBOT_SKIP_CHANNELS = "1";
+    process.env.POOLBOT_SKIP_PROVIDERS = "1";
+    process.env.POOLBOT_SKIP_CRON = "1";
+    process.env.POOLBOT_TEST_MINIMAL_GATEWAY = "1";
+    process.env.POOLBOT_BUNDLED_PLUGINS_DIR = tempHome
         ? path.join(tempHome, "poolbot-test-no-bundled-extensions")
         : "poolbot-test-no-bundled-extensions";
-    process.env.POOLBOT_BUNDLED_PLUGINS_DIR = bundledDir;
-    process.env.CLAWDBOT_BUNDLED_PLUGINS_DIR = bundledDir;
 }
 async function resetGatewayTestState(options) {
     // Some tests intentionally use fake timers; ensure they don't leak into gateway suites.
@@ -93,12 +98,18 @@ async function resetGatewayTestState(options) {
         throw new Error("resetGatewayTestState called before temp home was initialized");
     }
     applyGatewaySkipEnv();
-    tempConfigRoot = options.uniqueConfigRoot
-        ? await fs.mkdtemp(path.join(tempHome, "poolbot-test-"))
-        : path.join(tempHome, ".poolbot-test");
+    if (options.uniqueConfigRoot) {
+        tempConfigRoot = await fs.mkdtemp(path.join(tempHome, "poolbot-test-"));
+    }
+    else {
+        tempConfigRoot = path.join(tempHome, ".poolbot-test");
+        await fs.rm(tempConfigRoot, { recursive: true, force: true });
+        await fs.mkdir(tempConfigRoot, { recursive: true });
+    }
     setTestConfigRoot(tempConfigRoot);
     sessionStoreSaveDelayMs.value = 0;
     testTailnetIPv4.value = undefined;
+    testTailscaleWhois.value = null;
     testState.gatewayBind = undefined;
     testState.gatewayAuth = { mode: "token", token: "test-gateway-token-1234567890" };
     testState.gatewayControlUi = undefined;
@@ -126,7 +137,7 @@ async function resetGatewayTestState(options) {
     embeddedRunMock.waitResults.clear();
     drainSystemEvents(resolveMainSessionKeyFromConfig());
     resetAgentRunContextForTest();
-    const mod = await serverModulePromise;
+    const mod = await getServerModule();
     mod.__resetModelCatalogCacheForTest();
     piSdkMock.enabled = false;
     piSdkMock.discoverCalls = 0;
@@ -136,61 +147,77 @@ async function cleanupGatewayTestHome(options) {
     vi.useRealTimers();
     resetLogger();
     if (options.restoreEnv) {
-        if (previousHome === undefined)
+        if (previousHome === undefined) {
             delete process.env.HOME;
-        else
+        }
+        else {
             process.env.HOME = previousHome;
-        if (previousUserProfile === undefined)
+        }
+        if (previousUserProfile === undefined) {
             delete process.env.USERPROFILE;
-        else
+        }
+        else {
             process.env.USERPROFILE = previousUserProfile;
+        }
         if (previousStateDir === undefined) {
             delete process.env.POOLBOT_STATE_DIR;
-            delete process.env.CLAWDBOT_STATE_DIR;
         }
         else {
             process.env.POOLBOT_STATE_DIR = previousStateDir;
-            process.env.CLAWDBOT_STATE_DIR = previousStateDir;
         }
         if (previousConfigPath === undefined) {
             delete process.env.POOLBOT_CONFIG_PATH;
-            delete process.env.CLAWDBOT_CONFIG_PATH;
         }
         else {
             process.env.POOLBOT_CONFIG_PATH = previousConfigPath;
-            process.env.CLAWDBOT_CONFIG_PATH = previousConfigPath;
         }
         if (previousSkipBrowserControl === undefined) {
             delete process.env.POOLBOT_SKIP_BROWSER_CONTROL_SERVER;
-            delete process.env.CLAWDBOT_SKIP_BROWSER_CONTROL_SERVER;
         }
         else {
             process.env.POOLBOT_SKIP_BROWSER_CONTROL_SERVER = previousSkipBrowserControl;
-            process.env.CLAWDBOT_SKIP_BROWSER_CONTROL_SERVER = previousSkipBrowserControl;
         }
         if (previousSkipGmailWatcher === undefined) {
             delete process.env.POOLBOT_SKIP_GMAIL_WATCHER;
-            delete process.env.CLAWDBOT_SKIP_GMAIL_WATCHER;
         }
         else {
             process.env.POOLBOT_SKIP_GMAIL_WATCHER = previousSkipGmailWatcher;
-            process.env.CLAWDBOT_SKIP_GMAIL_WATCHER = previousSkipGmailWatcher;
         }
         if (previousSkipCanvasHost === undefined) {
             delete process.env.POOLBOT_SKIP_CANVAS_HOST;
-            delete process.env.CLAWDBOT_SKIP_CANVAS_HOST;
         }
         else {
             process.env.POOLBOT_SKIP_CANVAS_HOST = previousSkipCanvasHost;
-            process.env.CLAWDBOT_SKIP_CANVAS_HOST = previousSkipCanvasHost;
         }
         if (previousBundledPluginsDir === undefined) {
             delete process.env.POOLBOT_BUNDLED_PLUGINS_DIR;
-            delete process.env.CLAWDBOT_BUNDLED_PLUGINS_DIR;
         }
         else {
             process.env.POOLBOT_BUNDLED_PLUGINS_DIR = previousBundledPluginsDir;
-            process.env.CLAWDBOT_BUNDLED_PLUGINS_DIR = previousBundledPluginsDir;
+        }
+        if (previousSkipChannels === undefined) {
+            delete process.env.POOLBOT_SKIP_CHANNELS;
+        }
+        else {
+            process.env.POOLBOT_SKIP_CHANNELS = previousSkipChannels;
+        }
+        if (previousSkipProviders === undefined) {
+            delete process.env.POOLBOT_SKIP_PROVIDERS;
+        }
+        else {
+            process.env.POOLBOT_SKIP_PROVIDERS = previousSkipProviders;
+        }
+        if (previousSkipCron === undefined) {
+            delete process.env.POOLBOT_SKIP_CRON;
+        }
+        else {
+            process.env.POOLBOT_SKIP_CRON = previousSkipCron;
+        }
+        if (previousMinimalGateway === undefined) {
+            delete process.env.POOLBOT_TEST_MINIMAL_GATEWAY;
+        }
+        else {
+            process.env.POOLBOT_TEST_MINIMAL_GATEWAY = previousMinimalGateway;
         }
     }
     if (options.restoreEnv && tempHome) {
@@ -269,14 +296,46 @@ timeoutMs = 10_000) {
     });
 }
 export async function startGatewayServer(port, opts) {
-    const mod = await serverModulePromise;
+    const mod = await getServerModule();
     const resolvedOpts = opts?.controlUiEnabled === undefined ? { ...opts, controlUiEnabled: false } : opts;
     return await mod.startGatewayServer(port, resolvedOpts);
 }
+async function startGatewayServerWithRetries(params) {
+    let port = params.port;
+    for (let attempt = 0; attempt < 10; attempt++) {
+        try {
+            return {
+                port,
+                server: await startGatewayServer(port, params.opts),
+            };
+        }
+        catch (err) {
+            const code = err.cause?.code;
+            if (code !== "EADDRINUSE") {
+                throw err;
+            }
+            port = await getFreePort();
+        }
+    }
+    throw new Error("failed to start gateway server after retries");
+}
+export async function withGatewayServer(fn, opts) {
+    const started = await startGatewayServerWithRetries({
+        port: opts?.port ?? (await getFreePort()),
+        opts: opts?.serverOptions,
+    });
+    try {
+        return await fn({ port: started.port, server: started.server });
+    }
+    finally {
+        await started.server.close();
+    }
+}
 export async function startServerWithClient(token, opts) {
+    const { wsHeaders, ...gatewayOpts } = opts ?? {};
     let port = await getFreePort();
-    const envSnapshot = captureEnv(["POOLBOT_GATEWAY_TOKEN", "CLAWDBOT_GATEWAY_TOKEN"]);
-    const prev = process.env.POOLBOT_GATEWAY_TOKEN ?? process.env.CLAWDBOT_GATEWAY_TOKEN;
+    const envSnapshot = captureEnv(["POOLBOT_GATEWAY_TOKEN"]);
+    const prev = process.env.POOLBOT_GATEWAY_TOKEN;
     if (typeof token === "string") {
         testState.gatewayAuth = { mode: "token", token };
     }
@@ -286,29 +345,14 @@ export async function startServerWithClient(token, opts) {
             : undefined);
     if (fallbackToken === undefined) {
         delete process.env.POOLBOT_GATEWAY_TOKEN;
-        delete process.env.CLAWDBOT_GATEWAY_TOKEN;
     }
     else {
         process.env.POOLBOT_GATEWAY_TOKEN = fallbackToken;
-        process.env.CLAWDBOT_GATEWAY_TOKEN = fallbackToken;
     }
-    let server = null;
-    for (let attempt = 0; attempt < 10; attempt++) {
-        try {
-            server = await startGatewayServer(port, opts);
-            break;
-        }
-        catch (err) {
-            const code = err.cause?.code;
-            if (code !== "EADDRINUSE")
-                throw err;
-            port = await getFreePort();
-        }
-    }
-    if (!server) {
-        throw new Error("failed to start gateway server after retries");
-    }
-    const ws = new WebSocket(`ws://127.0.0.1:${port}`);
+    const started = await startGatewayServerWithRetries({ port, opts: gatewayOpts });
+    port = started.port;
+    const server = started.server;
+    const ws = new WebSocket(`ws://127.0.0.1:${port}`, wsHeaders ? { headers: wsHeaders } : undefined);
     await new Promise((resolve, reject) => {
         const timer = setTimeout(() => reject(new Error("timeout waiting for ws open")), 10_000);
         const cleanup = () => {
@@ -349,20 +393,26 @@ export async function connectReq(ws, opts) {
         ? undefined
         : typeof testState.gatewayAuth?.token === "string"
             ? (testState.gatewayAuth.token ?? undefined)
-            : (process.env.POOLBOT_GATEWAY_TOKEN ?? process.env.CLAWDBOT_GATEWAY_TOKEN);
+            : process.env.POOLBOT_GATEWAY_TOKEN;
     const defaultPassword = opts?.skipDefaultAuth === true
         ? undefined
         : typeof testState.gatewayAuth?.password === "string"
             ? (testState.gatewayAuth.password ?? undefined)
-            : (process.env.POOLBOT_GATEWAY_PASSWORD ?? process.env.CLAWDBOT_GATEWAY_PASSWORD);
+            : process.env.POOLBOT_GATEWAY_PASSWORD;
     const token = opts?.token ?? defaultToken;
     const password = opts?.password ?? defaultPassword;
-    const requestedScopes = Array.isArray(opts?.scopes) ? opts?.scopes : [];
+    const requestedScopes = Array.isArray(opts?.scopes)
+        ? opts.scopes
+        : role === "operator"
+            ? ["operator.admin"]
+            : [];
     const device = (() => {
-        if (opts?.device === null)
+        if (opts?.device === null) {
             return undefined;
-        if (opts?.device)
+        }
+        if (opts?.device) {
             return opts.device;
+        }
         const identity = loadOrCreateDeviceIdentity();
         const signedAtMs = Date.now();
         const payload = buildDeviceAuthPayload({
@@ -394,7 +444,7 @@ export async function connectReq(ws, opts) {
             commands: opts?.commands ?? [],
             permissions: opts?.permissions ?? undefined,
             role,
-            scopes: opts?.scopes,
+            scopes: requestedScopes,
             auth: token || password
                 ? {
                     token,
@@ -405,8 +455,9 @@ export async function connectReq(ws, opts) {
         },
     }));
     const isResponseForId = (o) => {
-        if (!o || typeof o !== "object" || Array.isArray(o))
+        if (!o || typeof o !== "object" || Array.isArray(o)) {
             return false;
+        }
         const rec = o;
         return rec.type === "res" && rec.id === id;
     };
@@ -418,13 +469,45 @@ export async function connectOk(ws, opts) {
     expect(res.payload?.type).toBe("hello-ok");
     return res.payload;
 }
+export async function connectWebchatClient(params) {
+    const origin = params.origin ?? `http://127.0.0.1:${params.port}`;
+    const ws = new WebSocket(`ws://127.0.0.1:${params.port}`, {
+        headers: { origin },
+    });
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error("timeout waiting for ws open")), 10_000);
+        const onOpen = () => {
+            clearTimeout(timer);
+            ws.off("error", onError);
+            resolve();
+        };
+        const onError = (err) => {
+            clearTimeout(timer);
+            ws.off("open", onOpen);
+            reject(err);
+        };
+        ws.once("open", onOpen);
+        ws.once("error", onError);
+    });
+    await connectOk(ws, {
+        client: params.client ??
+            {
+                id: GATEWAY_CLIENT_NAMES.WEBCHAT,
+                version: "1.0.0",
+                platform: "test",
+                mode: GATEWAY_CLIENT_MODES.WEBCHAT,
+            },
+    });
+    return ws;
+}
 export async function rpcReq(ws, method, params, timeoutMs) {
     const { randomUUID } = await import("node:crypto");
     const id = randomUUID();
     ws.send(JSON.stringify({ type: "req", id, method, params }));
     return await onceMessage(ws, (o) => {
-        if (!o || typeof o !== "object" || Array.isArray(o))
+        if (!o || typeof o !== "object" || Array.isArray(o)) {
             return false;
+        }
         const rec = o;
         return rec.type === "res" && rec.id === id;
     }, timeoutMs);
@@ -434,8 +517,9 @@ export async function waitForSystemEvent(timeoutMs = 2000) {
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
         const events = peekSystemEvents(sessionKey);
-        if (events.length > 0)
+        if (events.length > 0) {
             return events;
+        }
         await new Promise((resolve) => setTimeout(resolve, 10));
     }
     throw new Error("timeout waiting for system event");