dsh-plugin-rea 2.0.8 → 2.0.9

package/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 本插件遵循语义化版本。版本号变化说明「配置组合」这层的变化，与 REA 自身的版本无关。
 
+## 2.0.9 — 2026-10-18
+
+**2.0.8 的两处发布前问题（假回退、乱码）与若干文档缺口；不改正常路径，只让失败路径说真话。**
+
+### 修复
+
+- **`reexecFromCheckout` 的「回退」是假话**：spawn 失败时只打印「继续用镜像副本」，函数却返回了，`main()` 已经
+  return —— 没有 `exit` 事件、事件循环排空、进程以 **exit 0 静默退出**，行看起来启动成功却没有任何工具。现在这个
+  Promise **只在没接管时才 resolve**：子进程活着时本进程等待、由子进程的退出码决定；失败则 `main()` 继续用本地副本
+  启动，并如实说明在回退。
+- **回退覆盖了升级竞态的主形态**：`spawn` 的目标是 `process.execPath`，spawn 级失败几乎只剩资源耗尽；真正常见的是
+  「哈希比对通过 → node 启动 → 文件已被换掉」→ node 以 `MODULE_NOT_FOUND` 退 1。现在**退出码非 0 且源文件已不存在**
+  时同样回退到本地副本（窗口毫秒级，代价是一次 `stat`），不再把竞态变成一行死掉的 MCP。
+- **乱码 `鈥?` 混进用户可见输出**：2.0.7 在 GBK 编辑器里碰过 `bin/rea-shim.mjs`，16 处破折号被写成 `鈥?`，其中两条是
+  stderr 消息（首次自动供给、上次供给失败）—— 每个用户都会看到。全部还原为 `— `（含被吃掉的空格）。
+- **开发时可能测到「已安装插件」而不是自己的改动**：checkout 副本会顺着 bundle 的 `mirror.json` 转发到插件目录。
+  现在 checkout（带 `cordis.patch.yml`）永不转发，只有镜像副本会；注释也改成与行为一致。
+- **带 BOM 的 `mirror.json` / `bundle.json` 被当成「没有记录」**：`JSON.parse` 拒绝前导 BOM，而每个调用方都把解析失败
+  读成「无记录」。Windows 编辑器保存的 JSON 就会带 BOM，表现是镜像自愈静默不生效、bundle 被当成未供给。`bin/rea-shim.mjs`
+  与 `scripts/setup.mjs` 现在都经各自的 `readJson()` 去掉 `U+FEFF` 再解析。**两个文件读的是同一份记录，所以缺一不可**：
+  此前只有 shim 剥了 BOM，带 BOM 的 `mirror.json` 在 setup 眼里仍是「没有 checkout」，镜像 layout 下的 setup 于是把上一版
+  manifest 又镜了一遍并从它供给；`bundle.json` 同理被读成未供给。`verify-branch.ps1` 与 CI 都加了守卫：这两个文件里
+  出现裸的 `JSON.parse(readFileSync(...))` 即失败。
+
+### 文档 / CI
+
+- 两份 README 的钉版本示例改为**当前版本** `#v2.0.9`（2.0.8 那一轮已从 `#v2.0.0` 提到 `#v2.0.8`，版本号一动就得跟上，
+  否则读者拿到的 ref 不存在）；README 的「机器上已有 REA」一节补上 Windows 限制：**强制结束 shim 不会带走被委派的 REA**。
+- `docs/bundle-design.md`（随包发布）补上 2.0.7 的 launch mode 与 2.0.8 的镜像自愈，含 `mirror.json` 的
+  `shimSha256` / `pluginVersion` / `dshHome` 三个字段与控制流图。
+- CI 新增两条：README 必须逐字引用 `engines.dsh`；README 的钉版本示例必须等于 `package.json` 的 version（`verify-branch.ps1`
+  同步加了第二条，避免同一个漂移第三次发生）。
+- `systemReaCandidates` 的去重键改用传入的 `platform` 参数（测试缝一致，生产无变化）。
+
+### 验证
+
+- 单测 **71 条**（68 过 + 3 平台跳过；新增「checkout 副本不转发」「文件中途消失 → 回退」「带 BOM 的 `mirror.json`」
+  「带 BOM 的 `bundle.json`」四条）；镜像转发测试改为真的运行镜像副本。
+- `verify-branch.ps1` 44 项全绿；`audit-manifest` clean；`host-compat` 10 covered / 5 outside。
+
 ## 2.0.8 — 2026-10-18
 
 **2.0.7 的启动检测在两种边界上会失控：一个包着本 shim 的 `rea` 会让探针递归成进程链；超时探针会漏掉一个孙进程。两条都已修，并补了复现测试。**

package/README.md

@@ -100,7 +100,7 @@ releases, checksum-verified). Then install the plugin for your profile:
 ```
 dsh plugin --profile <profile> add dsh-plugin-rea
 # or pin this release instead of tracking npm latest:
-dsh plugin --profile <profile> add github:czcdr/dsh-plugin-rea#v2.0.0
+dsh plugin --profile <profile> add github:czcdr/dsh-plugin-rea#v2.0.9
 ```
 
 > **On an Electron host (the DeepSeek Harness desktop app) the profile is owned by the application.**
@@ -161,6 +161,9 @@ runs **that**, exactly as the 1.x line did, and nothing is provisioned:
   list says why a candidate was skipped (`"exit 7"`, `"inside the bundle"`, `"timeout"`).
 - A delegated child carries `REA_BUNDLE_DELEGATED=1`, so a wrapper that calls this shim cannot make it delegate to
   itself forever.
+- **On Windows a forced kill of the shim does not reap the delegated REA.** There is no job object here: Task Manager
+  or a supervisor terminating the shim leaves your `rea` running with the row's pipes (a console Ctrl+C reaches the
+  whole process group and does stop it). On POSIX the child is in the same group and dies with the terminal.
 
 ## Configure — nothing
 

package/README.zh-CN.md

@@ -94,7 +94,7 @@ profile 安装插件：
 ```
 dsh plugin --profile <profile> add dsh-plugin-rea
 # 或钉住这个版本，而不是跟着 npm latest 走：
-dsh plugin --profile <profile> add github:czcdr/dsh-plugin-rea#v2.0.0
+dsh plugin --profile <profile> add github:czcdr/dsh-plugin-rea#v2.0.9
 ```
 
 > **Electron 宿主（DeepSeek Harness 桌面版）的 profile 由应用独占。** 那种机器上 `dsh plugin --profile desktop …`
@@ -149,6 +149,9 @@ node scripts/setup.mjs --reuse      # 或先 --dry-run 看计划
 - `--shim-status` 会把判断结果打出来 —— `launch.mode`、`launch.reason`、`launch.systemRea`，`launch.rejected` 里
   写的是每个候选被跳过的原因（`"exit 7"`、`"inside the bundle"`、`"timeout"`）。
 - 被委派的子进程带着 `REA_BUNDLE_DELEGATED=1`，所以一个调用本 shim 的 wrapper 不会让它无限委派给自己。
+- **Windows 上强制结束 shim 不会带走被委派的 REA**：这里没有 job object，任务管理器或 supervisor 终止 shim 时，
+  你自己的 `rea` 会继续占着这一行的管道（控制台 Ctrl+C 会发给整个进程组，那种情况下会一起停）。POSIX 上子进程
+  在同一进程组，随终端一起退出。
 
 ## 配置 —— 不需要
 

package/bin/rea-shim.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * rea-shim 鈥?the process the DSH MCP row launches.
+ * rea-shim — the process the DSH MCP row launches.
  *
  * Why this exists: the published `cordis.patch.yml` must carry no machine path,
  * yet REA needs absolute paths for every dependency. The shim is the seam: it
@@ -10,7 +10,7 @@
  * It downloads nothing, writes nothing, and never touches PATH.
  *
  * Exit codes:  0 child exited normally   * child's own status
- *              78 EX_CONFIG  bundle not provisioned (or unusable) 鈥?the row has
+ *              78 EX_CONFIG  bundle not provisioned (or unusable) — the row has
  *                            `failOnStartupError: false`, so the harness stays up
  *                            and the message is the operator's remediation.
  */
@@ -26,6 +26,19 @@ const EX_CONFIG = 78;
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const PLUGIN_ROOT = path.resolve(HERE, "..");
 
+/**
+ * JSON from disk, tolerating the UTF-8 BOM a Windows editor writes.
+ *
+ * `JSON.parse` rejects a leading BOM, and every caller here reads a parse
+ * failure as "no record": a BOM would silently downgrade mirror.json to "no
+ * plugin checkout" and bundle.json to "not provisioned". Measured while testing
+ * this file — a hand-edited mirror.json written by Windows PowerShell behaved
+ * exactly that way.
+ */
+function readJson(file) {
+  return JSON.parse(readFileSync(file, "utf8").replace(/^\uFEFF/, ""));
+}
+
 /** DSH home, by the same rule setup.mjs and the published patch use. */
 function dshHome() {
   const fromEnv = process.env.DSH_HOME;
@@ -45,7 +58,7 @@ function recordedDshHome(root) {
   if (recordedDshHomeCache !== null) return recordedDshHomeCache;
   let value = null;
   try {
-    const record = JSON.parse(readFileSync(path.join(root, "mirror.json"), "utf8"));
+    const record = readJson(path.join(root, "mirror.json"));
     if (typeof record?.dshHome === "string" && record.dshHome.trim() !== "" && path.isAbsolute(record.dshHome)) {
       value = path.resolve(record.dshHome);
     }
@@ -74,11 +87,11 @@ function dshHomeFor(root) {
  *    DSH_HOME: the harness strips every `DSH_*` name from an MCP child's
  *    environment (case-insensitively, because Windows is), so a custom DSH_HOME
  *    would send it to `~/.dsh`, where it would report "not provisioned" for a
- *    bundle sitting right next to it 鈥?and start a second ~800 MB run there.
+ *    bundle sitting right next to it — and start a second ~800 MB run there.
  *  * The **checkout** copy (`<plugin>/bin/rea-shim.mjs`) is what a human runs, e.g.
  *    `npm run bundle:status`, from a shell where DSH_HOME *is* visible. Its own
  *    directory is the plugin, not the bundle, so resolving to itself would report
- *    "not provisioned" on a fully provisioned machine 鈥?and a bare
+ *    "not provisioned" on a fully provisioned machine — and a bare
  *    `node bin/rea-shim.mjs mcp` would provision ~800 MB into the checkout.
  *
  * Only the checkout ships `cordis.patch.yml`, so that file is the discriminator.
@@ -111,11 +124,11 @@ function usableSetup(dir) {
  * The mirrored copy is a snapshot: after a plugin upgrade it still holds the
  * previous manifest, so it would provision the previous versions forever. setup
  * writes <bundle>/mirror.json naming the real checkout; prefer that while it is
- * usable, and fall back to the local copy 鈥?which is also all a first run has.
+ * usable, and fall back to the local copy — which is also all a first run has.
  */
 function provisioningScript(root) {
   try {
-    const record = JSON.parse(readFileSync(path.join(root, "mirror.json"), "utf8"));
+    const record = readJson(path.join(root, "mirror.json"));
     const recorded = usableSetup(record && record.pluginRoot);
     if (recorded) return recorded;
   } catch {
@@ -167,7 +180,7 @@ function foreignReaRegistration(root) {
 /**
  * The provisioning lock is a small JSON record: { state, pid, at, exit? }.
  * `state: "running"` is written when a run is started (setup's own pid once it
- * exists), and the failing run rewrites it as `state: "failed"` 鈥?it is kept on
+ * exists), and the failing run rewrites it as `state: "failed"` — it is kept on
  * purpose so a broken setup cannot be re-downloaded in a loop. A legacy
  * plain-number lock is still honoured as "running".
  */
@@ -205,7 +218,7 @@ function pidAlive(pid) {
  * a killed attempt is simply continued on the next start.
  *
  * Set REA_BUNDLE_AUTO_PROVISION=0 to require an explicit `setup.mjs` run.
- * Returns { started, reason, logPath } 鈥?the caller words its message from
+ * Returns { started, reason, logPath } — the caller words its message from
  * `reason`, because "provisioning started in the background" was also printed
  * for a lock left behind by a run that had already failed, and for one whose
  * process was long gone.
@@ -242,7 +255,7 @@ function maybeAutoProvision(root) {
     // Reached when the lock is older than the freshness window, or its holder is
     // gone and never wrote an outcome (harness restart, power loss, a kill): what
     // it records is not happening any more. This removal is the whole point of the
-    // freshness rule 鈥?without it the exclusive create below failed with EEXIST
+    // freshness rule — without it the exclusive create below failed with EEXIST
     // *forever*, auto-provisioning never ran again, and main() printed nothing at
     // all for that outcome. The lock's own "honour it only while it is fresh"
     // comment described behaviour the code did not have.
@@ -299,7 +312,7 @@ function fail(message, detail) {
   if (detail) lines.push("", "  detail: " + detail);
   // Point at the real checkout when the record allows it: running the mirrored
   // copy is fine, but it can only ever provision the manifest it was mirrored
-  // with 鈥?and a bundle mirrored before the manifest travelled with it has no
+  // with — and a bundle mirrored before the manifest travelled with it has no
   // usable copy at all, so the honest answer is then "run the plugin's own script".
   const root = bundleRoot();
   const setupScript = provisioningScript(root);
@@ -333,7 +346,7 @@ function readBundleConfig(root) {
   if (!existsSync(file)) return { ok: false, code: "missing", file };
   let parsed;
   try {
-    parsed = JSON.parse(readFileSync(file, "utf8"));
+    parsed = readJson(file);
   } catch (error) {
     return { ok: false, code: "malformed", file, detail: String(error && error.message) };
   }
@@ -350,7 +363,7 @@ function resolveRea(config, root) {
   // The fallback has to match where setup actually installs the package:
   // `npm install --prefix <root>/vendor` resolves into vendor/node_modules, so a
   // fallback without that segment named a directory that never exists. It only
-  // fires when an older bundle.json has no paths.reaEntry 鈥?which is exactly when
+  // fires when an older bundle.json has no paths.reaEntry — which is exactly when
   // a wrong fallback turns a usable install into "the vendored REA CLI is gone".
   const reaEntry = paths.reaEntry
     ?? path.join(root, "vendor", "node_modules", "rea-agents", "scripts", "rea.mjs");
@@ -407,7 +420,7 @@ function childEnvironment(config) {
  * the machine already has one, the honest thing to do is run it.
  *
  * The 1.x line was exactly that: `rea mcp` off PATH, user-managed Node and
- * Ghidra. So "use the system install" is not a new code path invented here 鈥?it
+ * Ghidra. So "use the system install" is not a new code path invented here — it
  * is the 1.x contract, reachable from the 2.x row. `auto` (the default) prefers
  * the system install and falls back to the provisioned bundle; `bundle` pins the
  * old behaviour; `system` insists (and fails loudly instead of provisioning
@@ -466,7 +479,7 @@ function systemReaNames(platform = process.platform) {
 /**
  * Every path worth probing, most explicit first.
  *
- * `REA_BUNDLE_SYSTEM_REA` names one binary outright 鈥?that is both the test
+ * `REA_BUNDLE_SYSTEM_REA` names one binary outright — that is both the test
  * seam and a real operator need (an install that is not on the harness's PATH,
  * which on Desktop is not the user's shell PATH).
  */
@@ -488,7 +501,9 @@ function systemReaCandidates({ env = process.env, platform = process.platform }
   }
   const seen = new Set();
   return candidates.filter((candidate) => {
-    const key = process.platform === "win32" ? candidate.toLowerCase() : candidate;
+    // Keyed on the platform being RESOLVED, not on the one this process happens
+    // to run: the tests pass `platform` to exercise both shapes on one machine.
+    const key = platform === "win32" ? candidate.toLowerCase() : candidate;
     if (seen.has(key)) return false;
     seen.add(key);
     return true;
@@ -724,7 +739,7 @@ function compareDotted(a, b) {
  * the one this bundle provisioned would silently take the tool count back
  * (6.4.0 ships 170 tools, 6.5.0 ships 207), so the newer of the two wins and
  * the older is only used when asked for by name. `bundle` and `system` are
- * honoured literally 鈥?`system` fails loudly rather than provisioning 800 MB
+ * honoured literally — `system` fails loudly rather than provisioning 800 MB
  * behind an operator who asked for their own REA.
  */
 async function resolveLaunch({ root, bundleVersion = null, bundleProvisioned = false, env = process.env, platform = process.platform } = {}) {
@@ -863,7 +878,7 @@ function sha256(file) {
 /** Where the installed plugin lives according to setup's record, or null. */
 function pluginCheckout(root) {
   try {
-    const record = JSON.parse(readFileSync(path.join(root, "mirror.json"), "utf8"));
+    const record = readJson(path.join(root, "mirror.json"));
     const dir = record?.pluginRoot;
     if (typeof dir !== "string" || dir.trim() === "") return null;
     const shim = path.join(dir, "bin", "rea-shim.mjs");
@@ -883,7 +898,7 @@ function pluginCheckout(root) {
 function describeMirror(root, { self = fileURLToPath(import.meta.url) } = {}) {
   let record = null;
   try {
-    record = JSON.parse(readFileSync(path.join(root, "mirror.json"), "utf8"));
+    record = readJson(path.join(root, "mirror.json"));
   } catch {
     return null;
   }
@@ -910,32 +925,71 @@ function describeMirror(root, { self = fileURLToPath(import.meta.url) } = {}) {
   };
 }
 
-/** Run the checkout's launcher instead of this copy, once. */
+/**
+ * Run the checkout's launcher instead of this copy, once.
+ *
+ * The promise resolves ONLY when the re-exec did not take over, and the caller
+ * must then continue with its own launch path. While the child is alive the
+ * promise stays pending and the child's own exit becomes this process's exit —
+ * settling it at the `spawn` event was wrong: the event fires before the child
+ * has done anything, so a later "it actually failed" could no longer be seen, and
+ * the two handlers disagreed about who owns the exit code. That mistake made the
+ * file-vanishes-mid-flight case exit 0 silently.
+ *
+ * The first version of this printed "continuing with the mirrored copy" on
+ * `error` and returned: nothing continued, no `exit` event followed a failed
+ * spawn, the loop drained, and the row saw exit 0 with no tools and no message.
+ * A fallback that is announced but not performed is worse than none, because it
+ * hides the failure it was written for.
+ */
 function reexecFromCheckout(source, argv) {
   const child = spawn(process.execPath, [source, ...argv], {
     stdio: "inherit",
     env: { ...process.env, REA_BUNDLE_SHIM_REEXEC: "1" },
     windowsHide: true,
   });
-  child.on("error", () => {
-    // Falling back is better than failing: the copy still knows how to launch.
-    process.stderr.write(`rea-shim: could not run ${source}; continuing with the mirrored copy.\n`);
-  });
-  child.on("exit", (code, signal) => {
-    if (signal) {
-      const signals = { SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGKILL: 9, SIGTERM: 15 };
-      process.exit(128 + (signals[signal] ?? 0));
-    }
-    process.exit(code ?? 0);
+  return new Promise((resolve) => {
+    let started = false;
+    child.once("spawn", () => {
+      started = true;
+    });
+    child.once("error", () => {
+      if (started) return;
+      resolve(false);
+    });
+    child.once("exit", (code, signal) => {
+      if (!started) {
+        // Exit without a spawn event: the child never ran. Let the caller fall
+        // back rather than exiting 0 on its behalf.
+        resolve(false);
+        return;
+      }
+      if (signal) {
+        const signals = { SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGKILL: 9, SIGTERM: 15 };
+        process.exit(128 + (signals[signal] ?? 0));
+      }
+      // A non-zero exit is normally the child's own answer and must be passed
+      // through untouched. One case is not the child's answer: an upgrade in
+      // flight replaced the file BETWEEN the check and node reading it, so node
+      // starts fine and dies with MODULE_NOT_FOUND. Passing that on turns a
+      // millisecond race into a dead row; if the source is gone by now, fall back
+      // to this copy instead. The window is small, the cost of covering it is one
+      // stat, and the alternative is a row that reports failure for a file that
+      // still exists a directory up.
+      if ((code ?? 0) !== 0 && !isFileSync(source)) {
+        resolve(false);
+        return;
+      }
+      process.exit(code ?? 0);
+    });
   });
-  return null;
 }
 
 /**
  * Usage text, also what a bare invocation prints.
  *
  * `package.json` exposes this file as the `rea-bundle-status` bin, and npm's bin
- * shim can only forward the arguments a user typed 鈥?it cannot append a flag. So a
+ * shim can only forward the arguments a user typed — it cannot append a flag. So a
  * bare `rea-bundle-status`, which is exactly what that name invites, used to fall
  * through to the launch path: it started REA, and on an unprovisioned machine it
  * began an ~800 MB download. Reporting usage instead makes the command's behaviour
@@ -973,9 +1027,24 @@ async function main() {
   // market upgrade never re-runs setup. One hop, guarded, and never for the
   // status query — there the staleness is reported instead.
   const mirror = describeMirror(root);
-  if (mirror !== null && mirror.stale && process.env.REA_BUNDLE_SHIM_REEXEC !== "1" && !argv.includes("--shim-status")) {
+  // A CHECKOUT copy is the source, not a mirror: hopping from it into whatever
+  // the bundle's record names would silently run a different plugin — a developer
+  // testing a local edit would be testing the installed one instead. The
+  // discriminator is the one bundleRoot() already uses: only the checkout ships
+  // cordis.patch.yml.
+  const isCheckout = existsSync(path.join(PLUGIN_ROOT, "cordis.patch.yml"));
+  if (!isCheckout && mirror !== null && mirror.stale && process.env.REA_BUNDLE_SHIM_REEXEC !== "1" && !argv.includes("--shim-status")) {
     const source = pluginCheckout(root);
-    if (source !== null) return reexecFromCheckout(source, argv);
+    if (source !== null) {
+      // It resolves only when the re-exec did not take over; while the child
+      // runs, this process is parked and the child's exit is the exit.
+      await reexecFromCheckout(source, argv);
+      // The re-exec did not take over: a spawn failure, a child that exited
+      // before its spawn event, or one that started and found its own file gone
+      // (see the exit handler). Say so and run this copy for real — the point of
+      // the fallback.
+      process.stderr.write(`rea-shim: could not run ${source}; running the mirrored copy instead.\n`);
+    }
   }
   const loaded = readBundleConfig(root);
   // Decide what to run before asking whether the bundle is provisioned: a
@@ -1073,12 +1142,12 @@ async function main() {
     const provisioning = maybeAutoProvision(root);
     if (provisioning.started) {
       process.stderr.write(
-        `\n  dsh-plugin-rea (bundle): first run 鈥?provisioning started in the background.\n  progress: ${provisioning.logPath}\n`,
+        `\n  dsh-plugin-rea (bundle): first run — provisioning started in the background.\n  progress: ${provisioning.logPath}\n`,
       );
     } else if (provisioning.reason === "last-run-failed") {
       process.stderr.write(
         `\n  dsh-plugin-rea (bundle): the last provisioning attempt failed (exit ${provisioning.exit ?? "?"}).\n` +
-          `  Nothing is running right now 鈥?read the log, then re-run setup.\n  log: ${provisioning.logPath}\n`,
+          `  Nothing is running right now — read the log, then re-run setup.\n  log: ${provisioning.logPath}\n`,
       );
     } else if (provisioning.reason === "in-flight") {
       // A live run owns the lock. Saying nothing here is what made a wedged

package/docs/bundle-design.md

@@ -83,7 +83,10 @@ through `failOnStartupError: false` without breaking the harness.
 ```
 dsh starts
   └─ MCP row: node <bundle root>/bin/rea-shim.mjs   (setup mirrors it there)
-       ├─ bundle.json present & components verify  → exec REA (normal path)
+       ├─ mirrored copy differs from the installed plugin → re-exec that copy, once
+       ├─ a working `rea` on PATH is at least as new as the bundle
+       │                                            → exec it (the 1.x contract)
+       ├─ bundle.json present & components verify  → exec the provisioned REA
        ├─ missing, auto-provision allowed         → start setup detached, print
        │                                            remediation, exit non-zero
        └─ missing, auto-provision refused         → print exact command, exit
@@ -129,6 +132,26 @@ Two notes on stages that exist because their absence was a bug:
   harness's own dialect, `args[0]` became `{"[object Object]": "..."}` and the
   row could not launch at all. Any future expression with a ternary needs the
   quotes; `audit-manifest.mjs` rejects the bare form.
+- **Launch mode (2.0.7).** 2.x exists to supply a runtime a machine lacks, so a
+  machine that already has one should not be provisioned. Before touching bundle
+  state the shim asks whether `rea` is on PATH and answers `--version`; if it
+  does, and its version is not older than `bundle.json`'s `versions.reaAgents`,
+  the row execs that install exactly as the 1.x row did. The probe is asynchronous
+  and bounded (8 s: a `.cmd` shim needs ~2.4 s), runs with
+  `REA_BUNDLE_DELEGATED=1` and `REA_BUNDLE_AUTO_PROVISION=0` so a candidate that
+  wraps this shim cannot recurse or start an 800 MB run, and kills its whole tree
+  on timeout. `REA_BUNDLE_LAUNCH=auto|system|bundle` overrides the choice; an
+  unorderable pair (a prerelease on either side) keeps the bundle.
+- **Self-healing mirror (2.0.8).** The row launches a COPY, and a market upgrade
+  runs no setup, so without this the copy keeps executing the code it was made
+  from — invisibly, because it still works. The copy therefore compares its own
+  hash with `<mirror.json.pluginRoot>/bin/rea-shim.mjs` and re-execs that file
+  when they differ: one hop, guarded by `REA_BUNDLE_SHIM_REEXEC`, and only from a
+  mirror (a checkout ships `cordis.patch.yml`, so it never hops into another
+  copy). `mirror.json` carries `shimSha256`, `pluginVersion` and `dshHome` —
+  the last one because the harness strips `DSH_*` from an MCP child, so the
+  duplicate-registration check would otherwise read `~/.dsh` on a machine with a
+  custom home. `--shim-status` reports `mirror.stale` instead of hopping.
 - **3 (fetch).** Route order is deliberate and environment-dependent: direct
   first, then the system proxy, and on Windows the .NET route ahead of both
   because it follows the GitHub release-asset redirect that the Node routes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-rea",
-  "version": "2.0.8",
+  "version": "2.0.9",
   "description": "One-plugin bundle: provisions Node/REA/JDK/Ghidra for you, then registers the upstream REA MCP server as mcp__rea__* tools. · 一体包：自动准备 Node/REA/JDK/Ghidra，并把上游 REA 的 MCP 服务接入 DeepSeek Harness。",
   "type": "module",
   "main": "./index.mjs",

package/scripts/setup.mjs

@@ -954,6 +954,21 @@ function reuseExisting(name, root) {
 
 /* ------------------------------------------------------------------- manifest */
 
+/**
+ * JSON from disk, tolerating the UTF-8 BOM a Windows editor writes.
+ *
+ * `JSON.parse` rejects a leading BOM, and every caller in this file treats a
+ * parse failure as "no record". A BOM-ed mirror.json therefore meant "this is
+ * not a mirrored run", so setup went on to re-mirror the previous manifest;
+ * a BOM-ed bundle.json meant "nothing is provisioned". `bin/rea-shim.mjs`
+ * carries the same helper — the two must agree, or the same file means two
+ * different things depending on which one read it (a hand-edited record with
+ * PowerShell's BOM is exactly the case that produced this).
+ */
+function readJson(file) {
+  return JSON.parse(readFileSync(file, "utf8").replace(/^\uFEFF/, ""));
+}
+
 /**
  * Where this run's plugin files actually live.
  *
@@ -973,7 +988,7 @@ function sourceRoot() {
   const self = path.resolve(PLUGIN_ROOT);
   if (!samePath(self, options.root)) return self;
   try {
-    const record = JSON.parse(readFileSync(path.join(options.root, "mirror.json"), "utf8"));
+    const record = readJson(path.join(options.root, "mirror.json"));
     const recorded = record?.pluginRoot;
     if (typeof recorded === "string" && recorded.trim() !== "") {
       const candidate = path.resolve(recorded);
@@ -987,7 +1002,7 @@ function sourceRoot() {
 
 function loadManifest() {
   const file = path.join(sourceRoot(), "manifest", "bundle.manifest.json");
-  const parsed = JSON.parse(readFileSync(file, "utf8"));
+  const parsed = readJson(file);
   return parsed;
 }
 
@@ -1002,7 +1017,7 @@ function loadManifest() {
 function readBundleJson(file) {
   if (!existsSync(file)) return null;
   try {
-    const parsed = JSON.parse(readFileSync(file, "utf8"));
+    const parsed = readJson(file);
     return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
   } catch (error) {
     log(`       ${path.basename(file)} is not readable JSON (${String(error && error.message)}); ignoring it for this run`);
@@ -1648,7 +1663,7 @@ function writeMirrorRecord(context, source) {
     /* the copy is missing or unreadable; the shim reports the comparison itself */
   }
   try {
-    record.pluginVersion = JSON.parse(readFileSync(path.join(source, "package.json"), "utf8")).version ?? null;
+    record.pluginVersion = readJson(path.join(source, "package.json")).version ?? null;
   } catch {
     record.pluginVersion = null;
   }

package/scripts/setup.test.mjs

@@ -1313,13 +1313,13 @@ function writeFakeRea(dir, { version = "6.9.0", exitForVersion = 0, runExit = 0,
   return file;
 }
 
-function runShimIsolated(env, args) {
+function runShimIsolated(env, args, shim = path.join(REPO_ROOT, "bin", "rea-shim.mjs")) {
   const merged = { ...process.env, ...env };
   // Windows keeps PATH and Path as separate variables (both are "in" the
   // environment), and a child that reads Path while the test set PATH would see
   // the machine's real search path instead of the fixture's.
   if (process.platform === "win32" && Object.prototype.hasOwnProperty.call(env, "PATH")) delete merged.Path;
-  return spawnSync(process.execPath, [path.join(REPO_ROOT, "bin", "rea-shim.mjs"), ...args], {
+  return spawnSync(process.execPath, [shim, ...args], {
     encoding: "utf8",
     timeout: 60000,
     env: merged,
@@ -1662,7 +1662,14 @@ test("a mirrored launcher re-execs the plugin's launcher when they differ", () =
   const marker = path.join(f.root, "checkout-ran");
   checkoutStub(f.checkout, marker);
   try {
-    const run = runShimIsolated({ REA_BUNDLE_ROOT: f.bundle, REA_BUNDLE_AUTO_PROVISION: "0", REA_BUNDLE_LAUNCH: "bundle" }, ["mcp"]);
+    // The mirrored copy is what the row launches, and the checkout guard means a
+    // checkout shim refuses to hop at all — so the fixture must be exercised as
+    // the mirror it is meant to be.
+    const run = runShimIsolated(
+      { REA_BUNDLE_ROOT: f.bundle, REA_BUNDLE_AUTO_PROVISION: "0", REA_BUNDLE_LAUNCH: "bundle" },
+      ["mcp"],
+      path.join(f.bundle, "bin", "rea-shim.mjs"),
+    );
     assert.equal(run.status, 7, `expected the checkout's status, got ${run.status}: ${run.stderr}`);
     assert.equal(existsSync(marker), true, "the checkout launcher must have run");
   } finally {
@@ -1678,6 +1685,7 @@ test("the re-exec happens once, and a pinned guard stops it", () => {
     const run = runShimIsolated(
       { REA_BUNDLE_ROOT: f.bundle, REA_BUNDLE_AUTO_PROVISION: "0", REA_BUNDLE_LAUNCH: "bundle", REA_BUNDLE_SHIM_REEXEC: "1" },
       ["mcp"],
+      path.join(f.bundle, "bin", "rea-shim.mjs"),
     );
     // The guard is set, so the mirrored copy runs its own logic: bundle pinned and
     // nothing provisioned means EX_CONFIG, and the checkout never starts.
@@ -1693,7 +1701,11 @@ test("--shim-status reports a stale mirror instead of re-execing it", () => {
   const marker = path.join(f.root, "checkout-ran");
   checkoutStub(f.checkout, marker);
   try {
-    const run = runShimIsolated({ REA_BUNDLE_ROOT: f.bundle, REA_BUNDLE_AUTO_PROVISION: "0", REA_BUNDLE_LAUNCH: "bundle" }, ["--shim-status"]);
+    const run = runShimIsolated(
+      { REA_BUNDLE_ROOT: f.bundle, REA_BUNDLE_AUTO_PROVISION: "0", REA_BUNDLE_LAUNCH: "bundle" },
+      ["--shim-status"],
+      path.join(f.bundle, "bin", "rea-shim.mjs"),
+    );
     const report = JSON.parse(run.stdout);
     assert.equal(report.mirror.stale, true, JSON.stringify(report.mirror));
     assert.match(report.mirror.reason, /different launcher/);
@@ -1703,12 +1715,65 @@ test("--shim-status reports a stale mirror instead of re-execing it", () => {
   }
 });
 
+test("a checkout shim does not hop into the installed plugin", () => {
+  const f = mirrorFixture();
+  const marker = path.join(f.root, "checkout-ran");
+  checkoutStub(f.checkout, marker);
+  try {
+    // The repository's own shim is a CHECKOUT (it ships cordis.patch.yml). A
+    // developer running it must keep testing the edit in front of them, not a
+    // different plugin that the bundle's record happens to name.
+    const run = runShimIsolated(
+      { REA_BUNDLE_ROOT: f.bundle, REA_BUNDLE_AUTO_PROVISION: "0", REA_BUNDLE_LAUNCH: "bundle" },
+      ["mcp"],
+    );
+    assert.equal(run.status, 78, run.stderr);
+    assert.equal(existsSync(marker), false, "a checkout must never hop into another copy");
+  } finally {
+    f.clean();
+  }
+});
+
+test("a re-exec whose file vanishes mid-flight falls back to the mirrored copy", () => {
+  // The upgrade race the spawn handshake cannot see: the file existed when the
+  // mirror compared hashes, node started, and the file was replaced before node
+  // read it — node exits 1 with MODULE_NOT_FOUND. Passing that through turns a
+  // millisecond race into a dead row, so a non-zero exit with the source gone
+  // must fall back instead.
+  const f = mirrorFixture();
+  const marker = path.join(f.root, "checkout-ran");
+  const file = path.join(f.checkout, "bin", "rea-shim.mjs");
+  writeFileSync(
+    file,
+    'import { rmSync, writeFileSync } from "node:fs";\n' +
+      `writeFileSync(${JSON.stringify(marker)}, "checkout");\n` +
+      `rmSync(${JSON.stringify(file)});\n` +
+      "process.exit(3);\n",
+  );
+  try {
+    const run = runShimIsolated(
+      { REA_BUNDLE_ROOT: f.bundle, REA_BUNDLE_AUTO_PROVISION: "0", REA_BUNDLE_LAUNCH: "bundle" },
+      ["mcp"],
+      path.join(f.bundle, "bin", "rea-shim.mjs"),
+    );
+    assert.equal(existsSync(marker), true, "the checkout launcher did run");
+    assert.equal(run.status, 78, `expected the local copy's status, got ${run.status}: ${run.stderr}`);
+    assert.match(run.stderr, /running the mirrored copy instead/);
+  } finally {
+    f.clean();
+  }
+});
+
 test("an identical mirror is not stale and is not re-exec'd", () => {
   const f = mirrorFixture();
   const same = path.join(f.checkout, "bin", "rea-shim.mjs");
   copyFileSync(path.join(f.bundle, "bin", "rea-shim.mjs"), same);
   try {
-    const run = runShimIsolated({ REA_BUNDLE_ROOT: f.bundle, REA_BUNDLE_AUTO_PROVISION: "0", REA_BUNDLE_LAUNCH: "bundle" }, ["--shim-status"]);
+    const run = runShimIsolated(
+      { REA_BUNDLE_ROOT: f.bundle, REA_BUNDLE_AUTO_PROVISION: "0", REA_BUNDLE_LAUNCH: "bundle" },
+      ["--shim-status"],
+      path.join(f.bundle, "bin", "rea-shim.mjs"),
+    );
     const report = JSON.parse(run.stdout);
     assert.equal(report.mirror.stale, false, JSON.stringify(report.mirror));
     assert.equal(report.mirror.reason, "this copy matches the plugin");
@@ -1745,3 +1810,82 @@ test("a mirrored shim finds the real DSH home when the environment is scrubbed",
     f.clean();
   }
 });
+
+/* ------------------------------------ records a Windows editor has BOM-ed */
+
+// `bin/rea-shim.mjs` strips the UTF-8 BOM that PowerShell and Notepad write;
+// setup.mjs kept parsing raw. Both programs read the same two records, so a BOM
+// used to mean two different things: the shim found the checkout, setup did not.
+// A mirrored setup then re-mirrored the previous manifest and provisioned from
+// it, and a BOM-ed bundle.json read as "nothing is provisioned". These tests pin
+// setup's side of the contract, both files.
+
+/** A checkout with a manifest whose node probe accepts any node, so `--only node` is deterministic. */
+function bomFixtureCheckout(root) {
+  const checkout = path.join(root, "checkout");
+  mkdirSync(path.join(checkout, "scripts"), { recursive: true });
+  mkdirSync(path.join(checkout, "manifest"), { recursive: true });
+  copyFileSync(SETUP_SOURCE, path.join(checkout, "scripts", "setup.mjs"));
+  const manifest = JSON.parse(readFileSync(MANIFEST_SOURCE, "utf8"));
+  manifest.components.node.probe.expect.regex = "^v";
+  writeFileSync(path.join(checkout, "manifest", "bundle.manifest.json"), JSON.stringify(manifest, null, 2));
+  writeFileSync(path.join(checkout, "package.json"), JSON.stringify({ name: "dsh-plugin-rea", version: "0.0.0-bom" }));
+  return checkout;
+}
+
+test("a BOM-ed mirror.json still points a mirrored setup at the real checkout", () => {
+  const root = mkdtempSync(path.join(tmpdir(), "rea-bom-mirror-"));
+  try {
+    const checkout = bomFixtureCheckout(root);
+    const bundle = path.join(root, "bundle");
+    mkdirSync(path.join(bundle, "scripts"), { recursive: true });
+    copyFileSync(SETUP_SOURCE, path.join(bundle, "scripts", "setup.mjs"));
+    // Exactly what `Out-File` / `Set-Content` leaves behind, and what a human
+    // editing the record by hand produces on Windows.
+    writeFileSync(
+      path.join(bundle, "mirror.json"),
+      "\uFEFF" + JSON.stringify({ schema: 1, pluginRoot: checkout, mirroredAt: "2026-10-18T00:00:00Z" }),
+    );
+    // The bundle has no manifest of its own: only the record can supply one.
+    assert.equal(existsSync(path.join(bundle, "manifest", "bundle.manifest.json")), false);
+
+    const run = spawnSync(
+      process.execPath,
+      [path.join(bundle, "scripts", "setup.mjs"), "--dry-run", "--only", "node", "--root", bundle],
+      { encoding: "utf8", timeout: 120000 },
+    );
+    assert.equal(run.status, 0, run.stderr);
+    // loadManifest() runs before any component: reaching the plan proves the
+    // record was parsed. A BOM-blind parse fell through to the bundle and died
+    // on a missing manifest.
+    assert.match(run.stdout, /\[plan\] node/);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("a BOM-ed bundle.json is read instead of treated as unprovisioned", () => {
+  const root = mkdtempSync(path.join(tmpdir(), "rea-bom-bundle-"));
+  try {
+    const checkout = bomFixtureCheckout(root);
+    const bundle = path.join(root, "bundle");
+    mkdirSync(bundle, { recursive: true });
+    const args = [path.join(checkout, "scripts", "setup.mjs"), "--dry-run", "--only", "node", "--root", bundle];
+
+    // Control: with no record at all the component is planned, so the assertion
+    // below cannot pass for a reason unrelated to reading the file.
+    const fresh = spawnSync(process.execPath, args, { encoding: "utf8", timeout: 120000 });
+    assert.equal(fresh.status, 0, fresh.stderr);
+    assert.match(fresh.stdout, /\[plan\] node/);
+
+    writeFileSync(
+      path.join(bundle, "bundle.json"),
+      "\uFEFF" + JSON.stringify({ schema: 1, components: { node: { path: process.execPath, version: "v-bom-test" } } }, null, 2),
+    );
+    const run = spawnSync(process.execPath, args, { encoding: "utf8", timeout: 120000 });
+    assert.equal(run.status, 0, run.stderr);
+    assert.match(run.stdout, /already provisioned \(v-bom-test\)/, run.stdout);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});

package/scripts/verify-branch.ps1

@@ -17,6 +17,31 @@ foreach ($f in @('index.mjs','bin\rea-shim.mjs','scripts\setup.mjs','scripts\aud
   Check $f ($LASTEXITCODE -eq 0) ($out -join ' ')
 }
 
+Write-Host "`n=== 1b. both JSON readers tolerate a BOM ===" -ForegroundColor Cyan
+# bin/rea-shim.mjs and scripts/setup.mjs read the same mirror.json and bundle.json.
+# A BOM strip on one side only makes one file mean "there is a checkout" to the
+# shim and "there is none" to setup, and the mirrored setup then re-mirrors the
+# previous manifest. A bare JSON.parse(readFileSync(...)) is that divergence.
+$jsBom = Join-Path $env:TEMP 'rea-verify-bom.cjs'
+@'
+const fs = require("node:fs");
+const blind = [];
+for (const file of ["bin/rea-shim.mjs", "scripts/setup.mjs"]) {
+  const text = fs.readFileSync(file, "utf8");
+  for (const m of text.matchAll(/JSON\.parse\(\s*readFileSync\(/g)) {
+    // readJson() itself is the strip; anything else must not parse a file raw.
+    if (!/replace\(/.test(text.slice(m.index, m.index + 200))) {
+      blind.push(file + "@" + text.slice(0, m.index).split("\n").length);
+    }
+  }
+  if (!text.includes("replace(/^\\uFEFF/")) blind.push(file + ": no U+FEFF strip");
+}
+console.log("bom-blind reads: " + JSON.stringify(blind));
+if (blind.length) process.exit(1);
+'@ | Set-Content $jsBom -Encoding utf8
+& node $jsBom 2>&1 | ForEach-Object { Write-Host "        $_" -ForegroundColor Gray }
+Check 'no BOM-blind JSON read' ($LASTEXITCODE -eq 0) 'see above'
+
 Write-Host "`n=== 2. PowerShell parse + BOM ===" -ForegroundColor Cyan
 # This script checks itself too: it is edited as often as the others, and an editor
 # that drops the BOM would otherwise go unnoticed until someone adds CJK text here.
@@ -97,6 +122,11 @@ Check 'engines.dsh covers every released DSH host' ($LASTEXITCODE -eq 0) (($comp
 foreach ($doc in @('README.md', 'README.zh-CN.md')) {
   $text = Get-Content (Join-Path $root $doc) -Raw -Encoding UTF8
   Check "$doc quotes the declared engines.dsh" $text.Contains([string]$pkg.engines.dsh) "expected $($pkg.engines.dsh)"
+  # The pin example is copy-pasteable, so it must name a ref that will exist: the
+  # version this tree publishes. It has drifted twice (v2.0.0 long after 2.0.5,
+  # then v2.0.8 while the tree was 2.0.9), and both times every other signal was
+  # green because nothing compared the two.
+  Check "$doc pins the current version" $text.Contains("dsh-plugin-rea#v$($pkg.version)") "expected dsh-plugin-rea#v$($pkg.version)"
 }
 foreach ($script in @('bundle:setup', 'bundle:status', 'bundle:audit', 'bundle:test', 'bundle:host-compat')) {
   Check "scripts.$script exists" ($pkg.scripts.PSObject.Properties.Name -contains $script) ''