@noob-stupid/dsh-plugin-console 0.5.100 → 0.5.101

package/lib/server/domain/install-channels.js

@@ -14,6 +14,8 @@ import { noteChannel, tryGitChannel } from './git-channel.js'
 import { retryPnpmOnce } from './install-diagnose.js'
 import { targetVersionOf, versionMissOf, versionMissText } from './install-version.js'
 import { tryPresetSourceChannel } from './preset-source.js'
+// 自更新兜底（2026-11-03 加法，见 domain/self-update-guard.js 顶部事故记录）：只在"装的包名 === 本插件自己"时接管
+import { beginSelfUpdateGuard, selfUpdateFailureText, settleSelfUpdateGuard } from './self-update-guard.js'
 
 /** release 通道的候选预算（issue #3）：release 通道现在按包名反查发布仓库，**每个候选**至少一次
  * `releases?per_page=10` 调用（第一梯队仓库没命中还要多试几个候选仓库），而候选可能有十几个
@@ -21,6 +23,41 @@ import { tryPresetSourceChannel } from './preset-source.js'
  * 只给前 N 个候选扫 release；排在后面的候选仍照走 curl/并行竞速（按包名施工，代价小）。 */
 const RELEASE_CHANNEL_BUDGET = 3
 
+/**
+ * 单个候选的通道序列**外壳**（2026-11-03 加法）：只给"本插件自己的自更新"多加一层备份/校验/自愈，
+ * 其余情况（所有别的包）**原样直通**——`beginSelfUpdateGuard` 不成立就 `return tryCandidateChannelsInner(...)`，
+ * 一个字节都不多走（tests/test-self-update-guard.mjs ⑤ 用"零备份 + 无 selfUpdate 字段 + 通道调用顺序不变"钉住）。
+ *
+ * 为什么包在整条序列外面，而不是包在某一次 pnpm 调用里面：真机事故（宿主读着插件自己的文件 ⇒ EPERM、
+ * Windows 上 pnpm 先删旧目录再解包、删到一半被打断）里，**残缺态是整条序列结束时才看得见的**，
+ * 而"哪条通道声称装上了"完全不可信（那一次 curl/pnpm 都回了成功）。所以：
+ *   ① 进来先备份（复制，不打扰正在运行的目录）；
+ *   ② 出去无论成败都校验一遍（try/catch 之后仍然跑 —— 这就是"pnpm 报失败也要校验"）；
+ *   ③ 校验不过 ⇒ 把这次尝试**改判成没装上**（installedName=null + 如实错误），
+ *      由 install-job.js 的自更新分支收口成可见失败（绝不报"更新成功"）。
+ */
+async function tryCandidateChannels(args) {
+  const inner = () => tryCandidateChannelsInner(args)
+  const guardDeps = args?.selfUpdateDeps ?? {}
+  const session = beginSelfUpdateGuard({
+    packageName: args?.name, profileDir: args?.profileDir,
+    targetVersion: targetVersionOf(args?.job, args?.name), deps: guardDeps,
+  })
+  if (session === null) return inner()
+  let outcome = null
+  let thrown = null
+  try {
+    outcome = await inner()
+  } catch (error) {
+    thrown = error
+  }
+  const selfUpdate = settleSelfUpdateGuard(session, { targetVersion: targetVersionOf(args?.job, args?.name), deps: guardDeps })
+  if (args?.job !== null && args?.job !== undefined && typeof args.job === 'object') args.job.selfUpdate = selfUpdate
+  if (thrown !== null) throw thrown
+  if (selfUpdate !== null && selfUpdate.verified === true) return outcome
+  return { installedName: null, lastError: new Error(selfUpdateFailureText(selfUpdate) ?? '自更新校验未通过（原因未知）') }
+}
+
 /** 单个候选包的通道尝试序列（通道实现由 ch 注入；job.curlNote 等展示字段在此更新）。
  * 返回 { installedName, lastError }。三条守卫语义及理由（issue #3 要求逐条写清）：
  *
@@ -37,7 +74,7 @@ const RELEASE_CHANNEL_BUDGET = 3
  * ③ git 通道：**保留 repoChannelAllowed**（它只 clone `job.repo`，候选是子包时 clone 根仓库装不出子包，
  *    属无意义尝试）**并保留 !expanded**（同一作业里对同一个 job.repo 反复 clone 纯属浪费时间，
  *    级联顺序也不该被破坏）。 */
-async function tryCandidateChannels({ job, ch, name, profileDir, registries, repoChannelAllowed, budget, baseUrl = null, expanded = false, deadline = null, expand = null, sourceDeps = {} }) {
+async function tryCandidateChannelsInner({ job, ch, name, profileDir, registries, repoChannelAllowed, budget, baseUrl = null, expanded = false, deadline = null, expand = null, sourceDeps = {} }) {
   const installSpec = (typeof job?.version === 'string' && job.version !== '' && name === job.packageName)
     ? `${name}@${job.version}`
     : name // ★ 0.5.81：规格与身份分离 —— name 仍是身份；点名包+指定版本时规格才带 @version

package/lib/server/domain/install-job.js

@@ -16,6 +16,9 @@ import { RELEASE_CHANNEL_BUDGET, tryCandidateChannels } from './install-channels
 import { versionMissOf, versionMissText } from './install-version.js'
 import { settlePresetOutcome } from './preset-in-package.js'
 import { verifyInstalledEntry } from './install-verify.js'
+// 自更新兜底（2026-11-03 加法，见 domain/self-update-guard.js 顶部）：「自更新没落地」的那句话由它产出，
+// 与通道层的 selfUpdate 报告同一份文案，别在作业里另写一套。
+import { selfUpdateFailureText } from './self-update-guard.js'
 import { applyNpmNameHint, composeProbeFailureText, expandSubpackageCandidates, fetchRepoPackage, fetchRepoPackageEx, fetchSubdirPlugins, fetchSubpackageNames, npmNameHintForRepo, packageProbeErrorText, subpackageCandidates } from './market.js'
 import { decideNoRootManifest } from './subdir-detect.js'
 import { runSubdirInstallJob } from './subdir-install.js'
@@ -283,6 +286,20 @@ async function runInstallJob(job, ports, deps = {}) {
     // 预设收口（D-③ 源码装配成功 / D-⑥ 落地物里带预设）：能按预设收口就直接 return —— 见 preset-in-package.js
     // （这两条路都**没有 node_modules 插件**，写补丁行/声明依赖会让补丁行指向无入口模块 → 启动崩溃）。
     if (await settlePresetOutcome({ job, installedName, profileDir, repo: job.repo, deps: sourceDeps }) === true) return
+    // ★ 2026-11-03 加法（真机两次事故：控制台自更新被打断 ⇒ 目录只剩 scripts/ 与 SECURITY.md）：
+    //   **自更新校验不过 ⇒ 如实失败，且不清场、不进 AI 兜底。** 那一刻盘上要么是"刚从备份恢复好的旧版"、
+    //   要么是"已改名挪开的残缺目录"——再让模型去"修"只会把刚恢复好的东西再动一遍；而清场
+    //   （cleanupAttemptedCandidates）会把恢复回来的那一份也删掉，那才是真损失。
+    //   位置刻意放在版本闸分支**之前**：自更新的缺口（被打断/半棵树/没落地）比"镜像 latest 陈旧"更具体，
+    //   先说清是哪一种；失败原因、残缺目录位置与可直接复制运行的命令，全在 selfUpdate 里。
+    //   非自更新作业永远进不到这里（job.selfUpdate 只由 domain/self-update-guard.js 写入）。
+    if (installedName === null && job.selfUpdate != null && job.selfUpdate.verified !== true) {
+      job.status = 'failed'
+      job.stage = 'self-update-check'
+      job.error = selfUpdateFailureText(job.selfUpdate)
+      job.lastError = job.error
+      return
+    }
     // ★ 0.5.87（真机 2026-10-18 的根因收口）：**点名了版本却没装上**⇒ 如实失败，且**不清场**。
     // 为什么不清场：下面的失败路径会调 cleanupAttemptedCandidates，它会 rmSync 掉
     // `node_modules/<包名>` —— 而那一刻盘上放着的是用户**现在还能用**的旧版本（本例 0.1.6-alpha.1）。

package/lib/server/domain/install.js

@@ -506,6 +506,10 @@ function installJobView(job) {
     persisted: job.persisted ?? null, persistNote: job.persistNote ?? null, persist: job.persist ?? null,
     // 「其实已经装上了」的核实结果（0.5.47 加法，见 install-verify.js#installedEvidence）：失败作业由路由在下发前**现查**三处覆盖。
     installedEvidence: job.installedEvidence ?? null,
+    // 自更新保护结果（2026-11-03 加法，见 domain/self-update-guard.js 顶部事故记录）：只对"本插件自己"的
+    // 更新会出现，**非自更新作业恒 null**（既有契约一字不改）。`verified:false` ⇒ 作业必为 failed 且 job.error
+    // 已写清原因/残缺目录/手动命令；`healed:true` ⇒ 已从备份恢复成更新前的版本（那不是"更新成功"）。
+    selfUpdate: job.selfUpdate ?? null,
     // 抓清单那一轮的**通道身份** + 本地落地落点（0.5.47 加法，见 domain/manifest-probe.js）：
     // 面板据此显示"清单经 npm 镜像 / 本地落地 / 直连读到的"，本地命中时给出「从本地安装」的落点。
     probe: job.probe ?? null, localDir: job.localDir ?? null, localHint: job.localHint ?? null,

package/lib/server/domain/self-update-guard.js

@@ -0,0 +1,577 @@
+// L1 · domain —— self-update-guard.js（自更新兜底：更新前备份自身目录 → 更新后按同一判据校验 → 不过就自愈；2026-11-03 加法）
+//
+// ── 现场（真机两次，用户 2026-11-03 报告，已确认）──────────────────────────────────
+//   用户用控制台自带的「更新」把控制台自己更新，pnpm 装包**中途被打断**（宿主正在读插件自己的文件 ⇒ EPERM，
+//   本次还有外部杀进程干扰）。pnpm 的安装是"先删旧目录、再解包新目录"，删到一半失败就留下半棵树：
+//       node_modules/@noob-stupid/dsh-plugin-console/ 只剩 scripts/ 与 SECURITY.md，package.json 没了
+//   ⇒ 宿主解析不出 profile bundle ⇒ 面板显示「异常 / 包不可用」⇒ 只能手工把 npm tarball 解回原位（一天两次）。
+//
+// ── 这不是"自更新逻辑有 bug" ───────────────────────────────────────────────────
+//   用户此前长期正常更新。缺的是**中途被打断之后的自愈**：既有 gateVersion（0.5.87）只核对"落地版本是不是
+//   目标版本"，目录被删空时它读到的是"没装"，既没有恢复动作、也没人替用户把旧版放回去。所以本模块是**加法**：
+//   不改既有安装通道、不改版本闸、不改作业状态机，只在"被安装的包名 === 本插件自己"时多加一层保护。
+//
+// ── 六条硬规矩（改代码时别越线）────────────────────────────────────────────────
+//   ① **只对本插件自己生效**：`isSelfUpdate()` 不成立时 `beginSelfUpdateGuard()` 直接返回 null，
+//      调用方走原路径、一个字节都不变（tests/test-self-update-guard.mjs ⑤ 钉住：别的包不备份、不出字段）。
+//   ② 只有"磁盘上本来就有**一份能解析的**自身副本"才算自更新（= 真的在更新，而不是首次安装）。
+//      目录不存在 / 清单读不出来 ⇒ 不接管 ⇒ 首次安装、坏目录重装的既有行为原样保留。
+//   ③ 备份是**复制**不是移动（正在运行的目录不能被搬走，宿主还要继续读它）；备份失败**不阻断**更新，
+//      只如实记下来，等校验那一步再一起报。
+//   ④ 校验只认磁盘、不认"通道说成功"：清单存在 + 能解析 + 包名是本插件 + 声明的入口文件在 + version === 期望
+//      （没点名版本时只要求"是一份完整的自身副本"）。**同一判据**在自愈之后还要再跑一次。
+//   ⑤ 自愈：残缺目录**改名挪开**（`<dir>.broken-<ts>`，绝不删除 —— 用户可能还要从里面捞东西）→
+//      从备份复制回来 → 用同一判据再校验。Windows 上改名会因占用失败（EPERM/EBUSY），此时降级为
+//      **就地覆盖复制**，并用 `isLockFailure` 把"占用类失败"与"普通异常"分开说。
+//   ⑥ 绝不静默：`verified !== true` 的每一次都带 `reason` 与**可直接复制运行**的 `manualCommand`
+//      （全绝对路径，见 manualRestoreCommand），由调用方写进作业错误，绝不报"更新成功"。
+//
+// 分层：L1 · domain（不认识 cordis，不联网；文件系统读写全部走 node:fs 与 infra/fsx.js 的既有件）。
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import { copyTree, isLockFailure } from '../infra/fsx.js'
+import { pluginRoot, resolvePackageJson } from '../infra/paths.js'
+
+/** 本插件包名的**兜底**常量（与 domain/selfupdate.js#CONSOLE_PACKAGE、routes/plugins.js 里的同名常量一致）。
+ *  为什么这里还要再写一份、而不是 import 过来：识别"我是谁"绝不能依赖**会消失的那个文件**——
+ *  事故现场正是自身清单一度不见；而 import selfupdate.js 还会让本模块与它成环（那边要 import 本模块）。
+ *  正常路径上一律优先读**正在运行的包根** package.json（见 readOwnName），常量只兜底。 */
+const SELF_PACKAGE_FALLBACK = '@noob-stupid/dsh-plugin-console'
+
+/** 备份目录后缀（与 `<pkgDir>` 同父目录，同卷 rename/copy 才成立）。 */
+const PRE_UPDATE_SUFFIX = '.pre-update-'
+/** 残缺目录后缀（**只改名，不删除**）。 */
+const BROKEN_SUFFIX = '.broken-'
+/** 备份最多留几份（"别无限堆"，见 pruneSelfBackups）。 */
+const KEEP_BACKUPS = 1
+/** 时间戳等宽（Date.now() 13 位）——名字的字典序即时间序，prune 靠这一条挑"最新的那份"。 */
+const STAMP_WIDTH = 13
+
+/** 时间戳（名字用；`deps.now` 是单测注入缝）。 */
+function stampOf(now = Date.now()) {
+  const value = Number(now())
+  return String(Number.isFinite(value) ? value : 0).padStart(STAMP_WIDTH, '0')
+}
+
+/** 正在运行的这一份插件自己的 package.json 里的 name（读不到返回 null —— 事故现场就是读不到）。 */
+function readOwnName(deps = {}) {
+  const read = typeof deps.readFile === 'function' ? deps.readFile : readFileSync
+  try {
+    const parsed = JSON.parse(read(join(pluginRoot(), 'package.json'), 'utf8'))
+    if (parsed !== null && typeof parsed === 'object' && typeof parsed.name === 'string' && parsed.name !== '') return parsed.name
+  } catch {}
+  return null
+}
+
+/** 本插件包名：注入 > 运行中清单 > 兜底常量。 */
+function selfPackageNameOf(deps = {}) {
+  if (typeof deps.selfName === 'string' && deps.selfName !== '') return deps.selfName
+  return readOwnName(deps) ?? SELF_PACKAGE_FALLBACK
+}
+
+/** `pkgName` 是不是本插件自己（**纯函数**，判据的唯一入口）。 */
+function isSelfUpdate(packageName, deps = {}) {
+  if (typeof packageName !== 'string' || packageName === '') return false
+  return packageName === selfPackageNameOf(deps)
+}
+
+/** 「这个目录是不是**真的装在 node_modules 里**的那一份」（自更新唯一允许动手的地方）。
+ *  为什么必须有这道闸：Node 的**包自引用**让"仓库根/开发检出"也能解析出同名清单 —— 真机实测过
+ *  一次测试夹具把 profile 建在仓库里面，`resolve()` 直接自指到仓库根，于是守卫把整棵源码树当成
+ *  "安装副本"去做备份（几十万个文件、几分钟）。判据与 release-source.js#releaseInstallTarget 同源：
+ *  `<…>/node_modules/<包名>` 或 `<…>/node_modules/@scope/<包名>`；其余（源码检出）一律不接管。 */
+function looksInstalled(dir) {
+  const parent = basename(dirname(dir))
+  const grand = basename(dirname(dirname(dir)))
+  if (parent === 'node_modules') return true
+  return parent.startsWith('@') && grand === 'node_modules'
+}
+
+/** 被更新的那份**自身副本**在哪（绝对路径）。
+ *  ① 调用方显式给了目录（测试/特例）就用它；
+ *  ② `<profileDir>/node_modules/<包名>` —— pnpm / curl / 并行竞速三条通道的落点，事故现场就是它；
+ *  ③ 解析得到的清单所在目录（宿主根层安装等布局）；
+ *  ④ 正在运行的包根（npm 全局安装、profile 里没有副本时）。
+ *  注：这里只负责"找路"，"敢不敢动手"由 beginSelfUpdateGuard 的 looksInstalled 闸决定。 */
+function selfPackageDirOf({ profileDir = null, packageDir = null, deps = {} } = {}) {
+  if (typeof packageDir === 'string' && packageDir !== '') return packageDir
+  const name = selfPackageNameOf(deps)
+  if (typeof profileDir === 'string' && profileDir !== '') {
+    const profileCopy = join(profileDir, 'node_modules', ...name.split('/'))
+    if (existsSync(profileCopy) === true) return profileCopy
+    try {
+      const resolved = resolvePackageJson(name, profileDir)
+      if (typeof resolved === 'string' && resolved !== '') return dirname(resolved)
+    } catch {}
+    return profileCopy
+  }
+  return pluginRoot()
+}
+
+/** 读一份包清单（读不到返回 `{ parsed:null, version:null, error }`，永不抛）。 */
+function readManifestOf(pkgDir, deps = {}) {
+  const read = typeof deps.readFile === 'function' ? deps.readFile : readFileSync
+  try {
+    const parsed = JSON.parse(read(join(String(pkgDir ?? ''), 'package.json'), 'utf8'))
+    const version = typeof parsed?.version === 'string' && parsed.version !== '' ? parsed.version : null
+    return { parsed, version, error: null }
+  } catch (error) {
+    return { parsed: null, version: null, error: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+/** 「这段报错是不是占用/权限类失败」（判据的唯一真源是 infra/fsx.js#isLockFailure —— 别在这里另立一把尺子）。
+ *  占用类失败靠重试不会好，要做的是改名让开 / 事后恢复；说不清时按普通异常处理（不夸大）。 */
+function occupiedReasonOf(error) {
+  const text = error instanceof Error ? error.message : String(error ?? '')
+  const code = error !== null && error !== undefined && typeof error.code === 'string' ? error.code : ''
+  return isLockFailure(`${code} ${text}`) === true
+}
+
+/**
+ * 自更新的**唯一判据**：`<pkgDir>/package.json` 存在 + 能解析 + 包名是本插件 + 声明的入口文件在 +
+ * version === `expectedVersion`。没给期望版本时只要求"是一份完整的自身副本"（版本号非空）——
+ * "按 latest 更新"的请求本来就没有目标版本。入口文件那一条是"半棵树"的第二道探针：
+ * pnpm 删到一半时也可能留下清单却丢了 lib/，这种状态宿主一样加载不起来。
+ * 只读、永不抛。返回 `{ ok, reason, version, packageName, path, occupied }`。
+ */
+function verifySelfPackageDir(pkgDir, expectedVersion = null, deps = {}) {
+  const wanted = selfPackageNameOf(deps)
+  const dir = String(pkgDir ?? '')
+  const path = join(dir, 'package.json')
+  const out = { ok: false, reason: null, version: null, packageName: null, path, occupied: false }
+  const exists = typeof deps.exists === 'function' ? deps.exists : existsSync
+  if (exists(path) !== true) {
+    out.reason = '目录里没有 package.json（安装中途被打断的典型现场：pnpm 先删旧目录再解包，Windows 上删到一半失败就只剩几个文件）'
+    return out
+  }
+  const manifest = readManifestOf(dir, deps)
+  if (manifest.parsed === null) {
+    out.occupied = occupiedReasonOf(manifest.error)
+    out.reason = `package.json 读不出来/无法解析${out.occupied ? '（文件被占用）' : ''}：${manifest.error ?? '未知原因'}`
+    return out
+  }
+  out.packageName = typeof manifest.parsed.name === 'string' ? manifest.parsed.name : null
+  out.version = manifest.version
+  if (out.packageName !== wanted) {
+    out.reason = `package.json 里的包名是 ${out.packageName ?? '（空）'}，不是本插件 ${wanted}`
+    return out
+  }
+  if (out.version === null) {
+    out.reason = 'package.json 里没有可用的 version 字段'
+    return out
+  }
+  const entry = typeof manifest.parsed.main === 'string' && manifest.parsed.main !== '' ? manifest.parsed.main : null
+  if (entry !== null && exists(join(dir, ...entry.split('/'))) !== true) {
+    out.reason = `声明的入口文件不在了（main = ${entry}）：目录只剩半棵树`
+    return out
+  }
+  const expect = typeof expectedVersion === 'string' && expectedVersion !== '' ? expectedVersion : null
+  if (expect !== null && out.version !== expect) {
+    out.reason = `落地版本是 ${out.version}，不是目标版本 ${expect}`
+    return out
+  }
+  out.ok = true
+  return out
+}
+
+/**
+ * 更新前备份自身目录：**复制**到 `<pkgDir>.pre-update-<时间戳>`（同父目录）。
+ * 复制而不是移动：宿主还在读这份目录，把它搬走等于把正在运行的服务从脚下抽掉。
+ * 失败**不阻断**更新（本函数只回结果），原因留给校验那一步一起如实上报。
+ * 返回 `{ ok, path, reason, previousVersion, occupied }`。
+ */
+function backupSelfPackageDir(pkgDir, deps = {}) {
+  const dir = String(pkgDir ?? '')
+  const out = { ok: false, path: null, reason: null, previousVersion: null, occupied: false }
+  const exists = typeof deps.exists === 'function' ? deps.exists : existsSync
+  const copy = typeof deps.copy === 'function' ? deps.copy : copyTree
+  if (dir === '') {
+    out.reason = '没有给出插件目录'
+    return out
+  }
+  out.previousVersion = readManifestOf(dir, deps).version
+  if (exists(dir) !== true) {
+    out.reason = `插件目录不存在（${dir}）`
+    return out
+  }
+  const target = join(dirname(dir), `${basename(dir)}${PRE_UPDATE_SUFFIX}${stampOf(deps.now ?? Date.now)}`)
+  try {
+    if (exists(target) === true) rmSync(target, { recursive: true, force: true })
+    copy(dir, target)
+    out.ok = true
+    out.path = target
+    return out
+  } catch (error) {
+    out.occupied = occupiedReasonOf(error)
+    out.reason = `备份失败${out.occupied ? '（目录被占用）' : ''}：${error instanceof Error ? error.message : String(error)}`
+    try { rmSync(target, { recursive: true, force: true }) } catch {}
+    return out
+  }
+}
+
+/**
+ * 自愈：**先让开残缺目录（改名，不删）→ 再从备份复制回来**。
+ * 改名挪不开（占用：目录里有 share=None 的句柄 / 是活进程的 cwd）时降级为**就地覆盖复制**——
+ * 宁可留着残渣也别把用户的插件晾在半空；用哪种方式、挪到哪、为什么，全部如实记在返回值里。
+ * 返回 `{ ok, mode:'renamed'|'in-place'|null, brokenPath, reason, occupied }`。
+ */
+function restoreSelfPackageDir(pkgDir, backupPath, deps = {}) {
+  const dir = String(pkgDir ?? '')
+  const out = { ok: false, mode: null, brokenPath: null, reason: null, occupied: false }
+  const exists = typeof deps.exists === 'function' ? deps.exists : existsSync
+  const copy = typeof deps.copy === 'function' ? deps.copy : copyTree
+  const rename = typeof deps.rename === 'function' ? deps.rename : renameSync
+  const messageOf = (error) => (error instanceof Error ? error.message : String(error))
+  if (typeof backupPath !== 'string' || backupPath === '') {
+    out.reason = '没有可用备份'
+    return out
+  }
+  if (exists(backupPath) !== true) {
+    out.reason = `备份目录不存在（${backupPath}）`
+    return out
+  }
+  if (exists(dir) === true) {
+    const broken = join(dirname(dir), `${basename(dir)}${BROKEN_SUFFIX}${stampOf(deps.now ?? Date.now)}`)
+    try {
+      rename(dir, broken)
+      out.mode = 'renamed'
+      out.brokenPath = broken
+    } catch (error) {
+      out.occupied = occupiedReasonOf(error)
+      try {
+        copy(backupPath, dir)
+        out.mode = 'in-place'
+        out.reason = `残缺目录改名挪不开${out.occupied ? '（目录被占用）' : ''}（${messageOf(error)}），已把备份内容就地覆盖回去`
+      } catch (copyError) {
+        out.occupied = out.occupied === true || occupiedReasonOf(copyError) === true
+        out.reason = `残缺目录改名挪不开（${messageOf(error)}），就地覆盖也失败：${messageOf(copyError)}`
+        return out
+      }
+    }
+  } else {
+    try { mkdirSync(dirname(dir), { recursive: true }) } catch {}
+  }
+  if (out.mode === 'renamed') {
+    try {
+      copy(backupPath, dir)
+    } catch (error) {
+      // 复制不可用时的最后一条腿：把备份**改名**到原位置（备份此后不再存在，但盘上有完整的一份）
+      try {
+        rename(backupPath, dir)
+        out.reason = `从备份复制失败（${messageOf(error)}），已改用改名把备份搬回原位`
+      } catch (renameError) {
+        out.occupied = occupiedReasonOf(error) === true || occupiedReasonOf(renameError) === true
+        out.reason = `从备份恢复失败：复制 ${messageOf(error)}；改名 ${messageOf(renameError)}`
+        return out
+      }
+    }
+  }
+  out.ok = exists(join(dir, 'package.json')) === true
+  if (out.ok !== true && out.reason === null) out.reason = `恢复后仍看不到 ${join(dir, 'package.json')}`
+  return out
+}
+
+/** 备份只留最近 `keep` 份（名字里是等宽时间戳 ⇒ 字典序即时间序）。删不掉只记 note、绝不抛。 */
+function pruneSelfBackups(pkgDir, { keep = KEEP_BACKUPS, deps = {} } = {}) {
+  const out = { removed: [], kept: [], note: null }
+  const dir = String(pkgDir ?? '')
+  const parent = dirname(dir)
+  const prefix = `${basename(dir)}${PRE_UPDATE_SUFFIX}`
+  const readdir = typeof deps.readdir === 'function' ? deps.readdir : readdirSync
+  let names = []
+  try { names = readdir(parent).filter((n) => typeof n === 'string' && n.startsWith(prefix)).sort() } catch { return out }
+  const keepCount = Number.isFinite(keep) && keep >= 0 ? Math.floor(keep) : KEEP_BACKUPS
+  for (const name of names.slice(0, Math.max(0, names.length - keepCount))) {
+    try {
+      rmSync(join(parent, name), { recursive: true, force: true })
+      out.removed.push(name)
+    } catch (error) {
+      out.note = `旧备份没删掉（${name}）：${error instanceof Error ? error.message : String(error)}`
+    }
+  }
+  out.kept = names.slice(Math.max(0, names.length - keepCount))
+  return out
+}
+
+/** 去掉本次这一份备份（校验通过时用）。删不掉就留着交给 prune 收口，绝不抛。 */
+function dropBackupOf(backupPath) {
+  if (typeof backupPath !== 'string' || backupPath === '') return { removed: false, note: null }
+  try {
+    rmSync(backupPath, { recursive: true, force: true })
+    return { removed: true, note: null }
+  } catch (error) {
+    return { removed: false, note: `本次备份没删掉（${backupPath}）：${error instanceof Error ? error.message : String(error)}` }
+  }
+}
+
+/** registry tarball 地址（npm 约定：作用域在路径里，文件名不带作用域）。 */
+function registryTarballUrlOf(name, version) {
+  const tail = String(name).split('/').pop()
+  return `https://registry.npmmirror.com/${name}/-/${tail}-${version}.tgz`
+}
+
+/**
+ * 失败时要给用户的那条**可直接复制运行**的命令（全绝对路径 —— 用户可能在任何目录下粘贴它）。
+ *   ① 有备份 ⇒ 把备份整棵复制回来（Windows 用 robocopy：支持长路径，与本仓库回滚脚本同一手法）；
+ *   ② 没有备份 ⇒ 从 registry 取一份解到原位（**正是用户手工救过两次的那套动作**）。
+ * 落点全部选**已经存在**的目录（`<pkgDir>` 的父目录），所以粘贴即可跑，不必先建目录。
+ */
+function manualRestoreCommand({ pkgDir, backupPath = null, version = null, deps = {} } = {}) {
+  const dir = String(pkgDir ?? '')
+  if (dir === '') return null
+  const win = (typeof deps.platform === 'string' ? deps.platform : process.platform) === 'win32'
+  if (typeof backupPath === 'string' && backupPath !== '') {
+    return win
+      ? `robocopy "${backupPath}" "${dir}" /E /NFL /NDL /NJH /NJS /R:1 /W:1`
+      : `cp -a "${backupPath}/." "${dir}/"`
+  }
+  const wanted = typeof version === 'string' && version !== '' ? version : 'latest'
+  const url = registryTarballUrlOf(selfPackageNameOf(deps), wanted)
+  const parent = dirname(dir)
+  const tgz = join(parent, `${basename(dir)}-rescue.tgz`)
+  const unpacked = join(parent, 'package')
+  return win
+    ? `curl.exe -sL -o "${tgz}" "${url}" ; tar -xzf "${tgz}" -C "${parent}" ; robocopy "${unpacked}" "${dir}" /E /NFL /NDL /NJH /NJS /R:1 /W:1`
+    : `curl -sL -o "${tgz}" "${url}" && tar -xzf "${tgz}" -C "${parent}" && cp -a "${unpacked}/." "${dir}/"`
+}
+
+/**
+ * 开始一次自更新的保护（**唯一入口**）：不是本插件 / 磁盘上还没有可解析的自身副本 ⇒ 返回 null
+ * （调用方一个字节都不用走 —— 这就是"别的包行为不变"的实现方式）。
+ * 否则：先备份，返回后续 settle 要用的现场（含备份结果）。
+ */
+function beginSelfUpdateGuard({ packageName = null, profileDir = null, packageDir = null, targetVersion = null, deps = {} } = {}) {
+  if (isSelfUpdate(packageName, deps) !== true) return null
+  const name = selfPackageNameOf(deps)
+  const pkgDir = selfPackageDirOf({ profileDir, packageDir, deps })
+  // 规矩②之前先过一道闸：只认**真的装在 node_modules 里**的那一份（源码检出/仓库根绝不动手，见 looksInstalled）
+  if (looksInstalled(pkgDir) !== true) return null
+  // 规矩②：只有"本来就有完整的一份"才算自更新（首次安装 / 坏目录重装 ⇒ 不接管，既有行为原样保留）
+  const before = verifySelfPackageDir(pkgDir, null, deps)
+  if (before.ok !== true) return null
+  const backup = backupSelfPackageDir(pkgDir, deps)
+  return {
+    packageName: name,
+    packageDir: pkgDir,
+    targetVersion: typeof targetVersion === 'string' && targetVersion !== '' ? targetVersion : null,
+    previousVersion: backup.previousVersion ?? before.version,
+    backupPath: backup.path,
+    backupReason: backup.reason,
+    backedUp: backup.ok === true,
+    deps,
+  }
+}
+
+/**
+ * 「每一步结束都过一遍校验」（**记录器**：只读盘、不写盘、不抛）。
+ * 自更新的三条通道（pnpm update / pnpm add / curl 手铺）各自收尾时调一次 ⇒ `selfUpdate.steps` 里能查到
+ * "第几步之后目录是好的、哪一步把它弄坏了"。刻意**不改既有步骤条件**（某一步成功也照走既有的下一步），
+ * 真正的自愈留到收尾统一做：**全部走完仍不过才动手**（见 settleSelfUpdateGuard）。session 为 null 时返回 null。
+ */
+function noteGuardStep(session, step) {
+  if (session === null || session === undefined || typeof session !== 'object') return null
+  const io = session.deps ?? {}
+  const verdict = verifySelfPackageDir(session.packageDir, session.targetVersion ?? null, io)
+  const row = {
+    step: typeof step === 'string' && step !== '' ? step : 'unknown',
+    verified: verdict.ok === true,
+    version: verdict.version ?? null,
+    reason: verdict.reason ?? null,
+  }
+  session.steps = Array.isArray(session.steps) ? session.steps : []
+  session.steps.push(row)
+  return row
+}
+
+/**
+ * 收尾（**无论通道报成功还是报失败都要跑**）：校验 → 不过就自愈（改名挪开 + 从备份恢复 + 同一判据复核）
+ * → 备份收口（最多留 KEEP_BACKUPS 份）→ 产出如实报告。session 为 null 时原样返回 null。
+ * 返回的报告就是作业里那个 `selfUpdate` 字段（只增字段，见 installJobView）。
+ */
+function settleSelfUpdateGuard(session, { targetVersion = undefined, deps = {} } = {}) {
+  if (session === null || session === undefined || typeof session !== 'object') return null
+  const io = { ...(session.deps ?? {}), ...(deps ?? {}) }
+  const expected = targetVersion === undefined
+    ? session.targetVersion
+    : (typeof targetVersion === 'string' && targetVersion !== '' ? targetVersion : null)
+  const pkgDir = session.packageDir
+  const out = {
+    packageName: session.packageName ?? null,
+    packageDir: pkgDir ?? null,
+    targetVersion: expected ?? null,
+    previousVersion: session.previousVersion ?? null,
+    backedUp: session.backedUp === true,
+    backupPath: session.backupPath ?? null,
+    backupNote: session.backupReason ?? null,
+    verified: false,
+    healed: false,
+    restoredVersion: null,
+    brokenPath: null,
+    selfHeal: null,
+    reason: null,
+    manualCommand: null,
+    backupCleanup: null,
+    steps: Array.isArray(session.steps) ? session.steps : [],
+  }
+  const first = verifySelfPackageDir(pkgDir, expected, io)
+  out.verified = first.ok === true
+  out.restoredVersion = first.version ?? null
+  if (first.ok !== true) {
+    out.reason = first.reason
+    out.selfHeal = { attempted: true, restored: false, reason: null, mode: null, brokenPath: null, restoredVersion: null }
+    if (session.backedUp !== true) {
+      // 规矩③/⑥：备份没建起来 ⇒ 如实说"没有可用备份"（再给出用户可以自己跑的命令）
+      out.selfHeal.reason = `没有可用备份：${session.backupReason ?? '更新前的备份没能建立'}`
+    } else {
+      const restored = restoreSelfPackageDir(pkgDir, session.backupPath, io)
+      out.selfHeal.mode = restored.mode ?? null
+      out.selfHeal.brokenPath = restored.brokenPath ?? null
+      out.brokenPath = restored.brokenPath ?? null
+      if (restored.ok !== true) {
+        out.selfHeal.reason = restored.reason ?? '从备份恢复失败'
+      } else {
+        // 规矩④：**同一判据**再校验一次（期望值 = 备份里那一版 = 更新前的那一版）
+        const again = verifySelfPackageDir(pkgDir, out.previousVersion, io)
+        out.selfHeal.restored = again.ok === true
+        out.selfHeal.restoredVersion = again.version ?? null
+        out.selfHeal.reason = again.ok === true
+          ? `已从备份恢复成更新前的 v${out.previousVersion ?? '?'}`
+          : `已从备份恢复，但恢复后仍不过校验：${again.reason}`
+        out.healed = again.ok === true
+        if (again.ok === true) out.restoredVersion = again.version ?? null
+      }
+    }
+  }
+  // 备份收口（成败都收口到"最多 KEEP_BACKUPS 份"）：通过 ⇒ 本次这份也删掉；没通过 ⇒ 留着它（那是唯一的旧版）
+  const dropped = out.verified === true ? dropBackupOf(out.backupPath) : null
+  const pruned = pruneSelfBackups(pkgDir, { keep: KEEP_BACKUPS, deps: io })
+  out.backupCleanup = {
+    removed: [...(dropped !== null && dropped.removed === true ? [out.backupPath] : []), ...pruned.removed],
+    kept: pruned.kept,
+    note: dropped?.note ?? pruned.note ?? null,
+  }
+  if (out.verified !== true) {
+    out.manualCommand = manualRestoreCommand({
+      pkgDir,
+      backupPath: out.backedUp === true ? out.backupPath : null,
+      version: expected ?? out.previousVersion,
+      deps: io,
+    })
+  }
+  return out
+}
+
+/**
+ * `/self-update` 通路的**收尾段**（2026-11-03 从 domain/selfupdate.js#selfUpdateToLatest **原样搬出**：
+ * 那边贴着 600 行架构棘轮，而这段"清单 spec 跟上 + note 组装 + 返回结构"本来就是自洽的一节）。
+ * 搬移只换了绑定来源 —— `CONSOLE_PACKAGE` / `isRegistryRange` / `label` 三个符号由调用方传进来
+ * （domain 层不许反向 import selfupdate.js：那会成环，见 selfupdate.js#defaultSetSpec 的同一顾虑），
+ * 正文逐字未改。
+ *
+ * 本轮只**加**自更新兜底的三件事（规矩⑥，绝不静默）：
+ *   · 返回结构多 `ok` / `reason` / `selfUpdate`（既有 9 个字段名与语义一个都没动）；
+ *   · 校验没过时把那段失败文案同时推进 `errors` 与 `note`（面板/接口都看得见）；
+ *   · `installedVersion` 在"已自愈"时改报**盘上真实那一版**（否则会留一个 null 让人以为目录还是空的）。
+ */
+function finishSelfUpdate({ profileDir, packageName, latest, spec, installed, method, command, errors, lockVersion, lockUpdated, lockNote, registryRange, selfUpdate = null }) {
+  const CONSOLE_PACKAGE = packageName
+  const isRegistryRange = registryRange
+  const label = (e) => (e instanceof Error ? e.message : String(e))
+  const sourceSwitch = spec !== null && !isRegistryRange(spec) ? `安装来源已从 ${spec} 变为 registry 版本 ${latest}` : null
+
+  // ④ 清单 spec 也要跟上（2026-09-24 实测踩到：lock 写了、spec 还钉着 0.3.57，
+  //    于是下一次 pnpm 操作会把控制台「降级」回 0.3.57 —— 包管理器通道 ①② 通常会顺手改写 spec，
+  //    但手铺兜底不会，所以这里统一收口：装到哪版就把 spec 写成哪版（来源型 spec 除外，绝不丢来源）。
+  let specUpdated = null
+  if (installed === latest && (spec === null || isRegistryRange(spec))) {
+    try {
+      const manifestPath = join(profileDir, 'package.json')
+      const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
+      const deps = { ...(manifest.dependencies ?? {}) }
+      if (deps[CONSOLE_PACKAGE] !== latest) {
+        deps[CONSOLE_PACKAGE] = latest
+        manifest.dependencies = deps
+        writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8')
+        specUpdated = latest
+      }
+    } catch (error) {
+      errors.push(`清单 spec 同步失败：${label(error)}`)
+    }
+  } else if (installed === latest && spec !== null && !isRegistryRange(spec)) {
+    errors.push(`清单 spec 是来源型（${spec}），按约定保留不改写`)
+  }
+
+  const noteParts = [lockUpdated ? '已写入 pnpm-lock.yaml，重启服务后生效' : '已铺入文件但未写入 pnpm-lock.yaml：重启后可用，但会被 pnpm 还原']
+  if (sourceSwitch !== null) noteParts.push(sourceSwitch)
+  if (specUpdated !== null) noteParts.push(`清单 spec 已同步为 ${specUpdated}（防 pnpm 降级）`)
+
+  // ★ 加法：自更新校验的结论（只有"本插件自己 + 更新前就有完整副本"时 selfUpdate 才非空）
+  const verified = selfUpdate === null || selfUpdate === undefined ? true : selfUpdate.verified === true
+  const reason = verified === true ? null : selfUpdateFailureText(selfUpdate)
+  if (reason !== null) errors.push(reason)
+  if (reason !== null) noteParts.push(reason)
+  const installedVersion = verified !== true && typeof selfUpdate.restoredVersion === 'string' ? selfUpdate.restoredVersion : installed
+  return { method, spec: specUpdated ?? spec, installedVersion, lockVersion, lockUpdated, lockNote, command, note: noteParts.join('；'), errors, ok: verified, reason, selfUpdate: selfUpdate ?? null }
+}
+
+/**
+ * `/self-update` 通路的**响应视图**（2026-11-03 从 routes/plugins.js#routeSelfUpdate 的 sendJson 字面量**原样搬出**：
+ * 那个路由文件贴着 600 行架构棘轮，而"这条接口下发什么"本来就是自洽的一节 —— 与 install.js#installJobView
+ * 同一手法：view 归 domain，路由只管发送）。字段表达式逐字照搬，**只多了** selfUpdate / reason 两项。
+ *
+ * ★ 唯一一处取值修正：`updated`。旧代码恒写 `true`，于是"自更新没落地"时会下发 `{ok:false, updated:true}`
+ *   这种自相矛盾的响应（凡是按 updated 判断的消费方都会读成"已更新"）。现在它就是 `ok` 的同一事实。
+ *   面板（lib/client.js:7376）只认 `data.ok === true`，所以这处修正不改变既有 UI 行为。
+ */
+function selfUpdateView({ result, current = null, latest = null }) {
+  const ok = result?.ok !== false
+  return {
+    ok,
+    current,
+    latest,
+    updated: ok,
+    version: result.installedVersion ?? latest,
+    method: result.method,
+    spec: result.spec,
+    installedVersion: result.installedVersion,
+    lockVersion: result.lockVersion,
+    lockUpdated: result.lockUpdated,
+    lockNote: result.lockNote,
+    command: result.command,
+    note: result.note,
+    errors: result.errors,
+    selfUpdate: result.selfUpdate ?? null,
+    reason: result.reason ?? null,
+  }
+}
+
+/** 失败文案（作业 error / 面板提示共用同一份；通过校验时返回 null）。
+ *  一次说清四件事：没通过的原因、自愈有没有成、残缺目录留在哪、手动命令是什么。 */
+function selfUpdateFailureText(selfUpdate) {
+  if (selfUpdate === null || selfUpdate === undefined || typeof selfUpdate !== 'object') return null
+  if (selfUpdate.verified === true) return null
+  const parts = [`自更新没有完成：${selfUpdate.reason ?? '校验未通过'}（插件目录 ${selfUpdate.packageDir ?? '未知'}）。`]
+  if (selfUpdate.healed === true) {
+    parts.push(`已从更新前的备份自动恢复成 v${selfUpdate.restoredVersion ?? '?'}，本次更新**没有生效**（这不是更新成功）。`)
+  } else if (selfUpdate.backedUp !== true) {
+    parts.push(`无法自动恢复：${selfUpdate.selfHeal?.reason ?? '更新前没能建立备份'}。`)
+  } else {
+    parts.push(`自动恢复也失败了：${selfUpdate.selfHeal?.reason ?? '原因未知'}。`)
+  }
+  if (typeof selfUpdate.brokenPath === 'string' && selfUpdate.brokenPath !== '') {
+    parts.push(`残缺目录已改名保留在 ${selfUpdate.brokenPath}（未删除，可自行核对）。`)
+  }
+  if (typeof selfUpdate.manualCommand === 'string' && selfUpdate.manualCommand !== '') {
+    parts.push(`要手动处理可直接复制运行：${selfUpdate.manualCommand}`)
+  }
+  return parts.join('')
+}
+
+export {
+  SELF_PACKAGE_FALLBACK, PRE_UPDATE_SUFFIX, BROKEN_SUFFIX, KEEP_BACKUPS,
+  selfPackageNameOf, isSelfUpdate, looksInstalled, selfPackageDirOf, verifySelfPackageDir,
+  backupSelfPackageDir, restoreSelfPackageDir, pruneSelfBackups, dropBackupOf,
+  manualRestoreCommand, registryTarballUrlOf,
+  beginSelfUpdateGuard, noteGuardStep, settleSelfUpdateGuard, finishSelfUpdate, selfUpdateView, selfUpdateFailureText,
+}

package/lib/server/domain/selfupdate.js

@@ -16,6 +16,9 @@ import { linkSpecFor, linkSpecIsIntact, materializePackageForLink, probeRegistry
 import { canWriteImporterEntry, lockEntryKeyMatches, verifyLockReadOnly, writeLockImporterEntry } from './lock-importer.js'
 import { readManifestDeps } from './lockfile-health.js'
 import { pnpmInstall } from './install.js'
+// 自更新兜底（2026-11-03 加法，见 self-update-guard.js 顶部事故记录）：
+// begin/note/settle 是同一套判据与同一份 manualCommand；finishSelfUpdate 是本文件收尾段**原样搬出**的（腾行数用）。
+import { beginSelfUpdateGuard, finishSelfUpdate, noteGuardStep, settleSelfUpdateGuard } from './self-update-guard.js'
 import { fetchJsonUrl } from '../infra/http.js'
 import { runPnpmWithFallback } from '../infra/exec.js'
 
@@ -111,12 +114,14 @@ function selfUpdateCommand(latest, profileName = '<你的profile>') {
  * 依赖以参数注入（便于单测替换）：`runPnpm`（默认 runPnpmWithFallback）、`pnpmAdd`（默认 pnpmInstall）、
  * `curlManualInstall`（手铺文件兜底，由路由传入）。
  */
-async function selfUpdateToLatest({ profileDir, latest, registries, curlManualInstall, runPnpm = runPnpmWithFallback, pnpmAdd = pnpmInstall, profileName = null, execOpts = {} }) {
+async function selfUpdateToLatest({ profileDir, latest, registries, curlManualInstall, runPnpm = runPnpmWithFallback, pnpmAdd = pnpmInstall, profileName = null, execOpts = {}, selfUpdateDeps = {} }) {
   const command = selfUpdateCommand(latest, profileName ?? '<你的profile>')
   const spec = profileSpec(profileDir, CONSOLE_PACKAGE)
   const errors = []
   let method = null
   const label = (e) => (e instanceof Error ? e.message : String(e))
+  // 自更新兜底（规矩：只对本插件生效 / 更新前就有完整副本 / 真的装在 node_modules 里，三条闸都在 begin 里）
+  const guard = beginSelfUpdateGuard({ packageName: CONSOLE_PACKAGE, profileDir, targetVersion: latest, deps: selfUpdateDeps })
 
   // ① spec 是版本范围 → pnpm update（spec 不变，lock 提到范围内最新）
   if (isRegistryRange(spec)) {
@@ -126,6 +131,7 @@ async function selfUpdateToLatest({ profileDir, latest, registries, curlManualIn
     } catch (error) {
       errors.push(`pnpm update 失败：${label(error)}`)
     }
+    noteGuardStep(guard, 'pnpm-update') // 这一步结束就校验一次（只记录，自愈留到收尾统一做）
   }
   // ② 还没到 latest（超出 range / git·file 来源）→ pnpm add <pkg>@<latest>（spec 与 lock 一起改写）
   if (readInstalledVersion(profileDir, CONSOLE_PACKAGE) !== latest) {
@@ -135,6 +141,7 @@ async function selfUpdateToLatest({ profileDir, latest, registries, curlManualIn
     } catch (error) {
       errors.push(`pnpm add 失败：${label(error)}`)
     }
+    noteGuardStep(guard, 'pnpm-add')
   }
 
   let installed = readInstalledVersion(profileDir, CONSOLE_PACKAGE)
@@ -153,40 +160,15 @@ async function selfUpdateToLatest({ profileDir, latest, registries, curlManualIn
     } catch (error) {
       errors.push(`手动铺文件失败：${label(error)}`)
     }
+    noteGuardStep(guard, 'manual-copy')
     if (!lockUpdated) {
       lockNote = `此更新未写入 pnpm-lock.yaml（lock 里仍是 ${lock ?? '未知'}）：之后任何 pnpm 操作（开关插件、dsh plugin add/remove）都会把它还原成 lock 里的版本。要真正落地请执行：${command}`
     }
   }
 
-  const sourceSwitch = spec !== null && !isRegistryRange(spec) ? `安装来源已从 ${spec} 变为 registry 版本 ${latest}` : null
-
-  // ④ 清单 spec 也要跟上（2026-09-24 实测踩到：lock 写了、spec 还钉着 0.3.57，
-  //    于是下一次 pnpm 操作会把控制台「降级」回 0.3.57 —— 包管理器通道 ①② 通常会顺手改写 spec，
-  //    但手铺兜底不会，所以这里统一收口：装到哪版就把 spec 写成哪版（来源型 spec 除外，绝不丢来源）。
-  let specUpdated = null
-  if (installed === latest && (spec === null || isRegistryRange(spec))) {
-    try {
-      const manifestPath = join(profileDir, 'package.json')
-      const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
-      const deps = { ...(manifest.dependencies ?? {}) }
-      if (deps[CONSOLE_PACKAGE] !== latest) {
-        deps[CONSOLE_PACKAGE] = latest
-        manifest.dependencies = deps
-        writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8')
-        specUpdated = latest
-      }
-    } catch (error) {
-      errors.push(`清单 spec 同步失败：${label(error)}`)
-    }
-  } else if (installed === latest && spec !== null && !isRegistryRange(spec)) {
-    errors.push(`清单 spec 是来源型（${spec}），按约定保留不改写`)
-  }
-
-  const noteParts = [lockUpdated ? '已写入 pnpm-lock.yaml，重启服务后生效' : '已铺入文件但未写入 pnpm-lock.yaml：重启后可用，但会被 pnpm 还原']
-  if (sourceSwitch !== null) noteParts.push(sourceSwitch)
-  if (specUpdated !== null) noteParts.push(`清单 spec 已同步为 ${specUpdated}（防 pnpm 降级）`)
-
-  return { method, spec: specUpdated ?? spec, installedVersion: installed, lockVersion: lock, lockUpdated, lockNote, command, note: noteParts.join('；'), errors }
+  // 收尾：三步都走完才统一校验（全部走完仍不过才自愈），然后交给**原样搬出**的收尾段组装返回结构
+  const selfUpdate = settleSelfUpdateGuard(guard, { targetVersion: latest })
+  return finishSelfUpdate({ profileDir, packageName: CONSOLE_PACKAGE, latest, spec, installed, method, command, errors, lockVersion: lock, lockUpdated, lockNote, registryRange: isRegistryRange, selfUpdate })
 }
 
 /**

package/lib/server/routes/plugins.js

@@ -15,6 +15,8 @@ import { markPendingAdopted } from '../domain/quarantine.js'
 import { pendingRestartJobs, packageDirIn, needsPnpmRemove, revokePendingInstall } from '../domain/revoke.js'
 import { deriveEntryId, isProtectedModule, listEntries } from '../domain/runtime.js'
 import { selfUpdateToLatest } from '../domain/selfupdate.js'
+// 自更新响应视图（2026-11-03 搬出：这个文件贴着 600 行棘轮；字段与取值逻辑一字未改，只多 selfUpdate/reason）
+import { selfUpdateView } from '../domain/self-update-guard.js'
 import { orderedRegistries, readSources } from '../domain/sources.js'
 import { fetchJsonUrl } from '../infra/http.js'
 import { sendError, sendJson } from '../infra/httpd.js'
@@ -573,22 +575,9 @@ async function routeSelfUpdate(req, res, rc) {
       // 包管理器优先（见 domain/selfupdate.js 顶部注释）：旧实现只把文件铺进 node_modules、不写
       // pnpm-lock.yaml → "看起来升级成功、下一次 pnpm 操作就被还原"（用户 2026-09-20 实测报告）。
       const result = await selfUpdateToLatest({ profileDir, latest, registries, curlManualInstall })
-      sendJson(res, 200, {
-        ok: true,
-        current: selfVersion,
-        latest,
-        updated: true,
-        version: result.installedVersion ?? latest,
-        method: result.method,
-        spec: result.spec,
-        installedVersion: result.installedVersion,
-        lockVersion: result.lockVersion,
-        lockUpdated: result.lockUpdated,
-        lockNote: result.lockNote,
-        command: result.command,
-        note: result.note,
-        errors: result.errors,
-      })
+      // 响应视图统一在 domain/self-update-guard.js#selfUpdateView（字段与取值原样搬出，只多 selfUpdate/reason；
+      // 顺便给这个文件腾出 600 行棘轮的余量）。失败时 ok 与 updated 同时为 false —— 绝不把"没落地"报成更新成功。
+      sendJson(res, 200, selfUpdateView({ result, current: selfVersion, latest }))
     } catch (error) {
       sendError(res, 500, `Hub 自动更新失败：${error instanceof Error ? error.message : String(error)}`)
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noob-stupid/dsh-plugin-console",
-  "version": "0.5.100",
+  "version": "0.5.101",
   "description": "DSH 框架升级安全与插件升级门控：一键升级、失败自动回滚、升级后回滚上版、旧插件不适配自动禁用；内置多源插件市场为发现层，插件源全部可自定义，可指向公司内网私有源 / 私有索引 / 本地 Git 仓库，纯内网离线可用 | Framework upgrade safety & plugin version gating for DSH, with a customizable multi-source plugin market: point every source at internal mirrors or a local file:// repo for intranet-only, offline installs.",
   "repository": {
     "type": "git",