@dptech-corp/bohr-cli 2.6.91 → 2.6.92

package/CHANGELOG.md

@@ -16,6 +16,28 @@
 
 ## [Unreleased]
 
+## [2.6.92] - 2026-09-10
+
+### Fixed
+
+- **安装失败的原因现在真的看得见**：npm 默认把 postinstall 的输出整个收走，此前拒装/失败的理由一个字都到不了用户眼前；改走终端后正常 `npm install` 下就能看到。
+- **两个安装同时跑不再互相踩**：临时文件名此前固定，并发安装会让一个装好的工具被报成失败。
+- **服务端不出这个平台的包时会说清楚**：此前报的是「取哈希失败 HTTP 400」，读起来像服务端故障。
+- **postinstall 下载不再拖垮 `npm install`**：写盘失败、跨协议跳转、重定向环此前会让安装崩掉或卡死，现在都变成一次可见的失败并跳过该工具。
+- **伴生工具的哈希校验改为必须**：发布方给不出可用 SHA256（空响应、缺字段、格式非法）时，此前会静默跳过校验照装 trisol / wenyon-cli，现在改为不装并说清原因。
+- **npmmirror 显式同步真的会发出去了**：发版流水线里那一步此前用的是 `wget --method=PUT`，而镜像内是 BusyBox 的 wget、不认这个选项（v2.6.91 日志逐字为 `wget: unrecognized option: method=PUT`），失败又被 `|| true` 咽掉——「显式同步」看起来一直在做、实际一次都没做成，镜像站只能靠自己的机制慢慢追。现改用 node 发 PUT 并拆成独立 job，失败会显示为流水线 warning 而不是埋在日志里。
+
+### Added
+
+- **装完之后会告诉你 `bohr` 是不是刚装的那个**：`npm install -g` 结束时，若 PATH 上解析到的 `bohr` 不是本次安装的那一个（已知两个来源：早期版本留在 `~/.bohrium` 的可执行文件，以及 `scripts/install.sh` 装在 `~/.bohr/bin` 的那一个，两者都会把自己的目录前置进 PATH），会打印一段提示，并按**实际挡路的那个路径**给出改名命令。判不准时保持沉默：Windows 上不判（npm 生成的是 `.cmd` 垫片，比对必然不等）、PATH 上没有 `bohr` 时不判。它不改变安装的退出码。
+- **npm 包 README 补了「升级后 `bohr version` 还是旧版本号」的排障步骤**：含两个来源的对照表，以及一条容易踩的——改名旧二进制之后必须 `hash -r`（bash）或 `rehash`（zsh），否则下一条命令会报 `No such file or directory` 指着刚改名的文件。
+
+### Changed
+
+- **拒绝 https→http 的降级跳转**：清单与哈希旁挂文件是整条校验链的信任根，被降级到明文等于校验一起失效。
+- **伴生工具的复用判定只看哈希**：不再先跑一次 `<tool> version`——那等于在校验之前执行一个还没验证的文件；发布方没给版本号时现在也能复用。
+- **`--space` 的弃用告警改写**：直接给出改法（`--space personal` 加 `<path>` 写成 `personal/<path>`），不再只说「将来会移除」。
+
 ## [2.6.91] - 2026-09-09
 
 ### Added

package/README.md

@@ -99,6 +99,58 @@ npm install -g @dptech-corp/bohr-cli@latest
 npm install -g @dptech-corp/bohr-cli@latest --registry https://registry.npmjs.org
 ```
 
+### 升级后 `bohr version` 显示的还是旧版本号
+
+多半是早先的安装留下了一个可执行文件，并把它所在的目录前置进了 PATH。这种情况下 npm 装的新版拿不到控制权，敲 `bohr` 跑起来的仍然是旧的那个。`npm install -g` 现在会在装完时直接提示这件事，并且会把**实际挡路的那个路径**打出来。
+
+已知有两个来源，处置只差在第 3 步动哪个文件：
+
+| 来源 | 留下的可执行文件 | 写进 PATH 的位置 |
+|-|-|-|
+| 早期版本 | `~/.bohrium/bohr` | rc 文件里的 `~/.bohrium` |
+| `scripts/install.sh` | `~/.bohr/bin/bohr` | rc 文件里的 `export PATH="$HOME/.bohr/bin:$PATH"` |
+
+手动确认与处理如下。
+
+1. 看清实际命中的是哪一个、它是什么版本：
+
+   ```bash
+   command -v bohr
+   type -a bohr        # 按优先级列出 PATH 上全部同名可执行文件
+   bohr version
+   ```
+
+2. 找出把那个目录前置进 PATH 的那几行：
+
+   ```bash
+   grep -nE '\.bohrium|\.bohr/bin' ~/.zshrc ~/.bash_profile ~/.bashrc ~/.profile 2>/dev/null
+   ```
+
+3. 把第 1 步里 `command -v bohr` 报出来的**那个文件**改名——不是照抄下面的路径，是改你自己那一个：
+
+   ```bash
+   mv "$(command -v bohr)" "$(command -v bohr)-legacy"
+   ```
+
+   如果它在 `~/.bohrium` 里，**不要删掉 `~/.bohrium` 整个目录**——登录凭据还存在那里，新版是从它迁移过来的。`~/.bohr/bin` 里没有凭据，只有那个可执行文件。
+
+4. 刷新 shell 的命令缓存，或者直接新开一个终端：
+
+   ```bash
+   hash -r     # bash
+   rehash      # zsh
+   ```
+
+   **这一步不能省。** bash 会记住上一次解析到的路径；改完名不刷新，下一条 `bohr` 命令会报
+   `bash: /Users/you/.bohrium/bohr: No such file or directory`（或 `~/.bohr/bin` 里的那一个）——指着你刚刚改名的那个文件，
+   看上去像是把环境弄坏了。
+
+5. 复核：
+
+   ```bash
+   command -v bohr && bohr version
+   ```
+
 ## License
 
 MIT © DP Technology

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dptech-corp/bohr-cli",
-  "version": "2.6.91",
+  "version": "2.6.92",
   "description": "CLI tool for Bohrium scientific computing platform",
   "bin": {
     "bohr": "run.js"
@@ -32,11 +32,11 @@
     "CHANGELOG.md"
   ],
   "optionalDependencies": {
-    "@dptech-corp/bohr-cli-darwin-arm64": "2.6.91",
-    "@dptech-corp/bohr-cli-darwin-amd64": "2.6.91",
-    "@dptech-corp/bohr-cli-linux-amd64": "2.6.91",
-    "@dptech-corp/bohr-cli-linux-arm64": "2.6.91",
-    "@dptech-corp/bohr-cli-windows-amd64": "2.6.91",
-    "@dptech-corp/bohr-cli-windows-arm64": "2.6.91"
+    "@dptech-corp/bohr-cli-darwin-arm64": "2.6.92",
+    "@dptech-corp/bohr-cli-darwin-amd64": "2.6.92",
+    "@dptech-corp/bohr-cli-linux-amd64": "2.6.92",
+    "@dptech-corp/bohr-cli-linux-arm64": "2.6.92",
+    "@dptech-corp/bohr-cli-windows-amd64": "2.6.92",
+    "@dptech-corp/bohr-cli-windows-arm64": "2.6.92"
   }
 }

package/postinstall.js

@@ -93,62 +93,309 @@ function getPlatform() {
   return `${mp}-${ma}`;
 }
 
-function get(url) {
-  return new Promise((resolve, reject) => {
-    const mod = url.startsWith("https") ? https : http;
-    mod.get(url, { headers: { "User-Agent": "bohr-cli-postinstall" } }, (res) => {
-      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
-        return resolve(get(res.headers.location));
-      }
-      if (res.statusCode !== 200) {
-        res.resume();
-        return reject(new Error(`HTTP ${res.statusCode} from ${url}`));
-      }
-      const chunks = [];
-      res.on("data", (c) => chunks.push(c));
-      res.on("end", () => resolve(Buffer.concat(chunks)));
-      res.on("error", reject);
-    }).on("error", reject);
-  });
+// 重定向处理是这个文件里踩过三次的地方，三条都以「`npm install -g` 崩掉或者卡死」收场，
+// 而本文件开头写着 postinstall 失败必须是非致命的。三条都实测复现过（2026-09-09）：
+//
+//   跳数没有上限        服务端把 302 指回自己 → 6 秒跳了 148037 次，不会自己停
+//   跨协议跳转          downloadToFile 的 follow() 闭包捕获的是**第一个 URL 的** mod，
+//                      http.get("https://…") 同步抛 ERR_INVALID_PROTOCOL，抛在响应回调里、
+//                      不进 promise → 未捕获异常，退出码 1
+//   写盘失败            WriteStream 的 'error' 没人听 → 未捕获异常，退出码 1
+//
+// 前两条 get() 与 downloadToFile() 表现还不一样：get() 每跳重算 mod，所以同一次安装里
+// 「取哈希」那步能过、「取二进制」那步崩。两条下载路径对同一件事给出不同答案，本身就是
+// 缺陷——所以下面把跳转决策收敛成一个 nextRedirectURL()，两边共用。
+const MAX_REDIRECTS = 10;
+const GET_TIMEOUT_MS = 30000;
+
+function requestModule(url) {
+  return url.startsWith("https:") ? https : http;
 }
 
-function downloadToFile(url, dest, timeoutMs = 300000) {
+function isRedirect(res) {
+  return res.statusCode >= 300 && res.statusCode < 400 && res.headers.location;
+}
+
+// 一跳的全部决策：解析（Location 允许是相对路径）＋ 拒绝降级。
+//
+// **https → http 的跳转一律拒绝。** 哈希必填之后，二进制那条路即使被降级也换不掉内容
+// ——换了就对不上哈希。但清单与 sha256 旁挂文件走的是同一套跳转，它们**就是信任的根**，
+// 没有任何东西再去校验它们；把它们降级到明文，等于让中间人同时给出「期望哈希」和
+// 「匹配那个哈希的负载」，整条校验链一起失效。反向的 http → https 是升级，放行。
+function nextRedirectURL(currentURL, location) {
+  const next = new URL(location, currentURL);
+  if (currentURL.startsWith("https:") && next.protocol !== "https:") {
+    throw new Error(`refusing to follow redirect from https to ${next.protocol}// (${next.host})`);
+  }
+  return next.toString();
+}
+
+function get(url, options) {
+  const opts = options || {};
+  const redirectsLeft = opts.redirectsLeft === undefined ? MAX_REDIRECTS : opts.redirectsLeft;
+  const timeoutMs = opts.timeoutMs === undefined ? GET_TIMEOUT_MS : opts.timeoutMs;
   return new Promise((resolve, reject) => {
-    const mod = url.startsWith("https") ? https : http;
-    const follow = (u) => {
-      const req = mod.get(u, { headers: { "User-Agent": "bohr-cli-postinstall" }, timeout: timeoutMs }, (res) => {
-        if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+    const req = requestModule(url).get(
+      url,
+      { headers: { "User-Agent": "bohr-cli-postinstall" }, timeout: timeoutMs },
+      (res) => {
+        if (isRedirect(res)) {
           res.resume();
-          return follow(res.headers.location);
+          if (redirectsLeft <= 0) {
+            return reject(new Error(`too many redirects (>${MAX_REDIRECTS}) starting at ${url}`));
+          }
+          let next;
+          try {
+            next = nextRedirectURL(url, res.headers.location);
+          } catch (e) {
+            return reject(e);
+          }
+          return resolve(get(next, { redirectsLeft: redirectsLeft - 1, timeoutMs }));
         }
         if (res.statusCode !== 200) {
           res.resume();
-          return reject(new Error(`HTTP ${res.statusCode}`));
+          return reject(new Error(`HTTP ${res.statusCode} from ${url}`));
         }
-        const file = fs.createWriteStream(dest);
-        const hash = crypto.createHash("sha256");
-        res.on("data", (chunk) => {
-          file.write(chunk);
-          hash.update(chunk);
-        });
-        res.on("end", () => {
-          file.end(() => resolve(hash.digest("hex")));
-        });
-        res.on("error", (e) => { file.close(); reject(e); });
+        const chunks = [];
+        res.on("data", (c) => chunks.push(c));
+        res.on("end", () => resolve(Buffer.concat(chunks)));
+        res.on("error", reject);
+      }
+    );
+    req.on("error", reject);
+    // 原先 get() 完全没有超时：服务端接了连接不回话，postinstall 就一直等下去。
+    //
+    // 文案写「配置的上限是多少」，不写「实际等了多久」——'timeout' 事件不告诉你是哪一个
+    // 超时开的枪。不设这个选项时 Node 自己也会在 5 秒上触发同一个 handler，写成
+    // 「after 200ms」就是在谎报一个没量过的数（实测：不设选项时 5003ms 才回，文案照样
+    // 说 200ms）。
+    req.on("timeout", () => {
+      req.destroy();
+      reject(new Error(`request to ${url} timed out (limit ${timeoutMs}ms)`));
+    });
+  });
+}
+
+function downloadToFile(url, dest, timeoutMs = 300000) {
+  return new Promise((resolve, reject) => {
+    // 下面几路（请求出错、超时、写盘出错、正常结束）都可能先后到达，只认第一个。
+    let settled = false;
+    const fail = (e) => {
+      if (settled) return;
+      settled = true;
+      reject(e);
+    };
+    const done = (value) => {
+      if (settled) return;
+      settled = true;
+      resolve(value);
+    };
+
+    const follow = (u, redirectsLeft) => {
+      // mod 每跳重算。原先它是在函数外按第一个 URL 算一次的闭包变量。
+      const req = requestModule(u).get(
+        u,
+        { headers: { "User-Agent": "bohr-cli-postinstall" }, timeout: timeoutMs },
+        (res) => {
+          if (isRedirect(res)) {
+            res.resume();
+            if (redirectsLeft <= 0) {
+              return fail(new Error(`too many redirects (>${MAX_REDIRECTS}) starting at ${url}`));
+            }
+            let next;
+            try {
+              next = nextRedirectURL(u, res.headers.location);
+            } catch (e) {
+              return fail(e);
+            }
+            return follow(next, redirectsLeft - 1);
+          }
+          if (res.statusCode !== 200) {
+            res.resume();
+            return fail(new Error(`HTTP ${res.statusCode}`));
+          }
+          const file = fs.createWriteStream(dest);
+          // 这里原先顺手把网络流的 sha256 也算了、并把它当作校验依据返回。现在校验改成
+          // 读落盘的文件（见 installManagedTool），这一份就没有用处了——留着只会让人以为
+          // 「下载函数已经验过了」。下载就只管下载。
+          //
+          // 磁盘满、EIO、这个名字已经被别的东西占住——原先都没人接，Node 于是把
+          // WriteStream 的 'error' 变成未捕获异常，整个 postinstall 以退出码 1 结束。
+          file.on("error", (e) => {
+            res.destroy();
+            fail(e);
+          });
+          res.on("error", (e) => {
+            file.destroy();
+            fail(e);
+          });
+          res.on("data", (chunk) => file.write(chunk));
+          res.on("end", () => {
+            // end 的回调带 error 参数：写盘失败时它先于（或代替）'error' 事件到达。
+            // 忽略它的后果实测过：EISDIR 之下照样报 installed，那个目录被 rename 成了
+            // 目标路径。
+            file.end((err) => {
+              if (err) return fail(err);
+              done();
+            });
+          });
+        }
+      );
+      req.on("error", fail);
+      req.on("timeout", () => {
+        req.destroy();
+        fail(new Error("download timed out"));
       });
-      req.on("error", reject);
-      req.on("timeout", () => { req.destroy(); reject(new Error("download timed out")); });
     };
-    follow(url);
+    follow(url, MAX_REDIRECTS);
   });
 }
 
-// installTrisol downloads the trisol external edition (variant=bohrium) via
-// the trisol manifest protocol: fetch manifest → pick channel → download
-// binary + sha256 sidecar → verify → install to ~/.bohr/tools/trisol/current.
-async function installTrisol() {
+// 「按发布方给的哈希装一个受管伴生 CLI」的完整流程，trisol 与 wenyon 共用一份。
+//
+// 抽出来之前这段算法在本文件里抄了两遍，而且已经漂开了——复用判据与校验判据各写各的：
+//
+//   复用   trisol: out.includes(version) && localHash === expectedHash
+//          wenyon: out.includes(meta.version) && (!meta.sha256 || localHash === meta.sha256)
+//   校验   trisol: if (expectedHash && actualHash !== expectedHash)
+//          wenyon: if (meta.sha256 && actualHash !== meta.sha256)
+//
+// 两处写法不同，说的是同一件事：**哈希缺席就放行**。这条从今天起不成立了。
+//
+// 哈希是必填的，拿不到就不装。原先那个写法是可以走通的：sha256 端点回一个空的 200，
+// `"".trim().split(/\s+/)[0]` 得到空串，`if (expectedHash && …)` 于是整条校验被跳过，
+// 然后照样 chmod 755 装上去——而那一行日志跟校验通过的那次一字不差。这不是读码推出来的，
+// 是拿真实 postinstall.js 对着本地 http 服务跑出来的（负对照：哈希不符时会正确拦下）。
+//
+// 代价认下来：发布方哪天不给哈希了，伴生 CLI 就装不上。postinstall 失败本来就是非致命的
+// （bohr-cli 不依赖它们，`bohr extension install <tool>` 可以重试），而静默装一个没校验过的
+// 可执行文件，代价没有上限。
+//
+// 形状也要判，不只是判空：一页 HTML 错误正文、一句 "Not Found"、一个被截断的哈希，都不是
+// 哈希，判空只挡得住其中一种。
+const SHA256_HEX = /^[0-9a-f]{64}$/i;
+
+// 拒绝的时候要说清「发布方给的到底是什么」，否则这行日志跟网络故障分不开。截断是必要的：
+// 这个位置最可能拿到的就是一整页 HTML。
+function describeHash(raw) {
+  const text = String(raw == null ? "" : raw).trim();
+  if (!text) return "empty response";
+  return text.length > 32 ? `${JSON.stringify(text.slice(0, 32))}…` : JSON.stringify(text);
+}
+
+// 返回值说明这一趟走了哪条路。「装上了」「复用了」「拒了」在副作用上要费劲才分得开，
+// 在返回值上一目了然——测试断言的是这个，不是日志文案。
+// notify 是「这条话必须让用户看见」的出口，默认走 emitToUser（写 /dev/tty）。
+//
+// npm **默认把生命周期脚本的 stdout/stderr 整个收走**，只在脚本非零退出时才回放——而
+// postinstall 的失败是刻意做成非致命的，于是 console.error 打出来的原因一个字都到不了
+// 用户眼前。实测（npm 10.9.4，同一个 postinstall）：`npm install` 一行都不显示，
+// 加 --foreground-scripts 才显示。
+//
+// 也就是说，「拿不到哈希就出声拒绝」这件事里的**出声**，此前是不成立的。文件末尾的影子
+// 告警早就绕开了这层收集，安装这条路当时没跟上。
+//
+// 日常噪音（Installing… / already installed）不走 notify：它们没有「用户需要据此做点
+// 什么」的性质，往终端插话只是干扰。判据就是这一条——**这句话是否要求用户做点什么**。
+//
+// 可注入只为一件事：emitToUser 在有 tty 时写终端、没有时退回 stderr，两条路在用例里都
+// 断言不到；notify 收敛成参数之后，用例拿一个收集器就能判「哪几句进了这个出口」。
+async function installManagedTool({
+  name,
+  label,
+  root,
+  installDir,
+  executable,
+  version,
+  url,
+  expectedHash,
+  detail,
+  notify = emitToUser,
+}) {
+  const wanted = String(expectedHash == null ? "" : expectedHash).trim().toLowerCase();
+  if (!SHA256_HEX.test(wanted)) {
+    notify(
+      `[postinstall] ${label}: publisher gave no usable SHA256 (${describeHash(expectedHash)}), refusing to install`
+    );
+    return "rejected-hash";
+  }
+
+  const destPath = path.join(installDir, executable);
+
+  // 已装的那个，**只按哈希判**。哈希取自发布方，不取自本地文件——本地文件不能自证。
+  // 顺带把老版本 postinstall 漏写的 manifest 补上。
+  //
+  // 这里原先还先跑一次 `<tool> version` 比对版本号。哈希改成必填之后那一步就是冗余的：
+  // localHash === wanted 已经意味着这个文件逐字就是发布方那一版的产物，版本号不可能不对
+  // （expectedHash 本来就是按 version + 平台取的）。而它的代价是**在校验之前先执行了这个
+  // 文件**——本仓「已装的内容不是发布方那一份」那条用例跑的时候，被改过的文件真的被执行过
+  // 一次，然后才因为哈希不符被拒。
+  //
+  // 去掉它还顺带解开一个约束：原先复用要求 version 非空，而 wenyon 的 meta.version 可能缺，
+  // 于是那种情况下每次安装都要重下一遍。
+  if (fs.existsSync(destPath)) {
+    try {
+      const localHash = (await hashFile(destPath)).toLowerCase();
+      if (localHash === wanted) {
+        writeManagedManifest(root, {
+          name,
+          version,
+          executable,
+          sha256: localHash,
+          pinnedHash: readPinnedHash(root),
+        });
+        console.log(`[postinstall] ${label} ${version || ""} already installed`);
+        return "reused";
+      }
+    } catch (_) {
+      // 读不出哈希（文件损坏、权限不够）只意味着「没装好」，往下重装
+    }
+  }
+
+  console.log(`[postinstall] Installing ${label} ${version || ""} (${detail})...`);
+  // 临时文件名带上进程号与随机数。原先是固定的 `<dest>.tmp`，两个并发的 postinstall
+  // （两个终端各跑一次 npm install -g，或者 monorepo 同时装）抢同一个名字：实测一个
+  // installed、另一个报 `download failed (ENOENT … chmod trisol.tmp)`——一个装得好好的
+  // 工具被报成失败，而那句错误里没有一个字提到并发。
+  //
+  // 同一个文件里的 writeManagedManifest 早就用了 `${manifestPath}.${process.pid}.tmp`，
+  // 这个教训学过一次，二进制这条路当时没跟上。
+  const tmpPath = `${destPath}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`;
+  try {
+    // mkdir 放在 try 里面。它原先在外面，于是安装目录建不出来时（父路径是个文件、
+    // 权限不够）异常直接抛出这个函数——调用方拿到的是一个 rejected promise，而不是
+    // 跟其他失败一样的一个状态字符串。
+    fs.mkdirSync(installDir, { recursive: true });
+    await downloadToFile(url, tmpPath);
+    // 哈希算的是**落到盘上的那个文件**，不是收到的网络流。两者在正常情况下相同，但
+    // 「校验通过」这句话的意思应该是「待会儿要 chmod +x 并搬到 PATH 上的那个东西是对的」
+    // ——那就得读它。算网络流的话，任何在流与盘之间发生的事（并发写、部分写、坏块）都
+    // 恰好落在校验的视野之外。多读一遍 11–14 MB，相对一次下载可以忽略。
+    const actualHash = (await hashFile(tmpPath)).toLowerCase();
+    if (actualHash !== wanted) {
+      fs.unlinkSync(tmpPath);
+      notify(
+        `[postinstall] ${label}: SHA256 mismatch (expected ${wanted}, got ${actualHash}), skipping`
+      );
+      return "mismatch";
+    }
+    fs.chmodSync(tmpPath, 0o755);
+    fs.renameSync(tmpPath, destPath);
+    writeManagedManifest(root, { name, version, executable, sha256: actualHash });
+    console.log(`[postinstall] ${label} ${version || ""} installed to ${destPath}`);
+    return "installed";
+  } catch (e) {
+    try { fs.unlinkSync(tmpPath); } catch (_) {}
+    notify(`[postinstall] ${label}: download failed (${e.message}), skipping`);
+    return "failed";
+  }
+}
+
+// installTrisol 走 trisol 的清单协议：取清单 → 选通道 → 取二进制与 sha256 旁挂文件 →
+// 交给 installManagedTool 校验并装到 ~/.bohr/tools/trisol/current。
+async function installTrisol({ notify = emitToUser } = {}) {
   const platform = getPlatform();
-  if (!platform) return;
+  if (!platform) return "unsupported-platform";
   const [osName, archName] = platform.split("-");
 
   let manifest;
@@ -156,162 +403,277 @@ async function installTrisol() {
     const buf = await get(`${TRISOL_SERVER}/api/v1/cli/manifest`);
     manifest = JSON.parse(buf.toString());
   } catch (e) {
-    console.error(`[postinstall] trisol: could not fetch manifest (${e.message}), skipping`);
-    return;
+    notify(`[postinstall] trisol: could not fetch manifest (${e.message}), skipping`);
+    return "no-manifest";
+  }
+
+  // 清单自己就写着服务端出哪些平台的包。不看它的后果实测过（2026-09-09）：清单里
+  // platforms 不含 windows/arm64，而 bohr-cli 自己是发 windows-arm64 的；那台机器上
+  // 两个下载 URL 都回 HTTP 400，于是用户看到的是「could not fetch sha256 (HTTP 400)」
+  // ——读起来像服务端坏了，而实际是这个平台根本没有包。判断依据在清单里现成的。
+  //
+  // 老服务端不带 platforms 时 supported 为空，此时不判——用一个查不到的事实去拒绝安装，
+  // 比不判更糟。
+  const supported = (manifest.download && manifest.download.platforms) || [];
+  if (supported.length && !supported.includes(`${osName}/${archName}`)) {
+    notify(
+      `[postinstall] trisol: no build for ${osName}/${archName} (server offers ${supported.join(", ")}), skipping`
+    );
+    return "platform-not-offered";
   }
+
   const channel = process.env.BOHR_TRISOL_CHANNEL || manifest.default_channel || "stable";
   const ch = (manifest.channels || {})[channel];
   const version = ch && ch.version;
   if (!version) {
-    console.error(`[postinstall] trisol: channel "${channel}" has no version, skipping`);
-    return;
+    notify(`[postinstall] trisol: channel "${channel}" has no version, skipping`);
+    return "no-version";
   }
 
   const base = `${TRISOL_SERVER}/api/v1/cli/download/${version}/${osName}/${archName}`;
-  const binaryURL = `${base}?variant=bohrium`;
-  const shaURL = `${base}.sha256?variant=bohrium`;
   const ext = osName === "windows" ? ".exe" : "";
-  const destPath = path.join(TRISOL_INSTALL_DIR, `trisol${ext}`);
 
   let expectedHash;
   try {
-    const buf = await get(shaURL);
+    const buf = await get(`${base}.sha256?variant=bohrium`);
     expectedHash = buf.toString().trim().split(/\s+/)[0];
   } catch (e) {
-    console.error(`[postinstall] trisol: could not fetch sha256 (${e.message}), skipping`);
-    return;
-  }
-
-  // Retain an existing binary only when both its reported version and its
-  // publisher-provided hash match. This also repairs metadata omitted by older
-  // postinstall versions without treating the local file as its own authority.
-  if (fs.existsSync(destPath)) {
-    try {
-      const { execFileSync } = require("child_process");
-      const out = execFileSync(destPath, ["version"], { encoding: "utf8", timeout: 5000 });
-      const localHash = await hashFile(destPath);
-      if (out.includes(version) && localHash === expectedHash) {
-        writeManagedManifest(TRISOL_ROOT, {
-          name: "trisol",
-          version,
-          executable: `trisol${ext}`,
-          sha256: localHash,
-          pinnedHash: readPinnedHash(TRISOL_ROOT),
-        });
-        console.log(`[postinstall] trisol ${version} already installed`);
-        return;
-      }
-    } catch (_) {
-      // version/hash check failed, proceed with install
-    }
+    notify(`[postinstall] trisol: could not fetch sha256 (${e.message}), skipping`);
+    return "no-hash";
   }
 
-  console.log(`[postinstall] Installing trisol ${version} (${platform}, variant=bohrium)...`);
-  fs.mkdirSync(TRISOL_INSTALL_DIR, { recursive: true });
-  const tmpPath = destPath + ".tmp";
-  try {
-    const actualHash = await downloadToFile(binaryURL, tmpPath);
-    if (expectedHash && actualHash !== expectedHash) {
-      fs.unlinkSync(tmpPath);
-      console.error(`[postinstall] trisol: SHA256 mismatch (expected ${expectedHash}, got ${actualHash}), skipping`);
-      return;
-    }
-    fs.chmodSync(tmpPath, 0o755);
-    fs.renameSync(tmpPath, destPath);
-    writeManagedManifest(TRISOL_ROOT, {
-      name: "trisol",
-      version,
-      executable: `trisol${ext}`,
-      sha256: actualHash,
-    });
-    console.log(`[postinstall] trisol ${version} installed to ${destPath}`);
-  } catch (e) {
-    try { fs.unlinkSync(tmpPath); } catch (_) {}
-    console.error(`[postinstall] trisol: download failed (${e.message}), skipping`);
-  }
+  return installManagedTool({
+    name: "trisol",
+    label: "trisol",
+    root: TRISOL_ROOT,
+    installDir: TRISOL_INSTALL_DIR,
+    executable: `trisol${ext}`,
+    version,
+    url: `${base}?variant=bohrium`,
+    expectedHash,
+    detail: `${platform}, variant=bohrium`,
+    notify,
+  });
 }
 
-async function main() {
-  const platform = getPlatform();
-  if (platform) {
-    await installTrisol();
+// platform 可注入只为一件事：下面那条「平台不认识就整个不做」的分支，在任何一台跑得起
+// 这份测试的机器上都走不到（darwin/linux + amd64/arm64 全都认得），没有注入口就只能靠
+// 肉眼。本文件里 emitToUser 的 ttyPath、detectShadowedBohr 的 opts 已经是这个办法。
+async function main({ platform = getPlatform(), notify = emitToUser } = {}) {
+  // 原先这里只是「不装 trisol」，然后照样带着 platform=null 去问 wenyon 的发布接口——
+  // 一个必然问不出东西的请求，而且报出来的错长得像服务端故障。
+  if (!platform) {
+    notify(
+      `[postinstall] unsupported platform ${os.platform()}-${os.arch()}, skipping companion tools`
+    );
+    return "unsupported-platform";
   }
 
-  const metaUrl = `${WENYON_SERVER}/cli/releases/latest/download?platform=${platform}&variant=external`;
+  await installTrisol({ notify });
 
   let meta;
   try {
-    const buf = await get(metaUrl);
+    const buf = await get(
+      `${WENYON_SERVER}/cli/releases/latest/download?platform=${platform}&variant=external`
+    );
     meta = JSON.parse(buf.toString());
   } catch (e) {
-    console.error(`[postinstall] wenyon-cli: could not fetch release info (${e.message}), skipping`);
-    return;
+    notify(`[postinstall] wenyon-cli: could not fetch release info (${e.message}), skipping`);
+    return "no-release-info";
   }
 
   if (!meta.url) {
-    console.error("[postinstall] wenyon-cli: no download URL in release response, skipping");
-    return;
+    notify("[postinstall] wenyon-cli: no download URL in release response, skipping");
+    return "no-download-url";
   }
 
-  // Check if already installed and up-to-date
   const ext = platform.startsWith("windows") ? ".exe" : "";
-  const destPath = path.join(INSTALL_DIR, `wenyon-cli${ext}`);
+  return installManagedTool({
+    name: "wenyon",
+    label: "wenyon-cli",
+    root: WENYON_ROOT,
+    installDir: INSTALL_DIR,
+    executable: `wenyon-cli${ext}`,
+    version: meta.version,
+    url: meta.url,
+    expectedHash: meta.sha256,
+    detail: platform,
+    notify,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// 装完之后，PATH 上的 `bohr` 是不是刚装的这一个。
+//
+// 这个检查只能长在 postinstall 里。被旧二进制遮蔽时，新 CLI 里写什么检查都不会执行
+// ——用户敲 bohr 跑起来的是旧的那个。npm 的生命周期脚本是安装那一刻唯一还能说话的地方。
+//
+// 实测过两台机器上的形态（登记行 recvqLGpdH3RXI）：早期版本装在 ~/.bohrium 并把该目录
+// 前置进 PATH，之后 npm 装的新版永远拿不到控制权。官网安装页已经在教人装完跑
+// `bohr version`，但从没说过"你应该看到刚装的那个版本号"，于是看到 1.1.0 的人不知道那是错的。
+function realpathOrNull(p) {
+  try {
+    return fs.realpathSync(p);
+  } catch (_) {
+    return null;
+  }
+}
 
-  if (fs.existsSync(destPath) && meta.version) {
+// PATH 上第一个可执行的同名文件，就是 shell 会挑中的那个。
+function resolveOnPath(name, env) {
+  const raw = (env && env.PATH) || "";
+  if (!raw) return null;
+  for (const dir of raw.split(path.delimiter)) {
+    if (!dir) continue;
+    const candidate = path.join(dir, name);
     try {
-      const { execFileSync } = require("child_process");
-      const out = execFileSync(destPath, ["version"], { encoding: "utf8", timeout: 5000 });
-      const localHash = await hashFile(destPath);
-      if (out.includes(meta.version) && (!meta.sha256 || localHash === meta.sha256)) {
-        writeManagedManifest(WENYON_ROOT, {
-          name: "wenyon",
-          version: meta.version,
-          executable: `wenyon-cli${ext}`,
-          sha256: localHash,
-          pinnedHash: readPinnedHash(WENYON_ROOT),
-        });
-        console.log(`[postinstall] wenyon-cli ${meta.version} already installed`);
-        return;
-      }
+      if (!fs.statSync(candidate).isFile()) continue;
+      fs.accessSync(candidate, fs.constants.X_OK);
+      return candidate;
     } catch (_) {
-      // version check failed, proceed with install
+      // 不可读/不可执行/不存在都只意味着继续往后找，不是错误
     }
   }
+  return null;
+}
 
-  console.log(`[postinstall] Installing wenyon-cli ${meta.version || ""} (${platform})...`);
+// 判不出来就返回 null（沉默），只有**确定**不是我们才报。
+// 全局安装目录的形态在 nvm / pnpm / Volta 下差别很大，误报一次的代价比漏报大得多：
+// 它会让每个装得好好的人都看见一段"你装错了"，几轮之后就没人读这段字了。
+function detectShadowedBohr(opts) {
+  const o = opts || {};
+  const platform = o.platform || process.platform;
+  // Windows 上 npm 生成的是 bohr.cmd / bohr.ps1 垫片，不是指向 run.js 的符号链接，
+  // realpath 解出来必然不等于 run.js —— 判据在这个平台上会 100% 误报，所以不判。
+  if (platform === "win32") return null;
 
-  fs.mkdirSync(INSTALL_DIR, { recursive: true });
+  const env = o.env || process.env;
+  const packageRoot = o.packageRoot || __dirname;
 
-  const tmpPath = destPath + ".tmp";
-  try {
-    const actualHash = await downloadToFile(meta.url, tmpPath);
+  const ours = realpathOrNull(path.join(packageRoot, "run.js"));
+  if (!ours) return null;
 
-    if (meta.sha256 && actualHash !== meta.sha256) {
-      fs.unlinkSync(tmpPath);
-      console.error(`[postinstall] wenyon-cli: SHA256 mismatch (expected ${meta.sha256}, got ${actualHash}), skipping`);
-      return;
-    }
+  const found = resolveOnPath("bohr", env);
+  // PATH 上还没有 bohr：可能 bin 还没链好，也可能 npm 全局目录不在 PATH。
+  // 后者官网安装页已经讲了，这里不重复说。
+  if (!found) return null;
 
-    fs.chmodSync(tmpPath, 0o755);
-    fs.renameSync(tmpPath, destPath);
-    writeManagedManifest(WENYON_ROOT, {
-      name: "wenyon",
-      version: meta.version,
-      executable: `wenyon-cli${ext}`,
-      sha256: actualHash,
-    });
-    console.log(`[postinstall] wenyon-cli ${meta.version || ""} installed to ${destPath}`);
-  } catch (e) {
-    try { fs.unlinkSync(tmpPath); } catch (_) {}
-    console.error(`[postinstall] wenyon-cli: download failed (${e.message}), skipping`);
+  const foundReal = realpathOrNull(found);
+  if (!foundReal) return null;
+  if (foundReal === ours) return null;
+
+  return { found, foundReal, ours };
+}
+
+// 遮蔽源已知有两个，都是本仓自己造出来的：
+//
+//   ~/.bohrium/bohr        早期版本的安装位置（登记行 recvqLGpdH3RXI 实测两台机器）
+//   ~/.bohr/bin/bohr       scripts/install.sh 装的位置，它还往 rc 文件写
+//                          `export PATH="$HOME/.bohr/bin:$PATH"`——前置，所以必赢
+//
+// 所以补救命令**必须从实际挡路的那个路径生成**，不能写死其中一个。写死 ~/.bohrium 的
+// 后果不是少说了一句：被 ~/.bohr/bin 挡住的人照着敲会得到 "No such file or directory"，
+// 而上面三行刚刚把真实路径打给他看过——话术自相矛盾比不给话术更糟。
+//
+// 要改名的是 **PATH 上那一个**（found），不是它指向的目标（foundReal）：found 是符号
+// 链接时，改名目标会留下一条断链，而 PATH 解析仍然命中那个链接名。
+function shadowRemedyLines(detected, homeDir) {
+  const home = homeDir || os.homedir();
+  const legacyRoot = path.join(home, ".bohrium");
+  const underLegacyRoot = (p) =>
+    typeof p === "string" && (p === legacyRoot || p.startsWith(legacyRoot + path.sep));
+
+  const lines = [`[postinstall]        mv ${detected.found} ${detected.found}-legacy`];
+  // 「别删 ~/.bohrium」这句只在真的动到 ~/.bohrium 时才说。凭据在那儿，别处没有；
+  // 对着一个 ~/.bohr/bin 的遮蔽讲 ~/.bohrium 的凭据，只会让人以为自己找错了东西。
+  if (underLegacyRoot(detected.found) || underLegacyRoot(detected.foundReal)) {
+    return [
+      "[postinstall]   2. rename the shadowing executable — do NOT delete ~/.bohrium,",
+      "[postinstall]      your saved credentials still live there and are migrated from it:",
+    ].concat(lines);
+  }
+  return ["[postinstall]   2. rename the shadowing executable:"].concat(lines);
+}
+
+function formatShadowWarning(detected, homeDir) {
+  if (!detected) return null;
+  const lines = [
+    "",
+    "[postinstall] Installed, but `bohr` on your PATH is NOT the one just installed.",
+    `[postinstall]   PATH resolves to: ${detected.found}`,
+  ];
+  if (detected.foundReal !== detected.found) {
+    lines.push(`[postinstall]     which points at: ${detected.foundReal}`);
+  }
+  lines.push(
+    `[postinstall]   just installed:   ${detected.ours}`,
+    "[postinstall] Usually an earlier install left a `bohr` in ~/.bohrium or ~/.bohr/bin",
+    "[postinstall] and put that directory first on PATH.",
+    "[postinstall] To fix:",
+    "[postinstall]   1. see which one wins:  command -v bohr && bohr version"
+  );
+  lines.push.apply(lines, shadowRemedyLines(detected, homeDir));
+  lines.push(
+    "[postinstall]   3. refresh the shell command cache: `hash -r` (bash) or `rehash` (zsh),",
+    "[postinstall]      or just open a new terminal. Without this bash keeps the old path",
+    "[postinstall]      cached and the next `bohr` reports 'No such file or directory'.",
+    "[postinstall]   4. check:  bohr version",
+    ""
+  );
+  return lines.join("\n");
+}
+
+// npm **默认把生命周期脚本的 stdout/stderr 收走**，只在脚本非零退出时才回放——而这条
+// 提示恰恰必须在安装成功那一次出现。实测（npm 10.9.4，`npm install -g`）：不加
+// --foreground-scripts 时 console.error 的内容一个字都不显示，连现有那几行
+// "[postinstall] trisol … installed" 也一样，一直在打给空气。
+//
+// 所以直接写 /dev/tty：它是用户的终端本身，绕过 npm 这层收集。没有 tty 的场合
+// （CI、容器、输出被管道接走）写入会抛，退回 stderr——那些场合本来也没人在看。
+//
+// ttyPath 可注入只为一件事：**回退分支是 CI、容器、输出被管道接走时唯一会走的那条**，
+// 也就是 postinstall 无人值守跑的绝大多数场合。写死 "/dev/tty" 的话这条分支没有任何
+// 办法被测到，只能靠肉眼看一次安装输出。返回值说明走了哪条路，供测试断言。
+function emitToUser(text, ttyPath) {
+  try {
+    fs.writeFileSync(ttyPath || "/dev/tty", text + "\n");
+    return true;
+  } catch (_) {
+    console.error(text);
+    return false;
   }
 }
 
 if (require.main === module) {
-  main().catch((e) => {
-    // postinstall failures must not break npm install
-    console.error(`[postinstall] wenyon-cli: ${e.message}`);
-  });
+  main()
+    .catch((e) => {
+      // postinstall failures must not break npm install。同样走 emitToUser：
+      // 这是逃出 main() 的异常，属于「用户该知道有东西没装上」那一类。
+      emitToUser(`[postinstall] companion tools: ${e.message}`);
+    })
+    .finally(() => {
+      // 这段无论上面成没成都要跑：遮蔽与扩展装没装上无关。
+      // 整个包在 try 里，因为 postinstall 抛异常等于 `npm install -g` 装不上，
+      // 而这个提示的价值远够不上承担那个后果。
+      try {
+        const text = formatShadowWarning(detectShadowedBohr());
+        if (text) emitToUser(text);
+      } catch (_) {
+        /* 提示不出来就算了，绝不影响安装 */
+      }
+    });
 }
 
-module.exports = { readPinnedHash, writeManagedManifest };
+module.exports = {
+  readPinnedHash,
+  writeManagedManifest,
+  installManagedTool,
+  installTrisol,
+  main,
+  get,
+  nextRedirectURL,
+  resolveOnPath,
+  detectShadowedBohr,
+  formatShadowWarning,
+  emitToUser,
+};