dsh-builtin-browser 0.4.8 → 0.4.10

package/src/browser-electron/provider.ts

@@ -51,6 +51,7 @@ import type {
   ExportedCookie,
 } from '../browser/types.js'
 import { BrowserError } from '../browser/types.js'
+import type { CarrierPage } from '../browser/types.js'
 
 /**
  * Page-context human-verification (CAPTCHA / bot-detection) detection. Runs
@@ -156,6 +157,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
@@ -413,6 +443,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'
@@ -420,6 +459,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`. */
@@ -771,6 +812,27 @@ export class ElectronBrowserProvider implements BrowserProvider {
         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
   }
 
@@ -784,6 +846,19 @@ export class ElectronBrowserProvider implements BrowserProvider {
 
   /** Close one tab; closing the active tab activates the next. */
   closeTab(session: BrowserSessionId, tabId: string): Promise<void> {
+    // 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
@@ -1747,7 +1822,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
     // 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 } satisfies CdpMouseParams, 'move')
+      await send({ type: 'mouseMoved', x, y, buttons: 0 } satisfies CdpMouseParams, 'move')
     } catch (error) {
       throw new BrowserError(`browser: click failed: ${String(error)}`, 'BROWSER_CLICK_FAILED', { cause: error })
     }
@@ -1767,12 +1842,13 @@ export class ElectronBrowserProvider implements BrowserProvider {
           x,
           y,
           button: 'left',
+          buttons: 0,
           clickCount: 1,
         } satisfies CdpMouseParams)
         .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
       // never left in a stuck pressed state.
@@ -1780,7 +1856,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
       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
       // left pressed before surfacing the failure.

package/src/browser-electron/system-browser.ts

@@ -38,6 +38,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.
@@ -73,6 +82,7 @@ const defaultLauncher: BrowserLauncher = (path, args) =>
 import { spawn, type ChildProcess } from 'node:child_process'
 import { randomUUID } from 'node:crypto'
 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'
@@ -178,6 +188,34 @@ const INSTALL_LOCATIONS: Record<DetectedBrowser['kind'], Partial<Record<NodeJS.P
  * @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: unknown): boolean {
+  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: unknown): boolean {
+  if (typeof url !== 'string') return false
+  return url === 'about:blank'
+    || url.startsWith('chrome://newtab')
+    || url.startsWith('chrome://new-tab-page')
+}
+
 function expandLocation(location: string, env: NodeJS.ProcessEnv): string {
   return location.replace(/%([^%]+)%/g, (whole, name: string) =>
     env[name] ?? env[name.toUpperCase()] ?? env[name.toLowerCase()] ?? whole)
@@ -415,6 +453,16 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
    */
   private clientSuspect = false
   private child: ChildProcess | undefined
+  /**
+   * 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.
+   */
+  private adoptedRunning = false
+  /** Whether this connection's surplus blank pages have been collapsed already. */
+  private blanksNormalized = false
   private starting: Promise<CdpClient> | undefined
 
   /**
@@ -503,6 +551,10 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
   private forgetBrowserState(): void {
     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
   }
 
   private async ensureClient(): Promise<CdpClient> {
@@ -535,7 +587,70 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
     }
     // 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.
+   */
+  private async adoptRunningBrowser(why: string): Promise<CdpClient | undefined> {
+    const portFile = join(this.profileDir, 'DevToolsActivePort')
+    let port: number
+    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() as { webSocketDebuggerUrl?: string; Browser?: string }
+      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', {}) as { product?: string }
+      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
+    }
   }
 
   /**
@@ -547,6 +662,11 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
    * @returns the connected client.
    */
   private async start(): Promise<CdpClient> {
+    // 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}`,
@@ -598,12 +718,14 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
         })
       })
     }
-    // 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: ReturnType<typeof spawn>
     try {
@@ -723,6 +845,13 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
       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). `
@@ -752,6 +881,69 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
     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(): Promise<readonly CarrierPage[]> {
+    try {
+      const client = await this.ensureClient()
+      const listed = await client.send('Target.getTargets', {}) as {
+        targetInfos?: Array<{ targetId?: string; type?: string; url?: string; title?: string }>
+      }
+      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 as string))
+        .map(entry => ({
+          id: entry.targetId as string,
+          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: string): Promise<void> {
+    const client = await this.ensureClient()
+    await client.send('Target.closeTarget', { targetId: id }).catch(() => undefined)
+  }
+
   createView(): ElectronViewHandle {
     const viewId = randomUUID()
     return {
@@ -892,13 +1084,34 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
   dispose(): void {
     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)) {
-      try { leftover.kill() } catch { /* already gone */ }
+    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 { void client.send('Browser.close', {}).catch(() => { /* it is closing, not talking */ }) } 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 is ChildProcess => 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 = (): void => { 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) {
@@ -945,9 +1158,15 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
   /** Create and attach the target for one view. Serialised by {@link ensureSession}. */
   private async buildSession(viewId: string): Promise<string> {
     const client = await this.ensureClient()
-    const created = await client.send('Target.createTarget', { url: 'about:blank' }) as { targetId?: string }
-    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 }) as { sessionId?: string }
     const sessionId = attached?.sessionId
     if (typeof sessionId !== 'string') throw new Error('dsh-builtin-browser: the browser did not attach to the new page')
@@ -957,6 +1176,92 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
     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.
+   */
+  private async adoptBlankTarget(client: CdpClient): Promise<string | undefined> {
+    try {
+      const listed = await client.send('Target.getTargets', {}) as {
+        targetInfos?: Array<{ targetId?: string; type?: string; url?: string }>
+      }
+      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. */
+  private async createTarget(client: CdpClient): Promise<string> {
+    const created = await client.send('Target.createTarget', { url: 'about:blank' }) as { targetId?: string }
+    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.
+   */
+  private async normalizeBlankPages(client: CdpClient): Promise<number> {
+    try {
+      await client.send('Target.setDiscoverTargets', { discover: true })
+      const listed = await client.send('Target.getTargets', {}) as {
+        targetInfos?: Array<{ targetId?: string; type?: string; url?: string }>
+      }
+      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 as string
+        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. */
   private readonly sessionBuilding = new Map<string, Promise<string>>()