dsh-builtin-browser 0.4.2 → 0.4.5

package/src/browser-electron/entry.ts

@@ -67,8 +67,49 @@ export const Config: z<Config> = z.object({
   contentMaxChars: z.number(),
 })
 
+/**
+ * This process's session id, read the way DSH's own desktop host reads it.
+ *
+ * `dsh-desktop-host/lib/index.js` does `ctx.get('agents')` then `agents.list()`, and uses
+ * `agent.id` directly as a sessionId. One conversation per process, so the list holds this one.
+ *
+ * Returns undefined rather than throwing when the service is absent — an older host, or a
+ * non-desktop composition. The caller falls back to a random id, which is what the bridge used
+ * before and is safe: it only means "this process", not "this conversation".
+ *
+ * @param ctx - the plugin context.
+ * @returns the session id, or undefined when it cannot be read.
+ */
+function readSessionId(ctx: unknown): string | undefined {
+  try {
+    const surface = ctx as { get?: (name: string) => unknown }
+    if (typeof surface.get !== 'function') return undefined
+    const agents = surface.get('agents') as { list?: () => unknown } | undefined
+    const list = typeof agents?.list === 'function' ? agents.list() : undefined
+    if (!Array.isArray(list) || list.length === 0) return undefined
+    const first = list[0] as { id?: unknown } | undefined
+    return typeof first?.id === 'string' && first.id !== '' ? first.id : undefined
+  } catch {
+    return undefined
+  }
+}
+
 /** Register the Electron browser provider with `ctx.browser`. */
 export function apply(ctx: Context & { browser: BrowserRuntime }, config: Config): void {
+  // Which session is this process serving?
+  //
+  // The desktop shell keeps ONE sidebar per conversation — measured: two `[class*=_tabStrip]`
+  // containers sat in the DOM at once, each carrying its own session id on the React fiber, and
+  // the invisible one's webview was unloaded. So the bridge CAN tell which sidebar belongs to
+  // whom; what it lacked was the other half, this process's own identity. Without it, the bridge
+  // drove "whatever sidebar is on screen" and — measured on the running shell — typed into another
+  // conversation's address bar and navigated that page.
+  //
+  // The identity is available here, and DSH's own desktop host shows how
+  // (`dsh-desktop-host/lib/index.js`: `ctx.get('agents').list()`, with `agent.id` used directly as
+  // a sessionId). One conversation per process, so the list holds this one.
+  const sessionId = readSessionId(ctx)
+
   // One settings document per plugin instance: the settings panel writes it, the
   // provider reads it live, and both ends agree on the same file.
   const settings = new SettingsStore()
@@ -123,9 +164,22 @@ export function apply(ctx: Context & { browser: BrowserRuntime }, config: Config
       // process, and dropping it on the floor is how a failed upgrade becomes a leak that only
       // shows up as a stray Electron in the task manager.
       try { host.dispose?.() } catch { /* the fallback below matters more than this */ }
-      unregister = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(
-        new RemoteElectronViewHost(defaultHostMainPath()), providerConfig))
-      ctx.logger?.warn?.(`dsh-builtin-browser: could not adopt ${note} (${String(error)})`)
+      // The fallback registration gets its own guard, because THIS is the path taken when the
+      // context is already gone — and then `ctx.browser` throws `cannot get required service
+      // "browser" in inactive context`. Unguarded, that second throw escaped the async retry
+      // that calls `adopt`, became an unhandled rejection, and killed the host process with
+      // exit code 1: a failed upgrade, which should only ever cost a warning, took the whole
+      // session down instead. Observed 2026-10-05 (crash-…-host.log, phase: running).
+      try {
+        unregister = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(
+          new RemoteElectronViewHost(defaultHostMainPath()), providerConfig))
+        ctx.logger?.warn?.(`dsh-builtin-browser: could not adopt ${note} (${String(error)})`)
+      } catch (fallbackError) {
+        ctx.logger?.warn?.(
+          `dsh-builtin-browser: could not adopt ${note} (${String(error)}), and the fallback `
+          + `registration also failed (${String(fallbackError)}) — no browser provider is `
+          + 'registered for this context')
+      }
     }
   }
 
@@ -143,8 +197,8 @@ export function apply(ctx: Context & { browser: BrowserRuntime }, config: Config
   // that choice real — otherwise a user who picked Chrome would silently get the sidebar,
   // and a user who picked a browser that is not installed would never see the explanation
   // written for exactly that case, because the sidebar would quietly replace it.
-  const explicitChoice = channel !== 'bundled' && channel !== 'auto'
-  if (channel !== 'bundled') {
+  const explicitChoice: boolean = channel !== 'bundled' && channel !== 'auto' && channel !== 'sidebar'
+  if (channel !== 'bundled' && channel !== 'sidebar') {
     const detected = detectBrowser(channel)
     if (detected === undefined) {
       // `auto` promises to take whatever is available, so falling back is what it
@@ -188,7 +242,10 @@ export function apply(ctx: Context & { browser: BrowserRuntime }, config: Config
 
   // An explicit choice was already adopted above; discovering the sidebar here would
   // replace it, which is exactly what this guard prevents.
-  if (explicitChoice) return
+  //
+  // `sidebar` is explicit too, but it names the sidebar, so it is the one explicit choice that
+  // must FALL THROUGH to the discovery below instead of returning here.
+  if (explicitChoice && channel !== 'sidebar') return
 
   // The shell may not be up yet. `dsh web` starts before — or entirely without — the desktop app
   // that hosts the bridge, and a one-shot discovery meant a bridge that appeared a second later
@@ -202,7 +259,7 @@ export function apply(ctx: Context & { browser: BrowserRuntime }, config: Config
       if (delay > 0) await new Promise(resolve => setTimeout(resolve, delay))
       let sidebar: Awaited<ReturnType<typeof DesktopBridgeViewHost.discover>>
       try {
-        sidebar = await DesktopBridgeViewHost.discover()
+        sidebar = await DesktopBridgeViewHost.discover(sessionId)
       } catch {
         sidebar = undefined // discovery is documented not to throw; never let it stop the retries
       }
@@ -210,6 +267,17 @@ export function apply(ctx: Context & { browser: BrowserRuntime }, config: Config
       adopt(sidebar, 'driving the desktop sidebar browser')
       return
     }
+    // The user explicitly asked for the sidebar, so silence would leave them with a setting
+    // that did nothing and no way to tell why. This is reachable on `dsh web`, and on a desktop
+    // whose shell never published a bridge endpoint. An automatic attempt stays quiet (the
+    // self-hosted window is a fine outcome); an explicit request does not.
+    if (channel === 'sidebar') {
+      ctx.logger?.warn?.(
+        'dsh-builtin-browser: the sidebar browser was requested but no desktop bridge was found — '
+        + 'this DSH has no desktop shell, or its bridge never started. Falling back to the bundled '
+        + 'browser; set browser.channel to another value to silence this.',
+      )
+    }
   })()
 }
 

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

@@ -68,8 +68,8 @@ export class HistoryStore {
    * the common case a comparison.
    */
   private appendedSincePrune = 0
-  private readonly maxEntries: number
-  private readonly maxAgeMs: number
+  private maxEntries: number
+  private maxAgeMs: number
 
   /**
    * @param file - absolute path of the JSONL history file.
@@ -80,9 +80,24 @@ export class HistoryStore {
     limits: HistoryLimits = {},
   ) {
     this.maxEntries = limits.maxEntries ?? DEFAULT_MAX_ENTRIES
-    // The first rewrite is due once the file has grown PRUNE_SLACK past the cap.
+    this.maxAgeMs = (limits.maxAgeDays ?? DEFAULT_MAX_AGE_DAYS) * 24 * 60 * 60 * 1000
+    // The first rewrite is due once the file has grown the slack past the cap.
     this.pruneThreshold = this.maxEntries + this.slack()
+  }
+
+  /**
+   * Re-read the retention limits.
+   *
+   * They are settings, and settings change while the plugin runs — a panel that let the
+   * operator edit them while nothing read the new values made the control a lie. Entry count
+   * and age are the pair the interface presents, so they are updated together.
+   * @param limits - the current retention overrides.
+   */
+  updateLimits(limits: HistoryLimits): void {
+    this.maxEntries = limits.maxEntries ?? DEFAULT_MAX_ENTRIES
     this.maxAgeMs = (limits.maxAgeDays ?? DEFAULT_MAX_AGE_DAYS) * 24 * 60 * 60 * 1000
+    // Recomputed rather than left alone: a smaller cap means the next rewrite is sooner.
+    this.pruneThreshold = Math.max(this.pruneThreshold, this.maxEntries + this.slack())
   }
 
   /** Whether the history file exists yet (diagnostics and tests). */
@@ -163,13 +178,23 @@ export class HistoryStore {
     const cutoff = Date.now() - this.maxAgeMs
     const fresh = all.filter(page => page.at >= cutoff)
     const kept = fresh.length > this.maxEntries ? fresh.slice(fresh.length - this.maxEntries) : fresh
-    // Only rewrite when something actually fell off, and only once the excess
-    // is worth a full rewrite.
-    if (kept.length === all.length) return
+    // Every early exit has to retire the count it just spent, or the gate above stops gating.
+    // It counted appends so that the common "nothing to do" case is a comparison; leaving the
+    // counter set on the two paths that DO read the file meant it was never zero again, so
+    // every navigation paid the full parse this was written to avoid.
+    if (kept.length === all.length) {
+      this.appendedSincePrune = 0
+      return
+    }
     // Only rewrite once the file has grown PRUNE_SLACK past what we last wrote. Asking
     // "is the file over the cap?" instead was true from the first over-cap append
     // onwards, so every single navigation after that rewrote the whole file.
-    if (all.length < this.pruneThreshold) return
+    if (all.length < this.pruneThreshold) {
+      // Deliberately NOT reset here: the count is what tracks progress toward the threshold,
+      // so clearing it would postpone the rewrite indefinitely. The read is the price of
+      // staying under the threshold, and the threshold is what bounds how often that happens.
+      return
+    }
     try {
       const body = kept.map(page => `${JSON.stringify(page)}\n`).join('')
       // Atomic, like the settings document. A plain writeFileSync truncates first, and this is

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

@@ -808,6 +808,7 @@ async function handle(op: string, msg: { id: number; viewId?: string; windowId?:
         try { win.window.restore() } catch { /* not minimized */ }
         win.window.focus()
         let base64 = ''
+        let renderedSize: { width: number; height: number } | undefined
         try {
           let image
           try {
@@ -832,6 +833,9 @@ async function handle(op: string, msg: { id: number; viewId?: string; windowId?:
           if (maxW > 0 && w > maxW) { h = Math.round(h * maxW / w); w = maxW }
           if (maxH > 0 && h > maxH) { w = Math.round(w * maxH / h); h = maxH }
           if (w > 0 && h > 0 && (w !== size.width || h !== size.height)) image = image.resize({ width: w, height: h })
+          // What the caller actually receives: after the downscale, not the captured size.
+          // Recorded here because this is the last point that knows both.
+          if (w > 0 && h > 0) renderedSize = { width: w, height: h }
           const buf = wantFormat === 'jpeg' ? image.toJPEG(wantQuality) : image.toPNG()
           if (wantFormat === 'jpeg') mime = 'image/jpeg'
           if (buf.length > 0) base64 = buf.toString('base64')
@@ -876,7 +880,12 @@ async function handle(op: string, msg: { id: number; viewId?: string; windowId?:
         if (base64 === '') {
           throw new Error('capture produced no image (view not painted)')
         }
-        reply(msg.id, { ok: true, result: { base64, mime } })
+        // The measured size travels with the image. Without it the native path — which is the
+        // default self-hosted one — could never answer `browser_screenshot`'s width/height,
+        // because the seam's only channel was {base64, mime} and the provider had nothing to
+        // forward. The caller's `maxWidth`/`maxHeight` are applied here, so this is the only
+        // place that knows what came back.
+        reply(msg.id, { ok: true, result: { base64, mime, width: renderedSize?.width, height: renderedSize?.height } })
         return
       }
       case 'download': {

package/src/browser-electron/provider.ts

@@ -118,8 +118,13 @@ export interface ElectronBrowserViewHost {
    * Create a new browser view and return a handle to its webContents-like
    * surface. The host owns windowing (adding the view to the window, sizing,
    * removal); the provider owns CDP-driven behavior.
+   * @param owner - the conversation this view serves. A host shared by several conversations
+   *   needs it to keep one conversation's page out of another's; a host with one conversation per
+   *   process may ignore it. It is per VIEW and not per host on purpose: the desktop's host is a
+   *   single instance that every conversation runs through, so an owner held there would be one
+   *   conversation's id applied to all of them.
    */
-  createView(): ElectronViewHandle
+  createView(owner?: string): ElectronViewHandle
   /**
    * Destroy a view created by this host. Called on session close; idempotent
    * for an already-destroyed view.
@@ -159,6 +164,18 @@ export interface ElectronBrowserViewHost {
    * of failing only at first use.
    */
   available?(): boolean
+  /**
+   * Tell the human that a toolbar action the agent could not complete has failed.
+   *
+   * Optional. Declared rather than reached through a cast because this is what issue #16 was:
+   * the call used to be unbound, so `this` inside the host's implementation was undefined and
+   * its first statement threw — inside an async catch, which turned it into an unhandled
+   * rejection that took the whole DSH process down. A declared member is checkable; a cast is
+   * not.
+   * @param windowId - the window the action came from.
+   * @param message - what to show the human.
+   */
+  notifyUserActionError?(windowId: string, message: string): void
   /**
    * Optional: associate a view with a window group. Views grouped under the
    * same `windowId` share one window (one window per browser session); a host
@@ -194,7 +211,12 @@ export interface ElectronBrowserViewHost {
    * (settings: ui.closeWithSession) has to be asked for explicitly there.
    * @returns a promise that settles once the release was attempted.
    */
-  releasePage?(): Promise<void>
+  /**
+   * Release this carrier's browser pages for one conversation.
+   * @param owner - the conversation whose pages to close. Omit to close every conversation's,
+   *   which is only correct from a teardown that is itself global.
+   */
+  releasePage?(owner?: string): Promise<void>
   /**
    * Fold the carrier's presentation away while keeping the page alive.
    *
@@ -257,6 +279,37 @@ export interface ElectronViewHandle {
    * then behaves exactly as before.
    */
   focus?(): Promise<void>
+  /**
+   * Save a URL straight to disk, when the backing view can do that itself.
+   *
+   * Optional. Declared here rather than reached through a structural cast at the call site:
+   * a cast tells the compiler nothing, so a host that implements the interface without this
+   * method compiles and then silently does nothing.
+   * @param url - the URL to fetch.
+   * @param savePath - where to write it.
+   */
+  download?(url: string, savePath: string): Promise<void>
+  /**
+   * Export this view's cookies. Optional; see {@link download} for why it is declared.
+   * @returns the cookies, scoped to the view's own page.
+   */
+  flushAuth?(): Promise<readonly ExportedCookie[]>
+  /**
+   * Import cookies into this view. Optional.
+   * @param cookies - the cookies to write.
+   * @returns how many were accepted.
+   */
+  restoreAuth?(cookies: readonly ExportedCookie[]): Promise<number>
+  /**
+   * Capture this view natively, returning the image and its measured size.
+   *
+   * Optional. The size is part of the contract because the caller's own tool schema declares
+   * `width`/`height`; a host that can measure the image should say so here rather than leaving
+   * the provider to guess.
+   * @param opts - format, quality and downscale bounds.
+   * @returns the encoded image and the pixel size the caller will receive.
+   */
+  capture?(opts?: ScreenshotOptions): Promise<{ base64: string; mime: string; width?: number; height?: number }>
 }
 
 /** One tab inside a session: its view plus a stable id. */
@@ -655,7 +708,10 @@ export class ElectronBrowserProvider implements BrowserProvider {
    * in the window title so a human can tell which task's page is visible.
    */
   open(label?: string): Promise<BrowserSessionId> {
-    const handle = this.host.createView()
+    // The label is the calling DSH task, and it is handed to the view as its owner: a host shared
+    // by several conversations (the desktop's) keeps one conversation's page out of another's on
+    // the strength of it, so it is not decoration.
+    const handle = this.host.createView(label)
     const id = `browser:${randomUUID()}`
     // Group the session's views under its own window (one window per
     // session), carrying the label for the window title. Hosts without
@@ -2595,7 +2651,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
     // savePath admission: the shared gate — absolute, inside `downloadDir`,
     // and never an existing file. Screenshots use the very same one.
     const savePath = this.admitSavePath(request.savePath, 'download')
-    const downloadable = handle as { download?(url: string, savePath: string): Promise<void> }
+    const downloadable = handle
     if (typeof downloadable.download !== 'function') {
       throw new BrowserError('browser: download is only available on the self-hosted browser', 'BROWSER_DOWNLOAD_UNSUPPORTED')
     }
@@ -2632,7 +2688,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
     const timeoutMs = 30_000
     // The self-hosted carrier has a native path (the child reads its own session), which
     // is worth preferring: it reports exactly what the browser persisted.
-    const native = handle as { flushAuth?(): Promise<readonly ExportedCookie[]> }
+    const native = handle
     if (typeof native.flushAuth === 'function') {
       const cookies = await withTimeout(native.flushAuth(), timeoutMs, undefined, `browser: auth export timed out after ${timeoutMs}ms`)
       this.record(s, 'flushAuth', {}, true, { result: `${cookies.length} cookies` })
@@ -2684,7 +2740,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
     const s = this.session(session)
     const { handle } = this.activeTab(s)
     const timeoutMs = 30_000
-    const native = handle as { restoreAuth?(cookies: readonly ExportedCookie[]): Promise<number> }
+    const native = handle
     if (typeof native.restoreAuth === 'function') {
       const restored = await withTimeout(native.restoreAuth(cookies), timeoutMs, undefined, `browser: auth restore timed out after ${timeoutMs}ms`)
       this.record(s, 'restoreAuth', { count: cookies.length }, true, { result: `${restored} cookies` })
@@ -2723,7 +2779,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
     session: BrowserSessionId,
     request?: BrowserScreenshotRequest,
     signal?: AbortSignal,
-  ): Promise<{ readonly dataUrl: string; readonly path?: string }> {
+  ): Promise<{ readonly dataUrl: string; readonly path?: string; readonly width?: number; readonly height?: number }> {
     const s = this.session(session)
     const { handle } = this.activeTab(s)
     signal?.throwIfAborted()
@@ -2734,7 +2790,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
     // immediately (empty) for hidden ones. JPEG and downscaling are encoded
     // in the child from the NativeImage, so this path is the only one that
     // can produce JPEG (CDP JPEG hangs on Electron 43).
-    const capturable = handle as { capture?(opts?: ScreenshotOptions): Promise<{ base64: string; mime: string }> }
+    const capturable = handle
     if (request?.fullPage !== true && typeof capturable.capture === 'function') {
       // Ensure the target view is the visible one before capturing.
       this.showActive(s)
@@ -2752,7 +2808,17 @@ export class ElectronBrowserProvider implements BrowserProvider {
       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, shot.mime ?? 'image/png')
+      return this.saveScreenshot(
+        shot.base64,
+        request?.savePath,
+        shot.mime ?? 'image/png',
+        // The child measured these after applying any downscale, and they describe the image
+        // the caller receives. Without them this path — the default self-hosted one — could
+        // never answer the width/height its own tool schema declares.
+        shot.width !== undefined && shot.height !== undefined
+          ? { width: shot.width, height: shot.height }
+          : undefined,
+      )
     }
     // Fallback: a handle without a native capture() (the sidebar, or an installed Chrome
     // or Edge) uses CDP; full-page needs `captureBeyondViewport`, which capturePage lacks.
@@ -2887,8 +2953,14 @@ export class ElectronBrowserProvider implements BrowserProvider {
     const store = this.historyStore
     if (store === undefined) return
     // The settings panel can switch recording off at runtime; the static config
-    // only supplies the startup default.
-    if (this.settingsSource !== undefined && !this.settingsSource().history.enabled) return
+    // only supplies the startup default. The RETENTION limits are read here too: they were
+    // parsed and stored but never handed to the store, so editing maxEntries or maxAgeDays in
+    // the file changed nothing — the switch worked and the numbers beside it did not.
+    if (this.settingsSource !== undefined) {
+      const live = this.settingsSource().history
+      if (!live.enabled) return
+      store.updateLimits({ maxEntries: live.maxEntries, maxAgeDays: live.maxAgeDays })
+    }
     void handleSendEvaluate(handle, 'location.href + "\\u0000" + (document.title || "")')
       .then(result => {
         if (!result.ok || typeof result.value !== 'string') return
@@ -3015,7 +3087,9 @@ export class ElectronBrowserProvider implements BrowserProvider {
       // the views above; the desktop's sidebar does not, so it is asked explicitly
       // — and its cookies plus the browsing history outlive the page either way.
       if (this.settingsSource !== undefined && this.settingsSource().ui.closeWithSession) {
-        void this.host.releasePage?.().catch(() => undefined)
+        // Named, because one host serves every conversation: an unnamed release would end the
+        // pages of conversations that are still running.
+        void this.host.releasePage?.(existing.label).catch(() => undefined)
       }
     }
     return Promise.resolve()
@@ -3039,7 +3113,7 @@ export class ElectronBrowserProvider implements BrowserProvider {
 
   /** Append a fresh tab and make it active. */
   private newTab(s: Session): void {
-    const handle = this.host.createView()
+    const handle = this.host.createView(s.label)
     // Same window as the session's other tabs.
     this.host.groupView?.(handle, s.id, s.label)
     s.tabs.push({ id: `tab:${randomUUID()}`, handle })
@@ -3144,11 +3218,10 @@ export class ElectronBrowserProvider implements BrowserProvider {
     const message = `action ${action.type} failed: ${String(error)}`
     let reported = false
     try {
-      const host = this.host as { notifyUserActionError?(windowId: string, message: string): void }
-      const notify = host.notifyUserActionError
-      if (typeof notify === 'function') {
-        // Called on its owner: an unbound call here kills the host process.
-        notify.call(host, action.windowId, message)
+      const notify = this.host.notifyUserActionError?.bind(this.host)
+      if (notify !== undefined) {
+        // Bound at the call: an unbound call here kills the host process (issue #16).
+        notify(action.windowId, message)
         reported = true
       }
     } catch (notifyError) {

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

@@ -531,9 +531,11 @@ class ElectronChildClient {
   /**
    * Drop the escalation kill once there is nothing left for it to target.
    *
-   * Without this the timer would keep the parent's event loop alive for its full grace period
-   * after exactly the ordinary exit it was armed to catch as the bad case — and the child does
-   * not need killing once `fail()` has run for it.
+   * Called on the paths where the child is known to be gone — after an observed exit, and on
+   * release. It is deliberately NOT called from `fail()`: a dead socket says nothing about the
+   * process on the other end, and the timer exists for exactly the case where the child ignores
+   * the socket closing. Clearing it there disarmed the only escalation there was, which is how
+   * a child that ignored its socket could outlive dispose() and keep holding the profile.
    */
   private clearKillGrace(): void {
     if (this.killGraceTimer === undefined) return
@@ -558,7 +560,11 @@ class ElectronChildClient {
     // kept a live timer until it fired (harmless, but it is a dangling timer in a process
     // that may be shutting down).
     this.clearHelloTimer()
-    this.clearKillGrace()
+    // NOT clearKillGrace(): this path runs when the SOCKET died, which says nothing about
+    // whether the process did. Clearing the escalation here disarmed it for exactly the case it
+    // exists for — a child that ignores its socket closing — so dispose() could return with the
+    // child still running and still holding the profile. The timer clears itself when the child
+    // exits, and `kill()` replaces it on an explicit release.
     // Tag every failure as "host gone" so the view layer can tell a dead host
     // apart from a page-level error and rebuild against a fresh child.
     const wrapped = err instanceof HostGoneError ? err : new HostGoneError(err.message)
@@ -1297,10 +1303,17 @@ class DeferredRemoteView implements ElectronViewHandle {
   private materializeOnce(): Promise<RemoteView> {
     if (this.materialized === undefined) {
       const pending = this.materialize()
-      this.materialized = pending.catch(error => {
-        if (this.materialized === pending) this.materialized = undefined
+      // Compare against the promise actually stored — the derived one — not against `pending`.
+      // Storing `pending.catch(...)` and comparing `this.materialized === pending` compared two
+      // different objects, so the test was never true and the reset never ran: a materialization
+      // that failed with anything other than a HostGoneError (the child alive but not answering
+      // a ping, say) poisoned the handle for good, and the retry the comment below promises was
+      // unreachable.
+      const guarded = pending.catch(error => {
+        if (this.materialized === guarded) this.materialized = undefined
         throw error
       })
+      this.materialized = guarded
     }
     return this.materialized
   }

package/src/browser-electron/rpc-ops.ts

@@ -0,0 +1,41 @@
+/**
+ * The RPC operation vocabulary, in one place.
+ *
+ * The child (`host-main.ts`) switches on these names and the parent (`remote-host.ts`) sends
+ * them. Both spelled them out independently and nothing connected the two, so a rename on one
+ * side compiled fine and failed at run time as "unknown op" — and this pair has already
+ * produced one silent failure of that shape (`noteStartFailure`'s dedupe comparison, which was
+ * never true and meant a log line that never appeared).
+ *
+ * The lists are the source of truth for a test that reads both switch statements and asserts
+ * they agree, which is what makes a one-sided rename fail loudly instead of at run time.
+ */
+
+/** Operations the parent asks the child to perform. */
+export const RPC_OPS = [
+  'ping',
+  'createView',
+  'destroyView',
+  'showView',
+  'groupView',
+  'focus',
+  'command',
+  'capture',
+  'download',
+  'flushAuth',
+  'restoreAuth',
+  'navigate',
+  'new-tab',
+  'activate',
+  'close',
+  'back',
+  'forward',
+  'reload',
+  'userActionError',
+] as const
+
+/** Notifications the child sends the parent, which carry no reply. */
+export const RPC_NOTIFICATIONS = ['userAction', 'viewClosed'] as const
+
+/** One operation name. */
+export type RpcOp = (typeof RPC_OPS)[number]

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

@@ -9,17 +9,34 @@
  * It is NOT authentication, and cannot be. The plugin has no credential to check: DSH hands
  * plugin routes the raw request (`packages/host/webserver/src/index.ts` registers handlers with
  * no gate of its own), so the strongest same-origin evidence available is what a browser
- * reliably sends — `Sec-Fetch-Site`, plus `Origin` on every write, same-origin included.
+ * reliably sends.
  *
  * What that buys and what it does not:
- *   - a plain HTTP client (curl, a script, another process) cannot WRITE any more, because it
- *     sends no `Origin`;
- *   - a page of THIS origin still can, because a browser sending a same-origin write looks
- *     exactly like the panel. That is inherent to exposing an HTTP endpoint at all, and it is
- *     why the settings panel's own text must not promise a lock that does not exist.
+ *   - a plain HTTP client (curl, a script, another process) cannot WRITE, because it sends no
+ *     `user-agent` and no `accept-language`;
+ *   - a page of THIS origin can, because a browser sending a same-origin write looks exactly
+ *     like the panel. That is inherent to exposing an HTTP endpoint at all, and it is why the
+ *     settings panel's own text must not promise a lock that does not exist.
  */
 import type { IncomingMessage } from 'node:http'
 
+/** The shell's own URL schemes. Only the shell can mint a document on one of these. */
+const APP_SCHEMES = ['dsh-app:', 'dsh-desktop:']
+
+/**
+ * The scheme of a header value, when it names a URL.
+ * @param value - a raw header value.
+ * @returns the scheme, or undefined when the value is absent, opaque or unparseable.
+ */
+function schemeOf(value: string): string | undefined {
+  if (value === '' || value === 'null') return undefined
+  try {
+    return new URL(value).protocol
+  } catch {
+    return undefined
+  }
+}
+
 /**
  * Whether a request may touch the settings document.
  * @param request - the incoming request.
@@ -27,19 +44,43 @@ import type { IncomingMessage } from 'node:http'
  * @returns whether the request is admitted.
  */
 export function sameOrigin(request: IncomingMessage, writing = false): boolean {
+  const origin = String(request.headers.origin ?? '').trim()
   const site = String(request.headers['sec-fetch-site'] ?? '').toLowerCase()
+
+  // A shell URL, in either the Origin or the referrer: the strongest evidence there is.
+  if (APP_SCHEMES.includes(schemeOf(origin) ?? '')) return true
+  if (APP_SCHEMES.includes(schemeOf(String(request.headers.referer ?? '')) ?? '')) return true
+
+  // MEASURED on the running desktop, and what three earlier attempts each guessed wrong: a
+  // request from the shell's own settings panel carries NO origin, NO sec-fetch-site and NO
+  // referer. It is not "dsh-app://app" and it is not "null" — the headers are simply absent,
+  // because Chromium attaches no cross-origin metadata to a request leaving a custom scheme.
+  //
+  // So the rule for that shape cannot be "a request without an Origin is a script", which is
+  // what refused every desktop save, and it cannot lean on `Sec-Fetch-Site` either. It has to
+  // test what a hand-rolled client does not send:
+  //   - a renderer sends a full Mozilla-compatible `user-agent` AND an `accept-language`;
+  //   - curl sends neither unless told to, and a local process that forges both can also read
+  //     the settings document directly — it sits readable on disk, as the panel's own text
+  //     says. This was never the boundary it looked like.
+  if (origin === '') {
+    const agent = String(request.headers['user-agent'] ?? '')
+    const language = String(request.headers['accept-language'] ?? '')
+    if (/^Mozilla\/5\.0/.test(agent) && language !== '') return true
+    // Reads stay open: they return the document the panel is already showing, and refusing them
+    // would only break hand-inspection of a file that sits readable on disk anyway.
+    return !writing
+  }
+
   // `cross-site` is another origin entirely; `same-site` is another origin of the same site
   // (a.example.com -> b.example.com), which is not this panel either. Both are refused.
   if (site === 'cross-site' || site === 'same-site') return false
-  const origin = String(request.headers.origin ?? '').trim()
-  // `Origin: null` is what a sandboxed or opaque-origin document sends. Never this panel.
+  // `Origin: null` is a sandboxed or opaque-origin document. Never this panel.
   if (origin === 'null') return false
-  // Reads are let through without an Origin: they return the document the panel is already
-  // showing, and refusing them would only break hand-inspection of a file that sits readable
-  // on disk anyway. Writes are not: a browser always sends `Origin` on one.
-  if (origin === '') return !writing
   try {
-    return new URL(origin).host.toLowerCase() === String(request.headers.host ?? '').trim().toLowerCase()
+    const parsed = new URL(origin)
+    // The host comparison is for http(s), where a page and its route share one host.
+    return parsed.host.toLowerCase() === String(request.headers.host ?? '').trim().toLowerCase()
   } catch {
     return false
   }