dsh-builtin-browser 0.1.23 → 0.3.0

package/lib/browser-electron/provider.js

@@ -10,6 +10,8 @@ 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 } from './history-store.js';
+import { forgetCursor, paintCursor } from './virtual-cursor.js';
 import { BrowserError } from '../browser/types.js';
 /**
  * Page-context human-verification (CAPTCHA / bot-detection) detection. Runs
@@ -135,6 +137,13 @@ export class ElectronBrowserProvider {
     snapshotMaxElements;
     contentMaxChars;
     downloadDir;
+    /**
+     * Persistent browsing history, or `undefined` when the user turned it off.
+     * Sessions come and go; this record outlives all of them.
+     */
+    historyStore;
+    /** Live settings source; absent when nothing owns a settings document. */
+    settingsSource;
     constructor(host, config = {}) {
         this.host = host;
         this.httpOnly = config.httpOnly ?? true;
@@ -146,9 +155,21 @@ export class ElectronBrowserProvider {
         // 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); });
     }
     /**
      * Usable when the host says it can back views (the self-hosted host probes
@@ -313,6 +334,7 @@ export class ElectronBrowserProvider {
             // 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) {
@@ -371,6 +393,11 @@ export class ElectronBrowserProvider {
     async settleDocument(handle, before, signal) {
         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;
@@ -848,21 +875,39 @@ export class ElectronBrowserProvider {
       // 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)
@@ -930,6 +975,15 @@ export class ElectronBrowserProvider {
             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;
         }
@@ -951,6 +1005,11 @@ export class ElectronBrowserProvider {
         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 handle
                 .sendCommand('Input.dispatchMouseEvent', {
@@ -997,7 +1056,11 @@ export class ElectronBrowserProvider {
         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;
@@ -1067,6 +1130,7 @@ export class ElectronBrowserProvider {
         await withTimeout(handle.sendCommand('Page.navigateToHistoryEntry', { entryId: entry.id }), timeoutMs, signal, `browser: history navigation timed out after ${timeoutMs}ms`, () => { void handle.sendCommand('Page.stopLoading').catch(() => { }); });
         this.record(s, direction === -1 ? 'back' : 'forward', {}, true);
         await this.settleDocument(handle, before, signal);
+        this.recordVisit(s, handle);
         this.showActive(s);
     }
     /** Go back in the active tab's history. */
@@ -1091,6 +1155,7 @@ export class ElectronBrowserProvider {
         () => { void handle.sendCommand('Page.stopLoading').catch(() => { }); });
         this.record(s, 'reload', {}, true);
         await this.settleDocument(handle, before, signal);
+        this.recordVisit(s, handle);
         this.showActive(s);
     }
     /** Press one named key (Enter/Tab/arrows/…) via CDP key events. */
@@ -1332,7 +1397,18 @@ export class ElectronBrowserProvider {
         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) },
+      }
     })()`;
     }
     /**
@@ -1397,6 +1473,9 @@ export class ElectronBrowserProvider {
     `;
         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 });
         return { method: out.method, value: out.value };
     }
@@ -1422,6 +1501,9 @@ export class ElectronBrowserProvider {
     `;
         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 };
     }
@@ -1453,6 +1535,9 @@ export class ElectronBrowserProvider {
     `;
         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, text: out.text };
     }
@@ -1485,7 +1570,10 @@ export class ElectronBrowserProvider {
       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 };
     }
@@ -1775,6 +1863,65 @@ export class ElectronBrowserProvider {
     async history(session) {
         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.
+     */
+    recordVisit(s, handle) {
+        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(() => { });
+    }
+    /**
+     * 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 = {}) {
+        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).
+     */
+    showCursor(handle, x, y, action, label, force = false) {
+        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
@@ -1857,6 +2004,13 @@ export class ElectronBrowserProvider {
             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();
     }
@@ -1888,6 +2042,29 @@ export class ElectronBrowserProvider {
     tabByViewId(s, viewId) {
         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) {
+        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.
+     */
+    async handleViewClosed(windowId) {
+        if (typeof windowId !== 'string' || windowId === '')
+            return;
+        const s = this.sessions.get(windowId);
+        if (s === undefined)
+            return;
+        await this.close(s.id).catch(() => { });
+    }
     /**
      * 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
@@ -1943,19 +2120,47 @@ export class ElectronBrowserProvider {
             this.notifyUserActionError(action, error);
         }
     }
-    /** 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.
+     */
     notifyUserActionError(action, error) {
-        const notify = this.host.notifyUserActionError;
         const message = `action ${action.type} failed: ${String(error)}`;
-        if (typeof notify === 'function') {
-            notify(action.windowId, message);
+        let reported = false;
+        try {
+            const host = this.host;
+            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;
+            }
         }
-        else {
-            process.stderr.write(`[dsh-browser] user action failed: ${message}\n`);
+        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. */
     showActive(s) {
+        // §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);
     }
     /** Read the current URL of a view through CDP. */
@@ -2079,6 +2284,13 @@ function terminatePage(handle) {
  * @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) {
+    const point = out?.__point;
+    const x = Number(point?.x);
+    const y = Number(point?.y);
+    return Number.isFinite(x) && Number.isFinite(y) ? { x, y } : undefined;
+}
 async function handleSendEvaluate(handle, expression, signal) {
     signal?.throwIfAborted();
     const result = await handle.sendCommand(CDP_RUNTIME_EVALUATE, {

package/lib/browser-electron/remote-host.d.ts

@@ -118,6 +118,12 @@ export declare class RemoteElectronViewHost implements ElectronBrowserViewHost {
     private readonly groups;
     /** The provider's user-action handler; routes toolbar actions into sessions. */
     private userActionHandler;
+    /**
+     * 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;
     constructor(hostMainPath: string, 
     /** Test seam: the executable to spawn instead of the resolved Electron
      *  binary. Absent -> resolveElectronPath() (production behavior). */
@@ -139,7 +145,15 @@ export declare class RemoteElectronViewHost implements ElectronBrowserViewHost {
      * on a cooldown heals it by itself while keeping the scan off the hot path.
      */
     available(): boolean;
-    /** 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;
     private start;
     /** The child died: tear down so the next use starts a fresh child. */
@@ -167,6 +181,8 @@ export declare class RemoteElectronViewHost implements ElectronBrowserViewHost {
     groupView(handle: ElectronViewHandle, windowId: string, label?: string): void;
     /** Register the provider's handler for user-initiated toolbar actions. */
     onUserAction(handler: (action: BrowserUserAction) => void): void;
+    /** Register the provider's handler for windows the human closed. */
+    onViewClosed(handler: (windowId: string) => void): void;
     /** Surface a failed user action to the child's toolbar (address bar etc.). */
     notifyUserActionError(windowId: string, message: string): void;
     destroyView(handle: ElectronViewHandle): void;

package/lib/browser-electron/remote-host.js

@@ -374,6 +374,7 @@ class ElectronChildClient {
     token;
     onExit;
     onUserAction;
+    onViewClosed;
     executable;
     child;
     pending = new Map();
@@ -392,6 +393,12 @@ class ElectronChildClient {
     awaitingHello = true;
     helloTimer;
     constructor(hostMainPath, port, token, onExit, onUserAction, 
+    /**
+     * 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.
+     */
+    onViewClosed, 
     /** Test seam: the executable to spawn instead of the resolved Electron
      *  binary. Absent -> resolveElectronPath() (production behavior). */
     executable) {
@@ -400,9 +407,18 @@ class ElectronChildClient {
         this.token = token;
         this.onExit = onExit;
         this.onUserAction = onUserAction;
+        this.onViewClosed = onViewClosed;
         this.executable = executable;
         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.
@@ -439,15 +455,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}`));
         });
@@ -537,6 +564,14 @@ class ElectronChildClient {
                 this.onUserAction?.(msg.action);
                 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
@@ -681,6 +716,12 @@ export class RemoteElectronViewHost {
     groups = new Map();
     /** The provider's user-action handler; routes toolbar actions into sessions. */
     userActionHandler;
+    /**
+     * 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.
+     */
+    viewClosedHandler;
     constructor(hostMainPath, 
     /** Test seam: the executable to spawn instead of the resolved Electron
      *  binary. Absent -> resolveElectronPath() (production behavior). */
@@ -724,13 +765,27 @@ export class RemoteElectronViewHost {
         }
         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.
+     */
     ready() {
         // 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();
@@ -787,7 +842,7 @@ export class RemoteElectronViewHost {
         // Random per-spawn token: the child must prove knowledge of it (via
         // stdin hello) before any command is written to the socket.
         const token = randomBytes(24).toString('hex');
-        this.client = new ElectronChildClient(this.hostMainPath, port, token, () => this.onChildExit(), action => this.userActionHandler?.(action), this.spawnExecutable);
+        this.client = new ElectronChildClient(this.hostMainPath, port, token, () => this.onChildExit(), action => this.userActionHandler?.(action), windowId => this.viewClosedHandler?.(windowId), this.spawnExecutable);
         if (this.pendingSocket !== undefined) {
             this.client.attach(this.pendingSocket);
             this.pendingSocket = undefined;
@@ -916,6 +971,10 @@ export class RemoteElectronViewHost {
     onUserAction(handler) {
         this.userActionHandler = handler;
     }
+    /** Register the provider's handler for windows the human closed. */
+    onViewClosed(handler) {
+        this.viewClosedHandler = handler;
+    }
     /** Surface a failed user action to the child's toolbar (address bar etc.). */
     notifyUserActionError(windowId, message) {
         void this.ready()
@@ -1028,6 +1087,15 @@ class DeferredRemoteView {
  * gets large (a crash loop writes quickly).
  */
 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() {
+    return new Date().toISOString();
+}
 function appendHostLog(text) {
     const home = process.env.DSH_HOME;
     if (home === undefined || home === '')
@@ -1036,8 +1104,12 @@ function appendHostLog(text) {
         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 });