dsh-builtin-browser 0.4.1 → 0.4.5

package/lib/browser-electron/desktop-bridge-host.js

@@ -39,7 +39,9 @@ export function bridgeEndpointPath() {
  */
 function isGuestGone(error) {
     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);
 }
 /**
  * The desktop sidebar, presented as a browser view host.
@@ -51,16 +53,53 @@ function isGuestGone(error) {
  */
 export class DesktopBridgeViewHost {
     connection;
+    /**
+     * One entry per view this host handed out: the conversation it serves, and the guest backing it.
+     *
+     * 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.
+     */
     views = new Map();
     /**
-     * Guests whose view is gone but whose page may still be open in the sidebar.
+     * 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.
      *
-     * 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).
+     * 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.
      */
-    orphaned = new Set();
+    owner;
+    /**
+     * 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.
+     */
+    orphaned = new Map();
     /**
      * Registered by the provider, and deliberately never invoked on this carrier.
      *
@@ -75,8 +114,9 @@ export class DesktopBridgeViewHost {
     /**
      * @param endpoint - the shell's published bridge endpoint.
      */
-    constructor(endpoint) {
-        this.connection = new BridgeConnection(endpoint);
+    constructor(endpoint, sessionId) {
+        this.owner = sessionId !== undefined && sessionId !== String.fromCharCode(39, 39) ? sessionId : randomUUID();
+        this.connection = new BridgeConnection(endpoint, bridgeEndpointPath());
     }
     /**
      * Find a usable desktop bridge, if this surface has one.
@@ -86,7 +126,7 @@ export class DesktopBridgeViewHost {
      * caller falls back to self-hosting, which always works.
      * @returns the host, or undefined when no bridge is available.
      */
-    static async discover() {
+    static async discover(sessionId) {
         let endpoint;
         try {
             const raw = JSON.parse(readFileSync(bridgeEndpointPath(), 'utf8'));
@@ -100,10 +140,10 @@ export class DesktopBridgeViewHost {
         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();
@@ -119,62 +159,57 @@ export class DesktopBridgeViewHost {
         return true;
     }
     /**
-     * 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.
      */
     async guestFor(viewId, url) {
-        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;
-        // 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({
+        if (entry?.guest !== undefined)
+            return entry.guest;
+        // 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.
      */
-    async guestIds(count) {
-        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() {
+    createView(owner) {
         const viewId = randomUUID();
+        this.views.set(viewId, { owner: owner !== undefined && owner !== '' ? owner : this.owner });
         const navigateUrl = (method, params) => method === 'Page.navigate' ? String(params?.url ?? '') : undefined;
         const run = async (guest, method, params) => {
             const answer = await this.connection.call({ op: 'cdp', id: guest, method, params });
@@ -201,7 +236,11 @@ export class DesktopBridgeViewHost {
                     // 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);
                 }
@@ -209,35 +248,39 @@ export class DesktopBridgeViewHost {
         };
     }
     destroyView(handle) {
-        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).
-     */
-    showView() { }
-    /** Same as {@link showView}: the page is already presented by the shell. */
-    async presentView() { }
-    /**
-     * 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.)
+     * 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.
      */
-    groupView() { }
-    /** Focus is the shell's to manage, and there is no separate window to raise. */
-    async focus() { }
+    showView(handle) {
+        // `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);
+    }
     onUserAction(handler) {
         this.userActionHandler = handler;
     }
-    /** The shell reports its own window lifecycle; nothing to subscribe to here. */
-    onViewClosed() { }
     /**
      * Release the sidebar's browser pages (requirements §3, `ui.closeWithSession`).
      *
@@ -245,22 +288,42 @@ export class DesktopBridgeViewHost {
      * 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() {
-        // 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) {
+        // 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 = [];
+        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;
         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 : [];
             titles = sidebar
                 .filter(guest => mine.includes(Number(guest.id)))
@@ -275,7 +338,9 @@ export class DesktopBridgeViewHost {
         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

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

@@ -34,7 +34,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;
 }
 export declare const Config: z<Config>;

package/lib/browser-electron/entry.js

@@ -17,8 +17,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, ElectronBrowserProvider, } from './provider.js';
 export { RemoteElectronViewHost, defaultHostMainPath } from './remote-host.js';
 /** Cordis plugin name used by loader diagnostics. */
@@ -33,8 +35,50 @@ export const Config = z.object({
     snapshotMaxElements: z.number(),
     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) {
+    try {
+        const surface = ctx;
+        if (typeof surface.get !== 'function')
+            return undefined;
+        const agents = surface.get('agents');
+        const list = typeof agents?.list === 'function' ? agents.list() : undefined;
+        if (!Array.isArray(list) || list.length === 0)
+            return undefined;
+        const first = list[0];
+        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, config) {
+    // 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();
@@ -83,9 +127,29 @@ export function apply(ctx, config) {
             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');
+            }
         }
     };
     // A browser the user explicitly asked for outranks every automatic choice: the
@@ -102,8 +166,8 @@ export function apply(ctx, 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 = 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
@@ -118,32 +182,83 @@ export function apply(ctx, config) {
             }
         }
         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'})`);
         }
     }
     // An explicit choice was already adopted above; discovering the sidebar here would
     // replace it, which is exactly what this guard prevents.
-    if (explicitChoice)
+    //
+    // `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)
+    // 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;
+            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;
-        adopt(sidebar, 'driving the desktop sidebar browser');
-    }).catch(() => { });
+        }
+        // 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';
 /**
  * Expose the settings document over the host's web server, which is how the
  * settings panel reads and writes it. A host without that service (headless /
@@ -169,31 +284,9 @@ function installSettingsRoute(ctx, settings) {
         // No web server on this surface: the settings file remains the interface.
     }
 }
-/**
- * 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) {
-    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.
@@ -206,11 +299,11 @@ async function handleSettingsRequest(request, response, settings) {
         });
         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;

package/lib/browser-electron/ephemeral-profile.d.ts

@@ -0,0 +1,37 @@
+/** Test seams; production passes neither. */
+export interface SweepOptions {
+    /** The clock, for the age check. */
+    readonly now?: number;
+    /** Liveness test for an owner pid. */
+    readonly alive?: (pid: number) => boolean;
+}
+/**
+ * The directory name an ephemeral profile for `kind` gets, before it is claimed.
+ *
+ * The sweep matches on the same shape, so the two must agree: a name built anywhere else
+ * is a directory the sweep will never find.
+ * @param kind - the detected browser product (`chrome`, `edge`, ...).
+ * @param id - a per-run unique suffix.
+ * @returns the directory NAME, not a path.
+ */
+export declare function ephemeralProfileName(kind: string, id: string): string;
+/**
+ * Mark an ephemeral profile directory as this process's, so a later run can tell whether
+ * the process that created it is still there.
+ * @param dir - the profile directory (created if it does not exist yet).
+ * @param pid - the claiming process, defaulting to this one.
+ * @param now - the claim time, defaulting to the current clock.
+ * @returns true when the marker was written.
+ */
+export declare function claimEphemeralProfile(dir: string, pid?: number, now?: number): boolean;
+/**
+ * Delete the ephemeral profiles under `root` that belong to processes which are gone.
+ *
+ * Called before a new one is claimed, because that is the only moment that can still act
+ * on a profile whose owner was killed: nothing runs when the signal lands.
+ * @param root - the plugin's profile root (`<DSH_HOME>/dsh-builtin-browser-host`).
+ * @param kind - the browser product, which selects the directory-name prefix.
+ * @param options - test seams for the clock and the liveness test.
+ * @returns the names of the directories that were removed.
+ */
+export declare function sweepAbandonedEphemeralProfiles(root: string, kind: string, options?: SweepOptions): string[];