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

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,
+}