opendevbrowser 0.0.16 → 0.0.18

package/extension/dist/services/ConnectionManager.js

@@ -29,6 +29,20 @@ const logInfo = (message) => {
 const logWarn = (message) => {
     console.warn(`[opendevbrowser] ${message}`);
 };
+const getTrackedTabUrl = (tab) => {
+    if (!tab) {
+        return undefined;
+    }
+    const pendingUrl = typeof tab.pendingUrl === "string" && tab.pendingUrl.length > 0 ? tab.pendingUrl : undefined;
+    const currentUrl = typeof tab.url === "string" && tab.url.length > 0 ? tab.url : undefined;
+    return pendingUrl ?? currentUrl;
+};
+const getTrackedTabTitle = (tab) => {
+    if (!tab || tab.status === "loading") {
+        return undefined;
+    }
+    return typeof tab.title === "string" && tab.title.length > 0 ? tab.title : undefined;
+};
 const RECONNECT_INITIAL_DELAY_MS = 12_000;
 const RECONNECT_MAX_DELAY_MS = 30_000;
 export class ConnectionManager {
@@ -55,8 +69,11 @@ export class ConnectionManager {
     connectPromise = null;
     annotationHandler = null;
     opsHandler = null;
+    canvasHandler = null;
     heartbeatTimer = null;
     heartbeatInFlight = false;
+    handshakeRefreshQueued = false;
+    handshakeRefreshPromise = null;
     heartbeatIntervalMs = 25_000;
     heartbeatTimeoutMs = 2_000;
     constructor() {
@@ -91,6 +108,9 @@ export class ConnectionManager {
     onOpsMessage(handler) {
         this.opsHandler = handler;
     }
+    onCanvasMessage(handler) {
+        this.canvasHandler = handler;
+    }
     sendAnnotationResponse(response) {
         if (!this.relay)
             return;
@@ -121,6 +141,16 @@ export class ConnectionManager {
             logError("relay.send_ops_message", error, { code: "relay_send_failed" });
         }
     }
+    sendCanvasMessage(message) {
+        if (!this.relay)
+            return;
+        try {
+            this.relay.sendCanvasMessage(message);
+        }
+        catch (error) {
+            logError("relay.send_canvas_message", error, { code: "relay_send_failed" });
+        }
+    }
     getCdpRouter() {
         return this.cdp;
     }
@@ -129,13 +159,82 @@ export class ConnectionManager {
             return null;
         }
         try {
-            return await this.relay.sendHealthCheck();
+            const health = await this.relay.sendHealthCheck();
+            if (health.extensionConnected && !health.extensionHandshakeComplete) {
+                this.relayNotice = "Extension websocket is connected but the daemon-extension handshake is unhealthy. Re-establishing a clean handshake.";
+                this.refreshHandshake();
+            }
+            return health;
         }
         catch (error) {
             logError("relay.health_check", error, { code: "relay_health_failed" });
             return null;
         }
     }
+    async sendAnnotationCommand(command, timeoutMs = 5000) {
+        const socket = new WebSocket(this.buildAnnotationUrl());
+        let settled = false;
+        return await new Promise((resolve, reject) => {
+            const timeoutId = setTimeout(() => {
+                finish(() => reject(new Error("Annotation relay request timed out")));
+            }, timeoutMs);
+            const finish = (callback) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                clearTimeout(timeoutId);
+                try {
+                    if (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING) {
+                        socket.close(1000, "annotation-command-complete");
+                    }
+                }
+                catch {
+                    // Ignore socket close failures during cleanup.
+                }
+                callback();
+            };
+            socket.addEventListener("open", () => {
+                try {
+                    socket.send(JSON.stringify({
+                        type: "annotationCommand",
+                        payload: command
+                    }));
+                }
+                catch (error) {
+                    finish(() => reject(error instanceof Error ? error : new Error("Annotation relay send failed")));
+                }
+            }, { once: true });
+            socket.addEventListener("message", (event) => {
+                if (typeof event.data !== "string") {
+                    return;
+                }
+                try {
+                    const message = JSON.parse(event.data);
+                    if (message.type !== "annotationResponse") {
+                        return;
+                    }
+                    const payload = message.payload;
+                    if (!isAnnotationResponse(payload) || payload.requestId !== command.requestId) {
+                        return;
+                    }
+                    finish(() => resolve(payload));
+                }
+                catch {
+                    // Ignore malformed one-off annotation responses.
+                }
+            });
+            socket.addEventListener("error", () => {
+                finish(() => reject(new Error("Annotation relay unavailable")));
+            }, { once: true });
+            socket.addEventListener("close", () => {
+                if (settled) {
+                    return;
+                }
+                finish(() => reject(new Error("Annotation relay closed")));
+            }, { once: true });
+        });
+    }
     async connect() {
         if (this.connectPromise) {
             return await this.connectPromise;
@@ -179,6 +278,7 @@ export class ConnectionManager {
         this.shouldReconnect = false;
         this.clearReconnectTimer();
         this.stopHeartbeat();
+        this.handshakeRefreshQueued = false;
         try {
             if (this.relay) {
                 this.relay.disconnect();
@@ -214,6 +314,38 @@ export class ConnectionManager {
             logError(context, error, { code: "relay_send_failed" });
         }
     }
+    async getFirstHttpFallbackTab(currentTabId) {
+        const fallbackTab = await this.tabs.getFirstAttachableTab(currentTabId);
+        if (!fallbackTab || typeof fallbackTab.id !== "number" || !fallbackTab.url) {
+            return null;
+        }
+        logInfo("Falling back to first http(s) tab.");
+        return fallbackTab;
+    }
+    async bootstrapRelayAttachTab() {
+        try {
+            const fallbackTab = await this.tabs.createTab("about:blank", true);
+            if (fallbackTab && typeof fallbackTab.id === "number") {
+                logInfo("Bootstrapping a fresh browser tab for relay attach.");
+                return fallbackTab;
+            }
+        }
+        catch {
+            // Ignore tab creation failures and let the caller surface the original error.
+        }
+        return null;
+    }
+    async resolveRelayAttachFallback(currentTabId) {
+        const httpTab = await this.getFirstHttpFallbackTab(currentTabId);
+        if (httpTab) {
+            return { tab: httpTab, allowBlankRelayFallback: false };
+        }
+        const blankTab = await this.bootstrapRelayAttachTab();
+        if (blankTab) {
+            return { tab: blankTab, allowBlankRelayFallback: true };
+        }
+        return { tab: null, allowBlankRelayFallback: false };
+    }
     startHeartbeat() {
         if (this.heartbeatTimer !== null) {
             return;
@@ -240,7 +372,15 @@ export class ConnectionManager {
         }
         this.heartbeatInFlight = true;
         try {
-            await this.relay.sendPing(this.heartbeatTimeoutMs);
+            const health = await this.relay.sendPing(this.heartbeatTimeoutMs);
+            if (health.extensionConnected && !health.extensionHandshakeComplete) {
+                this.relayNotice = "Extension websocket is connected but the daemon-extension handshake is incomplete. Re-establishing a clean handshake.";
+                this.refreshHandshake();
+                return;
+            }
+            if (health.ok) {
+                this.relayNotice = null;
+            }
         }
         catch (error) {
             logError("relay.heartbeat", error, { code: "relay_heartbeat_failed" });
@@ -254,29 +394,35 @@ export class ConnectionManager {
     }
     async attachToActiveTab() {
         let tab = await this.tabs.getActiveTab();
+        let allowBlankRelayFallback = false;
+        let tabUrl = getTrackedTabUrl(tab);
         if (!tab || typeof tab.id !== "number") {
-            this.trackedTab = null;
-            this.setStatus("disconnected");
-            logWarn("Active tab not found.");
-            throw new ConnectionError("no_active_tab", "No active browser tab found. Focus a normal tab (not the popup) and retry.");
+            const fallback = await this.resolveRelayAttachFallback();
+            tab = fallback.tab;
+            allowBlankRelayFallback = fallback.allowBlankRelayFallback;
+            tabUrl = getTrackedTabUrl(tab);
+            if (!tab || typeof tab.id !== "number") {
+                this.trackedTab = null;
+                this.setStatus("disconnected");
+                logWarn("Active tab not found.");
+                throw new ConnectionError("no_active_tab", "No active browser page found. Focus the site tab or popup window you want to automate, not the extension popup, and retry.");
+            }
         }
-        if (!tab.url) {
+        if (!tabUrl) {
             logWarn("Active tab URL missing.");
-            const fallbackId = await this.tabs.getFirstHttpTabId();
-            if (fallbackId && fallbackId !== tab.id) {
-                const fallbackTab = await this.tabs.getTab(fallbackId);
-                if (fallbackTab && typeof fallbackTab.id === "number" && fallbackTab.url) {
-                    logInfo("Falling back to first http(s) tab.");
-                    tab = fallbackTab;
-                }
+            const fallback = await this.resolveRelayAttachFallback(tab.id);
+            if (fallback.tab) {
+                tab = fallback.tab;
+                allowBlankRelayFallback ||= fallback.allowBlankRelayFallback;
+                tabUrl = getTrackedTabUrl(tab);
             }
-            if (!tab.url) {
+            if (!tabUrl) {
                 throw new ConnectionError("tab_url_missing", "Active tab URL is unavailable. Reload the tab and retry.");
             }
         }
         let parsedUrl = null;
         try {
-            parsedUrl = new URL(tab.url);
+            parsedUrl = tabUrl ? new URL(tabUrl) : null;
         }
         catch (error) {
             logError("connection.parse_tab_url", error, { code: "tab_url_parse_failed" });
@@ -284,54 +430,48 @@ export class ConnectionManager {
         }
         if (!parsedUrl) {
             logWarn("Active tab URL is invalid.");
-            const fallbackId = await this.tabs.getFirstHttpTabId();
-            if (fallbackId && fallbackId !== tab.id) {
-                const fallbackTab = await this.tabs.getTab(fallbackId);
-                if (fallbackTab && typeof fallbackTab.id === "number" && fallbackTab.url) {
-                    logInfo("Falling back to first http(s) tab.");
-                    try {
-                        parsedUrl = new URL(fallbackTab.url);
-                        tab = fallbackTab;
-                    }
-                    catch {
-                        parsedUrl = null;
-                    }
+            const fallback = await this.resolveRelayAttachFallback(tab.id);
+            if (fallback.tab) {
+                tab = fallback.tab;
+                allowBlankRelayFallback ||= fallback.allowBlankRelayFallback;
+                tabUrl = getTrackedTabUrl(tab);
+                try {
+                    parsedUrl = tabUrl ? new URL(tabUrl) : null;
+                }
+                catch {
+                    parsedUrl = null;
                 }
             }
             if (!parsedUrl) {
-                throw new ConnectionError("tab_url_restricted", "Active tab URL is unsupported. Focus a normal http(s) tab and retry.");
+                throw new ConnectionError("tab_url_restricted", "Active browser page URL is unsupported. Focus an http(s) page or site popup window, not the extension popup, and retry.");
             }
         }
         const restrictionMessage = getRestrictionMessage(parsedUrl);
         if (restrictionMessage) {
-            logWarn(`Active tab blocked: ${summarizeProtocol(tab.url)} scheme.`);
-            const fallbackId = await this.tabs.getFirstHttpTabId();
-            if (fallbackId && fallbackId !== tab.id) {
-                const fallbackTab = await this.tabs.getTab(fallbackId);
-                if (fallbackTab && typeof fallbackTab.id === "number" && fallbackTab.url) {
-                    try {
-                        const fallbackUrl = new URL(fallbackTab.url);
-                        const fallbackRestriction = getRestrictionMessage(fallbackUrl);
-                        if (!fallbackRestriction) {
-                            logInfo("Falling back to first http(s) tab.");
-                            tab = fallbackTab;
-                            parsedUrl = fallbackUrl;
-                        }
-                    }
-                    catch {
-                        // Ignore invalid fallback URL.
-                    }
+            logWarn(`Active tab blocked: ${summarizeProtocol(tabUrl)} scheme.`);
+            const fallback = await this.resolveRelayAttachFallback(tab.id);
+            if (fallback.tab) {
+                tab = fallback.tab;
+                allowBlankRelayFallback ||= fallback.allowBlankRelayFallback;
+                tabUrl = getTrackedTabUrl(tab);
+                try {
+                    parsedUrl = tabUrl ? new URL(tabUrl) : null;
+                }
+                catch {
+                    parsedUrl = null;
                 }
             }
-            if (restrictionMessage && getRestrictionMessage(parsedUrl)) {
-                throw new ConnectionError("tab_url_restricted", restrictionMessage);
+            if (restrictionMessage && (!parsedUrl || getRestrictionMessage(parsedUrl))) {
+                if (!allowBlankRelayFallback) {
+                    throw new ConnectionError("tab_url_restricted", restrictionMessage);
+                }
             }
         }
         const tabId = tab.id;
         if (typeof tabId !== "number") {
             this.trackedTab = null;
             this.setStatus("disconnected");
-            throw new ConnectionError("no_active_tab", "No active browser tab found. Focus a normal tab (not the popup) and retry.");
+            throw new ConnectionError("no_active_tab", "No active browser page found. Focus the site tab or popup window you want to automate, not the extension popup, and retry.");
         }
         logInfo("Active tab resolved.");
         try {
@@ -346,12 +486,7 @@ export class ConnectionManager {
                 : "Debugger attach failed. Close DevTools for the tab and retry.";
             throw new ConnectionError("debugger_attach_failed", message);
         }
-        this.trackedTab = {
-            id: tabId,
-            url: tab.url ?? undefined,
-            title: tab.title ?? undefined,
-            groupId: typeof tab.groupId === "number" ? tab.groupId : undefined
-        };
+        this.trackedTab = this.toTrackedTab(tab, null);
     }
     async connectRelay() {
         if (!this.trackedTab) {
@@ -364,12 +499,18 @@ export class ConnectionManager {
                     this.handleCdpDetach({ reason: "cdp_command_failed" });
                 });
             },
+            onCdpControl: (message) => {
+                this.handleCdpControl(message);
+            },
             onAnnotationCommand: (command) => {
                 this.annotationHandler?.(command);
             },
             onOpsMessage: (message) => {
                 this.opsHandler?.(message);
             },
+            onCanvasMessage: (message) => {
+                this.canvasHandler?.(message);
+            },
             onClose: (detail) => {
                 this.handleRelayClose(detail);
             }
@@ -403,6 +544,10 @@ export class ConnectionManager {
             if (!mismatch) {
                 this.persistRelayIdentity(ack.payload.relayPort, this.relayInstanceId, this.relayEpoch);
             }
+            const handshakeHealthy = await this.verifyHandshakeHealth(relay, "connect");
+            if (!handshakeHealthy) {
+                return;
+            }
             logInfo("Relay WebSocket connected.");
             this.setStatus("connected");
             this.startHeartbeat();
@@ -421,6 +566,7 @@ export class ConnectionManager {
     handleRelayClose(detail) {
         this.stopHeartbeat();
         this.relay = null;
+        this.cdp.markClientClosed();
         if (detail && (detail.code === 1008 || detail.reason?.includes("Invalid pairing token"))) {
             this.clearStoredPairingToken();
         }
@@ -448,6 +594,10 @@ export class ConnectionManager {
         if (this.cdp.getAttachedTabIds().length > 0) {
             return;
         }
+        if (detail?.reason === "manual_disconnect") {
+            void this.recoverFromManualDetach(detail);
+            return;
+        }
         this.setStatus("disconnected");
         if (this.relay?.isConnected()) {
             this.relay.disconnect();
@@ -455,12 +605,49 @@ export class ConnectionManager {
         }
         this.scheduleReconnect();
     }
+    async recoverFromManualDetach(detail) {
+        try {
+            const preferredTabId = typeof detail?.tabId === "number" ? detail.tabId : this.trackedTab?.id ?? null;
+            if (typeof preferredTabId === "number") {
+                await this.cdp.attach(preferredTabId);
+                const recoveredTabId = this.cdp.getPrimaryTabId() ?? preferredTabId;
+                await this.refreshTrackedTab(recoveredTabId, { preserveCurrentOnRestricted: true });
+            }
+            else {
+                await this.attachToActiveTab();
+            }
+            if (!this.relay?.isConnected()) {
+                this.scheduleReconnect();
+                return;
+            }
+            this.setStatus("connected");
+            this.refreshHandshake();
+        }
+        catch (error) {
+            logError("connection.manual_detach_recover", error, { code: "tracked_tab_refresh_failed" });
+            this.setStatus("disconnected");
+            if (this.relay?.isConnected()) {
+                this.relay.disconnect();
+                return;
+            }
+            this.scheduleReconnect();
+        }
+    }
+    handleCdpControl(message) {
+        if (message.action !== "client_closed") {
+            return;
+        }
+        this.cdp.markClientClosed();
+    }
     scheduleReconnect() {
         if (this.reconnectTimer !== null) {
             return;
         }
         this.reconnectTimer = setTimeout(() => {
             this.reconnectTimer = null;
+            if (!this.shouldReconnect || this.status === "connected" || this.relay?.isConnected()) {
+                return;
+            }
             this.reconnectAttempts += 1;
             this.reconnectDelayMs = Math.min(this.reconnectDelayMs * 2, this.maxReconnectDelayMs);
             this.reconnectRelay().catch((error) => {
@@ -470,7 +657,7 @@ export class ConnectionManager {
         }, this.reconnectDelayMs);
     }
     async reconnectRelay() {
-        if (!this.shouldReconnect) {
+        if (!this.shouldReconnect || this.status === "connected" || this.relay?.isConnected()) {
             return;
         }
         const primaryId = this.cdp.getPrimaryTabId();
@@ -527,24 +714,59 @@ export class ConnectionManager {
         if (!this.trackedTab || this.trackedTab.id !== tabId) {
             return;
         }
-        if (this.cdp.getAttachedTabIds().length <= 1) {
+        const attachedTabIds = this.cdp.getAttachedTabIds().filter((attachedId) => attachedId !== tabId);
+        if (attachedTabIds.length === 0) {
             this.disconnect().catch((error) => {
                 logError("connection.tab_removed_disconnect", error, { code: "disconnect_failed" });
             });
+            return;
         }
+        const primaryTabId = this.cdp.getPrimaryTabId();
+        const nextTrackedTabId = primaryTabId && primaryTabId !== tabId
+            ? primaryTabId
+            : attachedTabIds[0] ?? null;
+        if (!nextTrackedTabId) {
+            this.disconnect().catch((error) => {
+                logError("connection.tab_removed_disconnect", error, { code: "disconnect_failed" });
+            });
+            return;
+        }
+        this.refreshTrackedTab(nextTrackedTabId, { preserveCurrentOnRestricted: true })
+            .then(() => {
+            this.refreshHandshake();
+        })
+            .catch((error) => {
+            logError("connection.tab_removed_refresh", error, { code: "tracked_tab_refresh_failed" });
+        });
     };
     handleTabUpdated = (_tabId, _changeInfo, tab) => {
-        if (!this.trackedTab || tab.id !== this.trackedTab.id) {
+        const updatedTabId = typeof tab.id === "number" ? tab.id : null;
+        if (updatedTabId === null) {
             return;
         }
-        this.trackedTab = {
-            id: tab.id,
-            url: tab.url ?? this.trackedTab.url,
-            title: tab.title ?? this.trackedTab.title,
-            groupId: typeof tab.groupId === "number" ? tab.groupId : this.trackedTab.groupId
-        };
+        const trackedTabId = this.trackedTab?.id ?? null;
+        const primaryTabId = this.cdp.getPrimaryTabId();
+        if (trackedTabId !== updatedTabId && primaryTabId !== updatedTabId) {
+            return;
+        }
+        if (trackedTabId !== updatedTabId) {
+            if (!this.isRestrictedTab(tab)) {
+                this.setTrackedTab(tab);
+                this.refreshHandshake();
+                return;
+            }
+            this.refreshTrackedTab(updatedTabId, { preserveCurrentOnRestricted: true })
+                .then(() => {
+                this.refreshHandshake();
+            })
+                .catch((error) => {
+                logError("connection.tab_updated_refresh", error, { code: "tracked_tab_refresh_failed" });
+            });
+            return;
+        }
+        this.setTrackedTab(tab);
         if (this.relay?.isConnected()) {
-            this.safeRelaySend(() => this.relay?.sendHandshake(this.buildHandshake()), "relay.send_handshake");
+            this.refreshHandshake();
         }
     };
     async loadSettings() {
@@ -567,7 +789,7 @@ export class ConnectionManager {
         }
         return {
             code: "unknown",
-            message: "Connection failed. Focus a normal tab and retry."
+            message: "Connection failed. Focus the site tab or popup window you want to automate, not the extension popup, and retry."
         };
     }
     updatePairingToken(value) {
@@ -649,9 +871,9 @@ export class ConnectionManager {
             this.clearStoredRelayIdentity();
             this.clearStoredPairingToken(false);
             this.relayNotice = instanceMismatch
-                ? "Relay instance changed. Re-pair and reconnect."
-                : "Relay restarted. Re-pair and reconnect.";
-            this.safeRelaySend(() => this.relay?.sendHandshake(this.buildHandshake()), "relay.rehandshake");
+                ? "Relay instance changed. Re-establishing a clean daemon-extension handshake."
+                : "Relay restarted. Re-establishing a clean daemon-extension handshake.";
+            this.refreshHandshake();
             return true;
         }
         this.relayNotice = null;
@@ -665,6 +887,13 @@ export class ConnectionManager {
     buildRelayUrl() {
         return `ws://127.0.0.1:${this.relayPort}/extension`;
     }
+    buildAnnotationUrl() {
+        const port = this.relayConfirmedPort ?? this.relayPort;
+        const query = this.pairingEnabled && this.pairingToken
+            ? `?token=${encodeURIComponent(this.pairingToken)}`
+            : "";
+        return `ws://127.0.0.1:${port}/annotation${query}`;
+    }
     async refreshRelay() {
         if (this.status !== "connected")
             return;
@@ -673,26 +902,101 @@ export class ConnectionManager {
     }
     async handlePrimaryTabChange(tabId) {
         if (!tabId) {
+            const trackedTabId = this.trackedTab?.id;
+            if (this.shouldReconnect && !this.disconnecting && typeof trackedTabId === "number") {
+                const trackedTab = await this.tabs.getTab(trackedTabId);
+                if (trackedTab && typeof trackedTab.id === "number") {
+                    await this.refreshTrackedTab(trackedTab.id, { preserveCurrentOnRestricted: true });
+                    this.refreshHandshake();
+                    return;
+                }
+            }
             this.trackedTab = null;
             if (this.relay?.isConnected()) {
                 this.relay.disconnect();
             }
             return;
         }
-        await this.refreshTrackedTab(tabId);
+        await this.refreshTrackedTab(tabId, { preserveCurrentOnRestricted: true });
         this.refreshHandshake();
     }
-    async refreshTrackedTab(tabId) {
-        const tab = await this.tabs.getTab(tabId);
+    isRestrictedTab(tab) {
+        const rawUrl = getTrackedTabUrl(tab);
+        if (!rawUrl) {
+            return true;
+        }
+        try {
+            return Boolean(getRestrictionMessage(new URL(rawUrl)));
+        }
+        catch {
+            return true;
+        }
+    }
+    async refreshTrackedTab(tabId, options) {
+        const previous = this.trackedTab;
+        let tab = await this.tabs.getTab(tabId);
+        if ((!tab || typeof tab.id !== "number") && options?.preserveCurrentOnRestricted && previous) {
+            this.trackedTab = previous;
+            return;
+        }
         if (!tab || typeof tab.id !== "number") {
             this.trackedTab = null;
             return;
         }
-        this.trackedTab = {
-            id: tab.id,
-            url: tab.url ?? this.trackedTab?.url,
-            title: tab.title ?? this.trackedTab?.title,
-            groupId: typeof tab.groupId === "number" ? tab.groupId : this.trackedTab?.groupId
+        if (this.isRestrictedTab(tab)) {
+            const httpFallback = await this.getFirstHttpFallbackTab(tab.id);
+            if (httpFallback) {
+                tab = httpFallback;
+            }
+            else if (options?.preserveCurrentOnRestricted && previous) {
+                this.trackedTab = previous;
+                return;
+            }
+            else {
+                const blankFallback = await this.bootstrapRelayAttachTab();
+                if (blankFallback) {
+                    tab = blankFallback;
+                }
+                else {
+                    this.trackedTab = null;
+                    return;
+                }
+            }
+        }
+        const nextTrackedTabId = tab.id;
+        if (typeof nextTrackedTabId !== "number") {
+            if (options?.preserveCurrentOnRestricted && previous) {
+                this.trackedTab = previous;
+                return;
+            }
+            this.trackedTab = null;
+            return;
+        }
+        this.setTrackedTab(tab);
+    }
+    setTrackedTab(tab) {
+        const tabId = typeof tab.id === "number" ? tab.id : null;
+        if (tabId === null) {
+            return;
+        }
+        this.trackedTab = this.toTrackedTab(tab, this.trackedTab);
+    }
+    toTrackedTab(tab, previous) {
+        const tabId = typeof tab.id === "number" ? tab.id : null;
+        if (tabId === null) {
+            throw new Error("Tracked tab id is missing");
+        }
+        const sameTab = previous?.id === tabId;
+        const url = getTrackedTabUrl(tab) ?? (sameTab ? previous?.url : undefined);
+        const title = getTrackedTabTitle(tab) ?? (sameTab ? previous?.title : undefined);
+        const groupId = typeof tab.groupId === "number"
+            ? tab.groupId
+            : (sameTab ? previous?.groupId : undefined);
+        return {
+            id: tabId,
+            ...(url ? { url } : {}),
+            ...(title ? { title } : {}),
+            ...(typeof groupId === "number" ? { groupId } : {})
         };
     }
     clearReconnectTimer() {
@@ -701,10 +1005,81 @@ export class ConnectionManager {
             this.reconnectTimer = null;
         }
     }
+    async verifyHandshakeHealth(relay, source) {
+        try {
+            const health = await relay.sendPing(this.heartbeatTimeoutMs);
+            if (health.extensionConnected && health.extensionHandshakeComplete) {
+                if (this.relay === relay) {
+                    this.relayNotice = null;
+                }
+                return true;
+            }
+            if (this.relay === relay) {
+                this.relayNotice = "Extension websocket is connected but the daemon-extension handshake is still incomplete. Retrying a clean handshake.";
+                if (this.shouldReconnect && !this.disconnecting) {
+                    relay.disconnect();
+                }
+            }
+        }
+        catch (error) {
+            logError(`relay.${source}_handshake_health`, error, { code: "relay_handshake_health_failed" });
+            if (this.relay === relay) {
+                this.relayNotice = "Failed to verify a clean daemon-extension handshake. Retrying the relay connection.";
+                if (this.shouldReconnect && !this.disconnecting) {
+                    relay.disconnect();
+                }
+            }
+        }
+        return false;
+    }
     refreshHandshake() {
         if (!this.trackedTab || !this.relay?.isConnected()) {
             return;
         }
-        this.safeRelaySend(() => this.relay?.sendHandshake(this.buildHandshake()), "relay.send_handshake");
+        this.handshakeRefreshQueued = true;
+        if (this.handshakeRefreshPromise) {
+            return;
+        }
+        const run = (async () => {
+            while (this.handshakeRefreshQueued) {
+                this.handshakeRefreshQueued = false;
+                const relay = this.relay;
+                if (!this.trackedTab || !relay || !relay.isConnected()) {
+                    return;
+                }
+                try {
+                    await relay.sendHandshake(this.buildHandshake());
+                    const handshakeHealthy = await this.verifyHandshakeHealth(relay, "refresh");
+                    if (!handshakeHealthy) {
+                        return;
+                    }
+                }
+                catch (error) {
+                    logError("relay.refresh_handshake", error, { code: "relay_handshake_refresh_failed" });
+                    if (this.relay === relay) {
+                        this.relayNotice = "Failed to re-establish a clean daemon-extension handshake. Open the extension popup, click Connect again, confirm `status --daemon` shows ext=on and handshake=on, then retry.";
+                        if (this.shouldReconnect && !this.disconnecting) {
+                            relay.disconnect();
+                        }
+                    }
+                    return;
+                }
+            }
+        })();
+        const refreshPromise = run.finally(() => {
+            if (this.handshakeRefreshPromise === refreshPromise) {
+                this.handshakeRefreshPromise = null;
+            }
+        });
+        this.handshakeRefreshPromise = refreshPromise;
     }
 }
+const isAnnotationResponse = (value) => {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const record = value;
+    return record.version === 1
+        && typeof record.requestId === "string"
+        && (record.status === "ok" || record.status === "cancelled" || record.status === "error");
+};