dsh-plugin-rea 2.0.7 → 2.0.9

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,11 +10,12 @@
  * 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.
  */
 import { spawn, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
@@ -25,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;
@@ -32,6 +46,36 @@ function dshHome() {
   return path.join(homedir(), ".dsh");
 }
 
+/**
+ * The DSH home recorded by setup, or null.
+ *
+ * Only the mirrored copy needs this: the harness strips `DSH_*` from an MCP
+ * child, so with a custom home the environment cannot answer. Read once per
+ * process — there is one bundle root per process and this is a startup query.
+ */
+let recordedDshHomeCache = null;
+function recordedDshHome(root) {
+  if (recordedDshHomeCache !== null) return recordedDshHomeCache;
+  let value = null;
+  try {
+    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);
+    }
+  } catch {
+    value = null;
+  }
+  recordedDshHomeCache = value;
+  return value;
+}
+
+/** The home to look in when the environment has been scrubbed. */
+function dshHomeFor(root) {
+  const fromEnv = process.env.DSH_HOME;
+  if (fromEnv && fromEnv.trim() !== "") return path.resolve(fromEnv);
+  return recordedDshHome(root) ?? path.join(homedir(), ".dsh");
+}
+
 /**
  * Where setup writes the machine-local truth.
  *
@@ -43,11 +87,11 @@ function dshHome() {
  *    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.
@@ -80,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 {
@@ -104,13 +148,16 @@ function provisioningScript(root) {
  *
  * The parse is deliberately small: the two files it cares about are block
  * mappings with one id/serverName per row, and anything it cannot attribute is
- * ignored 鈥?a missed hint is acceptable, a false alarm is not. The mirrored shim
- * cannot see a custom DSH_HOME (the harness strips DSH_* from an MCP child), so
- * this falls back to `~/.dsh` like the rest of the bundle; the row has the same
- * limitation.
+ * ignored — a missed hint is acceptable, a false alarm is not.
+ *
+ * Finding the file is the part that needed care: the harness strips every DSH_*
+ * variable from an MCP child, so a mirrored copy with a custom DSH_HOME used to
+ * read `~/.dsh` — the wrong file, and therefore a conflict it could never report.
+ * `setup.mjs` writes the home it ran under into `mirror.json`, and that record is
+ * what this uses when the environment has nothing to say.
  */
-function foreignReaRegistration() {
-  const patch = path.join(dshHome(), "cordis.patch.yml");
+function foreignReaRegistration(root) {
+  const patch = path.join(dshHomeFor(root), "cordis.patch.yml");
   let text;
   try {
     text = readFileSync(patch, "utf8");
@@ -133,7 +180,7 @@ function foreignReaRegistration() {
 /**
  * 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".
  */
@@ -171,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.
@@ -208,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.
@@ -265,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);
@@ -299,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) };
   }
@@ -316,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");
@@ -373,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
@@ -432,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).
  */
@@ -454,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;
@@ -516,7 +565,11 @@ function cmdQuote(value) {
  */
 function comspec() {
   const fromEnv = process.env.ComSpec ?? process.env.COMSPEC;
-  if (typeof fromEnv === "string" && fromEnv.trim() !== "") return fromEnv;
+  // A ComSpec that names nothing is a real (if unusual) state, and trusting it
+  // would judge every `.cmd` REA "spawn-failed" — i.e. report the machine as
+  // having no REA because its shell pointer is broken. Fall back to the path
+  // Windows itself would use.
+  if (typeof fromEnv === "string" && fromEnv.trim() !== "" && isFileSync(fromEnv)) return fromEnv;
   const systemRoot = process.env.SystemRoot ?? process.env.SYSTEMROOT ?? "C:\\Windows";
   return path.join(systemRoot, "System32", "cmd.exe");
 }
@@ -527,50 +580,77 @@ function comspec() {
  * A file existing on PATH is not the same as a working install: npx leftovers,
  * half-removed globals and a shim whose Node is gone all sit on PATH and all
  * fail at once. One bounded `--version` separates them, and a slow or hanging
- * answer counts as "not usable" 鈥?the fallback (the bundle) still works, while
+ * answer counts as "not usable" — the fallback (the bundle) still works, while
  * delegating to a broken binary would take the tools down with it.
+ *
+ * Two things here are not incidental:
+ *
+ *  * The probe runs with `REA_BUNDLE_DELEGATED=1`. A candidate that is itself a
+ *    wrapper around this shim would otherwise be probed by a nested shim that
+ *    probes the wrapper — measured: a process chain that keeps respawning
+ *    itself. The flag makes the nested run take the bundle path and return.
+ *  * It is asynchronous, not `spawnSync` with a timeout. `spawnSync` reaps the
+ *    child it started, and its timeout kills only that child: for a `.cmd` shim
+ *    that means cmd.exe dies while the REA inside it keeps running and holds
+ *    the pipes. Killing the TREE is only possible while the parent is alive,
+ *    which means owning the wait ourselves.
  */
 function probeRea(file, { platform = process.platform, timeout = PROBE_TIMEOUT_MS } = {}) {
-  // `existsSync` says nothing about the shape: a DIRECTORY named `rea.cmd` exists,
-  // fails to spawn, and would be reported as a broken install instead of as a
-  // name collision. Only a regular file is a candidate.
-  try {
-    if (!statSync(file).isFile()) return { ok: false, reason: "not a file" };
-  } catch {
-    return { ok: false, reason: "missing" };
-  }
-  const command = [file, "--version"];
-  // `cmd /d /s /c "<line>"`: Windows only. Two details are load-bearing.
-  // `/s` strips the first and last quote, so the whole line is quoted; and the
-  // arguments are passed VERBATIM, because Node otherwise backslash-escapes the
-  // quotes it sees and cmd.exe does not understand `\"` — every candidate then
-  // answers "exit 1", which reads as "no REA on this machine".
-  const result = platform === "win32" && /\.(cmd|bat)$/i.test(file)
-    ? spawnSync(comspec(), ["/d", "/s", "/c", `"${[cmdQuote(file), "--version"].join(" ")}"`], {
-        encoding: "utf8",
-        timeout,
-        windowsHide: true,
-        windowsVerbatimArguments: true,
-      })
-    : spawnSync(command[0], command.slice(1), {
-        encoding: "utf8",
-        timeout,
-        windowsHide: true,
-      });
-  if (result.error) {
-    // A timed-out probe leaves its grandchild running: cmd.exe is killed, the
-    // REA inside it is not, and it keeps the inherited pipes open. Clean the tree
-    // before answering, or a hung candidate leaves a process behind per start.
-    if (result.error.code === "ETIMEDOUT") killTree(result.pid, platform);
-    return { ok: false, reason: result.error.code === "ETIMEDOUT" ? "timeout" : "spawn-failed" };
-  }
-  if (result.status !== 0) return { ok: false, reason: `exit ${String(result.status)}` };
-  const text = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim();
-  const version = /\b(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)\b/.exec(text)?.[1] ?? null;
-  // A REA install prints its version. Anything else (a shim that swallowed the
-  // flag, an unrelated program that shares the name) is not a usable CLI.
-  if (version === null) return { ok: false, reason: "no version in --version output" };
-  return { ok: true, version };
+  return new Promise((resolve) => {
+    // `existsSync` says nothing about the shape: a DIRECTORY named `rea.cmd`
+    // exists, fails to spawn, and would be reported as a broken install instead
+    // of as a name collision. Only a regular file is a candidate.
+    if (!isFileSync(file)) {
+      resolve({ ok: false, reason: "not a file" });
+      return;
+    }
+    const useShell = platform === "win32" && /\.(cmd|bat)$/i.test(file);
+    // `REA_BUNDLE_AUTO_PROVISION=0` is part of the same guard: if the candidate
+    // turns out to be a wrapper around THIS shim, the nested run must not start
+    // an 800 MB provisioning job just because a probe asked it for a version.
+    const env = { ...process.env, REA_BUNDLE_DELEGATED: "1", REA_BUNDLE_AUTO_PROVISION: "0" };
+    // `cmd /d /s /c "<line>"`: Windows only. Two details are load-bearing.
+    // `/s` strips the first and last quote, so the whole line is quoted; and the
+    // arguments are passed VERBATIM, because Node otherwise backslash-escapes the
+    // quotes it sees and cmd.exe does not understand `\"` — every candidate then
+    // answers "exit 1", which reads as "no REA on this machine".
+    const child = useShell
+      ? spawn(comspec(), ["/d", "/s", "/c", `"${[cmdQuote(file), "--version"].join(" ")}"`], {
+          env,
+          stdio: ["ignore", "pipe", "pipe"],
+          windowsHide: true,
+          windowsVerbatimArguments: true,
+        })
+      : spawn(file, ["--version"], { env, stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+    let output = "";
+    let settled = false;
+    let timer = null;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      if (timer !== null) clearTimeout(timer);
+      resolve(result);
+    };
+    timer = setTimeout(() => {
+      killTree(child.pid, platform);
+      finish({ ok: false, reason: "timeout" });
+    }, timeout);
+    child.stdout.on("data", (chunk) => { output += String(chunk); });
+    child.stderr.on("data", (chunk) => { output += String(chunk); });
+    child.on("error", () => finish({ ok: false, reason: "spawn-failed" }));
+    child.on("close", (code) => {
+      if (code !== 0) {
+        finish({ ok: false, reason: `exit ${String(code)}` });
+        return;
+      }
+      // A REA install prints its version. Anything else (a shim that swallowed
+      // the flag, an unrelated program that shares the name) is not a usable CLI.
+      const version = /\b(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)\b/.exec(output.trim())?.[1] ?? null;
+      finish(version === null
+        ? { ok: false, reason: "no version in --version output" }
+        : { ok: true, version });
+    });
+  });
 }
 
 /**
@@ -580,7 +660,7 @@ function probeRea(file, { platform = process.platform, timeout = PROBE_TIMEOUT_M
  * provisioner installed is the `bundle` mode, and delegating to it would be a
  * loop through a path the bundle already covers.
  */
-function detectSystemRea({ env = process.env, platform = process.platform, root, pluginRoot = PLUGIN_ROOT } = {}) {
+async function detectSystemRea({ env = process.env, platform = process.platform, root, pluginRoot = PLUGIN_ROOT } = {}) {
   const rejected = [];
   let profiled = 0;
   const explicit = (env.REA_BUNDLE_SYSTEM_REA ?? "").trim();
@@ -609,7 +689,7 @@ function detectSystemRea({ env = process.env, platform = process.platform, root,
       continue;
     }
     profiled += 1;
-    const probe = probeRea(candidate, { platform });
+    const probe = await probeRea(candidate, { platform });
     if (probe.ok) return { found: true, file: candidate, version: probe.version };
     if (rejected.length < 8) rejected.push({ file: candidate, reason: probe.reason });
   }
@@ -624,7 +704,9 @@ function detectSystemRea({ env = process.env, platform = process.platform, root,
   if (explicitPath !== null && explicitRejection !== null) {
     reason = `REA_BUNDLE_SYSTEM_REA was rejected (${explicitRejection.reason}): ${explicitPath}`;
   } else if (explicitPath !== null && !isFileSync(explicitPath)) {
-    reason = `REA_BUNDLE_SYSTEM_REA does not exist: ${explicitPath}`;
+    reason = existsSync(explicitPath)
+      ? `REA_BUNDLE_SYSTEM_REA is not a file: ${explicitPath}`
+      : `REA_BUNDLE_SYSTEM_REA does not exist: ${explicitPath}`;
   } else {
     reason = profiled === 0 ? "no rea on PATH" : "no usable rea on PATH";
   }
@@ -657,10 +739,10 @@ 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.
  */
-function resolveLaunch({ root, bundleVersion = null, bundleProvisioned = false, env = process.env, platform = process.platform } = {}) {
+async function resolveLaunch({ root, bundleVersion = null, bundleProvisioned = false, env = process.env, platform = process.platform } = {}) {
   const preference = launchPreference(env);
   if (preference.value === "bundle") {
     return { preference: preference.value, invalid: preference.invalid, mode: "bundle", reason: "pinned by REA_BUNDLE_LAUNCH=bundle" };
@@ -678,7 +760,7 @@ function resolveLaunch({ root, bundleVersion = null, bundleProvisioned = false,
       reason: "REA_BUNDLE_DELEGATED=1: already running under a delegated system REA, refusing to delegate again",
     };
   }
-  const system = detectSystemRea({ env, platform, root });
+  const system = await detectSystemRea({ env, platform, root });
   if (system.found) {
     const order = bundleVersion === null ? null : compareDotted(system.version, bundleVersion);
     const pinned = preference.value === "system";
@@ -747,25 +829,14 @@ function launchSystemRea(system, argv) {
         windowsVerbatimArguments: true,
       })
     : spawn(system.file, args, { env, stdio: "inherit", windowsHide: true });
-  // Signal handling, per platform, because the two are not the same problem.
-  //
-  // POSIX: stdio is inherited and the child is in this process's group, so a
-  // terminal's Ctrl+C already reaches it. Forwarding again would deliver the
-  // signal twice.
-  //
-  // Windows: there is no process group to deliver to, and `child.kill("SIGINT")`
-  // is TerminateProcess on the cmd.exe WRAPPER — the REA inside it survives and
-  // keeps the inherited pipes open, which looks exactly like "the tools still
-  // work after I stopped the harness". `taskkill /T` is what actually ends the
-  // tree, so that is what a signal asks for here.
-  if (process.platform === "win32") {
-    for (const signal of ["SIGINT", "SIGTERM"]) {
-      process.on(signal, () => {
-        killTree(child.pid, "win32");
-        process.exit(signal === "SIGINT" ? 130 : 143);
-      });
-    }
-  }
+  // No signal forwarding on Windows, deliberately. `child.kill()` there is
+  // TerminateProcess on the cmd.exe WRAPPER — the REA inside it survives, still
+  // holding the inherited pipes — and a console Ctrl+C is delivered to the whole
+  // process group anyway, so the child already has it. A hard kill of this shim
+  // (what a supervisor or Task Manager does) runs no JavaScript at all, so the
+  // wrapper must not pretend otherwise: on Windows the delegated REA outlives a
+  // forcibly killed shim. On POSIX the child is in this process's group and gets
+  // the terminal's signal directly; `process.exit` below then ends the shim.
   child.on("error", (error) => {
     process.stderr.write(`rea-shim: could not start ${system.file}\n  ${String(error && error.message)}\n`);
     process.exit(EX_CONFIG);
@@ -780,11 +851,145 @@ function launchSystemRea(system, argv) {
   return null;
 }
 
+/**
+ * The mirror problem.
+ *
+ * The published row launches `<bundle>/bin/rea-shim.mjs` — a COPY made by
+ * `setup.mjs`. Upgrading the plugin from the market replaces the package but runs
+ * no setup, so the copy keeps executing the code it was made from: every fix in
+ * a new plugin version reaches a user only if they happen to re-run setup. That
+ * is invisible (the old copy keeps working) and it is exactly the wrong
+ * direction for a safety fix.
+ *
+ * The repair has to live in the copy, because the copy is what runs. So the
+ * copy compares itself with the plugin's own `bin/rea-shim.mjs`, recorded in
+ * `mirror.json` by setup, and re-execs that file when the two differ. One hop,
+ * guarded by an environment flag, and only from mirror to checkout — the
+ * checkout copy has no `mirror.json` and would find itself anyway.
+ *
+ * A plugin version older than 2.0.8 cannot do this for its own upgrades: there
+ * is nothing in it to run. `--shim-status` reports `mirror.stale` so the
+ * condition is at least visible, and `check-updates.ps1` says to re-run setup.
+ */
+function sha256(file) {
+  return createHash("sha256").update(readFileSync(file)).digest("hex");
+}
+
+/** Where the installed plugin lives according to setup's record, or null. */
+function pluginCheckout(root) {
+  try {
+    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");
+    return isFileSync(shim) ? shim : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Whether this copy is behind the plugin it was mirrored from.
+ *
+ * `self` is this file, `source` the checkout's. A checkout copy (it ships
+ * `cordis.patch.yml`) is never stale against itself; a mirror with no record, or
+ * whose recorded checkout is gone, is not re-pointed anywhere.
+ */
+function describeMirror(root, { self = fileURLToPath(import.meta.url) } = {}) {
+  let record = null;
+  try {
+    record = readJson(path.join(root, "mirror.json"));
+  } catch {
+    return null;
+  }
+  const source = pluginCheckout(root);
+  let stale = false;
+  let reason = "no usable plugin checkout in mirror.json";
+  if (source !== null) {
+    if (path.resolve(source) === path.resolve(self)) {
+      reason = "this copy is the plugin checkout";
+    } else {
+      try {
+        stale = sha256(source) !== sha256(self);
+        reason = stale ? "the plugin ships a different launcher than this mirrored copy" : "this copy matches the plugin";
+      } catch {
+        reason = "could not compare the two launchers";
+      }
+    }
+  }
+  return {
+    pluginRoot: typeof record?.pluginRoot === "string" ? record.pluginRoot : null,
+    mirroredAt: typeof record?.mirroredAt === "string" ? record.mirroredAt : null,
+    stale,
+    reason,
+  };
+}
+
+/**
+ * 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,
+  });
+  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);
+    });
+  });
+}
+
 /**
  * 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
@@ -808,7 +1013,7 @@ function usage() {
   ].join("\n");
 }
 
-function main() {
+async function main() {
   const argv = process.argv.slice(2);
 
   if (argv.includes("--shim-help") || argv.length === 0) {
@@ -817,12 +1022,36 @@ function main() {
   }
 
   const root = bundleRoot();
+  // Self-healing before anything else: a mirrored copy that predates the plugin
+  // it was made from would otherwise keep running that older code forever, and a
+  // 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);
+  // 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) {
+      // 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
   // machine with its own working REA must not be sent into an ~800 MB
   // provisioning run just because this bundle has no state yet.
   const bundleVersion = loaded.ok ? (loaded.config.versions?.reaAgents ?? null) : null;
-  const launch = resolveLaunch({ root, bundleVersion, bundleProvisioned: loaded.ok });
+  const launch = await resolveLaunch({ root, bundleVersion, bundleProvisioned: loaded.ok });
   if (launch.invalid !== null) {
     process.stderr.write(
       `rea-shim: REA_BUNDLE_LAUNCH="${launch.invalid}" is not one of ${LAUNCH_MODES.join("/")}; using auto.\n`,
@@ -831,7 +1060,7 @@ function main() {
   // Upstream can add a second row for the same serverName; the shim cannot stop
   // DSH from loading both rows, but saying so is better than doubled tools with
   // no stated cause. The status report carries the same fact for diagnostics.
-  const duplicate = foreignReaRegistration();
+  const duplicate = foreignReaRegistration(root);
   if (duplicate && !argv.includes("--shim-status")) {
     process.stderr.write(
       `\n  dsh-plugin-rea (bundle): duplicate REA registration.\n` +
@@ -860,6 +1089,10 @@ function main() {
       },
     };
     if (launch.system?.rejected?.length) report.launch.rejected = launch.system.rejected;
+    // A mirrored copy that lags the plugin keeps working, which is exactly why
+    // nobody notices it: the row runs old code until the mirror is refreshed.
+    // Reported here so `--shim-status` answers "am I running what I installed?".
+    if (mirror !== null) report.mirror = mirror;
     if (duplicate) report.duplicateRegistration = duplicate;
     if (loaded.ok) {
       report.paths = loaded.config.paths ?? {};
@@ -909,12 +1142,12 @@ 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
@@ -972,5 +1205,8 @@ function main() {
   return null;
 }
 
-const status = main();
+// The launch decision awaits a probe, so `main` is async; the status it returns
+// is this process's exit code, and a launch path resolves to null while the
+// child (already wired to `process.exit`) keeps the loop alive.
+const status = await main();
 if (typeof status === "number") process.exit(status);