dsh-baton-mcp 0.3.0 → 0.4.0

package/README.md

@@ -37,7 +37,7 @@ Codex and Claude take turns in the same Harness session, and every message is la
 ## Quick start
 
 <p align="center">
-  <img src="./assets/readme/install.svg" width="100%" alt="Step 1: run npx -y dsh-baton-mcp setup. Step 2: in Harness open Plugins, Add plugin, paste, Install, Enable now. Step 3: in a new chat, ask for dsh_list_workspaces">
+  <img src="./assets/readme/install.svg" width="100%" alt="Step 1: run npx -y dsh-baton-mcp setup. Step 2: in Harness open Plugins, Add plugin, enter dsh-baton-host from the npm registry, Install, Enable now. Step 3: in a new chat, ask for dsh_list_workspaces">
 </p>
 
 Requires DeepSeek Harness ≥ 0.2.1-rc.2 (signed in), Node.js ≥ 22.15. On Windows, see [WINDOWS.md](WINDOWS.md).
@@ -50,9 +50,9 @@ npx -y dsh-baton-mcp setup
 
 dsh-baton has no dependencies. `setup` copies itself to `~/.dsh-baton/app`, a folder that stays put (npx's cache does not), and registers the MCP server once, user-wide, for Claude Code and Codex: every new conversation, in any folder, has the `dsh_*` tools. It writes `~/.claude.json` and `~/.codex/config.toml` directly (a backup of each is kept as `*.bak-dsh-baton`), so it also works when only the desktop apps are installed and `claude` / `codex` are not on your `PATH`. Running it again is safe.
 
-**2. Paste in Harness.** `setup` copies the plugin folder path to your clipboard:
+**2. Add the plugin in Harness**, by its npm package name (`setup` copies it to your clipboard):
 
-**Plugins** (插件) → **Add plugin** (添加插件) → paste → **Install** (安装) → **Enable now** (立即启用)
+**Plugins** (插件) → **Add plugin** (添加插件) → registry **Official npm registry** → `dsh-baton-host` → **Install** (安装) → **Enable now** (立即启用)
 
 **3. Check.** Start a **new** conversation in Claude Code or Codex and ask it to call `dsh_list_workspaces`. It lists your Harness workspaces.
 
@@ -63,13 +63,18 @@ dsh-baton has no dependencies. `setup` copies itself to `~/.dsh-baton/app`, a fo
 - **Codex** waits inside `dsh_wait`, up to 270 s per call, just under its 300 s tool timeout. An unfinished wait returns only the state, so Codex calls again without summarising. Codex gets no `wait_command`: its terminal cannot wake it, so it would poll.
 - Codex asks you to approve MCP tool calls: approve the `dsh-baton` tools. For unattended `codex exec` runs, add `--approve-for-me`.
 
-**Updating:** run `npx -y dsh-baton-mcp@latest setup` again, then restart Harness to load plugin changes; new conversations pick up MCP server changes.
+**Updating:** the MCP server and the plugin update separately, and both carry the same version.
+- MCP server: `npx -y dsh-baton-mcp@latest setup`. New conversations use it.
+- Plugin: Harness offers an update button only for its own official plugins, so for this one: Plugins → dsh-baton-host → **Uninstall**, then **Add plugin** → `dsh-baton-host` again.
+- `setup` says when the two are out of step, and so does the first tool call that notices it.
 
-**Removing:** `npx -y dsh-baton-mcp setup --remove`, then Harness → Plugins → dsh-baton-host → Uninstall, then `setup --remove` once more to delete `~/.dsh-baton/app`.
+**Removing:** Harness → Plugins → dsh-baton-host → **Uninstall**, and `npx -y dsh-baton-mcp setup --remove`. That removes the MCP entries and `~/.dsh-baton/app`; run records stay in `~/.dsh-baton` until you delete it.
 
-**Upgrading from dsh-bridge**: run `setup` as above. It replaces the old `dsh-bridge` MCP entries; in Harness, uninstall `dsh-bridge-host`, then add the new path. `DSH_BRIDGE_*` variables and an existing `~/.dsh-bridge` folder keep working for now. Tools get a new prefix (`mcp__dsh-baton__…`), so update any permission allowlists.
+**Upgrading from dsh-bridge**: run `setup` as above. It replaces the old `dsh-bridge` MCP entries; in Harness, uninstall `dsh-bridge-host`, then add `dsh-baton-host` as in step 2. `DSH_BRIDGE_*` variables and an existing `~/.dsh-bridge` folder keep working for now. Tools get a new prefix (`mcp__dsh-baton__…`), so update any permission allowlists.
 
-**From source** (to follow `main` or to change the code): `git clone https://github.com/JialaoLiu/dsh-baton.git` and `node dsh-baton/src/cli.mjs setup`. setup then registers the clone itself; update with `git pull`.
+**Installed from a local folder before 0.4?** Earlier versions had you paste `~/.dsh-baton/app/host`. That still works, but it does not update with npm: uninstall it and add `dsh-baton-host` by name. `setup` points this out.
+
+**From source** (to follow `main` or to change the code): `git clone https://github.com/JialaoLiu/dsh-baton.git` and `node dsh-baton/src/cli.mjs setup`. setup then registers the clone itself and has you add the plugin from the clone's `host` folder (Add plugin → paste the path it copies), so plugin changes run before they are published; update with `git pull`.
 
 <details>
 <summary>Manual registration and the Claude desktop app</summary>

package/README.zh-CN.md

@@ -37,7 +37,7 @@ Codex 和 Claude 轮流往同一个 Harness 对话发消息，每条都标明是
 ## 快速上手
 
 <p align="center">
-  <img src="./assets/readme/zh/install.svg" width="100%" alt="第一步：运行 npx -y dsh-baton-mcp setup。第二步：Harness → 插件 → 添加插件 → 粘贴 → 安装 → 立即启用。第三步：新开对话，让它调用 dsh_list_workspaces">
+  <img src="./assets/readme/zh/install.svg" width="100%" alt="第一步：运行 npx -y dsh-baton-mcp setup。第二步：Harness → 插件 → 添加插件 → 从 npm 输入 dsh-baton-host → 安装 → 立即启用。第三步：新开对话，让它调用 dsh_list_workspaces">
 </p>
 
 需要：DeepSeek Harness ≥ 0.2.1-rc.2 并已登录；Node.js ≥ 22.15。Windows 见 [WINDOWS.md](WINDOWS.md)。
@@ -50,9 +50,9 @@ npx -y dsh-baton-mcp setup
 
 dsh-baton 没有任何依赖。`setup` 会把自己复制到 `~/.dsh-baton/app` 这个固定的文件夹（npx 的缓存目录会变），然后在用户级别给 Claude Code 和 Codex 注册一次 MCP 服务器：之后在任何文件夹新开的对话都有 `dsh_*` 工具。它直接写 `~/.claude.json` 和 `~/.codex/config.toml`（各留一份 `*.bak-dsh-baton` 备份），所以只装了桌面应用、`claude` / `codex` 不在 `PATH` 里也能用。重复运行也没问题。
 
-**2. 在 Harness 里粘贴。**`setup` 已经把插件文件夹路径复制到剪贴板：
+**2. 在 Harness 里按包名添加插件**（`setup` 已经把包名复制到剪贴板）：
 
-**插件** → **添加插件** → 粘贴 → **安装** → **立即启用**
+**插件** → **添加插件** → 来源选 **Official npm registry** → 输入 `dsh-baton-host` → **安装** → **立即启用**
 
 **3. 检查。**在 Claude Code 或 Codex 里**新开**一个对话，让它调用 `dsh_list_workspaces`，应该会列出你的 Harness 工作区。
 
@@ -63,13 +63,18 @@ dsh-baton 没有任何依赖。`setup` 会把自己复制到 `~/.dsh-baton/app`
 - **Codex** 在 `dsh_wait` 里等待，每次最多 270 秒，刚好低于它 300 秒的工具超时。没做完时只返回状态，Codex 会直接再调用，不会去总结进度。Codex 不会收到 `wait_command`：它的终端无法在命令结束时唤醒它，只能轮询。
 - Codex 调用 MCP 工具时会请你批准，批准 `dsh-baton` 的工具即可；无人值守的 `codex exec` 加上 `--approve-for-me`。
 
-**更新：** 再运行一次 `npx -y dsh-baton-mcp@latest setup`，然后重启 Harness 以加载插件改动；新开的对话会用上 MCP 服务器的改动。
+**更新：** MCP 服务器和插件分开更新，两者版本号相同。
+- MCP 服务器：`npx -y dsh-baton-mcp@latest setup`，新开的对话就会用上。
+- 插件：Harness 只给官方插件提供"更新"按钮，所以这个插件要：插件 → dsh-baton-host → **卸载**，再**添加插件** → `dsh-baton-host`。
+- 两边版本对不上时，`setup` 会提示，第一次发现不一致的工具调用也会提示。
 
-**卸载：** `npx -y dsh-baton-mcp setup --remove`，再到 Harness → 插件 → dsh-baton-host → 卸载，最后再运行一次 `setup --remove` 删除 `~/.dsh-baton/app`。
+**卸载：** Harness → 插件 → dsh-baton-host → **卸载**，再运行 `npx -y dsh-baton-mcp setup --remove`。它会删掉 MCP 注册和 `~/.dsh-baton/app`；运行记录留在 `~/.dsh-baton`，不需要的话自己删掉。
 
-**从 dsh-bridge 升级：**照上面运行 `setup`。它会替换掉旧的 `dsh-bridge` MCP 注册；在 Harness 里先卸载 `dsh-bridge-host`，再添加新路径。`DSH_BRIDGE_*` 环境变量和已有的 `~/.dsh-bridge` 文件夹暂时继续可用。工具前缀变成 `mcp__dsh-baton__…`，权限白名单里写了旧前缀的要改一下。
+**从 dsh-bridge 升级：**照上面运行 `setup`。它会替换掉旧的 `dsh-bridge` MCP 注册；在 Harness 里先卸载 `dsh-bridge-host`，再按第 2 步添加 `dsh-baton-host`。`DSH_BRIDGE_*` 环境变量和已有的 `~/.dsh-bridge` 文件夹暂时继续可用。工具前缀变成 `mcp__dsh-baton__…`，权限白名单里写了旧前缀的要改一下。
 
-**从源码安装**（想跟进 `main` 或改代码）：`git clone https://github.com/JialaoLiu/dsh-baton.git`，再运行 `node dsh-baton/src/cli.mjs setup`。这时 setup 注册的就是克隆目录本身，更新用 `git pull`。
+**0.4 之前从本地文件夹装的插件：**旧版本让你粘贴 `~/.dsh-baton/app/host`。这样装的仍然能用，但不会跟着 npm 更新：卸载它，再按包名添加 `dsh-baton-host`。`setup` 会提示这一点。
+
+**从源码安装**（想跟进 `main` 或改代码）：`git clone https://github.com/JialaoLiu/dsh-baton.git`，再运行 `node dsh-baton/src/cli.mjs setup`。这时 setup 注册的就是克隆目录本身，插件也从克隆目录的 `host` 文件夹添加（添加插件 → 粘贴它复制的路径），这样插件改动在发布前就能跑起来；更新用 `git pull`。
 
 <details>
 <summary>手动注册与 Claude 桌面应用</summary>

package/WINDOWS.md

@@ -26,17 +26,19 @@ Requires DeepSeek Harness ≥ 0.2.1-rc.2 and Node.js ≥ 22.15. In PowerShell:
 npx -y dsh-baton-mcp setup
 ```
 
-`setup` copies itself to `%USERPROFILE%\.dsh-baton\app` (npx's cache is not a stable place) and registers the MCP server once, user-wide, for Claude Code (`%USERPROFILE%\.claude.json`) and Codex (`%USERPROFILE%\.codex\config.toml`), with the absolute path of `node`. It edits the files directly, so it works with the desktop apps alone: their `claude.exe` / `codex.exe` are usually not on `PATH`. It also copies the plugin path to the clipboard.
+`setup` copies itself to `%USERPROFILE%\.dsh-baton\app` (npx's cache is not a stable place) and registers the MCP server once, user-wide, for Claude Code (`%USERPROFILE%\.claude.json`) and Codex (`%USERPROFILE%\.codex\config.toml`), with the absolute path of `node`. It edits the files directly, so it works with the desktop apps alone: their `claude.exe` / `codex.exe` are usually not on `PATH`. It also copies the plugin's package name to the clipboard.
 
-Then, in Harness: **Plugins / 插件** → **Add plugin / 添加插件** → paste the path it copied (`%USERPROFILE%\.dsh-baton\app\host`) → **Install / 安装** → **Enable now / 立即启用**. The pipe appears right away (see [Verify](#verify)); if it does not, restart Harness.
+Then, in Harness: **Plugins / 插件** → **Add plugin / 添加插件** → registry **Official npm registry** → `dsh-baton-host` → **Install / 安装** → **Enable now / 立即启用**. The pipe appears right away (see [Verify](#verify)); if it does not, restart Harness.
 
 Nothing else to configure: Claude Code waits for a run in the background (Git Bash runs the `wait_command` that `dsh_send` returns), and Codex waits up to 270 s per `dsh_wait` call, under its 300 s tool timeout. Approve the `dsh-baton` tools when Codex asks; for unattended `codex exec`, add `--approve-for-me`.
 
-Remove: `npx -y dsh-baton-mcp setup --remove`, then Harness → Plugins → dsh-baton-host → Uninstall, then `setup --remove` once more to delete the app folder.
+Update: `npx -y dsh-baton-mcp@latest setup` for the MCP server; for the plugin, Harness → Plugins → dsh-baton-host → Uninstall, then Add plugin → `dsh-baton-host` again (Harness has no update button for non-official plugins).
 
-Upgrading from dsh-bridge: `setup` replaces the old MCP entries and reuses an existing `%USERPROFILE%\.dsh-bridge` (the app then goes to `.dsh-bridge\app`). Uninstall `dsh-bridge-host` in Harness, then add the path `setup` copied. With the hoisted profile layout, uninstalling may leave a `node_modules\dsh-bridge-host` link behind in `%USERPROFILE%\.dsh\profiles\desktop`; it is no longer in the profile's dependencies, so delete it with Harness quit.
+Remove: Harness → Plugins → dsh-baton-host → Uninstall, and `npx -y dsh-baton-mcp setup --remove`.
 
-From source instead: `git clone https://github.com/JialaoLiu/dsh-baton.git C:\dev\dsh-baton` and `node C:\dev\dsh-baton\src\cli.mjs setup`; the plugin path is then `C:\dev\dsh-baton\host`.
+Upgrading from dsh-bridge: `setup` replaces the old MCP entries and reuses an existing `%USERPROFILE%\.dsh-bridge` (the app then goes to `.dsh-bridge\app`). Uninstall `dsh-bridge-host` in Harness, then add `dsh-baton-host` by name. A plugin added earlier from `.dsh-baton\app\host` (0.3) also works, but `setup` suggests swapping it for the npm package, which is the one that gets updates. With the hoisted profile layout, uninstalling may leave a `node_modules\dsh-bridge-host` link behind in `%USERPROFILE%\.dsh\profiles\desktop`; `setup --remove` deletes such a leftover link (old or new name) once the profile no longer lists the plugin.
+
+From source instead: `git clone https://github.com/JialaoLiu/dsh-baton.git C:\dev\dsh-baton` and `node C:\dev\dsh-baton\src\cli.mjs setup`; setup then has you add the plugin from `C:\dev\dsh-baton\host` (Add plugin → paste the path it copies).
 
 ### If the Plugins page cannot uninstall or install it
 
@@ -107,7 +109,7 @@ The suite runs on Windows with named pipes. Two POSIX-only checks are skipped: f
 
 - **套接字改为命名管道。** Windows 上 Node 不能监听 Unix 套接字文件，所以同一路径被映射成按用户区分的命名管道 `\\.\pipe\dsh-baton-<哈希>`。插件和 MCP 两边算法一致，`DSH_BATON_SOCKET` 仍然可用，Harness 退出后管道自动消失。
 - **headless 用 Harness 自带的 CLI。** Harness ≥ 0.2.1 自带 `resources\runtime\cli\bin\dsh.cmd`；更早的版本只有打包在 `app.asar` 里的 CLI，由 Harness 自己的 exe 以 Node 模式运行。会按顺序自动查找：`DSH_BIN`、`PATH` 里的 `dsh`、默认安装位置，以及注册表里的自定义安装目录。
-- **插件用 Harness 插件页安装。** 插件 → 添加插件 → 粘贴 `%USERPROFILE%\.dsh-baton\app\host` → 安装 → 立即启用（`setup` 已把路径复制到剪贴板）。
+- **插件用 Harness 插件页按包名安装。** 插件 → 添加插件 → 来源选 Official npm registry → 输入 `dsh-baton-host` → 安装 → 立即启用（`setup` 已把包名复制到剪贴板）。更新插件要先卸载再重新添加，Harness 只给官方插件提供更新按钮。
 - **一条命令注册 MCP。** `npx -y dsh-baton-mcp setup` 把自己复制到 `%USERPROFILE%\.dsh-baton\app`，再直接写 Claude Code 和 Codex 的用户级配置（用 `node` 的绝对路径），桌面版的 `claude` / `codex` 不在 `PATH` 里也没关系。之后新开对话就有 `dsh_*` 工具；Codex 每次最多等 270 秒，不用再配超时。
 - **插件页卸不掉或装不上时**（`ERR_PNPM_UNEXPECTED_STORE`，或提示"该插件已安装"）：是旧版 Harness 装 profile 时用了另一个 pnpm store。一次性修好：从菜单退出 Harness，把 `%USERPROFILE%\.dsh\profiles\desktop\node_modules` 改名备份，用 Harness 自带的 pnpm 运行 `install --frozen-lockfile`（不加 `--store-dir`；`$app` 改成你的安装目录，比如 `E:\Software\DeepSeek Harness`），再启动 Harness，插件页的卸载和添加就正常了；如果插件被关掉了，记得重新打开。
 - **headless 需要独立凭据。** 要么登录账户，要么设置 `DEEPSEEK_API_KEY`。桌面版里保存的 Key，headless CLI 读不到。

package/host/README.md

@@ -1,14 +1,16 @@
 # dsh-baton-host
 
-DeepSeek Harness plugin for [dsh-baton](../README.md). It runs inside the Harness host (desktop app or `dsh web`) and serves a local, owner-only Unix socket (`~/.dsh-baton/host.sock`; a per-user named pipe on Windows, see [WINDOWS.md](../WINDOWS.md)). Through it, an MCP client can list and create workspaces, create sessions, continue a specific session, and wait for its turn to finish. All of this goes through Harness's own session controller, so the messages show up live in the Harness UI.
+DeepSeek Harness plugin for [dsh-baton](https://github.com/JialaoLiu/dsh-baton#readme). It runs inside the Harness host (desktop app or `dsh web`) and serves a local, owner-only Unix socket (`~/.dsh-baton/host.sock`; a per-user named pipe on Windows, see [WINDOWS.md](https://github.com/JialaoLiu/dsh-baton/blob/main/WINDOWS.md)). Through it, an MCP client can list and create workspaces, create sessions, continue a specific session, and wait for its turn to finish. All of this goes through Harness's own session controller, so the messages show up live in the Harness UI.
 
-DeepSeek Harness 插件，配合 [dsh-baton](../README.zh-CN.md) 使用。它运行在 Harness 内部，只开一个当前用户才能访问的本地套接字，让 MCP 客户端能新建工作区和对话、续接指定对话、等待任务完成。所有操作都走 Harness 官方会话服务，界面实时可见。
+DeepSeek Harness 插件，配合 [dsh-baton](https://github.com/JialaoLiu/dsh-baton/blob/main/README.zh-CN.md) 使用。它运行在 Harness 内部，只开一个当前用户才能访问的本地套接字，让 MCP 客户端能新建工作区和对话、续接指定对话、等待任务完成。所有操作都走 Harness 官方会话服务，界面实时可见。
 
 ## Install / 安装
 
-Harness → Plugins / 插件 → Add plugin / 添加插件 → `dsh-baton-host` → Install / 安装 → Enable now / 立即应用
+Harness → Plugins / 插件 → Add plugin / 添加插件 → registry Official npm registry → `dsh-baton-host` → Install / 安装 → Enable now / 立即启用
 
-Then connect the MCP server / 然后接入 MCP 服务器: see [dsh-baton](../README.md).
+Update / 更新: uninstall, then add it again / 先卸载再重新添加. Keep it on the same version as `dsh-baton-mcp` / 版本与 `dsh-baton-mcp` 保持一致.
+
+Then connect the MCP server / 然后接入 MCP 服务器: see [dsh-baton](https://github.com/JialaoLiu/dsh-baton#readme).
 
 ## Socket protocol / 套接字协议
 

package/host/lib/index.js

@@ -15,7 +15,7 @@ import { socketEndpoint, batonHome, socketPath as socketPathSetting } from './so
 export const name = 'dsh-baton-host'
 export const inject = ['sessionController', 'workspaceRegistry']
 
-const VERSION = '0.3.0'
+const VERSION = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version
 const MAX_EVENTS = 200
 const MAX_RUNS = 100
 const QUIET_CONFIRM_MS = 2000

package/host/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-baton-host",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "DeepSeek Harness plugin for dsh-baton: takes the baton from Claude Code or Codex over a local, owner-only control socket, runs it in a specific session through the host's own session controller, and hands the result back when the turn is done.",
   "type": "module",
   "main": "lib/index.js",
@@ -53,5 +53,8 @@
     "url": "git+https://github.com/JialaoLiu/dsh-baton.git",
     "directory": "host"
   },
-  "homepage": "https://github.com/JialaoLiu/dsh-baton#readme"
+  "homepage": "https://github.com/JialaoLiu/dsh-baton#readme",
+  "scripts": {
+    "prepublishOnly": "node ../scripts/version.mjs"
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-baton-mcp",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Pass the baton from Claude Code, Codex or any MCP client to a local DeepSeek Harness: an MCP server that hands off tasks, continues a specific session, shows the run live in Harness and hands the result back when it is done.",
   "type": "module",
   "bin": {
@@ -35,7 +35,8 @@
   "license": "MIT",
   "scripts": {
     "test": "node --test --test-concurrency=1 tests/*.test.mjs",
-    "test:live": "node tests/live.mjs"
+    "test:live": "node tests/live.mjs",
+    "prepublishOnly": "node scripts/version.mjs"
   },
   "repository": {
     "type": "git",

package/src/core.mjs

@@ -150,15 +150,30 @@ function hostCallAt(endpoint, method, params = {}, { timeoutMs = 15000 } = {}) {
   })
 }
 
+export const VERSION = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8')).version
+
+// The plugin version from the last successful ping.
+let hostVersion = null
+
 export async function hostAvailable() {
   try {
-    await hostCall('ping', {}, { timeoutMs: 2000 })
+    hostVersion = (await hostCall('ping', {}, { timeoutMs: 2000 }))?.version ?? null
     return true
   } catch {
     return false
   }
 }
 
+export const hostVersionSeen = () => hostVersion
+
+// The plugin and the MCP server update separately (Harness and npx), so they can drift.
+// A different major.minor gets a note asking to update the older side; patch releases mix.
+const minorOf = (v) => String(v).split('.').slice(0, 2).join('.')
+export function versionWarning(plugin = hostVersion, server = VERSION) {
+  if (!plugin || minorOf(plugin) === minorOf(server)) return null
+  return `The Harness plugin dsh-baton-host is ${plugin} but this MCP server is ${server}. Update the older one: the server with \`npx -y dsh-baton-mcp@latest setup\`, the plugin in Harness (Plugins → dsh-baton-host → Uninstall, then Add plugin → dsh-baton-host).`
+}
+
 // Who a relayed message is from, shown on it in the Harness chat: DSH_BATON_SENDER if set,
 // else the MCP client's name (claude-code, claude-ai → claude; codex-mcp-client → codex).
 export function senderOf(clientName = setting('SENDER')) {

package/src/server.mjs

@@ -5,7 +5,7 @@ import path from 'node:path'
 import * as core from './core.mjs'
 import { stableNodePath } from './setup.mjs'
 
-const SERVER = { name: 'dsh-baton', version: '0.3.0' }
+const SERVER = { name: 'dsh-baton', version: core.VERSION }
 const PROTOCOLS = ['2025-06-18', '2025-03-26', '2024-11-05']
 
 const str = (description) => ({ type: 'string', description })
@@ -154,6 +154,7 @@ const TOOLS = [
 ]
 
 let clientName = null
+let versionWarned = false
 
 function send(msg) {
   process.stdout.write(JSON.stringify(msg) + '\n')
@@ -184,7 +185,11 @@ async function handle(req) {
         const progress = token === undefined ? undefined : (done, message) =>
           send({ jsonrpc: '2.0', method: 'notifications/progress', params: { progressToken: token, progress: done, message } })
         const result = await tool.run(req.params.arguments || {}, { progress })
-        return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] }
+        const content = [{ type: 'text', text: JSON.stringify(result, null, 2) }]
+        // Said once per server process, the first time a call finds the versions apart.
+        const warning = !versionWarned && core.versionWarning()
+        if (warning) { versionWarned = true; content.push({ type: 'text', text: `Note for the user: ${warning}` }) }
+        return { content }
       } catch (e) {
         return { content: [{ type: 'text', text: e.message }], isError: true }
       }

package/src/setup.mjs

@@ -5,7 +5,7 @@ import fs from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
 import { execFileSync } from 'node:child_process'
-import { ROOT, config, hostAvailable } from './core.mjs'
+import { ROOT, config, hostAvailable, hostVersionSeen as versionOfHost, versionWarning } from './core.mjs'
 
 const NAME = 'dsh-baton'
 // The name before the rename: setup removes its entries so the tools are not listed twice.
@@ -85,6 +85,63 @@ function installedPlugins() {
   }
 }
 
+// With pnpm's hoisted layout, uninstalling the plugin can leave its node_modules link
+// behind. Remove such a link once the profile no longer lists the plugin; only the
+// link itself goes, never the folder it points to. Returns the links removed and the
+// ones that could not be.
+export function cleanStalePluginLinks(profile = path.join(config.dshHome, 'profiles', 'desktop')) {
+  let deps
+  try { deps = JSON.parse(fs.readFileSync(path.join(profile, 'package.json'), 'utf8')).dependencies ?? {} } catch { return { removed: [], failed: [] } }
+  const removed = [], failed = []
+  for (const name of ['dsh-baton-host', 'dsh-bridge-host']) {
+    const link = path.join(profile, 'node_modules', name)
+    if (deps[name]) continue
+    let st
+    try { st = fs.lstatSync(link) } catch { continue }
+    if (!st.isSymbolicLink()) continue
+    try {
+      // A Windows junction is a directory link: rmdir removes the link, not its target.
+      try { fs.unlinkSync(link) } catch { fs.rmdirSync(link) }
+      removed.push(link)
+    } catch {
+      failed.push(link)
+    }
+  }
+  return { removed, failed }
+}
+
+// What setup says about the Harness plugin. The plugin is installed in Harness by its npm
+// package name; a checkout of this repo (setup run from a git clone) is the exception and
+// links its own host folder, so plugin changes can be tried before they are published.
+export function pluginSteps({ current, old }, running, hostDir, fromSource = fs.existsSync(path.join(ROOT, '.git'))) {
+  const isLink = (spec) => /^(link|file):/.test(spec ?? '')
+  const ok = fromSource ? pluginFrom(current, hostDir) : current && !isLink(current)
+  if (ok && !old && running) {
+    const warning = versionWarning(running)
+    return warning ? ['Harness plugin: running, but out of step.', `  ${warning}`] : [`Harness plugin: running (${running}).`]
+  }
+  const steps = ['Last step, in DeepSeek Harness:']
+  // The plugin was renamed: Harness cannot load the old entry once its folder holds the new name.
+  if (old) steps.push('  The plugin is installed under its old name: first Plugins (插件) → dsh-bridge-host → Uninstall (卸载).')
+  if (current && !ok) {
+    steps.push(isLink(current)
+      ? `  The plugin installed now comes from a local folder (${current.replace(/^(link|file):/, '')}): first Plugins (插件) → dsh-baton-host → Uninstall (卸载).`
+      : '  The plugin installed now comes from npm, not this checkout: first Plugins (插件) → dsh-baton-host → Uninstall (卸载).')
+  }
+  if (ok && !old) return ['Harness plugin: installed but not answering. Open Harness and check that dsh-baton-host is switched on in Plugins (插件).']
+  if (fromSource) {
+    const copied = copyToClipboard(hostDir)
+    steps.push(`  Plugins (插件) → Add plugin (添加插件) → paste ${copied ? 'the path (already copied)' : 'this path'}: ${hostDir}`)
+  } else {
+    const copied = copyToClipboard(PLUGIN)
+    steps.push(`  Plugins (插件) → Add plugin (添加插件) → registry: Official npm registry → package: ${PLUGIN}${copied ? ' (already copied)' : ''}`)
+  }
+  steps.push('  → Install (安装) → Enable now (立即启用)')
+  return steps
+}
+
+const PLUGIN = 'dsh-baton-host'
+
 const pluginFrom = (source, hostDir) => source === `link:${hostDir}` || source === `link:${hostDir.split(path.sep).join('/')}`
 
 // The node to register: the one on PATH when it is this same binary, since that path
@@ -143,32 +200,28 @@ export async function setup({ remove = false } = {}) {
 
   if (remove) {
     const plugins = installedPlugins()
-    lines.push('', `To remove the Harness plugin: Harness → Plugins → ${plugins.old && !plugins.current ? 'dsh-bridge-host' : 'dsh-baton-host'} → Uninstall.`)
+    if (plugins.current || plugins.old) {
+      lines.push('', `To remove the Harness plugin: Harness → Plugins → ${plugins.current ? 'dsh-baton-host' : 'dsh-bridge-host'} → Uninstall.`)
+    } else {
+      lines.push('', 'Harness plugin: not installed.')
+      const links = cleanStalePluginLinks()
+      for (const l of links.removed) lines.push(`Removed the leftover plugin link ${l}.`)
+      for (const l of links.failed) lines.push(`Could not remove the leftover plugin link ${l}: quit Harness and delete it.`)
+    }
     const app = appDir()
     if (fs.existsSync(app)) {
       // Harness loads the plugin from this folder: delete it only once the plugin is gone.
       if (pluginFrom(plugins.current, path.join(app, 'host'))) lines.push(`Then run this again to delete ${app}.`)
       else { fs.rmSync(app, { recursive: true, force: true }); lines.push(`Deleted ${app}.`) }
     }
+    const home = config.batonHome
+    if (['runs', 'host-runs'].some((d) => fs.existsSync(path.join(home, d)))) {
+      lines.push(`Run records are kept in ${home} (runs, host-runs); delete that folder to remove them too.`)
+    }
     return lines.join('\n')
   }
   lines.push('', 'MCP server registered user-wide: new conversations in Claude Code and Codex have the dsh_* tools.')
 
-  const hostDir = path.join(root, 'host')
-  const { current: source, old } = installedPlugins()
-  const fromHere = pluginFrom(source, hostDir)
-  const running = await hostAvailable()
-  if (running && !old && (fromHere || !source)) {
-    lines.push('', 'Harness plugin: running.')
-  } else {
-    const copied = copyToClipboard(hostDir)
-    lines.push('', 'Last step, in DeepSeek Harness:')
-    // The plugin was renamed: Harness cannot load the old entry once its folder holds the new name.
-    if (old) lines.push('  The plugin is installed under its old name: first Plugins (插件) → dsh-bridge-host → Uninstall (卸载).')
-    if (source && !fromHere) lines.push(`  The plugin installed now comes from another folder (${source}): first Plugins (插件) → dsh-baton-host → Uninstall (卸载).`)
-    lines.push(
-      `  Plugins (插件) → Add plugin (添加插件) → paste ${copied ? 'the path (already copied)' : 'this path'}: ${hostDir}`,
-      '  → Install (安装) → Enable now (立即启用)')
-  }
+  lines.push('', ...pluginSteps(installedPlugins(), await hostAvailable() ? versionOfHost() : null, path.join(root, 'host')))
   return lines.join('\n')
 }