@poolzin/pool-bot 2026.2.0 → 2026.2.2

package/dist/browser/client-fetch.js

@@ -23,7 +23,18 @@ function enhanceBrowserFetchError(url, err, timeoutMs) {
 async function fetchHttpJson(url, init) {
     const timeoutMs = init.timeoutMs ?? 5000;
     const ctrl = new AbortController();
-    const t = setTimeout(() => ctrl.abort(), timeoutMs);
+    const upstreamSignal = init.signal;
+    let upstreamAbortListener;
+    if (upstreamSignal) {
+        if (upstreamSignal.aborted) {
+            ctrl.abort(upstreamSignal.reason);
+        }
+        else {
+            upstreamAbortListener = () => ctrl.abort(upstreamSignal.reason);
+            upstreamSignal.addEventListener("abort", upstreamAbortListener, { once: true });
+        }
+    }
+    const t = setTimeout(() => ctrl.abort(new Error("timed out")), timeoutMs);
     try {
         const res = await fetch(url, { ...init, signal: ctrl.signal });
         if (!res.ok) {
@@ -34,6 +45,9 @@ async function fetchHttpJson(url, init) {
     }
     finally {
         clearTimeout(t);
+        if (upstreamSignal && upstreamAbortListener) {
+            upstreamSignal.removeEventListener("abort", upstreamAbortListener);
+        }
     }
 }
 export async function fetchBrowserJson(url, init) {
@@ -61,6 +75,29 @@ export async function fetchBrowserJson(url, init) {
                 // keep as string
             }
         }
+        const abortCtrl = new AbortController();
+        const upstreamSignal = init?.signal;
+        let upstreamAbortListener;
+        if (upstreamSignal) {
+            if (upstreamSignal.aborted) {
+                abortCtrl.abort(upstreamSignal.reason);
+            }
+            else {
+                upstreamAbortListener = () => abortCtrl.abort(upstreamSignal.reason);
+                upstreamSignal.addEventListener("abort", upstreamAbortListener, { once: true });
+            }
+        }
+        let abortListener;
+        const abortPromise = abortCtrl.signal.aborted
+            ? Promise.reject(abortCtrl.signal.reason ?? new Error("aborted"))
+            : new Promise((_, reject) => {
+                abortListener = () => reject(abortCtrl.signal.reason ?? new Error("aborted"));
+                abortCtrl.signal.addEventListener("abort", abortListener, { once: true });
+            });
+        let timer;
+        if (timeoutMs) {
+            timer = setTimeout(() => abortCtrl.abort(new Error("timed out")), timeoutMs);
+        }
         const dispatchPromise = dispatcher.dispatch({
             method: init?.method?.toUpperCase() === "DELETE"
                 ? "DELETE"
@@ -70,13 +107,19 @@ export async function fetchBrowserJson(url, init) {
             path: parsed.pathname,
             query,
             body,
+            signal: abortCtrl.signal,
+        });
+        const result = await Promise.race([dispatchPromise, abortPromise]).finally(() => {
+            if (timer) {
+                clearTimeout(timer);
+            }
+            if (abortListener) {
+                abortCtrl.signal.removeEventListener("abort", abortListener);
+            }
+            if (upstreamSignal && upstreamAbortListener) {
+                upstreamSignal.removeEventListener("abort", upstreamAbortListener);
+            }
         });
-        const result = await (timeoutMs
-            ? Promise.race([
-                dispatchPromise,
-                new Promise((_, reject) => setTimeout(() => reject(new Error("timed out")), timeoutMs)),
-            ])
-            : dispatchPromise);
         if (result.status >= 400) {
             const message = result.body && typeof result.body === "object" && "error" in result.body
                 ? String(result.body.error)

package/dist/browser/config.js

@@ -1,17 +1,8 @@
 import { deriveDefaultBrowserCdpPortRange, deriveDefaultBrowserControlPort, DEFAULT_BROWSER_CONTROL_PORT, } from "../config/port-defaults.js";
 import { resolveGatewayPort } from "../config/paths.js";
+import { isLoopbackHost } from "../gateway/net.js";
 import { DEFAULT_CLAWD_BROWSER_COLOR, DEFAULT_CLAWD_BROWSER_ENABLED, DEFAULT_BROWSER_EVALUATE_ENABLED, DEFAULT_BROWSER_DEFAULT_PROFILE_NAME, DEFAULT_CLAWD_BROWSER_PROFILE_NAME, } from "./constants.js";
 import { CDP_PORT_RANGE_START, getUsedPorts } from "./profiles.js";
-function isLoopbackHost(host) {
-    const h = host.trim().toLowerCase();
-    return (h === "localhost" ||
-        h === "127.0.0.1" ||
-        h === "0.0.0.0" ||
-        h === "[::1]" ||
-        h === "::1" ||
-        h === "[::]" ||
-        h === "::");
-}
 function normalizeHexColor(raw) {
     const value = (raw ?? "").trim();
     if (!value)

package/dist/browser/extension-relay.js

@@ -1,28 +1,20 @@
+import { randomBytes } from "node:crypto";
 import { createServer } from "node:http";
 import WebSocket, { WebSocketServer } from "ws";
+import { isLoopbackAddress, isLoopbackHost } from "../gateway/net.js";
 import { rawDataToString } from "../infra/ws.js";
-function isLoopbackHost(host) {
-    const h = host.trim().toLowerCase();
-    return (h === "localhost" ||
-        h === "127.0.0.1" ||
-        h === "0.0.0.0" ||
-        h === "[::1]" ||
-        h === "::1" ||
-        h === "[::]" ||
-        h === "::");
+const RELAY_AUTH_HEADER = "x-poolbot-relay-token";
+function headerValue(value) {
+    if (!value) {
+        return undefined;
+    }
+    if (Array.isArray(value)) {
+        return value[0];
+    }
+    return value;
 }
-function isLoopbackAddress(ip) {
-    if (!ip)
-        return false;
-    if (ip === "127.0.0.1")
-        return true;
-    if (ip.startsWith("127."))
-        return true;
-    if (ip === "::1")
-        return true;
-    if (ip.startsWith("::ffff:127."))
-        return true;
-    return false;
+function getHeader(req, name) {
+    return headerValue(req.headers[name.toLowerCase()]);
 }
 function parseBaseUrl(raw) {
     const parsed = new URL(raw.trim().replace(/\/$/, ""));
@@ -56,14 +48,43 @@ function rejectUpgrade(socket, status, bodyText) {
     }
 }
 const serversByPort = new Map();
+const relayAuthByPort = new Map();
+function relayAuthTokenForUrl(url) {
+    try {
+        const parsed = new URL(url);
+        if (!isLoopbackHost(parsed.hostname)) {
+            return null;
+        }
+        const port = parsed.port?.trim() !== ""
+            ? Number(parsed.port)
+            : parsed.protocol === "https:" || parsed.protocol === "wss:"
+                ? 443
+                : 80;
+        if (!Number.isFinite(port)) {
+            return null;
+        }
+        return relayAuthByPort.get(port) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export function getChromeExtensionRelayAuthHeaders(url) {
+    const token = relayAuthTokenForUrl(url);
+    if (!token) {
+        return {};
+    }
+    return { [RELAY_AUTH_HEADER]: token };
+}
 export async function ensureChromeExtensionRelayServer(opts) {
     const info = parseBaseUrl(opts.cdpUrl);
     if (!isLoopbackHost(info.host)) {
         throw new Error(`extension relay requires loopback cdpUrl host (got ${info.host})`);
     }
     const existing = serversByPort.get(info.port);
-    if (existing)
+    if (existing) {
         return existing;
+    }
     let extensionWs = null;
     const cdpClients = new Set();
     const connectedTargets = new Map();
@@ -86,14 +107,16 @@ export async function ensureChromeExtensionRelayServer(opts) {
     const broadcastToCdpClients = (evt) => {
         const msg = JSON.stringify(evt);
         for (const ws of cdpClients) {
-            if (ws.readyState !== WebSocket.OPEN)
+            if (ws.readyState !== WebSocket.OPEN) {
                 continue;
+            }
             ws.send(msg);
         }
     };
     const sendResponseToCdp = (ws, res) => {
-        if (ws.readyState !== WebSocket.OPEN)
+        if (ws.readyState !== WebSocket.OPEN) {
             return;
+        }
         ws.send(JSON.stringify(res));
     };
     const ensureTargetEventsForClient = (ws, mode) => {
@@ -143,14 +166,16 @@ export async function ensureChromeExtensionRelayServer(opts) {
                 const targetId = typeof params.targetId === "string" ? params.targetId : undefined;
                 if (targetId) {
                     for (const t of connectedTargets.values()) {
-                        if (t.targetId === targetId)
+                        if (t.targetId === targetId) {
                             return { targetInfo: t.targetInfo };
+                        }
                     }
                 }
                 if (cmd.sessionId && connectedTargets.has(cmd.sessionId)) {
                     const t = connectedTargets.get(cmd.sessionId);
-                    if (t)
+                    if (t) {
                         return { targetInfo: t.targetInfo };
+                    }
                 }
                 const first = Array.from(connectedTargets.values())[0];
                 return { targetInfo: first?.targetInfo };
@@ -158,11 +183,13 @@ export async function ensureChromeExtensionRelayServer(opts) {
             case "Target.attachToTarget": {
                 const params = (cmd.params ?? {});
                 const targetId = typeof params.targetId === "string" ? params.targetId : undefined;
-                if (!targetId)
+                if (!targetId) {
                     throw new Error("targetId required");
+                }
                 for (const t of connectedTargets.values()) {
-                    if (t.targetId === targetId)
+                    if (t.targetId === targetId) {
                         return { sessionId: t.sessionId };
+                    }
                 }
                 throw new Error("target not found");
             }
@@ -180,9 +207,18 @@ export async function ensureChromeExtensionRelayServer(opts) {
             }
         }
     };
+    const relayAuthToken = randomBytes(32).toString("base64url");
     const server = createServer((req, res) => {
         const url = new URL(req.url ?? "/", info.baseUrl);
         const path = url.pathname;
+        if (path.startsWith("/json")) {
+            const token = getHeader(req, RELAY_AUTH_HEADER);
+            if (!token || token !== relayAuthToken) {
+                res.writeHead(401);
+                res.end("Unauthorized");
+                return;
+            }
+        }
         if (req.method === "HEAD" && path === "/") {
             res.writeHead(200);
             res.end();
@@ -208,8 +244,9 @@ export async function ensureChromeExtensionRelayServer(opts) {
                 "Protocol-Version": "1.3",
             };
             // Only advertise the WS URL if a real extension is connected.
-            if (extensionWs)
+            if (extensionWs) {
                 payload.webSocketDebuggerUrl = cdpWsUrl;
+            }
             res.writeHead(200, { "Content-Type": "application/json" });
             res.end(JSON.stringify(payload));
             return;
@@ -290,6 +327,11 @@ export async function ensureChromeExtensionRelayServer(opts) {
             rejectUpgrade(socket, 403, "Forbidden");
             return;
         }
+        const origin = headerValue(req.headers.origin);
+        if (origin && !origin.startsWith("chrome-extension://")) {
+            rejectUpgrade(socket, 403, "Forbidden: invalid origin");
+            return;
+        }
         if (pathname === "/extension") {
             if (extensionWs) {
                 rejectUpgrade(socket, 409, "Extension already connected");
@@ -301,6 +343,11 @@ export async function ensureChromeExtensionRelayServer(opts) {
             return;
         }
         if (pathname === "/cdp") {
+            const token = getHeader(req, RELAY_AUTH_HEADER);
+            if (!token || token !== relayAuthToken) {
+                rejectUpgrade(socket, 401, "Unauthorized");
+                return;
+            }
             if (!extensionWs) {
                 rejectUpgrade(socket, 503, "Extension not connected");
                 return;
@@ -315,8 +362,9 @@ export async function ensureChromeExtensionRelayServer(opts) {
     wssExtension.on("connection", (ws) => {
         extensionWs = ws;
         const ping = setInterval(() => {
-            if (ws.readyState !== WebSocket.OPEN)
+            if (ws.readyState !== WebSocket.OPEN) {
                 return;
+            }
             ws.send(JSON.stringify({ method: "ping" }));
         }, 5000);
         ws.on("message", (data) => {
@@ -329,8 +377,9 @@ export async function ensureChromeExtensionRelayServer(opts) {
             }
             if (parsed && typeof parsed === "object" && "id" in parsed && typeof parsed.id === "number") {
                 const pending = pendingExtension.get(parsed.id);
-                if (!pending)
+                if (!pending) {
                     return;
+                }
                 pendingExtension.delete(parsed.id);
                 clearTimeout(pending.timer);
                 if ("error" in parsed && typeof parsed.error === "string" && parsed.error.trim()) {
@@ -342,21 +391,25 @@ export async function ensureChromeExtensionRelayServer(opts) {
                 return;
             }
             if (parsed && typeof parsed === "object" && "method" in parsed) {
-                if (parsed.method === "pong")
+                if (parsed.method === "pong") {
                     return;
-                if (parsed.method !== "forwardCDPEvent")
+                }
+                if (parsed.method !== "forwardCDPEvent") {
                     return;
+                }
                 const evt = parsed;
                 const method = evt.params?.method;
                 const params = evt.params?.params;
                 const sessionId = evt.params?.sessionId;
-                if (!method || typeof method !== "string")
+                if (!method || typeof method !== "string") {
                     return;
+                }
                 if (method === "Target.attachedToTarget") {
                     const attached = (params ?? {});
                     const targetType = attached?.targetInfo?.type ?? "page";
-                    if (targetType !== "page")
+                    if (targetType !== "page") {
                         return;
+                    }
                     if (attached?.sessionId && attached?.targetInfo?.targetId) {
                         const prev = connectedTargets.get(attached.sessionId);
                         const nextTargetId = attached.targetInfo.targetId;
@@ -382,8 +435,9 @@ export async function ensureChromeExtensionRelayServer(opts) {
                 }
                 if (method === "Target.detachedFromTarget") {
                     const detached = (params ?? {});
-                    if (detached?.sessionId)
+                    if (detached?.sessionId) {
                         connectedTargets.delete(detached.sessionId);
+                    }
                     broadcastToCdpClients({ method, params, sessionId });
                     return;
                 }
@@ -395,8 +449,9 @@ export async function ensureChromeExtensionRelayServer(opts) {
                     const targetId = targetInfo?.targetId;
                     if (targetId && (targetInfo?.type ?? "page") === "page") {
                         for (const [sid, target] of connectedTargets) {
-                            if (target.targetId !== targetId)
+                            if (target.targetId !== targetId) {
                                 continue;
+                            }
                             connectedTargets.set(sid, {
                                 ...target,
                                 targetInfo: { ...target.targetInfo, ...targetInfo },
@@ -437,10 +492,12 @@ export async function ensureChromeExtensionRelayServer(opts) {
             catch {
                 return;
             }
-            if (!cmd || typeof cmd !== "object")
+            if (!cmd || typeof cmd !== "object") {
                 return;
-            if (typeof cmd.id !== "number" || typeof cmd.method !== "string")
+            }
+            if (typeof cmd.id !== "number" || typeof cmd.method !== "string") {
                 return;
+            }
             if (!extensionWs) {
                 sendResponseToCdp(ws, {
                     id: cmd.id,
@@ -507,6 +564,7 @@ export async function ensureChromeExtensionRelayServer(opts) {
         extensionConnected: () => Boolean(extensionWs),
         stop: async () => {
             serversByPort.delete(port);
+            relayAuthByPort.delete(port);
             try {
                 extensionWs?.close(1001, "server stopping");
             }
@@ -528,14 +586,17 @@ export async function ensureChromeExtensionRelayServer(opts) {
             wssCdp.close();
         },
     };
+    relayAuthByPort.set(port, relayAuthToken);
     serversByPort.set(port, relay);
     return relay;
 }
 export async function stopChromeExtensionRelayServer(opts) {
     const info = parseBaseUrl(opts.cdpUrl);
     const existing = serversByPort.get(info.port);
-    if (!existing)
+    if (!existing) {
         return false;
+    }
     await existing.stop();
+    relayAuthByPort.delete(info.port);
     return true;
 }

package/dist/browser/pw-ai.js

@@ -1,2 +1,2 @@
-export { closePageByTargetIdViaPlaywright, closePlaywrightBrowserConnection, createPageViaPlaywright, ensurePageState, focusPageByTargetIdViaPlaywright, getPageForTargetId, listPagesViaPlaywright, refLocator, } from "./pw-session.js";
+export { closePageByTargetIdViaPlaywright, closePlaywrightBrowserConnection, createPageViaPlaywright, ensurePageState, forceDisconnectPlaywrightForTarget, focusPageByTargetIdViaPlaywright, getPageForTargetId, listPagesViaPlaywright, refLocator, } from "./pw-session.js";
 export { armDialogViaPlaywright, armFileUploadViaPlaywright, clickViaPlaywright, closePageViaPlaywright, cookiesClearViaPlaywright, cookiesGetViaPlaywright, cookiesSetViaPlaywright, downloadViaPlaywright, dragViaPlaywright, emulateMediaViaPlaywright, evaluateViaPlaywright, fillFormViaPlaywright, getConsoleMessagesViaPlaywright, getNetworkRequestsViaPlaywright, getPageErrorsViaPlaywright, highlightViaPlaywright, hoverViaPlaywright, navigateViaPlaywright, pdfViaPlaywright, pressKeyViaPlaywright, resizeViewportViaPlaywright, responseBodyViaPlaywright, scrollIntoViewViaPlaywright, selectOptionViaPlaywright, setDeviceViaPlaywright, setExtraHTTPHeadersViaPlaywright, setGeolocationViaPlaywright, setHttpCredentialsViaPlaywright, setInputFilesViaPlaywright, setLocaleViaPlaywright, setOfflineViaPlaywright, setTimezoneViaPlaywright, snapshotAiViaPlaywright, snapshotAriaViaPlaywright, snapshotRoleViaPlaywright, screenshotWithLabelsViaPlaywright, storageClearViaPlaywright, storageGetViaPlaywright, storageSetViaPlaywright, takeScreenshotViaPlaywright, traceStartViaPlaywright, traceStopViaPlaywright, typeViaPlaywright, waitForDownloadViaPlaywright, waitForViaPlaywright, } from "./pw-tools-core.js";

package/dist/browser/pw-session.js

@@ -1,6 +1,7 @@
 import { chromium } from "playwright-core";
 import { formatErrorMessage } from "../infra/errors.js";
-import { getHeadersWithAuth } from "./cdp.helpers.js";
+import { appendCdpPath, fetchJson, getHeadersWithAuth, withCdpSocket } from "./cdp.helpers.js";
+import { normalizeCdpWsUrl } from "./cdp.js";
 import { getChromeWebSocketUrl } from "./chrome.js";
 const pageStates = new WeakMap();
 const contextStates = new WeakMap();
@@ -196,13 +197,15 @@ async function connectBrowser(cdpUrl) {
                 const endpoint = wsUrl ?? normalized;
                 const headers = getHeadersWithAuth(endpoint);
                 const browser = await chromium.connectOverCDP(endpoint, { timeout, headers });
-                const connected = { browser, cdpUrl: normalized };
+                const onDisconnected = () => {
+                    if (cached?.browser === browser) {
+                        cached = null;
+                    }
+                };
+                const connected = { browser, cdpUrl: normalized, onDisconnected };
                 cached = connected;
+                browser.on("disconnected", onDisconnected);
                 observeBrowser(browser);
-                browser.on("disconnected", () => {
-                    if (cached?.browser === browser)
-                        cached = null;
-                });
                 return connected;
             }
             catch (err) {
@@ -254,7 +257,8 @@ async function findPageByTargetId(browser, targetId, cdpUrl) {
                 .replace(/\/+$/, "")
                 .replace(/^ws:/, "http:")
                 .replace(/\/cdp$/, "");
-            const response = await fetch(`${baseUrl}/json/list`);
+            const listUrl = `${baseUrl}/json/list`;
+            const response = await fetch(listUrl, { headers: getHeadersWithAuth(listUrl) });
             if (response.ok) {
                 const targets = (await response.json());
                 const target = targets.find((t) => t.id === targetId);
@@ -335,10 +339,141 @@ export function refLocator(page, ref) {
 export async function closePlaywrightBrowserConnection() {
     const cur = cached;
     cached = null;
-    if (!cur)
+    connecting = null;
+    if (!cur) {
         return;
+    }
+    if (cur.onDisconnected && typeof cur.browser.off === "function") {
+        cur.browser.off("disconnected", cur.onDisconnected);
+    }
     await cur.browser.close().catch(() => { });
 }
+function normalizeCdpHttpBaseForJsonEndpoints(cdpUrl) {
+    try {
+        const url = new URL(cdpUrl);
+        if (url.protocol === "ws:") {
+            url.protocol = "http:";
+        }
+        else if (url.protocol === "wss:") {
+            url.protocol = "https:";
+        }
+        url.pathname = url.pathname.replace(/\/devtools\/browser\/.*$/, "");
+        url.pathname = url.pathname.replace(/\/cdp$/, "");
+        return url.toString().replace(/\/$/, "");
+    }
+    catch {
+        // Best-effort fallback for non-URL-ish inputs.
+        return cdpUrl
+            .replace(/^ws:/, "http:")
+            .replace(/^wss:/, "https:")
+            .replace(/\/devtools\/browser\/.*$/, "")
+            .replace(/\/cdp$/, "")
+            .replace(/\/$/, "");
+    }
+}
+function cdpSocketNeedsAttach(wsUrl) {
+    try {
+        const pathname = new URL(wsUrl).pathname;
+        return (pathname === "/cdp" || pathname.endsWith("/cdp") || pathname.includes("/devtools/browser/"));
+    }
+    catch {
+        return false;
+    }
+}
+async function tryTerminateExecutionViaCdp(opts) {
+    const cdpHttpBase = normalizeCdpHttpBaseForJsonEndpoints(opts.cdpUrl);
+    const listUrl = appendCdpPath(cdpHttpBase, "/json/list");
+    const pages = await fetchJson(listUrl, 2000).catch(() => null);
+    if (!pages || pages.length === 0) {
+        return;
+    }
+    const target = pages.find((p) => String(p.id ?? "").trim() === opts.targetId);
+    const wsUrlRaw = String(target?.webSocketDebuggerUrl ?? "").trim();
+    if (!wsUrlRaw) {
+        return;
+    }
+    const wsUrl = normalizeCdpWsUrl(wsUrlRaw, cdpHttpBase);
+    const needsAttach = cdpSocketNeedsAttach(wsUrl);
+    const runWithTimeout = async (work, ms) => {
+        let timer;
+        const timeoutPromise = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error("CDP command timed out")), ms);
+        });
+        try {
+            return await Promise.race([work, timeoutPromise]);
+        }
+        finally {
+            if (timer) {
+                clearTimeout(timer);
+            }
+        }
+    };
+    await withCdpSocket(wsUrl, async (send) => {
+        let sessionId;
+        try {
+            if (needsAttach) {
+                const attached = (await runWithTimeout(send("Target.attachToTarget", { targetId: opts.targetId, flatten: true }), 1500));
+                if (typeof attached?.sessionId === "string" && attached.sessionId.trim()) {
+                    sessionId = attached.sessionId;
+                }
+            }
+            await runWithTimeout(send("Runtime.terminateExecution", undefined, sessionId), 1500);
+            if (sessionId) {
+                // Best-effort cleanup; not required for termination to take effect.
+                void send("Target.detachFromTarget", { sessionId }).catch(() => { });
+            }
+        }
+        catch {
+            // Best-effort; ignore
+        }
+    }, { handshakeTimeoutMs: 2000 }).catch(() => { });
+}
+/**
+ * Best-effort cancellation for stuck page operations.
+ *
+ * Playwright serializes CDP commands per page; a long-running or stuck operation (notably evaluate)
+ * can block all subsequent commands. We cannot safely "cancel" an individual command, and we do
+ * not want to close the actual Chromium tab. Instead, we disconnect Playwright's CDP connection
+ * so in-flight commands fail fast and the next request reconnects transparently.
+ *
+ * IMPORTANT: We CANNOT call Connection.close() because Playwright shares a single Connection
+ * across all objects (BrowserType, Browser, etc.). Closing it corrupts the entire Playwright
+ * instance, preventing reconnection.
+ *
+ * Instead we:
+ * 1. Null out `cached` so the next call triggers a fresh connectOverCDP
+ * 2. Fire-and-forget browser.close() — it may hang but won't block us
+ * 3. The next connectBrowser() creates a completely new CDP WebSocket connection
+ *
+ * The old browser.close() eventually resolves when the in-browser evaluate timeout fires,
+ * or the old connection gets GC'd. Either way, it doesn't affect the fresh connection.
+ */
+export async function forceDisconnectPlaywrightForTarget(opts) {
+    const normalized = normalizeCdpUrl(opts.cdpUrl);
+    if (cached?.cdpUrl !== normalized) {
+        return;
+    }
+    const cur = cached;
+    cached = null;
+    // Also clear `connecting` so the next call does a fresh connectOverCDP
+    // rather than awaiting a stale promise.
+    connecting = null;
+    if (cur) {
+        // Remove the "disconnected" listener to prevent the old browser's teardown
+        // from racing with a fresh connection and nulling the new `cached`.
+        if (cur.onDisconnected && typeof cur.browser.off === "function") {
+            cur.browser.off("disconnected", cur.onDisconnected);
+        }
+        // Best-effort: kill any stuck JS to unblock the target's execution context before we
+        // disconnect Playwright's CDP connection.
+        const targetId = opts.targetId?.trim() || "";
+        if (targetId) {
+            await tryTerminateExecutionViaCdp({ cdpUrl: normalized, targetId }).catch(() => { });
+        }
+        // Fire-and-forget: don't await because browser.close() may hang on the stuck CDP pipe.
+        cur.browser.close().catch(() => { });
+    }
+}
 /**
  * List all pages/tabs from the persistent Playwright connection.
  * Used for remote profiles where HTTP-based /json/list is ephemeral.