dsh-builtin-browser 0.4.7 → 0.4.9

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-builtin-browser",
-  "version": "0.4.7",
-  "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 (browser_auth), CAPTCHA detection, batch form fill (browser_fill), authenticated download, history/replay, action restriction",
+  "version": "0.4.9",
+  "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",
   "types": "lib/index.d.ts",

package/scripts/verify-host-compat.mjs

@@ -169,20 +169,20 @@ try {
 
 const exec = { agent: { id: 'verify-host-compat' } }
 try {
-  const value = await registered.get('browser_session').execute({}, exec)
-  ok('browser_session ran', value !== undefined, JSON.stringify(value).slice(0, 100))
+  const value = await registered.get('dsh_browser_session').execute({}, exec)
+  ok('dsh_browser_session ran', value !== undefined, JSON.stringify(value).slice(0, 100))
 } catch (error) {
-  ok('browser_session ran', false, String(error && error.message))
+  ok('dsh_browser_session ran', false, String(error && error.message))
 }
 
 try {
-  const tool = registered.get('browser_a11y')
+  const tool = registered.get('dsh_browser_a11y')
   const value = await tool.execute({}, exec)
   const text = JSON.stringify(tool.output.render({}, value))
-  ok('browser_a11y ran and rendered', value?.nodes?.length === 1, '')
+  ok('dsh_browser_a11y ran and rendered', value?.nodes?.length === 1, '')
   ok('its renderer emits the element selector', text.includes('#probe'), text.slice(0, 120))
 } catch (error) {
-  ok('browser_a11y ran', false, String(error && error.message))
+  ok('dsh_browser_a11y ran', false, String(error && error.message))
 }
 
 console.log('')

package/src/browser/types.ts

@@ -65,7 +65,7 @@ export interface BrowserScrollRequest {
 
 /** Press one named key (Enter, Tab, arrows, …). */
 export interface BrowserKeyRequest {
-  /** Key name from the supported set (see the browser_key tool). */
+  /** Key name from the supported set (see the dsh_browser_key tool). */
   readonly key: string
 }
 
@@ -361,7 +361,7 @@ export interface BrowserSnapshotElement {
   /**
    * True when the element lives inside an (same-origin) iframe: coordinates
    * are still top-document, but DOM selectors are frame-scoped — reach the
-   * element via `iframe.contentDocument` in browser_execute.
+   * element via `iframe.contentDocument` in dsh_browser_execute.
    */
   readonly frame?: boolean
 }

package/src/browser-electron/entry.ts

@@ -5,7 +5,7 @@
  * `ctx.electronViewHost`, that host is used (embedded, human-machine shared
  * view). Otherwise the plugin self-hosts: it spawns its own Electron child
  * (`host-main.js`) and drives it over a local TCP JSON-RPC socket, so
- * installing the plugin is enough for `browser_*` tools to work on any
+ * installing the plugin is enough for `dsh_browser_*` tools to work on any
  * surface.
  * @module dsh-browser/browser-electron
  */
@@ -48,7 +48,7 @@ export interface Config {
   /** Allow navigation only to HTTP(S) URLs. Default true. */
   readonly httpOnly?: boolean
   /**
-   * Directory `browser_download` save paths must resolve inside (prevents a
+   * Directory `dsh_browser_download` save paths must resolve inside (prevents a
    * prompt-injected agent from writing arbitrary machine paths). Default:
    * the user's Downloads folder; override to confine downloads elsewhere.
    */

package/src/browser-electron/history-store.ts

@@ -1,6 +1,6 @@
 /**
  * Persistent browsing history: which pages the shared browser actually visited,
- * kept independently from any session's operation log (`browser_history`) and
+ * kept independently from any session's operation log (`dsh_browser_history`) and
  * from the browser process's lifetime.
  *
  * It lives beside the browser profile (`$DSH_HOME/dsh-builtin-browser-host/

package/src/browser-electron/host-main.ts

@@ -41,7 +41,7 @@ import { dirname, join } from 'node:path'
 // several Electron instances sharing Roaming\Electron fight over the GPU
 // cache/session locks, which can leave the window without a display surface
 // (capturePage then fails). A dedicated userData also persists cookies across
-// host restarts (on top of browser_auth). Must run before app is ready.
+// host restarts (on top of dsh_browser_auth). Must run before app is ready.
 try {
   const base = process.env.DSH_HOME ?? app.getPath('appData')
   app.setPath('userData', join(base, 'dsh-builtin-browser-host'))
@@ -769,7 +769,7 @@ async function handle(op: string, msg: { id: number; viewId?: string; windowId?:
         const entry = win?.views.get(viewId)
         if (win === undefined || entry === undefined) throw new Error(`focus: unknown view ${viewId}`)
         // Keys go to the view that holds web focus. A view that was never
-        // clicked holds none, so the FIRST browser_key of a session was dropped
+        // clicked holds none, so the FIRST dsh_browser_key of a session was dropped
         // by the renderer while CDP still answered the dispatch with success —
         // and `document.hasFocus()` inside the page even read true.
         const contents = entry.webContentsView.webContents
@@ -881,7 +881,7 @@ async function handle(op: string, msg: { id: number; viewId?: string; windowId?:
           throw new Error('capture produced no image (view not painted)')
         }
         // The measured size travels with the image. Without it the native path — which is the
-        // default self-hosted one — could never answer `browser_screenshot`'s width/height,
+        // default self-hosted one — could never answer `dsh_browser_screenshot`'s width/height,
         // because the seam's only channel was {base64, mime} and the provider had nothing to
         // forward. The caller's `maxWidth`/`maxHeight` are applied here, so this is the only
         // place that knows what came back.

package/src/browser-electron/provider.ts

@@ -393,7 +393,7 @@ export interface ElectronBrowserProviderConfig {
    */
   readonly contentMaxChars?: number
   /**
-   * Directory `browser_download` save paths must resolve inside (prevents a
+   * Directory `dsh_browser_download` save paths must resolve inside (prevents a
    * prompt-injected agent from writing arbitrary machine paths). Default:
    * `~/Downloads`. NOTE: this default is a convenience, not a security
    * boundary — on Windows it may resolve to OneDrive/redirected paths;
@@ -477,7 +477,7 @@ export function layoutSize(metrics: Record<string, unknown>): { width: number; h
 }
 
 /**
- * Map CDP cookies onto the shape `browser_auth` exports.
+ * Map CDP cookies onto the shape `dsh_browser_auth` exports.
  *
  * CDP reports a cookie as domain + path rather than a URL, and in seconds rather than
  * milliseconds, so both are converted. Entries missing a name, value or domain are
@@ -955,9 +955,9 @@ export class ElectronBrowserProvider implements BrowserProvider {
   /**
    * Page.navigate resolves at navigation COMMIT, not at load: the new document
    * is already current (so location.href and document.title are the new page's)
-   * while its DOM is still being parsed. browser_open snapshots immediately
+   * while its DOM is still being parsed. dsh_browser_open snapshots immediately
    * after navigating, which is why it could report the right title with zero
-   * interactive elements — and why a separate browser_snapshot right after
+   * interactive elements — and why a separate dsh_browser_snapshot right after
    * always found them.
    *
    * Wait — bounded, best-effort — for the new document to settle: readyState
@@ -1077,7 +1077,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
    *
    * A renderer only delivers key events to the view that holds web focus. A
    * view that was created but never clicked holds none — and `Input` events
-   * injected over CDP do not grant it — so the FIRST `browser_key` of a fresh
+   * injected over CDP do not grant it — so the FIRST `dsh_browser_key` of a fresh
    * session vanished inside the renderer while the command still answered
    * success. Hosts that cannot focus a view (a test double, a different shell
    * adapter) simply have no `focus`, and nothing changes for them.
@@ -1086,7 +1086,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
     if (handle.focus === undefined) return
     try {
       // Bounded, unlike the rest of this call: the child RPC has no timeout of its own,
-      // and this runs before typing, so an unresponsive child would hang browser_key for
+      // and this runs before typing, so an unresponsive child would hang dsh_browser_key for
       // good. A timeout is caught below exactly like any other focus failure, so the
       // best-effort contract is unchanged.
       await withTimeout(handle.focus(), 5_000, undefined, 'browser: focusing the view timed out')
@@ -1328,12 +1328,12 @@ export class ElectronBrowserProvider implements BrowserProvider {
       // A timeout leaves the wedged view in the session, so every later read would pay the same
       // 30 seconds again — and `terminatePage` only interrupts the running script, it does not
       // make the view readable. Replacing it is what turns a permanent loss into one bad call:
-      // the tab keeps the id the caller holds, and the next browser_open with the real URL
+      // the tab keeps the id the caller holds, and the next dsh_browser_open with the real URL
       // repopulates it.
       if (error instanceof Error && error.name === 'TimeoutError') {
         this.replaceTabWithBlank(s, tab)
         throw new BrowserError(
-          'browser: snapshot timed out; the stuck tab was reset to blank. Call browser_open with the real target URL before reading it again.',
+          'browser: snapshot timed out; the stuck tab was reset to blank. Call dsh_browser_open with the real target URL before reading it again.',
           'BROWSER_SNAPSHOT_TIMEOUT',
           { cause: error },
         )
@@ -1536,7 +1536,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
       if (error instanceof Error && error.name === 'TimeoutError') {
         this.replaceTabWithBlank(s, tab)
         throw new BrowserError(
-          'browser: a11y timed out; the stuck tab was reset to blank. Call browser_open with the real target URL before reading it again.',
+          'browser: a11y timed out; the stuck tab was reset to blank. Call dsh_browser_open with the real target URL before reading it again.',
           'BROWSER_A11Y_TIMEOUT',
           { cause: error },
         )
@@ -2003,7 +2003,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
       placeholder: f.placeholder ?? null,
       // A field with NO kind is a field with no kind FILTER: absent, not 'text'. Defaulting
       // it to 'text' here made `if (spec.kind)` above always true, so every unspecified
-      // field was narrowed to an <input> — browser_fill on a <textarea> reported
+      // field was narrowed to an <input> — dsh_browser_fill on a <textarea> reported
       // `no "text" control matched`, and a contenteditable could not match any kind at all.
       // The value stays a string or null (never undefined): the in-page check tests truthiness,
       // and JSON drops an undefined member entirely, which is the same thing here.
@@ -2138,7 +2138,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
             el.dispatchEvent(new Event('change', { bubbles: true }))
             out.push({ ok: true, method: 'select', target: describe(spec) })
           } else if (type === 'file') {
-            out.push({ ok: false, error: 'file inputs cannot be set from script; use browser_download or ask the human', target: describe(spec) })
+            out.push({ ok: false, error: 'file inputs cannot be set from script; use dsh_browser_download or ask the human', target: describe(spec) })
           } else if (type === 'checkbox') {
             const want = spec.value === true || spec.value === 'true' || spec.value === 'on'
             if (el.checked !== want) el.click()
@@ -2592,7 +2592,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
    * Refuse an action the settings have switched off.
    *
    * These switches belong to the OPERATOR. The settings document is written through the
-   * plugin's own panel and no tool can reach it, so — unlike `browser_restrict`, which the
+   * plugin's own panel and no tool can reach it, so — unlike `dsh_browser_restrict`, which the
    * model owns and can lift at will — a refusal here stands for as long as the setting does.
    * That is the point of them: a deployment can take page-script execution, downloads, or
    * login-state writes off the table without relying on the model's cooperation.
@@ -2619,7 +2619,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
 
   /**
    * Admit a caller-supplied save path for a file the browser writes to disk.
-   * ONE gate for both `browser_download` and `browser_screenshot`: the path
+   * ONE gate for both `dsh_browser_download` and `dsh_browser_screenshot`: the path
    * must be absolute, must resolve inside `downloadDir`, and must not already
    * exist. Without it a prompt-injected agent could write — or silently
    * replace — any file the DSH process can reach, which also escapes the file
@@ -3053,7 +3053,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
   }
 
   /**
-   * List persisted visits, newest first — what `browser_visited` reads back.
+   * List persisted visits, newest first — what `dsh_browser_visited` reads back.
    * @param options - result cap and an optional hostname filter.
    * @returns the matching visits, or an empty list when history is disabled.
    */
@@ -3200,7 +3200,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
    *
    * A view whose renderer never commits cannot be read again: every evaluate into it runs out its
    * whole budget. Replacing it is what turns that from permanent into one bad call — the tab id
-   * callers hold stays valid, and the next `browser_open` with the real URL re-populates it.
+   * callers hold stays valid, and the next `dsh_browser_open` with the real URL re-populates it.
    *
    * The old view is destroyed AFTER the new one is in place, so a failure here cannot leave the
    * session holding a handle that is already gone.

package/src/browser-electron/remote-host.ts

@@ -1327,7 +1327,7 @@ class DeferredRemoteView implements ElectronViewHandle {
    * with "browser host is not running". Instead: drop the cache, rebuild the
    * view against a freshly spawned child, and retry the operation exactly
    * once — so sessions that survive a host death self-heal on their FIRST
-   * call after it, without a manual browser_reset_session. Page-level errors
+   * call after it, without a manual dsh_browser_reset_session. Page-level errors
    * are never retried (the view itself is fine).
    */
   private async withRecovery<T>(op: (view: RemoteView) => Promise<T>): Promise<T> {

package/src/browser-electron/settings-store.ts

@@ -55,15 +55,15 @@ export interface BrowserSettings {
    *
    * These are OPERATOR switches: the settings panel is not reachable from the model, so a
    * value here refuses whatever the model asks for, and no tool can lift it. That is what
-   * separates them from `browser_restrict`, which is the model's own soft guardrail. All
+   * separates them from `dsh_browser_restrict`, which is the model's own soft guardrail. All
    * three default to on, which is the documented out-of-the-box behaviour.
    */
   readonly actions: {
-    /** Run arbitrary page scripts in the active tab (`browser_execute`). */
+    /** Run arbitrary page scripts in the active tab (`dsh_browser_execute`). */
     readonly allowExecute: boolean
-    /** Download a URL to disk (`browser_download`). */
+    /** Download a URL to disk (`dsh_browser_download`). */
     readonly allowDownload: boolean
-    /** Write cookies — importing login state (`browser_auth` restore). */
+    /** Write cookies — importing login state (`dsh_browser_auth` restore). */
     readonly allowCredentialWrite: boolean
   }
 }

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.
@@ -178,6 +187,21 @@ 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 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 +439,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 +537,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 +573,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 (typeof version.Browser !== 'string' || !/chrome|chromium|edge/i.test(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 (typeof info?.product !== 'string' || !/chrome|chromium|edge/i.test(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 +648,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 +704,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 +831,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). `
@@ -892,13 +1007,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 +1081,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 +1099,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>>()
 

package/src/index.ts

@@ -3,7 +3,7 @@
  * pieces. The cordis.patch.yml rows reference subpath exports:
  *   - `dsh-builtin-browser/browser`          -> the ctx.browser seam (Service)
  *   - `dsh-builtin-browser/browser-electron` -> the Electron CDP provider
- *   - `dsh-builtin-browser/tool-browser`     -> the model-facing browser_* tools
+ *   - `dsh-builtin-browser/tool-browser`     -> the model-facing dsh_browser_* tools
  * The capability itself is composed by those rows; this root entry exists for
  * programmatic imports AND because the host's client-module scan identifies a
  * package's browser half through a loader row whose specifier resolves to the