dsh-builtin-browser 0.4.6 → 0.4.8

package/lib/browser-electron/entry.js

@@ -5,7 +5,7 @@
  * `ctx.electronViewHost`, that host is used (embedded, human-machine shared
  * view). Otherwise the plugin self-hosts: it spawns its own Electron child
  * (`host-main.js`) and drives it over a local TCP JSON-RPC socket, so
- * installing the plugin is enough for `browser_*` tools to work on any
+ * installing the plugin is enough for `dsh_browser_*` tools to work on any
  * surface.
  * @module dsh-browser/browser-electron
  */
@@ -81,9 +81,10 @@ export function apply(ctx, config) {
     // 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();
-    installSettingsRoute(ctx, settings);
+    // provider reads it live, and both ends agree on the same file. The logger is passed so a
+    // discarded value (a mistyped channel, most of all) is reported instead of being silently
+    // replaced by the default — "my setting did nothing" and "I misspelled it" must not look alike.
+    const settings = new SettingsStore(undefined, message => ctx.logger?.warn?.(message));
     const providerConfig = {
         httpOnly: config.httpOnly,
         downloadDir: config.downloadDir,
@@ -96,6 +97,15 @@ export function apply(ctx, config) {
     if (config.viewHost !== undefined) {
         const external = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(config.viewHost, providerConfig));
         ctx.effect(() => () => { external(); });
+        // The composition supplied the carrier, so `browser.channel` is not ours to honour on this
+        // surface. Saying so is the difference between a setting that cannot apply and a setting that
+        // appears not to have worked — the second is what sends people looking for a bug elsewhere.
+        const asked = settings.get().browser.channel;
+        if (asked !== 'sidebar' && asked !== 'bundled') {
+            ctx.logger?.warn?.(`dsh-builtin-browser: browser.channel is "${asked}", but this surface's carrier was `
+                + 'supplied by its composition (the desktop shell), which outranks the setting. Set it to '
+                + '"sidebar" to record the intent, or run on a surface that picks its own carrier.');
+        }
         return;
     }
     // Otherwise start self-hosted — a working browser from the first call, on every
@@ -106,26 +116,69 @@ export function apply(ctx, config) {
     const selfHosted = new RemoteElectronViewHost(defaultHostMainPath());
     let unregister = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(selfHosted, providerConfig));
     let upgraded = false;
+    /** The carrier an `adopt` installed, so a later choice can release it. */
+    let adoptedCarrier;
     ctx.effect(() => () => {
         unregister();
         selfHosted.dispose();
     });
+    /**
+     * Put the self-hosted browser back after an adopted carrier reports that it is gone.
+     *
+     * This is the half the startup retries never covered: a bridge that was alive at apply time and
+     * exited later left every subsequent call dialling a port nobody owns, because the swap happened
+     * once and only in one direction. Reaching here means the shell is gone, so the choice made at
+     * startup is no longer a choice — the alternative to falling back is a browser surface that does
+     * nothing until DSH is restarted.
+     * @param adopted - the carrier that reported the loss, disposed once its replacement is in place.
+     */
+    const restoreSelfHosted = (adopted) => {
+        try {
+            const restored = new RemoteElectronViewHost(defaultHostMainPath());
+            unregister();
+            unregister = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(restored, providerConfig));
+            ctx.logger?.warn?.('dsh-builtin-browser: the desktop shell backed the sidebar browser and has exited, so the '
+                + 'browser this plugin hosts itself takes over. Pages from the sidebar are gone with it; '
+                + 'open the page again.');
+        }
+        catch (error) {
+            // Nothing better is available: the adopted carrier is gone and a provider that throws is
+            // worse than one that explains.
+            ctx.logger?.warn?.(`dsh-builtin-browser: could not fall back to the self-hosted browser: ${String(error)}`);
+        }
+        finally {
+            adopted.dispose?.();
+        }
+    };
     /**
      * Swap the provider to another carrier, releasing the previous one.
      * @param host - the carrier to adopt.
      * @param note - a one-line description for the log.
      */
     const adopt = (host, note) => {
-        if (upgraded) {
-            host.dispose?.();
-            return;
-        }
+        // This guard used to make the FIRST choice final, disposing anything that arrived later. That
+        // is right against two carriers racing in, and exactly wrong for a user changing the setting:
+        // `chooseCarrier` runs again on purpose, and a refusal here is indistinguishable from the
+        // write having done nothing. The previous carrier is now released by the replacement instead.
         upgraded = true;
         try {
             unregister();
             unregister = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(host, providerConfig));
             selfHosted.dispose();
             ctx.logger?.info?.(`dsh-builtin-browser: ${note}`);
+            // A borrowed carrier can lose the process behind it, and this is the only notification that
+            // will ever arrive. Registering AFTER the swap succeeded means a listener can never fire
+            // against a provider that was never installed.
+            host.onLost?.(() => { restoreSelfHosted(host); });
+            const previous = adoptedCarrier;
+            adoptedCarrier = host;
+            // Released AFTER the replacement is installed, so the surface is never without a provider.
+            if (previous !== undefined && previous !== host) {
+                try {
+                    previous.dispose?.();
+                }
+                catch { /* the replacement is already serving */ }
+            }
         }
         catch (error) {
             // Never leave the surface without a provider. The half-built host is disposed FIRST: an
@@ -153,103 +206,119 @@ export function apply(ctx, config) {
             }
         }
     };
-    // A browser the user explicitly asked for outranks every automatic choice: the
-    // whole point of the setting is that they know which browser they want. It is
-    // launched with a plugin-owned profile, so their own windows are untouched.
-    //
-    // Registration is INERT: constructing the host starts nothing. The browser only
-    // launches when a command actually needs a page, so merely running DSH never
-    // spawns a browser window. (An earlier version launched it here, which meant a
-    // browser appeared the moment the plugin loaded — reported and fixed.)
-    const channel = settings.get().browser.channel;
-    // Naming a browser is a decision about which one to use, so it also decides whether the
-    // desktop sidebar may take over. Skipping discovery for an explicit choice is what makes
-    // 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' && 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
-            // asked for. Naming a browser is a specific request, and quietly satisfying it
-            // with a different one turns the real problem ("no Chrome here") into a
-            // confusing error about Electron later on. Report it instead.
-            if (channel === 'auto') {
-                ctx.logger?.warn?.('dsh-builtin-browser: no installed browser was found; using the bundled browser');
+    /**
+     * Choose and install the carrier that `browser.channel` names RIGHT NOW.
+     *
+     * A function rather than straight-line code because the setting is read live everywhere else:
+     * the settings route writes the file and the provider picks the change up on its next call, so a
+     * channel that could only be honoured at apply time was the one setting whose write silently did
+     * nothing. Re-entrant by design — changing the channel means replacing the carrier, which is
+     * exactly what a second call does.
+     */
+    const chooseCarrier = () => {
+        // A browser the user explicitly asked for outranks every automatic choice: the
+        // whole point of the setting is that they know which browser they want. It is
+        // launched with a plugin-owned profile, so their own windows are untouched.
+        //
+        // Registration is INERT: constructing the host starts nothing. The browser only
+        // launches when a command actually needs a page, so merely running DSH never
+        // spawns a browser window. (An earlier version launched it here, which meant a
+        // browser appeared the moment the plugin loaded — reported and fixed.)
+        const channel = settings.get().browser.channel;
+        // Naming a browser is a decision about which one to use, so it also decides whether the
+        // desktop sidebar may take over. Skipping discovery for an explicit choice is what makes
+        // 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' && 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
+                // asked for. Naming a browser is a specific request, and quietly satisfying it
+                // with a different one turns the real problem ("no Chrome here") into a
+                // confusing error about Electron later on. Report it instead.
+                if (channel === 'auto') {
+                    ctx.logger?.warn?.('dsh-builtin-browser: no installed browser was found; using the bundled browser');
+                }
+                else {
+                    adopt(new MissingSystemBrowserHost(channel, searchSummary(channel)), `the selected ${channel} is not installed — commands will explain how to fix it`);
+                }
             }
             else {
-                adopt(new MissingSystemBrowserHost(channel, searchSummary(channel)), `the selected ${channel} is not installed — commands will explain how to fix it`);
-            }
-        }
-        else {
-            // 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);
-            adoptLegacyProfileRoot(profileRoot);
-            const profileDir = persist
-                ? 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);
+                // 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);
+                adoptLegacyProfileRoot(profileRoot);
+                const profileDir = persist
+                    ? 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'})`);
             }
-            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.
-    //
-    // `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
-    // 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);
+        // An explicit choice was already adopted above; discovering the sidebar here would
+        // replace it, which is exactly what this guard prevents.
+        //
+        // `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
+        // 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;
             }
-            catch {
-                sidebar = undefined; // discovery is documented not to throw; never let it stop the retries
+            // 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.');
             }
-            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.');
-        }
-    })();
+        })();
+    };
+    chooseCarrier();
+    // Wired AFTER the chooser exists, because the handler re-runs it: a settings write that changes
+    // `browser.channel` is a request to switch carriers, and answering `ok` without switching is the
+    // one thing a caller cannot tell apart from a write that worked.
+    installSettingsRoute(ctx, settings, () => { chooseCarrier(); });
 }
 /** Route the settings panel reads and writes. */
 const SETTINGS_ROUTE = '/dsh-builtin-browser/settings';
@@ -303,7 +372,7 @@ export function adoptLegacyProfileRoot(profileRoot, legacyRoot = join(homedir(),
  * @param ctx - the plugin context.
  * @param settings - the settings document to expose.
  */
-function installSettingsRoute(ctx, settings) {
+function installSettingsRoute(ctx, settings, onChannelChange) {
     const inject = ctx.inject;
     if (typeof inject !== 'function')
         return;
@@ -312,7 +381,7 @@ function installSettingsRoute(ctx, settings) {
             host.effect(() => host.webServer.register({
                 kind: 'exact',
                 path: SETTINGS_ROUTE,
-                handler: (request, response) => handleSettingsRequest(request, response, settings),
+                handler: (request, response) => handleSettingsRequest(request, response, settings, onChannelChange),
             }, 'dsh-builtin-browser: settings'));
         });
     }
@@ -326,8 +395,9 @@ function installSettingsRoute(ctx, settings) {
  * @param request - the incoming request.
  * @param response - the response to write.
  * @param settings - the settings document.
+ * @param onChannelChange - re-runs the carrier choice when this write changed `browser.channel`.
  */
-async function handleSettingsRequest(request, response, settings) {
+async function handleSettingsRequest(request, response, settings, onChannelChange) {
     const json = (status, body) => {
         response.writeHead(status, {
             'content-type': 'application/json; charset=utf-8',
@@ -352,7 +422,20 @@ async function handleSettingsRequest(request, response, settings) {
     try {
         const body = await readBody(request);
         const patch = body.trim() === '' ? {} : JSON.parse(body);
-        json(200, { ok: true, settings: settings.update(patch) });
+        const before = settings.get().browser.channel;
+        const updated = settings.update(patch);
+        // A changed `browser.channel` is a request to switch carriers, not just a value to store. The
+        // choice is re-run here so the write takes effect now — and the response says so, because a
+        // caller that cannot tell "applied" from "stored for later" has no way to know what it got,
+        // which is exactly how a write that did nothing read as a success.
+        const channelChanged = updated.browser.channel !== before;
+        if (channelChanged)
+            onChannelChange?.();
+        json(200, {
+            ok: true,
+            settings: updated,
+            ...channelChanged ? { carrierRechosen: true } : {},
+        });
     }
     catch (error) {
         json(400, { ok: false, error: `invalid settings patch: ${String(error)}` });

package/lib/browser-electron/history-store.d.ts

@@ -1,6 +1,6 @@
 /**
  * Persistent browsing history: which pages the shared browser actually visited,
- * kept independently from any session's operation log (`browser_history`) and
+ * kept independently from any session's operation log (`dsh_browser_history`) and
  * from the browser process's lifetime.
  *
  * It lives beside the browser profile (`$DSH_HOME/dsh-builtin-browser-host/

package/lib/browser-electron/history-store.js

@@ -1,6 +1,6 @@
 /**
  * Persistent browsing history: which pages the shared browser actually visited,
- * kept independently from any session's operation log (`browser_history`) and
+ * kept independently from any session's operation log (`dsh_browser_history`) and
  * from the browser process's lifetime.
  *
  * It lives beside the browser profile (`$DSH_HOME/dsh-builtin-browser-host/

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

@@ -38,7 +38,7 @@ import { dirname, join } from 'node:path';
 // several Electron instances sharing Roaming\Electron fight over the GPU
 // cache/session locks, which can leave the window without a display surface
 // (capturePage then fails). A dedicated userData also persists cookies across
-// host restarts (on top of browser_auth). Must run before app is ready.
+// host restarts (on top of dsh_browser_auth). Must run before app is ready.
 try {
     const base = process.env.DSH_HOME ?? app.getPath('appData');
     app.setPath('userData', join(base, 'dsh-builtin-browser-host'));
@@ -785,7 +785,7 @@ async function handle(op, msg) {
                 if (win === undefined || entry === undefined)
                     throw new Error(`focus: unknown view ${viewId}`);
                 // Keys go to the view that holds web focus. A view that was never
-                // clicked holds none, so the FIRST browser_key of a session was dropped
+                // clicked holds none, so the FIRST dsh_browser_key of a session was dropped
                 // by the renderer while CDP still answered the dispatch with success —
                 // and `document.hasFocus()` inside the page even read true.
                 const contents = entry.webContentsView.webContents;
@@ -920,7 +920,7 @@ async function handle(op, msg) {
                     throw new Error('capture produced no image (view not painted)');
                 }
                 // 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,
+                // default self-hosted one — could never answer `dsh_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.

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

@@ -119,6 +119,17 @@ export interface ElectronBrowserViewHost {
      *   which is only correct from a teardown that is itself global.
      */
     releasePage?(owner?: string): Promise<void>;
+    /**
+     * Report that this carrier can no longer serve anything, so its owner may replace it.
+     *
+     * A carrier that borrows an outside process can lose it: the desktop shell exits, and every call
+     * after that would dial a port nobody owns. Without this signal the swap happens only at
+     * startup, so the choice made then is final for the process's life — which is what a user
+     * experiences as "the browser stopped working until I restart DSH". Optional: a carrier that
+     * owns its own lifetime has nothing to report.
+     * @param listener - called once, when the carrier concludes it is gone.
+     */
+    onLost?(listener: () => void): void;
     /**
      * Fold the carrier's presentation away while keeping the page alive.
      *
@@ -274,7 +285,7 @@ export interface ElectronBrowserProviderConfig {
      */
     readonly contentMaxChars?: number;
     /**
-     * Directory `browser_download` save paths must resolve inside (prevents a
+     * Directory `dsh_browser_download` save paths must resolve inside (prevents a
      * prompt-injected agent from writing arbitrary machine paths). Default:
      * `~/Downloads`. NOTE: this default is a convenience, not a security
      * boundary — on Windows it may resolve to OneDrive/redirected paths;
@@ -328,7 +339,7 @@ export declare function layoutSize(metrics: Record<string, unknown>): {
     viewportHeight: number;
 } | undefined;
 /**
- * Map CDP cookies onto the shape `browser_auth` exports.
+ * Map CDP cookies onto the shape `dsh_browser_auth` exports.
  *
  * CDP reports a cookie as domain + path rather than a URL, and in seconds rather than
  * milliseconds, so both are converted. Entries missing a name, value or domain are
@@ -441,9 +452,9 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
     /**
      * Page.navigate resolves at navigation COMMIT, not at load: the new document
      * is already current (so location.href and document.title are the new page's)
-     * while its DOM is still being parsed. browser_open snapshots immediately
+     * while its DOM is still being parsed. dsh_browser_open snapshots immediately
      * after navigating, which is why it could report the right title with zero
-     * interactive elements — and why a separate browser_snapshot right after
+     * interactive elements — and why a separate dsh_browser_snapshot right after
      * always found them.
      *
      * Wait — bounded, best-effort — for the new document to settle: readyState
@@ -482,7 +493,7 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
      *
      * A renderer only delivers key events to the view that holds web focus. A
      * view that was created but never clicked holds none — and `Input` events
-     * injected over CDP do not grant it — so the FIRST `browser_key` of a fresh
+     * injected over CDP do not grant it — so the FIRST `dsh_browser_key` of a fresh
      * session vanished inside the renderer while the command still answered
      * success. Hosts that cannot focus a view (a test double, a different shell
      * adapter) simply have no `focus`, and nothing changes for them.
@@ -587,7 +598,7 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
      * Refuse an action the settings have switched off.
      *
      * These switches belong to the OPERATOR. The settings document is written through the
-     * plugin's own panel and no tool can reach it, so — unlike `browser_restrict`, which the
+     * plugin's own panel and no tool can reach it, so — unlike `dsh_browser_restrict`, which the
      * model owns and can lift at will — a refusal here stands for as long as the setting does.
      * That is the point of them: a deployment can take page-script execution, downloads, or
      * login-state writes off the table without relying on the model's cooperation.
@@ -601,7 +612,7 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
     private assertActionAllowed;
     /**
      * Admit a caller-supplied save path for a file the browser writes to disk.
-     * ONE gate for both `browser_download` and `browser_screenshot`: the path
+     * ONE gate for both `dsh_browser_download` and `dsh_browser_screenshot`: the path
      * must be absolute, must resolve inside `downloadDir`, and must not already
      * exist. Without it a prompt-injected agent could write — or silently
      * replace — any file the DSH process can reach, which also escapes the file
@@ -665,7 +676,7 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
      */
     private recordVisit;
     /**
-     * List persisted visits, newest first — what `browser_visited` reads back.
+     * List persisted visits, newest first — what `dsh_browser_visited` reads back.
      * @param options - result cap and an optional hostname filter.
      * @returns the matching visits, or an empty list when history is disabled.
      */
@@ -705,6 +716,19 @@ export declare class ElectronBrowserProvider implements BrowserProvider {
     private activeTab;
     /** Append a fresh tab and make it active. */
     private newTab;
+    /**
+     * Swap a wedged view for a fresh blank one, keeping the tab's public id.
+     *
+     * A view whose renderer never commits cannot be read again: every evaluate into it runs out its
+     * whole budget. Replacing it is what turns that from permanent into one bad call — the tab id
+     * callers hold stays valid, and the next `dsh_browser_open` with the real URL re-populates it.
+     *
+     * The old view is destroyed AFTER the new one is in place, so a failure here cannot leave the
+     * session holding a handle that is already gone.
+     * @param s - the session owning the tab.
+     * @param tab - the tab to reset.
+     */
+    private replaceTabWithBlank;
     /** Find a session's tab by its backing view id (toolbar actions carry view ids). */
     private tabByViewId;
     /**