dsh-plugin-upgrader 1.6.3 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## 1.7.0 — 2026-11-03
+
+- **Every version is judged against the DSH that is actually running, before it is
+  offered.** The host refuses an install whose declared DSH range does not admit this
+  runtime, and on the older replacement path it refuses *after* the bundle has been
+  unloaded — switching a real skin plugin to `0.1.5` (`>=0.1.7-rc.1 <0.1.8-0`) left the
+  package removed from the profile with a dangling patch id. Both directions are covered
+  now. Going *down* the history on a newer DSH marks the releases that no longer admit
+  this runtime and disables their switch button. Going *up* on an older DSH stops
+  offering `latest` as an upgrade when that release does not admit this runtime, and the
+  row says which range it wants instead.
+- **The runtime version comes from the host's own entry point.** A profile's
+  `@deepseek-ai/dsh-app-boot` is a link into an npx cache and measured `0.1.2-rc.1`
+  against a runtime that reports `0.2.1-rc.5`; reading the profile would have marked
+  installable releases uninstallable. When the version cannot be read, nothing is marked
+  — the host stays the judge, and the page only loses a hint.
+- **The rules are the gate's rules.** `engines.dsh` decides alone when present;
+  otherwise every `peerDependencies` range on `@deepseek-ai/dsh` and `@deepseek-ai/dsh-*`
+  must hold, with `workspace:^`/`~`/`*` meaning "this runtime", prereleases included.
+  `src/host/version.ts` implements the matching, checked against `node-semver` over 49
+  ranges × 41 versions (2035 pairs, all agreeing). Three inequalities were wrong before
+  that check — most visibly `~0.1.7-rc.1` admitting `0.1.6`.
+- **A batch no longer disappears when the plugin replaces itself.** Upgrading another
+  plugin is what makes the host re-stage this plugin's own module in a `live` profile, so
+  the install a user was watching could evict the code tracking it: the replacement
+  instance started with an empty job map, answered `unknown-job` for the id the page was
+  polling, and the page reported "lost contact" over an install that finished fine. The
+  batch store now lives on `globalThis` under a stable symbol, so whichever module
+  instance answers knew the batch. Cleanup only clears the run that owns it.
+- **A version the host would refuse is never installed, and a failed replacement puts the
+  old one back.** The page already marked those releases, but a client-side mark cannot
+  stop a request, and the host's gate fires after pnpm has rewritten the lockfile — which
+  is how a refused switch used to end with the package gone. The step now reads the
+  target's declared range *before* touching anything and answers
+  `incompatible-version` with the range it wanted, leaving the profile untouched. When a
+  failure slips past that (the gate is still the final word), the recovery distinguishes
+  the two damages instead of guessing: a package that is still on disk gets re-selected, a
+  package that is gone gets the previous version installed again. The outcome carries
+  `rolledBack` so the log can say what came back, and a rollback that is itself refused
+  says so rather than reporting a clean failure over a missing plugin.
+- **The two ways a restart wait ends badly now say different things.** A pid that never
+  changes means the old process is still answering; a pid that *did* change but a page that
+  cannot reload onto the new host means another restart. Both used to print the first
+  sentence, which sent people looking for a process that was already gone.
+- **One unanswered poll no longer reports a healthy upgrade as lost.** Polling a batch used
+  to stop at the first failed request, and the tab reads "polling stopped" as "the host
+  restarted" — so an install that went on to succeed could still finish with a "lost
+  contact" banner. The host answers from the same thread that runs the install, so a
+  single poll timing out or coming back 5xx during pnpm is ordinary, not fatal. `fetch`
+  rejecting (a keep-alive socket closed under a long install) leaked out of the loop
+  entirely for the same reason. Polls now retry up to four times in a row, and a good poll
+  resets the count, so it takes ~3 s of real silence to give up.
+
 ## 1.6.3 — 2026-11-02
 
 - **"Restart DSH" is now a thing the page can walk you through, instead of advice it

package/README.en.md

@@ -2,6 +2,10 @@
 
 [![npm](https://img.shields.io/npm/v/dsh-plugin-upgrader.svg)](https://www.npmjs.com/package/dsh-plugin-upgrader)
 [![license](https://img.shields.io/npm/l/dsh-plugin-upgrader.svg)](./LICENSE)
+[![dsh.so install verified](https://cdn.dsh.so/badge/install/dsh-plugin-upgrader@0.2.1-rc.5.svg)](https://www.dsh.so/artifact/dsh-plugin-upgrader/)
+[![dsh.so risk: low](https://cdn.dsh.so/badge/dsh-plugin-upgrader.svg)](https://www.dsh.so/artifact/dsh-plugin-upgrader/)
+[![DSH Market listed](https://raw.githubusercontent.com/2BingLing/dsh-market/master/assets/readme/badge-listed-en.svg)](https://dsh.market/)
+[![DeepSeek Harness Plugin](https://deepseekharnessplugins.com/api/badge/zuwenyin/dsh-plugin-upgrader)](https://deepseekharnessplugins.com/plugins/zuwenyin/dsh-plugin-upgrader)
 
 > One-click upgrades plus version history and rollback for the DeepSeek Harness
 > **Plugins** page.
@@ -25,7 +29,10 @@ English · [中文](./README.md)
   runs, and a cancel button that works.
 - **Multi-select upgrade** — tick any subset of plugins and upgrade only those.
 - **Version history / rollback** — expand any plugin to see every published version
-  (with publish date and engine requirement) and switch to it in one click.
+  (with publish date and engine requirement) and switch to it in one click. Every
+  version is first checked against the **DSH you are actually running**: releases
+  this runtime cannot install are marked and their switch button is disabled (the
+  host's gate refuses them only after the bundle has been unloaded).
 - **GitHub links** — the `GH` button opens the plugin's repository; clicking a
   version number opens that version's GitHub release page.
 - **A lagging mirror is named** — versions published upstream but not yet mirrored
@@ -309,6 +316,35 @@ acceptance. `dshOperations` (install / start / uninstall / rollback) follows the
 rule: left out rather than filled with `passed` before there is a per-release run behind
 it.
 
+### Whether each version matches the DSH you run
+
+DSH checks a plugin's declared DSH requirement at install time and **refuses** the install
+when it does not hold. That check happens after the version has been taken out on the
+older replacement path, which is how "I clicked switch and the plugin disappeared" really
+happened. The page therefore reaches the verdict first, under exactly the host's rules:
+
+- when the manifest declares `engines.dsh`, that range alone decides and
+  `peerDependencies` are ignored;
+- otherwise every `peerDependencies` range on `@deepseek-ai/dsh` and
+  `@deepseek-ai/dsh-*` must hold, with `workspace:^` / `~` / `*` meaning "this very
+  runtime";
+- prereleases take part in matching (`includePrerelease`), as they do at the gate.
+
+Both directions are covered: after DSH moves forward, releases in the history that no
+longer admit this runtime are marked "not for this DSH" and their switch button is
+disabled; while DSH stays behind, a `latest` that this runtime cannot install stops
+counting as an upgrade, and the row says which range it wants instead.
+
+The runtime version is read from **the host's own entry point**, not from the profile: a
+profile's `@deepseek-ai/dsh-app-boot` is a link into an npx cache and measured
+`0.1.2-rc.1` against a runtime that reports `0.2.1-rc.5`. When it cannot be read, nothing
+is marked — a guessed version would call installable releases uninstallable.
+
+The matcher is implemented in `src/host/version.ts` and was checked against `node-semver`
+over 49 ranges × 41 versions (2035 pairs, all agreeing). The `semver` package is not
+pulled in because one more runtime dependency is one more supply-chain review, and the
+only semantics needed here are the `includePrerelease` ones.
+
 ## Project layout
 
 ```

package/README.md

@@ -2,6 +2,10 @@
 
 [![npm](https://img.shields.io/npm/v/dsh-plugin-upgrader.svg)](https://www.npmjs.com/package/dsh-plugin-upgrader)
 [![license](https://img.shields.io/npm/l/dsh-plugin-upgrader.svg)](./LICENSE)
+[![dsh.so install verified](https://cdn.dsh.so/badge/install/dsh-plugin-upgrader@0.2.1-rc.5.svg)](https://www.dsh.so/artifact/dsh-plugin-upgrader/)
+[![dsh.so risk: low](https://cdn.dsh.so/badge/dsh-plugin-upgrader.svg)](https://www.dsh.so/artifact/dsh-plugin-upgrader/)
+[![DSH Market 已收录](https://raw.githubusercontent.com/2BingLing/dsh-market/master/assets/readme/badge-listed-zh.svg)](https://dsh.market/)
+[![DeepSeek Harness Plugin](https://deepseekharnessplugins.com/api/badge/zuwenyin/dsh-plugin-upgrader)](https://deepseekharnessplugins.com/plugins/zuwenyin/dsh-plugin-upgrader)
 
 > 给 DeepSeek Harness（DSH）的「插件」页补上**一键升级**和**版本历史 / 回滚**。
 
@@ -20,6 +24,8 @@ DSH 自带的插件页能装、能卸、能看已安装列表，但缺两件事
   每步都有已用时计时和不确定态进度条，卡住时可以一键取消。
 - **多选升级** —— 勾选任意几个插件，只升级选中的这些。
 - **版本历史 / 回滚** —— 展开任意插件即可看到已发布的全部版本（含发布时间与引擎要求），点一下切到那个版本。
+  每个版本都会先跟你**当前跑的 DSH** 比对一次：装不了的版本会被标出来，切换按钮也是禁用的
+  （宿主的兼容性闸门是在 bundle 已经卸下之后才拒绝的，不能让它走到那一步）。
 - **一键跳 GitHub** —— 每行的 `GH` 按钮打开插件仓库主页；点版本号直接进该版本的 GitHub 发布页。
 - **镜像落后会标出来** —— 配置的镜像还没同步、但上游已经发布的版本会单独标一行，
   而不是假装已经是最新版。
@@ -258,6 +264,29 @@ atomic-write: timed out waiting for the writer lock at …/package.json.lock
 `dshOperations`（install / start / uninstall / rollback）同理，没有逐版本的实测记录就留空，
 不写 `passed`。
 
+### 每个版本对不对得上现在的 DSH
+
+DSH 在装插件时会检查插件声明的 DSH 要求，不满足就**拒绝安装**。这个检查发生在版本已经被
+摘掉之后（老路径是先卸再装），所以「点了切换，结果插件没了」是真实发生过的事。因此页面自己
+先算一遍，规则和宿主完全一致：
+
+- 插件声明了 `engines.dsh` 时，**只看它**，`peerDependencies` 被忽略；
+- 否则，`peerDependencies` 里每一个 `@deepseek-ai/dsh`、`@deepseek-ai/dsh-*` 都要满足，
+  `workspace:^` / `~` / `*` 视为「就是当前这个运行时」；
+- 预发布版本参与比较（`includePrerelease`），与宿主的闸门相同。
+
+两种方向都会标出来：DSH 升级之后想**降级**插件，历史里那些不再接受当前运行时的版本会
+被标成「不支持当前 DSH」，切换按钮禁用；DSH 还停在旧版本时想**升级**，如果 `latest`
+不接受当前运行时，它就不再算「可升级」，行上会写明它要的是哪个范围。
+
+运行时版本是从**宿主自己的入口**读的，不是从 profile 读的：profile 里的
+`@deepseek-ai/dsh-app-boot` 是指向 npx 缓存的链接，实测是 `0.1.2-rc.1`，而宿主真正报的是
+`0.2.1-rc.5`。读不到时**什么都不标**——猜一个版本会把本来能装的版本说成不能装。
+
+判定用的是 `src/host/version.ts` 里自己实现的区间匹配，已经在 49 个 range × 41 个版本共
+2035 组上跟 `node-semver` 逐一对过（全部一致）。不引入 `semver` 依赖，是因为这条链路上
+多一个运行时依赖就多一次供应链审阅，而这里需要的语义只有 `includePrerelease` 那一档。
+
 ## 项目结构
 
 ```

package/lib/client.js

@@ -87,6 +87,11 @@ window.__ModuleLoader__.load({
       noHistoryWhy: "\u8FD9\u4E2A\u5305\u4E0D\u662F\u4ECE npm \u6CE8\u518C\u8868\u5B89\u88C5\u7684\uFF0C\u6CA1\u6709\u53D1\u5E03\u5386\u53F2\u3002",
       historyFailed: "\u7248\u672C\u5217\u8868\u8BFB\u53D6\u5931\u8D25\uFF0C\u70B9\u300C\u68C0\u67E5\u66F4\u65B0\u300D\u53EF\u91CD\u8BD5",
       mirrorBehind: "\u955C\u50CF\u6E90\u5C1A\u672A\u540C\u6B65\u8FD9\u4E9B\u5DF2\u53D1\u5E03\u7248\u672C\uFF0C\u88C5\u4E0D\u4E86",
+      incompatible: "\u4E0D\u652F\u6301\u5F53\u524D DSH",
+      incompatibleWhy: (range) => `\u8FD9\u4E2A\u7248\u672C\u8981\u6C42 DSH ${range}\uFF0C\u800C\u5F53\u524D\u5BBF\u4E3B\u4E0D\u6EE1\u8DB3\u3002\u88C5\u4E0A\u53BB\u4F1A\u88AB\u5BBF\u4E3B\u62D2\u7EDD\u3002`,
+      incompatibleLatest: (version, range) => `\u6700\u65B0\u7248 ${version} \u8981\u6C42 DSH ${range}\uFF0C\u5F53\u524D\u5BBF\u4E3B\u4E0D\u6EE1\u8DB3\uFF0C\u6240\u4EE5\u4E0D\u80FD\u5347\u4E0A\u53BB\u3002\u53EF\u4EE5\u5148\u628A DSH \u5347\u5230\u90A3\u4E2A\u8303\u56F4\uFF0C\u6216\u6362\u4E00\u4E2A\u517C\u5BB9\u7684\u7248\u672C\u3002`,
+      runtimeUnknown: "\u8BFB\u4E0D\u5230\u5F53\u524D DSH \u7248\u672C\uFF0C\u65E0\u6CD5\u5224\u65AD\u517C\u5BB9\u6027",
+      requiresDsh: (range) => `\u8981\u6C42 DSH ${range}`,
       versions: (n) => `${n} \u4E2A\u7248\u672C`,
       showingNewest: (n) => `\u5217\u51FA\u6700\u65B0 ${n} \u4E2A`,
       progress: (done, total) => `\u6B63\u5728\u5904\u7406 ${done}/${total}`,
@@ -117,6 +122,7 @@ window.__ModuleLoader__.load({
       restartWaiting: "\u6B63\u5728\u7B49\u5BBF\u4E3B\u56DE\u6765\u2026",
       restartStillOld: "\u5BBF\u4E3B\u8FD8\u6CA1\u6362\u65B0\u8FDB\u7A0B\u3002\u786E\u8BA4\u65E7\u8FDB\u7A0B\u5DF2\u7ECF\u9000\u51FA\uFF0C\u518D\u8BD5\u4E00\u6B21\u3002",
       restartReloadBlocked: "\u5BBF\u4E3B\u5DF2\u7ECF\u91CD\u542F\uFF0C\u4F46\u8FD9\u4E00\u9875\u7684\u63D2\u4EF6\u6E05\u5355\u8FC7\u671F\u4E86\uFF0C\u76F4\u63A5\u5237\u65B0\u4F1A\u542F\u52A8\u5931\u8D25\u3002\u8BF7\u518D\u91CD\u542F\u4E00\u6B21 DSH\u3002",
+      restartReloadRefused: "\u5BBF\u4E3B\u5DF2\u7ECF\u91CD\u542F\uFF0C\u4F46\u8FD9\u4E00\u9875\u6CA1\u6CD5\u81EA\u5DF1\u5237\u65B0\u3002\u624B\u52A8\u5237\u65B0\u4E00\u4E0B\uFF0C\u6216\u8005\u91CD\u542F DSH \u5B8C\u6210\u5347\u7EA7\u3002",
       restartLoading: "\u6B63\u5728\u8BFB\u53D6\u5BBF\u4E3B\u4FE1\u606F\u2026",
       restartLoadFailed: (detail) => `\u8BFB\u4E0D\u5230\u5BBF\u4E3B\u4FE1\u606F\uFF1A${detail}`,
       reloadForAppearance: "\u4E3B\u9898\u63D2\u4EF6\u5DF2\u66F4\u65B0\uFF0C\u6B63\u5728\u91CD\u65B0\u52A0\u8F7D\u9875\u9762\u4EE5\u6062\u590D\u4E3B\u9898\u5916\u89C2\uFF08\u4E3B\u9898\u914D\u7F6E\u4FDD\u5B58\u5728\u78C1\u76D8\u4E0A\uFF0C\u4E0D\u4F1A\u4E22\u5931\uFF09\u3002",
@@ -220,6 +226,11 @@ window.__ModuleLoader__.load({
       noHistoryWhy: "This package was not installed from an npm registry, so it has no published history.",
       historyFailed: 'Could not read the version list; "Check for updates" retries it',
       mirrorBehind: "Your mirror has not synced these published versions yet, so they cannot be installed",
+      incompatible: "Not for this DSH",
+      incompatibleWhy: (range) => `This version requires DSH ${range}, which this host does not satisfy. Installing it would be rejected.`,
+      incompatibleLatest: (version, range) => `The newest release ${version} requires DSH ${range}, which this host does not satisfy, so the upgrade is not offered. Upgrade DSH into that range, or pick a compatible version.`,
+      runtimeUnknown: "Could not read the running DSH version, so compatibility cannot be judged",
+      requiresDsh: (range) => `requires DSH ${range}`,
       versions: (n) => `${n} versions`,
       showingNewest: (n) => `showing newest ${n}`,
       progress: (done, total) => `Working on ${done}/${total}`,
@@ -250,6 +261,7 @@ window.__ModuleLoader__.load({
       restartWaiting: "Waiting for the host to come back\u2026",
       restartStillOld: "The host has not been replaced yet. Check that the old process exited, then try again.",
       restartReloadBlocked: "The host restarted, but this page's plugin list is out of date and reloading it would fail to start. Restart DSH once more.",
+      restartReloadRefused: "The host restarted, but this page could not reload itself. Reload it by hand, or restart DSH to finish the upgrade.",
       restartLoading: "Reading host information\u2026",
       restartLoadFailed: (detail) => `Could not read host information: ${detail}`,
       reloadForAppearance: "The theme plugin was updated; reloading the page to restore its look (its settings are on disk and are not lost).",
@@ -421,15 +433,23 @@ window.__ModuleLoader__.load({
       const started = await readJson(response);
       return started.id;
     }
+    var WATCH_MISS_LIMIT = 4;
     async function watchJob(id, options) {
+      const wait = options.delay ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+      let missed = 0;
       for (; ; ) {
         if (!options.isAlive()) return void 0;
-        const response = await fetch(`${API}/job?id=${encodeURIComponent(id)}`, { credentials: "same-origin" });
-        const snapshot = await readJson(response).catch(() => void 0);
-        if (snapshot === void 0) return void 0;
+        const snapshot = await fetch(`${API}/job?id=${encodeURIComponent(id)}`, { credentials: "same-origin" }).then((response) => readJson(response)).catch(() => void 0);
+        if (snapshot === void 0) {
+          missed += 1;
+          if (missed >= WATCH_MISS_LIMIT) return void 0;
+          await wait(POLL_MS);
+          continue;
+        }
+        missed = 0;
         if (options.isAlive()) options.onSnapshot(snapshot);
         if (snapshot.status !== "running" && snapshot.status !== "queued") return snapshot;
-        await new Promise((resolve) => setTimeout(resolve, POLL_MS));
+        await wait(POLL_MS);
       }
     }
     async function submitJob(steps, watch) {
@@ -772,6 +792,7 @@ window.__ModuleLoader__.load({
     .dsh-pu-tag { font-size: 10px; line-height: 1; padding: 3px 6px; border-radius: 999px; border: 1px solid var(--dsw-alias-border-l1); color: var(--dsw-alias-label-secondary); font-weight: 500; white-space: nowrap; }
     .dsh-pu-tag.is-new { border-color: var(--dsw-alias-brand-primary); color: var(--dsw-alias-brand-primary); background: color-mix(in srgb, var(--dsw-alias-brand-primary) 14%, transparent); }
     .dsh-pu-tag.is-err { border-color: var(--dsw-alias-state-error-primary); color: var(--dsw-alias-state-error-primary); }
+    .dsh-pu-tag.is-foreign { border-color: var(--dsw-alias-state-warn-primary); color: var(--dsw-alias-state-warn-primary); }
     .dsh-pu-vers { display: flex; align-items: center; gap: 6px; font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 11px; color: var(--dsw-alias-label-secondary); flex: none; }
     .dsh-pu-vers b { color: var(--dsw-alias-label-primary); font-weight: 600; }
     .dsh-pu-vers i { font-style: normal; color: var(--dsw-alias-label-tertiary); }
@@ -784,6 +805,7 @@ window.__ModuleLoader__.load({
     .dsh-pu-hist-row { display: flex; align-items: center; gap: 10px; padding: 5px 6px; border-radius: 6px; font-size: 11px; }
     .dsh-pu-hist-row:hover { background: var(--dsw-alias-interactive-bg-hover); }
     .dsh-pu-hist-row.is-current { background: var(--dsw-alias-interactive-bg-hover); box-shadow: inset 2px 0 0 var(--dsw-alias-brand-primary); }
+    .dsh-pu-hist-row.is-foreign .dsh-pu-mono, .dsh-pu-hist-row.is-foreign time { opacity: .6; }
     .dsh-pu-hist-row .dsh-pu-mono { flex: none; min-width: 108px; color: var(--dsw-alias-label-primary); }
     .dsh-pu-link { display: inline-flex; align-items: center; gap: 4px; border: 0; padding: 0; margin: 0; background: none; cursor: pointer; font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; font-size: 11px; color: var(--dsw-alias-link); text-decoration: underline; text-decoration-color: color-mix(in srgb, var(--dsw-alias-link) 40%, transparent); text-underline-offset: 2px; }
     .dsh-pu-link:hover { color: var(--dsw-alias-brand-primary); text-decoration-color: currentColor; }
@@ -905,9 +927,11 @@ window.__ModuleLoader__.load({
       const link = resolveVersionLink(row, version);
       const linkLabel = link !== void 0 && /\/releases\/tag\//.test(link) ? t("githubVersion") : t("githubReleases");
       const title = link === void 0 ? void 0 : `${linkLabel} \u2192${link}`;
+      const foreign = version.compatible === false;
+      const why = foreign ? t("incompatibleWhy", version.requires ?? "") : title;
       return h(
         "div",
-        { className: `dsh-pu-hist-row${version.current ? " is-current" : ""}` },
+        { className: `dsh-pu-hist-row${version.current ? " is-current" : ""}${foreign ? " is-foreign" : ""}` },
         link !== void 0 ? h(
           "button",
           {
@@ -921,6 +945,7 @@ window.__ModuleLoader__.load({
         h("time", null, formatDate(version.time)),
         version.latest ? h("span", { className: "dsh-pu-tag is-new" }, t("latest")) : null,
         version.current ? h("span", { className: "dsh-pu-tag" }, t("current")) : null,
+        foreign ? h("span", { className: "dsh-pu-tag is-foreign", title: why }, t("incompatible")) : null,
         h("span", { className: "dsh-pu-note" }, note),
         link === void 0 ? null : h(
           "button",
@@ -938,7 +963,8 @@ window.__ModuleLoader__.load({
           {
             type: "button",
             className: "dsh-pu-btn is-tiny",
-            disabled: busy || version.current === true,
+            disabled: busy || version.current === true || foreign,
+            title: why,
             onClick: () => onSwitch(row, version.version)
           },
           /*
@@ -1025,6 +1051,20 @@ window.__ModuleLoader__.load({
               },
               `${t("mirrorBehind")}: ${row.mirrorMissing.slice(0, 3).join(", ")}${row.mirrorMissing.length > 3 ? " \u2026" : ""}`
             ) : null,
+            /*
+             * The newest release refuses to run on this DSH version. The row's
+             * upgrade button points at `latest`, so it is no longer an upgrade:
+             * naming the requirement is the only thing that turns "nothing happens"
+             * into something the person can act on.
+             */
+            row.blocked !== void 0 ? h(
+              "div",
+              {
+                className: "dsh-pu-note is-err",
+                title: t("incompatibleLatest", row.blocked.version, row.blocked.requires)
+              },
+              t("incompatibleLatest", row.blocked.version, row.blocked.requires)
+            ) : null,
             failure !== void 0 && retriable ? h(
               "div",
               { className: "dsh-pu-note is-err", title: failure },
@@ -1139,6 +1179,9 @@ window.__ModuleLoader__.load({
     // src/client/components/RestartDialog.ts
     var PROBE_MS = 1e3;
     var WAIT_LIMIT_MS = 12e4;
+    function stalledMessage(problem, t) {
+      return problem.trim() === "" ? t("restartStillOld") : problem;
+    }
     function RestartDialog(props) {
       const { t, onClose } = props;
       const h = getH();
@@ -1173,6 +1216,7 @@ window.__ModuleLoader__.load({
       const waitForRestart = React.useCallback(() => {
         const before = host?.pid;
         if (before === void 0) return;
+        setProblem("");
         setPhase("waiting");
         const startedAt = Date.now();
         const timer = window.setInterval(() => {
@@ -1193,7 +1237,10 @@ window.__ModuleLoader__.load({
                 setPhase("stalled");
               }
             }).then((done) => {
-              if (!done && !blocked) setPhase("stalled");
+              if (!done && !blocked) {
+                setProblem(t("restartReloadRefused"));
+                setPhase("stalled");
+              }
             });
           }).catch(() => {
           });
@@ -1257,7 +1304,7 @@ window.__ModuleLoader__.load({
           ),
           host === void 0 ? null : h("p", { className: "dsh-pu-hint" }, t("restartPid", host.pid, host.profileName ?? "\u2014")),
           phase === "waiting" ? h("p", { className: "dsh-pu-hint" }, t("restartWaiting")) : null,
-          phase === "stalled" ? h("p", { className: "dsh-pu-hint" }, t("restartStillOld")) : null,
+          phase === "stalled" ? h("p", { className: "dsh-pu-hint" }, stalledMessage(problem, t)) : null,
           h(
             "div",
             { className: "dsh-pu-src-foot" },

package/lib/host/install.d.ts

@@ -26,6 +26,8 @@ export interface StepOutcome {
     detail?: string;
     pendingBuilds?: string[];
     warnings?: string[];
+    /** The version this step put back after destroying the one that was there. */
+    rolledBack?: string;
     packageResult?: {
         exitCode: number;
         kind?: string;
@@ -35,6 +37,21 @@ export interface StepOutcome {
 }
 /** Allowed per-step actions. */
 export declare const ACTIONS: Set<string>;
+/**
+ * One version's DSH requirement, looked up only when a step is about to run.
+ *
+ * The lookup is injected rather than imported so this module keeps no registry
+ * client: the caller already has the packument cache and the chosen registry,
+ * and asking the network here would duplicate both.
+ */
+export interface InstallGuard {
+    /** The DSH build this process runs, when it could be read. */
+    runtimeVersion?: string | undefined;
+    /** The requirement `name@version` declares, or `undefined` when unknown. */
+    requirementOf: (name: string, version: string) => Promise<{
+        range: string;
+    } | undefined>;
+}
 /**
  * Re-apply the enabled state a step asked for after the package was replaced.
  *
@@ -78,9 +95,10 @@ export declare function restoreSelection(manager: PluginManager, name: string, l
  * @param log - progress sink.
  * @param announce - receives the request id the step installs under.
  * @param registry - the registry chosen in this plugin's config, if any.
+ * @param guard - the compatibility check, when the caller can supply one.
  * @returns the outcome record.
  */
-export declare function runStep(manager: PluginManager, step: StepRecord, log: LogSink, announce?: RequestIdSink, registry?: string): Promise<StepOutcome>;
+export declare function runStep(manager: PluginManager, step: StepRecord, log: LogSink, announce?: RequestIdSink, registry?: string, guard?: InstallGuard): Promise<StepOutcome>;
 /**
  * Whether a step names something this plugin is willing to install.
  *

package/lib/host/install.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../src/host/install.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAc,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAGvF,iCAAiC;AACjC,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;AAE/C;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAA;AAEvD,yDAAyD;AACzD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,EAAE,EAAE,OAAO,CAAA;IACX,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,WAAW,CAAC,EAAE,YAAY,CAAC,aAAa,CAAC,CAAA;IACzC,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,KAAK,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAA;IACvC,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;IACxB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,aAAa,CAAC,EAAE;QACd,QAAQ,EAAE,MAAM,CAAA;QAChB,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,QAAQ,CAAC,EAAE,OAAO,CAAA;QAClB,IAAI,CAAC,EAAE,MAAM,CAAA;KACd,CAAA;CACF;AAED,gCAAgC;AAChC,eAAO,MAAM,OAAO,aAAyC,CAAA;AA2L7D;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,EAC9B,MAAM,EAAE,OAAO,GAAG,SAAS,EAC3B,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAuB9B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,OAAO,CAAC,CAmBlB;AAsGD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,OAAO,CAC3B,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,OAAO,EACZ,QAAQ,CAAC,EAAE,aAAa,EACxB,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,WAAW,CAAC,CAqJtB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAM9D"}
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../../src/host/install.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAc,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,cAAc,CAAA;AAIvF,iCAAiC;AACjC,MAAM,MAAM,OAAO,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAA;AAE/C;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAA;AAEvD,yDAAyD;AACzD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,EAAE,EAAE,OAAO,CAAA;IACX,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,WAAW,CAAC,EAAE,YAAY,CAAC,aAAa,CAAC,CAAA;IACzC,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,KAAK,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAA;IACvC,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;IACxB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,aAAa,CAAC,EAAE;QACd,QAAQ,EAAE,MAAM,CAAA;QAChB,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,QAAQ,CAAC,EAAE,OAAO,CAAA;QAClB,IAAI,CAAC,EAAE,MAAM,CAAA;KACd,CAAA;CACF;AAED,gCAAgC;AAChC,eAAO,MAAM,OAAO,aAAyC,CAAA;AA+H7D;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,8DAA8D;IAC9D,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC,4EAA4E;IAC5E,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC,CAAA;CACzF;AA8GD;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,EAC9B,MAAM,EAAE,OAAO,GAAG,SAAS,EAC3B,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAuB9B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,OAAO,GACX,OAAO,CAAC,OAAO,CAAC,CAmBlB;AA0MD;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,OAAO,CAC3B,OAAO,EAAE,aAAa,EACtB,IAAI,EAAE,UAAU,EAChB,GAAG,EAAE,OAAO,EACZ,QAAQ,CAAC,EAAE,aAAa,EACxB,QAAQ,CAAC,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE,YAAY,GACnB,OAAO,CAAC,WAAW,CAAC,CAuLtB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAM9D"}

package/lib/host/install.js

@@ -9,10 +9,20 @@
  */
 import { explainLockTimeout } from './lock.js';
 import { confirmDependency, dropDependency, profileDirFrom, restoreDependency } from './manifest.js';
+import { satisfiesRange } from './version.js';
 /** Allowed per-step actions. */
 export const ACTIONS = new Set(['upgrade', 'switch']);
 /** The manager's code for "a live loader fiber still owns this bundle". */
 const IN_USE = 'bundle-in-use';
+/**
+ * The manager's code for "this version does not admit the running DSH".
+ *
+ * Worth naming: it is the one refusal that is *certain* to repeat. Every other
+ * failure might be a flaky registry or a busy lock, but a version whose declared
+ * range rejects this runtime will be rejected again no matter how many times the
+ * replacement is retried — so retrying it by removing first only destroys more.
+ */
+const INCOMPATIBLE = 'incompatible-version';
 /**
  * Read the manager's failure code off a result or a throw.
  *
@@ -86,6 +96,43 @@ async function readsAsEnabled(manager, name) {
         return undefined;
     }
 }
+/**
+ * One bundle as the manager currently reports it.
+ *
+ * "Absent" and "present but with no version" have to be told apart: the first
+ * means a rollback has to reinstall, the second only means the listing did not
+ * carry a version — re-selecting is still the right repair there.
+ *
+ * @param manager - the plugin manager.
+ * @param name - the bundle to read.
+ * @returns the entry, or `undefined` when it is not listed at all.
+ */
+async function bundleOf(manager, name) {
+    try {
+        const bundles = await manager.listBundles();
+        const list = Array.isArray(bundles) ? bundles : [];
+        return list.find((item) => item?.name === name);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The version a bundle currently has on disk, read before anything is removed.
+ *
+ * This is the value a failed replacement rolls back to. It has to be read up
+ * front: after `removeForReplacement` the package is gone, and the manager has
+ * nothing left to report a version for — which is precisely the moment the
+ * rollback needs to know what to put back.
+ *
+ * @param manager - the plugin manager.
+ * @param name - the bundle to read.
+ * @returns the installed version, or `undefined` when it cannot be read.
+ */
+async function installedVersion(manager, name) {
+    const version = (await bundleOf(manager, name))?.version;
+    return typeof version === 'string' && version.trim() !== '' ? version.trim() : undefined;
+}
 /**
  * Call `setBundleEnabled`, reporting a refusal instead of throwing it.
  *
@@ -267,6 +314,86 @@ export async function restoreSelection(manager, name, log) {
     }
     return true;
 }
+/**
+ * Put the previous version back after a replacement destroyed it.
+ *
+ * The in-place route only knows the install was refused after pnpm has run, and
+ * the manager's compatibility gate runs *after* pnpm rewrote the lockfile — so a
+ * version the host refuses can leave the package gone while the manifest entry
+ * is the only thing that got restored. The plugin then disappears from the page
+ * with no way back except reinstalling by hand.
+ *
+ * Installing the old version again is the repair that actually works: pnpm puts
+ * the files back, and the manager activates them exactly as it did before. It is
+ * deliberately attempted for every failure that follows a removal, not only the
+ * compatibility one — an entry pointing at a version that is not on disk is
+ * broken either way.
+ *
+ * Best effort: the step has already failed for its own reason, and a rollback
+ * that also fails must not replace that reason.
+ *
+ * @param manager - the plugin manager.
+ * @param step - the step that failed.
+ * @param previous - the version that was installed before the step ran.
+ * @param options - the install options the caller already built.
+ * @param log - progress sink.
+ * @param announce - receives the request id the rollback installs under.
+ * @returns whether the old version is back.
+ */
+async function rollBack(manager, step, previous, options, log, announce) {
+    const spec = `${step.name}@${previous}`;
+    const requestId = globalThis.crypto?.randomUUID?.() ?? `pu-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    announce?.(requestId);
+    log(`roll back: install ${spec} again (the failed replacement already removed it)`);
+    try {
+        const result = await manager.installBundle(spec, { ...options, requestId });
+        const back = result?.application === 'applied' || result?.application === 'restart-required';
+        if (result?.error !== undefined || !back) {
+            log(`  ! rollback refused (${result?.error?.code ?? 'no change'}); ${step.name}@${previous} is not installed — ` +
+                'install it again from the Installed tab');
+            return false;
+        }
+        log(`  ✓ ${step.name}@${previous} is back where it was`);
+        return true;
+    }
+    catch (error) {
+        log(`  ! rollback failed: ${describeFailure(error instanceof Error ? error.message : String(error))}; ` +
+            `${step.name}@${previous} is not installed`);
+        return false;
+    }
+}
+/**
+ * Put the profile back the way the step found it, whatever it managed to break.
+ *
+ * Two different damages need two different repairs, and picking the wrong one
+ * makes things worse:
+ *
+ * - the package is still on disk but was deselected — re-selecting it is enough,
+ *   and installing an old version over it would be a pointless pnpm run;
+ * - the package is gone — re-selecting nothing, which is what the old code did,
+ *   leaves an entry in `dependencies` that nothing can load, so the plugin is
+ *   simply missing from the page.
+ *
+ * @param manager - the plugin manager.
+ * @param step - the step that failed.
+ * @param previous - the version installed before the step ran, when known.
+ * @param options - the install options the caller already built.
+ * @param log - progress sink.
+ * @param announce - receives the request id a rollback installs under.
+ * @returns whether the profile was put back.
+ */
+async function recover(manager, step, previous, options, log, announce) {
+    const entry = await bundleOf(manager, step.name);
+    if (entry !== undefined && entry.installed !== false) {
+        await restoreSelection(manager, step.name, log);
+        return false;
+    }
+    if (previous === undefined) {
+        log(`  ! ${step.name} is no longer installed, and its previous version was not recorded`);
+        return false;
+    }
+    return rollBack(manager, step, previous, options, log, announce);
+}
 /**
  * Replace a version without removing the bundle first.
  *
@@ -367,9 +494,10 @@ async function replaceWithoutRemoval(manager, step, options, log, announce) {
  * @param log - progress sink.
  * @param announce - receives the request id the step installs under.
  * @param registry - the registry chosen in this plugin's config, if any.
+ * @param guard - the compatibility check, when the caller can supply one.
  * @returns the outcome record.
  */
-export async function runStep(manager, step, log, announce, registry) {
+export async function runStep(manager, step, log, announce, registry, guard) {
     const spec = `${step.name}@${step.version}`;
     const requestId = globalThis.crypto?.randomUUID?.() ?? `pu-${Date.now()}-${Math.random().toString(36).slice(2)}`;
     announce?.(requestId);
@@ -379,6 +507,29 @@ export async function runStep(manager, step, log, announce, registry) {
     const base = { name: step.name, version: step.version, spec, requestId };
     const restoreEnabled = typeof step.enabled === 'boolean' ? step.enabled : undefined;
     log(`install ${spec}`);
+    /*
+     * Ask the version itself before touching anything.
+     *
+     * The host's own gate is the final word and it runs inside pnpm's wake-up, so
+     * without this check a refusal arrives after the manager has already deselected
+     * — or removed — the bundle. Reading the published requirement first turns
+     * "your plugin is gone" into "this version was never going to work", which is
+     * the difference between a repair and a loss.
+     */
+    const requirement = guard === undefined ? undefined : await guard.requirementOf(step.name, step.version);
+    if (requirement !== undefined && guard?.runtimeVersion !== undefined) {
+        if (!satisfiesRange(guard.runtimeVersion, requirement.range)) {
+            log(`  ! ${spec} declares ${requirement.range}, which excludes DSH ${guard.runtimeVersion}; nothing was changed`);
+            return {
+                ...base,
+                ok: false,
+                application: 'failed',
+                stage: 'install',
+                message: INCOMPATIBLE,
+                detail: requirement.range,
+            };
+        }
+    }
     const options = {
         saveExact: true,
         ...(restoreEnabled === undefined ? {} : { enabled: restoreEnabled }),
@@ -392,6 +543,12 @@ export async function runStep(manager, step, log, announce, registry) {
         ...(typeof registry === 'string' && registry.trim() !== '' ? { registry: registry.trim() } : {}),
     };
     let result;
+    /*
+     * Read the version on disk *before* the manager can take it away. This is the
+     * value a failed replacement rolls back to, and once `removeForReplacement`
+     * has run there is nothing left to ask.
+     */
+    const previous = await installedVersion(manager, step.name);
     try {
         result = await manager.installBundle(spec, { ...options, requestId });
     }
@@ -462,12 +619,12 @@ export async function runStep(manager, step, log, announce, registry) {
         }
         catch (error) {
             /*
-             * The removal above already deselected the bundle, so a throw here leaves
-             * it installed-but-unloaded: still in `dependencies`, still on disk, no
-             * longer selected, and therefore invisible on the page. Put the selection
-             * back before reporting, or the operator has to repair it by hand.
+             * The removal above happened for real, so a throw here can leave the
+             * plugin gone. `recover` tells the two damages apart: still-on-disk means
+             * re-select it, gone means install the previous version again. Confusing
+             * them is what made "upgrade failed" also mean "plugin disappeared".
              */
-            await restoreSelection(manager, step.name, log);
+            const back = await recover(manager, step, previous, options, log, announce);
             return {
                 ...base,
                 requestId: retryId,
@@ -475,6 +632,7 @@ export async function runStep(manager, step, log, announce, registry) {
                 stage: 'install',
                 application: 'failed',
                 message: `install after removal failed: ${describeFailure(error instanceof Error ? error.message : String(error))}`,
+                ...(back ? { rolledBack: previous } : {}),
             };
         }
     }
@@ -483,8 +641,7 @@ export async function runStep(manager, step, log, announce, registry) {
      * removal already done. Same hazard, same repair; the reported reason stays
      * whatever the manager said.
      */
-    if (result?.error !== undefined)
-        await restoreSelection(manager, step.name, log);
+    const restored = result?.error === undefined ? false : await recover(manager, step, previous, options, log, announce);
     // Only a change that landed has an enabled state to restore: a failed install
     // left nothing behind, and asking to toggle it would report a second, louder
     // error (`operation-error`) for a package that was never added.
@@ -494,6 +651,7 @@ export async function runStep(manager, step, log, announce, registry) {
         ...base,
         ...(enabled === undefined ? {} : { enabled }),
         ok: installed,
+        ...(restored ? { rolledBack: previous } : {}),
         application: result?.application,
         changed: result?.changed === true,
         stage: result?.stage,