dsh-pwsh-plugin 0.2.12 → 0.2.14

package/FINDINGS.md

@@ -559,7 +559,12 @@ full-access 不挂围栏、流分离 + `exit code: 7`、2000 行大输出 ——
 
 ---
 
-## 十九、自动更新：只查、只提示、从不自己装
+## 十九、自动更新：只查、只提示、从不自己装（历史）
+
+> 本节记录的是 0.2.2 时期的形态：发布源是 GitHub 标签、装由人触发。第三十三节之后发布源换成
+> npm registry、自动路径会自己装，但下面的**判决逻辑与失败语义**（失败不抛、保留 stale、查与装分开的
+> 理由、`plugin_manager` 工具与服务的区别）仍然成立。文中出现的 `DSH_PWSH_UPDATE_SOURCE` / `github:` 规格
+> 与 WSLENV 陷阱都属于那一版，现已被 `DSH_PWSH_UPDATE_REGISTRY` 取代。
 
 参考同作者的 `dsh-remote-access-proxy`（v1.4 起有更新检查，1454 行里第 102-107 / 225-233 / 244 / 982 / 1010 行是全部相关代码）。
 本插件照搬了它的**判决逻辑与失败语义**，改掉了两处形态。
@@ -568,9 +573,9 @@ full-access 不挂围栏、流分离 + `exit code: 7`、2000 行大输出 ——
 
 | 设计 | 参考实现 | 本插件 |
 |---|---|---|
-| 标签契约 | `/^v(0\|\d*)\.(0\|\d*)\.(0\|\d*)$/`，预发布永不推送 | 同（`parseReleaseTag`）|
-| 安装规格 | `${source.spec}#${tag}` —— 一个 tag 一个规格，装新版就是盖掉旧的 | 同（`releaseSpec`）|
-| 源可覆盖 | `DSH_RAP_UPDATE_SOURCE`：`owner/repo` → GitHub；`git+<url>` → `git ls-remote` | `DSH_PWSH_UPDATE_SOURCE`，同名规则 |
+| 版本契约 | `/^v(0\|\d*)\.(0\|\d*)\.(0\|\d*)$/`，预发布永不推送 | 同（`parseVersion` / `updateVerdict`）|
+| 安装规格 | `${source.spec}#${tag}` —— 一个 tag 一个规格，装新版就是盖掉旧的 | `dsh-pwsh-plugin@X.Y.Z`（registry 形式，见第三十三节）|
+| 源可覆盖 | `DSH_RAP_UPDATE_SOURCE`：`owner/repo` → GitHub；`git+<url>` → `git ls-remote` | `DSH_PWSH_UPDATE_REGISTRY`，指 registry 基址（第三十三节已从 GitHub 标签改为 npm dist-tags）|
 | 首次延迟 / 周期 | 5s 之后每 12h，timer 都 `.unref?.()` | 同 |
 | 失败不抛 | `state:'failed'` + 保留先前 `latest` + `stale:'available'` | 同，注释原话「一次网络抖动不该让已知的新版本消失」 |
 | **查与装分开** | 页面把钉了 tag 的 spec 交给 DSH 的 `plugin_manager` | 输出末尾挂一行提示；装由 `pwsh_run_update` 显式触发，同样交给 `pluginManager` |
@@ -593,10 +598,10 @@ full-access 不挂围栏、流分离 + `exit code: 7`、2000 行大输出 ——
 
    ```powershell
    $env:DSH_HOME = '<DSH_HOME>'
-   & '<desktop cli>\dsh.cmd' plugin --profile desktop add 'github:<owner>/dsh-pwsh-plugin#v0.2.0'
+   & '<desktop cli>\dsh.cmd' plugin --profile desktop add 'dsh-pwsh-plugin@<version>'
    ```
 
-2. **`pwsh_run_update` 工具**（0.2.2 起）：把钉住 tag 的 spec 交给 `ctx.get('pluginManager')`。
+2. **`pwsh_run_update` 工具**（0.2.2 起）：把钉住版本的 spec 交给 `ctx.get('pluginManager')`。
 
    这里要区分**工具**与**服务**，早前我把两者混为一谈：
    - 工具 `plugin_manager`：`dsh-base/cordis.patch.yml:15-17` 里 `tool-plugin-manager` 是 `disabled: true`，
@@ -1695,4 +1700,125 @@ if [ -f "<path>" ] && [ -O "<path>" ] && chmod +x "<path>" 2>/dev/null && [ -x "
 改成先自己试写一次，写不出去就 `SKIP`。
 
 ### 验收
-十一份脚本在 Windows node 下 **272 项全绿**；bashtest 在 WSL 侧另跑到 `TOTAL pass=20 fail=0`（四项按平台跳过）。
+十一份脚本在 Windows node 下 **305 项全绿**；bashtest 在 WSL 侧另跑到 `TOTAL pass=20 fail=0`（四项按平台跳过）。
+
+---
+
+## 三十三、发布与更新改走 npm registry（2026-10-28）
+
+### 为什么换
+
+原来更新检查读的是 GitHub 的 `GET /repos/<repo>/tags`，安装规格是 `github:owner/repo#vX.Y.Z`。
+包既然已经发在 npm 上（第三十二节之后），读 tag 就成了第二个真相源：同一个版本在两处分别可达，
+而两边谁先谁后没有任何约束。而且 `github:` 规格装的是仓库快照，不经过 pnpm 的供应链策略
+（`minimumReleaseAge`）—— 绕开安全网的路不该是默认路。
+
+现在只有一个真相源：`dist-tags.latest`。
+
+### 检查：读 abbreviated 文档
+
+`GET https://registry.npmjs.org/dsh-pwsh-plugin`，请求头 `accept: application/vnd.npm.install-v1+json`。
+实测这份文档 200 时形状是：
+
+```json
+{ "dist-tags": { "latest": "0.2.12" },
+  "versions": { "0.0.0-stage": {...}, "0.2.12": { "version": "0.2.12", "dist": { "shasum": "1ca2d9f0…" } } } }
+```
+
+三条判决规则：
+
+| 情形 | 判决 |
+|---|---|
+| `dist-tags.latest` 是纯 `X.Y.Z` 且高于当前 | `available` |
+| `dist-tags.latest` 被标了 `deprecated` | `current`，并把被废弃的版本报出来（不推一个官方已劝退的版本）|
+| 没有 `dist-tags` | 从版本清单里挑最高**正式版**（预发布跳过）|
+
+`404` 单独成一条文案：`not published on <registry>`。它不是「没有新版本」——一个是配置或发版出了问题，
+一个是正常工作状态，混在一起会把事故说成安静。
+
+**abbreviated 文档里没有 `time` 字段**（实测 `time keys` 为空），所以检查阶段无法得知发布时间；
+冷却期只能靠 pnpm 自己的策略，见下。
+
+### 安装：回读磁盘，不信返回值
+
+`installBundle` 的返回里**没有 version 字段**（`application` 只有
+`'applied' | 'restart-required' | 'failed' | 'cancelled'`）。装到哪个版本只能从
+`<profileDir>/node_modules/dsh-pwsh-plugin/package.json` 回读。
+
+这不是洁癖。pnpm 的 `minimumReleaseAge` 默认 1440 分钟（1 天，v11 起），今天发布的版本今天解析不到 ——
+于是「请求 0.2.13、装到 0.2.12」是**正常行为**，而 `installRelease` 若拿 `state.latest` 当结果，
+就会把一个没发生的事记成发生了。现在的做法：
+
+- 回读 `installedVersion`；
+- 若它低于请求的版本，输出末尾追加一句 `pnpm installed X rather than Y: its minimumReleaseAge policy
+  withholds versions that are too recent.`；
+- 自动路径把 `lastInstalled` 传进下一轮预检（`cooled`），若「冷却期落地的版本」仍低于 `latest`，
+  把它从 `attempted` 里撤出来并在 1 小时后重试 —— 否则这个进程的生命周期会被钉死在那个旧版本上，
+  而它明明已经装好了。
+
+预检 `checkInstallNeed` 的 `cooling-down` 判据是：
+`cooled < latest && cooled >= (running ?? disk ?? '0.0.0')`。换句话说，只有当**已经装上的东西**比目标旧、
+且不比运行中的更旧时，才值得再发一次安装请求。
+
+### 发布：OIDC trusted publishing
+
+`.github/workflows/release.yml` 在 tag 上跑 `scripts/release-check.mjs`，然后
+`npm publish --provenance`，凭 npm 的 trusted publishing（runner 用 OIDC 换一个只对本仓库 + 本
+workflow 文件有效的令牌）。仓库里不放 `NPM_TOKEN`。
+
+三点是实测/文档里挑出来的硬约束：
+
+1. **workflow 文件名是信任契约的一部分。** 在 npm 的 Trusted publisher 设置里填的是 `release.yml`，
+   改名或搬到子目录，每次发布都会 403，而且报错不会告诉你原因。
+2. **npm 11.5.1 起才支持。** Node 24 自带 11.x，workflow 里仍显式校验这条下限。
+3. **trusted publishing 只授权带 provenance 的发布**，所以 `--provenance` 不是可选项。
+
+为什么不是「发版时手动 `npm publish`」：手动发布需要一个 bypass-2FA 的 granular token，而账号只有
+passkey（WebAuthn）、没有 TOTP 入口 —— 产不出 `--otp` 要的六位码。OIDC 把「谁能发」从「持有一个长期
+令牌的人」换成「这个仓库的这个 workflow」，同时消掉了令牌本身。
+
+#### 实测：OIDC 这条路当时走不通，0.2.13 是用 token 发的
+
+Trusted publisher 要在 npm 的 `/package/<name>/access` 页上绑定，提交表单后 npm 要求二次验证，
+而该账号的 2FA **只有 WebAuthn security key**（Bitwarden passkey），页面上只有一个 `Use security key`
+按钮；没有 TOTP 入口，也就没有可以填进 `--otp` 的六位码。**这一步需要人亲手碰钥匙，自动化在这里
+必须停手。**
+
+所以 0.2.13 走的是已经验证过的老路：从用户环境变量取 `NPM_TOKEN`，写一份临时 `.npmrc`
+（`//registry.npmjs.org/:_authToken=…`），`npm publish --access public`，发完立刻删掉 `.npmrc`。
+结果 `+ dsh-pwsh-plugin@0.2.13`、`http fetch PUT 202`、`exit 0`。**token 没有进对话，也没有留在磁盘。**
+
+顺带一条：`actions/setup-node` 一旦配了 `registry-url`，就会写一行空的
+`_authToken=${NODE_AUTH_TOKEN}`；npm 看到「有但为空」的凭据就不再走 OIDC，服务端把它映射成
+误导性的 `404 Not Found - PUT https://registry.npmjs.org/<pkg>`（provenance 都签成了、sigstore 也记了）。
+`0ae4bf5` 去掉 `registry-url` 并显式删掉这行，就是为了让 OIDC 接手。
+
+#### 实测：发布后头五分钟，tarball 在 CDN 上是 404
+
+`PUT 202` 返回时版本文档和 `dist-tags.latest` 已经是新值，但 tarball 地址
+`/-/dsh-pwsh-plugin-0.2.13.tgz` 仍回 **404**，响应头是 `cache-control: public, max-age=300`、
+`age: 179` —— Cloudflare 边缘缓存着一份「还没发布」时的 404。`pnpm add` 因此报：
+
+```
+[ERR_PNPM_FETCH_404] GET https://registry.npmjs.org/dsh-pwsh-plugin/-/dsh-pwsh-plugin-0.2.13.tgz:
+Not Found - 404
+No authorization header was set for the request.
+```
+
+看起来像权限问题，其实只是缓存。等满 300 秒后同一个 URL 立刻 200，`cache-control` 变成
+`immutable, max-age=31557600`。**没有捷径**：带 `?nocache=` 的地址能绕缓存，但 npm / pnpm 只会去取
+文档里那个裸 URL。实操口径于是写成「发布后等五分钟再装」。
+
+附带一个无害的副作用：安装失败那次已经把 `dsh-pwsh-plugin@0.2.13` 写进了 profile 的
+`pnpm-workspace.yaml` → `minimumReleaseAgeExclude`，重试时直接复用。
+
+### 测试
+
+`test/support.mjs` 里加了 `startRegistry`：用 `node:http` 起一个本机假 registry，记录每次请求的
+`accept` 头，可随时 `set(name, doc)`。**每个响应都带 `connection: close`** —— undici 会为 keep-alive
+空闲连接挂一个解析器超时计时器，而退避测试要压缩全局 `setTimeout`，那个计时器会被提前触发并抛
+`TypeError: Cannot read properties of undefined (reading 'deref') at Timeout.onParserTimeout`。
+让连接短命是唯一不用改被测代码的解法。
+
+`updatetest` 118 项、`autoupdatetest` 46 项、`wiringtest` 24 项全部改走这个假 registry。
+

package/README.md

@@ -45,6 +45,21 @@ It inserts two:
 It does **not** disable the stock `tool-bash`: that row already carries `disabled: !!js process.platform ===
 'win32'`, and a hard `disabled: true` from here would switch the official bash off on Linux too.
 
+**npm registry.** Also published to npm: `npm i dsh-pwsh-plugin`, or let DSH install the registry spec:
+
+```powershell
+& $dsh plugin --profile desktop add 'dsh-pwsh-plugin@<version>'
+```
+
+> pnpm's `minimumReleaseAge` defaults to 1440 minutes, so a version published today is not resolved
+today — pressing update installs the previous release. That is the supply-chain policy, not a failure.
+
+> For the first five minutes after `npm publish` the tarball URL still answers **404** from the CDN
+edge (`cache-control: public, max-age=300`) even though the version document and `dist-tags.latest` are
+already updated. Installing inside that window fails with `ERR_PNPM_FETCH_404 … .tgz: Not Found`, which
+reads like a permissions problem and is not one. Wait the five minutes out; a `?nocache=` query string
+bypasses the cache but neither npm nor pnpm will fetch that URL.
+
 **Sidebar.** Plugins → Add plugin → `https://github.com/citydirector/dsh-pwsh-plugin`, then switch it on.
 
 **CLI.** The `desktop` profile can only be managed by the desktop application's own CLI:
@@ -53,8 +68,8 @@ It does **not** disable the stock `tool-bash`: that row already carries `disable
 $dsh = '<desktop install>\resources\runtime\cli\bin\dsh.cmd'
 $env:DSH_HOME = '<DSH_HOME>'        # the data root the desktop app itself uses
 
-# <tag> is any released tag; the newest one is what the plugin itself would install
-& $dsh plugin --profile desktop add 'github:citydirector/dsh-pwsh-plugin#<tag>'
+# <version> is any published version; the newest one is what the plugin itself would install
+& $dsh plugin --profile desktop add 'dsh-pwsh-plugin@<version>'
 # or, from a local checkout
 & $dsh plugin --profile desktop add 'file:<path to checkout>'
 ```
@@ -65,10 +80,12 @@ back out. Verify with `--dump-config` on a non-reserved profile, where the row s
 
 Two things to know before you choose a spec:
 
-- **`github:` copies, `file:` hard-links.** A `github:` install is a snapshot of the tag — editing the checkout
-  changes nothing until you run `add` again. A `file:` install hard-links the checkout, so edits are live
-  immediately (`fsutil hardlink list` shows both paths), at the cost of pinning an absolute path in
-  `package.json`. Use `file:` while developing, `github:` for keeps.
+- **A registry spec copies, `file:` hard-links.** `dsh-pwsh-plugin@X.Y.Z` installs one copy of that release —
+  editing the checkout changes nothing until you run `add` again. A `file:` install hard-links the checkout,
+  so edits are live immediately (`fsutil hardlink list` shows both paths), at the cost of pinning an absolute
+  path in `package.json`. Use `file:` while developing, a registry spec for keeps.
+  `github:citydirector/dsh-pwsh-plugin#<tag>` still works and installs the same copy, but it goes around
+  pnpm's supply-chain policy.
 - **The bundle row cannot carry `?v=N`.** Its `name` must be the package name so it resolves from the
   profile's `node_modules`, so there is no URL to change and ESM keeps serving the module it already cached.
   Changing a file under `node_modules` is only picked up if the host happens to run a recomposition later;
@@ -127,7 +144,7 @@ When order matters, merge them yourself: `2>&1` or `*>&1`.
 | `maxSessions` | `4` | How many sessions may live at once (one per agent workspace). |
 | `maxOutputBytes` | `8388608` | Output collection cap per call (8 MB). Truncation is reported honestly, never silently. |
 | `allowUnconfined` | `false` | `true` = start a session even when the sandbox policy service is missing. |
-| `updateCheck` | `true` | Look for release tags periodically. Checking and installing are separate: this only checks; `pwsh_run_update` and auto-update do the install. |
+| `updateCheck` | `true` | Look for newer published versions periodically. Checking and installing are separate: this only checks; `pwsh_run_update` and auto-update do the install. |
 | `autoUpdate` | `true` | Install a newer release by itself, and — where the host runs HMR — take effect without a restart. |
 | `autoUpdateDelayMs` | `90000` | Wait before the first automatic check, so start-up is not competing with pnpm. |
 
@@ -165,14 +182,14 @@ runspace. The tool reports that clearly and points at the built-in `pwsh` tool,
 
 ## Updates
 
-Left alone, the plugin upgrades itself: 90 seconds after start, then every 12 hours, it reads the release
-tags, and a newer `vX.Y.Z` is installed on the spot. On a host that runs DSH's HMR service the new code is
+Left alone, the plugin upgrades itself: 90 seconds after start, then every 12 hours, it reads the `latest`
+dist-tag from the npm registry, and a newer release is installed on the spot. On a host that runs DSH's HMR service the new code is
 **already live when the install returns** — no restart, no prompt, nothing for the user to do.
 
 | How | What happens |
 |---|---|
 | Automatic (`autoUpdate: true`, default) | Checks, installs, and takes effect in place. A failed install backs off exponentially (5 min doubling to 2 h) and tries again; a version that installed successfully is not retried. **Never while a call is running** — it retries in 3 minutes. On a host **without** HMR it installs nothing — see below. |
-| `pwsh_run_update` `action: "check"` | Reads the tags once and reports `state` / `running` / `newest release` / `install spec`. Installs nothing. |
+| `pwsh_run_update` `action: "check"` | Reads the registry once and reports `state` / `running` / `newest release` / `install spec`. Installs nothing. |
 | `pwsh_run_update` `action: "install"` | The same install, driven by hand instead of by the clock. Reports `install: postponed` if a call is running, and `install: restart-required` / `install: broken-release` when a pre-flight check says installing would achieve nothing (see below). |
 
 The install goes through `ctx.get('pluginManager')` — the service behind the Plugins page — which runs pnpm
@@ -221,39 +238,31 @@ Without `pluginManager` — a profile where the `plugin-manager` service is disa
 
 ```powershell
 $env:DSH_HOME = '<DSH_HOME>'
-& '<desktop install>\resources\runtime\cli\bin\dsh.cmd' plugin --profile desktop add 'github:citydirector/dsh-pwsh-plugin#<tag>'
+& '<desktop install>\resources\runtime\cli\bin\dsh.cmd' plugin --profile desktop add 'dsh-pwsh-plugin@<version>'
 ```
 
 Note that DSH's stock composition disables the *tool* `plugin_manager` while leaving the *service* running
 for desktop profiles; the two are different things, and only the service is used here.
 
-The default source is `github:citydirector/dsh-pwsh-plugin`, read via `GET /repos/<repo>/tags`. A tag must
-match `^v\d+\.\d+\.\d+$` (prereleases are never offered), and the highest version wins.
+The source is the npm registry entry for this package: `GET https://registry.npmjs.org/dsh-pwsh-plugin`
+with `accept: application/vnd.npm.install-v1+json`. Its `dist-tags.latest` is the release to offer; it must
+be a plain `X.Y.Z`. A `latest` marked `deprecated` is never offered, and without a `dist-tags` the check
+falls back to the highest stable version in the version list. A `404` is reported as "not published on
+<registry>" rather than "no newer release" — those are different facts, and only one of them is temporary.
+
+The install spec is the registry form, `dsh-pwsh-plugin@X.Y.Z`, so what the plugin asks for and what
+`dsh plugin add` accepts are the same string.
 
 | Environment variable | Effect |
 |---|---|
-| `DSH_PWSH_UPDATE_SOURCE` | `owner/repo` → GitHub; `git+<url>` → plain `git ls-remote --tags` (`git+file:///path` rehearses locally) |
-| `DSH_PWSH_UPDATE_API` | GitHub API base, default `https://api.github.com` |
+| `DSH_PWSH_UPDATE_REGISTRY` | Registry base URL, default `https://registry.npmjs.org`. Point it at a mirror, or at a local server to rehearse. |
 | `DSH_PWSH_UPDATE_DELAY_MS` | First check delay, default 5000 |
 
-To rehearse locally, make a tagged repository and point the source at it:
-
 ```powershell
-$root = Join-Path $env:TEMP ('pwsh-rel-' + [guid]::NewGuid().ToString('N').Substring(0, 8))
-git init -q -b main $root
-git -C $root -c user.email=t@l -c user.name=t commit -q --allow-empty -m release
-git -C $root tag v0.2.1
-$env:DSH_PWSH_UPDATE_SOURCE = 'git+file:///' + ($root -replace '\\','/')
-node -e "import('./plugin/update-check.mjs').then(async (m) => console.log(JSON.stringify(await new m.UpdateChecker({ version: '0.1.0' }).check())))"
-# -> {"state":"available","latest":"v0.2.1","checkedAt":"..."}
-Remove-Item -Recurse -Force $root
+& $dsh plugin --profile desktop add 'dsh-pwsh-plugin@<version>'
 ```
 
-Rehearse on the **Windows** side (`pwsh_run` or the built-in `pwsh` tool). Exporting
-`DSH_PWSH_UPDATE_SOURCE` from a WSL `bash` call never reaches a Windows process — WSL only forwards the
-variables named in `WSLENV`, so every other `DSH_*` disappears and the plugin queries the default GitHub
-repository instead. Crossing over needs `WSLENV=DSH_PWSH_UPDATE_SOURCE`; do **not** add `/p`, which would
-rewrite `/tmp/...` into a `\\wsl.localhost\...` path and break it.
+Installing by hand is the same operation the plugin performs, with the same policy applied by pnpm.
 
 A failed query never throws into the tool call: it records `state: 'failed'`, logs one line through
 `ctx.logger`, and keeps an earlier `latest` as `stale: 'available'` — one network hiccup should not make a
@@ -352,7 +361,7 @@ plugin/
   index.mjs           tool registration, sandbox wiring, timeouts
   session.mjs         the session object: framing, queue, base64 encode, boot argv
   session-server.ps1  the PowerShell side: runspace, stream tagging, sentinels
-  update-check.mjs    release tag lookup and comparison
+  update-check.mjs    registry lookup and version comparison
   update-apply.mjs    hands the pinned spec to pluginManager, never downloads
   auto-update.mjs     the automatic path: install outside the HMR transaction, back off on failure
 test/
@@ -363,7 +372,7 @@ test/
   sandboxtest.mjs     real LocalSandboxProvider, boundary + fail-closed cases
   bashtest.mjs        custom-bash fence triage (mock runtime)
   bash-e2e.mjs        custom-bash end to end (real runtime + real llrun)
-  updatetest.mjs      update check against a local git repository, install outcomes
+  updatetest.mjs      update check against a local registry, install outcomes
   autoupdatetest.mjs  the automatic loop, its back-off, its idle gate, and the HMR-context escape it needs
   wiringtest.mjs      the update notice lands at the end of tool output, and installs wait for an idle session
   denialtest.mjs      the sandbox-denial hint fires on the right messages only
@@ -391,17 +400,24 @@ node test/denialtest.mjs                     # 11: sandbox-denial hint (no spawn
 node test/metatest.mjs                       # 23: plugin-page metadata (no spawn, runs anywhere)
 ```
 
-Eleven scripts, **272 assertions**, none of which needs DSH to be running — just node 24, PowerShell 7 and a
+Eleven scripts, **305 assertions**, none of which needs DSH to be running — just node 24, PowerShell 7 and a
 DSH install to borrow `node_modules` from. Tests that need a DSH runtime locate one automatically
 (`DSH_MODULES`, `DSH_MODULES_ASAR`, or by walking up from the working directory) and print a `SKIP` hint
 instead of failing when none is found.
 
 ### Releasing
 
+Publishing from a tag is `[.github/workflows/release.yml](.github/workflows/release.yml)`: it runs
+`scripts/release-check.mjs`, then `npm publish --provenance` under npm's **trusted publishing**, which trades
+the runner's short-lived GitHub identity for a token scoped to this repository and this workflow file. No
+`NPM_TOKEN` secret exists, and none should be added. Two consequences worth knowing: the workflow file name is
+part of the trust contract (rename it and every publish fails with 403 until the npm setting is updated), and
+provenance is mandatory there, so the tarball carries a signed statement of which commit built it.
+
 The version in `package.json` is the one thing in this repository that is hard-coded, and the update check
-compares it against the published tags. Tag a commit without bumping it and the check reports a newer
-release forever: the installed files keep reading the old number, so every cycle reinstalls the same tag and
-the back-off climbs to its ceiling. `npm version` writes the version, commits, and tags in one step, which is
+compares it against the published version. Publish without bumping it and the check reports a newer
+release forever: the installed files keep reading the old number, so every cycle requests the same version
+and the back-off climbs to its ceiling. `npm version` writes the version, commits, and tags in one step, which is
 why the three cannot drift apart:
 
 ```powershell

package/README.zh-CN.md

@@ -42,6 +42,16 @@
 它**不会**顺手禁用官方的 `tool-bash`：那一行本来就带 `disabled: !!js process.platform === 'win32'`，
 在这里写死 `disabled: true` 会把 Linux 上的官方 bash 一起关掉。
 
+**npm registry。** 也在 npm 上：`npm i dsh-pwsh-plugin`，或者让 DSH 装 registry 规格：
+
+```powershell
+& $dsh plugin --profile desktop add 'dsh-pwsh-plugin@<version>'
+```
+
+> 注意 pnpm 的 `minimumReleaseAge` 默认 1440 分钟：刚发布的版本当天不会自动解析到，点「更新」会装到上一个版本。这是供应链策略，不是装错。
+
+> `npm publish` 之后的头五分钟里，tarball 地址在 CDN 边缘仍返回 **404**（`cache-control: public, max-age=300`），而版本文档和 `dist-tags.latest` 都已经是新值。在这段时间里安装会报 `ERR_PNPM_FETCH_404 … .tgz: Not Found`，看起来像权限问题，其实不是。等满五分钟即可；加 `?nocache=` 能绕过缓存，但 npm 和 pnpm 都不会去取那个地址。
+
 **侧栏。** Plugins → Add plugin → `https://github.com/citydirector/dsh-pwsh-plugin`，然后打开开关。
 
 **命令行。** `desktop` profile 只能由桌面端自带的 CLI 管：
@@ -50,8 +60,8 @@
 $dsh = '<桌面端安装目录>\resources\runtime\cli\bin\dsh.cmd'
 $env:DSH_HOME = '<DSH_HOME>'        # 桌面 App 自己用的那个数据根
 
-# <tag> 是任意已发布的标签；最新的那个就是插件自己会装的那个
-& $dsh plugin --profile desktop add 'github:citydirector/dsh-pwsh-plugin#<tag>'
+# <version> 是任意已发布版本；最新的那个就是插件自己会装的那个
+& $dsh plugin --profile desktop add 'dsh-pwsh-plugin@<version>'
 # 或者从本地检出装
 & $dsh plugin --profile desktop add 'file:<检出目录>'
 ```
@@ -62,9 +72,11 @@ $env:DSH_HOME = '<DSH_HOME>'        # 桌面 App 自己用的那个数据根
 
 选 spec 之前要知道两件事：
 
-- **`github:` 是拷贝，`file:` 是硬链接。** `github:` 装的是那个 tag 的快照 —— 改检出不会生效，得重新 `add`。
-  `file:` 直接硬链接检出，改完立刻生效（`fsutil hardlink list` 能看到两条路径），代价是 `package.json`
-  里钉死了绝对路径。开发期用 `file:`，长期用 `github:`。
+- **registry 规格是拷贝，`file:` 是硬链接。** `dsh-pwsh-plugin@X.Y.Z` 装的是那次发布的一份拷贝 ——
+  改检出不会生效，得重新 `add`。`file:` 直接硬链接检出，改完立刻生效（`fsutil hardlink list` 能看到
+  两条路径），代价是 `package.json` 里钉死了绝对路径。开发期用 `file:`，长期用 registry 规格。
+  `github:citydirector/dsh-pwsh-plugin#<tag>` 仍然能装，效果与 registry 规格相同（都是拷贝），只是
+  绕开了 pnpm 的供应链策略。
 - **bundle 那一行带不了 `?v=N`。** 它的 `name` 必须是包名，才能从 profile 的 `node_modules` 解析，
   因此没有 URL 可变，ESM 继续用它已经缓存的那个模块。改 `node_modules` 下的文件，只有等宿主碰巧跑一次
   重组合才可能被换掉 —— 开发期不能指望这个，用下面那种手写行并把 `?v=N` 提一号，或者重启。
@@ -115,7 +127,7 @@ $env:DSH_HOME = '<DSH_HOME>'        # 桌面 App 自己用的那个数据根
 | `maxSessions` | `4` | 同时存活的会话上限（每个 agent 工作区一个）。 |
 | `maxOutputBytes` | `8388608` | 单次调用的输出收集上限（8MB）。截断会明确报出来，不静默。 |
 | `allowUnconfined` | `false` | `true` = 沙箱策略服务缺席时也起会话。 |
-| `updateCheck` | `true` | 定期查发布标签。查与装分开：这里只查，装由 `pwsh_run_update` 与自动更新做。 |
+| `updateCheck` | `true` | 定期查有没有新发布的版本。查与装分开：这里只查，装由 `pwsh_run_update` 与自动更新做。 |
 | `autoUpdate` | `true` | 自己装上更新，宿主有 HMR 时**不需要重启**即生效。 |
 | `autoUpdateDelayMs` | `90000` | 自动检查前的等待，避免与启动流程抢 pnpm。 |
 
@@ -148,14 +160,14 @@ session，**静默退回部署默认值**（mode + 配置里的 `workspaceRoot`
 
 ## 更新
 
-默认情况下插件自己升级：启动 90 秒后查一次发布标签，之后每 12 小时一次；查到更高的 `vX.Y.Z` 就直接
-装上。宿主跑着 DSH 的 HMR 服务时，**装上的那一刻新代码就已经在跑** —— 不用重启，不用弹窗，用户什么
+默认情况下插件自己升级：启动 90 秒后查一次 npm registry 的 `latest` 标签，之后每 12 小时一次；查到
+更高的版本就直接装上。宿主跑着 DSH 的 HMR 服务时，**装上的那一刻新代码就已经在跑** —— 不用重启，不用弹窗，用户什么
 都不用做。
 
 | 方式 | 行为 |
 |---|---|
 | 自动（`autoUpdate: true`，默认） | 查 → 装 → 就地生效。装失败按指数退避重试（5 分钟起、翻倍、封顶 2 小时）；装成功过的版本不再重试。**有调用在跑时绝不装** —— 3 分钟后再看。宿主**没有** HMR 时它什么都不装，见下。 |
-| `pwsh_run_update` 的 `action: "check"` | 只读一次标签，报出 `state` / `running` / `newest release` / `install spec`。不装任何东西。 |
+| `pwsh_run_update` 的 `action: "check"` | 只读一次 registry，报出 `state` / `running` / `newest release` / `install spec`。不装任何东西。 |
 | `pwsh_run_update` 的 `action: "install"` | 同一条安装路径，只是由人按下去而不是由时钟按下去。有调用在跑时报 `install: postponed`；预检判定「装了也没用」时报 `install: restart-required` / `install: broken-release`（见下）。 |
 
 安装走 `ctx.get('pluginManager')` —— 也就是「插件」页面背后那个服务 —— 由它跑 pnpm，失败时回滚
@@ -197,40 +209,29 @@ session，**静默退回部署默认值**（mode + 配置里的 `workspaceRoot`
 
 ```powershell
 $env:DSH_HOME = '<DSH_HOME>'
-& '<桌面端安装目录>\resources\runtime\cli\bin\dsh.cmd' plugin --profile desktop add 'github:citydirector/dsh-pwsh-plugin#<tag>'
+& '<桌面端安装目录>\resources\runtime\cli\bin\dsh.cmd' plugin --profile desktop add 'dsh-pwsh-plugin@<version>'
 ```
 
 注意 DSH 的默认组合关掉的是**工具** `plugin_manager`，而桌面 profile 上的**服务** `plugin-manager`
 是活的 —— 两者不是一回事，这里只用服务。
 
+发布源就是这个包在 npm registry 上的条目：`GET https://registry.npmjs.org/dsh-pwsh-plugin`，请求头带
+`accept: application/vnd.npm.install-v1+json`。它的 `dist-tags.latest` 就是要推的版本，必须是纯
+`X.Y.Z`；被标了 `deprecated` 的 `latest` 永不推送；没有 `dist-tags` 时回落到版本清单里的最高正式版。
+返回 `404` 时报的是「not published on <registry>」而不是「没有新版本」—— 这两件事不同，只有一件是临时的。
 
-
-默认发布源是 `github:citydirector/dsh-pwsh-plugin`，读 `GET /repos/<repo>/tags`。标签必须匹配
-`^v\d+\.\d+\.\d+$`（预发布永不推送），取版本号最大的那个。
+安装规格用 registry 形式 `dsh-pwsh-plugin@X.Y.Z`，所以插件请求的字符串与 `dsh plugin add` 接受的是同一个。
 
 | 环境变量 | 作用 |
 |---|---|
-| `DSH_PWSH_UPDATE_SOURCE` | `owner/repo` → GitHub；`git+<url>` → 直接 `git ls-remote --tags`（`git+file:///path` 可在本地预演） |
-| `DSH_PWSH_UPDATE_API` | GitHub API 基址，默认 `https://api.github.com` |
+| `DSH_PWSH_UPDATE_REGISTRY` | registry 基址，默认 `https://registry.npmjs.org`。可指向镜像，或指向本机服务做预演 |
 | `DSH_PWSH_UPDATE_DELAY_MS` | 首次检查延迟，默认 5000 |
 
-本地预演：先建一个带 tag 的仓库，再把源指过去 ——
-
 ```powershell
-$root = Join-Path $env:TEMP ('pwsh-rel-' + [guid]::NewGuid().ToString('N').Substring(0, 8))
-git init -q -b main $root
-git -C $root -c user.email=t@l -c user.name=t commit -q --allow-empty -m release
-git -C $root tag v0.2.1
-$env:DSH_PWSH_UPDATE_SOURCE = 'git+file:///' + ($root -replace '\\','/')
-node -e "import('./plugin/update-check.mjs').then(async (m) => console.log(JSON.stringify(await new m.UpdateChecker({ version: '0.1.0' }).check())))"
-# → {"state":"available","latest":"v0.2.1","checkedAt":"..."}
-Remove-Item -Recurse -Force $root
+& $dsh plugin --profile desktop add 'dsh-pwsh-plugin@<version>'
 ```
 
-预演请走 **Windows 侧**（`pwsh_run` 或内置 `pwsh` 工具）。在 WSL 的 `bash` 调用里
-`export DSH_PWSH_UPDATE_SOURCE=...` 传不进 Windows 进程 —— WSL 只透传 `WSLENV` 里点名过的变量，其余
-`DSH_*` 到子进程就消失，表现是「明明设了源，却去查默认的 GitHub 仓库」。真要跨过去得写
-`WSLENV=DSH_PWSH_UPDATE_SOURCE`；**别加 `/p`**，那会把 `/tmp/...` 转成 `\\wsl.localhost\...` 路径，源就废了。
+手动安装与插件自己做的事是同一条路径，同样由 pnpm 施加同样的策略。
 
 查询失败不会抛进工具调用：记 `state: 'failed'`，经 `ctx.logger` 留一行，先前查到过的 `latest` 保留成
 `stale: 'available'` —— 一次网络抖动不该让已知的新版本消失。
@@ -314,7 +315,7 @@ plugin/
   index.mjs           工具注册、沙箱接线、超时
   session.mjs         会话对象：分帧、队列、base64、启动 argv
   session-server.ps1  PowerShell 侧：runspace、流打标、哨兵
-  update-check.mjs    发布标签查询与比较
+  update-check.mjs    registry 查询与版本比较
   update-apply.mjs    把钉住的规格交给 pluginManager，不自己下载
   auto-update.mjs     自动路径：在 HMR 事务之外安装，失败退避
 test/
@@ -353,14 +354,21 @@ node test/denialtest.mjs                     # 11：沙箱拒绝提示（不起
 node test/metatest.mjs                       # 23：插件页元数据（不起子进程，哪儿都能跑）
 ```
 
-十一份脚本合计 **272 项**，都不需要 DSH 在跑 —— 只要 node 24、PowerShell 7，以及一个能借
+十一份脚本合计 **305 项**，都不需要 DSH 在跑 —— 只要 node 24、PowerShell 7，以及一个能借
 `node_modules` 的 DSH 安装。需要 DSH 运行时的测试会自动找（`DSH_MODULES`、`DSH_MODULES_ASAR`，
 或从工作目录逐级向上），找不到时打一行 `SKIP` 提示而不是失败。
 
 ### 发版
 
-`package.json` 里的 version 是本仓库唯一写死的东西，而更新检查拿它跟已发布的标签比。只打 tag 不升版本，
-检查会永远报有新版：装上去的文件读到的还是旧数字，于是每轮都重装同一个 tag，退避一路爬到上限。
+从 tag 发布由 [`.github/workflows/release.yml`](.github/workflows/release.yml) 负责：先跑
+`scripts/release-check.mjs`，再用 npm 的 **trusted publishing** 执行 `npm publish --provenance` ——
+runner 用自己那份短命的 GitHub 身份换一个只对「这个仓库 + 这个 workflow 文件」有效的令牌。仓库里没有
+`NPM_TOKEN`，也不该加。两个连带后果值得记住：workflow 的文件名是信任契约的一部分（改名后每次发布都会
+403，直到在 npm 上改设置）；provenance 在那里是强制的，所以 tarball 会带上「由哪个提交构建」的签名声明。
+
+`package.json` 里的 version 是本仓库唯一写死的东西，而更新检查拿它跟 registry 上的已发布版本比。
+不升版本就发版，检查会永远报有新版：装上去的文件读到的还是旧数字，于是每轮都请求同一个版本，
+退避一路爬到上限。
 `npm version` 一次完成「改版本 + 提交 + 打 annotated tag」，所以这三者不会漂开：
 
 ```powershell

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-pwsh-plugin",
-  "version": "0.2.12",
+  "version": "0.2.14",
   "type": "module",
   "description": "Persistent pwsh session tool (pwsh_run) for DeepSeek Harness: run PowerShell scripts with zero escaping, no 32K command-line cap, and state that survives across calls.",
   "icon": "./icon.svg",

package/plugin/auto-update.mjs

@@ -23,9 +23,19 @@
  *   若此刻正有一条调用在跑，它会连带被掐断——脚本跑到一半、半截输出、会话状态全丢，
  *   与直接断电没有区别。所以安装前要问宿主「现在安静吗」，忙就整个推迟，
  *   而不是装完再说「可惜刚才那条被打断了」。
+ *
+ * 为什么要记住「上一次实际装到了哪个版本」
+ *   pnpm 的 minimumReleaseAge 会让「请求 0.2.13、装到 0.2.12」成为正常结果。若不留这个记忆，
+ *   下一轮还会请求 0.2.13、还会落回 0.2.12，被 plugin-manager 判 already-installed，
+ *   退避爬到上限，永远如此。记住之后就能认出「这是冷却期，不是故障」，直接等到期。
+ *
+ * 为什么冷却期落地之后要把目标版本从「装过」里撤出来
+ *   落到更旧的版本算成功，但它不是这次的目标：目标自己还要等窗口过去。若不当场撤掉，
+ *   这个版本就再也不会被尝试，等于把这个进程的生命周期钉死在旧版本上。
  */
 
 import { installRelease, preflightInstall } from './update-apply.mjs'
+import { compareVersions } from './update-check.mjs'
 
 /** 首次检查前的等待：让启动流程先跑完，别跟它抢 pnpm。 */
 const FIRST_DELAY_MS = 90 * 1000
@@ -35,24 +45,29 @@ const RETRY_BASE_MS = 5 * 60 * 1000
 const RETRY_MAX_MS = 2 * 60 * 60 * 1000
 /** 查出有新版但有调用正跑着：过一会儿再看一眼，别等到下一轮 12 小时。 */
 const BUSY_RETRY_MS = 3 * 60 * 1000
+/** 冷却期：pnpm 的窗口默认 24 小时，隔一小时再看一眼不浪费什么。 */
+const COOLDOWN_RETRY_MS = 60 * 60 * 1000
 
 /**
  * 在 HMR 事务之外装一个发布。
  *
  * @param ctx - 插件上下文，用来取 pluginManager 与 hmr。
- * @param spec - 钉住 tag 的安装规格，例如 github:owner/repo#v1.2.3。
+ * @param spec - 钉住版本号的安装规格，例如 dsh-pwsh-plugin@0.2.13。
  * @param options - { requestId, log }。
  * @returns 与 installRelease 相同的结果对象，永不抛出。
  */
 export async function installReleaseLive(ctx, spec, options = {}) {
   const manager = ctx?.get?.('pluginManager')
   const hmr = ctx?.get?.('hmr')
+  // 回读装完的版本需要 profile 目录；读不到就只报 application，不编一个版本号出来。
+  const profileDir = ctx?.get?.('profileContext')?.dir
+  const base = { ...options, ...(typeof profileDir === 'string' ? { profileDir } : {}) }
   if (hmr === undefined || typeof hmr?.executing?.run !== 'function') {
-    return await installRelease(manager, spec, { ...options, live: false })
+    return await installRelease(manager, spec, { ...base, live: false })
   }
   // 上下文清空后 installBundle 自己会拿 runExclusive；装完 HMR 重组合，
   // 本插件的模块被驱逐、新模块 import 进来重新 apply。
-  return await hmr.executing.run(undefined, () => installRelease(manager, spec, { ...options, live: true }))
+  return await hmr.executing.run(undefined, () => installRelease(manager, spec, { ...base, live: true }))
 }
 
 /**
@@ -72,7 +87,7 @@ function hmrIsLive(ctx) {
  *
  * @param ctx - 插件上下文。
  * @param checker - UpdateChecker 实例；它的 check() 重入安全，直接复用。
- * @param options - { log, firstDelayMs, intervalMs, retryBaseMs, retryMaxMs }。
+ * @param options - { log, firstDelayMs, intervalMs, retryBaseMs, retryMaxMs, cooldownRetryMs }。
  * @returns 停止函数；插件被卸载或热替换时由调用方停掉。
  */
 export function startAutoUpdate(ctx, checker, options = {}) {
@@ -81,12 +96,15 @@ export function startAutoUpdate(ctx, checker, options = {}) {
   const intervalMs = options.intervalMs ?? INTERVAL_MS
   const retryBaseMs = options.retryBaseMs ?? RETRY_BASE_MS
   const retryMaxMs = options.retryMaxMs ?? RETRY_MAX_MS
+  const cooldownRetryMs = options.cooldownRetryMs ?? COOLDOWN_RETRY_MS
 
   const installGate = options.installGate
   const busyRetryMs = options.busyRetryMs ?? BUSY_RETRY_MS
 
   /** 已经自动装过的版本：同一个版本装成功过就不再装第二次。 */
   const attempted = new Set()
+  /** 上一次安装实际落到的版本：冷却期会让它与请求的版本不同，用来认出「不是故障」。 */
+  let lastInstalled
   let timer
   let stopped = false
   let running = false
@@ -116,15 +134,20 @@ export function startAutoUpdate(ctx, checker, options = {}) {
           const spec = doc.spec
           if (typeof spec === 'string' && spec.length > 0) {
             // 装之前先问一句值不值得装，否则 already-installed 会以「失败」的姿态出现，
-            // 而它其实有两种含义完全不同的成因（别人装好了 / 发布忘了升版本）。
-            const unnecessary = preflightInstall(ctx, checker, spec)
+            // 而它其实有几种含义完全不同的成因（别人装好了 / 发布忘了升版本 / 冷却期未过）。
+            const unnecessary = preflightInstall(ctx, checker, spec, lastInstalled === undefined ? {} : { cooled: lastInstalled })
             if (unnecessary !== null) {
               busyNoted = false
-              // 记下这个版本，别再排下一轮：三种成因都不会自己好转。
-              // 「别人装好了等重启」重启后会重建循环，那时代码已是最新，根本走不到这里。
+              // 记下这个版本，别再排下一轮：这几种成因都不会在几分钟内自己好转。
+              // 冷却期例外——它是会到期的，所以单独按小时再看。
               attempted.add(state.latest)
               log('auto update: ' + state.latest + ' — ' + unnecessary.outcome + ': ' + unnecessary.text)
-              if (unnecessary.ok === true) failures = 0
+              if (unnecessary.outcome === 'cooling-down') {
+                attempted.delete(state.latest)
+                next = cooldownRetryMs
+              } else if (unnecessary.ok === true) {
+                failures = 0
+              }
               return
             }
             busyNoted = false
@@ -132,6 +155,15 @@ export function startAutoUpdate(ctx, checker, options = {}) {
             log('auto update: installing ' + state.latest + ' from ' + spec)
             const outcome = await installReleaseLive(ctx, spec, { requestId: 'pwsh-run-auto-update', log })
             log('auto update: ' + outcome.outcome + ' — ' + outcome.text)
+            if (outcome.installedVersion !== undefined) {
+              lastInstalled = outcome.installedVersion
+              // 落到更旧的版本是 pnpm 冷却期的正常结果，但目标版本还在窗口里：
+              // 撤掉这条记录，过一小时（窗口是 24 小时）再看，而不是等满 12 小时。
+              if (compareVersions(outcome.installedVersion, state.latest) < 0) {
+                attempted.delete(state.latest)
+                next = cooldownRetryMs
+              }
+            }
             if (outcome.ok !== true) {
               // 装失败要能重来：把记录撤掉，交给退避后的下一轮。
               attempted.delete(state.latest)
@@ -175,4 +207,4 @@ export function startAutoUpdate(ctx, checker, options = {}) {
     stopped = true
     clearTimeout(timer)
   }
-}
+}

package/plugin/index.mjs

@@ -316,7 +316,7 @@ export function apply(ctx, config) {
     sessions.clear()
   }, 'pwsh-run.sessions')
 
-  // 更新检查：只读发布标签、只记判决，从不自己安装。
+  // 更新检查：只读 npm registry 的 dist-tags、只记判决，从不自己安装。
   // 发现新版本时不改工具描述（描述在注册时就固定了），而是把提示挂在每次调用的
   // 输出末尾一次——够模型看见，也不至于每次刷。
   const checker = updateCheck
@@ -366,10 +366,10 @@ export function apply(ctx, config) {
     name: 'pwsh_run_update',
     description: [
       'Check for, and optionally install, a newer release of the pwsh_run plugin.',
-      '* action "check" reads the release tags once and reports the verdict; it never installs anything.',
-      '* action "install" hands the pinned tag spec to DSH\'s own plugin manager (the same service the Plugins page uses), which runs pnpm and rolls back on failure.',
+      '* action "check" reads the npm registry dist-tags once and reports the verdict; it never installs anything.',
+      '* action "install" hands the pinned version spec (<package>@X.Y.Z) to DSH\'s own plugin manager (the same service the Plugins page uses), which runs pnpm and rolls back on failure.',
       '* Installing writes the package to the profile. Where the host runs its HMR service, the new code is already live when this returns; otherwise the running process keeps the old modules until DSH restarts. The result says which of the two happened.',
-      '* Only vX.Y.Z release tags are considered; pre-releases and branch heads are ignored.',
+      '* Only published stable versions are considered; pre-releases are never pushed. The version actually installed is read back from disk, because pnpm\'s minimumReleaseAge policy can install an older release than the one requested.',
       '* An install replaces this plugin in place, which terminates the persistent pwsh sessions. It is therefore refused while a pwsh_run call is running; retry after that call finishes (the automatic updater applies the same rule on its own).',
     ].join('\n'),
     parameters: {
@@ -413,8 +413,8 @@ export function apply(ctx, config) {
         }
         else {
           // 这条分支上 doc.spec 是 undefined，插值只会印出一个字面占位符，所以给模板。
-          lines.push('Could not reach the release source, so whether a newer version exists is unknown. '
-            + 'Run the check again later, or upgrade by hand: dsh plugin --profile <name> add "github:<owner>/<repo>#vX.Y.Z"')
+          lines.push('Could not reach the npm registry, so whether a newer version exists is unknown. '
+            + 'Run the check again later, or upgrade by hand: dsh plugin --profile <name> add "<package>@X.Y.Z"')
         }
         return { text: lines.join('\n') }
       }
@@ -446,6 +446,9 @@ export function apply(ctx, config) {
       }
       lines.push('install: ' + outcome.outcome)
       lines.push(outcome.text)
+      if (outcome.installedVersion !== undefined && outcome.installedVersion !== doc.latest) {
+        lines.push('Installed version on disk: ' + outcome.installedVersion + ' (requested ' + String(doc.latest) + ').')
+      }
       if (outcome.ok !== true && doc.spec !== undefined) lines.push('Manual path: dsh plugin --profile <name> add "' + String(doc.spec) + '"')
       return { text: lines.join('\n') }
     },

package/plugin/update-apply.mjs

@@ -9,6 +9,12 @@
  *   踩到脏状态。所以安装这一步交给 dsh-plugin-manager（Plugins 页面用的同一个服务），
  *   它自己跑 pnpm、自己回滚 package.json / lockfile。
  *
+ * 为什么装完必须回读磁盘版本
+ *   pnpm 有供应链冷却期（minimumReleaseAge，v11 起默认 1440 分钟）。请求 dsh-pwsh-plugin@0.2.13
+ *   而该版本刚发布几小时，pnpm 会装到它能接受的那个版本；installBundle 的返回值里没有版本号，
+ *   只有 application 这个枚举。所以「装了什么」只能从装完的 package.json 读回来 ——
+ *   把这里的判决当成既成事实去宣称，就是在说一句没人验证过的话。
+ *
  * 能不能不重启
  *   bundle 行的 name 是包名，拿不到 URL 上的缓存破坏参数，ESM 按 URL 缓存模块 —— 光重新 apply
  *   只是再 import 同一个 URL。但 installBundle 走 HMR 的 runExclusive，重组合会比对文件指纹
@@ -20,7 +26,7 @@
 import { readFileSync } from 'node:fs'
 import { join } from 'node:path'
 
-import { packageVersion } from './update-check.mjs'
+import { compareVersions, packageVersion } from './update-check.mjs'
 
 /** 本包的包名：profile 的 dependencies 用它记录安装规格。 */
 const OWN_NAME = (() => {
@@ -33,9 +39,37 @@ const OWN_NAME = (() => {
 })()
 
 /** `v1.2.3` 与 `1.2.3` 是同一个版本；不是这个形态时返回 undefined。 */
-function bareVersion(value) {
+export function bareVersion(value) {
   const text = String(value ?? '').trim().replace(/^v/i, '')
-  return /^\d+\.\d+\.\d+$/.test(text) ? text : undefined
+  return /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(text) ? text : undefined
+}
+
+/**
+ * 安装规格末尾钉的版本：`dsh-pwsh-plugin@1.2.3` → `1.2.3`。
+ *
+ * 只认包名之后的那一段：npm 规格里 @ 既是 scope 分隔符也是版本分隔符，
+ * 所以取**最后一个** @ 之后的部分，并对 `@scope/name@1.2.3` 同样成立。
+ */
+export function specVersion(spec) {
+  const text = typeof spec === 'string' ? spec.trim() : ''
+  const at = text.lastIndexOf('@')
+  if (at <= 0) return undefined
+  return bareVersion(text.slice(at + 1))
+}
+
+/**
+ * 从一份 package.json 里读版本号。
+ *
+ * @param path - package.json 的路径。
+ * @returns 版本号；文件不存在、坏 JSON、没有 version 字段时返回 undefined。
+ */
+export function readVersionAt(path) {
+  try {
+    const pkg = JSON.parse(readFileSync(path, 'utf8'))
+    return typeof pkg.version === 'string' ? pkg.version : undefined
+  } catch {
+    return undefined
+  }
 }
 
 /**
@@ -61,16 +95,18 @@ export function readInstalledSpec(profileDir, packageName = OWN_NAME) {
  *
  * 为什么要有它
  *   dsh-plugin-manager 在 HMR 在场的宿主上，对「规格与 profile 里已记录的完全相同」的安装会在
- *   pnpm 之前直接抛 already-installed。有两种情形会撞上，而它们都不该真去装一次：
+ *   pnpm 之前直接抛 already-installed。有三种情形会撞上，而它们都不该真去装一次：
  *     1. 别人（终端 dsh plugin add、Plugins 页面）已经装好了，只是进程还没重启；
  *     2. 发版时打了 tag 却忘了改 package.json 的 version —— 装的永远是同一个包内版本，
- *        于是每一轮都「有新版、装不进去」，静默循环到天荒地老。
- *   两种都能用手里已有的事实判掉：profile 记的规格、磁盘上的包版本、进程里在跑的版本。
- *   判掉之后要能说清是哪一种 —— 一个要重启，另一个是发布本身有毛病。
+ *        于是每一轮都「有新版、装不进去」，静默循环到天荒地老；
+ *     3. pnpm 的冷却期让这次安装只会落到已经装好的那个版本上（见下面的 cooled 参数）。
+ *   都能用手里已有的事实判掉，判掉之后要能说清是哪一种。
  *
- * @param options - `{ spec, latest, disk, running, installed }`。
+ * @param options - `{ spec, latest, disk, running, installed, cooled }`。
  *   `disk` 缺省时现读本包 package.json；`running` 缺省时不比对运行版本。
- * @returns 该装时返回 null；否则返回 `{ ok, outcome, text }`——三种情形成因不同，都不该重试。
+ *   `cooled` 是「上一次安装实际落到的版本」——冷却期让这次不可能装到 latest 时，
+ *   调用方把它传进来，这里就不再发起注定落空的安装。
+ * @returns 该装时返回 null；否则返回 `{ ok, outcome, text }`——几种情形成因不同，都不该重试。
  */
 export function checkInstallNeed(options = {}) {
   const latest = bareVersion(options.latest)
@@ -81,6 +117,7 @@ export function checkInstallNeed(options = {}) {
   const running = bareVersion(options.running)
   const spec = typeof options.spec === 'string' ? options.spec.trim() : undefined
   const installed = typeof options.installed === 'string' ? options.installed.trim() : undefined
+  const cooled = bareVersion(options.cooled)
 
   if (disk === latest) {
     // 磁盘上已经是这个版本了，再装一次要么被拒，要么装个同样的东西。
@@ -103,25 +140,30 @@ export function checkInstallNeed(options = {}) {
   // 读不到包内版本时不做这个判断：那是「本插件自己的 package.json 有问题」，不是发布的问题，
   // 按未知处理比按坏发布处理安全。
   if (disk !== undefined && spec !== undefined && spec.length > 0 && installed === spec) {
-    // profile 已经指向这个 tag，而磁盘上的包仍报别的版本：tag 与 package.json 对不上。
+    // profile 已经指向这个版本，而磁盘上的包仍报别的版本：发布本身坏了。
     return {
       ok: false,
       outcome: 'broken-release',
-      text: 'The release tagged v' + latest + ' still declares version ' + disk
-        + ' in its package.json, and the profile already points at that tag. Every install attempt would be '
-        + 'refused as already-installed and could never change anything. This release is broken: the tag '
-        + 'exists but package.json was not bumped.',
+      text: 'The release ' + latest + ' still declares version ' + disk
+        + ' in its package.json, and the profile already points at that version. Every install attempt would be '
+        + 'refused as already-installed and could never change anything. This release is broken: it was published '
+        + 'without bumping package.json.',
     }
   }
 
-  return null
-}
+  // 冷却期：上一次装同一个包时落在 cooled 上，而这次的目标比它新 —— pnpm 会重演同一个决定。
+  // 说清是策略在拦，并给出越过它的唯一官方办法（显式指定版本仍会被拦，所以要靠卸载重装）。
+  if (cooled !== undefined && compareVersions(cooled, latest) < 0 && compareVersions(cooled, running ?? disk ?? '0.0.0') >= 0) {
+    return {
+      ok: true,
+      outcome: 'cooling-down',
+      text: 'pnpm\'s supply-chain policy (minimumReleaseAge) refuses releases younger than its window, so ' + latest
+        + ' cannot be installed yet; the previous install landed on ' + cooled + '. Wait for the window to pass '
+        + '(24 hours by default from the publish time), or install it by hand after disabling the policy.',
+    }
+  }
 
-/** 安装规格末尾钉的 tag：`github:owner/repo#v1.2.3` → `v1.2.3`。 */
-export function specTag(spec) {
-  const text = typeof spec === 'string' ? spec.trim() : ''
-  const hash = text.lastIndexOf('#')
-  return hash === -1 ? undefined : text.slice(hash + 1)
+  return null
 }
 
 /**
@@ -129,16 +171,18 @@ export function specTag(spec) {
  *
  * @param ctx - 插件上下文；profileContext 缺席时读不到已装规格（预检只剩版本比对）。
  * @param checker - UpdateChecker 实例，用来取进程里在跑的版本。
- * @param spec - 要装的规格，末尾钉着 tag。
+ * @param spec - 要装的规格，末尾钉着版本号。
+ * @param options - `{ cooled }`：上一次安装实际落到的版本。
  * @returns checkInstallNeed 的结果：null 表示该装。
  */
-export function preflightInstall(ctx, checker, spec) {
+export function preflightInstall(ctx, checker, spec, options = {}) {
   const profileDir = ctx?.get?.('profileContext')?.dir
   return checkInstallNeed({
     spec,
-    latest: specTag(spec),
+    latest: specVersion(spec),
     running: checker?.version,
     installed: readInstalledSpec(profileDir),
+    ...(options.cooled === undefined ? {} : { cooled: options.cooled }),
   })
 }
 
@@ -184,12 +228,13 @@ export function describeInstallOutcome(result, options = {}) {
 }
 
 /**
- * 装一个钉住 tag 的规格。
+ * 装一个钉住版本号的规格，然后回读磁盘上真正落地的版本。
  *
  * @param manager - ctx.get('pluginManager')；缺席时传 null。
- * @param spec - 例如 `github:owner/repo#v1.2.3`。
- * @param options - `{ requestId, signal, log }`。
- * @returns `{ ok, outcome, text, error }`，永不抛出：安装失败是正常结果，不是程序缺陷。
+ * @param spec - 例如 `dsh-pwsh-plugin@0.2.13`。
+ * @param options - `{ requestId, signal, log, live, profileDir }`。
+ *   `profileDir` 用来回读装完后的 package.json —— 冷却期会让实际装到的版本比 spec 旧。
+ * @returns `{ ok, outcome, text, error, installedVersion }`，永不抛出：安装失败是正常结果，不是程序缺陷。
  */
 export async function installRelease(manager, spec, options = {}) {
   if (manager === null || manager === undefined) {
@@ -204,11 +249,22 @@ export async function installRelease(manager, spec, options = {}) {
   }
   try {
     const result = await manager.installBundle(spec, options.requestId === undefined ? {} : { requestId: options.requestId })
+    // 返回值里没有版本号：装了哪个版本只能从装完的磁盘读回来。冷却期会让它与 spec 不同，
+    // 而「说装好了」这句话必须对着磁盘上的事实说。
+    const installedVersion = typeof options.profileDir === 'string' && options.profileDir.length > 0
+      ? readVersionAt(join(options.profileDir, 'node_modules', OWN_NAME, 'package.json'))
+      : undefined
     const described = describeInstallOutcome(result, { live: options.live === true })
+    const text = installedVersion !== undefined && described.ok === true && compareVersions(installedVersion, specVersion(spec) ?? '0') < 0
+      // 装到了别的版本：pnpm 的冷却期在起作用。必须说出来，否则用户会以为升级成功了。
+      ? described.text + ' pnpm installed ' + installedVersion + ' rather than ' + String(specVersion(spec))
+        + ': its minimumReleaseAge policy withholds versions that are too recent.'
+      : described.text
     return {
       ok: described.ok,
       outcome: typeof result?.application === 'string' ? result.application : 'unknown',
-      text: described.text,
+      text,
+      ...(installedVersion === undefined ? {} : { installedVersion }),
       ...(result?.error === undefined ? {} : { error: result.error }),
     }
   } catch (error) {

package/plugin/update-check.mjs

@@ -3,136 +3,149 @@
  *
  * 为什么单独一个模块
  *   这个插件是纯宿主平面的工具插件，没有配置页面，也没有 client 入口。
- *   把「读发布标签 / 比版本 / 记状态」这几件事独立出来，就能在纯 node 里
+ *   把「读发布源 / 比版本 / 记状态」这几件事独立出来，就能在纯 node 里
  *   完整单测，不必起一个 DSH。
  *
+ * 发布源是 npm registry，不是 git 标签
+ *   早期版本读 GitHub 的 vX.Y.Z 标签，安装规格是 github:owner/repo#vX.Y.Z。
+ *   改到 registry 之后同一份发布既是 npm 包、也是 profile 里能被 pnpm 解析的依赖，
+ *   「装到的是哪个版本」由 pnpm 说了算，插件不必自己拼 git 规格。
+ *   更要紧的一条：pnpm 有供应链冷却期（minimumReleaseAge，默认 1440 分钟），
+ *   当天发布的版本当天可能解析不到 —— 于是「最新版」与「实际装到的版本」不是一回事。
+ *   检查阶段只认 registry 的 dist-tags，安装之后必须回读磁盘上的版本，
+ *   拿这里的判决去宣称装好了就是在说一句没人验证过的话。
+ *
  * 它做什么
- *   启动几秒后读一次发布源的 vX.Y.Z 标签，之后大约每 12 小时再读一次，
- *   与 package.json 里的版本比较。**从不自己安装**：发现新版本时只把
- *   版本号与 tag 钉住的安装规格（github:owner/repo#vX.Y.Z）记下来，
- *   由外部去装。一个 tag 一个规格，所以装新版本就是盖掉旧的，不需要额外逻辑。
- *   这里自己不动手：本模块只负责「读标签 → 比版本 → 记状态」，装与不装是另一个决定，
- *   由 pwsh_run_update 工具按用户的显式动作去做（见 update-apply.mjs）。
+ *   启动几秒后读一次 registry 的 dist-tags.latest，之后大约每 12 小时再读一次，
+ *   与 package.json 里的版本比较。**从不自己安装**：发现新版本时只把版本号与
+ *   安装规格（<package>@X.Y.Z）记下来。一个版本一个规格，所以装新版本就是盖掉旧的。
  *
  * 发布源可覆盖
- *   DSH_PWSH_UPDATE_SOURCE 可以是 owner/repo，也可以是任意 git URL
- *   （git+file:///…、git+https://…）。本地仓库预演发布就靠它。
- *   DSH_PWSH_UPDATE_API 覆盖 GitHub API 基址，DSH_PWSH_UPDATE_DELAY_MS
- *   覆盖首次检查的延迟（测试用）。
+ *   DSH_PWSH_UPDATE_REGISTRY 覆盖 registry 基址（测试与自建镜像靠它）。
+ *   DSH_PWSH_UPDATE_DELAY_MS 覆盖首次检查的延迟（测试用）。
  */
 
-import { execFile } from 'node:child_process'
 import { readFileSync } from 'node:fs'
 
-/** 发布在哪：这个仓库的 vX.Y.Z 标签就是发布。 */
-export const UPDATE_REPOSITORY = 'citydirector/dsh-pwsh-plugin'
+/** 发布在哪：这个包名在 npm registry 上的 dist-tags 就是发布。 */
+export const UPDATE_PACKAGE = 'dsh-pwsh-plugin'
+
+/** 默认 registry。 */
+export const UPDATE_REGISTRY = 'https://registry.npmjs.org'
 
 /** 启动后先让启动流程跑完，再查更新。 */
 const UPDATE_DELAY_MS = 5000
 const UPDATE_INTERVAL_MS = 12 * 60 * 60 * 1000
 
-/** 一个发布标签：v + 三段数字，后面不能再有东西（预发布版本永不推送）。 */
-const RELEASE_TAG = /^v(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/
+/** 三段数字，可选预发布尾巴；npm 的版本号允许的形态。 */
+const RELEASE_VERSION = /^(?:v)?(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z.-]+))?$/
 
 /**
- * 读一个发布标签。
+ * 读一个版本号。
  *
- * @param tag - git 标签名。
- * @returns `[major, minor, patch]`；不是 vX.Y.Z 形态时返回 undefined。
+ * @param value - 版本号，可带 v 前缀与预发布尾巴（1.2.3 / v1.2.3 / 1.2.3-rc.1）。
+ * @returns `{ parts: [major, minor, patch], prerelease }`；不是版本形态时返回 undefined。
  */
-export function parseReleaseTag(tag) {
-  const match = RELEASE_TAG.exec(String(tag ?? '').trim())
-  return match === null ? undefined : [Number(match[1]), Number(match[2]), Number(match[3])]
+export function parseVersion(value) {
+  const match = RELEASE_VERSION.exec(String(value ?? '').trim())
+  if (match === null) return undefined
+  const prerelease = match[4] === undefined ? undefined : match[4]
+  return { parts: [Number(match[1]), Number(match[2]), Number(match[3])], prerelease }
 }
 
 /**
  * 比两个版本，写 X.Y.Z 或 vX.Y.Z 都行。
  *
+ * 预发布（1.2.3-rc.1）按 semver 的规矩排在对应的正式版**之下**：
+ * 否则一个 rc 会被当成「比 1.2.3 还新」，自动更新就会把用户推到预发布上。
+ *
  * @returns 像排序比较器那样返回负数、零或正数；解析不出来的版本排在所有能解析的之下。
  */
 export function compareVersions(a, b) {
-  const tag = (value) => (String(value ?? '').startsWith('v') ? String(value) : 'v' + String(value))
-  const pa = parseReleaseTag(tag(a))
-  const pb = parseReleaseTag(tag(b))
+  const pa = parseVersion(a)
+  const pb = parseVersion(b)
   if (pa === undefined || pb === undefined) return (pa === undefined ? 0 : 1) - (pb === undefined ? 0 : 1)
-  for (let i = 0; i < 3; i += 1) if (pa[i] !== pb[i]) return pa[i] - pb[i]
-  return 0
-}
-
-/**
- * 标签里的最新发布：只认 vX.Y.Z，按语义版本取最高（不是按日期或列表顺序）。
- *
- * @param tags - 标签名，顺序无所谓。
- * @returns 最新的发布标签；一个都没有时返回 undefined。
- */
-export function latestRelease(tags) {
-  let best
-  for (const tag of tags ?? []) {
-    if (parseReleaseTag(tag) === undefined) continue
-    if (best === undefined || compareVersions(tag, best) > 0) best = tag
-  }
-  return best
+  for (let i = 0; i < 3; i += 1) if (pa.parts[i] !== pb.parts[i]) return pa.parts[i] - pb.parts[i]
+  if (pa.prerelease === pb.prerelease) return 0
+  // 都没有预发布尾巴 → 相等（上面已处理）；一个有一个没有 → 有尾巴的那个更旧。
+  if (pa.prerelease === undefined) return 1
+  if (pb.prerelease === undefined) return -1
+  return pa.prerelease < pb.prerelease ? -1 : pa.prerelease > pb.prerelease ? 1 : 0
 }
 
 /**
- * 发布从哪来。默认是 GitHub 仓库；DSH_PWSH_UPDATE_SOURCE 可以指向另一个
- * GitHub 仓库（owner/repo）或任意 git URL，发布正式上线前先在本地仓库预演就靠它。
+ * 发布从哪来。默认是 npm 公共 registry；DSH_PWSH_UPDATE_REGISTRY 可以指向自建镜像
+ * 或测试用的本地服务器 —— 发布正式上线前先在本地预演就靠它。
  *
  * @param env - 要读的环境。
- * @returns `{ kind: 'github', repository, spec }` 或 `{ kind: 'git', url, spec }`；
- *   `spec` 是不带 #tag 的安装规格。
+ * @returns `{ kind: 'registry', registry, name, spec }`；`spec` 是不带版本的安装规格。
  */
 export function updateSource(env = process.env) {
-  const raw = String(env.DSH_PWSH_UPDATE_SOURCE ?? '').trim()
-  if (/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(raw)) return { kind: 'github', repository: raw, spec: 'github:' + raw }
-  if (/^git(\+[a-z]+)?:\/\//i.test(raw)) return { kind: 'git', url: raw.replace(/^git\+/i, ''), spec: raw }
-  return { kind: 'github', repository: UPDATE_REPOSITORY, spec: 'github:' + UPDATE_REPOSITORY }
+  const raw = String(env.DSH_PWSH_UPDATE_REGISTRY ?? '').trim()
+  const registry = raw.length === 0 ? UPDATE_REGISTRY : raw.replace(/\/+$/, '')
+  return { kind: 'registry', registry, name: UPDATE_PACKAGE, spec: UPDATE_PACKAGE }
 }
 
-/** 一个发布的、钉住 tag 的安装规格：每个版本一个规格，DSH 会拿它盖掉旧的。 */
-export function releaseSpec(source, tag) {
-  return source.spec + '#' + tag
+/** 一个发布的、钉住版本号的安装规格：每个版本一个规格，DSH 会拿它盖掉旧的。 */
+export function releaseSpec(source, version) {
+  return source.name + '@' + String(version).replace(/^v/, '')
 }
 
 /**
- * 读发布源的全部标签。
+ * 读 registry 上的包摘要（abbreviated metadata）。
+ *
+ * 用 abbreviated 而不是完整文档：完整文档带每个版本的全部 package.json，动辄几百 KB，
+ * 而这里只需要 dist-tags 与版本清单。
  *
  * @param source - 由 updateSource() 给出。
- * @param options - `{ api, signal }`：GitHub API 基址、中止信号。
- * @returns 标签名（GitHub 侧是 API 列出的最新 100 个）。
+ * @param options - `{ fetch, signal }`：可替换的 fetch（测试用）与中止信号。
+ * @returns `{ latest, versions, deprecated }`：dist-tags.latest、版本清单、被废弃的版本集合。
  */
-export async function fetchReleaseTags(source, { api = 'https://api.github.com', signal } = {}) {
-  if (source.kind === 'git') {
-    const output = await new Promise((resolve, reject) => {
-      execFile('git', ['ls-remote', '--tags', '--', source.url], { timeout: 20000, signal, env: { ...process.env, GIT_TERMINAL_PROMPT: '0' } }, (error, stdout) => {
-        if (error) reject(error)
-        else resolve(stdout)
-      })
-    })
-    return output.split('\n').map((line) => /refs\/tags\/([^\s^]+)$/.exec(line.trim())?.[1]).filter(Boolean)
-  }
-  const response = await fetch(api.replace(/\/+$/, '') + '/repos/' + source.repository + '/tags?per_page=100', {
-    headers: { accept: 'application/vnd.github+json', 'user-agent': 'dsh-pwsh-plugin', 'x-github-api-version': '2022-11-28' },
+export async function fetchRegistry(source, { fetch: fetchImpl = globalThis.fetch, signal } = {}) {
+  const url = source.registry + '/' + encodeURIComponent(source.name)
+  const response = await fetchImpl(url, {
+    headers: { accept: 'application/vnd.npm.install-v1+json', 'user-agent': 'dsh-pwsh-plugin' },
     signal,
   })
   if (!response.ok) {
-    const limited = response.status === 403 || response.status === 429
-    throw new Error(limited ? 'GitHub rate limit (HTTP ' + response.status + ')' : 'GitHub answered HTTP ' + response.status)
+    // 404 是「这个包还不存在」，与「网络不通」必须分开说：前者重试一万次也不会好。
+    const reason = response.status === 404 ? 'not published on ' + source.registry : 'registry answered HTTP ' + response.status
+    throw new Error(reason)
   }
   const body = await response.json()
-  if (!Array.isArray(body)) throw new Error('GitHub answered something other than a tag list')
-  return body.map((item) => item?.name).filter((name) => typeof name === 'string')
+  if (body === null || typeof body !== 'object') throw new Error('registry answered something other than a package document')
+  const versions = Object.keys(body.versions ?? {})
+  const deprecated = new Set(versions.filter((version) => typeof body.versions[version]?.deprecated === 'string'))
+  const tagged = body['dist-tags']?.latest
+  return {
+    ...(typeof tagged === 'string' ? { latest: tagged } : {}),
+    versions,
+    deprecated,
+  }
 }
 
 /**
- * 拿标签表与正在跑的版本比一次。
+ * 拿 registry 的摘要与正在跑的版本比一次。
+ *
+ * dist-tags.latest 缺失时从版本清单里挑：只认正式版（预发布不自动推），取语义最高。
  *
- * @param tags - 发布源的标签名。
+ * @param document - fetchRegistry() 的返回。
  * @param current - 本包版本（X.Y.Z）。
  * @returns 有更新的发布时 `{ state: 'available', latest }`，否则 `{ state: 'current', latest? }`。
  */
-export function updateVerdict(tags, current) {
-  const latest = latestRelease(tags)
+export function updateVerdict(document, current) {
+  const versions = Array.isArray(document?.versions) ? document.versions : []
+  const deprecated = document?.deprecated instanceof Set ? document.deprecated : new Set()
+  let latest = typeof document?.latest === 'string' ? document.latest : undefined
+  if (latest === undefined) {
+    for (const version of versions) {
+      const parsed = parseVersion(version)
+      if (parsed === undefined || parsed.prerelease !== undefined || deprecated.has(version)) continue
+      if (latest === undefined || compareVersions(version, latest) > 0) latest = version
+    }
+  }
+  // 被标为 deprecated 的「最新版」不可信：那是发布者自己说的「别用这个」。
+  if (latest !== undefined && deprecated.has(latest)) return { state: 'current', deprecated: latest }
   if (latest !== undefined && compareVersions(latest, current) > 0) return { state: 'available', latest }
   return { state: 'current', ...(latest !== undefined ? { latest } : {}) }
 }
@@ -151,21 +164,21 @@ export function packageVersion(fromUrl = import.meta.url) {
 }
 
 /**
- * 一个更新检查器：定时读发布标签、记下判决、供工具层取用。
+ * 一个更新检查器：定时读 registry、记下判决、供工具层取用。
  *
  * 状态 `state`：off | pending | checking | current | available | failed。
- * 任何失败（断网、限流、没装 git）只记下来给调用方看，绝不抛出，也不提前重试：
+ * 任何失败（断网、镜像挂掉、包还没发布）只记下来给调用方看，绝不抛出，也不提前重试：
  * 下一轮定时检查会再试。
  */
 export class UpdateChecker {
   /**
-   * @param options - `{ env, api, delayMs, intervalMs, log, source, version }`。
+   * @param options - `{ env, fetch, delayMs, intervalMs, log, source, version }`。
    *   `version` 缺省时在**构造这一刻**读一次本包 package.json，之后固定在实例上；
    *   `log` 是接受一行文本的日志函数。
    */
   constructor(options = {}) {
     this.env = options.env ?? process.env
-    this.api = options.api ?? this.env.DSH_PWSH_UPDATE_API ?? undefined
+    this.fetch = options.fetch
     this.delayMs = options.delayMs
     this.intervalMs = options.intervalMs ?? UPDATE_INTERVAL_MS
     this.log = options.log ?? (() => undefined)
@@ -223,9 +236,9 @@ export class UpdateChecker {
     const previous = this.state
     this.state = { ...previous, state: 'checking' }
     const signal = AbortSignal.any([this.abort.signal, AbortSignal.timeout(20000)])
-    this.checking = fetchReleaseTags(this.source, { api: this.api, signal })
-      .then((tags) => {
-        const verdict = updateVerdict(tags, this.version)
+    this.checking = fetchRegistry(this.source, { ...(this.fetch === undefined ? {} : { fetch: this.fetch }), signal })
+      .then((document) => {
+        const verdict = updateVerdict(document, this.version)
         this.state = { ...verdict, checkedAt: new Date().toISOString() }
         this.log('update check: ' + this.state.state + (this.state.latest === undefined ? '' : ' (newest ' + this.state.latest + ', running ' + this.version + ')'))
       }, (error) => {