@noob-stupid/dsh-plugin-console 0.5.49 → 0.5.51

package/README.md

@@ -411,6 +411,30 @@ node scripts/safe-boot.mjs --mark-good            # mark a snapshot as good (nev
 
 Safe-boot snapshots live under `dshHome()/plugin-console/safe-boot/` (**not** in the profile directory),
 keeping the newest 3 plus the one you marked as good.
+
+### When the service won't start because **framework packages were wiped**
+
+The rollback above restores the **config layer** (`cordis.patch.yml`). There is a second failure
+class where the **package payloads** are gone — framework packages emptied or deleted. Then the
+patch is perfectly fine, restoring it changes nothing, and **the console itself runs inside dsh**:
+if dsh cannot boot, the console was never loaded (real outage, 2026-10-14: `cordis`'s store entity
+emptied plus `dsh-llm`/`dsh-tools`/`dsh-web` turned into empty directories ⇒
+`54 plugins failed to import` ⇒ `exit code=1`).
+
+That class needs the **out-of-process** closure preflight (also needs no running service):
+
+```bash
+node scripts/fw-preflight.mjs --check     # diagnose only: list unresolvable packages, write nothing
+node scripts/fw-preflight.mjs --repair    # restore from the **local npm cache** by lock integrity, then re-verify
+```
+
+The criterion is "**can the dependency closure be resolved**", not "is the directory empty" —
+the latter is completely blind to "the shell is still there, the inside was emptied"
+(measured: a naive empty-dir scan reported 237 false positives; the closure criterion passed all
+287 packages and named exactly the one that broke). `--repair` is **offline and never guesses a
+version** (a package missing from the lock is reported as `no-lock-entry`), and it **never kills or
+spawns a process and never grabs a port** (that is exactly what produces
+"The application failed to start or stopped unexpectedly") — restart the service yourself afterwards.
 ## Framework compatibility
 
 Measured on isolated instances (fresh `DSH_HOME`, real HTTP probes) — **supported: framework ≥ `0.1.5-rc.2`**, no workarounds needed.

package/README.zh.md

@@ -346,6 +346,26 @@ node scripts/safe-boot.mjs --mark-good            # 把某份快照标记为"良
 
 安全启动快照落在 `dshHome()/plugin-console/safe-boot/`（**不在** profile 目录里），保留最近 3 份 +
 永不删你标记为"良好"的那份。
+
+### 服务打不开、且原因是**框架包被掏空**时
+
+上面那套恢复的是**配置层**（`cordis.patch.yml`）。另有一类事故坏的是**包实体**——
+框架包被清空或删除，此时补丁好端端的，恢复补丁没有任何用，而**控制台自己也是跑在 dsh 里的**，
+dsh 起不来它就从未加载（真机停机事故 2026-10-14：`cordis` 实体被掏空 +
+`dsh-llm`/`dsh-tools`/`dsh-web` 成了空目录 ⇒ `54 个插件 failed to import` ⇒ `exit code=1`）。
+
+这类事故要用**进程外**的闭包预检（同样不需要服务在跑）：
+
+```bash
+node scripts/fw-preflight.mjs --check     # 只诊断：列出解析不了的包，一个字节都不写
+node scripts/fw-preflight.mjs --repair    # 按 lock 的 integrity 从**本地 npm 缓存**装回，再复验
+```
+
+判据是"**依赖闭包能不能解析**"，不是"目录空不空"—— 后者对"目录壳还在、里面被掏空"这种形态
+完全免疫（真机实测：按"目录空不空"粗扫会误报 237 个；按闭包判据 287 个包精准通过）。
+`--repair` **不联网、不猜版本**（lock 里没有的包如实报 `no-lock-entry`），
+也**绝不 kill / spawn 进程或抢端口**（那正是「应用无法启动或已意外停止」的来源）——
+修完请自己重启服务。
 ## 框架兼容性
 
 在隔离实例（全新 `DSH_HOME` + 真实 HTTP 探针）实测：**支持框架 ≥ `0.1.5-rc.2`**，无需任何变通。

package/lib/server/domain/fw-preflight.js

@@ -0,0 +1,351 @@
+// L1 · domain —— fw-preflight.js（框架闭包**预检与治包**：服务起不来时的自救；0.5.50 加法）
+//
+// ── 为什么必须有它（**真机停机事故 2026-10-14**）────────────────────────────────
+//   四个框架包被掏空（`cordis` 的 junction 还在但 `.pnpm` 实体被清空；`dsh-llm` / `dsh-tools` /
+//   `dsh-web` 成了空的真实目录）⇒ dsh 启动即 `54 个插件 failed to import` ⇒ web 服务 exit code=1。
+//
+//   **这次事故的所有既有防线都失效**，原因是结构性的：
+//     · safe-boot 快照存的是 `cordis.patch.yml` 的**文本**（63KB 全是配置）—— 坏的却是包实体，
+//       而补丁当时好端端的 ⇒ 恢复动作等于"把一份没坏的配置换成另一份没坏的配置"；
+//     · 指纹 `pnpmEntities` 数的是 `.pnpm` 里的**目录个数** —— "目录壳还在、里面被掏空"⇒ 计数不变
+//       ⇒ 判定环境未变 ⇒ 不触发任何动作；
+//     · 自动禁用针对"插件不适配" —— 这次是框架包没了，不是插件问题。
+//   而最根本的一条：**它是跑在 dsh 里的**。dsh 起不来 ⇒ 插件从未加载（事故日志里出现 0 次）
+//   ⇒ 一切"面板里有按钮"的方案在这类事故面前等于没有。
+//
+//   所以本模块的定位是**进程外的预检与治包**，可由 `scripts/fw-preflight.mjs` 在服务之外调用：
+//     探测（infra/fw-closure.js）→ 定计划 → 从本地 npm 缓存装回（infra/npm-cache.js）→ 复验。
+//   路由侧（若日后接线）同用本模块，两处不会分叉。
+//
+// ── 四条硬规矩（对齐仓库既有纪律）──────────────────────────────────────────────
+//   ① **只补缺的**：能解析的包一个字节都不写（幂等；健康的框架树是 no-op）。
+//   ② **绝不 kill / spawn / 抢端口 / 建计划任务** —— 这正是 2026-10-10 `restart.js` 下线的
+//      那套动作（会与宿主争端口 ⇒ `listen EADDRINUSE`；kill 宿主 ⇒ 外壳弹「应用无法启动或已意外停止」）。
+//      本模块只做**文件级**修复，跑完由调用方决定要不要重启。
+//   ③ **修复源必须可解释**：只从 `package-lock.json` 的 `integrity` + 本地 npm 缓存取，
+//      **不联网、不猜版本**；取不到就如实报"缺什么"，绝不假装成功。
+//   ④ **改前留痕**：有内容的目标目录先改名成 `<name>.preflight-bak-<ts>`（绝不直接删）。
+//
+// 分层：L1 · domain —— 不得出现 cordis ctx（test-architecture-guard 断言⑤）。
+// 行数预算：独立模块，留在 600 行架构硬顶内。
+
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import { probeClosure } from '../infra/fw-closure.js'
+import { candidateCacheRoots, extractTgz, readTarballFromAny } from '../infra/npm-cache.js'
+
+/** 备份名后缀（与 `.stale-*` 同族但可区分：预检造的备份不该被"框架残留"判据当成残留改名）。 */
+const PREFLIGHT_BAK = '.preflight-bak-'
+
+/** 该目录名是不是预检留下的备份。 */
+function isPreflightBak(name) {
+  return typeof name === 'string' && name.includes(PREFLIGHT_BAK)
+}
+
+/** 文件名里安全的时间戳（冒号/点在 Windows 上是非法字符）。 */
+function stampOf(ms) {
+  return new Date(ms).toISOString().replace(/[:.]/gu, '-')
+}
+
+/**
+ * 定位 lock 文件：`fwRoot` 是**那层 `node_modules` 本身**，而 lock 住在它的**父目录**
+ * （真机实测：`D:\node_cache\_npx\<hash>\node_modules` 是框架树，而
+ *   `D:\node_cache\_npx\<hash>\package-lock.json` 才是清单）。
+ *
+ * 候选顺序（先近后远，两种生态都认）：
+ *   ① `<fwRoot>/package-lock.json`（少数形态：树根就带清单）
+ *   ② `<dirname(fwRoot)>/package-lock.json` ← **真机主力**
+ *   ③ `<dirname(fwRoot)>/pnpm-lock.yaml`（pnpm 形态；本模块目前只解析 npm 的 JSON 清单，
+ *      命中 yaml 时返回它并由调用方如实记"该清单格式不支持"，**不静默当成没有**）
+ *
+ * @returns {{ path: string|null, kind: 'npm'|'pnpm'|null, tried: string[] }}
+ */
+function locateLockfile(fwRoot, { deps = {} } = {}) {
+  const exists = deps.exists ?? existsSync
+  const parent = dirname(fwRoot)
+  const tried = []
+  const cands = [
+    { p: join(fwRoot, 'package-lock.json'), kind: 'npm' },
+    { p: join(parent, 'package-lock.json'), kind: 'npm' },
+    { p: join(parent, 'pnpm-lock.yaml'), kind: 'pnpm' },
+  ]
+  for (const c of cands) {
+    tried.push(c.p)
+    if (exists(c.p)) return { path: c.p, kind: c.kind, tried }
+  }
+  return { path: null, kind: null, tried }
+}
+
+/**
+ * 从 `package-lock.json` 建索引：`名@版本` → `{ name, version, integrity }`。
+ * 兼容 lockfileVersion 3（`packages` 键形如 `node_modules/@scope/name`）与更老的 `dependencies` 树。
+ * 读不出/解析失败一律返回空 Map（调用方据此如实报"没有可用恢复源"）。
+ */
+function buildLockIndex(lockPath, { deps = {} } = {}) {
+  const exists = deps.exists ?? existsSync
+  const read = deps.read ?? ((p) => readFileSync(p, 'utf8'))
+  const idx = new Map()
+  if (typeof lockPath !== 'string' || !exists(lockPath)) return idx
+  let lock = null
+  try { lock = JSON.parse(read(lockPath)) } catch { return idx }
+  if (lock === null || typeof lock !== 'object') return idx
+
+  const add = (name, entry) => {
+    if (typeof name !== 'string' || name === '') return
+    if (entry === null || typeof entry !== 'object' || typeof entry.version !== 'string') return
+    const key = `${name}@${entry.version}`
+    if (!idx.has(key)) idx.set(key, { name, version: entry.version, integrity: entry.integrity ?? null, resolved: entry.resolved ?? null })
+  }
+
+  if (lock.packages !== null && typeof lock.packages === 'object') {
+    for (const [key, entry] of Object.entries(lock.packages)) {
+      if (!key.startsWith('node_modules/')) continue
+      // `node_modules/@scope/name` 与 `node_modules/a/node_modules/b` 都取**最后一段包名**
+      const m = /node_modules\/(@[^/]+\/[^/]+|[^/]+)$/u.exec(key)
+      if (m !== null) add(m[1], entry)
+    }
+  }
+  if (idx.size === 0 && lock.dependencies !== null && typeof lock.dependencies === 'object') {
+    const walkDeps = (tree) => {
+      for (const [name, entry] of Object.entries(tree ?? {})) {
+        add(name, entry)
+        if (entry?.dependencies) walkDeps(entry.dependencies)
+      }
+    }
+    walkDeps(lock.dependencies)
+  }
+  return idx
+}
+
+/** 宽松版本比较（够用于"多版本里挑一个"，不追求完整 semver）。 */
+function compareLoose(a, b) {
+  const pa = String(a ?? '').split(/[.\-+]/u)
+  const pb = String(b ?? '').split(/[.\-+]/u)
+  for (let i = 0; i < Math.max(pa.length, pb.length); i += 1) {
+    const na = Number.parseInt(pa[i] ?? '0', 10)
+    const nb = Number.parseInt(pb[i] ?? '0', 10)
+    if (Number.isFinite(na) && Number.isFinite(nb)) {
+      if (na !== nb) return na - nb
+    } else {
+      const sa = String(pa[i] ?? '')
+      const sb = String(pb[i] ?? '')
+      if (sa !== sb) return sa < sb ? -1 : 1
+    }
+  }
+  return 0
+}
+
+/**
+ * **纯函数**：给定闭包探测结果与 lock 索引，产出修复计划（不碰 IO，可离线单测）。
+ *
+ * 目标目录判定（先问"它本该在哪"，再退顶层投影 —— 真机 `dsh-llm` / `dsh-tools` / `dsh-web`
+ * 就住在顶层 `node_modules/@deepseek-ai/` 下，而 `cordis` 是顶层 junction 指向 `.pnpm` 实体）：
+ *   ① `resolveDir(name)` 给出的位置  ② `nodeModulesDir/<scope>/<name>`  ③ `storeDir/<name>`
+ *
+ * 同包多版本时取**版本最高**那条（把包装回来时，新版更可能是对的那份）。
+ *
+ * @returns {{ items: Array, skippable: Array }}
+ *          `skippable[].reason`：`no-lock-entry`（lock 里没有 ⇒ **不猜版本**）/`no-integrity`/`no-target`。
+ */
+function planClosureRepair({ broken = [], lockIndex = new Map(), resolveDir = () => null, nodeModulesDir = null, storeDir = null } = {}) {
+  const items = []
+  const skippable = []
+  for (const bad of Array.isArray(broken) ? broken : []) {
+    const name = bad?.name
+    if (typeof name !== 'string' || name === '') continue
+
+    const hits = []
+    for (const [key, entry] of lockIndex) if (key.startsWith(name + '@')) hits.push(entry)
+    if (hits.length === 0) { skippable.push({ name, reason: 'no-lock-entry' }); continue }
+    hits.sort((a, b) => compareLoose(a.version, b.version))
+    const chosen = hits[hits.length - 1]
+    if (chosen.integrity === null || chosen.integrity === undefined) { skippable.push({ name, reason: 'no-integrity' }); continue }
+
+    const segments = name.startsWith('@') ? name.split('/') : [name]
+    const resolved = typeof resolveDir === 'function' ? resolveDir(name) : null
+    const topLevel = nodeModulesDir === null ? null : join(nodeModulesDir, ...segments)
+    const store = storeDir === null ? null : join(storeDir, ...segments)
+    let target = null
+    let via = null
+    for (const [cand, how] of [[resolved, 'resolve'], [topLevel, 'top-level'], [store, 'pnpm-store']]) {
+      if (typeof cand === 'string' && cand !== '') { target = cand; via = how; break }
+    }
+    if (target === null) { skippable.push({ name, reason: 'no-target' }); continue }
+    items.push({ name, version: chosen.version, integrity: chosen.integrity, target, via, reason: bad.reason ?? 'unresolvable' })
+  }
+  return { items, skippable }
+}
+
+/**
+ * 执行计划里的**一条**恢复：缓存命中 → 解包到目标。
+ *
+ * ★ **junction 关键判据**（真机 2026-10-14 演练抓到的设计错误）：
+ *   `cordis` 的坏法是"顶层 junction 还在、它指向的 `.pnpm` **实体**被掏空"。若把内容写进
+ *   **顶层那个 junction 名字**，pnpm 的链接结构就被破坏了 —— 顶层从"链接"退化成"真实目录"，
+ *   同一份包在树里于是有了**第二个实体**：
+ *     · 模块身份不再共享（Cordis service 类 / LLM error 类靠 `instanceof` 与单例注册表相认 ——
+ *       这正是 domain/link-self-sufficiency.js 头注释里"必须链接而不是复制"的那条教训）；
+ *     · pnpm 后续重装会认为顶层"不是自己管的"，产生版本漂移与二次损坏。
+ *   ⇒ 目标是链接时，**只把内容写进它指向的真实目录**（`realpathSync`），链接原样保留。
+ *
+ * 其余三种形态照旧：空壳真实目录直接替换；有内容的真实目录先改名成 `.preflight-bak-<ts>`
+ * 再装（**绝不直接删**）；目标不存在则新建后装。
+ *
+ * 返回 `{ ok, action, note }`，失败必须带可读原因（绝不静默吞）。
+ */
+function applyRepairItem(item, { cacheRoots = [], deps = {} } = {}) {
+  const exists = deps.exists ?? existsSync
+  const rename = deps.rename ?? renameSync
+  const rm = deps.rm ?? ((p) => rmSync(p, { recursive: true, force: true }))
+  const mkdir = deps.mkdir ?? ((p) => mkdirSync(p, { recursive: true }))
+  const now = deps.now ?? (() => Date.now())
+  const realpath = deps.realpath ?? ((p) => realpathSync(p))
+  const lstat = deps.lstat ?? ((p) => lstatSync(p))
+  try {
+    const hit = readTarballFromAny(cacheRoots, item.integrity, { deps })
+    if (hit === null) return { ok: false, action: 'skipped', note: '本地 npm 缓存中找不到该 integrity（未联网，不猜版本）' }
+
+    // 目标是链接 ⇒ 写进它指向的实体，链接本身一个字节都不动
+    let target = item.target
+    let viaLink = false
+    let isLink = false
+    try { isLink = lstat(target).isSymbolicLink() } catch { isLink = false }
+    if (isLink) {
+      viaLink = true
+      try { target = realpath(target) } catch {
+        return { ok: false, action: 'failed', note: '目标是指向不存在实体的悬空链接，且无法解析真身 —— 不猜目标' }
+      }
+    }
+
+    let backupPath = null
+    if (exists(target)) {
+      let empty = false
+      try { empty = readdirSync(target).length === 0 } catch { empty = false }
+      if (empty) rm(target)
+      else {
+        backupPath = `${target}${PREFLIGHT_BAK}${stampOf(now())}`
+        rename(target, backupPath)
+      }
+    }
+    mkdir(target)
+    const stat = extractTgz(hit.buf, target, { deps })
+    if (!exists(join(target, 'package.json'))) {
+      return { ok: false, action: 'extracted-but-no-manifest', note: `解包完成但无 package.json（${stat.files} 个文件）`, backupPath }
+    }
+    return {
+      ok: true,
+      action: 'restored',
+      note: `${item.version}（${stat.files} 个文件）${viaLink ? ' → 经链接写入实体，链接保留' : ''}`,
+      backupPath,
+      cacheRoot: hit.cacheRoot,
+      viaLink,
+    }
+  } catch (error) {
+    return { ok: false, action: 'failed', note: String(error?.message ?? error) }
+  }
+}
+
+/** 定框架树的解析入口：优先顶层 `@deepseek-ai/dsh/lib/bin.js`，退 `.pnpm` 内层实体。 */
+function locateFrameworkEntry(fwRoot, { deps = {} } = {}) {
+  const exists = deps.exists ?? existsSync
+  const topBin = join(fwRoot, '@deepseek-ai', 'dsh', 'lib', 'bin.js')
+  if (exists(topBin)) return { entry: topBin, via: 'top-level' }
+  try {
+    for (const name of readdirSync(join(fwRoot, '.pnpm'))) {
+      if (!name.startsWith('@deepseek-ai+dsh@')) continue
+      const cand = join(fwRoot, '.pnpm', name, 'node_modules', '@deepseek-ai', 'dsh', 'lib', 'bin.js')
+      if (exists(cand)) return { entry: cand, via: 'pnpm-store' }
+    }
+  } catch {}
+  return { entry: null, via: null }
+}
+
+/**
+ * 预检 + 治包的**唯一入口**（探测 → 计划 → 执行 → 复验）。
+ *
+ * @param {object} p
+ * @param {string} p.fwRoot       框架树根（含 `@deepseek-ai/` 与 `.pnpm/`）。
+ * @param {boolean} [p.repair]    true = 真装回；false（默认）= **只诊断，一个字节都不写**。
+ * @param {string} [p.lockPath]   默认 `<fwRoot>/package-lock.json`。
+ * @param {number} [p.maxRepair]  单次最多修几个（防御上限；默认 200）。
+ * @param {object} [p.deps]       IO 注入（单测用）。
+ * @returns 结构化报告；`ok` = **修复前**闭包是否完整，`okAfter` = 修复后复验结果。
+ */
+function runFwPreflight({ fwRoot, repair = false, lockPath = null, maxRepair = 200, deps = {}, cacheRoots = null } = {}) {
+  const read = deps.read ?? ((p) => readFileSync(p, 'utf8'))
+  const makeReq = deps.createRequire ?? createRequire
+  const probe = deps.probeClosure ?? probeClosure
+  const roots = Array.isArray(cacheRoots) && cacheRoots.length > 0
+    ? cacheRoots
+    : (typeof deps.cacheRoots === 'function' ? deps.cacheRoots() : candidateCacheRoots({ env: deps.env ?? process.env }))
+
+  const report = { fwRoot: fwRoot ?? null, entry: null, entryVia: null, before: null, after: null, plan: [], repaired: [], failed: [], skipped: [], cacheRoots: roots, repair, lockPath: null, lockKind: null }
+
+  if (typeof fwRoot !== 'string' || fwRoot === '') { report.error = 'fwRoot 未提供'; return report }
+
+  const located = locateFrameworkEntry(fwRoot, { deps })
+  report.entry = located.entry
+  report.entryVia = located.via
+  if (located.entry === null) { report.error = '找不到 dsh 的 lib/bin.js（顶层与 .pnpm 都没有）——框架树本身不完整'; report.ok = false; return report }
+
+  const before = probe({ entry: located.entry, deps })
+  report.before = before
+  report.ok = before.ok
+
+  let req = null
+  try { req = makeReq(located.entry) } catch { req = null }
+  const resolveDir = (name) => {
+    if (req === null) return null
+    try { return dirname(req.resolve(name + '/package.json')) } catch { return null }
+  }
+
+  const lockLocated = typeof lockPath === 'string' && lockPath !== ''
+    ? { path: lockPath, kind: 'npm', tried: [lockPath] }
+    : locateLockfile(fwRoot, { deps })
+  report.lockPath = lockLocated.path
+  report.lockKind = lockLocated.kind
+  const lock = lockLocated.kind === 'npm' ? buildLockIndex(lockLocated.path, { deps }) : new Map()
+  // ★ 基准收口：`fwRoot` 就是**那层 node_modules 本身**（真机实测：`…\_npx\<hash>\node_modules`、
+  //   `…\profiles\node_modules`、桌面端 `…\dsh\node_modules` 都是这个形态）。
+  //   于是顶层投影就是 `fwRoot/@deepseek-ai/<name>` —— **不再拼一层 `node_modules`**。
+  //   （2026-10-14 踩到：拼成 `fwRoot/node_modules/@deepseek-ai/…` ⇒ 目标路径不存在 ⇒
+  //    修复计划指向错误的树，真正坏掉的那棵树纹丝不动。）
+  const plan = planClosureRepair({
+    broken: before.broken,
+    lockIndex: lock,
+    resolveDir,
+    nodeModulesDir: fwRoot,
+    storeDir: join(fwRoot, '.pnpm', 'node_modules'),
+  })
+  report.plan = plan.items.map((i) => ({ name: i.name, version: i.version, target: i.target, via: i.via, reason: i.reason }))
+  report.skipped = plan.skippable
+
+  if (repair !== true) return report
+
+  for (const item of plan.items.slice(0, maxRepair)) {
+    const r = applyRepairItem(item, { cacheRoots: roots, deps })
+    if (r.ok) report.repaired.push({ name: item.name, version: item.version, target: item.target, via: item.via, note: r.note })
+    else report.failed.push({ name: item.name, target: item.target, action: r.action, note: r.note })
+  }
+
+  // 复验：修完必须**重新走一遍闭包** —— 不靠"我装完了"自证
+  const after = probe({ entry: located.entry, deps })
+  report.after = after
+  report.okAfter = after.ok
+  report.changed = report.repaired.length > 0
+  return report
+}
+
+export {
+  PREFLIGHT_BAK,
+  applyRepairItem,
+  buildLockIndex,
+  compareLoose,
+  isPreflightBak,
+  locateFrameworkEntry,
+  locateLockfile,
+  planClosureRepair,
+  runFwPreflight,
+  stampOf,
+}

package/lib/server/infra/exec.js

@@ -445,16 +445,30 @@ function execFileWithKillTree(bin, argv, opts = {}, deps = {}) {
  *   仍然照需求注入这三个 env（CI 与非交互确实有用、registry 镜像照旧、fetch_* 是 npm 系标准写法，
  *   对 npm/后续 pnpm 版本仍可能生效），但**不把健壮性只押在 env 上**。
  *
- * ★ 2026-10-13（0.5.48，实测"装 ds-bot 时无 TTY 永久挂住"）：补 `npm_config_ci=true` ——
- *   pnpm 判"能不能弹交互"用的是**它自己的 ci 配置项**（`opts3.ci`，env 形态即 `npm_config_ci`），
- *   **不是** `process.env.CI`；只给 `CI=true` 时 `canPrompt` 可能仍为真 ⇒ 弹提问 ⇒ 读 stdin 到 EOF
- *   ⇒ 桌面壳的管道永不关闭 ⇒ 永久挂住。取证与完整链条见 infra/pnpm-release-gate.js 头注释。 */
+ * ★ 2026-10-14（回校 0.5.48 此处的判断，**行为未动、只更正说明**。完整取证与五组实验见
+ *   CHANGELOG「v0.5.51」那节；这里只留结论，因为本文件贴着架构守卫的 600 行硬顶）：
+ *   ① `npm_config_ci=true` 对 pnpm **自己的**配置项是**空操作**（只认 `pnpm_config_*` 前缀，
+ *      含 argv 的 `--config.*`）⇒ 这一行是安慰剂，别再当成非交互的保证。
+ *   ② `CI=true` **确实**点亮 ci 位（pnpm 配置默认值 `ci: isCI`，`isCI` 判 `env.CI`）⇒
+ *      `pnpm install` 面对过时 lock **会**被 frozen 拒绝（加 `--no-frozen-lockfile` 即恢复）。
+ *      这一位 **v0.5.30 就已注入**，不是 0.5.48 新增。
+ *   ③ 「pnpm 弹提问 ⇒ 读 stdin 到 EOF ⇒ 永久挂住」**不成立**：`canPrompt` 需要
+ *      `process.stdin.isTTY`，管道下恒为假 ⇒ pnpm 从不 prompt；五种 ci 配置实测**全部快速失败**。
+ *   ④ 那"挂到 90s / 180s"**是我们自己的超时常量**（`runPnpmAdd` timeout=90000、
+ *      `installTargetDependencies` timeoutMs=180000），与当时观察逐一吻合 ⇒ 是"超过我们的
+ *      超时被杀"，不是"等输入"。**那次为什么慢至今没有证据**（最可能是网络）。
+ *   ⑤ corepack 的下载提问也**默认是关的**（入口 shim `COREPACK_ENABLE_DOWNLOAD_PROMPT ??= '0'`），
+ *      只有显式设成 1 才会问 ⇒ 也不是默认真凶。
+ *   ⇒ 0.5.48 那条「永久挂住」的**根因至今未查明**，能确定的只有"不是 pnpm 的交互提问"。
+ *     `--config.ci=true` 仍保留独立价值：钉死 ci 位 + 让 install 在 lock 过时走 frozen 拒绝
+ *     而非静默改写；`pnpm add` 不受 frozen 影响（实测带/不带此旗结局相同）。 */
 function pnpmEnvOverrides(registry) {
   const overrides = {
     npm_config_fetch_timeout: '60000',
     npm_config_fetch_retries: '1',
     CI: 'true',
-    // pnpm 自己的 ci 位（非交互的权威开关）；`CI=true` 单独不够，理由见上。
+    // 0.5.48 原注：「pnpm 自己的 ci 位（非交互的权威开关）；CI=true 单独不够」——
+    // 2026-10-14 实测更正：这一行对 pnpm 是空操作（见上一段）。保留只为兼容与无害。
     npm_config_ci: 'true',
   }
   if (typeof registry === 'string' && registry !== '') overrides.COREPACK_NPM_REGISTRY = registry
@@ -490,8 +504,15 @@ function pnpmFetchArgs(timeoutMs = 60000, retries = 1) {
  *
  * ★ 2026-10-13（0.5.48）：追加 `--config.ci=true` —— pnpm **官方支持的非交互开关**
  * （`--config.<key>=<value>` 是 pnpm 设任意配置项的通用语法，**不是**绕过闸门的手段）。
- * 理由与取证见 infra/pnpm-release-gate.js 头注释：命中供应链闸门时它会弹提问等人回答，
- * 而无 TTY 的子进程 stdin 是永不关闭的管道 ⇒ **永久挂住**；钉死 ci 位 ⇒ 改成快速如实失败。 */
+ * ★ 2026-10-14（实测更正 0.5.48 的理由陈述，**行为未动**）：0.5.48 写"命中供应链闸 ⇒ 弹提问 ⇒
+ *   管道永不关闭 ⇒ 永久挂住"，这条因果链实测**不成立**：pnpm 的
+ *   `canPrompt = !inCi && Boolean(process.stdin.isTTY)`，管道下 isTTY 恒假 ⇒ pnpm 从不 prompt，
+ *   五种 ci 配置实测全部快速失败（无一挂住）。真正读 stdin 等人的是 **corepack 的下载提问**
+ *   （corepack.cjs L22083，判据 `process.stdin.isTTY && !process.env.CI`）。
+ *   所以这一位的真实价值是：**把 ci 位钉死**（与 `CI=true` 同向、但不受 env 被覆盖影响），
+ *   并让 install 类命令在 lock 过时走 frozen 拒绝而非静默改写。`pnpm add` 不受 frozen 影响
+ *   （实测：带/不带此旗，add 都照常装上并更新 lock）⇒ 不会把安装变成拒绝。
+ *   详见 pnpmEnvOverrides 上方的完整更正说明。 */
 function pnpmAddArgs(spec, registry, { fetchFlags = true, fetchTimeoutMs = 60000, fetchRetries = 1 } = {}) {
   const args = ['add', spec]
   if (typeof registry === 'string' && registry !== '') args.push('--registry', registry)

package/lib/server/infra/fw-closure.js

@@ -0,0 +1,142 @@
+// L0 · infra —— fw-closure.js（框架**依赖闭包**探测：判据是"能不能解析出来"；0.5.50 加法）
+//
+// 为什么需要它（**真机停机事故 2026-10-14**）：
+//   npx 缓存里的四个框架包被掏空 —— `cordis` 顶层 junction 还在、它指向的 `.pnpm` 实体目录
+//   被清空；`dsh-llm` / `dsh-tools` / `dsh-web` 直接成了**空的真实目录**。后果是 dsh 启动即
+//   `startup failed: 54 个插件 failed to import`，web 服务 exit code=1，**插件自己没机会运行**。
+//
+//   而既有指纹判据 `compat-state.js#pnpmEntities` 是**数 `.pnpm` 里 `@deepseek-ai*` 的目录个数**：
+//   本事故形态恰好是"目录壳还在、里面被掏空" ⇒ 19 → 19，计数**一个都不变** ⇒ 指纹判定环境未变
+//   ⇒ 不触发任何动作。次生的：`dsh-llm` / `dsh-tools` / `dsh-web` **根本不在 `.pnpm` 里**
+//   （它们住在顶层 `node_modules/@deepseek-ai/`），那个计数从来就不覆盖它们。
+//
+//   本模块给出**面向解析**的判据：从 dsh 的 `lib/bin.js` 出发，把 `@deepseek-ai/*` 的依赖闭包
+//   整条走一遍，谁 `resolve(name + '/package.json')` 失败谁就是坏的 —— 与目录长什么样无关，
+//   不存在"数个数"那种对"掏空"免疫的盲区，也不会把 `@scope` 目录、`.pnpm` 历史残留误判成损坏
+//   （2026-10-14 实测：按"目录空不空"粗扫本机会误报 237 个；换成闭包判据后 287 个包精准通过）。
+//
+// 两条纪律：
+//   ① 判据只认"能解析"这一件事（与版本号无关）—— 与 domain/framework-residuals.js 的
+//      `FRAMEWORK_BOOT_PACKAGES` 同源取舍：版本号对 ≠ 装完整。
+//   ② IO 全部可注入（`deps`）—— 单测用内存实现即可驱动，不必真造一棵坏框架树、不联网、不起进程。
+//
+// 分层：L0 · infra（不得 import domain/routes/index —— tests/test-architecture-guard.mjs 断言②）。
+// 行数预算：独立小模块，留在 600 行架构硬顶内。
+
+import { existsSync, readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { basename, dirname, join } from 'node:path'
+
+/** 框架命名空间：`@deepseek-ai/*` 随框架版本走，承载者永远是框架安装树。 */
+const FRAMEWORK_SCOPE = '@deepseek-ai/'
+
+/**
+ * 包名归一：`@scope/name/sub/deep` → `@scope/name`；裸名 `name/sub` → `name`。
+ * 与 domain/framework-root.js#basePackageName 同判据（这里独立实现：那边服务"基准枚举"，
+ * 这边服务"闭包遍历"，两者失败模式不同，不互相牵制）。
+ */
+function baseNameOf(spec) {
+  const text = String(spec ?? '')
+  if (text.startsWith('@')) {
+    const parts = text.split('/')
+    return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : text
+  }
+  return text.split('/')[0]
+}
+
+/** 该引用名是否属于要遍历的命名空间（默认 `@deepseek-ai/`）。 */
+function isInScope(spec, scopePrefix = FRAMEWORK_SCOPE) {
+  const name = baseNameOf(spec)
+  return name === scopePrefix.slice(0, -1) || name.startsWith(scopePrefix)
+}
+
+/**
+ * 走一遍依赖闭包，返回**解析不了**的包（= 真正的损坏面）。
+ *
+ * @param {object} p
+ * @param {string} p.entry            入口文件绝对路径（如 `<fwRoot>/@deepseek-ai/dsh/lib/bin.js`）；
+ *                                    解析基准由它决定 —— 与 Node 真实解析语义完全一致，不另造基准。
+ * @param {string} [p.rootName]       入口包名（默认 `@deepseek-ai/dsh`）。
+ * @param {string} [p.scopePrefix]    只遍历这个前缀（默认 `@deepseek-ai/`）。
+ * @param {number} [p.maxPackages]    遍历上限（防御病态闭包；默认 2000）。
+ * @param {object} [p.deps]           IO 注入（单测用）。
+ * @returns {{ ok: boolean, walked: string[], broken: Array<{name:string, from:string, reason:string}>,
+ *             total: number, truncated: boolean }}
+ *          `broken[].reason` 取值：`unresolvable`（解析失败）/`unreadable`（清单读不出）/`malformed`（JSON 坏）。
+ */
+function probeClosure({ entry, rootName = '@deepseek-ai/dsh', scopePrefix = FRAMEWORK_SCOPE, maxPackages = 2000, deps = {} } = {}) {
+  const createReq = deps.createRequire ?? createRequire
+  const readJson = deps.readJson ?? ((p) => JSON.parse(readFileSync(p, 'utf8')))
+  const exists = deps.exists ?? existsSync
+  const resolveSpec = deps.resolveSpec ?? null
+
+  const walked = []
+  const broken = []
+  const brokenSeen = new Set()
+  const seen = new Set()
+  if (typeof entry !== 'string' || entry === '') {
+    return { ok: false, walked, broken: [{ name: rootName, from: '(入口)', reason: 'entry-missing' }], total: 0, truncated: false }
+  }
+
+  /**
+   * 记录一个坏包。**同一个包只记一次**（保留第一个发现它的引用方）。
+   * 为什么去重：一个"枢纽包"（如 `dsh-tools`）坏了会波及整条下游 —— 真机实测清空 `dsh-tools`
+   * 会产出 46 条记录，而它们**全是同一个包**。逐条打印会把"到底哪个包坏了"淹没在噪声里；
+   * 修复计划也会对同一个目标重复下单。去重后：一个坏包 = 一条记录 = 一次修复。
+   */
+  const markBroken = (name, from, reason) => {
+    if (brokenSeen.has(name)) return
+    brokenSeen.add(name)
+    broken.push({ name, from, reason })
+  }
+
+  const entryReq = createReq(entry)
+  /** 解析一个引用名 → 它的包目录；失败返回 null。注入 `resolveSpec` 时完全走替身（单测）。 */
+  const resolveDir = (name, fromDir, fromReq) => {
+    if (typeof resolveSpec === 'function') return resolveSpec(name, fromDir)
+    try { return dirname(fromReq.resolve(name + '/package.json')) } catch { return null }
+  }
+
+  const walk = (name, from, fromReq, fromDir) => {
+    if (walked.length >= maxPackages) return
+    if (seen.has(name)) return
+    seen.add(name)
+    walked.push(name)
+
+    const dir = resolveDir(name, fromDir, fromReq)
+    if (dir === null) { markBroken(name, from, 'unresolvable'); return }
+    let pkg = null
+    try { pkg = readJson(join(dir, 'package.json')) } catch (error) { markBroken(name, from, 'unreadable'); return }
+    if (pkg === null || typeof pkg !== 'object') { markBroken(name, from, 'malformed'); return }
+
+    const depsOf = { ...(pkg.dependencies ?? {}), ...(pkg.peerDependencies ?? {}) }
+    const optionalPeers = pkg.peerDependenciesMeta ?? {}
+    let subReq = null
+    try { subReq = typeof resolveSpec === 'function' ? fromReq : createReq(join(dir, 'noop.js')) } catch { subReq = fromReq }
+    for (const spec of Object.keys(depsOf)) {
+      if (!isInScope(spec, scopePrefix)) continue
+      const child = baseNameOf(spec)
+      const optional = optionalPeers[spec]?.optional === true
+      const childDir = resolveDir(child, dir, subReq)
+      if (childDir === null) {
+        // 可选 peer 缺失不算坏（与既有判据一致：不放松成"一律放行"，也不冤枉合法的可选依赖）
+        if (!optional) markBroken(child, name, 'unresolvable')
+        continue
+      }
+      // `exists` 仅用于让注入替身也能表达"目录在、内容空"这一形态
+      if (typeof deps.exists === 'function' && exists(childDir) === false) continue
+      walk(child, name, subReq, dir)
+    }
+  }
+
+  // 入口包本身也要认：它解析不出来时，后面所有包都会连带失败 —— 先把根报出来，才有可读的原因链
+  const rootDir = resolveDir(rootName, dirname(entry), entryReq)
+  if (rootDir === null) {
+    return { ok: false, walked, broken: [{ name: rootName, from: '(入口)', reason: 'unresolvable' }], total: 0, truncated: false }
+  }
+  walk(rootName, '(入口)', entryReq, dirname(entry))
+
+  return { ok: broken.length === 0, walked, broken, total: walked.length, truncated: walked.length >= maxPackages }
+}
+
+export { FRAMEWORK_SCOPE, baseNameOf, isInScope, probeClosure }