@noob-stupid/dsh-plugin-console 0.5.31 → 0.5.32

package/README.md

@@ -311,8 +311,40 @@ The mode decides **who leads framework upgrades** — nothing else:
 
 - **Observer (default)**: the console only preflights, gates, and guards the rollback point. It does not take over upgrades.
 - **Managed**: framework upgrade and rollback are owned by this console. It switches to managed automatically when you upgrade through this console, and records the reason.
+- **Switches back to Observer automatically (0.5.32)**: when the **desktop-host shape** is detected (the existing `detectHostShape()` criteria), a mode that was **not set by hand** (`compat-mode.json` `source` is `auto:*`; a missing field counts as `manual`) is switched back to Observer on startup / first status query, with a one-line notice. **Once you switch it by hand it is never changed automatically again**; when it is already Observer nothing is written.
 
 **Boot-failure quarantine is not affected by the mode.** When the service cannot start, the console locates the culprit from the boot log and disables it (broken presets are renamed to `.broken-*`; with no clear culprit it falls back to safe mode so the service can start). A console that cannot boot cannot gate anything — so this rescue path always runs.
+
+**Auto-disable on confirmed evidence (0.5.32)**: when the fingerprint-triggered auto-preflight, or a
+boot-failure record, provides **confirmed evidence** (the row's package resolves on **none** of the
+resolution bases, a `file://` target truly does not exist, or the boot log names the row), the console
+writes `disabled: true` for those rows **itself** (no click needed). Safety rails: **only rows with
+evidence**; `@deepseek-ai/*` (framework-owned) and protected/core rows are **never** auto-disabled;
+a **safe-boot snapshot is written first**, so any auto-disable is one command away from a rollback;
+when there is nothing to write, **not a single byte is written**; every auto-disable leaves a record in
+`dshHome()/plugin-console/auto-disable.log` (time / row id / evidence / restore command).
+
+Prefer "report only, let me click" (enabled by default) — replace `<host:port>` with your instance
+(the default `dsh web` profile listens on `127.0.0.1:3080`):
+
+```bash
+curl -X POST http://<host:port>/plugin-console/compat-ack \
+  -H 'Content-Type: application/json' -d '{"autoDisableOnEvidence":false}'
+```
+
+**How to roll an auto-disable back**: the route `POST /plugin-console/safe-boot` with
+`{"action":"restore-last-good"}` (the current state is backed up first), or — when the service will not
+start — from the plugin directory:
+
+```bash
+node scripts/safe-boot.mjs --list                 # see which snapshots exist
+node scripts/safe-boot.mjs --restore-last-good    # restore the newest good snapshot byte-for-byte
+node scripts/safe-boot.mjs --disable-suspects     # or: append disabled: true to named rows only (nothing deleted)
+node scripts/safe-boot.mjs --mark-good            # mark a snapshot as good (never removed by retention)
+```
+
+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.
 ## 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

@@ -248,8 +248,40 @@ git clone https://github.com/Noob-stupid/dsh-plugin-gating-hub /tmp/dsh-plugin-c
 
 - **观察者（默认）**：只做预检、门控与回滚点守护，不接管框架升级。
 - **托管**：框架升级与回滚由本控制台负责。**走本控制台升级时会自动切到托管**并记下原因。
+- **自动切回观察者（0.5.32）**：检测到**桌面端宿主形态**（复用既有 `detectHostShape()` 判据）时，
+  若当前模式**不是用户手动设定的**（`compat-mode.json` 的 `source` 为 `auto:*`；缺字段按 `manual` 兼容），
+  启动/首次状态查询会把它自动拨回观察者并给一行提示。**你手动拨过一次之后，它永不自动改**；
+  已经是观察者时零写盘。
 
 **启动失败隔离不受模式影响。** 服务起不来时，控制台会从启动日志定位肇事插件并禁用它（预设文件改名 `.broken-*`；找不到明确肇事者则进安全模式先让服务起来）。**起不来的控制台什么都门控不了** —— 所以这条救火链路永远生效。
+
+**有确证证据时会自动禁用（0.5.32）**：环境指纹变化触发的自动预检、或启动失败记录给出**确证证据**时
+（行引用的包**在所有解析基准上都解析不到**、`file://` 目标确实不存在、启动失败日志**点名**该行），
+控制台会**自动**给这些行写 `disabled: true`（不再等你点）。安全栏：**只禁有证据的行**；
+`@deepseek-ai/*`（框架自带）与受保护/核心行**永不自动禁用**；**禁前先写一份"安全启动快照"**，
+所以任何一次自动禁用都能一条命令回滚；没有可写内容时**一个字节都不写**；每次自动禁用都在
+`dshHome()/plugin-console/auto-disable.log` 留一条记录（时间 / 行 id / 证据 / 恢复命令）。
+
+想改成"只报告、等我自己点"（默认启用）—— `<host:port>` 换成你实例的地址
+（默认 `dsh web` profile 监听 `127.0.0.1:3080`）：
+
+```bash
+curl -X POST http://<host:port>/plugin-console/compat-ack \
+  -H 'Content-Type: application/json' -d '{"autoDisableOnEvidence":false}'
+```
+
+**怎么恢复（把自动禁用回滚）**：接口 `POST /plugin-console/safe-boot` + `{"action":"restore-last-good"}`
+（改前会再备份一份当前状态）；或服务打不开时，在插件目录下跑：
+
+```bash
+node scripts/safe-boot.mjs --list                 # 先看清有哪些快照
+node scripts/safe-boot.mjs --restore-last-good    # 整份逐字节恢复到最近的良好快照
+node scripts/safe-boot.mjs --disable-suspects     # 或：只给点名的可疑行追加 disabled: true（不删任何行）
+node scripts/safe-boot.mjs --mark-good            # 把某份快照标记为"良好"（永不随保留策略删除）
+```
+
+安全启动快照落在 `dshHome()/plugin-console/safe-boot/`（**不在** profile 目录里），保留最近 3 份 +
+永不删你标记为"良好"的那份。
 ## 框架兼容性
 
 在隔离实例（全新 `DSH_HOME` + 真实 HTTP 探针）实测：**支持框架 ≥ `0.1.5-rc.2`**，无需任何变通。

package/lib/client.js

@@ -5486,7 +5486,21 @@ setMessage(t("failed") + "：" + (data?.reason ?? "未知"));
 			// 2026-09-27 加法：依赖锁体检结果（null = 还没体检过；不自动跑，用户点「体检」才打接口）
 			const [lockFix, setLockFix] = react.useState(null);
 			const load = async () => {
-				try { const data = await call("/plugin-console/compat-status"); if (data !== null) setStatus(data); } catch {}
+				try {
+					const data = await call("/plugin-console/compat-status");
+					if (data !== null) {
+						setStatus(data);
+						// 0.5.32 加法（D1/D4/D5）：**瞬时提示**，沿用既有 note 通道（自动消失、无新组件、无按钮）。
+						// 文案由服务端下发（中英双语短句）：「已自动切观察者」/「框架变化，已自动预检」/「已自动禁用 N 行」。
+						// 语言选择复用既有 i18n：t() 在中文下取键名本身（sentinel），在英文下取字典值。
+						const isEn = t("safetyUnknown") !== "safetyUnknown";
+						const pick = (pair) => (pair === null || pair === undefined ? null : (isEn ? (pair.en || pair.zh) : (pair.zh || pair.en)));
+						const auto = data.autoDisable && data.autoDisable.notice ? pick(data.autoDisable.notice) : null;
+						if (typeof auto === "string" && auto !== "") setNote({ text: auto });
+						else if (typeof data.autoPreflight?.note?.zh === "string" && data.autoPreflight.changed === true && data.autoPreflight.scheduled !== true) setNote({ text: pick(data.autoPreflight.note) });
+						else if (data.modeAuto) setNote({ text: pick(data.modeAuto.note) });
+					}
+				} catch {}
 			};
 			// 依赖锁体检：**只读**接口，不打任何写操作
 			const lockCheck = async () => {

package/lib/server/domain/auto-disable.js

@@ -0,0 +1,226 @@
+// L1 · domain —— auto-disable.js（把「自动禁用」的**触发源**从"我们升级"扩到"指纹变化 / 启动失败记录"；
+// 0.5.32 加法 D5，用户 2026-09-29 明确要求「我们本来就有自动禁用，要的是扩展」）
+//
+// 现状（0.5.31）自动禁用只有两个触发点，**都绑在我们自己的动作上**：
+//   ① `healPatchSafety`（判"模块确证缺失"，随 GET /state 每 ≤2min 跑一次）
+//   ② 我们升级流程里的 `preflightDisableIncompatible`
+// 于是**别人**改框架（官方桌面端更新器 / 手动 pnpm / npx 缓存变化）时，两者都不触发 ——
+// 用户看到的是一堆报错，而不是"肇事行已被关掉、服务能起来"。
+//
+// 本模块把触发源接到 D1 的预检清单与启动失败记录上，**但必须带上 0.5.30 已立的安全栏**：
+//   ① **只禁有证据的行**：`package-unresolvable`（解析器在所有基准上都解析不到）/ `file-target-missing`
+//      （`file://` 目标确实不存在）/ 启动失败日志**点名**的行。**解析不确定**（没有基准、解析器抛错、
+//      子路径解析不到）一律**只报告不写盘**。
+//   ② **`@deepseek-ai/*`（框架自带）永不自动禁用**、**受保护/核心行永不自动禁用**
+//      （`framework.js:483/493` 那两类判据：`CORE_PATCH_ROW_IDS` + `isProtected`）。
+//   ③ **禁前先写 last-known-good 快照**：任何一次自动禁用都能一键 / 一条命令回滚。
+//   ④ **幂等零写盘** + **每次留一条可读记录**（时间 / 行 id / 证据 / 恢复命令）。
+//   ⑤ **开关**：`compat-gate.json#autoDisableOnEvidence`（默认启用；关闭 = 退回"只报告 + 等你点"）。
+//
+// 分层：L1 domain —— 无 ctx；落盘复用 `domain/safe-boot.js` 的同一套原语（备份 + 原子写 + 读回核实）。
+
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { CORE_PATCH_ROW_IDS } from './patch.js'
+import { parsePatchRows } from './patch-composition-audit.js'
+import { disableSuspects, ensureSnapshotForCurrentState } from './safe-boot.js'
+import { dshHome } from '../infra/paths.js'
+
+/** 自动禁用的可读记录（追加式 JSONL：每次自动禁用一条，永不覆盖历史）。 */
+const autoDisableLog = (home = undefined) => join(home ?? dshHome(), 'plugin-console', 'auto-disable.log')
+
+/** 有证据的行必须落在这些 `code` 上（其余一律只报告）。 */
+const EVIDENCE_CODES = {
+  'package-unresolvable': '包在所有解析基准上都解析不到（确证缺失）',
+  'file-target-missing': 'file:// 目标文件确实不存在（确证缺失）',
+  'boot-log': '启动失败日志点名了这一行',
+  'boot-quarantine': '升级脚本留下的启动失败隔离记录点名了这一行',
+}
+
+/** 明确**不算**证据的形态（写在这里是为了让"为什么没禁"可查，而不是静默放过）。 */
+const NON_EVIDENCE_CODES = {
+  'subpath-unresolvable': '子路径解析不到（父包还在，可能只是导出变了）',
+  'row-without-name': '行既没有 name 也没有 config（形态可疑但无证据）',
+  'legacy-source-kind': '源码里的旧形状（可以自动改，不需要禁用）',
+  'legacy-source-kind-unresolved': '旧形状无法安全改写（需要人工过一眼）',
+  'schemastery-volatile': '依赖副本陈旧（对齐依赖即可，不需要禁用）',
+}
+
+/** 框架自带包（`@deepseek-ai/*`）—— 永不由本模块自动禁用。 */
+const isFrameworkOwnedName = (name) => {
+  const text = String(name ?? '')
+  if (text.startsWith('@deepseek-ai/')) return true
+  // 裸包名形态（补丁行写 `dsh-xxx` 而不是全名）也要认：框架内置包在补丁里两种写法都出现过
+  return /^dsh-[a-z0-9-]+$/iu.test(text)
+}
+
+/**
+ * 从「D1 预检清单 + 启动失败记录」里挑出**有确证证据、且过得了安全栏**的行（纯函数，不写盘）。
+ * @returns {{ disable: Array<{rowId,moduleName,evidence,detail}>, skipped: Array<{rowId,reason,evidence?}>, hasEvidence: boolean }}
+ */
+function planEvidenceDisable({
+  affected = [], bootRows = [], patchText = '', coreRowIds = CORE_PATCH_ROW_IDS,
+  isProtected = null, uncertainty = null, maxRows = 20,
+} = {}) {
+  const rows = parsePatchRows(patchText)
+  const byId = new Map(rows.map((r) => [r.id, r]))
+  const disable = []
+  const skipped = []
+  const pushSkip = (rowId, reason, evidence = null) => {
+    if (typeof rowId !== 'string' || rowId === '') return
+    if (disable.some((d) => d.rowId === rowId)) return
+    if (skipped.some((s) => s.rowId === rowId)) return
+    skipped.push({ rowId, reason, evidence })
+  }
+
+  // 解析面**不确定**（一个基准都没有 / 解析器建不起来）→ 整批只报告，绝不写盘
+  if (typeof uncertainty === 'string' && uncertainty !== '') {
+    for (const item of affected) if (item?.rowId) pushSkip(item.rowId, `resolution-uncertain: ${uncertainty}`, item.code ?? null)
+    return { disable, skipped, hasEvidence: false }
+  }
+
+  // ① D1 预检清单里的**确证**证据
+  for (const item of (Array.isArray(affected) ? affected : [])) {
+    const rowId = typeof item?.rowId === 'string' ? item.rowId : null
+    if (rowId === null) continue
+    const code = item.code ?? null
+    if (EVIDENCE_CODES[code] === undefined) { pushSkip(rowId, `not-evidence: ${NON_EVIDENCE_CODES[code] ?? code ?? 'unknown'}`, code); continue }
+    if (coreRowIds.has(rowId)) { pushSkip(rowId, 'core-row', code); continue }
+    if (rowId === 'plugin-console') { pushSkip(rowId, 'self', code); continue }
+    const row = byId.get(rowId) ?? null
+    if (row === null) { pushSkip(rowId, 'not-in-patch', code); continue }
+    if (row.disabled === true) { pushSkip(rowId, 'already-disabled', code); continue }
+    const moduleName = typeof item.moduleName === 'string' && item.moduleName !== '' ? item.moduleName : (row.name ?? null)
+    if (moduleName === null) { pushSkip(rowId, 'module-unknown', code); continue }
+    if (isFrameworkOwnedName(moduleName)) { pushSkip(rowId, 'framework-owned', code); continue }
+    if (typeof isProtected === 'function' && isProtected(moduleName) === true) { pushSkip(rowId, 'protected-module', code); continue }
+    if (disable.length >= maxRows) { pushSkip(rowId, 'row-limit', code); continue }
+    disable.push({ rowId, moduleName, evidence: code, detail: EVIDENCE_CODES[code] })
+  }
+
+  // ② 启动失败记录点名的行（计划里的 `rows`：分析器已剔除核心行/不可开关行）
+  for (const rowId of (Array.isArray(bootRows) ? bootRows : [])) {
+    if (typeof rowId !== 'string' || rowId === '') continue
+    if (coreRowIds.has(rowId) || rowId === 'plugin-console') { pushSkip(rowId, 'core-row', 'boot-log'); continue }
+    const row = byId.get(rowId) ?? null
+    if (row === null) { pushSkip(rowId, 'not-in-patch', 'boot-log'); continue }
+    if (row.disabled === true) { pushSkip(rowId, 'already-disabled', 'boot-log'); continue }
+    const moduleName = row.name ?? null
+    if (moduleName !== null && isFrameworkOwnedName(moduleName)) { pushSkip(rowId, 'framework-owned', 'boot-log'); continue }
+    if (moduleName !== null && typeof isProtected === 'function' && isProtected(moduleName) === true) { pushSkip(rowId, 'protected-module', 'boot-log'); continue }
+    if (disable.length >= maxRows) { pushSkip(rowId, 'row-limit', 'boot-log'); continue }
+    disable.push({ rowId, moduleName, evidence: 'boot-log', detail: EVIDENCE_CODES['boot-log'] })
+  }
+  return { disable, skipped, hasEvidence: disable.length > 0 }
+}
+
+/** 追加一条可读记录（JSONL；失败不抛 —— 它不能把自动禁用本身带崩）。 */
+function appendDisableLog(entry, { home = undefined, appendFile = (p, d) => appendFileSync(p, d, 'utf8'), mkdir = (d) => mkdirSync(d, { recursive: true }) } = {}) {
+  try {
+    const file = autoDisableLog(home)
+    mkdir(dirname(file))
+    appendFile(file, `${JSON.stringify(entry)}\n`)
+    return { ok: true, file }
+  } catch (error) {
+    return { ok: false, error: error instanceof Error ? error.message : String(error) }
+  }
+}
+
+/** 读记录（新→旧；损坏行跳过）。 */
+function readDisableLog({ home = undefined, limit = 50, readFile = (p) => readFileSync(p, 'utf8') } = {}) {
+  try {
+    return readFile(autoDisableLog(home))
+      .split(/\r?\n/u)
+      .filter((l) => l.trim() !== '')
+      .map((l) => { try { return JSON.parse(l) } catch { return null } })
+      .filter((x) => x !== null)
+      .slice(-limit)
+      .reverse()
+  } catch { return [] }
+}
+
+/**
+ * 有证据就自动禁用（D5 的落盘入口）。**顺序是关键**：
+ *   计划（纯判定）→ **禁前快照**（当前状态有可回滚材料）→ 复用 `disableSuspects`
+ *   （改前备份 + 严格 YAML 闸门 + 原子写 + 读回核实）→ 追加可读记录。
+ * 任一步失败都如实返回，**绝不部分静默**；`enabled !== true` 时只报告不写盘（退回"等你点"）。
+ */
+function applyEvidenceDisable({
+  patchPath, patchText = null, affected = [], bootRows = [], enabled = true,
+  fingerprint = null, frameworkVersion = null, reasons = [], home = undefined,
+  isProtected = null, uncertainty = null, coreRowIds = CORE_PATCH_ROW_IDS,
+  readFile = (p) => readFileSync(p, 'utf8'), exists = existsSync, ...rest
+} = {}) {
+  try {
+    if (typeof patchPath !== 'string' || patchPath === '') return { ok: false, code: 'no-patch-path', disabled: [], skipped: [] }
+    // 补丁不存在 → 如实拒绝（**绝不创建**：凭一份"没读到的补丁"去写 disabled 块等于凭空造文件）
+    if (typeof patchText !== 'string' && exists(patchPath) !== true) {
+      return { ok: false, code: 'patch-missing', disabled: [], skipped: [], error: `补丁文件不存在：${patchPath}` }
+    }
+    const text = typeof patchText === 'string' ? patchText : readFile(patchPath)
+    const plan = planEvidenceDisable({ affected, bootRows, patchText: text, coreRowIds, isProtected, uncertainty })
+    if (plan.disable.length === 0) {
+      return { ok: true, code: 'no-evidence', disabled: [], skipped: plan.skipped, snapshot: null, note: '没有确证证据可禁用（只报告不写盘）' }
+    }
+    if (enabled !== true) {
+      return {
+        ok: true, code: 'switch-off', disabled: [], skipped: plan.skipped, snapshot: null,
+        candidates: plan.disable.map((d) => d.rowId),
+        note: '自动禁用开关已关闭：只报告，等你手动点「只禁可疑行」（或离线脚本 --disable-suspects）',
+      }
+    }
+    // ③ 禁前先写 last-known-good 快照：没有可回滚材料就不动手
+    const snap = ensureSnapshotForCurrentState({
+      patchPath, patchText: text, fingerprint, frameworkVersion, reasons, home,
+      note: `自动禁用前的安全快照（点名 ${plan.disable.length} 行：${plan.disable.map((d) => d.rowId).join('、')}）`,
+      readFile,
+    })
+    if (snap.ok !== true) {
+      return { ok: false, code: 'snapshot-failed', disabled: [], skipped: plan.skipped, snapshot: snap, error: `禁前快照失败，已放弃自动禁用：${snap.error ?? '未知原因'}` }
+    }
+    const result = disableSuspects({
+      patchPath, rowIds: plan.disable.map((d) => d.rowId), home, coreRowIds,
+      moduleNameOf: (rowId) => plan.disable.find((d) => d.rowId === rowId)?.moduleName ?? null,
+      isProtected, isFrameworkOwned: null, readFile,
+    })
+    const entry = {
+      at: Date.now(),
+      kind: 'auto-disable',
+      source: 'evidence',
+      added: result.ok === true ? (result.added ?? []) : [],
+      skipped: result.skipped ?? plan.skipped,
+      evidence: plan.disable.map((d) => ({ rowId: d.rowId, moduleName: d.moduleName, code: d.evidence, detail: d.detail })),
+      snapshotId: snap.id ?? null,
+      backupPath: result.backupPath ?? null,
+      patchPath,
+      frameworkVersion: frameworkVersion ?? fingerprint?.frameworkVersion ?? null,
+      fingerprint: fingerprint ?? null,
+      restoreCommand: 'node scripts/safe-boot.mjs --restore-last-good',
+      result: { ok: result.ok === true, code: result.code ?? null, error: result.error ?? null },
+    }
+    const logged = appendDisableLog(entry, { home })
+    if (result.ok !== true) {
+      return { ok: false, code: result.code ?? 'disable-failed', disabled: [], skipped: result.skipped ?? plan.skipped, snapshot: snap, error: result.error ?? '自动禁用失败', log: logged }
+    }
+    return {
+      ok: true, code: result.changed === true ? 'auto-disabled' : 'noop', disabled: result.added ?? [], skipped: result.skipped ?? plan.skipped,
+      snapshot: snap, backupPath: result.backupPath ?? null, log: logged, prefixSame: result.prefixSame === true,
+      note: result.changed === true
+        ? `已自动禁用 ${result.added.length} 行（有确证证据；禁前快照 ${snap.id}，可一条命令回滚）`
+        : '点名行都已处于禁用状态（幂等零写盘）',
+    }
+  } catch (error) {
+    return { ok: false, code: 'auto-disable-failed', disabled: [], skipped: [], error: `自动禁用失败：${error instanceof Error ? error.message : String(error)}` }
+  }
+}
+
+export {
+  EVIDENCE_CODES,
+  NON_EVIDENCE_CODES,
+  appendDisableLog,
+  applyEvidenceDisable,
+  autoDisableLog,
+  isFrameworkOwnedName,
+  planEvidenceDisable,
+  readDisableLog,
+}

package/lib/server/domain/auto-preflight-run.js

@@ -0,0 +1,184 @@
+// L1 · domain —— auto-preflight-run.js（**只读**预检运行器：指纹变化后现场跑一次扫描；0.5.32 加法 D1）
+//
+// 与 `routes/framework-preflight.js` 的分工：
+//   · 那条路由是**用户手动点**的完整预检（目标版本可指定、会打 registry 抓契约、可能写补丁）；
+//   · 本模块是**指纹变化自动触发**的**只读**预检 —— 不下载、不安装、不改补丁、不碰 loader，
+//     只用「内置规则库 + 本地文件 + 补丁体检 + 启动失败日志分析」产出三样东西：
+//       ① 兼容清单（受影响行）  ② 隔离计划（建议禁用哪些行、为什么）  ③ 变更摘要（版本 from→to / 包增减 / 指纹 reasons）
+// 网络：自动模式下**一律跳过外部 registry**（自动触发不该偷偷联网）—— 结论完全由本地判据得出，
+//      这也是「离线脚本能在服务没跑时用同一套判据」的前提。
+//
+// 分层：L1 domain —— 不出现 ctx（loader 条目 / 扫描根由调用方注入）；IO 与纯判据分离，离线可断言。
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { affectedRows, planSuspectRows, summarizeDelta } from './auto-preflight.js'
+import { loadContractRules, summarizeContractRules } from './contract-rules.js'
+import { collectProducerTargets, scanProducerFiles } from './format-scan.js'
+import { CORE_PATCH_ROW_IDS } from './patch.js'
+import { classifyPatchRows, parsePatchRows } from './patch-composition-audit.js'
+import { collectPresetAudit } from './preset-audit.js'
+import { planQuarantine, readQuarantineRecord } from './quarantine.js'
+import { makePackageResolver } from '../infra/package-resolve.js'
+
+/** 扫不到规则库时的兜底规则（与 routes/framework-preflight.js 的兜底一字不差）。 */
+const DEFAULT_RULES = { producerKindRequired: false, forbiddenKinds: ['plugin'], pluginPrefix: 'plugin:', renames: {} }
+
+/** 自动模式下的固定说明（如实告诉用户"这份结论没打网络"）。 */
+const OFFLINE_NOTE = {
+  zh: '自动预检是只读且不联网的：结论来自内置规则库与本地文件；目标版本的 registry 契约未核对（可手动跑完整预检）',
+  en: 'Auto-preflight is read-only and offline: conclusions come from the built-in rule pack and local files; the target-version registry contract was not checked (run the full preflight manually)',
+}
+
+/**
+ * `<pnpmRoot>/.pnpm` 下的 `@deepseek-ai+*` 实体名（去版本后缀）—— 用于变更摘要的「新增/消失的包」。
+ * ★ 只用于**摘要展示**，绝不用于「包在不在」的判定：pnpm 会截断超长目录名（见 infra/package-resolve.js 头注释），
+ *   所以解析性判定一律走 Node 解析器（本文件里的 `resolve`）。
+ */
+function packageNamesOf(pnpmRoot, readDir = (dir) => readdirSync(dir)) {
+  if (typeof pnpmRoot !== 'string' || pnpmRoot === '') return []
+  let names = []
+  try { names = readDir(join(pnpmRoot, '.pnpm')) } catch { return [] }
+  const out = new Set()
+  for (const name of names) {
+    if (typeof name !== 'string' || !name.startsWith('@deepseek-ai+')) continue
+    const at = name.indexOf('@', 1)
+    out.add(at === -1 ? name : name.slice(0, at))
+  }
+  return [...out].sort()
+}
+
+/** `file://` URL → 路径（离线安全；解析失败抛给调用方，由调用方转成 false）。 */
+function fileUrlToPath(url) {
+  return fileURLToPath(String(url ?? ''))
+}
+
+/**
+ * 跑一次只读预检（**同步**：全部是本地文件扫描，调用方用 withTimeout 包裹即可）。
+ * @param {object} input
+ * @param {string|null} input.profileDir   profile 目录（补丁所在目录）
+ * @param {string|null} input.patchPath    cordis.patch.yml 绝对路径
+ * @param {object|null} input.current      当前指纹（frameworkVersion / pnpmEntities / pnpmRoot）
+ * @param {object|null} input.previous     基线指纹（可能为 null）
+ * @param {string[]} input.presetRoots     预设扫描根（通常 `<dshHome>/.agent-presets`）
+ * @param {Array<{root:string,kind:string,moduleName?:string|null}>} input.roots 生产方扫描根
+ * @param {string[]} input.reasons         指纹变更原因（直接来自 compareFingerprint）
+ * @param {string[]} input.previousPackages 上一次记录的框架包名（没有则空数组 → 摘要如实标 rationaleAvailable=false）
+ * @param {boolean} input.networkAllowed   是否允许打网络（自动预检一律 false）
+ * @param {Array} [input.targets]          直接给扫描目标（测试注入；缺省由 roots 推导）
+ * @param {boolean} [input.includeBootLog] 是否把 profile 下的 `.dsh-boot.log` 纳入启动失败分析（缺省 true）
+ */
+function runAutoPreflightScan(input = {}) {
+  const {
+    profileDir = null, patchPath = null, current = null, previous = null,
+    presetRoots = [], roots = [], reasons = [], previousPackages = [],
+    networkAllowed = false, targets = null, includeBootLog = true,
+    readFile = (p) => readFileSync(p, 'utf8'), existsFile = existsSync, readDir = (dir) => readdirSync(dir),
+  } = input
+
+  // ① 补丁体检（只读）：行 → 包可解析性（blocker / warning / 改名建议）
+  const patchText = typeof patchPath === 'string' && existsFile(patchPath) ? readFile(patchPath) : ''
+  const rows = parsePatchRows(patchText)
+  const bases = [profileDir, current?.pnpmRoot]
+    .map((b) => (typeof b === 'string' && b !== '' ? b : null))
+    .filter(Boolean)
+  const resolve = bases.length > 0 ? makePackageResolver(bases) : null
+  const patchReport = resolve === null
+    ? { blockers: [], warnings: [], resolvable: [], patchOnly: [], skipped: '没有可用的解析基准（profile 目录与框架运行时根都拿不到）' }
+    : classifyPatchRows(rows, {
+      resolve: (name) => resolve(name),
+      existsFile: (url) => { try { return existsFile(fileUrlToPath(url)) } catch { return false } },
+      candidates: [],
+    })
+
+  // ② 生产方源码扫描（会话格式契约）：规则来自**数据化规则库**（对我们没发过升级包的框架版本同样有效）
+  const rulePack = (() => { try { return loadContractRules() } catch { return null } })()
+  const hasRules = Array.isArray(rulePack?.rules) && rulePack.rules.length > 0
+  const scanTargets = Array.isArray(targets) ? targets : collectProducerTargets(roots)
+  const scan = scanProducerFiles({ targets: scanTargets, rules: hasRules ? rulePack.rules : DEFAULT_RULES, targetVersion: current?.frameworkVersion ?? null })
+  const scanSafe = { ...scan, files: (scan.files ?? []).slice(0, 40), findings: (scan.findings ?? []).slice(0, 40) }
+
+  // ③ 预设声明行体检（只读；失败如实记 error，不假装"零发现"）
+  let presetAudit = null
+  try {
+    presetAudit = collectPresetAudit({ presetsRoot: presetRoots[0] ?? null, patchPath })
+  } catch (error) {
+    presetAudit = { ok: false, error: error instanceof Error ? error.message : String(error), blockers: 0, stale: [], missing: [], orphan: [], targetMissing: [] }
+  }
+
+  // ④ 受影响行 + 隔离计划（只**建议**，绝不写盘）
+  const affected = affectedRows({ patchReport, scan, rows })
+  const plan = planSuspectRows(affected, { coreRowIds: CORE_PATCH_ROW_IDS, toggleableById: new Map() })
+
+  // ⑤ 我们的升级脚本若曾留下隔离记录，把它并进计划（旧记录仍有效）。
+  //    别人升级时没有这份记录 —— 这正是 0.5.32 补的缺口：兜底输入换成「指纹变化自动预检」的结论。
+  let bootQuarantine = null
+  try { bootQuarantine = readQuarantineRecord() } catch { bootQuarantine = null }
+  if (bootQuarantine !== null && Array.isArray(bootQuarantine.rows)) {
+    for (const rowId of bootQuarantine.rows) {
+      if (typeof rowId !== 'string' || rowId === '') continue
+      if (plan.suspects.some((s) => s.rowId === rowId)) continue
+      plan.suspects.push({ rowId, moduleName: null, reason: 'boot-quarantine', detail: '升级脚本留下的启动失败隔离记录', line: null })
+    }
+  }
+
+  // ⑥ 启动失败日志（若存在）：把「谁把服务搞挂了」也变成点名行
+  let bootPlan = null
+  if (includeBootLog === true) {
+    try {
+      const logPath = join(dirname(String(patchPath ?? join(profileDir ?? '.', 'x'))), '.dsh-boot.log')
+      if (existsFile(logPath)) {
+        bootPlan = planQuarantine({ logText: readFile(logPath), candidates: rows.map((r) => ({ rowId: r.id, moduleName: r.name, toggleable: true })) })
+        for (const rowId of bootPlan.rows ?? []) {
+          if (!plan.suspects.some((s) => s.rowId === rowId)) plan.suspects.push({ rowId, moduleName: null, reason: 'boot-log', detail: '启动失败日志点名', line: null })
+        }
+      }
+    } catch { bootPlan = null }
+  }
+
+  const delta = summarizeDelta({
+    current,
+    previous,
+    currentPackages: packageNamesOf(current?.pnpmRoot ?? null, readDir),
+    previousPackages,
+  })
+  const blockers = affected.filter((a) => a.severity === 'blocker').length
+  return {
+    ok: true,
+    at: Date.now(),
+    targetVersion: current?.frameworkVersion ?? null,
+    previousVersion: previous?.frameworkVersion ?? null,
+    reasons: Array.isArray(reasons) ? reasons : [],
+    summary: {
+      frameworkVersionFrom: previous?.frameworkVersion ?? null,
+      frameworkVersionTo: current?.frameworkVersion ?? null,
+      versionChanged: (previous?.frameworkVersion ?? null) !== (current?.frameworkVersion ?? null),
+      blockers,
+      affectedCount: affected.length,
+      suspectCount: plan.suspects.length,
+      packagesAdded: delta.packagesAdded,
+      packagesRemoved: delta.packagesRemoved,
+      note: blockers > 0 ? `预检发现 ${blockers} 行受影响` : '预检未发现受影响行',
+    },
+    affected,
+    suspects: plan.suspects,
+    skipped: plan.skipped,
+    delta,
+    // D5（自动禁用的扩展触发源）要用的两样东西：确证证据（affected 的行/码）与启动失败点名行。
+    // 这里是**只读**产出，是否落盘由 routes 层按开关决定（domain 不做"要不要动用户文件"的判断）。
+    evidence: {
+      uncertainty: resolve === null ? '没有可用的解析基准（profile 目录与框架运行时根都拿不到）' : (typeof patchReport.skipped === 'string' ? patchReport.skipped : null),
+      rows: affected.filter((a) => a.rowId !== null).map((a) => ({ rowId: a.rowId, moduleName: a.moduleName ?? null, code: a.code ?? null, severity: a.severity })),
+      bootRows: (bootPlan?.rows ?? []),
+    },
+    patch: { patchPath, rows: rows.length, blockers: (patchReport.blockers ?? []).length, warnings: (patchReport.warnings ?? []).length, skipped: patchReport.skipped ?? null },
+    scan: scanSafe,
+    rules: hasRules ? summarizeContractRules(rulePack) : { source: 'unavailable', version: null, updatedAt: null, total: 0, blockers: 0, autoDetected: 0, ids: [], error: '规则库不可用：本次扫描只用内置兜底规则（结论偏保守）' },
+    presetAudit,
+    bootPlan,
+    network: { allowed: networkAllowed === true, note: networkAllowed === true ? null : OFFLINE_NOTE },
+  }
+}
+
+export { DEFAULT_RULES, OFFLINE_NOTE, fileUrlToPath, packageNamesOf, runAutoPreflightScan }