@noob-stupid/dsh-plugin-console 0.5.14 → 0.5.16

package/lib/server/domain/repoland.js

@@ -5,10 +5,10 @@ import { readFileSync, writeFileSync, existsSync, readdirSync, mkdirSync, rename
 import { spawn } from 'node:child_process'
 import { dirname, join } from 'node:path'
 import { homedir } from 'node:os'
-import { gitCloneUrls } from './sources.js'
+import { gitCloneCandidates } from './sources.js'
 import { execFileAsync, gitEnv, killProcessTree } from '../infra/exec.js'
-import { removeDirVerified } from '../infra/fsx.js'
-import { repoLandConfFile } from '../infra/paths.js'
+import { removeDirVerifiedWithRetry } from '../infra/fsx.js'
+import { dshHome, repoLandConfFile } from '../infra/paths.js'
 
 /** 仓库落地根目录（可配置，默认 ~/.dsh/repos）。 */
 let reposDirCache = null
@@ -71,6 +71,44 @@ function gitErrorDetail(error) {
     .join(' | ')
 }
 
+/** 「上次成功的 git 源」记忆（2026-09-26 加法）：进程内缓存 + 状态文件双保险（两个实例/重启后依然有效）。
+ *  为什么需要：本机直连 github.com 不通（curl 000）→ 探活会把直连跳过，**唯一可用源就是 ghproxy**；
+ *  一旦 ghproxy 超时，整次安装就彻底失败。记住上次成功的源并优先使用，能省掉一轮无谓的探活/失败等待。 */
+const GIT_SOURCE_MEMO_FILE = () => join(dshHome(), 'plugin-console', 'git-source-memo.json')
+let gitSourceMemoCache = null
+
+function readGitSourceMemo() {
+  if (gitSourceMemoCache !== null) return gitSourceMemoCache
+  try {
+    const raw = JSON.parse(readFileSync(GIT_SOURCE_MEMO_FILE(), 'utf8'))
+    gitSourceMemoCache = typeof raw?.template === 'string' ? raw.template : ''
+  } catch {
+    gitSourceMemoCache = ''
+  }
+  return gitSourceMemoCache
+}
+
+function rememberGitSource(template) {
+  const tpl = String(template ?? '')
+  if (tpl === '') return
+  gitSourceMemoCache = tpl
+  try {
+    mkdirSync(dirname(GIT_SOURCE_MEMO_FILE()), { recursive: true })
+    writeFileSync(GIT_SOURCE_MEMO_FILE(), JSON.stringify({ template: tpl, at: Date.now() }, null, 2), 'utf8')
+  } catch {}
+}
+
+/** 把「上次成功过的源」提到最前（其余顺序不变）。纯函数，单测覆盖。 */
+function orderGitCandidates(candidates, preferredTemplate) {
+  const list = Array.isArray(candidates) ? [...candidates] : []
+  const tpl = typeof preferredTemplate === 'string' ? preferredTemplate : ''
+  if (tpl === '') return list
+  const at = list.findIndex((c) => c !== null && c !== undefined && c.urlTemplate === tpl)
+  if (at <= 0) return list
+  const [hit] = list.splice(at, 1)
+  return [hit, ...list]
+}
+
 /** 逐条尝试的错误汇总（纯函数，单测覆盖）：报**第一个**错误（真实原因）+ 尝试清单。
  * 2026-09-26 真机（官方桌面端里装 git 源插件）：ghproxy 卡死 → 我们的超时到了但**没杀 git 进程**，
  * 于是 `git clone` / `git remote-https` / `index-pack --shallow-file …\.git\shallow.lock` 常驻，
@@ -81,6 +119,7 @@ function summarizeCloneErrors(errors) {
   const tried = errors.map((e) => {
     if (e.unclean === true) return `${e.url}（残留目录被占用，已跳过重试）`
     if (e.skipped === true) return `${e.url}（探活失败，已跳过）`
+    if (e.retrying === true) return `${e.url}（超时，已改用更长超时重试）`
     if (e.timedOut === true) return `${e.url}（超时，进程已结束）`
     return /already exists and is not an empty directory/u.test(e.message) ? `${e.url}（目录非空）` : e.url
   }).join('；')
@@ -89,7 +128,8 @@ function summarizeCloneErrors(errors) {
   const stuckNote = stuck.length === 0
     ? ''
     : `；注意：${stuck[0].message}。可手动删除后重试：Remove-Item -Recurse -Force '${stuck[0].dir}'`
-  return `git clone 失败（首个错误：${first?.message ?? '未知'}${detail !== '' ? `；git 说：${detail}` : ''}）；已尝试 ${errors.length} 个源：${tried}${stuckNote}`
+  const sourceCount = new Set(errors.map((e) => e.url)).size
+  return `git clone 失败（首个错误：${first?.message ?? '未知'}${detail !== '' ? `；git 说：${detail}` : ''}）；已尝试 ${sourceCount} 个源（共 ${errors.length} 次尝试）：${tried}${stuckNote}`
 }
 
 /** 结束**整棵**进程树。超时/中断后必须做：git 会派生 remote-https / index-pack 子进程，
@@ -97,10 +137,26 @@ function summarizeCloneErrors(errors) {
  * 2026-09-26（本次）：实现搬进 infra/exec.js（pnpm 通道复用同一份，domain 不再各留一份拷贝），
  * 这里保留同名 re-export —— **对外导出名与调用点一个字都没变**。 */
 
-/** 跑一次 git clone：支持超时，且**超时即杀掉整棵树**。返回 { code, stderr, timedOut, pid }。 */
-function runGitClone(url, dest, timeout, { spawnFn = spawn, killTree = killProcessTree } = {}) {
+/** 等子进程真的退出（轮询 exitCode，并监听 close/exit），超时返回 false。
+ * 为什么必须有：Windows 上「taskkill /T /F 返回了」≠「句柄已经释放」——删目录要在进程真的没了之后再动手，
+ * 否则会出现「杀树明明成功（git 进程 0）却报残留被占用」的假失败（2026-09-26 真机）。 */
+function waitChildExit(child, timeoutMs, pollMs = 60) {
   return new Promise((resolve) => {
+    if (child === null || child === undefined) { resolve(true); return }
+    if (typeof child.exitCode === 'number') { resolve(true); return }
     let settled = false
+    const finish = (ok) => { if (!settled) { settled = true; clearTimeout(timer); clearInterval(ticker); resolve(ok) } }
+    const timer = setTimeout(() => finish(false), timeoutMs)
+    const ticker = setInterval(() => { if (child.exitCode !== undefined && child.exitCode !== null) finish(true) }, pollMs)
+    try { child.on?.('close', () => finish(true)); child.on?.('exit', () => finish(true)) } catch {}
+  })
+}
+
+/** 跑一次 git clone：支持超时，且**超时即杀掉整棵树并等它真的退出**。返回 { code, stderr, timedOut, pid, exited }。 */
+function runGitClone(url, dest, timeout, { spawnFn = spawn, killTree = killProcessTree, exitWaitMs = 800, exitWaitMs2 = 300 } = {}) {
+  return new Promise((resolve) => {
+    let settled = false
+    let timedOut = false
     const finish = (payload) => { if (!settled) { settled = true; resolve(payload) } }
     let child = null
     let stderr = ''
@@ -111,16 +167,24 @@ function runGitClone(url, dest, timeout, { spawnFn = spawn, killTree = killProce
         detached: process.platform !== 'win32', // POSIX：自成进程组，便于 -pid 整体杀
       })
     } catch (error) {
-      finish({ code: -1, stderr: String(error?.message ?? error), timedOut: false, pid: null })
+      finish({ code: -1, stderr: String(error?.message ?? error), timedOut: false, pid: null, exited: true })
       return
     }
-    const timer = setTimeout(() => {
+    const timer = setTimeout(async () => {
+      timedOut = true
       killTree(child.pid)
-      finish({ code: -1, stderr: stderr.trim(), timedOut: true, pid: child.pid })
+      // ① 先等整棵树退出（句柄释放）② 还没退就再杀一次、再等（Windows 上偶发第一次 taskkill 未落地）
+      let exited = await waitChildExit(child, exitWaitMs)
+      if (!exited) {
+        try { killTree(child.pid) } catch {}
+        exited = await waitChildExit(child, exitWaitMs2)
+      }
+      finish({ code: -1, stderr: stderr.trim(), timedOut: true, pid: child.pid, exited })
     }, timeout)
     child.stderr?.on?.('data', (chunk) => { stderr += String(chunk) })
-    child.on('error', (error) => { clearTimeout(timer); finish({ code: -1, stderr: String(error?.message ?? error), timedOut: false, pid: child.pid }) })
-    child.on('close', (code) => { clearTimeout(timer); finish({ code: typeof code === 'number' ? code : -1, stderr: stderr.trim(), timedOut: false, pid: child.pid }) })
+    child.on('error', (error) => { clearTimeout(timer); if (timedOut) return; finish({ code: -1, stderr: String(error?.message ?? error), timedOut: false, pid: child.pid, exited: true }) })
+    // 超时分支自己收尾（要先把退出等完），这里的 close 不能再抢答
+    child.on('close', (code) => { clearTimeout(timer); if (timedOut) return; finish({ code: typeof code === 'number' ? code : -1, stderr: stderr.trim(), timedOut: false, pid: child.pid, exited: true }) })
   })
 }
 
@@ -132,58 +196,89 @@ async function probeSourceAlive(url, timeoutMs = 4000) {
   } catch { return false }
 }
 
-/** git clone（镜像→直连；gitee 直连），返回 { url, attempt, dir } 或抛错。
+/** git clone（镜像→直连；gitee 直连），返回 { url, attempt, dir, source, retried } 或抛错。
  * 每次尝试都用**全新唯一目录** `.tryN`，成功后才 rename 到 dest —— 这样即使上一轮残留目录被占用，
- * 也不会再出现"一个源失败 → 后面所有源都因目录非空而无效"的连锁失效。 */
+ * 也不会再出现"一个源失败 → 后面所有源都因目录非空而无效"的连锁失效。
+ * 2026-09-26 真机加法：① 超时杀树后**等进程真的退出**（runGitClone 内两轮 kill+wait）；
+ *                      ② 失败后的清理走 removeDirVerifiedWithRetry（3 轮 × 250ms）——
+ * 杀树成功但 Windows 句柄晚一拍释放时，不再"一次定生死"、也不再误报"残留被占用"；
+ *                      ③ 源策略：**同一个源超时后用更长超时（默认 1.75 倍）重试一次**，
+ * 并把**上次成功过的源**提到最前来试（本机直连 github 不通、唯一可用源就是 ghproxy，
+ * 一旦它超时就"整次安装彻底失败"——现在先重试它一次，再谈别的源）。 */
 async function gitCloneRepo(repo, dest, source = 'github', timeout = 180000, deps = {}) {
   const {
     spawnFn = spawn,
     killTree = killProcessTree,
     probe = probeSourceAlive,
-    removeDir = removeDirVerified,
+    removeDir = removeDirVerifiedWithRetry,
     renameDir = renameSync,
+    exitWaitMs = 800,
+    retryFactor = 1.75,
+    readMemo = readGitSourceMemo,
+    writeMemo = rememberGitSource,
   } = deps
-  const urls = gitCloneUrls(repo, source)
+  let preferred = ''
+  try { preferred = readMemo() } catch { preferred = '' }
+  const candidates = orderGitCandidates(gitCloneCandidates(repo, source), preferred)
+  const retryTimeout = Math.max(timeout + 1, Math.round(timeout * retryFactor))
   const errors = []
-  for (const [attempt, url] of urls.entries()) {
-    const part = `${dest}.try${attempt + 1}`
-    // eslint-disable-next-line no-await-in-loop
+  let partSeq = 0
+  for (const [sourceIndex, cand] of candidates.entries()) {
+    const url = cand.url
     const alive = await probe(url)
     if (!alive) {
-      errors.push({ url, message: `源探活失败（连不上）：${url}`, skipped: true, dir: part })
+      partSeq += 1
+      errors.push({ url, message: `源探活失败（连不上）：${url}`, skipped: true, dir: `${dest}.try${partSeq}` })
       continue
     }
-    try { removeDir(part) } catch {}
-    // eslint-disable-next-line no-await-in-loop
-    const res = await runGitClone(url, part, timeout, { spawnFn, killTree })
-    if (res.code === 0) {
-      try {
-        removeDir(dest)
-        renameDir(part, dest)
-        return { url, attempt: attempt + 1, dir: dest }
-      } catch (error) {
-        errors.push({ url, message: `克隆成功但落地失败（${error instanceof Error ? error.message : String(error)}）`, dir: part })
+    // 同一个源最多两次：正常超时 → 更长超时重试一次
+    for (let round = 0; round < 2; round += 1) {
+      partSeq += 1
+      const part = `${dest}.try${partSeq}`
+      const useTimeout = round === 0 ? timeout : retryTimeout
+      try { removeDir(part) } catch {}
+      // eslint-disable-next-line no-await-in-loop
+      const res = await runGitClone(url, part, useTimeout, { spawnFn, killTree, exitWaitMs })
+      if (res.code === 0) {
+        try {
+          removeDir(dest)
+          renameDir(part, dest)
+          try { writeMemo(cand.urlTemplate) } catch {}
+          return { url, attempt: sourceIndex + 1, tries: partSeq, dir: dest, source: cand.id, retried: round > 0 }
+        } catch (error) {
+          errors.push({ url, message: `克隆成功但落地失败（${error instanceof Error ? error.message : String(error)}）`, dir: part })
+          break
+        }
+      }
+      // 失败：先尽力清掉半成品目录（带重试的核实删除）；清不掉就**如实说明**（不再谎报"环境禁止删除"，
+      // 也不再把"句柄晚一拍释放"误报成"被占用"）
+      const cleared = removeDir(part)
+      if (cleared && cleared.ok === false) {
+        errors.push({
+          url,
+          message: res.timedOut === true
+            ? (res.exited === false
+              ? `克隆超时；git 进程在等待后仍未退出（清理已重试 ${cleared.rounds ?? cleared.attempts ?? 1} 轮），残留目录清不掉：${part}`
+              : `克隆超时；git 进程已结束，但残留目录重试 ${cleared.rounds ?? cleared.attempts ?? 1} 轮后仍清不掉（可能被其它程序/杀软占用）：${part}`)
+            : `克隆失败，且残留目录重试 ${cleared.rounds ?? cleared.attempts ?? 1} 轮后仍清不掉（可能仍被 git 占用）：${part}`,
+          stderr: res.stderr,
+          unclean: true,
+          timedOut: res.timedOut === true,
+          exited: res.exited !== false,
+          dir: part,
+        })
+        break // 清不掉的残留和这个源绑着，换下一个源（新目录不受影响）
+      }
+      if (res.timedOut === true && round === 0) {
+        // ★ 同源、更长超时，重试一次（真机：ghproxy 卡死时短超时不够，长超时能过）
+        errors.push({ url, message: `克隆超时（${useTimeout}ms），改用 ${retryTimeout}ms 同源重试`, stderr: res.stderr, timedOut: true, retrying: true, dir: part })
         continue
       }
+      errors.push({ url, message: res.timedOut === true ? `克隆超时（${url}）` : (res.stderr !== '' ? res.stderr : `git clone 退出码 ${res.code}`), stderr: res.stderr, timedOut: res.timedOut === true, dir: part })
+      break
     }
-    // 失败：先尽力清掉半成品目录；清不掉就**如实说明**（这次不再谎报"环境禁止删除"）
-    const cleared = removeDir(part)
-    if (cleared && cleared.ok === false) {
-      errors.push({
-        url,
-        message: res.timedOut === true
-          ? `克隆超时，且残留目录仍被 git 占用（进程已尝试结束）：${part}`
-          : `克隆失败，且残留目录无法清理（可能仍被 git 占用）：${part}`,
-        stderr: res.stderr,
-        unclean: true,
-        timedOut: res.timedOut === true,
-        dir: part,
-      })
-      continue // **继续试下一个源**（新目录不受影响），不再像旧代码那样直接 break
-    }
-    errors.push({ url, message: res.timedOut === true ? `克隆超时（${url}）` : (res.stderr !== '' ? res.stderr : `git clone 退出码 ${res.code}`), stderr: res.stderr, timedOut: res.timedOut === true, dir: part })
   }
   throw new Error(summarizeCloneErrors(errors))
 }
 
-export { reposDirCache, getReposDir, setReposDir, listLandedRepos, gitCloneRepo, summarizeCloneErrors, killProcessTree, probeSourceAlive }
+export { reposDirCache, getReposDir, setReposDir, listLandedRepos, gitCloneRepo, summarizeCloneErrors, orderGitCandidates, readGitSourceMemo, rememberGitSource, killProcessTree, probeSourceAlive }

package/lib/server/domain/sources.js

@@ -289,9 +289,37 @@ function gitCloneUrls(repoFullName, source = 'github') {
   return urls.length > 0 ? urls : [`https://github.com/${repoFullName}.git`]
 }
 
+/** Git 克隆候选（带源 id/名称/模板）——2026-09-26 加法：给「记住上次成功的 git 源并优先使用」用。
+ *  `gitCloneUrls` 一个字没改（另外 5 个调用点的行为完全不变）；这里只是把同一份排序逻辑
+ *  连同**源标识**一起返回，让克隆侧能把"哪个模板成功了"记下来。 */
+function gitCloneCandidates(repoFullName, source = 'github') {
+  const full = String(repoFullName)
+  if (source === 'gitee') {
+    return [{ id: 'gitee-git', name: 'Gitee 直连', urlTemplate: 'https://gitee.com/{owner}/{repo}.git', url: `https://gitee.com/${full}.git` }]
+  }
+  const [owner = '', repo = ''] = full.split('/')
+  let list = []
+  try {
+    list = readSources().gitSources ?? []
+  } catch {
+    list = DEFAULT_SOURCES.gitSources
+  }
+  const ordered = [...list].sort((a, b) => (b.primary === true ? 1 : 0) - (a.primary === true ? 1 : 0))
+  const out = []
+  for (const s of ordered) {
+    const tpl = typeof s?.urlTemplate === 'string' ? s.urlTemplate : ''
+    if (tpl === '') continue
+    const url = tpl.replace(/\{owner\}/gu, owner).replace(/\{repo\}/gu, repo)
+    if (url === '') continue
+    out.push({ id: typeof s.id === 'string' ? s.id : '', name: typeof s.name === 'string' ? s.name : '', urlTemplate: tpl, url })
+  }
+  if (out.length === 0) out.push({ id: 'github-git', name: 'GitHub 直连', urlTemplate: 'https://github.com/{owner}/{repo}.git', url: `https://github.com/${full}.git` })
+  return out
+}
+
 /** Gitee OAuth 端点（第三方应用需在 gitee.com → 数据管理 → 第三方应用 创建）。 */
 const GITEE_AUTH_URL = 'https://gitee.com/oauth/authorize'
 
 const GITEE_TOKEN_URL = 'https://gitee.com/oauth/token'
 const DEFAULT_SEARCH = 'dsh-plugin'
-export { readSources, writeSources, maskSources, readSourceSecrets, writeSourceSecrets, isAllowedSourceUrl, isAllowedGitSourceUrl, readGiteeConfig, giteeStatusView, orderedRegistries, createGiteeOAuthState, consumeGiteeOAuthState, DEFAULT_SOURCES, GITEE_OAUTH_STATES, gitCloneUrls, GITEE_AUTH_URL, GITEE_TOKEN_URL, DEFAULT_SEARCH }
+export { readSources, writeSources, maskSources, readSourceSecrets, writeSourceSecrets, isAllowedSourceUrl, isAllowedGitSourceUrl, readGiteeConfig, giteeStatusView, orderedRegistries, createGiteeOAuthState, consumeGiteeOAuthState, DEFAULT_SOURCES, GITEE_OAUTH_STATES, gitCloneUrls, gitCloneCandidates, GITEE_AUTH_URL, GITEE_TOKEN_URL, DEFAULT_SEARCH }

package/lib/server/infra/exec.js

@@ -3,7 +3,7 @@
 
 import { execFile, spawn, spawnSync } from 'node:child_process'
 import { promisify } from 'node:util'
-import { existsSync } from 'node:fs'
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { homedir } from 'node:os'
 
@@ -108,22 +108,69 @@ function processAlive(pid) {
 }
 const execFileAsync = promisify(execFile)
 
+/** POSIX 兜底用：读 /proc 列出某 pid 的**全部后代**（按 `/proc/<pid>/stat` 的 ppid 字段建索引 + BFS）。
+ * 只有"进程组 kill 失败"时才走它，所以是纯读：任何一步读不到就返回 []，绝不抛。
+ * 为什么不用 `pkill -P <pid>`：slim 容器/最小镜像里未必装了 procps，而 /proc 是内核接口
+ * （Linux / Android 都有）；macOS 没有 /proc → 返回 []，调用方就退化成"只杀直接子进程"（不比旧行为差）。
+ * deps（procDir/readdir/readFile）只为单测注入，生产调用不传。 */
+function posixDescendants(pid, { procDir = '/proc', readdir = readdirSync, readFile = readFileSync } = {}) {
+  let entries
+  try { entries = readdir(procDir) } catch { return [] }
+  const childrenOf = new Map()
+  for (const name of entries) {
+    if (!/^\d+$/u.test(String(name))) continue
+    let stat
+    try { stat = String(readFile(join(procDir, String(name), 'stat'), 'utf8')) } catch { continue }
+    // 形如 `1234 (comm 里可能有空格/括号) S 5678 …`：进程名不可信 → 从**最后**一个 ')' 之后切
+    const rest = stat.slice(stat.lastIndexOf(')') + 1).trim().split(/\s+/u)
+    const ppid = Number(rest[1]) // rest[0]=state，rest[1]=ppid
+    if (!Number.isInteger(ppid)) continue
+    const list = childrenOf.get(ppid)
+    if (list === undefined) childrenOf.set(ppid, [Number(name)])
+    else list.push(Number(name))
+  }
+  const out = []
+  const queue = [pid]
+  while (queue.length > 0) {
+    for (const child of childrenOf.get(queue.shift()) ?? []) {
+      if (child === pid || out.includes(child)) continue // 防 /proc 读歪了造出自环
+      out.push(child)
+      queue.push(child)
+    }
+  }
+  return out
+}
+
 /** 结束**整棵**进程树（2026-09-26 从 domain/repoland.js 移入 infra —— pnpm 通道也要用同一份实现，
  * 不能让 git 通道和 pnpm 通道各写一份、同一个坑各踩一次）。
  * 超时/中断后必须做：git 会派生 remote-https / index-pack，pnpm 会派生 git / tar / node-gyp / 子 pnpm，
  * 只 kill 父进程会留下孤儿继续占着 .git 与 node_modules 里的文件（2026-09-26 真机实测占住
  * pack 临时文件与 shallow.lock，Windows 下直接导致目录删不掉）。
  * Windows：`taskkill /F /T /PID`（/T 连整棵子树）；POSIX：`kill(-pid)`（依赖 spawn 时 detached 自成进程组）。
- * 导入点不变：domain/repoland.js 继续 re-export 这个名字，老调用方一个字都不用改。 */
-function killProcessTree(pid) {
+ * 导入点不变：domain/repoland.js 继续 re-export 这个名字，老调用方一个字都不用改。
+ *
+ * 2026-09-26（本次改错）：POSIX 分支的兜底以前是"进程组杀不掉就直接 `kill(pid)`"——那等于承认
+ * **孙进程必然残留**（-pid 抛错只说明这个进程组不存在：子进程没成组、或已 setsid 带走了自己）。
+ * 现在兜底改成"按 /proc 的 ppid 链**从叶子往根**逐个 SIGKILL"，杀不掉任何一个才返回 false
+ * （返回值语义不变：仍然是"有没有成功发出过 kill"）。Windows 分支一个字没动。
+ * deps（platform/kill/…）只为单测注入 POSIX 分支，生产调用不传 → 行为与旧代码一致。 */
+function killProcessTree(pid, deps = {}) {
   if (typeof pid !== 'number' || pid <= 0) return false
+  const platform = deps.platform ?? process.platform
+  const kill = deps.kill ?? process.kill
   try {
-    if (process.platform === 'win32') {
+    if (platform === 'win32') {
       spawnSync('taskkill', ['/F', '/T', '/PID', String(pid)], { windowsHide: true, timeout: 15000 })
-    } else {
-      try { process.kill(-pid, 'SIGKILL') } catch { try { process.kill(pid, 'SIGKILL') } catch { return false } }
+      return true
     }
-    return true
+    try { kill(-pid, 'SIGKILL'); return true } catch {}
+    // 进程组不存在/无权限 → 兜底按进程树逐个杀（叶子先杀，父最后杀）
+    let killed = false
+    for (const child of posixDescendants(pid, deps).reverse()) {
+      try { kill(child, 'SIGKILL'); killed = true } catch {}
+    }
+    try { kill(pid, 'SIGKILL'); killed = true } catch {}
+    return killed
   } catch { return false }
 }
 
@@ -135,7 +182,7 @@ function killProcessTree(pid) {
  * 成功路径的 resolve 形状（{stdout, stderr}）与既有异常字段（message/stderr/stdout/code/killed/signal）
  * 保持一致，调用方无需改动；`detached` 仅为 POSIX 成组（Windows 上保持 false，避免弹新控制台窗口）。 */
 function execFileWithKillTree(bin, argv, opts = {}, deps = {}) {
-  const { killTree = killProcessTree, spawnFn = spawn } = deps
+  const { killTree = killProcessTree, spawnFn = spawn, platform = process.platform } = deps
   const timeout = Number.isFinite(opts.timeout) && opts.timeout > 0 ? opts.timeout : 0
   const maxBuffer = Number.isFinite(opts.maxBuffer) && opts.maxBuffer > 0 ? opts.maxBuffer : 1024 * 1024
   const signal = opts.signal ?? null
@@ -188,7 +235,7 @@ function execFileWithKillTree(bin, argv, opts = {}, deps = {}) {
         cwd: opts.cwd,
         env: opts.env,
         windowsHide: opts.windowsHide !== false,
-        detached: process.platform !== 'win32', // POSIX：自成进程组，-pid 才杀得掉整棵树
+        detached: platform !== 'win32', // POSIX：自成进程组，-pid 才杀得掉整棵树（platform 可注入，见单测）
       })
     } catch (error) { finish(error, null); return }
     const overflow = () => {
@@ -267,10 +314,15 @@ function pnpmAddArgs(spec, registry, { fetchFlags = true, fetchTimeoutMs = 60000
   return args
 }
 
-/** 该版本 pnpm 不认识我们加的选项（真实文案：`[ERROR] Unknown options: 'fetch-timeout', 'fetch-retries'`）。
+/** 该版本 pnpm 不认识我们加的选项。两代真实文案都要认（2026-09-26 CI 实测，缺一个就等于"装不上"）：
+ *   · pnpm 11（本机 11.21.0）：`[ERROR] Unknown options: 'fetch-timeout', 'fetch-retries'`
+ *   · pnpm 12（corepack 默认已解析到 12.6.0，Linux CI 实测 exit code=2）改成 clap 风格：
+ *     `error: unexpected argument '--fetch-timeout' found` + `Usage: pnpm add --registry <REGISTRY> <PACKAGE_NAMES>...`
+ * 为什么必须补上第二条：判据漏了 pnpm 12 的文案 → 降级分支永不触发 → **装了 pnpm 12 的机器
+ * 任何插件都装不上**（`pnpm add --fetch-timeout` 直接 exit 2），而这正好是我们自己加固出来的失败。
  * 加固**绝不能让用户装不上**：调用方看到这个错误就去掉加固选项重试一次（见 runPnpmAdd）。 */
 function unknownPnpmOption(message) {
-  return /Unknown option/iu.test(String(message ?? ''))
+  return /Unknown option|unexpected argument/iu.test(String(message ?? ''))
 }
 
 /** 跑一次 `pnpm add`（本控制台所有安装通道的唯一入口）—— 2026-09-26 新增。
@@ -307,4 +359,4 @@ const GH_BIN_CANDIDATES = [
   join(homedir(), 'scoop', 'shims', 'gh.exe'),
 ]
 
-export { GH_BIN_CANDIDATES, gitEnv, gitBin, processAlive, execFileAsync, resolvePnpmRunners, runPnpmWithFallback, killProcessTree, execFileWithKillTree, pnpmEnvOverrides, buildPnpmEnv, pnpmFetchArgs, pnpmAddArgs, unknownPnpmOption, runPnpmAdd }
+export { GH_BIN_CANDIDATES, gitEnv, gitBin, processAlive, execFileAsync, resolvePnpmRunners, runPnpmWithFallback, killProcessTree, posixDescendants, execFileWithKillTree, pnpmEnvOverrides, buildPnpmEnv, pnpmFetchArgs, pnpmAddArgs, unknownPnpmOption, runPnpmAdd }

package/lib/server/infra/fsx.js

@@ -4,6 +4,7 @@
 import { existsSync, rmSync, readdirSync, mkdirSync, copyFileSync, chmodSync, lstatSync } from 'node:fs'
 import { dirname, join, basename } from 'node:path'
 import { execFile } from 'node:child_process'
+import { execFileSync } from 'node:child_process'
 import { promisify } from 'node:util'
 
 const execFileAsync = promisify(execFile)
@@ -160,4 +161,52 @@ async function removeDirVerifiedAsync(dir, { attempts = 2, pollMs = 600 } = {})
   return { ok: false, attempts, method: null, error: detail }
 }
 
-export { copyTree, queuedWrite, cleanupStalePackageDir, removeDirVerified, removeDirVerifiedAsync, clearReadonly, waitGone, removeViaShell, writeQueue }
+/**
+ * 「带重试的核实删除」（2026-09-26 真机加法）：专治 Windows「杀完进程但句柄晚一拍释放」。
+ * 真机证据：git 整棵树已经杀干净（`git` 进程 0），可上一次尝试里 `removeDirVerified` **一次**判失败，
+ * 就被上游当成「残留被占用」写进用户可见的错误里。
+ * 每一轮都：`removeDirVerified` → 等 pollMs → 仍不消失就**外部 `rmdir /s /q` 兜底**（同步版）→ 再核实。
+ * 为什么要外部兜底（2026-09-26 本机实测）：同一个 `rmSync(…, {recursive:true, force:true, maxRetries:3})`
+ *   在 `C:\Users\<user>\AppData\Local\Temp\…` 下**不抛错、目录原封不动**，而 `cmd /c rmdir /s /q` 一次就删掉
+ *   （与 removeDirVerifiedAsync 已有的兜底同源，这里补上同步版）。只有确实清不掉才回 ok:false。
+ * 注：`Atomics.wait` 是 Node 里唯一可靠的同步 sleep（本函数是同步签名，调用点都在同步清理路径上）。
+ */
+function sleepSync(ms) {
+  try {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
+  } catch {}
+}
+
+/** 外部删除兜底（同步版）：实测本机 `cmd /c rmdir /s /q` 能删掉 Node `rmSync` 静默删不掉的树。 */
+function removeViaShellSync(dir, timeoutMs = 120000) {
+  try {
+    if (process.platform === 'win32') {
+      execFileSync('cmd.exe', ['/c', 'rmdir', '/s', '/q', dir], { windowsHide: true, timeout: timeoutMs, stdio: 'ignore' })
+      return { ok: true, method: 'rmdir' }
+    }
+    execFileSync('rm', ['-rf', '--', dir], { timeout: timeoutMs, stdio: 'ignore' })
+    return { ok: true, method: 'rm' }
+  } catch (error) {
+    return { ok: false, method: null, error: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+function removeDirVerifiedWithRetry(dir, { attempts = 3, pollMs = 250, remover = removeDirVerified, shellRemover = removeViaShellSync, viaShell = true } = {}) {
+  if (!existsSync(dir)) return { ok: true, attempts: 0, rounds: 1, method: 'already-gone', error: null }
+  let last = { ok: false, attempts: 0, error: null }
+  for (let round = 1; round <= attempts; round += 1) {
+    last = remover(dir)
+    if (last !== null && last !== undefined && last.ok === true) return { ok: true, attempts: last.attempts ?? 0, rounds: round, method: 'rmSync', error: null }
+    sleepSync(pollMs)
+    if (!existsSync(dir)) return { ok: true, attempts: last?.attempts ?? 0, rounds: round, method: 'rmSync(等待后消失)', error: null }
+    if (viaShell === true) {
+      const shell = shellRemover(dir)
+      sleepSync(pollMs)
+      if (!existsSync(dir)) return { ok: true, attempts: last?.attempts ?? 0, rounds: round, method: shell === null || shell === undefined ? null : shell.method, error: null }
+      if (shell !== null && shell !== undefined && shell.ok !== true) last = { ...last, error: shell.error ?? last?.error ?? null }
+    }
+  }
+  return { ok: false, attempts: last?.attempts ?? 0, rounds: attempts, method: null, error: last?.error ?? null }
+}
+
+export { copyTree, queuedWrite, cleanupStalePackageDir, removeDirVerified, removeDirVerifiedAsync, removeDirVerifiedWithRetry, removeViaShellSync, sleepSync, clearReadonly, waitGone, removeViaShell, writeQueue }

package/lib/server/routes/framework-upgrade.js

@@ -11,7 +11,7 @@ import { tmpdir } from 'node:os'
 import { pathToFileURL } from 'node:url'
 import { createRequire } from 'node:module'
 import { readCompatMode, writeCompatMode } from '../domain/compat-state.js'
-import { FRAMEWORK_BACKUP_ROOT, backupProfileSnapshot, checkpointFrameworkTree, preflightDisableIncompatible, relaunchPrelude, resolveDshBin, resolveFrameworkRootNodeModules, resolveFrameworkUpgradePlan } from '../domain/framework.js'
+import { FRAMEWORK_BACKUP_ROOT, backupProfileSnapshot, checkpointFrameworkTree, preflightDisableIncompatible, relaunchPrelude, resolveDshBin, resolveFrameworkRootNodeModules, resolveFrameworkUpgradePlan, shellHostedRefusal } from '../domain/framework.js'
 import { fwIntegrityCheck } from '../infra/fw-integrity-check.js'
 import { CORE_PATCH_ROW_IDS } from '../domain/patch.js'
 import { migrateAgentConfigsForUpgrade } from '../domain/presets.js'
@@ -51,6 +51,7 @@ async function routeFrameworkUpgrade(req, res, rc) {
     // 框架升级入口：一键流程 = 备份配置快照 + 备份框架本体（回滚点）+ 自动升级
     // （npx 缓存 dsh 本体 + profile 官方配套包）+ 失败自动回滚 + 重启提示。
     // 升级完成重启后，框架适配逻辑自动：备份新版本快照 + 重打框架补丁 + 版本提示。
+    const refusal = shellHostedRefusal(); if (refusal !== null) { sendError(res, 409, refusal.error, refusal.details); return } // 宿主守卫：本路由的「升级后重启」步骤含 Stop-Process + Invoke-DshRelaunch，外壳托管（桌面端 Electron 承载）时禁止生成该脚本——判据见 domain/framework.js#detectHostShape
     let current = null
     let dshDir = null
     // 面板自报名（自报名一致性校验用）：从插件自身 package.json 读，与部署目录比对

package/lib/server/routes/framework.js

@@ -8,7 +8,7 @@ import { dirname, join, resolve } from 'node:path'
 import { tmpdir } from 'node:os'
 import { createRequire } from 'node:module'
 import { readCompatGate, writeCompatGate } from '../domain/compat.js'
-import { cleanupStaleFwTasks, currentFrameworkVersion, pickFrameworkTarget, relaunchPrelude, resolveDshBin, resolveFrameworkRootNodeModules } from '../domain/framework.js'
+import { cleanupStaleFwTasks, currentFrameworkVersion, pickFrameworkTarget, relaunchPrelude, resolveDshBin, resolveFrameworkRootNodeModules, shellHostedRefusal } from '../domain/framework.js'
 import { readGithubAuth } from '../domain/install.js'
 import { webPort } from '../domain/runtime.js'
 import { fetchJsonUrl } from '../infra/http.js'
@@ -17,6 +17,21 @@ import { dshHome, entryPkgMeta, findPatchPath, packageNameOf, pluginRoot, profil
 import { isFrameworkVersionNewer, semverRangeMatchLoose, frameworkUpgradeCandidates } from '../infra/semver.js'
 import { fwCheckCache, setFwCheckCache } from '../state.js'
 
+/**
+ * 宿主形态守卫（2026-09-26 真机事故后的**加法分支**，只挡外壳托管这一种新形态）：
+ * 桌面端里 DSH host 由 Electron 二进制承载（asar 内 dsh-desktop-host），实例里根本没有 `node bin.js web` 可拉起。
+ * 我们原先的「按端口 Stop-Process → Invoke-DshRelaunch」会杀掉 host 却拉不起来，
+ * Electron 外壳只留下 `crash-…-host.log: dsh desktop host exited with 4294967295`（真机 20:28）。
+ * 命中时：**不 kill、不 spawn、不建 schtasks**，返回结构化 409 + 面向用户短句。
+ * 返回 true = 已拒绝（调用方直接 return）；false = 独立 `dsh web` 实例，原路径一字不改。
+ */
+function refuseWhenShellHosted(res) {
+  const refusal = shellHostedRefusal()
+  if (refusal === null) return false
+  sendError(res, 409, refusal.error, refusal.details)
+  return true
+}
+
 async function routeFrameworkUpgradeStatusGet(req, res, rc) {
   const ctx = rc.ctx
   const url = rc.url
@@ -100,6 +115,9 @@ async function routeFrameworkRelaunch(req, res, rc) {
   const method = rc.method
     // 手动拉起服务（升级期间左侧悬浮按钮调用）：Start-Process node bin.js web。
     // 端口已有监听则不重复拉起；bin.js 缺失时明确报错。
+    // 宿主守卫：外壳托管的实例里**没有** node bin.js web 这条现实路径（spawn 出来的只会是第二个实例/立刻死掉），
+    // 改为让用户在桌面端内重启。
+    if (refuseWhenShellHosted(res)) return
     const port = webPort(ctx)
     const binPath = resolveDshBin()
     const nodePath = process.execPath
@@ -326,6 +344,10 @@ async function routeFrameworkRollback(req, res, rc) {
   const body = rc.body
     // 一键回滚（2026-09-04 事故后的新能力）：读 framework-rollback.json（升级时写入），
     // 生成分离脚本：停服 → 全树恢复（.pnpm 自包镜像 + 顶层 scope + lock）→ 拉起 → 状态。
+    // 宿主守卫（**本机 20:28 事故的真正凶手就是这条路径**：它没有 bin.js 预检，直接按端口 Stop-Process，
+    // 杀掉 Electron 承载的 host 后 Invoke-DshRelaunch 找不到 bin.js → 外壳记 crash）：
+    // 外壳托管时一律拒绝，绝不生成会杀 host 的脚本。
+    if (refuseWhenShellHosted(res)) return
     let rec = null
     try { rec = JSON.parse(readFileSync(join(dshHome(), 'plugin-console', 'framework-rollback.json'), 'utf8')) } catch {}
     if (rec === null || typeof rec.checkpointDir !== 'string' || typeof rec.fwRoot !== 'string'
@@ -430,6 +452,8 @@ async function routeRestart(req, res, rc) {
     //   ② **守护任务**（关键）：主脚本动手**之前**就注册一个每分钟跑一次的独立计划任务，
     //      服务被杀、主脚本被杀都不影响它；端口起来了它自删，起不来就继续拉（最多 5 次）
     //   ③ bin 解析用与升级/回滚同一套多级回退（node resolve → .pnpm → 顶层链接）
+    // 宿主守卫（加法分支）：外壳托管时"自杀式重启"没有意义（杀了 host 没人拉起，只会产生 crash 日志）。
+    if (refuseWhenShellHosted(res)) return
     const port = webPort(ctx)
     const binPath = resolveDshBin()
     const nodePath = process.execPath
@@ -552,4 +576,4 @@ async function routeFrameworkStatusClear(req, res, rc) {
   }
   sendJson(res, 200, { ok: true, removed, status: 'idle', message: null })
 }
-export { routeFrameworkStatusClear, routeFrameworkUpgradeStatusGet, routeFrameworkRelaunch, routeFrameworkCheck, routeCompatGate, routeCheckUpdate, routeFrameworkRollback, routeRestart }
+export { refuseWhenShellHosted, routeFrameworkStatusClear, routeFrameworkUpgradeStatusGet, routeFrameworkRelaunch, routeFrameworkCheck, routeCompatGate, routeCheckUpdate, routeFrameworkRollback, routeRestart }

package/lib/server/routes/index.js

@@ -20,6 +20,7 @@ import { routeFrameworkPreflight, routeFrameworkPreflightPatch } from './framewo
 import { routeCheckUpdate, routeCompatGate, routeFrameworkCheck, routeFrameworkRelaunch, routeFrameworkRollback, routeFrameworkStatusClear, routeFrameworkUpgradeStatusGet, routeRestart } from './framework.js'
 import { routeGithubLogin, routeGithubOpenLogin } from './github-login.js'
 import { routeInstall, routeInstallStatus } from './install.js'
+import { routeLockfileCheck, routeLockfileRepair } from './lockfile.js'
 import { routeEnrich, routeMarketIndex, routeRepo, routeSearch, routeSubpackages } from './market.js'
 import { routeAdaptUnlock, routeAdaptUnlockAll, routeCleanResiduals, routeSelfUpdate, routeToggle, routeUninstall } from './plugins.js'
 import { routeSkillRemove, routeSkillToggle, routeSkillsInstalledGet } from './skills.js'
@@ -128,6 +129,9 @@ const ROUTES = [
   { methods: ['POST'], path: `${ROUTE_PREFIX}/component/start`, handler: routeComponentStart },
   { methods: ['POST'], path: `${ROUTE_PREFIX}/component/stop`, handler: routeComponentStop },
   { methods: ['POST'], path: `${ROUTE_PREFIX}/component/status`, handler: routeComponentStatus },
+  // 依赖锁体检与重建（2026-09-27 加法）：check 纯只读；repair 必须由用户显式调用
+  { methods: ['POST'], path: `${ROUTE_PREFIX}/lockfile-check`, handler: routeLockfileCheck },
+  { methods: ['POST'], path: `${ROUTE_PREFIX}/lockfile-repair`, handler: routeLockfileRepair },
 
 ]