dsh-builtin-browser 0.4.9 → 0.4.11

package/lib/browser-electron/provider.d.ts

@@ -9,6 +9,7 @@
 import { type VisitedPage } from './history-store.js';
 import type { BrowserSettings } from './settings-store.js';
 import type { BrowserA11yRequest, BrowserA11yResult, BrowserChallenge, BrowserCheckRequest, BrowserClearRequest, BrowserClickRequest, BrowserContentRequest, BrowserContentResult, BrowserElementTarget, BrowserExecuteRequest, BrowserExecuteResult, BrowserFillRequest, BrowserFillResult, BrowserGetValueRequest, BrowserGetValueResult, BrowserHistoryEntry, BrowserOpenRequest, BrowserProvider, BrowserScrapeRequest, BrowserScrapeResult, BrowserScreenshotRequest, BrowserSelectRequest, BrowserSelectResult, BrowserSessionId, BrowserSetValueRequest, BrowserSetValueResult, BrowserSnapshotResult, BrowserTab, BrowserTypeRequest, BrowserWaitRequest, BrowserWaitResult, BrowserScrollRequest, BrowserKeyRequest, ExportedCookie } from '../browser/types.js';
+import type { CarrierPage } from '../browser/types.js';
 /** Stable provider id registered with `ctx.browser`. */
 export declare const ELECTRON_BROWSER_PROVIDER_ID = "electron";
 /**
@@ -58,6 +59,35 @@ export interface ElectronBrowserViewHost {
      * @param label - human-readable session/task label, as in {@link showView}.
      */
     presentView?(handle: ElectronViewHandle, label?: string): Promise<void>;
+    /**
+     * Optional: pages this carrier holds that the provider never created.
+     *
+     * A sidebar panel and an installed browser both own their own page creation. Clicking a link
+     * that opens a new page — or any `window.open` the page performs — produces a page the provider
+     * did not ask for and therefore never recorded. Those pages are real: they are what the human
+     * sees, they hold memory, and they persist until something closes them. Without this the tab
+     * model reports only what the provider itself made, so the extras are invisible to
+     * `dsh_browser_list_tabs` and unclosable through `dsh_browser_close_tab`, accumulating for the
+     * life of the browser.
+     *
+     * Views the host itself opened are NOT included. That exclusion belongs to the host, which is the
+     * only side that can make it: a provider tab is identified by the provider's own id and a carrier
+     * page by the carrier's, so a caller comparing the two matches nothing and reports every page
+     * twice. Measured on the sidebar carrier: three clicks produced three webview guests while
+     * `dsh_browser_list_tabs` reported one tab; on the installed-browser carrier the window held four
+     * pages and the tool reported one.
+     * @returns every page the carrier holds that this host did not open.
+     */
+    listPages?(): Promise<readonly CarrierPage[]>;
+    /**
+     * Optional: close one page reported by {@link listPages}.
+     *
+     * The pair exists because listing a page the caller cannot close is worse than not listing it:
+     * `dsh_browser_list_tabs` would report pages that `dsh_browser_close_tab` answers "not open in
+     * this session" about, which reads as a contradiction rather than a boundary.
+     * @param id - the carrier's own page id, as {@link listPages} reported it.
+     */
+    closePage?(id: string): Promise<void>;
     /**
      * Optional cheap usability probe (no network): whether the host can back
      * views at all right now. The self-hosted host checks for a usable Electron
@@ -303,6 +333,15 @@ export interface CdpNavigateParams {
  * CDP method/params for `Input.dispatchMouseEvent`: a pointer move, or one half
  * of a click's press+release pair. `button`/`clickCount` belong to the press and
  * release halves; a move carries only the position.
+ *
+ * `buttons` is a BITMASK of what is held down at the moment of the event, and it is not the same
+ * field as `button` — `button` says which one this event is about, `buttons` says which ones are
+ * down. Chromium needs both to recognise a synthesized press as a real button press: with
+ * `buttons` omitted (0), the event still reaches the page and a `click` listener still fires, but
+ * the element's DEFAULT ACTION does not run. Measured on the sidebar carrier: a click on an
+ * anchor sent `mousedown`/`mouseup`/`click` to the page with `isTrusted: true` and
+ * `defaultPrevented: false`, and the browser did not follow the link — including for an anchor
+ * injected by the test itself, so the page was not responsible.
  */
 export interface CdpMouseParams {
     readonly type: 'mouseMoved' | 'mousePressed' | 'mouseReleased';
@@ -310,6 +349,8 @@ export interface CdpMouseParams {
     readonly y: number;
     readonly button?: 'left';
     readonly clickCount?: number;
+    /** Buttons held during the event: 1 = primary down. A move carries 0. */
+    readonly buttons?: number;
 }
 /** CDP method/params for `Input.insertText`. */
 export interface CdpInsertTextParams {

package/lib/browser-electron/provider.js

@@ -384,6 +384,28 @@ export class ElectronBrowserProvider {
                 active: i === s.activeIndex,
             });
         }
+        // Pages the CARRIER holds that this provider never created.
+        //
+        // A sidebar panel and an installed browser both open pages on their own: a click on a link
+        // that targets a new page, or any `window.open`, produces a page nothing tells us about.
+        // Reporting only our own tabs made those invisible to this tool and unclosable through
+        // `dsh_browser_close_tab`, so they accumulated for the life of the browser. Measured on the
+        // sidebar carrier: three clicks produced three webview guests while this listed one tab.
+        //
+        // `listPages` already excludes the pages it opened the view for — that filtering cannot happen
+        // here, because a tab is known by this provider's own id and a carrier page by the carrier's,
+        // and the two never match. A first version compared them anyway and listed every page twice.
+        //
+        // They are appended under a `page:` prefix so a caller can tell the two kinds apart — the
+        // prefix is also what `closeTab` uses to decide whether to close a view or a carrier page.
+        const pages = await this.host.listPages?.().catch(() => undefined) ?? [];
+        for (const page of pages) {
+            // A page with no URL is a blank one the carrier opened for itself. Listing it would invite a
+            // caller to act on nothing, and the blank normalisation already closes those.
+            if (page.url === '' || page.url === 'about:blank')
+                continue;
+            result.push({ id: `page:${page.id}`, url: page.url, active: false });
+        }
         return result;
     }
     /** Switch to a tab by id, making its view visible. */
@@ -395,6 +417,16 @@ export class ElectronBrowserProvider {
     }
     /** Close one tab; closing the active tab activates the next. */
     closeTab(session, tabId) {
+        // A page the carrier owns rather than a view we created. It was reported by `listTabs` under
+        // this prefix, so closing it here is what keeps the two tools consistent — a page that can be
+        // listed must be closable, or the listing reads as a contradiction.
+        if (tabId.startsWith('page:')) {
+            const id = tabId.slice('page:'.length);
+            if (this.host.closePage === undefined) {
+                return Promise.reject(new BrowserError('browser: this carrier does not expose the pages it opens on its own, so that page cannot be closed', 'BROWSER_TAB_NOT_FOUND'));
+            }
+            return this.host.closePage(id);
+        }
         const found = this.locateTab(session, tabId);
         const s = found.s;
         const index = found.index;
@@ -1290,7 +1322,7 @@ export class ElectronBrowserProvider {
         // landed because the first had quietly established the target. Move the
         // pointer first so a click is self-contained.
         try {
-            await send({ type: 'mouseMoved', x, y }, 'move');
+            await send({ type: 'mouseMoved', x, y, buttons: 0 }, 'move');
         }
         catch (error) {
             throw new BrowserError(`browser: click failed: ${String(error)}`, 'BROWSER_CLICK_FAILED', { cause: error });
@@ -1311,12 +1343,13 @@ export class ElectronBrowserProvider {
                 x,
                 y,
                 button: 'left',
+                buttons: 0,
                 clickCount: 1,
             })
                 .catch(() => { });
         };
         try {
-            await send({ type: 'mousePressed', x, y, button: 'left', clickCount: 1 }, 'press');
+            await send({ type: 'mousePressed', x, y, button: 'left', buttons: 1, clickCount: 1 }, 'press');
         }
         catch (error) {
             // The press may still land late; release best-effort so the button is
@@ -1325,7 +1358,7 @@ export class ElectronBrowserProvider {
             throw new BrowserError(`browser: click failed: ${String(error)}`, 'BROWSER_CLICK_FAILED', { cause: error });
         }
         try {
-            await send({ type: 'mouseReleased', x, y, button: 'left', clickCount: 1 }, 'release');
+            await send({ type: 'mouseReleased', x, y, button: 'left', buttons: 0, clickCount: 1 }, 'release');
         }
         catch (error) {
             // The press already landed; retry the release so the button is not

package/lib/browser-electron/system-browser.d.ts

@@ -36,6 +36,7 @@
 export type BrowserLauncher = (path: string, args: readonly string[]) => ReturnType<typeof spawn>;
 import { spawn } from 'node:child_process';
 import type { ElectronBrowserViewHost, ElectronViewHandle } from './provider.js';
+import type { CarrierPage } from '../browser/types.js';
 /** Which browser the user asked for. */
 export type BrowserChannel = 'bundled' | 'chrome' | 'edge' | 'auto' | 'sidebar';
 /** A resolved browser installation. */
@@ -213,6 +214,45 @@ export declare class SystemBrowserViewHost implements ElectronBrowserViewHost {
      * make the plugin fall back for no reason.
      */
     available(): boolean;
+    /**
+     * Every page the browser currently holds, including ones this plugin did not create.
+     *
+     * Chrome and Edge own their own page creation. A click on a link that opens a new page — or any
+     * `window.open` — produces a page the provider never asked for, and nothing reports it back.
+     * Those pages are real: they hold memory and stay until something closes them. Measured on a real
+     * window: four pages present while `dsh_browser_list_tabs` reported one.
+     *
+     * Discovery is already on at connection time (see the blank-page normalisation), so
+     * `Target.getTargets` also lists pages that existed before this client connected.
+     * @returns the browser's pages, or an empty list when it cannot answer.
+     */
+    /**
+     * Every page the browser holds that THIS HOST did not open.
+     *
+     * Chrome and Edge own their own page creation. A click on a link that opens a new page — or any
+     * `window.open` — produces a page the provider never asked for, and nothing reports it back.
+     * Those pages are real: they hold memory and stay until something closes them. Measured on a real
+     * window: four pages present while `dsh_browser_list_tabs` reported one.
+     *
+     * Pages this host opened are EXCLUDED here rather than deduplicated by the caller, because the
+     * caller cannot do it: the provider knows a tab by its own id, the carrier knows a page by its
+     * CDP target id, and the two never match. The first version returned everything and relied on the
+     * caller to filter, which reported the same page twice.
+     *
+     * Discovery is already on at connection time (see the blank-page normalisation), so
+     * `Target.getTargets` also lists pages that existed before this client connected.
+     * @returns the browser's pages that are not ours, or an empty list when it cannot answer.
+     */
+    listPages(): Promise<readonly CarrierPage[]>;
+    /**
+     * Close one page by the target id {@link listPages} reported.
+     *
+     * `Target.closeTarget` is the browser's own close, so it works for pages this plugin never
+     * created. The page may already be gone if the human closed it in the meantime — the caller
+     * asked for it to be closed and it is, so that is not an error.
+     * @param id - the CDP target id.
+     */
+    closePage(id: string): Promise<void>;
     createView(): ElectronViewHandle;
     destroyView(handle: ElectronViewHandle): void;
     /** Nothing to show: the browser owns its own windows. */

package/lib/browser-electron/system-browser.js

@@ -156,6 +156,18 @@ const INSTALL_LOCATIONS = {
  * @param env - the environment to resolve against.
  * @returns the path with %NAME% references replaced, or the entry unchanged when unknown.
  */
+/**
+ * Whether a browser's self-reported product name is one this carrier could have launched.
+ *
+ * `edg`, not `edge`: Edge reports itself as `Edg/155.0.4283.45`, both over HTTP and over the
+ * protocol. Testing for the full word rejected a live Edge that had just been started, so the
+ * call failed with the hand-off error this check was added to prevent — while the browser was
+ * running the whole time, answering on its own port.
+ * @param product - the product string a browser reports about itself.
+ */
+function isBrowserProduct(product) {
+    return typeof product === 'string' && /chrome|chromium|edg/i.test(product);
+}
 /**
  * Whether a target URL is one of the blanks a browser opens by itself.
  *
@@ -588,14 +600,14 @@ export class SystemBrowserViewHost {
                 return undefined;
             // The port number alone proves nothing — it can be reused once the browser that owned it
             // exits. The endpoint's own answer is the evidence, and it has to name a browser.
-            if (typeof version.Browser !== 'string' || !/chrome|chromium|edge/i.test(version.Browser))
+            if (!isBrowserProduct(version.Browser))
                 return undefined;
             const client = new CdpClient(version.webSocketDebuggerUrl);
             await client.whenReady();
             // Asked through the protocol too, so a websocket that merely accepts connections is not
             // mistaken for a browser that answers.
             const info = await client.send('Browser.getVersion', {});
-            if (typeof info?.product !== 'string' || !/chrome|chromium|edge/i.test(info.product)) {
+            if (!isBrowserProduct(info?.product)) {
                 client.close();
                 return undefined;
             }
@@ -687,11 +699,38 @@ export class SystemBrowserViewHost {
         // The port file is deliberately NOT deleted here, and that is a reversal.
         //
         // It used to be removed so the launch loop below could not read a previous browser's port. But
-        // the loop already refuses any file older than the spawn (`freshPort` compares mtimes), so the
-        // deletion never protected it — while it DID destroy the only record of a browser that may
-        // still be running for this profile. That record is what `adoptRunningBrowser` needs when the
-        // launch comes back as a hand-off: the browser was alive the whole time, and without the file
-        // there is no way to find it again.
+        // the loop judges freshness against a snapshot taken below, so the deletion never protected it
+        // — while it DID destroy the only record of a browser that may still be running for this
+        // profile. That record is what `adoptRunningBrowser` needs when the launch comes back as a
+        // hand-off: the browser was alive the whole time, and without the file there is no way to find
+        // it again.
+        const portFile = join(this.profileDir, 'DevToolsActivePort');
+        /**
+         * What the port file was like BEFORE this launch, so "fresh" is judged against a snapshot
+         * rather than against a clock.
+         *
+         * The test used to be `mtimeMs < spawnedAt` — a filesystem timestamp compared to `Date.now()`.
+         * Those are different clocks with different resolutions, and CI is where it showed: a file the
+         * fake browser had just written was rejected as stale, so the loop waited out its full 30s
+         * against a browser that was already listening, because the file's mtime had rounded down
+         * below the spawn time. That is not a test-only problem: on any filesystem whose mtime
+         * resolution is coarser than a millisecond, the plugin would fail to see the browser it had
+         * just launched, and report a CDP timeout for a browser that was up the whole time.
+         *
+         * `undefined` means there was no file, so any file that appears afterwards is fresh. When one
+         * existed, a later mtime OR different contents makes the new one fresh. Byte-identical contents
+         * with an unchanged mtime is the PREVIOUS browser's port, and adopting it is what this whole
+         * check exists to prevent: it may name a port that now belongs to something else entirely.
+         */
+        const portFileBefore = (() => {
+            try {
+                return { mtimeMs: statSync(portFile).mtimeMs, contents: readFileSync(portFile, 'utf8') };
+            }
+            catch {
+                return undefined;
+            }
+        })();
+        // Kept for the failure message and for the exit listener's diagnostics; no longer a judgement.
         const spawnedAt = Date.now();
         let child;
         try {
@@ -727,22 +766,28 @@ export class SystemBrowserViewHost {
             // Clearing these is what makes the restart usable rather than merely alive.
             this.forgetBrowserState();
         });
-        const portFile = join(this.profileDir, 'DevToolsActivePort');
         /**
          * The port this launch wrote, or undefined while it has not written one yet.
          *
-         * A file left by the PREVIOUS browser is not evidence about this one. Its contents
-         * name a port that may now belong to something else entirely — another Chromium, a
-         * node --inspect — and connecting there publishes a client this host does not own and
-         * dispose() can never kill. Only a file written after the spawn counts.
+         * A file left by the PREVIOUS browser is not evidence about this one. Its contents name a port
+         * that may now belong to something else entirely — another Chromium, a `node --inspect` — and
+         * connecting there publishes a client this host does not own and dispose() can never kill.
+         * Only a file that CHANGED across this launch counts, which is what `portFileBefore` records.
          */
         const freshPort = () => {
             try {
                 if (!existsSync(portFile))
                     return undefined;
-                if (statSync(portFile).mtimeMs < spawnedAt)
+                const after = statSync(portFile);
+                const contents = readFileSync(portFile, 'utf8');
+                // Unchanged since before the launch: this is the previous browser's file, whatever its
+                // mtime says. Comparing against the snapshot rather than the spawn time is what keeps this
+                // correct on a filesystem whose timestamps are coarser than the clock behind spawnedAt.
+                if (portFileBefore !== undefined
+                    && after.mtimeMs <= portFileBefore.mtimeMs
+                    && contents === portFileBefore.contents)
                     return undefined;
-                const value = Number(readFileSync(portFile, 'utf8').split('\n')[0]?.trim() ?? '');
+                const value = Number(contents.split('\n')[0]?.trim() ?? '');
                 return Number.isInteger(value) && value > 0 ? value : undefined;
             }
             catch {
@@ -875,6 +920,66 @@ export class SystemBrowserViewHost {
     available() {
         return !this.disposed;
     }
+    /**
+     * Every page the browser currently holds, including ones this plugin did not create.
+     *
+     * Chrome and Edge own their own page creation. A click on a link that opens a new page — or any
+     * `window.open` — produces a page the provider never asked for, and nothing reports it back.
+     * Those pages are real: they hold memory and stay until something closes them. Measured on a real
+     * window: four pages present while `dsh_browser_list_tabs` reported one.
+     *
+     * Discovery is already on at connection time (see the blank-page normalisation), so
+     * `Target.getTargets` also lists pages that existed before this client connected.
+     * @returns the browser's pages, or an empty list when it cannot answer.
+     */
+    /**
+     * Every page the browser holds that THIS HOST did not open.
+     *
+     * Chrome and Edge own their own page creation. A click on a link that opens a new page — or any
+     * `window.open` — produces a page the provider never asked for, and nothing reports it back.
+     * Those pages are real: they hold memory and stay until something closes them. Measured on a real
+     * window: four pages present while `dsh_browser_list_tabs` reported one.
+     *
+     * Pages this host opened are EXCLUDED here rather than deduplicated by the caller, because the
+     * caller cannot do it: the provider knows a tab by its own id, the carrier knows a page by its
+     * CDP target id, and the two never match. The first version returned everything and relied on the
+     * caller to filter, which reported the same page twice.
+     *
+     * Discovery is already on at connection time (see the blank-page normalisation), so
+     * `Target.getTargets` also lists pages that existed before this client connected.
+     * @returns the browser's pages that are not ours, or an empty list when it cannot answer.
+     */
+    async listPages() {
+        try {
+            const client = await this.ensureClient();
+            const listed = await client.send('Target.getTargets', {});
+            const ours = new Set(this.sessions.values());
+            return (listed?.targetInfos ?? [])
+                .filter(entry => entry.type === 'page' && typeof entry.targetId === 'string')
+                .filter(entry => !ours.has(entry.targetId))
+                .map(entry => ({
+                id: entry.targetId,
+                url: typeof entry.url === 'string' ? entry.url : '',
+                ...typeof entry.title === 'string' && entry.title !== '' ? { title: entry.title } : {},
+            }));
+        }
+        catch {
+            // A listing must not fail harder than driving does; the next command reports a real problem.
+            return [];
+        }
+    }
+    /**
+     * Close one page by the target id {@link listPages} reported.
+     *
+     * `Target.closeTarget` is the browser's own close, so it works for pages this plugin never
+     * created. The page may already be gone if the human closed it in the meantime — the caller
+     * asked for it to be closed and it is, so that is not an error.
+     * @param id - the CDP target id.
+     */
+    async closePage(id) {
+        const client = await this.ensureClient();
+        await client.send('Target.closeTarget', { targetId: id }).catch(() => undefined);
+    }
     createView() {
         const viewId = randomUUID();
         return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-builtin-browser",
-  "version": "0.4.9",
+  "version": "0.4.11",
   "description": "Shared real browser plugin for DeepSeek Harness: install-and-use — a visible native browser the human can take over, driven by the agent over CDP. DOM-level interaction (React/Vue safe), per-task session isolation, cookie persistence (dsh_browser_auth), CAPTCHA detection, batch form fill (dsh_browser_fill), authenticated download, history/replay, action restriction",
   "type": "module",
   "main": "lib/index.js",

package/src/browser/types.ts

@@ -503,8 +503,15 @@ export interface BrowserTab {
   readonly active: boolean
 }
 
-/** Request to open a URL: into the active tab or a new tab. */
-export interface BrowserOpenRequest {
+/** One page a carrier holds, whether or not this plugin created it. */
+export interface CarrierPage {
+  /** Stable within one carrier session; used to address the page. */
+  readonly id: string
+  readonly url: string
+  readonly title?: string
+}
+
+/** Request to open a URL: into the active tab or a new tab. */export interface BrowserOpenRequest {
   /** The URL to open. */
   readonly url: string
   /** Open in a new tab (parallel). Default false (reuse the active tab). */

package/src/browser-electron/desktop-bridge-host.ts

@@ -30,6 +30,7 @@ import { join } from 'node:path'
 import { randomUUID } from 'node:crypto'
 import type { ElectronBrowserViewHost, ElectronViewHandle } from './provider.js'
 import type { BrowserUserAction } from './provider.js'
+import type { CarrierPage } from '../browser/types.js'
 
 
 /** Absolute path of the endpoint file the shell writes. */
@@ -171,7 +172,26 @@ export class DesktopBridgeViewHost implements ElectronBrowserViewHost {
       const probe = new BridgeConnection(endpoint, bridgeEndpointPath())
       try {
         const answer = await probe.call({ op: 'list' }, 5_000)
-        return answer.ok === true ? new DesktopBridgeViewHost(endpoint, sessionId) : undefined
+        if (answer.ok !== true) return undefined
+        // Refuse a panel this plugin cannot drive, before adopting it.
+        //
+        // The sidebar browser renders as a <webview> only where the shell exposes
+        // `dshDesktop.browser` and enables `webviewTag`. Where it renders as an <iframe> there is
+        // no webContents, no `getWebContentsId()` and no CDP endpoint — and every tool here is
+        // built on CDP, so adopting it means failing every call, with no path back to a carrier
+        // that works. Reported on DSH Desktop 2.0.17 with both conditions measured.
+        //
+        // Read here WITHOUT an owner on purpose, because the question is not about a conversation:
+        // whether the panel is a webview is decided by the shell's preload and window options, so
+        // it is the same answer for every conversation and needs no session context.
+        //
+        // `none` and `unknown` are NOT refusals: a panel that does not exist yet is created by the
+        // first open, and a probe that could not read the attribute has learned nothing.
+        if (String(answer.frame ?? 'unknown') === 'iframe') {
+          DesktopBridgeViewHost.refuseIframe = true
+          return undefined
+        }
+        return new DesktopBridgeViewHost(endpoint, sessionId)
       } finally {
         probe.close()
       }
@@ -181,11 +201,96 @@ export class DesktopBridgeViewHost implements ElectronBrowserViewHost {
     }
   }
 
+  /**
+   * Whether the last discovery refused a bridge because its sidebar panel is an iframe.
+   *
+   * Recorded so the entry point can say WHY the plugin is self-hosting on a shell that does have a
+   * bridge. Otherwise the user sees a second browser window and no explanation, on a machine where
+   * they just followed instructions to install the bridge.
+   */
+  private static refuseIframe = false
+
+  /** Whether discovery refused a bridge for an undrivable sidebar panel (see {@link discover}). */
+  static refusedIframePanel(): boolean {
+    return this.refuseIframe
+  }
+
   /** Whether this host can back views: the bridge already answered `list`. */
   available(): boolean {
     return true
   }
 
+  /**
+   * Every page this conversation's sidebar panel currently holds.
+   *
+   * The shell owns page creation inside the panel: a link the user or the agent clicks may open a
+   * new page, and nothing tells the provider. Those pages are real — they are what the human sees
+   * — but without this the tab model reports only the ones the provider created, so the rest are
+   * invisible to `dsh_browser_list_tabs` and unclosable through `dsh_browser_close_tab`.
+   *
+   * The bridge's `list` already answers with the sidebar guests, which is the same information, so
+   * this asks for it rather than reaching into the shell again.
+   * @returns the panel's pages, or an empty list when the bridge cannot answer.
+   */
+  /**
+   * Every sidebar page this conversation holds that THIS HOST did not open.
+   *
+   * The shell owns page creation inside the panel: a link the user or the agent clicks may open a
+   * new page, and nothing tells the provider. Those pages are real — they are what the human sees
+   * — but without this the tab model reports only the ones the provider created, so the rest are
+   * invisible to `dsh_browser_list_tabs` and unclosable through `dsh_browser_close_tab`.
+   *
+   * Pages this host opened are EXCLUDED here rather than deduplicated by the caller, because the
+   * caller cannot do it: the provider knows a tab by its own id and the carrier knows a page by the
+   * guest id, and the two never match. The first version returned everything and relied on the
+   * caller to filter, which reported the same page twice — the mapping that makes the match
+   * possible exists only here.
+   * @returns the panel's pages that are not ours, or an empty list when the bridge cannot answer.
+   */
+  async listPages(): Promise<readonly CarrierPage[]> {
+    try {
+      const answer = await this.connection.call({ op: 'list', owner: this.owner }, 5_000)
+      const guests = Array.isArray(answer.sidebar) ? answer.sidebar : []
+      const ours = new Set<number>()
+      for (const view of this.views.values()) {
+        if (typeof view.guest === 'number') ours.add(view.guest)
+      }
+      return guests
+        .filter((guest): guest is { id: number; url?: unknown } => typeof guest?.id === 'number')
+        .filter(guest => !ours.has(guest.id))
+        .map(guest => ({
+          id: String(guest.id),
+          url: typeof guest.url === 'string' ? guest.url : '',
+        }))
+    } catch {
+      // A bridge that cannot answer has a real problem, and the next command reports it. Failing
+      // the tab LIST here would make a listing worse than the driving it exists to describe.
+      return []
+    }
+  }
+
+  /**
+   * Close one sidebar page by the id {@link listPages} reported.
+   *
+   * The bridge closes sidebar pages by TITLE, and only the ones the caller owns — that is what
+   * stopped one conversation's teardown from destroying another's page. So the title is looked up
+   * through the same listing, and a page that no longer appears is treated as already gone rather
+   * than as an error: the caller asked for it to be closed, and it is.
+   * @param id - the sidebar guest id, as a string.
+   */
+  async closePage(id: string): Promise<void> {
+    const numeric = Number(id)
+    if (!Number.isFinite(numeric)) throw new Error(`not a sidebar page id: ${id}`)
+    const answer = await this.connection.call({ op: 'list', owner: this.owner }, 5_000)
+    const guests = Array.isArray(answer.sidebar) ? answer.sidebar : []
+    const title = guests
+      .filter((guest): guest is { id: number; title?: unknown } => Number(guest?.id) === numeric)
+      .map(guest => String(guest.title ?? ''))
+      .find(candidate => candidate !== '')
+    if (title === undefined) return
+    await this.connection.call({ op: 'closeSidebarBrowser', titles: [title], owner: this.owner }, 10_000)
+  }
+
   /**
    * The guest backing a view, materialized on first use.
    *
@@ -223,7 +328,16 @@ export class DesktopBridgeViewHost implements ElectronBrowserViewHost {
       owner,
       ...url !== undefined && url !== '' ? { url } : {},
     }, 30_000)
-    if (answer.ok !== true) throw new Error(`dsh-builtin-browser: sidebar unavailable (${String(answer.error)})`)
+    if (answer.ok !== true) {
+      // A bridge that answers but cannot produce a page is as unusable as one that has exited, and
+      // the difference matters here: `onLost` is what returns the surface to the self-hosted
+      // browser. Without this the same failure repeats on every call until DSH is restarted — on a
+      // shell whose sidebar panel is an iframe, that is every call forever. Reported as "installing
+      // the bridge made it worse than not installing it": the carrier was switched to one that
+      // cannot work, with no path back to the one that does.
+      if (String(answer.error).includes('produced no page')) this.reportLost()
+      throw new Error(`dsh-builtin-browser: sidebar unavailable (${String(answer.error)})`)
+    }
     const id = Number(answer.id)
     if (!Number.isFinite(id) || id <= 0) {
       throw new Error('dsh-builtin-browser: the sidebar reported no browser page for this conversation')

package/src/browser-electron/entry.ts

@@ -335,6 +335,21 @@ export function apply(ctx: Context & { browser: BrowserRuntime }, config: Config
       adopt(sidebar, 'driving the desktop sidebar browser')
       return
     }
+    // A bridge exists but its sidebar panel is an iframe. Saying nothing here would leave the user
+    // with a second browser window on a machine where they just followed the instructions to
+    // install the bridge, and no way to know the two facts are related. The carrier is not
+    // unavailable by accident: an iframe has no CDP endpoint, so adopting it would fail every call
+    // instead of falling back — see DesktopBridgeViewHost.discover.
+    if (DesktopBridgeViewHost.refusedIframePanel()) {
+      ctx.logger?.warn?.(
+        'dsh-builtin-browser: a desktop bridge is installed, but this shell renders the sidebar '
+        + 'browser panel as an iframe rather than a webview, which exposes no CDP endpoint and '
+        + 'cannot be driven. Using the browser this plugin hosts itself instead — that is the '
+        + 'independent window, not the sidebar. A shell that exposes `dshDesktop.browser` and '
+        + 'enables `webviewTag` would provide a drivable panel.',
+      )
+      return
+    }
     // The user explicitly asked for the sidebar, so silence would leave them with a setting
     // that did nothing and no way to tell why. This is reachable on `dsh web`, and on a desktop
     // whose shell never published a bridge endpoint. An automatic attempt stays quiet (the