@moonquake2004/dsh-doctor 0.4.3 → 0.4.5

package/README.md

@@ -1,5 +1,7 @@
 # dsh-doctor
 
+**Verified against DSH `0.1.5-rc.1`** (session format v3, `dsh-session` located across npx / global / profile layouts; legacy v0 events read through the installed `dsh-session-format-*` migration chain).
+
 > [中文版 README](README.zh.md) · English
 
 Offline diagnostic for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) — run it **before** boot or before installing plugins, and it tells you which of the failure classes this community has been reporting will bite.
@@ -24,7 +26,7 @@ node dsh-doctor.mjs --json --envelope    # v1 doctor-contract envelope (lowercas
 
 Exit codes (default mode): `0` = all pass · `1` = problems found (built-in checks + catalog `severity: error`) · warn-level catalog failures don't flip the exit code.
 
-With `--envelope` (doctor-contract mode): `0` = all pass · `1` = any WARN · `2` = any FAIL. The envelope follows the shared `dsh-doctor/v1` schema (`{ schema, generatedAt, profile, exitCode, summary, ok, checks:[{name,status,detail}] }`) so implementations are interchangeable for CI/marketplace use. Installed via npm, the CLI is also available as the `dsh-doctor` bin.
+With `--envelope` (doctor-contract mode): `0` = all pass · `1` = any WARN · `2` = any FAIL. The envelope follows the shared `dsh-doctor/v1` schema (`{ schema, generatedAt, profile, exitCode, summary, ok, checks:[{name,status,detail}] }`) so implementations are interchangeable for CI/marketplace use. Installed via npm, the CLI is also available as the `dsh-doctor` bin. `--remediation` (with `--json --envelope`) adds the opt-in v1.1 `remediation` array — ordered `[check-name] fix` lines for failing checks, absent otherwise so r5 consumers stay byte-stable.
 
 ## Checks (28 built-in + 5 catalog = 33)
 
@@ -36,7 +38,7 @@ With `--envelope` (doctor-contract mode): `0` = all pass · `1` = any WARN · `2
 | E3 | node version / `--expose-internals` reachability | [#113](https://github.com/deepseek-ai/deepseek-harness/discussions/113), [#1313](https://github.com/deepseek-ai/deepseek-harness/discussions/1313) |
 | E4 | node-pty native binary present (`prebuilds/<platform>-<arch>/pty.node`) | [#1219](https://github.com/deepseek-ai/deepseek-harness/discussions/1219) |
 | E5 | storage JSON files valid (strict UTF-8 + parse) | [#1357](https://github.com/deepseek-ai/deepseek-harness/discussions/1357) |
-| E6 | anchor tripwire: our S6/S7/S10 contracts still in installed `dsh-session` | [anti-rot idea](https://github.com/deepseek-ai/deepseek-harness/discussions/1534) |
+| E6 | anchor tripwire: the S6/S7/S10 contracts still exist wherever the current release keeps them (npx / global / profile layouts; `dsh-session` or the `dsh-session-format-*` migration chain) | [anti-rot idea](https://github.com/deepseek-ai/deepseek-harness/discussions/1534) |
 | E10 | web port 3080 availability before launch (dsh web itself = OK; other process = FAIL; `DSH_DOCTOR_PORT` override) | [#1719](https://github.com/deepseek-ai/deepseek-harness/discussions/1719) |
 
 ### profile
@@ -50,6 +52,7 @@ With `--envelope` (doctor-contract mode): `0` = all pass · `1` = any WARN · `2
 | P12 | profile-installed bundle version vs running CLI (emits vocabulary name `installed_bundle`, #1719 v1.1: skip when unlisted / warn on manifest-lies or divergence / pass when equal; the web "Doctor" panel / `/dsh-doctor/run` API run the bundle) | [#1719](https://github.com/deepseek-ai/deepseek-harness/discussions/1719) |
 | P13 | client-half `provide` service name clashes with core client services (`chatFileMentions` etc. from `@deepseek-ai/dsh-client-*`, warn) or cross-bundle same-name grabs (browser-side "service already registered" → UI white screen, server logs see nothing) | [#2752](https://github.com/deepseek-ai/deepseek-harness/discussions/2752) |
 | P14 | declared `bin` executability (target file present + shebang required for text `bin`; exec-bit alone does not identify the interpreter → ENOEXEC on direct run, #1846) | [#1846](https://github.com/deepseek-ai/deepseek-harness/discussions/1846) |
+| P16 | plugin imports a named export the installed package does not provide (warn; boot fails hard on one bad entry) | [#5864](https://github.com/deepseek-ai/deepseek-harness/discussions/5864) |
 
 ### session
 | ID | Checks | Discussion |
@@ -58,10 +61,11 @@ With `--envelope` (doctor-contract mode): `0` = all pass · `1` = any WARN · `2
 | S2 | unclosed turns (session stuck "running") | [#466](https://github.com/deepseek-ai/deepseek-harness/discussions/466), [#1265](https://github.com/deepseek-ai/deepseek-harness/discussions/1265) |
 | S6 | `seq == index` contiguity (official semantics, chunk rows expanded like `expandRow`) | [#1333](https://github.com/deepseek-ai/deepseek-harness/discussions/1333), [#1452](https://github.com/deepseek-ai/deepseek-harness/discussions/1452), [#1469](https://github.com/deepseek-ai/deepseek-harness/discussions/1469) |
 | S7 | post-`end-seed` replay (replayed committed tail) | [#1497](https://github.com/deepseek-ai/deepseek-harness/discussions/1497) |
-| S8 | unknown event types without `ignorable` (wholesale refusal) | [#1538](https://github.com/deepseek-ai/deepseek-harness/discussions/1538) |
+| S8 | unknown event types without `ignorable` (wholesale refusal) — readable set = current table ∪ legacy types recognized by the installed `dsh-session-format-*` migrators | [#1538](https://github.com/deepseek-ai/deepseek-harness/discussions/1538) |
 | S9 | zstd container frame count (single-frame logs → `session.list` 500) | [#1043](https://github.com/deepseek-ai/deepseek-harness/discussions/1043) |
 | S10 | `sourceEventSeqs` referencing non-earlier events | [#1469](https://github.com/deepseek-ai/deepseek-harness/discussions/1469) |
 | S11 | whole-session scan: corrupt → quarantine suggestion; oversized / workspace estimated-heap (max(events×600B, bytes×6), default 1GiB, `DSH_DOCTOR_HEAP_MB`) → cold-start stall risk | [#1550](https://github.com/deepseek-ai/deepseek-harness/discussions/1550) |
+| S12 | migration-refusal pre-flight: session logs the installed `dsh-session-format-*` chain will refuse (v0 `subagent/descriptor` version gate; v2→v3 source-kind whitelist) — sessions that look present but cannot be opened | [#6045](https://github.com/deepseek-ai/deepseek-harness/discussions/6045), [#6328](https://github.com/deepseek-ai/deepseek-harness/discussions/6328), [#6311](https://github.com/deepseek-ai/deepseek-harness/discussions/6311) |
 
 ## Notes
 

package/README.zh.md

@@ -1,5 +1,7 @@
 # dsh-doctor
 
+**已针对 DSH `0.1.5-rc.1` 验证**（会话格式 v3；`dsh-session` 定位覆盖 npx / 全局 / profile 三种布局；v0 旧事件按已装 `dsh-session-format-*` 迁移链读取）。
+
 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 的离线诊断工具——在**启动前**或**安装插件前**跑一次，它会告诉你社区反复报告的哪几类故障会在你机器上咬人。
 
 零 npm 依赖。单文件。任何有 `node` 的环境都能跑（`zstd` 只在扫 `.zstd` 会话日志时需要，E1 会检查它）。
@@ -31,7 +33,7 @@ node dsh-doctor.mjs --no-catalog         # 不拉远程目录（只用内置副
 | E3 | node 版本 / `--expose-internals` 可及性 | [#113](https://github.com/deepseek-ai/deepseek-harness/discussions/113), [#1313](https://github.com/deepseek-ai/deepseek-harness/discussions/1313) |
 | E4 | node-pty 原生二进制在位（`prebuilds/<platform>-<arch>/pty.node`） | [#1219](https://github.com/deepseek-ai/deepseek-harness/discussions/1219) |
 | E5 | 存储 JSON 文件合法（严格 UTF-8 + 可解析） | [#1357](https://github.com/deepseek-ai/deepseek-harness/discussions/1357) |
-| E6 | 锚点 tripwire：S6/S7/S10 依赖的契约仍在安装的 `dsh-session` 里 | [anti-rot idea](https://github.com/deepseek-ai/deepseek-harness/discussions/1534) |
+| E6 | 锚点 tripwire：S6/S7/S10 依赖的契约仍在**当前版本存放它的位置**（npx / 全局 / profile 三布局；`dsh-session` 或 `dsh-session-format-*` 迁移链） | [anti-rot idea](https://github.com/deepseek-ai/deepseek-harness/discussions/1534) |
 | E10 | 启动前 Web 端口 3080 可用性（dsh web 自身占用=正常；其他进程=FAIL；`DSH_DOCTOR_PORT` 可覆盖） | [#1719](https://github.com/deepseek-ai/deepseek-harness/discussions/1719) |
 
 ### profile
@@ -45,6 +47,7 @@ node dsh-doctor.mjs --no-catalog         # 不拉远程目录（只用内置副
 | P12 | profile 内 bundle 版本 vs 运行 CLI（发词汇名 `installed_bundle`，#1719 v1.1：未声明=skip / manifest 撒谎或分歧=warn / 一致=pass；web「诊断」面板 / `/dsh-doctor/run` API 跑的是 bundle） | [#1719](https://github.com/deepseek-ai/deepseek-harness/discussions/1719) |
 | P13 | client 半 `provide` 服务名抢注核心客户端服务（`chatFileMentions` 等 `@deepseek-ai/dsh-client-*`，warn）或跨 bundle 同名（浏览器端 service already registered → UI 白屏、服务端日志无感知） | [#2752](https://github.com/deepseek-ai/deepseek-harness/discussions/2752) |
 | P14 | 声明 `bin` 可执行性（目标文件在位 + 文本 bin 必须带 shebang；仅可执行位不识别解释器 → 直接执行 ENOEXEC，#1846） | [#1846](https://github.com/deepseek-ai/deepseek-harness/discussions/1846) |
+| P16 | 插件导入了已装包未提供的命名导出（warn；单条坏 entry 即 boot 硬失败） | [#5864](https://github.com/deepseek-ai/deepseek-harness/discussions/5864) |
 
 ### session
 | ID | 检查 | 对应讨论 |
@@ -53,10 +56,11 @@ node dsh-doctor.mjs --no-catalog         # 不拉远程目录（只用内置副
 | S2 | 未闭合 turn（会话卡"运行中"） | [#466](https://github.com/deepseek-ai/deepseek-harness/discussions/466), [#1265](https://github.com/deepseek-ai/deepseek-harness/discussions/1265) |
 | S6 | `seq == index` 连续性（官方语义，chunk 行按 `expandRow` 展开） | [#1333](https://github.com/deepseek-ai/deepseek-harness/discussions/1333), [#1452](https://github.com/deepseek-ai/deepseek-harness/discussions/1452), [#1469](https://github.com/deepseek-ai/deepseek-harness/discussions/1469) |
 | S7 | `end-seed` 后重放（重放已提交尾部） | [#1497](https://github.com/deepseek-ai/deepseek-harness/discussions/1497) |
-| S8 | 未知事件类型且无 `ignorable`（整包拒绝） | [#1538](https://github.com/deepseek-ai/deepseek-harness/discussions/1538) |
+| S8 | 未知事件类型且无 `ignorable`（整包拒绝）——可读集 = 当前表 ∪ 已装 `dsh-session-format-*` 迁移包认的旧类型 | [#1538](https://github.com/deepseek-ai/deepseek-harness/discussions/1538) |
 | S9 | zstd 容器帧数（单帧日志 → `session.list` 整体 500） | [#1043](https://github.com/deepseek-ai/deepseek-harness/discussions/1043) |
 | S10 | `sourceEventSeqs` 引用非更早事件 | [#1469](https://github.com/deepseek-ai/deepseek-harness/discussions/1469) |
 | S11 | 全会话扫描：损坏 → 隔离建议；超大 / 工作区估算物化堆（max(事件×600B, 字节×6)，默认 1GiB，`DSH_DOCTOR_HEAP_MB`）→ 冷启动卡顿风险 | [#1550](https://github.com/deepseek-ai/deepseek-harness/discussions/1550) |
+| S12 | 迁移拒载预检：会被已装 `dsh-session-format-*` 迁移链拒绝的会话日志（v0 `subagent/descriptor` 版本门；v2→v3 source.kind 白名单）——列表里看着在、点开却打不开 | [#6045](https://github.com/deepseek-ai/deepseek-harness/discussions/6045), [#6328](https://github.com/deepseek-ai/deepseek-harness/discussions/6328), [#6311](https://github.com/deepseek-ai/deepseek-harness/discussions/6311) |
 
 ## 备注
 
@@ -95,7 +99,7 @@ If you're coming from a symptom (rather than from the machine), these are the ch
 | approval internals | S2 | ⚠️ runtime policy; only the turn-level effect |
 | credentials internals | E2, E5 | ⚠️ file-level only |
 
-The `dsh-doctor/v1` envelope (`--json --envelope`) is the machine-readable form of any of these runs, so a symptom tool can consume the verdict directly.
+The `dsh-doctor/v1` envelope (`--json --envelope`) is the machine-readable form of any of these runs, so a symptom tool can consume the verdict directly. `--remediation`（配合 `--json --envelope`）输出 v1.1 可选 `remediation` 数组——失败项的有序 `[检查名] 修复` 行；不带该 flag 时字段不存在，r5 消费者字节稳定。
 
 ## 自更新检查（v0.2.1，层 B）
 

package/dsh-doctor.mjs

@@ -15,6 +15,7 @@
  *     P10 inject 引用客户端专属服务（#1947：@deepseek-ai/dsh-client-* 服务端永不提供 → Fiber 永久 PENDING → web boot 失败）
  *     P11 已装 bundle 的 main 入口产物缺失（#1965：市场装未构建源码树 → ERR_MODULE_NOT_FOUND → boot 崩）
  *     P13 client 端 provide 服务名抢注核心客户端服务 / 跨 bundle 同名（#2752：浏览器端 service already registered → UI 白屏，服务端日志无感知）
+ *     P16 命名导入的导出缺失（#5864：warn 级，静态自省已装包导出面）
  *     P14 declared bin 可执行性（#1846：打包成功但 bin 缺 shebang/产物 → 直接执行 ENOEXEC；与 P11 互补）
  *     P12 `installed_bundle`（#1719 v1.1 词汇：profile 内 bundle 版本 vs 运行 CLI 版本——web 面板/API 跑的是 profile 里装的 bundle，可与独立 CLI 版本不一致）
  *   [session]
@@ -24,7 +25,8 @@
  *     S7  end-seed 后重放已提交尾部（#1497：种子末尾之后出现更低 seq）
  *     S9  zstd 容器结构（#1043：单帧容器 → session.list 整体 500，侧边栏全消失）
  *     S10 sourceEventSeqs 悬空引用（#1469：压缩未重映射溯源 → history unavailable）
- *     S8  未知事件类型且无 ignorable（#1538：插件写的事件 harness 读不了 → 整包拒绝；清单从安装的 dsh-session 解析，内置 0.1.0-rc.6 回退）
+ *     S8  未知事件类型且无 ignorable（#1538：harness 读不了 → 整包拒绝；可读集 = 安装的 dsh-session 当前表 ∪ dsh-session-format-* 迁移包旧类型，0.1.5-rc.1 回退）
+ *     S12 迁移拒载预检（#6045/#6328/#6311：规则自省自已装 dsh-session-format-* 迁移包）
  *     S11 全会话扫描（#1550：损坏会话 → 隔离建议；超大会话/工作区估算物化堆 → 冷启动风险警告；估算堆=解码MB×6+事件×200B，阈值默认 1GB，可设 DSH_DOCTOR_HEAP_MB）
  *   [env]
  *     E1  关键命令不在 PATH（#1270：node/pnpm/zstd）
@@ -32,7 +34,7 @@
  *     E3  node 版本 / --expose-internals 可及性（#113/#1313，headless/HMR 场景）
  *     E4  node-pty 原生模块完整性（#1219：pty.node 缺失 → dsh web 启动失败）
  *     E5  存储 JSON 文件合法性（#1357：并发写 workspace.json 乱码 → 工作区列表消失）
- *     E6  锚点元检查（tripwire：S6 的 expandRow seq0+k、S7 的 session/end-seed、S10 的 sourceEventSeqs 是否仍在安装的 dsh-session 中）
+ *     E6  锚点元检查（tripwire：S6 的 v0 chunk 展开契约、S7 的 session/end-seed、S10 的 sourceEventSeqs 是否仍在安装的 dsh-session/迁移包中；定位覆盖 npx/全局/profile 三布局）
  *     E10 3080 Web 端口可用性（#1719：启动 dsh web 前检查；dsh web 自身占用=正常，其他程序占用=FAIL；DSH_DOCTOR_PORT 可覆盖）
  *     （P6 Windows 空格参数 lint，#1420 —— 待实现）
  *
@@ -54,7 +56,7 @@ import { execFileSync, spawnSync } from 'node:child_process';
 import { closeSync, existsSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import net from 'node:net';
-import { basename, delimiter as PATH_DELIM, dirname, join, resolve } from 'node:path';
+import { basename, delimiter as PATH_DELIM, dirname, join, relative, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { pathToFileURL, fileURLToPath } from 'node:url';
 
@@ -67,37 +69,148 @@ const only = process.argv
   .map((a) => a.startsWith('--') ? a.slice(2) : a);
 const wants = (s) => only.length === 0 || only.includes(s) || only.includes(s.charAt(0).toUpperCase() + s.slice(1));
 
-// S8：官方 KNOWN_SESSION_EVENT_TYPES（0.1.0-rc.6 内置回退；优先从安装的 dsh-session 解析）
+// S8：官方 KNOWN_SESSION_EVENT_TYPES（回退表对齐 0.1.5-rc.1；优先从安装的 dsh-session 动态解析）
 const KNOWN_SESSION_EVENT_TYPES_FALLBACK = new Set([
-  'agent-preset/selected', 'agent/inbox/spliced', 'approval/asked', 'approval/decided', 'approval/policy',
-  'assistant/chunk', 'assistant/message', 'command/done', 'command/run', 'compaction/end', 'compaction/prune',
-  'compaction/start', 'compaction/summary', 'feedback/record', 'goal/change', 'hook/invoked', 'hook/result',
-  'llm/retry', 'llm/retry-started', 'permission/preset', 'plan/mode', 'request/context', 'request/header',
-  'sandbox/mode', 'schedule/change', 'session/end-seed', 'session/title', 'session/title-llm-request',
-  'step/end', 'step/start', 'subagent/descriptor', 'todo/write', 'tool-workflow/agent-end',
-  'tool-workflow/agent-start', 'tool-workflow/run-end', 'tool-workflow/run-start', 'tool/call',
-  'tool/code-dispatch', 'tool/code-dispatch-start', 'tool/result', 'turn/end', 'turn/start', 'user/message',
-  'web/deepseek-search-llm-request'
+  'agent-preset/selected', 'agent/inbox/spliced', 'approval/asked', 'approval/decided',
+  'approval/policy', 'assistant/attempt', 'assistant/message', 'command/done',
+  'command/run', 'compaction/end', 'compaction/prune', 'compaction/start',
+  'compaction/summary', 'feedback/message-delete', 'feedback/message-put', 'feedback/record',
+  'goal/change', 'hook/invoked', 'hook/result', 'llm/retry',
+  'llm/retry-started', 'model/selection', 'permission/preset', 'plan/mode',
+  'request/context', 'request/header', 'sandbox/mode', 'schedule/change',
+  'session-log-deepseek/delivery-accepted', 'session/end-seed', 'session/title', 'session/title-llm-request',
+  'step/end', 'step/start', 'subagent/descriptor', 'subagent/model-selection-policy',
+  'system/message', 'team/member', 'team/message/delivered', 'team/message/queued',
+  'team/task', 'todo/write', 'tool-workflow/agent-end', 'tool-workflow/agent-start',
+  'tool-workflow/run-end', 'tool-workflow/run-start', 'tool/call', 'tool/ptc-dispatch',
+  'tool/ptc-dispatch-start', 'tool/result', 'turn/end', 'turn/start',
+  'user/message', 'web/deepseek-search-llm-request'
 ]);
 // 存储行类型与 header，不属于事件门禁
 const STORAGE_ROW_TYPES = new Set(['text-chunks', 'reasoning-chunks', 'tool-call-chunks', 'session']);
-function knownSessionEventTypes() {
+/** 定位已安装的 dsh-session lib/index.js —— 覆盖三种安装形态（0.1.5 起 dsh 转全局安装，旧的 npx-only 查找会静默回退）：
+ *  ① npx/pnpm：<root>/node_modules/.bin/dsh → <root>/node_modules/@deepseek-ai/dsh-session
+ *  ② 全局 npm：<prefix>/bin/dsh → <prefix>/lib/node_modules/@deepseek-ai/dsh[/node_modules]/@deepseek-ai/dsh-session
+ *  ③ profile：$DSH_HOME/profiles/<name>/node_modules/@deepseek-ai/dsh-session（含 .pnpm store）
+ *  找不到返回 null —— 调用方回退内置假设并**声明**（不静默）。 */
+function findSessionLibs() {
+  const REL = join('@deepseek-ai', 'dsh-session', 'lib', 'index.js');
+  const cands = [];
   for (const p of (process.env.PATH || '').split(PATH_DELIM)) {
-    if (!p.endsWith('node_modules/.bin') || !existsSync(join(p, 'dsh'))) continue;
-    try {
-      const src = readFileSync(join(dirname(p), '@deepseek-ai', 'dsh-session', 'lib', 'index.js'), 'utf8');
-      const m = /const KNOWN_SESSION_EVENT_TYPES = new Set\(\[(.*?)\]\);/.exec(src);
-      if (m) {
-        const items = [...m[1].matchAll(/"([^"]+)"/g)].map((x) => x[1]);
-        if (items.length) return new Set(items);
+    if (!p || !existsSync(join(p, 'dsh'))) continue;
+    cands.push(join(dirname(p), REL)); // ① npx/pnpm 布局
+    let real = null;
+    try { real = realpathSync(join(p, 'dsh')); } catch { /* 忽略 */ }
+    if (real) {
+      let d = dirname(real);
+      for (let i = 0; i < 5; i++) {
+        cands.push(join(d, 'node_modules', REL)); // ② <pkg>/node_modules/…
+        cands.push(join(d, REL));                 // ② hoisted 到 <dir>/@deepseek-ai/
+        const up = dirname(d);
+        if (up === d) break;
+        d = up;
       }
-    } catch { /* 回退 */ }
-    break;
+    }
+  }
+  const profiles = join(HOME, 'profiles'); // ③
+  if (existsSync(profiles)) {
+    for (const name of readdirSync(profiles)) {
+      const nm = join(profiles, name, 'node_modules');
+      cands.push(join(nm, REL));
+      const store = join(nm, '.pnpm');
+      if (existsSync(store)) {
+        for (const d of readdirSync(store)) {
+          if (d.startsWith('@deepseek-ai+dsh-session@')) cands.push(join(store, d, 'node_modules', REL));
+        }
+      }
+    }
+  }
+  return [...new Set(cands.filter((c) => existsSync(c)))];
+}
+
+/** 机器上可能同时装着多份 dsh（全局 + 多个 npx checkout）——取版本最高的一份做"当前契约"，
+ *  可读类型则取所有安装的并集（任一安装能读的旧类型都不该判"读不了"）。 */
+function pickNewestSessionLib(libs) {
+  let best = null; let bestV = null;
+  for (const lib of libs) {
+    let v = null;
+    try { v = JSON.parse(readFileSync(join(dirname(dirname(lib)), 'package.json'), 'utf8')).version; } catch { /* 忽略 */ }
+    if (!v) { if (!best) best = lib; continue; }
+    const key = v.split(/[.-]/).map((x) => (/^\d+$/.test(x) ? Number(x) : 0));
+    if (!bestV || key.some((n, i) => n !== (bestV[i] ?? 0) && n > (bestV[i] ?? 0) && bestV.slice(0, i).every((m, j) => m === key[j]))) { best = lib; bestV = key; }
+    else if (!best) { best = lib; bestV = key; }
+  }
+  return best;
+}
+
+/** 单份安装的事件类型表（解析失败返回 null）。 */
+function sessionTableFrom(lib) {
+  try {
+    const s = readFileSync(lib, 'utf8');
+    const m = /const KNOWN_SESSION_EVENT_TYPES = new Set\(\[(.*?)\]\);/.exec(s);
+    if (!m) return null;
+    const items = [...m[1].matchAll(/"([^"]+)"/g)].map((x) => x[1]);
+    return items.length ? new Set(items) : null;
+  } catch { return null; }
+}
+
+/** 某份安装同级的会话格式迁移包（v0→v1→v2→v3）所认的旧类型。 */
+function migratorTypesFor(lib) {
+  const out = [];
+  const nm = lib.slice(0, lib.indexOf(join('@deepseek-ai', 'dsh-session')));
+  const libs = [];
+  const scope = join(nm, '@deepseek-ai');
+  if (existsSync(scope)) {
+    for (const d of readdirSync(scope)) if (d.startsWith('dsh-session-format-')) libs.push(join(scope, d, 'lib', 'index.js'));
+  }
+  const store = join(nm, '.pnpm');
+  if (existsSync(store)) {
+    for (const d of readdirSync(store)) {
+      if (!d.startsWith('@deepseek-ai+dsh-session-format-')) continue;
+      const inner = join(store, d, 'node_modules', '@deepseek-ai');
+      if (!existsSync(inner)) continue;
+      for (const p of readdirSync(inner)) if (p.startsWith('dsh-session-format-')) libs.push(join(inner, p, 'lib', 'index.js'));
+    }
+  }
+  for (const f of libs) {
+    try {
+      const s = readFileSync(f, 'utf8');
+      for (const m of s.matchAll(/"([a-z][a-z0-9-]*\/[a-z0-9-]+)"/g)) out.push(m[1]);
+    } catch { /* 忽略单个包 */ }
+  }
+  return out;
+}
+
+const SESSION_LIBS = findSessionLibs();
+/** 定位安装的 dsh-session（新→旧取最高版本；找不到返回 null）。 */
+function findSessionLib() { return pickNewestSessionLib(SESSION_LIBS) || null; }
+
+function knownSessionEventTypes() {
+  const lib = findSessionLib();
+  if (lib) {
+    const t = sessionTableFrom(lib);
+    if (t) return t;
   }
   return KNOWN_SESSION_EVENT_TYPES_FALLBACK;
 }
+
 const KNOWN = knownSessionEventTypes();
 
+/** 可读类型集 = 当前 KNOWN ∪ 已装 dsh-session-format-* 迁移包认的旧类型（0.1.5 起会话格式有 v0→v1→v2→v3 迁移链）。
+ *  只比对当前表会把**可迁移的旧会话**误判为"harness 读不了"（#1538 的语义是"读不了"，迁移得了就不算）。
+ *  旧类型在磁盘日志里真实存在（v0 日志含 assistant/chunk、tool/code-dispatch 等），迁移包负责转换。 */
+function readableSessionEventTypes() {
+  const set = new Set(KNOWN);
+  for (const lib of SESSION_LIBS) {
+    const t = sessionTableFrom(lib);
+    if (t) for (const x of t) set.add(x);
+    for (const x of migratorTypesFor(lib)) set.add(x);
+  }
+  return set;
+}
+
+const READABLE = readableSessionEventTypes();
+
 function report(section, id, ok, detail, fix, src) {
   results.push({ section, id, ok, detail, fix, src: src ?? 'builtin' });
 }
@@ -193,27 +306,31 @@ function checkEnv() {
 
   // E6：锚点元检查（tripwire）——我们 S6/S7/S10 依赖的契约是否仍在安装的 dsh-session 里
   // 上游改名/重构会让我们的离线结论静默腐烂（boyin111-1 的 --verify-anchors 同款思路）
-  let sessionLib = null;
-  for (const p of (process.env.PATH || '').split(PATH_DELIM)) {
-    if (p.endsWith('node_modules/.bin') && existsSync(join(p, 'dsh'))) {
-      const lib = join(dirname(p), '@deepseek-ai', 'dsh-session', 'lib', 'index.js');
-      if (existsSync(lib)) { sessionLib = lib; break; }
-    }
-  }
+  const sessionLib = findSessionLib();
   if (!sessionLib) {
-    report('env', 'E6', true, '⚠ 未定位到 dsh-session，锚点未校验（回退内置假设：expandRow/end-seed/sourceEventSeqs）', '安装 dsh 后重跑可校验');
+    // r5 语义：锚点校验在此上下文"不适用"（找不到安装）——用 skip 而非静默 pass，理由写进 detail
+    reportSkip('env', 'E6', '未定位到 dsh-session（npx/全局/profile 三种布局都没有）——锚点未校验，S6/S7/S10 结论回退内置假设', undefined);
   } else {
     const src = readFileSync(sessionLib, 'utf8');
+    // 0.1.5 起 expandRow 从 dsh-session 移到会话格式迁移包（v0→v1→v2→v3），锚点随之迁移：
+    // S6 读的是磁盘上的 v0/v1 日志，其 chunk 展开契约由迁移链承载。
+    const migratorLib = (() => {
+      const nm = sessionLib.slice(0, sessionLib.indexOf(join('@deepseek-ai', 'dsh-session')));
+      const p = join(nm, '@deepseek-ai', 'dsh-session-format-v0-to-v1', 'lib', 'index.js');
+      return existsSync(p) ? p : null;
+    })();
+    const expandOk = /function expandRow[\s\S]*?row\.seq0/.test(src)
+      || (migratorLib ? /"assistant\/chunk":\s*disposition\(/.test(readFileSync(migratorLib, 'utf8')) : false);
     const anchors = [
-      ['expandRow 的 seq0+k 展开（S6 依赖）', /function expandRow[\s\S]*?row\.seq0/, src],
-      ['session/end-seed 字面量（S7 依赖）', /"session\/end-seed"/, src],
-      ['sourceEventSeqs 字段（S10 依赖）', /sourceEventSeqs/, src],
+      ['v0 chunk 展开契约（S6 依赖；dsh-session 的 expandRow 或迁移包 disposition）', expandOk],
+      ['session/end-seed 字面量（S7 依赖）', /"session\/end-seed"/.test(src)],
+      ['sourceEventSeqs 字段（S10 依赖）', /sourceEventSeqs/.test(src)],
     ];
-    const missing = anchors.filter(([, re]) => !re.test(src));
+    const missing = anchors.filter(([, okFlag]) => !okFlag);
     if (missing.length) {
       report('env', 'E6', false, `锚点缺失（上游可能改了契约，S6/S7/S10 结论需人工复核）: ${missing.map(([n]) => n).join('; ')}（${sessionLib.slice(-60)}）`, '对照上游变更更新 dsh-doctor 的对应检查');
     } else {
-      report('env', 'E6', true, `锚点齐全（${anchors.length}/3: seq0+k / session/end-seed / sourceEventSeqs）`, undefined);
+      report('env', 'E6', true, `锚点齐全（${anchors.length}/3: v0 chunk 展开 / session/end-seed / sourceEventSeqs）`, undefined);
     }
   }
 }
@@ -450,6 +567,71 @@ function checkProfile(name) {
   else report('profile', 'P7', true, 'cordis.patch.yml 结构正常（无 tab / 无 ~ insert / 无映射-序列混排）', undefined);
 
   // P8/P9 需要扫描 bundle 构建产物：收集目录下有限深度的 .js 文件（lib/dist/根 + main 入口，跳过 node_modules）
+
+/** 从 fromDir 向上找 node_modules 里的裸包目录（也查 profile 与 CLI 安装）；找不到返回 null。 */
+/** 用户 patch 中标记 `disabled: true` 的 entry id 集合（P16 用：区分"已禁用不会崩"与"启用即崩"）。 */
+function disabledPatchIds() {
+  const set = new Set();
+  const f = join(HOME, 'profiles', 'web', 'cordis.patch.yml');
+  if (!existsSync(f)) return set;
+  let text;
+  try { text = readFileSync(f, 'utf8'); } catch { return set; }
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const m = /^\s*-?\s*id:\s*['"]?([^'"\s]+)['"]?\s*$/.exec(lines[i]);
+    if (!m) continue;
+    for (let j = i + 1; j < Math.min(i + 4, lines.length); j++) {
+      if (/^\s*-?\s*id:/.test(lines[j])) break;
+      if (/^\s*disabled:\s*true\s*$/.test(lines[j])) { set.add(m[1]); break; }
+    }
+  }
+  return set;
+}
+
+function resolveInstalledPackage(spec, fromDir) {
+  const seg = spec.split('/');
+  const name = spec.startsWith('@') ? seg.slice(0, 2).join('/') : seg[0];
+  const cands = [];
+  let d = fromDir;
+  for (let i = 0; i < 6; i++) {
+    cands.push(join(d, 'node_modules', name));
+    const up = dirname(d);
+    if (up === d) break;
+    d = up;
+  }
+  const profiles = join(HOME, 'profiles');
+  if (existsSync(profiles)) for (const p of readdirSync(profiles)) cands.push(join(profiles, p, 'node_modules', name));
+  for (const lib of SESSION_LIBS) {
+    const nm = lib.slice(0, lib.indexOf(join('@deepseek-ai', 'dsh-session')));
+    cands.push(join(nm, name));
+  }
+  return cands.find((c) => existsSync(join(c, 'package.json'))) || null;
+}
+
+/** 包入口的命名导出集合；**静态不可确定时返回 null**（CJS 入口 / `export *` / 找不到入口）。 */
+function packageNamedExports(pkgDir) {
+  let pkg;
+  try { pkg = JSON.parse(readFileSync(join(pkgDir, 'package.json'), 'utf8')); } catch { return null; }
+  let rel = null;
+  const pick = (v) => (typeof v === 'string' ? v : (v && typeof v === 'object' ? (pick(v.import) ?? pick(v.default) ?? pick(v.require) ?? null) : null));
+  if (pkg.exports) rel = pick(typeof pkg.exports === 'object' && pkg.exports['.'] !== undefined ? pkg.exports['.'] : pkg.exports);
+  if (!rel) rel = pick(pkg.module) ?? pick(pkg.main) ?? 'index.js';
+  let code;
+  try { code = readFileSync(join(pkgDir, rel), 'utf8'); } catch { return null; }
+  if (/export\s*\*/.test(code)) return null;            // 星号再导出 → 导出面不确定
+  const named = new Set();
+  for (const m of code.matchAll(/export\s*\{([^}]*)\}/g)) {
+    for (const x of m[1].split(',')) {
+      const n = x.trim().replace(/^type[ \t]+/, '').split(/[ \t]+as[ \t]+/).pop().trim();
+      if (n) named.add(n);
+    }
+  }
+  for (const m of code.matchAll(/export\s+(?:async\s+)?(?:const|let|var|function|class)\s+([A-Za-z_$][\w$]*)/g)) named.add(m[1]);
+  if (/export\s+default/.test(code)) named.add('default');
+  if (named.size === 0) return null;                      // 没有任何 ESM 导出语法 → 视为 CJS，不判
+  return named;
+}
+
   const bundleDirs = new Map(); // bundle 名 → 目录（可解析的）
   for (const b of bundles) {
     const d = findPkg(b);
@@ -707,6 +889,74 @@ function checkProfile(name) {
   } catch (e) {
     report('profile', 'installed_bundle', false, `bundle 版本对比异常: ${e.message.slice(0, 60)}`, undefined);
   }
+
+  // P15：关键文件 BOM 检测（#5176：package.json 被意外加 BOM 头导致 JSON 解析失败）
+  // UTF-8 BOM = EF BB BF = '\uFEFF'，pnpm/node 解析 JSON 时不认识 BOM → 报错
+  const bomTargets = [
+    join(dir, 'package.json'),
+    join(dir, 'cordis.patch.yml'),
+    join(dir, 'settings.yaml'),
+  ];
+  // 加上 config/*.json
+  const configDir = join(dir, 'config');
+  if (existsSync(configDir)) {
+    try {
+      for (const f of readdirSync(configDir)) {
+        if (f.endsWith('.json')) bomTargets.push(join(configDir, f));
+      }
+    } catch { /* skip */ }
+  }
+  const bomFiles = [];
+  for (const f of bomTargets) {
+    if (!existsSync(f)) continue;
+    try {
+      const head = readFileSync(f, 'utf8').slice(0, 1);
+      if (head === '\uFEFF') bomFiles.push(f.replace(dir + '/', ''));
+    } catch { /* skip */ }
+  }
+  if (bomFiles.length > 0) {
+    report('profile', 'P15', false, `检测到 BOM 头（#5176：JSON/YAML 解析将失败）: ${bomFiles.join(', ')}`, '用文本编辑器打开文件，删除首字符（BOM/U+FEFF）后保存；或运行: sed -i "" "1s/^\xEF\xBB\xBF//" <file>');
+  } else {
+    report('profile', 'P15', true, '关键文件无 BOM 头', undefined);
+  }
+
+  /* P16：插件命名导入的导出缺失检测（#5864：一个缺失导出 → 整棵插件树 boot 崩溃循环、
+   * 启动器每 ~11s 重启一次）。静态校验 `import { A } from 'pkg'` 的 A 是否存在于已装 pkg 的命名导出。
+   * **能不确定就不判**（本检查 warn 级，宁可漏报不误报）：解析不到包 / 入口含 `export *` / CJS 入口 /
+   * 条件导出取不到 ESM 入口 / type-only 导入 / 非裸说明符 —— 全部跳过，且只在"确定不存在"时报。 */
+  const exportIssues = [];
+  const disabledIds = disabledPatchIds();
+  for (const [b, d] of bundleDirs) {
+    const seen = new Map(); // "pkg → 缺失符号" → 证据文件
+    for (const f of collectJsFiles(d)) {
+      const code = readJs(f);
+      for (const m of code.matchAll(/(?:^|\n)[ \t]*(?:import|export)[ \t]*\{([^}]*)\}[ \t]*from[ \t]*['"]([^'"]+)['"]/g)) {
+        const names = m[1].split(',').map((x) => x.trim().replace(/^type[ \t]+/, '').split(/[ \t]+as[ \t]+/)[0].trim()).filter((x) => x && x !== 'default' && /^[A-Za-z_$][\w$]*$/.test(x));
+        const spec = m[2];
+        if (!names.length || !/^[@A-Za-z]/.test(spec) || spec.startsWith('node:')) continue; // 只查裸包说明符
+        // 带子路径的说明符（pkg/sub、pkg/a/b）走各自的 exports 入口，静态判定不可靠 → 跳过（防误报）
+        const segs = spec.split('/');
+        if (spec.startsWith('@') ? segs.length > 2 : segs.length > 1) continue;
+        const pkgDir = resolveInstalledPackage(spec, d);
+        if (!pkgDir) continue; // 解析不到 → 不判
+        const exports = packageNamedExports(pkgDir);
+        if (!exports) continue; // 静态不可确定 → 不判
+        const miss = names.filter((n) => !exports.has(n));
+        if (miss.length) seen.set(`${spec} → ${miss.join(', ')}`, relative(d, f));
+      }
+    }
+    if (seen.size) {
+      // patch 的 id 可能是裸名（dsh-noema）而 bundle 名是 scoped（@zseven-w/dsh-noema）→ 去 scope 归一化比对
+      const bare = (n) => (n.startsWith('@') ? n.split('/').slice(1).join('/') : n);
+      const isDisabled = disabledIds.has(b) || disabledIds.has(bare(b));
+      exportIssues.push(`${b}（${[...seen].map(([k, f]) => `${k} [${f}]`).join('; ')}）${isDisabled ? '〔当前已禁用，重新启用会 boot 失败〕' : '〔已启用 → boot 会失败〕'}`);
+    }
+  }
+  if (exportIssues.length) {
+    report('profile', 'P16', false, `插件导入了已装包未提供的导出（#5864：整棵插件树 boot 崩溃循环，启动器会反复重启）: ${exportIssues.join('; ')}`, '把该插件升到与所装 @deepseek-ai/* 版本匹配的版本（或降级/移除）；这类错误在 boot 期是硬失败，单条 entry 会拖垮整棵树');
+  } else {
+    report('profile', 'P16', true, '插件命名导入均在已装包的导出里（静态可判定的部分）', undefined);
+  }
 }
 
 /* ================= session ================= */
@@ -757,7 +1007,7 @@ function checkSession(targetPath) {
     let d; try { d = JSON.parse(line); } catch { continue; }
     const seq = d.seq; if (typeof seq === 'number' && seq > maxSeq) maxSeq = seq;
     // S8：未知事件类型且未标 ignorable（#1538：harness 整包拒绝）
-    if (!STORAGE_ROW_TYPES.has(d.type) && !KNOWN.has(d.type) && d.ignorable !== true) {
+    if (!STORAGE_ROW_TYPES.has(d.type) && !READABLE.has(d.type) && d.ignorable !== true) {
       s8Violations.push(`"${d.type}"`);
     }
     // S6（官方版）：按 decodeStorageRecord 语义展开 chunk 行，构建 seq==index 事件流
@@ -827,7 +1077,7 @@ function checkSession(targetPath) {
     const seen = [...new Set(s8Violations)].slice(0, 5).join(', ');
     report('session', 'S8', false, `未知事件类型且无 ignorable 标记（#1538，harness 将整包拒绝）: ${seen}${new Set(s8Violations).size > 5 ? ` 等 ${new Set(s8Violations).size} 种` : ''}`, '该日志由更新版本/外部插件写入，当前 harness 无法读取；升级 harness 或标记 ignorable');
   } else {
-    report('session', 'S8', true, `所有事件类型均在 KNOWN_SESSION_EVENT_TYPES 内（${KNOWN.size} 种）`, undefined);
+    report('session', 'S8', true, `所有事件类型均可读（当前表 ${KNOWN.size} 种 + 迁移包旧类型，共 ${READABLE.size} 种）`, undefined);
   }
 
   // S7：end-seed 之后出现低于种子末尾 seq 的事件（#1497：已提交尾部被重放）
@@ -848,6 +1098,170 @@ function checkSession(targetPath) {
   }
 }
 
+/* S12：迁移拒载预检（#6045/#6328/#6311）——升级/打开前列出会被"会话格式迁移链"拒绝的会话。
+ * 规则不硬编码：从已装 dsh-session-format-* 迁移包自省（v0→v1 的 descriptor 版本门 + v2→v3 的 source.kind 白名单）；
+ * 定位不到迁移包 → skip（不猜）。surface 事件集合照抄 v2→v3 的 assertSource 调用点（user/assistant/tool/inbox/title-llm-request）。 */
+const SURFACE_SOURCE_TYPES = new Set(['user/message', 'assistant/message', 'tool/result', 'agent/inbox/spliced', 'session/title-llm-request']);
+
+function findPkgLib(nm, name) {
+  const a = join(nm, '@deepseek-ai', name, 'lib', 'index.js');
+  if (existsSync(a)) return a;
+  const store = join(nm, '.pnpm');
+  if (existsSync(store)) {
+    for (const d of readdirSync(store)) {
+      if (!d.startsWith(`@deepseek-ai+${name}@`)) continue;
+      const b = join(store, d, 'node_modules', '@deepseek-ai', name, 'lib', 'index.js');
+      if (existsSync(b)) return b;
+    }
+  }
+  return null;
+}
+
+function migrationRules() {
+  const out = { descriptorVersion: null, kinds: null, from: null };
+  for (const lib of SESSION_LIBS) {
+    const nm = lib.slice(0, lib.indexOf(join('@deepseek-ai', 'dsh-session')));
+    if (out.descriptorVersion === null) {
+      const v0 = findPkgLib(nm, 'dsh-session-format-v0-to-v1');
+      if (v0) {
+        try {
+          const m = /data\["version"\]\s*!==\s*(\d+)/.exec(readFileSync(v0, 'utf8'));
+          if (m) { out.descriptorVersion = Number(m[1]); out.from = nm; }
+        } catch { /* 忽略 */ }
+      }
+    }
+    if (out.kinds === null) {
+      const v3 = findPkgLib(nm, 'dsh-session-format-v2-to-v3');
+      if (v3) {
+        try {
+          const m = /const SOURCE_KINDS = new Set\(\[(.*?)\]\);/s.exec(readFileSync(v3, 'utf8'));
+          if (m) {
+            const items = [...m[1].matchAll(/"([^"]+)"/g)].map((x) => x[1]);
+            if (items.length) { out.kinds = new Set(items); out.from = nm; }
+          }
+        } catch { /* 忽略 */ }
+      }
+    }
+    if (out.descriptorVersion !== null && out.kinds !== null) break;
+  }
+  return out;
+}
+const MIGRATION_RULES = migrationRules();
+
+/** 加载已装的会话格式目录（真实迁移链入口）。找不到/加载失败返回 null —— 调用方回退启发式规则或 skip。 */
+function loadFormatCatalog() {
+  for (const lib of SESSION_LIBS) {
+    const nm = lib.slice(0, lib.indexOf(join('@deepseek-ai', 'dsh-session')));
+    const cands = [join(nm, '@deepseek-ai', 'dsh-session-format-catalog', 'lib', 'index.js')];
+    const store = join(nm, '.pnpm');
+    if (existsSync(store)) {
+      for (const d of readdirSync(store)) {
+        if (d.startsWith('@deepseek-ai+dsh-session-format-catalog@')) {
+          cands.push(join(store, d, 'node_modules', '@deepseek-ai', 'dsh-session-format-catalog', 'lib', 'index.js'));
+        }
+      }
+    }
+    for (const c of cands) {
+      if (!existsSync(c)) continue;
+      try {
+        const req = createRequire(c);
+        const m = req(c);
+        if (m?.sessionFormatCatalog?.createRestore) return m.sessionFormatCatalog;
+      } catch { /* 试下一个 */ }
+    }
+  }
+  return null;
+}
+const FORMAT_CATALOG = loadFormatCatalog();
+
+/** 用**真实迁移链**在内存里跑一遍：返回 null = 可恢复，否则返回拒载原因（截断）。
+ *  比复刻规则更准（上游每条 fail-closed 规则都覆盖，且自动跟随版本变化）。 */
+function realChainRefusal(text) {
+  if (!FORMAT_CATALOG) return undefined; // undefined = 链不可用（区别于 null = 可恢复）
+  const lines = text.split('\n').filter((l) => l.trim());
+  if (!lines.length) return null;
+  try {
+    const header = JSON.parse(lines[0]);
+    const r = FORMAT_CATALOG.createRestore(header, { validation: 'current', recovery: 'strict' });
+    for (let i = 1; i < lines.length; i++) r.decodeRow(JSON.parse(lines[i]));
+    r.finish();
+    return null;
+  } catch (e) {
+    return String(e?.message ?? e).replace(/\s+/g, ' ').slice(0, 140);
+  }
+}
+
+
+/** 单个会话文本 → 会被迁移链拒绝的理由（空数组 = 可读）。 */
+function migrationRefusals(text) {
+  const reasons = [];
+  const { descriptorVersion, kinds } = MIGRATION_RULES;
+  let version = null;
+  for (const ln of text.split('\n')) {
+    if (!ln.trim()) continue;
+    let d; try { d = JSON.parse(ln); } catch { continue; }
+    if (version === null && d.type === 'session' && typeof d.version === 'number') { version = d.version; continue; }
+    if (version === 0 && descriptorVersion !== null && d.type === 'subagent/descriptor' && d.data?.version !== descriptorVersion) {
+      reasons.push(`subagent/descriptor version ${d.data?.version} 会被 v0→v1 拒载（该迁移只接受 version ${descriptorVersion}）`);
+    }
+    if (version === 2 && kinds && SURFACE_SOURCE_TYPES.has(d.type)) {
+      const s = d.data?.source ?? d.data?.message?.source;
+      if (s && typeof s.kind === 'string' && !kinds.has(s.kind)) reasons.push(`source.kind "${s.kind}" 会被 v2→v3 拒载（不在 ${kinds.size} 项白名单内）`);
+    }
+  }
+  return [...new Set(reasons)];
+}
+
+/**
+ * 全会话库迁移拒载预检（#6045：某真实库 321 个日志中 282 个中招；#6328：一个坏产物拖垮搜索索引）。
+ * 在升级/打开前给出"哪些会话将会打不开"，避免列表里看着在、点开就报错。
+ */
+function scanMigrationRefusals() {
+  if (!wants('session')) return;
+  if (MIGRATION_RULES.descriptorVersion === null && !MIGRATION_RULES.kinds) {
+    reportSkip('session', 'S12', '未定位到 dsh-session-format-* 迁移包，拒载规则不可自省——预检跳过（不猜）', undefined);
+    return;
+  }
+  const root = join(HOME, 'sessions');
+  if (!existsSync(root)) { reportSkip('session', 'S12', '无会话目录，迁移拒载预检不适用', undefined); return; }
+  const files = [];
+  for (const u of readdirSync(root)) {
+    const sd = join(root, u);
+    if (!existsSync(sd)) continue;
+    for (const s of readdirSync(sd)) {
+      const f = existsSync(join(sd, s, 'session.jsonl.zstd')) ? join(sd, s, 'session.jsonl.zstd') : join(sd, s, 'session.jsonl');
+      if (existsSync(f)) files.push(f);
+    }
+  }
+  if (files.length === 0) { reportSkip('session', 'S12', '未发现会话日志', undefined); return; }
+  const refused = [];
+  let viaChain = 0;
+  for (const f of files) {
+    let text;
+    try { text = f.endsWith('.zstd') ? execFileSync('zstd', ['-dc', f], { maxBuffer: 512 * 1024 * 1024 }).toString('utf8') : readFileSync(f, 'utf8'); }
+    catch { continue; } // 解压失败由 S11 报，不在 S12 重复
+    const chain = realChainRefusal(text);
+    if (chain === undefined) {
+      // 真实链不可用 → 回退启发式规则（覆盖子集，明确标注）
+      const rs = migrationRefusals(text);
+      if (rs.length) refused.push(`${basename(dirname(f))}（${rs[0]}）`);
+    } else if (chain !== null) {
+      viaChain++;
+      refused.push(`${basename(dirname(f))}（${chain}）`);
+    }
+  }
+  const rule = FORMAT_CATALOG
+    ? `判定方式：真实迁移链（format-catalog ${FORMAT_CATALOG.currentVersion ? `v${FORMAT_CATALOG.currentVersion}` : ''}，内存试迁移）`
+    : `判定方式：启发式规则（descriptor v${MIGRATION_RULES.descriptorVersion ?? '?'} / source.kind ${MIGRATION_RULES.kinds?.size ?? '?'} 项；真实链不可用，覆盖子集）`;
+  if (refused.length) {
+    report('session', 'S12', false,
+      `迁移拒载预检：${refused.length}/${files.length} 个会话会被当前迁移链拒绝（#6045/#6328/#6311——列表里看着在、点开即报 cannot safely transform / unsupported descriptor version）: ${refused.slice(0, 5).join('; ')}${refused.length > 5 ? ` 等 ${refused.length} 个` : ''}`,
+      `① 先备份这些会话目录（勿删）；② 等上游放宽版本门（#6045 已报）；③ 应急：把日志里 subagent/descriptor 的 version 改为 ${MIGRATION_RULES.descriptorVersion ?? 3} 再迁移（改前务必备份）`);
+  } else {
+    report('session', 'S12', true, `迁移拒载预检：${files.length} 个会话均可被当前迁移链读取（${rule}）`, undefined);
+  }
+}
+
 /* S11：全会话扫描 —— 损坏 → 隔离建议；超大 → 冷打开物化风险（#1550：一个坏/超大会话拖垮整个服务器） */
 function scanAllSessions() {
   if (!wants('session')) return;
@@ -885,7 +1299,7 @@ function scanAllSessions() {
     for (let li = 0; li < lines.length; li++) {
       const ln = lines[li]; if (!ln.trim()) continue;
       let d; try { d = JSON.parse(ln); } catch { problems.push(`行 ${li + 1} 无法解析`); continue; }
-      if (!STORAGE_ROW_TYPES.has(d.type) && !KNOWN.has(d.type) && d.ignorable !== true) problems.push(`未知类型 ${d.type}`);
+      if (!STORAGE_ROW_TYPES.has(d.type) && !READABLE.has(d.type) && d.ignorable !== true) problems.push(`未知类型 ${d.type}`);
       if (d.type === 'session/end-seed' && typeof d.seq === 'number') { lastSeed = d.seq; seedIdx = posList.length; }
       const t = d.type;
       if (t === 'text-chunks' || t === 'reasoning-chunks' || t === 'tool-call-chunks') {
@@ -945,6 +1359,8 @@ catalogSeverity.set('E3-node', 'warn');
 catalogSeverity.set('installed_bundle', 'warn');
 catalogSeverity.set('P13', 'warn');
 catalogSeverity.set('P14', 'warn');
+catalogSeverity.set('P15', 'error');
+catalogSeverity.set('P16', 'warn');
 
 function bundledCatalog() {
   const p = new URL('./checks.json', import.meta.url);
@@ -1175,6 +1591,26 @@ export function localVersion() {
 }
 
 /** 返回 { current, latest, available }；latest=null 表示无法确认（离线且无缓存）。 */
+
+/** 简易 semver 比较（支持 x.y.z-预发布）：a>b 返回 1，a<b 返回 -1，相等 0。
+ *  用途：本地版本可能领先 npm（未发布的工作版本），只比"不相等"会误报"新版本可用"。 */
+function compareVersions(a, b) {
+  const parse = (v) => {
+    const [core, pre = ''] = String(v).split('-');
+    const nums = core.split('.').map((x) => parseInt(x, 10) || 0);
+    return { nums, pre };
+  };
+  const A = parse(a); const B = parse(b);
+  for (let i = 0; i < 3; i++) {
+    const x = A.nums[i] ?? 0; const y = B.nums[i] ?? 0;
+    if (x !== y) return x > y ? 1 : -1;
+  }
+  if (A.pre === B.pre) return 0;
+  if (!A.pre) return 1;   // 正式版 > 预发布
+  if (!B.pre) return -1;
+  return A.pre > B.pre ? 1 : -1;
+}
+
 export async function checkForUpdate({ noRemote = false, fetchImpl, home = HOME } = {}) {
   const current = localVersion();
   if (noRemote || typeof fetchImpl !== 'function') return { current, latest: null, available: false };
@@ -1182,7 +1618,7 @@ export async function checkForUpdate({ noRemote = false, fetchImpl, home = HOME
   const readCache = () => { try { const d = JSON.parse(readFileSync(cachePath, 'utf8')); return d && typeof d.latest === 'string' ? d : null; } catch { return null; } };
   try {
     const c = readCache();
-    if (c && Date.now() - statSync(cachePath).mtimeMs < UPDATE_TTL_MS) return { current, latest: c.latest, available: c.latest !== current };
+    if (c && Date.now() - statSync(cachePath).mtimeMs < UPDATE_TTL_MS) return { current, latest: c.latest, available: c.latest !== current && compareVersions(c.latest, current) > 0 };
   } catch { /* 回退 */ }
   try {
     const ac = new AbortController();
@@ -1194,7 +1630,7 @@ export async function checkForUpdate({ noRemote = false, fetchImpl, home = HOME
       const latest = data?.['dist-tags']?.latest;
       if (typeof latest === 'string') {
         try { mkdirSync(dirname(cachePath), { recursive: true }); writeFileSync(cachePath, JSON.stringify({ latest, checkedAt: new Date().toISOString() })); } catch { /* 缓存失败不影响 */ }
-        return { current, latest, available: latest !== current };
+        return { current, latest, available: latest !== current && compareVersions(latest, current) > 0 };
       }
     }
   } catch { /* 离线/超时 → last-known-good */ }
@@ -1270,6 +1706,7 @@ async function run() {
     try { checkProfile(profileArg); } catch (e) { report('profile', 'P0', false, `profile 检查异常: ${e.message.slice(0, 100)}`); }
     try { checkSession(sessionArg); } catch (e) { report('session', 'S0', false, `session 检查异常: ${e.message.slice(0, 100)}`); }
     try { scanAllSessions(); } catch (e) { report('session', 'S11', false, `全会话扫描异常: ${e.message.slice(0, 100)}`); }
+    try { scanMigrationRefusals(); } catch (e) { report('session', 'S12', false, `迁移拒载预检异常: ${e.message.slice(0, 100)}`); }
   }
 
   // 远程检查目录（层 A）：内置检查之后追加执行；--no-catalog 只走内置副本；--security-only 跳过
@@ -1397,6 +1834,12 @@ async function run() {
     }
     const baseExit = baseFail > 0 ? 2 : baseWarn > 0 ? 1 : 0;
     const exitCode = Math.max(baseExit, secExit);
+    // v1.1 remediation（#1719 ADOPTED：ciceroyang 提名、两位 reviewer +1）：opt-in --remediation，
+    // 顶层有序数组 ["[<checks[].name>] <fix>", ...]，仅失败且有 fix 的项；键名取到首个 ']'，']' 是唯一禁用字符。
+    // 不带 --remediation 时字段不存在（r5 消费者字节稳定）。
+    const remediation = process.argv.includes('--remediation')
+      ? results.filter((r) => !r.ok && r.fix && !r.id.includes(']')).map((r) => `[${r.id}] ${r.fix}`)
+      : null;
     const out = {
       schema: 'dsh-doctor/v1',
       tool: 'dsh-doctor',
@@ -1406,6 +1849,7 @@ async function run() {
       summary,
       ok: exitCode === 0,
       checks,
+      ...(remediation ? { remediation } : {}),
     };
     if (securityMeta.enabled) {
       out.security = { enabled: true, summary: securityMeta.summary, ...(securityMeta.error ? { error: securityMeta.error } : {}) };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moonquake2004/dsh-doctor",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "Offline diagnostic for DeepSeek Harness — 28 built-in + 5 catalog checks across env/profile/session (Layer A checks-as-data), self-update (Layer B), and a semi-automatic LLM observer (Layer C, --observe); Doctor panel in web UI settings.",
   "main": "lib/index.js",
   "files": [