@noob-stupid/dsh-plugin-console 0.5.94 → 0.5.95

package/lib/server/domain/framework-cleanup.js

@@ -423,4 +423,55 @@ function readRollbackReferenced({ home = undefined, deps = {} } = {}) {
     return [raw?.checkpointDir, raw?.cliBackupDir].filter((p) => typeof p === 'string' && p !== '')
   } catch { return [] }
 }
-export { cleanFrameworkBackups, cleanFrameworkTopLevel, dirSizeBytes, isLinkEntry, readRollbackReferenced, removeLinkSafe, reportFrameworkEntities, resolveFrameworkLayout, verifyFrameworkTreeResolvable }
+/**
+ * 升级失败后的补偿：把 `<name>.stale-<ver>-<ts>` **改回真名** —— 但只在真名缺失时。
+ *
+ * 背景（2026-10-28 真机）：升级在「拉起」阶段失败，向上层报「自动回滚未生效」，而清扫步
+ * 已经把 10 个框架包改名成 `.stale-*`、真名处什么都没有。结果框架起不来：
+ *   `Cannot find package '@deepseek-ai/cordis' imported from @deepseek-ai/dsh-app-boot`
+ * 那一刻用户只能手改目录名 —— 这个函数就是那条手改的自动化版本。
+ *
+ * 纪律：
+ *   · **绝不删除**任何东西（只 rename）；
+ *   · **真名已存在就跳过**（宁可不动，也不覆盖可能更新的目录）；
+ *   · 幂等：重复调用第二次什么都不做；
+ *   · 只看 `@deepseek-ai` 这一层（顶层 scope），不递归、不碰 `.pnpm` 内部。
+ */
+function restoreStaleBackups({ scopeDir, deps = {} } = {}) {
+  const exists = deps.exists ?? existsSync
+  const readdir = deps.readdir ?? ((dir) => readdirSync(dir, { withFileTypes: true }))
+  const rename = deps.rename ?? renameSync
+  const restored = []
+  const skipped = []
+  const failed = []
+  if (typeof scopeDir !== 'string' || scopeDir === '') return { ok: false, restored, skipped, failed, problem: '没有给 scopeDir' }
+  let entries = []
+  try { entries = readdir(scopeDir) } catch (error) {
+    const missing = error?.code === 'ENOENT'
+    return { ok: missing, restored, skipped, failed, problem: missing ? null : '列不出目录：' + errText(error) }
+  }
+  for (const entry of entries) {
+    const name = typeof entry === 'string' ? entry : entry?.name
+    const isDir = typeof entry === 'string' ? true : entry?.isDirectory?.() === true
+    if (typeof name !== 'string' || !isDir || !name.includes('.stale-')) continue
+    const real = name.replace(/\.stale-.*$/u, '')
+    if (real === '' || real === name) continue
+    const target = join(scopeDir, real)
+    const source = join(scopeDir, name)
+    let targetExists = false
+    try { targetExists = exists(target) } catch { targetExists = false }
+    if (targetExists) {
+      skipped.push({ name, real, reason: 'real-name-exists' })
+      continue
+    }
+    try {
+      rename(source, target)
+      restored.push({ from: name, to: real })
+    } catch (error) {
+      failed.push({ name, real, error: errText(error) })
+    }
+  }
+  return { ok: failed.length === 0, restored, skipped, failed, problem: null }
+}
+
+export { cleanFrameworkBackups, cleanFrameworkTopLevel, dirSizeBytes, isLinkEntry, readRollbackReferenced, removeLinkSafe, reportFrameworkEntities, resolveFrameworkLayout, restoreStaleBackups, verifyFrameworkTreeResolvable }

package/lib/server/domain/framework-relaunch.js

@@ -0,0 +1,462 @@
+// L1 · domain —— 自动拉起服务 + 「拉起失败之后怎么办」（2026-10-28 真机事故，两轮修复）
+//
+// ── 第一轮现场（`<DSH_HOME>/plugin-console/fw-upgrade.log` 原文）─────────────────
+//   16:23:25 结构校验通过 / 框架本体升级完成 / 顶层可见版本校验通过
+//   16:30:18 服务拉起失败 → 启动失败隔离 → 隔离分析无输出 → 尝试自动回滚
+//   16:30:33 全树回滚完成：恢复 62 个版本包 + 顶层 scope
+// 而 `fw-relaunch.log` 里**只有一行时间戳 + bin 路径，没有任何子进程输出**。
+// ⇒ 框架本体是好的（CLI 手动跑得出版本号，之后手动 `node …\lib\bin.js web --no-open` 也能起），
+//   坏的是「自动拉起」这条路径；旧链条「拉起失败 → 立刻回滚」把一次**成功**的升级扔掉了。
+//
+// ── 第二轮现场（第一轮改过之后）暴露三个问题 ─────────────────────────────────
+//   18:21:37 已发起拉起（升级后，PID 15832，最多等 30 秒自证）
+//   18:22:08 拉起成功（升级后）：进程已存活 30 秒（端口尚未监听）      ← ① 判据太松
+//   18:23:55 服务拉起失败 → 隔离 → 隔离分析无输出                    ← ② 成功后**又查一次**
+//   18:23:56 回滚判定器不可用 → 保守回滚 → rollback                  ← ③ 把已起的服务回滚了
+// ① 「进程存活」不能算成功：**成功判据只有一个 —— 端口开始监听**（沿用调用方 webPort）。
+//    进程存活只是"仍在启动中"，到上限记为 `still-starting-timeout`（不确定，不是失败）。
+// ② 已经判成功之后**不许再做任何就绪检查、不许再判失败**：真把 `$ok = $true` 传出去并立刻收尾。
+//    直接来源是升级脚本"重启服务生效"那段端口轮询循环里的一行：
+//      `if (-not $ok -and -not $started) { if (Invoke-DshRelaunch '升级后') { $started = $true } }`
+//    —— 拉起的"成功"只被记成"别再拉起"（$started），没有记成"服务已经好了"（$ok），
+//    于是循环又空转约 95 秒等端口，然后隔离/判定链路把已经起来的服务判死并回滚。
+//    现在：Note-Relaunch 在"端口已监听"时置 `$script:relaunchListening`，调用点据此立刻 `$ok = $true; break`，
+//    隔离块与判定块都在 `if (-not $ok …)` 里 ⇒ 成功之后一个字节的后续就绪检查都不会跑。
+// ③ 自动回滚**取消**（用户原话：「他拉起来了后就不用管了啊……回滚需要人工点才行吧」）：
+//    拉起失败 / 超时 / 无输出 ⇒ 一律写 `ready|框架已就位，自动拉起失败：<原因>；请手动运行
+//    node "<真实 bin>" web --no-open，或点「回滚到上一版」`，**不自动回滚**（回滚是人工动作）。
+//    唯一保留自动回滚的情形：失败原因里出现**明确的框架树损坏证据**（缺包 / 模块解析失败 /
+//    缺 bin.js / 缺 package.json）—— 那种树留着也起不来，回滚才是对的。
+// 缺陷 B（同一次真机）：`cmd /c call "node" … web > out 2> err` 在 schtasks 任务环境里输出仍为零
+//   ⇒ 换掉 cmd 重定向，改由 **node 自己当拉起器**（`fw-launch.mjs`：把子进程 stdout/stderr
+//   直接接成文件 fd，detached 启动）。判定结论也不再走 stdout（同环境下既有的
+//   `隔离分析无输出` 是同一个病），改成**写判定文件**、ps1 读文件。
+//
+// 判据一行都不许写进 ps1 字符串里（否则测不到、还会分叉）。分工：
+//   · judgeRelaunchFailure()          「失败原因文本 → 是否回滚」的唯一纯函数
+//   · relaunchFallbackVerdict()       判定器不可用时的兜底（与上面同规则：**默认不回滚**）
+//   · relaunchLauncherSource()        生成 `fw-launch.mjs`（node 拉起器：fd 重定向 + detached + 状态代理）
+//   · relaunchVerdictHelperSource()   生成判定器转发脚本（结论写文件）
+//   · relaunchProbeHelpers()/relaunchInvoke()/relaunchVerdictBlock()  生成 ps1 片段
+
+/**
+ * 「框架树真的坏了」的特征串（命中才自动回滚）。
+ *
+ * 2026-10-28 现场校准（用户真机证据，比猜测更硬）：
+ *   · 用户**手动**跑 `node "…\@deepseek-ai\dsh\lib\bin.js" web --no-open` —— **能正常起来**
+ *     （当前 web 就靠它跑着，3080 在监听）。启动命令 / profile / 这套插件本身都是好的；
+ *   · 脚本拉起失败时 `fw-relaunch.log` **一个字都没有** —— 若真是插件 import 失败，
+ *     node 会把 `Cannot find package …` 打到 stderr。没有痕迹 ⇒ 是"子进程没活下来 / 看不到"，
+ *     不是加载崩溃 ⇒ **不能因为"没输出"就回滚**。
+ * 所以判据必须**窄**：只有明确的"模块解析失败 / 关键文件缺失"才算框架树坏。
+ * 反过来，这些**不许**命中（否则好框架会被回滚掉）：
+ *   · `EADDRINUSE`（端口被占 —— 常见于上一个实例还没退干净）、`listen EACCES`、`npm ERR!`
+ *   · `child-exited-early` / `still-starting-timeout`（秒退/超时但没有错误文本）
+ */
+const TREE_DAMAGE_MARKERS = [
+  'Cannot find package',
+  'ERR_MODULE_NOT_FOUND',
+  'MODULE_NOT_FOUND',
+  'Cannot find module',
+  'ERR_PACKAGE_PATH_NOT_EXPORTED',
+  '找不到 dsh 的 bin.js',
+  'package.json 不存在',
+]
+
+/** 状态/日志里给用户的手动启动命令（用户真机就是这么救回来的：`--no-open` 不弹浏览器）。 */
+const MANUAL_URL_FLAGS = 'web --no-open'
+
+/** 拉起器完全没留下输出、判定器也没产出结论时，判定用的原因文本（不含任何树损坏特征）。 */
+const NO_OUTPUT_REASON = '未捕获到输出（拉起器没有留下 stdout/stderr，判定器也没有产出结论）'
+
+/** `Invoke-DshRelaunch` 的三种结局前缀（判定器据此区分）。 */
+const REASON_PREFIX = {
+  stillStarting: 'still-starting-timeout', // 到上限仍没监听端口，但进程还活着 → 不确定，不回滚
+  exitedEarly: 'child-exited-early', // <5 秒就退出
+  exited: 'child-exited',
+  spawnFailed: 'spawn-failed',
+  launcherMissing: 'launcher-missing',
+  noBin: '找不到 dsh 的 bin.js',
+}
+
+/** 原因摘录的最大长度（状态文件是单行 `status|message`，太长会把界面撑爆）。 */
+const REASON_EXCERPT_LIMIT = 240
+
+/** 由真实 bin 路径拼手动启动命令（拿不到路径时返回空串 —— 绝不编一个假路径）。 */
+function manualRelaunchCommand(binPath) {
+  const bin = typeof binPath === 'string' ? binPath.trim() : ''
+  if (bin === '') return ''
+  return `node "${bin}" ${MANUAL_URL_FLAGS}`
+}
+
+/**
+ * 把任意输入归一成"可以写进状态文件/日志的一行文本"。
+ * 关键点：状态文件格式是 `status|message`，且会被 `/framework-upgrade-status` 按 `|` 切分，
+ * 所以原因里的换行与竖线必须先抹平（否则 message 会被切碎、stage= 判定也会错位）。
+ */
+function flatReason(value, limit = REASON_EXCERPT_LIMIT) {
+  const raw = typeof value === 'string' ? value : (value === null || value === undefined ? '' : String(value))
+  const flat = raw.replace(/\s+/gu, ' ').replace(/\|/gu, '/').trim()
+  if (flat === '') return ''
+  return flat.length > limit ? `${flat.slice(0, limit)}…` : flat
+}
+
+/**
+ * 保留框架时的状态行（三处复用：超时 / 拉起失败 / 判定器不可用）。
+ * 用户原话：拉起失败就别管了，**回滚要人工点** ⇒ 文案点明两条人工出路。
+ */
+function keepStatusText({ reasonPhrase, binPath }) {
+  const cmd = manualRelaunchCommand(binPath)
+  const tail = cmd === ''
+    ? '请手动启动 DSH（本机 bin.js 路径未解析出来），或点「回滚到上一版」'
+    : `请手动运行 ${cmd}，或点「回滚到上一版」`
+  return `框架已就位，${reasonPhrase}；${tail}`
+}
+
+/** 统一的判定返回形状（各分支都走它，避免字段漏写）。 */
+function verdictOf(kind, { rollback, treeDamaged = false, reasonExcerpt = '', status = null, manualCommand = null }) {
+  return { verdict: kind, rollback, treeDamaged, reasonExcerpt, status, manualCommand }
+}
+
+/** 保留分支的统一产物（超时 / 失败 / 未验证 都走它）。 */
+function keepVerdict({ reasonPhrase, binPath, reasonExcerpt }) {
+  const cmd = manualRelaunchCommand(binPath)
+  return verdictOf('keep', {
+    rollback: false,
+    reasonExcerpt,
+    status: keepStatusText({ reasonPhrase, binPath }),
+    manualCommand: cmd === '' ? null : cmd,
+  })
+}
+
+/**
+ * **唯一**的「拉起失败 → 是否回滚」判据（纯函数，无 IO、无宿主）。
+ *
+ * 规则（顺序即优先级，tests/test-framework-relaunch-verdict.mjs 逐条钉死）：
+ *   ① 没有失败原因（空/空白）→ ok：不需要判定，什么都不做（幂等边界）；
+ *   ② 原因里**有明确的框架树损坏证据** → rollback（唯一的自动回滚情形：那种树留着也起不来）；
+ *   ③ `still-starting-timeout` → keep（端口没通但进程还活着 = 不确定，不是坏树）；
+ *   ④ 其余一切（秒退 / 无输出 / 结构校验没过…）→ keep：框架保留 + 手动命令 + 提示可人工回滚。
+ *      —— 2026-10-28 用户定案「拉起失败就别管了，回滚要人工点」，所以这里**不再**保守回滚。
+ *
+ * @param {object} p
+ * @param {string|null} [p.reason] 拉起失败原因（Invoke-DshRelaunch 的返回值）
+ * @param {boolean} [p.structureVerified] 结构校验是否通过（留作记录/告警，不再决定是否回滚）
+ * @param {boolean} [p.topLevelVerified]  顶层可见版本校验是否通过（同上）
+ * @param {string} [p.binPath]  真实的 dsh bin.js 路径（拼手动启动命令用；空串 = 没解析出来）
+ * @returns {{ verdict: 'ok'|'rollback'|'keep', rollback: boolean, treeDamaged: boolean,
+ *   reasonExcerpt: string, status: string|null, manualCommand: string|null }}
+ */
+function judgeRelaunchFailure({ reason = '', structureVerified = false, topLevelVerified = false, binPath = '' } = {}) {
+  const reasonExcerpt = flatReason(reason)
+  // ① 没有原因 = 没有失败要判（调用方只在拉起失败时问，但纯函数自己也要幂等）
+  if (reasonExcerpt === '') return verdictOf('ok', { rollback: false })
+  // ② 框架树损坏证据（**唯一**的自动回滚情形）
+  if (TREE_DAMAGE_MARKERS.some((marker) => reasonExcerpt.includes(marker))) {
+    return verdictOf('rollback', { rollback: true, treeDamaged: true, reasonExcerpt })
+  }
+  // ③ 端口没通但进程还活着 = 不确定 → 保留（真机 18:24:39 那次就是再等一会儿端口才通的）
+  if (reasonExcerpt.startsWith(REASON_PREFIX.stillStarting)) {
+    return keepVerdict({ reasonPhrase: `自动拉起超时，端口在等待上限内未监听（${reasonExcerpt}）`, binPath, reasonExcerpt })
+  }
+  // ④ 其余一律保留：回滚改成人工动作（点了「回滚到上一版」才回滚）
+  const unverified = structureVerified === true && topLevelVerified === true
+    ? ''
+    : '（注意：结构校验/顶层版本校验没有都通过，框架是否完整未能确认）'
+  return keepVerdict({ reasonPhrase: `自动拉起失败：${reasonExcerpt}${unverified}`, binPath, reasonExcerpt })
+}
+
+/**
+ * 「判定器不可用」时的兜底结论 —— **必须与 judgeRelaunchFailure 同规则**：
+ * 把 `NO_OUTPUT_REASON` 喂进同一个纯函数（测试断言两者逐字段相等）。
+ * 真机 18:23:56 的"保守回滚"就是错的：拿不到输出 ≠ 框架坏了。
+ */
+function relaunchFallbackVerdict({ structureVerified = false, topLevelVerified = false, binPath = '' } = {}) {
+  return judgeRelaunchFailure({ reason: NO_OUTPUT_REASON, structureVerified, topLevelVerified, binPath })
+}
+
+/**
+ * 生成 **node 拉起器** `fw-launch.mjs`（2026-10-28 第二轮：绕开 cmd/schtasks 的重定向）。
+ *
+ * 为什么不让 ps1 直接 `Start-Process node bin.js web > out`：
+ *   · `cmd /c "…"` 的行首引号剥离会让整段重定向失效（真机 18:21：进程活了 30 秒，
+ *     `.out/.err` 一个字都没有）；
+ *   · `Start-Process -RedirectStandard*` 在本仓记录过「schtasks 下子进程启动即退出」。
+ * 拉起器做三件事（全部由 Node 自己的 fd 完成，跟 cmd 无关）：
+ *   ① `openSync(outFile,'a')` / `openSync(errFile,'a')` 直接当子进程的 stdio；
+ *   ② `spawn(nodePath, [bin,'web'], { detached: true, stdio: ['ignore', outFd, errFd], windowsHide: true })`
+ *      —— detached 保证计划任务/脚本退出后服务继续活着；
+ *   ③ 自己留在前台当**状态代理**：子进程退出就 `process.exit(child.code)`，并把
+ *      `{event, pid, code, signal, error}` 写进 status 文件。
+ *      这里刻意**不 unref()+立即退出**（虽然那样更省一个进程）：一旦拉起器先退，ps1 的
+ *      `-PassThru` 句柄立刻 `HasExited`，就再也分不清"服务在启动"还是"服务崩了"，退出码也没了。
+ *      detached 已经保证服务不受拉起器生死影响 —— 那正是必须保住的那件事。
+ */
+function relaunchLauncherSource() {
+  return [
+    '// 自动生成：DSH 服务拉起器（升级/回滚脚本用 node 启动它；逻辑见 domain/framework-relaunch.js）',
+    "import { spawn } from 'node:child_process'",
+    "import { closeSync, openSync, writeFileSync } from 'node:fs'",
+    'const [nodePath, binPath, outFile, errFile, statusFile] = process.argv.slice(2)',
+    'const say = (obj) => { try { writeFileSync(statusFile, JSON.stringify(obj), "utf8") } catch {} }',
+    'if (!nodePath || !binPath || !outFile || !errFile || !statusFile) { say({ event: "error", error: "拉起器参数不足" }); process.exit(2) }',
+    'let outFd = null',
+    'let errFd = null',
+    'try { outFd = openSync(outFile, "a"); errFd = openSync(errFile, "a") } catch (error) { say({ event: "error", error: "打不开输出文件：" + String(error && error.message ? error.message : error) }); process.exit(3) }',
+    'let child = null',
+    'try {',
+    '  child = spawn(nodePath, [binPath, "web"], { detached: true, stdio: ["ignore", outFd, errFd], windowsHide: true })',
+    '} catch (error) { say({ event: "error", error: "spawn 抛错：" + String(error && error.message ? error.message : error) }); process.exit(4) }',
+    'say({ event: "spawned", pid: child.pid ?? null, at: Date.now() })',
+    'child.on("error", (error) => { say({ event: "error", pid: child.pid ?? null, error: String(error && error.message ? error.message : error) }); process.exit(5) })',
+    'child.on("exit", (code, signal) => {',
+    '  say({ event: "exited", pid: child.pid ?? null, code, signal })',
+    '  try { closeSync(outFd); closeSync(errFd) } catch {}',
+    '  process.exit(typeof code === "number" ? code : 1)',
+    '})',
+    '',
+  ].join('\n')
+}
+
+/**
+ * 生成「读文件尾部」+「端口监听」两个小助手（PowerShell，整段作为一个数组元素展开）。
+ *
+ * · `Get-TailText`：把某文件的尾部压成一行、只留最后 600 字符 —— 失败原因要短到能进日志与状态文件。
+ *   刻意**不用 `Test-Path` 探变量**（既有断言要求拉起助手块里的 Test-Path 只出现在
+ *   Resolve-DshBin 的归一化变量上），直接 `Get-Content -ErrorAction SilentlyContinue`。
+ * · `Test-RelaunchPort`：沿用调用方（webPort）算好的 `$relaunchPort`；为 0 时永远不通过
+ *   （只可能落到 still-starting-timeout，绝不假装成功）。
+ */
+function relaunchProbeHelpers() {
+  return [
+    `function Get-TailText($path) {`,
+    `  $t = ''`,
+    // -Encoding UTF8 必写：拉起器/判定器写的是**无 BOM 的 UTF-8**，PS 5.1 的 Get-Content 默认按 ANSI(GBK) 读，
+    // 中文会变成乱码（真机 18:23 的"判定器不可用"就是这个：JSON 里的中文一乱、ConvertFrom-Json 直接抛）。
+    `  try { $t = Get-Content -LiteralPath $path -Raw -Encoding UTF8 -ErrorAction SilentlyContinue } catch { $t = '' }`,
+    `  if ([string]::IsNullOrEmpty($t)) { return '' }`,
+    `  $t = ($t -replace '\\s+', ' ').Trim()`,
+    `  if ($t.Length -gt 600) { $t = '…' + $t.Substring($t.Length - 600) }`,
+    `  return $t`,
+    `}`,
+    `function Test-RelaunchPort {`,
+    `  if ($relaunchPort -le 0) { return $false }`,
+    `  try { $c = Get-NetTCPConnection -LocalPort $relaunchPort -State Listen -ErrorAction SilentlyContinue; if ($c) { return $true } } catch {}`,
+    `  return $false`,
+    `}`,
+  ]
+}
+
+/**
+ * 生成「拉起 DSH 服务并自证」的 PowerShell 函数（整段作为一个数组元素展开）。
+ *
+ * 2026-10-28 两轮改错：
+ * 第一轮把 fire-and-forget 改成"发出去 + 等一小段"，但判据用了「进程存活」⇒ 缺陷 ①。
+ * 第二轮定稿：
+ *   ① 启动走 **node 拉起器**（`fw-launch.mjs`，fd 重定向 + detached），ps1 只 `Start-Process node 拉起器`；
+ *   ② **成功只认端口监听**（`webPort`）；进程存活只算"仍在启动中"，继续等（默认 120 秒，
+ *      `$script:DSH_RELAUNCH_WAIT_SEC` 可覆盖）；
+ *   ③ 三种结局：`listening`（返回空串，调用方据此立刻收尾、不再做任何就绪检查）/
+ *      `still-starting-timeout`（到上限端口没通但进程还活着）/ `child-exited-early|child-exited`
+ *      （失败，带退出码 + 拉起器状态 + 输出尾部）。
+ *   `Note-Relaunch` 是唯一的结果记账点：成功时置 `$script:relaunchListening = $true`。
+ *
+ * @param {object} p
+ * @param {(s: string) => string} p.ps PowerShell 双引号字符串字面量（与升级脚本共用同一份转义）
+ * @param {string} p.nodePath node.exe 绝对路径
+ * @param {boolean} [p.hosted] 外壳托管（桌面端承载）时脚本里只留一句拒绝
+ */
+function relaunchInvoke({ ps, nodePath, hosted = false }) {
+  const hostedGuard = hosted === true
+    ? [`  if ($script:DSH_HOSTED) { Log ('本实例由桌面端外壳托管，跳过拉起（' + $tag + '）：请在桌面端内重启/更新'); return '本实例由桌面端外壳托管，不自动拉起' }`]
+    : []
+  return [
+    // 拉起结果的统一记账（三处调用点共用）：
+    //   空串            = **端口已监听**（真·成功）→ $script:relaunchListening = $true，调用方立刻收尾
+    //   still-starting  = 已经拉起过、别再重复拉起（但不算成功）
+    //   其余            = 失败原因，允许下一轮重试
+    `function Note-Relaunch($lr) {`,
+    `  if ([string]::IsNullOrEmpty($lr)) { $script:relaunchListening = $true; return $true }`,
+    `  $script:relaunchReason = $lr`,
+    `  if ($lr.StartsWith('${REASON_PREFIX.stillStarting}')) { return $true }`,
+    `  return $false`,
+    `}`,
+    `function Invoke-DshRelaunch($tag) {`,
+    ...hostedGuard,
+    `  $bin = Resolve-DshBin`,
+    `  if ([string]::IsNullOrWhiteSpace($bin)) { Log ('拉起失败（' + $tag + '）：node resolve / .pnpm / 顶层链接 三种方式都找不到 dsh 的 bin.js，请手动启动 DSH'); return '${REASON_PREFIX.noBin}（node resolve / .pnpm / 顶层链接 三种方式都失败）' }`,
+    // 拉起器就在 fw-relaunch.log 旁边（由升级/回滚脚本落盘），不额外传参
+    `  $launcher = Join-Path (Split-Path -LiteralPath $launchLog) 'fw-launch.mjs'`,
+    `  if (-not (Test-Path -LiteralPath $launcher)) { Log ('拉起器缺失（' + $tag + '）：' + $launcher + ' 不存在（请重跑一次升级以重新生成）'); return ('${REASON_PREFIX.launcherMissing}：' + $launcher + ' 不存在') }`,
+    `  try { Add-Content -Path $launchLog -Value ((Get-Date -Format 'yyyy-MM-dd HH:mm:ss') + ' 拉起(' + $tag + '): ' + $bin) -Encoding UTF8 } catch {}`,
+    // 每轮拉起用**独立**的 .out/.err/.status.json：这轮失败才读得到这轮的证据
+    `  $outFile = $launchLog + '.out'`,
+    `  $errFile = $launchLog + '.err'`,
+    `  $statusFile = $launchLog + '.status.json'`,
+    `  try { Remove-Item -LiteralPath $outFile -Force -ErrorAction SilentlyContinue } catch {}`,
+    `  try { Remove-Item -LiteralPath $errFile -Force -ErrorAction SilentlyContinue } catch {}`,
+    `  try { Remove-Item -LiteralPath $statusFile -Force -ErrorAction SilentlyContinue } catch {}`,
+    `  $proc = $null`,
+    `  try {`,
+    `    $proc = Start-Process -FilePath ${ps(nodePath)} -ArgumentList @(('"' + $launcher + '" "' + ${ps(nodePath)} + '" "' + $bin + '" "' + $outFile + '" "' + $errFile + '" "' + $statusFile + '"')) -PassThru -WindowStyle Hidden`,
+    `  } catch {`,
+    `    Log ('拉起器启动失败（' + $tag + '）：' + $_.Exception.Message)`,
+    `    return ('${REASON_PREFIX.spawnFailed}：拉起器启动失败：' + $_.Exception.Message)`,
+    `  }`,
+    `  $startedAt = Get-Date`,
+    `  $waitSec = 120`,
+    `  if ($script:DSH_RELAUNCH_WAIT_SEC -gt 0) { $waitSec = [int]$script:DSH_RELAUNCH_WAIT_SEC }`,
+    `  $deadline = (Get-Date).AddSeconds($waitSec)`,
+    `  Log ('已发起拉起（' + $tag + '，拉起器 PID ' + [string]$proc.Id + '，最多等 ' + [string]$waitSec + ' 秒等端口 ' + [string]$relaunchPort + ' 监听）')`,
+    // 成功**只认端口监听**：进程存活只说明"还在启动中"，继续等到上限
+    `  while ($true) {`,
+    `    if (Test-RelaunchPort) { Log ('拉起成功（' + $tag + '）：服务已监听端口 ' + [string]$relaunchPort + '（拉起器 PID ' + [string]$proc.Id + '）'); return '' }`,
+    `    $alive = $false`,
+    `    try { if ($proc -and -not $proc.HasExited) { $alive = $true } } catch { $alive = $false }`,
+    `    if (-not $alive) { break }`,
+    `    if ((Get-Date) -ge $deadline) {`,
+    `      $tailT = Get-TailText $errFile`,
+    `      if ([string]::IsNullOrWhiteSpace($tailT)) { $tailT = Get-TailText $outFile }`,
+    `      Log ('拉起未完成（' + $tag + '）：进程仍存活，但 ' + [string]$waitSec + ' 秒内端口 ' + [string]$relaunchPort + ' 未监听 → still-starting-timeout（不确定，不是坏树）')`,
+    `      $why = '${REASON_PREFIX.stillStarting}(' + [string]$waitSec + 's,pid=' + [string]$proc.Id + ')'`,
+    `      if (-not [string]::IsNullOrWhiteSpace($tailT)) { $why = $why + '：' + $tailT }`,
+    `      return $why`,
+    `    }`,
+    `    Start-Sleep -Milliseconds 1000`,
+    `  }`,
+    // 走到这里 = 拉起器/服务已退出（秒退或跑一会儿才崩）。这次事故就丢在这一步：必须留证据。
+    `  $elapsedSec = [int](((Get-Date) - $startedAt).TotalSeconds)`,
+    `  $exitTag = '${REASON_PREFIX.exited}'`,
+    `  if ($elapsedSec -lt 5) { $exitTag = '${REASON_PREFIX.exitedEarly}' }`,
+    `  $codeText = '未知'`,
+    `  try { $codeText = [string]$proc.ExitCode } catch { $codeText = '未知' }`,
+    `  $statusText = Get-TailText $statusFile`,
+    `  $tailOut = Get-TailText $outFile`,
+    `  $tailErr = Get-TailText $errFile`,
+    `  $tail = $tailErr`,
+    `  if ([string]::IsNullOrWhiteSpace($tail)) { $tail = $tailOut }`,
+    `  Log ('拉起失败（' + $tag + '）：' + $exitTag + '（' + [string]$elapsedSec + ' 秒后退出，exit=' + $codeText + '）')`,
+    `  if (-not [string]::IsNullOrWhiteSpace($statusText)) { Log ('拉起失败（' + $tag + '）拉起器状态：' + $statusText) }`,
+    `  if ([string]::IsNullOrWhiteSpace($tail)) { Log ('拉起失败（' + $tag + '）：stdout/stderr 均为空 —— 没有任何输出证据（判定器据此**默认不回滚**，写 ready 交人工）') }`,
+    `  if (-not [string]::IsNullOrWhiteSpace($tail)) { Log ('拉起失败（' + $tag + '）输出尾部：' + $tail) }`,
+    `  $why = $exitTag + '(exit=' + $codeText + ',' + [string]$elapsedSec + 's)'`,
+    `  if (-not [string]::IsNullOrWhiteSpace($statusText)) { $why = $why + '|' + $statusText }`,
+    `  if (-not [string]::IsNullOrWhiteSpace($tail)) { $why = $why + '：' + $tail }`,
+    `  return $why`,
+    `}`,
+  ]
+}
+
+/**
+ * 生成「回滚判定器」转发脚本源码（写进 `<DSH_HOME>/plugin-console/fw-relaunch-verdict.mjs`）。
+ *
+ * 2026-10-28 第二轮：结论**写文件**，不再依赖 stdout —— 同一次真机里，既有的
+ * `隔离分析无输出` 与新的 `回滚判定器不可用` 是同一个病（`& node helper | Select -Last 1`
+ * 在 schtasks 环境里拿不到输出）。文件证据则一直好用（日志/状态文件都正常写）。
+ *
+ * argv: `<reasonFile> <structureFlag 0|1> <topLevelFlag 0|1> <binPath> <verdictFile>`
+ *
+ * @param {object} p
+ * @param {string} p.libUrl 本模块的 file:// URL（由调用方用 pathToFileURL 算好）
+ * @returns {string} 可直接 writeFileSync 的 .mjs 源码
+ */
+function relaunchVerdictHelperSource({ libUrl }) {
+  return [
+    '// 自动生成：自动拉起失败的「是否回滚」判定器（逻辑在插件内，本文件只做转发）',
+    `import { judgeRelaunchFailure } from ${JSON.stringify(libUrl)}`,
+    "import { readFileSync, writeFileSync } from 'node:fs'",
+    'const [reasonPath, structureFlag, topFlag, binPath, verdictFile] = process.argv.slice(2)',
+    "let reason = ''",
+    'try { reason = readFileSync(reasonPath, "utf8") } catch {}',
+    'let out = null',
+    'try {',
+    '  out = judgeRelaunchFailure({',
+    "    reason, structureVerified: structureFlag === '1', topLevelVerified: topFlag === '1', binPath,",
+    '  })',
+    '} catch (error) { out = { error: String(error && error.message ? error.message : error) } }',
+    'try { writeFileSync(verdictFile, JSON.stringify(out), "utf8") } catch (error) { process.exit(6) }',
+    '',
+  ].join('\n')
+}
+
+/**
+ * 生成「拉起失败 → 判定 → 保留（或唯一情形的回滚）」的 PowerShell 执行块。
+ *
+ * 要求调用点已具备：`$log` / `SetState` / `Log` / `Beat` / `Resolve-DshBin` / `Invoke-Rollback` /
+ * `Invoke-DshRelaunch` / `Note-Relaunch`，以及三个事实位：
+ *   `$script:relaunchReason`（Note-Relaunch 记下的原因）、`$script:structureOk`、`$script:topLevelOk`。
+ *
+ * 判定器不可用时**不再保守回滚**（真机 18:23:56 那样会把好框架扔掉）：走
+ * `relaunchFallbackVerdict` 的同一规则 —— 没有树损坏证据就保留 + 给手动命令。
+ *
+ * @param {object} p
+ * @param {(s: string) => string} p.ps  PowerShell 双引号字符串字面量（与升级脚本共用同一份转义）
+ * @param {string} p.nodePath            node.exe 绝对路径
+ * @param {string} p.helperPath          判定器 .mjs 的绝对路径
+ * @param {number} p.port                目标端口（沿用调用方的 webPort，不在这里另算）
+ */
+function relaunchVerdictBlock({ ps, nodePath, helperPath, port }) {
+  return [
+    `  $relaunchWhy = [string]$script:relaunchReason`,
+    `  if ([string]::IsNullOrWhiteSpace($relaunchWhy)) { $relaunchWhy = '${NO_OUTPUT_REASON}' }`,
+    `  Log ('自动拉起失败 → 判定是否回滚：' + $relaunchWhy)`,
+    // 原因与结论都走文件（该环境下子进程 stdout 抓不到，文件读写一直好用）
+    `  $reasonFile = $log + '.relaunch-reason.txt'`,
+    `  $verdictFile = $log + '.relaunch-verdict.json'`,
+    `  try { Set-Content -Path $reasonFile -Value $relaunchWhy -Encoding UTF8 } catch {}`,
+    `  try { Remove-Item -LiteralPath $verdictFile -Force -ErrorAction SilentlyContinue } catch {}`,
+    `  $binForCmd = Resolve-DshBin`,
+    `  $structureFlag = '0'; if ($script:structureOk) { $structureFlag = '1' }`,
+    `  $topFlag = '0'; if ($script:topLevelOk) { $topFlag = '1' }`,
+    `  try { & ${ps(nodePath)} ${ps(helperPath)} $reasonFile $structureFlag $topFlag $binForCmd $verdictFile 2>&1 | Out-Null } catch { Log ('回滚判定器调用异常：' + $_.Exception.Message) }`,
+    `  $verdictJson = ''`,
+    // -Encoding UTF8 必写：判定器写的是无 BOM UTF-8，而 PS 5.1 默认按 ANSI(GBK) 读
+    // ⇒ 中文乱码 ⇒ ConvertFrom-Json 抛"Invalid object passed in" ⇒ 判定被误判成"不可用"（真机 18:23）。
+    `  try { $verdictJson = Get-Content -LiteralPath $verdictFile -Raw -Encoding UTF8 -ErrorAction SilentlyContinue } catch { $verdictJson = '' }`,
+    `  $verdict = $null`,
+    `  if (-not [string]::IsNullOrWhiteSpace($verdictJson)) { try { $verdict = $verdictJson | ConvertFrom-Json } catch { $verdict = $null } }`,
+    `  if ($null -ne $verdict -and -not [string]::IsNullOrWhiteSpace([string]$verdict.error)) { Log ('回滚判定器报错：' + [string]$verdict.error); $verdict = $null }`,
+    `  if ($null -eq $verdict) {`,
+    // 兜底 = 与 relaunchFallbackVerdict 同规则：没有树损坏证据 ⇒ 保留 + 手动命令（回归人工回滚）
+    `    $verdict = [pscustomobject]@{ verdict = 'keep'; rollback = $false; status = ('框架已就位，自动拉起失败：' + $relaunchWhy + '；请手动运行 node "' + $binForCmd + '" web --no-open，或点「回滚到上一版」'); manualCommand = ('node "' + $binForCmd + '" web --no-open') }`,
+    `    Log '判定器没有产出结论 → 兜底为「保留框架 + 人工决定是否回滚」（自动回滚已取消）'`,
+    `  }`,
+    `  Log ('回滚判定：' + [string]$verdict.verdict)`,
+    `  if ($verdict.rollback) {`,
+    `    Log '判定结果指向框架树损坏 → 自动回滚到升级前版本（唯一保留的自动回滚情形）'`,
+    `    Invoke-Rollback`,
+    `    $ok = $false`,
+    `    $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) { $started = Note-Relaunch (Invoke-DshRelaunch '回滚后') }; Beat`,
+    `      if ($script:relaunchListening) { $ok = $true; break }`,
+    `      Start-Sleep -Seconds 5`,
+    `    }`,
+    `  } else {`,
+    // 保留分支（默认分支）：框架本体已在目标版本，**不回滚**；状态写成明确的终态 ready，
+    // 并把真实的手动启动命令留给用户（服务此时是停的，界面看不到 —— 命令得能直接复制粘贴）。
+    `    $script:keptReady = $true`,
+    `    SetState 'ready' ([string]$verdict.status)`,
+    `    Log ('框架本体已就位、不回滚：' + [string]$verdict.status)`,
+    `    Log ('手动启动命令：' + [string]$verdict.manualCommand)`,
+    `  }`,
+  ].join('\r\n')
+}
+
+export {
+  judgeRelaunchFailure,
+  relaunchFallbackVerdict,
+  relaunchLauncherSource,
+  relaunchVerdictHelperSource,
+  relaunchVerdictBlock,
+  relaunchProbeHelpers,
+  relaunchInvoke,
+  manualRelaunchCommand,
+  keepStatusText,
+  TREE_DAMAGE_MARKERS,
+  REASON_EXCERPT_LIMIT,
+  REASON_PREFIX,
+  NO_OUTPUT_REASON,
+  MANUAL_URL_FLAGS,
+}

package/lib/server/domain/framework-stale-repair.js

@@ -0,0 +1,31 @@
+// 升级失败后的「改名残留」修复：把 `<name>.stale-<ver>-<ts>` 改回真名。
+//
+// 2026-10-28 真机：升级在「拉起」阶段失败，清扫步已把 10 个框架包改名成 `.stale-*`，
+// 真名处什么都没有 ⇒ 框架起不来：`Cannot find package '@deepseek-ai/cordis'`。
+// 当时只能手工改目录名；这里把那件事自动化，并**只返回人类可读的步骤**，
+// 让调用方（routes/framework-upgrade.js）保持精简（那个文件有 700 行硬顶）。
+import { join } from 'node:path'
+import { restoreStaleBackups } from './framework-cleanup.js'
+
+/**
+ * @returns {{ steps: string[], restored: Array<{from: string, to: string}>, failed: Array<object> }}
+ */
+function repairStaleRenameResidue({ fwRoot } = {}) {
+  const steps = []
+  if (typeof fwRoot !== 'string' || fwRoot === '') return { steps, restored: [], failed: [] }
+  try {
+    const repair = restoreStaleBackups({ scopeDir: join(fwRoot, '@deepseek-ai') })
+    if (repair.restored.length > 0) {
+      steps.push(`修复上次失败留下的改名残留：${repair.restored.length} 个包已改回真名（${repair.restored.map((r) => r.to).join('、')}）`)
+    }
+    if (repair.failed.length > 0) {
+      steps.push(`改名残留修复未全部成功：${repair.failed.map((f) => f.real).join('、')}（不阻塞升级）`)
+    }
+    return { steps, restored: repair.restored, failed: repair.failed }
+  } catch (error) {
+    steps.push(`改名残留修复失败（不阻塞升级）：${error instanceof Error ? error.message : String(error)}`)
+    return { steps, restored: [], failed: [{ error: String(error) }] }
+  }
+}
+
+export { repairStaleRenameResidue }

package/lib/server/domain/framework.js

@@ -12,6 +12,7 @@ import { listEntries } from './runtime.js'
 import { copyTree } from '../infra/fsx.js'
 import { dshHome, entryPkgMeta, findPatchPath, pluginRoot, profileDirOf, resolvePackageJson } from '../infra/paths.js'
 import { frameworkUpgradeCandidates, isFrameworkVersionNewer, parseFrameworkVersion } from '../infra/semver.js'
+import { relaunchInvoke, relaunchProbeHelpers } from './framework-relaunch.js'
 
 /** 解析 dsh CLI 的 bin.js 绝对路径（守护拉起用）。 */
 function resolveDshBin() {
@@ -295,8 +296,19 @@ function platformUpgradeRefusal() {
  *   2) 解析走**多级回退**（不再假设某一处路径一定可用）：node resolve → 目标版本的 .pnpm 实体
  *      目录 → 顶层可见链接 → .pnpm 里最新的一个；
  *   3) 全路径参数一律 `Test-Path -LiteralPath`，失败只记录、不抛错。
+ *
+ * 2026-10-28 改错（真机：升级到 0.2.1-rc.4 后「自动拉起」无任何证据 → 好升级被当成失败回滚）：
+ * 旧实现在这里 `Start-Process cmd /c "node bin.js web >> fw-relaunch.log 2>&1"` 之后**立刻**
+ * `Log '已发起拉起服务'` + `return $true` —— fire-and-forget：不等、不验、不抓退出码。
+ * 所以 `fw-relaunch.log` 里只剩一行时间戳 + bin 路径，`隔离分析无输出`、直接回滚。
+ * 现在拉起分三段（实现与判据都在 domain/framework-relaunch.js，本函数只负责拼装）：
+ *   ① `relaunchProbeHelpers()`：读文件尾部 / 端口监听两个小助手（端口沿用调用方 webPort，不另算）；
+ *   ② `relaunchInvoke()`：`-PassThru` 拿句柄 + 每轮独立的 .out/.err + 轮询**正面证据**
+ *      （进程仍存活 或 端口开始监听），失败时留下退出码 / `child-exited-early` / stderr 尾部；
+ *   ③ 返回值是**失败原因字符串**（空串 = 成功）—— 调用方拿它去判"该不该回滚"
+ *      （judgeRelaunchFailure），不再是布尔。
  */
-function relaunchPrelude({ nodePath, pluginDir, fwRoot, target, ps, hosted }) {
+function relaunchPrelude({ nodePath, pluginDir, fwRoot, target, ps, hosted, port }) {
   // 未显式传 hosted 时自己判定一次（自接线，避免调用方漏传导致守卫失效）。
   // 独立 `dsh web` 实例下 detectHostShape().hosted === false ⇒ 生成结果与旧实现逐字节相同。
   const shellHosted = typeof hosted === 'boolean' ? hosted : detectHostShape().hosted === true
@@ -305,11 +317,13 @@ function relaunchPrelude({ nodePath, pluginDir, fwRoot, target, ps, hosted }) {
   // 外壳托管（桌面端 Electron 承载）：脚本里**只留一句拒绝**，绝不 Start-Process 拉起第二个实例。
   // `hosted === false` 时这里是空数组 —— 生成的脚本与旧实现**逐字节相同**（加法分支）。
   const hostedFlag = shellHosted === true ? [`$script:DSH_HOSTED = $true`] : []
-  const hostedGuard = shellHosted === true
-    ? [`  if ($script:DSH_HOSTED) { Log ('本实例由桌面端外壳托管，跳过拉起（' + $tag + '）：请在桌面端内重启/更新'); return $false }`]
-    : []
+  // 端口：沿用调用方（webPort）算好的值；没传就退化成 0 = 端口判据永不通过（不编一个端口）
+  const relaunchPort = Number.isInteger(port) && port > 0 ? port : 0
   return [
     `$launchLog = ''`,
+    // 拉起结果的三个事实位（2026-10-28）：原因文本 / 「端口已监听」（唯一成功判据）/ 是否已拉起过
+    `$script:relaunchReason = ''; $script:relaunchListening = $false`,
+    `$relaunchPort = ${relaunchPort}`,
     ...hostedFlag,
     // 心跳（v0.3.39）：脚本每推进一小步就更新一次心跳文件的时间戳。服务端据此区分
     // 「脚本还在干活」与「脚本进程被系统/启动器杀掉」。2026-09-11 真机事故：回滚脚本
@@ -331,15 +345,11 @@ function relaunchPrelude({ nodePath, pluginDir, fwRoot, target, ps, hosted }) {
     `  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) {`,
-    ...hostedGuard,
-    `  $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`,
-    `}`,
+    // 读文件尾部 / 端口监听两个小助手 + 「拉起并自证」的 Invoke-DshRelaunch 都在
+    // domain/framework-relaunch.js 里生成（本文件贴着 600 行上限，且拉起与"失败后判该不该回滚"
+    // 是同一件事，放一处更好审）。
+    ...relaunchProbeHelpers(),
+    ...relaunchInvoke({ ps, nodePath, hosted: shellHosted }),
   ].join('\r\n')
 }
 

package/lib/server/infra/fw-integrity-check.js

@@ -5,6 +5,10 @@
 // 也让这段逻辑能被单独读、单独审 —— 它是"升级完却没装全"这类事故的最后一道闸。
 //
 // 自包含：只用 target / nodePath / fwRoot 三个值（路径由调用方用 ps() 算好传进来），不依赖任何宿主上下文。
+//
+// 2026-10-28 加法：通过时置 `$script:structureOk = $true` —— 这个事实位是「拉起失败后该不该回滚」
+// 判据（domain/framework-relaunch.js#judgeRelaunchFailure）的输入之一。只有"真通过"才置位，
+// 失败分支保持原样（该值留在 $false，判据据此走保守回滚）。
 
 /** 生成"安装后结构校验"的 PowerShell 片段（返回单个字符串，供升级脚本数组作为一个元素展开）。 */
 function fwIntegrityCheck(params) {
@@ -27,7 +31,7 @@ function fwIntegrityCheck(params) {
     `      else {`,
     `        $probe = (& '${nodePath}' $bin --version 2>&1 | Out-String).Trim()`,
     `        if ($probe -ne '${target}') { Log ('结构校验失败：CLI 自报版本 ' + $probe + '，目标 ${target}（安装不完整或被其它副本顶替），按失败处理'); $code = 1 }`,
-    `        else { Log ('结构校验通过：package.json + bin.js 就位，CLI 自报 ' + $probe) }`,
+    `        else { $script:structureOk = $true; Log ('结构校验通过：package.json + bin.js 就位，CLI 自报 ' + $probe) }`,
     `      }`,
     `    } catch { Log ('结构校验异常，按失败处理：' + $_.Exception.Message); $code = 1 }`,
     `  }`,

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

@@ -11,7 +11,9 @@ import { pathToFileURL } from 'node:url'
 import { createRequire } from 'node:module'
 import { readCompatMode, writeCompatMode } from '../domain/compat-state.js'
 import { FRAMEWORK_BACKUP_ROOT, backupProfileSnapshot, checkpointFrameworkTree, platformUpgradeRefusal, preflightDisableIncompatible, relaunchPrelude, resolveDshBin, resolveFrameworkRootNodeModules, resolveFrameworkUpgradePlan, shellHostedRefusal } from '../domain/framework.js'
+import { relaunchLauncherSource, relaunchVerdictBlock, relaunchVerdictHelperSource } from '../domain/framework-relaunch.js'
 import { fwIntegrityCheck } from '../infra/fw-integrity-check.js'
+import { repairStaleRenameResidue } from '../domain/framework-stale-repair.js'
 import { CORE_PATCH_ROW_IDS } from '../domain/patch.js'
 import { migrateAgentConfigsForUpgrade } from '../domain/presets.js'
 import { planQuarantine } from '../domain/quarantine.js'
@@ -191,6 +193,7 @@ async function routeFrameworkUpgrade(req, res, rc) {
         sendError(res, 500, `无法定位框架安装根（期望含 .pnpm 与 @deepseek-ai/dsh 的顶层 node_modules，实际：${fwRoot ?? '未找到'}）——已取消升级，请修复框架安装后重试`)
         return
       }
+    steps.push(...repairStaleRenameResidue({ fwRoot }).steps) // 修上次失败的 .stale-* 改名残留（只 rename / 跳过已存在 / 幂等）
       // 框架全树 checkpoint（可靠回滚点）：升级前镜像全部 @deepseek-ai 版本包（自包内容）+ 顶层 scope + lock
       let fwCheckpoint = null
       try {
@@ -213,6 +216,7 @@ async function routeFrameworkUpgrade(req, res, rc) {
       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')
+      const rvHelperPath = join(dshHome(), 'plugin-console', 'fw-relaunch-verdict.mjs'), rlPath = join(dshHome(), 'plugin-console', 'fw-launch.mjs') // 判定器转发脚本 + node 服务拉起器（逻辑都在 domain/framework-relaunch.js）
       let thirdPartyRows = []
       try {
         thirdPartyRows = listEntries(ctx)
@@ -236,6 +240,7 @@ async function routeFrameworkUpgrade(req, res, rc) {
           '',
         ].join('\n')
         writeFileSync(qHelperPath, helperSource, 'utf8')
+        const rUrl = pathToFileURL(join(pluginRoot(), 'lib', 'server', 'domain', 'framework-relaunch.js')).href; writeFileSync(rvHelperPath, relaunchVerdictHelperSource({ libUrl: rUrl }), 'utf8'); writeFileSync(rlPath, relaunchLauncherSource(), 'utf8') // 判定器转发脚本 + node 拉起器（逻辑仍在插件内）
         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 }))
@@ -252,8 +257,10 @@ async function routeFrameworkUpgrade(req, res, rc) {
         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`
+      // 拉起片段（隔离重试用；与升级/回滚共用 relaunchPrelude 里的同一份实现）。
+      // 2026-10-28：成功只认端口监听 → Note-Relaunch 置位后**立刻**收尾（以前只记"别再拉起"，
+      // 循环又空转约 95 秒，最后把已起来的服务判死并回滚 —— 缺陷 ②）。
+      const launchSnippet = (tag) => `if (-not $ok -and -not $started) { $started = Note-Relaunch (Invoke-DshRelaunch '${tag}'); if ($script:relaunchListening) { $ok = $true; break } }; Beat`
       const lines = [
         `$state = ${ps(stateFile)}`,
         `$log = ${ps(logFile)}`,
@@ -265,7 +272,7 @@ async function routeFrameworkUpgrade(req, res, rc) {
         "  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: pluginRoot(), fwRoot, target, ps }),
+        relaunchPrelude({ nodePath, pluginDir: pluginRoot(), fwRoot, target, ps, port }),
         // 全局异常兜底（事故教训）：脚本任何未捕获异常都会无声死亡、状态永远卡住、服务没人拉起。
         // trap 捕获后：写 failed 状态 + 日志 + 尝试拉起服务 + 自删任务 + 退出
         "trap {",
@@ -392,7 +399,7 @@ async function routeFrameworkUpgrade(req, res, rc) {
         `    SetState 'failed' ('回滚过程异常，框架可能处于混合状态：' + $_.Exception.Message)`,
         `  }`,
         `}`,
-        `$script:rolledBack = $false`,
+        `$script:rolledBack = $false; $script:structureOk = $false; $script:topLevelOk = $false; $script:keptReady = $false; $script:relaunchListening = $false`,
         `$code = Install-Framework 'https://registry.npmmirror.com'`,
         `if ($code -ne 0) { Log ('npmmirror 安装失败（exit=' + $code + '），切换 registry.npmjs.org 重试一次'); $code = Install-Framework 'https://registry.npmjs.org' }`,
         `if ($code -ne 0) {`,
@@ -421,9 +428,9 @@ async function routeFrameworkUpgrade(req, res, rc) {
         `      if ($code -ne 0) { $code = Install-Framework 'https://registry.npmjs.org' }`,
         `      $vv = ''`,
         `      try { $vv = (Get-Content (Join-Path $visible 'package.json') -Raw | ConvertFrom-Json).version } catch {}`,
-        `      if ($vv -eq '${target}') { Log '顶层可见版本已修正为 ${target}' } else { Log ('顶层可见版本仍为 ' + $vv + '（拉起不受影响：Node 按链接真实路径解析依赖）') }`,
+        `      if ($vv -eq '${target}') { $script:topLevelOk = $true; Log '顶层可见版本已修正为 ${target}' } else { Log ('顶层可见版本仍为 ' + $vv + '（拉起不受影响：Node 按链接真实路径解析依赖）') }`,
         `    } else { Log ('顶层可见版本异常（' + $vv + '）且非实体目录，跳过改名（LinkType=' + $item.LinkType + '）') }`,
-        `  } else { Log '顶层可见版本校验通过' }`,
+        `  } else { $script:topLevelOk = $true; Log '顶层可见版本校验通过' }`,
         `}`,
         // 回滚后跳过重链/依赖修复/版本对齐（它们按新树预期运行，会对已恢复的旧树造成二次破坏）
         `if (-not $script:rolledBack) {`,
@@ -564,7 +571,7 @@ async function routeFrameworkUpgrade(req, res, rc) {
         '$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) { if (Invoke-DshRelaunch '升级后') { $started = $true } }; Beat`,
+        `  if (-not $ok -and -not $started) { $started = Note-Relaunch (Invoke-DshRelaunch '升级后'); if ($script:relaunchListening) { $ok = $true; break } }; Beat`,
         '  Start-Sleep -Seconds 5',
         '}',
         // ── 启动失败隔离（用户硬要求）：新框架起不来时先隔离肇事者再重试，不直接回滚 ──
@@ -620,19 +627,13 @@ async function routeFrameworkUpgrade(req, res, rc) {
         `    Log ('第 ' + $q + ' 轮隔离后仍失败')`,
         `  }`,
         `}`,
-        // 隔离也救不回才回滚（2026-09-04 教训：自动全树回滚并再拉起一次）
+        // 隔离也救不回：**先判定该怎么办**（2026-10-28 用户定案：自动回滚只留给"框架树确认损坏"，
+        // 其余一律 ready + 手动命令，回滚交人工）。判定 = domain/framework-relaunch.js#judgeRelaunchFailure。
         `if (-not $ok -and -not $script:rolledBack) {`,
-        `  Log '服务拉起失败，尝试自动回滚到升级前版本…'`,
-        `  Invoke-Rollback`,
-        `  $ok = $false`,
-        `  $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) { if (Invoke-DshRelaunch '回滚后') { $started = $true } }; Beat`,
-        `    Start-Sleep -Seconds 5`,
-        `  }`,
+        relaunchVerdictBlock({ ps, nodePath, helperPath: rvHelperPath, port }),
         `}`,
-        `if ($ok) { if ($script:rolledBack) { SetState 'failed' '升级失败，已自动回滚到升级前版本（服务已恢复）' ; Log '升级失败已自动回滚，服务已恢复' } else { SetState 'done' '升级完成，服务已监听 ${port}' ; Log '服务已监听 ${port}，升级完成' } } else { SetState 'failed' '拉起失败且自动回滚未生效：请手动运行 node ${binPath} web' ; Log '拉起失败且自动回滚未生效：请手动运行 node ${binPath} web（参考本日志排查）' }`,
+        // keptReady 时上面已写过 ready 终态，这里不再覆盖成 failed（否则又变成"整列红叉"）
+        `if ($ok) { if ($script:rolledBack) { SetState 'failed' '升级失败，已自动回滚到升级前版本（服务已恢复）' ; Log '升级失败已自动回滚，服务已恢复' } else { SetState 'done' '升级完成，服务已监听 ${port}' ; Log '服务已监听 ${port}，升级完成' } } elseif (-not $script:keptReady) { SetState 'failed' '拉起失败且自动回滚未生效：请手动运行 node ${binPath} web' ; Log '拉起失败且自动回滚未生效：请手动运行 node ${binPath} web（参考本日志排查）' }`,
         `schtasks /delete /f /tn ${taskName} 2>$null`,
       ].filter((l) => l !== '').join('\r\n')
       // 初始状态（备份完成、脚本即将执行）
@@ -695,4 +696,4 @@ async function routeFrameworkUpgrade(req, res, rc) {
     return
 }
 
-export { routeFrameworkUpgrade }
+export { routeFrameworkUpgrade }

package/lib/server/routes/framework.js

@@ -9,6 +9,7 @@ import { tmpdir } from 'node:os'
 import { createRequire } from 'node:module'
 import { readCompatGate, writeCompatGate } from '../domain/compat.js'
 import { cleanupStaleFwTasks, currentFrameworkVersion, detectHostShape, pickFrameworkTarget, platformUpgradeRefusal, relaunchPrelude, resolveDshBin, shellHostedRefusal } from '../domain/framework.js'
+import { relaunchLauncherSource } from '../domain/framework-relaunch.js'
 import { restartPathDecision } from '../domain/restart.js'
 // 0.5.84 加法（用户第 5 项）：独立实例的 detached 重拉 —— 计划在 domain/restart-launcher.js，
 // 进程原语仍走 infra/egress.js 的可注入出口（单测能证明"一次真进程都没起"）。
@@ -113,7 +114,9 @@ async function routeFrameworkUpgradeStatusGet(req, res, rc) {
         // = 0xC000013A），终态没写成 → 界面永远卡在「回滚中…」并每 3 秒轮询。心跳 + 现实核对
         // 能把它纠正回来：脚本不再心跳（>90 秒没动静）时，用「已装版本 vs 回滚记录的 from/to」
         // 判断真实结果；同时清掉残留的 DSH-FW-* 计划任务。
-        const terminal = status.status === 'idle' || status.status === 'done' || status.status === 'failed'
+        // 2026-10-28 加法：`ready` = 框架本体已就位、只有自动拉起失败（**不回滚**，回滚交人工）。
+        // 它是**终态**（下面两处 terminal 判定都得认它，否则自愈会改写成 done、15 分钟残留清理会抹成 idle）。
+        const terminal = status.status === 'idle' || status.status === 'done' || status.status === 'failed' || status.status === 'ready'
         if (!terminal) {
           let hbAge = null
           try { hbAge = Date.now() - statSync(`${f}.hb`).mtimeMs } catch { hbAge = null }
@@ -152,11 +155,13 @@ async function routeFrameworkUpgradeStatusGet(req, res, rc) {
         // 视为上次升级的残留——升级脚本要么成功（done）要么失败（failed），服务重启后不可能还在
         // 中途；任务调度失败/脚本空跑时状态会永远停在 starting，重启后不应再自动恢复进度条。
         // （升级进行中页面断连后用户手动重启服务属边缘情况：<15 分钟不受影响，进度仍可恢复）
-        if (status.status !== 'idle' && status.status !== 'done' && status.status !== 'failed'
+        if (status.status !== 'idle' && status.status !== 'done' && status.status !== 'failed' && status.status !== 'ready'
           && Date.now() - at > 15 * 60 * 1000) {
           try { writeFileSync(f, 'idle|', 'utf8') } catch {}
           status = { status: 'idle', message: null, at: Date.now() }
         }
+        // ready → 对客户端表现成 done + keptFrame/relaunchFailed 标记（不改 UI：done 是终态、message 原样显示）
+        if (status.status === 'ready') status = { ...status, status: 'done', keptFrame: true, relaunchFailed: true }
       }
     } catch {}
     sendJson(res, 200, { ok: true, ...status })
@@ -414,6 +419,7 @@ async function routeFrameworkRollback(req, res, rc) {
     const logFile = join(dshHome(), 'plugin-console', 'fw-upgrade.log')
     const stateFile = join(dshHome(), 'plugin-console', 'fw-upgrade-state.txt')
     const ps = (s) => JSON.stringify(s).replace(/\\\\/gu, '\\')
+    try { writeFileSync(join(dshHome(), 'plugin-console', 'fw-launch.mjs'), relaunchLauncherSource(), 'utf8') } catch {} // 2026-10-28：回滚后的拉起也走 node 拉起器（与升级脚本共用同一份生成物）
     const lines = [
       `$state = ${ps(stateFile)}`,
       `$log = ${ps(logFile)}`,
@@ -422,7 +428,7 @@ async function routeFrameworkRollback(req, res, rc) {
       "  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: pluginRoot(), fwRoot: rec.fwRoot, target: rec.from ?? '', ps }),
+      relaunchPrelude({ nodePath, pluginDir: pluginRoot(), fwRoot: rec.fwRoot, target: rec.from ?? '', ps, port }),
       "trap {",
       "  try { SetState 'failed' ('回滚脚本异常终止：' + $_.Exception.Message) } catch {}",
       `  schtasks /delete /f /tn ${taskName} 2>$null`,
@@ -449,10 +455,10 @@ async function routeFrameworkRollback(req, res, rc) {
       `$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) { if (Invoke-DshRelaunch '回滚后') { $started = $true } }; Beat`,
+      `  if (-not $ok -and -not $started) { $started = Note-Relaunch (Invoke-DshRelaunch '回滚后'); if ($script:relaunchListening) { $ok = $true; break } }; Beat`,
       `  Start-Sleep -Seconds 5`,
       `}`,
-      `if ($ok) { SetState 'done' ('已回滚到升级前版本 ${rec.from ?? '?'}，服务正常') ; Log '回滚完成，服务已恢复' } else { SetState 'failed' '回滚后服务拉起失败：请手动运行 node ${resolveDshBin() ?? '<bin>'} web' ; Log '回滚后拉起失败' }`,
+      `if ($ok) { SetState 'done' ('已回滚到升级前版本 ${rec.from ?? '?'}，服务正常') ; Log '回滚完成，服务已恢复' } else { SetState 'failed' ('回滚后服务拉起失败：' + [string]$script:relaunchReason + '；请手动运行 node ${resolveDshBin() ?? '<bin>'} web --no-open') ; Log ('回滚后拉起失败：' + [string]$script:relaunchReason) }`,
       `schtasks /delete /f /tn ${taskName} 2>$null`,
     ].filter((l) => l !== '').join('\r\n')
     try { writeFileSync(stateFile, 'rollback|回滚脚本已启动…', 'utf8') } catch {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@noob-stupid/dsh-plugin-console",
-  "version": "0.5.94",
+  "version": "0.5.95",
   "description": "DSH 框架升级安全与插件升级门控：一键升级、失败自动回滚、升级后回滚上版、旧插件不适配自动禁用；内置多源插件市场为发现层，插件源全部可自定义，可指向公司内网私有源 / 私有索引 / 本地 Git 仓库，纯内网离线可用 | Framework upgrade safety & plugin version gating for DSH, with a customizable multi-source plugin market: point every source at internal mirrors or a local file:// repo for intranet-only, offline installs.",
   "repository": {
     "type": "git",