dsh-builtin-browser 0.1.23 → 0.3.0

package/src/browser-electron/provider.ts

@@ -11,6 +11,9 @@ import { randomUUID } from 'node:crypto'
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { dirname, isAbsolute, join, resolve, sep } from 'node:path'
+import { HistoryStore, type VisitedPage } from './history-store.js'
+import type { BrowserSettings } from './settings-store.js'
+import { forgetCursor, paintCursor, type CursorAction } from './virtual-cursor.js'
 import type {
   BrowserA11yRequest,
   BrowserA11yResult,
@@ -175,6 +178,38 @@ export interface ElectronBrowserViewHost {
    * @param handler - called for every user action; must not throw.
    */
   onUserAction?(handler: (action: BrowserUserAction) => void): void
+  /**
+   * Optional: receive notice that the human closed a browser window. Closing the
+   * interface ends the session it showed — the next call opens a clean one —
+   * while browsing history and login state survive on disk.
+   * @param handler - called with the group (session) key; must not throw.
+   */
+  onViewClosed?(handler: (windowId: string) => void): void
+  /**
+   * Release the service's page(s) without ending the plugin's own lifetime.
+   *
+   * Only carriers that outlive a browser session need this. A self-hosted window
+   * dies with its view, but the desktop shell's sidebar keeps running no matter
+   * what the plugin does — so "release the browser when the session ends"
+   * (settings: ui.closeWithSession) has to be asked for explicitly there.
+   * @returns a promise that settles once the release was attempted.
+   */
+  releasePage?(): Promise<void>
+  /**
+   * Fold the carrier's presentation away while keeping the page alive.
+   *
+   * The desktop sidebar keeps running regardless of the plugin, so "do not take
+   * over the screen" (settings: ui.autoExpandOnce = false) can only be honoured by
+   * asking the shell to fold it. A self-hosted window has no such state and simply
+   * does not implement this.
+   * @returns a promise that settles once the fold was attempted.
+   */
+  collapse?(): Promise<void>
+  /**
+   * Release everything the carrier owns (a spawned browser, a socket, a child).
+   * Called when the plugin stops using it, never while it is still in service.
+   */
+  dispose?(): void
 }
 
 /**
@@ -238,6 +273,28 @@ interface Session {
 export interface ElectronBrowserProviderConfig {
   /** Allow navigation only to HTTP(S) URLs; reject anything else. Default true. */
   readonly httpOnly?: boolean
+  /**
+   * Persistent browsing history (visited pages), independent of session
+   * lifetime. `enabled: false` keeps the browser working but records nothing;
+   * the retained limits ride along so a user's choice from the settings panel
+   * reaches the store without a second configuration path.
+   */
+  readonly history?: {
+    readonly enabled?: boolean
+    readonly maxEntries?: number
+    readonly maxAgeDays?: number
+    /**
+     * Explicit history file path. Default: beside the browser profile
+     * (`$DSH_HOME/dsh-builtin-browser-host/history.jsonl`).
+     */
+    readonly file?: string
+  }
+  /**
+   * Live settings source (the settings panel's document). When present it wins
+   * over the static `history` config, so a switch flipped in the UI takes effect
+   * without restarting DSH.
+   */
+  readonly settings?: () => BrowserSettings
   /** Maximum snapshot elements before truncation. Default 60. */
   readonly snapshotMaxElements?: number
   /** Maximum content characters before truncation when no maxChars is given. Default 100_000. */
@@ -365,6 +422,13 @@ export class ElectronBrowserProvider implements BrowserProvider {
   private readonly snapshotMaxElements: number
   private readonly contentMaxChars: number
   private readonly downloadDir: string | undefined
+  /**
+   * Persistent browsing history, or `undefined` when the user turned it off.
+   * Sessions come and go; this record outlives all of them.
+   */
+  private readonly historyStore: HistoryStore | undefined
+  /** Live settings source; absent when nothing owns a settings document. */
+  private readonly settingsSource: (() => BrowserSettings) | undefined
 
   constructor(
     private readonly host: ElectronBrowserViewHost,
@@ -379,9 +443,21 @@ export class ElectronBrowserProvider implements BrowserProvider {
     // sandbox does not have to arbitrate. The localized name is probed so a
     // Chinese desktop (`~/下载`) works without configuring `downloadDir`.
     this.downloadDir = config.downloadDir ?? defaultDownloadDir()
+    this.settingsSource = config.settings
+    // Browsing history follows the browser profile's persistence rules (close
+    // the interface, lose nothing), and can be switched off from settings.
+    this.historyStore = config.history?.enabled === false
+      ? undefined
+      : new HistoryStore(config.history?.file, {
+        ...config.history?.maxEntries !== undefined ? { maxEntries: config.history.maxEntries } : {},
+        ...config.history?.maxAgeDays !== undefined ? { maxAgeDays: config.history.maxAgeDays } : {},
+      })
     // Route toolbar (host UI) actions into the session model: the human and
     // the agent then always drive the same tabs, history, and navigation.
     this.host.onUserAction?.(action => { void this.handleUserAction(action) })
+    // A window the human closed ends the session it showed: the next call opens a
+    // clean one instead of driving a page nobody can see.
+    this.host.onViewClosed?.(windowId => { void this.handleViewClosed(windowId) })
   }
 
   /**
@@ -556,6 +632,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
       // NEXT observation sees, not whether this action happened).
       this.record(s, 'navigate', { url }, true)
       await this.settleDocument(handle, before, signal)
+      this.recordVisit(s, handle)
       this.showActive(s)
     } catch (error) {
       if (!(error instanceof BrowserError && (error as { code?: string }).code === 'BROWSER_NAVIGATION_BLOCKED')) {
@@ -618,6 +695,11 @@ export class ElectronBrowserProvider implements BrowserProvider {
   private async settleDocument(handle: ElectronViewHandle, before: string, signal?: AbortSignal): Promise<void> {
     const started = Date.now()
     const deadline = started + SETTLE_TIMEOUT_MS
+    // The document is being replaced, so the synthetic pointer drawn into the old one
+    // is gone. Dropping the remembered position is what lets it be painted again:
+    // without this, a paint at coincidentally identical coordinates would be skipped
+    // and the pointer would never come back after a navigation.
+    forgetCursor(handle)
     for (;;) {
       if (signal?.aborted === true) return
       // A probe failure is expected while the navigation commits (the context is
@@ -1128,21 +1210,39 @@ export class ElectronBrowserProvider implements BrowserProvider {
       // iframes stay opaque — the browser forbids reading them).
       let content = ''
       if (fmt === 'txt') {
-        const parts = []
-        const textWalk = (node) => {
-          if (node.nodeType === Node.TEXT_NODE) { const t = (node.textContent || '').trim(); if (t) parts.push(t); return }
-          if (node.nodeType !== Node.ELEMENT_NODE) return
-          const tag = node.tagName.toLowerCase()
-          if (tag === 'script' || tag === 'style' || tag === 'noscript') return
-          if (tag === 'iframe') {
-            try { const d = node.contentDocument; if (d && d.body) for (const c of d.body.childNodes) textWalk(c) } catch { /* cross-origin */ }
-            return
+        // Prefer the browser's own rendered text.
+        //
+        // Walking text nodes and joining them is not equivalent: pages that wrap
+        // every character in its own element — one-character spans for a
+        // per-character animation, which is common — produce one text node per
+        // letter, and joining those with spaces turns every word into a column of
+        // letters. The rendered text reassembles them the way a reader sees them,
+        // and it also honours visibility, so hidden text does not leak out.
+        // (No backticks in this comment: it lives inside a template literal.)
+        const rendered = typeof root.innerText === 'string' ? root.innerText : ''
+        if (rendered.trim() !== '') {
+          content = rendered
+        } else {
+          // Fallback for nodes without layout (a detached root, or a fragment):
+          // collect text directly, still piercing shadow roots and same-origin
+          // iframes, and join without inventing separators beyond what the markup
+          // already implies.
+          const parts = []
+          const textWalk = (node) => {
+            if (node.nodeType === Node.TEXT_NODE) { const t = (node.textContent || '').trim(); if (t) parts.push(t); return }
+            if (node.nodeType !== Node.ELEMENT_NODE) return
+            const tag = node.tagName.toLowerCase()
+            if (tag === 'script' || tag === 'style' || tag === 'noscript') return
+            if (tag === 'iframe') {
+              try { const d = node.contentDocument; if (d && d.body) for (const c of d.body.childNodes) textWalk(c) } catch { /* cross-origin */ }
+              return
+            }
+            if (node.shadowRoot) for (const c of node.shadowRoot.childNodes) textWalk(c)
+            for (const child of node.childNodes) textWalk(child)
           }
-          if (node.shadowRoot) for (const c of node.shadowRoot.childNodes) textWalk(c)
-          for (const child of node.childNodes) textWalk(child)
+          textWalk(root)
+          content = parts.join(' ')
         }
-        textWalk(root)
-        content = parts.join(' ')
       }
       else if (fmt === 'html') content = root.outerHTML || ''
       else if (fmt === 'json') content = JSON.stringify(root)
@@ -1218,6 +1318,18 @@ export class ElectronBrowserProvider implements BrowserProvider {
       x = Number(out.x)
       y = Number(out.y)
     } else {
+      // A coordinate only exists because somebody read a picture. Under the
+      // non-visual strategy the plugin must not accept one: a model that cannot
+      // see cannot have produced it, so the coordinates are either copied from an
+      // earlier vision pass or invented, and honouring them turns a silent
+      // mis-click into a mystery. Refusing here, with a message that says what to
+      // do instead, converts that into a usable instruction.
+      if (this.settingsSource !== undefined && this.settingsSource().vision.strategy === 'nonVisual') {
+        throw new BrowserError(
+          'browser: the configured non-visual strategy refuses coordinate clicks — pass a semantic target instead, e.g. target { by: "text", value: "Sign in" }, which locates the element from the DOM and clicks its centre',
+          'BROWSER_NON_VISUAL_COORDINATES',
+        )
+      }
       x = request.x
       y = request.y
     }
@@ -1244,6 +1356,11 @@ export class ElectronBrowserProvider implements BrowserProvider {
     } catch (error) {
       throw new BrowserError(`browser: click failed: ${String(error)}`, 'BROWSER_CLICK_FAILED', { cause: error })
     }
+    // Paint before the press so the ripple is already on screen when the click
+    // lands — the cursor exists to show the human WHERE the agent acts.
+    // Name the operation in the overlay: the pointer is the "agent is driving this
+    // tab" signal, so the bubble is what lets a human follow along without the log.
+    this.showCursor(handle, x, y, 'click', 'click', true)
     const release = (): void => {
       void handle
         .sendCommand('Input.dispatchMouseEvent', {
@@ -1293,7 +1410,10 @@ export class ElectronBrowserProvider implements BrowserProvider {
         el.focus()
         return { ok: true }
       `)
-      await this.runTargetScript(this.activeTab(s), script, locateMs, signal, 'BROWSER_TYPE_FAILED', 'browser: type')
+      const locateTab = this.activeTab(s)
+      const out = await this.runTargetScript(locateTab, script, locateMs, signal, 'BROWSER_TYPE_FAILED', 'browser: type')
+      const cursorPoint = scriptPoint(out)
+      if (cursorPoint !== undefined) this.showCursor(locateTab.handle, cursorPoint.x, cursorPoint.y, 'click', 'type', true)
     }
     const text = 'text' in request ? request.text : ''
     const timeoutMs = 30_000
@@ -1383,6 +1503,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
     )
     this.record(s, direction === -1 ? 'back' : 'forward', {}, true)
     await this.settleDocument(handle, before, signal)
+    this.recordVisit(s, handle)
     this.showActive(s)
   }
 
@@ -1415,6 +1536,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
     )
     this.record(s, 'reload', {}, true)
     await this.settleDocument(handle, before, signal)
+    this.recordVisit(s, handle)
     this.showActive(s)
   }
 
@@ -1664,7 +1786,18 @@ export class ElectronBrowserProvider implements BrowserProvider {
         if (Date.now() >= deadline) return { ok: false, error: 'element not found: ' + JSON.stringify(spec) + ' (looked for ' + timeoutMs + 'ms)' }
         await sleep(100)
       }
+      const __result = await (async () => {
       ${body}
+      })()
+      // Report the operated element's viewport center next to the script's own
+      // verdict: the synthetic cursor (and any future feedback) needs the point,
+      // and no individual body should have to compute it a second time. Kept
+      // under a distinct key so a body that already returns x/y keeps them.
+      const __rect = el.getBoundingClientRect()
+      return {
+        ...(typeof __result === 'object' && __result !== null ? __result : { ok: true }),
+        __point: { x: Math.round(__rect.x + __rect.width / 2), y: Math.round(__rect.y + __rect.height / 2) },
+      }
     })()`
   }
 
@@ -1742,6 +1875,8 @@ export class ElectronBrowserProvider implements BrowserProvider {
     `
     const script = this.buildTargetScript(request.target, timeoutMs, body)
     const out = await this.runTargetScript(tab, script, timeoutMs, signal, 'BROWSER_SET_VALUE_FAILED', 'browser: setValue')
+    const cursorPoint = scriptPoint(out)
+    if (cursorPoint !== undefined) this.showCursor(tab.handle, cursorPoint.x, cursorPoint.y, 'click')
     this.record(s, 'setValue', { target: request.target, value: String(request.value) }, true, { result: out.method as string })
     return { method: out.method as string, value: out.value as string }
   }
@@ -1768,6 +1903,8 @@ export class ElectronBrowserProvider implements BrowserProvider {
     `
     const script = this.buildTargetScript(request.target, timeoutMs, body)
     const out = await this.runTargetScript(tab, script, timeoutMs, signal, 'BROWSER_CHECK_FAILED', 'browser: check')
+    const cursorPoint = scriptPoint(out)
+    if (cursorPoint !== undefined) this.showCursor(tab.handle, cursorPoint.x, cursorPoint.y, 'click')
     this.record(s, 'check', { target: request.target, checked: want }, true)
     return { checked: out.checked === true }
   }
@@ -1800,6 +1937,8 @@ export class ElectronBrowserProvider implements BrowserProvider {
     `
     const script = this.buildTargetScript(request.target, timeoutMs, body)
     const out = await this.runTargetScript(tab, script, timeoutMs, signal, 'BROWSER_SELECT_FAILED', 'browser: select')
+    const cursorPoint = scriptPoint(out)
+    if (cursorPoint !== undefined) this.showCursor(tab.handle, cursorPoint.x, cursorPoint.y, 'click')
     this.record(s, 'select', { target: request.target, optionValue: request.optionValue ?? null, optionText: request.optionText ?? null, optionIndex: request.optionIndex ?? null }, true)
     return { value: out.value as string, text: out.text as string }
   }
@@ -1833,7 +1972,9 @@ export class ElectronBrowserProvider implements BrowserProvider {
       return { ok: true }
     `
     const script = this.buildTargetScript(request.target, timeoutMs, body)
-    await this.runTargetScript(tab, script, timeoutMs, signal, 'BROWSER_CLEAR_FAILED', 'browser: clear')
+    const out = await this.runTargetScript(tab, script, timeoutMs, signal, 'BROWSER_CLEAR_FAILED', 'browser: clear')
+    const cursorPoint = scriptPoint(out)
+    if (cursorPoint !== undefined) this.showCursor(tab.handle, cursorPoint.x, cursorPoint.y, 'click')
     this.record(s, 'clear', { target: request.target }, true)
     return { cleared: true }
   }
@@ -2160,6 +2301,63 @@ export class ElectronBrowserProvider implements BrowserProvider {
     return this.session(session).history
   }
 
+  /**
+   * Record one page visit in the persistent browsing history. Fire-and-forget by
+   * design: a visit must never delay or fail the navigation that produced it,
+   * and the title is only worth reading once the document has settled.
+   * @param s - the session that drove the visit.
+   * @param handle - the view whose document just loaded.
+   */
+  private recordVisit(s: Session, handle: ElectronViewHandle): void {
+    const store = this.historyStore
+    if (store === undefined) return
+    // The settings panel can switch recording off at runtime; the static config
+    // only supplies the startup default.
+    if (this.settingsSource !== undefined && !this.settingsSource().history.enabled) return
+    void handleSendEvaluate(handle, 'location.href + "\\u0000" + (document.title || "")')
+      .then(result => {
+        if (!result.ok || typeof result.value !== 'string') return
+        const [url = '', title = ''] = result.value.split('\u0000')
+        // Internal documents are not visits: an untouched browser is not history.
+        if (url === '' || url.startsWith('about:') || url.startsWith('devtools:')) return
+        store.append({
+          at: Date.now(),
+          url,
+          ...title.trim() !== '' ? { title: title.trim() } : {},
+          ...s.label !== undefined ? { session: s.label } : {},
+        })
+        store.prune()
+      })
+      .catch(() => { /* best-effort: history is never worth surfacing an error */ })
+  }
+
+  /**
+   * List persisted visits, newest first — what `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.
+   */
+  visited(options: { readonly limit?: number; readonly domain?: string; readonly query?: string; readonly session?: string } = {}): readonly VisitedPage[] {
+    return this.historyStore?.list(options) ?? []
+  }
+
+  /**
+   * Show the synthetic pointer on a view, unless the user switched it off. The
+   * cursor is the "the agent has taken over this tab" signal, so it is painted
+   * for every operation that has a landing point — including DOM-level ones that
+   * move no real pointer.
+   * @param handle - the view to paint into.
+   * @param x - viewport x in CSS pixels.
+   * @param y - viewport y in CSS pixels.
+   * @param action - click pulses a ripple; move only relocates.
+   * @param label - short description of the operation, shown beside the pointer.
+   * @param force - paint even when the pointer is already there (a click ripple must
+   *   always play; a bare move need not repeat).
+   */
+  private showCursor(handle: ElectronViewHandle, x: number, y: number, action: CursorAction, label?: string, force = false): void {
+    if (this.settingsSource !== undefined && !this.settingsSource().ui.virtualCursor) return
+    paintCursor(handle, x, y, action, (target, expression) => handleSendEvaluate(target, expression), label, force)
+  }
+
   /**
    * Replay one recorded operation by sequence number. Navigate/click/type are
    * re-issued against the current page; execute re-runs its script. The
@@ -2237,6 +2435,13 @@ export class ElectronBrowserProvider implements BrowserProvider {
     if (existing !== undefined) {
       this.sessions.delete(session)
       for (const tab of existing.tabs) this.host.destroyView(tab.handle)
+      // Releasing the browser at session end is a setting, not fixed behaviour
+      // (requirements §3). A self-hosted carrier already tore its window down with
+      // the views above; the desktop's sidebar does not, so it is asked explicitly
+      // — and its cookies plus the browsing history outlive the page either way.
+      if (this.settingsSource !== undefined && this.settingsSource().ui.closeWithSession) {
+        void this.host.releasePage?.().catch(() => undefined)
+      }
     }
     return Promise.resolve()
   }
@@ -2272,6 +2477,29 @@ export class ElectronBrowserProvider implements BrowserProvider {
     return s.tabs.find(tab => tab.handle.id === viewId)
   }
 
+  /**
+   * Whether a session is still live. The human closing a window ends its session
+   * (see {@link handleViewClosed}), so callers that cache ids must ask first.
+   * @param session - the session id to test.
+   */
+  exists(session: BrowserSessionId): boolean {
+    return this.sessions.has(session)
+  }
+
+  /**
+   * The human closed a browser window: the session that window showed is over.
+   * Ending it here is what makes the next call a clean start rather than a
+   * resurrection of an invisible window. Browsing history and login state live
+   * on disk, so nothing the human cares about is lost with it.
+   * @param windowId - the group key the host reported, which is the session id.
+   */
+  private async handleViewClosed(windowId: string): Promise<void> {
+    if (typeof windowId !== 'string' || windowId === '') return
+    const s = this.sessions.get(windowId as BrowserSessionId)
+    if (s === undefined) return
+    await this.close(s.id).catch(() => { /* the window is already gone */ })
+  }
+
   /**
    * Route a user-initiated action from the host's UI into the session model.
    * Fire-and-forget by design: a user action failing (e.g. an unreachable
@@ -2325,19 +2553,46 @@ export class ElectronBrowserProvider implements BrowserProvider {
     }
   }
 
-  /** Report a failed user action to the host UI (toolbar), when supported. */
+  /**
+   * Report a failed user action to the host UI (toolbar), when supported.
+   *
+   * Two properties matter here, because this runs inside the catch of an async
+   * handler (issue #16):
+   *  - the receiver must be preserved. Reading the method off the host and calling
+   *    it unbound runs the host's implementation with `this === undefined`, so its
+   *    very first statement (`void this.ready()`) throws, the throw escapes the
+   *    async catch as an unhandled rejection, and the whole DSH host exits;
+   *  - this method must be incapable of throwing. Reporting a failed action is
+   *    diagnostics: it can never be allowed to become the failure.
+   */
   private notifyUserActionError(action: BrowserUserAction, error: unknown): void {
-    const notify = (this.host as { notifyUserActionError?(windowId: string, message: string): void }).notifyUserActionError
     const message = `action ${action.type} failed: ${String(error)}`
-    if (typeof notify === 'function') {
-      notify(action.windowId, message)
-    } else {
-      process.stderr.write(`[dsh-browser] user action failed: ${message}\n`)
+    let reported = false
+    try {
+      const host = this.host as { notifyUserActionError?(windowId: string, message: string): void }
+      const notify = host.notifyUserActionError
+      if (typeof notify === 'function') {
+        // Called on its owner: an unbound call here kills the host process.
+        notify.call(host, action.windowId, message)
+        reported = true
+      }
+    } catch (notifyError) {
+      // Contained on purpose; the log line below still carries the original cause.
+      process.stderr.write(`[dsh-browser] host notify failed: ${String(notifyError)}\n`)
     }
+    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. */
   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)
   }
 
@@ -2477,6 +2732,14 @@ function terminatePage(handle: ElectronViewHandle): void {
  * @param expression - the JS expression.
  * @param signal - optional abort signal; a fired signal rejects the call.
  */
+/** Viewport point a target script reported, when it reported one. */
+function scriptPoint(out: Record<string, unknown> | undefined): { x: number; y: number } | undefined {
+  const point = out?.__point as { x?: unknown; y?: unknown } | undefined
+  const x = Number(point?.x)
+  const y = Number(point?.y)
+  return Number.isFinite(x) && Number.isFinite(y) ? { x, y } : undefined
+}
+
 async function handleSendEvaluate(
   handle: ElectronViewHandle,
   expression: string,

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

@@ -440,12 +440,28 @@ class ElectronChildClient {
     private readonly token: string,
     private readonly onExit?: () => void,
     private readonly onUserAction?: (action: BrowserUserAction) => void,
+    /**
+     * Called when the human closes a browser window. The session it showed is
+     * over: the provider releases it, while history and login state stay on disk
+     * so the next open is a clean session rather than a resurrected one.
+     */
+    private readonly onViewClosed?: (windowId: string) => void,
     /** Test seam: the executable to spawn instead of the resolved Electron
      *  binary. Absent -> resolveElectronPath() (production behavior). */
     private readonly executable?: string,
   ) {
     const electron = this.executable ?? resolveElectronPath()
+    // Record what is about to be spawned — with existence checks — BEFORE the
+    // attempt. When Electron cannot load the app entry it exits 1 with EMPTY
+    // stderr, and that signature is otherwise indistinguishable from a missing
+    // binary: writing both paths (and whether they exist) in advance is what
+    // turns the next occurrence into a named cause instead of a guess.
     process.stderr.write(`[dsh-browser host] spawning electron: ${electron}\n`)
+    appendHostLog(
+      `${hostStamp()} spawning: electron=${electron} (exists=${String(existsSync(electron))})`
+      + ` hostMain=${this.hostMainPath} (exists=${String(existsSync(this.hostMainPath))})`
+      + ` port=${String(this.port)}\n`,
+    )
     // ELECTRON_RUN_AS_NODE (even an empty string) makes Electron run as plain
     // Node, breaking require('electron'); NODE_OPTIONS can inject flags that
     // break the child. Rebuild the env without either.
@@ -482,15 +498,26 @@ class ElectronChildClient {
     // A failed spawn (bad/corrupt binary) emits 'error' — without a listener
     // that would crash the whole DSH process.
     this.child.on('error', error => {
-      const line = `spawn error: ${String(error)}`
+      const line = `${hostStamp()} spawn error: ${String(error)} electron=${electron} hostMain=${this.hostMainPath}`
       process.stderr.write(`[dsh-browser host] ${line}\n`)
       appendHostLog(`${line}\n`)
       this.fail(new Error(`dsh-builtin-browser: browser host failed to start: ${String(error)}`))
     })
     this.child.on('exit', (code, signal) => {
       // The exit code/signal is the other half of a crash report; without it a
-      // restart loop is indistinguishable from a clean stop.
-      const line = `browser host exited (code=${String(code)} signal=${String(signal)})`
+      // restart loop is indistinguishable from a clean stop. The timestamp, pid
+      // and both paths are what turn a bare `code=1` into a diagnosis: Electron
+      // exits 1 with empty stderr precisely when it cannot load the app entry,
+      // so the dated `exists=` line written at spawn is the other half.
+      const entryExists = existsSync(this.hostMainPath)
+      const line = `${hostStamp()} browser host exited (code=${String(code)} signal=${String(signal)})`
+        + ` pid=${String(this.child?.pid)} electron=${electron} hostMain=${this.hostMainPath}`
+        + ` entryExists=${String(entryExists)}`
+        // Comparing this with the `exists=` recorded at spawn is the whole
+        // diagnosis: present at spawn and absent now means the installation was
+        // replaced underneath a running host, which is exactly how Electron ends
+        // up unable to load the app entry and exits 1 with empty stderr.
+        + (entryExists ? '' : ' [entry script missing at exit]')
       appendHostLog(`${line}\n`)
       this.fail(new Error(`dsh-builtin-browser: ${line}`))
     })
@@ -566,7 +593,7 @@ class ElectronChildClient {
       const line = this.buffer.slice(0, nl).trim()
       this.buffer = this.buffer.slice(nl + 1)
       if (line === '') continue
-      let msg: { id?: number; op?: string; token?: string; ok?: boolean; result?: unknown; err?: string; action?: unknown }
+      let msg: { id?: number; op?: string; token?: string; ok?: boolean; result?: unknown; err?: string; action?: unknown; windowId?: unknown }
       try {
         msg = JSON.parse(line) as typeof msg
       } catch {
@@ -580,6 +607,14 @@ class ElectronChildClient {
         this.onUserAction?.(msg.action as BrowserUserAction)
         continue
       }
+      if (msg.op === 'viewClosed') {
+        // Fire-and-forget notification from the child's own UI: the human closed
+        // the window, so the interface that session showed is gone. The provider
+        // decides what that ends — browsing history and login state survive on
+        // disk, only the session itself does not.
+        this.onViewClosed?.(typeof msg.windowId === 'string' ? msg.windowId : '')
+        continue
+      }
       if (this.awaitingHello) {
         // The FIRST line must be the child's hello carrying the spawn token.
         // Anything else (or a wrong token) means a spoofed connection: drop
@@ -717,6 +752,12 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
   private readonly groups = new Map<string, { windowId: string; label?: string }>()
   /** The provider's user-action handler; routes toolbar actions into sessions. */
   private userActionHandler: ((action: BrowserUserAction) => void) | undefined
+  /**
+   * The provider's handler for a window the human closed. Closing the interface
+   * ends the session it showed: history and login state stay on disk, so the
+   * next open starts clean instead of resuming a window nobody can see.
+   */
+  private viewClosedHandler: ((windowId: string) => void) | undefined
 
   constructor(
     private readonly hostMainPath: string,
@@ -758,12 +799,27 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
     return this.electronAvailable
   }
 
-  /** Ensure the child is up and ready (lazy on first use; restarts after a crash). */
+  /**
+   * Ensure the child is up and ready (lazy on first use; restarts after a crash).
+   *
+   * Never throws synchronously. Callers are fire-and-forget
+   * (`void this.ready().then(…).catch(…)`), and a synchronous throw escapes their
+   * `.catch` entirely — the shape that let a failed toolbar report take the whole
+   * DSH host down (issue #16). A disposed host is reported as a rejected promise
+   * instead, which those callers already handle.
+   */
   private ready(): Promise<void> {
     // Fail fast on a disposed host: a recovery path can re-enter ready() after
     // dispose() cleared its state, and starting fresh here would spawn a child
     // nobody will ever kill.
-    if (this.disposed) throw new HostGoneError('browser host disposed')
+    if (this.disposed) {
+      const gone = Promise.reject(new HostGoneError('browser host disposed'))
+      // Keep the rejection observable to callers while marking it handled here:
+      // a fire-and-forget caller that forgot to attach a handler must not turn
+      // this into an unhandled rejection either.
+      gone.catch(() => undefined)
+      return gone
+    }
     if (this.readyPromise !== undefined) return this.readyPromise
     const started = this.start()
     const wrapped = started.catch(error => {
@@ -826,6 +882,7 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
       token,
       () => this.onChildExit(),
       action => this.userActionHandler?.(action),
+      windowId => this.viewClosedHandler?.(windowId),
       this.spawnExecutable,
     )
     if (this.pendingSocket !== undefined) {
@@ -959,6 +1016,11 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
     this.userActionHandler = handler
   }
 
+  /** Register the provider's handler for windows the human closed. */
+  onViewClosed(handler: (windowId: string) => void): void {
+    this.viewClosedHandler = handler
+  }
+
   /** Surface a failed user action to the child's toolbar (address bar etc.). */
   notifyUserActionError(windowId: string, message: string): void {
     void this.ready()
@@ -1080,6 +1142,16 @@ class DeferredRemoteView implements ElectronViewHandle {
  */
 const HOST_LOG_MAX_BYTES = 2 * 1024 * 1024
 
+/**
+ * ISO timestamp prefix for host-log lines. This log is the only place a spawn
+ * failure is recorded, and an undated line cannot be lined up with anything else
+ * that happened on the machine — a plugin update replacing the entry script, for
+ * instance — which is precisely the question this log gets asked.
+ */
+function hostStamp(): string {
+  return new Date().toISOString()
+}
+
 function appendHostLog(text: string): void {
   const home = process.env.DSH_HOME
   if (home === undefined || home === '') return
@@ -1087,7 +1159,12 @@ function appendHostLog(text: string): void {
     const dir = join(home, 'logs')
     const file = join(dir, 'dsh-builtin-browser-host.log')
     try {
-      if (statSync(file).size > HOST_LOG_MAX_BYTES) writeFileSync(file, '')
+      if (statSync(file).size > HOST_LOG_MAX_BYTES) {
+        // Discard the old bytes but leave a dated marker: truncating to empty
+        // makes a rotation look like "nothing ever happened", which is how the
+        // history of a crash loop gets silently swallowed.
+        writeFileSync(file, `${hostStamp()} log rotated: previous content exceeded ${String(HOST_LOG_MAX_BYTES)} bytes and was discarded\n`)
+      }
     } catch { /* first write, or unreadable: just append */ }
     mkdirSync(dir, { recursive: true })
     appendFileSync(file, text)