opendevbrowser 0.0.17 → 0.0.19

package/extension/dist/services/CDPRouter.js

@@ -1,15 +1,30 @@
 import { TabManager } from "./TabManager.js";
 import { TargetSessionMap } from "./TargetSessionMap.js";
 import { logError } from "../logging.js";
+import { getRestrictionMessage } from "./url-restrictions.js";
+import { isAttachBlockedError } from "./attach-errors.js";
 import { handleSetDiscoverTargets, handleSetAutoAttach, handleCreateTarget, handleCloseTarget, handleActivateTarget, handleAttachToTarget, handleRoutedCommand } from "./cdp-router-commands.js";
 const FLAT_SESSION_ERROR = "Chrome 125+ required for extension relay (flat sessions).";
 const DEPRECATED_SEND_MESSAGE = "Target.sendMessageToTarget is deprecated in flat session mode. Use sessionId routing.";
 const DEFAULT_BROWSER_CONTEXT_ID = "default";
+const DEFAULT_BROWSER_TARGET_ID = "browser";
+const STALE_TAB_ERROR_MARKERS = [
+    "No tab with given id",
+    "Debugger is not attached",
+    "Detached while handling command"
+];
 export class CDPRouter {
     debuggees = new Map();
+    rootTargetTabIds = new Map();
     sessions = new TargetSessionMap();
     tabManager = new TabManager();
     rootAttachedSessions = new Set();
+    pendingTargetTabIds = new Map();
+    childAttachDiagnostics = new Map();
+    rootAttachDiagnostics = new Map();
+    rootRefreshDiagnostics = new Map();
+    expectedRootDetachDeadlines = new Map();
+    eventListeners = new Set();
     callbacks = null;
     autoAttachOptions = { autoAttach: false, waitForDebuggerOnStart: false, flatten: true };
     discoverTargets = false;
@@ -22,6 +37,7 @@ export class CDPRouter {
     churnTracker = new Map();
     churnWindowMs = 5000;
     churnThreshold = 3;
+    clientResetPending = false;
     handleEventBound = (source, method, params) => {
         this.handleEvent(source, method, params);
     };
@@ -31,38 +47,364 @@ export class CDPRouter {
     setCallbacks(callbacks) {
         this.callbacks = callbacks;
     }
+    addEventListener(listener) {
+        this.eventListeners.add(listener);
+    }
+    removeEventListener(listener) {
+        this.eventListeners.delete(listener);
+    }
+    async setDiscoverTargetsEnabled(discover) {
+        await this.prepareForNextClientIfNeeded();
+        const shouldEmit = discover && !this.discoverTargets;
+        this.discoverTargets = discover;
+        for (const debuggee of this.debuggees.values()) {
+            await this.applyDiscoverTargets(debuggee, discover);
+        }
+        if (!shouldEmit) {
+            return;
+        }
+        for (const targetInfo of this.sessions.listTargetInfos()) {
+            const tabId = this.sessions.getByTargetId(targetInfo.targetId)?.tabId
+                ?? this.rootTargetTabIds.get(targetInfo.targetId)
+                ?? this.primaryTabId;
+            if (typeof tabId === "number") {
+                this.emitTargetCreated(tabId, targetInfo);
+            }
+        }
+    }
+    async configureAutoAttach(options) {
+        await this.prepareForNextClientIfNeeded();
+        if (options.flatten === false) {
+            throw new Error(FLAT_SESSION_ERROR);
+        }
+        this.autoAttachOptions = { ...options, flatten: true };
+        if (this.autoAttachOptions.autoAttach) {
+            this.resetRootAttached();
+        }
+        for (const debuggee of this.debuggees.values()) {
+            await this.applyAutoAttach(debuggee);
+        }
+        if (!this.autoAttachOptions.autoAttach) {
+            this.emitRootDetached();
+            return;
+        }
+        for (const tabId of this.sessions.listTabIds()) {
+            await this.refreshRootTargetInfo(tabId);
+        }
+        for (const targetInfo of this.sessions.listTargetInfos()) {
+            this.emitRootAttached(targetInfo);
+        }
+    }
     async attach(tabId) {
+        await this.prepareForNextClientIfNeeded(tabId);
         await this.attachInternal(tabId, true);
     }
+    async refreshTabAttachment(tabId) {
+        const preparedTabId = await this.prepareForNextClientIfNeeded(tabId);
+        const resetPreparedSameTabRoot = preparedTabId === tabId && this.debuggees.has(tabId);
+        const path = this.debuggees.has(tabId)
+            ? "reattach_root_debuggee"
+            : "attach_internal";
+        try {
+            if (resetPreparedSameTabRoot) {
+                // Reset preflight already rebuilt this root; probing it is enough.
+            }
+            else if (path === "reattach_root_debuggee") {
+                await this.reattachRootDebuggee(tabId);
+            }
+            else {
+                await this.attachInternal(tabId, false);
+            }
+        }
+        catch (error) {
+            await this.captureRootRefreshDiagnostic(tabId, path, false, error);
+            throw error;
+        }
+        await this.captureRootRefreshDiagnostic(tabId, path, true);
+    }
+    async primeAttachedRootSession(tabId) {
+        await this.prepareForNextClientIfNeeded(tabId);
+        if (this.sessions.getAttachedRootSession(tabId)) {
+            return;
+        }
+        await this.ensureAttachedRootSession(tabId);
+    }
+    async resolveTabTargetId(tabId) {
+        await this.prepareForNextClientIfNeeded(tabId);
+        return (await this.readDebuggerTargetInfo(tabId))?.id ?? null;
+    }
+    async resolveTabOpenerTargetId(tabId) {
+        await this.prepareForNextClientIfNeeded();
+        const { tab, pageTargets } = await this.readDebuggerPageTargets(tabId);
+        if (pageTargets.length === 0) {
+            return null;
+        }
+        const preferredTarget = this.selectPreferredDebuggerTargetInfo(tab, pageTargets);
+        const candidates = preferredTarget
+            ? [preferredTarget, ...pageTargets.filter((target) => target !== preferredTarget)]
+            : pageTargets;
+        for (const candidate of candidates) {
+            const targetInfo = this.resolveTargetInfo(candidate.id);
+            const openerTabId = this.pendingTargetTabIds.get(candidate.id)
+                ?? this.resolveLinkedTargetTabId(candidate.openerId)
+                ?? this.resolveLinkedTargetTabId(targetInfo?.openerId)
+                ?? null;
+            if (openerTabId !== null) {
+                return `tab-${openerTabId}`;
+            }
+        }
+        return null;
+    }
+    async attachChildTarget(tabId, targetId) {
+        await this.prepareForNextClientIfNeeded(tabId);
+        let rootDebuggee;
+        try {
+            rootDebuggee = await this.resolveRootSessionDebuggee(tabId);
+        }
+        catch (error) {
+            this.recordChildAttachDiagnostic(tabId, targetId, {
+                stage: "raw_attach_failed",
+                reason: getErrorMessage(error)
+            });
+            throw error;
+        }
+        let initialStage;
+        let directError = null;
+        let rootTargetRetryStage;
+        const captureRootRecordState = () => {
+            const record = this.sessions.getByTabId(tabId);
+            return {
+                present: Boolean(record),
+                rootSessionId: record?.rootSessionId ?? null,
+                targetId: record?.targetInfo.targetId ?? null,
+                attachTargetId: record?.attachTargetId ?? null
+            };
+        };
+        try {
+            const directSessionId = await this.attachChildTargetWithDebuggee(rootDebuggee, targetId);
+            if (directSessionId) {
+                this.clearChildAttachDiagnostic(tabId, targetId);
+                return directSessionId;
+            }
+            const directTargetRetry = await this.attachChildTargetWithRootTargetId(rootDebuggee, targetId);
+            if (directTargetRetry.sessionId) {
+                this.clearChildAttachDiagnostic(tabId, targetId);
+                return directTargetRetry.sessionId;
+            }
+            if (directTargetRetry.stage !== "attached") {
+                rootTargetRetryStage = directTargetRetry.stage;
+            }
+            initialStage = "raw_attach_null";
+        }
+        catch (error) {
+            const attachBlocked = isAttachBlockedError(error);
+            const staleRootDebuggee = this.isStaleTabError(error);
+            if (!attachBlocked && !staleRootDebuggee) {
+                this.recordChildAttachDiagnostic(tabId, targetId, {
+                    stage: "raw_attach_failed",
+                    reason: getErrorMessage(error)
+                });
+                throw error;
+            }
+            if (staleRootDebuggee) {
+                directError = error;
+            }
+            if (attachBlocked || staleRootDebuggee) {
+                let directTargetRetry;
+                try {
+                    directTargetRetry = await this.attachChildTargetWithRootTargetId(rootDebuggee, targetId, error);
+                }
+                catch (fallbackError) {
+                    this.recordChildAttachDiagnostic(tabId, targetId, {
+                        stage: "raw_attach_failed",
+                        reason: getErrorMessage(fallbackError)
+                    });
+                    throw fallbackError;
+                }
+                if (directTargetRetry.sessionId) {
+                    this.clearChildAttachDiagnostic(tabId, targetId);
+                    return directTargetRetry.sessionId;
+                }
+                if (directTargetRetry.stage !== "attached") {
+                    rootTargetRetryStage = directTargetRetry.stage;
+                }
+                if (attachBlocked) {
+                    initialStage = "raw_attach_blocked";
+                    directError = error;
+                }
+            }
+        }
+        let attachedRootRecovery = await this.ensureAttachedRootSessionWithDiagnostic(tabId);
+        let attachedRootRecoveryRetriedAfterRegisterRoot = false;
+        let attachedRootRecoveryRegisterRootChanged;
+        let attachedRootRecoveryRegisterRootAttachTargetChanged;
+        if (!attachedRootRecovery.debuggerSession) {
+            const beforeRegisterRoot = captureRootRecordState();
+            await this.registerRootTab(tabId);
+            const afterRegisterRoot = captureRootRecordState();
+            attachedRootRecoveryRetriedAfterRegisterRoot = true;
+            attachedRootRecoveryRegisterRootChanged = beforeRegisterRoot.present !== afterRegisterRoot.present
+                || beforeRegisterRoot.rootSessionId !== afterRegisterRoot.rootSessionId
+                || beforeRegisterRoot.targetId !== afterRegisterRoot.targetId
+                || beforeRegisterRoot.attachTargetId !== afterRegisterRoot.attachTargetId;
+            attachedRootRecoveryRegisterRootAttachTargetChanged = beforeRegisterRoot.attachTargetId !== afterRegisterRoot.attachTargetId;
+            attachedRootRecovery = await this.ensureAttachedRootSessionWithDiagnostic(tabId);
+        }
+        if (!attachedRootRecovery.debuggerSession) {
+            const reattachedChild = await this.reattachRootAndAttachChildTarget(tabId, targetId);
+            if (reattachedChild.sessionId) {
+                this.clearChildAttachDiagnostic(tabId, targetId);
+                return reattachedChild.sessionId;
+            }
+            const terminalBranch = reattachedChild.terminalBranch
+                ?? (attachedRootRecoveryRetriedAfterRegisterRoot
+                    ? "post_register_root_recovery"
+                    : "initial_attached_root_recovery");
+            this.recordChildAttachDiagnostic(tabId, targetId, {
+                stage: "attached_root_unavailable",
+                ...(initialStage ? { initialStage } : {}),
+                ...(rootTargetRetryStage ? { rootTargetRetryStage } : {}),
+                ...(attachedRootRecovery.stage !== "attached"
+                    ? { attachedRootRecoveryStage: attachedRootRecovery.stage }
+                    : {}),
+                ...(attachedRootRecovery.attachTargetSource
+                    ? { attachedRootRecoverySource: attachedRootRecovery.attachTargetSource }
+                    : {}),
+                ...(attachedRootRecovery.attachTargetId
+                    ? { attachedRootRecoveryAttachTargetId: attachedRootRecovery.attachTargetId }
+                    : {}),
+                ...(attachedRootRecoveryRetriedAfterRegisterRoot
+                    ? { attachedRootRecoveryRetriedAfterRegisterRoot: true }
+                    : {}),
+                ...(typeof attachedRootRecoveryRegisterRootChanged === "boolean"
+                    ? { attachedRootRecoveryRegisterRootChanged }
+                    : {}),
+                ...(typeof attachedRootRecoveryRegisterRootAttachTargetChanged === "boolean"
+                    ? { attachedRootRecoveryRegisterRootAttachTargetChanged }
+                    : {}),
+                ...(typeof attachedRootRecovery.registerAttachedRootSessionCalled === "boolean"
+                    ? { attachedRootRecoveryRegisterAttachedRootSessionCalled: attachedRootRecovery.registerAttachedRootSessionCalled }
+                    : {}),
+                attachedRootUnavailableTerminalBranch: terminalBranch,
+                ...(reattachedChild.stage ? { reattachRecoveryStage: reattachedChild.stage } : {}),
+                ...(reattachedChild.reason ? { reattachRecoveryReason: reattachedChild.reason } : {}),
+                ...(attachedRootRecovery.reason
+                    ? { attachedRootRecoveryReason: attachedRootRecovery.reason }
+                    : {}),
+                ...((directError || attachedRootRecovery.reason || reattachedChild.reason)
+                    ? {
+                        reason: directError
+                            ? getErrorMessage(directError)
+                            : (attachedRootRecovery.reason ?? reattachedChild.reason)
+                    }
+                    : {})
+            });
+            if (directError) {
+                throw directError;
+            }
+            return null;
+        }
+        try {
+            const attachedRootSessionId = await this.attachChildTargetWithDebuggee(attachedRootRecovery.debuggerSession, targetId);
+            if (attachedRootSessionId) {
+                this.clearChildAttachDiagnostic(tabId, targetId);
+                return attachedRootSessionId;
+            }
+            await this.restoreRootAfterChildAttachFailure(tabId);
+            this.recordChildAttachDiagnostic(tabId, targetId, {
+                stage: "attached_root_attach_null",
+                ...(initialStage ? { initialStage } : {}),
+                ...(rootTargetRetryStage ? { rootTargetRetryStage } : {}),
+                ...(attachedRootRecovery.attachTargetSource
+                    ? { attachedRootRecoverySource: attachedRootRecovery.attachTargetSource }
+                    : {}),
+                ...(attachedRootRecovery.attachTargetId
+                    ? { attachedRootRecoveryAttachTargetId: attachedRootRecovery.attachTargetId }
+                    : {}),
+                ...(typeof attachedRootRecovery.registerAttachedRootSessionCalled === "boolean"
+                    ? { attachedRootRecoveryRegisterAttachedRootSessionCalled: attachedRootRecovery.registerAttachedRootSessionCalled }
+                    : {})
+            });
+            return null;
+        }
+        catch (error) {
+            await this.restoreRootAfterChildAttachFailure(tabId);
+            this.recordChildAttachDiagnostic(tabId, targetId, {
+                stage: "attached_root_attach_failed",
+                ...(initialStage ? { initialStage } : {}),
+                ...(rootTargetRetryStage ? { rootTargetRetryStage } : {}),
+                ...(attachedRootRecovery.attachTargetSource
+                    ? { attachedRootRecoverySource: attachedRootRecovery.attachTargetSource }
+                    : {}),
+                ...(attachedRootRecovery.attachTargetId
+                    ? { attachedRootRecoveryAttachTargetId: attachedRootRecovery.attachTargetId }
+                    : {}),
+                ...(typeof attachedRootRecovery.registerAttachedRootSessionCalled === "boolean"
+                    ? { attachedRootRecoveryRegisterAttachedRootSessionCalled: attachedRootRecovery.registerAttachedRootSessionCalled }
+                    : {}),
+                reason: getErrorMessage(error)
+            });
+            throw error;
+        }
+    }
+    getLastChildAttachDiagnostic(tabId, targetId) {
+        return this.childAttachDiagnostics.get(this.childAttachDiagnosticKey(tabId, targetId)) ?? null;
+    }
+    getLastRootRefreshDiagnostic(tabId) {
+        return this.rootRefreshDiagnostics.get(tabId) ?? null;
+    }
+    getLastRootAttachDiagnostic(tabId) {
+        return this.rootAttachDiagnostics.get(tabId) ?? null;
+    }
+    hasDebuggerSession(sessionId) {
+        return this.sessions.hasSession(sessionId);
+    }
+    registerChildSession(tabId, targetInfo, sessionId) {
+        this.sessions.registerChildSession(tabId, targetInfo, sessionId);
+    }
     async attachInternal(tabId, allowRetry) {
         if (this.debuggees.has(tabId)) {
+            this.clearRootAttachDiagnostic(tabId);
             this.updatePrimaryTab(tabId);
+            await this.pruneRootDebuggees(tabId);
             return;
         }
-        const debuggee = { tabId };
+        const debuggee = await this.resolveRootDebuggee(tabId);
+        let attachedDebuggee = debuggee;
+        const displacedRoots = await this.detachConflictingRootDebuggees(tabId);
         this.debuggees.set(tabId, debuggee);
         this.ensureListeners();
         try {
-            await this.runDebuggerAction((done) => {
-                chrome.debugger.attach(debuggee, "1.3", done);
-            });
-            await this.ensureFlatSessionSupport(debuggee);
+            attachedDebuggee = await this.attachRootDebuggeeWithFallback(tabId, debuggee);
             const targetInfo = await this.registerRootTab(tabId);
             if (this.discoverTargets) {
-                this.emitTargetCreated(targetInfo);
+                await this.applyDiscoverTargets(attachedDebuggee, true);
+                this.emitTargetCreated(tabId, targetInfo);
             }
             if (this.autoAttachOptions.autoAttach) {
-                await this.applyAutoAttach(debuggee);
+                await this.applyAutoAttach(attachedDebuggee);
                 this.emitRootAttached(targetInfo);
             }
             this.updatePrimaryTab(tabId);
+            this.commitDetachedRootDebuggees(displacedRoots);
+            await this.pruneRootDebuggees(tabId);
+            this.clearRootAttachDiagnostic(tabId);
         }
         catch (error) {
+            if (isAttachBlockedError(error) && await this.reuseAlreadyAttachedRootDebuggee(tabId)) {
+                this.commitDetachedRootDebuggees(displacedRoots);
+                await this.pruneRootDebuggees(tabId);
+                this.clearRootAttachDiagnostic(tabId);
+                return;
+            }
             this.debuggees.delete(tabId);
+            if (typeof attachedDebuggee.targetId === "string") {
+                this.rootTargetTabIds.delete(attachedDebuggee.targetId);
+            }
             if (this.debuggees.size === 0) {
                 this.removeListeners();
             }
-            await this.safeDetach(debuggee);
+            await this.safeDetach(attachedDebuggee);
             if (allowRetry && this.isStaleTabError(error)) {
                 const attemptedTabIds = new Set([tabId]);
                 let lastStaleError = error;
@@ -70,7 +412,9 @@ export class CDPRouter {
                 if (activeTabId && !attemptedTabIds.has(activeTabId)) {
                     attemptedTabIds.add(activeTabId);
                     try {
-                        return await this.attachInternal(activeTabId, false);
+                        await this.attachInternal(activeTabId, false);
+                        this.commitDetachedRootDebuggees(displacedRoots);
+                        return;
                     }
                     catch (candidateError) {
                         if (!this.isStaleTabError(candidateError)) {
@@ -83,7 +427,9 @@ export class CDPRouter {
                 if (fallbackTabId && !attemptedTabIds.has(fallbackTabId)) {
                     attemptedTabIds.add(fallbackTabId);
                     try {
-                        return await this.attachInternal(fallbackTabId, false);
+                        await this.attachInternal(fallbackTabId, false);
+                        this.commitDetachedRootDebuggees(displacedRoots);
+                        return;
                     }
                     catch (candidateError) {
                         if (!this.isStaleTabError(candidateError)) {
@@ -95,7 +441,9 @@ export class CDPRouter {
                 try {
                     const createdTab = await this.tabManager.createTab("about:blank", true);
                     if (typeof createdTab.id === "number" && !attemptedTabIds.has(createdTab.id)) {
-                        return await this.attachInternal(createdTab.id, false);
+                        await this.attachInternal(createdTab.id, false);
+                        this.commitDetachedRootDebuggees(displacedRoots);
+                        return;
                     }
                 }
                 catch (candidateError) {
@@ -104,11 +452,122 @@ export class CDPRouter {
                     }
                     lastStaleError = candidateError;
                 }
+                await this.restoreDetachedRootDebuggees(displacedRoots);
                 throw lastStaleError;
             }
+            await this.restoreDetachedRootDebuggees(displacedRoots);
+            throw error;
+        }
+    }
+    async reuseAlreadyAttachedRootDebuggee(tabId) {
+        const targetInfo = await this.readDebuggerTargetInfo(tabId);
+        if (!targetInfo?.attached) {
+            return false;
+        }
+        const reusedDebuggee = {
+            tabId,
+            targetId: targetInfo.id,
+            attachBy: "targetId"
+        };
+        this.debuggees.set(tabId, reusedDebuggee);
+        this.ensureListeners();
+        try {
+            await this.ensureFlatSessionSupport(reusedDebuggee);
+            const registeredTarget = await this.registerRootTab(tabId);
+            if (this.discoverTargets) {
+                await this.applyDiscoverTargets(reusedDebuggee, true);
+                this.emitTargetCreated(tabId, registeredTarget);
+            }
+            if (this.autoAttachOptions.autoAttach) {
+                await this.applyAutoAttach(reusedDebuggee);
+                this.emitRootAttached(registeredTarget);
+            }
+            this.updatePrimaryTab(tabId);
+            return true;
+        }
+        catch {
+            this.debuggees.delete(tabId);
+            this.rootTargetTabIds.delete(targetInfo.id);
+            if (this.debuggees.size === 0) {
+                this.removeListeners();
+            }
+            return false;
+        }
+    }
+    async attachRootDebuggeeWithFallback(tabId, debuggee) {
+        await this.attachRootDebuggee(debuggee);
+        try {
+            await this.ensureFlatSessionSupport(debuggee);
+            return debuggee;
+        }
+        catch (error) {
+            this.recordRootAttachDiagnostic(tabId, {
+                origin: "flat_session_bootstrap",
+                stage: "flat_session_probe_failed",
+                attachBy: this.resolveRootAttachBy(debuggee),
+                probeMethod: "Target.setAutoAttach",
+                reason: getErrorMessage(error)
+            });
+            const targetAttachDebuggee = this.createTargetAttachRootDebuggee(tabId, debuggee, error);
+            if (!targetAttachDebuggee) {
+                throw error;
+            }
+            this.markExpectedRootDetach(tabId);
+            await this.safeDetach(debuggee);
+            this.debuggees.set(tabId, targetAttachDebuggee);
+            await this.attachRootDebuggee(targetAttachDebuggee);
+            try {
+                await this.ensureFlatSessionSupport(targetAttachDebuggee);
+            }
+            catch (fallbackError) {
+                this.recordRootAttachDiagnostic(tabId, {
+                    origin: "flat_session_bootstrap",
+                    stage: "fallback_flat_session_probe_failed",
+                    attachBy: this.resolveRootAttachBy(targetAttachDebuggee),
+                    probeMethod: "Target.setAutoAttach",
+                    reason: getErrorMessage(fallbackError)
+                });
+                throw fallbackError;
+            }
+            return targetAttachDebuggee;
+        }
+    }
+    async attachRootDebuggee(debuggee) {
+        try {
+            await this.runDebuggerAction((done) => {
+                chrome.debugger.attach(this.toChromeDebuggee(debuggee), "1.3", done);
+            });
+        }
+        catch (error) {
+            if (typeof debuggee.tabId === "number") {
+                this.recordRootAttachDiagnostic(debuggee.tabId, {
+                    origin: "root_attach",
+                    stage: debuggee.attachBy === "targetId"
+                        ? "fallback_root_debugger_attach_failed"
+                        : "root_debugger_attach_failed",
+                    attachBy: this.resolveRootAttachBy(debuggee),
+                    reason: getErrorMessage(error)
+                });
+            }
             throw error;
         }
     }
+    createTargetAttachRootDebuggee(tabId, debuggee, error) {
+        if (!isAttachBlockedError(error)) {
+            return null;
+        }
+        const targetId = typeof debuggee.targetId === "string" && debuggee.targetId.length > 0
+            ? debuggee.targetId
+            : null;
+        if (!targetId || debuggee.attachBy === "targetId") {
+            return null;
+        }
+        return {
+            tabId,
+            targetId,
+            attachBy: "targetId"
+        };
+    }
     async detachAll() {
         const entries = Array.from(this.debuggees.entries());
         this.debuggees.clear();
@@ -145,7 +604,22 @@ export class CDPRouter {
     getAttachedTabIds() {
         return Array.from(this.debuggees.keys());
     }
+    isTabAttached(tabId) {
+        return this.debuggees.has(tabId);
+    }
+    getTabDebuggee(tabId) {
+        return this.sessions.getAttachedRootSession(tabId)?.debuggerSession
+            ?? this.debuggees.get(tabId)
+            ?? (() => {
+                const rootRecord = this.sessions.getByTabId(tabId);
+                if (!rootRecord) {
+                    return null;
+                }
+                return this.sessions.getBySessionId(rootRecord.rootSessionId)?.debuggerSession ?? null;
+            })();
+    }
     async handleCommand(command) {
+        await this.prepareForNextClientIfNeeded();
         if (!this.callbacks)
             return;
         if (this.debuggees.size === 0) {
@@ -179,7 +653,8 @@ export class CDPRouter {
                     this.respondError(command.id, "No tab attached");
                     return;
                 }
-                this.respond(command.id, { sessionId: rootSession.sessionId });
+                const browserSessionId = await this.ensureBrowserSession(rootSession.tabId);
+                this.respond(command.id, { sessionId: browserSessionId ?? rootSession.sessionId });
                 return;
             }
             case "Target.sendMessageToTarget":
@@ -193,9 +668,7 @@ export class CDPRouter {
                 return;
             case "Target.getTargetInfo": {
                 const targetId = typeof commandParams.targetId === "string" ? commandParams.targetId : "";
-                const record = targetId ? this.sessions.getByTargetId(targetId) : null;
-                const targetInfo = record?.targetInfo
-                    ?? (record?.kind === "root" ? this.sessions.getByTabId(record.tabId)?.targetInfo ?? null : null);
+                const targetInfo = this.resolveTargetInfo(targetId, sessionId);
                 this.respond(command.id, { targetInfo });
                 return;
             }
@@ -218,6 +691,9 @@ export class CDPRouter {
                 await handleRoutedCommand(ctx, command.id, method, commandParams, sessionId);
         }
     }
+    markClientClosed() {
+        this.clientResetPending = true;
+    }
     buildCommandContext() {
         return {
             debuggees: this.debuggees,
@@ -232,9 +708,25 @@ export class CDPRouter {
             setDiscoverTargets: (value) => {
                 this.discoverTargets = value;
             },
+            applyDiscoverTargets: this.applyDiscoverTargets.bind(this),
             respond: this.respond.bind(this),
             respondError: this.respondError.bind(this),
-            emitTargetCreated: this.emitTargetCreated.bind(this),
+            emitEvent: (method, params, sessionId) => {
+                const tabId = sessionId
+                    ? this.sessions.getBySessionId(sessionId)?.tabId ?? this.primaryTabId
+                    : this.primaryTabId;
+                if (typeof tabId === "number") {
+                    this.emitEvent(tabId, method, params, sessionId);
+                }
+            },
+            emitTargetCreated: (targetInfo) => {
+                const tabId = this.sessions.getByTargetId(targetInfo.targetId)?.tabId
+                    ?? this.rootTargetTabIds.get(targetInfo.targetId)
+                    ?? this.primaryTabId;
+                if (typeof tabId === "number") {
+                    this.emitTargetCreated(tabId, targetInfo);
+                }
+            },
             emitRootAttached: this.emitRootAttached.bind(this),
             emitRootDetached: this.emitRootDetached.bind(this),
             resetRootAttached: this.resetRootAttached.bind(this),
@@ -243,18 +735,137 @@ export class CDPRouter {
             safeDetach: this.safeDetach.bind(this),
             attach: this.attach.bind(this),
             registerRootTab: this.registerRootTab.bind(this),
+            refreshRootTargetInfo: this.refreshRootTargetInfo.bind(this),
             applyAutoAttach: this.applyAutoAttach.bind(this),
             sendCommand: this.sendCommand.bind(this),
-            getPrimaryDebuggee: this.getPrimaryDebuggee.bind(this)
+            getPrimaryDebuggee: this.getPrimaryDebuggee.bind(this),
+            resolveCommandDebuggee: this.resolveCommandDebuggee.bind(this)
         };
     }
     async registerRootTab(tabId) {
         const existing = this.sessions.getByTabId(tabId);
         const sessionId = existing?.rootSessionId ?? this.createRootSessionId();
         const targetInfo = await this.buildTargetInfo(tabId);
-        this.sessions.registerRootTab(tabId, targetInfo, sessionId);
+        const debuggerSession = await this.resolveRootSessionDebuggee(tabId);
+        this.sessions.registerRootTab(tabId, targetInfo, sessionId, debuggerSession.targetId, debuggerSession);
         return targetInfo;
     }
+    async refreshRootTargetInfo(tabId) {
+        const existing = this.sessions.getByTabId(tabId);
+        const sessionId = existing?.rootSessionId ?? this.createRootSessionId();
+        const targetInfo = await this.buildTargetInfo(tabId);
+        const debuggerSession = await this.resolveRootSessionDebuggee(tabId);
+        const rootFrame = await this.readRootFrameInfo(tabId);
+        const refreshed = rootFrame
+            ? {
+                ...targetInfo,
+                targetId: rootFrame.id,
+                ...(rootFrame.url ? { url: rootFrame.url } : {})
+            }
+            : targetInfo;
+        this.sessions.registerRootTab(tabId, refreshed, sessionId, debuggerSession.targetId, debuggerSession);
+        return refreshed;
+    }
+    async prepareForNextClientIfNeeded(preferredTabIdHint) {
+        if (!this.clientResetPending) {
+            return null;
+        }
+        const preferredTabId = await this.resolvePreferredResetTabId(preferredTabIdHint);
+        const retainedPreferredRootTargetId = preferredTabId !== null
+            ? this.resolveRetainedRootTargetId(preferredTabId)
+            : null;
+        this.clientResetPending = false;
+        this.autoAttachOptions = { autoAttach: false, waitForDebuggerOnStart: false, flatten: true };
+        this.discoverTargets = false;
+        this.rootAttachedSessions.clear();
+        this.pendingTargetTabIds.clear();
+        this.quarantinedSessions.clear();
+        this.churnTracker.clear();
+        this.sessions.reset();
+        for (const [tabId, debuggee] of Array.from(this.debuggees.entries())) {
+            if (preferredTabId !== null && tabId === preferredTabId) {
+                continue;
+            }
+            this.debuggees.delete(tabId);
+            await this.safeDetach(debuggee);
+        }
+        if (preferredTabId === null) {
+            this.primaryTabId = null;
+            this.lastActiveTabId = null;
+            if (this.debuggees.size === 0) {
+                this.removeListeners();
+            }
+            return null;
+        }
+        const attachedPrimary = this.debuggees.get(preferredTabId);
+        if (attachedPrimary) {
+            this.updatePrimaryTab(preferredTabId);
+            // After a client reset, a preserved root tab is only a candidate anchor.
+            // Rebuild the real root attachment before any same-tab reuse is considered healthy.
+            await this.reattachRootDebuggee(preferredTabId, true);
+            const refreshedRoot = this.sessions.getByTabId(preferredTabId);
+            if (retainedPreferredRootTargetId && !refreshedRoot?.attachTargetId) {
+                this.sessions.setRootAttachTargetId(preferredTabId, retainedPreferredRootTargetId);
+                const refreshedDebuggee = this.debuggees.get(preferredTabId);
+                if (refreshedDebuggee && !refreshedDebuggee.targetId) {
+                    refreshedDebuggee.targetId = retainedPreferredRootTargetId;
+                }
+                const refreshedRootSession = refreshedRoot
+                    ? this.sessions.getBySessionId(refreshedRoot.rootSessionId)
+                    : null;
+                if (refreshedRootSession?.debuggerSession && !refreshedRootSession.debuggerSession.targetId) {
+                    refreshedRootSession.debuggerSession.targetId = retainedPreferredRootTargetId;
+                }
+            }
+            return preferredTabId;
+        }
+        await this.attachInternal(preferredTabId, true);
+        return preferredTabId;
+    }
+    async resolvePreferredResetTabId(preferredTabIdHint) {
+        const candidateTabIds = [];
+        const pushCandidate = (tabId) => {
+            if (typeof tabId === "number" && !candidateTabIds.includes(tabId)) {
+                candidateTabIds.push(tabId);
+            }
+        };
+        pushCandidate(preferredTabIdHint ?? null);
+        pushCandidate(await this.tabManager.getActiveTabId());
+        pushCandidate(this.lastActiveTabId);
+        pushCandidate(this.primaryTabId);
+        for (const tabId of candidateTabIds) {
+            if (await this.isUsableResetTab(tabId)) {
+                return tabId;
+            }
+        }
+        const firstHttpTabId = await this.tabManager.getFirstHttpTabId();
+        if (firstHttpTabId !== null) {
+            return firstHttpTabId;
+        }
+        for (const tabId of candidateTabIds) {
+            if (this.debuggees.has(tabId)) {
+                return tabId;
+            }
+            const tab = await this.tabManager.getTab(tabId);
+            if (tab) {
+                return tabId;
+            }
+        }
+        const [firstAttachedTabId] = this.debuggees.keys();
+        return typeof firstAttachedTabId === "number" ? firstAttachedTabId : null;
+    }
+    async isUsableResetTab(tabId) {
+        const tab = await this.tabManager.getTab(tabId);
+        if (!tab?.url) {
+            return false;
+        }
+        try {
+            return getRestrictionMessage(new URL(tab.url)) === null;
+        }
+        catch {
+            return false;
+        }
+    }
     updatePrimaryTab(tabId) {
         if (tabId === this.primaryTabId)
             return;
@@ -264,6 +875,50 @@ export class CDPRouter {
         }
         this.callbacks?.onPrimaryTabChange?.(tabId);
     }
+    async pruneRootDebuggees(primaryTabId) {
+        const displacedRoots = await this.detachConflictingRootDebuggees(primaryTabId);
+        this.commitDetachedRootDebuggees(displacedRoots);
+    }
+    async detachConflictingRootDebuggees(nextTabId) {
+        const staleTabIds = Array.from(this.debuggees.keys()).filter((tabId) => tabId !== nextTabId);
+        const displacedRoots = [];
+        for (const staleTabId of staleTabIds) {
+            const debuggee = this.debuggees.get(staleTabId);
+            if (!debuggee) {
+                continue;
+            }
+            this.debuggees.delete(staleTabId);
+            this.markExpectedRootDetach(staleTabId);
+            await this.safeDetach(debuggee);
+            displacedRoots.push({ tabId: staleTabId });
+        }
+        return displacedRoots;
+    }
+    commitDetachedRootDebuggees(detachedRoots) {
+        for (const { tabId } of detachedRoots) {
+            if (this.debuggees.has(tabId)) {
+                continue;
+            }
+            this.detachTabState(tabId);
+        }
+    }
+    async restoreDetachedRootDebuggees(detachedRoots) {
+        for (const { tabId } of detachedRoots) {
+            if (this.debuggees.has(tabId)) {
+                return;
+            }
+            try {
+                await this.attachInternal(tabId, false);
+                return;
+            }
+            catch (error) {
+                logError("cdp.restore_root_attach", error, {
+                    code: "restore_root_attach_failed",
+                    extra: { tabId }
+                });
+            }
+        }
+    }
     selectFallbackPrimary() {
         if (this.lastActiveTabId && this.debuggees.has(this.lastActiveTabId)) {
             return this.lastActiveTabId;
@@ -272,27 +927,467 @@ export class CDPRouter {
         return first ?? null;
     }
     getPrimaryDebuggee() {
-        if (this.primaryTabId !== null && this.debuggees.has(this.primaryTabId)) {
-            return { tabId: this.primaryTabId };
+        if (this.primaryTabId !== null) {
+            const primary = this.debuggees.get(this.primaryTabId);
+            if (primary) {
+                return primary;
+            }
         }
-        const [first] = this.debuggees.keys();
-        return typeof first === "number" ? { tabId: first } : null;
+        const [first] = this.debuggees.values();
+        return first ?? null;
+    }
+    async resolveCommandDebuggee(sessionId) {
+        if (!sessionId) {
+            return this.getPrimaryDebuggee();
+        }
+        const session = this.sessions.getBySessionId(sessionId);
+        if (!session) {
+            return null;
+        }
+        if (session.kind !== "root") {
+            return session.debuggerSession;
+        }
+        if (typeof session.debuggerSession.targetId === "string" && session.debuggerSession.targetId.length > 0) {
+            return session.debuggerSession;
+        }
+        const attached = await this.ensureAttachedRootSession(session.tabId);
+        return attached ?? session.debuggerSession;
     }
     async ensureRootSessionForPrimary() {
-        const debuggee = this.getPrimaryDebuggee();
-        if (!debuggee || typeof debuggee.tabId !== "number") {
+        const tabId = this.primaryTabId ?? this.resolveSourceTabId(this.getPrimaryDebuggee() ?? {});
+        if (typeof tabId !== "number") {
             return null;
         }
-        const existing = this.sessions.getByTabId(debuggee.tabId);
+        const existing = this.sessions.getByTabId(tabId);
         if (existing) {
-            return { sessionId: existing.rootSessionId, targetInfo: existing.targetInfo };
+            return { tabId, sessionId: existing.rootSessionId, targetInfo: existing.targetInfo };
         }
-        const targetInfo = await this.registerRootTab(debuggee.tabId);
-        const refreshed = this.sessions.getByTabId(debuggee.tabId);
+        const targetInfo = await this.registerRootTab(tabId);
+        const refreshed = this.sessions.getByTabId(tabId);
         if (!refreshed) {
             return null;
         }
-        return { sessionId: refreshed.rootSessionId, targetInfo: targetInfo ?? refreshed.targetInfo };
+        return { tabId, sessionId: refreshed.rootSessionId, targetInfo: targetInfo ?? refreshed.targetInfo };
+    }
+    async ensureAttachedRootSession(tabId) {
+        return (await this.ensureAttachedRootSessionWithDiagnostic(tabId)).debuggerSession;
+    }
+    async ensureAttachedRootSessionWithDiagnostic(tabId) {
+        const existing = this.sessions.getAttachedRootSession(tabId);
+        if (existing) {
+            return {
+                debuggerSession: existing.debuggerSession,
+                stage: "attached",
+                registerAttachedRootSessionCalled: false
+            };
+        }
+        const record = this.sessions.getByTabId(tabId);
+        if (!record) {
+            return {
+                debuggerSession: null,
+                stage: "record_missing",
+                registerAttachedRootSessionCalled: false
+            };
+        }
+        const recordAttachTargetId = typeof record.attachTargetId === "string" && record.attachTargetId.length > 0
+            ? record.attachTargetId
+            : null;
+        const retainedAttachTargetId = recordAttachTargetId ?? this.resolveRetainedRootTargetId(tabId);
+        const liveAttachTargetId = await this.readDebuggerTargetId(tabId);
+        const attachTargetId = recordAttachTargetId ?? liveAttachTargetId ?? retainedAttachTargetId;
+        const attachTargetSource = recordAttachTargetId
+            ? "record"
+            : liveAttachTargetId
+                ? "debugger"
+                : retainedAttachTargetId
+                    ? "debuggee"
+                    : undefined;
+        if (!attachTargetId) {
+            return {
+                debuggerSession: null,
+                stage: "session_missing",
+                registerAttachedRootSessionCalled: false,
+                reason: "attach_target_id_unavailable"
+            };
+        }
+        if (recordAttachTargetId !== attachTargetId) {
+            this.sessions.setRootAttachTargetId(tabId, attachTargetId);
+        }
+        const attachRootSession = async (debuggee) => {
+            try {
+                const attached = await this.sendCommandOnce(debuggee, "Target.attachToTarget", {
+                    targetId: attachTargetId,
+                    flatten: true
+                });
+                const sessionRecord = isRecord(attached) ? attached : {};
+                return {
+                    sessionId: typeof sessionRecord.sessionId === "string" ? sessionRecord.sessionId : null
+                };
+            }
+            catch (error) {
+                return {
+                    sessionId: null,
+                    error
+                };
+            }
+        };
+        const initialAttachDebuggee = liveAttachTargetId
+            ? { tabId }
+            : { targetId: attachTargetId, attachBy: "targetId" };
+        let attachAttempt = await attachRootSession(initialAttachDebuggee);
+        if (typeof initialAttachDebuggee.tabId === "number"
+            && !attachAttempt.sessionId
+            && (!attachAttempt.error
+                || isAttachBlockedError(attachAttempt.error)
+                || this.isStaleTabError(attachAttempt.error))) {
+            const initialFailure = attachAttempt;
+            const retriedAttachAttempt = await attachRootSession({ targetId: attachTargetId, attachBy: "targetId" });
+            attachAttempt = retriedAttachAttempt.sessionId
+                || retriedAttachAttempt.error
+                || !initialFailure.error
+                ? retriedAttachAttempt
+                : initialFailure;
+        }
+        try {
+            const attachedSessionId = attachAttempt.sessionId;
+            if (!attachedSessionId) {
+                if (attachAttempt.error) {
+                    throw attachAttempt.error;
+                }
+                return {
+                    debuggerSession: null,
+                    stage: "attach_null",
+                    ...(attachTargetSource ? { attachTargetSource } : {}),
+                    attachTargetId,
+                    registerAttachedRootSessionCalled: false
+                };
+            }
+            const attachedRecord = this.sessions.registerAttachedRootSession(tabId, attachedSessionId);
+            if (attachedRecord?.debuggerSession) {
+                attachedRecord.debuggerSession.targetId = attachTargetId;
+            }
+            return {
+                debuggerSession: attachedRecord?.debuggerSession ?? {
+                    tabId,
+                    sessionId: attachedSessionId,
+                    targetId: attachTargetId
+                },
+                stage: "attached",
+                ...(attachTargetSource ? { attachTargetSource } : {}),
+                attachTargetId,
+                registerAttachedRootSessionCalled: true
+            };
+        }
+        catch (error) {
+            return {
+                debuggerSession: null,
+                stage: "attach_failed",
+                ...(attachTargetSource ? { attachTargetSource } : {}),
+                attachTargetId,
+                registerAttachedRootSessionCalled: false,
+                reason: getErrorMessage(error)
+            };
+        }
+    }
+    async resolveRootSessionDebuggee(tabId) {
+        await this.syncLiveRootTargetId(tabId);
+        const attachedDebuggee = this.debuggees.get(tabId);
+        if (attachedDebuggee?.targetId) {
+            return attachedDebuggee;
+        }
+        const attachedRootSession = this.sessions.getAttachedRootSession(tabId);
+        if (attachedRootSession?.debuggerSession) {
+            return attachedRootSession.debuggerSession;
+        }
+        const existing = this.sessions.getByTabId(tabId);
+        const existingSession = existing ? this.sessions.getBySessionId(existing.rootSessionId) : null;
+        if (existingSession?.debuggerSession?.targetId) {
+            return existingSession.debuggerSession;
+        }
+        return await this.resolveRootDebuggee(tabId);
+    }
+    async syncLiveRootTargetId(tabId) {
+        const liveTargetId = await this.readDebuggerTargetId(tabId);
+        if (!liveTargetId) {
+            return;
+        }
+        const staleTargetIds = new Set();
+        const attachedDebuggee = this.debuggees.get(tabId);
+        if (typeof attachedDebuggee?.targetId === "string" && attachedDebuggee.targetId.length > 0) {
+            staleTargetIds.add(attachedDebuggee.targetId);
+        }
+        const rootRecord = this.sessions.getByTabId(tabId);
+        if (typeof rootRecord?.targetInfo.targetId === "string" && rootRecord.targetInfo.targetId.length > 0) {
+            staleTargetIds.add(rootRecord.targetInfo.targetId);
+        }
+        if (typeof rootRecord?.attachTargetId === "string" && rootRecord.attachTargetId.length > 0) {
+            staleTargetIds.add(rootRecord.attachTargetId);
+        }
+        for (const targetId of staleTargetIds) {
+            if (targetId !== liveTargetId && this.rootTargetTabIds.get(targetId) === tabId) {
+                this.rootTargetTabIds.delete(targetId);
+            }
+        }
+        this.rootTargetTabIds.set(liveTargetId, tabId);
+        this.sessions.setRootAttachTargetId(tabId, liveTargetId);
+        if (attachedDebuggee) {
+            attachedDebuggee.targetId = liveTargetId;
+        }
+        const rootSession = rootRecord
+            ? this.sessions.getBySessionId(rootRecord.rootSessionId)
+            : null;
+        if (rootSession?.debuggerSession) {
+            rootSession.debuggerSession.targetId = liveTargetId;
+        }
+        const attachedRootSession = this.sessions.getAttachedRootSession(tabId);
+        if (attachedRootSession?.debuggerSession) {
+            attachedRootSession.debuggerSession.targetId = liveTargetId;
+        }
+    }
+    async resolveRootDebuggee(tabId) {
+        const attachTargetId = await this.readDebuggerTargetId(tabId);
+        if (attachTargetId) {
+            this.rootTargetTabIds.set(attachTargetId, tabId);
+            return { tabId, targetId: attachTargetId };
+        }
+        return { tabId };
+    }
+    async attachChildTargetWithDebuggee(debuggee, targetId) {
+        const result = await this.sendCommandOnce(debuggee, "Target.attachToTarget", { targetId, flatten: true });
+        const record = isRecord(result) ? result : {};
+        const childSessionId = typeof record.sessionId === "string" ? record.sessionId : null;
+        if (!childSessionId || typeof debuggee.tabId !== "number") {
+            return childSessionId;
+        }
+        const targetInfo = this.resolveTargetInfo(targetId) ?? {
+            targetId,
+            type: "page",
+            browserContextId: DEFAULT_BROWSER_CONTEXT_ID
+        };
+        this.sessions.registerChildSession(debuggee.tabId, targetInfo, childSessionId);
+        return childSessionId;
+    }
+    async attachChildTargetWithRootTargetId(debuggee, targetId, priorError) {
+        if (typeof debuggee.sessionId === "string" || typeof debuggee.tabId !== "number") {
+            return {
+                sessionId: null,
+                stage: "missing_root_target_id"
+            };
+        }
+        const rootTargetId = typeof debuggee.targetId === "string" && debuggee.targetId.length > 0
+            ? debuggee.targetId
+            : null;
+        if (!rootTargetId) {
+            return {
+                sessionId: null,
+                stage: "missing_root_target_id"
+            };
+        }
+        try {
+            const result = await this.sendCommandOnce({ targetId: rootTargetId }, "Target.attachToTarget", {
+                targetId,
+                flatten: true
+            });
+            const record = isRecord(result) ? result : {};
+            const childSessionId = typeof record.sessionId === "string" ? record.sessionId : null;
+            if (!childSessionId) {
+                return {
+                    sessionId: null,
+                    stage: "attach_null"
+                };
+            }
+            const targetInfo = this.resolveTargetInfo(targetId) ?? {
+                targetId,
+                type: "page",
+                browserContextId: DEFAULT_BROWSER_CONTEXT_ID
+            };
+            this.sessions.registerChildSession(debuggee.tabId, targetInfo, childSessionId);
+            return {
+                sessionId: childSessionId,
+                stage: "attached"
+            };
+        }
+        catch (error) {
+            if (priorError && isAttachBlockedError(priorError) && isAttachBlockedError(error)) {
+                return {
+                    sessionId: null,
+                    stage: "attach_blocked",
+                    reason: getErrorMessage(error)
+                };
+            }
+            if (priorError && this.isStaleTabError(priorError) && this.isStaleTabError(error)) {
+                return {
+                    sessionId: null,
+                    stage: "attach_blocked",
+                    reason: getErrorMessage(error)
+                };
+            }
+            throw error;
+        }
+    }
+    async reattachRootAndAttachChildTarget(tabId, targetId) {
+        let result = { sessionId: null };
+        try {
+            let tabScopedRootDebuggee;
+            try {
+                tabScopedRootDebuggee = await this.reattachTabScopedRootDebuggeeForPopup(tabId);
+            }
+            catch (error) {
+                result = {
+                    sessionId: null,
+                    terminalBranch: "tab_scoped_root_reattach",
+                    stage: "tab_scoped_root_reattach_failed",
+                    reason: getErrorMessage(error)
+                };
+                return result;
+            }
+            try {
+                const tabScopedSessionId = await this.attachChildTargetWithDebuggee(tabScopedRootDebuggee, targetId);
+                if (tabScopedSessionId) {
+                    result = { sessionId: tabScopedSessionId };
+                    return result;
+                }
+            }
+            catch (tabScopedError) {
+                if (!isAttachBlockedError(tabScopedError) && !this.isStaleTabError(tabScopedError)) {
+                    result = {
+                        sessionId: null,
+                        terminalBranch: "tab_scoped_root_reattach",
+                        stage: "tab_scoped_attach_failed",
+                        reason: getErrorMessage(tabScopedError)
+                    };
+                    return result;
+                }
+            }
+            try {
+                await this.reattachRootDebuggee(tabId);
+                const rootDebuggee = await this.resolveRootSessionDebuggee(tabId);
+                const rootSessionId = await this.attachChildTargetWithDebuggee(rootDebuggee, targetId);
+                result = rootSessionId
+                    ? { sessionId: rootSessionId }
+                    : {
+                        sessionId: null,
+                        terminalBranch: "root_debuggee_reattach",
+                        stage: "root_debuggee_attach_null"
+                    };
+            }
+            catch (error) {
+                const blocked = isAttachBlockedError(error) || this.isStaleTabError(error);
+                result = {
+                    sessionId: null,
+                    terminalBranch: "root_debuggee_reattach",
+                    stage: blocked ? "root_debuggee_attach_blocked" : "root_debuggee_attach_failed",
+                    reason: getErrorMessage(error)
+                };
+            }
+            return result;
+        }
+        catch (error) {
+            result = {
+                sessionId: null,
+                terminalBranch: "root_debuggee_reattach",
+                stage: "root_debuggee_reattach_failed",
+                reason: getErrorMessage(error)
+            };
+            return result;
+        }
+        finally {
+            if (!result.sessionId) {
+                await this.restoreRootAfterChildAttachFailure(tabId);
+            }
+        }
+    }
+    async reattachTabScopedRootDebuggeeForPopup(tabId) {
+        const existing = this.debuggees.get(tabId);
+        this.debuggees.delete(tabId);
+        this.detachTabState(tabId);
+        if (existing) {
+            this.markExpectedRootDetach(tabId);
+            await this.safeDetach(existing);
+        }
+        this.ensureListeners();
+        const resolvedRootDebuggee = await this.resolveRootDebuggee(tabId);
+        const tabScopedDebuggee = typeof resolvedRootDebuggee.targetId === "string" && resolvedRootDebuggee.targetId.length > 0
+            ? { tabId, targetId: resolvedRootDebuggee.targetId }
+            : { tabId };
+        await this.attachRootDebuggee(tabScopedDebuggee);
+        this.debuggees.set(tabId, tabScopedDebuggee);
+        await this.registerRootTab(tabId);
+        this.updatePrimaryTab(tabId);
+        return await this.resolveRootSessionDebuggee(tabId);
+    }
+    async restoreRootAfterChildAttachFailure(tabId) {
+        try {
+            await this.refreshTabAttachment(tabId);
+        }
+        catch {
+            // Best-effort root restoration only. The original popup attach error remains authoritative.
+        }
+    }
+    async reattachRootDebuggee(tabId, allowRetry = false) {
+        const existing = this.debuggees.get(tabId);
+        this.debuggees.delete(tabId);
+        this.detachTabState(tabId);
+        if (existing) {
+            this.markExpectedRootDetach(tabId);
+            await this.safeDetach(existing);
+        }
+        await this.attachInternal(tabId, allowRetry);
+    }
+    async readDebuggerPageTargets(tabId) {
+        const tab = await this.tabManager.getTab(tabId);
+        const targets = await new Promise((resolve) => {
+            chrome.debugger.getTargets((records) => {
+                const lastError = chrome.runtime.lastError;
+                if (lastError || !Array.isArray(records)) {
+                    resolve([]);
+                    return;
+                }
+                resolve(records);
+            });
+        });
+        const pageTargets = targets.filter((target) => target.tabId === tabId && target.type === "page");
+        return { tab: tab ?? null, pageTargets };
+    }
+    selectPreferredDebuggerTargetInfo(tab, pageTargets) {
+        if (pageTargets.length === 0) {
+            return null;
+        }
+        const liveTargets = pageTargets.some((target) => target.attached)
+            ? pageTargets.filter((target) => target.attached)
+            : pageTargets;
+        const preferredByUrl = typeof tab?.url === "string"
+            ? liveTargets.find((target) => target.url === tab.url)
+            : null;
+        const preferredByTitle = typeof tab?.title === "string"
+            ? liveTargets.find((target) => target.title === tab.title)
+            : null;
+        return preferredByUrl ?? preferredByTitle ?? liveTargets[0] ?? null;
+    }
+    async readDebuggerTargetInfo(tabId) {
+        const { tab, pageTargets } = await this.readDebuggerPageTargets(tabId);
+        return this.selectPreferredDebuggerTargetInfo(tab, pageTargets);
+    }
+    async readDebuggerTargetId(tabId) {
+        return (await this.readDebuggerTargetInfo(tabId))?.id ?? null;
+    }
+    resolveTargetInfo(targetId, sessionId) {
+        if (targetId) {
+            const record = this.sessions.getByTargetId(targetId);
+            return record?.targetInfo
+                ?? (record?.kind === "root" ? this.sessions.getByTabId(record.tabId)?.targetInfo ?? null : null);
+        }
+        if (sessionId) {
+            const session = this.sessions.getBySessionId(sessionId);
+            return session?.targetInfo
+                ?? (session?.kind === "root" ? this.sessions.getByTabId(session.tabId)?.targetInfo ?? null : null);
+        }
+        return {
+            targetId: DEFAULT_BROWSER_TARGET_ID,
+            type: "browser",
+            title: "OpenDevBrowser Relay",
+            url: ""
+        };
     }
     ensureListeners() {
         if (this.listenersActive)
@@ -316,7 +1411,7 @@ export class CDPRouter {
                 autoAttach: false,
                 waitForDebuggerOnStart: false,
                 flatten: true
-            });
+            }, { preserveTab: true, refreshPreparedDebuggee: false });
             this.flatSessionValidated = true;
         }
         catch (error) {
@@ -325,7 +1420,12 @@ export class CDPRouter {
             throw new Error(`${FLAT_SESSION_ERROR} (${detail})`);
         }
     }
+    async applyDiscoverTargets(debuggee, discover) {
+        const rootTrackingDebuggee = this.resolveRootTrackingDebuggee(debuggee);
+        await this.sendCommand(rootTrackingDebuggee, "Target.setDiscoverTargets", { discover }, { preserveTab: true, refreshPreparedDebuggee: false });
+    }
     async applyAutoAttach(debuggee) {
+        const rootTrackingDebuggee = this.resolveRootTrackingDebuggee(debuggee);
         const params = {
             autoAttach: this.autoAttachOptions.autoAttach,
             waitForDebuggerOnStart: this.autoAttachOptions.waitForDebuggerOnStart,
@@ -335,7 +1435,7 @@ export class CDPRouter {
             params.filter = this.autoAttachOptions.filter;
         }
         try {
-            await this.sendCommand(debuggee, "Target.setAutoAttach", params);
+            await this.sendCommand(rootTrackingDebuggee, "Target.setAutoAttach", params, { preserveTab: true, refreshPreparedDebuggee: false });
         }
         catch (error) {
             const detail = getErrorMessage(error);
@@ -343,6 +1443,24 @@ export class CDPRouter {
             throw new Error(`${FLAT_SESSION_ERROR} (${detail})`);
         }
     }
+    resolveRootTrackingDebuggee(debuggee) {
+        const rootDebuggee = typeof debuggee.tabId === "number"
+            ? this.debuggees.get(debuggee.tabId) ?? debuggee
+            : debuggee;
+        if (rootDebuggee.attachBy === "targetId"
+            && typeof rootDebuggee.targetId === "string"
+            && rootDebuggee.targetId.length > 0) {
+            return {
+                ...(typeof rootDebuggee.tabId === "number" ? { tabId: rootDebuggee.tabId } : {}),
+                targetId: rootDebuggee.targetId,
+                attachBy: "targetId"
+            };
+        }
+        if (typeof rootDebuggee.sessionId === "string" && typeof rootDebuggee.tabId === "number") {
+            return { tabId: rootDebuggee.tabId };
+        }
+        return rootDebuggee;
+    }
     async applyAutoAttachToChild(tabId, sessionId) {
         if (!this.autoAttachOptions.autoAttach)
             return;
@@ -403,16 +1521,29 @@ export class CDPRouter {
     handleEvent(source, method, params) {
         if (!this.callbacks)
             return;
-        const tabId = typeof source.tabId === "number" ? source.tabId : null;
+        const tabId = this.resolveEventTabId(source, params);
         if (tabId === null || !this.debuggees.has(tabId))
             return;
         if (method === "Target.receivedMessageFromTarget")
             return;
+        if (method === "Target.targetCreated" && params && isRecord(params)) {
+            const targetInfo = isTargetInfo(params.targetInfo) ? params.targetInfo : null;
+            if (targetInfo) {
+                this.pendingTargetTabIds.set(targetInfo.targetId, tabId);
+            }
+        }
         if (method === "Target.attachedToTarget" && params && isRecord(params)) {
             const sessionId = typeof params.sessionId === "string" ? params.sessionId : null;
             const targetInfo = isTargetInfo(params.targetInfo) ? params.targetInfo : null;
             if (sessionId && targetInfo) {
-                this.sessions.registerChildSession(tabId, targetInfo, sessionId);
+                this.pendingTargetTabIds.delete(targetInfo.targetId);
+                if (this.isAttachedRootTarget(tabId, targetInfo)) {
+                    this.sessions.setRootAttachTargetId(tabId, targetInfo.targetId);
+                    this.sessions.registerAttachedRootSession(tabId, sessionId);
+                }
+                else {
+                    this.sessions.registerChildSession(tabId, targetInfo, sessionId);
+                }
                 this.quarantinedSessions.delete(sessionId);
                 this.applyAutoAttachToChild(tabId, sessionId).catch((error) => {
                     logError("cdp.apply_auto_attach_child", error, { code: "auto_attach_failed" });
@@ -424,6 +1555,10 @@ export class CDPRouter {
         }
         if (method === "Target.detachedFromTarget" && params && isRecord(params)) {
             const detachedSessionId = typeof params.sessionId === "string" ? params.sessionId : null;
+            const detachedTargetId = typeof params.targetId === "string" ? params.targetId : null;
+            if (detachedTargetId) {
+                this.pendingTargetTabIds.delete(detachedTargetId);
+            }
             if (detachedSessionId) {
                 const removed = this.sessions.removeBySessionId(detachedSessionId);
                 if (!removed) {
@@ -433,16 +1568,26 @@ export class CDPRouter {
                 }
             }
         }
+        if (method === "Target.targetDestroyed" && params && isRecord(params)) {
+            const targetId = typeof params.targetId === "string" ? params.targetId : null;
+            if (targetId) {
+                this.pendingTargetTabIds.delete(targetId);
+            }
+        }
         const sourceSessionId = source.sessionId;
-        if (typeof sourceSessionId === "string" && !this.sessions.hasSession(sourceSessionId)) {
+        if (typeof sourceSessionId === "string"
+            && !this.sessions.hasSession(sourceSessionId)
+            && !this.shouldAllowUnknownSourceSession(method, source, tabId)) {
             this.quarantineUnknownSession(tabId, sourceSessionId, method);
             return;
         }
         const forwardSessionId = this.resolveForwardSessionId(method, source);
-        this.emitEvent(method, params, forwardSessionId);
+        this.emitEvent(tabId, method, params, forwardSessionId);
     }
     handleDetach(source, reason) {
-        const tabId = typeof source.tabId === "number" ? source.tabId : null;
+        if (this.consumeExpectedRootDetach(source))
+            return;
+        const tabId = this.resolveSourceTabId(source);
         if (tabId === null || !this.debuggees.has(tabId))
             return;
         this.debuggees.delete(tabId);
@@ -453,14 +1598,29 @@ export class CDPRouter {
         }
     }
     detachTabState(tabId) {
+        this.expectedRootDetachDeadlines.delete(tabId);
+        this.clearRootAttachDiagnostic(tabId);
         const record = this.sessions.removeByTabId(tabId);
+        for (const [key, diagnostic] of this.childAttachDiagnostics.entries()) {
+            if (diagnostic.tabId === tabId) {
+                this.childAttachDiagnostics.delete(key);
+            }
+        }
+        for (const [targetId, mappedTabId] of this.pendingTargetTabIds.entries()) {
+            if (mappedTabId === tabId) {
+                this.pendingTargetTabIds.delete(targetId);
+            }
+        }
         if (record) {
+            if (record.attachTargetId) {
+                this.rootTargetTabIds.delete(record.attachTargetId);
+            }
             this.rootAttachedSessions.delete(record.rootSessionId);
             if (this.autoAttachOptions.autoAttach) {
-                this.emitTargetDetached(record.rootSessionId, record.targetInfo.targetId);
+                this.emitTargetDetached(record.tabId, record.rootSessionId, record.targetInfo.targetId);
             }
             if (this.discoverTargets) {
-                this.emitTargetDestroyed(record.targetInfo.targetId);
+                this.emitTargetDestroyed(record.tabId, record.targetInfo.targetId);
             }
         }
         if (tabId === this.primaryTabId) {
@@ -476,14 +1636,186 @@ export class CDPRouter {
         if (typeof sessionId === "string") {
             return this.sessions.getBySessionId(sessionId) ? sessionId : undefined;
         }
-        const tabId = typeof source.tabId === "number" ? source.tabId : null;
+        const tabId = this.resolveSourceTabId(source);
         if (tabId === null)
             return undefined;
         const record = this.sessions.getByTabId(tabId);
         if (!record)
             return undefined;
+        const browserSession = this.sessions.getBrowserSession(tabId);
+        if (browserSession) {
+            return browserSession.sessionId;
+        }
         return this.rootAttachedSessions.has(record.rootSessionId) ? record.rootSessionId : undefined;
     }
+    resolveEventTabId(source, params) {
+        const sourceTabId = this.resolveSourceTabId(source);
+        if (sourceTabId !== null) {
+            return sourceTabId;
+        }
+        if (!params || !isRecord(params)) {
+            return null;
+        }
+        const targetInfo = isTargetInfo(params.targetInfo) ? params.targetInfo : null;
+        const openerTabId = this.resolveLinkedTargetTabId(targetInfo?.openerId);
+        if (openerTabId !== null) {
+            if (targetInfo) {
+                this.pendingTargetTabIds.set(targetInfo.targetId, openerTabId);
+            }
+            return openerTabId;
+        }
+        if (targetInfo) {
+            const targetTabId = this.resolveLinkedTargetTabId(targetInfo.targetId);
+            if (targetTabId !== null) {
+                return targetTabId;
+            }
+        }
+        const targetId = typeof params.targetId === "string" ? params.targetId : null;
+        if (targetId) {
+            return this.resolveLinkedTargetTabId(targetId);
+        }
+        const sessionId = typeof params.sessionId === "string" ? params.sessionId : null;
+        if (sessionId) {
+            return this.sessions.getBySessionId(sessionId)?.tabId ?? null;
+        }
+        return null;
+    }
+    resolveSourceTabId(source) {
+        if (typeof source.tabId === "number") {
+            return source.tabId;
+        }
+        const sourceSessionId = source.sessionId;
+        if (typeof sourceSessionId === "string") {
+            const knownTabId = this.sessions.getBySessionId(sourceSessionId)?.tabId
+                ?? this.quarantinedSessions.get(sourceSessionId)?.tabId
+                ?? null;
+            if (typeof knownTabId === "number") {
+                return knownTabId;
+            }
+            if (this.debuggees.size === 1) {
+                const nextAttachedTab = this.debuggees.keys().next();
+                return nextAttachedTab.done ? null : nextAttachedTab.value;
+            }
+            return null;
+        }
+        if (typeof source.targetId === "string") {
+            return this.resolveLinkedTargetTabId(source.targetId);
+        }
+        return null;
+    }
+    shouldAllowUnknownSourceSession(method, source, tabId) {
+        if (method !== "Page.javascriptDialogOpening"
+            && method !== "Page.javascriptDialogClosed"
+            && method !== "Page.fileChooserOpened") {
+            return false;
+        }
+        if (typeof source.tabId === "number") {
+            return source.tabId === tabId;
+        }
+        if (typeof source.targetId === "string") {
+            return this.resolveLinkedTargetTabId(source.targetId) === tabId;
+        }
+        if (typeof source.sessionId === "string") {
+            return this.resolveSourceTabId(source) === tabId;
+        }
+        return false;
+    }
+    resolveLinkedTargetTabId(targetId) {
+        if (typeof targetId !== "string" || targetId.length === 0) {
+            return null;
+        }
+        return parseTabTargetAlias(targetId)
+            ?? this.rootTargetTabIds.get(targetId)
+            ?? this.sessions.getByTargetId(targetId)?.tabId
+            ?? this.sessions.getTabIdByTargetAlias(targetId)
+            ?? this.pendingTargetTabIds.get(targetId)
+            ?? null;
+    }
+    isAttachedRootTarget(tabId, targetInfo) {
+        if (targetInfo.type !== "page") {
+            return false;
+        }
+        const record = this.sessions.getByTabId(tabId);
+        if (!record) {
+            return false;
+        }
+        if (record.attachTargetId && targetInfo.targetId === record.attachTargetId) {
+            return true;
+        }
+        if (targetInfo.targetId === record.targetInfo.targetId) {
+            return true;
+        }
+        if (record.targetInfo.url && targetInfo.url === record.targetInfo.url) {
+            return true;
+        }
+        if (record.targetInfo.title && targetInfo.title === record.targetInfo.title) {
+            return true;
+        }
+        return false;
+    }
+    childAttachDiagnosticKey(tabId, targetId) {
+        return `${tabId}:${targetId}`;
+    }
+    resolveRootAttachBy(debuggee) {
+        return debuggee.attachBy === "targetId" ? "targetId" : "tabId";
+    }
+    clearRootAttachDiagnostic(tabId) {
+        this.rootAttachDiagnostics.delete(tabId);
+    }
+    recordRootAttachDiagnostic(tabId, diagnostic) {
+        this.rootAttachDiagnostics.set(tabId, {
+            tabId,
+            at: Date.now(),
+            ...diagnostic
+        });
+    }
+    clearChildAttachDiagnostic(tabId, targetId) {
+        this.childAttachDiagnostics.delete(this.childAttachDiagnosticKey(tabId, targetId));
+    }
+    recordChildAttachDiagnostic(tabId, targetId, diagnostic) {
+        this.childAttachDiagnostics.set(this.childAttachDiagnosticKey(tabId, targetId), {
+            tabId,
+            targetId,
+            at: Date.now(),
+            ...diagnostic
+        });
+    }
+    async captureRootRefreshDiagnostic(tabId, path, refreshCompleted, error) {
+        const attachedDebuggee = this.debuggees.get(tabId) ?? null;
+        const rootRecord = this.sessions.getByTabId(tabId);
+        const rootSession = rootRecord
+            ? this.sessions.getBySessionId(rootRecord.rootSessionId)
+            : null;
+        const debuggee = attachedDebuggee ?? rootSession?.debuggerSession ?? null;
+        const rootTargetIdAfterRefresh = typeof debuggee?.targetId === "string" && debuggee.targetId.length > 0
+            ? debuggee.targetId
+            : undefined;
+        let probeStage = refreshCompleted ? "missing_debuggee" : "skipped";
+        let probeReason;
+        if (refreshCompleted && debuggee) {
+            try {
+                await this.sendCommandOnce(debuggee, "Target.getTargets", {});
+                probeStage = "succeeded";
+            }
+            catch (probeError) {
+                probeStage = "failed";
+                probeReason = getErrorMessage(probeError);
+            }
+        }
+        this.rootRefreshDiagnostics.set(tabId, {
+            tabId,
+            path,
+            refreshCompleted,
+            debuggeePresentAfterRefresh: attachedDebuggee !== null,
+            rootSessionPresentAfterRefresh: rootSession !== null,
+            ...(rootTargetIdAfterRefresh ? { rootTargetIdAfterRefresh } : {}),
+            probeMethod: "Target.getTargets",
+            probeStage,
+            ...(probeReason ? { probeReason } : {}),
+            ...(error ? { reason: getErrorMessage(error) } : {}),
+            at: Date.now()
+        });
+    }
     async buildTargetInfo(tabId) {
         const tab = await this.tabManager.getTab(tabId);
         return {
@@ -494,14 +1826,32 @@ export class CDPRouter {
             url: tab?.url ?? undefined
         };
     }
-    emitTargetCreated(targetInfo) {
-        this.emitEvent("Target.targetCreated", { targetInfo });
+    async readRootFrameInfo(tabId) {
+        try {
+            const result = await Promise.race([
+                this.sendCommand({ tabId }, "Page.getFrameTree", {}, { preserveTab: true }),
+                new Promise((resolve) => {
+                    setTimeout(() => resolve(null), 750);
+                })
+            ]);
+            const rootFrame = readRootFrame(result);
+            if (!rootFrame) {
+                return null;
+            }
+            return rootFrame;
+        }
+        catch {
+            return null;
+        }
+    }
+    emitTargetCreated(tabId, targetInfo) {
+        this.emitEvent(tabId, "Target.targetCreated", { targetInfo });
     }
-    emitTargetDestroyed(targetId) {
-        this.emitEvent("Target.targetDestroyed", { targetId });
+    emitTargetDestroyed(tabId, targetId) {
+        this.emitEvent(tabId, "Target.targetDestroyed", { targetId });
     }
-    emitTargetDetached(sessionId, targetId) {
-        this.emitEvent("Target.detachedFromTarget", { sessionId, targetId });
+    emitTargetDetached(tabId, sessionId, targetId) {
+        this.emitEvent(tabId, "Target.detachedFromTarget", { sessionId, targetId });
     }
     emitRootAttached(targetInfo) {
         const record = this.sessions.getByTargetId(targetInfo.targetId);
@@ -510,7 +1860,7 @@ export class CDPRouter {
         if (this.rootAttachedSessions.has(record.sessionId))
             return;
         this.rootAttachedSessions.add(record.sessionId);
-        this.emitEvent("Target.attachedToTarget", {
+        this.emitEvent(record.tabId, "Target.attachedToTarget", {
             sessionId: record.sessionId,
             targetInfo,
             waitingForDebugger: false
@@ -524,7 +1874,7 @@ export class CDPRouter {
             if (!this.rootAttachedSessions.has(record.sessionId))
                 continue;
             this.rootAttachedSessions.delete(record.sessionId);
-            this.emitTargetDetached(record.sessionId, targetInfo.targetId);
+            this.emitTargetDetached(record.tabId, record.sessionId, targetInfo.targetId);
         }
     }
     resetRootAttached() {
@@ -535,25 +1885,76 @@ export class CDPRouter {
         this.sessionCounter += 1;
         return sessionId;
     }
-    async sendCommand(debuggee, method, params) {
+    createBrowserSessionId() {
+        const sessionId = `pw-browser-${this.sessionCounter}`;
+        this.sessionCounter += 1;
+        return sessionId;
+    }
+    async ensureBrowserSession(tabId) {
+        const existing = this.sessions.getBrowserSession(tabId);
+        if (existing) {
+            return existing.sessionId;
+        }
+        const browserSessionId = this.createBrowserSessionId();
+        return this.sessions.registerBrowserSession(tabId, browserSessionId)?.sessionId ?? null;
+    }
+    async sendCommand(debuggee, method, params, options = {}) {
+        const preferredTabId = this.resolveSourceTabId(debuggee);
+        const refreshCommandDebuggee = options.refreshPreparedDebuggee !== false
+            && this.shouldRefreshPreparedCommandDebuggee(debuggee, preferredTabId);
+        await this.prepareForNextClientIfNeeded(preferredTabId);
+        const commandDebuggee = refreshCommandDebuggee && preferredTabId !== null
+            ? (this.getTabDebuggee(preferredTabId) ?? debuggee)
+            : debuggee;
         try {
-            return await this.sendCommandOnce(debuggee, method, params);
+            return await this.sendCommandOnce(commandDebuggee, method, params);
         }
         catch (error) {
-            const hasChildSession = typeof debuggee.sessionId === "string";
+            const hasChildSession = typeof commandDebuggee.sessionId === "string";
             if (!this.isStaleTabError(error) || hasChildSession) {
                 throw error;
             }
-            const recovered = await this.recoverFromStaleTab(debuggee);
+            const retainedRootDebuggee = this.resolveRetainedRootTargetDebuggee(commandDebuggee);
+            if (retainedRootDebuggee) {
+                try {
+                    return await this.sendCommandOnce(retainedRootDebuggee, method, params);
+                }
+                catch (retainedError) {
+                    if (!this.isStaleTabError(retainedError)) {
+                        throw retainedError;
+                    }
+                    error = retainedError;
+                }
+            }
+            const recovered = await this.recoverFromStaleTab(commandDebuggee, options.preserveTab === true);
             if (!recovered) {
                 throw error;
             }
             return await this.sendCommandOnce(recovered, method, params);
         }
     }
+    shouldRefreshPreparedCommandDebuggee(debuggee, preferredTabId) {
+        if (preferredTabId === null) {
+            return false;
+        }
+        if (typeof debuggee.sessionId !== "string") {
+            return true;
+        }
+        const sessionRecord = this.sessions.getBySessionId(debuggee.sessionId);
+        const rootRecord = this.sessions.getByTabId(preferredTabId);
+        return Boolean(sessionRecord
+            && rootRecord
+            && sessionRecord.tabId === preferredTabId
+            && sessionRecord.targetId === rootRecord.targetInfo.targetId);
+    }
     async sendCommandOnce(debuggee, method, params) {
+        const chromeDebuggee = this.toChromeDebuggee(debuggee);
+        const sendCommandFn = chrome.debugger.sendCommand;
+        if (!("mock" in sendCommandFn) || chrome.debugger.sendCommand.length < 4) {
+            return await chrome.debugger.sendCommand(chromeDebuggee, method, params);
+        }
         return await new Promise((resolve, reject) => {
-            chrome.debugger.sendCommand(debuggee, method, params, (result) => {
+            chrome.debugger.sendCommand(chromeDebuggee, method, params, (result) => {
                 const lastError = chrome.runtime.lastError;
                 if (lastError) {
                     reject(new Error(lastError.message));
@@ -563,25 +1964,96 @@ export class CDPRouter {
             });
         });
     }
-    async recoverFromStaleTab(debuggee) {
-        const staleTabId = typeof debuggee.tabId === "number" ? debuggee.tabId : null;
+    resolveRetainedRootTargetDebuggee(debuggee) {
+        if (typeof debuggee.sessionId === "string") {
+            return null;
+        }
+        const staleTabId = typeof debuggee.tabId === "number"
+            ? debuggee.tabId
+            : (typeof debuggee.targetId === "string" ? this.rootTargetTabIds.get(debuggee.targetId) ?? null : null);
+        if (staleTabId === null) {
+            return null;
+        }
+        const targetId = this.resolveRetainedRootTargetId(staleTabId);
+        if (!targetId) {
+            return null;
+        }
+        if (typeof debuggee.targetId === "string" && debuggee.targetId === targetId && typeof debuggee.tabId !== "number") {
+            return null;
+        }
+        return { targetId };
+    }
+    resolveRetainedRootTargetId(tabId) {
+        const attachedDebuggee = this.debuggees.get(tabId);
+        if (typeof attachedDebuggee?.targetId === "string" && attachedDebuggee.targetId.length > 0) {
+            return attachedDebuggee.targetId;
+        }
+        const rootRecord = this.sessions.getByTabId(tabId);
+        const rootSession = rootRecord
+            ? this.sessions.getBySessionId(rootRecord.rootSessionId)
+            : null;
+        if (typeof rootSession?.debuggerSession?.targetId === "string" && rootSession.debuggerSession.targetId.length > 0) {
+            return rootSession.debuggerSession.targetId;
+        }
+        if (typeof rootRecord?.attachTargetId === "string" && rootRecord.attachTargetId.length > 0) {
+            return rootRecord.attachTargetId;
+        }
+        return null;
+    }
+    async recoverFromStaleTab(debuggee, preserveTab) {
+        const staleTabId = typeof debuggee.tabId === "number"
+            ? debuggee.tabId
+            : (typeof debuggee.targetId === "string" ? this.rootTargetTabIds.get(debuggee.targetId) ?? null : null);
         if (staleTabId === null) {
             return null;
         }
-        this.debuggees.delete(staleTabId);
-        this.detachTabState(staleTabId);
-        await this.safeDetach({ tabId: staleTabId });
         try {
-            await this.attachInternal(staleTabId, true);
+            await this.reattachRootDebuggee(staleTabId, !preserveTab);
         }
         catch {
             return null;
         }
-        return this.getPrimaryDebuggee();
+        return preserveTab
+            ? this.debuggees.get(staleTabId) ?? null
+            : this.debuggees.get(staleTabId) ?? this.getPrimaryDebuggee();
     }
     isStaleTabError(error) {
         const message = error instanceof Error ? error.message : String(error);
-        return message.includes("No tab with given id");
+        return STALE_TAB_ERROR_MARKERS.some((marker) => message.includes(marker));
+    }
+    markExpectedRootDetach(tabId) {
+        this.expectedRootDetachDeadlines.set(tabId, Date.now() + 1000);
+    }
+    consumeExpectedRootDetach(source) {
+        const tabId = this.resolveSourceTabId(source);
+        if (tabId === null) {
+            return false;
+        }
+        const deadline = this.expectedRootDetachDeadlines.get(tabId);
+        if (typeof deadline !== "number") {
+            return false;
+        }
+        const sourceSessionId = source.sessionId;
+        if (typeof sourceSessionId === "string") {
+            return false;
+        }
+        this.expectedRootDetachDeadlines.delete(tabId);
+        return deadline >= Date.now();
+    }
+    toChromeDebuggee(debuggee) {
+        if (typeof debuggee.sessionId === "string") {
+            if (typeof debuggee.targetId === "string" && debuggee.targetId.length > 0) {
+                return { targetId: debuggee.targetId, sessionId: debuggee.sessionId };
+            }
+            return { tabId: debuggee.tabId, sessionId: debuggee.sessionId };
+        }
+        if (debuggee.attachBy === "targetId" && typeof debuggee.targetId === "string" && debuggee.targetId.length > 0) {
+            return { targetId: debuggee.targetId };
+        }
+        if (typeof debuggee.tabId === "number") {
+            return { tabId: debuggee.tabId };
+        }
+        return { targetId: debuggee.targetId };
     }
     async runDebuggerAction(action) {
         return new Promise((resolve, reject) => {
@@ -598,7 +2070,7 @@ export class CDPRouter {
     async safeDetach(debuggee) {
         try {
             await this.runDebuggerAction((done) => {
-                chrome.debugger.detach(debuggee, done);
+                chrome.debugger.detach(this.toChromeDebuggee(debuggee), done);
             });
         }
         catch (error) {
@@ -615,10 +2087,14 @@ export class CDPRouter {
             return;
         this.callbacks.onResponse({ id, error: { message }, ...(sessionId ? { sessionId } : {}) });
     }
-    emitEvent(method, params, sessionId) {
+    emitEvent(tabId, method, params, sessionId) {
+        const event = { tabId, method, ...(typeof params !== "undefined" ? { params } : {}), ...(sessionId ? { sessionId } : {}) };
+        for (const listener of this.eventListeners) {
+            listener(event);
+        }
         if (!this.callbacks)
             return;
-        const payload = { method, params };
+        const payload = { method, ...(typeof params !== "undefined" ? { params } : {}) };
         if (sessionId) {
             payload.sessionId = sessionId;
         }
@@ -628,6 +2104,17 @@ export class CDPRouter {
 const isTargetInfo = (value) => {
     return isRecord(value) && typeof value.targetId === "string" && typeof value.type === "string";
 };
+const parseTabTargetAlias = (targetId) => {
+    if (typeof targetId !== "string") {
+        return null;
+    }
+    const match = /^tab-(\d+)$/.exec(targetId);
+    if (!match) {
+        return null;
+    }
+    const parsed = Number.parseInt(match[1] ?? "", 10);
+    return Number.isFinite(parsed) ? parsed : null;
+};
 const getErrorMessage = (error) => {
     if (error instanceof Error) {
         return error.message;
@@ -637,3 +2124,20 @@ const getErrorMessage = (error) => {
 const isRecord = (value) => {
     return typeof value === "object" && value !== null;
 };
+const readRootFrame = (value) => {
+    if (!isRecord(value)) {
+        return null;
+    }
+    const frameTree = value.frameTree;
+    if (!isRecord(frameTree)) {
+        return null;
+    }
+    const frame = frameTree.frame;
+    if (!isRecord(frame) || typeof frame.id !== "string") {
+        return null;
+    }
+    return {
+        id: frame.id,
+        ...(typeof frame.url === "string" ? { url: frame.url } : {})
+    };
+};