@noob-stupid/dsh-plugin-console 0.3.33 → 0.3.47

package/lib/index.js

@@ -13,10 +13,10 @@
  * 移除该块即恢复；HMR 监视器会自动重组合，无需重启。
  */
 import { readFile, writeFile } from 'node:fs/promises'
-import { readFileSync, writeFileSync, existsSync, statSync, rmSync, readdirSync, mkdirSync, copyFileSync } from 'node:fs'
+import { readFileSync, writeFileSync, existsSync, statSync, rmSync, readdirSync, mkdirSync, copyFileSync, realpathSync } from 'node:fs'
 import { execFile, spawn } from 'node:child_process'
 import { promisify } from 'node:util'
-import { dirname, join, basename } from 'node:path'
+import { dirname, join, basename, sep } from 'node:path'
 import { tmpdir, homedir } from 'node:os'
 import { fileURLToPath } from 'node:url'
 import { createRequire } from 'node:module'
@@ -341,6 +341,26 @@ function semverRangeMatchLoose(versionText, rangeText) {
  * 静态声明检查判 pass 是假通过；真实兼容性只有模块 import 时见分晓，而 loader 单行失败
  * = 整个服务启动崩溃）。返回命中的符号列表，空数组 = 干净。
  */
+const REMOVED_SETTINGS_SYMBOLS = ['settingsNamespace', 'installSettingsSection']
+
+/** 源码是否**引用**了已删除符号——而不是「恰好包含同名前缀的其它标识符」或「自己定义的同名局部函数」。
+ *  v0.3.35 修复（真机演练抓到的误伤）：原先用 `text.includes('settingsNamespace')` 子串匹配，
+ *  而框架自带的 @deepseek-ai/dsh-api-settings-controller 里有个 `settingsNamespaceRequestSchema`，
+ *  于是框架自己的 settings 控制器被判「引用已删除 API」→ 升级预扫会把它自动禁用（砍掉框架功能）。
+ *  现在要求标识符边界，且排除「本地 const/let/var/function/class 定义且同行没有 dsh-settings 引用」。 */
+function referencesRemovedSymbol(text, sym) {
+  const re = new RegExp(`(?<![A-Za-z0-9_$])${sym}(?![A-Za-z0-9_$])`, 'u')
+  for (const line of text.split(/\r?\n/u)) {
+    const m = re.exec(line)
+    if (m === null) continue
+    const before = line.slice(0, m.index)
+    const localDefinition = /(?:^|[^\w$])(?:const|let|var|function|class|async\s+function)\s*$/u.test(before)
+    if (localDefinition && !/dsh-settings/u.test(line)) continue
+    return true
+  }
+  return false
+}
+
 function scanSettingsApiUsage(pkgDir) {
   const found = []
   const seen = new Set()
@@ -361,8 +381,9 @@ function scanSettingsApiUsage(pkgDir) {
       if (seen.size > 120) return
       try {
         const text = readFileSync(full, 'utf8').slice(0, 400000)
-        for (const sym of ['settingsNamespace', 'installSettingsSection']) {
-          if (text.includes(sym) && !found.includes(sym)) found.push(sym)
+        for (const sym of REMOVED_SETTINGS_SYMBOLS) {
+          if (found.includes(sym)) continue
+          if (referencesRemovedSymbol(text, sym)) found.push(sym)
         }
       } catch {}
     }
@@ -371,6 +392,18 @@ function scanSettingsApiUsage(pkgDir) {
   return found
 }
 
+/** 包是否由框架自带（解析到 profile 目录之外，如 npx/pnpm 缓存里的 @deepseek-ai/*）。
+ *  v0.3.35：这类行随框架一起发布，禁用**不是**正确处置（正确处置是回滚框架），
+ *  而且一旦判定有误就会把框架功能砍掉——所以升级预扫永不自动禁用它们。 */
+function isFrameworkOwnedPackage(pkgDir, profileDir) {
+  if (typeof pkgDir !== 'string' || pkgDir === '' || typeof profileDir !== 'string' || profileDir === '') return false
+  const real = (p) => { try { return realpathSync(p) } catch { return p } }
+  const dir = real(pkgDir).toLowerCase()
+  let base = real(profileDir).toLowerCase()
+  if (!base.endsWith(sep)) base += sep
+  return !dir.startsWith(base)
+}
+
 /**
  * 插件-框架兼容校验（框架升级适配门）：
  * 1) 显式兼容声明（dsh.engines.framework / dsh.compat.framework / engines.dsh）：以声明为准；
@@ -1073,6 +1106,208 @@ function writeCompatPending(payload) {
   } catch {}
 }
 
+/** 兼容门总开关（用户定案 2026-09-11）：用户可关掉自动行为，回到纯手动。
+ *  autoDisable —— 升级前是否自动禁用判定不适配的行（关掉 = 只提示不动开关）
+ *  autoDetect  —— 打开控制台时是否自动检测「已适配」（关掉 = 不显示可解锁提示） */
+const COMPAT_GATE_FILE = () => join(dshHome(), 'plugin-console', 'compat-gate.json')
+const COMPAT_GATE_DEFAULTS = { autoDisable: true, autoDetect: true }
+function readCompatGate() {
+  try {
+    const raw = JSON.parse(readFileSync(COMPAT_GATE_FILE(), 'utf8'))
+    return {
+      autoDisable: raw?.autoDisable !== false,
+      autoDetect: raw?.autoDetect !== false,
+    }
+  } catch { return { ...COMPAT_GATE_DEFAULTS } }
+}
+function writeCompatGate(patch) {
+  const next = { ...readCompatGate(), ...patch }
+  try {
+    mkdirSync(dirname(COMPAT_GATE_FILE()), { recursive: true })
+    writeFileSync(COMPAT_GATE_FILE(), JSON.stringify(next, null, 2), 'utf8')
+  } catch {}
+  return next
+}
+
+/** 待适配行的「现在是否已适配」检测（只提示，不自动解锁——用户定案：我点才开）。
+ * 返回 Map<rowId, {version, check, note}>：仅当版本已变化且源码扫描不再 fail 时才算可解锁。 */
+function detectAdoptablePending(ctx) {
+  const out = new Map()
+  const pending = readCompatPending()
+  if (pending === null) return out
+  const fwVer = typeof pending.frameworkVersion === 'string' ? pending.frameworkVersion : null
+  if (fwVer === null) return out
+  let profileDir = null
+  try { profileDir = dirname(findPatchPath(ctx)) } catch { return out }
+  for (const p of (pending.pending ?? []).filter((x) => (x.status ?? 'pending') === 'pending')) {
+    try {
+      const pkgPath = resolvePackageJson(p.moduleName, profileDir)
+      if (pkgPath === null) continue
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'))
+      const version = typeof pkg.version === 'string' ? pkg.version : null
+      const changed = version !== null && version !== p.version
+      const check = checkPluginFrameworkCompat(pkg, fwVer, dirname(pkgPath))
+      if (changed && check.decision !== 'fail') {
+        out.set(p.rowId, { version, check: check.decision, note: check.reason ?? null })
+      }
+    } catch {}
+  }
+  return out
+}
+
+/** 把升级脚本留下的「启动失败隔离」记录并入适配门清单（只处理一次：处理后改名 .applied）。
+ *  作用：服务被隔离救回来之后，用户能在面板上看到「谁被自动关了、为什么」，并可逐个解锁。 */
+/** 读取升级脚本写下的隔离记录（含 BOM 兼容）。
+ *  ★ 2026-09-11 事故根因：升级脚本用 PowerShell `Set-Content -Encoding UTF8` 写这个文件，
+ *  PS5.1 会**带 UTF-8 BOM**；而合并逻辑先"复制 + 删除"再判断 JSON.parse 结果 → BOM 让 parse
+ *  必失败 → 记录被销毁、却从未并进适配门清单 → 界面上那 20 行只剩一个**没有解释的【停用】**。
+ *  这里统一剥 BOM 再解析；解析失败返回 null（调用方会保留文件、留错误日志，绝不销毁证据）。 */
+function readQuarantineRecord() {
+  const file = join(dshHome(), 'plugin-console', 'fw-quarantine.json')
+  if (!existsSync(file)) return null
+  let raw = ''
+  try { raw = readFileSync(file, 'utf8') } catch { return null }
+  if (raw.charCodeAt(0) === 0xFEFF) raw = raw.slice(1)
+  try {
+    const rec = JSON.parse(raw)
+    return rec !== null && typeof rec === 'object' ? rec : null
+  } catch { return null }
+}
+
+/** 合并隔离记录失败时留痕（v0.3.44）：静默 catch 让 2026-09-11 那次 20 行隔离记录凭空消失，
+ *  界面只剩一个没有解释的【停用】，而且事后完全查不到原因。错误落到 fw-merge-error.log。 */
+function logQuarantineMergeError(error) {
+  try {
+    const file = join(dshHome(), 'plugin-console', 'fw-merge-error.log')
+    mkdirSync(dirname(file), { recursive: true })
+    writeFileSync(file, `${new Date().toISOString()} ${error?.stack ?? String(error)}\n`, { flag: 'a' })
+  } catch {}
+}
+
+/** 把升级脚本留下的「启动失败隔离」记录并入适配门清单。
+ *  顺序很关键（v0.3.44）：**先写清单并校验成功，再归档移除记录**。反过来的话，
+ *  任何解析/写入意外都会"记录没了、清单也没进"，用户只看到一个没有理由的【停用】。
+ *  导出仅供测试直接驱动（避免测试为了跑它而 apply 整个插件）。 */
+export function mergeQuarantineRecord(ctx) {
+  const file = join(dshHome(), 'plugin-console', 'fw-quarantine.json')
+  if (!existsSync(file)) return null
+  const rec = readQuarantineRecord()
+  if (rec === null) {
+    logQuarantineMergeError(new Error('隔离记录无法解析（已按 BOM 兼容处理仍失败），保留文件待下次启动重试'))
+    return null
+  }
+  const rows = (Array.isArray(rec.rows) ? rec.rows : []).filter((rowId) => typeof rowId === 'string' && rowId !== '')
+  const pending = readCompatPending() ?? { frameworkVersion: null, upgradeFrom: null, pending: [] }
+  if (!Array.isArray(pending.pending)) pending.pending = []
+  const lines = Array.isArray(rec.lines) ? rec.lines : []
+  // 隔离记录里只有 rowId（脚本写的），但清单里其它地方都按 moduleName 认身份：
+  // 「全家桶一键启用已适配」按 moduleName 前缀匹配、`检测到已适配 vX` 也要 moduleName 才能算。
+  // 所以这里按当前 loader 反查补上（v0.3.45：补不上就会永远匹配不到 —— 用户实测「点了说没有待适配行」）。
+  const info = ctx === undefined || ctx === null ? new Map() : rowIdModuleMap(ctx)
+  for (const rowId of rows) {
+    const meta = info.get(rowId) ?? null
+    const record = {
+      rowId,
+      moduleName: meta?.moduleName ?? null,
+      version: meta?.version ?? null,
+      status: 'pending',
+      check: 'unknown',
+      checkNote: `启动失败隔离（${rec.mode ?? 'targeted'}）：${lines[0] ?? '启动日志命中，服务曾被它拖垮'}`,
+      forcedAt: Date.now(),
+      source: 'boot-quarantine',
+    }
+    const at = pending.pending.findIndex((p) => p.rowId === rowId)
+    if (at >= 0) pending.pending[at] = { ...pending.pending[at], ...record }
+    else pending.pending.push(record)
+    // 该行现在就是启用的（比如用户在隔离之后已经手动启用过）→ 直接记成已适配，别留一个假 pending
+    if (meta?.enabled === true) markPendingAdopted(pending, rowId, 'row-enabled', meta)
+  }
+  // 预设隔离单独记录（它不是插件行，没有「启用」语义；解锁 = 把 .broken 文件改回来）
+  if (Array.isArray(rec.presets) && rec.presets.length > 0) {
+    pending.presetsQuarantined = rec.presets.map((name) => ({ name, at: rec.at ?? null, note: 'agent.cordis.yml 已改名 .broken（启动失败隔离），确认修好后改回文件名即可恢复' }))
+  }
+  pending.quarantineAt = rec.at ?? null
+  pending.quarantineLines = lines.slice(0, 5)
+  writeCompatPending(pending)
+  // 写后校验：清单里必须真的能看到这些行，才允许销毁原始记录
+  const back = readCompatPending()
+  const missing = rows.filter((rowId) => !(back?.pending ?? []).some((p) => p.rowId === rowId))
+  if (back === null || missing.length > 0) {
+    logQuarantineMergeError(new Error(`隔离记录写入清单后校验失败（缺失 ${missing.length}/${rows.length} 行），保留记录待下次启动重试`))
+    return rec
+  }
+  try {
+    copyFileSync(file, `${file}.applied-${Date.now()}`)
+    rmSync(file, { force: true })
+  } catch {}
+  return rec
+}
+
+/** 当前 loader 树里的 rowId → { moduleName, version, enabled }（补 moduleName、对账用）。 */
+export function rowIdModuleMap(ctx) {
+  const out = new Map()
+  let entries = []
+  try { entries = listEntries(ctx) } catch { return out }
+  const profileDir = profileDirOf(ctx)
+  for (const entry of entries) {
+    if (typeof entry.rowId !== 'string' || entry.rowId === '') continue
+    let version = null
+    try {
+      const pkgPath = profileDir === null ? null : resolvePackageJson(entry.moduleName, profileDir)
+      if (pkgPath !== null) version = JSON.parse(readFileSync(pkgPath, 'utf8')).version ?? null
+    } catch {}
+    out.set(entry.rowId, { moduleName: entry.moduleName ?? null, version, enabled: entry.enabled === true })
+  }
+  return out
+}
+
+/** 把某行的待适配记录标记为「已适配」（保留历史判定痕迹：check / checkNote / riskyApprovedAt）。
+ *  语义（用户定案 2026-09-11）：**启用即视为已适配**，但要留下"曾被判定/隔离"的痕迹供事后查。 */
+function markPendingAdopted(pending, rowId, by, meta) {
+  const rec = (pending?.pending ?? []).find((p) => p.rowId === rowId)
+  if (rec === undefined) return false
+  rec.status = 'adopted'
+  rec.adoptedAt = Date.now()
+  rec.adoptedBy = by
+  if (meta !== null && meta !== undefined) {
+    if (typeof meta.moduleName === 'string' && meta.moduleName !== '') rec.moduleName = meta.moduleName
+    if (typeof meta.version === 'string' && meta.version !== '') rec.version = meta.version
+  }
+  return true
+}
+
+/** 启动时让清单与现实对账（v0.3.45）：
+ *   ① 老记录缺 moduleName → 按当前 loader 补上（否则「全家桶一键启用已适配」永远匹配不到）；
+ *   ② 记录还是 pending、但这一行**当前已经启用**（用户手动启用过 / 补丁被清过）→ 转 adopted。
+ *  不这么做就会出现用户实测的那种矛盾：**已启用的行，重启后仍挂着【待适配】**。
+ *  返回 { backfilled, adopted } 供日志/测试核对；无变化则不写盘。 */
+export function reconcileCompatPending(ctx) {
+  const pending = readCompatPending()
+  if (pending === null || !Array.isArray(pending.pending)) return { backfilled: 0, adopted: 0 }
+  const info = rowIdModuleMap(ctx)
+  let backfilled = 0
+  let adopted = 0
+  for (const rec of pending.pending) {
+    if ((rec.status ?? 'pending') !== 'pending') continue
+    const meta = info.get(rec.rowId) ?? null
+    if (meta !== null) {
+      if ((rec.moduleName === null || rec.moduleName === undefined || rec.moduleName === '') && typeof meta.moduleName === 'string' && meta.moduleName !== '') {
+        rec.moduleName = meta.moduleName
+        if (meta.version !== null && meta.version !== undefined) rec.version = meta.version
+        backfilled += 1
+      }
+      if (meta.enabled === true) {
+        if (markPendingAdopted(pending, rec.rowId, 'row-enabled', meta)) adopted += 1
+      }
+    }
+  }
+  if (backfilled > 0 || adopted > 0) {
+    pending.updatedAt = new Date().toISOString()
+    writeCompatPending(pending)
+  }
+  return { backfilled, adopted }
+}
+
 /** 定位 @deepseek-ai/dsh-app-boot（与 @deepseek-ai/dsh 同级）。 */
 function locateAppBootFile(baseUrl) {
   try {
@@ -1181,6 +1416,27 @@ function profileDirOf(ctx) {
   }
 }
 
+/** 框架版本检查缓存（功能包 → 框架 面板用；5 分钟 TTL，避免每次打开面板都打 registry）。 */
+let fwCheckCache = null
+
+/** 清理残留的框架升级/回滚/重启计划任务（脚本被强杀时它来不及自删）。
+ *  v0.3.43：把「重启」与「重启守护」任务也纳入——2026-09-11 现场残留了 5 个 Ready 僵尸任务
+ *  （DSH-Restart-13804 / -31688 / -3744 / RestartV2 / RestartV3），正是"重启后没人拉起"的证据。
+ *  只在服务已经起来了的时候清理是安全的：服务在跑 ⇒ 守护任务无事可做（它自己也会立刻收工）。 */
+function cleanupStaleFwTasks() {
+  try {
+    execFile('schtasks', ['/query', '/fo', 'CSV', '/nh'], { windowsHide: true, timeout: 20000 }, (error, stdout) => {
+      if (error) return
+      const names = String(stdout).split(/\r?\n/u)
+        .map((line) => (line.match(/^"([^"]*)"/u)?.[1] ?? '').trim())
+        .filter((name) => /^\\?DSH-(?:FW-(?:Upgrade|Rollback)|Restart(?:V\d+)?|RestartGuard)-\d+$/u.test(name))
+      for (const name of names) {
+        execFile('schtasks', ['/delete', '/f', '/tn', name], { windowsHide: true, timeout: 20000 }, () => {})
+      }
+    })
+  } catch {}
+}
+
 /** 读取补丁文件并扫描：停用块与 insert 行的 id。 */
 async function readPatchState(patchPath) {
   let text = ''
@@ -2346,17 +2602,17 @@ let installJobSeq = 0
 const aiJobs = new Map()
 let aiJobSeq = 0
 /** 组件注册表（服务型组件：启动/停止/状态控制按钮的数据源）。 */
-const COMPONENTS_FILE = join(homedir(), '.dsh', 'plugin-console', 'components.json')
+const componentsFile = () => join(dshHome(), 'plugin-console', 'components.json')
 /** AI 赋能任务持久化文件（DSH 重启不丢计划/结果；running 任务重启后标记中断）。 */
-const AI_JOBS_FILE = join(homedir(), '.dsh', 'plugin-console', 'ai-jobs.json')
+const aiJobsFile = () => join(dshHome(), 'plugin-console', 'ai-jobs.json')
 /** 仓库落地根目录（可配置，默认 ~/.dsh/repos）。 */
 let reposDirCache = null
-const REPO_LAND_CONF = join(homedir(), '.dsh', 'plugin-console', 'repo-land.json')
+const repoLandConfFile = () => join(dshHome(), 'plugin-console', 'repo-land.json')
 function getReposDir() {
   if (reposDirCache !== null) return reposDirCache
   try {
-    if (existsSync(REPO_LAND_CONF)) {
-      const conf = JSON.parse(readFileSync(REPO_LAND_CONF, 'utf8'))
+    if (existsSync(repoLandConfFile())) {
+      const conf = JSON.parse(readFileSync(repoLandConfFile(), 'utf8'))
       if (typeof conf.dir === 'string' && conf.dir.trim() !== '') {
         reposDirCache = conf.dir.trim()
         return reposDirCache
@@ -2368,8 +2624,8 @@ function getReposDir() {
 }
 function setReposDir(dir) {
   reposDirCache = String(dir ?? '').trim()
-  mkdirSync(dirname(REPO_LAND_CONF), { recursive: true })
-  writeFileSync(REPO_LAND_CONF, JSON.stringify({ dir: reposDirCache }, null, 2), 'utf8')
+  mkdirSync(dirname(repoLandConfFile()), { recursive: true })
+  writeFileSync(repoLandConfFile(), JSON.stringify({ dir: reposDirCache }, null, 2), 'utf8')
   return reposDirCache
 }
 /** 已落地仓库列表：扫描 dir 下两级目录（owner/name 下含 .git）。 */
@@ -2394,15 +2650,15 @@ function listLandedRepos() {
 }
 function saveAiJobs() {
   try {
-    mkdirSync(dirname(AI_JOBS_FILE), { recursive: true })
+    mkdirSync(dirname(aiJobsFile()), { recursive: true })
     const arr = [...aiJobs.values()].map((j) => ({ id: j.id, source: j.source, status: j.status, stage: j.stage, plan: j.plan ?? null, logText: j.logText ?? '', stepStates: j.stepStates ?? [], progress: j.progress ?? null, error: j.error ?? null, createdAt: j.createdAt, finishedAt: j.finishedAt ?? null }))
-    writeFileSync(AI_JOBS_FILE, JSON.stringify(arr, null, 2), 'utf8')
+    writeFileSync(aiJobsFile(), JSON.stringify(arr, null, 2), 'utf8')
   } catch {}
 }
 function loadAiJobs() {
   try {
-    if (!existsSync(AI_JOBS_FILE)) return
-    const arr = JSON.parse(readFileSync(AI_JOBS_FILE, 'utf8'))
+    if (!existsSync(aiJobsFile())) return
+    const arr = JSON.parse(readFileSync(aiJobsFile(), 'utf8'))
     for (const j of arr) {
       if (!j || typeof j.id !== 'string') continue
       let job = j
@@ -2722,7 +2978,7 @@ async function runSuiteInstallJob(job, ctx) {
 
 /** 技能安装：git clone 仓库 → 定位 SKILL.md（根或第一层子目录）→ 复制到 ~/.dsh/skills/<name>/。
  * 技能由 dsh-skill-filesystem 插件扫描（发现根：<dshHome>/skills），与桌面版共享。 */
-async function runSkillInstallJob(job, ctx) {
+async function runSkillInstallJob(job) {
   const tmpDir = join(tmpdir(), `dsh-skill-${job.id}-${Date.now()}`)
   try {
     job.stage = 'preparing'
@@ -3146,7 +3402,7 @@ function resolvePythonPath() {
 
 function findComponents() {
   try {
-    const parsed = JSON.parse(readFileSync(COMPONENTS_FILE, 'utf8'))
+    const parsed = JSON.parse(readFileSync(componentsFile(), 'utf8'))
     return Array.isArray(parsed) ? parsed : (Array.isArray(parsed?.components) ? parsed.components : [])
   } catch {
     return []
@@ -3154,8 +3410,8 @@ function findComponents() {
 }
 
 function saveComponents(list) {
-  mkdirSync(dirname(COMPONENTS_FILE), { recursive: true })
-  writeFileSync(COMPONENTS_FILE, JSON.stringify(list, null, 2), 'utf8')
+  mkdirSync(dirname(componentsFile()), { recursive: true })
+  writeFileSync(componentsFile(), JSON.stringify(list, null, 2), 'utf8')
 }
 
 function compFind(id) {
@@ -3808,6 +4064,60 @@ const PRESET_CONFIG_MIGRATIONS = [
   { pkg: '@deepseek-ai/dsh-persona', from: 'text', to: 'prefix', since: '0.1.5' },
 ]
 
+/**
+ * 生成「拉起 DSH 服务」的 PowerShell 前导块（升级脚本 / 回滚脚本共用，v0.3.37 事故修复）。
+ *
+ * 2026-09-11 事故：脚本在「重启服务」这一步崩溃，服务没人拉起（框架其实已经升级成功，
+ * 界面却显示全红）。根因是一条**静默的 null**：
+ *     $binNow = ''; try { $binNow = (& node -e "…require.resolve…" | Select-Object -Last 1) } catch {}
+ *     if ($binNow -ne '' -and (Test-Path $binNow)) { … }
+ * 当 node 解析那一瞬间失败（新版链接尚未就绪等）时输出为空 → `Select-Object -Last 1` 让
+ * `$binNow` 变成 **$null**，而 PowerShell 里 `$null -ne ''` 是 **true**（守卫失效）→
+ * `Test-Path $null` 抛「无法将参数绑定到参数"Path"，因为该参数是空值」→ 脚本当场终止。
+ * 同一段代码原先被复制了 5 份，所以这个坑反复出现。
+ *
+ * 现在：只保留这一份实现，并且
+ *   1) 返回值**永不为 $null**（非字符串一律归一成空串，再做 IsNullOrWhiteSpace 判断）；
+ *   2) 解析走**多级回退**（不再假设某一处路径一定可用）：node resolve → 目标版本的 .pnpm 实体
+ *      目录 → 顶层可见链接 → .pnpm 里最新的一个；
+ *   3) 全路径参数一律 `Test-Path -LiteralPath`，失败只记录、不抛错。
+ */
+function relaunchPrelude({ nodePath, pluginDir, fwRoot, target, ps }) {
+  const probe = "const path=require('path');const p=require.resolve('@deepseek-ai/dsh/package.json',{paths:[process.env.DSH_RESOLVE_ROOT]});console.log(path.join(path.dirname(p),'lib','bin.js'))"
+  const pnpmBin = (dirExpr) => `Join-Path ${dirExpr} 'node_modules\\@deepseek-ai\\dsh\\lib\\bin.js'`
+  return [
+    `$launchLog = ''`,
+    // 心跳（v0.3.39）：脚本每推进一小步就更新一次心跳文件的时间戳。服务端据此区分
+    // 「脚本还在干活」与「脚本进程被系统/启动器杀掉」。2026-09-11 真机事故：回滚脚本
+    // 干完活之后被 Ctrl+C 类事件结束（计划任务 Last Result = 0xC000013A），终态没写成，
+    // 界面就永远卡在「回滚中…」——有心跳就能判定「脚本已死 + 现实是什么」。
+    `$hb = $state + '.hb'`,
+    `function Beat { try { Set-Content -Path $hb -Value ([string](Get-Date).Ticks) -Encoding UTF8 } catch {} }`,
+    `try { Beat } catch {}`,
+    `try { if ($log) { $launchLog = Join-Path (Split-Path -LiteralPath $log) 'fw-relaunch.log' } } catch {}`,
+    `if ([string]::IsNullOrWhiteSpace($launchLog)) { $launchLog = Join-Path $env:TEMP 'fw-relaunch.log' }`,
+    `function Resolve-DshBin {`,
+    `  $cand = ''`,
+    `  try { $env:DSH_RESOLVE_ROOT = ${ps(pluginDir)}; $cand = (& ${ps(nodePath)} -e "${probe}" 2>$null | Select-Object -Last 1) } catch { $cand = '' }`,
+    `  if ($cand -isnot [string]) { $cand = '' }`,
+    `  $cand = ([string]$cand).Trim()`,
+    `  if ($cand -ne '' -and (Test-Path -LiteralPath $cand)) { return $cand }`,
+    `  try { foreach ($d in @(Get-ChildItem -Path (Join-Path ${ps(fwRoot)} '.pnpm') -Directory -Filter '@deepseek-ai+dsh@${target}*' -ErrorAction SilentlyContinue)) { $c = ${pnpmBin('$d.FullName')}; if (Test-Path -LiteralPath $c) { return $c } } } catch {}`,
+    `  try { $c = ${ps(join(fwRoot, '@deepseek-ai', 'dsh', 'lib', 'bin.js'))}; if (Test-Path -LiteralPath $c) { return $c } } catch {}`,
+    `  try { foreach ($d in @(Get-ChildItem -Path (Join-Path ${ps(fwRoot)} '.pnpm') -Directory -Filter '@deepseek-ai+dsh@*' -ErrorAction SilentlyContinue | Sort-Object Name -Descending)) { $c = ${pnpmBin('$d.FullName')}; if (Test-Path -LiteralPath $c) { return $c } } } catch {}`,
+    `  return ''`,
+    `}`,
+    `function Invoke-DshRelaunch($tag) {`,
+    `  $bin = Resolve-DshBin`,
+    `  if ([string]::IsNullOrWhiteSpace($bin)) { Log ('拉起失败（' + $tag + '）：node resolve / .pnpm / 顶层链接 三种方式都找不到 dsh 的 bin.js，请手动启动 DSH'); return $false }`,
+    `  try { Add-Content -Path $launchLog -Value ((Get-Date -Format 'yyyy-MM-dd HH:mm:ss') + ' 拉起(' + $tag + '): ' + $bin) -Encoding UTF8 } catch {}`,
+    `  try { Start-Process -FilePath 'cmd.exe' -ArgumentList @('/c', ('"' + ${ps(nodePath)} + '" "' + $bin + '" web >> "' + $launchLog + '" 2>&1')) -WindowStyle Hidden } catch { Log ('拉起进程启动失败（' + $tag + '）：' + $_.Exception.Message); return $false }`,
+    `  Log ('已发起拉起服务（' + $tag + '，输出见 fw-relaunch.log）')`,
+    `  return $true`,
+    `}`,
+  ].join('\r\n')
+}
+
 /** 待扫描的 agent 配置文件：所有预设 + profile 的 host 组合。 */
 function collectAgentConfigFiles(profileDir) {
   const files = []
@@ -3890,6 +4200,162 @@ export function migrateAgentConfigsForUpgrade(profileDir, targetVersion) {
   return out
 }
 
+/**
+ * 启动失败日志分析器（纯函数，导出供测试）：
+ * 从服务/预设的启动失败日志里提取「谁把服务搞挂了」——用于**启动失败隔离**（升级后服务拉不起来时，
+ * 先禁用/隔离肇事者并重试，而不是整包回滚）。三类信号：
+ *   ① 预设挂载失败：`preset "router-spec" failed to mount` 或路径 `.agent-presets/<name>/agent.cordis.yml`
+ *   ② loader 条目应用失败：`failed to apply loader entry <rowId> (<moduleName>)`
+ *   ③ 模块解析失败：`Cannot find module '<moduleName>'`
+ * 返回 { presets:[name], modules:[{rowId,moduleName}], lines:[命中行] }
+ */
+export function analyzeBootFailure(logText) {
+  const text = String(logText ?? '')
+  const presets = new Set()
+  const modules = new Map() // moduleName -> rowId|null
+  const hits = []
+  const pushHit = (line) => { if (hits.length < 40 && !hits.includes(line.trim())) hits.push(line.trim().slice(0, 300)) }
+
+  for (const line of text.split(/\r?\n/u)) {
+    if (line.trim() === '') continue
+    let matched = false
+    for (const m of line.matchAll(/preset\s+"([^"]+)"\s+failed to mount/gu)) { presets.add(m[1]); matched = true }
+    for (const m of line.matchAll(/\.agent-presets[\\/]([^\\/\s"']+)[\\/]agent\.cordis\.ya?ml/gu)) { presets.add(m[1]); matched = true }
+    for (const m of line.matchAll(/failed to apply loader entry\s+(\S+)\s+\(([^)]+)\)/gu)) { modules.set(m[2], m[1]); matched = true }
+    for (const m of line.matchAll(/Cannot find module '([^']+)'/gu)) {
+      if (!modules.has(m[1])) modules.set(m[1], null)
+      matched = true
+    }
+    if (matched) pushHit(line)
+  }
+  return {
+    presets: [...presets],
+    modules: [...modules].map(([moduleName, rowId]) => ({ moduleName, rowId })),
+    lines: hits,
+  }
+}
+
+/** 启动失败隔离决策器（纯函数，导出供测试）。
+ * 输入：启动失败日志 + 当前可开关行清单（[{rowId,moduleName,toggleable}]）。
+ * 输出一份**可直接执行的隔离方案**（PowerShell 侧只负责照做，不掺判断逻辑）：
+ *   presets  要隔离的预设文件（改名 .broken-<ts>，避免预设挂载失败拖垮整个服务）
+ *   rows     要写入 disabled:true 的行（已剔除核心行/受保护行/控制台自身）
+ *   safeMode 无明确肇事者时是否建议安全模式（禁用全部第三方行，先让服务起来）
+ *   coreHits 命中的行属于核心/受保护（禁它没用，正确动作是回滚框架）
+ * 设计依据：loader 单行 import 失败 = 整个服务启动崩溃；静态扫描抓不到全部不兼容，
+ * 所以必须有一条「起不来 → 定位肇事者 → 隔离 → 重试」的运行时兜底。 */
+export function planQuarantine({ logText, candidates, presetRoot = null, exists = existsSync }) {
+  const analysis = analyzeBootFailure(logText)
+  const byModule = new Map()
+  const byRow = new Map()
+  for (const c of candidates ?? []) {
+    if (typeof c?.rowId !== 'string' || c.rowId === '') continue
+    if (typeof c.moduleName === 'string' && c.moduleName !== '') byModule.set(c.moduleName, c)
+    byRow.set(c.rowId, c)
+  }
+  const rows = []
+  const coreHits = []
+  const unknown = []
+  for (const m of analysis.modules) {
+    const hit = (m.rowId !== null && byRow.get(m.rowId)) || byModule.get(m.moduleName) || null
+    if (hit === null) { unknown.push(m.moduleName); continue }
+    const isCore = CORE_PATCH_ROW_IDS.has(hit.rowId) || hit.rowId === 'plugin-console'
+    if (isCore || hit.toggleable === false) { coreHits.push({ rowId: hit.rowId, moduleName: hit.moduleName }); continue }
+    if (!rows.includes(hit.rowId)) rows.push(hit.rowId)
+  }
+  const root = presetRoot ?? join(dshHome(), '.agent-presets')
+  const presets = []
+  for (const name of analysis.presets) {
+    const file = join(root, name, 'agent.cordis.yml')
+    presets.push({ name, file, exists: exists(file) })
+  }
+  return {
+    presets,
+    rows,
+    unknown,
+    coreHits,
+    safeMode: presets.length === 0 && rows.length === 0,
+    lines: analysis.lines,
+  }
+}
+
+/** 框架升级前置门禁（用户硬要求：「升级后所有不适配的必须先禁用」）。
+ * 在升级脚本执行**之前**扫描全部可开关行，对目标框架版本判定为 fail 的行就地写 disabled:true，
+ * 并记入 compat-pending（UI 显示「待适配」，更新后一键解锁）。这样新框架 boot 时不会因为
+ * 某行 import 失败而整树崩溃（loader 单行失败 = 服务起不来）。
+ * 受保护行/核心行/自身永不禁用——禁它们本身就会让服务起不来。
+ * 返回 { disabled:[{rowId,moduleName,version,reason}], skipped:[{rowId,reason}] } */
+export async function preflightDisableIncompatible({ ctx, profileDir, patchPath, targetVersion }) {
+  const disabled = []
+  const skipped = []
+  const gate = readCompatGate()
+  if (typeof targetVersion !== 'string' || targetVersion === '') return { disabled, skipped }
+  let entries = []
+  try { entries = listEntries(ctx) } catch { return { disabled, skipped } }
+  let pending = readCompatPending()
+  if (pending === null || !Array.isArray(pending.pending)) pending = { frameworkVersion: targetVersion, upgradeFrom: null, pending: [] }
+  for (const entry of entries) {
+    if (typeof entry.rowId !== 'string' || entry.rowId === '') continue
+    if (!entry.enabled) continue
+    if (entry.rowId === 'plugin-console') continue // 控制台自己永不禁用
+    if (!entry.toggleable || CORE_PATCH_ROW_IDS.has(entry.rowId)) {
+      skipped.push({ rowId: entry.rowId, reason: '受保护/核心行（禁用会让服务起不来，改由启动失败隔离兜底）' })
+      continue
+    }
+    let pkg = null
+    let pkgDir = null
+    try {
+      const pkgPath = resolvePackageJson(entry.moduleName, profileDir)
+      if (pkgPath !== null) { pkg = JSON.parse(readFileSync(pkgPath, 'utf8')); pkgDir = dirname(pkgPath) }
+    } catch {}
+    if (pkg === null) {
+      skipped.push({ rowId: entry.rowId, reason: '无法读取包信息（保持启用，改由启动失败隔离兜底）' })
+      continue
+    }
+    // v0.3.35：框架自带包永不自动禁用（真机演练抓到：框架自己的 settings 控制器被误判成不适配）。
+    // 它们与框架同源安装，禁用不是正确处置——正确处置是回滚；误判则直接砍掉框架功能。
+    if (isFrameworkOwnedPackage(pkgDir, profileDir)) {
+      skipped.push({ rowId: entry.rowId, reason: '框架自带包（与框架同源安装，禁用不是正确处置，改由回滚兜底）' })
+      continue
+    }
+    let check = { decision: 'unknown', reason: '' }
+    try { check = checkPluginFrameworkCompat(pkg, targetVersion, pkgDir) } catch (error) { check = { decision: 'unknown', reason: error instanceof Error ? error.message : String(error) } }
+    if (check.decision !== 'fail') continue // pass / unknown 一律不禁用（避免过度禁用把功能砍掉）
+    if (gate.autoDisable !== true) {
+      // 总开关关闭：只报告不动开关（用户定案：自动行为必须可关）
+      skipped.push({ rowId: entry.rowId, reason: `判定不适配（${check.reason ?? '不兼容'}），但「升级时自动禁用」已关闭——保持启用，请手动处理` })
+      continue
+    }
+    try {
+      await disableEntry(patchPath, entry.rowId)
+    } catch (error) {
+      skipped.push({ rowId: entry.rowId, reason: `禁用写入失败：${error instanceof Error ? error.message : String(error)}` })
+      continue
+    }
+    const version = typeof pkg.version === 'string' ? pkg.version : null
+    disabled.push({ rowId: entry.rowId, moduleName: entry.moduleName, version, reason: check.reason ?? null })
+    const record = {
+      rowId: entry.rowId,
+      moduleName: entry.moduleName,
+      version,
+      status: 'pending',
+      check: 'fail',
+      checkNote: check.reason ?? null,
+      forcedAt: Date.now(),
+      source: 'preflight-disabled-before-upgrade',
+    }
+    const at = pending.pending.findIndex((p) => p.rowId === entry.rowId)
+    if (at >= 0) pending.pending[at] = { ...pending.pending[at], ...record }
+    else pending.pending.push(record)
+  }
+  if (disabled.length > 0) {
+    pending.frameworkVersion = targetVersion
+    pending.updatedAt = new Date().toISOString()
+    writeCompatPending(pending)
+  }
+  return { disabled, skipped }
+}
+
 /** 移除补丁中的单行 disabled/forced 覆盖块（兼容门解锁用）。 */
 function removeDisableBlock(patchPath, rowId) {
   return queuedWrite(async () => {
@@ -4058,7 +4524,7 @@ async function runInstallJob(job, ctx) {
         const skillProbe = await detectSkillRepo(job.repo, branch)
         if (skillProbe.hasSkill) {
           job.kind = 'skill'
-          await runSkillInstallJob(job, ctx)
+          await runSkillInstallJob(job)
           return
         }
         job.status = 'failed'
@@ -4365,6 +4831,20 @@ function listEntries(ctx) {  const entries = []
 export function apply(ctx) {
   // 恢复 AI 赋能任务（restart 后 running 置失败，plan-ready/结果保留）
   loadAiJobs()
+  // 升级脚本的「启动失败隔离」记录并入适配门清单（让用户看到谁被自动关了）
+  // v0.3.44：这里的 catch 不再静默 —— 2026-09-11 那次隔离记录（20 行）就是这样凭空消失的：
+  // 合并函数在中途抛错、catch 吞掉，界面只剩一个没有解释的【停用】。失败必须留痕。
+  try { mergeQuarantineRecord(ctx) } catch (error) { logQuarantineMergeError(error) }
+  // v0.3.45：清单与现实对账 —— 补 moduleName（否则「全家桶一键启用已适配」永远匹配不到），
+  // 以及把「已经启用、却还挂着 pending」的记录转成已适配（用户实测：启用后重启又变【待适配】）
+  try {
+    const fixed = reconcileCompatPending(ctx)
+    if (fixed.backfilled > 0 || fixed.adopted > 0) {
+      try { writeFileSync(join(dshHome(), 'plugin-console', 'fw-merge-error.log'), `${new Date().toISOString()} 清单对账：补 moduleName ${fixed.backfilled} 行，已启用转已适配 ${fixed.adopted} 行\n`, { flag: 'a' }) } catch {}
+    }
+  } catch (error) { logQuarantineMergeError(error) }
+  // 启动时清掉上次升级/回滚/重启留下的僵尸计划任务（脚本被强杀时来不及自删）
+  try { cleanupStaleFwTasks() } catch {}
   // DSH 启动时自动拉起标记了「自启动」的服务器组件（幂等，不阻塞启动）
   autostartComponents().catch(() => {})
   ctx.effect(() => {
@@ -4421,11 +4901,14 @@ async function handle(ctx, req, res) {
     const extraRows = await readExtraBundleRows(dirname(patchPath))
     const compatPending = readCompatPending()
     const compatPendingRows = new Set((compatPending?.pending ?? []).filter((p) => (p.status ?? 'pending') === 'pending').map((p) => p.rowId))
+    // 兼容门总开关 + 自动检测（只提示不自动开）
+    const compatGate = readCompatGate()
+    const adoptable = compatGate.autoDetect ? detectAdoptablePending(ctx) : new Map()
     let rollbackRec = null
     try {
       const rr = JSON.parse(readFileSync(join(dshHome(), 'plugin-console', 'framework-rollback.json'), 'utf8'))
       if (rr !== null && typeof rr.checkpointDir === 'string' && existsSync(join(rr.checkpointDir, '.pnpm'))) {
-        rollbackRec = { from: rr.from ?? null, to: rr.to ?? null, at: rr.at ?? null }
+        rollbackRec = { from: rr.from ?? null, to: rr.to ?? null, at: rr.at ?? null, applicable: true }
       }
     } catch {}
     const entries = listEntries(ctx).map((entry) => {
@@ -4438,7 +4921,11 @@ async function handle(ctx, req, res) {
         installDate: meta?.installDate ?? null,
         version: meta?.version ?? null,
         repository: meta?.repository ?? null,
-        pendingCompat: compatPendingRows.has(entry.rowId),
+        // v0.3.45：只有"补丁里此刻确实还禁着它"的行才显示【待适配】——
+        // 记录与开关脱节时（用户手动启用过 / 补丁块被清掉）不能继续挂着「待适配」误导人
+        pendingCompat: compatPendingRows.has(entry.rowId) && patch.disables.includes(entry.rowId),
+        // 自动检测结果（只提示，不自动开）：该待适配行现在是否已适配（插件已更新 + 扫描通过）
+        adoptable: adoptable.get(entry.rowId) ?? null,
       }
     })
     const compat = await detectCompat(ctx.baseUrl ?? 'file:///')
@@ -4448,12 +4935,18 @@ async function handle(ctx, req, res) {
     // 框架升级检测与适配（备份快照 + 重打框架补丁），try 包裹不阻塞 state 返回
     let framework = null
     try { framework = detectFrameworkUpgrade(ctx) } catch {}
+    // 回滚可用性（2026-09-11 用户困惑：版本已经回滚了，回滚按钮还能点）——
+    // 当前版本已经等于记录里的 from 时，再点回滚等于"恢复到你现在这个版本"，无意义。
+    if (rollbackRec !== null) {
+      const currentVer = typeof framework?.version === 'string' ? framework.version : null
+      rollbackRec.applicable = !(currentVer !== null && rollbackRec.from !== null && currentVer === rollbackRec.from)
+    }
     let selfVersion = null
     try {
       const selfPkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8'))
       selfVersion = typeof selfPkg.version === 'string' ? selfPkg.version : null
     } catch {}
-    sendJson(res, 200, { ok: true, entries, patchPath, compat, installJobs: jobs, recentFailures, github: { loggedIn: auth.loggedIn, login: auth.login }, patch: { disables: patch.disables, forced: patch.forced, inserts: patch.inserts }, framework, patchHeal: patchHeal === null ? null : { healed: patchHeal.healed ?? [], autoDisabled: patchHeal.autoDisabled ?? [], healedAt: patchHeal.healedAt ?? 0 }, compatPending: compatPending === null ? null : { frameworkVersion: compatPending.frameworkVersion ?? null, upgradeFrom: compatPending.upgradeFrom ?? null, pending: (compatPending.pending ?? []).filter((p) => (p.status ?? 'pending') === 'pending').map((p) => ({ rowId: p.rowId, moduleName: p.moduleName, version: p.version ?? null, checkNote: p.checkNote ?? null, check: p.check ?? null })) }, rollback: rollbackRec, selfVersion, components: findComponents().map((c) => ({ id: c.id, name: c.name, kind: c.kind ?? 'server', pid: c.pid ?? null, port: c.port ?? null, healthUrl: c.healthUrl ?? null, uiUrl: compUiUrl(c), autoStart: c.autoStart === true })) })
+    sendJson(res, 200, { ok: true, entries, patchPath, compat, installJobs: jobs, recentFailures, github: { loggedIn: auth.loggedIn, login: auth.login }, patch: { disables: patch.disables, forced: patch.forced, inserts: patch.inserts }, framework, patchHeal: patchHeal === null ? null : { healed: patchHeal.healed ?? [], autoDisabled: patchHeal.autoDisabled ?? [], healedAt: patchHeal.healedAt ?? 0 }, compatPending: compatPending === null ? null : { frameworkVersion: compatPending.frameworkVersion ?? null, upgradeFrom: compatPending.upgradeFrom ?? null, pending: (compatPending.pending ?? []).filter((p) => (p.status ?? 'pending') === 'pending').map((p) => ({ rowId: p.rowId, moduleName: p.moduleName, version: p.version ?? null, checkNote: p.checkNote ?? null, check: p.check ?? null, riskyApprovedAt: p.riskyApprovedAt ?? null, adoptable: adoptable.get(p.rowId) ?? null })) }, compatGate, rollback: rollbackRec, selfVersion, components: findComponents().map((c) => ({ id: c.id, name: c.name, kind: c.kind ?? 'server', pid: c.pid ?? null, port: c.port ?? null, healthUrl: c.healthUrl ?? null, uiUrl: compUiUrl(c), autoStart: c.autoStart === true })) })
     return
   }
 
@@ -4537,7 +5030,50 @@ async function handle(ctx, req, res) {
         if (raw.charCodeAt(0) === 0xFEFF) raw = raw.slice(1)
         const [st, ...rest] = raw.split('|')
         const at = statSync(f).mtimeMs
-        status = { status: st ?? 'idle', message: rest.join('|') || null, at }
+        // v0.3.37：失败记录里带 stage=<崩溃前最后阶段>，界面据此把已完成的步骤显示成 ✓（而不是整列 ✕）
+        const stageRaw = rest.find((p) => p.startsWith('stage='))
+        const stage = stageRaw === undefined ? null : (stageRaw.slice(6) || null)
+        status = { status: st ?? 'idle', message: rest.filter((p) => !p.startsWith('stage=')).join('|') || null, stage, at }
+        // ── v0.3.39 状态自愈 ──────────────────────────────────────────────────
+        // 2026-09-11 真机：回滚脚本干完活之后**进程被 Ctrl+C 类事件结束**（计划任务 Last Result
+        // = 0xC000013A），终态没写成 → 界面永远卡在「回滚中…」并每 3 秒轮询。心跳 + 现实核对
+        // 能把它纠正回来：脚本不再心跳（>90 秒没动静）时，用「已装版本 vs 回滚记录的 from/to」
+        // 判断真实结果；同时清掉残留的 DSH-FW-* 计划任务。
+        const terminal = status.status === 'idle' || status.status === 'done' || status.status === 'failed'
+        if (!terminal) {
+          let hbAge = null
+          try { hbAge = Date.now() - statSync(`${f}.hb`).mtimeMs } catch { hbAge = null }
+          const scriptAlive = hbAge !== null && hbAge < 90000
+          if (!scriptAlive) {
+            let rec = null
+            let current = null
+            try { rec = JSON.parse(readFileSync(join(dshHome(), 'plugin-console', 'framework-rollback.json'), 'utf8')) } catch {}
+            try {
+              const localRequire = createRequire(ctx.baseUrl ?? 'file:///')
+              current = JSON.parse(readFileSync(localRequire.resolve('@deepseek-ai/dsh/package.json'), 'utf8')).version ?? null
+            } catch {}
+            const upgradedTo = rec !== null && typeof rec.to === 'string' && current === rec.to
+            const rolledBackTo = rec !== null && typeof rec.from === 'string' && current === rec.from
+            // 「安装阶段」不能靠 from 判定（那时本来就还是旧版本），只认 to
+            if (upgradedTo) {
+              status = { ...status, status: 'done', reconciled: { from: st, note: `脚本进程已中断，但框架已是 ${current}、服务正常 —— 实际结果：升级成功` } }
+            } else if (rolledBackTo && (st === 'rollback' || st === 'relaunching' || st === 'stopped')) {
+              status = { ...status, status: 'done', reconciled: { from: st, note: `脚本进程已中断，但框架已回到 ${current}、服务正常 —— 实际结果：回滚成功` } }
+            } else if (hbAge !== null) {
+              status = { ...status, stalled: true, note: '升级/回滚脚本已超过 90 秒没有心跳，进程可能已被结束——请用「重新检查版本」核对，必要时重启服务' }
+            }
+            if (status.reconciled !== undefined) cleanupStaleFwTasks()
+          }
+        }
+        // 失败但框架本体其实已经装到目标版本：明确告诉用户「升级本体成功、失败的是重启那一步」，
+        // 免得整列红叉让人以为白干了（2026-09-11 真机事故就是这样）。
+        if (status.status === 'failed') {
+          try {
+            const rr = JSON.parse(readFileSync(join(dshHome(), 'plugin-console', 'framework-rollback.json'), 'utf8'))
+            const cur = JSON.parse(readFileSync(join(rr.fwRoot, '@deepseek-ai', 'dsh', 'package.json'), 'utf8')).version
+            if (typeof rr.to === 'string' && rr.to !== '' && cur === rr.to) status.frameworkAtTarget = cur
+          } catch {}
+        }
         // 残留清理：非终止状态（starting/stopped/installing/rollback/pkg/relaunching）超过 15 分钟
         // 视为上次升级的残留——升级脚本要么成功（done）要么失败（failed），服务重启后不可能还在
         // 中途；任务调度失败/脚本空跑时状态会永远停在 starting，重启后不应再自动恢复进度条。
@@ -4654,12 +5190,34 @@ async function handle(ctx, req, res) {
       return
     }
     if (enabled) {
-      // 框架升级适配门（事故教训）：兼容门清单内的行保持强制禁用，直到更新并通过校验
+      // 框架升级适配门（用户定案 2026-09-11：**软禁**）——自动禁用的目的是「保证新框架能起来」，
+      // 不是「剥夺用户控制权」：默认自动禁用，但允许手动强行启用（首次请求返回 needsConfirm，
+      // 前端弹风险提示确认框；带 confirmRisky:true 才放行）。
+      // 注意下面还有一条**硬**门禁：启用前的 import 冒烟检查——那条是事实性崩溃（模块根本加载不了），
+      // 不允许覆盖（否则下次启动必崩，与「服务永不崩」冲突）。
       const compatPending = readCompatPending()
       const pend = (compatPending?.pending ?? []).find((p) => p.rowId === rowId && (p.status ?? 'pending') === 'pending')
       if (pend) {
-        sendError(res, 409, `「${rowId}」仍在框架升级适配门中（${compatPending.frameworkVersion ?? '?'}）被强制禁用：请先点击「更新并适配 / 已适配，立即解锁」，通过兼容校验后系统自动解锁`)
-        return
+        if (body.confirmRisky !== true) {
+          sendError(
+            res,
+            409,
+            `「${rowId}」在框架升级适配门清单中（框架 ${compatPending.frameworkVersion ?? '?'}${pend.checkNote ? `，判定：${pend.checkNote}` : ''}）——已自动禁用。强行启用可能让 DSH 下次启动失败，需要你确认。`,
+            {
+              code: 'compat-confirm',
+              rowId,
+              moduleName: pend.moduleName ?? null,
+              frameworkVersion: compatPending.frameworkVersion ?? null,
+              checkNote: pend.checkNote ?? null,
+            },
+          )
+          return
+        }
+        try {
+          const next = readCompatPending()
+          const rec = (next?.pending ?? []).find((p) => p.rowId === rowId)
+          if (rec) { rec.riskyApprovedAt = Date.now(); writeCompatPending(next) }
+        } catch {}
       }
     }
     const patchPath = findPatchPath(ctx)
@@ -4680,6 +5238,19 @@ async function handle(ctx, req, res) {
     const result = enabled
       ? await enableEntry(patchPath, rowId)
       : await disableEntry(patchPath, rowId)
+    // v0.3.45（用户定案：启用即视为已适配，但保留痕迹）：手动启用一个待适配行后，
+    // 清单里的 pending 记录要转成 adopted —— 否则重启后界面上会出现「已启用却还挂着【待适配】」，
+    // 用户实测就是这样（5 行）。check / checkNote / riskyApprovedAt 一律保留供事后查。
+    if (enabled) {
+      try {
+        const list = readCompatPending()
+        const meta = rowIdModuleMap(ctx).get(rowId) ?? null
+        if (list !== null && markPendingAdopted(list, rowId, 'manual-enable', meta)) {
+          list.updatedAt = new Date().toISOString()
+          writeCompatPending(list)
+        }
+      } catch {}
+    }
     sendJson(res, 200, { ok: true, entryId, rowId, enabled, changed: result.changed, patchPath })
     return
   }
@@ -5407,6 +5978,49 @@ async function handle(ctx, req, res) {
     return
   }
 
+  if (pathname === `${ROUTE_PREFIX}/framework-check`) {
+    // 框架版本检查（「功能包 → 框架」常驻面板用）：当前版本 / latest / next / 升级目标。
+    // 与升级路由同一套判定规则，但**只读**（不备份、不写状态文件）；5 分钟内存缓存 +
+    // body.refresh === true 强制重查——面板是常驻入口，不能每次打开都打 registry。
+    const now = Date.now()
+    if (body.refresh === true || fwCheckCache === null || now - fwCheckCache.at > 300000) {
+      let latest = null
+      let next = null
+      let registryError = null
+      try {
+        const data = await fetchJsonUrl('https://registry.npmmirror.com/@deepseek-ai%2fdsh')
+        latest = data?.['dist-tags']?.latest ?? null
+        next = data?.['dist-tags']?.next ?? null
+      } catch (error) {
+        registryError = error instanceof Error ? error.message : String(error)
+      }
+      let current = null
+      try {
+        const localRequire = createRequire(ctx.baseUrl ?? 'file:///')
+        const pkg = JSON.parse(readFileSync(localRequire.resolve('@deepseek-ai/dsh/package.json'), 'utf8'))
+        current = typeof pkg.version === 'string' ? pkg.version : null
+      } catch {}
+      const target = latest !== null && current !== null && isFrameworkVersionNewer(latest, current)
+        ? latest
+        : (next !== null && current !== null && isFrameworkVersionNewer(next, current) ? next : null)
+      fwCheckCache = { at: now, data: { current, latest, next, target, registryError } }
+    }
+    sendJson(res, 200, { ok: true, ...fwCheckCache.data, checkedAt: fwCheckCache.at })
+    return
+  }
+
+  if (pathname === `${ROUTE_PREFIX}/compat-gate`) {
+    // 兼容门总开关（用户定案 2026-09-11）：自动行为必须可关，关掉即回到纯手动。
+    //  autoDisable —— 升级前是否自动禁用判定不适配的行
+    //  autoDetect  —— 打开控制台时是否自动检测「已适配」（仅提示，绝不自动解锁）
+    const patchBody = {}
+    if (typeof body.autoDisable === 'boolean') patchBody.autoDisable = body.autoDisable
+    if (typeof body.autoDetect === 'boolean') patchBody.autoDetect = body.autoDetect
+    const gateNext = Object.keys(patchBody).length > 0 ? writeCompatGate(patchBody) : readCompatGate()
+    sendJson(res, 200, { ok: true, compatGate: gateNext })
+    return
+  }
+
   if (pathname === `${ROUTE_PREFIX}/adapt-unlock`) {
     // 待适配行「已适配，立即解锁」：无需等新版本——对已装模块重跑源码扫描，通过即移除禁用块。
     const rowId = typeof body.rowId === 'string' ? body.rowId : ''
@@ -5462,10 +6076,31 @@ async function handle(ctx, req, res) {
     const pending = readCompatPending()
     const patchPath = findPatchPath(ctx)
     const profileDir = dirname(patchPath)
-    const targets = (pending?.pending ?? []).filter((p) => (p.status ?? 'pending') === 'pending' && (p.moduleName === root || String(p.moduleName).startsWith(root + '/')))
+    // v0.3.45：匹配规则改成「moduleName 前缀 **或** 属主行集合」——
+    // 隔离记录合并进来的老行 moduleName 为空（脚本只写 rowId），只按 moduleName 比会匹配不到，
+    // 于是用户点「一键启用已适配」得到「该全家桶没有待适配行」（实测就是这个）。
+    const info = rowIdModuleMap(ctx)
+    const bundleRowIds = new Set()
+    for (const [rowId, meta] of info) {
+      const name = meta?.moduleName
+      if (typeof name === 'string' && name !== '' && (name === root || name.startsWith(root + '/'))) bundleRowIds.add(rowId)
+    }
+    const inFamily = (p) => {
+      if (typeof p.moduleName === 'string' && p.moduleName !== '' && (p.moduleName === root || p.moduleName.startsWith(root + '/'))) return true
+      return bundleRowIds.has(p.rowId) || info.get(p.rowId)?.moduleName === root
+    }
+    // 目标 = ① 待适配（pending）② **已记已适配、但从没通过源码扫描**（check !== 'pass'）。
+    // ② 这类正是"账面上已适配、补丁里却还禁着"的行 —— 老逻辑只挑 pending，于是用户点「一键启用已适配」
+    // 得到"没有待适配行、无需操作"，可它们其实一行都没启用（实测就是这个）。
+    const targets = (pending?.pending ?? []).filter((p) => {
+      if (!inFamily(p)) return false
+      const status = p.status ?? 'pending'
+      if (status === 'pending') return true
+      return status === 'adopted' && p.check !== 'pass'
+    })
     if (targets.length === 0) {
       // 无待适配行=全部已适配/已解锁，属正常状态：返回友好提示而非错误（点击「一键启用已适配」不应报"操作失败"）
-      sendJson(res, 200, { ok: true, unlocked: [], kept: [], note: '该全家桶没有待适配行（已全部适配/解锁），无需操作' })
+      sendJson(res, 200, { ok: true, unlocked: [], kept: [], note: '该全家桶内没有待扫描/待解锁的行（全部已通过源码扫描或已解锁）' })
       return
     }
     const fwVer = typeof pending.frameworkVersion === 'string' ? pending.frameworkVersion : '?'
@@ -5498,7 +6133,17 @@ async function handle(ctx, req, res) {
       unlocked.push(p.rowId)
     }
     writeCompatPending(pending)
-    sendJson(res, 200, { ok: true, root, unlocked, kept })
+    // kept = 扫描未通过（保持禁用，并带上原因）；unlocked = 本次真解锁的行
+    sendJson(res, 200, {
+      ok: true,
+      root,
+      unlocked,
+      kept,
+      scanned: targets.length,
+      note: kept.length === 0
+        ? `已重跑源码扫描并解锁 ${unlocked.length} 行`
+        : `扫描 ${targets.length} 行：解锁 ${unlocked.length} 行，${kept.length} 行未通过（保持禁用，原因见下）`,
+    })
     return
   }
 
@@ -5637,7 +6282,7 @@ async function handle(ctx, req, res) {
     // 面板自报名（自报名一致性校验用）：从插件自身 package.json 读，与部署目录比对
     let selfName = null
     try {
-      const selfPkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), 'package.json'), 'utf8'))
+      const selfPkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8'))
       selfName = typeof selfPkg.name === 'string' ? selfPkg.name : null
     } catch {}
     try {
@@ -5698,6 +6343,28 @@ async function handle(ctx, req, res) {
         steps.push(`自动迁移了 ${configMigrations.length} 处框架新版不再接受的预设字段（不迁移会让升级后预设挂载失败、服务拉不起来）`)
       }
     }
+    // 1.6) 不适配行预禁用（用户硬要求：「更新框架后所有不适配的必须先禁用」）。
+    // 适配门此前只有「执行侧」（读清单→锁启用→更新后解锁），**检测侧从未实现**：
+    // 那份 compat-pending.json 一直是人工/一次性脚本产出的（v0.3.25 起遗留至今）。
+    // 这里补上检测侧：升级脚本执行**前**扫描全部可开关行，判定 fail 的就地禁用 + 记入清单，
+    // 保证新框架 boot 时不会被某行 import 失败拖垮（loader 单行失败 = 整个服务起不来）。
+    let preflight = { disabled: [], skipped: [] }
+    if (hasUpdate) {
+      try {
+        preflight = await preflightDisableIncompatible({ ctx, profileDir, patchPath: findPatchPath(ctx), targetVersion: target })
+      } catch (error) {
+        steps.push(`不适配行预禁用失败（不阻塞升级，改由启动失败隔离兜底）：${error instanceof Error ? error.message : String(error)}`)
+      }
+      for (const row of preflight.disabled) {
+        steps.push(`已预先禁用不适配行：${row.rowId}（${row.moduleName}@${row.version ?? '?'}）— ${row.reason ?? '判定不兼容目标框架'}`)
+      }
+      if (preflight.disabled.length > 0) {
+        steps.push(`共预先禁用 ${preflight.disabled.length} 行：新框架启动不会再被它们拖垮；等它们发布适配版本后点「更新并适配」即可解锁`)
+      }
+      if (preflight.skipped.length > 0) {
+        steps.push(`另有 ${preflight.skipped.length} 行无法预判（受保护行/包信息读不到），保持启用，由升级后的启动失败隔离兜底`)
+      }
+    }
     // 2) 自动升级框架：运行中的服务锁着 dsh/lib 目录（EBUSY 无法原地替换），
     //    因此生成独立升级脚本（kill 服务 → npm 升级 → 失败回滚 → 拉起服务），后台执行。
     //    与 /restart 同款自守护模式：端口无监听会自动拉起，不会留下"服务起不来"。
@@ -5714,7 +6381,7 @@ async function handle(ctx, req, res) {
       // 避免"kill 后升级/拉起双双失败，服务永久 down"
       if (!existsSync(corepackJs) || binPath === null || !existsSync(binPath)) {
         steps.push(`升级已取消：无法定位 ${!existsSync(corepackJs) ? 'corepack（pnpm 通道）' : 'dsh bin.js'}（框架安装可能不完整），服务保持运行；请先修复框架再升级`)
-        sendJson(res, 200, { ok: true, current, latest, next, target, hasUpdate, upgraded: false, backupDir, configMigrations, steps, hints: steps })
+        sendJson(res, 200, { ok: true, current, latest, next, target, hasUpdate, upgraded: false, backupDir, configMigrations, preflight, steps, hints: steps })
         return
       }
       const profileDir2 = profileDir
@@ -5766,6 +6433,40 @@ async function handle(ctx, req, res) {
       const ps1 = join(tmpdir(), `fw-upgrade-${process.pid}.ps1`)
       const logFile = join(dshHome(), 'plugin-console', 'fw-upgrade.log')
       const stateFile = join(dshHome(), 'plugin-console', 'fw-upgrade-state.txt')
+      // 启动失败隔离所需的两个文件（升级脚本在服务起不来时调用）：
+      // ① 分析器：直接 import 本插件的 planQuarantine，避免把判断逻辑再写一份到 PowerShell；
+      // ② 候选行快照：升级发起时的可开关行（决策器据此把日志里的模块名映射回行 id）。
+      const qHelperPath = join(dshHome(), 'plugin-console', 'fw-analyze-boot.mjs')
+      const qCandidatesPath = join(dshHome(), 'plugin-console', 'fw-quarantine-candidates.json')
+      const qRecordPath = join(dshHome(), 'plugin-console', 'fw-quarantine.json')
+      let thirdPartyRows = []
+      try {
+        thirdPartyRows = listEntries(ctx)
+          .filter((e) => e.enabled && e.toggleable && e.rowId !== 'plugin-console'
+            && !CORE_PATCH_ROW_IDS.has(e.rowId)
+            && typeof e.moduleName === 'string' && !e.moduleName.startsWith('@deepseek-ai/'))
+          .map((e) => e.rowId)
+      } catch {}
+      try {
+        const selfLibUrl = new URL('./index.js', import.meta.url).href
+        const helperSource = [
+          '// 自动生成：启动失败隔离分析器（升级脚本在服务起不来时调用；逻辑在插件内，本文件只做转发）',
+          `import { planQuarantine } from ${JSON.stringify(selfLibUrl)}`,
+          "import { readFileSync } from 'node:fs'",
+          'const [logPath, candPath] = process.argv.slice(2)',
+          "let logText = ''",
+          "try { logText = readFileSync(logPath, 'utf8').split(/\\r?\\n/u).slice(-400).join('\\n') } catch {}",
+          'let candidates = []',
+          'try { candidates = JSON.parse(readFileSync(candPath, "utf8")) } catch {}',
+          'try { process.stdout.write(JSON.stringify(planQuarantine({ logText, candidates }))) } catch (error) { process.stdout.write(JSON.stringify({ error: String(error && error.message ? error.message : error) })) }',
+          '',
+        ].join('\n')
+        writeFileSync(qHelperPath, helperSource, 'utf8')
+        const candidateSnapshot = listEntries(ctx)
+          .filter((e) => typeof e.rowId === 'string' && e.rowId !== '')
+          .map((e) => ({ rowId: e.rowId, moduleName: e.moduleName, toggleable: e.toggleable === true, enabled: e.enabled === true }))
+        writeFileSync(qCandidatesPath, JSON.stringify(candidateSnapshot, null, 2), 'utf8')
+      } catch {}
       try { mkdirSync(dirname(logFile), { recursive: true }) } catch {}
       // PowerShell 字符串里反斜杠是字面量（无 \\ 转义）：JSON.stringify 产生的 \\ 必须还原为 \，
       // 否则所有路径无效（npm 调不起来、回滚无效、拉起失败——曾导致升级脚本空跑）
@@ -5776,18 +6477,28 @@ async function handle(ctx, req, res) {
         if (j === '""') return "''"
         return j.replace(/`/gu, '``').replace(/\$/gu, '`$')
       }
+      const patchFilePath = join(profileDir, 'cordis.patch.yml')
+      // 拉起服务的 PowerShell 片段（隔离重试用；与升级/回滚路径共用 relaunchPrelude 里的同一份实现）
+      const launchSnippet = (tag) => `if (-not $ok -and -not $started) { if (Invoke-DshRelaunch '${tag}') { $started = $true } }; Beat`
       const lines = [
         `$state = ${ps(stateFile)}`,
         `$log = ${ps(logFile)}`,
         "function Log($m) { try { Add-Content -Path $log -Value ((Get-Date -Format 'yyyy-MM-dd HH:mm:ss') + ' ' + $m) -Encoding UTF8 } catch {} }",
-        "function SetState($s, $m) { try { Set-Content -Path $state -Value ($s + '|' + $m) -Encoding UTF8 } catch {} }",
+        "function SetState($s, $m) {",
+        // v0.3.37：失败时把**崩溃前最后到达的阶段**一起写进状态文件（stage=…）——
+        // 否则界面只能看到 failed，把已经成功的步骤全打成 ✕（2026-09-11 用户实测就是这个观感：
+        // 框架其实升好了，卡片却整列红叉）。$script:stage 未设置时 [string] 会安全地变成空串。
+        "  try { if ($s -eq 'failed') { Set-Content -Path $state -Value ($s + '|' + $m + '|stage=' + [string]$script:stage) -Encoding UTF8; return } } catch {}",
+        "  try { if ($s -ne 'done' -and $s -ne 'idle') { $script:stage = $s }; Set-Content -Path $state -Value ($s + '|' + $m) -Encoding UTF8; Beat } catch {}",
+        "}",
+        relaunchPrelude({ nodePath, pluginDir: join(dirname(fileURLToPath(import.meta.url)), '..'), fwRoot, target, ps }),
         // 全局异常兜底（事故教训）：脚本任何未捕获异常都会无声死亡、状态永远卡住、服务没人拉起。
         // trap 捕获后：写 failed 状态 + 日志 + 尝试拉起服务 + 自删任务 + 退出
         "trap {",
         "  try { SetState 'failed' ('升级脚本异常终止：' + $_.Exception.Message) } catch {}",
         // 事故教训（2026-09-10）：只记消息无法定位是哪一行崩的 —— 连出错位置一起写日志
         "  try { Log ('升级脚本异常终止：' + $_.Exception.Message + ' @ ' + $_.InvocationInfo.PositionMessage) } catch {}",
-        `  try { $c = Get-NetTCPConnection -LocalPort ${port} -State Listen -ErrorAction SilentlyContinue; if (-not $c) { $bt = ''; try { $env:DSH_RESOLVE_ROOT = '${join(dirname(fileURLToPath(import.meta.url)), '..')}'; $bt = (& ${ps(nodePath)} -e "const path=require('path');const p=require.resolve('@deepseek-ai/dsh/package.json',{paths:[process.env.DSH_RESOLVE_ROOT]});console.log(path.join(path.dirname(p),'lib','bin.js'))" 2>$null | Select-Object -Last 1) } catch {}; if ($bt -ne '') { $launchLog = Join-Path (Split-Path $log) 'fw-relaunch.log'; try { Add-Content -Path $launchLog -Value ((Get-Date -Format 'yyyy-MM-dd HH:mm:ss') + ' 拉起(异常兜底): ' + $bt) -Encoding UTF8 } catch {}; Start-Process -FilePath 'cmd.exe' -ArgumentList @('/c', ('"' + ${ps(nodePath)} + '" "' + $bt + '" web >> "' + $launchLog + '" 2>&1')) -WindowStyle Hidden } } } catch {}`,
+        `  try { $c = Get-NetTCPConnection -LocalPort ${port} -State Listen -ErrorAction SilentlyContinue; if (-not $c) { [void](Invoke-DshRelaunch '异常兜底') } } catch {}`,
         `  schtasks /delete /f /tn ${taskName} 2>$null`,
         "  exit 1",
         "}",
@@ -5820,7 +6531,7 @@ async function handle(ctx, req, res) {
         `  $cacheDir = ''`,
         `  try {`,
         `    $npmrcFile = Join-Path $env:USERPROFILE '.npmrc'`,
-        `    if (Test-Path $npmrcFile) { $m = Select-String -Path $npmrcFile -Pattern '^cache\s*=\s*(.+)$' | Select-Object -Last 1; if ($m) { $cacheDir = $m.Matches[0].Groups[1].Value.Trim().Trim('"') } }`,
+        `    if (Test-Path $npmrcFile) { $m = Select-String -Path $npmrcFile -Pattern '^cache\\s*=\\s*(.+)$' | Select-Object -Last 1; if ($m) { $cacheDir = $m.Matches[0].Groups[1].Value.Trim().Trim('"') } }`,
         `  } catch {}`,
         `  if ($cacheDir -eq '') { $fb = Join-Path $env:APPDATA 'npm-cache'; if (Test-Path (Join-Path $fb '_logs')) { $cacheDir = $fb } }`,
         `  $npmOut = $log + '.npm.out.txt'`,
@@ -5956,8 +6667,8 @@ async function handle(ctx, req, res) {
         `  # 版本数值比较（修复：字符串比较在版本号位数变化时出错，如 0.1.10 < 0.1.9；PS5.1 兼容，不用三元运算符）`,
         `  function Compare-Version($a, $b) {`,
         `    if ($a -eq $b) { return 0 }`,
-        `    $pa = [regex]::Match($a, '^(\d+)\.(\d+)\.(\d+)(?:-(?:[a-z]+\.)?(\d+))?' )`,
-        `    $pb = [regex]::Match($b, '^(\d+)\.(\d+)\.(\d+)(?:-(?:[a-z]+\.)?(\d+))?' )`,
+        `    $pa = [regex]::Match($a, '^(\\d+)\\.(\\d+)\\.(\\d+)(?:-(?:[a-z]+\\.)?(\\d+))?' )`,
+        `    $pb = [regex]::Match($b, '^(\\d+)\\.(\\d+)\\.(\\d+)(?:-(?:[a-z]+\\.)?(\\d+))?' )`,
         `    if (-not $pa.Success -or -not $pb.Success) { return ($a.CompareTo($b)) }`,
         `    for ($i = 1; $i -le 4; $i++) {`,
         `      if ($pa.Groups[$i].Success) { $va = [int]$pa.Groups[$i].Value } else { $va = 2147483647 }`,
@@ -5973,15 +6684,15 @@ async function handle(ctx, req, res) {
         `    try { $topVer = (Get-Content $topPkgJson -Raw | ConvertFrom-Json).version } catch { continue }`,
         `    # 找 .pnpm 里该包的所有主目录（@deepseek-ai+dsh-<name>@<ver>_<hash> 或 @deepseek-ai+dsh-<name>@<ver>-rc.x_<hash>）`,
         `    $cands = Get-ChildItem -Path $pnpm -Directory -ErrorAction SilentlyContinue | Where-Object { $_.Name -match ('^@deepseek-ai\\\\+dsh-' + [regex]::Escape($name.Substring(4)) + '@') }`,
-        `    $best = $nil; $bestVer = ''`,
+        `    $best = $null; $bestVer = ''`,
         `    foreach ($c in $cands) {`,
         `      $inner = Join-Path $c.FullName ('node_modules\\@deepseek-ai\\' + $name)`,
         `      $pj = Join-Path $inner 'package.json'`,
         `      if (-not (Test-Path $pj)) { continue }`,
         `      try { $v = (Get-Content $pj -Raw | ConvertFrom-Json).version } catch { continue }`,
-        `      if ($best -eq $nil -or (Compare-Version $v $bestVer) -gt 0) { $bestVer = $v; $best = $inner }`,
+        `      if ($null -eq $best -or (Compare-Version $v $bestVer) -gt 0) { $bestVer = $v; $best = $inner }`,
         `    }`,
-        `    if ($best -eq $nil) { continue }`,
+        `    if ($null -eq $best) { continue }`,
         `    if ($bestVer -eq $topVer) { continue }`,
         `    try {`,
         `      $bak = $top.FullName + '.bak-' + $topVer`,
@@ -6078,10 +6789,63 @@ async function handle(ctx, req, res) {
         '$started = $false',
         `for ($i = 0; $i -lt 20; $i++) {`,
         `  try { $c = Get-NetTCPConnection -LocalPort ${port} -State Listen -ErrorAction SilentlyContinue; if ($c.Count -gt 0) { $ok = $true; break } } catch {}`,
-        `  if (-not $ok -and -not $started) { $binNow = ''; try { $env:DSH_RESOLVE_ROOT = '${join(dirname(fileURLToPath(import.meta.url)), '..')}'; $binNow = (& ${ps(nodePath)} -e "const path=require('path');const p=require.resolve('@deepseek-ai/dsh/package.json',{paths:[process.env.DSH_RESOLVE_ROOT]});console.log(path.join(path.dirname(p),'lib','bin.js'))" 2>$null | Select-Object -Last 1) } catch {}; if ($binNow -ne '' -and (Test-Path $binNow)) { $launchLog = Join-Path (Split-Path $log) 'fw-relaunch.log'; try { Add-Content -Path $launchLog -Value ((Get-Date -Format 'yyyy-MM-dd HH:mm:ss') + ' 拉起(升级后): ' + $binNow) -Encoding UTF8 } catch {}; Start-Process -FilePath 'cmd.exe' -ArgumentList @('/c', ('"' + ${ps(nodePath)} + '" "' + $binNow + '" web >> "' + $launchLog + '" 2>&1')) -WindowStyle Hidden; $started = $true; Log '已发起拉起服务（输出见 fw-relaunch.log）' } else { Log 'bin.js 缺失，跳过拉起' } }`,
+        `  if (-not $ok -and -not $started) { if (Invoke-DshRelaunch '升级后') { $started = $true } }; Beat`,
         '  Start-Sleep -Seconds 5',
         '}',
-        // 拉起失败不再只留提示（2026-09-04 教训）：自动全树回滚并再拉起一次
+        // ── 启动失败隔离（用户硬要求）：新框架起不来时先隔离肇事者再重试，不直接回滚 ──
+        // 判定逻辑全在 Node 决策器（fw-analyze-boot.mjs → planQuarantine）；这里只执行方案。
+        `function Invoke-Quarantine {`,
+        `  $helper = ${ps(qHelperPath)}`,
+        `  if (-not (Test-Path $helper)) { Log '隔离分析器缺失，跳过隔离'; return $false }`,
+        `  $logPath = Join-Path (Split-Path $log) 'fw-relaunch.log'`,
+        `  if (-not (Test-Path $logPath)) { $logPath = $log }`,
+        `  $out = ''`,
+        `  try { $out = (& ${ps(nodePath)} $helper $logPath ${ps(qCandidatesPath)} 2>$null | Select-Object -Last 1) } catch { Log ('隔离分析调用失败：' + $_.Exception.Message); return $false }`,
+        `  if (-not $out) { Log '隔离分析无输出'; return $false }`,
+        `  $plan = $null`,
+        `  try { $plan = $out | ConvertFrom-Json } catch { Log '隔离分析输出无法解析'; return $false }`,
+        `  $acted = $false; $doneP = @(); $doneR = @(); $mode = 'targeted'`,
+        `  foreach ($p in @($plan.presets)) {`,
+        `    if (-not $p.exists) { continue }`,
+        `    try { Rename-Item -LiteralPath $p.file -NewName ((Split-Path $p.file -Leaf) + '.broken-' + (Get-Date -Format 'yyyyMMdd-HHmmss')) -ErrorAction Stop; $doneP += $p.name; $acted = $true; Log ('已隔离预设：' + $p.name + '（改名 .broken，不再参与挂载）') } catch { Log ('预设隔离失败：' + $p.name + ' ' + $_.Exception.Message) }`,
+        `  }`,
+        `  foreach ($r in @($plan.rows)) {`,
+        `    try {`,
+        `      $has = Select-String -Path ${ps(patchFilePath)} -Pattern ('^- id: ' + [regex]::Escape($r) + '\\s*$') -Quiet -ErrorAction SilentlyContinue`,
+        `      if (-not $has) { Add-Content -Path ${ps(patchFilePath)} -Value ('- id: ' + $r) -Encoding UTF8; Add-Content -Path ${ps(patchFilePath)} -Value '  disabled: true' -Encoding UTF8 }`,
+        `      $doneR += $r; $acted = $true; Log ('已禁用不适配行：' + $r)`,
+        `    } catch { Log ('禁用行失败：' + $r + ' ' + $_.Exception.Message) }`,
+        `  }`,
+        `  if (-not $acted -and $plan.safeMode) {`,
+        `    $mode = 'safe-mode'`,
+        `    foreach ($r in @(${thirdPartyRows.length > 0 ? thirdPartyRows.map((r) => ps(r)).join(', ') : "''"})) {`,
+        `      try { $has = Select-String -Path ${ps(patchFilePath)} -Pattern ('^- id: ' + [regex]::Escape($r) + '\\s*$') -Quiet -ErrorAction SilentlyContinue; if (-not $has) { Add-Content -Path ${ps(patchFilePath)} -Value ('- id: ' + $r) -Encoding UTF8; Add-Content -Path ${ps(patchFilePath)} -Value '  disabled: true' -Encoding UTF8 }; $doneR += $r; $acted = $true } catch {}`,
+        `    }`,
+        `    if ($acted) { Log ('安全模式：已禁用 ' + $doneR.Count + ' 个第三方行，先让服务起来（适配后逐个解锁）') }`,
+        `  }`,
+        `  if ($acted) {`,
+        `    try {`,
+        `      $rec = [pscustomobject]@{ at = (Get-Date -Format 'yyyy-MM-dd HH:mm:ss'); mode = $mode; presets = $doneP; rows = $doneR; lines = $plan.lines } | ConvertTo-Json -Depth 4`,
+        `      Set-Content -Path ${ps(qRecordPath)} -Value $rec -Encoding UTF8`,
+        `    } catch {}`,
+        `  } else { Log '隔离分析未定位到可隔离对象' }`,
+        `  return $acted`,
+        `}`,
+        `if (-not $ok -and -not $script:rolledBack) {`,
+        `  Log '服务拉起失败 → 先做启动失败隔离（隔离肇事者后重试，不直接回滚）'`,
+        `  for ($q = 1; $q -le 3; $q++) {`,
+        `    if (-not (Invoke-Quarantine)) { Log ('第 ' + $q + ' 轮：未定位到可隔离对象，停止隔离'); break }`,
+        `    $ok = $false; $started = $false`,
+        `    for ($i = 0; $i -lt 12; $i++) {`,
+        `      try { $c = Get-NetTCPConnection -LocalPort ${port} -State Listen -ErrorAction SilentlyContinue; if ($c.Count -gt 0) { $ok = $true; break } } catch {}`,
+        `      ${launchSnippet('隔离后重试')}`,
+        `      Start-Sleep -Seconds 5`,
+        `    }`,
+        `    if ($ok) { Log ('第 ' + $q + ' 轮隔离后服务已起来（被隔离项可在控制台解锁）'); break }`,
+        `    Log ('第 ' + $q + ' 轮隔离后仍失败')`,
+        `  }`,
+        `}`,
+        // 隔离也救不回才回滚（2026-09-04 教训：自动全树回滚并再拉起一次）
         `if (-not $ok -and -not $script:rolledBack) {`,
         `  Log '服务拉起失败，尝试自动回滚到升级前版本…'`,
         `  Invoke-Rollback`,
@@ -6089,7 +6853,7 @@ async function handle(ctx, req, res) {
         `  $started = $false`,
         `  for ($i = 0; $i -lt 20; $i++) {`,
         `    try { $c = Get-NetTCPConnection -LocalPort ${port} -State Listen -ErrorAction SilentlyContinue; if ($c.Count -gt 0) { $ok = $true; break } } catch {}`,
-        `    if (-not $ok -and -not $started) { $binNow = ''; try { $env:DSH_RESOLVE_ROOT = '${join(dirname(fileURLToPath(import.meta.url)), '..')}'; $binNow = (& ${ps(nodePath)} -e "const path=require('path');const p=require.resolve('@deepseek-ai/dsh/package.json',{paths:[process.env.DSH_RESOLVE_ROOT]});console.log(path.join(path.dirname(p),'lib','bin.js'))" 2>$null | Select-Object -Last 1) } catch {}; if ($binNow -ne '' -and (Test-Path $binNow)) { $launchLog = Join-Path (Split-Path $log) 'fw-relaunch.log'; try { Add-Content -Path $launchLog -Value ((Get-Date -Format 'yyyy-MM-dd HH:mm:ss') + ' 拉起(回滚后): ' + $binNow) -Encoding UTF8 } catch {}; Start-Process -FilePath 'cmd.exe' -ArgumentList @('/c', ('"' + ${ps(nodePath)} + '" "' + $binNow + '" web >> "' + $launchLog + '" 2>&1')) -WindowStyle Hidden; $started = $true; Log '已发起拉起服务（回滚后，输出见 fw-relaunch.log）' } else { Log 'bin.js 缺失，跳过拉起' } }`,
+        `    if (-not $ok -and -not $started) { if (Invoke-DshRelaunch '回滚后') { $started = $true } }; Beat`,
         `    Start-Sleep -Seconds 5`,
         `  }`,
         `}`,
@@ -6098,6 +6862,8 @@ async function handle(ctx, req, res) {
       ].filter((l) => l !== '').join('\r\n')
       // 初始状态（备份完成、脚本即将执行）
       try { writeFileSync(stateFile, 'starting|备份配置完成，启动升级脚本…', 'utf8') } catch {}
+      // 版本检查缓存作废：升级后 [框架] 面板要立刻显示新版本（否则 5 分钟内还显示"可升级到…"）
+      fwCheckCache = null
       // UTF-8 BOM：powershell 5.1 按 ANSI 读无 BOM 文件，中文会乱码——加 BOM 保证解析正确。
       // 执行方式：schtasks 一次性计划任务（Task Scheduler 启动，独立于服务进程树/Job Object）——
       // 服务进程被杀时，其子进程（execFile/detached 的 powershell）会被 Job/进程树连带杀死，
@@ -6152,7 +6918,7 @@ async function handle(ctx, req, res) {
       '升级完成后请重启 DSH 服务生效——重启后 Hub 自动：备份新版本配置快照、重打框架补丁（issue #5 容错）、给出适配提示。',
       '官方配套组件（@deepseek-ai/*）随框架一起升级，请勿在市场单独更新。',
     ]
-    sendJson(res, 200, { ok: true, current, latest, next, target, hasUpdate, upgraded, backupDir, registryError, configMigrations, steps, hints })
+    sendJson(res, 200, { ok: true, current, latest, next, target, hasUpdate, upgraded, backupDir, registryError, configMigrations, preflight, steps, hints })
     return
   }
 
@@ -6177,7 +6943,11 @@ async function handle(ctx, req, res) {
       `$state = ${ps(stateFile)}`,
       `$log = ${ps(logFile)}`,
       "function Log($m) { try { Add-Content -Path $log -Value ((Get-Date -Format 'yyyy-MM-dd HH:mm:ss') + ' ' + $m) -Encoding UTF8 } catch {} }",
-      "function SetState($s, $m) { try { Set-Content -Path $state -Value ($s + '|' + $m) -Encoding UTF8 } catch {} }",
+      "function SetState($s, $m) {",
+      "  try { if ($s -eq 'failed') { Set-Content -Path $state -Value ($s + '|' + $m + '|stage=' + [string]$script:stage) -Encoding UTF8; return } } catch {}",
+      "  try { if ($s -ne 'done' -and $s -ne 'idle') { $script:stage = $s }; Set-Content -Path $state -Value ($s + '|' + $m) -Encoding UTF8; Beat } catch {}",
+      "}",
+      relaunchPrelude({ nodePath, pluginDir: join(dirname(fileURLToPath(import.meta.url)), '..'), fwRoot: rec.fwRoot, target: rec.from ?? '', ps }),
       "trap {",
       "  try { SetState 'failed' ('回滚脚本异常终止：' + $_.Exception.Message) } catch {}",
       `  schtasks /delete /f /tn ${taskName} 2>$null`,
@@ -6204,13 +6974,14 @@ async function handle(ctx, req, res) {
       `$started = $false`,
       `for ($i = 0; $i -lt 20; $i++) {`,
       `  try { $c = Get-NetTCPConnection -LocalPort ${port} -State Listen -ErrorAction SilentlyContinue; if ($c.Count -gt 0) { $ok = $true; break } } catch {}`,
-      `  if (-not $ok -and -not $started) { $binNow = ''; try { $env:DSH_RESOLVE_ROOT = '${join(dirname(fileURLToPath(import.meta.url)), '..')}'; $binNow = (& ${ps(nodePath)} -e "const path=require('path');const p=require.resolve('@deepseek-ai/dsh/package.json',{paths:[process.env.DSH_RESOLVE_ROOT]});console.log(path.join(path.dirname(p),'lib','bin.js'))" 2>$null | Select-Object -Last 1) } catch {}; if ($binNow -ne '' -and (Test-Path $binNow)) { $launchLog = Join-Path (Split-Path $log) 'fw-relaunch.log'; try { Add-Content -Path $launchLog -Value ((Get-Date -Format 'yyyy-MM-dd HH:mm:ss') + ' 拉起(回滚后): ' + $binNow) -Encoding UTF8 } catch {}; Start-Process -FilePath 'cmd.exe' -ArgumentList @('/c', ('"' + ${ps(nodePath)} + '" "' + $binNow + '" web >> "' + $launchLog + '" 2>&1')) -WindowStyle Hidden; $started = $true; Log '已发起拉起服务（回滚后，输出见 fw-relaunch.log）' } else { Log 'bin.js 缺失，跳过拉起' } }`,
+      `  if (-not $ok -and -not $started) { if (Invoke-DshRelaunch '回滚后') { $started = $true } }; Beat`,
       `  Start-Sleep -Seconds 5`,
       `}`,
       `if ($ok) { SetState 'done' ('已回滚到升级前版本 ${rec.from ?? '?'}，服务正常') ; Log '回滚完成，服务已恢复' } else { SetState 'failed' '回滚后服务拉起失败：请手动运行 node ${resolveDshBin() ?? '<bin>'} web' ; Log '回滚后拉起失败' }`,
       `schtasks /delete /f /tn ${taskName} 2>$null`,
     ].filter((l) => l !== '').join('\r\n')
     try { writeFileSync(stateFile, 'rollback|回滚脚本已启动…', 'utf8') } catch {}
+    fwCheckCache = null // 回滚后 [框架] 面板要立刻显示回滚到的版本
     writeFile(ps1, `\uFEFF${lines}`, 'utf8').then(
       () => {
         const ps1Posix = ps1.replace(/\\/gu, '/')
@@ -6363,7 +7134,7 @@ async function handle(ctx, req, res) {
     }
     installJobs.set(job.id, job)
     // 后台执行：请求立即返回，安装不受客户端断开/离开面板影响
-    void (kind === 'skill' ? runSkillInstallJob(job, ctx) : kind === 'suite' ? runSuiteInstallJob(job, ctx) : runInstallJob(job, ctx))
+    void (kind === 'skill' ? runSkillInstallJob(job) : kind === 'suite' ? runSuiteInstallJob(job, ctx) : runInstallJob(job, ctx))
     sendJson(res, 200, { ok: true, jobId: job.id, status: 'installing', kind })
     return
   }
@@ -6758,6 +7529,16 @@ async function handle(ctx, req, res) {
     // 不再依赖桌面端监督器（它并不总是会重启服务，曾导致用户需要重启电脑）。
     // 安全护栏（事故教训）：无法定位 dsh bin 或 bin.js 不存在时**拒绝重启**——
     // 避免"kill 后拉不起"（框架缓存损坏时常见），提示先修复框架安装。
+    //
+    // v0.3.43 事故修复（2026-09-11 用户实测「重启后服务没自己拉起来，只能手动重启」）：
+    // 现场证据＝一堆 Ready 僵尸任务（DSH-Restart-13804 / -31688 / -3744 / V2 / V3），
+    // 说明脚本杀完服务后**自己也被结束了**（与升级/回滚脚本同一个毛病：0xC000013A），
+    // 于是"检查端口→拉起"那几行根本没跑到；而且原来只等 3 秒、只查一次端口。
+    // 现在改成三层保险：
+    //   ① 主脚本：等到端口真正空出来（最多 20 秒轮询）→ 拉起 → 重试 3 次 → 写 console-restart.log
+    //   ② **守护任务**（关键）：主脚本动手**之前**就注册一个每分钟跑一次的独立计划任务，
+    //      服务被杀、主脚本被杀都不影响它；端口起来了它自删，起不来就继续拉（最多 5 次）
+    //   ③ bin 解析用与升级/回滚同一套多级回退（node resolve → .pnpm → 顶层链接）
     const port = webPort(ctx)
     const binPath = resolveDshBin()
     const nodePath = process.execPath
@@ -6766,37 +7547,92 @@ async function handle(ctx, req, res) {
       return
     }
     if (process.platform === 'win32') {
-      const ps1 = join(tmpdir(), `console-restart-${process.pid}.ps1`)
+      const consoleDir = join(dshHome(), 'plugin-console')
+      try { mkdirSync(consoleDir, { recursive: true }) } catch {}
+      const restartLog = join(consoleDir, 'console-restart.log')
+      const fwRoot = resolveFrameworkRootNodeModules(dirname(dirname(binPath)))
+      let installedVersion = ''
+      try { installedVersion = JSON.parse(readFileSync(join(dirname(dirname(binPath)), 'package.json'), 'utf8')).version ?? '' } catch {}
+      const ps = (s) => {
+        const j = JSON.stringify(String(s)).replace(/\\\\/gu, '\\')
+        if (j === '""') return "''"
+        return j.replace(/`/gu, '``').replace(/\$/gu, '`$')
+      }
+      const prelude = relaunchPrelude({ nodePath, pluginDir: join(dirname(fileURLToPath(import.meta.url)), '..'), fwRoot: fwRoot ?? dirname(dirname(binPath)), target: installedVersion, ps })
       const taskName = `DSH-Restart-${process.pid}`
-      const lines = [
-        `Stop-Process -Id ${process.pid} -Force -ErrorAction SilentlyContinue`,
-        'Start-Sleep -Seconds 3',
-        '$ok = $false',
-        `try { $c = Get-NetTCPConnection -LocalPort ${port} -State Listen -ErrorAction SilentlyContinue; $ok = $c.Count -gt 0 } catch {}`,
-        `if (-not $ok) { Start-Process -FilePath ${JSON.stringify(nodePath)} -ArgumentList ${JSON.stringify(binPath)},'web' -WindowStyle Hidden }`,
-        // 任务自删：否则 DSH-Restart-* 残留（服务重启后任务列表里一堆 Ready 僵尸任务）
+      const guardName = `DSH-RestartGuard-${process.pid}`
+      const guardCount = join(consoleDir, `restart-guard-${process.pid}.count`)
+      const killLine = `Stop-Process -Id ${process.pid} -Force -ErrorAction SilentlyContinue`
+      // ① 主脚本：等端口空 → 拉起（重试 3 次）
+      const mainLines = [
+        `$log = ${ps(restartLog)}`,
+        `$state = ${ps(join(consoleDir, 'fw-upgrade-state.txt'))}`,
+        `function Log($m) { try { Add-Content -Path $log -Value ((Get-Date -Format 'yyyy-MM-dd HH:mm:ss') + ' ' + $m) -Encoding UTF8 } catch {} }`,
+        prelude,
+        `Log ('重启脚本启动：目标端口 ${port}，bin=' + ${ps(binPath)})`,
+        killLine,
+        // 等到端口真正空出来（原实现只 sleep 3 秒、只查一次 —— 端口还占着就误判"已有人监听"而跳过拉起）
+        `$free = $false`,
+        `for ($i = 0; $i -lt 20; $i++) { Start-Sleep -Seconds 1; try { $c = Get-NetTCPConnection -LocalPort ${port} -State Listen -ErrorAction SilentlyContinue; if (-not $c -or $c.Count -eq 0) { $free = $true; break } } catch { $free = $true; break } }`,
+        `Log ('端口 ' + ${ps(String(port))} + ' 状态：' + $(if ($free) { '已释放' } else { '仍被占用（可能被其它实例占着）' }))`,
+        `$up = $false`,
+        `for ($a = 1; $a -le 3; $a++) {`,
+        `  [void](Invoke-DshRelaunch ('重启第 ' + $a + ' 次'))`,
+        `  for ($w = 0; $w -lt 8; $w++) { Start-Sleep -Seconds 2; try { $c = Get-NetTCPConnection -LocalPort ${port} -State Listen -ErrorAction SilentlyContinue; if ($c -and $c.Count -gt 0) { $up = $true; break } } catch {} }; if ($up) { break }`,
+        `}`,
+        `if ($up) { Log '服务已重新监听，重启完成' } else { Log '三次拉起后端口仍未监听：守护任务会继续尝试（输出见 fw-relaunch.log）' }`,
         `schtasks /delete /f /tn ${taskName} 2>$null`,
       ]
-      // schtasks 计划任务执行（独立于服务进程树/Job Object）：服务被杀时脚本不被连带杀死，
-      // 否则「重启」会在 kill 后无人拉起（历史重启偶发崩溃的根因之一）
-      writeFile(ps1, lines.join('\r\n'), 'utf8').then(
-        () => {
-          const ps1Posix = ps1.replace(/\\/gu, '/')
-          // 无引号 /tr（重要）：Task Scheduler 对带引号命令的解析会把 Command 拆坏成
-          // `"powershell ... -File \"`（非有效可执行文件）——任务显示 Ready、/run 报 SUCCESS
-          // 但永不执行（曾导致升级/重启脚本反复"已启动"却不动作、服务不停止）。实测无引号
-          // 格式（exe 与脚本路径均无空格时）任务正常执行、脚本完整跑通。仅当脚本路径含空格
-          // 时才退回带引号格式（schtasks 引号解析在服务 execFile 上下文不可靠，此时宁可用它）。
-          const tr = / /.test(ps1Posix)
-            ? `"powershell -NoProfile -WindowStyle Hidden -ExecutionPolicy Bypass -File \\"${ps1Posix}\\""`
-            : `C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe -NoProfile -WindowStyle Hidden -ExecutionPolicy Bypass -File ${ps1Posix}`
-          execFile('schtasks.exe', ['/create', '/f', '/tn', taskName, '/tr', tr, '/sc', 'once', '/st', '00:00'], { windowsHide: true }, (error) => {
-            if (error) {
-              execFile('powershell.exe', ['-NoProfile', '-WindowStyle', 'Hidden', '-ExecutionPolicy', 'Bypass', '-File', ps1], { windowsHide: true, detached: true, stdio: 'ignore' }, () => {})
-              return
-            }
-            execFile('schtasks.exe', ['/run', '/tn', taskName], { windowsHide: true }, () => {})
-          })
+      // ② 守护任务：独立于主脚本与服务进程，端口不起来就一直拉（最多 5 次）
+      const guardLines = [
+        `$log = ${ps(restartLog)}`,
+        `$state = ${ps(join(consoleDir, 'fw-upgrade-state.txt'))}`,
+        `function Log($m) { try { Add-Content -Path $log -Value ((Get-Date -Format 'yyyy-MM-dd HH:mm:ss') + ' [guard] ' + $m) -Encoding UTF8 } catch {} }`,
+        prelude,
+        `$c = $null`,
+        `try { $c = Get-NetTCPConnection -LocalPort ${port} -State Listen -ErrorAction SilentlyContinue } catch {}`,
+        `if ($c -and $c.Count -gt 0) { Log '服务已在监听，守护任务收工'; Remove-Item ${ps(guardCount)} -Force -ErrorAction SilentlyContinue; schtasks /delete /f /tn ${guardName} 2>$null; schtasks /delete /f /tn ${taskName} 2>$null; exit 0 }`,
+        `$n = 0`,
+        `try { $n = [int](Get-Content ${ps(guardCount)} -Raw -ErrorAction SilentlyContinue) } catch { $n = 0 }`,
+        `$n = $n + 1`,
+        `if ($n -gt 5) { Log ('已尝试 ' + ($n - 1) + ' 次仍拉不起来，放弃并自删（请手动启动，或看 fw-relaunch.log / console-restart.log）'); schtasks /delete /f /tn ${guardName} 2>$null; exit 0 }`,
+        `try { Set-Content -Path ${ps(guardCount)} -Value ([string]$n) -Encoding UTF8 } catch {}`,
+        `Log ('端口 ' + ${ps(String(port))} + ' 无监听，第 ' + $n + ' 次拉起')`,
+        `[void](Invoke-DshRelaunch ('守护第 ' + $n + ' 次'))`,
+      ]
+      const ps1 = join(tmpdir(), `console-restart-${process.pid}.ps1`)
+      const guardPs1 = join(tmpdir(), `console-restart-guard-${process.pid}.ps1`)
+      const scheduleFor = (file, name, scheduleArgs) => {
+        const posix = String(file).replace(/\\/gu, '/')
+        // 无引号 /tr（重要）：Task Scheduler 对带引号命令的解析会把 Command 拆坏成
+        // `"powershell ... -File \"`（非有效可执行文件）——任务显示 Ready、/run 报 SUCCESS
+        // 但永不执行（曾导致升级/重启脚本反复"已启动"却不动作、服务不停止）。实测无引号
+        // 格式（exe 与脚本路径均无空格时）任务正常执行、脚本完整跑通。仅当脚本路径含空格
+        // 时才退回带引号格式（schtasks 引号解析在服务 execFile 上下文不可靠，此时宁可用它）。
+        const tr = / /.test(posix)
+          ? `"powershell -NoProfile -WindowStyle Hidden -ExecutionPolicy Bypass -File \\"${posix}\\""`
+          : `C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe -NoProfile -WindowStyle Hidden -ExecutionPolicy Bypass -File ${posix}`
+        return new Promise((resolve) => {
+          execFile('schtasks.exe', ['/create', '/f', '/tn', name, '/tr', tr, ...scheduleArgs], { windowsHide: true }, (error) => resolve(error ?? null))
+        })
+      }
+      Promise.all([
+        writeFile(ps1, `\uFEFF${mainLines.join('\r\n')}`, 'utf8'),
+        writeFile(guardPs1, `\uFEFF${guardLines.join('\r\n')}`, 'utf8'),
+      ]).then(
+        async () => {
+          // 守护任务先注册（每分钟一次，独立于服务进程树）——主脚本被杀也有它兜底
+          const guardError = await scheduleFor(guardPs1, guardName, ['/sc', 'minute', '/mo', '1'])
+          const mainError = await scheduleFor(ps1, taskName, ['/sc', 'once', '/st', '00:00'])
+          if (mainError !== null) {
+            // schtasks 不可用：退回 detached 直接执行主脚本（守护任务仍可能已建）
+            execFile('powershell.exe', ['-NoProfile', '-WindowStyle', 'Hidden', '-ExecutionPolicy', 'Bypass', '-File', ps1], { windowsHide: true, detached: true, stdio: 'ignore' }, () => {})
+            return
+          }
+          execFile('schtasks.exe', ['/run', '/tn', taskName], { windowsHide: true }, () => {})
+          if (guardError !== null) {
+            try { writeFileSync(restartLog, `[warn] 守护任务注册失败（${guardError.message}），仅靠主脚本重启\n`, { flag: 'a' }) } catch {}
+          }
         },
         () => {},
       )