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

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

@@ -12,10 +12,13 @@ import { cleanupStalePackageDir } from '../infra/fsx.js'
 import { alreadyInstalledTarget } from './install-verify.js'
 import { noteChannel, tryGitChannel } from './git-channel.js'
 import { retryPnpmOnce } from './install-diagnose.js'
+import { INSTALL_LOCK_TIMEOUT, withInstallLock } from './install-lock.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'
+// 通用"超时/中断把目录弄坏 ⇒ 复核 + 恢复"（2026-11-04 加法，见 domain/install-recovery.js 顶部）：对**所有**包生效
+import { withInstallRecovery } from './install-recovery.js'
 
 /** release 通道的候选预算（issue #3）：release 通道现在按包名反查发布仓库，**每个候选**至少一次
  * `releases?per_page=10` 调用（第一梯队仓库没命中还要多试几个候选仓库），而候选可能有十几个
@@ -24,11 +27,17 @@ import { beginSelfUpdateGuard, selfUpdateFailureText, settleSelfUpdateGuard } fr
 const RELEASE_CHANNEL_BUDGET = 3
 
 /**
- * 单个候选的通道序列**外壳**（2026-11-03 加法）：只给"本插件自己的自更新"多加一层备份/校验/自愈，
- * 其余情况（所有别的包）**原样直通**——`beginSelfUpdateGuard` 不成立就 `return tryCandidateChannelsInner(...)`，
- * 一个字节都不多走（tests/test-self-update-guard.mjs ⑤ 用"零备份 + 无 selfUpdate 字段 + 通道调用顺序不变"钉住）。
+ * 单个候选的通道序列**外壳**（2026-11-04 起有两个壳，顺序如下）：
+ *   ① 最外层 = **互斥**（domain/install-lock.js）：同一个 `profile + 包名` 同一时刻只允许一个安装作业，
+ *      第二个排队等待（不同包照旧并行）。为什么放在最外层：整套通道（竞速 / 串行 pnpm / curl / release /
+ *      git / 定向重试）动的都是**同一个** `node_modules/<包名>` 目录 —— 真机 2026-11-04 的事故就是
+ *      两个 pnpm 同时装同一个包，pnpm 把正式目录改名成 `_tmp_` 后进程被杀，正式目录直接空掉。
+ *   ② 里层 = **自更新兜底**（2026-11-03 加法）：只给"本插件自己的自更新"多加一层备份/校验/自愈，
+ *      其余情况（所有别的包）**原样直通** —— `beginSelfUpdateGuard` 不成立就走
+ *      `withInstallRecovery(...)`（通用恢复，见下），自更新那条路一个字节都不多走
+ *      （tests/test-self-update-guard.mjs ⑤ 用"零备份 + 无 selfUpdate 字段 + 通道调用顺序不变"钉住）。
  *
- * 为什么包在整条序列外面，而不是包在某一次 pnpm 调用里面：真机事故（宿主读着插件自己的文件 ⇒ EPERM、
+ * 为什么自更新兜底包在整条序列外面，而不是包在某一次 pnpm 调用里面：真机事故（宿主读着插件自己的文件 ⇒ EPERM、
  * Windows 上 pnpm 先删旧目录再解包、删到一半被打断）里，**残缺态是整条序列结束时才看得见的**，
  * 而"哪条通道声称装上了"完全不可信（那一次 curl/pnpm 都回了成功）。所以：
  *   ① 进来先备份（复制，不打扰正在运行的目录）；
@@ -37,13 +46,50 @@ const RELEASE_CHANNEL_BUDGET = 3
  *      由 install-job.js 的自更新分支收口成可见失败（绝不报"更新成功"）。
  */
 async function tryCandidateChannels(args) {
+  const packageName = typeof args?.name === 'string' ? args.name : ''
+  const profileDir = typeof args?.profileDir === 'string' ? args.profileDir : ''
+  try {
+    return await withInstallLock({
+      profileDir, packageName, job: args?.job ?? null,
+      // 排队上限默认 10 分钟（domain/install-lock.js#INSTALL_LOCK_WAIT_MS）；单测可传更小的值
+      ...(Number.isFinite(args?.lockWaitMs) ? { waitMs: args.lockWaitMs } : {}),
+      // 排队时留一行可读日志（面板的「通道备注」里看得到"在等谁"）
+      onWait: ({ holder }) => {
+        if (args?.job !== null && args?.job !== undefined && typeof args.job === 'object') {
+          noteChannel(args.job, `同一个包正在被另一个作业安装${holder?.jobId ? `（${holder.jobId}）` : ''}：本次排队等待，不会同时动 node_modules/${packageName}`)
+        }
+      },
+    }, async () => await runSelfUpdateGuarded(args))
+  } catch (error) {
+    if (error?.code !== INSTALL_LOCK_TIMEOUT) throw error
+    // 排队超时 ⇒ 如实"没装成"（不改既有通道语义：调用方本来就按 installedName=null 处理失败）
+    if (args?.job !== null && args?.job !== undefined && typeof args.job === 'object') {
+      args.job.installLock = { ...(args.job.installLock ?? {}), ...(error.holder ?? {}), timeout: true, reason: error.message }
+    }
+    return { installedName: null, lastError: error }
+  }
+}
+
+/** 自更新兜底那一层（原 tryCandidateChannels 的正文，逐字保留）—— 见上方 ② 的说明。 */
+async function runSelfUpdateGuarded(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()
+  // ★ 2026-11-04 加法（见 domain/install-recovery.js 顶部现场）：不是自更新 ⇒ 走**通用**恢复那一层 ——
+  //   对所有包生效（真机清空的不止控制台：用户的 dsh-workbuddy-connect 也被清空过）。
+  //   为什么二选一、不叠加：两层用的都是同一个备份后缀（`.pre-update-<ts>`），叠在一起会互相把对方
+  //   刚建好的那份 prune 掉；而自更新那条路的判据更强（还核对版本与入口文件），由它自己负责到底。
+  //   `run(null)` = 没接管 ⇒ 用**原来的**通道对象跑（一个字节都不多走）；接管时换成"被杀即复核"的代理。
+  if (session === null) {
+    const runWith = (channels) => tryCandidateChannelsInner(channels === null || channels === undefined ? args : { ...args, ch: channels })
+    return await withInstallRecovery({
+      job: args?.job ?? null, name: args?.name, profileDir: args?.profileDir,
+      targetVersion: targetVersionOf(args?.job, args?.name), ch: args?.ch ?? null, deps: args?.recoveryDeps ?? {},
+    }, runWith)
+  }
   let outcome = null
   let thrown = null
   try {

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

@@ -12,11 +12,19 @@ import { buildPnpmEnv, runPnpmWithFallback } from '../infra/exec.js'
 /** 安装失败清场：把本次尝试过的候选包目录与 pnpm `_tmp_` 半成品一起清掉，并**如实汇报**清了什么、什么没清掉
  * （2026-09-20 真装演练：聚合仓库跑 19 分钟后失败，node_modules 留着 `…_tmp_56272_2` 半成品，面板只说"安装失败"）。
  * 2026-09-26（改错）：删除一律走 disposeDir（本机 C 盘/`%TEMP%` 下 rmSync 会静默落空，不核实就会谎报干净）；
- * 删不掉时它**改名降级成同父目录的 `.trash-<ts>`**（做法借自 2BingLing/dsh-market 的 `.bak-<ts>` + renameSync）。 */
-function cleanupAttemptedCandidates(profileDir, candidates) {
+ * 删不掉时它**改名降级成同父目录的 `.trash-<ts>`**（做法借自 2BingLing/dsh-market 的 `.bak-<ts>` + renameSync）。
+ *
+ * ★ 2026-11-04 加法（真机：超时之后正式目录被清空，用户面对的是"面板说失败、插件也真没了"）：
+ *   第 3 个参数 `{ protect }` 列出**本次绝对不许清**的包名 —— 那些目录里放的是
+ *   "domain/install-recovery.js 刚从更新前备份恢复回来的可用旧版本"，清掉它才是真损失。
+ *   不传（老调用点、老测试）⇒ 一个字节都不变；被保护项单独汇报在 `protected` 里，不混进 cleaned。
+ */
+function cleanupAttemptedCandidates(profileDir, candidates, { protect = [] } = {}) {
   const cleaned = []
   const failed = []
   const trashed = []
+  const protectedNames = []
+  const keep = new Set(Array.isArray(protect) ? protect.filter((n) => typeof n === 'string' && n !== '') : [])
   const dispose = (label, dir) => {
     const result = disposeDir(dir)
     if (result.trashed === true) trashed.push({ name: label, path: dir, trashPath: result.trashPath, note: disposeNote(result) })
@@ -25,6 +33,10 @@ function cleanupAttemptedCandidates(profileDir, candidates) {
     return 0
   }
   for (const name of candidates) {
+    if (keep.has(name)) {
+      protectedNames.push(name)
+      continue
+    }
     const dir = join(profileDir, 'node_modules', ...String(name).split('/'))
     const parent = dirname(dir)
     const base = basename(dir)
@@ -38,7 +50,7 @@ function cleanupAttemptedCandidates(profileDir, candidates) {
     } catch {}
     if (touched > 0) cleaned.push(name)
   }
-  return { cleaned, failed, trashed }
+  return { cleaned, failed, trashed, protected: protectedNames }
 }
 
 /** 授权被拒/超时后的失败文案（纯函数，单测覆盖）：说清为什么失败、清理了什么、什么没清掉。
@@ -52,13 +64,18 @@ function aiConsentFailureText(decision, leftovers, timeoutMs = AI_CONSENT_TIMEOU
   const cleaned = leftovers?.cleaned ?? []
   const failed = leftovers?.failed ?? []
   const trashed = leftovers?.trashed ?? []
+  const protectedList = Array.isArray(leftovers?.protected) ? leftovers.protected : []
   const noteOf = (item) => (typeof item?.note === 'string' && item.note !== '' ? `（${item.note}）` : (item?.error != null ? `（${item.error}）` : ''))
   const cleanedNote = cleaned.length > 0 ? `；已清理本次落盘残留：${cleaned.join('、')}` : ''
+  // 2026-11-04 加法：被保护的项要**说出来**（否则用户以为我们忘了清场）
+  const protectedNote = protectedList.length > 0
+    ? `；已保留 ${protectedList.join('、')} 不清场 —— 那是安装过程中被弄坏后、刚从备份恢复回来的旧版本，删掉它才是真损失`
+    : ''
   const trashedNote = trashed.length > 0
     ? `；有 ${trashed.length} 项正被占用、已改名降级为 .trash-*（${trashed.map((t) => (typeof t?.note === 'string' && t.note !== '' ? t.note : basename(String(t?.trashPath ?? '')))).join('、')}）`
     : ''
   const failedNote = failed.length > 0 ? `；**有 ${failed.length} 项没能清理**：${failed.map((f) => `${f.path}${noteOf(f)}`).join('、')}` : ''
-  return `${base}${cleanedNote}${trashedNote}${failedNote}`
+  return `${base}${cleanedNote}${protectedNote}${trashedNote}${failedNote}`
 }
 
 /** 用 corepack pnpm 移除包（与安装同一管理器与凭据抑制环境）。

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

@@ -92,6 +92,16 @@ const DIAGNOSIS_RULES = [
     hint: 'registry 上没有这个包/这个版本（包名拼错、子包未发布，或镜像未同步）：核对包名与版本后重试；'
       + '若确认已发布，多半是镜像未同步完整 —— 换一个 registry 或稍后再试。',
   },
+  {
+    // 2026-11-04 加法：**同一个包正被另一个作业装着**（并发互斥闸拦下的那一次，见 domain/install-lock.js）。
+    // 必须排在 network-timeout 之前：这段文案里有"排队等待…超时"这种字样，落进网络分类会把用户带到
+    // "换源/稍后重试网络"的错误方向 —— 而真相是"等前一个作业跑完就能装，重试网络毫无意义"。
+    kind: 'package-locked',
+    re: /正在安装中|INSTALL_LOCK_TIMEOUT|排队等待/iu,
+    retry: null,
+    hint: '这个包正被另一个作业安装/更新：本控制台已保证**同一时刻只有一个作业动同一个包**，所以这次没有启动任何安装、'
+      + '也没有改动磁盘 —— 等那边结束后重试即可（不是网络问题，也不是包本身有问题）。',
+  },
   {
     kind: 'locked',
     re: /EPERM|EACCES|EBUSY|ERR_PNPM_EEXIST|operation not permitted|being used by another process/iu,

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

@@ -19,6 +19,8 @@ import { verifyInstalledEntry } from './install-verify.js'
 // 自更新兜底（2026-11-03 加法，见 domain/self-update-guard.js 顶部）：「自更新没落地」的那句话由它产出，
 // 与通道层的 selfUpdate 报告同一份文案，别在作业里另写一套。
 import { selfUpdateFailureText } from './self-update-guard.js'
+// 通用超时/中断恢复（2026-11-04 加法，见 domain/install-recovery.js 顶部）：「安装把目录弄坏了」的那句话由它产出
+import { installRecoveryFailureText } from './install-recovery.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'
@@ -277,6 +279,9 @@ async function runInstallJob(job, ports, deps = {}) {
       const attempt = await tryCandidateChannels({
         job, ch, name, profileDir, registries, repoChannelAllowed, budget,
         baseUrl: ports.baseUrl ?? null, expanded, deadline, sourceDeps,
+        // 包互斥闸的排队上限（domain/install-lock.js#INSTALL_LOCK_WAIT_MS 是生产默认值；
+        // 这里只是**单测注入缝**，生产调用方不传 deps.installLockWaitMs ⇒ undefined ⇒ 默认值）
+        lockWaitMs: Number.isFinite(deps.installLockWaitMs) ? deps.installLockWaitMs : undefined,
         expand: (expanded || job.npmNameHint !== undefined) ? null : expandSubpackages,
       })
       installedName = attempt.installedName
@@ -323,6 +328,18 @@ async function runInstallJob(job, ports, deps = {}) {
       return
     }
     if (installedName === null) {
+      // ★ 2026-11-04 加法（真机：两个 pnpm 同时装同一个包 ⇒ 正式目录被清空）：**拿不到包互斥锁** ⇒ 如实失败，
+      //   且**不进 AI 兜底**。理由与自更新/版本闸两条同源：这不是"哪一步坏了"，而是"这个包正被另一个作业装着"，
+      //   让模型去"修"只会去动一个正被别人写着的目录（必然 EPERM，还要等 10 分钟授权）。
+      //   `job.installLock.timeout` 只由 domain/install-lock.js 写入 ⇒ 非并发场景一个字节都不受影响。
+      if (job.installLock !== null && job.installLock !== undefined && job.installLock.timeout === true) {
+        job.status = 'failed'
+        job.stage = 'install-lock'
+        job.error = job.installLock.reason ?? `这个包正在安装中（${job.packageName ?? job.candidateName ?? '未知包'}），本次排队等待超时，已放弃`
+        job.lastError = job.error
+        job.diagnosis = { kind: 'package-locked', hint: '同一个包同一时刻只允许一个安装作业：等前一个结束后重试即可（不是网络问题）。', retry: null, packages: [job.packageName ?? job.candidateName].filter((n) => typeof n === 'string' && n !== '') }
+        return
+      }
       if (job.diagnosis == null) job.diagnosis = classifyInstallFailure(lastError?.message) // 分类提示兜底（加法）
       // 本地 AI 兜底会调用模型 API、产生费用：挂起等待用户明确同意后再执行
       job.stage = 'ai-consent'
@@ -358,15 +375,23 @@ async function runInstallJob(job, ports, deps = {}) {
         job.status = 'failed'
         // 失败/取消时清场并如实汇报（见 cleanupAttemptedCandidates 注释）：
         // 不能让用户面对"面板说失败、磁盘上却留了半个包和 _tmp_ 残留"的糊涂账。
-        const leftovers = cleanupAttemptedCandidates(profileDir, candidates)
+        // ★ 2026-11-04 加法：**恢复回来的那份不许清**（domain/install-recovery.js 刚把更新前的备份放回原位，
+        //   那一刻盘上是用户**现在还能用**的旧版本；旧代码在这里把它一起删掉 —— 真机"正式目录被清空且再也回不来"
+        //   的最后一刀就在这一行）。保护名单只来自本作业自己的恢复报告，其余候选照旧清场。
+        const protect = job.installRecovery !== null && job.installRecovery !== undefined && job.installRecovery.healed === true
+          && typeof job.installRecovery.packageName === 'string' ? [job.installRecovery.packageName] : []
+        const leftovers = cleanupAttemptedCandidates(profileDir, candidates, { protect })
         job.leftovers = leftovers
         // ★ 失败路径 B 的文案（0.5.41 加法）：**只有如实失败 + 原因**。取样/下载本身失败时磁盘上
         // 什么都没有 ⇒ 没有任何东西可挂 ⇒ 面板**绝不**出现"回落成功 / 已安装 / 已启用"之类说法。
         // 这里把最后一次的真实失败原因接在既有文案之后（不改写、不掩盖），并保留既有诊断分类（可重试动作
         // 由面板的「重试」按钮与 diagnosis.hint 承担）。
         const reason = typeof lastError?.message === 'string' && lastError.message !== '' ? lastError.message : null
+        // ★ 2026-11-04 加法：恢复/校验的结论单独接一句（绝不与"装上了"混在一起）
+        const recoveryNote = installRecoveryFailureText(job.installRecovery)
         job.error = aiConsentFailureText(decision, leftovers, aiConsentTimeoutMs)
           + (reason === null ? '' : `；最后一次失败原因：${reason}`)
+          + (recoveryNote === null ? '' : `；${recoveryNote}`)
       }
       return
     }

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

@@ -0,0 +1,225 @@
+// L1 · domain —— install-lock.js（**同一个 profile + 包名** 的安装互斥；2026-11-04 加法）
+// 分层分组：L1 · domain（边界由 tests/test-architecture-guard.mjs 断言；不认识 cordis ctx）
+//
+// ── 现场（真机 2026-11-04，用户提供的原始日志）────────────────────────────────────
+//   一次「详情页更新控制台自己」失败，日志里 pnpm 先被 180s 超时杀树，随后：
+//       [WARN] Moving @noob-stupid/dsh-plugin-console_tmp_13796_2 to node_modules\.ignored\…
+//       [WARN] Moving dsh-workbuddy-connect_tmp_13796_3 to node_modules\.ignored\…
+//   后果：正式目录被清空（只剩 1 个文件、package.json 不见），`node_modules/.ignored` 堆到 118 项 / 335 MB。
+//   用户的判断（原文要点）：「这是**两个 pnpm 安装同时装同一个包**造成的冲突 —— 并行竞速本身没问题，
+//   要的是『如果下载一个的时候，就停止另一个相同的安装』」。
+//
+// ── 本模块只做一件事：包的**互斥**（粒度 = 包，不是全局）────────────────────────────
+//   · 同一个 `profileDir + 包名` 同一时刻只允许**一个**安装作业；第二个**排队等待**（FIFO，先到先得）。
+//   · 不同包**照旧并行** —— 用户明确要「支持同时下载多个」，把闸门做成全局串行是错的。
+//   · 等待有上限（默认真机作业预算 10 分钟）：到点如实拒绝（`INSTALL_LOCK_TIMEOUT`），绝不放行去动目录。
+//   · **可重入**：同一个异步上下文里已经持有该包的锁时直接放行（否则"安装收口里再调一次 pnpm"这种
+//     嵌套会自己把自己锁死；用 AsyncLocalStorage 认上下文，不靠猜）。
+//
+// ── 为什么队列实现要复用 enrich-throttle.js#makeLimiter ────────────────────────────
+//   仓库里已经有一份经过真机验证的 FIFO 计数闸门（`makeLimiter(max)`：绝不丢任务、先到先得、能报
+//   active/queued/peak）。用户的原话是「先搜，能复用就复用，不要另造一套」——所以这里**只**复用它的队列，
+//   不重写调度。本模块新增的只有三样它没有的东西：
+//     ① 以「包」为键（每个键一个 `max=1` 的 limiter ⇒ 天然就是该包的串行队列）；
+//     ② **可取消的排队票**：等待超时后把票标记作废，轮到它时**不执行**（`makeLimiter` 本身不支持取消，
+//        但我们不需要改它 —— 传入的 fn 自己看票）；
+//     ③ **可重入**（同上，AsyncLocalStorage）。
+//
+// ── 语义边界（别越线）────────────────────────────────────────────────────────────
+//   · 本模块**不安装任何东西**，也不判断安装成败：它只保证"同一时刻只有一个人在动同一个目录"。
+//   · 拿不到锁 ⇒ 抛错（由调用方如实报成失败）；**绝不**降级成"不拿锁直接装"。
+//   · 空包名 / 空 profileDir ⇒ 直接放行（既有调用路径不传这些参数时行为一个字都不变）。
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { resolve } from 'node:path'
+import { makeLimiter } from './enrich-throttle.js'
+
+/** 排队等待上限（默认 10 分钟）：到点就如实拒绝，绝不无限等。
+ *  取值理由：单次作业预算 8 分钟（domain/install-job.js#jobBudgetMs），最快的一轮 pnpm 失败约 90s；
+ *  10 分钟足以覆盖"前一个作业跑完一轮"的绝大多数情形，又不会让第二个作业挂到用户以为死了。 */
+const INSTALL_LOCK_WAIT_MS = 10 * 60 * 1000
+/** 拒绝时的错误码（调用方据此产出如实文案；不要靠匹配中文）。 */
+const INSTALL_LOCK_TIMEOUT = 'INSTALL_LOCK_TIMEOUT'
+
+/** 锁键：`<规范化的 profileDir>::<包名>`。Windows 路径不区分大小写 ⇒ 统一小写，否则同一个目录会有两把锁。 */
+function installLockKey(profileDir, packageName) {
+  const name = typeof packageName === 'string' ? packageName.trim() : ''
+  if (name === '') return ''
+  const dir = typeof profileDir === 'string' && profileDir.trim() !== '' ? profileDir.trim() : '<unknown-profile>'
+  let normalized = ''
+  try { normalized = resolve(dir) } catch { normalized = dir }
+  if (process.platform === 'win32') normalized = normalized.toLowerCase()
+  return `${normalized}::${name.toLowerCase()}`
+}
+
+// ── 模块级状态（一个进程一份；`__resetInstallLocks()` 供单测还原）─────────────────────────
+const states = new Map()
+const heldStore = new AsyncLocalStorage()
+
+function lockStateFor(key) {
+  let st = states.get(key)
+  if (st === undefined) {
+    st = { key, limiter: makeLimiter(1), holder: null, acquired: 0, waits: 0, timeouts: 0, peakQueued: 0, lastWaitMs: 0, seq: 0 }
+    states.set(key, st)
+  }
+  return st
+}
+
+/** 当前是否有人在装这个包（**不拿锁**，只读状态；给"要不要提示用户在排队"用）。 */
+function installLockHolder(profileDir, packageName) {
+  const key = installLockKey(profileDir, packageName)
+  if (key === '') return null
+  const st = states.get(key)
+  if (st === undefined || st.holder === null) return null
+  const s = st.limiter.stats()
+  return { ...st.holder, active: s.active, queued: s.queued }
+}
+
+/** 闸门现状（诊断 / 单测断言"不同包确实并行、同一个包确实串行"用）。 */
+function installLockStats() {
+  const items = []
+  for (const st of states.values()) {
+    const s = st.limiter.stats()
+    items.push({ key: st.key, holder: st.holder?.packageName ?? null, holderSince: st.holder?.since ?? null, active: s.active, queued: s.queued, peak: s.max, acquired: st.acquired, waits: st.waits, timeouts: st.timeouts, lastWaitMs: st.lastWaitMs, peakQueued: st.peakQueued })
+  }
+  return { locks: items.length, items }
+}
+
+/** 清空全部在途记录（单测 & 诊断用；已在跑的作业不会被取消 —— 它们退出时也不会再写回这张表）。 */
+function __resetInstallLocks() {
+  states.clear()
+}
+
+/** 超时拒绝的错误对象（文案要能直接展示给用户：谁在装、等了多久、下一步怎么做）。 */
+function installLockTimeoutError({ packageName, waitedMs, holder = null }) {
+  const seconds = Math.max(1, Math.round(waitedMs / 1000))
+  const who = typeof holder?.packageName === 'string'
+    ? `另一个作业（${holder.jobId ?? '未命名作业'}）正在安装这个包，已进行 ${Math.max(1, Math.round((Date.now() - Number(holder.since ?? Date.now())) / 1000))}s`
+    : '另一个作业正在安装这个包'
+  const error = new Error(`这个包正在安装中：${who}。本次已排队等待 ${seconds}s 仍未轮到，已放弃（没有动任何文件）——请等它结束后重试。`)
+  error.code = INSTALL_LOCK_TIMEOUT
+  error.packageName = packageName
+  error.waitedMs = waitedMs
+  error.holder = holder
+  return error
+}
+
+/**
+ * 过闸执行一次"动 `node_modules/<包名>`"的动作（**唯一入口**）。
+ * @param {object} spec
+ * @param {string} [spec.profileDir]   profile 目录（与另一个作业同一个 profile 才会互斥）
+ * @param {string} [spec.packageName]  包名（锁的粒度就是它；空字符串 ⇒ 不过闸、直接执行）
+ * @param {number} [spec.waitMs]       排队上限（默认 INSTALL_LOCK_WAIT_MS；传 0 = 有人占着就立刻拒绝）
+ * @param {object} [spec.job]          作业（只用于把"我在排队 / 我等了多久"写回去，便于面板显示）
+ * @param {(info:{queued:boolean,waitedMs:number,key:string})=>void} [spec.onWait] 排队回调（写日志用）
+ * @param {() => Promise<any>} fn      真正要做的活
+ * @returns {Promise<any>} fn 的返回值；拿不到锁 ⇒ 抛 INSTALL_LOCK_TIMEOUT
+ */
+async function withInstallLock(spec, fn, deps = {}) {
+  const packageName = typeof spec?.packageName === 'string' ? spec.packageName.trim() : ''
+  const key = installLockKey(spec?.profileDir, packageName)
+  if (key === '' || typeof fn !== 'function') return await fn()
+  // 可重入：同一个异步上下文里已经持有这个包 ⇒ 直接执行（防"安装收口里再调一次"把自己锁死）
+  const held = heldStore.getStore()
+  if (held !== undefined && held !== null && held.has(key) === true) return await fn({ queued: false, waitedMs: 0, key, reentrant: true })
+  const st = lockStateFor(key)
+  const now = typeof deps.now === 'function' ? deps.now : Date.now
+  const waitMs = Number.isFinite(spec?.waitMs) && spec.waitMs >= 0 ? spec.waitMs : INSTALL_LOCK_WAIT_MS
+  const startedAt = now()
+  // 「前面还有人」的判据要有两条：`holder` 是人可读的当前持有者，`limiter.active` 是队列的**权威**计数
+  // （同一个 tick 里两个调用同时进来时 holder 还是 null，只有 limiter 已经把它算进去了）。
+  const queued = st.holder !== null || st.limiter.stats().active > 0
+  const ticket = { cancelled: false }
+  if (queued) {
+    st.waits += 1
+    const depth = st.limiter.stats().queued + 1
+    if (depth > st.peakQueued) st.peakQueued = depth
+    const holder = st.holder === null ? null : { ...st.holder }
+    if (spec?.job !== null && spec?.job !== undefined && typeof spec.job === 'object') {
+      // 只增字段：面板/诊断据此显示"在排队等谁"，不改任何既有作业字段的语义
+      spec.job.installLock = { key, packageName, queued: true, since: startedAt, waitedFor: holder?.packageName ?? null, holderJobId: holder?.jobId ?? null, waitMs }
+    }
+    if (typeof spec?.onWait === 'function') {
+      try { spec.onWait({ queued: true, waitedMs: 0, key, holder }) } catch {}
+    }
+  }
+  // 排队（max=1 的 FIFO；票作废后轮到它时**不执行**，只把队列让给下一位）
+  // `queueTimer` 在**拿到锁的那一刻**就清掉 —— 排队上限只约束"排队"，绝不能把**已经轮到自己、
+  // 正在装**的那一次作业从后面掐断（真实形状：等 9 分钟才轮到，再装 8 分钟，旧写法会在第 10 分钟误杀）。
+  let queueTimer = null
+  const task = st.limiter.run(async () => {
+    if (ticket.cancelled === true) return { skipped: true }
+    if (queueTimer !== null) { clearTimeout(queueTimer); queueTimer = null }
+    const waitedMs = now() - startedAt
+    st.holder = { key, packageName, since: now(), jobId: spec?.job?.id ?? null, serial: (st.seq += 1) }
+    st.acquired += 1
+    st.lastWaitMs = waitedMs
+    if (spec?.job !== null && spec?.job !== undefined && typeof spec.job === 'object') {
+      spec.job.installLock = { key, packageName, queued: queued, waitedMs, acquiredAt: now() }
+    }
+    try {
+      return await heldStore.run(new Set([...(heldStore.getStore() ?? []), key]), () => fn({ queued, waitedMs, key, reentrant: false }))
+    } finally {
+      st.holder = null
+    }
+  })
+  // `waitMs === 0` = 明确拒绝策略（有人占着就立刻失败，不排队）；否则立刻放行或排队
+  if (waitMs === 0) {
+    if (queued === true) {
+      st.timeouts += 1
+      ticket.cancelled = true
+      void task.catch(() => {})
+      throw installLockTimeoutError({ packageName, waitedMs: 0, holder: st.holder === null ? null : { ...st.holder } })
+    }
+    return await task
+  }
+  if (queued !== true) return await task
+  // 有上限地等：到点把票作废并如实拒绝（**不会**降级成"不拿锁直接装"）
+  const guard = new Promise((resolveGuard, rejectGuard) => {
+    queueTimer = setTimeout(() => {
+      queueTimer = null
+      ticket.cancelled = true
+      const waitedMs = now() - startedAt
+      st.timeouts += 1
+      rejectGuard(installLockTimeoutError({ packageName, waitedMs, holder: st.holder === null ? null : { ...st.holder } }))
+    }, waitMs)
+  })
+  try {
+    return await Promise.race([task, guard])
+  } finally {
+    if (queueTimer !== null) { clearTimeout(queueTimer); queueTimer = null }
+    // 票作废后那个 limiter 任务仍会用 { skipped: true } 落地 —— 这里接住它，别留下未处理的 rejection
+    if (ticket.cancelled === true) void task.catch(() => {})
+  }
+}
+
+/** 失败文案（作业 error / 面板提示共用一份；非锁超时返回 null）：拿不到锁时**如实失败**，绝不报成功。 */
+function installLockFailureText(job) {
+  const lock = job !== null && job !== undefined && typeof job === 'object' ? job.installLock : null
+  if (lock === null || lock === undefined) return null
+  if (lock.timeout !== true) return null
+  return lock.reason ?? `这个包正在安装中（${lock.packageName ?? '未知包'}），本次排队等待超时，已放弃`
+}
+
+/** `withInstallLock` 的"拿不到锁就返回一份**如实**的结果"版本（只吞 `INSTALL_LOCK_TIMEOUT`，其余照抛）。
+ *  `onTimeout(error)` 的返回值原样交给调用方 —— 调用方据此产出"没装成 + 原因"，绝不假装成功。 */
+async function withInstallLockOr(spec, fn, onTimeout, deps = {}) {
+  try {
+    return await withInstallLock(spec, fn, deps)
+  } catch (error) {
+    if (error?.code !== INSTALL_LOCK_TIMEOUT || typeof onTimeout !== 'function') throw error
+    return await onTimeout(error)
+  }
+}
+
+export {
+  INSTALL_LOCK_WAIT_MS,
+  INSTALL_LOCK_TIMEOUT,
+  installLockKey,
+  installLockHolder,
+  installLockStats,
+  installLockTimeoutError,
+  installLockFailureText,
+  withInstallLock,
+  withInstallLockOr,
+  __resetInstallLocks,
+}

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

@@ -0,0 +1,476 @@
+// L1 · domain —— install-recovery.js（安装过程把**已有副本**弄坏之后的复核与恢复；2026-11-04 加法）
+// 分层分组：L1 · domain（边界由 tests/test-architecture-guard.mjs 断言；不认识 cordis ctx）
+//
+// ── 现场（真机 2026-11-04，用户提供的原始日志）────────────────────────────────────
+//   一次「详情页更新控制台自己」失败：pnpm 被 180s 超时**杀整棵进程树**（`已终止整棵进程树 pid=25340`），
+//   同一个进程还在把 `@noob-stupid/dsh-plugin-console_tmp_13796_2` 之类的目录往 `.ignored` 里搬。
+//   杀掉之后没人收尾 ⇒ pnpm 那一套"先把正式目录改名成 `_tmp_`、再解包新内容"停在中途：
+//       node_modules/@noob-stupid/dsh-plugin-console/  只剩 1 个文件，package.json 没了
+//   ⇒ 宿主解析不出这个包 ⇒ 面板显示「异常 / 包不可用」。同一次里 `.ignored` 已经堆到 **118 项 / 335 MB**，
+//   其中 `dsh-workbuddy-connect_tmp_*` 六十多个 —— 说明这个失败模式**长期存在**，只是以前没人收口。
+//
+// ── 本模块补的是什么（用户原话：「杀进程后立刻复核目标目录，发现 package.json 缺失或空壳就从备份恢复；
+//    恢复不了就如实报，绝不允许报成功」）────────────────────────────────────────────
+//   ① **杀进程前**先把"这个目录里原来是什么"记下来（有没有清单、版本是多少）；
+//   ② 通道**每次**抛"被杀/超时/占用"类错误之后**立刻**复核 + 恢复（不等整条通道序列走完 —— 否则后面
+//      每条通道都在一个空目录上继续施工，越走越远）；
+//   ③ 整条序列结束时（成功、失败、抛异常都算）再复核一次：结构坏了 ⇒ 先试**更新前的备份**，
+//      没有再试 **pnpm 的暂存目录**（`<pkg>_tmp_*`，那里面通常是一份完整副本 ⇒ 这正是"从暂存目录恢复"）；
+//   ④ 恢复不了 ⇒ 报告里带**绝对路径** + 可直接复制运行的修复命令，并且**绝不报成功**
+//      （调用方据此把这次尝试改判成"没装上"）。
+//
+// ── 与既有实现的关系（复用，不另造一套）────────────────────────────────────────────
+//   · 备份/恢复/校验/手动命令**全部复用** domain/self-update-guard.js 的现成实现：
+//     `backupSelfPackageDir` / `restoreSelfPackageDir` / `pruneSelfBackups` / `dropBackupOf` /
+//     `manualRestoreCommand` / `verifySelfPackageDir`。那套判据本来是给"控制台自己"写的，
+//     但它的判据函数都接受一个包名（通过既有注入缝 `deps.selfName`），所以这里**不改它一个字节**，
+//     只是把包名传进去 —— 于是同一套备份命名（`.pre-update-<ts>`）、同一套"改名挪开不删"、
+//     同一份手动命令，对本模块覆盖的所有包都成立。
+//   · 本模块**只管"目录被弄坏之后的复核与恢复"**：不判断安装成功与否、不改版本闸、不改任何通道。
+//
+// ── 什么时候**不**接管（边界写死在这里，别越线）──────────────────────────────────
+//   ① 包名/目录算不出来 ⇒ 不接管（既有行为一个字节都不变）。
+//   ② 目标目录不在 `node_modules` 里（源码检出 / 开发树）⇒ 不接管（与 self-update-guard 的 looksInstalled 同源）。
+//   ③ 目标目录本身是**链接**（`link:` / junction 安装）⇒ **不接管**：那是用户自己的源码树，把它恢复成"真目录"
+//      会让"改了源码不生效"变成常态。宁可不动手，也要在报告里说清为什么不动手。
+//   ④ 安装**之前**目录就已经不是一份完整副本（首次安装、本来就坏着）⇒ 不接管：
+//      没有"原来那版"可回滚，接管只会把既有失败路径改一遍。
+//   ⑤ 备份成败都不阻断安装：备份失败只记原因（真机 EPERM 时连读都读不出来），恢复永远排在校验之后。
+import { existsSync, lstatSync, readdirSync, statSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import { compareSemverText, parseSemverText } from '../infra/semver.js'
+import { alreadyInstalledTarget } from './install-verify.js'
+import {
+  PRE_UPDATE_SUFFIX, backupSelfPackageDir, dropBackupOf, looksInstalled, manualRestoreCommand,
+  pruneSelfBackups, restoreSelfPackageDir, verifySelfPackageDir,
+} from './self-update-guard.js'
+
+/** 备份的体积上限（默认 256 MB）：超了就**跳过备份并如实记下原因**（一次更新不该顺带拷几百 MB）。
+ *  真机量级参考：本机 desktop profile 里的控制台 2.7 MB / 161 个文件，普通插件都在个位数 MB。 */
+const MAX_BACKUP_BYTES = 256 * 1024 * 1024
+/** pnpm 的暂存目录前缀：`<包目录名>_tmp_<pid>_<序号>`（真机日志里就是这个形状）。 */
+const STAGING_MARK = '_tmp_'
+/** 备份最多留几份（与 self-update-guard 的 KEEP_BACKUPS 同口径：这里只收口"本模块造的"那一族）。 */
+const KEEP_BACKUPS = 1
+
+/** `<profileDir>/node_modules/<包名>`（作用域包按 `/` 分段）。 */
+function packageDirOf(profileDir, packageName) {
+  const name = typeof packageName === 'string' ? packageName.trim() : ''
+  const dir = typeof profileDir === 'string' ? profileDir.trim() : ''
+  if (name === '' || dir === '') return ''
+  return join(dir, 'node_modules', ...name.split('/'))
+}
+
+/** 目录是不是**链接**（junction 在 lstat 上也表现为符号链接）—— 见边界③。只读，失败按"不是链接"处理。 */
+function isLinkedDir(dir) {
+  try { return lstatSync(dir).isSymbolicLink() === true } catch { return false }
+}
+
+/** 目录体积（有上限地递归统计：一旦超过 `limit` 立刻返回，不把一次更新变成一次全盘扫描）。 */
+function dirBytes(dir, { limit = MAX_BACKUP_BYTES, readdir = readdirSync, stat = statSync } = {}) {
+  let total = 0
+  const walk = (current) => {
+    let entries = []
+    try { entries = readdir(current, { withFileTypes: true }) } catch { return }
+    for (const entry of entries) {
+      if (total > limit) return
+      const full = join(current, entry.name)
+      if (entry.isDirectory()) { walk(full); continue }
+      if (!entry.isFile()) continue
+      try { total += stat(full).size } catch {}
+    }
+  }
+  try { if (existsSync(dir)) walk(dir) } catch {}
+  return total
+}
+
+/** 一次"这个目录现在是什么"的只读快照（结构判据复用 verifySelfPackageDir，包名走既有注入缝）。 */
+function inspectPackageDir(packageDir, packageName, deps = {}) {
+  const dir = String(packageDir ?? '')
+  const name = typeof packageName === 'string' ? packageName.trim() : ''
+  const exists = typeof deps.exists === 'function' ? deps.exists : existsSync
+  const out = { path: join(dir, 'package.json'), exists: exists(dir) === true, linked: false, ok: false, hasManifest: false, version: null, packageName: null, reason: null }
+  if (dir === '' || name === '') { out.reason = '包名或目录为空'; return out }
+  out.linked = isLinkedDir(dir)
+  if (exists(dir) !== true) { out.reason = '目录不存在（安装过程把它删掉/搬走了）'; return out }
+  const verdict = verifySelfPackageDir(dir, null, { ...deps, selfName: name })
+  out.ok = verdict.ok === true
+  out.version = verdict.version ?? null
+  out.packageName = verdict.packageName ?? null
+  out.reason = verdict.reason ?? null
+  out.hasManifest = exists(out.path) === true
+  return out
+}
+
+/** 判断"这个错误是不是'进程被杀/目录被占用'那一类"（只认明确的证据，宁窄勿宽）。 */
+function looksInterrupted(error) {
+  if (error === null || error === undefined) return false
+  if (error.timedOut === true || error.killed === true) return true
+  const text = `${error.code ?? ''} ${error.message ?? ''}`
+  return /已终止整棵进程树|SIGTERM|SIGKILL|EPERM|EACCES|EBUSY|ENOTEMPTY|operation not permitted|being used by another process|maxBuffer/iu.test(text)
+}
+
+/** 版本比较（只用来**记录**"有没有退回"，不参与任何成功判定；解析不了就返回 null）。 */
+function versionDirection(before, after) {
+  const a = parseSemverText(before ?? '')
+  const b = parseSemverText(after ?? '')
+  if (a === null || b === null) return null
+  const diff = compareSemverText(b, a)
+  return diff < 0 ? 'regressed' : (diff > 0 ? 'advanced' : 'same')
+}
+
+/**
+ * 找 pnpm 留下的**可用暂存副本**：`node_modules/<父>/<包目录名>_tmp_*` 里含同一包名清单的那些，
+ * 按版本取最高的一个（都没有版本号就按名字排序取最后一个）。返回绝对路径或 null。
+ * 为什么值得一试：真机日志里 pnpm 正是把正式目录改名成 `_tmp_<pid>_<n>` 再搬去 `.ignored`，
+ * 所以**正式目录空掉时，完整的那一份很可能就在这几个 `_tmp_` 里**。
+ */
+function findStagingDir(profileDir, packageName, deps = {}) {
+  const dir = packageDirOf(profileDir, packageName)
+  if (dir === '') return null
+  const parent = dirname(dir)
+  const base = basename(dir)
+  const readdir = typeof deps.readdir === 'function' ? deps.readdir : readdirSync
+  const name = typeof packageName === 'string' ? packageName.trim() : ''
+  let names = []
+  try { names = readdir(parent).filter((entry) => typeof entry === 'string' && entry.startsWith(`${base}${STAGING_MARK}`)).sort() } catch { return null }
+  const usable = []
+  for (const entry of names) {
+    const candidate = join(parent, entry)
+    const verdict = verifySelfPackageDir(candidate, null, { ...deps, selfName: name })
+    if (verdict.ok === true) usable.push({ path: candidate, version: verdict.version ?? null })
+  }
+  if (usable.length === 0) return null
+  usable.sort((x, y) => {
+    const a = parseSemverText(x.version ?? '')
+    const b = parseSemverText(y.version ?? '')
+    if (a !== null && b !== null) return compareSemverText(b, a)
+    return String(x.path) < String(y.path) ? 1 : -1
+  })
+  return usable[0]
+}
+
+/** 备份一族（`<pkg>.pre-update-*`）里最新的一份（本模块只在"本次备份没建成功"时用它兜底）。返回绝对路径或 null。 */
+function findLatestBackup(packageDir) {
+  const dir = String(packageDir ?? '')
+  if (dir === '') return null
+  const parent = dirname(dir)
+  const prefix = `${basename(dir)}${PRE_UPDATE_SUFFIX}`
+  try {
+    const names = readdirSync(parent).filter((entry) => typeof entry === 'string' && entry.startsWith(prefix)).sort()
+    return names.length === 0 ? null : join(parent, names[names.length - 1])
+  } catch { return null }
+}
+
+/**
+ * 开始一次"更新已有副本"的保护（**唯一入口**）。不满足边界 ①–④ 时返回 null：
+ * 调用方据此走原路径，一个字节都不多走（这就是"别的行为不变"的实现方式）。
+ * 返回的 session 只装现场事实与备份结果，**不动任何文件**（除了复制出一份备份）。
+ */
+function beginInstallRecovery({ packageName = '', profileDir = '', packageDir = null, targetVersion = null, job = null, deps = {} } = {}) {
+  const name = typeof packageName === 'string' ? packageName.trim() : ''
+  if (name === '') return null
+  const dir = typeof packageDir === 'string' && packageDir !== '' ? packageDir : packageDirOf(profileDir, name)
+  if (dir === '') return null
+  // 边界⑤：这一次通道**根本不会动目录**（包已在盘上、且不是更新请求 ⇒ install-verify 的 alreadyInstalledTarget
+  //   会直接短路"跳过重复下载"）⇒ 不备份、不接管：省掉一次整目录复制，语义与那条既有判据一致（不新造判据）。
+  if (job !== null && job !== undefined && typeof profileDir === 'string' && profileDir !== ''
+    && alreadyInstalledTarget(profileDir, name, job) !== null) return null
+  // 边界②：只认"真的装在 node_modules 里"的那一份
+  const installedShaped = typeof deps.looksInstalled === 'function' ? deps.looksInstalled(dir) === true : looksInstalled(dir) === true
+  if (installedShaped !== true) return null
+  // 边界③：链接安装（link:/junction）不动手
+  if (isLinkedDir(dir) === true) return null
+  // 边界④：安装前就必须是一份完整的副本（首次安装 / 本来就坏着 ⇒ 不接管）
+  const before = inspectPackageDir(dir, name, deps)
+  if (before.ok !== true) return null
+  // 备份（复制；失败不阻断，只如实记）
+  const limit = Number.isFinite(deps.maxBackupBytes) && deps.maxBackupBytes > 0 ? deps.maxBackupBytes : MAX_BACKUP_BYTES
+  const bytes = typeof deps.sizeOf === 'function' ? Number(deps.sizeOf(dir)) || 0 : dirBytes(dir, { limit })
+  let backup = { ok: false, path: null, reason: null, previousVersion: before.version, occupied: false }
+  let backupSkipped = false
+  if (bytes > limit) {
+    backupSkipped = true
+    backup.reason = `目录体积约 ${Math.round(bytes / (1024 * 1024))} MB，超过备份上限 ${Math.round(limit / (1024 * 1024))} MB：本次**没有**建备份（恢复时会退而使用 pnpm 暂存目录）`
+  } else {
+    try {
+      const result = backupSelfPackageDir(dir, deps)
+      if (result !== null && typeof result === 'object') backup = result
+      else backup.reason = '备份实现没有返回结果'
+    } catch (error) {
+      backup.reason = `备份抛错：${error instanceof Error ? error.message : String(error)}`
+    }
+  }
+  return {
+    packageName: name,
+    packageDir: dir,
+    profileDir: typeof profileDir === 'string' ? profileDir : '',
+    targetVersion: typeof targetVersion === 'string' && targetVersion !== '' ? targetVersion : null,
+    before,
+    previousVersion: backup.previousVersion ?? before.version,
+    backupPath: backup.path,
+    backedUp: backup.ok === true,
+    backupReason: backup.reason,
+    backupSkipped,
+    deps,
+  }
+}
+
+/** 恢复现场的"流水"（每次复核/恢复都记一条，供报告与面板显示；不参与判定）。
+ *  `pendingHeal`：最近一次恢复之后**还没有**任何通道成功过 —— 也就是说盘上那一份是"恢复回来的旧版"，
+ *  不能算这次安装的成果。后面有通道成功写入时它会被清掉（见 wrapChannelsWithRecovery）。 */
+function makeRecoveryState(session) {
+  return { session, timeline: [], healCount: 0, savedFrom: null, savedVersion: null, brokenPaths: [], pendingHeal: false }
+}
+
+/**
+ * 立刻复核 + 必要时恢复（"杀进程后立刻复核"的那一步；幂等，可以反复调）。
+ * 先试**更新前的备份**，再试 **pnpm 暂存目录**；都不行就如实返回原因（绝不假装恢复了）。
+ */
+function healPackageDir(state, { trigger = 'manual', deps = {} } = {}) {
+  const session = state.session
+  const io = { ...(session.deps ?? {}), ...(deps ?? {}) }
+  const dir = session.packageDir
+  const name = session.packageName
+  const current = inspectPackageDir(dir, name, io)
+  const row = { at: typeof io.now === 'function' ? io.now() : Date.now(), trigger, ok: current.ok === true, version: current.version ?? null, restored: false, restoredFrom: null, restoredVersion: null, brokenPath: null, reason: null }
+  if (current.ok === true) {
+    row.reason = '目录当前是完整的，无需恢复'
+    state.timeline.push(row)
+    return row
+  }
+  // ① 更新前的备份（本次这一份优先；本次没建成才用同目录里最新的那一份）
+  const backupPath = session.backedUp === true && typeof session.backupPath === 'string' && existsSync(session.backupPath) ? session.backupPath : findLatestBackup(dir)
+  if (backupPath !== null) {
+    const restored = restoreSelfPackageDir(dir, backupPath, io)
+    const again = inspectPackageDir(dir, name, io)
+    if (restored.ok === true && again.ok === true) {
+      row.restored = true
+      row.restoredFrom = 'backup'
+      row.restoredVersion = again.version ?? null
+      row.brokenPath = restored.brokenPath ?? null
+      row.version = again.version ?? null
+      row.ok = true
+      row.reason = `已从备份恢复（${backupPath}）`
+      state.healCount += 1
+      state.pendingHeal = true
+      state.savedFrom = 'backup'
+      state.savedVersion = again.version ?? null
+      if (typeof restored.brokenPath === 'string') state.brokenPaths.push(restored.brokenPath)
+      state.timeline.push(row)
+      return row
+    }
+    row.reason = `从备份恢复失败：${restored.reason ?? '恢复后仍不过校验'}${restored.ok === true ? `（${again.reason ?? '结构不完整'}）` : ''}`
+  } else {
+    row.reason = session.backupSkipped === true ? `本次没有建备份（${session.backupReason ?? '体积超上限'}）` : `没有可用备份${session.backupReason ? `（${session.backupReason}）` : ''}`
+  }
+  // ② pnpm 暂存目录（`<pkg>_tmp_*`）：正式目录空掉时，完整的那一份常常就在这里
+  const staging = session.profileDir === '' ? null : findStagingDir(session.profileDir, name, io)
+  if (staging !== null) {
+    const restored = restoreSelfPackageDir(dir, staging.path, io)
+    const again = inspectPackageDir(dir, name, io)
+    if (restored.ok === true && again.ok === true) {
+      row.restored = true
+      row.restoredFrom = 'staging'
+      row.restoredVersion = again.version ?? null
+      row.brokenPath = restored.brokenPath ?? null
+      row.version = again.version ?? null
+      row.ok = true
+      row.reason = `已从 pnpm 暂存目录恢复（${staging.path}${staging.version ? `，v${staging.version}` : ''}）`
+      state.healCount += 1
+      state.pendingHeal = true
+      state.savedFrom = 'staging'
+      state.savedVersion = again.version ?? null
+      if (typeof restored.brokenPath === 'string') state.brokenPaths.push(restored.brokenPath)
+      state.timeline.push(row)
+      return row
+    }
+    row.reason = `${row.reason}；从暂存目录也恢复失败：${restored.reason ?? '恢复后仍不过校验'}`
+  }
+  state.timeline.push(row)
+  return row
+}
+
+/** 出错之后**立刻**复核的那一次（通道层每次"被杀/超时/占用"失败都会调它；幂等）。 */
+function noteInterrupted(state, { trigger = 'channel', error = null, deps = {} } = {}) {
+  if (state === null || state === undefined) return null
+  if (looksInterrupted(error) !== true) return null
+  return healPackageDir(state, { trigger, deps })
+}
+
+/**
+ * 收尾（**成功、失败、抛异常三条路都要跑**）：复核 → 坏了就恢复（备份 → 暂存目录）→ 同一判据再复核 →
+ * 备份收口（最多留 1 份）→ 产出如实报告。报告就是作业上的 `installRecovery` 字段。
+ */
+function settleInstallRecovery(state, { deps = {} } = {}) {
+  if (state === null || state === undefined) return null
+  const session = state.session
+  const io = { ...(session.deps ?? {}), ...(deps ?? {}) }
+  const after0 = inspectPackageDir(session.packageDir, session.packageName, io)
+  let heal = null
+  if (after0.ok !== true) heal = healPackageDir(state, { trigger: 'settle', deps: io })
+  const after = inspectPackageDir(session.packageDir, session.packageName, io)
+  const verified = after.ok === true
+  const healed = state.healCount > 0
+  // `landed` = 这次安装**真的落地了**：目录完整 **且** 盘上那份不是"恢复回来的旧版"。
+  // 只看 verified 不够（真机现场：恢复完目录当然完整，但那一份是**更新前**的旧版）；
+  // 只看 healed 也不够（"pnpm 超时被杀 → 恢复旧版 → curl 后来真的装上了"是成功，不能报失败）——
+  // 两者之间的判据就是 `pendingHeal`：恢复之后有没有通道成功写入过。
+  const landed = verified === true && state.pendingHeal !== true
+  // `problem` = 到底坏在哪（如实描述现场）；`reason` = 收尾时的结论（含恢复动作的结果）
+  const problem = after0.ok !== true
+    ? (after0.reason ?? '目录里没有可读的 package.json')
+    : (healed === true ? '目录在安装过程中被清空过（恢复动作发生在通道失败的那一刻，见 timeline）' : null)
+  const reason = landed === true
+    ? null
+    : (problem ?? heal?.reason ?? '安装过程把目录弄坏了（目录已不可用）')
+  const backupPath = session.backedUp === true ? session.backupPath : null
+  // 备份收口（与 self-update-guard 同一口径）：这次更新**落地了**才删本次备份；失败/恢复过就留着（那是唯一旧版）
+  const dropped = landed === true ? dropBackupOf(backupPath) : null
+  const pruned = pruneSelfBackups(session.packageDir, { keep: KEEP_BACKUPS, deps: io })
+  const report = {
+    packageName: session.packageName,
+    packageDir: session.packageDir,
+    targetVersion: session.targetVersion ?? null,
+    previousVersion: session.previousVersion ?? null,
+    before: { ok: session.before.ok === true, version: session.before.version ?? null, hasManifest: session.before.hasManifest === true },
+    after: { ok: after.ok === true, version: after.version ?? null, hasManifest: after.hasManifest === true },
+    backedUp: session.backedUp === true,
+    backupPath,
+    backupNote: session.backupReason ?? null,
+    backupSkipped: session.backupSkipped === true,
+    verified,
+    healed,
+    landed,
+    restoredFrom: state.savedFrom,
+    restoredVersion: state.savedVersion ?? after.version ?? null,
+    brokenPath: state.brokenPaths.length > 0 ? state.brokenPaths[state.brokenPaths.length - 1] : null,
+    versionDirection: versionDirection(session.previousVersion, after.version ?? null),
+    problem,
+    reason,
+    selfHeal: {
+      attempted: heal !== null,
+      restored: heal?.restored === true,
+      reason: heal?.reason ?? null,
+      mode: heal?.restoredFrom ?? null,
+    },
+    timeline: state.timeline,
+    backupCleanup: { removed: [...(dropped !== null && dropped.removed === true ? [backupPath] : []), ...pruned.removed], kept: pruned.kept, note: dropped?.note ?? pruned.note ?? null },
+    manualCommand: null,
+  }
+  if (verified !== true) {
+    report.manualCommand = manualRestoreCommand({
+      pkgDir: session.packageDir,
+      backupPath,
+      version: session.targetVersion ?? session.previousVersion,
+      // 包名走既有注入缝（self-update-guard 的 selfName），这样命令里取的 tarball 是**这个包**的
+      deps: { ...io, selfName: session.packageName },
+    })
+  }
+  return report
+}
+
+/**
+ * 通道代理：每次"被杀/超时/占用"类失败 ⇒ **立刻**复核 + 恢复，再把原错误抛回去
+ * （既有语义不变：通道失败照旧被上层吞成"没装成"）。
+ * 另外记一件事：恢复之后**只要还有通道成功写入**，就说明盘上那份不再是"恢复回来的旧版" ⇒
+ * 清掉 `pendingHeal`（否则"pnpm 超时被杀 → 恢复旧版 → curl 后来装成功"会被误判成失败）。
+ */
+function wrapChannelsWithRecovery(ch, state, deps = {}) {
+  if (ch === null || ch === undefined || typeof ch !== 'object') return ch
+  const wrapped = { ...ch }
+  for (const key of ['raceInstallChannels', 'pnpmInstall', 'curlManualInstall', 'githubReleaseInstall']) {
+    if (typeof ch[key] !== 'function') continue
+    wrapped[key] = async (...callArgs) => {
+      let out = null
+      try {
+        out = await ch[key](...callArgs)
+      } catch (error) {
+        try { noteInterrupted(state, { trigger: `channel:${key}`, error, deps }) } catch {}
+        throw error
+      }
+      // "通道成功"的判据：竞速通道返回非空才算有赢家；其余通道能正常返回就算写成功了
+      const succeeded = key === 'raceInstallChannels' ? (out !== null && out !== undefined) : true
+      if (succeeded === true) state.pendingHeal = false
+      return out
+    }
+  }
+  return wrapped
+}
+
+/**
+ * 接线外壳（被 domain/install-channels.js#runSelfUpdateGuarded 调用）：
+ *   · 不接管（session=null）⇒ `run(null)`，用**原来的**通道对象，一个字节都不多走；
+ *   · 接管 ⇒ 通道换成带"被杀即复核"的代理，收尾统一 settle，并把报告挂到 `job.installRecovery`。
+ * 返回值的语义与不改时**一样**（{ installedName, lastError, source }），唯一的例外是
+ * "通道说装上了、但目录其实已经坏了" —— 那一条改判成没装上（绝不报成功）。
+ */
+async function withInstallRecovery({ job = null, name = '', profileDir = '', targetVersion = null, ch = null, deps = {} } = {}, run) {
+  const session = beginInstallRecovery({ packageName: name, profileDir, targetVersion, job, deps })
+  if (session === null) return await run(null)
+  const state = makeRecoveryState(session)
+  const guarded = wrapChannelsWithRecovery(ch, state, deps)
+  let outcome = null
+  let thrown = null
+  try {
+    outcome = await run(guarded)
+  } catch (error) {
+    thrown = error
+  }
+  const report = settleInstallRecovery(state, { deps })
+  if (job !== null && job !== undefined && typeof job === 'object') job.installRecovery = report
+  if (thrown !== null) throw thrown
+  // 通道说"装上了"不算数：**目录完整 且 不是靠恢复旧版救回来的**才算这次真的落地。
+  // （只看 verified 会把"恢复成旧版后的完整目录"当成更新成功 —— 那正是真机谎报的形状。）
+  if (outcome !== null && outcome !== undefined && outcome.installedName !== null && outcome.installedName !== undefined && report.landed !== true) {
+    return { installedName: null, lastError: new Error(installRecoveryFailureText(report) ?? '安装没有落地（目录已不可用）') }
+  }
+  return outcome
+}
+
+/**
+ * 失败文案（作业 error / 面板提示共用一份；**这次真的落地了**才返回 null）。
+ * 一次说清四件事：没通过的原因、自愈有没有成、残缺目录留在哪、手动命令是什么。
+ */
+function installRecoveryFailureText(report) {
+  if (report === null || report === undefined || typeof report !== 'object') return null
+  if (report.landed === true) return null
+  const parts = [`安装没有落地：安装过程把 ${report.packageDir ?? '插件目录'} 弄坏了（${report.problem ?? report.reason ?? '目录里没有可读的 package.json'}）。`]
+  if (report.healed === true) {
+    const from = report.restoredFrom === 'staging' ? 'pnpm 暂存目录' : '更新前的备份'
+    parts.push(`已从${from}自动恢复成 v${report.restoredVersion ?? '?'}，本次更新**没有生效**（这不是更新成功）。`)
+  } else if (report.backedUp !== true) {
+    parts.push(`无法自动恢复：${report.selfHeal?.reason ?? report.backupNote ?? '更新前没能建立备份'}。`)
+  } else {
+    parts.push(`自动恢复也失败了：${report.selfHeal?.reason ?? '原因未知'}。`)
+  }
+  if (typeof report.brokenPath === 'string' && report.brokenPath !== '') {
+    parts.push(`残缺目录已改名保留在 ${report.brokenPath}（未删除，可自行核对）。`)
+  }
+  if (typeof report.manualCommand === 'string' && report.manualCommand !== '') {
+    parts.push(`要手动处理可直接复制运行：${report.manualCommand}`)
+  }
+  return parts.join('')
+}
+
+export {
+  MAX_BACKUP_BYTES,
+  STAGING_MARK,
+  KEEP_BACKUPS,
+  packageDirOf,
+  isLinkedDir,
+  dirBytes,
+  inspectPackageDir,
+  looksInterrupted,
+  versionDirection,
+  findStagingDir,
+  findLatestBackup,
+  beginInstallRecovery,
+  makeRecoveryState,
+  healPackageDir,
+  noteInterrupted,
+  settleInstallRecovery,
+  wrapChannelsWithRecovery,
+  withInstallRecovery,
+  installRecoveryFailureText,
+}

package/lib/server/domain/install.js

@@ -510,6 +510,15 @@ function installJobView(job) {
     // 更新会出现，**非自更新作业恒 null**（既有契约一字不改）。`verified:false` ⇒ 作业必为 failed 且 job.error
     // 已写清原因/残缺目录/手动命令；`healed:true` ⇒ 已从备份恢复成更新前的版本（那不是"更新成功"）。
     selfUpdate: job.selfUpdate ?? null,
+    // 同一个包互斥的结果（2026-11-04 加法，见 domain/install-lock.js 顶部现场）：`queued:true` ⇒ 本次在排队
+    // 等前一个作业（有 `waitedMs` 就能看出等了多久）；`timeout:true` ⇒ 排队超时、本次**没装**（job.error 已写清）。
+    // 非并发场景恒 null（既有契约一字不改）。
+    installLock: job.installLock ?? null,
+    // 通用"超时/中断把目录弄坏 ⇒ 复核 + 恢复"的结论（2026-11-04 加法，见 domain/install-recovery.js 顶部）：
+    // `verified:false` ⇒ 这次尝试被改判成"没装上"（job.error 已写清原因/残缺目录/手动命令）；
+    // `healed:true` ⇒ 已从更新前的备份（或 pnpm 暂存目录）恢复成旧版 —— **那不是更新成功**。
+    // 只在"安装前目录里就有一份完整副本"时出现（首次安装 / link: 安装恒 null，既有契约一字不改）。
+    installRecovery: job.installRecovery ?? 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/plugin-actions.js

@@ -39,6 +39,10 @@ import { join } from 'node:path'
 import { applyAllowBuilds, pendingApprovedBuilds, readWorkspaceApprovals } from './allow-builds.js'
 import { NPM_NAME_RE, sameSourceSpec, suggestedAllowBuildsAction } from './dep-source.js'
 import { classifyInstallFailure, ignoredBuildsFrom } from './install-diagnose.js'
+// 同一个 profile + 包名 的安装互斥（2026-11-04 加法，见 domain/install-lock.js 顶部现场）：
+// 本模块的两个动作（pin-dependency / real-install）都会跑 `pnpm add`，动的就是 `node_modules/<包名>`
+// 那一份目录 —— 与安装作业（domain/install-channels.js）必须串行，否则就是真机事故的重演。
+import { withInstallLockOr } from './install-lock.js'
 import { runLockfileRepair } from './lockfile-health.js'
 import { pinProfileDependency, specOf } from './manifest.js'
 import { ensurePersisted } from './persist.js'
@@ -129,6 +133,19 @@ function isReleaseAgeBlock(message) {
   return /ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION|minimumReleaseAge/iu.test(String(message ?? ''))
 }
 
+/**
+ * 过**包互斥闸**跑一次 pnpm（2026-11-04 加法）：动作会把 `node_modules/<包名>` 重写一遍，与安装作业
+ * 动的是同一份目录 ⇒ 必须排队。拿不到锁 ⇒ 返回一份**如实失败**的结果（`locked: true` + reason），
+ * 绝不降级成"不拿锁照样装"，也绝不报成功。
+ */
+async function runAddUnderLock({ profileDir, packageName, timeoutMs, run }) {
+  return await withInstallLockOr(
+    { profileDir, packageName },
+    async () => ({ locked: false, result: await run() }),
+    (error) => ({ locked: true, reason: error.message, result: { ok: false, exitCode: null, stdout: '', stderr: '', relaxedReleaseAge: false, error, argv: [] } }),
+  )
+}
+
 /** 跑一次 pnpm（原样），必要时**只对这一条命令**放宽供应链闸并如实标记。
  *  返回 { ok, exitCode, stdout, stderr, relaxedReleaseAge, error }。
  *
@@ -186,6 +203,7 @@ async function runSuggestedAction({ body, profileDir, registries = [], deps = {}
     registry, exitCode: null, command: null, stdout: '', stderr: '', relaxedReleaseAge: false,
     manifest: null, lock: null, notes: [], reason: null, hint: null, detail: null,
     kind: parsed.action, ignoredBuilds: [], nextAction: null,
+    locked: false, // 2026-11-04 加法：true = 这个包正被别的作业装着，本次**没有**启动 pnpm（如实失败）
   }
   if (parsed.action === 'allow-builds') {
     const applyAllow = typeof deps.applyAllow === 'function' ? deps.applyAllow : applyAllowBuilds
@@ -326,7 +344,19 @@ async function runSuggestedAction({ body, profileDir, registries = [], deps = {}
       }
     }
     const before = await specOf(profileDir, parsed.packageName)
-    const run = await runAddWithReleaseAgeRetry({ profileDir, spec: record.spec, registry, runAdd, timeoutMs: ACTION_ADD_TIMEOUT_MS })
+    // 过包互斥闸（见上方 runAddUnderLock）：拿不到锁 ⇒ 如实失败，连 pnpm 都不启动
+    const runGuard = await runAddUnderLock({
+      profileDir, packageName: parsed.packageName, timeoutMs: ACTION_ADD_TIMEOUT_MS,
+      run: async () => await runAddWithReleaseAgeRetry({ profileDir, spec: record.spec, registry, runAdd, timeoutMs: ACTION_ADD_TIMEOUT_MS }),
+    })
+    const run = runGuard.result
+    if (runGuard.locked === true) {
+      return {
+        ...base, ok: false, status: 200, locked: true, error: runGuard.reason, reason: runGuard.reason,
+        command: `pnpm ${pnpmAddArgs(record.spec, registry).join(' ')}`,
+        notes: ['这个包正在被另一个作业安装/更新：本次没有启动 pnpm，也没有动任何文件（排到队尾再试即可）。'],
+      }
+    }
     const after = await specOf(profileDir, parsed.packageName)
     const entry = lockVersion(profileDir, parsed.packageName)
     const failure = run.ok === true ? null : classifyInstallFailure(`${run.stderr}\n${String(run.error?.message ?? '')}`)
@@ -391,7 +421,12 @@ async function runSuggestedAction({ body, profileDir, registries = [], deps = {}
   const timeoutMs = Number.isFinite(deps.timeoutMs) && deps.timeoutMs > 0
     ? deps.timeoutMs
     : (pendingBuilds.pending === true ? ACTION_BUILD_TIMEOUT_MS : ACTION_ADD_TIMEOUT_MS)
-  const run = await runAddWithReleaseAgeRetry({ profileDir, spec: pinned.spec, registry, runAdd, timeoutMs })
+  // 过包互斥闸（见上方 runAddUnderLock）：pin 的这一步会重铺 node_modules 里那一份 —— 必须与安装作业串行
+  const runGuard = await runAddUnderLock({
+    profileDir, packageName: parsed.packageName, timeoutMs,
+    run: async () => await runAddWithReleaseAgeRetry({ profileDir, spec: pinned.spec, registry, runAdd, timeoutMs }),
+  })
+  const run = runGuard.result
   const after = await specOf(profileDir, parsed.packageName)
   const entry = lockVersion(profileDir, parsed.packageName)
   const lockSynced = typeof entry === 'string' && entry.startsWith('link:')
@@ -405,6 +440,10 @@ async function runSuggestedAction({ body, profileDir, registries = [], deps = {}
   const ignoredBuilds = ignored === true ? ignoredBuildsFrom(run.stderr) : []
   const nextAction = ignored === true ? suggestedAllowBuildsAction({ packages: ignoredBuilds, profile: parsed.profile, reason: 'pnpm 因构建脚本未获批准而报错' }) : null
   const notes = []
+  if (runGuard.locked === true) {
+    // 拿不到包互斥锁：pnpm 一步都没启动。清单可能已经写成 link:（pin 的第一步），要把这半件事如实说清
+    notes.push('这个包正在被另一个作业安装/更新：本次**没有启动 pnpm**，也没有动 node_modules 里那一份（排到队尾再试即可）。')
+  }
   if (run.relaxedReleaseAge) notes.push('本机 pnpm 的 24h 供应链闸（minimumReleaseAge）拦下了这次 lock 校验，已**仅对这一条命令**追加 --config.minimumReleaseAge=0 重试一次（有安全代价，未写进任何配置文件）。')
   if (pendingBuilds.pending === true) {
     notes.push(`本 profile 已有放行项但还没构建过：本次 pnpm 那一步会真的执行构建脚本（本机实测约 19 分钟），`
@@ -434,6 +473,7 @@ async function runSuggestedAction({ body, profileDir, registries = [], deps = {}
     // 只有"清单真的是 link: **且** lock 里也有这条 link"才算成功；只成一半时 partial=true 并如实说明
     ok: manifests.pinned && lockSynced,
     partial: manifests.pinned && !lockSynced,
+    locked: runGuard.locked === true,
     exitCode: run.exitCode,
     command: `pnpm ${argv.join(' ')}`,
     stdout: run.stdout,
@@ -444,9 +484,11 @@ async function runSuggestedAction({ body, profileDir, registries = [], deps = {}
     lock: { entry: entry ?? null, synced: lockSynced },
     notes,
     failureKind: failure?.kind ?? null,
-    reason: manifests.pinned
-      ? (lockSynced ? `${parsed.packageName} 已钉住：清单与 pnpm-lock.yaml 都指向 link:${pinned.dir}` : `${parsed.packageName} 的清单已钉住，lock 未对齐`)
-      : `${parsed.packageName} 的清单写回未生效（实际是 ${after ?? '（无该条目）'}）`,
+    reason: runGuard.locked === true
+      ? runGuard.reason
+      : (manifests.pinned
+        ? (lockSynced ? `${parsed.packageName} 已钉住：清单与 pnpm-lock.yaml 都指向 link:${pinned.dir}` : `${parsed.packageName} 的清单已钉住，lock 未对齐`)
+        : `${parsed.packageName} 的清单写回未生效（实际是 ${after ?? '（无该条目）'}）`),
   }
 }
 

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'
+// 同一个 profile + 包名 的安装互斥（2026-11-04 加法，见 domain/install-lock.js 顶部现场）：
+// 「插件卡片的更新」与「市场页那颗自更新 pill」动的是**同一个** node_modules/<控制台> 目录 —— 必须串行。
+import { withInstallLockOr } from './install-lock.js'
 // 自更新兜底（2026-11-03 加法，见 self-update-guard.js 顶部事故记录）：
 // begin/note/settle 是同一套判据与同一份 manualCommand；finishSelfUpdate 是本文件收尾段**原样搬出**的（腾行数用）。
 import { beginSelfUpdateGuard, finishSelfUpdate, noteGuardStep, settleSelfUpdateGuard } from './self-update-guard.js'
@@ -113,8 +116,27 @@ function selfUpdateCommand(latest, profileName = '<你的profile>') {
  * 把控制台升到 `latest` 并**确保写进 lock**。
  * 依赖以参数注入（便于单测替换）：`runPnpm`（默认 runPnpmWithFallback）、`pnpmAdd`（默认 pnpmInstall）、
  * `curlManualInstall`（手铺文件兜底，由路由传入）。
+ *
+ * ★ 2026-11-04 加法（唯一的改动，见 domain/install-lock.js 顶部现场）：整段操作过**同一个包互斥闸** ——
+ *   这条路和插件卡片的「更新」（`/install` → domain/install-channels.js）动的是**同一个**
+ *   `node_modules/@noob-stupid/dsh-plugin-console`，真机事故就是两边同时装这个包。
+ *   拿不到锁 ⇒ 如实返回"正在安装中"（ok=false + reason），**不装、不碰目录**（结构同 finishSelfUpdate）。
  */
-async function selfUpdateToLatest({ profileDir, latest, registries, curlManualInstall, runPnpm = runPnpmWithFallback, pnpmAdd = pnpmInstall, profileName = null, execOpts = {}, selfUpdateDeps = {} }) {
+async function selfUpdateToLatest(args = {}) {
+  return await withInstallLockOr(
+    { profileDir: args?.profileDir, packageName: CONSOLE_PACKAGE },
+    async () => await selfUpdateToLatestLocked(args),
+    (error) => ({
+      method: null, spec: profileSpec(args?.profileDir ?? '', CONSOLE_PACKAGE), installedVersion: readInstalledVersion(args?.profileDir ?? '', CONSOLE_PACKAGE),
+      lockVersion: lockVersion(args?.profileDir ?? '', CONSOLE_PACKAGE), lockUpdated: false, lockNote: null,
+      command: selfUpdateCommand(args?.latest, args?.profileName ?? '<你的profile>'), note: error.message, errors: [error.message],
+      ok: false, reason: error.message, selfUpdate: null,
+    }),
+  )
+}
+
+/** 上面那个互斥外壳里的正文（原来的函数体，逐字未改）。 */
+async function selfUpdateToLatestLocked({ 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 = []

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

@@ -32,6 +32,7 @@ import { PLUGIN_SRC_DIR, linkSpecFor, sameSourceSpec } from './dep-source.js'
 import { noteChannel } from './git-channel.js'
 import { addBundleToManifest, detectBundleOnly } from './install.js'
 import { finalizeInstallPersistence } from './install-finalize.js'
+import { INSTALL_LOCK_TIMEOUT, withInstallLock } from './install-lock.js'
 import { alreadyInstalledTarget, verifyInstalledEntry } from './install-verify.js'
 import { ensureLinkSelfSufficiency } from './link-self-sufficiency.js'
 import { setProfileDependency } from './manifest.js'
@@ -313,9 +314,15 @@ async function runSubdirInstallJobInner(job, ports, deps = {}) {
     job.subdirSource = { dir, from: acquired.dir, reused: acquired.reused === true, placed: placed.dir, version: recheck.version }
     // ⑥ 本地目录来源 = 既有安装通道：`pnpm add link:<目录>` 建起 node_modules 里的那条链接
     //    （link: 是本地目录的正常形态，见 source-spec.js 判据 C；依赖由下一步的自足性补齐）
+    //    ★ 2026-11-04：过**同一个包互斥闸**（domain/install-lock.js）—— 它动的也是 node_modules/<包名>
     try {
-      await channels.pnpmInstall(profileDir, spec, undefined)
+      await withInstallLock({ profileDir, packageName, job }, async () => await channels.pnpmInstall(profileDir, spec, undefined))
     } catch (error) {
+      // 排队等不到（INSTALL_LOCK_TIMEOUT）与 pnpm 真失败都是"没装上"，但文案必须分开（不把排队说成安装失败）
+      if (error?.code === INSTALL_LOCK_TIMEOUT) {
+        job.installLock = { ...(job.installLock ?? {}), timeout: true, reason: error.message }
+        return failSubdirInstall(job, error.message)
+      }
       return failSubdirInstall(job, `从子目录 ${dir}/ 安装失败（本地目录来源 ${spec}）：${error instanceof Error ? error.message : String(error)}。`
         + `源码已取到本地（${placed.dir}），可重试；重试会复用已取到的源码。`)
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noob-stupid/dsh-plugin-console",
-  "version": "0.5.101",
+  "version": "0.5.102",
   "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",