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

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

@@ -281,6 +281,168 @@ async function writeLockImporterEntry(profileDir, { name, spec, section = IMPORT
   })
 }
 
+/**
+ * **registry 版本**的 lock 定点写入（2026-11-04 加法，自更新手铺兜底专用）：
+ * 一次动作把该包的三处写到目标版本 —— ① importer 条目（`specifier` + `version`，走**同一个**规划器
+ * `planLockImporterEntry`）；② `packages:` 键名里的版本 + `resolution.integrity`；③ `snapshots:` 键名里的版本。
+ * 为什么走本模块（而不是另写一套 lock 解析）：lock 的**唯一**写入口就在这里（读 → 纯函数规划 → 写 → 读回核实
+ * → 走 fsx 的写队列），自更新的"补 lock"必须复用同一把尺子，否则读得出来的键写得进去、写的键读不出来。
+ *
+ * 与 `writeLockImporterEntry` 的差别只有一处：那个只认 `link:` 来源（`lockVersionText` 对版本号返回 null，
+ * 因为 registry 依赖的 lock 记录**不止** importer 一行）；这里由调用方**显式**给出目标版本与完整性，
+ * 再交给 `planLockVersionKeys` 处理那两段。给出完整性才写完整性（见那个函数的保守规则③）。
+ * 返回 `{ changed, unchanged, specifier, version, importerChanged, renamed, integrityWritten, reason }`。
+ */
+async function writeLockRegistryVersion(profileDir, { name, spec, version, integrity = null, section = IMPORTER_SECTIONS[0], deps = {} } = {}) {
+  const readText = typeof deps.readText === 'function' ? deps.readText : (p) => readFileSync(p, 'utf8')
+  const writeText = typeof deps.writeText === 'function' ? deps.writeText : (p, text) => writeFileSync(p, text, 'utf8')
+  const file = join(String(profileDir), LOCKFILE_NAME)
+  const want = typeof version === 'string' ? version.trim() : ''
+  const specifier = typeof spec === 'string' && spec.trim() !== '' ? spec.trim() : want
+  const fail = (reason) => ({ changed: false, unchanged: false, specifier, version: want, importerChanged: false, renamed: { packages: false, snapshots: false }, integrityWritten: false, reason })
+  if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/u.test(want)) return fail(`目标版本 ${want === '' ? '（空）' : want} 不是裸版本号 —— 不往 lock 里写非版本形态`)
+  return queuedWrite(async () => {
+    let text = null
+    try {
+      text = await readText(file)
+    } catch (error) {
+      return fail(`读不到 ${LOCKFILE_NAME}（${error instanceof Error ? error.message : String(error)}），未写入`)
+    }
+    const importerPlan = planLockImporterEntry(text, { name, specifier, version: want, section })
+    if (importerPlan.ok !== true) return fail(importerPlan.reason ?? 'lock importer 段规划失败（形态不认识），未写入')
+    const keysPlan = planLockVersionKeys(importerPlan.text, { name, toVersion: want, integrity })
+    if (keysPlan.ok !== true) return fail(keysPlan.reason ?? 'packages/snapshots 段规划失败，未写入')
+    const next = keysPlan.text
+    const importerChanged = importerPlan.changed === true
+    if (next === text) {
+      return { changed: false, unchanged: true, specifier: importerPlan.specifier ?? specifier, version: want, importerChanged, renamed: keysPlan.renamed, integrityWritten: keysPlan.integrityWritten, reason: keysPlan.reason ?? null }
+    }
+    try {
+      await writeText(file, next)
+    } catch (error) {
+      return fail(`写盘失败：${error instanceof Error ? error.message : String(error)}`)
+    }
+    let after = null
+    try {
+      after = await readText(file)
+    } catch (error) {
+      return fail(`写盘后读回失败：${error instanceof Error ? error.message : String(error)}`)
+    }
+    if (after !== next) return fail('写盘后读回与预期不一致（未能核实），按未写入处理')
+    return { changed: true, unchanged: false, specifier: importerPlan.specifier ?? specifier, version: want, importerChanged, renamed: keysPlan.renamed, integrityWritten: keysPlan.integrityWritten, reason: keysPlan.reason ?? null }
+  })
+}
+
+/**
+ * `packages:` / `snapshots:` 段里 `'<name>@<版本>'` 键行的定位（同一个包的所有**解析记录**行）。
+ * 只认这两段的键行（段头顶格 + 2 空格缩进的键），避免把 importers 里的同名条目、或别的包读进来。
+ * 返回 `[{ index, section, indent, version, quoted }]`；版本里可能带 peer 后缀 `(peer@1.0.0)`，原样保留。
+ */
+function resolutionKeyRows(lines, name) {
+  const escaped = String(name).replace(/[/\\^$*+?.()|[\]{}]/gu, '\\$&')
+  // 键行形态三种都认：`'name@1.0.0':`、`name@1.0.0:`、`'name@1.0.0': {}`（真机 lock 的 snapshots 就是最后一种）
+  const keyRe = new RegExp(`^(\\s*)'?${escaped}@([^\\s']+?)'?\\s*:\\s*(\\{.*\\})?\\s*$`, 'u')
+  const rows = []
+  let section = null
+  for (let i = 0; i < lines.length; i += 1) {
+    const top = /^([A-Za-z][A-Za-z0-9_]*):\s*$/u.exec(lines[i])
+    if (top !== null) {
+      section = top[1]
+      continue
+    }
+    if (section !== 'packages' && section !== 'snapshots') continue
+    const m = keyRe.exec(lines[i])
+    if (m === null) continue
+    rows.push({ index: i, section, indent: m[1], version: m[2], rest: m[3] ?? null, quoted: lines[i].trim().startsWith("'") })
+  }
+  return rows
+}
+
+/**
+ * 纯函数：把 lock 里该包的**解析记录**（`packages:` / `snapshots:` 的键与 integrity）改到目标版本。
+ * 为什么需要它（2026-11-04 加法）：自更新的手铺兜底只把文件铺进去，`pnpm-lock.yaml` 里仍钉着旧版本 ——
+ * 那正是"更新成功、下一次 pnpm 操作又被还原"的老毛病。importer 条目由 planLockImporterEntry 负责
+ * （同一份规划器，不另写一套），这里只补它表达不了的那两段：键名里的版本 + `resolution.integrity`。
+ *
+ * 四条保守规则（**绝不猜**，做不到就一个字节都不写并把原因带回去）：
+ *   ① 没有**该版本**的完整性摘要（registry 元数据 `dist.integrity`）⇒ 整段都不动 —— 把旧版本的 integrity
+ *      挂到新版本号下面比"不写"更糟（pnpm 会 ERR_PNPM_TARBALL_INTEGRITY）；
+ *   ② 只有**唯一**一个陈旧键、且它的块里有**单行** `resolution: {…}` 才改名（版本与完整性必须一起落地）；
+ *   ③ 目标版本键已存在 ⇒ 不改名，只把 integrity 补成该版本的；
+ *   ④ snapshots 段只在 packages 段真的改成功之后才跟着改（两段保持一致）。
+ * 返回 `{ ok, changed, text, renamed:{packages,snapshots}, integrityWritten, reason }`。
+ */
+function planLockVersionKeys(text, { name, toVersion, integrity = null } = {}) {
+  const src = typeof text === 'string' ? text : String(text ?? '')
+  const want = typeof toVersion === 'string' ? toVersion.trim() : ''
+  const digest = typeof integrity === 'string' ? integrity.trim() : ''
+  const unchanged = (reason) => ({ ok: true, changed: false, text: src, renamed: { packages: false, snapshots: false }, integrityWritten: false, reason })
+  if (want === '') return { ...unchanged('没有目标版本，未改动'), ok: false }
+  if (digest === '') return unchanged('没有该版本的完整性摘要（registry 元数据缺失）⇒ 未改 packages/snapshots 段（绝不把旧 integrity 挂到新版本号上）')
+  const eol = /\r\n/u.test(src) ? '\r\n' : '\n'
+  const trailing = /\r?\n$/u.test(src)
+  const lines = src.split(/\r?\n/u)
+  if (trailing && lines.length > 0 && lines[lines.length - 1] === '') lines.pop()
+  const rows = resolutionKeyRows(lines, name)
+  if (rows.length === 0) return unchanged('lock 里没有该包的 packages/snapshots 解析记录（下一次 pnpm 操作会自己补出来），未改动')
+  const out = [...lines]
+  const renamed = { packages: false, snapshots: false }
+  let integrityWritten = false
+  const reasons = []
+  /** 在该行所属块的 `resolution:` 行上换 integrity；块里没有单行 resolution 就什么都不写（不伪造结构）。 */
+  const writeIntegrity = (row) => {
+    for (let k = row.index + 1; k < out.length; k += 1) {
+      if (out[k].trim() !== '' && !/^\s{3,}/u.test(out[k])) break
+      const m = /^(\s*resolution:\s*)\{[^}]*\}(\s*)$/u.exec(out[k])
+      if (m === null) continue
+      if (!out[k].includes(digest)) {
+        out[k] = `${m[1]}{integrity: ${digest}}${m[2]}`
+        integrityWritten = true
+      }
+      return true
+    }
+    return false
+  }
+  for (const section of ['packages', 'snapshots']) {
+    const mine = rows.filter((r) => r.section === section)
+    if (mine.length === 0) continue
+    const fresh = mine.filter((r) => r.version === want || r.version.startsWith(`${want}(`))
+    if (fresh.length > 0) {
+      if (section === 'packages' && writeIntegrity(fresh[0]) !== true) reasons.push('packages 里的条目没有单行 resolution 记录 ⇒ integrity 未写（不伪造结构）')
+      continue
+    }
+    if (mine.length > 1) {
+      reasons.push(`${section} 里有 ${mine.length} 个陈旧键（${mine.map((r) => r.version).join('、')}）—— 未改名（不猜该留哪一个）`)
+      break
+    }
+    const row = mine[0]
+    const suffix = /\(.*\)$/u.exec(row.version)?.[0] ?? ''
+    const keyBody = row.quoted ? `'${name}@${want}${suffix}':` : `${name}@${want}${suffix}:`
+    const nextKey = `${row.indent}${keyBody}${row.rest === null ? '' : ` ${row.rest}`}`
+    // 规则②：版本与完整性必须**一起**落地 —— 先在草稿上换 integrity，换不成就整体放弃这一段
+    const draft = [...out]
+    const saved = out[row.index]
+    out[row.index] = nextKey
+    if (section === 'packages' && writeIntegrity(row) !== true) {
+      out[row.index] = saved
+      reasons.push('packages 里的条目没有单行 resolution 记录 ⇒ 未改名（版本与完整性必须一起落地，不伪造结构）')
+      for (let k = 0; k < draft.length; k += 1) out[k] = draft[k]
+      integrityWritten = false
+      break
+    }
+    renamed[section] = true
+  }
+  const changed = renamed.packages || renamed.snapshots || integrityWritten
+  return {
+    ok: true,
+    changed,
+    text: changed ? out.join(eol) + (trailing ? eol : '') : src,
+    renamed,
+    integrityWritten,
+    reason: changed ? null : (reasons.join('；') || null),
+  }
+}
+
 /**
  * 从 lock 自己的 `settings:` 段取出 pnpm 配置，供**只读**校验按 lock 的形态复算
  * （不镜像它时 pnpm 直接 `ERR_PNPM_LOCKFILE_CONFIG_MISMATCH`：本机实测 `autoInstallPeers`）。
@@ -405,7 +567,10 @@ export {
   lockVersionText,
   lockfileSettingsFlags,
   planLockImporterEntry,
+  planLockVersionKeys,
+  resolutionKeyRows,
   verifyArgsFor,
   verifyLockReadOnly,
   writeLockImporterEntry,
+  writeLockRegistryVersion,
 }

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

@@ -474,7 +474,7 @@ function settleSelfUpdateGuard(session, { targetVersion = undefined, deps = {} }
  *   · 校验没过时把那段失败文案同时推进 `errors` 与 `note`（面板/接口都看得见）；
  *   · `installedVersion` 在"已自愈"时改报**盘上真实那一版**（否则会留一个 null 让人以为目录还是空的）。
  */
-function finishSelfUpdate({ profileDir, packageName, latest, spec, installed, method, command, errors, lockVersion, lockUpdated, lockNote, registryRange, selfUpdate = null }) {
+function finishSelfUpdate({ profileDir, packageName, latest, spec, installed, method, command, errors, lockVersion, lockUpdated, lockNote, registryRange, selfUpdate = null, copy = null, tarball = null, lockPatch = null }) {
   const CONSOLE_PACKAGE = packageName
   const isRegistryRange = registryRange
   const label = (e) => (e instanceof Error ? e.message : String(e))
@@ -505,6 +505,15 @@ function finishSelfUpdate({ profileDir, packageName, latest, spec, installed, me
   const noteParts = [lockUpdated ? '已写入 pnpm-lock.yaml，重启服务后生效' : '已铺入文件但未写入 pnpm-lock.yaml：重启后可用，但会被 pnpm 还原']
   if (sourceSwitch !== null) noteParts.push(sourceSwitch)
   if (specUpdated !== null) noteParts.push(`清单 spec 已同步为 ${specUpdated}（防 pnpm 降级）`)
+  // ★ 2026-11-04 加法：手铺那一步到底怎么铺的、lock 补没补上，都要让用户看得见（绝不静默）
+  if (copy !== null && copy !== undefined && copy?.channel === 'overlay') {
+    noteParts.push(`用预下载的 tarball 只覆盖了 ${copy.files ?? '?'} 个文件、**没有清空目录**（原地保留 ${copy.preserved ?? 0} 个不在 tarball 里的文件）`)
+  }
+  if (lockPatch !== null && lockPatch !== undefined && lockPatch?.attempted === true) {
+    if (lockPatch.changed === true && lockPatch.verified === true) noteParts.push(`pnpm-lock.yaml 已补齐 ${latest} 的版本/完整性并通过 pnpm 只读校验`)
+    else if (lockPatch.changed === true && lockPatch.verified === null) noteParts.push(`pnpm-lock.yaml 已补齐 ${latest} 的版本/完整性，但 pnpm 的只读校验**无法确认**（${lockPatch.verifyNote ?? '原因未知'}）`)
+    else if (lockPatch.reason !== null && lockPatch.reason !== undefined) noteParts.push(`pnpm-lock.yaml 未补齐：${lockPatch.reason}`)
+  }
 
   // ★ 加法：自更新校验的结论（只有"本插件自己 + 更新前就有完整副本"时 selfUpdate 才非空）
   const verified = selfUpdate === null || selfUpdate === undefined ? true : selfUpdate.verified === true
@@ -512,7 +521,7 @@ function finishSelfUpdate({ profileDir, packageName, latest, spec, installed, me
   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 }
+  return { method, spec: specUpdated ?? spec, installedVersion, lockVersion, lockUpdated, lockNote, command, note: noteParts.join('；'), errors, ok: verified, reason, selfUpdate: selfUpdate ?? null, copy: copy ?? null, tarball: tarball ?? null, lockPatch: lockPatch ?? null }
 }
 
 /**
@@ -543,6 +552,10 @@ function selfUpdateView({ result, current = null, latest = null }) {
     errors: result.errors,
     selfUpdate: result.selfUpdate ?? null,
     reason: result.reason ?? null,
+    // ★ 2026-11-04 加法（手铺兜底）：这三项只增不减 —— 既有字段名与取值语义一个都没动
+    copy: result.copy ?? null,
+    tarball: result.tarball ?? null,
+    lockPatch: result.lockPatch ?? null,
   }
 }
 

package/lib/server/domain/selfupdate-copy.js

@@ -0,0 +1,393 @@
+// L1 · domain —— selfupdate-copy.js（自更新的**手铺兜底**：先备好 tarball → 只覆盖文件、不清空目录 → 补 lock）
+//
+// ── 现场（真机 2026-11-04 实测采样，用户提供的原始时间线）─────────────────────────────────
+//   0.5.102 的自更新是「包管理器优先」：`pnpm update` → `pnpm add` → 才轮到手铺（见 domain/selfupdate.js 顶部）。
+//   pnpm 一启动就**先清空目标目录**再重算整棵依赖树；这一步在 profile 里要跑几分钟
+//   （`14:45:46 pkg=True files=160` → `14:45:56 pkg=False files=1`），于是：
+//     · 撞 90s/180s 超时被杀 → 目录停在"空了"的状态，跑了一整夜都没轮到第三步；
+//     · 就算第三步轮到了，既有 curl 通道也是"先 rmSync 整目录再 copyTree"（见 install.js#curlManualInstall），
+//       宿主正读着这些文件时更容易被 Windows 拒绝。
+//   ⇒ 用户要的：pnpm 卡住/失败时**立刻**手铺、并把 lock 一起补上（否则又会"更新成功、下次 pnpm 操作被还原"）。
+//
+// ── 本模块只做三件事（都不改既有通道的触发条件）──────────────────────────────────
+//   ① prepareSelfUpdateTarball：走 pnpm **之前**先用既有 curl/元数据链路把目标版本 tarball 备到手
+//      （失败**不影响**后续，只把原因记下来 —— 后面照样跑 pnpm 与既有 curl 通道）；
+//   ② overlaySelfUpdateTarball：用备好的 tarball **只覆盖文件、绝不清空目录**（copyTree 的语义，
+//      见 infra/fsx.js —— 它只 copyFileSync，不删任何东西），随后**读回** package.json 的版本与期望值比对；
+//   ③ patchSelfUpdateLock：把 `pnpm-lock.yaml` 里该包的版本/完整性更新到目标版本（**唯一**写入口仍是
+//      domain/lock-importer.js#writeLockRegistryVersion，本模块不另写一套 lock 解析），
+//      再用既有 `verifyLockReadOnly`（pnpm 只读用法）复核；复核明确不通过 ⇒ **把 lock 还原成改动前的字节**
+//      并如实上报（宁可报"没补上"，也绝不留下 pnpm 会拒绝的 lock）。
+//
+// ── 与既有实现的关系（复用，不另造一套）──────────────────────────────────────────
+//   · 盒子校验 `verifyPackageBox`（install-box.js）、覆盖复制 `copyTree`（fsx.js）、
+//     lock 写入/只读校验（lock-importer.js）、失败兜底与自愈（self-update-guard.js）全部是既有件；
+//   · 本模块**不判断"更新成功与否"**：那由 selfupdate.js 的回读核实 + 自更新守卫说了算。
+//
+// ── 边界（别越线）──────────────────────────────────────────────────────────────
+//   ① 只对**自更新**生效：由 selfupdate.js 在 `/self-update` 那条路里调用；装别的插件的通道一个字节都不经过这里。
+//   ② 拿不到 tarball / 没有该版本的完整性摘要 ⇒ 什么都不做（返回 reason），调用方回落到 0.5.102 的既有行为。
+//   ③ 覆盖失败（EPERM/EBUSY 等）⇒ 如实返回 reason，**不重试、不删目录、不谎报**。
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { verifyLockReadOnly, writeLockRegistryVersion } from './lock-importer.js'
+import { verifyPackageBox } from './install-box.js'
+import { execFileAsync } from '../infra/exec.js'
+import { copyTree, removeDirVerified } from '../infra/fsx.js'
+import { fetchJsonUrl } from '../infra/http.js'
+
+/** registry 元数据的超时（与既有 curl 通道同量级；拿不到就是拿不到，不许拖住自更新）。 */
+const META_TIMEOUT_MS = 15000
+/** tarball 下载超时（既有 curl 通道是 70s；这里 60s 封顶）。 */
+const DOWNLOAD_TIMEOUT_MS = 60000
+/** 解包超时（既有 curl 通道 30s）。 */
+const EXTRACT_TIMEOUT_MS = 30000
+/** 补完 lock 之后那次 pnpm **只读**校验的超时。刻意比 lock-importer 的 60s 短：
+ *  自更新这条路上 pnpm 本来就是"可能很慢"的那一环，不能为了复核再让用户多等一分钟；
+ *  超时按"**无法确认**"处理（verified=null），**不**回滚 —— 只有 pnpm 真的报错才回滚。 */
+const LOCK_VERIFY_TIMEOUT_MS = 20000
+/** 工作目录前缀（临时目录，跑完即删；名字里带随机段避免并发互撞）。 */
+const WORK_PREFIX = 'dsh-selfupdate-'
+
+/** registry 包名 → URL 段（与 install.js#curlManualInstall **同一口径**：scope 的 `/` 编成 `%2f`）。 */
+function encodePackageName(packageName) {
+  const name = String(packageName ?? '')
+  if (!name.startsWith('@')) return encodeURIComponent(name)
+  return `@${encodeURIComponent(name.slice(1).split('/')[0])}%2f${encodeURIComponent(name.split('/').slice(1).join('/'))}`
+}
+
+/** curl 可执行名（与既有通道一致：Windows 上是 curl.exe —— 有些环境里 PATH 上只有它）。 */
+function curlBin() {
+  return process.platform === 'win32' ? 'curl.exe' : 'curl'
+}
+
+/** 离线/测试模式：CI 里 `DSH_TEST_SKIP_NETWORK=1`（见 .github/workflows/test.yml），照着跳过网络。 */
+function networkBlocked(deps = {}) {
+  const env = typeof deps.env === 'object' && deps.env !== null ? deps.env : process.env
+  return String(env?.DSH_TEST_SKIP_NETWORK ?? '') === '1'
+}
+
+/** 建一个本次自更新专用的临时工作目录。 */
+function makeWorkDir(deps = {}) {
+  const base = typeof deps.tmpDir === 'function' ? deps.tmpDir() : tmpdir()
+  const dir = join(base, `${WORK_PREFIX}${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`)
+  mkdirSync(dir, { recursive: true })
+  return dir
+}
+
+/** 删掉一个工作目录并**核实**（infra/fsx.js#removeDirVerified：本机实测 `%TEMP%` 下 rmSync 会
+ *  **静默落空** —— 不抛错、目录仍在；临时目录里装着下载下来的 tarball，不能"以为删了"就算了）。
+ *  返回 `{ removed, note }`；没删掉时 note 里带绝对路径（用户可自己清）。 */
+function cleanWorkDir(dir) {
+  const target = typeof dir === 'string' ? dir : ''
+  if (target === '') return { removed: false, note: null }
+  const verdict = removeDirVerified(target)
+  if (verdict.ok === true) return { removed: true, note: null }
+  return { removed: false, note: `临时目录没删掉（${target}）：${verdict.error ?? '原因未知'}（可自行删除）` }
+}
+
+/** `curl -sL -m <秒> -o <tgz> <url>`（与 install.js#curlManualInstall 同一形态）。 */
+async function downloadToFile(url, tgz, { timeout = DOWNLOAD_TIMEOUT_MS, deps = {} } = {}) {
+  const run = typeof deps.exec === 'function' ? deps.exec : execFileAsync
+  await run(curlBin(), ['-s', '-L', '-m', String(Math.max(5, Math.ceil(timeout / 1000))), '-o', tgz, url], { timeout: timeout + 10000, windowsHide: true })
+}
+
+/** `tar -xzf <tgz> -C <dir>`（与既有通道同一形态）。 */
+async function extractTarball(tgz, dir, { deps = {} } = {}) {
+  const run = typeof deps.exec === 'function' ? deps.exec : execFileAsync
+  await run('tar', ['-xzf', tgz, '-C', dir], { timeout: EXTRACT_TIMEOUT_MS, windowsHide: true })
+}
+
+/** 解压目录里含 package.json 的那一层（npm tarball 恒为 `package/`，但别假设）。 */
+function findPackageDir(dir) {
+  const direct = join(dir, 'package')
+  if (existsSync(join(direct, 'package.json'))) return direct
+  let entries = []
+  try {
+    entries = readdirSync(dir, { withFileTypes: true })
+  } catch {
+    return null
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    const candidate = join(dir, entry.name)
+    if (existsSync(join(candidate, 'package.json'))) return candidate
+  }
+  return null
+}
+
+/** 目录里的文件相对路径集合（用于如实报"铺了几个文件、原地保留了几个"）。只读、失败返回空集。 */
+function filesUnder(dir) {
+  const out = new Set()
+  const walk = (current, prefix) => {
+    let entries = []
+    try {
+      entries = readdirSync(current, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const entry of entries) {
+      const rel = prefix === '' ? entry.name : `${prefix}/${entry.name}`
+      if (entry.isDirectory()) walk(join(current, entry.name), rel)
+      else if (entry.isFile()) out.add(rel)
+    }
+  }
+  if (existsSync(dir)) walk(dir, '')
+  return out
+}
+
+/**
+ * ① 预先备好目标版本的 tarball（**pnpm 之前**跑；失败只记原因，不阻断后续）。
+ * 走的是既有链路：registry 元数据（`fetchJsonUrl`，可注入）→ `meta.versions[版本].dist.tarball` → curl 下载。
+ * 返回 `{ ok, version, tgzPath, workDir, integrity, tarball, registry, reason, ms }`。
+ * `integrity` 来自元数据 `dist.integrity`（pnpm 自己写进 lock 的就是这个值）——
+ * 拿不到就为 null，调用方据此**不**改 lock 的 packages 段（绝不用旧版本的摘要顶替）。
+ */
+async function prepareSelfUpdateTarball({ packageName, version, registries = [], deps = {} } = {}) {
+  const startedAt = Date.now()
+  const out = { ok: false, version: typeof version === 'string' ? version : null, tgzPath: null, workDir: null, integrity: null, tarball: null, registry: null, reason: null, ms: 0 }
+  const label = (error) => (error instanceof Error ? error.message : String(error))
+  const fetchJson = typeof deps.fetchJson === 'function' ? deps.fetchJson : fetchJsonUrl
+  if (typeof version !== 'string' || version.trim() === '') {
+    out.reason = '没有目标版本，未预先下载 tarball'
+    return out
+  }
+  if (networkBlocked(deps)) {
+    out.reason = '已跳过网络（DSH_TEST_SKIP_NETWORK=1）—— 未预先下载 tarball'
+    return out
+  }
+  const regs = Array.isArray(registries) ? registries.filter((r) => typeof r === 'string' && r !== '') : []
+  if (regs.length === 0) {
+    out.reason = '没有可用的软件源，未预先下载 tarball'
+    return out
+  }
+  let dist = null
+  const metaErrors = []
+  for (const registry of regs) {
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      const meta = await fetchJson(`${registry}/${encodePackageName(packageName)}`, META_TIMEOUT_MS)
+      const record = meta?.versions?.[version]
+      if (record === undefined || record === null) {
+        metaErrors.push(`${registry}：元数据里没有 ${version} 这个版本`)
+        continue
+      }
+      const tarball = typeof record.dist?.tarball === 'string' ? record.dist.tarball : null
+      if (tarball === null) {
+        metaErrors.push(`${registry}：${version} 没有 dist.tarball`)
+        continue
+      }
+      dist = { registry, tarball, integrity: typeof record.dist?.integrity === 'string' && record.dist.integrity !== '' ? record.dist.integrity : null }
+      break
+    } catch (error) {
+      metaErrors.push(`${registry}：${label(error)}`)
+    }
+  }
+  if (dist === null) {
+    out.reason = `拿不到 ${version} 的 registry 元数据（${metaErrors.join('；') || '原因未知'}）`
+    out.ms = Date.now() - startedAt
+    return out
+  }
+  let workDir = null
+  try {
+    workDir = makeWorkDir(deps)
+    const tgzPath = join(workDir, 'pkg.tgz')
+    const download = typeof deps.download === 'function' ? deps.download : downloadToFile
+    await download(dist.tarball, tgzPath, { timeout: deps.downloadTimeoutMs ?? DOWNLOAD_TIMEOUT_MS, deps })
+    const size = existsSync(tgzPath) ? statSync(tgzPath).size : 0
+    if (size <= 0) throw new Error(`下载下来的 tarball 是空文件（${tgzPath}）`)
+    out.ok = true
+    out.version = version
+    out.tgzPath = tgzPath
+    out.workDir = workDir
+    out.integrity = dist.integrity
+    out.tarball = dist.tarball
+    out.registry = dist.registry
+    return out
+  } catch (error) {
+    out.reason = `下载 ${version} 的 tarball 失败：${label(error)}`
+    if (workDir !== null) {
+      cleanWorkDir(workDir)
+    }
+    return out
+  } finally {
+    out.ms = Date.now() - startedAt
+  }
+}
+
+/**
+ * ② 用备好的 tarball **只覆盖文件、不清空目录**地铺进 `node_modules/<包名>`，随后**读回**版本核实。
+ * 与既有 curl 通道的区别只有一条、但正是这条要命：**不先 rmSync 整目录**
+ * （宿主正读着这些文件时，删目录比覆盖文件更容易被 Windows 拒绝；而且删完再失败就只剩空目录）。
+ * 返回 `{ ok, version, files, preserved, boxNote, reason }`：`preserved` = 目录里原有的、**不在 tarball 里**的文件数
+ * （copyTree 一个都不删，这个数是给"没清空目录"作证的）。
+ */
+async function overlaySelfUpdateTarball({ prepared = null, profileDir, packageName, expectedVersion = null, deps = {} } = {}) {
+  const out = { ok: false, version: null, files: 0, preserved: 0, boxNote: null, reason: null }
+  const label = (error) => (error instanceof Error ? error.message : String(error))
+  if (prepared === null || prepared === undefined || prepared.ok !== true || typeof prepared.tgzPath !== 'string') {
+    out.reason = `没有可用的预下载 tarball${prepared?.reason ? `（${prepared.reason}）` : ''}`
+    return out
+  }
+  const target = join(String(profileDir), 'node_modules', ...String(packageName).split('/'))
+  let extractDir = null
+  try {
+    extractDir = makeWorkDir(deps)
+    const extract = typeof deps.extract === 'function' ? deps.extract : extractTarball
+    await extract(prepared.tgzPath, extractDir, { deps })
+    const pkgDir = findPackageDir(extractDir)
+    if (pkgDir === null) throw new Error('解包后未找到含 package.json 的目录')
+    // 盒子校验（既有件）：包名不符 / 入口文件缺失 / bundle 引用缺失 —— 覆盖旧版本**之前**拦住
+    const box = verifyPackageBox(pkgDir, profileDir, packageName)
+    out.boxNote = box?.note ?? null
+    const tarballFiles = filesUnder(pkgDir)
+    const existing = filesUnder(target)
+    let preserved = 0
+    for (const rel of existing) if (!tarballFiles.has(rel)) preserved += 1
+    // ★ 只覆盖：copyTree 只 copyFileSync（不删任何东西），目录缺就建目录 —— 见 infra/fsx.js
+    copyTree(pkgDir, target)
+    try {
+      writeFileSync(join(target, '.dsh-installed-at'), String(Date.now()), 'utf8')
+    } catch {}
+    const installed = readVersionOf(target)
+    out.version = installed
+    out.files = tarballFiles.size
+    out.preserved = preserved
+    const want = typeof expectedVersion === 'string' && expectedVersion !== '' ? expectedVersion : null
+    if (want !== null && installed !== want) {
+      out.reason = `铺完之后读回的版本是 ${installed ?? '（读不出来）'}，不是目标版本 ${want}`
+      return out
+    }
+    out.ok = true
+    return out
+  } catch (error) {
+    out.reason = `覆盖文件失败：${label(error)}`
+    return out
+  } finally {
+    if (extractDir !== null) {
+      cleanWorkDir(extractDir)
+    }
+  }
+}
+
+/** 读一份包目录里清单的版本（读不到返回 null）。 */
+function readVersionOf(dir) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(String(dir), 'package.json'), 'utf8'))
+    return typeof pkg?.version === 'string' ? pkg.version : null
+  } catch {
+    return null
+  }
+}
+
+/** 该包在清单里属于哪个依赖分区 —— **不在这里再写一份**：由调用方（selfupdate.js#manifestSectionOf，
+ *  复用 lockfile-health.js 的既有解析器）传进来，两处各写一份必然分叉。 */
+
+/**
+ * ③ 手铺成功之后**必须**把 lock 补到目标版本（不补就重演"下次 pnpm 操作把版本还原"的老毛病）。
+ * 写入走 domain/lock-importer.js#writeLockRegistryVersion（唯一写入口，内部再复用 importer 规划器）；
+ * 复核走既有 `verifyLockReadOnly`（`pnpm install --lockfile-only --dry-run --frozen-lockfile`）。
+ * 复核**明确不通过**（verified === false）⇒ 把 lock 还原成改动前的字节，并按未补上如实上报：
+ * 宁可回到"会被还原"的老状态 + 一条可复制的命令，也绝不留下 pnpm 会拒绝的 lock。
+ * 返回 `{ attempted, changed, unchanged, version, integrityWritten, renamed, verified, verifyNote, rolledBack, reason, note }`。
+ */
+async function patchSelfUpdateLock({ profileDir, packageName, targetVersion, spec = null, integrity = null, section = 'dependencies', deps = {} } = {}) {
+  const out = { attempted: false, changed: false, unchanged: false, version: null, integrityWritten: false, renamed: { packages: false, snapshots: false }, verified: null, verifyNote: null, rolledBack: false, reason: null, note: null }
+  const label = (error) => (error instanceof Error ? error.message : String(error))
+  const specText = typeof spec === 'string' ? spec.trim() : ''
+  const rangeLike = specText === '' || /^[\^~]?\d/u.test(specText) || /^(>=|>|=)\s*\d/u.test(specText)
+  if (rangeLike !== true) {
+    // 来源型 spec（git/file/link/URL）：既有约定是**原样保留**清单声明，lock 的 importer 条目也因此不改
+    // （改成版本号就会与清单对不上，pnpm 下一次操作会把链接/来源丢掉）。
+    out.reason = `清单 spec 是来源型（${specText}）—— 按既有约定保留来源，importer 条目不改写，lock 未补`
+    return out
+  }
+  const lockFile = join(String(profileDir), 'pnpm-lock.yaml')
+  let before = null
+  try {
+    before = readFileSync(lockFile, 'utf8')
+  } catch (error) {
+    out.reason = `读不到 pnpm-lock.yaml（${label(error)}）—— lock 未补`
+    return out
+  }
+  out.attempted = true
+  const write = typeof deps.writeLock === 'function' ? deps.writeLock : writeLockRegistryVersion
+  let written = null
+  try {
+    written = await write(String(profileDir), {
+      name: packageName,
+      // 清单会被收尾段同步成裸版本号（见 self-update-guard.js#finishSelfUpdate），lock 的 specifier 跟它一致
+      spec: targetVersion,
+      version: targetVersion,
+      integrity,
+      section,
+      deps: deps.writeDeps ?? {},
+    })
+  } catch (error) {
+    out.reason = `写 lock 失败：${label(error)}`
+    return out
+  }
+  out.changed = written?.changed === true
+  out.unchanged = written?.unchanged === true
+  out.version = written?.version ?? null
+  out.integrityWritten = written?.integrityWritten === true
+  out.renamed = written?.renamed ?? out.renamed
+  // 写入器"改成了、但有话要说"（例如没有该版本的完整性摘要 ⇒ packages/snapshots 段按规则不动）：
+  // 这句是**说明**不是失败，放 note 里如实下发（reason 只留给真正的失败）。
+  out.note = typeof written?.reason === 'string' && written.reason !== '' ? written.reason : null
+  if (out.changed !== true && out.unchanged !== true) {
+    out.reason = written?.reason ?? 'lock 未写入（原因未给出）'
+    return out
+  }
+  const verify = typeof deps.verifyLock === 'function' ? deps.verifyLock : verifyLockReadOnly
+  try {
+    const verdict = await verify({ profileDir, registry: deps.registry ?? null, execOpts: { timeout: LOCK_VERIFY_TIMEOUT_MS }, ...(deps.verifyArgs ?? {}) })
+    out.verified = verdict?.verified ?? null
+    out.verifyNote = verdict?.reason ?? null
+  } catch (error) {
+    out.verified = null
+    out.verifyNote = `只读校验执行失败：${label(error)}`
+  }
+  // 只读校验**没跑完**（超时/被杀/执行方式不可用）不算"明确不通过" ⇒ 按无法确认处理，不回滚：
+  // 这类失败说明的是"这台机器上 pnpm 跑不动"，而不是"写进去的 lock 有问题"。
+  if (out.verified === false && /超时|timed out|timeout|已终止整棵进程树|killed|ENOENT|Cannot find module|不可用/iu.test(String(out.verifyNote ?? ''))) {
+    out.verified = null
+    out.verifyNote = `pnpm 只读校验没跑完（按无法确认处理，未回滚）：${out.verifyNote ?? '原因未知'}`
+  }
+  if (out.verified === false) {
+    // 明确不通过：还原成改动前的字节（宁可报没补上，也绝不留下 pnpm 会拒绝的 lock）
+    try {
+      writeFileSync(lockFile, before, 'utf8')
+      out.rolledBack = true
+      out.changed = false
+      out.reason = `pnpm 的只读校验未通过（${out.verifyNote ?? '原因未知'}）—— 已把 pnpm-lock.yaml 还原成改动前的内容，按未补上处理`
+    } catch (error) {
+      out.reason = `pnpm 的只读校验未通过（${out.verifyNote ?? '原因未知'}），且还原 pnpm-lock.yaml 失败：${label(error)}`
+    }
+  }
+  return out
+}
+
+/** 收尾：删掉本次临时工作目录（不抛、不阻塞、绝不影响返回结构）。 */
+function disposeSelfUpdateTarball(prepared) {
+  return cleanWorkDir(typeof prepared?.workDir === 'string' ? prepared.workDir : '')
+}
+
+export {
+  DOWNLOAD_TIMEOUT_MS,
+  EXTRACT_TIMEOUT_MS,
+  LOCK_VERIFY_TIMEOUT_MS,
+  META_TIMEOUT_MS,
+  WORK_PREFIX,
+  disposeSelfUpdateTarball,
+  downloadToFile,
+  encodePackageName,
+  extractTarball,
+  filesUnder,
+  findPackageDir,
+  overlaySelfUpdateTarball,
+  patchSelfUpdateLock,
+  prepareSelfUpdateTarball,
+  readVersionOf,
+}

package/lib/server/domain/selfupdate-read.js

@@ -0,0 +1,95 @@
+// L1 · domain —— selfupdate-read.js（自更新/对账共用的**只读**读数：spec 判定、已装版本、lock 里被钉住的版本）
+//
+// 为什么单独一个模块（2026-11-04 加法）：domain/selfupdate.js 贴着 600 行架构棘轮
+// （tests/test-architecture-guard.mjs），而本轮要给"pnpm 卡住/失败后立刻手铺 + 补 lock"腾出空间。
+// 这几个函数本来就是自洽的一族"只读、纯函数式、不认识 cordis"的读数，搬出来只换绑定来源：
+//   · 名字与语义**一个字节都没改**；selfupdate.js 继续 import 它们并**原样 re-export**
+//     （外部 persist.js / plugin-actions.js / unpin-dev-dir.js / install-version.js 与 6 个测试套件
+//      都还从 selfupdate.js 取这几个名字，导出面一个字不能少）；
+//   · 真值只有一份：lock 的键判据仍然只来自 lock-importer.js#lockEntryKeyMatches
+//     （见下面 lockVersion 的长注释 —— 两处各写一份必然再次分叉，0.5.38 就是那个现场）。
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { lockEntryKeyMatches } from './lock-importer.js'
+
+/** spec 是否是 registry 版本范围（`^1.2.3` / `~1.2.3` / `1.2.3` / `>=1` / `=1`）。
+ * 只有这种才能用 `pnpm update` 在**不改写 spec**的前提下把 lock 提到范围内最新；
+ * git / file / link / workspace 来源没有"范围"可言，只能走 `pnpm add <pkg>@<版本>`。 */
+function isRegistryRange(spec) {
+  if (typeof spec !== 'string') return false
+  const s = spec.trim()
+  if (/^[\^~]?\d/u.test(s)) return true
+  return /^(>=|>|=)\s*\d/u.test(s)
+}
+
+/** profile 里该包的依赖声明（spec）。读不到返回 null。 */
+function profileSpec(profileDir, name) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(profileDir, 'package.json'), 'utf8'))
+    const spec = pkg?.dependencies?.[name]
+    return typeof spec === 'string' ? spec : null
+  } catch {
+    return null
+  }
+}
+
+/** 已安装版本（直接读 node_modules 里那份 package.json）。 */
+function readInstalledVersion(profileDir, name) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(profileDir, 'node_modules', ...name.split('/'), 'package.json'), 'utf8'))
+    return typeof pkg?.version === 'string' ? pkg.version : null
+  } catch {
+    return null
+  }
+}
+
+/**
+ * 从 pnpm-lock.yaml 读出该包被**钉住**的版本。解析策略（lock 格式五花八门，只认两种确定性位置，避免子串误命中）：
+ *   ① importers 段：行内容恰为 `'<name>':`（可带缩进），随后几行内的 `version: X`；
+ *   ② packages 段：行首（可带缩进/引号）`<name>@<版本或 git+...>:` 的键名。
+ * 读不到返回 null（调用方据此判定"没能核实"，不谎报成功）。
+ *
+ * ★ 2026-09-22 修复（缺陷②连带）：旧版 ① 在遇到 `specifier: …` 行时**直接 break**，而 importers 段
+ *   恒为 `specifier:` 在前、`version:` 在后 → ① 从来没生效过，全靠 ② 兜底；而 ② 的正则用 `[^':\s]+`
+ *   取值，遇到 `name@https://…tgz` / `link:…` 会在第一个冒号处截断（读出 `http`）或读不到（link 依赖
+ *   在 lock 里没有 packages 条目 → 返回 null）。后果：来源钉住的包永远被判为「漂移」→ 每次安装都白跑
+ *   一次 pnpm add，并给用户一条假的「没写进 lock」警告。现在 ① 跳过 specifier 行、② 取到行尾。
+ */
+function lockVersion(profileDir, name) {
+  const file = join(profileDir, 'pnpm-lock.yaml')
+  if (!existsSync(file)) return null
+  let lines = []
+  try {
+    lines = readFileSync(file, 'utf8').split(/\r?\n/u)
+  } catch {
+    return null
+  }
+  for (let i = 0; i < lines.length; i += 1) {
+    // 键形态三种都认（0.5.38 改错）：`name`、`'name':`（pnpm 对**含 `/`/`@`** 的包名加引号）、
+    // `name:`（pnpm 对**未加 scope** 的包名不加引号）。旧判据漏了第三种 ⇒ 未加 scope 的 `link:`
+    // 依赖在 importers 里明明有条目却读不出来（真机 desktop profile 的 `dshmarket` 就是：
+    // lock 的 35-37 行写着 `dshmarket: / specifier: link:… / version: link:../../plugin-src/dshmarket`，
+    // 而 `lockVersion()` 返回 null）——后果是面板永远报"没写进 pnpm-lock.yaml"、pin 永远 partial、
+    // 每次对账都白跑一次 `pnpm add`。真值一律从下面这一处读，别在调用方再补一套。
+    // 0.5.39：键判据搬进 lock-importer.js#lockEntryKeyMatches —— 定点**写**入也要认同一批键形态，
+    // 两处各写一份必然再次分叉（写进去的键、读的时候认不出，就是 0.5.38 那个现场）。
+    if (lockEntryKeyMatches(lines[i], name)) {
+      for (let k = i + 1; k < Math.min(i + 8, lines.length); k += 1) {
+        const m = /^\s*version:\s*(\S+)\s*$/u.exec(lines[k])
+        if (m) return m[1]
+        // 只在新包的键行（`'<name>':` 形态）处停止；`specifier: X` 有值，不是键行，必须继续往下看
+        if (/^\s*'?[^\s:]+'?:\s*$/u.test(lines[k])) break
+      }
+    }
+  }
+  const escaped = name.replace(/[/\\^$*+?.()|[\]{}]/gu, '\\$&')
+  // 取到行尾再剥尾部的引号/冒号：`'name@https://…tgz':` / `name@git+https://…#sha:` / `name@1.2.3:`
+  const keyRe = new RegExp(`^\\s*'?${escaped}@(.+?)'?:\\s*$`, 'u')
+  for (const line of lines) {
+    const m = keyRe.exec(line)
+    if (m) return m[1]
+  }
+  return null
+}
+
+export { isRegistryRange, lockVersion, profileSpec, readInstalledVersion }

package/lib/server/domain/selfupdate.js

@@ -10,7 +10,7 @@
 // 现在的顺序：① spec 是版本范围 → `pnpm update <pkg>`（spec 不变、lock 提到范围内最新）
 //            ② 仍不是 latest（超出范围 / spec 是 git·file 来源）→ `pnpm add <pkg>@<latest>`（spec 与 lock 同步改写）
 //            ③ 回读核实 readInstalledVersion / lockVersion；都不匹配才回落手铺文件，且**必须**带 lockNote 警告。
-import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { linkSpecFor, linkSpecIsIntact, materializePackageForLink, probeRegistryPackage, sameSourceSpec, suggestedPinAction } from './dep-source.js'
 import { canWriteImporterEntry, lockEntryKeyMatches, verifyLockReadOnly, writeLockImporterEntry } from './lock-importer.js'
@@ -22,91 +22,18 @@ 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'
+// 只读读数（spec 判定 / 已装版本 / lock 里钉住的版本）2026-11-04 搬进 selfupdate-read.js：
+// 本文件贴着 600 行架构棘轮，而本轮要给"pnpm 卡住/失败后立刻手铺 + 补 lock"腾出空间。
+// 名字与语义一个字未改；下面的 export 语句照旧把它们**原样 re-export**（外部调用方与测试不用改）。
+import { isRegistryRange, lockVersion, profileSpec, readInstalledVersion } from './selfupdate-read.js'
+// 手铺兜底（2026-11-04 加法，见 selfupdate-copy.js 顶部现场）：pnpm 之前先把 tarball 备好 →
+// pnpm 超时/失败就**只覆盖文件、不清空目录**地铺进去 → 再把 lock 的版本/完整性补上。
+import { disposeSelfUpdateTarball, overlaySelfUpdateTarball, patchSelfUpdateLock, prepareSelfUpdateTarball } from './selfupdate-copy.js'
 import { fetchJsonUrl } from '../infra/http.js'
 import { runPnpmWithFallback } from '../infra/exec.js'
 
 const CONSOLE_PACKAGE = '@noob-stupid/dsh-plugin-console'
 
-/** spec 是否是 registry 版本范围（`^1.2.3` / `~1.2.3` / `1.2.3` / `>=1` / `=1`）。
- * 只有这种才能用 `pnpm update` 在**不改写 spec**的前提下把 lock 提到范围内最新；
- * git / file / link / workspace 来源没有"范围"可言，只能走 `pnpm add <pkg>@<版本>`。 */
-function isRegistryRange(spec) {
-  if (typeof spec !== 'string') return false
-  const s = spec.trim()
-  if (/^[\^~]?\d/u.test(s)) return true
-  return /^(>=|>|=)\s*\d/u.test(s)
-}
-
-/** profile 里该包的依赖声明（spec）。读不到返回 null。 */
-function profileSpec(profileDir, name) {
-  try {
-    const pkg = JSON.parse(readFileSync(join(profileDir, 'package.json'), 'utf8'))
-    const spec = pkg?.dependencies?.[name]
-    return typeof spec === 'string' ? spec : null
-  } catch {
-    return null
-  }
-}
-
-/** 已安装版本（直接读 node_modules 里那份 package.json）。 */
-function readInstalledVersion(profileDir, name) {
-  try {
-    const pkg = JSON.parse(readFileSync(join(profileDir, 'node_modules', ...name.split('/'), 'package.json'), 'utf8'))
-    return typeof pkg?.version === 'string' ? pkg.version : null
-  } catch {
-    return null
-  }
-}
-
-/**
- * 从 pnpm-lock.yaml 读出该包被**钉住**的版本。解析策略（lock 格式五花八门，只认两种确定性位置，避免子串误命中）：
- *   ① importers 段：行内容恰为 `'<name>':`（可带缩进），随后几行内的 `version: X`；
- *   ② packages 段：行首（可带缩进/引号）`<name>@<版本或 git+...>:` 的键名。
- * 读不到返回 null（调用方据此判定"没能核实"，不谎报成功）。
- *
- * ★ 2026-09-22 修复（缺陷②连带）：旧版 ① 在遇到 `specifier: …` 行时**直接 break**，而 importers 段
- *   恒为 `specifier:` 在前、`version:` 在后 → ① 从来没生效过，全靠 ② 兜底；而 ② 的正则用 `[^':\s]+`
- *   取值，遇到 `name@https://…tgz` / `link:…` 会在第一个冒号处截断（读出 `http`）或读不到（link 依赖
- *   在 lock 里没有 packages 条目 → 返回 null）。后果：来源钉住的包永远被判为「漂移」→ 每次安装都白跑
- *   一次 pnpm add，并给用户一条假的「没写进 lock」警告。现在 ① 跳过 specifier 行、② 取到行尾。
- */
-function lockVersion(profileDir, name) {
-  const file = join(profileDir, 'pnpm-lock.yaml')
-  if (!existsSync(file)) return null
-  let lines = []
-  try {
-    lines = readFileSync(file, 'utf8').split(/\r?\n/u)
-  } catch {
-    return null
-  }
-  for (let i = 0; i < lines.length; i += 1) {
-    // 键形态三种都认（0.5.38 改错）：`name`、`'name':`（pnpm 对**含 `/`/`@`** 的包名加引号）、
-    // `name:`（pnpm 对**未加 scope** 的包名不加引号）。旧判据漏了第三种 ⇒ 未加 scope 的 `link:`
-    // 依赖在 importers 里明明有条目却读不出来（真机 desktop profile 的 `dshmarket` 就是：
-    // lock 的 35-37 行写着 `dshmarket: / specifier: link:… / version: link:../../plugin-src/dshmarket`，
-    // 而 `lockVersion()` 返回 null）——后果是面板永远报"没写进 pnpm-lock.yaml"、pin 永远 partial、
-    // 每次对账都白跑一次 `pnpm add`。真值一律从下面这一处读，别在调用方再补一套。
-    // 0.5.39：键判据搬进 lock-importer.js#lockEntryKeyMatches —— 定点**写**入也要认同一批键形态，
-    // 两处各写一份必然再次分叉（写进去的键、读的时候认不出，就是 0.5.38 那个现场）。
-    if (lockEntryKeyMatches(lines[i], name)) {
-      for (let k = i + 1; k < Math.min(i + 8, lines.length); k += 1) {
-        const m = /^\s*version:\s*(\S+)\s*$/u.exec(lines[k])
-        if (m) return m[1]
-        // 只在新包的键行（`'<name>':` 形态）处停止；`specifier: X` 有值，不是键行，必须继续往下看
-        if (/^\s*'?[^\s:]+'?:\s*$/u.test(lines[k])) break
-      }
-    }
-  }
-  const escaped = name.replace(/[/\\^$*+?.()|[\]{}]/gu, '\\$&')
-  // 取到行尾再剥尾部的引号/冒号：`'name@https://…tgz':` / `name@git+https://…#sha:` / `name@1.2.3:`
-  const keyRe = new RegExp(`^\\s*'?${escaped}@(.+?)'?:\\s*$`, 'u')
-  for (const line of lines) {
-    const m = keyRe.exec(line)
-    if (m) return m[1]
-  }
-  return null
-}
-
 /** 给用户的兜底建议命令（照用户报告里那条：让 lock 也变成新版本，而不是只改文件）。 */
 function selfUpdateCommand(latest, profileName = '<你的profile>') {
   return `dsh plugin --profile ${profileName} add ${CONSOLE_PACKAGE}@${latest}`
@@ -135,8 +62,18 @@ async function selfUpdateToLatest(args = {}) {
   )
 }
 
-/** 上面那个互斥外壳里的正文（原来的函数体，逐字未改）。 */
-async function selfUpdateToLatestLocked({ profileDir, latest, registries, curlManualInstall, runPnpm = runPnpmWithFallback, pnpmAdd = pnpmInstall, profileName = null, execOpts = {}, selfUpdateDeps = {} }) {
+/**
+ * 上面那个互斥外壳里的正文。
+ *
+ * ★ 2026-11-04 加法（**三步的触发条件与顺序一个字未改**，只多了"预先备 tarball"和"手铺后补 lock"）：
+ *   现场：pnpm 一启动就清空目标目录，在 profile 里重算整棵依赖树要几分钟 → 撞 90s/180s 超时被杀 →
+ *   目录停在"空了"的状态，手铺那一步（第③步）压根还没轮到；即使轮到，既有 curl 通道也是"先删再铺"。
+ *   现在：⓪ 先用既有 curl/元数据链路把目标版本 tarball 备到手（失败不影响后续）→ ① ② 照旧 →
+ *   ③ 需要手铺时**先用备好的 tarball 只覆盖文件（绝不清空目录）**，不行才回落到既有 curl 通道 →
+ *   ③c 手铺成功但 lock 没跟上 ⇒ 立刻补 lock（版本 + 完整性）并复核；补不上就如实记 lockNote。
+ *   `copyDeps` 只是单测注入口（默认全是既有实现），路由侧一个字都不用改。
+ */
+async function selfUpdateToLatestLocked({ profileDir, latest, registries, curlManualInstall, runPnpm = runPnpmWithFallback, pnpmAdd = pnpmInstall, profileName = null, execOpts = {}, selfUpdateDeps = {}, copyDeps = {} }) {
   const command = selfUpdateCommand(latest, profileName ?? '<你的profile>')
   const spec = profileSpec(profileDir, CONSOLE_PACKAGE)
   const errors = []
@@ -145,6 +82,9 @@ async function selfUpdateToLatestLocked({ profileDir, latest, registries, curlMa
   // 自更新兜底（规矩：只对本插件生效 / 更新前就有完整副本 / 真的装在 node_modules 里，三条闸都在 begin 里）
   const guard = beginSelfUpdateGuard({ packageName: CONSOLE_PACKAGE, profileDir, targetVersion: latest, deps: selfUpdateDeps })
 
+  // ⓪ 走 pnpm **之前**先把目标版本的 tarball 备到手（失败只记原因，绝不阻断后续：三步顺序不变）
+  const prepared = await prepareSelfUpdateTarball({ packageName: CONSOLE_PACKAGE, version: latest, registries, deps: copyDeps })
+
   // ① spec 是版本范围 → pnpm update（spec 不变，lock 提到范围内最新）
   if (isRegistryRange(spec)) {
     try {
@@ -170,27 +110,65 @@ async function selfUpdateToLatestLocked({ profileDir, latest, registries, curlMa
   let lock = lockVersion(profileDir, CONSOLE_PACKAGE)
   let lockUpdated = installed === latest && lock === latest
   let lockNote = null
+  let copy = null
+  let lockPatch = null
 
-  // ③ 包管理器都没成 → 手铺文件兜底（**不写 lock**），并且必须明确警告，不能让人以为升级成功
+  // ③ 包管理器都没成 → 手铺文件兜底（触发条件与 0.5.102 一致：`!lockUpdated`）
   if (!lockUpdated) {
-    try {
-      const info = await curlManualInstall(profileDir, CONSOLE_PACKAGE, registries, null, latest)
-      method = method === null ? 'manual-copy' : `${method}+manual-copy`
-      installed = info?.version ?? readInstalledVersion(profileDir, CONSOLE_PACKAGE)
+    // ③a 先用**已备好的 tarball 只覆盖文件、不清空目录**（pnpm 卡住/失败时那条"立刻手铺"的腿）
+    const overlay = await overlaySelfUpdateTarball({ prepared, profileDir, packageName: CONSOLE_PACKAGE, expectedVersion: latest, deps: copyDeps })
+    if (overlay.ok === true) {
+      method = method === null ? 'manual-overlay' : `${method}+manual-overlay`
+      installed = overlay.version ?? readInstalledVersion(profileDir, CONSOLE_PACKAGE)
+      copy = { channel: 'overlay', files: overlay.files, preserved: overlay.preserved, version: overlay.version ?? null, boxNote: overlay.boxNote ?? null, noClear: true, reason: null }
+    } else {
+      // ③b 没 tarball / 覆盖失败 → **既有** curl 通道（先删再铺），行为与 0.5.102 逐字一致
+      try {
+        const info = await curlManualInstall(profileDir, CONSOLE_PACKAGE, registries, null, latest)
+        method = method === null ? 'manual-copy' : `${method}+manual-copy`
+        installed = info?.version ?? readInstalledVersion(profileDir, CONSOLE_PACKAGE)
+        copy = { channel: 'curl', files: null, preserved: null, version: info?.version ?? null, boxNote: info?.boxNote ?? null, noClear: false, reason: overlay.reason ?? null }
+      } catch (error) {
+        errors.push(`手动铺文件失败：${label(error)}`)
+        copy = { channel: null, files: null, preserved: null, version: null, boxNote: null, noClear: false, reason: overlay.reason ?? null }
+      }
+    }
+    lock = lockVersion(profileDir, CONSOLE_PACKAGE)
+    lockUpdated = installed === latest && lock === latest
+    // ③c 手铺成功（版本对了）但 lock 还钉在旧版本 ⇒ **必须补 lock**，否则下一次 pnpm 操作就把它还原
+    if (installed === latest && !lockUpdated) {
+      lockPatch = await patchSelfUpdateLock({
+        profileDir, packageName: CONSOLE_PACKAGE, targetVersion: latest, spec,
+        integrity: prepared.ok === true ? prepared.integrity : null,
+        section: manifestSectionOf(profileDir, CONSOLE_PACKAGE), deps: copyDeps,
+      })
       lock = lockVersion(profileDir, CONSOLE_PACKAGE)
       lockUpdated = installed === latest && lock === latest
-    } catch (error) {
-      errors.push(`手动铺文件失败：${label(error)}`)
+      if (lockPatch.reason !== null) errors.push(`补 pnpm-lock.yaml 未成功：${lockPatch.reason}`)
     }
     noteGuardStep(guard, 'manual-copy')
     if (!lockUpdated) {
       lockNote = `此更新未写入 pnpm-lock.yaml（lock 里仍是 ${lock ?? '未知'}）：之后任何 pnpm 操作（开关插件、dsh plugin add/remove）都会把它还原成 lock 里的版本。要真正落地请执行：${command}`
+      if (lockPatch !== null && lockPatch.reason !== null) lockNote = `${lockNote}（补 lock 未成功：${lockPatch.reason}）`
     }
   }
 
+  // 临时工作目录（预下载的 tarball / 解包目录）收尾即删；删不掉要如实记下来（本机 %TEMP% 下 rmSync 会静默落空）
+  const cleanup = disposeSelfUpdateTarball(prepared)
+
   // 收尾：三步都走完才统一校验（全部走完仍不过才自愈），然后交给**原样搬出**的收尾段组装返回结构
   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 })
+  const tarball = {
+    ok: prepared.ok === true,
+    version: prepared.version ?? latest,
+    integrity: prepared.integrity ?? null,
+    tarball: prepared.tarball ?? null,
+    registry: prepared.registry ?? null,
+    reason: prepared.reason ?? null,
+    ms: prepared.ms ?? 0,
+    cleanup: { removed: cleanup.removed === true, note: cleanup.note ?? null },
+  }
+  return finishSelfUpdate({ profileDir, packageName: CONSOLE_PACKAGE, latest, spec, installed, method, command, errors, lockVersion: lock, lockUpdated, lockNote, registryRange: isRegistryRange, selfUpdate, copy, tarball, lockPatch })
 }
 
 /**

package/package.json

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