dsh-builtin-browser 0.4.5 → 0.4.7

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

@@ -69,6 +69,13 @@ export declare const DEFAULT_SETTINGS: BrowserSettings;
  * @returns the settings file path.
  */
 export declare function settingsPath(): string;
+/**
+ * The channels a settings document may name.
+ *
+ * Exported so the log line and the error message can quote the same set the parser accepts: a
+ * message that lists a value the code rejects (or omits one it takes) is worse than no message.
+ */
+export declare const BROWSER_CHANNELS: readonly ["chrome", "edge", "auto", "bundled", "sidebar"];
 /**
  * Resolve a raw settings document (already parsed, shape unknown) into the full
  * document, field by field. Unknown keys are dropped: the file is not a place to
@@ -76,7 +83,7 @@ export declare function settingsPath(): string;
  * @param raw - the parsed file contents.
  * @returns the resolved settings.
  */
-export declare function resolveSettings(raw: unknown): BrowserSettings;
+export declare function resolveSettings(raw: unknown, warn?: (message: string) => void): BrowserSettings;
 /**
  * File-backed settings with an in-memory snapshot. Reads re-stat the file so an
  * edit from another process (or the settings panel writing through a second
@@ -85,13 +92,14 @@ export declare function resolveSettings(raw: unknown): BrowserSettings;
  */
 export declare class SettingsStore {
     private readonly file;
+    private readonly log?;
     private cached;
     /** Last observed mtime, used to invalidate the cache on external edits. */
     private cachedMtimeMs;
     /**
      * @param file - settings file path (defaults beside the browser profile).
      */
-    constructor(file?: string);
+    constructor(file?: string, log?: ((message: string) => void) | undefined);
     /** Path this store reads and writes. */
     path(): string;
     /**

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

@@ -68,16 +68,34 @@ const SETTINGS_WHEN_UNREADABLE = {
     credentials: { allowRead: false },
     actions: { allowExecute: false, allowDownload: false, allowCredentialWrite: false },
 };
+/**
+ * The channels a settings document may name.
+ *
+ * Exported so the log line and the error message can quote the same set the parser accepts: a
+ * message that lists a value the code rejects (or omits one it takes) is worse than no message.
+ */
+export const BROWSER_CHANNELS = ['chrome', 'edge', 'auto', 'bundled', 'sidebar'];
 /**
  * Coerce the browser channel, keeping the default when it is not one of the
  * known choices. A hand-edited typo must not silently select a different browser.
+ *
+ * Coercing is right; coercing QUIETLY is not. A typo and "the setting did nothing" look exactly
+ * the same to whoever typed it, which is why every discarded value is reported.
  * @param value - the raw value from the settings document.
+ * @param warn - where to report a discarded value, when the caller has somewhere to put it.
  * @returns a valid channel.
  */
-function resolveChannel(value) {
-    return value === 'chrome' || value === 'edge' || value === 'auto' || value === 'bundled' || value === 'sidebar'
-        ? value
-        : DEFAULT_SETTINGS.browser.channel;
+function resolveChannel(value, warn) {
+    // Absent is the ordinary case, not a mistake: a document that never mentioned the channel gets
+    // the default without a word.
+    if (value === undefined)
+        return DEFAULT_SETTINGS.browser.channel;
+    if (BROWSER_CHANNELS.includes(value))
+        return value;
+    warn?.(`dsh-builtin-browser: browser.channel ${JSON.stringify(value)} is not a known channel, so the `
+        + `default "${DEFAULT_SETTINGS.browser.channel}" was used instead. Expected one of: `
+        + `${BROWSER_CHANNELS.join(', ')}.`);
+    return DEFAULT_SETTINGS.browser.channel;
 }
 /** Coerce one positive-integer field, keeping the default when invalid. */
 function count(value, fallback) {
@@ -119,7 +137,7 @@ function section(source, key) {
  * @param raw - the parsed file contents.
  * @returns the resolved settings.
  */
-export function resolveSettings(raw) {
+export function resolveSettings(raw, warn) {
     const source = typeof raw === 'object' && raw !== null ? raw : {};
     const history = section(source, 'history');
     const cookies = section(source, 'cookies');
@@ -146,7 +164,7 @@ export function resolveSettings(raw) {
             virtualCursor: bool(ui?.virtualCursor, DEFAULT_SETTINGS.ui.virtualCursor),
         },
         vision: { strategy: vision?.strategy === 'nonVisual' ? 'nonVisual' : DEFAULT_SETTINGS.vision.strategy },
-        browser: { channel: resolveChannel(browser?.channel) },
+        browser: { channel: resolveChannel(browser?.channel, warn) },
         credentials: {
             // `gate` returns false for anything present-and-not-a-boolean, so an unreadable section
             // is refused here for free: the section itself is the "present but wrong" value.
@@ -175,14 +193,16 @@ export function resolveSettings(raw) {
  */
 export class SettingsStore {
     file;
+    log;
     cached;
     /** Last observed mtime, used to invalidate the cache on external edits. */
     cachedMtimeMs = -1;
     /**
      * @param file - settings file path (defaults beside the browser profile).
      */
-    constructor(file = settingsPath()) {
+    constructor(file = settingsPath(), log) {
         this.file = file;
+        this.log = log;
     }
     /** Path this store reads and writes. */
     path() {
@@ -230,7 +250,7 @@ export class SettingsStore {
             // value in it: the document looked correct, and the plugin quietly ran on
             // defaults — including switches the user had just turned off.
             const body = text?.replace(/^\uFEFF/, '');
-            this.cached = body === undefined ? DEFAULT_SETTINGS : resolveSettings(JSON.parse(body));
+            this.cached = body === undefined ? DEFAULT_SETTINGS : resolveSettings(JSON.parse(body), m => this.log?.(m));
         }
         catch {
             // A document that EXISTS but cannot be parsed is not the same as no document at all: the
@@ -250,7 +270,7 @@ export class SettingsStore {
      */
     update(patch) {
         const current = this.get();
-        const merged = resolveSettings(deepMerge(current, patch));
+        const merged = resolveSettings(deepMerge(current, patch), m => this.log?.(m));
         try {
             mkdirSync(dirname(this.file), { recursive: true });
             writeFileAtomic(this.file, `${JSON.stringify(merged, null, 2)}\n`);

package/lib/tool-browser/index.js

@@ -98,6 +98,40 @@ function assertAllowed(state, toolName, task) {
 function agentOf(exec) {
     return exec?.agent;
 }
+/**
+ * Refuse the bare DSH web root, which answers 401 and looks like a real page.
+ *
+ * The address comes from `DSH_WEB_URL`, which the harness exports to its children — NOT from a
+ * hardcoded port. This machine's GUI has run on 3080 and on 19387, so a number would stop matching
+ * exactly when the guard is needed, and the trap is not a port anyway: it is the SHAPE. A loopback
+ * address at its root with no token renders as an unauthenticated 401 page, which an agent reads
+ * as the site it meant to open.
+ * @param rawUrl - the address a caller asked to open.
+ */
+function assertNotBareDshWebUrl(rawUrl) {
+    const advertised = process.env.DSH_WEB_URL;
+    if (typeof advertised !== 'string' || advertised === '')
+        return;
+    let target;
+    let dsh;
+    try {
+        target = new URL(rawUrl);
+        dsh = new URL(advertised);
+    }
+    catch {
+        return; // not a URL this guard can judge; the provider's own admission is the next gate
+    }
+    if (target.origin !== dsh.origin)
+        return;
+    if (target.pathname !== '/')
+        return;
+    // The authenticated URL printed by `dsh web` carries a token; the bare root does not.
+    if (target.searchParams.has('token'))
+        return;
+    throw new Error('browser_open: refusing the bare DSH web root (' + dsh.origin + '/) because it carries no '
+        + 'authentication token, so it answers with a 401 page that reads like a real site. Open the '
+        + 'target site instead; to open DSH itself, use the authenticated URL printed by `dsh web`.');
+}
 /**
  * Read a target's `index`, refusing the values that cannot mean anything.
  *
@@ -263,7 +297,7 @@ export function apply(ctx, config = {}) {
     });
     ctx.tools.register(defineTool({
         name: 'browser_open',
-        description: 'Open a URL in the shared browser window. Opens this task\'s browser session on first use; optionally opens in a new tab. Returns the resulting page snapshot.',
+        description: 'Open a URL in the shared browser window. Opens this task\'s browser session on first use; optionally opens in a new tab. Returns the resulting page snapshot. A fresh session starts on a blank, uncommitted tab: call this with the REAL target URL before reading, because reading that tab returns an empty page instead of waiting. Never treat the bare DSH host (e.g. http://127.0.0.1:3080/) as the target website — it requires the authenticated URL printed by `dsh web`, and the bare root is refused outright.',
         parameters: {
             url: { type: 'string', required: true, description: 'The URL to open (HTTP/HTTPS).' },
             newTab: { type: 'boolean', description: 'Open in a new tab instead of the active one.' },
@@ -302,6 +336,7 @@ export function apply(ctx, config = {}) {
         isConcurrencySafe: () => false, // opens tabs / navigates; exclusive within a task
         async execute(args, exec) {
             assertAllowed(state, 'browser_open', taskKey(exec));
+            assertNotBareDshWebUrl(args.url);
             const browser = ctx.get('browser');
             if (browser === undefined)
                 throw new Error('tool-browser: browser service unavailable');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-builtin-browser",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "description": "Shared real browser plugin for DeepSeek Harness: install-and-use — a visible native browser the human can take over, driven by the agent over CDP. DOM-level interaction (React/Vue safe), per-task session isolation, cookie persistence (browser_auth), CAPTCHA detection, batch form fill (browser_fill), authenticated download, history/replay, action restriction",
   "type": "module",
   "main": "lib/index.js",

package/src/browser-electron/bridge-connection.ts

@@ -51,6 +51,16 @@ const MAX_BUFFER_BYTES = 128 * 1024 * 1024
  */
 const REQUEST_ID_FIELD = 'bridgeRequestId'
 
+/**
+ * How long the published endpoint may go un-refreshed before its shell is presumed gone.
+ *
+ * A live shell rewrites the file every fifteen seconds (its keep-alive), so four missed refreshes
+ * is not a slow shell — it is a shell that exited and left its last write behind. The distinction
+ * matters because the file is the ONLY thing that says where the bridge is: a tombstone names a
+ * port nobody owns, and a client that trusts it dials that port for the rest of its life.
+ */
+const ENDPOINT_TTL_MS = 60_000
+
 /**
  * A reusable connection to the bridge.
  *
@@ -78,12 +88,19 @@ export class BridgeConnection {
   private idLessBridge = false
   /** True once this connection may only have one request in flight at a time. */
   private serialisable = false
+  /** True once the shell behind this connection has been reported gone. */
+  private lostNotified = false
 
   /**
    * @param endpoint - the shell's published bridge endpoint.
    * @param endpointPath - where that endpoint is republished, so a moved port can be followed.
+   * @param onLost - called once when this connection concludes the shell behind it is gone.
    */
-  constructor(private endpoint: BridgeEndpoint, private readonly endpointPath?: string) {}
+  constructor(
+    private endpoint: BridgeEndpoint,
+    private readonly endpointPath?: string,
+    private readonly onLost?: () => void,
+  ) {}
 
   /**
    * Re-read the published endpoint, and adopt it if the shell has moved.
@@ -103,6 +120,13 @@ export class BridgeConnection {
     try {
       const raw = JSON.parse(readFileSync(this.endpointPath, 'utf8')) as Partial<BridgeEndpoint>
       if (typeof raw.port !== 'number' || typeof raw.token !== 'string') return false
+      // A shell that exited stops refreshing the file, and what it left names a port nobody owns.
+      // Trusting it is how a host ends up dialling a dead port for the rest of the process's life
+      // — reported as "the browser stopped working and only restarting DSH brought it back".
+      if (endpointExpired(raw.updatedAt)) {
+        this.notifyLost()
+        return false
+      }
       if (raw.port === this.endpoint.port && raw.token === this.endpoint.token) return false
       this.endpoint = {
         port: raw.port,
@@ -117,6 +141,17 @@ export class BridgeConnection {
     }
   }
 
+  /** Report once that the shell is gone, so the surface can fall back instead of dialling it. */
+  private notifyLost(): void {
+    if (this.lostNotified) return
+    this.lostNotified = true
+    try {
+      this.onLost?.()
+    } catch {
+      // A listener must never break the transport: the caller's error is the one that matters.
+    }
+  }
+
   /**
    * Send one request, reusing the socket if it is still healthy.
    *
@@ -138,6 +173,16 @@ export class BridgeConnection {
     // when the condition could not clear, spun until the process ran out of heap.
     // Follow the shell if its bridge moved to a new port (see refreshEndpoint).
     this.refreshEndpoint()
+    // The shell behind this connection is gone, and the endpoint file says so. Refusing here is
+    // what turns a permanent ECONNREFUSED into one named error the surface can act on — by
+    // falling back to the browser it hosts itself, instead of dialling a dead port until DSH is
+    // restarted.
+    if (this.lostNotified) {
+      throw new Error(
+        'dsh-builtin-browser: the desktop shell that backed this browser has exited '
+        + '(its published endpoint stopped being refreshed)',
+      )
+    }
     let socket = this.ensureSocket()
     if (this.serialisable && this.queue.length > 0) {
       this.reset(new Error('dsh-builtin-browser: bridge connection reopened so replies stay attributable'))
@@ -288,8 +333,21 @@ export class BridgeConnection {
   }
 }
 
-/** The request id a raw answer line echoes back, when it carries one. */
-function echoOf(line: string): number | undefined {
+/**
+ * Whether a published endpoint has gone un-refreshed long enough to be a tombstone.
+ *
+ * A missing or unparseable stamp is NOT expired: an older bridge that never wrote one must keep
+ * working, and guessing "stale" from absence would break every shell that predates the field.
+ * @param updatedAt - the file's own refresh stamp, when it carries one.
+ */
+function endpointExpired(updatedAt: unknown): boolean {
+  if (typeof updatedAt !== 'string') return false
+  const at = Date.parse(updatedAt)
+  if (!Number.isFinite(at)) return false
+  return Date.now() - at > ENDPOINT_TTL_MS
+}
+
+/** The request id a raw answer line echoes back, when it carries one. */function echoOf(line: string): number | undefined {
   try {
     const answer = JSON.parse(line) as Record<string, unknown>
     const value = answer[REQUEST_ID_FIELD]

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

@@ -118,13 +118,34 @@ export class DesktopBridgeViewHost implements ElectronBrowserViewHost {
    * the desktop sidebar is the carrier — by design, not by omission.
    */
   private userActionHandler: ((action: BrowserUserAction) => void) | undefined
+  /** Told when the shell behind this bridge exits; see `onLost`. */
+  private lostListener: (() => void) | undefined
 
   /**
    * @param endpoint - the shell's published bridge endpoint.
    */
   private constructor(endpoint: BridgeEndpoint, sessionId?: string) {
     this.owner = sessionId !== undefined && sessionId !== String.fromCharCode(39,39) ? sessionId : randomUUID()
-    this.connection = new BridgeConnection(endpoint, bridgeEndpointPath())
+    this.connection = new BridgeConnection(endpoint, bridgeEndpointPath(), () => this.reportLost())
+  }
+
+  /**
+   * Called by the transport once the shell behind it is gone.
+   *
+   * Forwarded rather than acted on here: only the entry point owns the swap back to the self-hosted
+   * browser, and a host that tried to replace itself would be reaching outside its own contract.
+   */
+  private reportLost(): void {
+    try {
+      this.lostListener?.()
+    } catch {
+      // The listener's failure is not the transport's problem.
+    }
+  }
+
+  /** Register the "this carrier is gone" listener (see the interface's `onLost`). */
+  onLost(listener: () => void): void {
+    this.lostListener = listener
   }
 
   /**

package/src/browser-electron/entry.ts

@@ -17,8 +17,9 @@ import type { BrowserRuntime } from '../browser/runtime.js'
 import { ElectronBrowserProvider } from './provider.js'
 import type { ElectronBrowserViewHost } from './provider.js'
 import { randomUUID } from 'node:crypto'
+import { existsSync, mkdirSync, renameSync } from 'node:fs'
 import { homedir } from 'node:os'
-import { join } from 'node:path'
+import { dirname, 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'
@@ -111,9 +112,10 @@ export function apply(ctx: Context & { browser: BrowserRuntime }, config: Config
   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,
@@ -128,6 +130,17 @@ export function apply(ctx: Context & { browser: BrowserRuntime }, config: Config
   if (config.viewHost !== undefined) {
     const external = ctx.browser.registerBrowserProvider(new ElectronBrowserProvider(config.viewHost as ElectronBrowserViewHost, 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
   }
 
@@ -139,25 +152,69 @@ export function apply(ctx: Context & { browser: BrowserRuntime }, config: 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: ElectronBrowserViewHost | undefined
 
   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: ElectronBrowserViewHost): void => {
+    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: ElectronBrowserViewHost, note: string): void => {
-    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
       // adopt that got as far as constructing it may already hold a socket, a listener or a child
@@ -183,6 +240,16 @@ export function apply(ctx: Context & { browser: BrowserRuntime }, config: Config
     }
   }
 
+  /**
+   * 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 = (): void => {
   // 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.
@@ -225,6 +292,7 @@ export function apply(ctx: Context & { browser: BrowserRuntime }, config: Config
       // 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()))
@@ -279,6 +347,14 @@ export function apply(ctx: Context & { browser: BrowserRuntime }, config: Config
       )
     }
   })()
+  }
+
+  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. */
@@ -293,6 +369,41 @@ const SETTINGS_ROUTE = '/dsh-builtin-browser/settings'
  */
 const BROWSER_PROFILE_DIR = 'dsh-builtin-browser-host'
 
+/**
+ * Move a browser profile left behind by the old layout into the directory the plugin uses now.
+ *
+ * Before the `?.dsh` component was added here, a desktop launched from a shortcut (no `DSH_HOME`
+ * in the environment) put its browser profile in `<homedir>/dsh-builtin-browser-host/` while its
+ * settings and history lived in `<homedir>/.dsh/dsh-builtin-browser-host/`. Login state lives
+ * INSIDE the browser profile, so leaving the old directory behind silently signs the user out of
+ * everything they had signed into — reported after the fix shipped, as a one-time cost of it.
+ *
+ * That cost does not have to be paid. The move happens only when the new location is absent, so a
+ * profile in use is never overwritten, and every failure — a cross-device rename, a permission
+ * problem, a profile another process holds — falls through to an empty profile, which is exactly
+ * what would have happened without this function. The old directory is then left untouched rather
+ * than deleted, because a half-moved profile is worse than a stale one.
+ *
+ * @param profileRoot - the root the plugin resolves today (`<DSH_HOME>/dsh-builtin-browser-host`).
+ * @param legacyRoot - the pre-`DSH_HOME` layout's root. Injected so the move can be exercised
+ *   without touching the real home directory.
+ */
+export function adoptLegacyProfileRoot(
+  profileRoot: string,
+  legacyRoot: string = join(homedir(), BROWSER_PROFILE_DIR),
+): void {
+  try {
+    if (legacyRoot === profileRoot) return
+    if (!existsSync(legacyRoot) || existsSync(profileRoot)) return
+    // `renameSync` needs the destination's PARENT to exist, and on a fresh install it does not:
+    // the old layout never created `.dsh` at all. Creating it is harmless if it is already there.
+    mkdirSync(dirname(profileRoot), { recursive: true })
+    renameSync(legacyRoot, profileRoot)
+  } catch {
+    // Nothing here is worth failing an apply over; the fallback is the pre-existing behaviour.
+  }
+}
+
 /** The host web-server surface this plugin uses, described structurally. */
 interface WebServerHost {
   readonly webServer: {
@@ -316,7 +427,11 @@ interface WebServerHost {
  * @param ctx - the plugin context.
  * @param settings - the settings document to expose.
  */
-function installSettingsRoute(ctx: Context, settings: SettingsStore): void {
+function installSettingsRoute(
+  ctx: Context,
+  settings: SettingsStore,
+  onChannelChange?: () => void,
+): void {
   const inject = (ctx as unknown as {
     inject?: (deps: readonly string[], callback: (host: WebServerHost) => void) => void
   }).inject
@@ -326,7 +441,7 @@ function installSettingsRoute(ctx: Context, settings: SettingsStore): void {
       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'))
     })
   } catch {
@@ -340,11 +455,13 @@ function installSettingsRoute(ctx: Context, settings: SettingsStore): void {
  * @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: IncomingMessage,
   response: ServerResponse,
   settings: SettingsStore,
+  onChannelChange?: () => void,
 ): Promise<void> {
   const json = (status: number, body: unknown): void => {
     response.writeHead(status, {
@@ -370,7 +487,19 @@ async function handleSettingsRequest(
   try {
     const body = await readBody(request)
     const patch: unknown = 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)}` })
   }