dsh-builtin-browser 0.4.1 → 0.4.5

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

@@ -25,15 +25,57 @@
  * @module dsh-browser/browser-electron/system-browser
  */
 
-import { readFileSync, rmSync } from 'node:fs'
+import { readFileSync, rmSync, statSync } from 'node:fs'
 import { existsSync } from 'node:fs'
 import { join } from 'node:path'
+
+/**
+ * How long a killed browser is given to actually exit before the launch proceeds.
+ *
+ * `kill()` only sends the signal — on Windows it is TerminateProcess, which is asynchronous —
+ * and the browser may hold this profile's singleton lock for a while afterwards. Spawning
+ * immediately meant the replacement saw a live instance, handed its command line over and
+ * exited, and that exit was reported as a bad browser path.
+ */
+const EXIT_GRACE_MS = 3_000
+
+/**
+ * Ceiling on one attempt to ask a discovered CDP port who it is.
+ *
+ * The launch loop below polls: it reads `DevToolsActivePort`, tries `/json/version` on the port
+ * inside it, and waits 250 ms between attempts under a 30 s deadline. An unbounded fetch can
+ * park inside one iteration for the whole budget, so a bound is needed — but it has to be
+ * small enough that the loop still behaves like a loop.
+ *
+ * The usual case is NOT a slow answer, it is NO answer: a browser that has written the file but
+ * is not listening yet refuses the connection instantly, and that immediacy is what lets the
+ * loop spin. Any timeout added here is paid on every iteration in which the port is not ready,
+ * so an earlier attempt at this used 2000 ms — eight times the poll interval — and cut the
+ * attempts available in the budget from roughly 120 to 15. This value is the same size as the
+ * interval, so a worst-case iteration costs 500 ms and the budget still affords ~60 attempts.
+ */
+const PORT_PROBE_MS = 250
+
+/**
+ * Starts a browser process and returns a handle to it.
+ *
+ * Injectable so tests can supply something that speaks CDP — the seam a recovery test needs
+ * and could not have while the launch was hardcoded to a stub that rejects Chromium's args.
+ * @param path - the executable to run.
+ * @param args - its arguments.
+ * @returns the child process.
+ */
+export type BrowserLauncher = (path: string, args: readonly string[]) => ReturnType<typeof spawn>
+
+/** The real launcher: spawn a detached-free child with pipes closed. */
+const defaultLauncher: BrowserLauncher = (path, args) =>
+  spawn(path, [...args], { stdio: ['ignore', 'ignore', 'ignore'], windowsHide: false })
 import { spawn, type ChildProcess } from 'node:child_process'
 import { randomUUID } from 'node:crypto'
 import type { ElectronBrowserViewHost, ElectronViewHandle } from './provider.js'
 
 /** Which browser the user asked for. */
-export type BrowserChannel = 'bundled' | 'chrome' | 'edge' | 'auto'
+export type BrowserChannel = 'bundled' | 'chrome' | 'edge' | 'auto' | 'sidebar'
 
 /** A resolved browser installation. */
 export interface DetectedBrowser {
@@ -83,6 +125,11 @@ const INSTALL_LOCATIONS: Record<DetectedBrowser['kind'], Partial<Record<NodeJS.P
     win32: [
       String.raw`C:\Program Files\Google\Chrome\Application\chrome.exe`,
       String.raw`C:\Program Files (x86)\Google\Chrome\Application\chrome.exe`,
+      // Where a per-user install lands, which is what Chrome's own installer chooses when it
+      // cannot (or should not) write to Program Files. Missing this meant the plugin reported
+      // "no browser found" on machines that plainly had one.
+      String.raw`%LOCALAPPDATA%\Google\Chrome\Application\chrome.exe`,
+      String.raw`%LOCALAPPDATA%\Chromium\Application\chrome.exe`,
     ],
     darwin: [
       '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
@@ -100,6 +147,7 @@ const INSTALL_LOCATIONS: Record<DetectedBrowser['kind'], Partial<Record<NodeJS.P
     win32: [
       String.raw`C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe`,
       String.raw`C:\Program Files\Microsoft\Edge\Application\msedge.exe`,
+      String.raw`%LOCALAPPDATA%\Microsoft\Edge\Application\msedge.exe`,
     ],
     darwin: ['/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge'],
     linux: [
@@ -112,12 +160,29 @@ const INSTALL_LOCATIONS: Record<DetectedBrowser['kind'], Partial<Record<NodeJS.P
     win32: [
       String.raw`C:\Program Files\BraveSoftware\Brave-Browser\Application\brave.exe`,
       String.raw`C:\Program Files (x86)\BraveSoftware\Brave-Browser\Application\brave.exe`,
+      String.raw`%LOCALAPPDATA%\BraveSoftware\Brave-Browser\Application\brave.exe`,
     ],
     darwin: ['/Applications/Brave Browser.app/Contents/MacOS/Brave Browser'],
     linux: ['/usr/bin/brave-browser', '/usr/bin/brave', '/snap/bin/brave'],
   },
 }
 
+/**
+ * Resolve the environment references in one install location.
+ *
+ * The list is static strings, but a per-user install lands under %LOCALAPPDATA%, so the entry
+ * has to be resolved against the environment detection was HANDED rather than process.env — a
+ * caller that supplies a platform and an environment (which is what makes detection testable)
+ * must not end up reading the developer's real machine.
+ * @param location - one entry from the install-location table.
+ * @param env - the environment to resolve against.
+ * @returns the path with %NAME% references replaced, or the entry unchanged when unknown.
+ */
+function expandLocation(location: string, env: NodeJS.ProcessEnv): string {
+  return location.replace(/%([^%]+)%/g, (whole, name: string) =>
+    env[name] ?? env[name.toUpperCase()] ?? env[name.toLowerCase()] ?? whole)
+}
+
 /**
  * Find an executable by name on PATH.
  *
@@ -172,7 +237,8 @@ export function detectBrowser(
     if (fromEnv !== undefined && fromEnv !== '' && existsSync(fromEnv)) return { kind, path: fromEnv }
     const onPath = findOnPath(PATH_NAMES[kind]?.[platform] ?? [], env, platform)
     if (onPath !== undefined) return { kind, path: onPath }
-    for (const candidate of INSTALL_LOCATIONS[kind]?.[platform] ?? []) {
+    for (const raw of INSTALL_LOCATIONS[kind]?.[platform] ?? []) {
+      const candidate = expandLocation(raw, env)
       if (existsSync(candidate)) return { kind, path: candidate }
     }
   }
@@ -189,9 +255,15 @@ export function detectBrowser(
  * @param platform - the platform whose names and locations apply.
  * @returns the launcher names (as PATH lookups) and the fixed locations checked.
  */
-export function searchSummary(kind: DetectedBrowser['kind'], platform: NodeJS.Platform = process.platform): string[] {
+export function searchSummary(
+  kind: DetectedBrowser['kind'],
+  platform: NodeJS.Platform = process.platform,
+  env: NodeJS.ProcessEnv = process.env,
+): string[] {
   const onPath = (PATH_NAMES[kind]?.[platform] ?? []).map(name => `${name} (on PATH)`)
-  const located = INSTALL_LOCATIONS[kind]?.[platform] ?? []
+  // Expanded, so the report names the location that was actually tested rather than a template
+  // the user cannot paste into a file manager.
+  const located = (INSTALL_LOCATIONS[kind]?.[platform] ?? []).map(entry => expandLocation(entry, env))
   return [...onPath, ...located]
 }
 
@@ -310,7 +382,19 @@ class CdpClient {
 
 /** A system browser driven over CDP, presented as a browser view host. */
 export class SystemBrowserViewHost implements ElectronBrowserViewHost {
-  private readonly views = new Map<string, string>()
+  /**
+   * viewId -> the session that view rides, and the client that issued it.
+   *
+   * The client is part of the value on purpose. A session id means nothing to a browser other
+   * than the one that handed it out, and this host replaces browsers routinely: the process
+   * dies, or its debugging socket closes while the process lives on. Keeping only the id meant
+   * the host could start a NEW browser successfully and then send every command to it carrying
+   * a session the old one had issued — `Session with given id not found`, on every call, with a
+   * browser that answers /json/version perfectly well and nothing the user can do short of
+   * restarting DSH. Comparing identity catches it with no round trip; validating each cached
+   * session against the browser would put one on every page command.
+   */
+  private readonly views = new Map<string, { session: string; client: CdpClient }>()
   private disposed = false
   /**
    * The browser is started on FIRST USE, never on construction.
@@ -321,21 +405,47 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
    * spawned when a view is actually needed.
    */
   private client: CdpClient | undefined
+  /**
+   * Set when a command went unanswered rather than being refused.
+   *
+   * A timeout says nothing about the connection: the page may simply be slow. It marks the
+   * client for a cheap check before the next command trusts it, which keeps a slow page
+   * from being mistaken for a dead browser while still catching one that has truly stopped
+   * answering.
+   */
+  private clientSuspect = false
   private child: ChildProcess | undefined
   private starting: Promise<CdpClient> | undefined
 
+  /**
+   * Browsers that ignored a kill.
+   *
+   * They are no longer this host's child — a replacement has taken that slot — but they
+   * are still running, still holding the profile, and still something release must try to
+   * stop. Forgetting them is what allowed a launch this host could not undo.
+   */
+  private readonly stubborn: { kill: () => void; exitCode: number | null; signalCode: NodeJS.Signals | null }[] = []
+
   /**
    * @param browser - the detected installation to launch on first use.
    * @param profileDir - a plugin-owned directory; the user's own profile is never touched.
    * @param extraArgs - additional Chromium switches.
    * @param ephemeralDir - a directory to delete on release, when the user has turned
    *   persistence off so no login state outlives the session.
+   * @param launcher - how to start the browser, for tests.
+   *
+   *   Recovery after the browser dies was untestable without this: the suite spawns a stub
+   *   with Chromium's arguments, and a stub that is not a browser rejects them and exits, so
+   *   no CDP endpoint ever appears and no session is ever created. Verified by mutation —
+   *   removing every sessions.clear() left the recovery tests green. A launcher lets a test
+   *   provide something that actually speaks CDP, so the state those tests describe exists.
    */
   constructor(
     private readonly browser: DetectedBrowser,
     private readonly profileDir: string,
     private readonly extraArgs: readonly string[] = [],
     private readonly ephemeralDir?: string,
+    private readonly launcher: BrowserLauncher = defaultLauncher,
   ) {}
 
   /** Which product this host would drive (for diagnostics). */
@@ -352,6 +462,49 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
    * The CDP client, starting the browser on first use.
    * @returns the connected client.
    */
+  /**
+   * Whether a client that reports itself open is actually answering.
+   *
+   * An open socket proves nothing: a browser can hold the connection and never reply, and
+   * that state must not be cached, or every later command waits out its own timeout. Asking
+   * the browser something cheap is a fact; reading the failure text is a guess, and the
+   * guess was wrong in both directions (it killed healthy browsers on a slow page, and it
+   * mistook the browser's own free text for a verdict).
+   *
+   * This is only reached when the socket is open, so the common path costs nothing.
+   * @param client - the client to question.
+   * @returns true when it answered.
+   */
+  private async probeClient(client: CdpClient): Promise<boolean> {
+    try {
+      // The command budget (30s) on purpose, not a shorter "probe" value, because of what the
+      // answer is used for: a false verdict discards the client and replaces the browser,
+      // which KILLS the window the human is looking at. A page that is merely slow must not
+      // lose its browser, so this errs toward waiting. The price is that a truly wedged
+      // browser takes the full budget to be declared dead — the tool call that triggered the
+      // probe answers first, and its timeout is the error the caller sees. Trading a later
+      // error for a window that is not destroyed is the right way round.
+      await client.send('Browser.getVersion', {})
+      return true
+    } catch {
+      // No answer within the budget, or the socket failed while asking: unusable either way.
+      return false
+    }
+  }
+
+  /**
+   * Forget which browser issued what, after that browser is gone.
+   *
+   * The two maps must move together: `views` maps a view id to a session id and `sessions`
+   * maps a session id to a target id, so clearing one alone leaves a mapping the next command
+   * will act on. Every path that abandons a browser calls this rather than spelling the pair
+   * out — four separate copies is how the third one came to be missing.
+   */
+  private forgetBrowserState(): void {
+    this.views.clear()
+    this.sessions.clear()
+  }
+
   private async ensureClient(): Promise<CdpClient> {
     // A disposed host must never start a browser: doing so would spawn a process
     // nobody owns and nobody will kill.
@@ -360,9 +513,25 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
     // (the browser closing its debugging endpoint, a dropped connection). Checking the
     // socket's own state costs nothing and turns a 30s hang into a restart.
     if (this.client !== undefined) {
-      if (this.client.isAlive()) return this.client
-      this.client.close()
+      // A closed socket means the browser is gone; an OPEN socket proves nothing, because
+      // a browser can hold the connection and never answer. Only probe when the socket is
+      // closed or a previous command went unanswered without being refused — probing every
+      // call would add a round trip to the common path for nothing.
+      const current = this.client
+      if (current.isAlive() && !this.clientSuspect) return current
+      if (current.isAlive() && await this.probeClient(current)) {
+        this.clientSuspect = false
+        return current
+      }
+      current.close()
       this.client = undefined
+      this.clientSuspect = false
+      // Everything this client issued dies with it. `start()` clears these too, but only
+      // inside its "kill the old child" branch — and the shape of this failure usually has no
+      // child left to kill: the process already exited, its exit listener already set
+      // `this.child` to undefined, so start() skips that branch and publishes a new browser
+      // while the views still point at the dead one. That is the state that never recovers.
+      this.forgetBrowserState()
     }
     // Concurrent first calls share one startup rather than racing two browsers.
     this.starting ??= this.start().finally(() => { this.starting = undefined })
@@ -391,7 +560,60 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
       ...this.extraArgs,
       'about:blank',
     ]
-    const child = spawn(this.browser.path, args, { stdio: ['ignore', 'ignore', 'ignore'], windowsHide: false })
+    // A browser from a previous attempt may still be running with this same
+    // --user-data-dir. On Windows the new one would merely hand off to it and exit, and that
+    // exit would then be treated as the launch failing.
+    if (this.child !== undefined) {
+      const dying = this.child
+      try { dying.kill() } catch { /* already gone */ }
+      this.child = undefined
+
+      // Whatever the old browser issued is worthless now, and its exit listener cannot clean
+      // up after itself: this.child is reassigned below, so the old child's exit event returns
+      // early and the session ids it handed out would be reused against a browser that never
+      // heard of them — the "Session with given id not found" loop, which never clears.
+      this.client?.close()
+      this.client = undefined
+      this.forgetBrowserState()
+
+      // Wait for it to actually die. kill() only sends the signal: on Windows it is
+      // TerminateProcess, which is asynchronous, and the browser may still hold this profile's
+      // singleton lock for a while. Spawning immediately meant the replacement saw an existing
+      // instance, handed its command line over and exited — and that exit was then reported as
+      // "check that the path is a runnable browser", blaming the user's install for a race this
+      // code created. Bounded, because a process that refuses to die must not hang the call.
+      await new Promise<void>(resolve => {
+        if (dying.exitCode !== null || dying.signalCode !== null) { resolve(); return }
+        const done = (): void => { clearTimeout(timer); resolve() }
+        const timer = setTimeout(done, EXIT_GRACE_MS)
+        dying.once('exit', done)
+        // It did not exit in time. Dropping the reference here was how this host could
+        // launch a browser it could never kill again: dispose() only knows about this.child,
+        // and this process still holds the profile's singleton lock. Remember it so release
+        // still reaches it.
+        if (dying.exitCode === null && dying.signalCode === null) this.stubborn.push(dying)
+        dying.once('exit', () => {
+          const at2 = this.stubborn.indexOf(dying)
+          if (at2 !== -1) this.stubborn.splice(at2, 1)
+        })
+      })
+    }
+    // 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 */ }
+    const spawnedAt = Date.now()
+    let child: ReturnType<typeof spawn>
+    try {
+      child = this.launcher(this.browser.path, args)
+    } catch (error) {
+      // spawn throws synchronously for some targets (a .cmd on Windows, a path that cannot
+      // be executed). Without this the exception escaped start() and skipped every
+      // diagnostic below it.
+      throw new Error(`dsh-builtin-browser: could not launch ${this.browser.path}: ${error instanceof Error ? error.message : String(error)}`)
+    }
     this.child = child
     /**
      * A launch that fails (ENOENT, no permission, a broken binary) is reported by an
@@ -410,8 +632,30 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
       this.client?.close()
       this.client = undefined
       this.child = undefined
+      // The pages this client opened belong to the process that just died; keeping their
+      // session ids means every later command is sent to a browser that never issued them.
+      // Clearing these is what makes the restart usable rather than merely alive.
+      this.forgetBrowserState()
     })
     const portFile = join(this.profileDir, 'DevToolsActivePort')
+    /**
+     * The port this launch wrote, or undefined while it has not written one yet.
+     *
+     * A file left by the PREVIOUS browser is not evidence about this one. Its contents
+     * name a port that may now belong to something else entirely — another Chromium, a
+     * node --inspect — and connecting there publishes a client this host does not own and
+     * dispose() can never kill. Only a file written after the spawn counts.
+     */
+    const freshPort = (): number | undefined => {
+      try {
+        if (!existsSync(portFile)) return undefined
+        if (statSync(portFile).mtimeMs < spawnedAt) return undefined
+        const value = Number(readFileSync(portFile, 'utf8').split('\n')[0]?.trim() ?? '')
+        return Number.isInteger(value) && value > 0 ? value : undefined
+      } catch {
+        return undefined
+      }
+    }
     const deadline = Date.now() + 30_000
     /**
      * Why the loop stopped, so the failure can say what actually happened. Reporting
@@ -428,14 +672,29 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
       if (this.disposed) { child.kill(); if (this.child === child) this.child = undefined; stopped = 'released'; break }
       if (launchError !== undefined) { if (this.child === child) this.child = undefined; stopped = 'launch-failed'; break }
       if (Date.now() > deadline) { child.kill(); if (this.child === child) this.child = undefined; stopped = 'timeout'; break }
-      if (child.exitCode !== null) { if (this.child === child) this.child = undefined; stopped = 'exited'; break }
-      if (existsSync(portFile)) {
+      // signalCode too: a browser killed by a signal never sets exitCode, so checking exitCode
+      // alone made a killed browser look alive and the launch run out its full 30s deadline
+      // before reporting "did not expose CDP" — a timeout for something that died at once.
+      // The sibling check on the release path already looked at both.
+      if (child.exitCode !== null || child.signalCode !== null) { if (this.child === child) this.child = undefined; stopped = 'exited'; break }
+      // Only a port THIS launch wrote: reading whatever file happened to be there is how a
+          // restart could adopt the previous browser, or any process now holding that port.
+          const port = freshPort()
+          if (port !== undefined) {
         try {
-          const port = readFileSync(portFile, 'utf8').split('\n')[0]?.trim() ?? ''
-          if (port !== '') {
-            const version = await (await fetch(`http://127.0.0.1:${port}/json/version`)).json() as { webSocketDebuggerUrl?: string }
+            const version = await (await fetch(`http://127.0.0.1:${port}/json/version`, {
+              // Bounded: an unanswered loopback request would otherwise park inside this
+              // iteration for the rest of the budget, and the deadline above is only re-checked
+              // between iterations. Deliberately no larger than the 250 ms sleep — see
+              // PORT_PROBE_MS.
+              signal: AbortSignal.timeout(PORT_PROBE_MS),
+            })).json() as { webSocketDebuggerUrl?: string }
             if (typeof version.webSocketDebuggerUrl === 'string') {
               const client = new CdpClient(version.webSocketDebuggerUrl)
+              // `whenReady` has its own 30 s ceiling, and it is reached only after the port
+              // answered above — so the browser is listening and this is a handshake, not a
+              // discovery. A handshake that outlives the launch is reported as the timeout it
+              // is, by the same deadline that governs everything else here.
               await client.whenReady()
               // Still wanted? A dispose() during the handshake has already killed the
               // process, so publishing the client would leave a dangling connection.
@@ -443,7 +702,6 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
               this.client = client
               return client
             }
-          }
         } catch {
           // The file can exist a moment before the port answers; poll again.
         }
@@ -458,7 +716,24 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
       throw new Error(`dsh-builtin-browser: could not launch ${target}: ${launchError?.message ?? 'unknown error'}`)
     }
     if (stopped === 'exited') {
-      throw new Error(`dsh-builtin-browser: ${target} exited immediately after launch (exit code ${child.exitCode}); check that the path is a runnable browser`)
+      // Only exit code 0 is the hand-off story. A non-zero code or a signal means the browser
+      // died on its own — a crash, a missing library, a sandbox refusal — and asserting the
+      // profile story for those sent people looking for a leftover process that was not there,
+      // which is the same mistake this message was written to correct, pointing the other way.
+      const code = child.exitCode
+      const signal = child.signalCode
+      const clean = code === 0 && signal === null
+      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 '
+            + 'directory and quit — look for a leftover browser process from an earlier run, then retry.'
+          : `dsh-builtin-browser: ${target} exited immediately after launch `
+            + `(${signal !== null ? `killed by ${signal}` : `exit code ${String(code)}`}), so it did not `
+            + 'hand the request anywhere — the browser failed to start rather than deferring to another '
+            + 'instance. Check that it can run at all: run it by hand, and look for a crash or a missing '
+            + 'dependency rather than a leftover process.',
+      )
     }
     if (stopped === 'released') {
       throw new Error(`dsh-builtin-browser: ${target} was released while it was starting`)
@@ -489,24 +764,65 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
       // socket can stay OPEN while nothing comes back, which is the form the reporter saw with
       // a live, healthy-looking Edge. Dropping the client here means the next call starts a new
       // browser rather than hanging again, and the error names the cause instead of a timeout.
+      const client = await this.ensureClient()
+      const cachedView = this.views.get(viewId)
+      // A session belongs to the browser that issued it. Clearing the cache whenever a client is
+      // dropped covers the ordinary case, but not this one: another call can be inside
+      // ensureSession() holding the OLD client while this one discards it and clears, and that
+      // call's `views.set` then lands afterwards — re-adding an entry naming a browser that is
+      // gone. The identity check is what refuses it, and it costs a comparison rather than the
+      // round trip that validating every cached session against the browser would cost.
+      //
+      // (Not covered by the tests: the race needs two interleaved commands, and the suite's fake
+      // browser is synchronous enough that they never interleave. Verified by mutation instead —
+      // removing this check alone leaves every case green, which is why the comment says what it
+      // protects rather than claiming a case proves it.)
+      const session = cachedView !== undefined && cachedView.client === client
+        ? cachedView.session
+        : await this.ensureSession(viewId)
       try {
-        const client = await this.ensureClient()
-        const session = this.views.get(viewId) ?? await this.ensureSession(viewId)
         const result = await client.send(method, params, session)
         return (result ?? {}) as Record<string, unknown>
-      } catch (error) {
-        this.client?.close()
-        this.client = undefined
-        throw error
+        } catch (error) {
+          // A CDP protocol error means the browser ANSWERED and refused this one command, so the
+          // connection is healthy and must be kept. Deciding by the error TEXT misfires both
+          // ways: the inner timeout rejects with "… timed out", so a slow but healthy page read
+          // as a dead browser, the client was dropped, and the next call's start() killed the
+          // running child — the human's tabs and half-filled forms gone, which is worse than the
+          // bug that change was fixing. The browser's own free text is interpolated into
+          // protocol errors too, so any message containing those words misfired the same way.
+          // Unanswered versus refused. 'timed out' is the inner client's own budget expiring,
+          // which says the page was slow, not that the browser died — so it only marks the client
+          // for a probe. Being wrong here costs a two-second check; being wrong about the
+          // browser being dead cost the user their open tabs.
+          if (error instanceof Error && /timed out/.test(error.message)) this.clientSuspect = true
+          if (!client.isAlive()) {
+            // Only THIS call's client. Under concurrency the field may already hold a
+            // connection another call just published, and closing that would kill a healthy one.
+            if (this.client === client) {
+              this.client = undefined
+              // This is the third of the three paths that discard a client, and it was the one
+              // that did not retire what the client had issued. A view holding a session id
+              // from the dead browser kept handing it to the replacement, which had never heard
+              // of it: every page command then failed with "Session with given id not found"
+              // and no later call could clear it, because the cached session was returned
+              // unconditionally. Gated on the same identity check as the field itself, so a
+              // concurrent call that just published a healthy client does not lose its maps.
+              this.forgetBrowserState()
+            }
+            client.close()
+          }
+          throw error
       }
       },
     }
   }
 
   destroyView(handle: ElectronViewHandle): void {
-    const session = this.views.get(handle.id)
+    const cachedView = this.views.get(handle.id)
     this.views.delete(handle.id)
-    if (session === undefined) return
+    if (cachedView === undefined) return
+    const session = cachedView.session
     // A session id is not a target id: closing the page needs the target the session
     // was attached to, which is why they are tracked separately.
     const targetId = this.sessions.get(session)
@@ -521,11 +837,32 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
   /** Nothing to show: the browser owns its own windows. */
   showView(): void {}
 
-  /** Same as {@link showView}. */
-  async presentView(): Promise<void> {}
+  /**
+   * Bring the target's page to the front, then report success.
+   *
+   * The comment on `focus` below used to say this was impossible — that raising the page needs
+   * `Page.bringToFront` on a target session, which is a view-level concern the host cannot
+   * reach. The handle this method is handed IS that view, and it can send commands, so the
+   * capability was here all along; it just was not used. Without it `presentView` was an empty
+   * async method, so the provider's whole presentation barrier — the one that stops
+   * `Input.*` from being silently dropped for a view with no display surface, and reports
+   * `BROWSER_VIEW_NOT_PRESENTED` when it cannot present — never ran on this carrier.
+   *
+   * A failure is swallowed rather than propagated: a real Chrome window that refuses to come
+   * forward is not a reason to refuse the click that follows. The barrier exists to order the
+   * two, and the order is honoured either way.
+   * @param handle - the view to present.
+   */
+  async presentView(handle: ElectronViewHandle): Promise<void> {
+    try {
+      await handle.sendCommand('Page.bringToFront')
+    } catch {
+      // Backgrounded, minimised, or a target that went away between the snapshot and the
+      // click. The command that called this will report its own failure if the page is gone.
+    }
+  }
+
 
-  /** The browser owns window grouping. */
-  groupView(): void {}
 
   /**
    * Best effort at bringing the browser's window forward.
@@ -543,11 +880,7 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
     try { this.child?.kill('SIGCONT') } catch { /* Windows has no SIGCONT; nothing to do */ }
   }
 
-  /** The browser reports its own window lifecycle. */
-  onUserAction(): void {}
 
-  /** The browser reports its own window lifecycle. */
-  onViewClosed(): void {}
 
   /**
    * Close the browser we launched, if we ever launched one.
@@ -559,25 +892,58 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
   dispose(): void {
     if (this.disposed) return
     this.disposed = true
-    this.views.clear()
-    this.sessions.clear()
+    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 */ }
+    }
     const ephemeral = this.ephemeralDir
     if (ephemeral !== undefined && this.child !== undefined) {
       // The browser flushes its profile while shutting down, so deleting later avoids
       // racing it. Leftovers are only a stray temp directory, never a live credential.
-      setTimeout(() => { try { rmSync(ephemeral, { recursive: true, force: true }) } catch { /* best effort */ } }, 3_000).unref?.()
+      //
+      // The timer is unref'd, so it never holds the process open — which also means that a
+      // process which exits inside this 3s window (a CLI probe, a DSH restart) leaves the
+      // directory behind for good, silently contradicting the user's "keep no profile"
+      // choice. The exit hook below is the same delete, run synchronously as a last resort;
+      // the callback is idempotent, so whichever runs first wins and the other is a no-op.
+      const removeEphemeral = (): void => {
+        try { rmSync(ephemeral, { recursive: true, force: true }) } catch { /* best effort */ }
+      }
+      setTimeout(removeEphemeral, 3_000).unref?.()
+      process.once('exit', removeEphemeral)
     } else if (ephemeral !== undefined) {
       // Never started, so nothing can be holding it open.
       try { rmSync(ephemeral, { recursive: true, force: true }) } catch { /* best effort */ }
     }
   }
 
-  /** The flattened session for a view, creating its page on first use. */
+  /**
+   * The flattened session for a view, creating its page on first use.
+   *
+   * No cache check here: the only caller has already established that the cached session does
+   * not belong to the client it is about to use. Re-checking would mean either a round trip or
+   * a second copy of that rule.
+   */
   private async ensureSession(viewId: string): Promise<string> {
-    const existing = this.views.get(viewId)
-    if (existing !== undefined) return existing
+    // One target per view, even when two commands arrive together. The two CDP round trips
+    // below are awaits, so without this a second caller entering during the first's flight saw
+    // no session in `views` and created its own target — leaving an orphan page that nothing
+    // closes, because only the last id survives in the map.
+    const inFlight = this.sessionBuilding.get(viewId)
+    if (inFlight !== undefined) return await inFlight
+    const building = this.buildSession(viewId).finally(() => {
+      this.sessionBuilding.delete(viewId)
+    })
+    this.sessionBuilding.set(viewId, building)
+    return await building
+  }
+
+  /** 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
@@ -587,10 +953,13 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
     if (typeof sessionId !== 'string') throw new Error('dsh-builtin-browser: the browser did not attach to the new page')
     // The session id is what page commands ride; the target id is what closes it.
     this.sessions.set(sessionId, targetId)
-    this.views.set(viewId, sessionId)
+    this.views.set(viewId, { session: sessionId, client })
     return sessionId
   }
 
+  /** Views whose session is being created right now, so a second caller waits for the first. */
+  private readonly sessionBuilding = new Map<string, Promise<string>>()
+
   /** sessionId -> targetId, so a destroyed view can close the right page. */
   private readonly sessions = new Map<string, string>()
 }