dsh-plugin-rea 2.0.2 → 2.0.3

package/scripts/setup.test.mjs

@@ -11,8 +11,10 @@
  * Runs with `node --test`. No network, no filesystem writes outside a temp dir.
  */
 import assert from "node:assert/strict";
-import { spawnSync } from "node:child_process";
-import { chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { spawn, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import { createServer } from "node:http";
 import { tmpdir } from "node:os";
 import path from "node:path";
 import test from "node:test";
@@ -319,7 +321,17 @@ function runSetupNodeOnly(setupPath, root, env) {
   });
 }
 
-test("--reuse still adopts a compatible node", () => {
+test("--reuse still adopts a compatible node", (t) => {
+  // The candidate is the host's own interpreter, so this test only means anything
+  // where the host satisfies REA's engines: on a Node 20 runner it fails for a
+  // reason that has nothing to do with the reuse check (the check is doing its
+  // job), while CI's pinned Node 22 never notices.
+  const [major, minor] = process.versions.node.split(".").map(Number);
+  const compatible = (major === 22 && minor >= 19) || (major === 24 && minor >= 11) || major >= 26;
+  if (!compatible) {
+    t.skip(`host Node ${process.versions.node} is outside REA's engines; the candidate would be rejected on purpose`);
+    return;
+  }
   const root = mkdtempSync(path.join(tmpdir(), "rea-node-ok-"));
   try {
     const run = runSetupNodeOnly(SETUP_SOURCE, root, { REA_BUNDLE_NODE: process.execPath });
@@ -395,7 +407,7 @@ test("an unavailable optional component is reported, not fatal", () => {
     mkdirSync(stub, { recursive: true });
     writeFileSync(
       path.join(stub, "rea.mjs"),
-      'if (process.argv.includes("--version")) { console.log("6.4.0"); } else { console.log(JSON.stringify({ checks: [], tools: [] })); }\n',
+      'if (process.argv.includes("--version")) { console.log("6.5.0"); } else { console.log(JSON.stringify({ checks: [], tools: [] })); }\n',
     );
 
     const run = spawnSync(process.execPath, [SETUP_SOURCE, "--offline", "--only", "androidPlatformTools", "--root", root], {
@@ -416,3 +428,670 @@ test("an unavailable optional component is reported, not fatal", () => {
     rmSync(root, { recursive: true, force: true });
   }
 });
+
+/* =========================== this round's regressions =========================
+ *
+ * Each test below pins a defect that was verified in the code before it was
+ * changed. They run setup.mjs itself (never a mirror of it) against a throwaway
+ * plugin tree, so the whole wiring — manifest → download → place → wire — is the
+ * real one. Nothing here reaches the network: a component is either satisfied
+ * from a primed cache, or its download is *supposed* to return before opening a
+ * socket.
+ */
+
+const REPO_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+const REPO_SHIM = path.join(REPO_ROOT, "bin", "rea-shim.mjs");
+
+/** A throwaway plugin tree: setup.mjs, the real manifest, and the shim. */
+function makePluginTree(root, mutateManifest) {
+  const plugin = path.join(root, "plugin");
+  mkdirSync(path.join(plugin, "scripts"), { recursive: true });
+  mkdirSync(path.join(plugin, "manifest"), { recursive: true });
+  mkdirSync(path.join(plugin, "bin"), { recursive: true });
+  copyFileSync(SETUP_SOURCE, path.join(plugin, "scripts", "setup.mjs"));
+  copyFileSync(REPO_SHIM, path.join(plugin, "bin", "rea-shim.mjs"));
+  const manifest = JSON.parse(readFileSync(MANIFEST_SOURCE, "utf8"));
+  if (mutateManifest) mutateManifest(manifest);
+  writeFileSync(path.join(plugin, "manifest", "bundle.manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
+  return path.join(plugin, "scripts", "setup.mjs");
+}
+
+/** A `file`-kind component, used to replace a real one in a test manifest. */
+function testComponent(url, payload, extra = {}) {
+  return {
+    description: "test vehicle",
+    kind: "file",
+    license: "test",
+    requires: extra.requires ?? [],
+    optional: extra.optional ?? false,
+    probe: extra.probe ?? {},
+    entries: {
+      all: [
+        {
+          id: "payload",
+          version: "1",
+          url,
+          format: "file",
+          size: payload.length,
+          sha256: createHash("sha256").update(payload).digest("hex"),
+          moveTo: extra.moveTo ?? "payload",
+          saveAs: extra.saveAs ?? "payload.bin",
+          ...(extra.executable ? { executable: true } : {}),
+        },
+      ],
+    },
+  };
+}
+
+/** A stub vendored CLI, so the probe/shim stages have something to run. */
+function addReaStub(bundleRoot, version = "6.5.0") {
+  const dir = path.join(bundleRoot, "vendor", "node_modules", "rea-agents", "scripts");
+  mkdirSync(dir, { recursive: true });
+  const identity = JSON.stringify({ cli_package_version: version, catalog: { counts: { mcp_tools: 206 } } });
+  writeFileSync(
+    path.join(dir, "rea.mjs"),
+    'if (process.argv.includes("--version")) { console.log(' + JSON.stringify(version) + '); }\n' +
+      "else { console.log(JSON.stringify({ healthy: true, checks: [], identity: " + identity + " })); }\n",
+  );
+}
+
+function runToCompletion(command, args, options) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, options);
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => { stdout += chunk; });
+    child.stderr.on("data", (chunk) => { stderr += chunk; });
+    child.on("error", (error) => resolve({ status: -1, stdout, stderr: String(error) }));
+    child.on("close", (code) => resolve({ status: code, stdout, stderr }));
+  });
+}
+
+async function waitFor(predicate, timeoutMs = 8000) {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    if (predicate()) return true;
+    if (Date.now() > deadline) return false;
+    await new Promise((resolve) => setTimeout(resolve, 50));
+  }
+}
+
+/* ------------------------------- --only keeps what it did not touch -------- */
+
+test("--only keeps the records of the components it did not touch", () => {
+  const root = mkdtempSync(path.join(tmpdir(), "rea-only-keep-"));
+  try {
+    const bundle = path.join(root, "bundle");
+    mkdirSync(bundle, { recursive: true });
+    const jdkHome = path.join(root, "jdk-home");
+    mkdirSync(jdkHome, { recursive: true });
+    // A provisioned machine: the JDK and Node are recorded, and only adb is being
+    // topped up. Writing bundle.json from this run's results alone erased the
+    // other two, so the shim stopped exporting JAVA_HOME/GHIDRA_INSTALL_DIR.
+    writeFileSync(
+      path.join(bundle, "bundle.json"),
+      JSON.stringify(
+        {
+          schema: 1,
+          paths: { node: process.execPath, jdk: jdkHome, ghidra: null, adb: null },
+          versions: { reaAgents: "6.5.0", node: process.versions.node, jdk: "21" },
+          components: {
+            node: { path: process.execPath, version: process.versions.node },
+            jdk: { path: jdkHome, version: "21" },
+          },
+        },
+        null,
+        2,
+      ) + "\n",
+    );
+    addReaStub(bundle);
+    const setup = makePluginTree(root, (manifest) => {
+      manifest.components.androidPlatformTools = testComponent("http://127.0.0.1:9/payload.bin", Buffer.from("adb"), { optional: true });
+    });
+    const run = spawnSync(process.execPath, [setup, "--offline", "--only", "androidPlatformTools", "--root", bundle], {
+      encoding: "utf8",
+      timeout: 120000,
+    });
+    assert.equal(run.status, 0, `${run.stdout}\n${run.stderr}`);
+    const written = JSON.parse(readFileSync(path.join(bundle, "bundle.json"), "utf8"));
+    assert.equal(written.components.jdk.path, jdkHome, "the jdk record must survive an --only run");
+    assert.equal(written.paths.jdk, jdkHome, "and so must the path the shim exports as JAVA_HOME");
+    assert.equal(written.components.node.path, process.execPath);
+    assert.equal(written.paths.node, process.execPath);
+    // The component that did run failed (offline), and stays unavailable: the
+    // merge must not invent a path for it.
+    assert.equal(written.paths.adb, null);
+    assert.equal(written.components.androidPlatformTools.unavailable, true);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("--only satisfies a requirement from the record instead of skipping the check", () => {
+  const root = mkdtempSync(path.join(tmpdir(), "rea-only-requires-"));
+  try {
+    const bundle = path.join(root, "bundle");
+    mkdirSync(bundle, { recursive: true });
+    const jdkHome = path.join(root, "jdk-home");
+    mkdirSync(jdkHome, { recursive: true });
+    const setup = makePluginTree(root, () => {});
+    const args = (extra) => [setup, "--reuse", "--dry-run", "--only", "apktool", "--root", bundle, ...extra];
+    // JAVA_HOME is also a way "the machine" answers this requirement, so it is
+    // cleared: the first case needs the requirement to be genuinely unavailable.
+    const env = { ...process.env, JAVA_HOME: "" };
+
+    // No record at all: the requirement is genuinely unavailable, and that must be
+    // reported exactly as a full run reports it.
+    const missing = spawnSync(process.execPath, args([]), { encoding: "utf8", timeout: 120000, env });
+    assert.match(missing.stdout, /required component "jdk" is unavailable/);
+
+    // With a recorded JDK the requirement is answered by the record, so apktool
+    // plans instead of failing on a vendor/jdk that --only never provisions.
+    writeFileSync(
+      path.join(bundle, "bundle.json"),
+      JSON.stringify({ schema: 1, paths: { jdk: jdkHome }, versions: { jdk: "21" }, components: { jdk: { path: jdkHome, version: "21" } } }, null, 2) + "\n",
+    );
+    const recorded = spawnSync(process.execPath, args([]), { encoding: "utf8", timeout: 120000, env });
+    assert.equal(recorded.status, 0, `${recorded.stdout}\n${recorded.stderr}`);
+    assert.doesNotMatch(recorded.stdout, /required component "jdk" is unavailable/);
+    assert.match(recorded.stdout, /\[plan\] apktool/);
+    // And `--only reaAgents` on a fresh root must still work: the node it needs is
+    // the interpreter running setup, which is what provisionReaAgents already uses.
+    const fresh = path.join(root, "fresh");
+    const reaOnly = spawnSync(process.execPath, [setup, "--dry-run", "--only", "reaAgents", "--root", fresh], { encoding: "utf8", timeout: 120000, env });
+    assert.equal(reaOnly.status, 0, `${reaOnly.stdout}\n${reaOnly.stderr}`);
+    assert.doesNotMatch(reaOnly.stdout, /required component "node" is unavailable/);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+/* ------------------------------------------- a complete .part is finished work */
+
+test("a complete .part is verified and kept instead of re-requested", () => {
+  const root = mkdtempSync(path.join(tmpdir(), "rea-part-complete-"));
+  try {
+    const bundle = path.join(root, "bundle");
+    mkdirSync(path.join(bundle, "cache"), { recursive: true });
+    const payload = Buffer.from("the whole file, already on disk\n");
+    // The URL points at a closed port on purpose: the fixed code must complete
+    // without opening a socket. Before the fix it sent `Range: bytes=<size>-`,
+    // which a real server answers with 416, and four attempts later it reported a
+    // download that was already finished as failed.
+    const setup = makePluginTree(root, (manifest) => {
+      manifest.components.androidPlatformTools = testComponent("http://127.0.0.1:9/payload.bin", payload);
+    });
+    addReaStub(bundle);
+    writeFileSync(path.join(bundle, "cache", "payload.bin.part"), payload);
+
+    const run = spawnSync(process.execPath, [setup, "--only", "androidPlatformTools", "--root", bundle], { encoding: "utf8", timeout: 120000 });
+    assert.equal(run.status, 0, `${run.stdout}\n${run.stderr}`);
+    assert.match(run.stdout, /was already complete; verified and kept/);
+    assert.deepEqual(readFileSync(path.join(bundle, "vendor", "payload", "payload.bin")), payload);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+/* ------------------------------------------------- the PowerShell route resumes */
+
+test("the PowerShell route resumes from the bytes already on disk", async (t) => {
+  if (process.platform !== "win32") {
+    // The Node route pins TLS (`httpsRequest`) whatever the URL scheme says, so a
+    // plain-HTTP fixture can only exercise the PowerShell route — which is also the
+    // Windows default and the one the resume defect was in.
+    t.skip("the PowerShell download route only exists on Windows");
+    return;
+  }
+  const payload = Buffer.alloc(1024 * 1024, 11);
+  const alreadyHave = 256 * 1024;
+  const seen = [];
+  const server = createServer((req, res) => {
+    req.on("error", () => {});
+    res.on("error", () => {});
+    const range = req.headers.range ?? null;
+    seen.push(range);
+    const start = range ? Number(/bytes=(\d+)-/.exec(range)?.[1] ?? 0) : 0;
+    if (range && start >= payload.length) {
+      res.writeHead(416);
+      res.end();
+      return;
+    }
+    const slice = payload.subarray(start);
+    const headers = { "content-type": "application/octet-stream", "content-length": String(slice.length) };
+    if (start > 0) headers["content-range"] = `bytes ${start}-${payload.length - 1}/${payload.length}`;
+    res.writeHead(start > 0 ? 206 : 200, headers);
+    res.end(slice);
+  });
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const port = server.address().port;
+  const root = mkdtempSync(path.join(tmpdir(), "rea-ps-resume-"));
+  try {
+    const bundle = path.join(root, "bundle");
+    mkdirSync(path.join(bundle, "cache"), { recursive: true });
+    const setup = makePluginTree(root, (manifest) => {
+      manifest.components.androidPlatformTools = testComponent(`http://127.0.0.1:${port}/payload.bin`, payload);
+    });
+    addReaStub(bundle);
+    writeFileSync(path.join(bundle, "cache", "payload.bin.part"), payload.subarray(0, alreadyHave));
+
+    const run = await runToCompletion(process.execPath, [setup, "--only", "androidPlatformTools", "--root", bundle], {
+      encoding: "utf8",
+      timeout: 120000,
+    });
+    assert.equal(run.status, 0, `${run.stdout}\n${run.stderr}`);
+    assert.ok(
+      seen.some((header) => header && Number(/bytes=(\d+)-/.exec(header)?.[1]) === alreadyHave),
+      `expected a resume request starting at ${alreadyHave}; saw ${JSON.stringify(seen)}`,
+    );
+    assert.deepEqual(readFileSync(path.join(bundle, "vendor", "payload", "payload.bin")), payload);
+  } finally {
+    await new Promise((resolve) => server.close(resolve));
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+/* ------------------------------------------------- a wrapper must be executable */
+
+test("a wrapper marked executable lands with the exec bit on POSIX", (t) => {
+  if (process.platform === "win32") {
+    t.skip("POSIX exec bits do not exist on Windows; the flag is honoured but meaningless there");
+    return;
+  }
+  const root = mkdtempSync(path.join(tmpdir(), "rea-exec-bit-"));
+  try {
+    const bundle = path.join(root, "bundle");
+    mkdirSync(path.join(bundle, "cache"), { recursive: true });
+    const marked = Buffer.from("#!/bin/sh\necho wrapper\n");
+    const plain = Buffer.from("not a script\n");
+    const setup = makePluginTree(root, (manifest) => {
+      const component = testComponent("http://127.0.0.1:9/wrapper.sh", marked, { executable: true, saveAs: "wrapper.sh", moveTo: "tool" });
+      component.entries.all.push({
+        id: "plain",
+        version: "1",
+        url: "http://127.0.0.1:9/plain.sh",
+        format: "file",
+        size: plain.length,
+        sha256: createHash("sha256").update(plain).digest("hex"),
+        moveTo: "tool",
+        saveAs: "plain.sh",
+      });
+      manifest.components.androidPlatformTools = component;
+    });
+    addReaStub(bundle);
+    // Prime the cache so no socket is opened and the mode is the only variable.
+    writeFileSync(path.join(bundle, "cache", "wrapper.sh"), marked);
+    writeFileSync(path.join(bundle, "cache", "plain.sh"), plain);
+
+    const run = spawnSync(process.execPath, [setup, "--only", "androidPlatformTools", "--root", bundle], { encoding: "utf8", timeout: 120000 });
+    assert.equal(run.status, 0, `${run.stdout}\n${run.stderr}`);
+    const wrapperMode = statSync(path.join(bundle, "vendor", "tool", "wrapper.sh")).mode;
+    const plainMode = statSync(path.join(bundle, "vendor", "tool", "plain.sh")).mode;
+    assert.notEqual(wrapperMode & 0o111, 0, `the marked wrapper must be executable, mode ${wrapperMode.toString(8)}`);
+    assert.equal(plainMode & 0o111, 0, "an unmarked file must keep the mode the archive gave it");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+/* ------------------------------------------- a file probe's expect is honoured */
+
+test("a file probe honours expect.contains", () => {
+  const root = mkdtempSync(path.join(tmpdir(), "rea-file-probe-"));
+  try {
+    const make = (content) => {
+      const bundle = path.join(root, `bundle-${content.length}`);
+      mkdirSync(path.join(bundle, "cache"), { recursive: true });
+      const payload = Buffer.from(content);
+      const component = testComponent("http://127.0.0.1:9/marker.txt", payload, { saveAs: "marker.txt", moveTo: "probe" });
+      component.probe = { file: "{vendor}/probe/marker.txt", expect: { contains: "application.version=" } };
+      const setup = makePluginTree(path.join(root, `tree-${content.length}`), (manifest) => {
+        manifest.components.androidPlatformTools = component;
+      });
+      addReaStub(bundle);
+      writeFileSync(path.join(bundle, "cache", "marker.txt"), payload);
+      return spawnSync(process.execPath, [setup, "--only", "androidPlatformTools", "--root", bundle], { encoding: "utf8", timeout: 120000 });
+    };
+    const ok = make("application.version=12.1.4\n");
+    assert.equal(ok.status, 0, `${ok.stdout}\n${ok.stderr}`);
+    // The file exists either way; only its content decides. Before the fix the
+    // `expect` on a file probe was dead configuration and this case passed.
+    const wrong = make("this is not a Ghidra properties file\n");
+    assert.equal(wrong.status, 1, `${wrong.stdout}\n${wrong.stderr}`);
+    assert.match(wrong.stdout, /does not contain "application\.version="/);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+/* ------------------------------------- a reused engine must pass its own probe */
+
+test("a reused component must pass the probe a provisioned copy would face", () => {
+  const root = mkdtempSync(path.join(tmpdir(), "rea-reuse-probe-"));
+  try {
+    const install = path.join(root, "ghidra");
+    mkdirSync(path.join(install, "support"), { recursive: true });
+    mkdirSync(path.join(install, "Ghidra"), { recursive: true });
+    writeFileSync(path.join(install, "support", process.platform === "win32" ? "analyzeHeadless.bat" : "analyzeHeadless"), "");
+    const properties = path.join(install, "Ghidra", "application.properties");
+    const setup = makePluginTree(root, (manifest) => {
+      // The real manifest needs a JDK for ghidra; this test is about the reuse
+      // probe, so the requirement is removed rather than faked.
+      manifest.components.ghidra.requires = [];
+    });
+    const bundle = path.join(root, "bundle");
+    const args = ["--reuse", "--dry-run", "--only", "ghidra", "--root", bundle];
+    const env = { ...process.env, GHIDRA_INSTALL_DIR: install };
+
+    writeFileSync(properties, "application.version=12.1.4\n");
+    const good = spawnSync(process.execPath, [setup, ...args], { encoding: "utf8", env, timeout: 120000 });
+    assert.equal(good.status, 0, `${good.stdout}\n${good.stderr}`);
+    assert.match(good.stdout, /reusing existing ghidra from GHIDRA_INSTALL_DIR/);
+
+    // Adoption used to test only that analyzeHeadless exists, so any directory
+    // shaped like a Ghidra install was recorded and the failure surfaced inside REA.
+    writeFileSync(properties, "not a Ghidra properties file\n");
+    const bad = spawnSync(process.execPath, [setup, ...args], { encoding: "utf8", env, timeout: 120000 });
+    assert.doesNotMatch(bad.stdout, /reusing existing ghidra/);
+    assert.match(bad.stdout, /not reusing GHIDRA_INSTALL_DIR ghidra/);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+/* ------------------------------------------------------------- the shim's lock */
+
+function makeBundleTree(root, { marker, lock }) {
+  const bundle = path.join(root, "bundle");
+  mkdirSync(path.join(bundle, "bin"), { recursive: true });
+  mkdirSync(path.join(bundle, "scripts"), { recursive: true });
+  mkdirSync(path.join(bundle, "manifest"), { recursive: true });
+  copyFileSync(REPO_SHIM, path.join(bundle, "bin", "rea-shim.mjs"));
+  writeFileSync(path.join(bundle, "scripts", "setup.mjs"), 'import { writeFileSync } from "node:fs";\nwriteFileSync(' + JSON.stringify(marker) + ', "ran");\n');
+  writeFileSync(path.join(bundle, "manifest", "bundle.manifest.json"), "{}\n");
+  if (lock !== undefined) writeFileSync(path.join(bundle, "setup.lock"), lock);
+  return bundle;
+}
+
+function runShim(bundle, args) {
+  const env = { ...process.env, REA_BUNDLE_ROOT: bundle };
+  delete env.REA_BUNDLE_AUTO_PROVISION;
+  return spawnSync(process.execPath, [path.join(bundle, "bin", "rea-shim.mjs"), ...args], { encoding: "utf8", timeout: 60000, env });
+}
+
+test("a malformed bundle.json starts a provisioning run instead of failing forever", async () => {
+  const root = mkdtempSync(path.join(tmpdir(), "rea-shim-malformed-"));
+  try {
+    const marker = path.join(root, "setup-ran");
+    const bundle = makeBundleTree(root, { marker, lock: undefined });
+    writeFileSync(path.join(bundle, "bundle.json"), "{ this is not json");
+    const run = runShim(bundle, ["mcp"]);
+    assert.equal(run.status, 78, run.stderr);
+    assert.match(run.stderr, /provisioning started in the background/);
+    assert.ok(await waitFor(() => existsSync(marker)), "setup was never started for a malformed bundle.json");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("a failed lock is reported as failed, not as provisioning in progress", async () => {
+  const root = mkdtempSync(path.join(tmpdir(), "rea-shim-failed-lock-"));
+  try {
+    const marker = path.join(root, "setup-ran");
+    const lock = JSON.stringify({ state: "failed", pid: 1, at: Date.now(), exit: 1 });
+    const bundle = makeBundleTree(root, { marker, lock });
+    // No bundle.json: the "missing" path, which used to print the "provisioning
+    // started" sentence for six hours while nothing was running at all.
+    const run = runShim(bundle, ["mcp"]);
+    assert.equal(run.status, 78, run.stderr);
+    assert.match(run.stderr, /the last provisioning attempt failed/);
+    assert.doesNotMatch(run.stderr, /provisioning started in the background/);
+    assert.equal(existsSync(marker), false, "a fresh failed lock must not trigger another run");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("a lock whose holder is gone does not block provisioning", async () => {
+  const root = mkdtempSync(path.join(tmpdir(), "rea-shim-dead-lock-"));
+  try {
+    const marker = path.join(root, "setup-ran");
+    const dead = spawnSync(process.execPath, ["-e", ""]);
+    assert.ok(Number.isInteger(dead.pid), "could not obtain a pid to outlive");
+    const lock = JSON.stringify({ state: "running", pid: dead.pid, at: Date.now() });
+    const bundle = makeBundleTree(root, { marker, lock });
+    const run = runShim(bundle, ["mcp"]);
+    assert.equal(run.status, 78, run.stderr);
+    assert.match(run.stderr, /provisioning started in the background/);
+    assert.ok(await waitFor(() => existsSync(marker)), "a dead lock holder must not suppress the run");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("an expired lock is cleared instead of wedging provisioning forever", async () => {
+  const stale = Date.now() - 7 * 60 * 60 * 1000;
+  const dead = spawnSync(process.execPath, ["-e", ""]).pid;
+  const cases = {
+    "running lock with a dead holder": JSON.stringify({ state: "running", pid: dead, at: stale }),
+    "failed lock past the freshness window": JSON.stringify({ state: "failed", pid: dead, at: stale, exit: 1 }),
+    "legacy numeric lock": String(stale),
+  };
+  for (const [label, lock] of Object.entries(cases)) {
+    const root = mkdtempSync(path.join(tmpdir(), "rea-shim-stale-"));
+    try {
+      const marker = path.join(root, "setup-ran");
+      const bundle = makeBundleTree(root, { marker, lock });
+      const run = runShim(bundle, ["mcp"]);
+      assert.equal(run.status, 78, `${label}: ${run.stderr}`);
+      // Reproduced before the fix: all three cases were silent AND blocked, because
+      // the stale lock was never removed and the exclusive create then failed with
+      // EEXIST forever. A lock older than the freshness window is not evidence of a
+      // run, so it must be dropped and the attempt started again.
+      assert.match(run.stderr, /provisioning started in the background/, label);
+      assert.ok(await waitFor(() => existsSync(marker)), `${label}: setup was never started`);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  }
+});
+
+/* ------------------------------- --offline is a promise, and npm is the one step
+ * that cannot keep it: it is an install, not a download. -------------------- */
+
+test("--offline refuses the npm step instead of going online anyway", () => {
+  const root = mkdtempSync(path.join(tmpdir(), "rea-offline-rea-"));
+  try {
+    const setup = makePluginTree(root, () => {});
+    const bundle = path.join(root, "bundle");
+    const run = spawnSync(process.execPath, [setup, "--offline", "--only", "reaAgents", "--root", bundle], {
+      encoding: "utf8",
+      timeout: 120000,
+    });
+    assert.equal(run.status, 1, `${run.stdout}\n${run.stderr}`);
+    assert.match(run.stdout, /--offline and the vendored REA/);
+
+    // The other direction: a usable vendored copy is still accepted offline, so the
+    // flag does not turn into "reaAgents can never be provisioned".
+    const second = path.join(root, "bundle2");
+    mkdirSync(second, { recursive: true });
+    addReaStub(second);
+    const ok = spawnSync(process.execPath, [setup, "--offline", "--only", "reaAgents", "--root", second], {
+      encoding: "utf8",
+      timeout: 120000,
+    });
+    assert.equal(ok.status, 0, `${ok.stdout}\n${ok.stderr}`);
+    assert.match(ok.stdout, /already vendored/);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+/* ------------------------------- numeric overrides must not become NaN ------ */
+
+test("a non-numeric numeric override falls back to the default", () => {
+  const root = mkdtempSync(path.join(tmpdir(), "rea-env-"));
+  try {
+    const setup = makePluginTree(root, () => {});
+    const run = (env) =>
+      spawnSync(process.execPath, [setup, "--dry-run", "--only", "node", "--root", path.join(root, "bundle")], {
+        encoding: "utf8",
+        timeout: 120000,
+        env: { ...process.env, ...env },
+      });
+    // `Number("abc")` is NaN, and NaN reached the socket layer as 0-ish behaviour;
+    // `REA_BUNDLE_FETCH_RETRIES=abc` once produced "gave up after NaN attempt(s)".
+    const bogus = run({ REA_BUNDLE_FETCH_RETRIES: "abc", REA_BUNDLE_IDLE_TIMEOUT_MS: "abc", REA_BUNDLE_CONNECT_TIMEOUT_MS: "abc" });
+    assert.equal(bogus.status, 0, `${bogus.stdout}\n${bogus.stderr}`);
+    assert.match(bogus.stdout, /retries=4\b/);
+    assert.match(bogus.stdout, /idle=120000ms/);
+    assert.doesNotMatch(bogus.stdout, /NaN/);
+    const explicit = run({ REA_BUNDLE_FETCH_RETRIES: "7" });
+    assert.match(explicit.stdout, /retries=7\b/);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+/* ------------------------------- POSIX extraction fallbacks ----------------- */
+
+/** An `archive`-kind component, for the extraction paths. */
+function testArchive(url, payload, extra = {}) {
+  return {
+    description: "test archive",
+    kind: "archive",
+    license: "test",
+    requires: [],
+    optional: false,
+    unpack: { stripRootComponents: extra.strip ?? 0, moveTo: extra.moveTo ?? "arch" },
+    probe: extra.probe ?? {},
+    sources: {
+      all: {
+        version: "1",
+        url,
+        format: extra.format ?? "zip",
+        size: payload.length,
+        sha256: createHash("sha256").update(payload).digest("hex"),
+      },
+    },
+  };
+}
+
+test("a zip still extracts when unzip is absent (POSIX fallbacks)", (t) => {
+  if (process.platform === "win32") {
+    t.skip("Windows extracts through tar/Expand-Archive; the POSIX fallbacks do not exist there");
+    return;
+  }
+  const root = mkdtempSync(path.join(tmpdir(), "rea-extract-"));
+  try {
+    // A real zip, built with the very tool the fallback will use.
+    const zipPath = path.join(root, "fixture.zip");
+    const built = spawnSync("python3", [
+      "-c",
+      "import sys,zipfile;z=zipfile.ZipFile(sys.argv[1],'w');z.writestr('inside.txt','hello from inside\\n');z.close()",
+      zipPath,
+    ]);
+    if (built.status !== 0) {
+      t.skip("python3 is unavailable, so neither the fixture nor the fallback can run");
+      return;
+    }
+    const payload = readFileSync(zipPath);
+    const python = spawnSync("sh", ["-c", "command -v python3"], { encoding: "utf8" }).stdout.trim();
+    assert.ok(python, "python3 was just used to build the fixture");
+
+    // A PATH that has python3 and nothing else: unzip cannot be found, which is
+    // exactly the bare-server case. Ghidra ships only as a zip, so this used to be
+    // a certain failure rather than an occasional one.
+    const binDir = path.join(root, "bin");
+    mkdirSync(binDir, { recursive: true });
+    const onlyPython = path.join(binDir, "python3");
+    symlinkSync(python, onlyPython);
+    const setup = makePluginTree(root, (manifest) => {
+      manifest.components.androidPlatformTools = testArchive("http://127.0.0.1:9/fixture.zip", payload);
+    });
+    const cases = [
+      { label: "python3 fallback", path: binDir, expected: 0 },
+      { label: "no extractor at all", path: path.join(root, "empty-bin"), expected: 1 },
+    ];
+    for (const testCase of cases) {
+      mkdirSync(testCase.path, { recursive: true });
+      const bundle = path.join(root, `bundle-${testCase.expected}`);
+      mkdirSync(path.join(bundle, "cache"), { recursive: true });
+      writeFileSync(path.join(bundle, "cache", "fixture.zip"), payload);
+      addReaStub(bundle);
+      const run = spawnSync(process.execPath, [setup, "--only", "androidPlatformTools", "--root", bundle], {
+        encoding: "utf8",
+        timeout: 120000,
+        env: { ...process.env, PATH: testCase.path },
+      });
+      assert.equal(run.status, testCase.expected, `${testCase.label}: ${run.stdout}\n${run.stderr}`);
+      if (testCase.expected === 0) {
+        assert.equal(readFileSync(path.join(bundle, "vendor", "arch", "inside.txt"), "utf8"), "hello from inside\n");
+      } else {
+        assert.match(run.stdout, /no zip extractor available/);
+        assert.match(run.stdout, /install unzip or python3/);
+      }
+    }
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("the fallback vendored-REA path matches where setup installs it", () => {
+  const root = mkdtempSync(path.join(tmpdir(), "rea-shim-fallback-"));
+  try {
+    const bundle = path.join(root, "bundle");
+    // An older bundle.json has paths.node but no paths.reaEntry. The fallback used
+    // to omit `node_modules`, so a working install was reported as gone.
+    mkdirSync(bundle, { recursive: true });
+    addReaStub(bundle);
+    writeFileSync(path.join(bundle, "bundle.json"), JSON.stringify({ schema: 1, paths: { node: process.execPath } }, null, 2) + "\n");
+    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" },
+    });
+    const report = JSON.parse(run.stdout);
+    assert.equal(report.rea.ok, true, JSON.stringify(report.rea));
+    assert.match(report.rea.reaEntry, /node_modules/);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("--json releases the lock on success and marks it failed on failure", () => {
+  const root = mkdtempSync(path.join(tmpdir(), "rea-lock-json-"));
+  try {
+    const bundle = path.join(root, "bundle");
+    mkdirSync(bundle, { recursive: true });
+    addReaStub(bundle);
+    const component = (optional) =>
+      makePluginTree(path.join(root, optional ? "ok" : "bad"), (manifest) => {
+        manifest.components.androidPlatformTools = testComponent("http://127.0.0.1:9/payload.bin", Buffer.from("adb"), { optional });
+      });
+
+    // The lock is what tells the shim a run is in flight. A successful --json run
+    // used to leave it behind (the removal sat in the non---json branch), so a
+    // fully provisioned machine advertised "provisioning started" for six hours.
+    writeFileSync(path.join(bundle, "setup.lock"), JSON.stringify({ state: "running", pid: process.pid, at: Date.now() }));
+    const ok = spawnSync(process.execPath, [component(true), "--json", "--offline", "--only", "androidPlatformTools", "--root", bundle], {
+      encoding: "utf8",
+      timeout: 120000,
+    });
+    assert.equal(ok.status, 0, `${ok.stdout}\n${ok.stderr}`);
+    assert.equal(existsSync(path.join(bundle, "setup.lock")), false, "a successful --json run must not leave the lock behind");
+
+    // A failing run keeps the lock on purpose, but records why, so the shim can
+    // report a failure instead of pretending a run is still going.
+    const bad = spawnSync(process.execPath, [component(false), "--json", "--offline", "--only", "androidPlatformTools", "--root", bundle], {
+      encoding: "utf8",
+      timeout: 120000,
+    });
+    assert.equal(bad.status, 1, `${bad.stdout}\n${bad.stderr}`);
+    const lock = JSON.parse(readFileSync(path.join(bundle, "setup.lock"), "utf8"));
+    assert.equal(lock.state, "failed");
+    assert.equal(lock.exit, 1);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});