dsh-builtin-browser 0.4.5 → 0.4.7

package/CHANGELOG.md

@@ -4,6 +4,108 @@
 
 ---
 
+# 第四十三轮(2026-10-12,三个"看起来无关"的缺陷:载体被写死、宿主死了不换、设置读了不生效)
+
+这一轮的共同点不是症状,而是**判断被做了一次就再也不做了**:载体在启动时选一次、连接端口在建立时记一次、`browser.channel` 在 apply 时读一次。三次都发生在"当时是对的"的情况下,三次的后果都是"之后永远不对"。
+
+## 一、标签级三件套 + 裸根拦截(issue #26,@dengyun2018-commits)
+
+他带着一份本地 patch 来,已在 0.4.0 → 0.4.5 四个版本上实跑、每次 `apply --check` 零偏移。四条全部收下,两条判据换了实现:
+
+**标签 URL 跟踪**:每个标签记住"最后一次被接受的 URL"。`listTabs` 不再探测它已知为空的标签——未提交的视图上那次往返只能回答"没有";而"从未导航"与"导航过但读不出来"终于可区分(此前两者都塌进同一个空字符串)。读失败时保留上次的 URL,而不是把标签报成空的。
+
+**空白标签短路**:`snapshot` / `a11y` 在未导航的标签上立即返回空页,而不是在一个没有文档可提交的视图里跑采集器、先耗尽整个 30 秒预算。
+
+**超时自愈**:超时的读操作**原位替换**卡死的视图(标签对调用方保持同一个 id),并抛出 `BROWSER_SNAPSHOT_TIMEOUT` / `BROWSER_A11Y_TIMEOUT`。此前视图留在会话里,于是**之后的每一次读都要再付一遍 30 秒**——`terminatePage` 只中断正在跑的脚本,并不会让视图变得可读。它还有个每视图 3 次的待终止上限,所以反复读会累积挂起的 evaluate。
+
+**裸根拦截**:`browser_open` 拒绝不带 token 的 DSH web 根地址——它返回 401 页面,读起来像一个真站点。**判据用的是 `DSH_WEB_URL`(harness 自己导出的环境变量),而不是端口号**:这台机器的 GUI 在 3080 和 19387 上都跑过,硬编码端口会在最需要它的那次不匹配。识别陷阱靠的是形状——同源 + 根路径 + 无 token——不是数字。
+
+## 二、桌面壳退出后,浏览器面板跟着一起死
+
+用户报的是"浏览器不能正常使用了,只能重启 DSH"。
+
+链条是两处叠加:**载体只在启动时选一次,而且只能向上走**——自托管先注册,发现桌面 bridge 后把它换成 provider,紧接着 `selfHosted.dispose()`。**没有回退目标。**启动时那四次重试只覆盖"bridge 出现得晚",而代码注释自己写着这个交换是单向的。
+
+**`refreshEndpoint` 也救不了,原因很精确**:它比较 port 和 token,而死掉的 shell 留下的文件**内容原封不动**——文件看着是新的,指向的是尸体。
+
+**判据来自文件里本来就有的字段**:活的 shell 每 15 秒重写 `updatedAt`,所以**四次没刷新就不是"慢",是"没了"**。超过一分钟的端点现在被判定为墓碑,一次性上报,经由载体接口上新增的 `onLost`;entry 收到后用自托管把 provider 重新注册回来。**缺失 `updatedAt` 刻意不算过期**,否则所有比这个字段更老的 shell 都会在首次使用时就判死。
+
+失败信息也不再是裸的 `ECONNREFUSED`——它点名原因,因为读它的人正是决定要不要回退的那个。
+
+## 三、`browser.channel` 只在 apply 时读一次(issue #27,@sbtxdy)
+
+他给了一组对照测量:`Electron/44.5.1` 对 `Edg/155.0.0.0`,以及"改完不重启、进程里没有任何带插件自有 `--user-data-dir` 的 msedge.exe"。三条建议全收,第一条选了**热切换**而不是退让到 `restartRequired`。
+
+**载体实时重选**:选择逻辑改成一个 `chooseCarrier()`,设置路由在写入改变 channel 时重跑它。这里有一处必须一起动:`adopt` 原有的一次性 guard 会把晚到的载体直接 `dispose` 掉——**防两个载体抢入是对的,对"用户改设置"恰好是错的**,因为那正是"写成功了、然后新载体被安静丢掉"的来源。现在换掉旧载体的是新载体,且在装好之后才释放。
+
+**不生效的写会说出来**:响应区分"已应用"和"只存了"(`carrierRechosen`);载体由 composition 提供(桌面 shell)而 channel 无法生效时打 WARN。**对一次没人会读的写回 `ok`,是调用方唯一分不出"成功"和"什么都没做"的地方**。
+
+**拼错的值不再静默**:`resolveChannel` 把未知值退回默认——它的注释写着这是有意为之("手改的错别字不该静默选中别的浏览器"),**但结果让错别字和"设置没生效"长得一模一样**。退回是对的,静默退回不是:现在会报出原值并列出接受集合。**缺席保持安静**,否则警告会变成噪音。
+
+## 四、自我更正
+
+**第二节的光标是我的**:`BridgeConnection.refreshEndpoint` 的存在恰恰证明我知道"端口会变"这件事,但判据选成了"与当前不同",而墓碑的特征是"与当前相同但已经死了"。同一个字段的两端,我只写了会变的那一端。
+
+**测试**:237 → 250(本轮新增 13 条:标签 URL 与空白短路 3 条、墓碑与回退 4 条、channel 重选 6 条)。`tsc` 干净。其中超时自愈那条是**形状断言**而不是行为断言——真跑 30 秒太慢——这一点写进了 commit 和给报告者的回复里,免得以后有人把它读强。
+
+**发布**:0.4.7。`npm` 与仓库同步。
+
+---
+
+# 第四十二轮(2026-10-08,三个"能看见的"缺陷:跨会话读错、空白页堆积、升级登出)
+
+0.4.5 发布后,用户连续报了三个现象。**三个都在同一段代码的新实现里**,而它们看着毫不相干——一个是"别的会话读到我这边",一个是"一次开一堆空白页",一个是"升级后所有站点被登出"。前两个实际上是**同一个会话在两种状态下的两种表现**。
+
+## 一、面板查找越出本会话(跨会话读错)
+
+**症状**:另一个会话调用时读到了**本会话的侧栏**——同一段对话里两次读取给出相反结论(先说"已登录"、后说"未登录"),点 GitHub 登录也没有反应。
+
+**根因(实测确认,不是推理)**:客户端半边的 `guestsInPanel` 从本会话的侧栏条**向上走**,找"第一个含 `<webview>` 的祖先"。而**外壳把所有会话的侧栏都挂在同一棵文档树里**(隐藏的也在),所以多走一步就落到了共同根,那里的"第一个 guest"属于**外壳先渲染的那个会话**——顺序随挂载状态漂移,于是同一个会话两次能拿到不同的页面。
+
+现场证据:
+
+    panelGuest(本会话 session-fe0a980a) →
+      {"panel":true,"guestId":3,"url":"https://github.com/login?...virtualembryo.ai..."}
+
+那个 GitHub 登录页**不是本会话打开的**。本会话因此会去驱动一个不属于它的页面——第二次读取时那个页面已不在,于是"未登录"。
+
+**修法**:向上走的循环**一遇到不属于本会话的侧栏条就停**。同级的侧栏条是"已经跨出本会话"的精确标志,且不依赖任何类名;一个会话自己可以有多个,所以判据是**"有没有不是我的"**,不是数量。起点也改回侧栏条自身(而非其父节点),这样 guest 与条同级的布局也能走到。
+
+**守护用例**构造了两会话共存的树、邻居持有 guest,断言本会话报告自己没有、且打开面板时**不导航邻居的任何页面**。
+
+## 二、等待期间误建页面(一次开一堆空白初始页)
+
+**症状**:"一次性打开很多个浏览器初始页面,但只有最后一个是我们需要的。"
+
+**根因**:桥在等 guest 附着时每 250ms 轮询一次,**而每轮调的都是 `openPanel`——那是个会创建标签的动作**。20 秒的预算 = 最多 80 次创建,每次一个不带地址的初始页。"最后一个是需要的"也对得上:第一个才是带地址的那次。
+
+**修法**:等待改用**只读**形式。`evaluatePanelService` 现在明确区分两种语义——**`null` 是读,字符串才是放置/导航**。只读形式自带 `ok`,因为"你现在有什么"回答"还没有"是合法答案,不是请求失败(否则每一轮都像出错)。
+
+**守护用例**:无论等待多久都**恰好一次**放置,且每一轮调的都是 `api.panelGuest(`、从不调 `api.openPanel(`。匹配的是**调用**而非名字,因为每个表达式都带 `typeof api.openPanel !== 'function'` 的能力检查。
+
+## 三、升级把浏览器登出(profile 路径变更的尾巴)
+
+**症状**(由 @EmyiaC 在 issue #21 复测后报告):0.4.1 → 0.4.5 升级后,浏览器**登出所有站点**。他建议写进 release notes。
+
+**根因**:早先修过一个路径不一致——从快捷方式启动的桌面端(环境里没有 `DSH_HOME`)把浏览器 profile 放在 `<homedir>/dsh-builtin-browser-host/`,而 settings 与 history 在 `<homedir>/.dsh/dsh-builtin-browser-host/`。**登录态就在 profile 里**,路径一改,旧目录连同登录态被丢下。
+
+**修法**:**不写那行 release note,而是把代价去掉。** apply 时若旧根存在、当前根不存在,则把旧根**移**过去。两条规则兜住风险:
+
+- **只在目标缺席时移动**——正在用的 profile 永不被覆盖;
+- **任何失败都退回空 profile**(跨设备 rename、权限、被别的进程占用),此时旧目录**原样保留**而不是移一半。Windows 的 rename 需要目标父目录存在,所以先建。
+
+**守护用例四条**:移动、不覆盖、无可迁移、两侧同路径。旧根做成**带默认值的参数**,这让移动**可以在不碰真实 home 的情况下被测**。
+
+**对已升级的人(包括报告者)为时已晚**——他们的登出发生在修复发布之前。它有效的是"下一次升级的人不必再付这笔代价"。
+
+## 四、这一轮的自我更正
+
+**第一个缺陷是我两条命令之前刚引入的**:同一轮里我先修了"向外读错",又在修"等待误建"时把轮询从创建改成只读,**中间那版一度让"标签数没增加"被误判成"侧栏没挂载"**——而 `openTabIn` 对同类页面是**去重**的,所以那个判据会把"已经持有该页面"读成"未挂载",于是"打开过的地址反而打不开"。判据改为**"从 0 到 0"**才是真信号,那条守护用例在写出来的当次就抓到了同批的一个 `created` 恒真错误。
+
+**发布**:0.4.6。`npm` 与仓库同步——**没发出去的修复等于没有修复**。
+
+---
+
 # 第四十一轮(2026-10-06,桌面端:会话串扰的真正根因,以及一次架构级改正)
 
 用户报的症状只有一句:**"还是其他窗口的侧栏"**。前几轮都在 owner 台账上加检查,这一轮做的第一件事是**不采信台账的立论,把它实测一遍**。

package/client.js

@@ -617,15 +617,30 @@ window.__ModuleLoader__.load({ id: "dsh-builtin-browser", factory: (require) =>
     return null
   }
 
-  /** Every live `<webview>` guest inside this conversation's panel subtree. */
+  /**
+   * Every live `<webview>` guest inside this conversation's panel subtree.
+   *
+   * The walk up stops the moment an ancestor carries ANOTHER conversation's sidebar, and that stop
+   * condition is the whole point of this function. The shell mounts every conversation's panel in
+   * the same document — hidden ones included — so one step too far lands on a subtree that holds
+   * all of them, and the first guest found there belongs to whichever conversation the shell
+   * happens to render first. Measured: a GitHub login page opened in a different conversation was
+   * reported as this one's guest, which is the cross-conversation bleed this service exists to
+   * prevent. A sibling strip is the exact, class-name-independent signature of having stepped
+   * outside; a conversation may legitimately own more than one strip of its own, so the test is
+   * "is there one that is NOT mine", never a count.
+   */
   function guestsInPanel(sessionId) {
     const strip = tabStripFor(sessionId)
     if (strip === null) return []
-    // Walk up to the first ancestor that owns a guest: the strip itself is outside the
-    // body region, so the search starts low and stops as soon as it has one. It never
-    // crosses out of this conversation's branch, which is what keeps it scoped.
+    // Start at the strip itself: it is by construction this conversation's own, so the foreign test
+    // below cannot trip on it, and a shell that renders the guest as a sibling of the strip is
+    // still reached.
     let node = strip
     while (node !== null && node !== undefined && node !== document.body) {
+      const foreign = Array.from(node.querySelectorAll("[class*=_tabStrip]"))
+        .some(el => sessionIdOfElement(el) !== sessionId)
+      if (foreign) break
       const found = Array.from(node.querySelectorAll("webview")).filter(view => {
         try { return typeof view.getWebContentsId === "function" && view.getWebContentsId() > 0 }
         catch (error) { return false }

package/desktop-bridge/plugin-browser-bridge.js

@@ -238,17 +238,26 @@ async function sendCdp(id, method, params) {
  *
  * @param shellId - the shell window's webContents id.
  * @param sessionId - the conversation that asked (the request's `owner`).
- * @param url - address to load when a panel has to be opened; empty to only read.
+ * @param url - address to load when a panel has to be opened; `null` to only READ.
  * @returns the renderer's verdict, normalized so a malformed answer is a named failure.
  */
 async function evaluatePanelService(shellId, sessionId, url) {
+  // `null` means read-only. This distinction is not cosmetic: `openPanel` CREATES a tab when the
+  // conversation has none, so polling with it turned a 20-second wait into one empty tab every
+  // 250ms — the "it opens a pile of blank pages at once" report. A wait must never be a write.
+  const reading = url === null
+  const call = reading
+    // `panelGuest` reports state, not success, so the read form supplies the verdict itself: a
+    // conversation with no panel yet is a legitimate answer to "what do you have", not a failure.
+    ? `JSON.stringify({ ok: true, ...api.panelGuest(${JSON.stringify(String(sessionId))}) })`
+    : `JSON.stringify(api.openPanel(${JSON.stringify(String(sessionId))}, ${JSON.stringify(String(url ?? ''))}))`
   const expression = `(() => {
     const api = globalThis.__dshBuiltinBrowser;
     if (api === undefined || api === null || typeof api.openPanel !== 'function') {
       return JSON.stringify({ ok: false, reason: 'the plugin client half is not loaded in this window' });
     }
     try {
-      return JSON.stringify(api.openPanel(${JSON.stringify(String(sessionId))}, ${JSON.stringify(String(url ?? ''))}));
+      return ${call};
     } catch (error) {
       return JSON.stringify({ ok: false, reason: String((error && error.message) || error) });
     }
@@ -361,7 +370,9 @@ async function handle(request) {
     }
 
     const ask = async (withUrl) => {
-      const answer = await evaluatePanelService(shell.id, owner, withUrl ? url : '')
+      // `null` reads, a string places or navigates. Every round of the wait below uses the READ
+      // form, because a wait must never create anything.
+      const answer = await evaluatePanelService(shell.id, owner, withUrl ? url : null)
       if (answer.ok !== true) {
         // Carry the renderer's own findings into the failure: it is the side that can see why the
         // lookup missed, and a bare "not mounted" leaves the next reader guessing between a real
@@ -423,9 +434,9 @@ async function handle(request) {
     // human was looking at. Reported as issue #23; the other two carriers already did this
     // (the self-hosted window re-adds the view, the system browser calls Page.bringToFront).
     //
-    // The tab belongs to the renderer, so the same reasoning as `ensureTabs` applies: drive the
-    // sidebar's own control. A tab is matched by the title it shows, which is what the sidebar
-    // renders from the guest — the guest's id is not exposed in the DOM.
+    // The tab strip belongs to the renderer, so raising one means asking the sidebar to do it. A
+    // tab is matched by the title it shows, which is what the sidebar renders from the guest —
+    // the guest's id is not exposed in the DOM.
     const viewId = Number(request.viewId)
     if (!Number.isFinite(viewId)) throw new Error('showTab needs a viewId')
     const guest = webContents.fromId(viewId)

package/lib/browser-electron/bridge-connection.d.ts

@@ -23,6 +23,7 @@ export interface BridgeEndpoint {
 export declare class BridgeConnection {
     private endpoint;
     private readonly endpointPath?;
+    private readonly onLost?;
     private socket;
     private buffer;
     /** Outstanding requests by id. */
@@ -34,11 +35,14 @@ export declare class BridgeConnection {
     private idLessBridge;
     /** True once this connection may only have one request in flight at a time. */
     private serialisable;
+    /** True once the shell behind this connection has been reported gone. */
+    private lostNotified;
     /**
      * @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(endpoint: BridgeEndpoint, endpointPath?: string | undefined);
+    constructor(endpoint: BridgeEndpoint, endpointPath?: string | undefined, onLost?: (() => void) | undefined);
     /**
      * Re-read the published endpoint, and adopt it if the shell has moved.
      *
@@ -53,6 +57,8 @@ export declare class BridgeConnection {
      * @returns true when a different endpoint was adopted.
      */
     private refreshEndpoint;
+    /** Report once that the shell is gone, so the surface can fall back instead of dialling it. */
+    private notifyLost;
     /**
      * Send one request, reusing the socket if it is still healthy.
      *

package/lib/browser-electron/bridge-connection.js

@@ -33,6 +33,15 @@ const MAX_BUFFER_BYTES = 128 * 1024 * 1024;
  * client then falls back to arrival order, which is what the protocol guaranteed before.
  */
 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.
  *
@@ -51,6 +60,7 @@ const REQUEST_ID_FIELD = 'bridgeRequestId';
 export class BridgeConnection {
     endpoint;
     endpointPath;
+    onLost;
     socket;
     buffer = '';
     /** Outstanding requests by id. */
@@ -62,13 +72,17 @@ export class BridgeConnection {
     idLessBridge = false;
     /** True once this connection may only have one request in flight at a time. */
     serialisable = false;
+    /** True once the shell behind this connection has been reported gone. */
+    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(endpoint, endpointPath) {
+    constructor(endpoint, endpointPath, onLost) {
         this.endpoint = endpoint;
         this.endpointPath = endpointPath;
+        this.onLost = onLost;
     }
     /**
      * Re-read the published endpoint, and adopt it if the shell has moved.
@@ -90,6 +104,13 @@ export class BridgeConnection {
             const raw = JSON.parse(readFileSync(this.endpointPath, 'utf8'));
             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 = {
@@ -105,6 +126,18 @@ export class BridgeConnection {
             return false;
         }
     }
+    /** Report once that the shell is gone, so the surface can fall back instead of dialling it. */
+    notifyLost() {
+        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.
      *
@@ -126,6 +159,14 @@ 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'));
@@ -281,8 +322,22 @@ export class BridgeConnection {
             entry.reject(error);
     }
 }
-/** The request id a raw answer line echoes back, when it carries one. */
-function echoOf(line) {
+/**
+ * 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) {
+    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) {
     try {
         const answer = JSON.parse(line);
         const value = answer[REQUEST_ID_FIELD];

package/lib/browser-electron/desktop-bridge-host.d.ts

@@ -94,10 +94,21 @@ export declare class DesktopBridgeViewHost implements ElectronBrowserViewHost {
      * the desktop sidebar is the carrier — by design, not by omission.
      */
     private userActionHandler;
+    /** Told when the shell behind this bridge exits; see `onLost`. */
+    private lostListener;
     /**
      * @param endpoint - the shell's published bridge endpoint.
      */
     private constructor();
+    /**
+     * 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;
+    /** Register the "this carrier is gone" listener (see the interface's `onLost`). */
+    onLost(listener: () => void): void;
     /**
      * Find a usable desktop bridge, if this surface has one.
      *

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

@@ -111,12 +111,32 @@ export class DesktopBridgeViewHost {
      * the desktop sidebar is the carrier — by design, not by omission.
      */
     userActionHandler;
+    /** Told when the shell behind this bridge exits; see `onLost`. */
+    lostListener;
     /**
      * @param endpoint - the shell's published bridge endpoint.
      */
     constructor(endpoint, sessionId) {
         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.
+     */
+    reportLost() {
+        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) {
+        this.lostListener = listener;
     }
     /**
      * Find a usable desktop bridge, if this surface has one.

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

@@ -42,3 +42,23 @@ export declare const Config: z<Config>;
 export declare function apply(ctx: Context & {
     browser: BrowserRuntime;
 }, config: Config): void;
+/**
+ * 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 declare function adoptLegacyProfileRoot(profileRoot: string, legacyRoot?: string): void;