dsh-plugin-rea 2.0.7 → 2.0.9

package/check-updates.ps1

@@ -73,9 +73,13 @@ function Test-NodeEngines([string]$node, [string]$engines) {
 # bundle.json：把全局路径当默认是 1.x 的答案，在 2.x 机器上会让这一节指向错误的
 # 对象（"全局包丢了"），并给出错误的升级动作（npm i -g）。
 $bundleRootEarly = $env:REA_BUNDLE_ROOT
+# Resolve the home unconditionally: the profile section below needs it whether or
+# not REA_BUNDLE_ROOT was set, and computing it only inside the fallback branch
+# left it $null — `Join-Path $null 'profiles'` throws, so the section degraded to
+# "no profile" on exactly the machines that use the override.
+$homeEarly = $env:DSH_HOME
+if (-not $homeEarly) { $homeEarly = Join-Path $HOME '.dsh' }
 if (-not $bundleRootEarly) {
-  $homeEarly = $env:DSH_HOME
-  if (-not $homeEarly) { $homeEarly = Join-Path $HOME '.dsh' }
   $bundleRootEarly = Join-Path $homeEarly 'plugins\rea-bundle'
 }
 $bundleState = $null
@@ -106,8 +110,12 @@ $reaFromBundle = [bool]($bundleReaPackageDir -and $ReaPackageDir -eq $bundleReaP
 if (-not $ProfileDir) {
   if ($env:DSH_PROFILE_DIR) { $ProfileDir = $env:DSH_PROFILE_DIR }
   else {
-    $profiles = @(Get-ChildItem (Join-Path $env:USERPROFILE '.dsh\profiles') -Directory -ErrorAction SilentlyContinue)
-    $ProfileDir = if ($profiles.Count -gt 0) { $profiles[0].FullName } else { Join-Path $env:USERPROFILE '.dsh\profiles\desktop' }
+    # Same home rule the bundle uses everywhere else: DSH_HOME, then ~/.dsh.
+    # Hardcoding $env:USERPROFILE here was a second algorithm in the same script,
+    # so on a custom DSH_HOME the profile section reported "no profile found"
+    # while the rest of the run had already resolved that home correctly.
+    $profiles = @(Get-ChildItem (Join-Path $homeEarly 'profiles') -Directory -ErrorAction SilentlyContinue)
+    $ProfileDir = if ($profiles.Count -gt 0) { $profiles[0].FullName } else { Join-Path $homeEarly 'profiles\desktop' }
   }
 }
 
@@ -340,7 +348,27 @@ if (-not (Test-Path $manifestPath)) {
         Warn ("TOFU（无厂商校验和，取首次实测值）: " + (@($state.unverifiedChecksums) -join ', '))
       }
       $mirrored = Join-Path $bundleRoot 'bin\rea-shim.mjs'
-      if (Test-Path $mirrored) { Ok 'MCP 行指向的 shim 已就位' }
+      if (Test-Path $mirrored) {
+        Ok 'MCP 行指向的 shim 已就位'
+        # The row launches this COPY, so a plugin upgrade that does not re-run
+        # setup leaves the old launcher in place — visible only as "the new
+        # version behaves like the old one". Compare it with the checkout the
+        # mirror record names.
+        $mirrorRecord = Join-Path $bundleRoot 'mirror.json'
+        if (Test-Path $mirrorRecord) {
+          try {
+            $record = Get-Content $mirrorRecord -Raw -Encoding UTF8 | ConvertFrom-Json
+            $pluginShim = if ($record.pluginRoot) { Join-Path $record.pluginRoot 'bin\rea-shim.mjs' } else { $null }
+            if ($pluginShim -and (Test-Path $pluginShim)) {
+              $same = (Get-FileHash $mirrored -Algorithm SHA256).Hash -eq (Get-FileHash $pluginShim -Algorithm SHA256).Hash
+              if ($same) { Ok '镜像 shim 与插件一致（行跑的就是这个版本）' }
+              else { Warn "镜像 shim 落后于插件（$($record.pluginRoot)）—— 行仍在跑旧副本；重跑 node scripts/setup.mjs 让它换成新版本" }
+            } else {
+              Warn "mirror.json 指向的插件目录已不存在（$($record.pluginRoot)）—— 无法比对镜像 shim 是否最新"
+            }
+          } catch { Warn "mirror.json 解析失败: $($_.Exception.Message)" }
+        }
+      }
       else { Bad "缺少 MCP 行指向的 shim: $mirrored —— 重跑 setup --reuse" }
       # 镜像副本的 setup 用它自己所在的位置推 plugin root，所以 manifest 必须
       # 一起镜像。旧版镜像缺这个文件：auto-provision 会以 ENOENT 崩掉且不可见，

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.7",
+  "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`);
@@ -1636,6 +1651,31 @@ function mirrorLauncher(context) {
  */
 function writeMirrorRecord(context, source) {
   const record = { schema: 1, pluginRoot: source, mirroredAt: new Date().toISOString() };
+  // Provenance for the self-healing check: the mirrored shim compares itself
+  // with `<pluginRoot>/bin/rea-shim.mjs` and re-execs that one when the plugin
+  // has moved on. These two fields are what `--shim-status` shows when the
+  // comparison cannot be made (missing checkout, unreadable file).
+  try {
+    record.shimSha256 = createHash("sha256")
+      .update(readFileSync(path.join(context.root, "bin", "rea-shim.mjs")))
+      .digest("hex");
+  } catch {
+    /* the copy is missing or unreadable; the shim reports the comparison itself */
+  }
+  try {
+    record.pluginVersion = readJson(path.join(source, "package.json")).version ?? null;
+  } catch {
+    record.pluginVersion = null;
+  }
+  // The MCP child the harness starts has every DSH_* variable stripped, so the
+  // mirrored shim cannot re-derive a CUSTOM home from its environment — it would
+  // read `~/.dsh` and miss a duplicate `serverName: rea` living in the real one.
+  // Record the home setup ran under; the shim prefers the environment, then this.
+  try {
+    record.dshHome = dshHome();
+  } catch {
+    record.dshHome = null;
+  }
   try {
     mkdirSync(context.root, { recursive: true });
     writeFileSync(path.join(context.root, "mirror.json"), JSON.stringify(record, null, 2) + "\n");

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,
@@ -1564,3 +1564,328 @@ test("--shim-print-env reports the system launch instead of a child environment"
     f.clean();
   }
 });
+
+test("a candidate that wraps this shim is rejected instead of recursing", () => {
+  // The probe asks the candidate for `--version`; a wrapper answers by running
+  // this very shim, which would probe the wrapper again. The probe therefore runs
+  // with REA_BUNDLE_DELEGATED=1, so the nested run takes the bundle path and
+  // returns. Without that, one wrapper on PATH spawns a process chain that keeps
+  // respawning after the parent is killed.
+  const f = launchFixture();
+  mkdirSync(f.bin, { recursive: true });
+  const shim = path.join(REPO_ROOT, "bin", "rea-shim.mjs");
+  const wrapper = path.join(f.bin, process.platform === "win32" ? "rea.cmd" : "rea");
+  if (process.platform === "win32") {
+    writeFileSync(wrapper, `@echo off\r\n"${process.execPath}" "${shim}" %*\r\n`);
+  } else {
+    writeFileSync(wrapper, `#!/bin/sh\nexec "${process.execPath}" "${shim}" "$@"\n`);
+    chmodSync(wrapper, 0o755);
+  }
+  try {
+    const started = Date.now();
+    const run = runShimIsolated(
+      { PATH: f.emptyPath, REA_BUNDLE_SYSTEM_REA: wrapper, REA_BUNDLE_ROOT: f.bundleRoot, REA_BUNDLE_AUTO_PROVISION: "0", REA_BUNDLE_LAUNCH: "" },
+      ["--shim-status"],
+    );
+    const elapsed = Date.now() - started;
+    const report = JSON.parse(run.stdout);
+    assert.equal(report.launch.mode, "bundle");
+    assert.deepEqual(report.launch.rejected.map(r => r.reason), ["exit 78"]);
+    assert.ok(elapsed < 20000, `the probe must not recurse; it took ${elapsed} ms`);
+  } finally {
+    f.clean();
+  }
+});
+
+test("a ComSpec that points at nothing falls back to the real shell", () => {
+  // Trusting ComSpec blindly would judge every .cmd REA "spawn-failed" — i.e.
+  // report the machine as having no REA because its shell pointer is broken.
+  const f = launchFixture();
+  mkdirSync(f.bin, { recursive: true });
+  const rea = writeFakeRea(f.bin, { version: "6.9.0" });
+  try {
+    const run = runShimIsolated(
+      {
+        PATH: f.emptyPath,
+        ComSpec: path.join(f.root, "no-such-cmd.exe"),
+        REA_BUNDLE_SYSTEM_REA: rea,
+        REA_BUNDLE_ROOT: f.bundleRoot,
+        REA_BUNDLE_AUTO_PROVISION: "0",
+        REA_BUNDLE_LAUNCH: "",
+      },
+      ["--shim-status"],
+    );
+    const report = JSON.parse(run.stdout);
+    if (process.platform === "win32") {
+      assert.equal(report.launch.mode, "system", JSON.stringify(report.launch));
+      assert.equal(report.launch.systemRea.version, "6.9.0");
+    } else {
+      // POSIX never consults ComSpec; the assertion above would be incidental.
+      assert.equal(report.launch.mode, "system");
+    }
+  } finally {
+    f.clean();
+  }
+});
+
+/* --------------------------------------------------- the mirrored launcher */
+
+// The row launches `<bundle>/bin/rea-shim.mjs`, a COPY. A market upgrade replaces
+// the package and runs no setup, so without this the copy keeps running the code
+// it was made from — every fix silently stops at the old mirror. These tests pin
+// the repair: the copy re-execs the plugin's launcher when they differ, once.
+
+function mirrorFixture() {
+  const root = mkdtempSync(path.join(tmpdir(), "rea-mirror-"));
+  const bundle = path.join(root, "bundle");
+  const checkout = path.join(root, "checkout");
+  mkdirSync(path.join(bundle, "bin"), { recursive: true });
+  mkdirSync(path.join(checkout, "bin"), { recursive: true });
+  copyFileSync(path.join(REPO_ROOT, "bin", "rea-shim.mjs"), path.join(bundle, "bin", "rea-shim.mjs"));
+  writeFileSync(path.join(bundle, "mirror.json"), JSON.stringify({ schema: 1, pluginRoot: checkout, mirroredAt: "2026-10-18T00:00:00Z" }));
+  return { root, bundle, checkout, clean() { rmSync(root, { recursive: true, force: true }); } };
+}
+
+function checkoutStub(checkout, marker) {
+  const file = path.join(checkout, "bin", "rea-shim.mjs");
+  writeFileSync(
+    file,
+    'import { writeFileSync } from "node:fs";\n' +
+      `writeFileSync(${JSON.stringify(marker)}, "checkout");\n` +
+      "process.exit(7);\n",
+  );
+  return file;
+}
+
+test("a mirrored launcher re-execs the plugin's launcher when they differ", () => {
+  const f = mirrorFixture();
+  const marker = path.join(f.root, "checkout-ran");
+  checkoutStub(f.checkout, marker);
+  try {
+    // 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 {
+    f.clean();
+  }
+});
+
+test("the re-exec happens once, and a pinned guard stops it", () => {
+  const f = mirrorFixture();
+  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", 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.
+    assert.equal(run.status, 78, run.stderr);
+    assert.equal(existsSync(marker), false, "the guard must prevent a second hop");
+  } finally {
+    f.clean();
+  }
+});
+
+test("--shim-status reports a stale mirror instead of re-execing it", () => {
+  const f = mirrorFixture();
+  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"],
+      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/);
+    assert.equal(existsSync(marker), false, "status is a query; it must not start anything");
+  } finally {
+    f.clean();
+  }
+});
+
+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"],
+      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");
+  } finally {
+    f.clean();
+  }
+});
+
+test("a mirrored shim finds the real DSH home when the environment is scrubbed", () => {
+  // The harness strips DSH_* from an MCP child, so with a custom DSH_HOME the
+  // old code read ~/.dsh — the wrong file — and could never report upstream's
+  // duplicate `serverName: rea`. setup records the home; the shim must use it.
+  const f = mirrorFixture();
+  const home = path.join(f.root, "custom-home");
+  mkdirSync(home, { recursive: true });
+  writeFileSync(
+    path.join(home, "cordis.patch.yml"),
+    "- insert:\n    - id: rea-mcp\n      name: '@deepseek-ai/dsh-mcp-client'\n      config:\n        serverName: rea\n",
+  );
+  writeFileSync(
+    path.join(f.bundle, "mirror.json"),
+    JSON.stringify({ schema: 1, pluginRoot: f.checkout, mirroredAt: "2026-10-18T00:00:00Z", dshHome: home }),
+  );
+  try {
+    const run = runShimIsolated(
+      // DSH_HOME="" models the scrubbed environment: the variable exists, empty.
+      { REA_BUNDLE_ROOT: f.bundle, REA_BUNDLE_AUTO_PROVISION: "0", REA_BUNDLE_LAUNCH: "bundle", DSH_HOME: "" },
+      ["--shim-status"],
+    );
+    const report = JSON.parse(run.stdout);
+    assert.equal(report.duplicateRegistration?.id, "rea-mcp", run.stdout);
+    assert.equal(report.duplicateRegistration.patch, path.join(home, "cordis.patch.yml"));
+  } finally {
+    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.
@@ -90,6 +115,19 @@ Check 'main resolves to a shipped file' ($pkg.main -and (Test-Path (Join-Path $r
 Check 'package.json declares engines.dsh' (-not [string]::IsNullOrWhiteSpace($pkg.engines.dsh)) ''
 $compat = & node scripts\host-compat.mjs 2>&1
 Check 'engines.dsh covers every released DSH host' ($LASTEXITCODE -eq 0) (($compat | Select-Object -Last 2) -join ' ')
+# Both READMEs quote the range verbatim, and a stale quote is invisible: JSON,
+# host-compat and the audit all agree while the sentence a human reads names a
+# different ceiling. That is exactly how `<0.3.0` survived in the docs after the
+# declaration moved to `<0.3.0-0`, so the comparison lives here now.
+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) ''
 }