fix: recover navigation from cross-extension CDP restrictions

Classify Chrome extension-frame access failures and provide an actionable CLI hint. Recover navigate and reload only when their initial CDP setup is denied, using browser navigation events and verifying that CDP access returns.

Preserve normal navigation, Agent Window checks, transfer error details, and network-idle semantics. Never replay an already-dispatched navigation.

apps/extension/src/entrypoints/background.ts

@@ -25,7 +25,7 @@ import { recordFrameCoordinator } from "@/lib/recording/frame-coordinator";
 import { attachSessionsLiveFlag } from "@/lib/sessions-live-flag";
 import { createDisconnectCleanup } from "@/session-manager/disconnect-cleanup";
 import { attachSessionEventHandler } from "@/session-manager/event-handler";
-import { isAgentControlledTab, SessionManager } from "@/session-manager/manager";
+import { SessionManager } from "@/session-manager/manager";
 import {
   attachBorrowNotificationButtonHandler,
   attachBorrowNotificationClickHandler,
@@ -41,8 +41,6 @@ import {
   attachRecordStepListener,
   type RecordRuntimeDeps,
 } from "@/tools/record";
-import { chromeTabsApi } from "@/tools/shared";
-import { chromeTabMutationApi } from "@/tools/tabs";
 import { detectBrowserMeta } from "@/transport/handshake";
 import type { Transport } from "@/transport/transport";
 import { WSTransport } from "@/transport/ws-transport";
@@ -82,24 +80,6 @@ export default defineBackground(() => {
     };
   }
 
-  /**
-   * Authoritative overlay state for a specific tab. Agent Window tabs are
-   * free by default; only tabs explicitly claimed through session startup,
-   * `tab_create`, or `tab_borrow` receive the control overlay.
-   */
-  function overlayStateForTab(tabId?: number, windowId?: number): OverlayAgentStateMessage {
-    if (typeof tabId === "number" && typeof windowId === "number") {
-      const ctx = sessions.findByWindowId(windowId);
-      if (ctx && isAgentControlledTab(ctx, tabId)) return overlayStateForWindow(windowId);
-    }
-    return {
-      type: OVERLAY_AGENT_STATE,
-      sessionId: null,
-      mode: "hidden",
-      generation: overlayGeneration,
-    };
-  }
-
   async function pushOverlayStateToTab(
     tabId: number,
     state: OverlayAgentStateMessage,
@@ -111,18 +91,13 @@ export default defineBackground(() => {
     }
   }
 
-  async function pushOverlayStateForTab(tabId: number, windowId?: number): Promise<void> {
-    const state = overlayStateForTab(tabId, windowId);
-    await pushOverlayStateToTab(tabId, state);
-  }
-
   async function pushOverlayStateForWindow(windowId: number): Promise<void> {
+    const state = overlayStateForWindow(windowId);
     const tabs = await chrome.tabs.query({ windowId });
     await Promise.all(
-      tabs.map((tab) => {
-        if (typeof tab.id !== "number") return Promise.resolve();
-        return pushOverlayStateForTab(tab.id, windowId);
-      }),
+      tabs.map((tab) =>
+        typeof tab.id === "number" ? pushOverlayStateToTab(tab.id, state) : Promise.resolve(),
+      ),
     );
   }
 
@@ -161,30 +136,13 @@ export default defineBackground(() => {
     if (typeof tab.windowId !== "number") return;
     pushOverlayStateForAgentWindow(tab.windowId);
   });
-  // Newly observed tabs are free unless the agent's own creation path has
-  // already claimed their concrete id. This listener only renders that
-  // state; it never infers or mutates ownership from event ordering.
-  chrome.tabs.onCreated.addListener((tab) => {
-    if (typeof tab.windowId !== "number" || typeof tab.id !== "number") return;
-    if (!sessions.findByWindowId(tab.windowId)) return;
-    void pushOverlayStateForTab(tab.id, tab.windowId);
-  });
-  chrome.tabs.onRemoved.addListener((tabId, removeInfo) => {
-    sessions.forgetClosedTab(tabId, { isWindowClosing: removeInfo.isWindowClosing });
-  });
   // Re-sync the storage.session flag on SW startup so a previous SW's
   // stale `true` does not keep waking us on every page load until the
   // first mutation (review M4/M5 round 3 m-R3-1).
   void sessionsLive.refresh();
   const cleanupAfterDisconnect = createDisconnectCleanup({
     manager: sessions,
-    // Same contract as the dispatcher's `tool.session_stop`: without these
-    // deps the agent-tab cleanup and the window-release path are dead code.
-    sessionStopDeps: {
-      cdp,
-      tabManagement: { tabs: chromeTabMutationApi },
-      tabsQuery: chromeTabsApi,
-    },
+    sessionStopDeps: { cdp },
     onSessionsChanged: () => {
       void sessionsLive.syncFromManager();
     },
@@ -218,9 +176,6 @@ export default defineBackground(() => {
     recording: recordDeps,
     onSessionsChanged: onOverlaySessionStateChanged,
     onBrowserControlResumed,
-    onAgentTabClaimed: (tabId, windowId) => {
-      void pushOverlayStateForTab(tabId, windowId);
-    },
     approveBorrow: (ctx) =>
       requestBorrowConfirmation(ctx.tabId, {
         ...(ctx.signal !== undefined ? { signal: ctx.signal } : {}),
@@ -354,11 +309,7 @@ export default defineBackground(() => {
     }
 
     if (msg.kind === OVERLAY_MSG_READY) {
-      // Resolve from explicit tab ownership before sending so free tabs never
-      // flash the control mask.
-      if (typeof sender.tab?.id === "number") {
-        void pushOverlayStateForTab(sender.tab.id, sender.tab.windowId);
-      }
+      sendResponse(overlayStateForWindow(sender.tab?.windowId));
       return false;
     }
 

apps/extension/src/lib/overlay-bridge.ts

@@ -3,10 +3,8 @@
  * between the content-script control overlay and the background SW.
  *
  * Content script → background:
- *  - `{ kind: "overlay.ready" }` → background decides the per-tab state first
- *      (see overlayStateForTab) and pushes the authoritative overlay state for
- *      that tab. It also proactively pushes on tab create and control-mode
- *      change, so a tab usually receives state before it ever sends ready.
+ *  - `{ kind: "overlay.ready" }` → background replies with the authoritative
+ *      overlay state for the sender's window.
  *  - `{ kind: "overlay.interrupt", sessionId }` → background asks the
  *      daemon (via a `session.user_interrupt` WS event) to cancel
  *      every inflight + queued tool call for that session with

apps/extension/src/session-manager/__tests__/disconnect-cleanup.test.ts

@@ -9,7 +9,7 @@ describe("disconnect session cleanup", () => {
     const manager = new SessionManager({
       agentWindow: {
         create: vi.fn(async () => nextWindowId++),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
         remove,
       },
     });
@@ -41,7 +41,7 @@ describe("disconnect session cleanup", () => {
     const manager = new SessionManager({
       agentWindow: {
         create: vi.fn(async () => 100),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
         remove: vi.fn(() => removeGate),
       },
     });

apps/extension/src/session-manager/__tests__/event-handler.test.ts

@@ -39,7 +39,7 @@ describe("attachSessionEventHandler", () => {
       agentWindow: {
         create: vi.fn(async () => 4242),
         remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
       },
     });
     await manager.start("aa11");
@@ -73,7 +73,7 @@ describe("attachSessionEventHandler", () => {
       agentWindow: {
         create: vi.fn(async () => 4242),
         remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
       },
     });
     const ctx = await manager.start("aa11");
@@ -87,7 +87,6 @@ describe("attachSessionEventHandler", () => {
       windowEvents: events.api,
     });
 
-    manager.forgetClosedTab(7, { isWindowClosing: true });
     events.emit(4242);
     for (let i = 0; i < 4; i += 1) await Promise.resolve();
 
@@ -114,7 +113,7 @@ describe("attachSessionEventHandler", () => {
       agentWindow: {
         create: vi.fn(async () => 1),
         remove: vi.fn(),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
       },
     });
     const transport = fakeTransport();
@@ -130,7 +129,7 @@ describe("attachSessionEventHandler", () => {
       agentWindow: {
         create: vi.fn(async () => 1),
         remove: vi.fn(),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
       },
     });
     const transport = fakeTransport();

apps/extension/src/session-manager/__tests__/manager.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from "vitest";
 import type { AgentWindowApi, AgentWindowCreateOptions } from "../agent-window";
-import { isAgentControlledTab, SessionManager } from "../manager";
+import { SessionManager } from "../manager";
 
 function fakeAgentWindow(): AgentWindowApi & {
   createMock: ReturnType<typeof vi.fn>;
@@ -13,7 +13,7 @@ function fakeAgentWindow(): AgentWindowApi & {
     return id;
   });
   const removeMock = vi.fn(async (_id: number) => {});
-  const ensureActiveTabMock = vi.fn(async (_windowId: number, _url: string) => 0);
+  const ensureActiveTabMock = vi.fn(async (_windowId: number, _url: string) => {});
   return {
     create: createMock,
     remove: removeMock,
@@ -151,76 +151,6 @@ describe("SessionManager", () => {
     expect(sm.list()).toEqual([]);
   });
 
-  describe("explicit tab claims", () => {
-    it("claims the exact home tab returned by AgentWindowApi", async () => {
-      const sm = new SessionManager({ agentWindow: fakeAgentWindow() });
-      const ctx = await sm.start("aa11");
-      expect(ctx.agentCreatedTabs).toEqual(new Set([0]));
-      expect(isAgentControlledTab(ctx, 0)).toBe(true);
-    });
-
-    it("keeps every other tab free without classification state", async () => {
-      const sm = new SessionManager({ agentWindow: fakeAgentWindow() });
-      const ctx = await sm.start("aa11");
-      expect(isAgentControlledTab(ctx, 99)).toBe(false);
-      expect(ctx).not.toHaveProperty("userTabs");
-      expect(ctx).not.toHaveProperty("pendingAgentTabCount");
-    });
-
-    it("treats a committed borrow as an explicit claim", async () => {
-      const sm = new SessionManager({ agentWindow: fakeAgentWindow() });
-      const ctx = await sm.start("aa11");
-      const reservation = sm.tryReserveBorrow(42, ctx.sessionId);
-      if ("borrowedBy" in reservation) throw new Error("unexpected borrow conflict");
-      reservation.commit({ tabId: 42, originalWindowId: 7, originalIndex: 3 });
-      expect(isAgentControlledTab(ctx, 42)).toBe(true);
-    });
-
-    it("forgets an agent-created tab after Chrome removes it", async () => {
-      const sm = new SessionManager({ agentWindow: fakeAgentWindow() });
-      const ctx = await sm.start("aa11");
-      ctx.agentCreatedTabs.add(42);
-      sm.forgetClosedTab(42);
-      expect(ctx.agentCreatedTabs.has(42)).toBe(false);
-      expect(isAgentControlledTab(ctx, 0)).toBe(true);
-    });
-
-    it("forgets closed borrows idempotently without affecting other tabs or sessions", async () => {
-      const sm = new SessionManager({ agentWindow: fakeAgentWindow() });
-      const a = await sm.start("aa11");
-      const b = await sm.start("bb22");
-      a.borrowedTabs.set(42, { tabId: 42, originalWindowId: 7, originalIndex: 0 });
-      a.borrowedTabs.set(43, { tabId: 43, originalWindowId: 7, originalIndex: 1 });
-      b.borrowedTabs.set(44, { tabId: 44, originalWindowId: 8, originalIndex: 0 });
-
-      sm.forgetClosedTab(42);
-      sm.forgetClosedTab(42);
-      sm.forgetClosedTab(999);
-
-      expect(isAgentControlledTab(a, 42)).toBe(false);
-      expect(sm.findBorrowingSession(42, null)).toBeNull();
-      expect([...a.borrowedTabs.keys()]).toEqual([43]);
-      expect([...b.borrowedTabs.keys()]).toEqual([44]);
-      expect(sm.list()).toHaveLength(2);
-    });
-
-    it("prevents an in-flight borrow from reclaiming a closed tab", async () => {
-      const sm = new SessionManager({ agentWindow: fakeAgentWindow() });
-      const ctx = await sm.start("aa11");
-      const reservation = sm.tryReserveBorrow(42, ctx.sessionId);
-      if ("borrowedBy" in reservation) throw new Error("unexpected borrow conflict");
-
-      sm.forgetClosedTab(42);
-
-      expect(() =>
-        reservation.commit({ tabId: 42, originalWindowId: 7, originalIndex: 0 }),
-      ).toThrow(/reservation disappeared/);
-      reservation.release();
-      expect(sm.findBorrowingSession(42, null)).toBeNull();
-      expect(ctx.borrowedTabs.has(42)).toBe(false);
-    });
-  });
-
   describe("findBorrowingSession", () => {
     it("returns null when no session has borrowed the tab", async () => {
       const sm = new SessionManager({ agentWindow: fakeAgentWindow() });

apps/extension/src/session-manager/agent-window.ts

@@ -14,11 +14,8 @@ export interface AgentWindowApi {
    * Guarantee the Agent Window has an active, CDP-navigable tab.
    * `chrome://` pages (including the New Tab page) reject `Page.navigate`,
    * so sessions bootstrap with `about:blank` instead.
-   *
-   * Resolves with the id of the activated (or newly created) tab, so callers
-   * can track the session's home tab without re-querying Chrome.
    */
-  ensureActiveTab(windowId: number, url: string): Promise<number>;
+  ensureActiveTab(windowId: number, url: string): Promise<void>;
 }
 
 /** Creation hints for a new Agent Window. */
@@ -52,19 +49,15 @@ export const chromeAgentWindowApi: AgentWindowApi = {
     // cancellation success while the Agent Window remains open.
     await chrome.windows.remove(windowId);
   },
-  async ensureActiveTab(windowId: number, url: string): Promise<number> {
+  async ensureActiveTab(windowId: number, url: string): Promise<void> {
     const tabs = await chrome.tabs.query({ windowId });
     const first = tabs.find((t) => typeof t.id === "number");
-    if (first?.id !== undefined) {
+    if (first?.id) {
       if (!first.active) {
         await chrome.tabs.update(first.id, { active: true });
       }
-      return first.id;
+      return;
     }
-    const created = await chrome.tabs.create({ windowId, url, active: true });
-    if (typeof created?.id !== "number") {
-      throw new Error("[bh] chrome.tabs.create returned no tab id");
-    }
-    return created.id;
+    await chrome.tabs.create({ windowId, url, active: true });
   },
 };

apps/extension/src/session-manager/manager.ts

@@ -6,20 +6,9 @@ export interface SessionContext {
   agentWindowId: number;
   refStore: RefStore;
   borrowedTabs: Map<number, BorrowedTab>;
-  /**
-   * Tabs explicitly claimed by the agent because it created them. This
-   * includes the Agent Window's home tab and tabs created by `tool.tab_create`.
-   * Tabs opened through Chrome UI never enter this set.
-   */
-  agentCreatedTabs: Set<number>;
   createdAtMs: number;
 }
 
-/** Whether this session has explicitly claimed control of `tabId`. */
-export function isAgentControlledTab(ctx: SessionContext, tabId: number): boolean {
-  return ctx.agentCreatedTabs.has(tabId) || ctx.borrowedTabs.has(tabId);
-}
-
 export interface BorrowedTab {
   tabId: number;
   originalWindowId: number;
@@ -117,19 +106,6 @@ export class SessionManager {
     return Array.from(this.sessions.values());
   }
 
-  /**
-   * Forget a tab Chrome has removed, including any uncommitted borrow.
-   * Whole-window closures keep committed borrows until the window-removed
-   * handler reports which user tabs could not be returned.
-   */
-  forgetClosedTab(tabId: number, { isWindowClosing = false } = {}): void {
-    this.borrowReservations.delete(tabId);
-    for (const ctx of this.sessions.values()) {
-      ctx.agentCreatedTabs.delete(tabId);
-      if (!isWindowClosing) ctx.borrowedTabs.delete(tabId);
-    }
-  }
-
   /**
    * Look up whether `tabId` is currently borrowed by some *other*
    * session than the one calling. Used by M8 `tab_borrow` to refuse
@@ -203,7 +179,7 @@ export class SessionManager {
       const { signal: _signal, ...createOptions } = opts;
       windowId = await this.agentWindow.create(AGENT_WINDOW_HOME, createOptions);
       throwIfSessionStartAborted(opts.signal);
-      const homeTabId = await this.agentWindow.ensureActiveTab(windowId, AGENT_WINDOW_HOME);
+      await this.agentWindow.ensureActiveTab(windowId, AGENT_WINDOW_HOME);
       throwIfSessionStartAborted(opts.signal);
 
       const ctx: SessionContext = {
@@ -211,10 +187,6 @@ export class SessionManager {
         agentWindowId: windowId,
         refStore: new RefStore(),
         borrowedTabs: new Map(),
-        // The home tab is the session's first explicit claim. Every other
-        // tab remains free until `tab_create` or `tab_borrow` identifies it
-        // by its concrete Chrome tab id.
-        agentCreatedTabs: new Set([homeTabId]),
         createdAtMs: this.now(),
       };
       this.sessions.set(sessionId, ctx);

apps/extension/src/tools/__tests__/console.test.ts

@@ -13,7 +13,7 @@ function fakeAgentWindow(ids: number[]) {
       return id;
     }),
     remove: vi.fn(async () => {}),
-    ensureActiveTab: vi.fn(async () => 1),
+    ensureActiveTab: vi.fn(async () => {}),
   };
 }
 

apps/extension/src/tools/__tests__/dispatcher.test.ts

@@ -49,13 +49,54 @@ describe("ToolDispatcher", () => {
     vi.unstubAllGlobals();
   });
 
+  it.each([
+    "tool.snapshot",
+    "tool.evaluate",
+    "tool.get_html",
+    "tool.console",
+  ])("annotates Chrome extension-access failures from %s", async (method) => {
+    const tab = { id: 7, windowId: 4242, active: true, url: "https://example.test" };
+    vi.stubGlobal("chrome", {
+      tabs: {
+        get: vi.fn(async () => tab),
+        query: vi.fn(async () => [tab]),
+      },
+    });
+    const { transport, sent, deliver } = fakeTransport();
+    const sessions = new SessionManager({
+      agentWindow: {
+        create: vi.fn(async () => 4242),
+        remove: vi.fn(),
+        ensureActiveTab: vi.fn(),
+      },
+    });
+    await sessions.start("test");
+    const error = new Error("Cannot access a chrome-extension:// URL of different extension");
+    const cdp = {
+      send: vi.fn().mockRejectedValue(error),
+      ensureConsoleCapture: vi.fn().mockRejectedValue(error),
+      consoleEntriesSince: vi.fn(),
+    } as unknown as TestDispatcherCdp;
+    const dispatcher = new ToolDispatcher({ transport, sessions, cdp });
+    dispatcher.start();
+    deliver(makeRequest(method, { session_id: "test", expression: "document.title" }));
+    await vi.waitFor(() => expect(sent).toHaveLength(1));
+    expect(sent[0]).toMatchObject({
+      error: {
+        code: "cdp_failed",
+        data: { reason: "cdp_extension_access_denied" },
+      },
+    });
+    dispatcher.stop();
+  });
+
   it("uses the configured recording runtime for start and stop", async () => {
     const { transport, sent, deliver } = fakeTransport();
     const sessions = new SessionManager({
       agentWindow: {
         create: vi.fn(async () => 4242),
         remove: vi.fn(),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
       },
     });
     await sessions.start("aa11");
@@ -117,7 +158,7 @@ describe("ToolDispatcher", () => {
       agentWindow: {
         create: vi.fn(async () => 4242),
         remove: vi.fn(),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
       },
     });
     const dispatcher = new ToolDispatcher({ transport, sessions });
@@ -140,7 +181,7 @@ describe("ToolDispatcher", () => {
       agentWindow: {
         create,
         remove: vi.fn(),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
       },
     });
     const dispatcher = new ToolDispatcher({ transport, sessions });
@@ -158,7 +199,7 @@ describe("ToolDispatcher", () => {
       agentWindow: {
         create: vi.fn(async () => 4242),
         remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
       },
     });
     await sessions.start("aa11");
@@ -172,47 +213,6 @@ describe("ToolDispatcher", () => {
     expect(sent[0]).toEqual({ id: "r-1", result: {} });
   });
 
-  it("wires the production tab APIs into tool.session_stop so a surviving user tab releases the window", async () => {
-    // Regression guard for the deps that session_stop reads directly: when
-    // `tabManagement.tabs` / `tabsQuery` are not injected by the dispatcher,
-    // the agent-tab cleanup and the release decision silently no-op and the
-    // Agent Window is closed even though a user tab is still open (issue #57).
-    const removeTab = vi.fn(async () => {});
-    const closeWindow = vi.fn(async () => {});
-    // After cleanup the window still holds one tab (id 99) that is neither
-    // the home tab nor an agent-created tab — i.e. a genuine user tab.
-    vi.stubGlobal("chrome", {
-      tabs: {
-        remove: removeTab,
-        query: vi.fn(async () => [{ id: 99, windowId: 4242, active: true }]),
-      },
-    });
-    const { transport, sent, deliver } = fakeTransport();
-    const sessions = new SessionManager({
-      agentWindow: {
-        create: vi.fn(async () => 4242),
-        remove: closeWindow,
-        ensureActiveTab: vi.fn(async () => 1),
-      },
-    });
-    await sessions.start("aa11");
-    // Register the exact tab id returned by the agent's creation path.
-    sessions.get("aa11")?.agentCreatedTabs.add(7);
-
-    const dispatcher = new ToolDispatcher({ transport, sessions });
-    dispatcher.start();
-
-    deliver(makeRequest("tool.session_stop", { session_id: "aa11" }));
-    await flushMicrotasks();
-
-    // The agent tab is closed through the real chrome.tabs surface...
-    expect(removeTab).toHaveBeenCalledWith(7);
-    // ...and the window is released rather than closed, so the user's tab survives.
-    expect(closeWindow).not.toHaveBeenCalled();
-    expect(sessions.has("aa11")).toBe(false);
-    expect(sent[0]).toEqual({ id: "r-1", result: { window_released: true } });
-  });
-
   it("routes tool.console through the CDP console buffer", async () => {
     vi.stubGlobal("chrome", {
       tabs: {
@@ -224,7 +224,7 @@ describe("ToolDispatcher", () => {
       agentWindow: {
         create: vi.fn(async () => 4242),
         remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
       },
     });
     await sessions.start("aa11");
@@ -287,7 +287,7 @@ describe("ToolDispatcher", () => {
       agentWindow: {
         create: vi.fn(async () => 4242),
         remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
       },
     });
     const ctx = await sessions.start("aa11");
@@ -380,7 +380,7 @@ describe("ToolDispatcher", () => {
       agentWindow: {
         create: vi.fn(async () => 4242),
         remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
       },
     });
     await sessions.start("aa11");
@@ -416,7 +416,7 @@ describe("ToolDispatcher", () => {
       agentWindow: {
         create: vi.fn(async () => 4242),
         remove,
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
       },
     });
     await sessions.start("aa11");
@@ -464,7 +464,7 @@ describe("ToolDispatcher", () => {
       agentWindow: {
         create: vi.fn(async () => 1),
         remove: vi.fn(),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
       },
     });
     const dispatcher = new ToolDispatcher({ transport, sessions });
@@ -484,7 +484,7 @@ describe("ToolDispatcher", () => {
       agentWindow: {
         create: vi.fn(async () => 1),
         remove: vi.fn(),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
       },
     });
     const dispatcher = new ToolDispatcher({ transport, sessions });
@@ -508,7 +508,7 @@ describe("ToolDispatcher", () => {
       agentWindow: {
         create: vi.fn(async () => 1),
         remove: vi.fn(),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
       },
     });
     const dispatcher = new ToolDispatcher({ transport, sessions });
@@ -525,7 +525,7 @@ describe("ToolDispatcher", () => {
       agentWindow: {
         create: vi.fn(async () => 1),
         remove: vi.fn(),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
       },
     });
     const dispatcher = new ToolDispatcher({ transport, sessions });
@@ -542,7 +542,7 @@ describe("ToolDispatcher", () => {
       agentWindow: {
         create: vi.fn(async () => 1),
         remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
       },
     });
     const onSessionsChanged = vi.fn();
@@ -559,32 +559,16 @@ describe("ToolDispatcher", () => {
   });
 
   it("invokes onBrowserControlResumed for browser-control tools but not passive reads", async () => {
-    vi.stubGlobal("chrome", {
-      tabs: {
-        create: vi.fn(async (props: chrome.tabs.CreateProperties) => ({
-          id: 7,
-          windowId: props.windowId,
-          url: props.url,
-          active: props.active,
-        })),
-      },
-    });
     const { transport, sent, deliver } = fakeTransport();
     const sessions = new SessionManager({
       agentWindow: {
         create: vi.fn(async () => 1),
         remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
       },
     });
     const onBrowserControlResumed = vi.fn();
-    const onAgentTabClaimed = vi.fn();
-    const dispatcher = new ToolDispatcher({
-      transport,
-      sessions,
-      onBrowserControlResumed,
-      onAgentTabClaimed,
-    });
+    const dispatcher = new ToolDispatcher({ transport, sessions, onBrowserControlResumed });
     dispatcher.start();
 
     deliver(makeRequest("tool.session_start", { session_id: "aa11" }));
@@ -601,7 +585,6 @@ describe("ToolDispatcher", () => {
     });
     await flushMicrotasks();
     expect(onBrowserControlResumed).toHaveBeenCalledWith("aa11");
-    expect(onAgentTabClaimed).toHaveBeenCalledWith(7, 1);
   });
 
   it("reasserts remembered hover before follow-up work and releases only after actions", async () => {
@@ -615,7 +598,7 @@ describe("ToolDispatcher", () => {
       agentWindow: {
         create: vi.fn(async () => 1),
         remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
       },
     });
     const order: string[] = [];
@@ -697,7 +680,7 @@ describe("ToolDispatcher", () => {
       agentWindow: {
         create: vi.fn(async () => 1),
         remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
       },
     });
     const cdp = {
@@ -758,7 +741,7 @@ describe("ToolDispatcher", () => {
       agentWindow: {
         create: vi.fn(async () => 1),
         remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
       },
     });
     const dispatcher = new ToolDispatcher({ transport, sessions });
@@ -795,7 +778,7 @@ describe("ToolDispatcher", () => {
       agentWindow: {
         create: vi.fn(async () => 4242),
         remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
       },
     });
     await sessions.start("aa11");
@@ -847,7 +830,7 @@ describe("ToolDispatcher", () => {
       agentWindow: {
         create: vi.fn(async () => 1),
         remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
       },
     });
     const dispatcher = new ToolDispatcher({ transport, sessions });
@@ -881,7 +864,7 @@ describe("ToolDispatcher", () => {
       agentWindow: {
         create: vi.fn(async () => 4242),
         remove: vi.fn(),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
       },
     });
     transport.send = () => {
@@ -903,7 +886,7 @@ describe("ToolDispatcher", () => {
       agentWindow: {
         create: vi.fn(async () => 5555),
         remove,
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
       },
     });
     transport.send = () => {
@@ -931,7 +914,7 @@ describe("ToolDispatcher", () => {
       agentWindow: {
         create: vi.fn(() => createPromise),
         remove: vi.fn(async () => {}),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
       },
     });
     const dispatcher = new ToolDispatcher({ transport, sessions });
@@ -982,7 +965,7 @@ describe("ToolDispatcher", () => {
       agentWindow: {
         create: vi.fn(async () => 1),
         remove: vi.fn(),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
       },
     });
     const dispatcher = new ToolDispatcher({ transport, sessions });
@@ -1003,7 +986,7 @@ describe("ToolDispatcher", () => {
       agentWindow: {
         create: vi.fn(() => createPromise),
         remove: vi.fn(),
-        ensureActiveTab: vi.fn(async () => 1),
+        ensureActiveTab: vi.fn(async () => {}),
       },
     });
     const dispatcher = new ToolDispatcher({ transport, sessions });

apps/extension/src/tools/__tests__/emulate.test.ts

@@ -20,7 +20,7 @@ function fakeAgentWindow(ids: number[]) {
       return id;
     }),
     remove: vi.fn(async () => {}),
-    ensureActiveTab: vi.fn(async () => 1),
+    ensureActiveTab: vi.fn(async () => {}),
   };
 }
 

apps/extension/src/tools/__tests__/errors.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from "vitest";
+import type { RpcError } from "@/transport/types";
+import { cdpError, classifyCdpError } from "../errors";
+
+const denied = "Cannot access a chrome-extension:// URL of different extension";
+
+describe("CDP extension access errors", () => {
+  it("classifies both Chrome Error instances and string failures", () => {
+    for (const error of [new Error(denied), denied]) {
+      expect(cdpError(error)).toEqual({
+        code: "cdp_failed",
+        message: denied,
+        data: { reason: "cdp_extension_access_denied" },
+      });
+    }
+  });
+
+  it("preserves transfer outcome and cleanup instructions when CDP was denied", () => {
+    const error: RpcError = {
+      code: "cdp_failed",
+      message: denied,
+      data: {
+        reason: "transfer_outcome_unknown",
+        effect_state: "unknown",
+        cleanup_state: "failed",
+      },
+    };
+    expect(classifyCdpError(error)).toBe(error);
+  });
+
+  it("leaves other error codes and unrelated debugger failures unchanged", () => {
+    for (const error of [
+      { code: "permission_denied", message: denied },
+      { code: "cdp_failed", message: "Another debugger is already attached" },
+    ] satisfies RpcError[]) {
+      expect(classifyCdpError(error)).toBe(error);
+    }
+  });
+});

apps/extension/src/tools/__tests__/evaluate.test.ts

@@ -12,7 +12,7 @@ function fakeAgentWindow(ids: number[]) {
       return id;
     }),
     remove: vi.fn(async () => {}),
-    ensureActiveTab: vi.fn(async () => 1),
+    ensureActiveTab: vi.fn(async () => {}),
   };
 }
 

apps/extension/src/tools/__tests__/file-transfer.test.ts

@@ -13,7 +13,7 @@ function sessions() {
     agentWindow: {
       create: vi.fn(async () => 100),
       remove: vi.fn(async () => {}),
-      ensureActiveTab: vi.fn(async () => 1),
+      ensureActiveTab: vi.fn(async () => {}),
     },
   });
 }

apps/extension/src/tools/__tests__/interaction.test.ts

@@ -21,7 +21,7 @@ function fakeAgentWindow(ids: number[]) {
       return id;
     }),
     remove: vi.fn(async () => {}),
-    ensureActiveTab: vi.fn(async () => 1),
+    ensureActiveTab: vi.fn(async () => {}),
   };
 }
 

apps/extension/src/tools/__tests__/navigation-recovery.test.ts

@@ -0,0 +1,266 @@
+import { describe, expect, it, vi } from "vitest";
+import { SessionManager } from "@/session-manager/manager";
+import type { BrowserNavigationApi } from "../browser-navigation";
+import { handleNavigate, handleReload } from "../navigation";
+import type { CdpRunner } from "../shared";
+
+const denied = "Cannot access a chrome-extension:// URL of different extension";
+const url = "https://example.test/recovered";
+
+function event<T extends (...args: never[]) => void>() {
+  const listeners = new Set<T>();
+  return {
+    listeners,
+    addListener: (listener: T) => listeners.add(listener),
+    removeListener: (listener: T) => listeners.delete(listener),
+    fire: (...args: Parameters<T>) => {
+      for (const listener of [...listeners]) listener(...args);
+    },
+  };
+}
+
+async function fixture() {
+  const manager = new SessionManager({
+    agentWindow: {
+      create: vi.fn(async () => 100),
+      remove: vi.fn(async () => {}),
+      ensureActiveTab: vi.fn(async () => {}),
+    },
+  });
+  await manager.start("test");
+  type Listener = Parameters<BrowserNavigationApi["onCommitted"]["addListener"]>[0];
+  const events = {
+    onCommitted: event<Listener>(),
+    onDOMContentLoaded: event<Listener>(),
+    onCompleted: event<Listener>(),
+    onErrorOccurred: event<Listener>(),
+  };
+  const cdpEvents = event<Parameters<NonNullable<CdpRunner["onEvent"]>>[0]>();
+  const state = { blocked: true, destinationBlocked: false, emitIdle: true };
+  const send = vi.fn(async (_tabId: number, method: string) => {
+    if (state.blocked) throw new Error(denied);
+    if (method === "Page.getFrameTree") {
+      return { frameTree: { frame: { id: "main", loaderId: "new-loader" } } };
+    }
+    if (method === "Runtime.evaluate") return { result: { value: "complete" } };
+    if (method === "Page.setLifecycleEventsEnabled" && state.emitIdle) {
+      cdpEvents.fire({ tabId: 4 }, "Page.lifecycleEvent", {
+        frameId: "main",
+        loaderId: "new-loader",
+        name: "networkIdle",
+      });
+    }
+    if (method === "Page.navigate") return { frameId: "main", loaderId: "new-loader" };
+    return {};
+  });
+  const cdp: CdpRunner = {
+    send: send as CdpRunner["send"],
+    onEvent: (listener) => {
+      cdpEvents.addListener(listener);
+      return { dispose: () => cdpEvents.removeListener(listener) };
+    },
+  };
+  const main = { tabId: 4, frameId: 0, documentId: "new-document" };
+  const navigate = async () => {
+    state.blocked = state.destinationBlocked;
+    events.onCommitted.fire(main);
+    events.onDOMContentLoaded.fire(main);
+    events.onCompleted.fire(main);
+  };
+  const browserNavigation = { ...events, update: vi.fn(navigate), reload: vi.fn(navigate) };
+  const tab = { id: 4, windowId: 100, active: true, url } as chrome.tabs.Tab;
+  const tabsApi = { get: vi.fn(async () => tab), query: vi.fn(async () => [tab]) };
+  const deps = { cdp, tabsApi, browserNavigation, defaultTimeoutMs: 1000 };
+  const expectCleanedUp = () => {
+    for (const entry of Object.values(events)) expect(entry.listeners.size).toBe(0);
+    expect(cdpEvents.listeners.size).toBe(0);
+  };
+  return { manager, deps, state, send, events, main, cdpEvents, expectCleanedUp };
+}
+
+describe("navigation after Chrome denies extension-frame access", () => {
+  it.each([
+    "load",
+    "commit",
+    "domcontentloaded",
+    "networkidle",
+  ] as const)("recovers the same tab with the requested %s checkpoint", async (waitUntil) => {
+    const f = await fixture();
+    const result = await handleNavigate(
+      f.manager,
+      {
+        session_id: "test",
+        url,
+        wait_until: waitUntil,
+      },
+      f.deps,
+    );
+
+    expect(result).toMatchObject({ tab_id: 4, final_url: url, reached: waitUntil });
+    expect(f.deps.browserNavigation.update).toHaveBeenCalledExactlyOnceWith(4, { url });
+    expect(f.send.mock.calls.some(([, method]) => method === "Page.navigate")).toBe(false);
+    expect(f.send).toHaveBeenCalledWith(4, "Page.enable", {});
+    f.expectCleanedUp();
+  });
+
+  it("recovers reload through tabs.reload and preserves hard reload", async () => {
+    const f = await fixture();
+    const result = await handleReload(f.manager, { session_id: "test", hard: true }, f.deps);
+    expect(result).toMatchObject({ tab_id: 4, reached: "load" });
+    expect(f.deps.browserNavigation.reload).toHaveBeenCalledExactlyOnceWith(4, {
+      bypassCache: true,
+    });
+    expect(f.deps.browserNavigation.update).not.toHaveBeenCalled();
+    f.expectCleanedUp();
+  });
+
+  it("reports the restriction when reload leaves the conflicting frame present", async () => {
+    const f = await fixture();
+    f.state.destinationBlocked = true;
+    const result = await handleReload(f.manager, { session_id: "test" }, f.deps);
+    expect(result).toMatchObject({
+      code: "cdp_failed",
+      data: { reason: "cdp_extension_access_denied" },
+    });
+    expect(f.deps.browserNavigation.reload).toHaveBeenCalledOnce();
+    f.expectCleanedUp();
+  });
+
+  it("does not fall back for unrelated debugger failures", async () => {
+    const f = await fixture();
+    f.send.mockRejectedValue(new Error("Another debugger is already attached"));
+    const result = await handleNavigate(f.manager, { session_id: "test", url }, f.deps);
+    expect(result).toMatchObject({
+      code: "cdp_failed",
+      message: "Another debugger is already attached",
+    });
+    expect(f.deps.browserNavigation.update).not.toHaveBeenCalled();
+    f.expectCleanedUp();
+  });
+
+  it("does not replay navigation when a dispatched CDP command fails", async () => {
+    const f = await fixture();
+    f.state.blocked = false;
+    const send = f.send.getMockImplementation()!;
+    f.send.mockImplementation(async (tabId, method) => {
+      if (method === "Page.navigate") throw new Error(denied);
+      return send(tabId, method);
+    });
+    const result = await handleNavigate(f.manager, { session_id: "test", url }, f.deps);
+    expect(result).toMatchObject({
+      code: "cdp_failed",
+      data: { reason: "cdp_extension_access_denied" },
+    });
+    expect(f.deps.browserNavigation.update).not.toHaveBeenCalled();
+    f.expectCleanedUp();
+  });
+
+  it("keeps the Agent Window guard in front of the recovery", async () => {
+    const f = await fixture();
+    f.deps.tabsApi.get.mockResolvedValue({
+      id: 4,
+      windowId: 200,
+      active: true,
+      url,
+    } as chrome.tabs.Tab);
+    const result = await handleNavigate(f.manager, { session_id: "test", tab_id: 4, url }, f.deps);
+    expect(result).toMatchObject({ code: "permission_denied" });
+    expect(f.send).not.toHaveBeenCalled();
+    expect(f.deps.browserNavigation.update).not.toHaveBeenCalled();
+  });
+
+  it("ignores old-document, subframe, and other-tab completion events", async () => {
+    const f = await fixture();
+    f.deps.browserNavigation.update.mockImplementation(async () => {});
+    let settled = false;
+    const work = handleNavigate(f.manager, { session_id: "test", url }, f.deps).then((result) => {
+      settled = true;
+      return result;
+    });
+    await vi.waitFor(() => expect(f.deps.browserNavigation.update).toHaveBeenCalledOnce());
+    f.events.onCompleted.fire(f.main);
+    f.events.onCommitted.fire({ ...f.main, tabId: 9 });
+    f.events.onCommitted.fire({ ...f.main, frameId: 1 });
+    f.events.onCompleted.fire(f.main);
+    await Promise.resolve();
+    expect(settled).toBe(false);
+    f.events.onCommitted.fire(f.main);
+    f.events.onCompleted.fire({ ...f.main, documentId: "old-document" });
+    await Promise.resolve();
+    expect(settled).toBe(false);
+    f.state.blocked = false;
+    f.events.onCompleted.fire(f.main);
+    expect(await work).toMatchObject({ reached: "load" });
+    f.expectCleanedUp();
+  });
+
+  it("does not infer network idle from a browser load event", async () => {
+    const f = await fixture();
+    f.state.emitIdle = false;
+    const result = await handleNavigate(
+      f.manager,
+      {
+        session_id: "test",
+        url,
+        wait_until: "networkidle",
+        timeout_ms: 10,
+      },
+      f.deps,
+    );
+    expect(result).toMatchObject({ reached: "timeout" });
+    f.expectCleanedUp();
+  });
+
+  it("cleans up browser listeners on timeout", async () => {
+    const f = await fixture();
+    f.deps.browserNavigation.update.mockImplementation(async () => {});
+    const result = await handleNavigate(
+      f.manager,
+      { session_id: "test", url, timeout_ms: 10 },
+      f.deps,
+    );
+    expect(result).toMatchObject({ reached: "timeout" });
+    f.expectCleanedUp();
+  });
+
+  it("does not navigate an already-cancelled request", async () => {
+    const f = await fixture();
+    const result = await handleNavigate(
+      f.manager,
+      { session_id: "test", url },
+      {
+        ...f.deps,
+        signal: AbortSignal.abort(),
+      },
+    );
+    expect(result).toMatchObject({ code: "cancelled" });
+    expect(f.deps.browserNavigation.update).not.toHaveBeenCalled();
+    f.expectCleanedUp();
+  });
+
+  it("cleans up browser listeners when cancelled after dispatch", async () => {
+    const f = await fixture();
+    const ac = new AbortController();
+    f.deps.browserNavigation.update.mockImplementation(async () => {
+      ac.abort();
+    });
+    const result = await handleNavigate(
+      f.manager,
+      { session_id: "test", url },
+      { ...f.deps, signal: ac.signal },
+    );
+    expect(result).toMatchObject({ code: "cancelled" });
+    expect(f.deps.browserNavigation.update).toHaveBeenCalledOnce();
+    f.expectCleanedUp();
+  });
+
+  it("reports browser navigation errors and releases listeners", async () => {
+    const f = await fixture();
+    f.deps.browserNavigation.update.mockImplementation(async () => {
+      f.events.onErrorOccurred.fire({ ...f.main, error: "net::ERR_NAME_NOT_RESOLVED" });
+    });
+    const result = await handleNavigate(f.manager, { session_id: "test", url }, f.deps);
+    expect(result).toMatchObject({ code: "cdp_failed", message: "net::ERR_NAME_NOT_RESOLVED" });
+    f.expectCleanedUp();
+  });
+});

apps/extension/src/tools/__tests__/navigation.test.ts

@@ -21,7 +21,7 @@ function fakeAgentWindow(ids: number[]) {
       return id;
     }),
     remove: vi.fn(async () => {}),
-    ensureActiveTab: vi.fn(async () => 1),
+    ensureActiveTab: vi.fn(async () => {}),
   };
 }
 

apps/extension/src/tools/__tests__/network.test.ts

@@ -12,7 +12,7 @@ function fakeAgentWindow(ids: number[]) {
       return id;
     }),
     remove: vi.fn(async () => {}),
-    ensureActiveTab: vi.fn(async () => 1),
+    ensureActiveTab: vi.fn(async () => {}),
   };
 }
 

apps/extension/src/tools/__tests__/observation.test.ts

@@ -28,7 +28,7 @@ function fakeAgentWindow(ids: number[]) {
       return id;
     }),
     remove: vi.fn(async () => {}),
-    ensureActiveTab: vi.fn(async () => 1),
+    ensureActiveTab: vi.fn(async () => {}),
   };
 }
 

apps/extension/src/tools/__tests__/session.test.ts

@@ -1,26 +1,8 @@
 import { describe, expect, it, vi } from "vitest";
 import { SessionManager } from "@/session-manager/manager";
 import { handleSessionStop } from "../session";
-import type { ChromeTabsApi } from "../shared";
 import { type AgentOverlayResetApi, type ChromeWindowsApi, type TabMutationApi } from "../tabs";
 
-/** Build a read-only query api over a FakeState. */
-function makeQuery(state: FakeState): ChromeTabsApi {
-  return {
-    get: vi.fn(async (id) => {
-      const t = state.tabs.get(id);
-      if (!t) throw new Error(`tab ${id} not found`);
-      return t;
-    }),
-    query: vi.fn(async (q: chrome.tabs.QueryInfo) => {
-      const w = q.windowId;
-      return Array.from(state.tabs.values()).filter(
-        (t) => typeof w !== "number" || t.windowId === w,
-      );
-    }),
-  };
-}
-
 function fakeAgentWindow(ids: number[]) {
   let i = 0;
   const create = vi.fn(async () => {
@@ -29,7 +11,7 @@ function fakeAgentWindow(ids: number[]) {
     return id;
   });
   const remove = vi.fn(async () => {});
-  const ensureActiveTab = vi.fn(async () => 0);
+  const ensureActiveTab = vi.fn(async () => {});
   return { create, remove, ensureActiveTab };
 }
 
@@ -48,9 +30,7 @@ function makeApis(
 } {
   const tabs: TabMutationApi = {
     create: vi.fn(),
-    remove: vi.fn(async (id: number) => {
-      state.tabs.delete(id);
-    }),
+    remove: vi.fn(async () => {}),
     update: vi.fn(async (_id, _p) => undefined),
     get: vi.fn(async (id) => {
       const t = state.tabs.get(id);
@@ -287,275 +267,4 @@ describe("handleSessionStop with auto-return", () => {
     await handleSessionStop(sm, { session_id: "aa11" }, { tabManagement: { tabs, windows } });
     expect(ctx.refStore.isEmpty()).toBe(true);
   });
-
-  it.each([
-    "before teardown",
-    "during its return",
-    "after its return failed",
-    "before its turn in the return loop",
-  ])("finishes stopping when a borrowed tab closes %s", async (timing) => {
-    const aw = fakeAgentWindow([100]);
-    const sm = new SessionManager({ agentWindow: aw });
-    const ctx = await sm.start("aa11");
-    ctx.borrowedTabs.set(1, { tabId: 1, originalWindowId: 200, originalIndex: 0 });
-    ctx.borrowedTabs.set(2, { tabId: 2, originalWindowId: 200, originalIndex: 1 });
-    const state: FakeState = {
-      tabs: new Map([
-        [1, { id: 1, windowId: 100 } as chrome.tabs.Tab],
-        [2, { id: 2, windowId: 100 } as chrome.tabs.Tab],
-      ]),
-      windowsClosed: new Set(),
-      moves: [],
-    };
-    const { tabs, windows } = makeApis(state);
-    const cdp = { detachSession: vi.fn(async () => {}) };
-    const closeTab = (tabId: number) => {
-      state.tabs.delete(tabId);
-      sm.forgetClosedTab(tabId);
-    };
-    const baseMove = tabs.move;
-    tabs.move = vi.fn(async (tabId, props) => {
-      if (tabId === 1 && timing === "during its return") closeTab(1);
-      if (tabId === 1 && timing === "after its return failed") {
-        throw new Error("simulated move failure");
-      }
-      if (tabId === 2 && timing === "after its return failed") closeTab(1);
-      if (tabId === 1 && timing === "before its turn in the return loop") closeTab(2);
-      if (!state.tabs.has(tabId)) throw new Error(`tab ${tabId} not found`);
-      return baseMove(tabId, props);
-    });
-    if (timing === "before teardown") closeTab(1);
-
-    const res = await handleSessionStop(
-      sm,
-      { session_id: "aa11" },
-      {
-        cdp,
-        tabManagement: {
-          tabs,
-          windows,
-          agentOverlayReset: { resetAgentOverlays: vi.fn(async () => {}) },
-        },
-        tabsQuery: makeQuery(state),
-      },
-    );
-
-    if ("code" in res) throw new Error(`unexpected error: ${JSON.stringify(res)}`);
-    const closedTabId = timing === "before its turn in the return loop" ? 2 : 1;
-    expect(res.returned_tab_ids).toEqual([closedTabId === 1 ? 2 : 1]);
-    expect(res.return_failures).toBeUndefined();
-    expect(ctx.borrowedTabs.size).toBe(0);
-    expect(sm.has("aa11")).toBe(false);
-    expect(cdp.detachSession).toHaveBeenCalledWith("aa11");
-    expect(aw.remove).toHaveBeenCalledWith(100);
-    if (timing === "before teardown" || timing === "before its turn in the return loop") {
-      expect(tabs.move).not.toHaveBeenCalledWith(closedTabId, expect.anything());
-    }
-  });
-});
-
-describe("handleSessionStop window release (issue #57)", () => {
-  const agentWindowId = 100;
-
-  it("releases the window when user-created tabs remain", async () => {
-    const aw = fakeAgentWindow([agentWindowId]);
-    // ensureActiveTab returns the home tab id (10). We override the fake to
-    // return a known id.
-    aw.ensureActiveTab = vi.fn(async () => 10);
-    const sm = new SessionManager({ agentWindow: aw });
-    const ctx = await sm.start("aa11");
-    ctx.agentCreatedTabs.add(11);
-    ctx.agentCreatedTabs.add(12);
-    // user tab 99 (created via Chrome UI, NOT in agentCreatedTabs)
-    const state: FakeState = {
-      tabs: new Map([
-        [10, { id: 10, windowId: agentWindowId } as chrome.tabs.Tab],
-        [11, { id: 11, windowId: agentWindowId } as chrome.tabs.Tab],
-        [12, { id: 12, windowId: agentWindowId } as chrome.tabs.Tab],
-        [99, { id: 99, windowId: agentWindowId } as chrome.tabs.Tab],
-      ]),
-      windowsClosed: new Set(),
-      moves: [],
-    };
-    const { tabs, windows } = makeApis(state);
-    const query = makeQuery(state);
-
-    const res = await handleSessionStop(
-      sm,
-      { session_id: "aa11" },
-      { tabManagement: { tabs, windows }, tabsQuery: query },
-    );
-    if ("code" in res) throw new Error(`unexpected error: ${JSON.stringify(res)}`);
-    expect(res.window_released).toBe(true);
-    // agent tabs + home removed, user tab 99 kept
-    expect((tabs.remove as ReturnType<typeof vi.fn>).mock.calls.map((c) => c[0]).sort()).toEqual([
-      10, 11, 12,
-    ]);
-    expect(state.tabs.has(99)).toBe(true);
-    // window released (dropOnly), not closed
-    expect(aw.remove).not.toHaveBeenCalled();
-    expect(sm.has("aa11")).toBe(false);
-  });
-
-  it("closes the window (not release) when no user tabs remain", async () => {
-    const aw = fakeAgentWindow([agentWindowId]);
-    aw.ensureActiveTab = vi.fn(async () => 10);
-    const sm = new SessionManager({ agentWindow: aw });
-    const ctx = await sm.start("aa11");
-    ctx.agentCreatedTabs.add(11);
-    const state: FakeState = {
-      tabs: new Map([
-        [10, { id: 10, windowId: agentWindowId } as chrome.tabs.Tab],
-        [11, { id: 11, windowId: agentWindowId } as chrome.tabs.Tab],
-      ]),
-      windowsClosed: new Set(),
-      moves: [],
-    };
-    const { tabs, windows } = makeApis(state);
-    const query = makeQuery(state);
-
-    const res = await handleSessionStop(
-      sm,
-      { session_id: "aa11" },
-      { tabManagement: { tabs, windows }, tabsQuery: query },
-    );
-    if ("code" in res) throw new Error(`unexpected error: ${JSON.stringify(res)}`);
-    expect(res.window_released).toBeFalsy();
-    expect(aw.remove).toHaveBeenCalledWith(agentWindowId);
-    expect(sm.has("aa11")).toBe(false);
-  });
-
-  it("is non-fatal when an agent tab is already gone", async () => {
-    const aw = fakeAgentWindow([agentWindowId]);
-    aw.ensureActiveTab = vi.fn(async () => 10);
-    const sm = new SessionManager({ agentWindow: aw });
-    const ctx = await sm.start("aa11");
-    ctx.agentCreatedTabs.add(11); // no longer in state → remove throws
-    const state: FakeState = {
-      tabs: new Map([[10, { id: 10, windowId: agentWindowId } as chrome.tabs.Tab]]),
-      windowsClosed: new Set(),
-      moves: [],
-    };
-    const { tabs, windows } = makeApis(state);
-    (tabs.remove as ReturnType<typeof vi.fn>).mockImplementation(async (id: number) => {
-      if (id === 11) throw new Error("tab 11 already closed");
-      state.tabs.delete(id); // home (10) removed normally
-    });
-    const query = makeQuery(state);
-
-    const res = await handleSessionStop(
-      sm,
-      { session_id: "aa11" },
-      { tabManagement: { tabs, windows }, tabsQuery: query },
-    );
-    if ("code" in res) throw new Error(`unexpected error: ${JSON.stringify(res)}`);
-    // user tab 10? no — 10 is home, removed. window would be empty → close.
-    expect(res.window_released).toBeFalsy();
-    expect(aw.remove).toHaveBeenCalled();
-  });
-
-  it("degrades to close-window when tabsQuery is missing", async () => {
-    const aw = fakeAgentWindow([agentWindowId]);
-    aw.ensureActiveTab = vi.fn(async () => 10);
-    const sm = new SessionManager({ agentWindow: aw });
-    const ctx = await sm.start("aa11");
-    ctx.agentCreatedTabs.add(11);
-    const state: FakeState = {
-      tabs: new Map([
-        [10, { id: 10, windowId: agentWindowId } as chrome.tabs.Tab],
-        [11, { id: 11, windowId: agentWindowId } as chrome.tabs.Tab],
-      ]),
-      windowsClosed: new Set(),
-      moves: [],
-    };
-    const { tabs, windows } = makeApis(state);
-
-    const res = await handleSessionStop(
-      sm,
-      { session_id: "aa11" },
-      { tabManagement: { tabs, windows } }, // no tabsQuery
-    );
-    if ("code" in res) throw new Error(`unexpected error: ${JSON.stringify(res)}`);
-    // No query available → conservatively close the window.
-    expect(res.window_released).toBeFalsy();
-    expect(aw.remove).toHaveBeenCalledWith(agentWindowId);
-  });
-
-  it("degrades to close-window when tabsQuery.query throws", async () => {
-    const aw = fakeAgentWindow([agentWindowId]);
-    aw.ensureActiveTab = vi.fn(async () => 10);
-    const sm = new SessionManager({ agentWindow: aw });
-    const ctx = await sm.start("aa11");
-    ctx.agentCreatedTabs.add(11);
-    const state: FakeState = {
-      tabs: new Map([[11, { id: 11, windowId: agentWindowId } as chrome.tabs.Tab]]),
-      windowsClosed: new Set(),
-      moves: [],
-    };
-    const { tabs, windows } = makeApis(state);
-    const query = makeQuery(state);
-    (query.query as ReturnType<typeof vi.fn>).mockImplementation(async () => {
-      throw new Error("query failed");
-    });
-
-    const res = await handleSessionStop(
-      sm,
-      { session_id: "aa11" },
-      { tabManagement: { tabs, windows }, tabsQuery: query },
-    );
-    if ("code" in res) throw new Error(`unexpected error: ${JSON.stringify(res)}`);
-    expect(res.window_released).toBeFalsy();
-    expect(aw.remove).toHaveBeenCalled();
-  });
-
-  it("tracks agentCreatedTabs across tab_create / tab_close", async () => {
-    const aw = fakeAgentWindow([agentWindowId]);
-    aw.ensureActiveTab = vi.fn(async () => 10);
-    const sm = new SessionManager({ agentWindow: aw });
-    const ctx = await sm.start("aa11");
-    // Simulate handleTabCreate adding, then handleTabClose removing.
-    ctx.agentCreatedTabs.add(11);
-    expect(ctx.agentCreatedTabs.has(11)).toBe(true);
-    ctx.agentCreatedTabs.delete(11); // as handleTabClose does on success
-    expect(ctx.agentCreatedTabs.has(11)).toBe(false);
-    // Unknown id delete is a safe no-op (user-closed tab).
-    expect(() => ctx.agentCreatedTabs.delete(999)).not.toThrow();
-  });
-
-  it("closes the window (not release) when an agent tab fails to close", async () => {
-    // Regression: a leaked agent tab (still in agentCreatedTabs, but
-    // still present because Step 4 remove() threw) must NOT be mistaken
-    // for a user tab. Otherwise the window would be released (dropOnly)
-    // and the agent tab would leak (issue #57 regression).
-    const aw = fakeAgentWindow([agentWindowId]);
-    aw.ensureActiveTab = vi.fn(async () => 10);
-    const sm = new SessionManager({ agentWindow: aw });
-    const ctx = await sm.start("aa11");
-    ctx.agentCreatedTabs.add(11); // Step 4 remove() will throw for this tab
-    const state: FakeState = {
-      tabs: new Map([
-        [10, { id: 10, windowId: agentWindowId } as chrome.tabs.Tab],
-        [11, { id: 11, windowId: agentWindowId } as chrome.tabs.Tab],
-      ]),
-      windowsClosed: new Set(),
-      moves: [],
-    };
-    const { tabs, windows } = makeApis(state);
-    (tabs.remove as ReturnType<typeof vi.fn>).mockImplementation(async (id: number) => {
-      if (id === 11) throw new Error("tab 11 failed to close");
-      state.tabs.delete(id); // home (10) removed normally; 11 lingers
-    });
-    const query = makeQuery(state);
-
-    const res = await handleSessionStop(
-      sm,
-      { session_id: "aa11" },
-      { tabManagement: { tabs, windows }, tabsQuery: query },
-    );
-    if ("code" in res) throw new Error(`unexpected error: ${JSON.stringify(res)}`);
-    // The leaked agent tab must NOT keep the window open.
-    expect(res.window_released).toBeFalsy();
-    expect(aw.remove).toHaveBeenCalledWith(agentWindowId);
-    expect(sm.has("aa11")).toBe(false);
-  });
 });

apps/extension/src/tools/__tests__/shared.test.ts

@@ -12,7 +12,7 @@ function fakeAgentWindow() {
   return {
     create: vi.fn(async () => 100),
     remove: vi.fn(async () => {}),
-    ensureActiveTab: vi.fn(async () => 1),
+    ensureActiveTab: vi.fn(async () => {}),
   };
 }
 

apps/extension/src/tools/__tests__/snapshot-ref.test.ts

@@ -11,7 +11,7 @@ function fakeAgentWindow(ids: number[]) {
       return id;
     },
     remove: async () => {},
-    ensureActiveTab: async () => 1,
+    ensureActiveTab: async () => {},
   };
 }
 

apps/extension/src/tools/__tests__/tabs.test.ts

@@ -23,7 +23,7 @@ function fakeAgentWindow(ids: number[]) {
       return id;
     }),
     remove: vi.fn(async () => {}),
-    ensureActiveTab: vi.fn(async () => 1),
+    ensureActiveTab: vi.fn(async () => {}),
   };
 }
 
@@ -221,7 +221,6 @@ describe("handleTabCreate", () => {
       active: true,
     });
     expect(res).toMatchObject({ tab_id: 10, window_id: 100 });
-    expect(sm.get("aa11")?.agentCreatedTabs.has(10)).toBe(true);
   });
 
   it("forwards explicit url + index + active=false", async () => {
@@ -257,41 +256,6 @@ describe("handleTabCreate", () => {
     const res = await handleTabCreate(sm, { session_id: "aa11", index: -1 }, { tabs: api });
     expect(res).toMatchObject({ code: "invalid_params" });
   });
-
-  it("does not claim any tab when chrome.tabs.create fails", async () => {
-    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-    await sm.start("aa11");
-    const state: FakeTabState = { tabs: new Map(), nextTabId: 10, windowsClosed: new Set() };
-    const { api, spies } = makeTabMutationApi(state);
-    spies.create.mockRejectedValueOnce(new Error("chrome.tabs.create failed"));
-
-    const res = await handleTabCreate(sm, { session_id: "aa11" }, { tabs: api });
-    expect(res).toMatchObject({ code: "protocol_error" });
-
-    expect(sm.get("aa11")?.agentCreatedTabs).toEqual(new Set([1]));
-  });
-
-  it("claims the returned id even when a user tab appears during tab creation", async () => {
-    const sm = new SessionManager({ agentWindow: fakeAgentWindow([100]) });
-    const ctx = await sm.start("aa11");
-    const state: FakeTabState = { tabs: new Map(), nextTabId: 10, windowsClosed: new Set() };
-    const { api, spies } = makeTabMutationApi(state);
-    let resolveCreate!: (tab: chrome.tabs.Tab) => void;
-    const createResult = new Promise<chrome.tabs.Tab>((resolve) => {
-      resolveCreate = resolve;
-    });
-    spies.create.mockImplementationOnce(() => createResult);
-
-    const pending = handleTabCreate(sm, { session_id: "aa11" }, { tabs: api });
-    // A user can create an unrelated same-window tab while Chrome is still
-    // resolving the agent request. There is no pending slot for it to steal.
-    expect(ctx.agentCreatedTabs.has(99)).toBe(false);
-    resolveCreate({ id: 10, windowId: 100, active: true } as chrome.tabs.Tab);
-
-    await expect(pending).resolves.toMatchObject({ tab_id: 10 });
-    expect(ctx.agentCreatedTabs.has(10)).toBe(true);
-    expect(ctx.agentCreatedTabs.has(99)).toBe(false);
-  });
 });
 
 describe("handleTabClose", () => {

apps/extension/src/tools/__tests__/waits.test.ts

@@ -12,7 +12,7 @@ function fakeAgentWindow(ids: number[]) {
       return id;
     }),
     remove: vi.fn(async () => {}),
-    ensureActiveTab: vi.fn(async () => 1),
+    ensureActiveTab: vi.fn(async () => {}),
   };
 }
 

apps/extension/src/tools/__tests__/window.test.ts

@@ -11,7 +11,7 @@ function fakeAgentWindow(ids: number[]) {
     return id;
   });
   const remove = vi.fn(async () => {});
-  const ensureActiveTab = vi.fn(async () => 1);
+  const ensureActiveTab = vi.fn(async () => {});
   return { create, remove, ensureActiveTab };
 }
 

apps/extension/src/tools/browser-navigation.ts

@@ -0,0 +1,110 @@
+import type { RpcError, WaitUntil } from "@/transport/types";
+import { cdpError } from "./errors";
+
+interface NavigationEvent {
+  tabId: number;
+  frameId: number;
+  documentId?: string;
+  error?: string;
+}
+
+interface NavigationEvents {
+  addListener(listener: (details: NavigationEvent) => void): void;
+  removeListener(listener: (details: NavigationEvent) => void): void;
+}
+
+/** Normal browser navigation remains available when chrome.debugger is denied. */
+export interface BrowserNavigationApi {
+  update(tabId: number, props: { url: string }): Promise<unknown>;
+  reload(tabId: number, props: { bypassCache: boolean }): Promise<void>;
+  onCommitted: NavigationEvents;
+  onDOMContentLoaded: NavigationEvents;
+  onCompleted: NavigationEvents;
+  onErrorOccurred: NavigationEvents;
+}
+
+export const chromeBrowserNavigationApi: BrowserNavigationApi = {
+  update: (tabId, props) => chrome.tabs.update(tabId, props),
+  reload: (tabId, props) => chrome.tabs.reload(tabId, props),
+  get onCommitted() {
+    return chrome.webNavigation.onCommitted;
+  },
+  get onDOMContentLoaded() {
+    return chrome.webNavigation.onDOMContentLoaded;
+  },
+  get onCompleted() {
+    return chrome.webNavigation.onCompleted;
+  },
+  get onErrorOccurred() {
+    return chrome.webNavigation.onErrorOccurred;
+  },
+};
+
+export type NavigationOutcome =
+  | { reached: "match" | "timeout" | "cancelled"; lastLifecycle?: string }
+  | { reached: "failed"; error: RpcError };
+
+/** Subscribe before dispatch and ignore the departing document's load events. */
+export async function navigateWithBrowserApi(
+  api: BrowserNavigationApi,
+  tabId: number,
+  action: () => Promise<unknown>,
+  waitUntil: Exclude<WaitUntil, "networkidle">,
+  timeoutMs: number,
+  signal?: AbortSignal,
+): Promise<NavigationOutcome> {
+  if (signal?.aborted) return { reached: "cancelled" };
+  if (timeoutMs <= 0) return { reached: "timeout" };
+  let committed = false;
+  let documentId: string | undefined;
+  let lastLifecycle: string | undefined;
+  let finish!: (outcome: NavigationOutcome) => void;
+  const outcome = new Promise<NavigationOutcome>((resolve) => {
+    finish = resolve;
+  });
+  const isMainFrame = (details: NavigationEvent) =>
+    details.tabId === tabId && details.frameId === 0;
+  const onCommitted = (details: NavigationEvent) => {
+    if (!isMainFrame(details)) return;
+    committed = true;
+    documentId = details.documentId;
+    lastLifecycle = "commit";
+    if (waitUntil === "commit") finish({ reached: "match", lastLifecycle });
+  };
+  const onDOMContentLoaded = (details: NavigationEvent) => {
+    if (!isMainFrame(details) || !committed || (documentId && details.documentId !== documentId))
+      return;
+    lastLifecycle = "DOMContentLoaded";
+    if (waitUntil === "domcontentloaded") finish({ reached: "match", lastLifecycle });
+  };
+  const onCompleted = (details: NavigationEvent) => {
+    if (!isMainFrame(details) || !committed || (documentId && details.documentId !== documentId))
+      return;
+    finish({ reached: "match", lastLifecycle: "load" });
+  };
+  const onError = (details: NavigationEvent) => {
+    if (!isMainFrame(details)) return;
+    finish({ reached: "failed", error: cdpError(details.error ?? "browser navigation failed") });
+  };
+  const onAbort = () => finish({ reached: "cancelled", lastLifecycle });
+  const subscriptions = [
+    [api.onCommitted, onCommitted],
+    [api.onDOMContentLoaded, onDOMContentLoaded],
+    [api.onCompleted, onCompleted],
+    [api.onErrorOccurred, onError],
+  ] as const;
+  for (const [event, listener] of subscriptions) event.addListener(listener);
+  signal?.addEventListener("abort", onAbort, { once: true });
+  const timer = setTimeout(() => finish({ reached: "timeout", lastLifecycle }), timeoutMs);
+  try {
+    if (signal?.aborted) return { reached: "cancelled" };
+    await action();
+    return await outcome;
+  } catch (error) {
+    return { reached: "failed", error: cdpError(error) };
+  } finally {
+    clearTimeout(timer);
+    signal?.removeEventListener("abort", onAbort);
+    for (const [event, listener] of subscriptions) event.removeListener(listener);
+  }
+}

apps/extension/src/tools/dispatcher.ts

@@ -36,6 +36,7 @@ import { isRequestFrame } from "@/transport/types";
 import { handleConsole } from "./console";
 import { handleDownload } from "./download";
 import { type EmulateCdpRunner, handleEmulate } from "./emulate";
+import { classifyCdpError } from "./errors";
 import { handleEvaluate } from "./evaluate";
 import { handleRequestHelp } from "./human-loop";
 import { handleClick, handleFill, handleHover, handlePress, handleSelect } from "./interaction";
@@ -69,7 +70,6 @@ import {
 import { chromeTabsApi, lookupSession, resolveTargetTab } from "./shared";
 import {
   type BorrowConfirmationApprover,
-  chromeTabMutationApi,
   handleTabBorrow,
   handleTabClose,
   handleTabCreate,
@@ -119,8 +119,6 @@ export interface DispatcherDeps {
   onSessionsChanged?: () => void;
   /** Invoked before a tool that dispatches page input or mutates browser state is forwarded. */
   onBrowserControlResumed?: (sessionId: string) => void;
-  /** Invoked after a tab is explicitly claimed so its overlay can be refreshed immediately. */
-  onAgentTabClaimed?: (tabId: number, windowId: number) => void;
   /** User approval for `tool.tab_borrow` (overlay in content script). */
   approveBorrow?: BorrowConfirmationApprover;
   /** i18n notification copy for `tool.request_help` (resolved per-call). */
@@ -150,7 +148,6 @@ export class ToolDispatcher {
   private readonly recording?: RecordRuntimeDeps;
   private readonly onSessionsChanged?: () => void;
   private readonly onBrowserControlResumed?: (sessionId: string) => void;
-  private readonly onAgentTabClaimed?: (tabId: number, windowId: number) => void;
   private readonly approveBorrow?: BorrowConfirmationApprover;
   private readonly helpNotificationCopy?: () => { title: string; body: string };
   private subscription: { dispose(): void } | null = null;
@@ -171,7 +168,6 @@ export class ToolDispatcher {
     this.recording = deps.recording;
     this.onSessionsChanged = deps.onSessionsChanged;
     this.onBrowserControlResumed = deps.onBrowserControlResumed;
-    this.onAgentTabClaimed = deps.onAgentTabClaimed;
     this.approveBorrow = deps.approveBorrow;
     this.helpNotificationCopy = deps.helpNotificationCopy;
   }
@@ -239,7 +235,7 @@ export class ToolDispatcher {
       if (sessionId) this.onBrowserControlResumed?.(sessionId);
       const result = await this.invoke(req, ac.signal);
       if (isRpcError(result)) {
-        body = { id: req.id, error: result };
+        body = { id: req.id, error: classifyCdpError(result) };
       } else {
         body = { id: req.id, result };
         if (req.method === "tool.session_start") {
@@ -307,25 +303,13 @@ export class ToolDispatcher {
         await this.releaseHoverLatch((req.params as SessionStopParams).session_id);
         return handleSessionStop(this.sessions, req.params as SessionStopParams, {
           cdp: this.cdp,
-          // Must be wired in production: the agent-tab cleanup and the
-          // window-release decision (issue #57) read these deps directly
-          // and silently no-op when they are absent.
-          tabManagement: { tabs: chromeTabMutationApi },
-          tabsQuery: chromeTabsApi,
           signal,
         });
       }
       case "tool.tab_list":
         return handleTabList(this.sessions, req.params as TabListParams, chromeTabsApi, signal);
-      case "tool.tab_create": {
-        const result = await handleTabCreate(this.sessions, req.params as TabCreateParams, {
-          signal,
-        });
-        if (!isRpcError(result)) {
-          this.onAgentTabClaimed?.(result.tab_id, result.window_id);
-        }
-        return result;
-      }
+      case "tool.tab_create":
+        return handleTabCreate(this.sessions, req.params as TabCreateParams, { signal });
       case "tool.tab_close":
         return this.withHoverReleaseForRequest(
           req.params as TabCloseParams,
@@ -334,16 +318,11 @@ export class ToolDispatcher {
         );
       case "tool.tab_select":
         return handleTabSelect(this.sessions, req.params as TabSelectParams, { signal });
-      case "tool.tab_borrow": {
-        const result = await handleTabBorrow(this.sessions, req.params as TabBorrowParams, {
+      case "tool.tab_borrow":
+        return handleTabBorrow(this.sessions, req.params as TabBorrowParams, {
           signal,
           approveBorrow: this.approveBorrow,
         });
-        if (!isRpcError(result)) {
-          this.onAgentTabClaimed?.(result.tab_id, result.agent_window_id);
-        }
-        return result;
-      }
       case "tool.tab_return":
         return handleTabReturn(this.sessions, req.params as TabReturnParams, { signal });
       case "tool.window_resize":

apps/extension/src/tools/errors.ts

@@ -13,6 +13,34 @@ import type {
 
 export type { RpcErrorData, RpcErrorReason };
 
+/** Chrome checks the whole tab's frame tree, including other extensions' frames. */
+export function isCdpExtensionAccessDenied(error: unknown): boolean {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.includes("Cannot access a chrome-extension:// URL of different extension");
+}
+
+/** Preserve more specific reasons, especially file-transfer outcome/cleanup details. */
+export function classifyCdpError(error: RpcError): RpcError {
+  if (
+    error.code !== "cdp_failed" ||
+    error.data?.reason ||
+    !isCdpExtensionAccessDenied(error.message)
+  ) {
+    return error;
+  }
+  return {
+    ...error,
+    data: { ...error.data, reason: "cdp_extension_access_denied" },
+  };
+}
+
+export function cdpError(error: unknown): RpcError {
+  return classifyCdpError({
+    code: "cdp_failed",
+    message: error instanceof Error ? error.message : String(error),
+  });
+}
+
 export interface TransferErrorOptions {
   effectState: TransferEffectState;
   phase: string;

apps/extension/src/tools/navigation.ts

@@ -28,7 +28,13 @@ import type {
   RpcError,
   WaitUntil,
 } from "@/transport/types";
+import {
+  type BrowserNavigationApi,
+  chromeBrowserNavigationApi,
+  navigateWithBrowserApi,
+} from "./browser-navigation";
 import { attachDialogs, markDialogCursor } from "./dialogs";
+import { cdpError, isCdpExtensionAccessDenied } from "./errors";
 import {
   type CdpRunner,
   type ChromeTabsApi,
@@ -42,6 +48,7 @@ import {
 export interface NavigationDeps {
   cdp: CdpRunner;
   tabsApi: ChromeTabsApi;
+  browserNavigation?: BrowserNavigationApi;
   /** Optional AbortSignal — M7 abort hook (M10.2 will wire the full chain). */
   signal?: AbortSignal;
   /** Override default timeout when the caller omits `timeout_ms`. */
@@ -479,6 +486,81 @@ async function readTabUrl(api: ChromeTabsApi, tabId: number): Promise<string | u
   }
 }
 
+/** Recover only a failed preflight; never replay an already-dispatched navigation. */
+async function recoverBrowserNavigation(
+  deps: NavigationDeps,
+  tabId: number,
+  action: (api: BrowserNavigationApi) => Promise<unknown>,
+  waitUntil: WaitUntil,
+  timeoutMs: number,
+): Promise<ReloadResult | RpcError> {
+  const abort = linkedAbortSignal(deps.signal);
+  const deadline = Date.now() + timeoutMs;
+  const api = deps.browserNavigation ?? chromeBrowserNavigationApi;
+  try {
+    let outcome = await navigateWithBrowserApi(
+      api,
+      tabId,
+      () => action(api),
+      waitUntil === "networkidle" ? "commit" : waitUntil,
+      timeoutMs,
+      abort.signal,
+    );
+    if (outcome.reached === "failed") return outcome.error;
+    if (outcome.reached === "cancelled" || abort.signal.aborted) {
+      return { code: "cancelled", message: "navigation recovery aborted" };
+    }
+    if (outcome.reached === "match") {
+      // A completed reload is not a recovery if the restricted frame remains.
+      await deps.cdp.send(tabId, "Page.enable", {});
+      if (abort.signal.aborted)
+        return { code: "cancelled", message: "navigation recovery aborted" };
+      if (waitUntil === "networkidle") {
+        // webNavigation cannot prove network idle. Subscribe on the new
+        // document before enabling CDP lifecycle events after its commit.
+        const frame = await readMainFrameInfo(deps.cdp, tabId);
+        if (!frame.frameId) return cdpError("no main frame after navigation");
+        const remaining = deadline - Date.now();
+        if (remaining <= 0) {
+          outcome = { reached: "timeout", lastLifecycle: "commit" };
+        } else {
+          const wait = startLifecycleWait(
+            deps.cdp,
+            tabId,
+            frame.frameId,
+            "networkIdle",
+            remaining,
+            abort.signal,
+            { loaderId: frame.loaderId ?? undefined },
+          );
+          await deps.cdp.send(tabId, "Page.setLifecycleEventsEnabled", { enabled: true });
+          outcome = await wait.promise;
+        }
+      }
+    }
+    if (outcome.reached === "cancelled" || abort.signal.aborted) {
+      return { code: "cancelled", message: "navigation recovery aborted" };
+    }
+    return {
+      tab_id: tabId,
+      final_url: await readTabUrl(deps.tabsApi, tabId),
+      reached: outcome.reached === "match" ? waitUntil : "timeout",
+      ...(outcome.reached === "timeout"
+        ? {
+            error_text: `timed out waiting for ${waitUntil} during navigation recovery after ${timeoutMs}ms`,
+          }
+        : {}),
+    };
+  } catch (error) {
+    return abort.signal.aborted
+      ? { code: "cancelled", message: "navigation recovery aborted" }
+      : cdpError(error);
+  } finally {
+    abort.abort();
+    abort.cleanup();
+  }
+}
+
 // ---------------------------------------------------------------------------
 // tool.navigate
 // ---------------------------------------------------------------------------
@@ -505,7 +587,20 @@ export async function handleNavigate(
 
   try {
     deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
-    await ensureCdpReady(deps.cdp, target.tabId);
+    try {
+      await ensureCdpReady(deps.cdp, target.tabId);
+    } catch (error) {
+      if (!isCdpExtensionAccessDenied(error)) throw error;
+      const recovered = await recoverBrowserNavigation(
+        deps,
+        target.tabId,
+        (api) => api.update(target.tabId, { url: params.url }),
+        waitUntil,
+        timeoutMs,
+      );
+      if (isRpcError(recovered)) return recovered;
+      return attachDialogs(deps.cdp, target.tabId, dialogCursor, { ...recovered, url: params.url });
+    }
     const expected = cdpLifecycleName(waitUntil);
     const beforeReadyState = await probeMainFrameReadyState(deps.cdp, target.tabId);
     const beforeFrame = await readMainFrameInfo(deps.cdp, target.tabId);
@@ -574,10 +669,7 @@ export async function handleNavigate(
       }`,
     });
   } catch (err) {
-    return {
-      code: "cdp_failed",
-      message: err instanceof Error ? err.message : String(err),
-    };
+    return cdpError(err);
   }
 }
 
@@ -727,7 +819,24 @@ export async function handleReload(
 
   try {
     deps.cdp.trackSessionTab?.(ctx.sessionId, target.tabId);
-    await ensureCdpReady(deps.cdp, target.tabId);
+    try {
+      await ensureCdpReady(deps.cdp, target.tabId);
+    } catch (error) {
+      if (!isCdpExtensionAccessDenied(error)) throw error;
+      const previousUrl = await readTabUrl(deps.tabsApi, target.tabId);
+      const recovered = await recoverBrowserNavigation(
+        deps,
+        target.tabId,
+        (api) => api.reload(target.tabId, { bypassCache: ignoreCache }),
+        waitUntil,
+        timeoutMs,
+      );
+      if (isRpcError(recovered)) return recovered;
+      return attachDialogs(deps.cdp, target.tabId, dialogCursor, {
+        ...recovered,
+        previous_url: previousUrl,
+      });
+    }
     const previousUrl = await readTabUrl(deps.tabsApi, target.tabId);
     const beforeFrame = await readMainFrameInfo(deps.cdp, target.tabId);
     const expected = cdpLifecycleName(waitUntil);
@@ -776,10 +885,7 @@ export async function handleReload(
       }`,
     });
   } catch (err) {
-    return {
-      code: "cdp_failed",
-      message: err instanceof Error ? err.message : String(err),
-    };
+    return cdpError(err);
   }
 }
 

apps/extension/src/tools/session.ts

@@ -2,7 +2,6 @@ import { type SessionManager, SessionStartCleanupError } from "@/session-manager
 import type { RpcError } from "@/transport/types";
 import { rpcError } from "./errors";
 import { clearRecordingForSession } from "./record";
-import type { ChromeTabsApi } from "./shared";
 import { isRpcError } from "./shared";
 import { returnBorrowedTab, type TabManagementDeps } from "./tabs";
 
@@ -74,12 +73,6 @@ export interface SessionStopResult {
   /** Tab ids whose return path failed; those entries remain borrowed so
    *  shutdown can be retried without closing the Agent Window. */
   return_failures?: Array<{ tab_id: number; code: string; message: string }>;
-  /**
-   * True when the Agent Window was *released* to the user (instead of being
-   * closed) because it still contained user-created tabs after the agent's own
-   * tabs were closed. Single-session scope.
-   */
-  window_released?: boolean;
 }
 
 export interface SessionStopDeps {
@@ -94,13 +87,6 @@ export interface SessionStopDeps {
    * without a real browser.
    */
   tabManagement?: TabManagementDeps;
-  /**
-   * Read-only Chrome tabs API used to *query* remaining tabs before deciding
-   * whether to release the window. Kept separate from `tabManagement.tabs`
-   * (a `TabMutationApi` that has no `query`) so the mutation interface stays
-   * pure. Tests can inject a fake `ChromeTabsApi` too.
-   */
-  tabsQuery?: ChromeTabsApi;
 }
 
 /**
@@ -166,10 +152,8 @@ export async function handleSessionStart(
  *      cleanly (review parity with M6).
  *   3. Detach CDP sessions the extension still holds for this
  *      session (no-op if M6/M7 didn't attach to any tab).
- *   4. Close the agent-created tabs and the home tab (design §3.2).
- *   5. If any tab remains — those are user-created tabs — release the
- *      window to the user (dropOnly) instead of closing it, so user
- *      tabs survive. Otherwise close the window as before.
+ *   4. Close the Agent Window. SessionManager.stop() removes the
+ *      Chrome window and forgets the context.
  *
  * Failures in step 1 keep the Agent Window open: a failed borrowed tab
  * may still be there, so closing the window would risk losing user
@@ -204,8 +188,6 @@ export async function handleSessionStop(
   const returnFailures: SessionStopResult["return_failures"] = [];
   const borrowedIds = Array.from(ctx.borrowedTabs.keys());
   for (const tabId of borrowedIds) {
-    // A close event may have removed this borrow while another tab returned.
-    if (!ctx.borrowedTabs.has(tabId)) continue;
     try {
       const tabManagement = {
         ...(deps.tabManagement ?? {}),
@@ -215,7 +197,6 @@ export async function handleSessionStop(
           ((windowId: number) => manager.findByWindowId(windowId) !== null),
       };
       const outcome = await returnBorrowedTab(ctx, tabId, tabManagement);
-      if (!ctx.borrowedTabs.has(tabId)) continue;
       if (typeof outcome === "object" && "code" in outcome) {
         console.warn(`[bsk session_stop] auto-return failed for tab ${tabId}`, outcome);
         returnFailures?.push({
@@ -228,7 +209,6 @@ export async function handleSessionStop(
         ctx.borrowedTabs.delete(tabId);
       }
     } catch (err) {
-      if (!ctx.borrowedTabs.has(tabId)) continue;
       const message = err instanceof Error ? err.message : String(err);
       console.warn(`[bsk session_stop] auto-return threw for tab ${tabId}: ${message}`);
       returnFailures?.push({
@@ -239,15 +219,8 @@ export async function handleSessionStop(
     }
   }
 
-  // A previously failed tab may have closed during a later return. Only
-  // confirmed close events remove borrows; ordinary move failures stay retryable.
-  const pendingReturnFailures = returnFailures.filter((failure) =>
-    ctx.borrowedTabs.has(failure.tab_id),
-  );
   if (deps.signal?.aborted) {
-    const nonCancelFailures = pendingReturnFailures.filter(
-      (failure) => failure.code !== "cancelled",
-    );
+    const nonCancelFailures = returnFailures?.filter((failure) => failure.code !== "cancelled");
     if (nonCancelFailures && nonCancelFailures.length > 0) {
       return {
         ...(returnedTabIds.length > 0 ? { returned_tab_ids: returnedTabIds } : {}),
@@ -259,8 +232,8 @@ export async function handleSessionStop(
 
   const result: SessionStopResult = {};
   if (returnedTabIds.length > 0) result.returned_tab_ids = returnedTabIds;
-  if (pendingReturnFailures.length > 0) {
-    result.return_failures = pendingReturnFailures;
+  if (returnFailures && returnFailures.length > 0) {
+    result.return_failures = returnFailures;
     // A failed return means at least one borrowed user tab may still be
     // inside the Agent Window. Keep the session/window alive so the user
     // can retry `bsk session stop` or explicitly `bsk tab return` after the
@@ -280,66 +253,8 @@ export async function handleSessionStop(
     return { code: "cancelled", message: "session_stop aborted before window close" };
   }
 
-  // Step 4: close every tab explicitly created by the agent, including the
-  // home tab. `tabsApi` is a
-  // TabMutationApi (remove only); `queryApi` is a separate read-only
-  // ChromeTabsApi. If neither is injected, we conservatively fall back to
-  // closing the window (see Step 5).
-  const tabsApi = deps.tabManagement?.tabs;
-  const queryApi = deps.tabsQuery;
-
-  if (tabsApi) {
-    // Close each agent-created tab that still exists.
-    const agentCreatedTabIds = Array.from(ctx.agentCreatedTabs);
-    for (const tabId of agentCreatedTabIds) {
-      try {
-        await tabsApi.remove(tabId);
-        ctx.agentCreatedTabs.delete(tabId);
-      } catch (err) {
-        // Tab may already be gone (closed by the user). Non-fatal.
-        console.warn(`[bsk session_stop] failed to close agent tab ${tabId}`, err);
-      }
-    }
-  }
-
-  // Step 5: decide whether to release (keep) the window or close it.
-  let shouldRelease = false;
-  if (queryApi) {
-    try {
-      const liveWindowTabs = await queryApi.query({ windowId: ctx.agentWindowId });
-      // Only genuine *user* tabs count toward keeping the window open.
-      // An agent tab that failed to close in Step 4 may still be present
-      // here; if we counted it as a reason to release (dropOnly), the
-      // window would be kept and that agent tab would leak (issue #57
-      // regression). Exclude any id still tracked in agentCreatedTabs.
-      const userTabs = liveWindowTabs.filter((t) => {
-        if (t.id === undefined) return false;
-        return !ctx.agentCreatedTabs.has(t.id);
-      });
-      const leakedAgentTabs = liveWindowTabs.filter(
-        (t) => t.id !== undefined && ctx.agentCreatedTabs.has(t.id),
-      );
-      if (leakedAgentTabs.length > 0) {
-        console.warn(
-          `[bsk session_stop] ${leakedAgentTabs.length} agent tab(s) failed to close; forcing window close instead of release`,
-          leakedAgentTabs.map((t) => t.id),
-        );
-      }
-      shouldRelease = userTabs.length > 0;
-    } catch {
-      // Query failed (e.g. window already gone) — conservatively close it.
-      shouldRelease = false;
-    }
-  }
-
-  if (shouldRelease) {
-    // Keep the window + its user tabs; only drop the session binding.
-    await manager.stop(params.session_id, { dropOnly: true });
-    result.window_released = true;
-  } else {
-    // Window is empty (or we couldn't verify state) — close it.
-    await manager.stop(params.session_id);
-  }
+  // Step 4: close the Agent Window and drop the context.
+  await manager.stop(params.session_id);
 
   return result;
 }

apps/extension/src/tools/tabs.ts

@@ -369,7 +369,6 @@ function buildCreateProps(
  * Returns the created tab on success, or an `RpcError` on failure.
  */
 async function createTabAndCleanup(
-  ctx: SessionContext,
   deps: TabManagementDeps,
   createProps: chrome.tabs.CreateProperties,
 ): Promise<CreatedChromeTab | RpcError> {
@@ -382,28 +381,25 @@ async function createTabAndCleanup(
       message: err instanceof Error ? err.message : String(err),
     };
   }
-  if (typeof tab.id !== "number") {
-    return { code: "protocol_error", message: "chrome.tabs.create returned no tab id" };
-  }
-  // Claim the concrete id returned by Chrome. Ownership never depends on
-  // matching this request to an asynchronous onCreated event.
-  ctx.agentCreatedTabs.add(tab.id);
   if (aborted(deps.signal, "tab_create")) {
-    try {
-      await getTabsApi(deps).remove(tab.id);
-      ctx.agentCreatedTabs.delete(tab.id);
-    } catch (cleanupErr) {
-      // Keep the claim when cleanup fails so session_stop can retry instead
-      // of releasing an agent-owned tab to the user.
-      return rpcError(
-        "protocol_error",
-        "cleanup_failed",
-        `tab_create aborted but cleanup of tab ${tab.id} failed: ${describeError(cleanupErr)}`,
-        { resource_type: "tab", resource_id: tab.id },
-      );
+    // We already opened the tab; close it on abort so we don't leak.
+    if (typeof tab.id === "number") {
+      try {
+        await getTabsApi(deps).remove(tab.id);
+      } catch (cleanupErr) {
+        return rpcError(
+          "protocol_error",
+          "cleanup_failed",
+          `tab_create aborted but cleanup of tab ${tab.id} failed: ${describeError(cleanupErr)}`,
+          { resource_type: "tab", resource_id: tab.id },
+        );
+      }
     }
     return { code: "cancelled", message: "tab_create aborted" };
   }
+  if (typeof tab.id !== "number") {
+    return { code: "protocol_error", message: "chrome.tabs.create returned no tab id" };
+  }
   return { ...tab, id: tab.id };
 }
 
@@ -430,7 +426,7 @@ export async function handleTabCreate(
   const paramErr = validateTabCreateParams(params);
   if (paramErr) return paramErr;
 
-  const tab = await createTabAndCleanup(ctx, deps, buildCreateProps(ctx, params));
+  const tab = await createTabAndCleanup(deps, buildCreateProps(ctx, params));
   if (isRpcError(tab)) return tab;
 
   return {
@@ -530,9 +526,6 @@ export async function handleTabClose(
   }
   try {
     await getTabsApi(deps).remove(params.tab_id);
-    // Keep the tracking set accurate so session_stop won't try to close a
-    // tab that's already gone (design §3.1).
-    ctx.agentCreatedTabs.delete(params.tab_id);
   } catch (err) {
     return {
       code: "protocol_error",
@@ -760,6 +753,13 @@ async function executeBorrowCore(
   );
   if (moveErr) return moveErr;
 
+  // Best-effort activation — failure is non-fatal.
+  try {
+    await p.tabsApi.update(p.tabId, { active: true });
+  } catch (err) {
+    console.debug("[bsk tab_borrow] activate after move failed", err);
+  }
+
   return { originalWindowId, originalIndex };
 }
 
@@ -823,12 +823,6 @@ export async function handleTabBorrow(
         message: err instanceof Error ? err.message : String(err),
       };
     }
-    // Activate after commit so overlay/event observers see the tab as claimed.
-    try {
-      await tabsApi.update(params.tab_id, { active: true });
-    } catch (err) {
-      console.debug("[bsk tab_borrow] activate after move failed", err);
-    }
     return {
       tab_id: params.tab_id,
       original_window_id: coreResult.originalWindowId,

apps/extension/src/transport/types.ts

@@ -31,6 +31,7 @@ export type RpcErrorReason =
   | "single_select_value_count"
   | "tab_not_active"
   | "restricted_tab_url"
+  | "cdp_extension_access_denied"
   | "borrow_conflict"
   | "screenshot_capture_failed"
   | "file_input_probe_failed"

crates/bsk-cli/src/cli/render_error.rs

@@ -47,6 +47,7 @@ pub mod reason {
     pub const OPTION_NOT_FOUND: &str = "option_not_found";
     pub const SINGLE_SELECT_VALUE_COUNT: &str = "single_select_value_count";
     pub const TAB_NOT_ACTIVE: &str = "tab_not_active";
+    pub const CDP_EXTENSION_ACCESS_DENIED: &str = "cdp_extension_access_denied";
     pub const BORROW_CONFLICT: &str = "borrow_conflict";
     pub const SCREENSHOT_CAPTURE_FAILED: &str = "screenshot_capture_failed";
     pub const FILE_INPUT_PROBE_FAILED: &str = "file_input_probe_failed";
@@ -206,6 +207,13 @@ pub fn info_for_error(code: ErrorCode, data: Option<&serde_json::Value>) -> Rend
         return base;
     };
     match (code, reason) {
+        (ErrorCode::CdpFailed, reason::CDP_EXTENSION_ACCESS_DENIED) => RenderInfo {
+            summary: "Chrome blocked CDP access to another extension's content in this tab",
+            hint: Some(
+                "a web page can contain a restricted extension frame; disable the conflicting extension and reload, or use `bsk navigate <url>` to leave this page; reconnecting BrowserSkill alone does not remove the restriction",
+            ),
+            exit_code: base.exit_code,
+        },
         (_, reason::TRANSFER_OUTCOME_UNKNOWN) => RenderInfo {
             summary: "the file transfer outcome could not be confirmed",
             hint: Some(
@@ -454,6 +462,18 @@ mod tests {
         assert!(!info.summary.contains("sandbox"));
     }
 
+    #[test]
+    fn extension_access_denied_explains_the_frame_restriction_and_navigation_recovery() {
+        let data = serde_json::json!({ "reason": reason::CDP_EXTENSION_ACCESS_DENIED });
+        let info = info_for_error(ErrorCode::CdpFailed, Some(&data));
+        assert!(info.summary.contains("another extension"));
+        let hint = info.hint.unwrap();
+        assert!(hint.contains("restricted extension frame"));
+        assert!(hint.contains("bsk navigate <url>"));
+        assert!(hint.contains("disable the conflicting extension"));
+        assert_eq!(info.exit_code, 3);
+    }
+
     #[test]
     fn session_busy_overrides_timeout_copy() {
         let data = serde_json::json!({ "reason": reason::SESSION_BUSY });

crates/bsk-cli/src/cli/update.rs

@@ -761,7 +761,6 @@ fn stage_windows_replacement(
     .with_context(|| format!("write {}", paths.script_path.display()))?;
 
     const CREATE_NO_WINDOW: u32 = 0x0800_0000;
-    const CREATE_NEW_PROCESS_GROUP: u32 = 0x0000_0200;
     let command = format!("\"{}\"", paths.script_path.display());
     if let Err(err) = Command::new("cmd.exe")
         .args(["/D", "/S", "/C"])
@@ -769,7 +768,7 @@ fn stage_windows_replacement(
         .stdin(Stdio::null())
         .stdout(Stdio::null())
         .stderr(Stdio::null())
-        .creation_flags(CREATE_NO_WINDOW | CREATE_NEW_PROCESS_GROUP)
+        .creation_flags(CREATE_NO_WINDOW)
         .spawn()
     {
         let _ = std::fs::remove_file(&paths.binary_path);
@@ -807,7 +806,7 @@ fn windows_replacement_script(target: &Path, staged_binary: &Path, restart_daemo
          :retry\r\n\
          move /Y \"{staged_binary}\" \"{target}\" >nul 2>nul\r\n\
          if errorlevel 1 (\r\n\
-           ping -n 2 127.0.0.1 >nul\r\n\
+           timeout /t 1 /nobreak >nul\r\n\
            goto retry\r\n\
          )\r\n\
          {restart}\
@@ -1008,8 +1007,6 @@ mod tests {
 
         assert!(script.contains(":retry"));
         assert!(script.contains("move /Y"));
-        assert!(script.contains("ping -n 2 127.0.0.1"));
-        assert!(!script.contains("timeout"));
         assert!(script.contains(r#"start "" /B "C:\Program Files\bsk.exe" daemon start"#));
         assert!(script.contains(r#"del /F /Q "%~f0""#));
     }

packages/i18n/package.json

@@ -13,10 +13,6 @@
       "default": "./src/react.tsx"
     }
   },
-  "scripts": {
-    "test": "vitest run",
-    "test:watch": "vitest"
-  },
   "peerDependencies": {
     "react": "^19.0.0"
   },
@@ -24,8 +20,5 @@
     "i18next": "^24.2.2",
     "i18next-browser-languagedetector": "^8.0.2",
     "react-i18next": "^15.3.4"
-  },
-  "devDependencies": {
-    "vitest": "^4.1.6"
   }
 }

packages/i18n/src/chrome-storage-sync.ts

@@ -24,9 +24,6 @@ declare const chrome:
           ) => void;
         };
       };
-      i18n?: {
-        getUILanguage(): string;
-      };
     }
   | undefined;
 
@@ -34,116 +31,14 @@ function getChromeLocal(): ChromeStorageLocal | undefined {
   return typeof chrome !== "undefined" ? chrome.storage?.local : undefined;
 }
 
-/** Regions whose written Chinese defaults to Traditional. */
-const TRADITIONAL_CHINESE_REGIONS = new Set(["tw", "hk", "mo"]);
-
-/**
- * Group resource keys by primary language subtag, so a bare `ko` can find
- * `ko-KR` without anyone maintaining a side map by hand.
- */
-function buildPrimarySubtagIndex(resourceKeys: string[]): Map<string, string[]> {
-  const index = new Map<string, string[]>();
-  for (const key of resourceKeys) {
-    const primary = key.split(/[-_]/)[0].toLowerCase();
-    const bucket = index.get(primary);
-    if (bucket) {
-      bucket.push(key);
-    } else {
-      index.set(primary, [key]);
-    }
-  }
-  return index;
-}
-
-/**
- * Chinese is the one language where a single primary subtag maps to several
- * resources, because Simplified and Traditional differ by script rather than
- * by region. Every other language resolves straight from the index.
- */
-function resolveChineseVariant(parts: string[], candidates: string[]): string {
-  const byRegion = (region: string): string | undefined =>
-    candidates.find((key) => key.toLowerCase().endsWith(`-${region}`));
-
-  // 1. Script subtag is the most accurate signal (zh-Hans / zh-Hant).
-  if (parts.includes("hans")) {
-    return byRegion("cn") ?? candidates[0];
-  }
-  if (parts.includes("hant")) {
-    return byRegion("tw") ?? candidates[candidates.length - 1];
-  }
-  // 2. Fall back to the region subtag, which is what Chrome actually reports.
-  //    Skip parts[0] — the primary subtag `zh` is also two characters long.
-  const region = parts.slice(1).find((part) => part.length === 2);
-  if (region && TRADITIONAL_CHINESE_REGIONS.has(region)) {
-    return byRegion("tw") ?? candidates[0];
-  }
-  // 3. Bare `zh` and any other region default to Simplified.
-  return byRegion("cn") ?? candidates[0];
-}
-
-/**
- * Build a normalizer driven entirely by the resource keys i18next ships, so
- * registering a new translation needs no change here.
- *
- * For a detected BCP 47 tag, in order:
- *
- * 1. it already names a resource (`ko-KR`)               → unchanged
- * 2. one resource shares its language (`ko` → `ko-KR`)   → that resource
- * 3. several do (`zh` → `zh-CN` / `zh-TW`)               → script, then region
- * 4. nothing is shipped for the language                 → unchanged
- *
- * Case 4 leaves the tag untouched so i18next applies `fallbackLng`, rather
- * than silently routing an untranslated language to the wrong bundle.
- */
-export function createLanguageNormalizer(resourceKeys: string[]): (code: string) => string {
-  const keySet = new Set(resourceKeys);
-  const index = buildPrimarySubtagIndex(resourceKeys);
-
-  return (code: string): string => {
-    if (keySet.has(code)) {
-      return code;
-    }
-    const parts = code.split(/[-_]/).map((part) => part.toLowerCase());
-    const candidates = index.get(parts[0]);
-    if (!candidates?.length) {
-      return code;
-    }
-    if (candidates.length === 1) {
-      return candidates[0];
-    }
-    if (parts[0] === "zh") {
-      return resolveChineseVariant(parts, candidates);
-    }
-    return candidates[0];
-  };
-}
-
-/**
- * i18next detector that prefers `chrome.i18n.getUILanguage()`, Chrome's
- * authoritative source for the extension UI language. The popup runs on a
- * `chrome-extension://` origin where `navigator.language` can disagree with it.
- */
-export const chromeUiLanguageDetector = {
-  name: "chromeUILanguage",
-  lookup(): string | undefined {
-    if (typeof chrome !== "undefined" && chrome.i18n?.getUILanguage) {
-      return chrome.i18n.getUILanguage();
-    }
-    return undefined;
-  },
-};
-
 /** Avoid page-origin localStorage; use extension storage + navigator only. */
-export function getLanguageDetectionOptions(resourceKeys: string[]): {
+export function getLanguageDetectionOptions(): {
   order: string[];
   caches: string[];
-  convertDetectedLanguage: (lng: string) => string;
 } {
   return {
-    order: ["chromeUILanguage", "navigator"],
+    order: ["navigator"],
     caches: [],
-    // Normalise the detected tag before i18next resolves it against `resources`.
-    convertDetectedLanguage: createLanguageNormalizer(resourceKeys),
   };
 }
 

packages/i18n/src/i18n.ts

@@ -2,11 +2,7 @@ import i18n from "i18next";
 import LanguageDetector from "i18next-browser-languagedetector";
 import { initReactI18next } from "react-i18next";
 
-import {
-  bindChromeStorageLanguageSync,
-  chromeUiLanguageDetector,
-  getLanguageDetectionOptions,
-} from "./chrome-storage-sync";
+import { bindChromeStorageLanguageSync, getLanguageDetectionOptions } from "./chrome-storage-sync";
 import enUSCommon from "./locales/en-US/common.json";
 import enUSExtension from "./locales/en-US/extension.json";
 import zhCNCommon from "./locales/zh-CN/common.json";
@@ -23,21 +19,12 @@ const resources = {
   },
 } as const;
 
-const languageDetector = new LanguageDetector();
-languageDetector.addDetector(chromeUiLanguageDetector);
-
-// Drive locale normalisation off the keys we actually ship, so registering a
-// translation is the only step needed to support a new language.
-const resourceKeys = Object.keys(resources);
-
 i18n
-  .use(languageDetector)
+  .use(LanguageDetector)
   .use(initReactI18next)
   .init({
     resources,
-    // English is the international default; Chinese users still get Chinese.
-    // `zh` → zh-CN also covers zh-TW/zh-HK until a Traditional resource exists.
-    fallbackLng: { en: ["en-US"], zh: ["zh-CN"], default: ["en-US"] },
+    fallbackLng: "zh-CN",
     defaultNS: "common",
     ns: ["common", "extension"],
 
@@ -45,7 +32,7 @@ i18n
       escapeValue: false,
     },
 
-    detection: getLanguageDetectionOptions(resourceKeys),
+    detection: getLanguageDetectionOptions(),
 
     react: {
       useSuspense: false,

packages/i18n/tests/locale-resolution.test.ts

@@ -1,126 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import {
-  chromeUiLanguageDetector,
-  createLanguageNormalizer,
-  getLanguageDetectionOptions,
-} from "../src/chrome-storage-sync";
-
-/** What `packages/i18n` ships today — kept in sync with `resources` in i18n.ts. */
-const SHIPPED_RESOURCE_KEYS = ["zh-CN", "en-US"];
-
-/**
- * Locks the locale-resolution table from issue #168: the UI must follow the
- * browser language instead of falling through to Chinese for every locale
- * other than `en-US`.
- */
-describe("createLanguageNormalizer", () => {
-  const normalize = createLanguageNormalizer(SHIPPED_RESOURCE_KEYS);
-
-  const cases: Array<[detected: string, resource: string]> = [
-    // English — every variant maps to the single en-US resource.
-    ["en", "en-US"],
-    ["en-US", "en-US"],
-    ["en-GB", "en-US"],
-    ["en-CN", "en-US"],
-    ["en-AU", "en-US"],
-
-    // Chinese — only `zh-CN` ships today, so every variant resolves to it
-    // directly rather than leaking into the fallback chain. Traditional picks
-    // up `zh-TW` automatically once that bundle is registered (see below).
-    ["zh", "zh-CN"],
-    ["zh-CN", "zh-CN"],
-    ["zh-SG", "zh-CN"],
-    ["zh-Hans", "zh-CN"],
-    ["zh-Hans-CN", "zh-CN"],
-    ["zh-Hans-SG", "zh-CN"],
-    ["zh-TW", "zh-CN"],
-    ["zh-HK", "zh-CN"],
-    ["zh-MO", "zh-CN"],
-    ["zh-Hant", "zh-CN"],
-    ["zh-Hant-TW", "zh-CN"],
-    ["zh-Hant-HK", "zh-CN"],
-
-    // No translation shipped — returned unchanged so i18next applies the
-    // `default` fallback (en-US) rather than Chinese.
-    ["ja", "ja"],
-    ["ja-JP", "ja-JP"],
-    ["fr-FR", "fr-FR"],
-    ["de-DE", "de-DE"],
-  ];
-
-  it.each(cases)("maps %s to %s", (detected, resource) => {
-    expect(normalize(detected)).toBe(resource);
-  });
-
-  it("is case-insensitive", () => {
-    expect(normalize("EN-us")).toBe("en-US");
-    expect(normalize("zh-hant-tw")).toBe("zh-CN");
-  });
-});
-
-/**
- * The point of the factory: supporting a new language means registering its
- * bundle in `resources` — never touching the normalizer.
- */
-describe("createLanguageNormalizer extensibility", () => {
-  it("auto-resolves a newly registered language", () => {
-    const normalize = createLanguageNormalizer(["en-US", "zh-CN", "ko-KR"]);
-    expect(normalize("ko")).toBe("ko-KR");
-    expect(normalize("ko-KR")).toBe("ko-KR");
-  });
-
-  it("disambiguates zh once a Traditional bundle ships", () => {
-    const normalize = createLanguageNormalizer(["en-US", "zh-CN", "zh-TW"]);
-    expect(normalize("zh-Hant")).toBe("zh-TW");
-    expect(normalize("zh-Hant-TW")).toBe("zh-TW");
-    expect(normalize("zh-TW")).toBe("zh-TW");
-    expect(normalize("zh-HK")).toBe("zh-TW");
-    expect(normalize("zh-MO")).toBe("zh-TW");
-    expect(normalize("zh-Hans")).toBe("zh-CN");
-    expect(normalize("zh-CN")).toBe("zh-CN");
-    expect(normalize("zh")).toBe("zh-CN");
-  });
-
-  it("leaves unregistered languages to fallbackLng", () => {
-    const normalize = createLanguageNormalizer(["en-US", "zh-CN"]);
-    expect(normalize("pt-BR")).toBe("pt-BR");
-    expect(normalize("ru")).toBe("ru");
-  });
-});
-
-describe("chromeUiLanguageDetector", () => {
-  it("prefers chrome.i18n.getUILanguage() when available", () => {
-    vi.stubGlobal("chrome", { i18n: { getUILanguage: () => "en-GB" } });
-    expect(chromeUiLanguageDetector.lookup()).toBe("en-GB");
-  });
-
-  it("returns undefined outside a Chrome extension context", () => {
-    vi.stubGlobal("chrome", undefined);
-    expect(chromeUiLanguageDetector.lookup()).toBeUndefined();
-  });
-
-  it("returns undefined when the i18n API is unavailable", () => {
-    vi.stubGlobal("chrome", {});
-    expect(chromeUiLanguageDetector.lookup()).toBeUndefined();
-  });
-});
-
-describe("getLanguageDetectionOptions", () => {
-  it("orders the Chrome UI language ahead of navigator", () => {
-    expect(getLanguageDetectionOptions(SHIPPED_RESOURCE_KEYS).order).toEqual([
-      "chromeUILanguage",
-      "navigator",
-    ]);
-  });
-
-  it("normalises whatever the detectors report", () => {
-    const { convertDetectedLanguage } = getLanguageDetectionOptions(SHIPPED_RESOURCE_KEYS);
-    expect(convertDetectedLanguage("en-GB")).toBe("en-US");
-    expect(convertDetectedLanguage("zh-TW")).toBe("zh-CN");
-    expect(convertDetectedLanguage("ja-JP")).toBe("ja-JP");
-  });
-
-  it("does not write to page-origin storage", () => {
-    expect(getLanguageDetectionOptions(SHIPPED_RESOURCE_KEYS).caches).toEqual([]);
-  });
-});

packages/i18n/vitest.config.ts

@@ -1,8 +0,0 @@
-import { defineConfig } from "vitest/config";
-
-export default defineConfig({
-  test: {
-    environment: "node",
-    include: ["tests/**/*.test.ts"],
-  },
-});

pnpm-lock.yaml

@@ -189,10 +189,6 @@ importers:
       react-i18next:
         specifier: ^15.3.4
         version: 15.7.4(i18next@24.2.3(typescript@5.9.3))(react@19.2.6)(typescript@5.9.3)
-    devDependencies:
-      vitest:
-        specifier: ^4.1.6
-        version: 4.1.6(@types/node@25.8.0)(happy-dom@15.11.7)(vite@8.0.13(@types/node@25.8.0)(esbuild@0.27.7)(jiti@2.7.0))
 
   packages/ui:
     dependencies: