dsh-builtin-browser 0.3.0 → 0.4.0

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

@@ -0,0 +1,113 @@
+/**
+ * A host that exists only to explain why the browser you asked for is not here.
+ *
+ * WHY THIS EXISTS
+ * When the browser setting names a browser explicitly (Chrome or Edge rather than
+ * "bundled" or "automatic"), the plugin used to log a warning and quietly fall back
+ * to its own Electron window. That is worse than failing: you asked for Chrome, you
+ * got an Electron window, and the error that eventually surfaced talked about
+ * Electron — pointing at something you never chose and never wanted to install. The
+ * actual problem ("no Chrome on this machine") never reached you.
+ *
+ * So the two choices are treated as the different requests they are:
+ *   - `auto` means "any browser will do", and falling back to the bundled one is the
+ *     behaviour it asks for;
+ *   - `chrome` / `edge` are explicit, and an explicit request that cannot be met is
+ *     reported as such, with the ways out of it.
+ *
+ * `available()` reports true on purpose. Reporting false would make the provider pick
+ * a different carrier and hide the problem again, which is exactly the bug.
+ */
+import type { ElectronBrowserViewHost, ElectronViewHandle } from './provider.js'
+import type { BrowserChannel } from './system-browser.js'
+
+/**
+ * How each product is named in the message, and what to install.
+ *
+ * Only chrome and edge can appear: the constructor's type excludes `bundled` and `auto`,
+ * and `BrowserChannel` has no `brave`. A brave entry here would be unreachable code.
+ */
+const PRODUCT: Record<string, { label: string; install: string; variable: string }> = {
+  chrome: {
+    label: 'Google Chrome',
+    install: 'install Google Chrome',
+    variable: 'DSH_BROWSER_CHROME_PATH',
+  },
+  edge: {
+    label: 'Microsoft Edge',
+    install: 'install Microsoft Edge',
+    variable: 'DSH_BROWSER_EDGE_PATH',
+  },
+}
+
+/** How the setting is named to the user. */
+const SETTING_LABEL: Record<string, string> = {
+  chrome: '本机 Chrome / installed Chrome',
+  edge: '本机 Edge / installed Edge',
+  auto: '自动 / automatic',
+  bundled: '内置 / bundled',
+}
+
+/**
+ * A carrier that cannot carry anything: every command explains the real problem.
+ *
+ * The message is written to be acted on, not just read: it says which browser was
+ * requested, where the plugin looked, and the three concrete ways to resolve it.
+ */
+export class MissingSystemBrowserHost implements ElectronBrowserViewHost {
+  /**
+   * @param kind - the browser the user asked for.
+   * @param searched - the names and locations that were checked, for the report.
+   */
+  constructor(private readonly kind: Exclude<BrowserChannel, 'bundled' | 'auto'>, private readonly searched: readonly string[]) {}
+
+  /** @returns always true: see the module comment — reporting false would hide this. */
+  available(): boolean {
+    return true
+  }
+
+  /**
+   * The message every command fails with.
+   * @returns a multi-line explanation with the fixes.
+   */
+  private explain(): string {
+    const product = PRODUCT[this.kind] ?? { label: this.kind, install: `install ${this.kind}`, variable: 'DSH_BROWSER_<KIND>_PATH' }
+    const searched = this.searched.length > 0 ? this.searched.join(', ') : 'PATH and the usual install locations'
+    return [
+      `dsh-builtin-browser: the browser you selected is not installed — no ${product.label} was found.`,
+      ``,
+      `  Setting:  browser carrier = "${SETTING_LABEL[this.kind] ?? this.kind}"`,
+      `  Looked for: ${searched}`,
+      ``,
+      `Nothing else is wrong: the plugin falls back to its own bundled browser only when the`,
+      `setting is "bundled" or "automatic". Because this one names a browser explicitly, it`,
+      `reports the missing browser instead of silently using a different one.`,
+      ``,
+      `To fix it, any ONE of these is enough:`,
+      `  1. ${product.install}, then restart DSH;`,
+      `  2. point ${product.variable} at its executable;`,
+      `  3. set the browser carrier back to "内置 / bundled" (or "自动 / automatic" to let it`,
+      `     fall back on its own next time).`,
+    ].join('\n')
+  }
+
+  /**
+   * Create a handle whose every command fails with the explanation.
+   * @returns a handle that never reaches a page.
+   */
+  createView(): ElectronViewHandle {
+    const message = this.explain()
+    return {
+      id: `missing-${this.kind}`,
+      sendCommand: async () => { throw new Error(message) },
+    }
+  }
+
+  /**
+   * Accept a handle for destruction. Nothing was created, so nothing is released.
+   * @param handle - the handle returned by {@link createView}.
+   */
+  destroyView(handle: ElectronViewHandle): void {
+    void handle
+  }
+}

package/src/browser-electron/provider.ts

@@ -242,6 +242,15 @@ export interface ElectronViewHandle {
    * @returns the CDP `result` object.
    */
   sendCommand(method: string, params?: Record<string, unknown>): Promise<Record<string, unknown>>
+  /**
+   * Whether this view's CDP can encode JPEG and honour a quality setting.
+   *
+   * Electron 43's CDP hangs on `Page.captureScreenshot` with `format: 'jpeg'`, so a view
+   * backed by Electron must leave this unset and the provider keeps to PNG. A view backed
+   * by an installed Chrome or Edge is the real browser, where JPEG works, and sets it so
+   * the requested format is not silently downgraded.
+   */
+  readonly supportsCdpJpeg?: boolean
   /**
    * Give the backing view web focus so keyboard input reaches its page.
    * Optional: an adapter that cannot focus a view omits it, and the provider
@@ -344,6 +353,114 @@ export interface CdpEvaluateParams {
 /** CDP method for a full-page screenshot capture. */
 export const CDP_PAGE_CAPTURE_SCREENSHOT = 'Page.captureScreenshot'
 
+/** One cookie as CDP reports it (`Storage.getCookies`). */
+interface CdpCookie {
+  readonly name?: unknown
+  readonly value?: unknown
+  readonly domain?: unknown
+  readonly path?: unknown
+  readonly expires?: unknown
+  readonly httpOnly?: unknown
+  readonly secure?: unknown
+  readonly sameSite?: unknown
+}
+
+/**
+ * The document size out of a `Page.getLayoutMetrics` response.
+ *
+ * CDP returns `cssContentSize` (the whole document) and `cssLayoutViewport` (what is
+ * visible); the newer spellings `contentSize` / `layoutViewport` appear on some
+ * versions, so both are accepted. Returns undefined when neither is usable, leaving the
+ * caller to capture unscaled rather than guess.
+ * @param metrics - the raw CDP response.
+ * @returns the document and viewport size in CSS pixels.
+ */
+export function layoutSize(metrics: Record<string, unknown>): { width: number; height: number; viewportHeight: number } | undefined {
+  const pick = (candidates: readonly unknown[]): { width: number; height: number } | undefined => {
+    for (const candidate of candidates) {
+      if (typeof candidate !== 'object' || candidate === null) continue
+      const box = candidate as { width?: unknown; height?: unknown }
+      if (typeof box.width === 'number' && typeof box.height === 'number' && box.width > 0 && box.height > 0) {
+        return { width: box.width, height: box.height }
+      }
+    }
+    return undefined
+  }
+  const content = pick([metrics.cssContentSize, metrics.contentSize])
+  const viewport = pick([metrics.cssLayoutViewport, metrics.layoutViewport])
+  if (content === undefined) return undefined
+  return { width: content.width, height: content.height, viewportHeight: viewport?.height ?? content.height }
+}
+
+/**
+ * Map CDP cookies onto the shape `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
+ * dropped rather than exported as broken cookies the caller cannot restore.
+ * @param raw - the `cookies` array from a CDP response, of unknown shape.
+ * @returns the mappable cookies.
+ */
+export function toExportedCookies(raw: unknown): ExportedCookie[] {
+  if (!Array.isArray(raw)) return []
+  const out: ExportedCookie[] = []
+  for (const entry of raw) {
+    if (typeof entry !== 'object' || entry === null) continue
+    const cookie = entry as CdpCookie
+    // An empty domain is as unusable as a missing one: it cannot form a cookie URL, so
+    // exporting it would hand the caller something that fails to restore.
+    if (typeof cookie.name !== 'string' || cookie.name === '') continue
+    if (typeof cookie.value !== 'string') continue
+    if (typeof cookie.domain !== 'string' || cookie.domain === '') continue
+    const path = typeof cookie.path === 'string' && cookie.path !== '' ? cookie.path : '/'
+    // A leading dot means "this domain and its subdomains"; a cookie URL must not keep it.
+    const host = cookie.domain.replace(/^\./, '')
+    out.push({
+      url: `${cookie.secure === true ? 'https' : 'http'}://${host}${path}`,
+      name: cookie.name,
+      value: cookie.value,
+      domain: cookie.domain,
+      path,
+      ...cookie.secure === true ? { secure: true } : {},
+      ...cookie.httpOnly === true ? { httpOnly: true } : {},
+      ...typeof cookie.expires === 'number' && cookie.expires > 0 ? { expirationDate: cookie.expires } : {},
+    })
+  }
+  return out
+}
+
+/**
+ * Map an exported cookie onto the fields `Storage.setCookies` expects.
+ *
+ * An exported cookie may carry only a URL, so the domain and path are recovered from it
+ * when they are absent; without either, CDP cannot place the cookie and it is skipped.
+ * @param cookie - the cookie to convert.
+ * @returns the CDP cookie, or undefined when it lacks a usable domain.
+ */
+export function toCdpCookie(cookie: ExportedCookie): Record<string, unknown> | undefined {
+  let domain = cookie.domain
+  let path = cookie.path
+  if (domain === undefined || domain === '') {
+    try {
+      const parsed = new URL(cookie.url)
+      domain = parsed.hostname
+      if (path === undefined || path === '') path = parsed.pathname === '' ? '/' : parsed.pathname
+    } catch {
+      return undefined
+    }
+  }
+  if (typeof domain !== 'string' || domain === '') return undefined
+  return {
+    name: cookie.name,
+    value: cookie.value,
+    domain,
+    path: path === undefined || path === '' ? '/' : path,
+    ...cookie.secure === true ? { secure: true } : {},
+    ...cookie.httpOnly === true ? { httpOnly: true } : {},
+    ...typeof cookie.expirationDate === 'number' ? { expires: cookie.expirationDate } : {},
+  }
+}
+
 /** Native capture options the self-hosted view handle understands. */
 export interface ScreenshotOptions {
   readonly format?: 'png' | 'jpeg'
@@ -566,10 +683,11 @@ export class ElectronBrowserProvider implements BrowserProvider {
     const wanted = stripTabPrefix(tabId)
     const own = s.tabs.findIndex(tab => stripTabPrefix(tab.id) === wanted)
     if (own >= 0) return { s, index: own }
-    for (const other of this.sessions.values()) {
-      const index = other.tabs.findIndex(tab => stripTabPrefix(tab.id) === wanted)
-      if (index >= 0) return { s: other, index }
-    }
+    // Deliberately NOT searched across other sessions. Accepting a bare uuid and
+    // searching elsewhere are different things: ids are globally unique, so the first is
+    // harmless convenience, but the second lets a stale id close or switch a tab that
+    // belongs to another task — or to the human — while reporting success, which
+    // contradicts the isolation the tools promise.
     const ownIds = s.tabs.map(t => t.id).join(', ') || '(none)'
     throw new BrowserError(
       `browser: tab "${tabId}" is not open in this session (session tabs: ${ownIds})`,
@@ -630,6 +748,11 @@ export class ElectronBrowserProvider implements BrowserProvider {
       // Record as soon as the navigation has committed: history bookkeeping must
       // not wait on the best-effort settle below (which only delays what the
       // NEXT observation sees, not whether this action happened).
+      // The page has already moved by now, so a caller that aborted must be told that rather
+      // than handed a success: settleDocument returns quietly on abort by design, so without
+      // this the whole path completes exception-free — success reported, success recorded, and
+      // the visit written to the persistent history for a navigation nobody awaits any more.
+      signal?.throwIfAborted()
       this.record(s, 'navigate', { url }, true)
       await this.settleDocument(handle, before, signal)
       this.recordVisit(s, handle)
@@ -767,7 +890,11 @@ export class ElectronBrowserProvider implements BrowserProvider {
   private async focusView(handle: ElectronViewHandle): Promise<void> {
     if (handle.focus === undefined) return
     try {
-      await handle.focus()
+      // 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
+      // 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')
     } catch {
       // Best-effort: a view that refuses focus must not fail the caller's key
       // press; the dispatch below reports a real channel failure itself.
@@ -826,6 +953,11 @@ export class ElectronBrowserProvider implements BrowserProvider {
       }, true, { result: typeof value === 'string' ? value.slice(0, 500) : JSON.stringify(value).slice(0, 500) })
       return { ok: true, value }
     } catch (error) {
+      // A caller that aborted is not a failure of the page: report its own reason, or the
+      // cancellation surfaces as "execute failed: AbortError" and — if the caller's reason
+      // happens to be named TimeoutError — as "timed out after 30000ms", quoting a budget
+      // that belongs to the caller rather than to this call.
+      if (signal?.aborted) throw signal.reason
       if (error instanceof Error && error.name === 'TimeoutError') {
         throw new BrowserError(`browser: execute timed out after ${request.timeoutMs ?? 30_000}ms`, 'BROWSER_EXECUTE_TIMEOUT', { cause: error })
       }
@@ -900,10 +1032,9 @@ export class ElectronBrowserProvider implements BrowserProvider {
         return { ready: false, reason: misses.join('; ') }
       }
       // Sleep between polls, abortable by the caller.
-      await new Promise<void>((resolve, reject) => {
-        const timer = setTimeout(resolve, 200)
-        signal?.addEventListener('abort', () => { clearTimeout(timer); reject(signal.reason ?? new Error('aborted')) }, { once: true })
-      })
+      // Sleep between polls; delay() removes its abort listener on both paths, which the
+      // hand-rolled version here did not — a 30s wait leaked about 150 of them.
+      await delay(200, signal)
     }
   }
 
@@ -1641,7 +1772,31 @@ export class ElectronBrowserProvider implements BrowserProvider {
           continue
         }
         if (els.length === 0) { out.push({ ok: false, error: 'field not found', target: describe(spec) }); continue }
-        const el = els[0]
+        let el = els[0]
+        // The caller may name a kind. Honor it: the branches below read the element's own
+        // tag/type, so without this a selector matching two different controls acted on
+        // whichever came first — usually right, which is what hid the mistake.
+        if (spec.kind) {
+          const matchesKind = (node) => {
+            const nodeTag = node.tagName
+            const nodeType = (node.type || '').toLowerCase()
+            if (spec.kind === 'select') return nodeTag === 'SELECT'
+            if (spec.kind === 'textarea') return nodeTag === 'TEXTAREA'
+            if (spec.kind === 'checkbox' || spec.kind === 'radio') return nodeType === spec.kind
+            return nodeTag === 'INPUT' && nodeType !== 'checkbox' && nodeType !== 'radio' && nodeType !== 'file'
+          }
+          const wanted = els.find(matchesKind)
+          if (wanted === undefined) {
+            out.push({ ok: false, error: 'no "' + spec.kind + '" control matched', target: describe(spec) })
+            continue
+          }
+          els.length = 0
+          els.push(wanted)
+          // el was bound before the filter narrowed els, so the branches below would still
+          // read the first match — the very silent wrong-element behaviour this filter exists
+          // to remove.
+          el = els[0]
+        }
         const tag = el.tagName
         const type = (el.type || '').toLowerCase()
         try {
@@ -2057,7 +2212,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
     })()`
     const result = await withTimeout(
       handleSendEvaluate(tab.handle, script),
-      timeoutMs,
+      timeoutMs + TARGET_SCRIPT_GRACE_MS,
       signal,
       `browser: scrape timed out after ${timeoutMs}ms`,
       () => terminatePage(tab.handle),
@@ -2165,29 +2320,65 @@ export class ElectronBrowserProvider implements BrowserProvider {
    * Self-hosted only; the desktop shell's embedded views use the real profile.
    */
   async flushAuth(session: BrowserSessionId): Promise<readonly ExportedCookie[]> {
+    // The settings panel offers "allow the agent to read cookies / export login state".
+    // Until now nothing read that switch, so turning it off changed nothing at all —
+    // the tool exported every cookie regardless.
+    if (this.settingsSource?.().credentials.allowRead === false) {
+      throw new BrowserError('browser: reading cookies is switched off in settings (Browser → credentials)', 'BROWSER_AUTH_DISABLED')
+    }
     const s = this.session(session)
     const { handle } = this.activeTab(s)
-    const host = handle as { flushAuth?(): Promise<ExportedCookie[]> }
-    if (typeof host.flushAuth !== 'function') {
-      throw new BrowserError('browser: auth export is only available on the self-hosted browser', 'BROWSER_AUTH_UNSUPPORTED')
-    }
     const timeoutMs = 30_000
-    const cookies = await withTimeout(host.flushAuth(), timeoutMs, undefined, `browser: auth export timed out after ${timeoutMs}ms`)
-    this.record(s, 'flushAuth', {}, true, { result: `${cookies.length} cookies` })
+    // The self-hosted carrier has a native path (the child reads its own session), which
+    // is worth preferring: it reports exactly what the browser persisted.
+    const native = handle as { flushAuth?(): Promise<readonly ExportedCookie[]> }
+    if (typeof native.flushAuth === 'function') {
+      const cookies = await withTimeout(native.flushAuth(), timeoutMs, undefined, `browser: auth export timed out after ${timeoutMs}ms`)
+      this.record(s, 'flushAuth', {}, true, { result: `${cookies.length} cookies` })
+      return cookies
+    }
+    // Every other carrier drives a real browser over CDP, and cookies are part of CDP —
+    // the sidebar goes through the shell's webContents.debugger, an installed Chrome or
+    // Edge is the browser itself. So this works everywhere rather than only self-hosted.
+    const result = await withTimeout(
+      handle.sendCommand('Storage.getCookies', {}),
+      timeoutMs,
+      undefined,
+      `browser: auth export timed out after ${timeoutMs}ms`,
+    )
+    const cookies = toExportedCookies(result.cookies)
+    this.record(s, 'flushAuth', {}, true, { result: `${cookies.length} cookies (CDP)` })
     return cookies
   }
 
   /** Import cookies into the session (restore login state). Self-hosted only. */
   async restoreAuth(session: BrowserSessionId, cookies: readonly ExportedCookie[]): Promise<number> {
+    // The settings panel offers "allow the agent to read cookies / export login state".
+    // Until now nothing read that switch, so turning it off changed nothing at all —
+    // the tool exported every cookie regardless.
+    if (this.settingsSource?.().credentials.allowRead === false) {
+      throw new BrowserError('browser: reading cookies is switched off in settings (Browser → credentials)', 'BROWSER_AUTH_DISABLED')
+    }
     const s = this.session(session)
     const { handle } = this.activeTab(s)
-    const host = handle as { restoreAuth?(cookies: readonly ExportedCookie[]): Promise<number> }
-    if (typeof host.restoreAuth !== 'function') {
-      throw new BrowserError('browser: auth restore is only available on the self-hosted browser', 'BROWSER_AUTH_UNSUPPORTED')
-    }
     const timeoutMs = 30_000
-    const restored = await withTimeout(host.restoreAuth(cookies), timeoutMs, undefined, `browser: auth restore timed out after ${timeoutMs}ms`)
-    this.record(s, 'restoreAuth', { count: cookies.length }, true, { result: `${restored} cookies` })
+    const native = handle as { restoreAuth?(cookies: readonly ExportedCookie[]): Promise<number> }
+    if (typeof native.restoreAuth === 'function') {
+      const restored = await withTimeout(native.restoreAuth(cookies), timeoutMs, undefined, `browser: auth restore timed out after ${timeoutMs}ms`)
+      this.record(s, 'restoreAuth', { count: cookies.length }, true, { result: `${restored} cookies` })
+      return restored
+    }
+    // CDP again, for the same reason as the export: any carrier that drives a real
+    // browser can set cookies on it. Storage.setCookies needs the cookie fields spelled
+    // the CDP way, including the sameSite spelling and seconds rather than milliseconds.
+    const result = await withTimeout(
+      handle.sendCommand('Storage.setCookies', { cookies: cookies.map(toCdpCookie) }),
+      timeoutMs,
+      undefined,
+      `browser: auth restore timed out after ${timeoutMs}ms`,
+    )
+    const restored = toExportedCookies(result.cookies).length
+    this.record(s, 'restoreAuth', { count: cookies.length }, true, { result: `${restored} cookies (CDP)` })
     return restored
   }
 
@@ -2227,16 +2418,50 @@ export class ElectronBrowserProvider implements BrowserProvider {
       }
       return this.saveScreenshot(shot.base64, request?.savePath, shot.mime ?? 'image/png')
     }
-    // Fallback: a desktop-shell handle (no capture()) or a full-page capture
-    // uses CDP; full-page needs `captureBeyondViewport` which capturePage
-    // lacks. PNG only — the JPEG hang is a CDP-on-Electron-43 defect.
+    // Fallback: a handle without a native capture() (the sidebar, or an installed Chrome
+    // or Edge) uses CDP; full-page needs `captureBeyondViewport`, which capturePage lacks.
+    //
+    // JPEG: Electron 43's CDP hangs on it, which is why the sidebar stays PNG. An
+    // installed Chrome or Edge is the real browser and has no such defect, so it says so
+    // through `supportsCdpJpeg` and gets the format it asked for, and the same for
+    // downscaling, which CDP performs through a full-document clip.
+    const timeoutMs = 30_000
     const params: Record<string, unknown> = {}
     if (request?.fullPage === true) {
       // `captureBeyondViewport` captures the full scrollable content; without
       // a clip this yields the full-page image (CDP default is the viewport).
       params.captureBeyondViewport = true
     }
-    const timeoutMs = 30_000
+    const supportsJpeg = (handle as { supportsCdpJpeg?: boolean }).supportsCdpJpeg === true
+    if (format === 'jpeg' && supportsJpeg) {
+      params.format = 'jpeg'
+      // CDP range is 0-100 and defaults to 80 when omitted.
+      if (request?.quality !== undefined) params.quality = request.quality
+    }
+    // Downscaling on this path: CDP scales through `clip.scale`, and a clip only applies
+    // to the region it names, so it has to cover the whole document. The page's own size
+    // is read first; when that is unavailable the capture proceeds unscaled rather than
+    // failing — an image the caller can shrink itself beats no image at all.
+    if (request?.maxWidth !== undefined || request?.maxHeight !== undefined) {
+      const metrics = await withTimeout(
+        handle.sendCommand('Page.getLayoutMetrics', {}),
+        timeoutMs,
+        signal,
+        `browser: screenshot timed out after ${timeoutMs}ms`,
+      )
+      const size = layoutSize(metrics)
+      if (size !== undefined) {
+        const height = request.fullPage === true ? size.height : size.viewportHeight
+        const byWidth = request.maxWidth !== undefined && size.width > 0 ? request.maxWidth / size.width : 1
+        const byHeight = request.maxHeight !== undefined && height > 0 ? request.maxHeight / height : 1
+        const scale = Math.min(1, byWidth, byHeight)
+        if (scale < 1) {
+          params.clip = { x: 0, y: 0, width: size.width, height, scale }
+          // The clip defines the captured area; captureBeyondViewport must not also apply.
+          delete params.captureBeyondViewport
+        }
+      }
+    }
     const result = await withTimeout(
       handle.sendCommand(CDP_PAGE_CAPTURE_SCREENSHOT, params),
       timeoutMs,
@@ -2583,17 +2808,23 @@ export class ElectronBrowserProvider implements BrowserProvider {
     if (!reported) process.stderr.write(`[dsh-browser] user action failed: ${message}\n`)
   }
 
-  /** Ask the host to show the active tab's view, carrying the session label. */
+  /**
+   * Ask the host to show the active tab's view, carrying the session label.
+   *
+   * The two halves are sequential, not alternatives. `showView` makes the view the
+   * visible one — which is what keeps what the human sees in step with what the agent
+   * drives, and what lets `capturePage` return an image at all (a hidden view captures
+   * empty) — while `collapse` folds the carrier's own chrome away when the user asked
+   * for no auto-expand. Making them exclusive meant that with auto-expand off this
+   * method did nothing at all on carriers without `collapse` (the self-hosted one),
+   * silently desynchronising the two and failing every screenshot.
+   */
   private showActive(s: Session): void {
-    // §3: whether the agent's page takes over the screen is the user's choice, not
-    // a fixed behaviour. With auto-expand off the page still exists and is still
-    // driven — it is simply folded away, so the agent works without claiming the
-    // sidebar. Carriers that own no presentation (self-hosted) ignore the call.
-    if (this.settingsSource !== undefined && !this.settingsSource().ui.autoExpandOnce) {
-      void this.host.collapse?.().catch(() => undefined)
-      return
-    }
     this.host.showView?.(this.activeTab(s).handle, s.label)
+    const autoExpand = this.settingsSource === undefined || this.settingsSource().ui.autoExpandOnce
+    if (autoExpand) return
+    // Best effort: a carrier that owns no presentation (self-hosted) simply has none.
+    void this.host.collapse?.().catch(() => undefined)
   }
 
   /** Read the current URL of a view through CDP. */

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

@@ -25,7 +25,7 @@
  * @module dsh-browser/browser-electron/remote-host
  */
 
-import { execFileSync, spawn, type ChildProcessByStdio } from 'node:child_process'
+import { execFileSync, spawn } from 'node:child_process'
 import { appendFileSync, mkdirSync, statSync, writeFileSync } from 'node:fs'
 import { randomBytes } from 'node:crypto'
 import { createRequire } from 'node:module'
@@ -907,8 +907,11 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
 
   /** The child died: tear down so the next use starts a fresh child. */
   private onChildExit(): void {
-    if (this.disposed) return
-    process.stderr.write('[dsh-browser host] browser host gone; will restart on next use\n')
+    // A disposed host still has to drop these: returning here left a child that had
+    // already been replaced during a dispose race in no map at all, so nothing would
+    // ever kill it. Only the restart is suppressed, not the cleanup.
+    const wasDisposed = this.disposed
+    if (!wasDisposed) process.stderr.write('[dsh-browser host] browser host gone; will restart on next use\n')
     this.client = undefined
     this.server?.close()
     this.server = undefined

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

@@ -202,11 +202,18 @@ export class SettingsStore {
     try {
       mkdirSync(dirname(this.file), { recursive: true })
       writeFileSync(this.file, `${JSON.stringify(merged, null, 2)}\n`)
-    } catch {
-      // Keep the merged value in memory even when the write fails.
+    } catch (error) {
+      // Do NOT publish the new value as cached, and do not pretend the file changed: a
+      // reader compares the file's mtime against this stamp, so stamping "now" on a failed
+      // write made the next get() re-read the file and silently revert the user's change.
+      // Clear the cache before failing: the value on disk is still the old one, so leaving
+      // the merged document cached would hand the next reader something that does not exist —
+      // and the stamp would make it look fresh until the mtime comparison rolled it back.
+      this.cached = undefined
+      this.cachedMtimeMs = -1
+      throw new Error(`dsh-builtin-browser: settings could not be saved: ${error instanceof Error ? error.message : String(error)}`)
+
     }
-    this.cached = merged
-    this.cachedMtimeMs = Date.now()
     return merged
   }
 }