@1e0zj/dsh-plugin-mall 0.3.2 → 0.3.3

package/README.md

@@ -73,9 +73,11 @@ node <profile>/node_modules/@1e0zj/dsh-plugin-mall/src/cli.js guard launch --pro
 
 **A plain `dsh web` already resolves pending installs.** The marketplace plugin runs
 recovery when it loads: reaching that point proves dsh booted far enough to compose
-the profile, so the pending marker is committed (or rolled back when the profile
-fails validation). Without this a single install would wedge the profile — every
-later install and uninstall refuses while a marker is outstanding.
+the profile, so the pending marker is committed — or rolled back, either because the
+profile fails validation or because the install was left paused at the build-script
+approval gate (an unapproved install is never committed, however healthy it looks).
+Without this a single install would wedge the profile — every later install and
+uninstall refuses while a marker is outstanding.
 
 **`guard launch` is still strictly better**, because it also covers what a plain
 start cannot: a plugin that boots fine and then crashes seconds later. It checks the
@@ -83,13 +85,42 @@ profile's pending-install marker before starting the command after `--`:
 
 - **No pending install** — the command runs as-is, inheriting the terminal, and its exit code is preserved.
 - **Clearly broken on disk** — the profile is rolled back to its pre-install snapshot *before* launch, then the command starts on the restored state.
-- **Alive through the grace period** (default **10 seconds**; `--grace-ms <ms>` to change) — the pending snapshot is committed and the wrapper keeps waiting on the process.
+- **Alive through the grace period** (default **10 seconds**; `--grace-ms <ms>` to change) — the pending snapshot is committed and the wrapper keeps waiting on the process. An install still paused at the approval gate is rolled back instead: surviving probation only proves the JS loads, not that you approved its build scripts.
 - **Exits 0 inside the grace period** (one-shot command) — the pending snapshot is committed.
 - **Crashes or exits nonzero inside the grace period** — the profile is rolled back and the *exact same command* is restarted once with the restored state (never in a loop); the restarted process's exit code is preserved. SIGINT/SIGTERM are forwarded to the child where the platform supports it; on Windows `.cmd`/`.bat` shims go through `%ComSpec%` with strict per-argument quoting.
 
 Limitations: the grace window is the probation period — a failure that only surfaces **after** it (a plugin that crashes minutes in, or on a specific interaction) cannot be rolled back automatically, because committing deletes the active snapshot and `guard recover` then has nothing to restore. `guard validate` still diagnoses the on-disk state, but a post-commit failure needs manual repair — uninstall and reinstall the plugin, or restore a backup you kept separately. Both commands do only **static on-disk validation**; neither proves the plugin actually loads. A corrupt pending marker fails closed: the command is not launched and no unvalidated path is deleted. Preserve the snapshot and repair or restore a trustworthy marker, then run `guard recover`; quarantine the marker only after you have independently verified the profile, or decided to abandon automatic recovery.
 
 
+## dsh won't start after an update? (affects 0.2.0 – 0.3.2, fixed in 0.3.3)
+
+Symptom: `dsh web` exits with `cannot resolve profile bundle "<package>"`.
+
+Cause: **updating an already-installed plugin** into a rollback (most often the
+target carries build scripts and the flow paused at the approval card) could lose
+the package — the rollback's reinstall of the old version was fooled by pnpm's
+"Already up to date" short-circuit, so the plugin left node_modules while its
+bundles declaration stayed. Fresh installs and removals are unaffected.
+
+Recovery: add the package back exactly as the profile's `package.json` declares
+it, then run `dsh web`.
+
+```bash
+# <profile> = %USERPROFILE%\.dsh\profiles\web  or  ~/.dsh/profiles/web
+# npm package — package.json says "dsh-better-sidebar": "^0.13.1"
+pnpm --dir <profile> add "dsh-better-sidebar@^0.13.1" --ignore-scripts
+# GitHub source — package.json says "dsh-at-file": "github:omdsh-dev/dsh-at-file"
+pnpm --dir <profile> add "github:omdsh-dev/dsh-at-file" --ignore-scripts
+```
+
+> Do not reach for 0.3.2's `dsh-plugin-guard recover` here. Its per-package
+> fallback refuses `^` (a cmd metacharacter) and skips `github:` entirely, and
+> pnpm writes nearly every dependency with one or the other — so the fallback
+> never fires and recovery fails closed. Fixed on main: the fallback now pins the
+> version (or commit) the lockfile resolved. Fixed in 0.3.3 — on that version
+> `dsh-plugin-guard recover` does repair this.
+
+
 ## Agent tools
 
 | Tool | What it does |
@@ -191,22 +222,48 @@ node <profile>/node_modules/@1e0zj/dsh-plugin-mall/src/cli.js guard launch --pro
 ```
 
 **普通的 `dsh web` 就会了结 pending 安装。** 本插件加载时即执行恢复——能加载
-本身就证明 dsh 已经组装好 profile、启动到了这一步，于是提交 pending 标记
-（profile 校验不过则回滚）。没有这一步的话，装完一个插件就会把 profile 卡住：
-只要标记还在，之后所有安装和卸载都会被拒绝。
+本身就证明 dsh 已经组装好 profile、启动到了这一步，于是提交 pending 标记；两种
+情况改为回滚：profile 校验不过，或者那次安装停在构建脚本批准闸而未获批准
+（没批准的安装绝不提交，哪怕它看起来一切正常）。没有这一步的话，装完一个插件
+就会把 profile 卡住：只要标记还在，之后所有安装和卸载都会被拒绝。
 
 **`guard launch` 仍然更强**，因为它覆盖普通启动覆盖不了的情况：插件启动正常、
 几秒后才崩。它在启动 `--` 之后的命令前检查该 profile 的 pending 安装标记：
 
 - **无 pending 安装** —— 命令原样运行（继承终端），透传退出码；
 - **静态校验明显过不了** —— 启动*之前*先把 profile 回滚到安装前快照，再在恢复后的状态上启动；
-- **活过缓刑期**（默认 **10 秒**，`--grace-ms <ms>` 可调）—— 提交 pending 快照，包装器继续守候该进程；
+- **活过缓刑期**（默认 **10 秒**，`--grace-ms <ms>` 可调）—— 提交 pending 快照，包装器继续守候该进程；但仍停在批准闸的安装改为回滚：活过缓刑期只证明 JS 能加载，不证明你批准了它的构建脚本；
 - **缓刑期内以 0 退出**（一次性命令）—— 同样提交 pending 快照；
 - **缓刑期内崩溃或非零退出** —— 回滚 profile，并用恢复后的状态**原样重启同一命令一次**（绝不循环），透传重启进程的退出码。支持的平台会把 SIGINT/SIGTERM 转发给子进程；Windows 上 `.cmd`/`.bat` 经 `%ComSpec%` 启动，逐参数严格加引号。
 
 限制：缓刑期就是观察期——**之后**才暴露的故障（跑了几分钟才崩、或某个特定操作才触发）无法自动回滚：提交会删掉当前快照，此时 `guard recover` 已无可恢复的东西。`guard validate` 仍能诊断落盘状态，但提交之后的故障只能手工修复——卸载并重装插件（或恢复你另行保留的备份）。两条命令都只做**静态落盘校验**，都不证明插件真的能加载。pending 标记损坏时关闭式失败：不启动命令、不删除任何未校验路径。要**保留快照**、修复或恢复一个可信的标记后再跑 `guard recover`；只有在你已经独立核实过 profile、或决定放弃自动恢复之后，才去隔离（删除/移走）标记。
 
 
+## 升级后 dsh 起不来？（0.2.0 – 0.3.2 受影响，0.3.3 已修复）
+
+症状：`dsh web` 报 `cannot resolve profile bundle "<包名>"` 直接退出。
+
+原因：**更新已装插件**时若走到回滚（最常见：目标插件带构建脚本、停在批准卡），
+回滚里「装回旧版本」的一步会被 pnpm 的 "Already up to date" 空转骗过——包从
+node_modules 消失而 bundles 声明还在。新装、卸载不受影响。
+
+恢复：照 profile `package.json` 里原本的写法把包装回去，然后 `dsh web`。
+
+```bash
+# <profile> = %USERPROFILE%\.dsh\profiles\web 或 ~/.dsh/profiles/web
+# npm 包 —— package.json 里是 "dsh-better-sidebar": "^0.13.1"
+pnpm --dir <profile> add "dsh-better-sidebar@^0.13.1" --ignore-scripts
+# GitHub 源 —— package.json 里是 "dsh-at-file": "github:omdsh-dev/dsh-at-file"
+pnpm --dir <profile> add "github:omdsh-dev/dsh-at-file" --ignore-scripts
+```
+
+> 别指望 0.3.2 的 `dsh-plugin-guard recover` 修这个：它的 per-package 兜底会
+> 拒掉 `^`（cmd 转义符），`github:` 更是整个跳过，而 pnpm 存依赖几乎不是前者
+> 就是后者——兜底一次也不会触发，恢复只会 fail-closed。main 上已修：兜底改钉
+> lockfile 解析出的版本（或 commit）。0.3.3 已修复——那个版本的
+> `dsh-plugin-guard recover` 确实能修这个故障。
+
+
 ## 工作原理
 
 - 双面包（dual-face）插件：`dsh.bundle` 半边挂在 **host 平面**（profile bundle 层），

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1e0zj/dsh-plugin-mall",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "dsh 插件市场：搜索 GitHub dsh-plugin 话题下的插件仓库，一键安装到本地 dsh profile（agent 工具 + 设置页插件市场 tab）",
   "type": "module",
   "main": "src/index.js",

package/src/cli.js

@@ -40,13 +40,18 @@ import { tmpdir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import {
+  clearPendingApprovalPause,
   commitPendingSnapshot,
   createProfileSnapshot,
+  describeRollbackRebuild,
   listPendingSnapshots,
+  markPendingApprovalPause,
   markPendingSnapshot,
+  pendingApprovalPaused,
   pnpmGuardEnv,
   preflightInstall,
   readPendingSnapshot,
+  readValidatedPendingSnapshot,
   recoverAll,
   recoverProfile,
   resolveDshHome,
@@ -380,6 +385,8 @@ function cmdRecover({ home, profileDir }) {
     } else if (entry.action === "rolled-back") {
       console.log(`ROLLED BACK ${scope}: ${(entry.issues ?? []).map((issueEntry) => issueEntry.title).join("; ") || "profile would not load"}`);
       if (entry.removed?.length) console.log(`  removed from node_modules: ${entry.removed.join(", ")}`);
+      const rebuild = describeRollbackRebuild(entry.rebuild);
+      if (rebuild !== undefined) console.log(`  node_modules rebuild: ${rebuild}`);
     } else if (entry.action === "none") {
       console.log(`no pending  ${scope}`);
     } else {
@@ -693,9 +700,25 @@ async function runPlain(command, args) {
  * Commit the pending snapshot once startup probation passes. A commit failure
  * is a warning, not a launch failure — the process is already running and
  * healthy, and the marker simply stays pending for the next launch.
+ *
+ * An approval-paused marker must never commit: the new version sits there with
+ * its build scripts never approved, so staying alive only proves the JS loads.
+ * Roll it back to the pre-install snapshot instead (a rollback failure keeps
+ * the marker for the next attempt, same as recoverProfile).
  */
 function commitLaunchSnapshot(profileDir) {
   try {
+    let pending;
+    try {
+      pending = readValidatedPendingSnapshot(profileDir);
+    } catch {
+      pending = undefined; // unreadable marker: leave it to guard recover
+    }
+    if (pending !== undefined && pendingApprovalPaused(pending) !== undefined) {
+      rollbackPendingSnapshot(profileDir);
+      console.log(`[guard] startup probation passed, but the install was abandoned at the approval gate — profile rolled back for ${profileDir}`);
+      return;
+    }
     commitPendingSnapshot(profileDir);
     console.log(`[guard] startup probation passed — pending snapshot committed for ${profileDir}`);
   } catch (error) {
@@ -1156,6 +1179,31 @@ async function selfTest() {
     const validated = validateInstalledProfile(profileDir);
     if (validated.ok !== true) throw new Error("healthy profile should validate clean (cli)");
 
+    // commitLaunchSnapshot: a marker paused at the approval gate must roll back
+    // instead of committing even after a healthy probation — the candidate sits
+    // there with its build scripts never approved, and committing would delete
+    // the only rollback snapshot. Layout keeps the candidate a NEW dependency
+    // so the rollback prunes node_modules without spawning pnpm.
+    {
+      const pauseProfile = join(root, "pause-home", "profiles", "web");
+      mkdirSync(join(pauseProfile, "node_modules"), { recursive: true });
+      writeFileSync(join(pauseProfile, "package.json"), JSON.stringify({ dependencies: {} }));
+      writeFileSync(join(pauseProfile, "cordis.patch.yml"), "[]\n");
+      const snap = createProfileSnapshot(pauseProfile, { fixture: true });
+      markPendingSnapshot(snap, { spec: "good@2.0.0", preflight: { candidate: { name: "good", version: "2.0.0", kind: "bundle" } } });
+      // 暂停现场：候选已装、声明已写，静态校验过得去——正是不许提交的原因。
+      writeFileSync(join(pauseProfile, "package.json"), JSON.stringify({ dependencies: { good: "^2.0.0" } }));
+      mkdirSync(join(pauseProfile, "node_modules", "good"), { recursive: true });
+      writeFileSync(join(pauseProfile, "node_modules", "good", "package.json"), JSON.stringify({ name: "good", version: "2.0.0" }));
+      markPendingApprovalPause(pauseProfile);
+      commitLaunchSnapshot(pauseProfile);
+      if (readPendingSnapshot(pauseProfile) !== undefined) throw new Error("commitLaunchSnapshot must consume (roll back) an approval-paused marker");
+      if (existsSync(snap.dir)) throw new Error("the paused rollback must delete the snapshot dir");
+      if (JSON.parse(readFileSync(join(pauseProfile, "package.json"), "utf8")).dependencies?.good !== undefined) {
+        throw new Error("the paused rollback must restore the pre-install manifest");
+      }
+    }
+
     // guarded remove: exact official argv + shell:false runner seam, snapshot
     // before mutation, immediate commit after a statically safe removal.
     {

package/src/client.js

@@ -188,6 +188,7 @@ window.__ModuleLoader__.load({
                 status: snapshot.status,
                 detail: snapshot.detail,
                 needsApproval: snapshot.needsApproval,
+                staleOnRestart: snapshot.staleOnRestart,
                 approvalToken: snapshot.approvalToken,
                 kind: snapshot.kind,
                 output: output,
@@ -249,6 +250,7 @@ window.__ModuleLoader__.load({
             spec: snap.spec,
             detail: snap.detail,
             needsApproval: snap.needsApproval,
+            staleOnRestart: snap.staleOnRestart,
             approvalToken: snap.approvalToken,
             kind: snap.kind,
             output: entry.output || "",
@@ -259,9 +261,13 @@ window.__ModuleLoader__.load({
         // 不在本次服务器列表里的条目属于上一次宿主会话（进程重启后
         // tracker 清空）。已兑现的直接翻篇撤掉：completed 的重启已经
         // 发生；needsApproval 暂停的批准卡片已随进程失效（事务由启动
-        // 恢复处置），留着只会让人点一个必然失败的按钮。running 的标
-        // 中断，别让轮询对着不存在的 id 空转。failed 保留——日志还有
-        // 排障价值。这个判据不依赖 finishedAt（旧镜像里没有该字段）。
+        // 恢复处置），留着只会让人点一个必然失败的按钮；staleOnRestart
+        // 的失败是「被另一个未了结事务挡住」，而那个事务必然已被启动恢复
+        // 处置——它的报错是现在时写的（「还没做完」「现在无法安装」），
+        // 留到重启之后会被当成当前状态读，而它描述的情形已经不存在。
+        // running 的标中断，别让轮询对着不存在的 id 空转。其余 failed
+        // 保留——网络、预检阻断这类原因重启后可能仍然成立，日志有排障
+        // 价值。这个判据不依赖 finishedAt（旧镜像里没有该字段）。
         for (var key in next) {
           if (serverIds[key]) continue;
           var stale = next[key];
@@ -270,7 +276,9 @@ window.__ModuleLoader__.load({
               status: "killed",
               detail: "宿主进程已重启，该任务的记录随之丢失",
             });
-          } else if (stale.status === "completed" || (Array.isArray(stale.needsApproval) && stale.needsApproval.length > 0)) {
+          } else if (stale.status === "completed"
+            || stale.staleOnRestart === true
+            || (Array.isArray(stale.needsApproval) && stale.needsApproval.length > 0)) {
             delete next[key];
           }
         }

package/src/guard.js

@@ -1008,6 +1008,32 @@ function addedDependencyNames(pending, originalDependencies = pending?.dependenc
 // that used to live there. Restoring manifest + lockfile is then only half the
 // job: the tree must be rebuilt from the restored lockfile, or the profile is
 // left declaring a dependency nothing provides.
+//
+// WHEN the reconcile short-circuits (the reason the per-package add fallback
+// below exists at all). pnpm decides "up to date" by comparing its virtual
+// store bookkeeping (node_modules/.pnpm/lock.yaml) against the profile's
+// pnpm-lock.yaml — and reconcileNodeModules deletes node_modules/<name>
+// WITHOUT touching either. So the outcome hinges on how far the failed install
+// got before the rollback:
+//
+//   pnpm add SUCCEEDED (e.g. it installed the new version and only then
+//     stopped at the build-script approval gate) — .pnpm/lock.yaml already
+//     records the new version, the restored pnpm-lock.yaml records the old
+//     one, they disagree, pnpm does the work and relinks the old copy. The
+//     fallback never runs.
+//
+//   pnpm add FAILED EARLY (or never ran) — .pnpm/lock.yaml still matches the
+//     restored pnpm-lock.yaml, so pnpm answers `install --frozen` with exit 0
+//     and does nothing while the package it was asked about is gone. Only the
+//     per-package add relinks it.
+//
+// This is why an approval-pause rollback is the WRONG scenario to validate the
+// fallback with: it is precisely the branch that never reaches it (confirmed on
+// a real profile — reconcile exit 0, package restored, fallback untouched). To
+// exercise it, reproduce the second row: install the package, leave
+// .pnpm/lock.yaml in agreement with pnpm-lock.yaml, mark a pending UPDATE
+// transaction, and roll back without running any pnpm in between. Both the `^`
+// range and the github: pinning paths were verified that way.
 
 /**
  * Env for any pnpm the guard (or its callers) spawns: peer auto-install stays
@@ -1062,26 +1088,86 @@ function fallbackAddArgs(target) {
 }
 
 /**
- * The argv target for a fallback `pnpm add` of one restored dependency, or
- * undefined when that spec cannot be added offline and safely. Semver ranges
- * become `name@range`, local file:/link: paths add by the spec itself;
- * github:/git+ specs need the network or git and stay fail-closed, and
- * anything carrying shell metacharacters (a multi-clause range like
- * `^1.0.0 || ^2.0.0` contains spaces and pipes) is skipped — the
- * shell-wrapped pnpm spawn joins argv with spaces without quoting.
+ * The lockfile's pinned resolution for one direct dependency, or undefined. In
+ * a rollback the lockfile has just been restored from the snapshot, so this IS
+ * the exact thing the rollback is trying to get back — not a guess. For a
+ * semver dependency it is the resolved version (`0.13.1`); for a git-hosted one
+ * it is the resolved tarball URL carrying the commit sha, which is precisely
+ * what makes a moving `github:` spec pinnable.
+ *
+ * Only the profile's own importer (`.`) is read — a dsh profile is a single
+ * package, never a workspace. A version carrying pnpm's peer suffix
+ * (`1.2.3(react@18.0.0)`, emitted when a peer is resolved from inside the
+ * project) is not a legal add spec; it is returned as-is and the caller's
+ * assertSafeSpec rejects it on the parens, so the fallback fails closed rather
+ * than adding something wrong. Profiles install with auto-install-peers off and
+ * take their peers from the host, so this has not been observed in practice.
  */
-function fallbackAddTarget(name, spec) {
-  const range = String(spec ?? "");
-  if (range.length === 0) return undefined;
-  const isLocal = /^(?:file:|link:)/i.test(range);
-  if (!isLocal && validRange(range) === null) return undefined;
-  const target = isLocal ? range : `${name}@${range}`;
+function pinnedLockfileVersion(profileDir, name) {
+  try {
+    const doc = load(readFileSync(join(profileDir, "pnpm-lock.yaml"), "utf8"));
+    const version = doc?.importers?.["."]?.dependencies?.[name]?.version;
+    return typeof version === "string" && version.length > 0 ? version : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** The target when it survives the spec blacklist, undefined when it does not. */
+function safeAddTarget(target) {
   try {
     assertSafeSpec(target);
+    return target;
   } catch {
     return undefined;
   }
-  return target;
+}
+
+/**
+ * The argv target for a fallback `pnpm add` of one restored dependency, or
+ * undefined when that spec cannot be added offline and safely.
+ *
+ * - `file:`/`link:` paths add by the spec itself: a local path is not a moving
+ *   target, it names one fixed thing.
+ * - `github:owner/repo` MUST be pinned to the lockfile's resolution and is
+ *   never added by the spec itself. A bare github spec means "whatever HEAD is
+ *   now", but a rollback needs "what I had" — and the freshest thing in pnpm's
+ *   resolution cache and store is exactly the commit the failed update just
+ *   fetched, i.e. the version being rolled back FROM. Adding the bare spec
+ *   would relink that commit, and candidateRestoredCompatible cannot catch it:
+ *   a non-semver spec has no range to check, so a present package passes on
+ *   name alone. The rollback would then clear the marker and delete the
+ *   snapshot, leaving node_modules on the rejected version, the lockfile
+ *   claiming the old one, and no recovery evidence at all — a fail-OPEN worse
+ *   than not trying. The pinned tarball URL carries the commit sha, so pnpm
+ *   either relinks that exact commit from the store or exits nonzero.
+ * - Semver ranges: `name@range` only when the range carries no shell
+ *   metacharacters — and `^` (the near-universal pnpm save prefix!) is one
+ *   (cmd's escape character: it mangles the argv through the shell-wrapped
+ *   spawn, so assertSafeSpec refuses it). For those — including multi-clause
+ *   ranges like `^1.0.0 || ^2.0.0` — the target becomes
+ *   `name@<lockfile pinned version>`: the lockfile is the authority this
+ *   rollback just restored, so its pinned version is by definition a legal
+ *   restore target for any range.
+ *
+ * Everything that cannot be pinned stays fail-closed (marker + snapshot kept
+ * for `guard recover` or manual repair), which is the whole point: an unpinned
+ * guess is not a recovery.
+ */
+function fallbackAddTarget(name, spec, profileDir) {
+  const range = String(spec ?? "");
+  if (range.length === 0) return undefined;
+  if (/^(?:file:|link:)/i.test(range)) return safeAddTarget(range);
+  const isGit = /^github:/i.test(range);
+  if (!isGit) {
+    if (validRange(range) === null) return undefined;
+    // A shell-safe range splices directly; `^` and friends fall through.
+    const direct = safeAddTarget(`${name}@${range}`);
+    if (direct !== undefined) return direct;
+  }
+  const pinned = pinnedLockfileVersion(profileDir, name);
+  if (pinned === undefined) return undefined;
+  return safeAddTarget(`${name}@${pinned}`);
 }
 
 /**
@@ -1263,6 +1349,14 @@ export function rollbackPendingSnapshot(profileDir) {
   // newly added candidate (absent from the restored manifest) needs nothing
   // reinstalled: removing its node_modules entry above is sufficient.
   // Without a lockfile a frozen install can never succeed, so it is skipped.
+  // What the rebuild actually did, reported back to the caller. A successful
+  // rollback used to be completely silent: reconcile and the per-package add
+  // leave no trace, so after the fact nobody can tell which one relinked the
+  // package — or whether either ran at all. That matters here more than usual,
+  // because the add fallback exists precisely for the case where reconcile
+  // silently no-ops, and "the profile looks right afterwards" does not
+  // distinguish the two.
+  const rebuild = { reconcile: undefined, fallback: [] };
   let attempt;
   if (isRemove) {
     // A failed/no-op remove commonly leaves the original direct package fully
@@ -1277,6 +1371,7 @@ export function rollbackPendingSnapshot(profileDir) {
   } else if (wasUpdate && pending.files?.["pnpm-lock.yaml"]?.present === true) {
     attempt = runReconcileInstall(profileDir);
   }
+  if (attempt !== undefined) rebuild.reconcile = { exitCode: attempt.exitCode };
 
   // Before clearing marker/snapshot after rollback, strictly verify ALL
   // direct dependencies declared by the restored manifest exist in that
@@ -1302,15 +1397,21 @@ export function rollbackPendingSnapshot(profileDir) {
     // whatever pnpm wrote: the add is only the means to relink node_modules,
     // the snapshot stays authoritative for the declaration files.
     for (const depName of [...unsatisfied]) {
-      const target = fallbackAddTarget(depName, restoredDependencies[depName]);
-      if (target === undefined) continue; // not offline-addable — fail closed below
+      const target = fallbackAddTarget(depName, restoredDependencies[depName], profileDir);
+      if (target === undefined) {
+        // Not offline-addable (an unpinnable spec, no lockfile entry) — record
+        // the refusal too, it is the reason the throw below is about to fire.
+        rebuild.fallback.push({ name: depName, target: undefined, exitCode: undefined, restored: false });
+        continue; // fail closed below
+      }
       const addAttempt = runFallbackAdd(profileDir, target);
+      let restored = false;
       if (addAttempt.exitCode === 0) {
         restoreProfileSnapshot(pending);
-        if (candidateRestoredCompatible(profileDir, depName, restoredDependencies[depName])) {
-          unsatisfied.splice(unsatisfied.indexOf(depName), 1);
-        }
+        restored = candidateRestoredCompatible(profileDir, depName, restoredDependencies[depName]);
+        if (restored) unsatisfied.splice(unsatisfied.indexOf(depName), 1);
       }
+      rebuild.fallback.push({ name: depName, target, exitCode: addAttempt.exitCode, restored });
     }
   }
 
@@ -1334,7 +1435,25 @@ export function rollbackPendingSnapshot(profileDir) {
 
   rmSync(pendingPath(profileDir), { force: true });
   rmSync(pending.dir, { recursive: true, force: true });
-  return pending;
+  return { ...pending, rebuild };
+}
+
+/**
+ * One line describing what a rollback's node_modules rebuild did, or undefined
+ * when there was nothing to rebuild (a fresh install's rollback only prunes).
+ * Kept next to the producer so the CLI and the plugin's startup recovery report
+ * it identically.
+ */
+export function describeRollbackRebuild(rebuild) {
+  if (rebuild === null || typeof rebuild !== "object") return undefined;
+  const parts = [];
+  if (rebuild.reconcile !== undefined) parts.push(`reconcile exit ${rebuild.reconcile.exitCode}`);
+  for (const entry of rebuild.fallback ?? []) {
+    parts.push(entry.target === undefined
+      ? `add ${entry.name}: refused (no pinnable offline target)`
+      : `add ${entry.target}: exit ${entry.exitCode}${entry.restored ? ", restored" : ", NOT restored"}`);
+  }
+  return parts.length > 0 ? parts.join("; ") : undefined;
 }
 
 // ── pending-snapshot recovery (startup + external CLI) ───────────────────────
@@ -1426,11 +1545,149 @@ export function validateRemoveCompletion(profileDir, candidateName) {
  * @param profileDir - the profile directory (may come straight from the marker).
  * @returns {{action: "none"|"committed"|"rolled-back", issues?, removed?}}
  */
+// ── approval-pause mark ──────────────────────────────────────────────────────
+//
+// A needsApproval pause otherwise lives only in console output: the marker
+// carries no trace of it, so a restart that passes the STATIC validation would
+// commit the new version with its build scripts never approved — a natively
+// built plugin is then left installed-but-broken and the rollback snapshot is
+// deleted. Both recovery commit points (recoverProfile here, cli.js's
+// commitLaunchSnapshot) must check this mark and roll back instead.
+//
+// Deliberately NOT mirrored into snapshot.json (it is written before the
+// transaction begins and cannot know about a later pause) and NOT a
+// SNAPSHOT_VERSION bump (a bump would fail-close every marker already written
+// by earlier versions, pushing users from auto-recoverable to manual).
+// sanitizeSnapshot ignores unknown metadata fields, so a missing `paused`
+// simply reads as "not paused" and old markers keep their behavior. Tampering
+// with the mark is fail-safe: forging it forces a rollback (refuses the new
+// plugin); deleting it restores the pre-mark behavior.
+
+/** The pause record on a validated pending marker, or undefined. */
+export function pendingApprovalPaused(pending) {
+  const paused = pending?.metadata?.paused;
+  return paused !== null && typeof paused === "object" ? paused : undefined;
+}
+
+/**
+ * How the profile looked BEFORE a paused install began, for the one package
+ * that install is about, or undefined when nothing is paused (or the snapshot
+ * cannot be read, in which case callers should leave their own view alone).
+ *
+ * A paused transaction has already written its half: `pnpm add` swapped
+ * node_modules/<name> to the new version and the manifest declares it, but the
+ * build scripts were never approved, dsh has not loaded any of it, and the next
+ * startup rolls the whole thing back. Reporting that half-state as "installed"
+ * inverts the truth for the user — an UPDATE shows the new version number while
+ * the old one is what is actually running and what a restart will restore. So
+ * the marketplace lists this package the way the snapshot has it instead:
+ *
+ *   present: true  — it was already installed (an update). Show `version`, the
+ *                    version the snapshot's lockfile pins: what runs now and
+ *                    what a restart goes back to.
+ *   present: false — it was not installed at all (a fresh install). It should
+ *                    not appear in the list; nothing about it took effect.
+ *
+ * @returns {{name: string, present: boolean, spec?: string, version?: string}|undefined}
+ */
+export function pausedCandidateBeforeState(profileDir) {
+  let pending;
+  try {
+    pending = readValidatedPendingSnapshot(profileDir);
+  } catch {
+    return undefined;
+  }
+  if (pending === undefined || pendingApprovalPaused(pending) === undefined) return undefined;
+  const name = pending.preflight?.candidate?.name ?? pending.candidate?.name;
+  if (typeof name !== "string" || name.length === 0) return undefined;
+  let spec;
+  try {
+    // The snapshot's manifest — not the live one, which the paused install
+    // already rewrote — decides whether this package existed beforehand.
+    spec = readJson(join(pending.dir, "package.json"))?.dependencies?.[name];
+  } catch {
+    return undefined; // unreadable snapshot: do not touch the caller's view
+  }
+  if (spec === undefined) return { name, present: false };
+  // The snapshot's lockfile pins what that install would have kept running.
+  return { name, present: true, spec, version: pinnedLockfileVersion(pending.dir, name) };
+}
+
+/**
+ * Validate the pending marker, let `mutate` edit its metadata, write it back.
+ * The whole read-mutate-write sits under ONE try: the marker can disappear or
+ * be replaced between the validating read and the write (an install pausing
+ * while startup recovery consumes the same marker), and a pause mark is never
+ * worth turning that race into a thrown error in the middle of an install.
+ * Both callers below promise a boolean, so the failure is reported that way.
+ * @param mutate - returns true when it changed something worth persisting.
+ * @returns true when the marker was rewritten; false when there was nothing to
+ *   do or anything failed — never creates or heals a marker.
+ */
+function updatePendingMarkerMetadata(profileDir, mutate) {
+  try {
+    if (readValidatedPendingSnapshot(profileDir) === undefined) return false;
+    const markerPath = pendingPath(profileDir);
+    const marker = readJson(markerPath);
+    if (marker === null || typeof marker !== "object") return false;
+    // Validation above already guarantees metadata is a plain object.
+    const metadata = marker.metadata ?? {};
+    if (mutate(metadata) !== true) return false;
+    marker.metadata = metadata;
+    writeFileSync(markerPath, JSON.stringify(marker, undefined, 2) + "\n");
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Mark the profile's existing pending marker as paused at the approval gate.
+ * @returns true when a marker was marked; false when there is nothing to mark
+ *   (no marker) or it fails validation (fail closed — never create or heal one).
+ */
+export function markPendingApprovalPause(profileDir, reason = "paused for build-script approval") {
+  return updatePendingMarkerMetadata(profileDir, (metadata) => {
+    metadata.paused = { reason, at: Date.now() };
+    return true;
+  });
+}
+
+/**
+ * Clear the approval-pause mark: a token retry resumed the transaction, so its
+ * eventual completion must commit normally instead of being rolled back.
+ * @returns true when a mark was removed, false when there was none to remove.
+ */
+export function clearPendingApprovalPause(profileDir) {
+  return updatePendingMarkerMetadata(profileDir, (metadata) => {
+    // Same notion of "a mark exists" as pendingApprovalPaused: a non-object
+    // reads as not paused, so there is nothing to clear.
+    if (metadata.paused === null || typeof metadata.paused !== "object") return false;
+    delete metadata.paused;
+    return true;
+  });
+}
+
 export function recoverProfile(profileDir) {
   const pending = readValidatedPendingSnapshot(profileDir);
   if (pending === undefined) return { action: "none" };
-  const validation = validateInstalledProfile(profileDir);
   const isRemove = pending.operation === "remove";
+  // 批准闸暂停后被放弃：静态校验过得去也不许提交——那会把「构建脚本从未
+  // 批准」的新版本以已提交状态留下（原生构建插件装着但坏），且快照被删、
+  // 回滚目标消失。一律回滚到第一次安装前。
+  const pause = pendingApprovalPaused(pending);
+  if (!isRemove && pause !== undefined) {
+    const rolled = rollbackPendingSnapshot(profileDir);
+    return {
+      action: "rolled-back",
+      reason: "批准闸暂停后被放弃（构建脚本未获批准），已回滚到安装前状态",
+      issues: [issue("warn", "approval-paused-abandoned", "批准闸暂停后被放弃，已回滚",
+        `安装停在构建脚本批准处未被批准（${pause.reason}），profile 已回滚到安装前状态`)],
+      removed: addedDependencyNames(pending),
+      rebuild: rolled?.rebuild,
+    };
+  }
+  const validation = validateInstalledProfile(profileDir);
   const candidateName = pending.preflight?.candidate?.name ?? pending.candidate?.name;
   const removeValidation = isRemove
     ? validateRemoveCompletion(pending.profileDir, candidateName)
@@ -1441,8 +1698,20 @@ export function recoverProfile(profileDir) {
   }
   const recoveryIssues = [...validation.issues, ...removeValidation.issues];
   const added = isRemove ? [] : addedDependencyNames(pending);
-  rollbackPendingSnapshot(profileDir);
-  return { action: "rolled-back", issues: recoveryIssues, removed: added };
+  const rolled = rollbackPendingSnapshot(profileDir);
+  // The blockers are the reason; naming them beats the old generic wording,
+  // which said "profile failed validation" for every rollback including the
+  // ones that were not validation failures at all.
+  const blockers = recoveryIssues.filter((entry) => entry.severity === "block");
+  return {
+    action: "rolled-back",
+    reason: blockers.length > 0
+      ? `profile 静态校验未通过：${blockers.map((entry) => entry.title).join("; ")}`
+      : "profile 静态校验未通过",
+    issues: recoveryIssues,
+    removed: added,
+    rebuild: rolled?.rebuild,
+  };
 }
 
 /** Recover every profile with a pending marker under a dsh home. */
@@ -1682,6 +1951,105 @@ async function selfTest() {
       if (existsSync(snap.dir)) throw new Error("recoverProfile commit should delete the snapshot dir");
     }
 
+    // Approval-pause mark, part 1: a paused marker must NEVER commit on
+    // recovery — not even when the static validation would pass (the version
+    // sits there with its build scripts never approved; committing would drop
+    // the only rollback snapshot). Recovery rolls back to the pre-install
+    // state. Layout: the candidate is a NEW dependency (snapshot has none), so
+    // the rollback only prunes node_modules and never spawns pnpm.
+    {
+      const p = join(root, "profiles", "approval-pause");
+      mkdirSync(join(p, "node_modules", "good"), { recursive: true });
+      writeFileSync(join(p, "package.json"), JSON.stringify({ dependencies: {} }));
+      writeFileSync(join(p, "cordis.patch.yml"), "[]\n");
+      if (markPendingApprovalPause(p) !== false) throw new Error("markPendingApprovalPause without a marker must return false, not create one");
+      const snap = createProfileSnapshot(p, { fixture: true });
+      markPendingSnapshot(snap, { spec: "good@2.0.0", preflight: { candidate: { name: "good", version: "2.0.0", kind: "bundle" } } });
+      // 暂停现场：pnpm 已把候选装上、声明也写了——静态校验完全过得去，
+      // 这正是危险所在（提交 = 脚本从未批准的版本以已提交状态留下）。
+      writeFileSync(join(p, "package.json"), JSON.stringify({ dependencies: { good: "^2.0.0" } }));
+      writeFileSync(join(p, "node_modules", "good", "package.json"), JSON.stringify({ name: "good", version: "2.0.0" }));
+      if (markPendingApprovalPause(p) !== true) throw new Error("markPendingApprovalPause must mark an existing marker");
+      const pausedMarker = readJson(pendingPath(p));
+      if (pausedMarker?.metadata?.paused?.reason !== "paused for build-script approval") throw new Error("the pause mark must persist on the marker file");
+      const recPaused = recoverProfile(p);
+      if (recPaused.action !== "rolled-back") throw new Error(`a paused marker must roll back even when validation would pass, got ${recPaused.action}`);
+      if (!recPaused.issues.some((entry) => entry.code === "approval-paused-abandoned")) throw new Error("the rollback must carry the approval-paused-abandoned issue");
+      if (readJson(join(p, "package.json")).dependencies?.good !== undefined) throw new Error("rollback must restore the pre-install manifest (no candidate)");
+      if (existsSync(join(p, "node_modules", "good"))) throw new Error("rollback must prune the never-approved candidate");
+      if (readPendingSnapshot(p) !== undefined) throw new Error("the rolled-back pause must consume its marker");
+    }
+
+    // pausedCandidateBeforeState: what the marketplace must SHOW while an
+    // install sits paused. The half-written profile says the new version is
+    // installed; the truth is that nothing took effect and a restart undoes it.
+    {
+      // An UPDATE: the package existed before, so the list keeps showing the
+      // version that is actually running — the snapshot's pinned one.
+      const p = join(root, "profiles", "paused-view-update");
+      mkdirSync(join(p, "node_modules", "good"), { recursive: true });
+      writeFileSync(join(p, "package.json"), JSON.stringify({ dependencies: { good: "^1.0.0" } }));
+      writeFileSync(join(p, "cordis.patch.yml"), "[]\n");
+      writeFileSync(join(p, "pnpm-lock.yaml"), [
+        "lockfileVersion: '9.0'", "importers:", "  .:", "    dependencies:",
+        "      good:", "        specifier: ^1.0.0", "        version: 1.0.0", "",
+      ].join("\n"));
+      writeFileSync(join(p, "node_modules", "good", "package.json"), JSON.stringify({ name: "good", version: "1.0.0" }));
+      const snap = createProfileSnapshot(p, { spec: "good@2.0.0" });
+      markPendingSnapshot(snap, { spec: "good@2.0.0", preflight: { candidate: { name: "good", version: "2.0.0", kind: "plain" } } });
+      if (pausedCandidateBeforeState(p) !== undefined) throw new Error("a marker with no pause mark must not rewrite the view");
+      // The paused half: pnpm already swapped in 2.0.0 and the manifest says so.
+      writeFileSync(join(p, "package.json"), JSON.stringify({ dependencies: { good: "^2.0.0" } }));
+      writeFileSync(join(p, "node_modules", "good", "package.json"), JSON.stringify({ name: "good", version: "2.0.0" }));
+      markPendingApprovalPause(p);
+      const view = pausedCandidateBeforeState(p);
+      if (view?.name !== "good" || view.present !== true) throw new Error(`a paused update must report the package as previously present, got ${JSON.stringify(view)}`);
+      if (view.version !== "1.0.0") throw new Error(`the reported version must be the snapshot's pin (what actually runs), got ${JSON.stringify(view.version)}`);
+      if (view.spec !== "^1.0.0") throw new Error(`the reported spec must be the snapshot's, got ${JSON.stringify(view.spec)}`);
+      rmSync(pendingPath(p), { force: true });
+      rmSync(snap.dir, { recursive: true, force: true });
+    }
+    {
+      // A FRESH install: the package did not exist before, so it must drop out
+      // of the list entirely — nothing about it took effect.
+      const p = join(root, "profiles", "paused-view-fresh");
+      mkdirSync(join(p, "node_modules"), { recursive: true });
+      writeFileSync(join(p, "package.json"), JSON.stringify({ dependencies: {} }));
+      writeFileSync(join(p, "cordis.patch.yml"), "[]\n");
+      const snap = createProfileSnapshot(p, { spec: "good@2.0.0" });
+      markPendingSnapshot(snap, { spec: "good@2.0.0", preflight: { candidate: { name: "good", version: "2.0.0", kind: "plain" } } });
+      writeFileSync(join(p, "package.json"), JSON.stringify({ dependencies: { good: "^2.0.0" } }));
+      mkdirSync(join(p, "node_modules", "good"), { recursive: true });
+      writeFileSync(join(p, "node_modules", "good", "package.json"), JSON.stringify({ name: "good", version: "2.0.0" }));
+      markPendingApprovalPause(p);
+      const view = pausedCandidateBeforeState(p);
+      if (view?.name !== "good" || view.present !== false) throw new Error(`a paused fresh install must report the package as absent beforehand, got ${JSON.stringify(view)}`);
+      if (view.version !== undefined) throw new Error("an absent package has no version to show");
+      rmSync(pendingPath(p), { force: true });
+      rmSync(snap.dir, { recursive: true, force: true });
+      if (pausedCandidateBeforeState(p) !== undefined) throw new Error("no marker means no view rewrite");
+    }
+
+    // Approval-pause mark, part 2: a cleared mark (token retry resumed and
+    // finished the transaction) commits normally — the mark must not outlive
+    // the transaction it belonged to.
+    {
+      const p = join(root, "profiles", "approval-pause-cleared");
+      mkdirSync(join(p, "node_modules", "good"), { recursive: true });
+      writeFileSync(join(p, "package.json"), JSON.stringify({ dependencies: { good: "1.0.0" }, dsh: { profile: { bundles: ["good"] } } }));
+      writeFileSync(join(p, "cordis.patch.yml"), "[]\n");
+      writeFileSync(join(p, "node_modules", "good", "package.json"), JSON.stringify({ name: "good", version: "1.0.0", dsh: { bundle: { patch: "./cordis.patch.yml" } } }));
+      writeFileSync(join(p, "node_modules", "good", "cordis.patch.yml"), "- insert:\n    - id: good\n      name: good\n");
+      const snap = createProfileSnapshot(p, { fixture: true });
+      markPendingSnapshot(snap, { spec: "good", preflight: { candidate: { name: "good", version: "1.0.0", kind: "bundle" } } });
+      markPendingApprovalPause(p);
+      if (clearPendingApprovalPause(p) !== true) throw new Error("clearPendingApprovalPause must remove an existing mark");
+      const rec = recoverProfile(p);
+      if (rec.action !== "committed") throw new Error(`after the mark is cleared a healthy install must commit, got ${rec.action}`);
+      if (readPendingSnapshot(p) !== undefined) throw new Error("the commit must clear the marker");
+      if (clearPendingApprovalPause(p) !== false) throw new Error("clearPendingApprovalPause without a mark must return false");
+    }
+
     // Remove rollback, no-op failure: the official command failed before
     // touching the package. Rollback must preserve the healthy direct package
     // and must not run the install/update path's candidate pruning logic.
@@ -2021,6 +2389,69 @@ async function selfTest() {
       if (!args.includes("--ignore-scripts")) throw new Error("probe args must keep install scripts disabled");
     }
 
+    // fallbackAddTarget (pure): what one restored dependency may be offline
+    // re-added as. `^` ranges (pnpm's near-universal save prefix) cannot be
+    // spliced into a shell-wrapped argv (cmd eats the caret), so they resolve
+    // to the lockfile's pinned version — exactly what a rollback is restoring
+    // to. A `github:` spec resolves to its pinned tarball URL for a different
+    // and sharper reason: the bare spec means "HEAD now", and the freshest
+    // thing in pnpm's cache/store is the commit the failed update just fetched,
+    // so adding it bare would relink the very version being rolled back FROM —
+    // and a non-semver spec has no range for candidateRestoredCompatible to
+    // check, so that wrong copy would pass on name alone, clear the marker and
+    // delete the snapshot. Pinning is what keeps the fallback fail-closed.
+    {
+      const lockRoot = join(root, "profiles", "fbtarget");
+      mkdirSync(lockRoot, { recursive: true });
+      const tarball = "https://codeload.github.com/owner/repo/tar.gz/898369ece56ae6ec41afd8e014f187bb5b723409";
+      writeFileSync(join(lockRoot, "pnpm-lock.yaml"), [
+        "lockfileVersion: '9.0'",
+        "importers:",
+        "  .:",
+        "    dependencies:",
+        "      good:",
+        "        specifier: ^1.0.0",
+        "        version: 1.0.0",
+        "      hosted:",
+        "        specifier: github:owner/repo",
+        `        version: ${tarball}`,
+        "      peered:",
+        "        specifier: ^1.0.0",
+        "        version: 1.0.0(@deepseek-ai/cordis@4.0.1)",
+        "",
+      ].join("\n"));
+      if (fallbackAddTarget("good", "1.0.0", lockRoot) !== "good@1.0.0") throw new Error("a plain range splices directly");
+      if (fallbackAddTarget("good", "^1.0.0", lockRoot) !== "good@1.0.0") throw new Error("a ^-range must resolve to the lockfile pinned version");
+      if (fallbackAddTarget("good", "^1.0.0", join(root, "profiles", "no-lock-here")) !== undefined) {
+        throw new Error("a ^-range without a readable lockfile must stay fail-closed");
+      }
+      // A bare github spec must NEVER be added as itself: pinning to the
+      // lockfile's tarball URL is the only thing that names the old commit.
+      if (fallbackAddTarget("hosted", "github:owner/repo", lockRoot) !== `hosted@${tarball}`) {
+        throw new Error("a github spec must resolve to the lockfile pinned tarball, never to the moving bare spec");
+      }
+      if (fallbackAddTarget("hosted", "github:owner/repo", join(root, "profiles", "no-lock-here")) !== undefined) {
+        throw new Error("a github spec without a readable lockfile must stay fail-closed, not fall back to the bare spec");
+      }
+      if (fallbackAddTarget("absent", "github:owner/absent", lockRoot) !== undefined) {
+        throw new Error("a github spec with no lockfile entry must stay fail-closed");
+      }
+      // pnpm's peer suffix is not a legal add spec — the parens hit the spec
+      // blacklist, so the fallback fails closed instead of adding something odd.
+      if (fallbackAddTarget("peered", "^1.0.0", lockRoot) !== undefined) {
+        throw new Error("a peer-suffixed pinned version must stay fail-closed");
+      }
+      if (fallbackAddTarget("good", "file:D:\\pkg.tgz", lockRoot) !== "file:D:\\pkg.tgz") throw new Error("local file target expected");
+      // 多区间 range 直拼必被拒（空格/管道），但 lockfile 的 pinned 对任何
+      // range 都是合法恢复目标（lockfile 即权威）——同样走 pinned，
+      // 只有 lockfile 不可读/无该条目才 fail-closed。
+      if (fallbackAddTarget("good", "^1.0.0 || ^2.0.0", lockRoot) !== "good@1.0.0") throw new Error("a multi-clause range must resolve to the lockfile pinned version");
+      if (fallbackAddTarget("good", "^1.0.0 || ^2.0.0", join(root, "profiles", "no-lock-here")) !== undefined) {
+        throw new Error("a multi-clause range without a readable lockfile must stay fail-closed");
+      }
+      if (fallbackAddTarget("good", "", lockRoot) !== undefined) throw new Error("an empty spec has no target");
+    }
+
     // pnpmSpawnPlan (pure, plus a real spawn on Windows): the .cmd shim path
     // must carry its own quotes. Node's shell:true joins command and args
     // without per-argument quoting, so `D:\Program Files\nodejs\pnpm.CMD`
@@ -2188,12 +2619,27 @@ async function selfTest() {
       markPendingSnapshot(snap, { spec: "good@2.0.0", preflight: { candidate: { name: "good", version: "2.0.0", kind: "plain" } } });
       const previousPath = process.env.PATH;
       process.env.PATH = `${binDir}${delimiter}${previousPath ?? ""}`;
+      let rolled;
       try {
-        rollbackPendingSnapshot(p);
+        rolled = rollbackPendingSnapshot(p);
       } finally {
         if (previousPath === undefined) delete process.env.PATH;
         else process.env.PATH = previousPath;
       }
+      // The rebuild report is the ONLY way to tell "reconcile relinked it" from
+      // "reconcile no-opped and the add fallback saved it" after the fact —
+      // both leave an identical-looking profile behind.
+      if (rolled?.rebuild?.reconcile?.exitCode !== 0) throw new Error("the rebuild report must record the no-op reconcile and its exit code");
+      if (rolled.rebuild.fallback.length !== 1) throw new Error(`the rebuild report must record exactly one fallback add, got ${rolled.rebuild.fallback.length}`);
+      const [addReport] = rolled.rebuild.fallback;
+      if (addReport.name !== "good" || addReport.target !== "good@1.0.0" || addReport.exitCode !== 0 || addReport.restored !== true) {
+        throw new Error(`the fallback report must name the package, target, exit code and outcome, got ${JSON.stringify(addReport)}`);
+      }
+      const described = describeRollbackRebuild(rolled.rebuild);
+      if (!/reconcile exit 0/.test(described) || !/add good@1\.0\.0: exit 0, restored/.test(described)) {
+        throw new Error(`describeRollbackRebuild must render both steps, got ${JSON.stringify(described)}`);
+      }
+      if (describeRollbackRebuild(undefined) !== undefined) throw new Error("no rebuild means no line to print");
       if (readPendingSnapshot(p) !== undefined) throw new Error("an add-fallback-rescued rollback must clear the marker");
       if (existsSync(snap.dir)) throw new Error("an add-fallback-rescued rollback must delete the snapshot dir");
       if (readJson(join(p, "node_modules", "good", "package.json")).version !== "1.0.0") throw new Error("the add fallback must relink the old version");

package/src/index.js

@@ -25,7 +25,7 @@ import { tmpdir } from "node:os";
 import { resolveProfileDir } from "@deepseek-ai/dsh-app-boot";
 import { repoInfo, searchPlugins, verifyPlugins, cachedRepoManifest, fetchRawFile, preferNpmSpec, npmPackageInfo, compareVersions, assertSafeToInstall, mapLimit, NETWORK_CONCURRENCY } from "./github.js";
 import { ensureProfile, listInstalled, normalizeSpec, runInstall, runRemove, assertSafeSpec, resolveRegistry, serializeCanonicalProof, persistPluginDisabled } from "./installer.js";
-import { preflightInstall, inspectRemoteCandidate, recoverProfile } from "./guard.js";
+import { preflightInstall, inspectRemoteCandidate, recoverProfile, describeRollbackRebuild } from "./guard.js";
 
 export const name = "@1e0zj/dsh-plugin-mall";
 // `loader` 用来读装配树、并对单个 entry 做热开关（entry.update）。读法照抄
@@ -829,6 +829,9 @@ export function createJobTracker({ producerFactory } = {}) {
           record.status = status;
           record.detail = outcome?.detail;
           record.needsApproval = outcome?.needsApproval;
+          // 原因活不过一次重启的失败（被别的未了结事务挡住）：浏览器据此在
+          // 重启后撤掉记录，而不是把一段现在时的描述留在面板上当现状读。
+          record.staleOnRestart = outcome?.staleOnRestart === true;
           record.finishedAt = Date.now();
 
           if (status === "completed") {
@@ -940,6 +943,7 @@ export function createJobTracker({ producerFactory } = {}) {
           status: record.status,
           detail: record.detail,
           needsApproval: record.needsApproval,
+          staleOnRestart: record.staleOnRestart,
           approvalToken: isSameSession ? record.approvalToken : undefined,
           // extras（如预检结论）同样只对同一 session 可见，与 approvalToken 同规格。
           extras: isSameSession ? record.extras : undefined,
@@ -977,6 +981,7 @@ export function createJobTracker({ producerFactory } = {}) {
             status: record.status,
             detail: record.detail,
             needsApproval: record.needsApproval,
+            staleOnRestart: record.staleOnRestart,
             approvalToken: isSameSession ? record.approvalToken : undefined,
             extras: isSameSession ? record.extras : undefined,
             spec: record.spec,
@@ -1636,6 +1641,11 @@ export function apply(ctx, config = {}) {
       console.log(`[dsh-plugin-mall] startup recovery: committed the pending install for profile "${defaultProfile}"`);
     } else if (result.action === "rolled-back") {
       console.warn(`[dsh-plugin-mall] startup recovery: rolled back the pending install for profile "${defaultProfile}" — ${result.reason ?? "profile failed validation"}`);
+      // What the rebuild did, when it did anything. A rollback that relinked a
+      // package used to be silent, so a reconcile that silently no-opped and a
+      // fallback add that saved the profile looked exactly alike afterwards.
+      const rebuild = describeRollbackRebuild(result.rebuild);
+      if (rebuild !== undefined) console.warn(`[dsh-plugin-mall] startup recovery: node_modules rebuild — ${rebuild}`);
     }
   } catch (error) {
     // 恢复失败绝不能拖垮插件加载：报出来，让市场照常可用（用户还能手动

package/src/installer.js

@@ -16,7 +16,7 @@ import { createHash } from "node:crypto";
 import { dump, load } from "js-yaml";
 import { DEFAULT_PROFILE_BUNDLES, PROFILE_TEMPLATES, initProfile, resolveProfileDir } from "@deepseek-ai/dsh-app-boot";
 import { describeBuildScripts, npmNameOf } from "./github.js";
-import { commitPendingSnapshot, createProfileSnapshot, markPendingSnapshot, pnpmGuardEnv, pnpmSpawnPlan, readValidatedPendingSnapshot, rollbackPendingSnapshot } from "./guard.js";
+import { clearPendingApprovalPause, commitPendingSnapshot, createProfileSnapshot, markPendingApprovalPause, markPendingSnapshot, pausedCandidateBeforeState, pendingApprovalPaused, pnpmGuardEnv, pnpmSpawnPlan, readValidatedPendingSnapshot, rollbackPendingSnapshot } from "./guard.js";
 
 // ── spec normalization ──────────────────────────────────────────────────────
 
@@ -188,7 +188,20 @@ export function reconcileBundles(profileDir, beforeDeps = new Set()) {
   return result;
 }
 
-/** List a profile's installed plugins (dependencies with classification + version). */
+/**
+ * List a profile's installed plugins (dependencies with classification +
+ * version).
+ *
+ * An install paused at the build-script approval gate is reported as the
+ * snapshot has it, not as the half-written profile has it: the candidate's
+ * scripts were never approved, dsh has not loaded it, and the next startup
+ * rolls it back, so calling it "installed" tells the user the opposite of what
+ * is true — an update would show the NEW version while the old one is what is
+ * actually running and what a restart restores. A paused fresh install drops
+ * out of the list entirely. Every consumer goes through here (the browser's
+ * installed panel, the `updates` check that decides whether an update button
+ * appears, and the `market_installed` agent tool), so they all agree.
+ */
 export function listInstalled(profile) {
   const dir = resolveProfileDir(profile);
   const manifestPath = join(dir, "package.json");
@@ -209,7 +222,13 @@ export function listInstalled(profile) {
     }
     return { name, version, kind };
   });
-  return { dir, deps };
+  const before = pausedCandidateBeforeState(dir);
+  if (before === undefined) return { dir, deps };
+  if (!before.present) return { dir, deps: deps.filter((dep) => dep.name !== before.name) };
+  return {
+    dir,
+    deps: deps.map((dep) => (dep.name === before.name ? { ...dep, version: before.version ?? "?" } : dep)),
+  };
 }
 
 // ── npm registry resolution ─────────────────────────────────────────────────
@@ -1094,6 +1113,9 @@ export function createJobTracker() {
         // 待批准的构建脚本清单：浏览器侧据此渲染「允许并继续」，没有它就只有
         // 一段文本，用户看不出要批准的到底是什么。
         record.needsApproval = outcome.needsApproval;
+        // 这次失败的原因活不过一次重启（见 failedNow），浏览器据此在重启后
+        // 撤掉记录，而不是把一段现在时的描述当成当前状态留在面板上。
+        record.staleOnRestart = outcome.staleOnRestart === true;
         record.finishedAt = Date.now();
         onSettled?.(outcome);
       });
@@ -1112,6 +1134,7 @@ export function createJobTracker() {
           status: record.status,
           detail: record.detail,
           needsApproval: record.needsApproval,
+          staleOnRestart: record.staleOnRestart,
           spec: record.spec,
           startedAt: record.startedAt,
           finishedAt: record.finishedAt,
@@ -1455,14 +1478,28 @@ function runInstallInner({ profile, spec, allowBuildScripts, approvedProof, pref
   try {
     existingMarker = readValidatedPendingSnapshot(profileDir);
   } catch (error) {
-    return failedNow(`profile has an unreadable pending marker — refusing to install ${spec} (${error.message}); run \`dsh-plugin-guard guard recover\` first`);
+    return failedNow(`profile 里有一个读不出来的安装记录，无法判断它是什么，因此拒绝安装 ${spec}（${error.message}）。请先运行 \`dsh-plugin-guard guard recover\` 处理它。`);
   }
   if (existingMarker !== undefined) {
     const previous = existingMarker.metadata?.spec ?? existingMarker.metadata?.packageName ?? "unknown";
     if (existingMarker.operation !== "install" || existingMarker.metadata?.spec !== spec) {
-      return failedNow(`profile has a pending ${existingMarker.operation} transaction for ${JSON.stringify(previous)} — refusing to install ${spec}; restart dsh (startup recovery) or run \`dsh-plugin-guard guard recover\` first`);
+      // 拒绝是对的（marker 是一次性事务，不能被覆盖），但用户看不见 marker，
+      // 所以要说清楚挡路的是什么、以及怎么让它让开。暂停在批准闸的那种最
+      // 常见——它正是用户刚点过取消的那次安装。
+      const paused = pendingApprovalPaused(existingMarker) !== undefined;
+      const what = existingMarker.operation === "remove" ? "卸载" : "安装";
+      return failedNow(paused
+        ? `${previous} 的${what}还没做完——它停在「允许安装依赖」那一步等你决定，没有批准就不会真正装上。现在无法安装 ${spec}。重启 dsh 会撤回那次未批准的${what}，之后就能重新操作；也可以运行 \`dsh-plugin-guard guard recover\` 立即撤回。`
+        : `${previous} 的${what}还没了结，现在无法安装 ${spec}。重启 dsh 会自动了结它（装好的提交、没批准的撤回），也可以运行 \`dsh-plugin-guard guard recover\` 手动处理。`,
+      { staleOnRestart: true });
     }
     push(`[dsh-plugin-mall] resuming the paused install transaction for ${spec} — its original snapshot stays the rollback target\n`);
+    // 事务复活：清掉暂停标记，否则重试成功后的启动提交会被它拦下错误回滚。
+    try {
+      clearPendingApprovalPause(profileDir);
+    } catch (pauseError) {
+      push(`[dsh-plugin-mall] WARNING: could not clear the approval-pause mark: ${pauseError.message}\n`);
+    }
   } else {
     let snapshot;
     try {
@@ -1719,7 +1756,15 @@ function runInstallInner({ profile, spec, allowBuildScripts, approvedProof, pref
         // The retry's rebuild branch also needs this tree in place. Leave the
         // on-disk state and the marker for the token retry; an abandoned pause
         // is settled by startup recovery / `guard recover`, whose rollback
-        // target is still the pre-first-attempt snapshot.
+        // target is still the pre-first-attempt snapshot. The pause is also
+        // marked ON the marker: without the mark a restart that passes the
+        // static validation would commit the never-approved version and drop
+        // the snapshot (both recovery commit points check it).
+        try {
+          markPendingApprovalPause(profileDir);
+        } catch (pauseError) {
+          push(`[dsh-plugin-mall] WARNING: could not mark the pause on the pending marker: ${pauseError.message}\n`);
+        }
         push("\n[dsh-plugin-mall] install paused for build-script approval — the candidate stays installed with its scripts blocked; approve in the UI to finish, or restart dsh / run `dsh-plugin-guard guard recover` to roll back\n");
       } else {
         try {
@@ -1747,10 +1792,21 @@ function runInstallInner({ profile, spec, allowBuildScripts, approvedProof, pref
 // ── the background uninstall job ────────────────────────────────────────────
 
 /** A terminal producer for fast-fail cases (no pnpm spawn needed). */
-function failedNow(detail) {
+/**
+ * @param staleOnRestart - true when this failure's CAUSE cannot outlive a
+ *   restart, so the browser should drop the record instead of keeping it as
+ *   history. Only the "another transaction owns this profile" refusals qualify:
+ *   startup recovery settles that transaction on the way up, so the message
+ *   ("X is still waiting at the approval gate, so Y cannot install") describes a
+ *   situation that is guaranteed gone — and it is written in the present tense,
+ *   so a reader after the restart takes it for the current state. Ordinary
+ *   failures (network, preflight blockers, pnpm errors) may well still apply
+ *   after a restart and keep their diagnostic value, so they stay.
+ */
+function failedNow(detail, { staleOnRestart = false } = {}) {
   return {
     cancel: () => {},
-    done: Promise.resolve({ status: "failed", detail }),
+    done: Promise.resolve({ status: "failed", detail, staleOnRestart }),
     readOutput: () => "",
   };
 }
@@ -1786,7 +1842,11 @@ function runRemoveInner({ profile, packageName, _profileDir, _spawn }, selfHeale
   // hard as a valid one, and is left untouched for the recovery path.
   const markerPath = pendingMarkerPath(profileDir);
   if (existsSync(markerPath)) {
-    return failedNow(`profile "${profile}" has a pending install transaction (${markerPath}) — refusing to remove ${packageName} until it is resolved; restart dsh (startup recovery) or run \`dsh-plugin-guard guard recover\` first`);
+    // 存在性判断（同 markPendingSnapshot）：坏 marker 也照样挡路。所以这里
+    // 只能拿到「有」而拿不到「是什么」，文案相应保持笼统，但仍要给出路。
+    return failedNow(
+      `profile "${profile}" 里有一个还没了结的安装事务，在它了结之前无法卸载 ${packageName}。重启 dsh 会自动了结它（装好的提交、没批准的撤回），也可以运行 \`dsh-plugin-guard guard recover\` 手动处理（事务记录：${markerPath}）。`,
+      { staleOnRestart: true });
   }
   const manifestPath = join(profileDir, "package.json");
   if (!existsSync(manifestPath)) {
@@ -2175,13 +2235,50 @@ async function runTransactionFixtures() {
           && /paused for build-script approval/.test(output),
         `status=${outcome.status} calls=${calls.length} marker=${existsSync(markerBefore)}`,
       );
+      check(
+        "暂停必须落盘到 marker（metadata.paused）——重启后的恢复靠它区分「装完待验证」与「停在批准闸被放弃」",
+        (() => {
+          try {
+            const marker = JSON.parse(readFileSync(markerBefore, "utf8"));
+            return marker?.metadata?.paused?.reason === "paused for build-script approval";
+          } catch { return false; }
+        })(),
+      );
+
+      // 1a-ter. 暂停期间装别的包：拒绝是对的（marker 是一次性事务），但用户
+      // 看不见 marker，所以报错必须点名挡路的是那次「停在允许安装依赖」的
+      // 安装，并给出让它让开的办法。这里 marker 仍带 paused。
+      {
+        const during = scriptedSpawn([{ code: 0, out: "Done\n" }]);
+        const duringOutcome = await runInstall({
+          profile: "p",
+          spec: "other-during-pause",
+          preflight: preflightStub("other-during-pause"),
+          _profileDir: profileDir,
+          _spawn: during.spawnFn,
+          _describe: async () => [],
+        }).done;
+        check(
+          // staleOnRestart：这条报错是现在时写的，而挡路的事务必然被启动恢复
+          // 了结——留到重启之后会被当成当前状态读，所以面板要撤掉它。
+          "暂停期间装别的包 → 拒绝，报错点名「停在允许安装依赖」+ 撤回办法 + 标记重启后失效",
+          duringOutcome.status === "failed"
+            && /停在「允许安装依赖」/.test(duringOutcome.detail ?? "")
+            && /重启 dsh/.test(duringOutcome.detail ?? "")
+            && duringOutcome.staleOnRestart === true
+            && during.calls.length === 0,
+          `status=${duringOutcome.status} detail=${(duringOutcome.detail ?? "").slice(0, 120)}`,
+        );
+      }
 
       // 1a-bis. 同 spec 重试接管暂停的 marker：不再新建快照（回滚目标仍是
-      // 第一次安装前的现场），继续 spawn pnpm；异 spec 则拒绝且不 spawn。
+      // 第一次安装前的现场），继续 spawn pnpm；这次给批准后的成功路径——
+      // completed 后 marker 保留给启动提交，且暂停标记必须已被接管清掉
+      // （否则启动提交会被它拦下错误回滚）。异 spec 则拒绝且不 spawn。
       {
         const snapshotRootDir = join(dirname(dirname(profileDir)), "guard", "snapshots");
         const snapshotsBefore = readdirSync(snapshotRootDir, { withFileTypes: true }).filter((e) => e.isDirectory()).length;
-        const retry = scriptedSpawn([{ code: 0, out: "Ignored build scripts: node-pty@1.0.0\nDone\n" }]);
+        const retry = scriptedSpawn([{ code: 0, out: "Done in 1s\n" }]);
         const retryProducer = runInstall({
           profile: "p",
           spec: "some-plugin",
@@ -2194,12 +2291,18 @@ async function runTransactionFixtures() {
         const retryOutput = retryProducer.readOutput();
         const snapshotsAfter = readdirSync(snapshotRootDir, { withFileTypes: true }).filter((e) => e.isDirectory()).length;
         check(
-          "同 spec 重试接管暂停的 marker → 复用原快照，继续安装而非拒绝",
-          retryOutcome.status === "failed"
-            && Array.isArray(retryOutcome.needsApproval)
+          "同 spec 重试接管暂停的 marker → 复用原快照、继续安装并清掉暂停标记",
+          retryOutcome.status === "completed"
             && retry.calls.length === 1
             && /resuming the paused install transaction/.test(retryOutput)
-            && snapshotsAfter === snapshotsBefore,
+            && snapshotsAfter === snapshotsBefore
+            && existsSync(markerBefore)
+            && (() => {
+              try {
+                const marker = JSON.parse(readFileSync(markerBefore, "utf8"));
+                return marker?.metadata?.paused === undefined;
+              } catch { return false; }
+            })(),
           `status=${retryOutcome.status} calls=${retry.calls.length} snapshots=${snapshotsBefore}->${snapshotsAfter}`,
         );
         const other = scriptedSpawn([{ code: 0, out: "Done\n" }]);
@@ -2212,9 +2315,13 @@ async function runTransactionFixtures() {
           _describe: async () => [],
         }).done;
         check(
-          "异 spec 遇暂停 marker → 拒绝且不 spawn",
+          // 此刻 paused 已被上面的接管清掉，所以报错走的是「未了结」那一支，
+          // 而不是「停在允许安装依赖」那一支。
+          "异 spec 遇既有（已非暂停）marker → 拒绝且不 spawn",
           otherOutcome.status === "failed"
-            && /pending install transaction/.test(otherOutcome.detail ?? "")
+            && /还没了结/.test(otherOutcome.detail ?? "")
+            && !/停在「允许安装依赖」/.test(otherOutcome.detail ?? "")
+            && otherOutcome.staleOnRestart === true
             && other.calls.length === 0,
           `status=${otherOutcome.status} calls=${other.calls.length}`,
         );
@@ -2551,6 +2658,8 @@ async function runTransactionFixtures() {
           && installOutcome.status === "failed"
           && removeOutcome.status === "failed"
           && /not a dependency/.test(removeOutcome.detail ?? "")
+          // 普通失败不标记：重启治不好「这个包本来就不在依赖里」。
+          && removeOutcome.staleOnRestart !== true
           && procs.length === 1,
         `procs=${procs.length} install=${installOutcome.status} remove=${removeOutcome.status} ${JSON.stringify(removeOutcome.detail)}`,
       );
@@ -2579,9 +2688,12 @@ async function runTransactionFixtures() {
       const snapshotsDir = join(dirname(marker), "snapshots");
       const leftoverSnapshots = existsSync(snapshotsDir) ? readdirSync(snapshotsDir) : [];
       check(
-        "损坏/既有 pending marker → install 不 spawn、不覆盖证据、不遗留新 snapshot",
+        // 不标 staleOnRestart：损坏的 marker 重启后仍然 fail-closed 留给人工
+        // 检查，不会被启动恢复了结——这条失败的原因活得过重启，面板要留着。
+        "损坏/既有 pending marker → install 不 spawn、不覆盖证据、不遗留新 snapshot，且不标记重启后失效",
         outcome.status === "failed"
-          && /unreadable pending marker/.test(outcome.detail ?? "")
+          && /读不出来的安装记录/.test(outcome.detail ?? "")
+          && outcome.staleOnRestart !== true
           && calls.length === 0
           && readFileSync(marker, "utf8") === corruptBytes
           && leftoverSnapshots.length === 0,
@@ -2604,7 +2716,8 @@ async function runTransactionFixtures() {
       check(
         "pending marker 存在 → remove 拒绝执行且不 spawn pnpm，marker 保留",
         outcome.status === "failed"
-          && /pending install transaction/.test(outcome.detail ?? "")
+          && /还没了结的安装事务/.test(outcome.detail ?? "")
+          && outcome.staleOnRestart === true
           && procs.length === 0
           && existsSync(pendingMarkerPath(profileDir)),
         `status=${outcome.status} procs=${procs.length} ${JSON.stringify(outcome.detail)}`,