dsh-builtin-browser 0.1.9 → 0.1.11

package/README.en.md

@@ -120,9 +120,15 @@ The browser's **visible view**, the **browser column layout**, and the **column-
 ## Known limitations
 
 - Screenshots are PNG-only (CDP JPEG hangs on Electron 43); JPEG awaits a non-CDP conversion path.
+- Self-hosted captures prefer Electron's native `capturePage` (CDP `captureScreenshot` can hang with multiple views in the window); the target tab is raised before capturing.
+- **Electron >= 40 is recommended**: 33.x has a compositor defect that intermittently breaks capture ("display surface not available"). The plugin automatically picks the newest Electron in the environment (peer dependency > `ELECTRON_PATH` > newest among anchors/pnpm store).
 - `fullPage` capture is flaky under software compositing on some hosts.
-- Session lifecycle is plugin-level (one session shared by the model), not per-agent yet.
+- Sessions are isolated per task (each DSH session gets its own browser session with own tabs/history; concurrent tasks never interfere; calls within one task reuse the same session). Logins (cookies) are shared and can be exported/restored with `browser_auth`.
+- CAPTCHA cannot be solved automatically: snapshots flag detected challenges (`browser_challenge` checks explicitly); ask the human to complete it in the shared window instead of retrying.
 - Private mode (`privateMode`) is not implemented: it needs Electron session partitioning, which is host-layer territory; this plugin does not promise it.
+- `browser_download` fetches in the page context (keeps logins) and is subject to same-origin/CORS constraints; single files are capped at 256 MB.
+- The `browser_auth` cookie round-trip does not preserve `hostOnly`/`sameSite` (host-only cookies come back as domain cookies); it is available on the self-hosted browser only.
+- After a self-hosted child crash the browser host restarts automatically, but sessions opened before the crash are gone — call `browser_reset_session` to rebuild.
 - This plugin contains no browser-column UI — that is host-shell territory; do not treat "browser column" as a plugin feature.
 
 ## License

package/README.md

@@ -127,10 +127,15 @@ provider 按构造与 Electron 解耦:它通过 `ElectronBrowserViewHost` 接缝
 ## 已知限制
 
 - 截图仅 PNG(CDP JPEG 在 Electron 43 上挂起);JPEG 等待非 CDP 转换路径。
+- 自托管截图优先走 Electron 原生 `capturePage`(CDP `captureScreenshot` 在多视图下会挂起);截图前自动把目标标签置顶。
+- **Electron 版本建议 ≥ 40**:33.x 存在合成器缺陷,会间歇性导致截图失败("display surface not available")。插件会**自动选择环境中最新版本的 Electron**(peer 依赖 > `ELECTRON_PATH` > 锚点/pnpm store 中最新版)。
 - 部分主机在软件合成下 `fullPage` 截图不稳定。
 - 会话按任务隔离:每个调用方任务(DSH 会话)拥有独立的浏览器会话(独立标签页与历史),并发任务互不干扰;同一任务的多次调用复用同一会话。登录态(cookie)为共享,可用 `browser_auth` 导出/恢复。
 - 人机验证(CAPTCHA)无法自动解决:快照会标注检测到的挑战(`browser_challenge` 可显式检查),此时应请用户在共享窗口中人工完成,而不是反复重试。
 - 无痕模式(`privateMode`)未实现:它需要 Electron 的 session 分区能力,属于宿主层,本插件不承诺。
+- `browser_download` 在页面上下文内 `fetch`(带登录态),受同源/CORS 约束;单文件上限 256MB。
+- `browser_auth` 的 cookie 往返不保留 `hostOnly`/`sameSite` 字段(host-only cookie 恢复后变成 domain cookie);仅自托管浏览器可用。
+- 自托管浏览器子进程崩溃后会自动重启,但崩溃前已打开的会话视图已失效,调用 `browser_reset_session` 重建即可。
 - 本插件不含浏览器列 UI——那是宿主外壳的配套,别把"浏览器列"当成插件能力。
 
 ## 许可证

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

@@ -16,8 +16,23 @@
 import { app, BrowserWindow, WebContentsView } from 'electron';
 import { createInterface } from 'node:readline';
 import { createConnection } from 'node:net';
+import { join } from 'node:path';
+// Isolate this host's profile from the DSH app's default Electron userData:
+// several Electron instances sharing Roaming\Electron fight over the GPU
+// cache/session locks, which can leave the window without a display surface
+// (capturePage then fails). A dedicated userData also persists cookies across
+// host restarts (on top of browser_auth). Must run before app is ready.
+try {
+    const base = process.env.DSH_HOME ?? app.getPath('appData');
+    app.setPath('userData', join(base, 'dsh-builtin-browser-host'));
+}
+catch (error) {
+    process.stderr.write(`[dsh-browser host] userData setup failed: ${String(error)}\n`);
+}
 /** CDP protocol version attached to every view's debugger. */
 const CDP_VERSION = '1.3';
+/** Download cap: the body is shipped base64 as one JSON line; bound the memory. */
+const MAX_DOWNLOAD_BYTES = 256 * 1024 * 1024;
 /** Views by the id the parent assigned at createView time. */
 const views = new Map();
 /** The single browser window; created lazily on first createView. */
@@ -48,6 +63,9 @@ async function handle(op, msg) {
                     window.on('closed', () => { window = undefined; });
                 }
                 const view = new WebContentsView();
+                // Attach the debugger BEFORE the view can be seen: an attach failure
+                // then leaves nothing in the window (no visible ghost view).
+                view.webContents.debugger.attach(CDP_VERSION);
                 // New views start hidden: with several sessions/tabs only the shown
                 // one may be visible (they stack in contentView child order).
                 view.setVisible(false);
@@ -56,7 +74,6 @@ async function handle(op, msg) {
                 view.setBounds({ x: 0, y: 0, width: width ?? 0, height: height ?? 0 });
                 if (views.size === 0)
                     view.setVisible(true);
-                view.webContents.debugger.attach(CDP_VERSION);
                 views.set(viewId, { webContentsView: view });
                 reply(msg.id, { ok: true });
                 return;
@@ -117,6 +134,94 @@ async function handle(op, msg) {
                 reply(msg.id, { ok: true, result });
                 return;
             }
+            case 'capture': {
+                const viewId = msg.viewId;
+                if (viewId === undefined)
+                    throw new Error('capture missing viewId');
+                const entry = views.get(viewId);
+                if (entry === undefined)
+                    throw new Error(`capture: unknown view ${viewId}`);
+                // Two complementary paths, because each has a failure mode:
+                //  - capturePage: fast and reliable with several WebContentsViews in
+                //    the window, but needs a live display surface (fails when the
+                //    window is minimized/occluded/unpainted).
+                //  - CDP Page.captureScreenshot: works without a display surface, but
+                //    can hang when another hidden WebContentsView exists in the window.
+                // Try capturePage first (show/focus/restore + one retry), then CDP.
+                if (window !== undefined) {
+                    try {
+                        if (!window.isVisible())
+                            window.show();
+                    }
+                    catch { /* closing */ }
+                    try {
+                        window.restore();
+                    }
+                    catch { /* not minimized */ }
+                    window.focus();
+                }
+                let base64 = '';
+                try {
+                    let image;
+                    try {
+                        image = await entry.webContentsView.webContents.capturePage();
+                    }
+                    catch (error) {
+                        process.stderr.write(`[dsh-browser host] capturePage failed: ${String(error)}\n`);
+                        await new Promise(resolve => setTimeout(resolve, 400));
+                        image = await entry.webContentsView.webContents.capturePage();
+                    }
+                    const png = image.toPNG();
+                    if (png.length > 0)
+                        base64 = png.toString('base64');
+                }
+                catch (error) {
+                    const state = window !== undefined
+                        ? JSON.stringify({
+                            win: { visible: window.isVisible(), minimized: window.isMinimized(), focused: window.isFocused() },
+                        })
+                        : 'no-window';
+                    process.stderr.write(`[dsh-browser host] capturePage retry failed: ${String(error)} state=${state}\n`);
+                    base64 = '';
+                }
+                if (base64 === '') {
+                    // CDP fallback. Page.captureScreenshot can hang when OTHER views
+                    // (especially hidden attach-first ones) are in the window, so
+                    // temporarily detach the siblings, capture in single-view state,
+                    // then restore them (target stays on top).
+                    const siblings = [...views.values()].filter(v => v !== entry);
+                    for (const v of siblings) {
+                        try {
+                            window?.contentView.removeChildView(v.webContentsView);
+                        }
+                        catch { /* already gone */ }
+                    }
+                    try {
+                        const shot = await entry.webContentsView.webContents.debugger.sendCommand('Page.captureScreenshot', {});
+                        const data = shot.data;
+                        if (typeof data === 'string' && data.length > 0)
+                            base64 = data;
+                    }
+                    finally {
+                        for (const v of siblings) {
+                            try {
+                                window?.contentView.addChildView(v.webContentsView);
+                            }
+                            catch { /* destroyed */ }
+                        }
+                        try {
+                            window?.contentView.removeChildView(entry.webContentsView);
+                            window?.contentView.addChildView(entry.webContentsView);
+                        }
+                        catch { /* closing */ }
+                    }
+                }
+                if (base64 === '') {
+                    throw new Error('capture produced no image (view not painted)');
+                }
+                reply(msg.id, { ok: true, result: { base64, width: 0, height: 0 } });
+                return;
+            }
             case 'download': {
                 const viewId = msg.viewId;
                 const url = msg.url;
@@ -137,6 +242,7 @@ async function handle(op, msg) {
             if (!r.ok) throw new Error('HTTP ' + r.status)
             const b = await r.arrayBuffer()
             const bytes = new Uint8Array(b)
+            if (bytes.length > ${String(MAX_DOWNLOAD_BYTES)}) throw new Error('download too large (limit ' + ${String(MAX_DOWNLOAD_BYTES)} + ' bytes, got ' + bytes.length + ')')
             let bin = ''
             for (let i = 0; i < bytes.length; i += 0x8000) bin += String.fromCharCode.apply(null, bytes.subarray(i, i + 0x8000))
             return btoa(bin)
@@ -162,16 +268,21 @@ async function handle(op, msg) {
                 // Export the session's cookies so login state can be saved/restored
                 // across browser hosts (or shared with another machine).
                 const cookies = await entry.webContentsView.webContents.session.cookies.get({});
-                const exported = cookies.map(c => ({
-                    url: `http${c.secure ? 's' : ''}://${c.domain.startsWith('.') ? c.domain.slice(1) : c.domain}${c.path}`,
-                    name: c.name,
-                    value: c.value,
-                    domain: c.domain,
-                    path: c.path,
-                    secure: c.secure,
-                    httpOnly: c.httpOnly,
-                    expirationDate: c.expirationDate,
-                }));
+                const exported = cookies.map(c => {
+                    const host = c.domain.startsWith('.') ? c.domain.slice(1) : c.domain;
+                    // IPv6 literal domains need brackets in a URL (e.g. http://[::1]/).
+                    const hostPart = host.includes(':') && !host.startsWith('[') ? `[${host}]` : host;
+                    return {
+                        url: `http${c.secure ? 's' : ''}://${hostPart}${c.path}`,
+                        name: c.name,
+                        value: c.value,
+                        domain: c.domain,
+                        path: c.path,
+                        secure: c.secure,
+                        httpOnly: c.httpOnly,
+                        expirationDate: c.expirationDate,
+                    };
+                });
                 reply(msg.id, { ok: true, result: { cookies: exported } });
                 return;
             }
@@ -185,6 +296,7 @@ async function handle(op, msg) {
                     throw new Error(`restoreAuth: unknown view ${viewId}`);
                 if (!Array.isArray(cookies))
                     throw new Error('restoreAuth missing cookies array');
+                let restored = 0;
                 for (const c of cookies) {
                     if (typeof c.url !== 'string' || typeof c.name !== 'string' || typeof c.value !== 'string')
                         continue;
@@ -198,8 +310,9 @@ async function handle(op, msg) {
                         ...typeof c.httpOnly === 'boolean' ? { httpOnly: c.httpOnly } : {},
                         ...typeof c.expirationDate === 'number' ? { expirationDate: c.expirationDate } : {},
                     });
+                    restored++;
                 }
-                reply(msg.id, { ok: true, result: { restored: cookies.length } });
+                reply(msg.id, { ok: true, result: { restored } });
                 return;
             }
             default:

package/lib/browser-electron/provider.d.ts

@@ -183,6 +183,8 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
         readonly dataUrl: string;
         readonly path?: string;
     }>;
+    /** Build the data URL and optionally write the PNG to disk. */
+    private saveScreenshot;
     /** Append one operation to the session's history. */
     private record;
     /** Return the session's chronological operation log (newest last). */

package/lib/browser-electron/provider.js

@@ -531,7 +531,10 @@ export class ElectronBrowserProvider {
         if (typeof downloadable.download !== 'function') {
             throw new BrowserError('browser: download is only available on the self-hosted browser', 'BROWSER_DOWNLOAD_UNSUPPORTED');
         }
-        await downloadable.download(request.url, request.savePath);
+        // The child fetches in-page with awaitPromise; a slow/hung network can
+        // block it well past the tool budget, so bound it like every other call.
+        const timeoutMs = 60_000;
+        await withTimeout(downloadable.download(request.url, request.savePath), timeoutMs, signal, `browser: download timed out after ${timeoutMs}ms`);
         this.record(s, 'download', { url: request.url, savePath: request.savePath }, true, { result: request.savePath });
         return { path: request.savePath };
     }
@@ -546,7 +549,8 @@ export class ElectronBrowserProvider {
         if (typeof host.flushAuth !== 'function') {
             throw new BrowserError('browser: auth export is only available on the self-hosted browser', 'BROWSER_AUTH_UNSUPPORTED');
         }
-        const cookies = await host.flushAuth();
+        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` });
         return cookies;
     }
@@ -558,42 +562,60 @@ export class ElectronBrowserProvider {
         if (typeof host.restoreAuth !== 'function') {
             throw new BrowserError('browser: auth restore is only available on the self-hosted browser', 'BROWSER_AUTH_UNSUPPORTED');
         }
-        const restored = await host.restoreAuth(cookies);
+        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` });
         return restored;
     }
     /** Capture the current page, optionally full-page. PNG only (CDP JPEG hangs on Electron 43). */
     async screenshot(session, request, signal) {
-        const { handle } = this.activeTab(this.session(session));
+        const s = this.session(session);
+        const { handle } = this.activeTab(s);
         signal?.throwIfAborted();
+        // Native capturePage path (self-hosted): CDP Page.captureScreenshot can
+        // hang indefinitely on a view once another (hidden) WebContentsView exists
+        // in the window; capturePage is fast for visible views and resolves
+        // immediately (empty) for hidden ones.
+        const capturable = handle;
+        if (request?.fullPage !== true && typeof capturable.capture === 'function') {
+            // Ensure the target view is the visible one before capturing.
+            this.showActive(s);
+            const timeoutMs = 30_000;
+            const shot = await withTimeout(capturable.capture(), timeoutMs, signal, `browser: screenshot timed out after ${timeoutMs}ms`);
+            if (shot.base64 === '') {
+                throw new BrowserError('browser: capture returned an empty image (view not painted); retry shortly', 'BROWSER_SCREENSHOT_FAILED');
+            }
+            return this.saveScreenshot(shot.base64, request?.savePath);
+        }
+        // Fallback: a desktop-shell handle (no capture()) or a full-page capture
+        // uses CDP; full-page needs `captureBeyondViewport` which capturePage lacks.
         const params = {};
         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;
         }
-        // Bound the capture: a view that has not painted can wedge
-        // Page.captureScreenshot indefinitely (observed after view re-showing).
         const timeoutMs = 30_000;
         const result = await withTimeout(handle.sendCommand(CDP_PAGE_CAPTURE_SCREENSHOT, params), timeoutMs, signal, `browser: screenshot timed out after ${timeoutMs}ms`);
         const data = result.data;
         if (typeof data !== 'string') {
             throw new BrowserError('browser: screenshot returned no image data', 'BROWSER_SCREENSHOT_FAILED');
         }
-        // Optional disk write so a vision tool (e.g. modlens read_image) can read
-        // the screenshot from a file path. Fire-and-forget: a write failure must
-        // not fail the capture.
-        if (request?.savePath !== undefined) {
+        return this.saveScreenshot(data, request?.savePath);
+    }
+    /** Build the data URL and optionally write the PNG to disk. */
+    saveScreenshot(base64, savePath) {
+        if (savePath !== undefined) {
             try {
-                writeFileSync(request.savePath, Buffer.from(data, 'base64'));
-                return { dataUrl: `data:image/png;base64,${data}`, path: request.savePath };
+                writeFileSync(savePath, Buffer.from(base64, 'base64'));
+                return { dataUrl: `data:image/png;base64,${base64}`, path: savePath };
             }
             catch (error) {
                 // Report the write problem but keep the capture usable.
-                throw new BrowserError(`browser: screenshot save to "${request.savePath}" failed: ${String(error)}`, 'BROWSER_SCREENSHOT_SAVE_FAILED', { cause: error });
+                throw new BrowserError(`browser: screenshot save to "${savePath}" failed: ${String(error)}`, 'BROWSER_SCREENSHOT_SAVE_FAILED', { cause: error });
             }
         }
-        return { dataUrl: `data:image/png;base64,${data}` };
+        return { dataUrl: `data:image/png;base64,${base64}` };
     }
     /** Append one operation to the session's history. */
     record(s, action, params, ok, detail) {
@@ -706,7 +728,9 @@ export class ElectronBrowserProvider {
     }
     /** Read the current URL of a view through CDP. */
     async currentUrl(handle) {
-        const result = await handleSendEvaluate(handle, 'location.href');
+        // Bound the read: a wedged renderer would otherwise hang listTabs.
+        const timeoutMs = 10_000;
+        const result = await withTimeout(handleSendEvaluate(handle, 'location.href'), timeoutMs, undefined, `browser: url read timed out after ${timeoutMs}ms`);
         return result.ok && typeof result.value === 'string' ? result.value : '';
     }
 }

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

@@ -23,13 +23,16 @@ import { createServer } from 'node:net';
 import { fileURLToPath } from 'node:url';
 /** How long to wait for the child to signal readiness before failing. */
 const READY_TIMEOUT_MS = 20_000;
+/** Safety cap on a single RPC reply line (base64 downloads are the big ones). */
+const MAX_RPC_BUFFER_BYTES = 512 * 1024 * 1024;
 /**
- * Locate the Electron binary, trying, in order:
+ * Locate the Electron binary:
  *   1. require('electron') from this module (optional peer dependency),
- *   2. require.resolve('electron') against DSH install anchors (global dsh
- *      package, npm global root) — desktop-shell environments satisfy this,
- *   3. a pnpm virtual store under common workspace layouts,
- *   4. ELECTRON_PATH (explicit override).
+ *   2. ELECTRON_PATH (explicit override),
+ *   3. every DSH install anchor + pnpm virtual store candidate, choosing the
+ *      NEWEST version found. Older Electron releases (e.g. 33.x) have a
+ *      compositor defect that intermittently breaks page capture, so prefer
+ *      the newest binary available in the environment.
  * @returns the path to the Electron executable.
  */
 function resolveElectronPath() {
@@ -43,8 +46,16 @@ function resolveElectronPath() {
     catch {
         // continue probing
     }
-    // 2. DSH install anchors: the global dsh package and the npm global root
-    // both carry electron junctions under pnpm layouts.
+    // 2. Explicit override (user intent wins).
+    const override = process.env.ELECTRON_PATH;
+    if (typeof override === 'string' && override.length > 0 && existsSync(override))
+        return override;
+    // 3. Collect every candidate (anchors + pnpm stores), then pick the newest.
+    const candidates = [];
+    const add = (version, path) => {
+        if (path !== undefined)
+            candidates.push({ version, path });
+    };
     const anchors = [];
     const globalPrefix = process.env.npm_config_prefix ?? process.env.PREFIX;
     if (globalPrefix !== undefined) {
@@ -58,21 +69,13 @@ function resolveElectronPath() {
         try {
             const resolved = require.resolve('electron', { paths: [anchor] });
             if (typeof resolved === 'string' && resolved.length > 0) {
-                // electron's index.js is not the binary; find the dist executable
-                // next to the package root.
-                const exe = electronExeBeside(resolved);
-                if (exe !== undefined)
-                    return exe;
+                add(versionOf(resolved), electronExeBeside(resolved));
             }
         }
         catch {
             // continue probing
         }
     }
-    // 3. pnpm virtual store, walking up from several candidate roots: this
-    // module (its real path may differ from where the profile resolves it when
-    // installed via a junction/link), the process CWD, and the Node executable
-    // dir (DSH CLI typically runs from the workspace root).
     const roots = new Set([
         fileURLToPath(new URL('.', import.meta.url)),
         process.cwd(),
@@ -83,9 +86,12 @@ function resolveElectronPath() {
         for (let depth = 0; depth < 8; depth++) {
             const store = join(dir, 'node_modules', '.pnpm');
             if (existsSync(store)) {
-                const exe = findElectronExe(store);
-                if (exe !== undefined)
-                    return exe;
+                for (const entry of readdirSync(store)) {
+                    if (!entry.startsWith('electron@'))
+                        continue;
+                    const exe = electronDistExe(join(store, entry, 'node_modules', 'electron'));
+                    add(entry.slice('electron@'.length), exe);
+                }
             }
             const parent = join(dir, '..');
             if (parent === dir)
@@ -93,13 +99,31 @@ function resolveElectronPath() {
             dir = parent;
         }
     }
-    // 4. Explicit override.
-    const override = process.env.ELECTRON_PATH;
-    if (typeof override === 'string' && override.length > 0 && existsSync(override))
-        return override;
+    if (candidates.length > 0) {
+        candidates.sort((a, b) => compareVersions(b.version, a.version));
+        const best = candidates[0];
+        if (best !== undefined)
+            return best.path;
+    }
     throw new Error('dsh-builtin-browser: cannot locate the Electron binary. Install electron in the host profile ' +
         '(e.g. `dsh plugin --profile web add electron`) or set ELECTRON_PATH to the electron executable.');
 }
+/** Extract an electron version like "43.4.0" from a path containing it. */
+function versionOf(path) {
+    const match = /electron@(\d+\.\d+\.\d+)/.exec(path);
+    return match?.[1] ?? '0.0.0';
+}
+/** Compare dotted numeric versions; higher wins. */
+function compareVersions(a, b) {
+    const pa = a.split('.').map(n => Number(n) || 0);
+    const pb = b.split('.').map(n => Number(n) || 0);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const d = (pa[i] ?? 0) - (pb[i] ?? 0);
+        if (d !== 0)
+            return d;
+    }
+    return 0;
+}
 /** From an electron package entry file, find the dist executable beside it. */
 function electronExeBeside(entry) {
     const candidates = [
@@ -114,6 +138,14 @@ function electronExeBeside(entry) {
     }
     return undefined;
 }
+/** From an electron package root, find its dist executable. */
+function electronDistExe(pkgRoot) {
+    for (const candidate of [join(pkgRoot, 'dist', 'electron.exe'), join(pkgRoot, 'dist', 'electron')]) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return undefined;
+}
 /** dirname without importing node:path's dirname separately. */
 function dirname(p) {
     const i = p.lastIndexOf('/');
@@ -121,23 +153,6 @@ function dirname(p) {
     const k = Math.max(i, j);
     return k < 0 ? p : p.slice(0, k);
 }
-/** Search a pnpm virtual store for an Electron dist binary. */
-function findElectronExe(store) {
-    const entries = existsSync(store) ? readdirSync(store) : [];
-    for (const entry of entries) {
-        if (!entry.startsWith('electron@'))
-            continue;
-        const candidates = [
-            join(store, entry, 'node_modules', 'electron', 'dist', 'electron.exe'),
-            join(store, entry, 'node_modules', 'electron', 'dist', 'electron'),
-        ];
-        for (const candidate of candidates) {
-            if (existsSync(candidate))
-                return candidate;
-        }
-    }
-    return undefined;
-}
 /**
  * Line-delimited JSON-RPC client over a local TCP socket. Electron's main
  * process on Windows does not receive piped stdin, so the parent listens on a
@@ -162,6 +177,7 @@ class ElectronChildClient {
         this.port = port;
         this.onExit = onExit;
         const electron = resolveElectronPath();
+        process.stderr.write(`[dsh-browser host] spawning electron: ${electron}\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.
@@ -227,6 +243,14 @@ class ElectronChildClient {
     }
     onData(chunk) {
         this.buffer += typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+        // Safety net: a pathological child (or a reply larger than expected)
+        // must not grow the parent's memory without bound. The child caps
+        // downloads at 256 MiB, so a healthy stream never approaches this.
+        if (this.buffer.length > MAX_RPC_BUFFER_BYTES) {
+            this.buffer = '';
+            this.fail(new Error(`dsh-builtin-browser: RPC reply exceeded ${MAX_RPC_BUFFER_BYTES} bytes`));
+            return;
+        }
         let nl;
         while ((nl = this.buffer.indexOf('\n')) >= 0) {
             const line = this.buffer.slice(0, nl).trim();
@@ -300,6 +324,10 @@ class RemoteView {
         const result = await this.client.call('download', { viewId: this.id, url, savePath });
         writeFileSync(savePath, Buffer.from(result.base64, 'base64'));
     }
+    /** Native capturePage snapshot of the view (PNG base64 + size). */
+    capture() {
+        return this.client.call('capture', { viewId: this.id });
+    }
     /** Export the session's cookies (login state). */
     flushAuth() {
         return this.client.call('flushAuth', { viewId: this.id }).then(r => r.cookies);
@@ -329,8 +357,22 @@ export class RemoteElectronViewHost {
     ready() {
         if (this.readyPromise !== undefined)
             return this.readyPromise;
-        this.readyPromise = this.start();
-        return this.readyPromise;
+        const started = this.start();
+        const wrapped = started.catch(error => {
+            // A failed startup must not poison the host forever: tear down whatever
+            // was half-created and let the next call retry from scratch.
+            if (this.readyPromise === wrapped) {
+                this.readyPromise = undefined;
+                this.client?.kill();
+                this.client = undefined;
+                this.server?.close();
+                this.server = undefined;
+                this.pendingSocket = undefined;
+            }
+            throw error;
+        });
+        this.readyPromise = wrapped;
+        return wrapped;
     }
     async start() {
         // Listen on an ephemeral loopback port; the child connects back.
@@ -386,6 +428,11 @@ export class RemoteElectronViewHost {
         if (client === undefined)
             throw new Error('browser host unavailable');
         await client.call('createView', { viewId: id });
+        // If the view was destroyed while the createView RPC was in flight, do
+        // not re-insert a stale entry that would resurrect a dead child view.
+        if (this.views.get(id) === undefined) {
+            throw new Error('browser: view destroyed while starting');
+        }
         const view = new RemoteView(id, client);
         this.views.set(id, view);
         return view;
@@ -426,27 +473,41 @@ class DeferredRemoteView {
         this.id = id;
         this.materialize = materialize;
     }
+    /**
+     * Materialize once and cache: every sendCommand on the same handle must
+     * target the SAME child view (re-materializing would re-run createView and
+     * duplicate the window). A FAILED materialization is reset so a later call
+     * (e.g. after the host restarted) can retry instead of being poisoned.
+     */
+    materializeOnce() {
+        if (this.materialized === undefined) {
+            const pending = this.materialize();
+            this.materialized = pending.catch(error => {
+                if (this.materialized === pending)
+                    this.materialized = undefined;
+                throw error;
+            });
+        }
+        return this.materialized;
+    }
     async sendCommand(method, params) {
-        // Materialize once and cache: every sendCommand on the same handle must
-        // target the SAME child view. Re-materializing would re-run createView
-        // (duplicate window) and drop the established view.
-        this.materialized ??= this.materialize();
-        const view = await this.materialized;
+        const view = await this.materializeOnce();
         return view.sendCommand(method, params);
     }
     async download(url, savePath) {
-        this.materialized ??= this.materialize();
-        const view = await this.materialized;
+        const view = await this.materializeOnce();
         return view.download(url, savePath);
     }
+    async capture() {
+        const view = await this.materializeOnce();
+        return view.capture();
+    }
     async flushAuth() {
-        this.materialized ??= this.materialize();
-        const view = await this.materialized;
+        const view = await this.materializeOnce();
         return view.flushAuth();
     }
     async restoreAuth(cookies) {
-        this.materialized ??= this.materialize();
-        const view = await this.materialized;
+        const view = await this.materializeOnce();
         return view.restoreAuth(cookies);
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-builtin-browser",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "description": "Shared real browser plugin for DeepSeek Harness: install-and-use — a visible native browser the human can take over, driven by the agent over CDP. DOM-level interaction (React/Vue safe), per-task session isolation, cookie persistence (browser_auth), CAPTCHA detection, batch form fill (browser_fill), authenticated download, history/replay, action restriction",
   "type": "module",
   "main": "lib/index.js",

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

@@ -17,10 +17,26 @@
 import { app, BrowserWindow, WebContentsView } from 'electron'
 import { createInterface } from 'node:readline'
 import { createConnection } from 'node:net'
+import { join } from 'node:path'
+
+// Isolate this host's profile from the DSH app's default Electron userData:
+// several Electron instances sharing Roaming\Electron fight over the GPU
+// cache/session locks, which can leave the window without a display surface
+// (capturePage then fails). A dedicated userData also persists cookies across
+// host restarts (on top of browser_auth). Must run before app is ready.
+try {
+  const base = process.env.DSH_HOME ?? app.getPath('appData')
+  app.setPath('userData', join(base, 'dsh-builtin-browser-host'))
+} catch (error) {
+  process.stderr.write(`[dsh-browser host] userData setup failed: ${String(error)}\n`)
+}
 
 /** CDP protocol version attached to every view's debugger. */
 const CDP_VERSION = '1.3'
 
+/** Download cap: the body is shipped base64 as one JSON line; bound the memory. */
+const MAX_DOWNLOAD_BYTES = 256 * 1024 * 1024
+
 /** One view: the Electron object plus its CDP-backed surface. */
 interface HostView {
   readonly webContentsView: WebContentsView
@@ -59,6 +75,9 @@ async function handle(op: string, msg: { id: number; viewId?: string; method?: s
           window.on('closed', () => { window = undefined })
         }
         const view = new WebContentsView()
+        // Attach the debugger BEFORE the view can be seen: an attach failure
+        // then leaves nothing in the window (no visible ghost view).
+        view.webContents.debugger.attach(CDP_VERSION)
         // New views start hidden: with several sessions/tabs only the shown
         // one may be visible (they stack in contentView child order).
         view.setVisible(false)
@@ -66,7 +85,6 @@ async function handle(op: string, msg: { id: number; viewId?: string; method?: s
         const [width, height] = window.getContentSize()
         view.setBounds({ x: 0, y: 0, width: width ?? 0, height: height ?? 0 })
         if (views.size === 0) view.setVisible(true)
-        view.webContents.debugger.attach(CDP_VERSION)
         views.set(viewId, { webContentsView: view })
         reply(msg.id, { ok: true })
         return
@@ -115,6 +133,73 @@ async function handle(op: string, msg: { id: number; viewId?: string; method?: s
         reply(msg.id, { ok: true, result })
         return
       }
+      case 'capture': {
+        const viewId = msg.viewId
+        if (viewId === undefined) throw new Error('capture missing viewId')
+        const entry = views.get(viewId)
+        if (entry === undefined) throw new Error(`capture: unknown view ${viewId}`)
+        // Two complementary paths, because each has a failure mode:
+        //  - capturePage: fast and reliable with several WebContentsViews in
+        //    the window, but needs a live display surface (fails when the
+        //    window is minimized/occluded/unpainted).
+        //  - CDP Page.captureScreenshot: works without a display surface, but
+        //    can hang when another hidden WebContentsView exists in the window.
+        // Try capturePage first (show/focus/restore + one retry), then CDP.
+        if (window !== undefined) {
+          try { if (!window.isVisible()) window.show() } catch { /* closing */ }
+          try { window.restore() } catch { /* not minimized */ }
+          window.focus()
+        }
+        let base64 = ''
+        try {
+          let image
+          try {
+            image = await entry.webContentsView.webContents.capturePage()
+          } catch (error) {
+            process.stderr.write(`[dsh-browser host] capturePage failed: ${String(error)}\n`)
+            await new Promise(resolve => setTimeout(resolve, 400))
+            image = await entry.webContentsView.webContents.capturePage()
+          }
+          const png = image.toPNG()
+          if (png.length > 0) base64 = png.toString('base64')
+        } catch (error) {
+          const state = window !== undefined
+            ? JSON.stringify({
+              win: { visible: window.isVisible(), minimized: window.isMinimized(), focused: window.isFocused() },
+            })
+            : 'no-window'
+          process.stderr.write(`[dsh-browser host] capturePage retry failed: ${String(error)} state=${state}\n`)
+          base64 = ''
+        }
+        if (base64 === '') {
+          // CDP fallback. Page.captureScreenshot can hang when OTHER views
+          // (especially hidden attach-first ones) are in the window, so
+          // temporarily detach the siblings, capture in single-view state,
+          // then restore them (target stays on top).
+          const siblings = [...views.values()].filter(v => v !== entry)
+          for (const v of siblings) {
+            try { window?.contentView.removeChildView(v.webContentsView) } catch { /* already gone */ }
+          }
+          try {
+            const shot = await entry.webContentsView.webContents.debugger.sendCommand('Page.captureScreenshot', {})
+            const data = (shot as { data?: unknown }).data
+            if (typeof data === 'string' && data.length > 0) base64 = data
+          } finally {
+            for (const v of siblings) {
+              try { window?.contentView.addChildView(v.webContentsView) } catch { /* destroyed */ }
+            }
+            try {
+              window?.contentView.removeChildView(entry.webContentsView)
+              window?.contentView.addChildView(entry.webContentsView)
+            } catch { /* closing */ }
+          }
+        }
+        if (base64 === '') {
+          throw new Error('capture produced no image (view not painted)')
+        }
+        reply(msg.id, { ok: true, result: { base64, width: 0, height: 0 } })
+        return
+      }
       case 'download': {
         const viewId = msg.viewId
         const url = msg.url
@@ -134,6 +219,7 @@ async function handle(op: string, msg: { id: number; viewId?: string; method?: s
             if (!r.ok) throw new Error('HTTP ' + r.status)
             const b = await r.arrayBuffer()
             const bytes = new Uint8Array(b)
+            if (bytes.length > ${String(MAX_DOWNLOAD_BYTES)}) throw new Error('download too large (limit ' + ${String(MAX_DOWNLOAD_BYTES)} + ' bytes, got ' + bytes.length + ')')
             let bin = ''
             for (let i = 0; i < bytes.length; i += 0x8000) bin += String.fromCharCode.apply(null, bytes.subarray(i, i + 0x8000))
             return btoa(bin)
@@ -157,16 +243,21 @@ async function handle(op: string, msg: { id: number; viewId?: string; method?: s
         // Export the session's cookies so login state can be saved/restored
         // across browser hosts (or shared with another machine).
         const cookies = await entry.webContentsView.webContents.session.cookies.get({})
-        const exported = cookies.map(c => ({
-          url: `http${c.secure ? 's' : ''}://${c.domain.startsWith('.') ? c.domain.slice(1) : c.domain}${c.path}`,
-          name: c.name,
-          value: c.value,
-          domain: c.domain,
-          path: c.path,
-          secure: c.secure,
-          httpOnly: c.httpOnly,
-          expirationDate: c.expirationDate,
-        }))
+        const exported = cookies.map(c => {
+          const host = c.domain.startsWith('.') ? c.domain.slice(1) : c.domain
+          // IPv6 literal domains need brackets in a URL (e.g. http://[::1]/).
+          const hostPart = host.includes(':') && !host.startsWith('[') ? `[${host}]` : host
+          return {
+            url: `http${c.secure ? 's' : ''}://${hostPart}${c.path}`,
+            name: c.name,
+            value: c.value,
+            domain: c.domain,
+            path: c.path,
+            secure: c.secure,
+            httpOnly: c.httpOnly,
+            expirationDate: c.expirationDate,
+          }
+        })
         reply(msg.id, { ok: true, result: { cookies: exported } })
         return
       }
@@ -177,6 +268,7 @@ async function handle(op: string, msg: { id: number; viewId?: string; method?: s
         const entry = views.get(viewId)
         if (entry === undefined) throw new Error(`restoreAuth: unknown view ${viewId}`)
         if (!Array.isArray(cookies)) throw new Error('restoreAuth missing cookies array')
+        let restored = 0
         for (const c of cookies as Array<{ url?: string; name?: string; value?: string; domain?: string; path?: string; secure?: boolean; httpOnly?: boolean; expirationDate?: number }>) {
           if (typeof c.url !== 'string' || typeof c.name !== 'string' || typeof c.value !== 'string') continue
           await entry.webContentsView.webContents.session.cookies.set({
@@ -189,8 +281,9 @@ async function handle(op: string, msg: { id: number; viewId?: string; method?: s
             ...typeof c.httpOnly === 'boolean' ? { httpOnly: c.httpOnly } : {},
             ...typeof c.expirationDate === 'number' ? { expirationDate: c.expirationDate } : {},
           })
+          restored++
         }
-        reply(msg.id, { ok: true, result: { restored: (cookies as unknown[]).length } })
+        reply(msg.id, { ok: true, result: { restored } })
         return
       }
       default:

package/src/browser-electron/provider.ts

@@ -693,7 +693,15 @@ export class ElectronBrowserProvider implements BrowserProvider {
     if (typeof downloadable.download !== 'function') {
       throw new BrowserError('browser: download is only available on the self-hosted browser', 'BROWSER_DOWNLOAD_UNSUPPORTED')
     }
-    await downloadable.download(request.url, request.savePath)
+    // The child fetches in-page with awaitPromise; a slow/hung network can
+    // block it well past the tool budget, so bound it like every other call.
+    const timeoutMs = 60_000
+    await withTimeout(
+      downloadable.download(request.url, request.savePath),
+      timeoutMs,
+      signal,
+      `browser: download timed out after ${timeoutMs}ms`,
+    )
     this.record(s, 'download', { url: request.url, savePath: request.savePath }, true, { result: request.savePath })
     return { path: request.savePath }
   }
@@ -709,7 +717,8 @@ export class ElectronBrowserProvider implements BrowserProvider {
     if (typeof host.flushAuth !== 'function') {
       throw new BrowserError('browser: auth export is only available on the self-hosted browser', 'BROWSER_AUTH_UNSUPPORTED')
     }
-    const cookies = await host.flushAuth()
+    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` })
     return cookies
   }
@@ -722,7 +731,8 @@ export class ElectronBrowserProvider implements BrowserProvider {
     if (typeof host.restoreAuth !== 'function') {
       throw new BrowserError('browser: auth restore is only available on the self-hosted browser', 'BROWSER_AUTH_UNSUPPORTED')
     }
-    const restored = await host.restoreAuth(cookies)
+    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` })
     return restored
   }
@@ -733,16 +743,37 @@ export class ElectronBrowserProvider implements BrowserProvider {
     request?: { readonly fullPage?: boolean; readonly savePath?: string },
     signal?: AbortSignal,
   ): Promise<{ readonly dataUrl: string; readonly path?: string }> {
-    const { handle } = this.activeTab(this.session(session))
+    const s = this.session(session)
+    const { handle } = this.activeTab(s)
     signal?.throwIfAborted()
+    // Native capturePage path (self-hosted): CDP Page.captureScreenshot can
+    // hang indefinitely on a view once another (hidden) WebContentsView exists
+    // in the window; capturePage is fast for visible views and resolves
+    // immediately (empty) for hidden ones.
+    const capturable = handle as { capture?(): Promise<{ base64: string; width: number; height: number }> }
+    if (request?.fullPage !== true && typeof capturable.capture === 'function') {
+      // Ensure the target view is the visible one before capturing.
+      this.showActive(s)
+      const timeoutMs = 30_000
+      const shot = await withTimeout(
+        capturable.capture(),
+        timeoutMs,
+        signal,
+        `browser: screenshot timed out after ${timeoutMs}ms`,
+      )
+      if (shot.base64 === '') {
+        throw new BrowserError('browser: capture returned an empty image (view not painted); retry shortly', 'BROWSER_SCREENSHOT_FAILED')
+      }
+      return this.saveScreenshot(shot.base64, request?.savePath)
+    }
+    // Fallback: a desktop-shell handle (no capture()) or a full-page capture
+    // uses CDP; full-page needs `captureBeyondViewport` which capturePage lacks.
     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
     }
-    // Bound the capture: a view that has not painted can wedge
-    // Page.captureScreenshot indefinitely (observed after view re-showing).
     const timeoutMs = 30_000
     const result = await withTimeout(
       handle.sendCommand(CDP_PAGE_CAPTURE_SCREENSHOT, params),
@@ -754,19 +785,21 @@ export class ElectronBrowserProvider implements BrowserProvider {
     if (typeof data !== 'string') {
       throw new BrowserError('browser: screenshot returned no image data', 'BROWSER_SCREENSHOT_FAILED')
     }
-    // Optional disk write so a vision tool (e.g. modlens read_image) can read
-    // the screenshot from a file path. Fire-and-forget: a write failure must
-    // not fail the capture.
-    if (request?.savePath !== undefined) {
+    return this.saveScreenshot(data, request?.savePath)
+  }
+
+  /** Build the data URL and optionally write the PNG to disk. */
+  private saveScreenshot(base64: string, savePath?: string): { dataUrl: string; path?: string } {
+    if (savePath !== undefined) {
       try {
-        writeFileSync(request.savePath, Buffer.from(data, 'base64'))
-        return { dataUrl: `data:image/png;base64,${data}`, path: request.savePath }
+        writeFileSync(savePath, Buffer.from(base64, 'base64'))
+        return { dataUrl: `data:image/png;base64,${base64}`, path: savePath }
       } catch (error) {
         // Report the write problem but keep the capture usable.
-        throw new BrowserError(`browser: screenshot save to "${request.savePath}" failed: ${String(error)}`, 'BROWSER_SCREENSHOT_SAVE_FAILED', { cause: error })
+        throw new BrowserError(`browser: screenshot save to "${savePath}" failed: ${String(error)}`, 'BROWSER_SCREENSHOT_SAVE_FAILED', { cause: error })
       }
     }
-    return { dataUrl: `data:image/png;base64,${data}` }
+    return { dataUrl: `data:image/png;base64,${base64}` }
   }
 
   /** Append one operation to the session's history. */
@@ -887,7 +920,14 @@ export class ElectronBrowserProvider implements BrowserProvider {
 
   /** Read the current URL of a view through CDP. */
   private async currentUrl(handle: ElectronViewHandle): Promise<string> {
-    const result = await handleSendEvaluate(handle, 'location.href')
+    // Bound the read: a wedged renderer would otherwise hang listTabs.
+    const timeoutMs = 10_000
+    const result = await withTimeout(
+      handleSendEvaluate(handle, 'location.href'),
+      timeoutMs,
+      undefined,
+      `browser: url read timed out after ${timeoutMs}ms`,
+    )
     return result.ok && typeof result.value === 'string' ? result.value : ''
   }
 }

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

@@ -28,13 +28,17 @@ import type { ExportedCookie } from '../browser/types.ts'
 /** How long to wait for the child to signal readiness before failing. */
 const READY_TIMEOUT_MS = 20_000
 
+/** Safety cap on a single RPC reply line (base64 downloads are the big ones). */
+const MAX_RPC_BUFFER_BYTES = 512 * 1024 * 1024
+
 /**
- * Locate the Electron binary, trying, in order:
+ * Locate the Electron binary:
  *   1. require('electron') from this module (optional peer dependency),
- *   2. require.resolve('electron') against DSH install anchors (global dsh
- *      package, npm global root) — desktop-shell environments satisfy this,
- *   3. a pnpm virtual store under common workspace layouts,
- *   4. ELECTRON_PATH (explicit override).
+ *   2. ELECTRON_PATH (explicit override),
+ *   3. every DSH install anchor + pnpm virtual store candidate, choosing the
+ *      NEWEST version found. Older Electron releases (e.g. 33.x) have a
+ *      compositor defect that intermittently breaks page capture, so prefer
+ *      the newest binary available in the environment.
  * @returns the path to the Electron executable.
  */
 function resolveElectronPath(): string {
@@ -46,8 +50,14 @@ function resolveElectronPath(): string {
   } catch {
     // continue probing
   }
-  // 2. DSH install anchors: the global dsh package and the npm global root
-  // both carry electron junctions under pnpm layouts.
+  // 2. Explicit override (user intent wins).
+  const override = process.env.ELECTRON_PATH
+  if (typeof override === 'string' && override.length > 0 && existsSync(override)) return override
+  // 3. Collect every candidate (anchors + pnpm stores), then pick the newest.
+  const candidates: Array<{ version: string; path: string }> = []
+  const add = (version: string, path: string | undefined): void => {
+    if (path !== undefined) candidates.push({ version, path })
+  }
   const anchors: string[] = []
   const globalPrefix = process.env.npm_config_prefix ?? process.env.PREFIX
   if (globalPrefix !== undefined) {
@@ -61,19 +71,12 @@ function resolveElectronPath(): string {
     try {
       const resolved: unknown = require.resolve('electron', { paths: [anchor] })
       if (typeof resolved === 'string' && resolved.length > 0) {
-        // electron's index.js is not the binary; find the dist executable
-        // next to the package root.
-        const exe = electronExeBeside(resolved)
-        if (exe !== undefined) return exe
+        add(versionOf(resolved), electronExeBeside(resolved))
       }
     } catch {
       // continue probing
     }
   }
-  // 3. pnpm virtual store, walking up from several candidate roots: this
-  // module (its real path may differ from where the profile resolves it when
-  // installed via a junction/link), the process CWD, and the Node executable
-  // dir (DSH CLI typically runs from the workspace root).
   const roots = new Set<string>([
     fileURLToPath(new URL('.', import.meta.url)),
     process.cwd(),
@@ -84,23 +87,45 @@ function resolveElectronPath(): string {
     for (let depth = 0; depth < 8; depth++) {
       const store = join(dir, 'node_modules', '.pnpm')
       if (existsSync(store)) {
-        const exe = findElectronExe(store)
-        if (exe !== undefined) return exe
+        for (const entry of readdirSync(store)) {
+          if (!entry.startsWith('electron@')) continue
+          const exe = electronDistExe(join(store, entry, 'node_modules', 'electron'))
+          add(entry.slice('electron@'.length), exe)
+        }
       }
       const parent = join(dir, '..')
       if (parent === dir) break
       dir = parent
     }
   }
-  // 4. Explicit override.
-  const override = process.env.ELECTRON_PATH
-  if (typeof override === 'string' && override.length > 0 && existsSync(override)) return override
+  if (candidates.length > 0) {
+    candidates.sort((a, b) => compareVersions(b.version, a.version))
+    const best = candidates[0]
+    if (best !== undefined) return best.path
+  }
   throw new Error(
     'dsh-builtin-browser: cannot locate the Electron binary. Install electron in the host profile ' +
     '(e.g. `dsh plugin --profile web add electron`) or set ELECTRON_PATH to the electron executable.',
   )
 }
 
+/** Extract an electron version like "43.4.0" from a path containing it. */
+function versionOf(path: string): string {
+  const match = /electron@(\d+\.\d+\.\d+)/.exec(path)
+  return match?.[1] ?? '0.0.0'
+}
+
+/** Compare dotted numeric versions; higher wins. */
+function compareVersions(a: string, b: string): number {
+  const pa = a.split('.').map(n => Number(n) || 0)
+  const pb = b.split('.').map(n => Number(n) || 0)
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] ?? 0) - (pb[i] ?? 0)
+    if (d !== 0) return d
+  }
+  return 0
+}
+
 /** From an electron package entry file, find the dist executable beside it. */
 function electronExeBeside(entry: string): string | undefined {
   const candidates = [
@@ -115,6 +140,14 @@ function electronExeBeside(entry: string): string | undefined {
   return undefined
 }
 
+/** From an electron package root, find its dist executable. */
+function electronDistExe(pkgRoot: string): string | undefined {
+  for (const candidate of [join(pkgRoot, 'dist', 'electron.exe'), join(pkgRoot, 'dist', 'electron')]) {
+    if (existsSync(candidate)) return candidate
+  }
+  return undefined
+}
+
 /** dirname without importing node:path's dirname separately. */
 function dirname(p: string): string {
   const i = p.lastIndexOf('/')
@@ -123,22 +156,6 @@ function dirname(p: string): string {
   return k < 0 ? p : p.slice(0, k)
 }
 
-/** Search a pnpm virtual store for an Electron dist binary. */
-function findElectronExe(store: string): string | undefined {
-  const entries = existsSync(store) ? readdirSync(store) : []
-  for (const entry of entries) {
-    if (!entry.startsWith('electron@')) continue
-    const candidates = [
-      join(store, entry, 'node_modules', 'electron', 'dist', 'electron.exe'),
-      join(store, entry, 'node_modules', 'electron', 'dist', 'electron'),
-    ]
-    for (const candidate of candidates) {
-      if (existsSync(candidate)) return candidate
-    }
-  }
-  return undefined
-}
-
 /** One RPC round-trip with the child. */
 interface Pending {
   resolve(result: unknown): void
@@ -168,6 +185,7 @@ class ElectronChildClient {
     private readonly onExit?: () => void,
   ) {
     const electron = resolveElectronPath()
+    process.stderr.write(`[dsh-browser host] spawning electron: ${electron}\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.
@@ -233,6 +251,14 @@ class ElectronChildClient {
 
   private onData(chunk: string | Buffer): void {
     this.buffer += typeof chunk === 'string' ? chunk : chunk.toString('utf8')
+    // Safety net: a pathological child (or a reply larger than expected)
+    // must not grow the parent's memory without bound. The child caps
+    // downloads at 256 MiB, so a healthy stream never approaches this.
+    if (this.buffer.length > MAX_RPC_BUFFER_BYTES) {
+      this.buffer = ''
+      this.fail(new Error(`dsh-builtin-browser: RPC reply exceeded ${MAX_RPC_BUFFER_BYTES} bytes`))
+      return
+    }
     let nl: number
     while ((nl = this.buffer.indexOf('\n')) >= 0) {
       const line = this.buffer.slice(0, nl).trim()
@@ -297,6 +323,11 @@ class RemoteView implements ElectronViewHandle {
     writeFileSync(savePath, Buffer.from(result.base64, 'base64'))
   }
 
+  /** Native capturePage snapshot of the view (PNG base64 + size). */
+  capture(): Promise<{ base64: string; width: number; height: number }> {
+    return this.client.call<{ base64: string; width: number; height: number }>('capture', { viewId: this.id })
+  }
+
   /** Export the session's cookies (login state). */
   flushAuth(): Promise<ExportedCookie[]> {
     return this.client.call<{ cookies: ExportedCookie[] }>('flushAuth', { viewId: this.id }).then(r => r.cookies)
@@ -326,8 +357,22 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
   /** Ensure the child is up and ready (lazy on first use; restarts after a crash). */
   private ready(): Promise<void> {
     if (this.readyPromise !== undefined) return this.readyPromise
-    this.readyPromise = this.start()
-    return this.readyPromise
+    const started = this.start()
+    const wrapped = started.catch(error => {
+      // A failed startup must not poison the host forever: tear down whatever
+      // was half-created and let the next call retry from scratch.
+      if (this.readyPromise === wrapped) {
+        this.readyPromise = undefined
+        this.client?.kill()
+        this.client = undefined
+        this.server?.close()
+        this.server = undefined
+        this.pendingSocket = undefined
+      }
+      throw error
+    })
+    this.readyPromise = wrapped
+    return wrapped
   }
 
   private async start(): Promise<void> {
@@ -383,6 +428,11 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
     const client = this.client
     if (client === undefined) throw new Error('browser host unavailable')
     await client.call('createView', { viewId: id })
+    // If the view was destroyed while the createView RPC was in flight, do
+    // not re-insert a stale entry that would resurrect a dead child view.
+    if (this.views.get(id) === undefined) {
+      throw new Error('browser: view destroyed while starting')
+    }
     const view = new RemoteView(id, client)
     this.views.set(id, view)
     return view
@@ -426,30 +476,45 @@ class DeferredRemoteView implements ElectronViewHandle {
     private readonly materialize: () => Promise<RemoteView>,
   ) {}
 
+  /**
+   * Materialize once and cache: every sendCommand on the same handle must
+   * target the SAME child view (re-materializing would re-run createView and
+   * duplicate the window). A FAILED materialization is reset so a later call
+   * (e.g. after the host restarted) can retry instead of being poisoned.
+   */
+  private materializeOnce(): Promise<RemoteView> {
+    if (this.materialized === undefined) {
+      const pending = this.materialize()
+      this.materialized = pending.catch(error => {
+        if (this.materialized === pending) this.materialized = undefined
+        throw error
+      })
+    }
+    return this.materialized
+  }
+
   async sendCommand(method: string, params?: Record<string, unknown>): Promise<Record<string, unknown>> {
-    // Materialize once and cache: every sendCommand on the same handle must
-    // target the SAME child view. Re-materializing would re-run createView
-    // (duplicate window) and drop the established view.
-    this.materialized ??= this.materialize()
-    const view = await this.materialized
+    const view = await this.materializeOnce()
     return view.sendCommand(method, params)
   }
 
   async download(url: string, savePath: string): Promise<void> {
-    this.materialized ??= this.materialize()
-    const view = await this.materialized
+    const view = await this.materializeOnce()
     return view.download(url, savePath)
   }
 
+  async capture(): Promise<{ base64: string; width: number; height: number }> {
+    const view = await this.materializeOnce()
+    return view.capture()
+  }
+
   async flushAuth(): Promise<ExportedCookie[]> {
-    this.materialized ??= this.materialize()
-    const view = await this.materialized
+    const view = await this.materializeOnce()
     return view.flushAuth()
   }
 
   async restoreAuth(cookies: ExportedCookie[]): Promise<number> {
-    this.materialized ??= this.materialize()
-    const view = await this.materialized
+    const view = await this.materializeOnce()
     return view.restoreAuth(cookies)
   }
 }

package/src/types/electron-shim.d.ts

@@ -41,12 +41,17 @@ declare module 'electron' {
       set(details: CookieSetter): Promise<void>
     }
   }
+  export interface NativeImage {
+    toPNG(): Buffer
+    getSize(): { width: number; height: number }
+  }
   export interface WebContents {
     readonly id: number
     readonly debugger: WebContentsDebugger
     readonly session: Session
     close(): void
     downloadURL(url: string): void
+    capturePage(): Promise<NativeImage>
   }
   export interface WebContentsView {
     readonly webContents: WebContents
@@ -62,6 +67,12 @@ declare module 'electron' {
       readonly children: WebContentsView[]
     }
     getContentSize(): [number, number]
+    isVisible(): boolean
+    isMinimized(): boolean
+    isFocused(): boolean
+    show(): void
+    restore(): void
+    focus(): void
     on(event: 'closed', listener: () => void): this
     on(event: 'resize', listener: () => void): this
     off(event: 'closed', listener: () => void): this
@@ -70,6 +81,8 @@ declare module 'electron' {
   export const app: {
     whenReady(): Promise<void>
     exit(code?: number): void
+    getPath(name: string): string
+    setPath(name: string, path: string): void
   }
   export interface BrowserWindowConstructor {
     new(options?: Record<string, unknown>): BrowserWindow