dsh-plugin-rea 2.0.5 → 2.0.7

package/scripts/host-compat.mjs

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+/**
+ * host-compat — does the range this package declares cover the DSH releases it
+ * claims to support?
+ *
+ * `package.json` carries `engines.dsh`, and that single string is what the
+ * plugin market reads to say "compatible" instead of "unknown" (the market's
+ * `deriveHostCompatibility` treats `engines.dsh` as a host declaration and
+ * checks it against the running host version). A declaration is therefore load
+ * bearing twice over: it decides whether the market HIDES this plugin from users
+ * on a matching host, and it decides whether users on a host we never tested are
+ * told it works.
+ *
+ * The two ways it goes wrong are silent. A typo makes the range unparseable, and
+ * the market then reports `unknown` — a plugin that looks undeclared rather than
+ * mis-declared. A floor that drifted (say `>=0.2.0`) silently drops hosts the
+ * README still promises. Neither shows up as a test failure unless something
+ * compares the STRING to the release list, which is what this file does.
+ *
+ * `HOST_RELEASES` is the dsh release line this package is built against, newest
+ * first, as published on github.com/deepseek-ai/deepseek-harness. It is a
+ * literal list rather than a GitHub query on purpose: a check that needs the
+ * network fails on a plane and passes on a total outage, which is the wrong
+ * shape for a gate. When a release is added upstream, add it here too — that
+ * edit is the reminder to re-check the row against the new host.
+ *
+ * SEMANTICS: this file evaluates the declaration the way `includePrerelease:
+ * true` does, and that choice is not stylistic. Both consumers of `engines.dsh`
+ * in this ecosystem pass that option — dshmarket's discovery
+ * (`satisfiesRange(host, declared, { includePrerelease: true })` in
+ * `deriveHostCompatibility`) and the host's own peer gate — so a plain semver
+ * reading, where `0.2.0-rc.2` does NOT satisfy `>=0.1.7-rc.2 <0.3.0-0` (a
+ * prerelease must be named by a comparator on its own tuple), would disagree
+ * with the verdict users actually see. The tests pin the option's effect.
+ *
+ * Usage: `node scripts/host-compat.mjs` (exit 0 = every listed release is
+ * covered by the declared range; exit 1 = at least one is not).
+ */
+import { readFileSync } from 'node:fs'
+import path from 'node:path'
+import process from 'node:process'
+import { fileURLToPath } from 'node:url'
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+const REPO_ROOT = path.join(HERE, '..')
+
+/**
+ * Every dsh release this bundle is checked against, newest first.
+ *
+ * Taken from the release list of github.com/deepseek-ai/deepseek-harness. The
+ * floor is the oldest release the plugin has been adapted to; everything above
+ * it up to the declared ceiling must keep working, so a release that is missing
+ * here is a release nobody checked.
+ */
+export const HOST_RELEASES = [
+  '0.2.1-rc.2',
+  '0.2.1-rc.1',
+  '0.2.1-alpha.5',
+  '0.2.1-alpha.4',
+  '0.2.1-alpha.3',
+  '0.2.1-alpha.2',
+  '0.2.1-alpha.1',
+  '0.2.0-rc.2',
+  '0.2.0-rc.1',
+  '0.1.7-rc.2',
+]
+
+/** Hosts that must fall OUTSIDE the declaration, for the other direction. */
+export const OUTSIDE_HOSTS = [
+  '0.3.0',
+  // Prereleases of the NEXT line are the case a plain `<0.3.0` ceiling lets
+  // through: with `includePrerelease` they sort below `0.3.0` itself. The
+  // declared ceiling is `<0.3.0-0`, semver's idiom for "nothing from 0.3.0",
+  // and these entries are what proves it does what it says.
+  '0.3.0-rc.1',
+  '0.3.0-alpha.1',
+  '0.1.7-rc.1',
+  '0.1.7-alpha.2',
+]
+
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/
+
+/**
+ * Split a version into comparable parts.
+ *
+ * Build metadata (`+sha`) is dropped, as semver says it must be for precedence
+ * and as node-semver does for comparison: a host that reports
+ * `0.2.0-rc.2+build.7` is running 0.2.0-rc.2. Everything else is deliberately
+ * strict — a leading `v` or a zero-padded identifier is rejected rather than
+ * guessed at, because this gate exists to catch a declaration nobody checked and
+ * a guess would put the guess in charge.
+ * @param {string} version - a plain semver string, no range operators.
+ * @returns {{ parts: number[], pre: (string|number)[] } | null} null when unparseable.
+ */
+export function parseVersion(version) {
+  const cleaned = String(version ?? '').trim().replace(/\+.*$/, '')
+  const match = SEMVER.exec(cleaned)
+  if (match === null) return null
+  const raw = match[4] === undefined ? [] : match[4].split('.')
+  // semver forbids a zero-padded numeric prerelease identifier (`0.2.1-01`);
+  // accepting one would make this gate read a typo as a version.
+  if (raw.some(part => /^\d+$/.test(part) && part.length > 1 && part.startsWith('0'))) return null
+  const pre = raw.map(part => (/^\d+$/.test(part) ? Number(part) : part))
+  return { parts: [Number(match[1]), Number(match[2]), Number(match[3])], pre }
+}
+
+/**
+ * Compare two versions the way semver does, prerelease included.
+ *
+ * A prerelease sorts BELOW its release (`0.2.0-rc.2 < 0.2.0`), and among
+ * prereleases an identifier that is numeric sorts below one that is not, which
+ * is why `0.2.1-alpha.5 < 0.2.1-rc.1` — the whole reason this file cannot lean
+ * on a numeric comparison.
+ * @returns -1, 0 or 1; NaN-free because unparseable input throws.
+ */
+export function compareVersions(a, b) {
+  const left = parseVersion(a)
+  const right = parseVersion(b)
+  if (left === null) throw new Error(`not a version: ${a}`)
+  if (right === null) throw new Error(`not a version: ${b}`)
+  for (let index = 0; index < 3; index += 1) {
+    if (left.parts[index] !== right.parts[index]) return left.parts[index] < right.parts[index] ? -1 : 1
+  }
+  if (left.pre.length === 0 && right.pre.length === 0) return 0
+  if (left.pre.length === 0) return 1
+  if (right.pre.length === 0) return -1
+  for (let index = 0; index < Math.max(left.pre.length, right.pre.length); index += 1) {
+    const l = left.pre[index]
+    const r = right.pre[index]
+    if (l === undefined) return -1
+    if (r === undefined) return 1
+    if (l === r) continue
+    const lNum = typeof l === 'number'
+    const rNum = typeof r === 'number'
+    if (lNum && rNum) return l < r ? -1 : 1
+    // Numeric identifiers always have lower precedence than alphanumeric ones.
+    if (lNum !== rNum) return lNum ? -1 : 1
+    return String(l) < String(r) ? -1 : 1
+  }
+  return 0
+}
+
+/**
+ * Evaluate one `>=floor <ceiling` declaration (the only shape this package
+ * ships, and the shape the market's `engines.dsh` is compared with).
+ *
+ * Deliberately narrow: a wider parser here could disagree with the market's
+ * semver implementation on a range the manifest would then be trusted for. If a
+ * future declaration needs `||` or `^`, this function has to grow with it.
+ * @param {string} version - host version to test.
+ * @param {string} range - the declared range.
+ * @returns {boolean} whether the host is inside the declaration.
+ */
+export function satisfiesDeclaredRange(version, range) {
+  const match = /^>=\s*(\S+)\s+<\s*(\S+)$/.exec(range.trim())
+  if (match === null) throw new Error(`unsupported host range: ${range}`)
+  return compareVersions(version, match[1]) >= 0 && compareVersions(version, match[2]) < 0
+}
+
+/**
+ * The host range this repository declares, `engines.dsh`.
+ * @param {string} [root] - repository root, for tests.
+ * @returns {string | null} the declared range, or null when absent.
+ */
+export function declaredHostRange(root = REPO_ROOT) {
+  try {
+    const pkg = JSON.parse(readFileSync(path.join(root, 'package.json'), 'utf8'))
+    const value = pkg?.engines?.dsh
+    return typeof value === 'string' ? value : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Every release covered by the declaration, and every version that must not be.
+ * @param {string} range - declared host range.
+ * @returns {{ covered: string[], uncovered: string[], leaked: string[] }} findings.
+ */
+export function checkHostCoverage(range) {
+  const covered = []
+  const uncovered = []
+  for (const version of HOST_RELEASES) {
+    if (satisfiesDeclaredRange(version, range)) covered.push(version)
+    else uncovered.push(version)
+  }
+  const leaked = OUTSIDE_HOSTS.filter(version => satisfiesDeclaredRange(version, range))
+  return { covered, uncovered, leaked }
+}
+
+function main() {
+  const range = declaredHostRange()
+  if (range === null) {
+    console.error('FAIL: package.json declares no engines.dsh — the market would report this plugin as "unknown"')
+    process.exit(1)
+  }
+  let result
+  try {
+    result = checkHostCoverage(range)
+  } catch (error) {
+    console.error(`FAIL: ${error.message}`)
+    process.exit(1)
+  }
+  console.log(`engines.dsh = ${range}`)
+  for (const version of HOST_RELEASES) {
+    const inside = satisfiesDeclaredRange(version, range)
+    console.log(`  ${inside ? 'ok  ' : 'MISS'} ${version}`)
+  }
+  for (const version of OUTSIDE_HOSTS) {
+    const inside = satisfiesDeclaredRange(version, range)
+    console.log(`  ${inside ? 'LEAK' : 'ok  '} ${version} (must stay outside)`)
+  }
+  if (result.uncovered.length > 0) {
+    console.error(`FAIL: the declaration does not cover ${result.uncovered.join(', ')}`)
+    process.exit(1)
+  }
+  if (result.leaked.length > 0) {
+    console.error(`FAIL: the declaration also admits ${result.leaked.join(', ')}, which is not a tested host`)
+    process.exit(1)
+  }
+  console.log(`host range ok: ${HOST_RELEASES.length} releases covered, ${OUTSIDE_HOSTS.length} correctly outside`)
+}
+
+if (process.argv[1] !== undefined && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) main()

package/scripts/rea-bundle-bootstrap.ps1

@@ -30,6 +30,11 @@ function Write-Step([string]$Message) { Write-Host "[bootstrap] $Message" }
 
 # --- where things go -------------------------------------------------------
 
+# Same precedence as setup.mjs, the shim and check-updates.ps1: explicit override,
+# then DSH_HOME, then ~/.dsh. An override this script alone ignored would put
+# ~800 MB into <DSH_HOME>/plugins/rea-bundle while every reader looked in
+# REA_BUNDLE_ROOT, saw an empty bundle, and started a second run.
+if (-not $Root -or $Root.Trim() -eq '') { $Root = $env:REA_BUNDLE_ROOT }
 if (-not $Root -or $Root.Trim() -eq '') {
   $home2 = $env:DSH_HOME
   if (-not $home2 -or $home2.Trim() -eq '') { $home2 = Join-Path $HOME '.dsh' }

package/scripts/setup.mjs

@@ -1553,7 +1553,11 @@ if (!options.dryRun) {
     const shim = spawnSync(process.execPath, [mirroredShim, "--version"], {
       encoding: "utf8",
       timeout: 120000,
-      env: { ...process.env, REA_BUNDLE_ROOT: options.root },
+      // Pin the bundle path: this step exists to confirm the shim relays the REA
+      // THIS run provisioned. Under the default `auto` mode a machine that also
+      // has a newer global REA answers with its own version, and the step would
+      // report success for something this run never verified.
+      env: { ...process.env, REA_BUNDLE_ROOT: options.root, REA_BUNDLE_LAUNCH: "bundle" },
     });
     const output = `${shim.stdout ?? ""}${shim.stderr ?? ""}`.trim();
     const ok = shim.status === 0 && /\d+\.\d+\.\d+/.test(output);

package/scripts/setup.test.mjs

@@ -19,6 +19,7 @@ import { tmpdir } from "node:os";
 import path from "node:path";
 import test from "node:test";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { HOST_RELEASES, OUTSIDE_HOSTS, checkHostCoverage, declaredHostRange, compareVersions, satisfiesDeclaredRange } from "./host-compat.mjs";
 
 /* ------------------------------------------------- probe token substitution */
 
@@ -212,7 +213,10 @@ const SHIM_SOURCE = path.join(path.dirname(fileURLToPath(import.meta.url)), ".."
 function shimBundleRoot(shimFile, env) {
   const run = spawnSync(process.execPath, [shimFile, "--shim-status"], {
     encoding: "utf8",
-    env: { ...process.env, REA_BUNDLE_AUTO_PROVISION: "0", ...env },
+    // These tests assert bundle-root resolution, not the launch decision. Pinning
+    // the mode keeps them independent of whether THIS machine has a REA on PATH
+    // (and keeps them from paying for a probe on every spawn).
+    env: { ...process.env, REA_BUNDLE_AUTO_PROVISION: "0", REA_BUNDLE_LAUNCH: "bundle", ...env },
   });
   // --shim-status prints its report even when no bundle exists yet (exit 78).
   return JSON.parse(run.stdout).bundleRoot;
@@ -820,6 +824,10 @@ function runShim(bundle, args, extraEnv = {}) {
     ...process.env,
     DSH_HOME: path.join(path.dirname(bundle), "dsh-home"),
     REA_BUNDLE_ROOT: bundle,
+    // The bundle path is what these tests assert. Without this pin the shim
+    // would take its `auto` branch and, on a machine that happens to have a REA
+    // on PATH, delegate to it instead of exercising the code under test.
+    REA_BUNDLE_LAUNCH: "bundle",
     ...extraEnv,
   };
   delete env.REA_BUNDLE_AUTO_PROVISION;
@@ -943,7 +951,7 @@ test("a second REA registration is reported instead of silently duplicated", ()
 
     const status = spawnSync(process.execPath, [path.join(bundle, "bin", "rea-shim.mjs"), "--shim-status"], {
       encoding: "utf8",
-      env: { ...process.env, DSH_HOME: home, REA_BUNDLE_ROOT: bundle },
+      env: { ...process.env, DSH_HOME: home, REA_BUNDLE_ROOT: bundle, REA_BUNDLE_LAUNCH: "bundle" },
     });
     assert.equal(JSON.parse(status.stdout).duplicateRegistration.id, "rea-mcp");
   } finally {
@@ -1122,7 +1130,7 @@ test("the fallback vendored-REA path matches where setup installs it", () => {
     const run = spawnSync(process.execPath, [path.join(REPO_ROOT, "bin", "rea-shim.mjs"), "--shim-status"], {
       encoding: "utf8",
       timeout: 60000,
-      env: { ...process.env, REA_BUNDLE_ROOT: bundle, REA_BUNDLE_AUTO_PROVISION: "0" },
+      env: { ...process.env, REA_BUNDLE_ROOT: bundle, REA_BUNDLE_AUTO_PROVISION: "0", REA_BUNDLE_LAUNCH: "bundle" },
     });
     const report = JSON.parse(run.stdout);
     assert.equal(report.rea.ok, true, JSON.stringify(report.rea));
@@ -1199,3 +1207,360 @@ test("the entry loads as a cordis plugin and does nothing", async () => {
   // which the harness refuses. Returning undefined is the whole contract.
   assert.equal(mod.apply(), undefined);
 });
+
+/* --------------------------------------------------------- declared DSH hosts */
+
+// The market reads `engines.dsh` to answer "is this plugin compatible with the
+// host I am running" — and hides the plugin from hosts that mismatch. Two silent
+// failures follow from a declaration nobody checks: a typo leaves the range
+// unparseable and the market falls back to "undeclared", while a drifted floor
+// drops hosts the README still promises. Both look exactly like a plugin that
+// simply has nothing to say, so the string is pinned against the release list.
+test("the manifest declares a DSH host range the market can read", () => {
+  const range = declaredHostRange(REPO_ROOT);
+  assert.equal(typeof range, "string", "engines.dsh must be declared; without it the market reports the plugin as unknown");
+  // The string is pinned, not just parsed: the ceiling decides which hosts are
+  // admitted, and `<0.3.0` vs `<0.3.0-0` is exactly the difference between
+  // "no 0.3.0" and "0.3.0-alpha.1 is fine" once prereleases are included.
+  assert.equal(range, ">=0.1.7-rc.2 <0.3.0-0");
+  assert.throws(() => satisfiesDeclaredRange("0.2.0-rc.2", "not a range"), "the gate must reject an unparseable range");
+  assert.doesNotThrow(() => satisfiesDeclaredRange("0.2.0-rc.2", range));
+});
+
+test("the release list this gate checks is the published one", () => {
+  // Pinned literally: deleting an entry from the list would otherwise shrink the
+  // coverage claim silently, and every test below would still pass.
+  assert.deepEqual(HOST_RELEASES, [
+    "0.2.1-rc.2",
+    "0.2.1-rc.1",
+    "0.2.1-alpha.5",
+    "0.2.1-alpha.4",
+    "0.2.1-alpha.3",
+    "0.2.1-alpha.2",
+    "0.2.1-alpha.1",
+    "0.2.0-rc.2",
+    "0.2.0-rc.1",
+    "0.1.7-rc.2",
+  ]);
+  assert.deepEqual(OUTSIDE_HOSTS, ["0.3.0", "0.3.0-rc.1", "0.3.0-alpha.1", "0.1.7-rc.1", "0.1.7-alpha.2"]);
+});
+
+test("every released DSH host is inside the declared range, and nothing untested is", () => {
+  const range = declaredHostRange(REPO_ROOT);
+  const { covered, uncovered, leaked } = checkHostCoverage(range);
+  assert.deepEqual(uncovered, [], `these releases fall outside ${range}`);
+  assert.deepEqual(leaked, [], `the declaration also admits ${leaked.join(", ")}, which nobody tested`);
+  assert.deepEqual(covered, HOST_RELEASES, "every release in the list must be covered");
+});
+
+test("the host-range gate rejects a plausible but wrong declaration", () => {
+  // Negative control: a gate that always passes proves nothing. `>=0.2.0` is the
+  // shape someone writes after testing only on their own machine — and because a
+  // prerelease sorts BELOW its release, it drops the whole 0.2.0-rc line as well
+  // as 0.1.7. That is the trap this test exists for: the typo looks like it names
+  // the running host.
+  const drifted = checkHostCoverage(">=0.2.0 <0.3.0-0");
+  assert.deepEqual(drifted.uncovered, ["0.2.0-rc.2", "0.2.0-rc.1", "0.1.7-rc.2"], "a 0.2.0 floor must be seen dropping the 0.2.0 prereleases");
+  // The OTHER half of the gate needs its own control: a floor low enough to admit
+  // a host nobody audited must be reported as a leak, not silently accepted.
+  const loose = checkHostCoverage(">=0.1.0 <0.3.0-0");
+  assert.deepEqual(loose.leaked, ["0.1.7-rc.1", "0.1.7-alpha.2"], "a low floor must be seen admitting the earlier prereleases");
+  // And the ceiling is load bearing: the next minor line is a host nobody audited,
+  // including its prereleases, which `<0.3.0` would have let through.
+  assert.equal(satisfiesDeclaredRange("0.3.0", ">=0.1.7-rc.2 <0.3.0-0"), false);
+  assert.equal(satisfiesDeclaredRange("0.3.0-rc.1", ">=0.1.7-rc.2 <0.3.0-0"), false);
+});
+
+test("prerelease ordering matches semver, not string order", () => {
+  assert.equal(compareVersions("0.2.1-alpha.5", "0.2.1-rc.1"), -1);
+  assert.equal(compareVersions("0.2.1-rc.2", "0.2.1"), -1);
+  assert.equal(compareVersions("0.2.0-rc.2", "0.2.0-rc.1"), 1);
+  // String comparison would sort "alpha.10" before "alpha.5"; semver does not.
+  assert.equal(compareVersions("0.2.1-alpha.10", "0.2.1-alpha.5"), 1);
+});
+
+test("the evaluator reads the two tolerances semver does, and refuses the rest", () => {
+  // Build metadata carries no precedence: a host reporting it is that version.
+  assert.equal(satisfiesDeclaredRange("0.2.0-rc.2+build.7", ">=0.1.7-rc.2 <0.3.0-0"), true);
+  // Everything else is refused rather than guessed at — a gate that accepts `v`
+  // prefixes and zero-padded identifiers would also accept a typo.
+  assert.throws(() => satisfiesDeclaredRange("v0.2.0-rc.2", ">=0.1.7-rc.2 <0.3.0-0"));
+  assert.throws(() => satisfiesDeclaredRange("0.2.1-01", ">=0.1.7-rc.2 <0.3.0-0"));
+});
+
+/* ------------------------------------------------------- the launch decision */
+
+// 2.x supplies a runtime the machine may not have; when it HAS one, the row must
+// use it — the 1.x contract. These tests own that decision, so every one of them
+// isolates PATH: without it the suite would silently depend on whatever `rea`
+// the machine running it happens to have, which is the one thing a test of a
+// machine-dependent decision must not do.
+
+function writeFakeRea(dir, { version = "6.9.0", exitForVersion = 0, runExit = 0, record = null } = {}) {
+  const file = path.join(dir, process.platform === "win32" ? "rea.cmd" : "rea");
+  if (process.platform === "win32") {
+    const lines = ["@echo off", 'if "%1"=="--version" (', `  echo ${version}`, `  exit /b ${exitForVersion}`, ")"];
+    if (record !== null) lines.push(`echo %* > "${record}"`);
+    lines.push(`exit /b ${runExit}`);
+    writeFileSync(file, lines.join("\r\n") + "\r\n");
+  } else {
+    const lines = ["#!/bin/sh", `if [ "$1" = "--version" ]; then echo ${version}; exit ${exitForVersion}; fi`];
+    if (record !== null) lines.push(`echo "$*" > "${record}"`);
+    lines.push(`exit ${runExit}`);
+    writeFileSync(file, lines.join("\n") + "\n");
+    chmodSync(file, 0o755);
+  }
+  return file;
+}
+
+function runShimIsolated(env, args) {
+  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], {
+    encoding: "utf8",
+    timeout: 60000,
+    env: merged,
+  });
+}
+
+function launchFixture() {
+  const root = mkdtempSync(path.join(tmpdir(), "rea-launch-"));
+  const emptyPath = path.join(root, "empty-path");
+  mkdirSync(emptyPath, { recursive: true });
+  return {
+    root,
+    emptyPath,
+    bundleRoot: path.join(root, "bundle"),
+    bin: path.join(root, "bin"),
+    record: path.join(root, "record.txt"),
+    clean() {
+      rmSync(root, { recursive: true, force: true });
+    },
+  };
+}
+
+test("a machine with its own REA runs the 1.x way, and no bundle is required", () => {
+  const f = launchFixture();
+  mkdirSync(f.bin, { recursive: true });
+  const rea = writeFakeRea(f.bin, { version: "6.9.0", record: f.record });
+  try {
+    const env = {
+      PATH: f.emptyPath,
+      REA_BUNDLE_SYSTEM_REA: rea,
+      REA_BUNDLE_ROOT: f.bundleRoot,
+      REA_BUNDLE_AUTO_PROVISION: "0",
+      REA_BUNDLE_LAUNCH: "",
+    };
+    const status = runShimIsolated(env, ["--shim-status"]);
+    const report = JSON.parse(status.stdout);
+    assert.equal(status.status, 0, status.stderr);
+    assert.equal(report.launch.mode, "system", JSON.stringify(report.launch));
+    assert.equal(report.launch.systemRea.version, "6.9.0");
+    // Unprovisioned and still healthy: the row does not depend on the bundle.
+    assert.equal(report.provisioned, false);
+    assert.equal(existsSync(path.join(f.bundleRoot, "bundle.json")), false, "no provisioning may be started");
+
+    const run = runShimIsolated(env, ["mcp"]);
+    assert.equal(run.status, 0, run.stderr);
+    assert.equal(readFileSync(f.record, "utf8").trim(), "mcp", "the system REA must receive the row's arguments");
+  } finally {
+    f.clean();
+  }
+});
+
+test("REA_BUNDLE_LAUNCH=bundle keeps the bundle path even with a REA on PATH", () => {
+  const f = launchFixture();
+  mkdirSync(f.bin, { recursive: true });
+  const rea = writeFakeRea(f.bin);
+  try {
+    const run = runShimIsolated(
+      { PATH: f.emptyPath, REA_BUNDLE_SYSTEM_REA: rea, REA_BUNDLE_ROOT: f.bundleRoot, REA_BUNDLE_AUTO_PROVISION: "0", REA_BUNDLE_LAUNCH: "bundle" },
+      ["--shim-status"],
+    );
+    const report = JSON.parse(run.stdout);
+    assert.equal(report.launch.mode, "bundle");
+    assert.equal(report.launch.reason, "pinned by REA_BUNDLE_LAUNCH=bundle");
+    assert.equal(run.status, 78, "an unpinned bundle that is not provisioned still reports EX_CONFIG");
+  } finally {
+    f.clean();
+  }
+});
+
+test("an older system REA does not displace a newer provisioned one unless pinned", () => {
+  const f = launchFixture();
+  mkdirSync(f.bin, { recursive: true });
+  mkdirSync(f.bundleRoot, { recursive: true });
+  const rea = writeFakeRea(f.bin, { version: "6.4.0" });
+  try {
+    writeFileSync(
+      path.join(f.bundleRoot, "bundle.json"),
+      JSON.stringify({ schema: 1, paths: { node: process.execPath }, versions: { reaAgents: "6.5.0" } }),
+    );
+    const base = { PATH: f.emptyPath, REA_BUNDLE_SYSTEM_REA: rea, REA_BUNDLE_ROOT: f.bundleRoot, REA_BUNDLE_AUTO_PROVISION: "0" };
+    const auto = JSON.parse(runShimIsolated({ ...base, REA_BUNDLE_LAUNCH: "" }, ["--shim-status"]).stdout);
+    assert.equal(auto.launch.mode, "bundle");
+    assert.match(auto.launch.reason, /older than the provisioned one/);
+    const pinned = JSON.parse(runShimIsolated({ ...base, REA_BUNDLE_LAUNCH: "system" }, ["--shim-status"]).stdout);
+    assert.equal(pinned.launch.mode, "system");
+    assert.match(pinned.launch.reason, /pinned by REA_BUNDLE_LAUNCH=system/);
+  } finally {
+    f.clean();
+  }
+});
+
+test("a candidate that cannot answer --version is rejected, not launched", () => {
+  const f = launchFixture();
+  mkdirSync(f.bin, { recursive: true });
+  const rea = writeFakeRea(f.bin, { exitForVersion: 7 });
+  try {
+    const run = runShimIsolated(
+      { PATH: f.emptyPath, 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);
+    assert.equal(report.launch.mode, "bundle");
+    assert.equal(report.launch.systemRea, null);
+    assert.deepEqual(report.launch.rejected.map(r => r.reason), ["exit 7"]);
+    assert.equal(run.status, 78);
+  } finally {
+    f.clean();
+  }
+});
+
+test("REA_BUNDLE_LAUNCH=system refuses instead of provisioning", () => {
+  const f = launchFixture();
+  const missing = path.join(f.bin, "no-such-rea");
+  try {
+    const run = runShimIsolated(
+      { PATH: f.emptyPath, REA_BUNDLE_SYSTEM_REA: missing, REA_BUNDLE_ROOT: f.bundleRoot, REA_BUNDLE_AUTO_PROVISION: "1", REA_BUNDLE_LAUNCH: "system" },
+      ["mcp"],
+    );
+    assert.equal(run.status, 78, run.stdout);
+    assert.match(run.stderr, /REA_BUNDLE_LAUNCH=system was requested/);
+    assert.equal(existsSync(f.bundleRoot), false, "a pinned system launch must not create a bundle");
+  } finally {
+    f.clean();
+  }
+});
+
+test("an unknown REA_BUNDLE_LAUNCH value is reported and treated as auto", () => {
+  const f = launchFixture();
+  mkdirSync(f.bin, { recursive: true });
+  const rea = writeFakeRea(f.bin, { version: "6.9.0" });
+  try {
+    const run = runShimIsolated(
+      { PATH: f.emptyPath, REA_BUNDLE_SYSTEM_REA: rea, REA_BUNDLE_ROOT: f.bundleRoot, REA_BUNDLE_AUTO_PROVISION: "0", REA_BUNDLE_LAUNCH: "nonsense" },
+      ["--shim-status"],
+    );
+    assert.match(run.stderr, /REA_BUNDLE_LAUNCH="nonsense" is not one of/);
+    assert.equal(JSON.parse(run.stdout).launch.mode, "system");
+  } finally {
+    f.clean();
+  }
+});
+
+test("the system REA is found through PATH itself, not only through the override", () => {
+  const f = launchFixture();
+  mkdirSync(f.bin, { recursive: true });
+  writeFakeRea(f.bin, { version: "6.9.0" });
+  try {
+    const run = runShimIsolated(
+      { PATH: f.bin, REA_BUNDLE_ROOT: f.bundleRoot, REA_BUNDLE_AUTO_PROVISION: "0", REA_BUNDLE_LAUNCH: "" },
+      ["--shim-status"],
+    );
+    const report = JSON.parse(run.stdout);
+    assert.equal(report.launch.mode, "system", JSON.stringify(report.launch));
+    assert.equal(report.launch.systemRea.version, "6.9.0");
+    assert.equal(run.status, 0);
+  } finally {
+    f.clean();
+  }
+});
+
+test("a REA installed under a path with a space is probed and launched", () => {
+  const f = launchFixture();
+  const spaced = path.join(f.root, "rea space");
+  mkdirSync(spaced, { recursive: true });
+  const rea = writeFakeRea(spaced, { version: "6.9.0", record: f.record });
+  try {
+    const env = { PATH: f.emptyPath, REA_BUNDLE_SYSTEM_REA: rea, REA_BUNDLE_ROOT: f.bundleRoot, REA_BUNDLE_AUTO_PROVISION: "0", REA_BUNDLE_LAUNCH: "" };
+    const status = JSON.parse(runShimIsolated(env, ["--shim-status"]).stdout);
+    assert.equal(status.launch.mode, "system", JSON.stringify(status.launch));
+    const run = runShimIsolated(env, ["mcp"]);
+    assert.equal(run.status, 0, run.stderr);
+    assert.equal(readFileSync(f.record, "utf8").trim(), "mcp");
+  } finally {
+    f.clean();
+  }
+});
+
+test("the delegated process's exit status is the shim's exit status", () => {
+  const f = launchFixture();
+  mkdirSync(f.bin, { recursive: true });
+  const rea = writeFakeRea(f.bin, { version: "6.9.0", runExit: 9 });
+  try {
+    const run = runShimIsolated(
+      { PATH: f.emptyPath, REA_BUNDLE_SYSTEM_REA: rea, REA_BUNDLE_ROOT: f.bundleRoot, REA_BUNDLE_AUTO_PROVISION: "0", REA_BUNDLE_LAUNCH: "" },
+      ["mcp"],
+    );
+    assert.equal(run.status, 9, `the row must see REA's own status, got ${run.status}`);
+  } finally {
+    f.clean();
+  }
+});
+
+test("a REA inside the bundle is not treated as a system install", () => {
+  const f = launchFixture();
+  mkdirSync(f.bundleRoot, { recursive: true });
+  const inside = writeFakeRea(f.bundleRoot, { version: "6.9.0" });
+  try {
+    const run = runShimIsolated(
+      { PATH: f.emptyPath, REA_BUNDLE_SYSTEM_REA: inside, REA_BUNDLE_ROOT: f.bundleRoot, REA_BUNDLE_AUTO_PROVISION: "0", REA_BUNDLE_LAUNCH: "" },
+      ["--shim-status"],
+    );
+    const report = JSON.parse(run.stdout);
+    assert.equal(report.launch.mode, "bundle");
+    assert.equal(report.launch.systemRea, null);
+    assert.deepEqual(report.launch.rejected.map(r => r.reason), ["inside the bundle"]);
+  } finally {
+    f.clean();
+  }
+});
+
+test("REA_BUNDLE_LAUNCH=bundle never probes the machine", () => {
+  const f = launchFixture();
+  mkdirSync(f.bin, { recursive: true });
+  // Any invocation at all leaves the record behind — including --version, which
+  // is exactly what `auto` would run.
+  const rea = writeFakeRea(f.bin, { version: "6.9.0", record: f.record });
+  try {
+    runShimIsolated(
+      { PATH: f.bin, REA_BUNDLE_SYSTEM_REA: rea, REA_BUNDLE_ROOT: f.bundleRoot, REA_BUNDLE_AUTO_PROVISION: "0", REA_BUNDLE_LAUNCH: "bundle" },
+      ["--shim-status"],
+    );
+    assert.equal(existsSync(f.record), false, "the pinned bundle path must not pay for a probe");
+  } finally {
+    f.clean();
+  }
+});
+
+test("--shim-print-env reports the system launch instead of a child environment", () => {
+  const f = launchFixture();
+  mkdirSync(f.bin, { recursive: true });
+  const rea = writeFakeRea(f.bin, { version: "6.9.0", record: f.record });
+  try {
+    const run = runShimIsolated(
+      { PATH: f.emptyPath, REA_BUNDLE_SYSTEM_REA: rea, REA_BUNDLE_ROOT: f.bundleRoot, REA_BUNDLE_AUTO_PROVISION: "0", REA_BUNDLE_LAUNCH: "" },
+      ["--shim-print-env"],
+    );
+    const printed = JSON.parse(run.stdout);
+    assert.equal(printed.launch, "system");
+    assert.equal(printed.version, "6.9.0");
+    assert.equal(existsSync(f.record), false, "printing the environment must not start REA");
+  } finally {
+    f.clean();
+  }
+});