dsh-builtin-browser 0.1.8 → 0.1.10

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

@@ -21,6 +21,9 @@ import { createConnection } from 'node:net'
 /** 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,12 +62,16 @@ 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)
         window.contentView.addChildView(view)
         const [width, height] = window.getContentSize()
         view.setBounds({ x: 0, y: 0, width: width ?? 0, height: height ?? 0 })
-        view.setVisible(true)
-        view.webContents.debugger.attach(CDP_VERSION)
+        if (views.size === 0) view.setVisible(true)
         views.set(viewId, { webContentsView: view })
         reply(msg.id, { ok: true })
         return
@@ -86,7 +93,19 @@ async function handle(op: string, msg: { id: number; viewId?: string; method?: s
         const viewId = msg.viewId
         if (viewId === undefined) throw new Error('showView missing viewId')
         const entry = views.get(viewId)
-        if (entry !== undefined) entry.webContentsView.setVisible(true)
+        if (entry !== undefined) {
+          // Hide every other view, then show and RAISE the target so the
+          // human actually sees the active tab/session (topmost child wins).
+          for (const v of views.values()) {
+            if (v === entry) continue
+            try { v.webContentsView.setVisible(false) } catch { /* destroyed */ }
+          }
+          entry.webContentsView.setVisible(true)
+          if (window !== undefined) {
+            window.contentView.removeChildView(entry.webContentsView)
+            window.contentView.addChildView(entry.webContentsView)
+          }
+        }
         reply(msg.id, { ok: true })
         return
       }
@@ -120,6 +139,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)
@@ -143,16 +163,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
       }
@@ -163,6 +188,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({
@@ -175,8 +201,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:
@@ -220,6 +247,12 @@ void app.whenReady().then(() => {
   socket.on('error', error => {
     process.stderr.write(`[dsh-browser host] socket error: ${String(error)}\n`)
   })
+  // The parent owns our lifetime: when it closes the socket (dispose) or dies
+  // without cleanup, exit so no zombie Electron window is left behind.
+  socket.on('close', () => {
+    process.stderr.write('[dsh-browser host] parent connection closed, exiting\n')
+    app.exit(0)
+  })
   // Keep the process alive until the parent closes the socket or kills us.
 })
 

package/src/browser-electron/provider.ts

@@ -39,11 +39,11 @@ const CHALLENGE_DETECT_EXPRESSION = `(() => {
   const lower = (title + '\\n' + bodyText).toLowerCase()
   const frameSrcs = [...document.querySelectorAll('iframe')].map(f => f.src || '').join(' ')
   const framesLower = frameSrcs.toLowerCase()
-  const hasCfInterstitial = /just a moment|checking your browser|attention required|cf_chl|challenge-platform/i.test(lower)
+  const hasCfInterstitial = /just a moment|checking your browser|attention required|cf_chl/i.test(lower)
     || !!document.querySelector('#challenge-running, #challenge-stage, #cf-chl-container')
   const hasHCaptcha = !!window.hcaptcha || !!document.querySelector('.h-captcha') || /hcaptcha\\.com/i.test(framesLower)
   const hasRecaptcha = !!window.grecaptcha || !!document.querySelector('.g-recaptcha') || /recaptcha\\/api|google\\.com\\/recaptcha/i.test(framesLower)
-  const hasTurnstile = !!window.turnstile || /challenges\\.cloudflare\\.com/i.test(framesLower) || /turnstile/i.test(lower)
+  const hasTurnstile = !!window.turnstile || /challenges\\.cloudflare\\.com/i.test(framesLower) || /turnstile|challenge-platform/i.test(lower)
   const verifyWording = /verify you are human|verify you are not a robot|\\u4eba\\u673a\\u9a8c\\u8bc1|\\u5b89\\u5168\\u9a8c\\u8bc1|enable javascript and cookies|\\u8bf7.*\\u9a8c\\u8bc1/i.test(lower)
   if (hasCfInterstitial) return { blocked: true, kind: 'cloudflare', reason: 'Cloudflare "Just a moment" interstitial' }
   if (hasHCaptcha) return { blocked: true, kind: 'hcaptcha', reason: 'hCaptcha verification' }
@@ -114,8 +114,10 @@ interface Session {
   readonly id: BrowserSessionId
   readonly tabs: Tab[]
   activeIndex: number
-  /** Chronological operation log (navigate/execute/click/type/screenshot). */
+  /** Chronological operation log (navigate/execute/click/type/fill/download/auth). */
   readonly history: BrowserHistoryEntry[]
+  /** Monotonic sequence counter for history entries (survives truncation). */
+  nextSeq: number
 }
 
 /** Provider config: navigation admission defaults and snapshot caps. */
@@ -207,7 +209,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
   open(): Promise<BrowserSessionId> {
     const handle = this.host.createView()
     const id = `browser:${randomUUID()}`
-    this.sessions.set(id, { id, tabs: [{ id: `tab:${randomUUID()}`, handle }], activeIndex: 0, history: [] })
+    this.sessions.set(id, { id, tabs: [{ id: `tab:${randomUUID()}`, handle }], activeIndex: 0, history: [], nextSeq: 1 })
     return Promise.resolve(id)
   }
 
@@ -302,15 +304,24 @@ export class ElectronBrowserProvider implements BrowserProvider {
         }
       }
       signal?.throwIfAborted()
-      const result = await handle.sendCommand(CDP_PAGE_NAVIGATE, { url } satisfies CdpNavigateParams)
+      // Page.navigate can hang on an unreachable/slow host; bound it like the
+      // evaluate paths so a wedged navigation surfaces as an error instead of
+      // blocking the tool call forever.
+      const timeoutMs = 30_000
+      const result = await withTimeout(
+        handle.sendCommand(CDP_PAGE_NAVIGATE, { url } satisfies CdpNavigateParams),
+        timeoutMs,
+        signal,
+        `browser: navigation timed out after ${timeoutMs}ms`,
+      )
       // Page.navigate resolves even when the navigation fails; surface the
       // failure instead of leaving a silent white screen.
       const errorText = (result as { errorText?: string }).errorText
       if (typeof errorText === 'string' && errorText !== '') {
-        this.record(s, 'navigate', { url }, false, { error: errorText })
         throw new BrowserError(`browser: navigation to "${url}" failed: ${errorText}`, 'BROWSER_NAVIGATION_FAILED')
       }
       this.record(s, 'navigate', { url }, true)
+      this.showActive(s)
     } catch (error) {
       if (!(error instanceof BrowserError && (error as { code?: string }).code === 'BROWSER_NAVIGATION_BLOCKED')) {
         this.record(s, 'navigate', { url }, false, { error: String(error) })
@@ -362,9 +373,15 @@ export class ElectronBrowserProvider implements BrowserProvider {
         return { ok: false, exception }
       }
       const value = (result.result as { value?: unknown } | undefined)?.value ?? null
-      this.record(s, 'execute', { script: request.script }, true, { result: typeof value === 'string' ? value.slice(0, 500) : JSON.stringify(value).slice(0, 500) })
+      this.record(s, 'execute', {
+        script: request.script,
+        ...request.args !== undefined && request.args.length > 0 ? { args: request.args } : {},
+      }, true, { result: typeof value === 'string' ? value.slice(0, 500) : JSON.stringify(value).slice(0, 500) })
       return { ok: true, value }
     } catch (error) {
+      if (error instanceof Error && error.name === 'TimeoutError') {
+        throw new BrowserError(`browser: execute timed out after ${request.timeoutMs ?? 30_000}ms`, 'BROWSER_EXECUTE_TIMEOUT', { cause: error })
+      }
       throw new BrowserError(`browser: execute failed: ${String(error)}`, 'BROWSER_EXECUTE_FAILED', { cause: error })
     }
   }
@@ -476,13 +493,15 @@ export class ElectronBrowserProvider implements BrowserProvider {
       return { ok: true, content: content.slice(0, ${String(maxChars)}), truncated }
     })()`
     // Honor a per-call timeout: content evaluation can hang on a heavy page,
-    // so a caller-supplied budget bounds it. AbortSignal.any merges the
-    // caller's signal with a timeout.
+    // so a caller-supplied budget bounds it. Unlike a bare signal entry check,
+    // withTimeout also interrupts a call already in flight.
     const timeoutMs = request.timeoutMs ?? 30_000
-    const timeoutSignal = AbortSignal.timeout(timeoutMs)
-    const result = signal !== undefined
-      ? await handleSendEvaluate(tab.handle, script, AbortSignal.any([signal, timeoutSignal]))
-      : await handleSendEvaluate(tab.handle, script, timeoutSignal)
+    const result = await withTimeout(
+      handleSendEvaluate(tab.handle, script),
+      timeoutMs,
+      signal,
+      `browser: content timed out after ${timeoutMs}ms`,
+    )
     if (!result.ok) throw new BrowserError(`browser: content evaluation failed: ${result.exception}`, 'BROWSER_CONTENT_FAILED')
     const value = result.value as { ok: boolean; reason?: string; content?: string; truncated?: boolean }
     if (!value.ok) throw new BrowserError(`browser: content fetch failed: ${value.reason ?? 'unknown'}`, 'BROWSER_CONTENT_FAILED')
@@ -505,7 +524,9 @@ export class ElectronBrowserProvider implements BrowserProvider {
     const { handle } = this.activeTab(s)
     signal?.throwIfAborted()
     await handle.sendCommand('Input.insertText', { text: request.text } satisfies CdpInsertTextParams)
-    this.record(s, 'type', { text: request.text.slice(0, 200) }, true)
+    // Store the full text so replay re-issues the same input; the history
+    // tool truncates long values when rendering.
+    this.record(s, 'type', { text: request.text }, true)
   }
 
   /**
@@ -565,7 +586,15 @@ export class ElectronBrowserProvider implements BrowserProvider {
         return vis.length > 0 ? vis : all
       }
       for (const spec of specs) {
-        const els = candidates(spec)
+        let els
+        try {
+          els = candidates(spec)
+        } catch (e) {
+          // A malformed selector must not abort the whole batch; report the
+          // field as failed and continue with the rest.
+          out.push({ ok: false, error: String(e), target: describe(spec) })
+          continue
+        }
         if (els.length === 0) { out.push({ ok: false, error: 'field not found', target: describe(spec) }); continue }
         const el = els[0]
         const tag = el.tagName
@@ -625,7 +654,9 @@ export class ElectronBrowserProvider implements BrowserProvider {
       let submitted = false
       if (${submitFlag}) {
         let last = null
-        for (const spec of specs) { const els = candidates(spec); if (els.length > 0) { last = els[0]; break } }
+        for (const spec of specs) {
+          try { const els = candidates(spec); if (els.length > 0) { last = els[0]; break } } catch { /* skip */ }
+        }
         const form = last && (last.form || last.closest('form'))
         if (form) { form.requestSubmit(); submitted = true }
       }
@@ -662,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 }
   }
@@ -678,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
   }
@@ -691,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
   }
@@ -710,7 +751,15 @@ export class ElectronBrowserProvider implements BrowserProvider {
       // a clip this yields the full-page image (CDP default is the viewport).
       params.captureBeyondViewport = true
     }
-    const result = await handle.sendCommand(CDP_PAGE_CAPTURE_SCREENSHOT, params)
+    // 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')
@@ -739,7 +788,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
     detail?: { result?: string; error?: string },
   ): void {
     const entry: BrowserHistoryEntry = {
-      seq: s.history.length + 1,
+      seq: s.nextSeq++,
       action,
       params,
       ok,
@@ -796,8 +845,10 @@ export class ElectronBrowserProvider implements BrowserProvider {
       case 'execute': {
         const script = entry.params.script
         if (typeof script !== 'string') throw new BrowserError(`browser: history seq ${seq} execute has no script`, 'BROWSER_HISTORY_INVALID')
-        const result = await this.execute(session, { script })
-        this.record(s, 'replay', { seq, of: entry.action, script }, result.ok, result.ok ? { result: String(result.value) } : { error: result.exception })
+        const recordedArgs = entry.params.args
+        const args = Array.isArray(recordedArgs) ? recordedArgs.filter((a): a is string => typeof a === 'string') : undefined
+        const result = await this.execute(session, { script, ...args !== undefined && args.length > 0 ? { args } : {} })
+        this.record(s, 'replay', { seq, of: entry.action, script, ...args !== undefined && args.length > 0 ? { args } : {} }, result.ok, result.ok ? { result: String(result.value) } : { error: result.exception })
         return
       }
       default:
@@ -846,7 +897,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 : ''
   }
 }
@@ -872,7 +930,12 @@ function withTimeout<T>(
     const timer = setTimeout(() => {
       if (done) return
       done = true
-      reject(new Error(message))
+      // A fired timeout must also release the abort listener; { once: true }
+      // only releases it on the next abort, which may never come.
+      if (signal !== undefined) signal.removeEventListener('abort', onAbort)
+      const error = new Error(message)
+      error.name = 'TimeoutError'
+      reject(error)
     }, ms)
     const finish = (fn: () => void): void => {
       if (done) return

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

@@ -2,9 +2,9 @@
  * Self-hosted Electron browser host (parent side): an
  * {@link ElectronBrowserViewHost} implementation that spawns the plugin's own
  * Electron child process (host-main.js) and drives it over line-delimited
- * JSON-RPC on stdio. This is what makes the plugin work on surfaces without a
- * desktop shell's electronViewHost (plain dsh web): installing the plugin is
- * enough — the browser window appears on first use.
+ * JSON-RPC on a loopback TCP socket. This is what makes the plugin work on
+ * surfaces without a desktop shell's electronViewHost (plain dsh web):
+ * installing the plugin is enough — the browser window appears on first use.
  *
  * Protocol (one JSON object per line, both directions):
  *   -> { id, op: 'createView' } | { id, op: 'destroyView', viewId } |
@@ -28,6 +28,9 @@ 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:
  *   1. require('electron') from this module (optional peer dependency),
@@ -159,10 +162,13 @@ class ElectronChildClient {
   private socket: import('node:net').Socket | undefined
   private connected = false
   private outbox: string[] = []
+  /** Set once the child has exited; further calls fail fast instead of queueing. */
+  private dead = false
 
   constructor(
     private readonly hostMainPath: string,
     private readonly port: number,
+    private readonly onExit?: () => void,
   ) {
     const electron = resolveElectronPath()
     // ELECTRON_RUN_AS_NODE (even an empty string) makes Electron run as plain
@@ -181,24 +187,45 @@ class ElectronChildClient {
       // Diagnostics only; never parse stderr as protocol.
       process.stderr.write(`[dsh-browser host] ${String(chunk)}`)
     })
+    // A failed spawn (bad/corrupt binary) emits 'error' — without a listener
+    // that would crash the whole DSH process.
+    this.child.on('error', error => {
+      process.stderr.write(`[dsh-browser host] spawn error: ${String(error)}\n`)
+      this.fail(new Error(`dsh-builtin-browser: browser host failed to start: ${String(error)}`))
+    })
     this.child.on('exit', (code, signal) => {
-      const err = new Error(`dsh-builtin-browser: browser host exited (code=${String(code)} signal=${String(signal)})`)
-      for (const pending of this.pending.values()) pending.reject(err)
-      this.pending.clear()
+      this.fail(new Error(`dsh-builtin-browser: browser host exited (code=${String(code)} signal=${String(signal)})`))
     })
   }
 
+  /** Reject everything in flight, mark the client dead, and notify the host. */
+  private fail(err: Error): void {
+    if (this.dead) return
+    this.dead = true
+    this.connected = false
+    for (const pending of this.pending.values()) pending.reject(err)
+    this.pending.clear()
+    this.outbox = []
+    this.onExit?.()
+  }
+
   /** Accept the child's connection (called by the server). */
   attach(socket: import('node:net').Socket): void {
     this.socket = socket
     this.connected = true
     socket.setEncoding('utf8')
+    // Without an 'error' listener a remote reset (ECONNRESET/EPIPE) throws an
+    // uncaught 'error' event and crashes the whole DSH process; 'close' below
+    // does the cleanup.
+    socket.on('error', error => {
+      process.stderr.write(`[dsh-browser host] socket error: ${String(error)}\n`)
+    })
     socket.on('data', chunk => this.onData(chunk))
     socket.on('close', () => {
       this.connected = false
-      const err = new Error('dsh-builtin-browser: browser host connection closed')
-      for (const pending of this.pending.values()) pending.reject(err)
-      this.pending.clear()
+      if (!this.dead) {
+        this.fail(new Error('dsh-builtin-browser: browser host connection closed'))
+      }
     })
     // Flush anything queued while disconnected.
     if (this.outbox.length > 0) {
@@ -209,6 +236,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()
@@ -232,6 +267,9 @@ class ElectronChildClient {
 
   /** Send one command and await the reply. */
   call<T = unknown>(op: string, payload: Record<string, unknown> = {}): Promise<T> {
+    if (this.dead) {
+      return Promise.reject(new Error('dsh-builtin-browser: browser host is not running'))
+    }
     const id = this.nextId++
     const line = JSON.stringify({ id, op, ...payload })
     return new Promise<T>((resolve, reject) => {
@@ -292,14 +330,29 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
   private pendingSocket: Socket | undefined
   private readonly views = new Map<string, ElectronViewHandle>()
   private readyPromise: Promise<void> | undefined
+  private disposed = false
 
   constructor(private readonly hostMainPath: string) {}
 
-  /** Ensure the child is up and ready (lazy on first use). */
+  /** 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> {
@@ -312,10 +365,15 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
       server.once('error', reject)
       server.listen(0, '127.0.0.1', () => resolve())
     })
+    // A later server error (rare on a loopback ephemeral port) must not crash
+    // the process; the client's fail path handles the actual recovery.
+    server.on('error', error => {
+      process.stderr.write(`[dsh-browser host] rpc server error: ${String(error)}\n`)
+    })
     const address = server.address()
     const port = typeof address === 'object' && address !== null ? address.port : 0
     this.server = server
-    this.client = new ElectronChildClient(this.hostMainPath, port)
+    this.client = new ElectronChildClient(this.hostMainPath, port, () => this.onChildExit())
     if (this.pendingSocket !== undefined) {
       this.client.attach(this.pendingSocket)
       this.pendingSocket = undefined
@@ -324,6 +382,18 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
     await withTimeout(this.client.call('ping'), READY_TIMEOUT_MS, 'browser host did not become ready')
   }
 
+  /** The child died: tear down so the next use starts a fresh child. */
+  private onChildExit(): void {
+    if (this.disposed) return
+    this.client = undefined
+    this.server?.close()
+    this.server = undefined
+    this.pendingSocket = undefined
+    this.readyPromise = undefined
+    // Keep the views map: handles still resolve to ids; a fresh child simply
+    // has no such views yet, and reset_session reopens clean sessions.
+  }
+
   createView(): ElectronViewHandle {
     // The seam is synchronous; the provider uses the handle immediately, so
     // commands are deferred until the child is up and the view materialized.
@@ -338,13 +408,22 @@ 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
   }
 
   showView(handle: ElectronViewHandle): void {
-    void this.ready().then(() => this.client?.call('showView', { viewId: handle.id }))
+    // Fire-and-forget by design (visibility is best-effort), but a rejected
+    // promise must not become an unhandled rejection (crash on Node >= 15).
+    void this.ready()
+      .then(() => this.client?.call('showView', { viewId: handle.id }))
+      .catch(() => { /* host unavailable */ })
   }
 
   destroyView(handle: ElectronViewHandle): void {
@@ -358,6 +437,7 @@ export class RemoteElectronViewHost implements ElectronBrowserViewHost {
 
   /** Shut the child and the RPC server down. */
   dispose(): void {
+    this.disposed = true
     this.client?.kill()
     this.client = undefined
     this.server?.close()
@@ -376,30 +456,40 @@ 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 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)
   }
 }