dsh-plugin-rea 2.0.2 → 2.0.3

package/CHANGELOG.md

@@ -2,6 +2,98 @@
 
 本插件遵循语义化版本。版本号变化说明「配置组合」这层的变化，与 REA 自身的版本无关。
 
+## 2.0.3 — 2026-10-16
+
+**修复 11 处已核实的缺陷（每条都先确认存在、并配了"回退即变红"的回归测试）；上游 REA 钉子从 6.4.0 升到 6.5.0。**
+
+### 上游
+
+- `pins.reaAgents` 与 `components.reaAgents.sources.npm.version` → **6.5.0**：engines 与 bin 入口未变
+  （`^22.19.0 || ^24.11.0 || >=26.0.0`、`scripts/rea.mjs`），工具数 170 → **207**（运行时 `rea doctor --json` 实测；上游源码静态清点为 206，多出的 1 个注册在 contracts 之外。新增：Frida 9、
+  GDB 4、Rizin/Cutter 6、pcap/packet 4、flutter 2、sqlite/rust/go/wasm/electron/harmony/hopper 各 1 等）。
+  新增的 `optionalDependencies.frida` 在 `--ignore-scripts` 下不会执行安装脚本。REA 探针正则收紧为
+  `^6\.5\.0(\s|$)`，审计新增"下一个 patch/minor 不得通过"的断言。
+- Ghidra 12.1.4 / apktool 3.0.3 / jadx-headless-mcp 0.7.1 **经核实仍是当前最新**；Node 24.22.0 虽已发布，
+  但晚于本插件的实测矩阵，故保持 24.21.0（engines 完全满足）。
+
+### 修复
+
+- **`--only` 抹掉其它组件的记录**：bundle.json 由本轮结果整份重写，未点名组件的 `paths.jdk/ghidra` 变
+  `null`，shim 不再导出 `JAVA_HOME`/`GHIDRA_INSTALL_DIR`——原生分析静默失效，下次完整跑还得重新解压
+  750 MB。未点名的组件现在按旧记录结转（且只在记录的路径仍然存在时），缺依赖时优先用旧记录/机器/运行
+  setup 的解释器来满足，而不是整段跳过检查。
+- **完整的 `.part` 不被当作已完成**：只打一行日志，然后发 `Range: bytes=<全长>-`（416；四次重试后把
+  已经下好的文件报成失败）。现在校验通过即改名收下。
+- **Windows 下载主路线没有续传**：PowerShell 路线每轮先删 `.part`；失败后 Node 兜底仍用进本轮前的
+  `have`，以 append 把 200 全量接在半成品后面（长度必然超标，只能重下）。两条路线现在都按盘上实际
+  长度发 Range 续传。
+- **POSIX 的 apktool wrapper 没有执行位**（copyFileSync 落 0644，而 REA 不加 shell 直接 spawn → EACCES）：
+  manifest 里标了 `executable` 的条目落盘时 chmod 0755。
+- **apktool wrapper 钉在 `master` 分支 + 硬校验 sha256**：上游对 wrapper 的任何一次提交都会让全网新装
+  hash mismatch。改钉不可变的 `v3.0.3` tag，哈希按该 tag 重新实测。
+- **`--reuse` 不校验版本**：JDK 只看 `javac` 存在、Ghidra 只看 `analyzeHeadless` 存在（JDK 8/11、Ghidra 11
+  照收）。现在候选必须通过该组件自己的 probe；同时修好"文件型 probe 从不检查 `expect`"（Ghidra 的
+  `application.version=` 断言此前是死配置）。
+- **`bundle.json` 损坏即永久失败**：setup 读不了它、也没人启动 setup，用户只能手删文件。现在 setup 容忍
+  它（并按需重写），shim 对 `malformed` 与 `missing` 一样触发供给。
+- **失败后 shim 谎报 6 小时**：lock 现在记录状态与 pid；失败态如实报告"上一次失败了"，持有者已消失的
+  lock 不再阻塞重试。
+- **成功的 `--json` 轮次从不删 lock**：删除语句原先在非 `--json` 分支里，--json 成功也留下 lock。
+- **shim 兜底 REA 路径少了 `node_modules`**：旧 bundle.json 缺 `paths.reaEntry` 时会把可用安装判成"CLI 丢了"。
+- **`scripts/rea-bundle-bootstrap.ps1`**：`node -v` 输出非数字时 `[int]` 强转在 `$ErrorActionPreference='Stop'`
+  下会炸掉整个 bootstrap（而它存在的意义就是这条路径）；`&` 调用失败时 `$LASTEXITCODE` 可能为 `$null` →
+  `exit $null` = 假成功；engines 改从 manifest 的 `pins.nodeEngines` 读（不再抄第二份）；`-DryRun` 不再创建
+  目录（它承诺"什么都没改"）。
+- **`check-updates.ps1` 的 1.x 残留**：REA 节默认找 npm 全局包（2.x 是 vendored）、Ghidra 节读用户级
+  `GHIDRA_INSTALL_DIR`、`rea doctor` 拿不到 vendored CLI（整段自检被静默跳过）、一体包对账对"未记录版本"
+  的组件静默 `continue` 却打印"全部一致"。现在一律先读 `bundle.json`，并如实报告无法对账的项。
+
+### 审计与 CI
+
+- `audit-manifest.mjs` 新增 4 项：manifest 组件 ⇄ `INSTALL_ORDER` 对账、`pins.nodeEngines` ⇄ `package.json
+  engines`、REA pin 探针不得放行下一个 patch/minor、POSIX wrapper 必须标 `executable`。
+- `validate.yml` 新增 `windows-latest` job：PowerShell 下载路线、zip 解压与 bootstrap 此前是零 CI 覆盖的
+  Windows 专属代码。
+- 单测 33 条（32 过 + 1 条按平台跳过）；`--reuse adopts a compatible node` 在 engines 之外的宿主上改为显式
+  skip（此前在 Node 20 上必红，而 CI 钉 22 看不出来）。
+
+### 第二轮修复（同一份**更新后**的清单，2026-10-16 晚）
+
+- 🔴 **过期 lock 永久卡死自动供给（2.0.0–2.0.2 三版全带）**：`maybeAutoProvision()` 只在 lock 新鲜时
+  处理它，过期的 lock 既不清除也不报告 → 落到独占创建 → `EEXIST` → 返回 `in-flight`，而 `main()` 对
+  `in-flight` **一个字都不打印**。于是「下载被 kill / 断电」这一常态，在 6 小时后再启动就变成**永久不再
+  自动供给且完全静默**。已按清单复现（7 小时死 lock：不启动、lock 原样、无任何提示；5 分钟 lock 对照组
+  正常删锁重启），修法：**不新鲜或持有者已死就一律清锁**（这正是注释里"只在新鲜时尊重它"的本意），
+  并给 `in-flight` / `spawn-failed` / `unwritable` 补上如实提示。
+- 🔴 **`examples/` 两个文件是 1.x 内容，却随 2.x 进了 npm 包**：`cordis.patch.posix.yml` 教人把整行换成
+  `command: rea`、`cordis.patch.with-env.yml` 给的是 `cmd.exe /c rea` 的 1.x 行——对 2.x 全错（2.x 的行是
+  跨平台的 `process.execPath` + bundle shim，照抄会整行绕过 bundle）。两份都已是孤儿（README 不再引用），
+  故从 `main` **删除**，并同步 `package.json files[]` 与 `validate.yml` 的载荷/YAML/机器路径三项检查
+  （v1 分支保留它们，在 1.x 语境里是对的）。npm 载荷由此 21 → 19 个文件。
+- 🟡 **`--offline` 管不住 `reaAgents`**：`provisionReaAgents()` 里 0 处 offline 判断，`npm install` 永远
+  联网——与「`--offline` is a promise, not a hint」直接矛盾。现在 `--offline` 且内置副本不可用时**直接
+  FAIL** 并说明原因（而可用的内置副本仍照常跳过）。
+- 🟡 **npm 那一步没有代理/镜像兜底**：压缩包有 direct→proxy→PowerShell 三路，npm 只读环境变量。失败时
+  现在会打印这句提示，两份 README 的能力/注意里也写明 `HTTPS_PROXY` / `NPM_CONFIG_REGISTRY`。
+- 🟡 **POSIX 缺 `unzip`/`xz` 必现失败**：Ghidra 全平台只有 zip，而 POSIX 解压原先只有 `unzip` 一条路。
+  现在 zip 依次尝试 `unzip` → `python3 -m zipfile` → **已供给 JDK 自带的 `jar`**（JDK 在 Ghidra 之前供给，
+  等于保底），tar 依次 `tar` → `python3`；三者皆无时打印明确的「no zip extractor available」而不是干巴巴的
+  「extraction failed」。
+- 🟡 **manifest 的 arm64 注释是错的**：Google 的 linux/darwin platform-tools 都是 x86_64 二进制，
+  「The same archive serves x86-64 and arm64」不成立。三个条目改成如实描述（macOS 需 Rosetta 2、
+  linux-arm64 上 probe 预期失败并被报为可选组件不可用）。
+- 🟡 **`docs/bundle-design.md` 与实现漂移**：§3 的「row points at `<plugin>/bin/rea-shim.mjs`」改成
+  「按 `DSH_HOME` 算出 `<DSH_HOME>/plugins/rea-bundle/bin/rea-shim.mjs`（镜像副本）」；§7 的
+  `vendor/rea-agents` 改成 `vendor/node_modules/rea-agents`。
+- 🟢 **`release.yml` 的 `workflow_dispatch` 可绕过 Release 直接发 npm**：publish job 现在先断言
+  `v<package.json version>` 的 tag 在 origin 上存在、且该 Release 挂着版本无关的 `dsh-plugin-rea.tgz`
+  资产，否则拒绝发布（否则 npm 与市场兜底链接会岔开）。
+- 🟢 **数值环境变量会变成 NaN**：`REA_BUNDLE_FETCH_RETRIES=abc` → `Math.max(1, NaN)` → 报
+  「gave up after NaN attempt(s)」；NaN 的 socket 超时等价于 0（立即超时）。现在非正有限值一律回落到默认，
+  且启动日志新增一行 `limits connect=… idle=… retries=…`，让覆盖生效可见。
+- 🟢 注释与整洁：`downloadViaPowerShell` 的文档说自己是 fallback，实际在 Windows 上是主路线（已改口径）；
+  去掉 setup.mjs 里 3 处对已静态导入成员的重复 `await import("node:fs")`（`readdirSync` 补进静态导入）。
+
 ## 2.0.2 — 2026-10-15
 
 **仅文档，无行为变更。**

package/README.md

@@ -179,11 +179,11 @@ exact shim launch the MCP row will use.
 
 ## Verified against
 
-Author's machine, 2026-10-13 / 14:
+Author's machine, 2026-10-13 / 14 / 16:
 
 | Component | Version |
 |---|---|
-| REA (`rea-agents`) | **6.4.0** (170 tools) |
+| REA (`rea-agents`) | **6.5.0** (207 tools) |
 | DeepSeek Harness | desktop runtime **0.2.0-rc.2**, with its bundled dsh CLI 0.1.7-rc.2 |
 | `@deepseek-ai/dsh-mcp-client` (row provider) | bundled by the harness |
 | Ghidra | 12.1.4 |
@@ -192,7 +192,7 @@ Author's machine, 2026-10-13 / 14:
 | Host | Windows 11 x64 (build 26200) |
 
 Exercised live: a clean `setup.mjs --reuse` run reached `setup complete`; an MCP `initialize` handshake
-**through the shim with no `rea` on PATH** answered `serverInfo {name: rea, version: 6.4.0}`; and the whole
+**through the shim with no `rea` on PATH** answered `serverInfo {name: rea, version: 6.5.0}`; and the whole
 chain ran under the real desktop host — its own Electron binary launched
 `<DSH_HOME>/plugins/rea-bundle/bin/rea-shim.mjs mcp`, the shim started the **vendored** REA, and a live tool
 call reported `path_source: environment` for a path only that machine's `bundle.json` knows.
@@ -203,19 +203,28 @@ macOS/Linux.
 
 ## Scope and caveats
 
-- REA exposes 170 tools at 6.4.0, so every session's tool list grows.
+- REA exposes 207 tools at 6.5.0, so every session's tool list grows.
 - Provisioning is honest about checksums: where a vendor publishes one it is pinned and verified; where none
   exists (jadx-headless-mcp, the apktool wrapper, Android platform-tools, the rolling "latest" URLs) the
   hash is **measured once and recorded**, and later drift is reported rather than silently accepted.
   `bundle.json` lists which components are in that state under `unverifiedChecksums`.
 - Downloads are slow on some networks (measured 0.35–0.54 MiB/s from the GitHub release CDN here, so Ghidra
-  alone takes ~25–45 min). Fetching is resumable: the cache is kept and re-verified, and a killed run
-  continues instead of restarting.
+  alone takes ~25–45 min). Fetching is resumable on both routes: a partial `.part` is continued with a Range
+  request, and a `.part` that already holds the whole file is verified and kept instead of re-fetched.
 - Some REA tools launch processes, write files and access the network — DSH's permission policy applies.
   Analyse only artifacts you are authorized to inspect.
 - `scripts/setup.mjs` runs `npm install` for the REA CLI with `--ignore-scripts`: the published tarball
   carries no `node_modules`, so a dependency closure must be resolved, and package lifecycle scripts are
-  skipped on purpose during provisioning.
+  skipped on purpose during provisioning. That step is also the **only** one that cannot use this bundle's
+  own route/proxy resolution — npm reads `HTTPS_PROXY`/`HTTP_PROXY` and `NPM_CONFIG_REGISTRY` from the
+  environment, so on a network that needs a mirror, set one of those before provisioning
+  (`NPM_CONFIG_REGISTRY=https://registry.npmmirror.com`). With `--offline` the step is refused outright
+  instead of quietly going online.
+- On POSIX, extraction falls back when the usual tools are missing: a zip is opened with `unzip`, then
+  `python3 -m zipfile`, then the provisioned JDK's `jar`; a tarball with `tar`, then `python3`. A minimal
+  image that has none of them fails with an explicit "no zip extractor available" line rather than a bare
+  "extraction failed". This matters because Ghidra is a zip on every platform and `unzip` is not installed
+  everywhere by default.
 
 ## Updating — three independent things
 

package/README.zh-CN.md

@@ -170,11 +170,11 @@ shim 启动**。
 
 ## 实测环境
 
-作者机器，2026-10-13 / 14：
+作者机器，2026-10-13 / 14 / 16：
 
 | 组件 | 版本 |
 |---|---|
-| REA（`rea-agents`） | **6.4.0**（170 个工具） |
+| REA（`rea-agents`） | **6.5.0**（207 个工具） |
 | DeepSeek Harness | desktop runtime **0.2.0-rc.2**，内含 dsh CLI 0.1.7-rc.2 |
 | `@deepseek-ai/dsh-mcp-client`（行 provider） | 随 harness 打包 |
 | Ghidra | 12.1.4 |
@@ -183,7 +183,7 @@ shim 启动**。
 | 宿主 | Windows 11 x64（build 26200） |
 
 实测跑过：一次干净的 `setup.mjs --reuse` 走到 `setup complete`；一次**不经 PATH 上的 `rea`、完全经由
-shim** 的 MCP `initialize` 握手返回 `serverInfo {name: rea, version: 6.4.0}`；以及**真实桌面宿主下的完整链路** ——
+shim** 的 MCP `initialize` 握手返回 `serverInfo {name: rea, version: 6.5.0}`；以及**真实桌面宿主下的完整链路** ——
 宿主自己的 Electron 二进制启动 `<DSH_HOME>/plugins/rea-bundle/bin/rea-shim.mjs mcp`，shim 拉起 **bundle 内置**
 的 REA，随后一次真实工具调用报出 `path_source: environment`，而那个路径只有该机的 `bundle.json` 知道。
 
@@ -192,18 +192,27 @@ shim** 的 MCP `initialize` 握手返回 `serverInfo {name: rea, version: 6.4.0}
 
 ## 边界与注意事项
 
-- REA 在 6.4.0 有 170 个工具，每个会话的工具列表都会变长。
+- REA 在 6.5.0 有 207 个工具，每个会话的工具列表都会变长。
 - 校验和对得起良心：厂商发布了的就固定并验证；没发布的（jadx-headless-mcp、apktool 包装脚本、
   Android platform-tools、滚动的 `latest` 地址）则**实测一次并记录**，之后若漂移是**报告**而不是默默接受。
   `bundle.json` 的 `unverifiedChecksums` 会列出处于该状态的组件。
 - 某些网络下很慢（这里实测 GitHub release CDN 只有 0.35–0.54 MiB/s，光 Ghidra 就要 25–45 分钟）。
-  下载是**可续传**的：缓存保留并重新校验，被中断的一轮会继续而不是从头再来。
+  下载是**可续传**的：两条路线都按盘上已有的字节发 Range 继续；若 `.part` 恰好已经完整，会校验后直接收下
+  而不是重下。
 - **代理**：Node 的全局 `fetch` 不读系统代理，而 .NET/PowerShell 会读。在开着 WinINET 代理的机器上，
   同一个地址 `Invoke-WebRequest` 通、Node 却 `ECONNRESET`/超时。setup 自己解析代理
   （环境变量优先，Windows 上回退读注册表）并用 CONNECT 隧道，`NO_PROXY` 也照常生效。
 - REA 的部分工具会启动进程、写文件、访问网络 —— DSH 的权限策略照常适用。只分析你有权检视的样本。
 - `scripts/setup.mjs` 为 REA CLI 跑的是带 `--ignore-scripts` 的 `npm install`：官方 tarball 不带
-  `node_modules`，必须解析依赖闭包；而供给过程中**刻意跳过包的 lifecycle 脚本**。
+  `node_modules`，必须解析依赖闭包；而供给过程中**刻意跳过包的 lifecycle 脚本**。这一步也是**唯一**用不上
+  本插件自己的路由/代理回退的环节 —— npm 只从环境读 `HTTPS_PROXY`/`HTTP_PROXY` 与
+  `NPM_CONFIG_REGISTRY`，所以网络需要镜像时请先设其中一个（例如
+  `NPM_CONFIG_REGISTRY=https://registry.npmmirror.com`）。带 `--offline` 时这一步会被**直接拒绝**，
+  而不是悄悄联网。
+- POSIX 上解压有兜底：zip 依次尝试 `unzip` → `python3 -m zipfile` → 已供给 JDK 自带的 `jar`；tar 包依次
+  尝试 `tar` → `python3`。三者都没有的最小镜像会得到一句明确的「no zip extractor available」，而不是
+  干巴巴的「extraction failed」。Ghidra 在所有平台都只有 zip，而 `unzip` 并非每个发行版默认安装，
+  所以这条不是理论问题。
 
 ## 更新 —— 三件互相独立的事
 

package/assets/make-screenshots.ps1

@@ -84,7 +84,7 @@ Draw-Text $g '第三方适配 · 自身不做逆向分析 · 自供给 Node/REA/
 $rowY = 180; $boxH = 158; $boxW = 250
 Draw-Box $g 60 $rowY $boxW $boxH $([System.Drawing.Color]::White) $line
 Draw-Text $g 'DeepSeek Harness 会话' $fBox $ink 80 ($rowY + 18)
-Draw-Text $g "mcp__rea__* 工具`n（6.4.0 暴露 170+）`n工具随会话注入`n按 DSH 权限策略执行" $fBody $muted 80 ($rowY + 50)
+Draw-Text $g "mcp__rea__* 工具`n（6.5.0 暴露 207）`n工具随会话注入`n按 DSH 权限策略执行" $fBody $muted 80 ($rowY + 50)
 
 Draw-Box $g 360 $rowY $boxW $boxH $([System.Drawing.Color]::FromArgb(255,239,246,255)) $accent
 Draw-Text $g '官方 MCP 客户端行' $fBox $accent 380 ($rowY + 18)
@@ -112,7 +112,7 @@ Draw-Line  $g 358 446 150 446 $muted
 Draw-Arrow $g 150 446 150 342 $muted
 
 Draw-Text $g '上游 REA（MIT）：github.com/morluto/rea      本插件：github.com/czcdr/dsh-plugin-rea' $fSmall $muted 60 620
-Draw-Text $g '实测 REA 6.4.0 + DSH 桌面运行时 0.2.0-rc.2 + Ghidra 12.1.4 + Node 24.21.0（Windows 11 x64，2026-10-14）' $fSmall $muted 60 646
+Draw-Text $g '实测 REA 6.5.0 + DSH 桌面运行时 0.2.0-rc.2 + Ghidra 12.1.4 + Node 24.21.0（Windows 11 x64，2026-10-16）' $fSmall $muted 60 646
 Draw-Text $g 'Ghidra 为 Apache-2.0（NSA）；REA 为 MIT。本仓库不分发上游代码。' $fSmall $muted 60 672
 Save-Png $bmp $g (Join-Path $OutDir 'screenshot-1.png')
 

package/bin/rea-shim.mjs

@@ -15,7 +15,7 @@
  *                            and the message is the operator's remediation.
  */
 import { spawn } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
 import process from "node:process";
@@ -93,6 +93,40 @@ function provisioningScript(root) {
   return usableSetup(PLUGIN_ROOT);
 }
 
+/**
+ * The provisioning lock is a small JSON record: { state, pid, at, exit? }.
+ * `state: "running"` is written when a run is started (setup's own pid once it
+ * exists), and the failing run rewrites it as `state: "failed"` — it is kept on
+ * purpose so a broken setup cannot be re-downloaded in a loop. A legacy
+ * plain-number lock is still honoured as "running".
+ */
+const STALE_LOCK_MS = 6 * 60 * 60 * 1000;
+
+function readLock(lock) {
+  try {
+    const raw = readFileSync(lock, "utf8").trim();
+    if (raw.startsWith("{")) {
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === "object") return parsed;
+    }
+    const at = Number(raw);
+    return Number.isFinite(at) ? { state: "running", at } : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Is the process recorded in the lock still alive? null means "cannot tell". */
+function pidAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return null;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code === "ESRCH" ? false : null;
+  }
+}
+
 /**
  * On first run there is nothing to launch. Provisioning is a long download, so
  * it is started detached: the harness may kill this row (or the whole session)
@@ -100,34 +134,58 @@ function provisioningScript(root) {
  * a killed attempt is simply continued on the next start.
  *
  * Set REA_BUNDLE_AUTO_PROVISION=0 to require an explicit `setup.mjs` run.
- * Returns the log path when a run was started, otherwise null.
+ * 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.
  */
 function maybeAutoProvision(root) {
-  if (process.env.REA_BUNDLE_AUTO_PROVISION === "0") return null;
+  if (process.env.REA_BUNDLE_AUTO_PROVISION === "0") return { started: false, reason: "disabled" };
   const setupScript = provisioningScript(root);
-  if (!setupScript) return null;
+  if (!setupScript) return { started: false, reason: "no-setup" };
   const lock = path.join(root, "setup.lock");
   const logPath = path.join(root, "logs", "setup.log");
   if (existsSync(lock)) {
     // A crashed run must not wedge provisioning forever: honour the lock only
     // while it is fresh; setup removes it itself when it finishes cleanly.
-    let age = Infinity;
-    try {
-      age = Date.now() - Number(readFileSync(lock, "utf8").trim() || 0);
-    } catch {
-      age = Infinity;
+    const record = readLock(lock);
+    const age = record && Number.isFinite(record.at) ? Date.now() - record.at : Infinity;
+    const fresh = Number.isFinite(age) && age < STALE_LOCK_MS;
+    if (fresh && record?.state === "failed") {
+      // The run gave up and left the lock behind so it would not be retried in a
+      // loop. Claiming it is still provisioning was a six-hour lie: nothing runs,
+      // and every restart repeated the sentence.
+      return {
+        started: false,
+        reason: "last-run-failed",
+        exit: record.exit,
+        failedAt: record.at,
+        ageMs: age,
+        logPath,
+      };
+    }
+    if (fresh) {
+      const alive = pidAlive(record?.pid);
+      if (alive !== false) return { started: false, reason: "in-flight", logPath, ageMs: age };
     }
-    if (Number.isFinite(age) && age < 6 * 60 * 60 * 1000) return logPath;
+    // 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
+    // *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.
+    rmSync(lock, { force: true });
   }
   try {
     mkdirSync(path.join(root, "logs"), { recursive: true });
     // Exclusive create: check-then-write is not atomic, so two rows starting at
     // once could both decide to provision. EEXIST means another run owns it.
-    writeFileSync(lock, String(Date.now()), { flag: "wx" });
+    writeFileSync(lock, JSON.stringify({ state: "running", pid: process.pid, at: Date.now() }), { flag: "wx" });
   } catch (error) {
-    if (error?.code === "EEXIST") return logPath;
+    if (error?.code === "EEXIST") return { started: false, reason: "in-flight", logPath };
     /* a read-only bundle root must never break the harness */
-    return null;
+    return { started: false, reason: "unwritable" };
   }
   try {
     const child = spawn(process.execPath, [setupScript, "--root", root], {
@@ -136,9 +194,18 @@ function maybeAutoProvision(root) {
       windowsHide: true,
     });
     child.unref();
-    return logPath;
+    // Hand the lock to the detached downloader, so a later start that finds this
+    // row dead still sees the run that is actually doing the work as alive.
+    if (Number.isInteger(child.pid)) {
+      try {
+        writeFileSync(lock, JSON.stringify({ state: "running", pid: child.pid, at: Date.now(), supervisor: process.pid }));
+      } catch {
+        /* the lock is advisory: the row keeps working without it */
+      }
+    }
+    return { started: true, reason: "started", logPath };
   } catch {
-    return null;
+    return { started: false, reason: "spawn-failed", logPath };
   }
 }
 
@@ -195,8 +262,13 @@ function readBundleConfig(root) {
 function resolveRea(config, root) {
   const paths = config.paths ?? {};
   const node = paths.node;
+  // 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
+  // a wrong fallback turns a usable install into "the vendored REA CLI is gone".
   const reaEntry = paths.reaEntry
-    ?? path.join(root, "vendor", "rea-agents", "scripts", "rea.mjs");
+    ?? path.join(root, "vendor", "node_modules", "rea-agents", "scripts", "rea.mjs");
 
   if (typeof node !== "string" || node.trim() === "") {
     return { ok: false, reason: "bundle.json has no paths.node" };
@@ -302,10 +374,31 @@ function main() {
       loaded.code === "missing"
         ? `No bundle state at ${loaded.file}.`
         : `Bundle state at ${loaded.file} could not be parsed.`;
-    const logPath = loaded.code === "missing" ? maybeAutoProvision(root) : null;
-    if (logPath) {
+    // Both "missing" and "malformed" start a run. A malformed file used to fail
+    // permanently: setup overwrites a bundle.json it cannot parse, but nothing
+    // ever started setup, so every restart reported the same EX_CONFIG until the
+    // operator deleted the file by hand. The lock stops a provisioning loop when
+    // writing keeps failing.
+    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`,
+      );
+    } 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`,
+      );
+    } else if (provisioning.reason === "in-flight") {
+      // A live run owns the lock. Saying nothing here is what made a wedged
+      // provisioning attempt look like a machine that simply has no bundle.
+      process.stderr.write(
+        `\n  dsh-plugin-rea (bundle): provisioning is already running in the background.\n  progress: ${provisioning.logPath}\n`,
+      );
+    } else if (provisioning.reason === "spawn-failed" || provisioning.reason === "unwritable") {
       process.stderr.write(
-        `\n  dsh-plugin-rea (bundle): first run — provisioning started in the background.\n  progress: ${logPath}\n`,
+        `\n  dsh-plugin-rea (bundle): provisioning could not be started (${provisioning.reason}).\n` +
+          `  Run it by hand:\n    node "${path.join(root, "scripts", "setup.mjs")}"\n`,
       );
     }
     return fail(message, loaded.detail);

package/check-updates.ps1

@@ -69,13 +69,40 @@ function Test-NodeEngines([string]$node, [string]$engines) {
 }
 
 # ------------------------------------------------------- 定位 REA 与 profile
+# 2.x 的 REA 在 <bundleRoot>\vendor\node_modules\rea-agents，不在 npm 全局。先读
+# bundle.json：把全局路径当默认是 1.x 的答案，在 2.x 机器上会让这一节指向错误的
+# 对象（"全局包丢了"），并给出错误的升级动作（npm i -g）。
+$bundleRootEarly = $env:REA_BUNDLE_ROOT
+if (-not $bundleRootEarly) {
+  $homeEarly = $env:DSH_HOME
+  if (-not $homeEarly) { $homeEarly = Join-Path $HOME '.dsh' }
+  $bundleRootEarly = Join-Path $homeEarly 'plugins\rea-bundle'
+}
+$bundleState = $null
+$bundleJsonEarly = Join-Path $bundleRootEarly 'bundle.json'
+if (Test-Path $bundleJsonEarly) {
+  try { $bundleState = Get-Content $bundleJsonEarly -Raw -Encoding UTF8 | ConvertFrom-Json } catch { $bundleState = $null }
+}
+$bundleReaPackageDir = $null
+$bundleReaEntry = $null
+if ($bundleState -and $bundleState.paths.reaEntry) {
+  $bundleReaEntry = [string]$bundleState.paths.reaEntry
+  # <vendor>\node_modules\rea-agents\scripts\rea.mjs -> <vendor>\node_modules\rea-agents
+  $bundleReaPackageDir = Split-Path -Parent (Split-Path -Parent $bundleReaEntry)
+}
+
 if (-not $ReaPackageDir) {
-  $npmRoot = $null
-  if (Get-Command npm -ErrorAction SilentlyContinue) {
-    try { $npmRoot = (& npm root -g 2>$null | Select-Object -First 1).Trim() } catch { }
+  if ($bundleReaPackageDir -and (Test-Path (Join-Path $bundleReaPackageDir 'package.json'))) {
+    $ReaPackageDir = $bundleReaPackageDir
+  } else {
+    $npmRoot = $null
+    if (Get-Command npm -ErrorAction SilentlyContinue) {
+      try { $npmRoot = (& npm root -g 2>$null | Select-Object -First 1).Trim() } catch { }
+    }
+    $ReaPackageDir = if ($npmRoot) { Join-Path $npmRoot 'rea-agents' } else { Join-Path $env:APPDATA 'npm\node_modules\rea-agents' }
   }
-  $ReaPackageDir = if ($npmRoot) { Join-Path $npmRoot 'rea-agents' } else { Join-Path $env:APPDATA 'npm\node_modules\rea-agents' }
 }
+$reaFromBundle = [bool]($bundleReaPackageDir -and $ReaPackageDir -eq $bundleReaPackageDir)
 if (-not $ProfileDir) {
   if ($env:DSH_PROFILE_DIR) { $ProfileDir = $env:DSH_PROFILE_DIR }
   else {
@@ -94,11 +121,21 @@ if (Test-Path $pkgFile) {
     $installed = $pkg.version; $engines = $pkg.engines.node
     $binPath = ($pkg.bin.PSObject.Properties | Select-Object -First 1).Value
     if ($binPath) { $reaEntry = Join-Path $ReaPackageDir ($binPath -replace '/', '\') }
-    Ok "本地已安装: $installed"
-    Info "入口(bin): $binPath   ← 插件通过 PATH 上的 rea 调用它，跨版本稳定"
+    if ($reaFromBundle) {
+      Ok "一体包内置（vendored）: $installed"
+      Info "位置: $ReaPackageDir"
+      Info "入口(bin): $binPath"
+    } else {
+      Ok "本地已安装: $installed"
+      Info "入口(bin): $binPath   ← 插件通过 PATH 上的 rea 调用它，跨版本稳定"
+    }
     if ($engines) { Info "Node 要求: $engines" }
   } catch { Bad "package.json 解析失败: $($_.Exception.Message)" }
-} else { Bad "找不到 $pkgFile —— REA 全局包丢了？重装: npm i -g rea-agents" }
+} else {
+  if ($reaFromBundle) { Bad "找不到 $pkgFile —— 内置副本不完整？重跑 setup.mjs" }
+  elseif ($bundleReaPackageDir) { Bad "找不到 $pkgFile —— 一体包内置副本也缺（$bundleReaPackageDir）；记录里没有 reaEntry" }
+  else { Bad "找不到 $pkgFile —— REA 全局包丢了？重装: npm i -g rea-agents" }
+}
 
 $latest = $null
 foreach ($r in @($Registry, 'https://registry.npmjs.org')) {
@@ -110,7 +147,11 @@ if ($installed -and $latest) {
   $vi = Get-NumericVersion $installed; $vl = Get-NumericVersion $latest
   if ($vi -and $vl -and $vl -gt $vi) {
     Warn "有新版本：$installed → $latest"
-    $actions.Add("升级上游 REA:  npm i -g rea-agents@$latest    （只更新 REA；本插件不会自动更新——从市场装的在市场里更新，file: 装的覆盖目录后重装）")
+    if ($reaFromBundle) {
+      $actions.Add("升级一体包内置 REA：把 manifest 的 pins.reaAgents / components.reaAgents.sources.npm.version 改成 $latest，然后重跑 node scripts\setup.mjs（内置副本不会自己更新）")
+    } else {
+      $actions.Add("升级上游 REA:  npm i -g rea-agents@$latest    （只更新 REA；本插件不会自动更新——从市场装的在市场里更新，file: 装的覆盖目录后重装）")
+    }
   } elseif ($vi -and $vl -and $vl -eq $vi -and $installed -ne $latest) {
     Warn "同版本号但通道不同：$installed → $latest（预发布/正式）"
   } else { Ok '已是最新版本' }
@@ -139,7 +180,14 @@ if (Get-Command node -ErrorAction SilentlyContinue) {
 
 # ------------------------------------------------------------ Ghidra 引擎
 Head 'Ghidra 引擎'
-$gd = [Environment]::GetEnvironmentVariable('GHIDRA_INSTALL_DIR', 'User')
+# bundle.json 是 2.x 的真源：shim 只在 MCP 子进程里设 GHIDRA_INSTALL_DIR，用户级
+# 变量是 1.x 的写法，没手工设过的机器会被误报"未设置"。
+$gd = $null
+if ($bundleState -and $bundleState.paths.ghidra) {
+  $bundleGhidra = [string]$bundleState.paths.ghidra
+  if (Test-Path $bundleGhidra) { $gd = $bundleGhidra }
+}
+if (-not $gd) { $gd = [Environment]::GetEnvironmentVariable('GHIDRA_INSTALL_DIR', 'User') }
 if (-not $gd) { $gd = $env:GHIDRA_INSTALL_DIR }
 if ($gd -and (Test-Path $gd)) {
   Ok "GHIDRA_INSTALL_DIR = $gd"
@@ -162,11 +210,28 @@ try {
 # --------------------------------------------------------- REA 引擎自检
 Head 'REA 引擎自检（rea doctor）'
 $env:GHIDRA_INSTALL_DIR = $gd
-# 优先取 .cmd：发布出去的那一行是 `cmd.exe /c rea mcp`（走 cmd 的 PATHEXT，命中 rea.cmd），
-# 而 PowerShell 的 Get-Command rea 会先命中同目录的 rea.ps1 垫片，两者行为（尤其退出码）并不相同。
-$reaCmd = (Get-Command 'rea.cmd' -ErrorAction SilentlyContinue).Source
-if (-not $reaCmd) { $reaCmd = (Get-Command rea -ErrorAction SilentlyContinue).Source }
+# 2.x：优先用 bundle 内置的 CLI 和它自己的 Node。PATH 上的 rea 可能是另一个，
+# 甚至完全不在 PATH —— 那会让整段自检被静默跳过。这正是 1.x 口径的残留。
+$reaCmd = $null
 $reaArgs = @()
+if ($bundleReaEntry -and (Test-Path $bundleReaEntry)) {
+  $bundleNode = $null
+  if ($bundleState -and $bundleState.paths.node) {
+    $candidateNode = [string]$bundleState.paths.node
+    if (Test-Path $candidateNode) { $bundleNode = $candidateNode }
+  }
+  if (-not $bundleNode) { $bundleNode = (Get-Command node -ErrorAction SilentlyContinue).Source }
+  if ($bundleNode) {
+    $reaCmd = $bundleNode; $reaArgs = @($bundleReaEntry)
+    Info '使用一体包内置 REA（node <bundle 入口>），不依赖 PATH 上的 rea'
+  }
+}
+if (-not $reaCmd) {
+  # 优先取 .cmd：发布出去的那一行是 `cmd.exe /c rea mcp`（走 cmd 的 PATHEXT，命中 rea.cmd），
+  # 而 PowerShell 的 Get-Command rea 会先命中同目录的 rea.ps1 垫片，两者行为（尤其退出码）并不相同。
+  $reaCmd = (Get-Command 'rea.cmd' -ErrorAction SilentlyContinue).Source
+  if (-not $reaCmd) { $reaCmd = (Get-Command rea -ErrorAction SilentlyContinue).Source }
+}
 if (-not $reaCmd) {
   if ($reaEntry -and (Test-Path $reaEntry) -and (Get-Command node -ErrorAction SilentlyContinue)) {
     $reaCmd = 'node'; $reaArgs = @($reaEntry)
@@ -247,6 +312,8 @@ if (-not (Test-Path $manifestPath)) {
       $state = Get-Content $bundleJson -Raw -Encoding UTF8 | ConvertFrom-Json
       Ok "已供给：$($state.provisionedAt)"
       $drift = 0
+      $compared = 0
+      $unrecorded = 0
       foreach ($name in $manifest.pins.PSObject.Properties.Name) {
         if ($name -eq 'nodeEngines') { continue }
         $pinned = [string]$manifest.pins.$name
@@ -254,13 +321,21 @@ if (-not (Test-Path $manifestPath)) {
         if ($state.versions -and ($state.versions.PSObject.Properties.Name -contains $name)) {
           $installed = [string]$state.versions.$name
         }
-        if (-not $installed) { continue }
+        if (-not $installed) {
+          # 被 --reuse 采纳的组件没有 version 字段（bundle.json 里是 null）。静默
+          # continue 会让这一项从未被比对，却在下面打印"全部一致"——那是假绿。
+          $unrecorded++
+          Warn "  $name 未记录版本（reuse 采纳的组件？）—— 无法与 pin $pinned 对账"
+          continue
+        }
+        $compared++
         # Node 的 pin 是引擎范围，不是版本号；其它组件比前缀即可
         $same = $installed.Equals($pinned) -or $installed.StartsWith(($pinned -split '\.')[0] + '.')
         if ($same) { Info "  $name = $installed（pin $pinned）" }
         else { Warn "$name 盘上为 $installed，manifest 已钉 $pinned —— 重跑 setup 对齐"; $drift++ }
       }
-      if ($drift -eq 0) { Ok '所有组件与 manifest 的 pin 一致' }
+      if ($drift -eq 0 -and $unrecorded -eq 0) { Ok '所有组件与 manifest 的 pin 一致' }
+      elseif ($drift -eq 0) { Warn "已比对的 $compared 项与 pin 一致，但 $unrecorded 项没有记录版本（见上）—— 不是全绿" }
       if ($state.unverifiedChecksums -and @($state.unverifiedChecksums).Count -gt 0) {
         Warn ("TOFU（无厂商校验和，取首次实测值）: " + (@($state.unverifiedChecksums) -join ', '))
       }

package/docs/bundle-design.md

@@ -31,11 +31,11 @@ Two upstream rules shape the runtime wiring:
 
 ## 2. Verified facts this design rests on
 
-Measured on Windows 11 x64, REA 6.4.0, Ghidra 12.1.4, Temurin JDK 25.0.4:
+Measured on Windows 11 x64, REA 6.5.0, Ghidra 12.1.4, Temurin JDK 25.0.4:
 
 | Fact | Evidence |
 | --- | --- |
-| A row can launch REA with **no PATH `rea`** | `node <pkg>/scripts/rea.mjs mcp` answered the MCP `initialize` handshake (`serverInfo.name = rea`, version 6.4.0) and `rea doctor --json` reported 170 tools, `healthy: true` |
+| A row can launch REA with **no PATH `rea`** | `node <pkg>/scripts/rea.mjs mcp` answered the MCP `initialize` handshake (`serverInfo.name = rea`, version 6.5.0) and `rea doctor --json` reported 207 tools. `healthy` is `false` on a bundle-only install: 6.5.0 also checks the host's own setup (Hopper, IDA registration, `rea setup` skill/registrations), which provisioning deliberately never touches — the row does not require `healthy`, only a CLI that runs and a catalog it can read |
 | `!!js` expressions are supported in this profile layer | the existing profile patch already used one; the loader evaluates them |
 | A row-level `env:` block reaches the MCP child | `binary_session` reported `registrationEnvironment` = `GHIDRA_INSTALL_DIR`, `JAVA_HOME` |
 | No fixed home/layout is promised | the disk layout differs per install; nothing may assume one |
@@ -54,8 +54,9 @@ Three responsibilities, kept strictly apart:
    checksums, unpacks, runs the readiness probe, and writes `bundle.json`.
    Idempotent and re-runnable; `--reuse` adopts pre-existing installs.
 3. **Patch (wiring, published).** `cordis.patch.yml` on `main`, carrying
-   **no machine path**: the row points at `<plugin>/bin/rea-shim.mjs` and the
-   shim is responsible for the rest.
+   **no machine path**: the row computes `<DSH_HOME>/plugins/rea-bundle/bin/rea-shim.mjs`
+   at load time from `DSH_HOME` alone, and that mirrored shim is responsible for the
+   rest. (The checkout's own copy is what a human runs; the row never points at it.)
 
 The published plugin therefore stays portable, while the machine-specific truth
 lives in one small JSON file under the DSH home.
@@ -161,7 +162,7 @@ Windows and is what this bundle targets to complete.
 | Component | Needed for | Provisioned as |
 | --- | --- | --- |
 | Node runtime | running REA at all | reuse a compatible existing node, else portable `node.exe` |
-| `rea-agents` | the MCP server itself | vendored copy under `vendor/rea-agents` |
+| `rea-agents` | the MCP server itself | vendored copy under `vendor/node_modules/rea-agents` |
 | Temurin JDK 21/25 | Ghidra headless + JADX bridge | portable JDK zip (full JDK, not a JRE) |
 | Ghidra 12.1.x | native analysis | official release zip, extracted |
 | apktool | Android resource decode | `apktool.bat` + jar in one directory |