dsh-builtin-browser 0.4.1 → 0.4.5

package/src/browser-electron/desktop-bridge-host.ts

@@ -45,7 +45,9 @@ export function bridgeEndpointPath(): string {
  */
 function isGuestGone(error: unknown): boolean {
   const message = error instanceof Error ? error.message : String(error)
-  return /guest \d+ is not available|sidebar unavailable|did not create a browser guest/i.test(message)
+  // The panel path reports its own failure when the renderer never produced a page, and that is the
+  // same class as a vanished guest — worth one retry on a fresh panel — so it is listed here too.
+  return /guest \d+ is not available|sidebar unavailable|produced no page/i.test(message)
 }
 
 /**
@@ -58,16 +60,53 @@ function isGuestGone(error: unknown): boolean {
  */
 export class DesktopBridgeViewHost implements ElectronBrowserViewHost {
   private readonly connection: BridgeConnection
-  private readonly views = new Map<string, number>()
   /**
-   * Guests whose view is gone but whose page may still be open in the sidebar.
+   * One entry per view this host handed out: the conversation it serves, and the guest backing it.
    *
-   * The provider destroys its view handles before it asks for a release, so the
-   * mapping is dropped by then — keeping the guest ids here is what lets us close
-   * only our own tabs when several sessions are running (requirements §4: each
-   * session gets its own page).
+   * The conversation belongs to the ENTRY, not to this host. A single plugin process serves every
+   * conversation — DSH runs them all through one host instance — so an owner held on the host
+   * would be one conversation's id applied to all of them, and a page could still land in
+   * another's sidebar however carefully the bridge checked it.
    */
-  private readonly orphaned = new Set<number>()
+  private readonly views = new Map<string, { guest?: number; owner: string }>()
+  /**
+   * This process's identity with the bridge, for tab ownership.
+   *
+   * Every DSH session is its own plugin process, and the sidebar is one surface they all share.
+   * A session can only see its own `views` map, so before the bridge kept a ledger it adopted
+   * whichever tab it found — including one another session had opened, which is how a URL from
+   * one session appeared in another's sidebar. The id is per process, so two sessions never
+   * collide and one session's tabs are never handed to another; it is deliberately not the DSH
+   * session id, which this layer has no access to and does not need.
+   *
+   * The whole ledger rests on that premise, so it was measured rather than assumed: with two
+   * sessions running, the desktop had TWO host processes (plus one main, two renderers and a
+   * gpu/utility pair). If sessions ever shared a process, every owner check in the bridge would
+   * compare equal and the bleed would return in a new shape — so a change to how DSH spawns
+   * sessions invalidates this file, not just this comment.
+   *
+   * It is now the CONVERSATION id rather than an invented uuid, read from the plugin's ctx by the
+   * same path DSH's own desktop host uses. That matters because the shell keeps one sidebar per
+   * conversation and writes its session id onto each sidebar container (on the React fiber,
+   * measured on the running app) — so the bridge can only answer "is this sidebar mine" if it has
+   * a comparable id. With an invented uuid it never could, which is how a command came to be typed
+   * into another conversation's address bar.
+   *
+   * Falls back to a random uuid when the host cannot supply one — an older DSH, or a non-desktop
+   * composition. That is no worse than before: the bridge then knows only "this process", and it
+   * refuses to operate on a sidebar it cannot prove is its own.
+   */
+  private readonly owner: string
+  /**
+   * Guests whose view is gone but whose page may still be open in the sidebar, with the
+   * conversation each belongs to.
+   *
+   * The provider destroys its view handles before it asks for a release, so the mapping is dropped
+   * by then — keeping the guest ids here is what lets us close only our own tabs when several
+   * conversations are running (requirements §4: each session gets its own page). The owner rides
+   * along for the same reason it does in {@link views}: a release names one conversation.
+   */
+  private readonly orphaned = new Map<number, string>()
   /**
    * Registered by the provider, and deliberately never invoked on this carrier.
    *
@@ -83,8 +122,9 @@ export class DesktopBridgeViewHost implements ElectronBrowserViewHost {
   /**
    * @param endpoint - the shell's published bridge endpoint.
    */
-  private constructor(endpoint: BridgeEndpoint) {
-    this.connection = new BridgeConnection(endpoint)
+  private constructor(endpoint: BridgeEndpoint, sessionId?: string) {
+    this.owner = sessionId !== undefined && sessionId !== String.fromCharCode(39,39) ? sessionId : randomUUID()
+    this.connection = new BridgeConnection(endpoint, bridgeEndpointPath())
   }
 
   /**
@@ -95,7 +135,7 @@ export class DesktopBridgeViewHost implements ElectronBrowserViewHost {
    * caller falls back to self-hosting, which always works.
    * @returns the host, or undefined when no bridge is available.
    */
-  static async discover(): Promise<DesktopBridgeViewHost | undefined> {
+  static async discover(sessionId?: string): Promise<DesktopBridgeViewHost | undefined> {
     let endpoint: BridgeEndpoint
     try {
       const raw = JSON.parse(readFileSync(bridgeEndpointPath(), 'utf8')) as Partial<BridgeEndpoint>
@@ -107,10 +147,10 @@ export class DesktopBridgeViewHost implements ElectronBrowserViewHost {
     try {
       // A throwaway connection for discovery: the adopted host opens its own, and a
       // rejected endpoint must not leave a socket behind.
-      const probe = new BridgeConnection(endpoint)
+      const probe = new BridgeConnection(endpoint, bridgeEndpointPath())
       try {
         const answer = await probe.call({ op: 'list' }, 5_000)
-        return answer.ok === true ? new DesktopBridgeViewHost(endpoint) : undefined
+        return answer.ok === true ? new DesktopBridgeViewHost(endpoint, sessionId) : undefined
       } finally {
         probe.close()
       }
@@ -126,61 +166,58 @@ export class DesktopBridgeViewHost implements ElectronBrowserViewHost {
   }
 
   /**
-   * The guest id backing a view, materialized on first use.
+   * The guest backing a view, materialized on first use.
    *
-   * The sidebar browser is itself a multi-tab surface, so each view gets its own
-   * tab's guest: the provider's tab bookkeeping then maps onto real tabs the human
-   * can see and switch between. Two rules keep that honest:
-   *   - a cached guest is used as-is: probing it first cost a round-trip on every
-   *     command, so liveness is established by the command failing instead;
-   *   - a fresh view takes an unclaimed guest, growing the tab strip only when
-   *     every existing guest is already spoken for.
+   * The conversation that called owns exactly one sidebar page on this carrier — a human and the
+   * agent look at the same page — so every view resolves to that conversation's own guest, and the
+   * page does not multiply behind the provider's own tab bookkeeping.
+   *
+   * A cached guest is used as-is: probing it first cost a round-trip on every command, so liveness
+   * is established by the command failing instead.
    * @param viewId - the view whose guest is wanted.
-   * @param url - address to use when a sidebar browser has to be opened first.
+   * @param url - address to use when this conversation has no page yet.
    */
+
   private async guestFor(viewId: string, url?: string): Promise<number> {
-    const existing = this.views.get(viewId)
+    const entry = this.views.get(viewId)
     // No liveness check here: verifying the cached guest cost a round-trip on every
     // command. A guest that has gone away is detected by the command itself failing,
     // and `createView`'s sendCommand then discards the cache and calls back in here.
-    if (existing !== undefined) return existing
+    if (entry?.guest !== undefined) return entry.guest
 
-    // The browser tab must exist before its strip can be extended: `ensureSidebar`
-    // opens the sidebar (and, on a fresh shell, materializes the first guest).
-    const sidebar = await this.connection.call({
+    // The conversation THIS VIEW serves — read from the view, never from the process.
+    //
+    // The difference is the whole bug. This host is one instance shared by every conversation, so
+    // `this.owner` alone can only be "whichever conversation this process happens to name", and
+    // naming the wrong one is exactly how a page requested in one conversation appeared in
+    // another. The view was created for a conversation (`createView(owner)`), so that is what it
+    // asks for its page.
+    //
+    // Nothing here asks which conversation is on screen: `ensureSidebar` reaches this
+    // conversation's own panel by id through the renderer, rather than by pressing the shell's
+    // shortcut or clicking its card, both of which the shell delivers to whatever it displays.
+    const owner = entry?.owner ?? this.owner
+    const answer = await this.connection.call({
       op: 'ensureSidebar',
-      ...url !== undefined ? { url } : {},
-    })
-    if (sidebar.ok !== true) throw new Error(`dsh-builtin-browser: sidebar unavailable (${String(sidebar.error)})`)
-
-    const wanted = this.views.size + 1
-    let ids = await this.guestIds(Math.max(1, wanted))
-    const taken = new Set(this.views.values())
-    let free = ids.find(id => !taken.has(id))
-    if (free === undefined) {
-      // Every tab is already driving something: the strip has to grow.
-      ids = await this.guestIds(ids.length + 1)
-      free = ids.find(id => !taken.has(id))
+      owner,
+      ...url !== undefined && url !== '' ? { url } : {},
+    }, 30_000)
+    if (answer.ok !== true) throw new Error(`dsh-builtin-browser: sidebar unavailable (${String(answer.error)})`)
+    const id = Number(answer.id)
+    if (!Number.isFinite(id) || id <= 0) {
+      throw new Error('dsh-builtin-browser: the sidebar reported no browser page for this conversation')
     }
-    if (free === undefined) throw new Error('dsh-builtin-browser: the sidebar reported no free browser tab')
-    this.views.set(viewId, free)
-    return free
+    this.views.set(viewId, { guest: id, owner })
+    return id
   }
 
   /**
-   * Ask for at least `count` sidebar tabs and return their guest ids.
-   * @param count - minimum number of tabs.
+   * @param owner - the conversation this view serves. Recorded WITH the view: one host instance
+   *   serves every conversation, so the owner cannot live on the host.
    */
-  private async guestIds(count: number): Promise<number[]> {
-    const answer = await this.connection.call({ op: 'ensureTabs', count })
-    if (answer.ok !== true) throw new Error(`dsh-builtin-browser: could not open a sidebar tab (${String(answer.error)})`)
-    const ids = Array.isArray(answer.ids) ? answer.ids.map(Number).filter(Number.isFinite) : []
-    if (ids.length === 0) throw new Error('dsh-builtin-browser: the sidebar reported no browser tabs')
-    return ids
-  }
-
-  createView(): ElectronViewHandle {
+  createView(owner?: string): ElectronViewHandle {
     const viewId = randomUUID()
+    this.views.set(viewId, { owner: owner !== undefined && owner !== '' ? owner : this.owner })
     const navigateUrl = (method: string, params?: Record<string, unknown>): string | undefined =>
       method === 'Page.navigate' ? String((params as { url?: unknown })?.url ?? '') : undefined
     const run = async (guest: number, method: string, params?: Record<string, unknown>): Promise<Record<string, unknown>> => {
@@ -205,7 +242,10 @@ export class DesktopBridgeViewHost implements ElectronBrowserViewHost {
           // The human closed the tab: the page is gone, so take a fresh one and
           // replay the command once. This is the "closing the interface ends the
           // session" rule, now paid for only when it actually happens.
-          this.views.delete(viewId)
+          // Drop the guest but keep the entry: the conversation it serves is what the retry needs,
+          // and removing the entry would lose it back to the process-wide fallback owner.
+          const lost = this.views.get(viewId)
+          if (lost !== undefined) delete lost.guest
           guest = await this.guestFor(viewId, url)
           return await run(guest, method, params)
         }
@@ -214,41 +254,44 @@ export class DesktopBridgeViewHost implements ElectronBrowserViewHost {
   }
 
   destroyView(handle: ElectronViewHandle): void {
-    const guest = this.views.get(handle.id)
-    if (guest !== undefined) {
-      // Remember it: the page outlives our handle, and a later release must be able
-      // to name exactly the tabs this plugin opened.
-      this.orphaned.add(guest)
+    const entry = this.views.get(handle.id)
+    if (entry !== undefined) {
+      // Remember the page: it outlives our handle, and a later release must be able to name
+      // exactly the tabs this conversation's views opened. The owner comes along so a release
+      // naming one conversation does not sweep up another's.
+      if (entry.guest !== undefined) this.orphaned.set(entry.guest, entry.owner)
       this.views.delete(handle.id)
     }
   }
 
   /**
-   * Nothing to show: the sidebar is already on screen, and showing it again is
-   * the shell's business (it owns the tab strip and the visibility toggle).
+   * Bring this view's tab to the front in the sidebar.
+   *
+   * This used to be empty, on the reasoning that the sidebar is already on screen so there is
+   * nothing to show. That confused "the sidebar is visible" with "this page is the one being
+   * looked at": opening a page left it behind whatever the human had in front, which is issue
+   * #23. The other two carriers both do this — the self-hosted window re-adds the view and the
+   * system browser calls `Page.bringToFront` — so this carrier was the odd one out.
+   *
+   * Best-effort by design: the tab strip belongs to the shell's renderer, and failing to raise
+   * it must not fail the navigation that has already happened.
+   * @param handle - the view to bring forward.
    */
-  showView(): void {}
+  showView(handle: ElectronViewHandle): void {
+    // `owner` is required: the bridge refuses to bring forward a guest held by another session.
+    // It comes from the view, not the process — with several conversations live, a process-wide
+    // owner would raise the wrong conversation's tab.
+    const owner = this.views.get(handle.id)?.owner ?? this.owner
+    void this.connection.call({ op: 'showTab', viewId: Number(handle.id), owner }, 5_000).catch(() => undefined)
+  }
 
-  /** Same as {@link showView}: the page is already presented by the shell. */
-  async presentView(): Promise<void> {}
 
-  /**
-   * The shell owns window grouping, and one sidebar serves every view, so there
-   * is nothing to record here. (It must not write a placeholder guest id either:
-   * a view whose guest is not yet materialized has to stay absent from the map,
-   * or the first real command would be sent to the placeholder.)
-   */
-  groupView(): void {}
 
-  /** Focus is the shell's to manage, and there is no separate window to raise. */
-  async focus(): Promise<void> {}
 
   onUserAction(handler: (action: BrowserUserAction) => void): void {
     this.userActionHandler = handler
   }
 
-  /** The shell reports its own window lifecycle; nothing to subscribe to here. */
-  onViewClosed(): void {}
 
   /**
    * Release the sidebar's browser pages (requirements §3, `ui.closeWithSession`).
@@ -257,21 +300,38 @@ export class DesktopBridgeViewHost implements ElectronBrowserViewHost {
    * belongs to the shell and would happily keep the page (and its renderer) alive.
    * Closing the tabs is what actually ends the page — and only the page: cookies
    * live in the partition, history on disk, so both survive.
+   * @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.
    * @returns a promise that settles once the shell has been asked.
    */
-  async releasePage(): Promise<void> {
-    // Only our own tabs: the ids come from the views we handed out (and their
-    // orphans), never from "every webview currently visible". With two sessions
-    // live, releasing one must leave the other's page alone.
-    const mine = [...this.views.values(), ...this.orphaned]
-    this.views.clear()
-    this.orphaned.clear()
+  async releasePage(owner?: string): Promise<void> {
+    // Only this conversation's tabs. The host is ONE instance shared by every conversation, so a
+    // release that named none would close pages other conversations are still driving — "every
+    // webview currently visible" is precisely what must never be used here.
+    const mine: number[] = []
+    for (const [viewId, entry] of [...this.views]) {
+      if (owner !== undefined && entry.owner !== owner) continue
+      if (entry.guest !== undefined) mine.push(entry.guest)
+      this.views.delete(viewId)
+    }
+    // A view destroyed before the release still owns its page; its guest is collected here.
+    for (const [guest, holder] of [...this.orphaned]) {
+      if (owner !== undefined && holder !== owner) continue
+      mine.push(guest)
+      this.orphaned.delete(guest)
+    }
     // Nothing of ours is open: release nothing. Falling through to an unfiltered
     // release here would close tabs a human opened, or another session's page.
     if (mine.length === 0) return
     let titles: string[]
     try {
-      const answer = await this.connection.call({ op: 'list' }, 5_000)
+      // `owner` is REQUIRED here now that the bridge filters `list` by it. Without it the bridge
+      // falls back to a different owner, so the guests this session holds are filtered out of the
+      // answer, `mine.includes(...)` matches nothing, the title list comes back empty and this
+      // returns without closing anything — the page stayed open and the human had to close it by
+      // hand. Adding the ledger to the bridge without updating this call site is exactly the kind
+      // of half-change that made the ownership work take four rounds.
+      const answer = await this.connection.call({ op: 'list', owner: owner ?? this.owner }, 5_000)
       const sidebar = Array.isArray(answer.sidebar) ? answer.sidebar as Array<{ id?: unknown; title?: unknown }> : []
       titles = sidebar
         .filter(guest => mine.includes(Number(guest.id)))
@@ -284,7 +344,9 @@ export class DesktopBridgeViewHost implements ElectronBrowserViewHost {
     }
     if (titles.length === 0) return
     try {
-      await this.connection.call({ op: 'closeSidebarBrowser', titles }, 10_000)
+      // `owner` is required for the same reason as above: the bridge closes only the guests the
+      // caller holds, so an owner-less call closes nothing and the page stays open.
+      await this.connection.call({ op: 'closeSidebarBrowser', titles, owner: owner ?? this.owner }, 10_000)
     } catch {
       // Best effort: the setting expresses a preference, and a shell that cannot
       // be reached is no reason to fail the session teardown that called us.

package/src/browser-electron/entry.ts

@@ -22,8 +22,10 @@ import { join } from 'node:path'
 import { defaultHostMainPath, RemoteElectronViewHost } from './remote-host.js'
 import { DesktopBridgeViewHost } from './desktop-bridge-host.js'
 import { detectBrowser, searchSummary, SystemBrowserViewHost } from './system-browser.js'
+import { claimEphemeralProfile, ephemeralProfileName, sweepAbandonedEphemeralProfiles } from './ephemeral-profile.js'
 import { MissingSystemBrowserHost } from './missing-system-browser.js'
 import { SettingsStore } from './settings-store.js'
+import { sameOrigin } from './settings-route.js'
 
 export {
   ELECTRON_BROWSER_PROVIDER_ID,
@@ -52,7 +54,7 @@ export interface Config {
   readonly downloadDir?: string
   /** Maximum snapshot elements before truncation. Default 60. */
   readonly snapshotMaxElements?: number
-  /** Maximum content characters before truncation when no maxChars is given. Default 100_000. */
+  /** Maximum content characters before truncation when no maxChars is given. No longer read: the cap is per format (html and json 50 000, otherwise 20 000). */
   readonly contentMaxChars?: number
 }
 
@@ -65,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()
@@ -116,10 +159,27 @@ export function apply(ctx: Context & { browser: BrowserRuntime }, config: Config
       selfHosted.dispose()
       ctx.logger?.info?.(`dsh-builtin-browser: ${note}`)
     } catch (error) {
-      // Never leave the surface without a provider.
-      unregister = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(
-        new RemoteElectronViewHost(defaultHostMainPath()), providerConfig))
-      ctx.logger?.warn?.(`dsh-builtin-browser: could not adopt ${note} (${String(error)})`)
+      // Never leave the surface without a provider. The half-built host is disposed FIRST: an
+      // adopt that got as far as constructing it may already hold a socket, a listener or a child
+      // 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 */ }
+      // 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')
+      }
     }
   }
 
@@ -137,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
@@ -152,15 +212,29 @@ export function apply(ctx: Context & { browser: BrowserRuntime }, config: Config
           `the selected ${channel} is not installed — commands will explain how to fix it`)
       }
     } else {
-      const home = process.env.DSH_HOME ?? homedir()
+      // Same profile root as settings-store, history-store and desktop-bridge-host: the
+      // `?.dsh` component used to be missing HERE only, so a desktop launched from a
+      // shortcut (no DSH_HOME in the environment) put its browser profile in
+      // `C:\Users\<user>\dsh-builtin-browser-host\` while its settings and history lived in
+      // `~/.dsh/dsh-builtin-browser-host/` — two half-profiles that never met, and a
+      // settings panel whose switches appeared not to apply.
+      const home = process.env.DSH_HOME ?? join(homedir(), '.dsh')
       // Login state lives in the browser profile, so the cookies setting decides where
       // that profile goes: a stable directory keeps the user signed in across restarts
       // (the point of using their own browser), while turning persistence off gets a
       // throwaway directory that is removed when the browser is released.
       const persist = settings.get().cookies.persist
+      const profileRoot = join(home, BROWSER_PROFILE_DIR)
       const profileDir = persist
-        ? join(home, 'dsh-builtin-browser-host', `${detected.kind}-profile`)
-        : join(home, 'dsh-builtin-browser-host', `${detected.kind}-profile-ephemeral-${randomUUID()}`)
+        ? join(profileRoot, `${detected.kind}-profile`)
+        : join(profileRoot, ephemeralProfileName(detected.kind, randomUUID()))
+      if (!persist) {
+        // A process killed outright never runs its own cleanup (see ephemeral-profile.ts),
+        // so the sweep happens HERE — at the only moment that can still act on a profile
+        // whose owner is gone — and before this run claims a directory of its own.
+        sweepAbandonedEphemeralProfiles(profileRoot, detected.kind)
+        claimEphemeralProfile(profileDir)
+      }
       adopt(new SystemBrowserViewHost(detected, profileDir, [], persist ? undefined : profileDir),
         `will drive the installed ${detected.kind} (${detected.path}${persist ? '' : ', ephemeral profile'})`)
     }
@@ -168,19 +242,57 @@ 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
 
-  void DesktopBridgeViewHost.discover().then(sidebar => {
-    // No bridge (plain `dsh web`, an older desktop build, or a shell that already
-    // exited): keep self-hosting, which is what every surface has always done.
-    if (sidebar === undefined) return
-    adopt(sidebar, 'driving the desktop sidebar browser')
-  }).catch(() => { /* discovery never throws; keep self-hosting */ })
+  // 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
+  // was never adopted for the rest of the process's life. Retry a handful of times over roughly
+  // half a minute, then stop: this is a convenience, not a promise, and the session the user is
+  // already driving in the self-hosted window is not worth replacing minutes into their work.
+  // `adopt` is itself one-shot (its `upgraded` guard), so the only possible effect of a retry
+  // that lands late is adopting a bridge that showed up just after startup.
+  void (async () => {
+    for (const delay of [0, 2_000, 5_000, 15_000]) {
+      if (delay > 0) await new Promise(resolve => setTimeout(resolve, delay))
+      let sidebar: Awaited<ReturnType<typeof DesktopBridgeViewHost.discover>>
+      try {
+        sidebar = await DesktopBridgeViewHost.discover(sessionId)
+      } catch {
+        sidebar = undefined // discovery is documented not to throw; never let it stop the retries
+      }
+      if (sidebar === undefined) continue
+      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.',
+      )
+    }
+  })()
 }
 
 /** Route the settings panel reads and writes. */
 const SETTINGS_ROUTE = '/dsh-builtin-browser/settings'
 
+/**
+ * The directory under the DSH home that holds this plugin's browser profile.
+ *
+ * Named once, because every consumer of it must agree: `settingsPath()` and the history
+ * store resolve their own copy from `$DSH_HOME`, and a profile written under a different
+ * root than the settings document is a pair that silently never meets.
+ */
+const BROWSER_PROFILE_DIR = 'dsh-builtin-browser-host'
+
 /** The host web-server surface this plugin uses, described structurally. */
 interface WebServerHost {
   readonly webServer: {
@@ -222,28 +334,9 @@ function installSettingsRoute(ctx: Context, settings: SettingsStore): void {
   }
 }
 
-/**
- * Same-origin guard. Settings are machine-local configuration, so a page loaded
- * elsewhere must not be able to read or rewrite them.
- * @param request - the incoming request.
- * @returns whether the request may touch the settings document.
- */
-function sameOrigin(request: IncomingMessage): boolean {
-  const site = String(request.headers['sec-fetch-site'] ?? '').toLowerCase()
-  if (site === 'cross-site') return false
-  const origin = String(request.headers.origin ?? '').trim()
-  if (origin === 'null') return false
-  if (origin === '') return true
-  try {
-    return new URL(origin).host.toLowerCase() === String(request.headers.host ?? '').trim().toLowerCase()
-  } catch {
-    return false
-  }
-}
-
 /**
  * One settings round-trip: `GET` reads the document, `PUT`/`POST` merges a
- * partial patch into it.
+ * partial patch into it. Admission lives in `settings-route.ts` so it can be tested.
  * @param request - the incoming request.
  * @param response - the response to write.
  * @param settings - the settings document.
@@ -260,11 +353,11 @@ async function handleSettingsRequest(
     })
     response.end(JSON.stringify(body))
   }
-  if (!sameOrigin(request)) {
+  const method = request.method ?? 'GET'
+  if (!sameOrigin(request, method !== 'GET')) {
     json(403, { ok: false, error: 'cross-origin request refused' })
     return
   }
-  const method = request.method ?? 'GET'
   if (method === 'GET') {
     json(200, { ok: true, settings: settings.get(), path: settings.path() })
     return