dsh-builtin-browser 0.4.8 → 0.4.10

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

@@ -36,6 +36,15 @@ import { join } from 'node:path';
  * exited, and that exit was reported as a bad browser path.
  */
 const EXIT_GRACE_MS = 3_000;
+/**
+ * How long a browser is given to close itself after being asked, before it is killed.
+ *
+ * Long enough for Chrome to flush its profile, which is what keeps the next launch from reading
+ * the profile as crashed and offering a session restore. Deliberately not the same knob as
+ * {@link EXIT_GRACE_MS}: that one waits for a browser to die because a NEW one cannot start until
+ * it does, this one merely prefers a graceful exit to a kill.
+ */
+const CLOSE_GRACE_MS = 6_000;
 /**
  * Ceiling on one attempt to ask a discovered CDP port who it is.
  *
@@ -147,6 +156,33 @@ 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.
+ *
+ * Deliberately narrow: `about:blank` and Chrome's own new-tab pages, and nothing else. A wider
+ * test ("has no path", "starts with chrome://") would sooner or later match a page the user is
+ * reading, and the caller closes what this returns.
+ * @param url - the target's reported URL.
+ */
+function isBlankUrl(url) {
+    if (typeof url !== 'string')
+        return false;
+    return url === 'about:blank'
+        || url.startsWith('chrome://newtab')
+        || url.startsWith('chrome://new-tab-page');
+}
 function expandLocation(location, env) {
     return location.replace(/%([^%]+)%/g, (whole, name) => env[name] ?? env[name.toUpperCase()] ?? env[name.toLowerCase()] ?? whole);
 }
@@ -385,6 +421,16 @@ export class SystemBrowserViewHost {
      */
     clientSuspect = false;
     child;
+    /**
+     * True when the browser in use was adopted from a previous run rather than launched here.
+     *
+     * Worth recording because the two differ on teardown: a browser this host spawned is its to
+     * kill, while one it merely took over belongs to a process that is already gone — closing it is
+     * still right (it holds the profile nobody else can use), but it is a decision, not cleanup.
+     */
+    adoptedRunning = false;
+    /** Whether this connection's surplus blank pages have been collapsed already. */
+    blanksNormalized = false;
     starting;
     /**
      * Browsers that ignored a kill.
@@ -468,6 +514,10 @@ export class SystemBrowserViewHost {
     forgetBrowserState() {
         this.views.clear();
         this.sessions.clear();
+        // A new browser comes with its own surplus pages, so the tidy-up runs again for it. Without
+        // this, a restart would inherit the previous connection's "already handled" and leave the new
+        // browser's extra blank page in place for the rest of the session.
+        this.blanksNormalized = false;
     }
     async ensureClient() {
         // A disposed host must never start a browser: doing so would spawn a process
@@ -501,7 +551,78 @@ export class SystemBrowserViewHost {
         }
         // Concurrent first calls share one startup rather than racing two browsers.
         this.starting ??= this.start().finally(() => { this.starting = undefined; });
-        return await this.starting;
+        const client = await this.starting;
+        // Once per connection. A browser opens more than one page when it starts, and the surplus is
+        // invisible to the plugin's tab model — see normalizeBlankPages for why that matters.
+        if (!this.blanksNormalized) {
+            this.blanksNormalized = true;
+            await this.normalizeBlankPages(client);
+        }
+        return client;
+    }
+    /**
+     * Take over a browser already serving this profile, instead of racing it.
+     *
+     * A previous DSH process leaves its browser running: the child handle died with that process, so
+     * nothing here knows about it, and `start()`'s cleanup branch is skipped because it keys on
+     * `this.child`. Launching then does something worse than fail — on Windows Chrome hands the
+     * request to the instance already holding the profile and exits 0, and that exit is read as a
+     * launch failure. The user is told to go kill the leftovers by hand, on every restart, which is
+     * exactly what was reported.
+     *
+     * The launch loop deliberately refuses to trust a `<profile>/DevToolsActivePort` left by a
+     * previous launch, and it is right to: a stale port number can be reused by something that is
+     * not a browser at all. What makes adoption safe HERE is that this runs BEFORE launching, on a
+     * file that lives inside this plugin's own profile directory — only a browser started with this
+     * `--user-data-dir` writes it — and the endpoint is then asked to identify itself.
+     * @param why - a short phrase for the log, naming which attempt this is.
+     * @returns a connected client for the running browser, or undefined when there is none.
+     */
+    async adoptRunningBrowser(why) {
+        const portFile = join(this.profileDir, 'DevToolsActivePort');
+        let port;
+        try {
+            if (!existsSync(portFile))
+                return undefined;
+            const value = Number(readFileSync(portFile, 'utf8').split('\n')[0]?.trim() ?? '');
+            if (!Number.isInteger(value) || value <= 0)
+                return undefined;
+            port = value;
+        }
+        catch {
+            return undefined;
+        }
+        try {
+            const version = await (await fetch(`http://127.0.0.1:${port}/json/version`, {
+                signal: AbortSignal.timeout(PORT_PROBE_MS),
+            })).json();
+            if (typeof version.webSocketDebuggerUrl !== 'string')
+                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 (!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 (!isBrowserProduct(info?.product)) {
+                client.close();
+                return undefined;
+            }
+            if (this.disposed) {
+                client.close();
+                return undefined;
+            }
+            this.client = client;
+            this.adoptedRunning = true;
+            return client;
+        }
+        catch {
+            // No endpoint, nothing listening, or not a browser: all of them mean "launch one".
+            return undefined;
+        }
     }
     /**
      * Launch the browser with a private profile and connect over CDP.
@@ -512,6 +633,12 @@ export class SystemBrowserViewHost {
      * @returns the connected client.
      */
     async start() {
+        // Before spawning anything: is a browser for THIS profile already running? A DSH restart
+        // leaves one behind, and launching into it is the failure reported as "exited immediately
+        // after launch (exit code 0)" that required killing seven processes by hand.
+        const adopted = await this.adoptRunningBrowser('before launch');
+        if (adopted !== undefined)
+            return adopted;
         const args = [
             '--remote-debugging-port=0',
             `--user-data-dir=${this.profileDir}`,
@@ -569,15 +696,14 @@ export class SystemBrowserViewHost {
                 });
             });
         }
-        // The port file belongs to the browser that just died, and it is NOT removed when the
-        // process is killed: nothing gives a terminated browser a chance to clean up. The launch
-        // loop below reads it to learn the port, so a stale file means connecting to whatever else
-        // holds that port — or to the previous instance — and publishing a client this host does
-        // not own and dispose() can never kill.
-        try {
-            rmSync(join(this.profileDir, 'DevToolsActivePort'), { force: true });
-        }
-        catch { /* nothing to remove */ }
+        // 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.
         const spawnedAt = Date.now();
         let child;
         try {
@@ -728,6 +854,14 @@ export class SystemBrowserViewHost {
             const code = child.exitCode;
             const signal = child.signalCode;
             const clean = code === 0 && signal === null;
+            // Exit code 0 IS the hand-off: the request went to an instance already holding this profile,
+            // so that instance is our browser and it is running right now. Adopting it turns the
+            // reported "kill the leftovers by hand, on every restart" into a call that just works.
+            if (clean) {
+                const recovered = await this.adoptRunningBrowser('after a hand-off');
+                if (recovered !== undefined)
+                    return recovered;
+            }
             throw new Error(clean
                 ? `dsh-builtin-browser: ${target} exited immediately after launch (exit code 0). `
                     + 'That means it handed the request to an instance already using this profile '
@@ -753,6 +887,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 {
@@ -892,20 +1086,39 @@ export class SystemBrowserViewHost {
         if (this.disposed)
             return;
         this.disposed = true;
+        const client = this.client;
         this.forgetBrowserState();
-        this.client?.close();
-        try {
-            this.child?.kill();
-        }
-        catch { /* already gone */ }
-        // And anything that ignored an earlier kill. They hold this profile, so leaving them
-        // running means the next launch contends with a browser nobody owns.
-        for (const leftover of this.stubborn.splice(0)) {
+        this.client = undefined;
+        // Ask before killing. `kill()` on Windows is TerminateProcess, which gives the browser no
+        // chance to flush its profile — and Chrome records how it ended in that profile, so a
+        // hard kill leaves it marked as a crash and the NEXT launch offers to restore a session.
+        // That is a visible symptom (an extra window) traced all the way back to this line.
+        if (client !== undefined) {
             try {
-                leftover.kill();
+                void client.send('Browser.close', {}).catch(() => { });
             }
             catch { /* already gone */ }
         }
+        // Both the browser we launched and anything that ignored an earlier kill. They hold this
+        // profile, so leaving them running means the next launch contends with a browser nobody owns.
+        const doomed = [this.child, ...this.stubborn.splice(0)].filter((entry) => entry !== undefined);
+        this.child = undefined;
+        for (const dying of doomed) {
+            /**
+             * A bounded reprieve, then the kill we used to do immediately.
+             *
+             * The timer is unref'd so it never holds the process open: a DSH shutdown that is itself
+             * ending does not wait for this, and the browser — having been asked to close — generally
+             * gets there on its own. If it does not, the kill still lands while the process lives.
+             */
+            const force = () => { try {
+                dying.kill();
+            }
+            catch { /* already gone */ } };
+            const timer = setTimeout(force, CLOSE_GRACE_MS);
+            timer.unref?.();
+            dying.once('exit', () => { clearTimeout(timer); });
+        }
         const ephemeral = this.ephemeralDir;
         if (ephemeral !== undefined && this.child !== undefined) {
             // The browser flushes its profile while shutting down, so deleting later avoids
@@ -957,10 +1170,15 @@ export class SystemBrowserViewHost {
     /** Create and attach the target for one view. Serialised by {@link ensureSession}. */
     async buildSession(viewId) {
         const client = await this.ensureClient();
-        const created = await client.send('Target.createTarget', { url: 'about:blank' });
-        const targetId = created?.targetId;
-        if (typeof targetId !== 'string')
-            throw new Error('dsh-builtin-browser: the browser did not create a page');
+        // Adopt a blank page the browser opened on its own before creating another one.
+        //
+        // Chrome starts with more than one page when handed a URL on top of its own start page, so
+        // creating a target here discarded the original and left it behind as a tab that is not in
+        // the plugin's tab model — invisible to `dsh_browser_list_tabs`, and therefore unclosable
+        // through the tools. Taking the blank instead makes the page the browser already opened the
+        // one the caller gets.
+        const adopted = await this.adoptBlankTarget(client);
+        const targetId = adopted ?? await this.createTarget(client);
         const attached = await client.send('Target.attachToTarget', { targetId, flatten: true });
         const sessionId = attached?.sessionId;
         if (typeof sessionId !== 'string')
@@ -970,6 +1188,94 @@ export class SystemBrowserViewHost {
         this.views.set(viewId, { session: sessionId, client });
         return sessionId;
     }
+    /**
+     * Take an unclaimed blank page, if the browser has one to spare.
+     *
+     * "Unclaimed" is what matters: a blank page the plugin is already driving belongs to a view, and
+     * handing the same target to a second view would make two views share one page. The page kept by
+     * {@link normalizeBlankPages} is exactly the unclaimed one this is looking for.
+     * @param client - the connected browser.
+     * @returns the target id to reuse, or undefined when a new page has to be created.
+     */
+    async adoptBlankTarget(client) {
+        try {
+            const listed = await client.send('Target.getTargets', {});
+            const claimed = new Set(this.sessions.values());
+            for (const entry of listed?.targetInfos ?? []) {
+                if (entry.type !== 'page' || typeof entry.targetId !== 'string')
+                    continue;
+                if (!isBlankUrl(entry.url))
+                    continue;
+                if (claimed.has(entry.targetId))
+                    continue;
+                return entry.targetId;
+            }
+            return undefined;
+        }
+        catch {
+            // Discovery is best-effort; creating a page is the behaviour this replaced.
+            return undefined;
+        }
+    }
+    /** Create one page, refusing to go on without an id. */
+    async createTarget(client) {
+        const created = await client.send('Target.createTarget', { url: 'about:blank' });
+        const targetId = created?.targetId;
+        if (typeof targetId !== 'string')
+            throw new Error('dsh-builtin-browser: the browser did not create a page');
+        return targetId;
+    }
+    /**
+     * Collapse the blank pages a freshly started browser comes with down to one.
+     *
+     * Chrome opens more than one page when it is given a URL on top of its own start page, and this
+     * is the browser's behaviour rather than a session restore: measured on a cleanly exited profile
+     * as well as a crashed one, both pages appear within a second of launch. There is nothing to
+     * configure away — by the time a client can talk to the browser, both already exist.
+     *
+     * Left alone the surplus page is invisible to the plugin's tab model and therefore unclosable
+     * through the tools, so it survives every navigation and accumulates for as long as the window
+     * lives. One is kept deliberately: {@link buildSession} adopts it instead of creating a third.
+     *
+     * `Target.setDiscoverTargets` has to come first. Without it the browser may omit pages that
+     * existed before this client connected — which is precisely the page that needs closing, and the
+     * reason the first attempt at this fix failed silently.
+     * @param client - the connected browser.
+     * @returns how many surplus blank pages were closed.
+     */
+    async normalizeBlankPages(client) {
+        try {
+            await client.send('Target.setDiscoverTargets', { discover: true });
+            const listed = await client.send('Target.getTargets', {});
+            const blanks = (listed?.targetInfos ?? []).filter(entry => entry.type === 'page' && typeof entry.targetId === 'string' && isBlankUrl(entry.url));
+            const claimed = new Set(this.sessions.values());
+            let closed = 0;
+            // Keep the first unclaimed blank (that is the one buildSession will adopt) and close the rest.
+            let kept = false;
+            for (const entry of blanks) {
+                const targetId = entry.targetId;
+                if (claimed.has(targetId))
+                    continue;
+                if (!kept) {
+                    kept = true;
+                    continue;
+                }
+                try {
+                    await client.send('Target.closeTarget', { targetId });
+                    closed += 1;
+                }
+                catch {
+                    // It may already be gone; one failure must not stop the rest.
+                }
+            }
+            return closed;
+        }
+        catch {
+            // A browser that will not answer Target commands has a real problem, and the next command
+            // will report it. Turning a tidy-up into a functional error here would hide that.
+            return 0;
+        }
+    }
     /** Views whose session is being created right now, so a second caller waits for the first. */
     sessionBuilding = new Map();
     /** sessionId -> targetId, so a destroyed view can close the right page. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-builtin-browser",
-  "version": "0.4.8",
+  "version": "0.4.10",
   "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