dsh-builtin-browser 0.4.10 → 0.4.13

package/CHANGELOG.md

@@ -4,6 +4,121 @@
 
 ---
 
+# 第五十轮(2026-10-17,对齐 DSH 0.2.1 的插件契约 + 工具描述瘦身)
+
+## 一、版本范围改到 DSH 真正读取的位置
+
+DSH 从 0.2.1-alpha.3 起改成:**有 `engines.dsh` 就只看它**,`@deepseek-ai/dsh*` 的 `peerDependencies` 被忽略;没有才回退到 peer 规则(官方指南 `docs/upgrade-guide/v0.2.1-alpha.3/plugin-engines-dsh/`)。
+
+本插件原来把范围写在 **`dsh.compatibility.dsh`** —— **那一块没有任何代码读取**(在 `packages/boot` 里搜 `manifest.dsh` 只命中 `dsh.bundle` 与 `dsh.profile.bundles`,`dshReleases` 零匹配)。当时的兼容完全是 peer 回退规则顺带成立的,而且声明下限还与 peers 不一致。
+
+现在 `engines.dsh: ">=0.1.1-rc.2 <0.3.0"`,与 peers 逐字相同。用 DSH 自己的 `evaluatePluginCompatibility` 验证:改前改后在 `0.2.1-rc.1` 上都是 compatible,`0.3.0` 与 `0.1.0-rc.8` 两个方向都被 BLOCKED,非字符串取值被明确拒绝。
+
+## 二、更新路径改成两步
+
+`plugin-install-over-installed`(0.2.1-alpha.2):`installBundle` 对已依赖的包**在跑 pnpm 之前就失败**,报 `already-installed`(代码证据:`plugin-manager/src/index.ts:439`、`:444`)。原文档写的"更新它 = 把依赖更新到新版本"照做会撞上这个失败。已改为明确的 `remove` 然后 `add <版本>`,两版 README 与用户指南都同步。
+
+## 三、工具描述瘦身(省 5%)
+
+先测量,再动手。34 个工具的**模型可见**开销是 `name + description + parameters` —— 注意**不含 `output.schema`**:DSH 的 `schemaOf()` 只投影前三个字段,所以第一版把 `output` 算进去得出的 79k 字符 / 22k tokens 是**高估**,实际是 20,348 字符 / 约 5,650 tokens。
+
+据此重排优先级:参数 9,782 字符(48%)、描述 9,932 字符(49%),平均每个工具 166 tokens —— **已经算紧凑**,所以"精简能省一大截"不成立。
+
+只压最长的 6 条描述(restrict / screenshot / auth / click / open / fill / a11y),保留全部操作约束、参数含义与安全警告,删掉解释性从句与重复列举。结果:
+
+| | 改前 | 改后 |
+| --- | --- | --- |
+| 描述合计 | 9,932 字符 | 8,932 字符 |
+| 模型可见合计 | 20,348 字符 | 19,348 字符 |
+| 估算 token | 约 5,650 | 约 5,374 |
+
+**收益 5%,如实记录**:不是数量级改进,但它是确定性的、无风险的部分。
+
+## 四、评估后不做的两条
+
+- **`presentationMeta`**:查了 `packages/core/tools/src/presentation.ts`,它是把结构化数据存进会话日志、由 `presentResult` 读回来渲染成**特定卡片类型**(`card: 'read'`、`'search'`)。UI 只认已定义的卡片,浏览器元素没有对应类型,加了只会回退到原始文本 —— **收益为零**,不做。
+- **`ToolSchema.deferLoading`**:看似正是为这种情况设计的(Anthropic 的 `defer_loading`)。但 DSH 的语义是"延迟的基线工具仍需一次 tool-addition 才能激活",且在不支持 tool-update 的路由上标志会被**剥掉、全部立即加载**。插件单方面标记它的风险是工具直接不可用,不做。
+
+**真正能省一个量级的是 PTC 模式**:prompt 里从 34 个工具变成 `run_code` 一个入口,省掉约 5,000 tokens。但它需要宿主有 `ctx.ptcRuntime` 且 agent preset 切到 `mode: ptc` —— **插件无法单方面启用**,只能写进文档由使用者选择。
+
+## 五、验证
+
+- `scripts/verify-host-compat.mjs` 在 **0.2.1-rc.1** 上全绿:34 个工具注册、`dsh_browser_session` 与 `dsh_browser_a11y` 实跑成功;
+- DSH 自己的 `evaluatePluginCompatibility` 对改动前后、四个版本边界逐一验证;
+- **测试 290 → 290(289 通过 + 1 条平台门控跳过)**,`tsc` 干净。
+
+---
+
+# 第四十九轮(2026-10-17,DSH 0.2.1 的兼容性新规:版本范围必须写在 `engines.dsh`)
+
+DSH 升到 **`0.2.1-rc.1`** 后,兼容性判定规则变了。本插件把版本范围写在一个**没有任何代码读取**的位置,当时的"兼容"是靠回退规则蒙对的。
+
+## 一、规则变了什么
+
+官方迁移指南:`docs/upgrade-guide/v0.2.1-alpha.3/plugin-engines-dsh/`(英文/中文各一份)。判定实现在 `packages/boot/app-boot/src/plugin-compatibility.ts`。
+
+**新规**:**有 `engines.dsh` 就只看它**,`@deepseek-ai/dsh` 与 `@deepseek-ai/dsh-*` 的 `peerDependencies` **被忽略**;**没有** `engines.dsh` 才回退到 peer 规则。另有三条附带约束:
+
+- `engines.dsh` 里**不接受** `workspace:` 值(只有 peers 接受),写成那样等于声明不兼容;
+- 非对象 `engines` 或非字符串 `engines.dsh` → manifest 对兼容性而言**不可读** → 拒绝该包;
+- `IncompatiblePlugin` / `PluginCompatibility` 的 `peers` 字段**改名为 `requirements`**,键为 `engines.dsh` 或 peer 包名。
+
+## 二、本插件的处境
+
+范围原来写在 **`dsh.compatibility.dsh`**:`>=0.1.1-rc.1 <0.3.0`。**那一块没有任何代码读取** —— 在 `packages/boot` 里搜 `manifest.dsh` 只命中 `dsh.bundle` 与 `dsh.profile.bundles`,`dshReleases` 零匹配。当时的兼容完全是 peer 回退规则(`@deepseek-ai/dsh-*: >=0.1.1-rc.2 <0.3.0`)顺带成立的。
+
+于是这个声明在两个意义上都是虚的:写在没人读的地方,而且它的下限也与 peers 的 `<0.1.1-rc.2` 不一致。
+
+## 三、改法
+
+`engines` 里加 `dsh: ">=0.1.1-rc.2 <0.3.0"`,**与 peers 逐字相同**。迁移指南第 1 条明确要求"范围必须覆盖所有支持的 release,因为 peers 不再增减它" —— 取与 peers 相同的值,是保证"换规则前后答案不变"最直接的方式。
+
+`dsh.compatibility` 块保留但**去掉 `dsh` 字段**,并加 `_comment` 说明它现在只是给人看的兼容性记录、不参与任何判定;`dshReleases` 补记 `0.2.1-rc.1`。留着比删掉好 —— 逐版本的支持记录对人有价值,而且它不会被误认为判定依据了:真正的判据在 `engines.dsh` 里一眼可见。
+
+第三条不受影响:插件代码从不读 `IncompatiblePlugin` / `PluginCompatibility`(`src/` 里那三处 `requirements` 是注释里对需求文档的引用,与 API 无关)。
+
+## 四、验证:用 DSH 自己的判定函数
+
+不靠推断,直接 import `packages/boot/app-boot/lib/types/plugin-compatibility.js` 里的 `evaluatePluginCompatibility`:
+
+| manifest | `engines.dsh` | 0.2.1-rc.1 上的判定 |
+| --- | --- | --- |
+| 改之前 | 无(靠 peers 回退) | compatible |
+| 改之后 | `>=0.1.1-rc.2 <0.3.0` | compatible |
+
+范围真的生效,两个方向都试了:`0.3.0` → BLOCKED、`0.1.0-rc.8` → BLOCKED、`0.2.0-rc.2` → compatible;非字符串的 `engines.dsh` 被明确拒绝(`Plugin manifest engines.dsh must be a string`)。
+
+**改前改后都是 compatible,这一点值得说清楚**:这一轮不是修一个"装不上"的故障,而是把一个**恰好成立的默认**换成**显式成立的声明**。区别在于今后 DSH 再收紧规则、或有人照着 `dsh.compatibility` 去改范围时,行为会与声明一致,而不是继续靠巧合。
+
+**测试**:285 → 290(新增 5 条:`tests/manifest-compatibility.test.mjs`)。其中一条直接调用 DSH 的判定函数,在 checkout 不存在时跳过(CI 上没有那个 checkout);另一条守住下面那条文档要求。`tsc` 干净。
+
+## 五、其余迁移指南逐条核对(结论:一条要改文档,其余无关)
+
+0.2.1 前后共有 40 余份迁移指南。按"本插件是否用到被改动的 API/配置"逐条核对,用 grep 确认而非推断:
+
+| 指南 | 是否影响 | 依据 |
+| --- | --- | --- |
+| `plugin-engines-dsh` | **是,已改** | 见上文 |
+| `plugin-install-over-installed` | **是,改文档** | 见下 |
+| `tool-presentation-mode` | 否 | 搜索 `presentAs` / `mode: both` / `DSH_TOOLS_MODE` 零匹配 |
+| `jsonl-persistence-plugin` | 否 | 不使用 `sessionPersistence`,自有一份 history 存储 |
+| `web-listener-trust-config` | 否 | 不注入 `webRuntime`,设置路由走 `ctx.webServer` |
+| `remove-runtime-invariants` | 否 | 不导入 `@deepseek-ai/dsh-invariants` |
+| `working-directory` | 否 | 34 个工具用的 `output` 是返回值 JSON Schema,不是 `output.presentationMeta`(该字段零匹配) |
+| `instruction-home-override` | 否 | 不配置 `agent-instructions` |
+| `subpath-plugin-display-manifest` | 否 | 本包是包根插件,不是子路径插件 |
+| `plugin-option-placement` | 否 | 那是 CLI 参数位置,不影响已安装的包 |
+| `experimental-package-composition` | 否 | 本包的 `dsh.bundle.patch` 是完整 insertion,不是"只启用被移除的行" |
+| `new-session-generations`、`account-*`、`pi-ai-*`、`sdk-*`、`subagent-*`、`python-*`、`desktop-*`、`schedule-*` 等 | 否 | 均不涉及浏览器插件使用的任何接缝 |
+
+**`plugin-install-over-installed` 要改的是文档,不是代码**:从 0.2.1-alpha.2 起,`installBundle` 对 profile 已依赖的包**在跑 pnpm 之前就失败**,报 `already-installed`,且不改任何 profile 文件。代码侧证据:`packages/boot/plugin-manager/src/index.ts:439`、`:444` 的 `refused('already-installed', ...)`,以及 `tools.ts:18` 的错误文案本身就写着"to install another version, call remove_bundle first, then install_bundle again"。
+
+原来的文档只说"更新它 = 把依赖更新到新版本",**照做会撞上这个失败**。已改为明确的两步(`remove` 然后 `add <版本>`),并写明替代路径(Web 插件管理页的 Update 按钮会自己先移除再安装),README 中英两版都加了这一步的提示。
+
+这一条加了一条守护测试:断言文档里 `remove` 出现在 `add` 之前,且 README 两版都带这步 —— 否则下次改文档时很容易又把一步写回去。
+
+---
+
 # 第四十八轮(2026-10-16,实机四载体检验:三次误判、一个真 bug、一个跨载体缺陷)
 
 YG 要求逐个检验四种载体(侧栏 / 自托管 / Chrome / Edge)能否正常拉开并操作。检验过程里我犯了一个贯穿始终的错误,也发现了两个真实缺陷。

package/README.en.md

@@ -27,6 +27,8 @@ In one line: **install the plugin and you have a real browser shared with, and d
 
 **First, which side are you on** — these are two separate installs; updating one does not update the other, and they host the browser differently.
 
+> **Updating an installed plugin takes two steps** (since DSH 0.2.1-alpha.2, installing over an installed package fails outright with `already-installed`): run `dsh plugin --profile <profile> remove dsh-builtin-browser` first, then `add` the target version. See the [user guide](docs/user-guide.md) (Chinese).
+
 ### DSH Desktop
 
 ```sh

package/README.md

@@ -27,6 +27,8 @@
 
 **先确认你在哪一端** —— 两端是两份独立安装,**更新其中一端不会带上另一端**,浏览器的承载方式也不同。
 
+> **更新已安装的插件是两步**(DSH 0.2.1-alpha.2 起,对已装包再装会直接报 `already-installed`):先 `dsh plugin --profile <profile> remove dsh-builtin-browser`,再 `add` 目标版本。详见[用户指南](docs/user-guide.md#先移除再安装)。
+
 ### DSH Desktop(桌面端)
 
 ```sh

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

@@ -609,6 +609,20 @@ async function handle(request) {  const op = String(request?.op ?? '')
 }
 
 
+/**
+ * When the bridge instance currently running was constructed.
+ *
+ * Recorded once and republished unchanged, because a reader uses it to answer "how long has this
+ * bridge been up". Refreshing it on every keepalive made it mean "the last keepalive" instead: a
+ * reporter read two values 15 seconds apart, concluded the bridge had restarted, and only noticed
+ * otherwise because the port had not changed. Each module evaluation gets its own value, so a
+ * genuinely new instance is still reported as such.
+ */
+const instanceStartedAt = (() => {
+  const at = new Date().toISOString()
+  return () => at
+})()
+
 /**
  * Publish the endpoint, and keep it published.
  *
@@ -624,7 +638,7 @@ function publishEndpoint(port, token) {
     port,
     token,
     pid: process.pid,
-    startedAt: new Date().toISOString(),
+    startedAt: instanceStartedAt(),
     updatedAt: new Date().toISOString(),
   }
   try {

package/docs/development.md

@@ -31,8 +31,16 @@ node scripts/verify-host-compat.mjs
 
 它用某个 profile 里**真实安装**的 `@deepseek-ai/*` 包组装一个宿主,加载本插件的编译产物、经宿主自己的 `defineTool` 注册工具、再用一个假 provider 真调两个工具(`dsh_browser_session` / `dsh_browser_a11y`)。默认读 `$DSH_HOME/profiles` 下的 profile,可用 `DSH_PROFILE` / `DSH_HOME` 指定。
 
-## 关于 peer 范围的 semver 语义
+## 关于 DSH 版本范围
 
-插件声明 `>=0.1.1-rc.2 <0.3.0`。这个范围在 **semver 默认语义**下**不匹配**任何带预发布标签的版本(如 `0.2.1-alpha.1`)—— 这是规范行为:预发布只被"同一 major.minor.patch 元组"的比较器允许。
+插件在 **`engines.dsh`** 里声明 `>=0.1.1-rc.2 <0.3.0`。
 
-DSH 判定插件兼容性时用的是 `includePrerelease: true`(`packages/boot/app-boot/src/plugin-compatibility.ts`),因此这些预发布宿主**实际都在范围内**。若某个外部工具用默认语义得出"不兼容",那是它的语义与 DSH 不同,不是这里的声明写错了。
+位置不是随便选的。DSH 从 0.2.1-alpha.3 之后改成:**有 `engines.dsh` 就只看它,`@deepseek-ai/dsh*` 的 `peerDependencies` 被忽略;没有 `engines.dsh` 才回退到 peer 规则**(`packages/boot/app-boot/src/plugin-compatibility.ts`;官方迁移指南在 `docs/upgrade-guide/v0.2.1-alpha.3/plugin-engines-dsh/`)。
+
+本插件 0.4.12 之前把范围写在 `dsh.compatibility.dsh` 里 —— 那个位置**没有任何代码读取**,当时的兼容性实际是靠 peer 回退蒙对的。现在两处一致(`engines.dsh` 与 peers 同范围),所以哪条规则生效都得到同一个答案。
+
+这个范围在 **semver 默认语义**下**不匹配**任何带预发布标签的版本(如 `0.2.1-rc.1`)—— 规范如此:预发布只被"同一 major.minor.patch 元组"的比较器允许。
+
+DSH 判定时用的是 `includePrerelease: true`,因此这些预发布宿主**实际都在范围内**。若某个外部工具用默认语义得出"不兼容",那是它的语义与 DSH 不同,不是这里的声明写错了。
+
+`engines.dsh` 里不接受 `workspace:` 值(只有 peers 接受);写成那样等于声明不兼容。

package/docs/user-guide.md

@@ -160,7 +160,7 @@ DSH Desktop 上②命中即可用(0.1.18+ 插件自带 electron 包;44+ 二进
 
 | 组件 | 版本 |
 | --- | --- |
-| DeepSeek Harness(dsh) | `0.2.1-alpha.1`(peer 声明 `>=0.1.1-rc.2 <0.3.0`;更早的 `0.2.0-rc.2`、`0.1.x` 亦有实测记录) |
+| DeepSeek Harness(dsh) | `0.2.1-rc.1`(`engines.dsh` 声明 `>=0.1.1-rc.2 <0.3.0`;更早的 `0.2.1-alpha.1`、`0.2.0-rc.2`、`0.1.x` 亦有实测记录) |
 | Electron | `44.0.0`(推荐 ≥ 40;33.x 存在合成器缺陷) |
 | Node.js | `22.20.0` |
 | 本机 Chrome / Edge(可选载体) | `154.0.8037.58` / `154.0.4258.37` |
@@ -174,6 +174,23 @@ DSH Desktop 上②命中即可用(0.1.18+ 插件自带 electron 包;44+ 二进
 
 插件在两种宿主里各有一份安装,更新路径也不同 —— **更新其中一端不会连带更新另一端**。
 
+### 先移除,再安装
+
+**DSH 0.2.1-alpha.2 起,对已经装着的包再执行一次安装会直接失败**,报 `already-installed`,并且在跑 pnpm 之前就失败、不改任何 profile 文件(官方迁移指南:`docs/upgrade-guide/v0.2.1-alpha.2/plugin-install-over-installed/`)。这条在启用 HMR 的 profile 上生效,而自带 profile 都启用 HMR。
+
+所以更新一个**已安装**的插件是两步:
+
+```bash
+dsh plugin --profile web remove dsh-builtin-browser
+dsh plugin --profile web add dsh-builtin-browser@<目标版本>
+```
+
+移除会停掉该 bundle 的插件并清掉它的包映射,新版本随即重新映射,因此**不需要重启**就能生效(桌面端仍需重启,理由见下)。
+
+替代做法:Web 界面的插件管理页对官方插件提供 Update 按钮,它自己会先移除再安装。桌面端尚无可用的新版,按上面的两步来。
+
+## 桌面端细节
+
 **桌面端(DSH Desktop)**
 
 - 插件是桌面端 profile 里的依赖(profile 目录通常是 `$DSH_HOME/profiles/desktop`)。更新它 = 把该 profile 里的依赖更新到新版本,然后**重启 DSH Desktop**,客户端设置栏与工具才会换成新代码。
@@ -186,12 +203,14 @@ DSH Desktop 上②命中即可用(0.1.18+ 插件自带 electron 包;44+ 二进
 - 浏览器内核默认由桌面端自带的 Electron 提供,插件不会再下载一份 Electron;也可以在设置里改用它自己装的 Chrome / Edge。
 - **升级桌面端本身不会带上插件**,按上面的方法单独更新它。
 
+## Web 端细节
+
 **Web 端(`dsh web`)**
 
 - 插件是 web profile 里的依赖(`$DSH_HOME/profiles/web`),更新后**重启 `dsh web`** 生效。
 - Web 端**没有侧栏、也没有 bridge**:共享浏览器由插件自托管拉起。首次安装可能需要 Electron 二进制;若包管理器的构建白名单拦下了它(pnpm v10+ 会拦 `electron` 的 postinstall),执行一次 `npx install-electron` 补上即可。
 - 同样可以在设置里改用本机 Chrome / Edge —— 这是两端**行为一致**的选项。
-- 更新方式与首次安装它时一致(按 npm 包名 `dsh-builtin-browser`、按 GitHub 仓库 `wqty123/dsh-browser`,或本地目录)。
+- 更新方式与首次安装它时一致(按 npm 包名 `dsh-builtin-browser`、按 GitHub 仓库 `wqty123/dsh-browser`,或本地目录),但**已安装时先按上面的两步移除再装**。
 
 **两端一致的体验**
 

package/lib/browser/types.d.ts

@@ -472,6 +472,22 @@ export interface CarrierPage {
     readonly url: string;
     readonly title?: string;
 }
+/**
+ * Why a carrier reported that it can no longer be used.
+ *
+ * Two different failures reach the same fallback, and saying which one is the difference between a
+ * message a user can act on and one that misleads them:
+ *
+ * - `shell-exited`: the shell process behind the carrier is gone. Its published endpoint stops
+ *   being refreshed, which is the condition the fallback was originally written for.
+ * - `panel-unusable`: the shell is alive and answering, but its sidebar panel cannot provide a page
+ *   — on a shell that renders that panel as an iframe there is no webContents and no CDP endpoint,
+ *   so the carrier is undrivable rather than merely unready.
+ *
+ * The fallback announced the first of these unconditionally, so a `panel-unusable` fallback told
+ * the user their desktop shell had exited while it was running normally. Reported as such.
+ */
+export type CarrierLossReason = 'shell-exited' | 'panel-unusable';
 /** Request to open a URL: into the active tab or a new tab. */ export interface BrowserOpenRequest {
     /** The URL to open. */
     readonly url: string;

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

@@ -24,7 +24,7 @@
  */
 import type { ElectronBrowserViewHost, ElectronViewHandle } from './provider.js';
 import type { BrowserUserAction } from './provider.js';
-import type { CarrierPage } from '../browser/types.js';
+import type { CarrierPage, CarrierLossReason } from '../browser/types.js';
 /** Absolute path of the endpoint file the shell writes. */
 export declare function bridgeEndpointPath(): string;
 /**
@@ -102,14 +102,15 @@ export declare class DesktopBridgeViewHost implements ElectronBrowserViewHost {
      */
     private constructor();
     /**
-     * Called by the transport once the shell behind it is gone.
+     * Called when this carrier concludes it cannot serve anything more.
      *
      * 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.
+     * @param reason - which failure this was, so the fallback can say so accurately.
      */
     private reportLost;
     /** Register the "this carrier is gone" listener (see the interface's `onLost`). */
-    onLost(listener: () => void): void;
+    onLost(listener: (reason: CarrierLossReason) => void): void;
     /**
      * Find a usable desktop bridge, if this surface has one.
      *

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

@@ -118,17 +118,20 @@ export class DesktopBridgeViewHost {
      */
     constructor(endpoint, sessionId) {
         this.owner = sessionId !== undefined && sessionId !== String.fromCharCode(39, 39) ? sessionId : randomUUID();
-        this.connection = new BridgeConnection(endpoint, bridgeEndpointPath(), () => this.reportLost());
+        // The transport reaches this only by concluding the shell stopped refreshing its endpoint, which
+        // is `shell-exited`.
+        this.connection = new BridgeConnection(endpoint, bridgeEndpointPath(), () => this.reportLost('shell-exited'));
     }
     /**
-     * Called by the transport once the shell behind it is gone.
+     * Called when this carrier concludes it cannot serve anything more.
      *
      * 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.
+     * @param reason - which failure this was, so the fallback can say so accurately.
      */
-    reportLost() {
+    reportLost(reason) {
         try {
-            this.lostListener?.();
+            this.lostListener?.(reason);
         }
         catch {
             // The listener's failure is not the transport's problem.
@@ -326,8 +329,12 @@ export class DesktopBridgeViewHost {
             // shell whose sidebar panel is an iframe, that is every call forever. Reported as "installing
             // the bridge made it worse than not installing it": the carrier was switched to one that
             // cannot work, with no path back to the one that does.
+            //
+            // `panel-unusable`, not `shell-exited`: the shell is alive and answered this very request. The
+            // fallback's message used to announce an exiting shell unconditionally, which told the user
+            // their desktop had crashed when it was running normally.
             if (String(answer.error).includes('produced no page'))
-                this.reportLost();
+                this.reportLost('panel-unusable');
             throw new Error(`dsh-builtin-browser: sidebar unavailable (${String(answer.error)})`);
         }
         const id = Number(answer.id);

package/lib/browser-electron/entry.js

@@ -127,19 +127,29 @@ export function apply(ctx, config) {
      *
      * 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.
+     * once and only in one direction. Reaching here means the carrier cannot serve anything more, 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.
+     *
+     * Two failures arrive here and the message must distinguish them. The first draft announced an
+     * exiting shell unconditionally, so a fallback caused by an undrivable sidebar panel told the
+     * user their desktop shell had exited while it was running normally.
      * @param adopted - the carrier that reported the loss, disposed once its replacement is in place.
+     * @param reason - which failure this was; see {@link CarrierLossReason}.
      */
-    const restoreSelfHosted = (adopted) => {
+    const restoreSelfHosted = (adopted, reason) => {
         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.');
+            ctx.logger?.warn?.(reason === 'shell-exited'
+                ? '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.'
+                : 'dsh-builtin-browser: this desktop shell renders the sidebar browser panel in a way that '
+                    + 'cannot be driven (no webContents, so no CDP endpoint), so the browser this plugin hosts '
+                    + 'itself takes over. The shell is still running and nothing else is affected; the page '
+                    + 'opens in this plugin\'s own window. Set browser.channel to another value to silence this.');
         }
         catch (error) {
             // Nothing better is available: the adopted carrier is gone and a provider that throws is
@@ -147,7 +157,21 @@ export function apply(ctx, config) {
             ctx.logger?.warn?.(`dsh-builtin-browser: could not fall back to the self-hosted browser: ${String(error)}`);
         }
         finally {
-            adopted.dispose?.();
+            // Disposed on a LATER turn of the event loop, deliberately.
+            //
+            // Disposing synchronously here closes the bridge socket while the request that triggered this
+            // fallback is still settling, and the close rejects every call still waiting on that socket —
+            // so the caller received "bridge closed" instead of the reason it actually failed for. The
+            // fallback is what the user is supposed to be able to understand; replacing its explanation
+            // with one about the connection loses exactly the information this path exists to convey.
+            setImmediate(() => {
+                try {
+                    adopted.dispose?.();
+                }
+                catch {
+                    // A carrier that cannot be released is not the caller's problem; the swap already happened.
+                }
+            });
         }
     };
     /**
@@ -169,7 +193,7 @@ export function apply(ctx, config) {
             // 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); });
+            host.onLost?.(reason => { restoreSelfHosted(host, reason); });
             const previous = adoptedCarrier;
             adoptedCarrier = host;
             // Released AFTER the replacement is installed, so the surface is never without a provider.

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

@@ -9,7 +9,7 @@
 import { type VisitedPage } from './history-store.js';
 import type { BrowserSettings } from './settings-store.js';
 import type { BrowserA11yRequest, BrowserA11yResult, BrowserChallenge, BrowserCheckRequest, BrowserClearRequest, BrowserClickRequest, BrowserContentRequest, BrowserContentResult, BrowserElementTarget, BrowserExecuteRequest, BrowserExecuteResult, BrowserFillRequest, BrowserFillResult, BrowserGetValueRequest, BrowserGetValueResult, BrowserHistoryEntry, BrowserOpenRequest, BrowserProvider, BrowserScrapeRequest, BrowserScrapeResult, BrowserScreenshotRequest, BrowserSelectRequest, BrowserSelectResult, BrowserSessionId, BrowserSetValueRequest, BrowserSetValueResult, BrowserSnapshotResult, BrowserTab, BrowserTypeRequest, BrowserWaitRequest, BrowserWaitResult, BrowserScrollRequest, BrowserKeyRequest, ExportedCookie } from '../browser/types.js';
-import type { CarrierPage } from '../browser/types.js';
+import type { CarrierPage, CarrierLossReason } from '../browser/types.js';
 /** Stable provider id registered with `ctx.browser`. */
 export declare const ELECTRON_BROWSER_PROVIDER_ID = "electron";
 /**
@@ -157,9 +157,14 @@ export interface ElectronBrowserViewHost {
      * 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.
+     *
+     * The listener receives WHY, because the fallback's message has to match what happened: a shell
+     * that exited and a shell whose panel cannot provide a page both reach the same fallback, and
+     * announcing "the shell has exited" for the second tells the user their desktop crashed when it
+     * did not.
      * @param listener - called once, when the carrier concludes it is gone.
      */
-    onLost?(listener: () => void): void;
+    onLost?(listener: (reason: CarrierLossReason) => void): void;
     /**
      * Fold the carrier's presentation away while keeping the page alive.
      *

package/lib/browser-electron/system-browser.js

@@ -699,11 +699,38 @@ export class SystemBrowserViewHost {
         // The port file is deliberately NOT deleted here, and that is a reversal.
         //
         // It used to be removed so the launch loop below could not read a previous browser's port. But
-        // the loop already refuses any file older than the spawn (`freshPort` compares mtimes), so the
-        // deletion never protected it — while it DID destroy the only record of a browser that may
-        // still be running for this profile. That record is what `adoptRunningBrowser` needs when the
-        // launch comes back as a hand-off: the browser was alive the whole time, and without the file
-        // there is no way to find it again.
+        // the loop judges freshness against a snapshot taken below, so the deletion never protected it
+        // — while it DID destroy the only record of a browser that may still be running for this
+        // profile. That record is what `adoptRunningBrowser` needs when the launch comes back as a
+        // hand-off: the browser was alive the whole time, and without the file there is no way to find
+        // it again.
+        const portFile = join(this.profileDir, 'DevToolsActivePort');
+        /**
+         * What the port file was like BEFORE this launch, so "fresh" is judged against a snapshot
+         * rather than against a clock.
+         *
+         * The test used to be `mtimeMs < spawnedAt` — a filesystem timestamp compared to `Date.now()`.
+         * Those are different clocks with different resolutions, and CI is where it showed: a file the
+         * fake browser had just written was rejected as stale, so the loop waited out its full 30s
+         * against a browser that was already listening, because the file's mtime had rounded down
+         * below the spawn time. That is not a test-only problem: on any filesystem whose mtime
+         * resolution is coarser than a millisecond, the plugin would fail to see the browser it had
+         * just launched, and report a CDP timeout for a browser that was up the whole time.
+         *
+         * `undefined` means there was no file, so any file that appears afterwards is fresh. When one
+         * existed, a later mtime OR different contents makes the new one fresh. Byte-identical contents
+         * with an unchanged mtime is the PREVIOUS browser's port, and adopting it is what this whole
+         * check exists to prevent: it may name a port that now belongs to something else entirely.
+         */
+        const portFileBefore = (() => {
+            try {
+                return { mtimeMs: statSync(portFile).mtimeMs, contents: readFileSync(portFile, 'utf8') };
+            }
+            catch {
+                return undefined;
+            }
+        })();
+        // Kept for the failure message and for the exit listener's diagnostics; no longer a judgement.
         const spawnedAt = Date.now();
         let child;
         try {
@@ -739,22 +766,28 @@ export class SystemBrowserViewHost {
             // Clearing these is what makes the restart usable rather than merely alive.
             this.forgetBrowserState();
         });
-        const portFile = join(this.profileDir, 'DevToolsActivePort');
         /**
          * The port this launch wrote, or undefined while it has not written one yet.
          *
-         * A file left by the PREVIOUS browser is not evidence about this one. Its contents
-         * name a port that may now belong to something else entirely — another Chromium, a
-         * node --inspect — and connecting there publishes a client this host does not own and
-         * dispose() can never kill. Only a file written after the spawn counts.
+         * A file left by the PREVIOUS browser is not evidence about this one. Its contents name a port
+         * that may now belong to something else entirely — another Chromium, a `node --inspect` — and
+         * connecting there publishes a client this host does not own and dispose() can never kill.
+         * Only a file that CHANGED across this launch counts, which is what `portFileBefore` records.
          */
         const freshPort = () => {
             try {
                 if (!existsSync(portFile))
                     return undefined;
-                if (statSync(portFile).mtimeMs < spawnedAt)
+                const after = statSync(portFile);
+                const contents = readFileSync(portFile, 'utf8');
+                // Unchanged since before the launch: this is the previous browser's file, whatever its
+                // mtime says. Comparing against the snapshot rather than the spawn time is what keeps this
+                // correct on a filesystem whose timestamps are coarser than the clock behind spawnedAt.
+                if (portFileBefore !== undefined
+                    && after.mtimeMs <= portFileBefore.mtimeMs
+                    && contents === portFileBefore.contents)
                     return undefined;
-                const value = Number(readFileSync(portFile, 'utf8').split('\n')[0]?.trim() ?? '');
+                const value = Number(contents.split('\n')[0]?.trim() ?? '');
                 return Number.isInteger(value) && value > 0 ? value : undefined;
             }
             catch {

package/lib/tool-browser/index.js

@@ -319,7 +319,7 @@ export function apply(ctx, config = {}) {
     };
     registerSafely(defineTool({
         name: 'dsh_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. 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.',
+        description: 'Open a URL in the shared browser window and return the resulting snapshot. Opens this task\'s session on first use; newTab is optional. A fresh session starts on a blank 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 — it needs the authenticated URL printed by `dsh web`, and the bare root is refused.',
         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.' },
@@ -445,7 +445,7 @@ export function apply(ctx, config = {}) {
     }));
     registerSafely(defineTool({
         name: 'dsh_browser_a11y',
-        description: 'Read the page\'s accessibility tree: every interactive node with its semantic role (button/link/textbox/checkbox/…), accessible name, current value, and states (enabled/disabled/checked/expanded/…), (coordinates only when coords: true). Prefer this over dsh_browser_snapshot to understand a page\'s structure and find the right element: roles and names tell you WHAT each node is, and the name is what dsh_browser_click matches when you target by text. Penetrates same-origin iframes and shadow roots.',
+        description: 'Read the accessibility tree: every interactive node with its role (button/link/textbox/checkbox/…), accessible name, value, and states (enabled/checked/expanded/…); coordinates only with coords: true. Prefer this over dsh_browser_snapshot to understand structure and find the right element — roles and names say WHAT each node is, and the name is what dsh_browser_click matches when targeting by text. Penetrates same-origin iframes and shadow roots.',
         parameters: {
             includeHidden: { type: 'boolean', description: 'Include hidden elements (default false).' },
             maxNodes: { type: 'number', description: 'Maximum nodes (default 150, range 10-5000).' },
@@ -744,7 +744,7 @@ export function apply(ctx, config = {}) {
     }));
     registerSafely(defineTool({
         name: 'dsh_browser_click',
-        description: 'Click in the shared browser. Prefer the semantic target: pass target {by: css|text|xpath, value, index?} and the element is located from the DOM, scrolled into view and clicked at its centre — this needs no image input and is the only form that works without vision. The alternative is viewport coordinates (x/y), which are meaningful only after a vision model has located the element on a dsh_browser_screenshot; coordinate clicks are refused outright under the non-visual strategy. Provide exactly one of target or x/y.',
+        description: 'Click in the shared browser. Prefer target {by: css|text|xpath, value, index?}: the element is located from the DOM, scrolled into view, and clicked at its centre — no image input needed, and the only form that works without vision. Alternatively x/y viewport coordinates, meaningful only after a vision model located the element on a dsh_browser_screenshot; refused under the non-visual strategy. Provide exactly one of target or x/y.',
         parameters: {
             target: {
                 type: 'object',
@@ -965,7 +965,7 @@ export function apply(ctx, config = {}) {
     }));
     registerSafely(defineTool({
         name: 'dsh_browser_fill',
-        description: 'Fill a form in one batch: pass fields with a CSS selector or name/label/placeholder text and the value to set (string, number, or boolean for checkbox/radio; for selects or radio groups pass the option value or visible text). Values are applied with the native setter plus input/change events, so React/Vue controlled inputs update correctly. Optionally submit the containing form. Prefer this over hand-written dsh_browser_execute for form filling; per-field failures are reported instead of throwing.',
+        description: 'Fill a form in one batch: each field takes a CSS selector or name/label/placeholder text plus its value (boolean for checkbox/radio; option value or visible text for selects and radio groups). The native setter plus input/change events fire, so React/Vue controlled inputs update. Optionally submit the form. Prefer this over hand-written dsh_browser_execute; per-field failures are reported instead of throwing.',
         parameters: {
             fields: {
                 type: 'array',
@@ -1263,7 +1263,7 @@ export function apply(ctx, config = {}) {
     }));
     registerSafely(defineTool({
         name: 'dsh_browser_screenshot',
-        description: 'Capture the current shared-browser page as a screenshot (PNG default, JPEG optional). This is for models that can read images: layout checks, charts, designs, CAPTCHAs, or locating an element by eye before clicking its coordinates. A model without image input gains nothing from it — dsh_browser_snapshot, dsh_browser_a11y and dsh_browser_content carry the same page as text, and dsh_browser_scrape extracts structured data. Supports full-page capture, save-to-file, JPEG encoding, and downscaling (maxWidth/maxHeight) to cut vision-tool token cost. JPEG needs a browser whose CDP encoder works — the self-hosted browser and an installed Chrome/Edge; some carriers (the desktop sidebar) return PNG instead. Downscaling works on every carrier.',
+        description: 'Screenshot the shared-browser page (PNG default, JPEG optional) for models that can read images: layout, charts, CAPTCHAs, or locating an element before clicking its coordinates. Without image input it gains nothing — dsh_browser_snapshot/a11y/content carry the same page as text, dsh_browser_scrape extracts structured data. Supports fullPage, savePath, JPEG quality, and maxWidth/maxHeight downscaling to cut vision tokens. JPEG needs a carrier whose CDP encoder works (self-hosted, installed Chrome/Edge); the desktop sidebar returns PNG. Downscaling works everywhere.',
         parameters: {
             fullPage: { type: 'boolean', description: 'Capture the full scrollable page instead of the viewport (default false).' },
             savePath: { type: 'string', description: 'Absolute file path to also save the image to (e.g. for read_image vision location). Must resolve inside the configured downloadDir (default: the system Downloads folder, localized names such as ~/下载 included); an existing file is never overwritten.' },
@@ -1716,7 +1716,7 @@ export function apply(ctx, config = {}) {
     }));
     registerSafely(defineTool({
         name: 'dsh_browser_restrict',
-        description: 'Restrict which browser actions are allowed, to prevent stray clicks/navigation. Pass a list of browser tool names (e.g. ["dsh_browser_snapshot","dsh_browser_content","dsh_browser_click"]) — any other dsh_browser_* call is refused. Pass an empty list or omit to lift the restriction. Never blocked, whatever the list says: the observing tools (snapshot/a11y/content/scrape/screenshot/get_value/wait/challenge/list_tabs/session/history/visited) and the three that lift a restriction or recover from a bad state (restrict/reset/reset_session) — so a restriction can always be read around and undone. IMPORTANT: this is a SOFT guardrail against accidental actions, NOT a security boundary — you (the model) can lift it yourself with an empty list.',
+        description: 'Allow only the listed browser tools; any other dsh_browser_* call is refused. Empty list or omitted lifts it. Never blocked whatever the list says — the observing tools (snapshot/a11y/content/scrape/screenshot/get_value/wait/challenge/list_tabs/session/history/visited) and restrict/reset/reset_session — so a restriction can always be read around and undone. A SOFT guardrail against stray clicks, NOT a security boundary: you can lift it with an empty list.',
         parameters: {
             allowed: {
                 type: 'array',
@@ -1751,7 +1751,7 @@ export function apply(ctx, config = {}) {
     }));
     registerSafely(defineTool({
         name: 'dsh_browser_auth',
-        description: 'Export or restore the browser session\'s cookies (login state). Use "flush" to get a JSON cookie list (save it to a private file to persist logins), or "restore" with that list to put logins back (e.g. after the browser host restarted). Available on all three carriers: the self-hosted browser reads its own session, while the desktop sidebar and an installed Chrome/Edge go through CDP. Refused entirely when the credential switch is off. Exported cookies are LIVE CREDENTIALS: treat them as secrets — do not echo them into the conversation, keep them out of logs, and store the list in a private file.',
+        description: 'Export or restore the session\'s cookies (login state): "flush" returns a JSON cookie list, "restore" takes that list back (e.g. after the host restarted). Works on all carriers. Refused when the credential switch is off. Exported cookies are LIVE CREDENTIALS: never echo them into the conversation or logs; keep the list in a private file.',
         parameters: {
             action: { type: 'string', required: true, enum: ['flush', 'restore'], description: 'flush = export cookies; restore = import cookies.' },
             cookies: { type: 'array', items: { type: 'object', additionalProperties: true }, description: 'Cookie list to restore (required when action=restore).' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-builtin-browser",
-  "version": "0.4.10",
+  "version": "0.4.13",
   "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 (dsh_browser_auth), CAPTCHA detection, batch form fill (dsh_browser_fill), authenticated download, history/replay, action restriction",
   "type": "module",
   "main": "lib/index.js",
@@ -65,7 +65,8 @@
     "url": "https://github.com/wqty123/dsh-browser/issues"
   },
   "engines": {
-    "node": ">=22.19"
+    "node": ">=22.19",
+    "dsh": ">=0.1.1-rc.2 <0.3.0"
   },
   "dependencies": {
     "electron": ">= 30.0.0"
@@ -97,7 +98,7 @@
       ]
     },
     "compatibility": {
-      "dsh": ">=0.1.1-rc.1 <0.3.0",
+      "_comment": "Documentation only. DSH decides plugin compatibility from engines.dsh (falling back to @deepseek-ai/dsh* peerDependencies when it is absent); nothing reads this block. Kept because the release-by-release record is useful to a human and costs nothing.",
       "profiles": [
         "web",
         "desktop"
@@ -108,7 +109,8 @@
         "0.1.1-rc.2": "compatible",
         "0.2.0-rc.1": "compatible",
         "0.2.0-rc.2": "compatible",
-        "0.2.1-alpha.1": "compatible"
+        "0.2.1-alpha.1": "compatible",
+        "0.2.1-rc.1": "compatible"
       }
     }
   }

package/src/browser/types.ts

@@ -511,6 +511,23 @@ export interface CarrierPage {
   readonly title?: string
 }
 
+/**
+ * Why a carrier reported that it can no longer be used.
+ *
+ * Two different failures reach the same fallback, and saying which one is the difference between a
+ * message a user can act on and one that misleads them:
+ *
+ * - `shell-exited`: the shell process behind the carrier is gone. Its published endpoint stops
+ *   being refreshed, which is the condition the fallback was originally written for.
+ * - `panel-unusable`: the shell is alive and answering, but its sidebar panel cannot provide a page
+ *   — on a shell that renders that panel as an iframe there is no webContents and no CDP endpoint,
+ *   so the carrier is undrivable rather than merely unready.
+ *
+ * The fallback announced the first of these unconditionally, so a `panel-unusable` fallback told
+ * the user their desktop shell had exited while it was running normally. Reported as such.
+ */
+export type CarrierLossReason = 'shell-exited' | 'panel-unusable'
+
 /** Request to open a URL: into the active tab or a new tab. */export interface BrowserOpenRequest {
   /** The URL to open. */
   readonly url: string

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

@@ -30,7 +30,7 @@ import { join } from 'node:path'
 import { randomUUID } from 'node:crypto'
 import type { ElectronBrowserViewHost, ElectronViewHandle } from './provider.js'
 import type { BrowserUserAction } from './provider.js'
-import type { CarrierPage } from '../browser/types.js'
+import type { CarrierPage, CarrierLossReason } from '../browser/types.js'
 
 
 /** Absolute path of the endpoint file the shell writes. */
@@ -120,32 +120,35 @@ export class DesktopBridgeViewHost implements ElectronBrowserViewHost {
    */
   private userActionHandler: ((action: BrowserUserAction) => void) | undefined
   /** Told when the shell behind this bridge exits; see `onLost`. */
-  private lostListener: (() => void) | undefined
+  private lostListener: ((reason: CarrierLossReason) => 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.reportLost())
+    // The transport reaches this only by concluding the shell stopped refreshing its endpoint, which
+    // is `shell-exited`.
+    this.connection = new BridgeConnection(endpoint, bridgeEndpointPath(), () => this.reportLost('shell-exited'))
   }
 
   /**
-   * Called by the transport once the shell behind it is gone.
+   * Called when this carrier concludes it cannot serve anything more.
    *
    * 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.
+   * @param reason - which failure this was, so the fallback can say so accurately.
    */
-  private reportLost(): void {
+  private reportLost(reason: CarrierLossReason): void {
     try {
-      this.lostListener?.()
+      this.lostListener?.(reason)
     } 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 {
+  onLost(listener: (reason: CarrierLossReason) => void): void {
     this.lostListener = listener
   }
 
@@ -335,7 +338,11 @@ export class DesktopBridgeViewHost implements ElectronBrowserViewHost {
       // shell whose sidebar panel is an iframe, that is every call forever. Reported as "installing
       // the bridge made it worse than not installing it": the carrier was switched to one that
       // cannot work, with no path back to the one that does.
-      if (String(answer.error).includes('produced no page')) this.reportLost()
+      //
+      // `panel-unusable`, not `shell-exited`: the shell is alive and answered this very request. The
+      // fallback's message used to announce an exiting shell unconditionally, which told the user
+      // their desktop had crashed when it was running normally.
+      if (String(answer.error).includes('produced no page')) this.reportLost('panel-unusable')
       throw new Error(`dsh-builtin-browser: sidebar unavailable (${String(answer.error)})`)
     }
     const id = Number(answer.id)

package/src/browser-electron/entry.ts

@@ -16,6 +16,7 @@ import z from '@deepseek-ai/schemastery'
 import type { BrowserRuntime } from '../browser/runtime.js'
 import { ElectronBrowserProvider } from './provider.js'
 import type { ElectronBrowserViewHost } from './provider.js'
+import type { CarrierLossReason } from '../browser/types.js'
 import { randomUUID } from 'node:crypto'
 import { existsSync, mkdirSync, renameSync } from 'node:fs'
 import { homedir } from 'node:os'
@@ -165,27 +166,50 @@ export function apply(ctx: Context & { browser: BrowserRuntime }, config: Config
    *
    * 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.
+   * once and only in one direction. Reaching here means the carrier cannot serve anything more, 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.
+   *
+   * Two failures arrive here and the message must distinguish them. The first draft announced an
+   * exiting shell unconditionally, so a fallback caused by an undrivable sidebar panel told the
+   * user their desktop shell had exited while it was running normally.
    * @param adopted - the carrier that reported the loss, disposed once its replacement is in place.
+   * @param reason - which failure this was; see {@link CarrierLossReason}.
    */
-  const restoreSelfHosted = (adopted: ElectronBrowserViewHost): void => {
+  const restoreSelfHosted = (adopted: ElectronBrowserViewHost, reason: CarrierLossReason): 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.',
+        reason === 'shell-exited'
+          ? '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.'
+          : 'dsh-builtin-browser: this desktop shell renders the sidebar browser panel in a way that '
+            + 'cannot be driven (no webContents, so no CDP endpoint), so the browser this plugin hosts '
+            + 'itself takes over. The shell is still running and nothing else is affected; the page '
+            + 'opens in this plugin\'s own window. Set browser.channel to another value to silence this.',
       )
     } 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?.()
+      // Disposed on a LATER turn of the event loop, deliberately.
+      //
+      // Disposing synchronously here closes the bridge socket while the request that triggered this
+      // fallback is still settling, and the close rejects every call still waiting on that socket —
+      // so the caller received "bridge closed" instead of the reason it actually failed for. The
+      // fallback is what the user is supposed to be able to understand; replacing its explanation
+      // with one about the connection loses exactly the information this path exists to convey.
+      setImmediate(() => {
+        try {
+          adopted.dispose?.()
+        } catch {
+          // A carrier that cannot be released is not the caller's problem; the swap already happened.
+        }
+      })
     }
   }
 
@@ -208,7 +232,7 @@ export function apply(ctx: Context & { browser: BrowserRuntime }, config: Config
       // 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) })
+      host.onLost?.(reason => { restoreSelfHosted(host, reason) })
       const previous = adoptedCarrier
       adoptedCarrier = host
       // Released AFTER the replacement is installed, so the surface is never without a provider.

package/src/browser-electron/provider.ts

@@ -51,7 +51,7 @@ import type {
   ExportedCookie,
 } from '../browser/types.js'
 import { BrowserError } from '../browser/types.js'
-import type { CarrierPage } from '../browser/types.js'
+import type { CarrierPage, CarrierLossReason } from '../browser/types.js'
 
 /**
  * Page-context human-verification (CAPTCHA / bot-detection) detection. Runs
@@ -255,9 +255,14 @@ export interface ElectronBrowserViewHost {
    * 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.
+   *
+   * The listener receives WHY, because the fallback's message has to match what happened: a shell
+   * that exited and a shell whose panel cannot provide a page both reach the same fallback, and
+   * announcing "the shell has exited" for the second tells the user their desktop crashed when it
+   * did not.
    * @param listener - called once, when the carrier concludes it is gone.
    */
-  onLost?(listener: () => void): void
+  onLost?(listener: (reason: CarrierLossReason) => void): void
   /**
    * Fold the carrier's presentation away while keeping the page alive.
    *

package/src/browser-electron/system-browser.ts

@@ -721,11 +721,37 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
     // The port file is deliberately NOT deleted here, and that is a reversal.
     //
     // It used to be removed so the launch loop below could not read a previous browser's port. But
-    // the loop already refuses any file older than the spawn (`freshPort` compares mtimes), so the
-    // deletion never protected it — while it DID destroy the only record of a browser that may
-    // still be running for this profile. That record is what `adoptRunningBrowser` needs when the
-    // launch comes back as a hand-off: the browser was alive the whole time, and without the file
-    // there is no way to find it again.
+    // the loop judges freshness against a snapshot taken below, so the deletion never protected it
+    // — while it DID destroy the only record of a browser that may still be running for this
+    // profile. That record is what `adoptRunningBrowser` needs when the launch comes back as a
+    // hand-off: the browser was alive the whole time, and without the file there is no way to find
+    // it again.
+    const portFile = join(this.profileDir, 'DevToolsActivePort')
+    /**
+     * What the port file was like BEFORE this launch, so "fresh" is judged against a snapshot
+     * rather than against a clock.
+     *
+     * The test used to be `mtimeMs < spawnedAt` — a filesystem timestamp compared to `Date.now()`.
+     * Those are different clocks with different resolutions, and CI is where it showed: a file the
+     * fake browser had just written was rejected as stale, so the loop waited out its full 30s
+     * against a browser that was already listening, because the file's mtime had rounded down
+     * below the spawn time. That is not a test-only problem: on any filesystem whose mtime
+     * resolution is coarser than a millisecond, the plugin would fail to see the browser it had
+     * just launched, and report a CDP timeout for a browser that was up the whole time.
+     *
+     * `undefined` means there was no file, so any file that appears afterwards is fresh. When one
+     * existed, a later mtime OR different contents makes the new one fresh. Byte-identical contents
+     * with an unchanged mtime is the PREVIOUS browser's port, and adopting it is what this whole
+     * check exists to prevent: it may name a port that now belongs to something else entirely.
+     */
+    const portFileBefore = ((): { mtimeMs: number; contents: string } | undefined => {
+      try {
+        return { mtimeMs: statSync(portFile).mtimeMs, contents: readFileSync(portFile, 'utf8') }
+      } catch {
+        return undefined
+      }
+    })()
+    // Kept for the failure message and for the exit listener's diagnostics; no longer a judgement.
     const spawnedAt = Date.now()
     let child: ReturnType<typeof spawn>
     try {
@@ -759,20 +785,26 @@ export class SystemBrowserViewHost implements ElectronBrowserViewHost {
       // Clearing these is what makes the restart usable rather than merely alive.
       this.forgetBrowserState()
     })
-    const portFile = join(this.profileDir, 'DevToolsActivePort')
     /**
      * The port this launch wrote, or undefined while it has not written one yet.
      *
-     * A file left by the PREVIOUS browser is not evidence about this one. Its contents
-     * name a port that may now belong to something else entirely — another Chromium, a
-     * node --inspect — and connecting there publishes a client this host does not own and
-     * dispose() can never kill. Only a file written after the spawn counts.
+     * A file left by the PREVIOUS browser is not evidence about this one. Its contents name a port
+     * that may now belong to something else entirely — another Chromium, a `node --inspect` — and
+     * connecting there publishes a client this host does not own and dispose() can never kill.
+     * Only a file that CHANGED across this launch counts, which is what `portFileBefore` records.
      */
     const freshPort = (): number | undefined => {
       try {
         if (!existsSync(portFile)) return undefined
-        if (statSync(portFile).mtimeMs < spawnedAt) return undefined
-        const value = Number(readFileSync(portFile, 'utf8').split('\n')[0]?.trim() ?? '')
+        const after = statSync(portFile)
+        const contents = readFileSync(portFile, 'utf8')
+        // Unchanged since before the launch: this is the previous browser's file, whatever its
+        // mtime says. Comparing against the snapshot rather than the spawn time is what keeps this
+        // correct on a filesystem whose timestamps are coarser than the clock behind spawnedAt.
+        if (portFileBefore !== undefined
+          && after.mtimeMs <= portFileBefore.mtimeMs
+          && contents === portFileBefore.contents) return undefined
+        const value = Number(contents.split('\n')[0]?.trim() ?? '')
         return Number.isInteger(value) && value > 0 ? value : undefined
       } catch {
         return undefined

package/src/tool-browser/index.ts

@@ -375,7 +375,7 @@ export function apply(ctx: Context, config: Config = {}): void {
 
   registerSafely(defineTool({
     name: 'dsh_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. 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.',
+    description: 'Open a URL in the shared browser window and return the resulting snapshot. Opens this task\'s session on first use; newTab is optional. A fresh session starts on a blank 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 — it needs the authenticated URL printed by `dsh web`, and the bare root is refused.',
     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.' },
@@ -501,7 +501,7 @@ export function apply(ctx: Context, config: Config = {}): void {
 
   registerSafely(defineTool({
     name: 'dsh_browser_a11y',
-    description: 'Read the page\'s accessibility tree: every interactive node with its semantic role (button/link/textbox/checkbox/…), accessible name, current value, and states (enabled/disabled/checked/expanded/…), (coordinates only when coords: true). Prefer this over dsh_browser_snapshot to understand a page\'s structure and find the right element: roles and names tell you WHAT each node is, and the name is what dsh_browser_click matches when you target by text. Penetrates same-origin iframes and shadow roots.',
+    description: 'Read the accessibility tree: every interactive node with its role (button/link/textbox/checkbox/…), accessible name, value, and states (enabled/checked/expanded/…); coordinates only with coords: true. Prefer this over dsh_browser_snapshot to understand structure and find the right element — roles and names say WHAT each node is, and the name is what dsh_browser_click matches when targeting by text. Penetrates same-origin iframes and shadow roots.',
     parameters: {
       includeHidden: { type: 'boolean', description: 'Include hidden elements (default false).' },
       maxNodes: { type: 'number', description: 'Maximum nodes (default 150, range 10-5000).' },
@@ -799,7 +799,7 @@ export function apply(ctx: Context, config: Config = {}): void {
 
   registerSafely(defineTool({
     name: 'dsh_browser_click',
-    description: 'Click in the shared browser. Prefer the semantic target: pass target {by: css|text|xpath, value, index?} and the element is located from the DOM, scrolled into view and clicked at its centre — this needs no image input and is the only form that works without vision. The alternative is viewport coordinates (x/y), which are meaningful only after a vision model has located the element on a dsh_browser_screenshot; coordinate clicks are refused outright under the non-visual strategy. Provide exactly one of target or x/y.',
+    description: 'Click in the shared browser. Prefer target {by: css|text|xpath, value, index?}: the element is located from the DOM, scrolled into view, and clicked at its centre — no image input needed, and the only form that works without vision. Alternatively x/y viewport coordinates, meaningful only after a vision model located the element on a dsh_browser_screenshot; refused under the non-visual strategy. Provide exactly one of target or x/y.',
     parameters: {
       target: {
         type: 'object',
@@ -1018,7 +1018,7 @@ export function apply(ctx: Context, config: Config = {}): void {
 
   registerSafely(defineTool({
     name: 'dsh_browser_fill',
-    description: 'Fill a form in one batch: pass fields with a CSS selector or name/label/placeholder text and the value to set (string, number, or boolean for checkbox/radio; for selects or radio groups pass the option value or visible text). Values are applied with the native setter plus input/change events, so React/Vue controlled inputs update correctly. Optionally submit the containing form. Prefer this over hand-written dsh_browser_execute for form filling; per-field failures are reported instead of throwing.',
+    description: 'Fill a form in one batch: each field takes a CSS selector or name/label/placeholder text plus its value (boolean for checkbox/radio; option value or visible text for selects and radio groups). The native setter plus input/change events fire, so React/Vue controlled inputs update. Optionally submit the form. Prefer this over hand-written dsh_browser_execute; per-field failures are reported instead of throwing.',
     parameters: {
       fields: {
         type: 'array',
@@ -1315,7 +1315,7 @@ export function apply(ctx: Context, config: Config = {}): void {
 
   registerSafely(defineTool({
     name: 'dsh_browser_screenshot',
-    description: 'Capture the current shared-browser page as a screenshot (PNG default, JPEG optional). This is for models that can read images: layout checks, charts, designs, CAPTCHAs, or locating an element by eye before clicking its coordinates. A model without image input gains nothing from it — dsh_browser_snapshot, dsh_browser_a11y and dsh_browser_content carry the same page as text, and dsh_browser_scrape extracts structured data. Supports full-page capture, save-to-file, JPEG encoding, and downscaling (maxWidth/maxHeight) to cut vision-tool token cost. JPEG needs a browser whose CDP encoder works — the self-hosted browser and an installed Chrome/Edge; some carriers (the desktop sidebar) return PNG instead. Downscaling works on every carrier.',
+    description: 'Screenshot the shared-browser page (PNG default, JPEG optional) for models that can read images: layout, charts, CAPTCHAs, or locating an element before clicking its coordinates. Without image input it gains nothing — dsh_browser_snapshot/a11y/content carry the same page as text, dsh_browser_scrape extracts structured data. Supports fullPage, savePath, JPEG quality, and maxWidth/maxHeight downscaling to cut vision tokens. JPEG needs a carrier whose CDP encoder works (self-hosted, installed Chrome/Edge); the desktop sidebar returns PNG. Downscaling works everywhere.',
     parameters: {
       fullPage: { type: 'boolean', description: 'Capture the full scrollable page instead of the viewport (default false).' },
       savePath: { type: 'string', description: 'Absolute file path to also save the image to (e.g. for read_image vision location). Must resolve inside the configured downloadDir (default: the system Downloads folder, localized names such as ~/下载 included); an existing file is never overwritten.' },
@@ -1764,7 +1764,7 @@ export function apply(ctx: Context, config: Config = {}): void {
 
   registerSafely(defineTool({
     name: 'dsh_browser_restrict',
-    description: 'Restrict which browser actions are allowed, to prevent stray clicks/navigation. Pass a list of browser tool names (e.g. ["dsh_browser_snapshot","dsh_browser_content","dsh_browser_click"]) — any other dsh_browser_* call is refused. Pass an empty list or omit to lift the restriction. Never blocked, whatever the list says: the observing tools (snapshot/a11y/content/scrape/screenshot/get_value/wait/challenge/list_tabs/session/history/visited) and the three that lift a restriction or recover from a bad state (restrict/reset/reset_session) — so a restriction can always be read around and undone. IMPORTANT: this is a SOFT guardrail against accidental actions, NOT a security boundary — you (the model) can lift it yourself with an empty list.',
+    description: 'Allow only the listed browser tools; any other dsh_browser_* call is refused. Empty list or omitted lifts it. Never blocked whatever the list says — the observing tools (snapshot/a11y/content/scrape/screenshot/get_value/wait/challenge/list_tabs/session/history/visited) and restrict/reset/reset_session — so a restriction can always be read around and undone. A SOFT guardrail against stray clicks, NOT a security boundary: you can lift it with an empty list.',
     parameters: {
       allowed: {
         type: 'array',
@@ -1798,7 +1798,7 @@ export function apply(ctx: Context, config: Config = {}): void {
 
   registerSafely(defineTool({
     name: 'dsh_browser_auth',
-    description: 'Export or restore the browser session\'s cookies (login state). Use "flush" to get a JSON cookie list (save it to a private file to persist logins), or "restore" with that list to put logins back (e.g. after the browser host restarted). Available on all three carriers: the self-hosted browser reads its own session, while the desktop sidebar and an installed Chrome/Edge go through CDP. Refused entirely when the credential switch is off. Exported cookies are LIVE CREDENTIALS: treat them as secrets — do not echo them into the conversation, keep them out of logs, and store the list in a private file.',
+    description: 'Export or restore the session\'s cookies (login state): "flush" returns a JSON cookie list, "restore" takes that list back (e.g. after the host restarted). Works on all carriers. Refused when the credential switch is off. Exported cookies are LIVE CREDENTIALS: never echo them into the conversation or logs; keep the list in a private file.',
     parameters: {
       action: { type: 'string', required: true, enum: ['flush', 'restore'], description: 'flush = export cookies; restore = import cookies.' },
       cookies: { type: 'array', items: { type: 'object', additionalProperties: true }, description: 'Cookie list to restore (required when action=restore).' },