[Bug] 重启后子代理列表全部显示"不可用"：v0 日志的 header.system 无法迁移到 v3，且错误被降级为可重试的 unavailable

[Linus-hub-code]

环境

项	值
DSH 版本	0.1.5-rc.2（在 0.1.5-rc.1 上复现，升级后仍存在）
profile	web
平台	Windows 11，Node v24.18.0
相关包	@deepseek-ai/dsh-subagent、@deepseek-ai/dsh-session-query、@deepseek-ai/dsh-session-format-v2-to-v3

---

症状

Web GUI「任务管理」面板中，某父会话派生的全部子代理不再显示标题／模式／活动状态，只显示各自 UUID + 灰色「不可用」。

• 重启 DSH 前：正常显示 Analyze docs and experiments 等标题
• 重启 DSH 后：全部退化为 UUID + 「不可用」
• 子代理日志完好无损：标签、事件、完整历史都能用官方 API 读出来

---

最小复现

1. 会话中派生若干子代理。
2. 让某个子代理再派生子代理（delegationDepth: 2）。
3. 完全重启 DSH，使这些子代理成为冷会话。
4. 打开该父会话的「任务管理」面板。

期望：显示子代理标题／模式／状态。
实际：UUID + 「不可用」。

---

根因

链路如下：

① 冷读取

dsh-subagent/lib/index.js 的 resolveColdIdentity()（2240-2248 行）：

try {
  observation = await query.observeSession(childId, ...)
} catch (error) {
  return {
    kind: "diagnostic",
    id: childId,
    reason: sessionQueryCode(error) === "SESSION_QUERY_CORRUPT_SESSION"
         || sessionQueryCode(error) === "SESSION_QUERY_SOURCE_CONFLICT"
      ? "corrupt" : "unavailable"        // ← 落在这里
  }
}

② 冷读触发 v3 迁移

observeSession → SessionObservationReader.read() → 冷读 → 迁移到当前格式。

③ 迁移器直接拒绝

dsh-session-format-v2-to-v3/lib/index.js:236：

if (Object.hasOwn(record(data["header"], "request header"), "system"))
  throw new SessionFormatUnsupportedMigrationError(
    "format v3 request/header rejects retired header.system")

④ 错误被错误分类

SessionFormatUnsupportedMigrationError 既不是 SESSION_QUERY_CORRUPT_SESSION 也不是 SESSION_QUERY_SOURCE_CONFLICT，于是被归为 unavailable（语义是"暂时失败、下次重试"），而不是"此日志格式需要升级 harness"。

因为每次重列都必然失败，该占位文案永久留存。

---

证据

涉及的子代理日志均为 version: 0，其中各有一条违规的 request/header：

4e88f0bd-…  events=1118  request/header 带 header.system（6910 字符）
5460df61-…  events=1131  request/header 带 header.system（6910 字符）
65dd6b63-…  events=582   request/header 带 header.system（6910 字符）
f7076563-…  events=628   request/header 带 header.system（6910 字符）

用 0.1.5-rc.2 自带的格式目录验证：

const { sessionFormatCatalog } = await import(
  '<dsh>/node_modules/@deepseek-ai/dsh-session-format-catalog/lib/index.js')

sessionFormatCatalog.encodeCurrentEvent(v0RequestHeaderEvent)
// throws: format v3 request/header rejects retired header.system

同一批数据经 createRestore(...) 与 decodeEvent(...) 零失败 ——
说明日志可读、内容完整，失败点纯粹是 v3 迁移策略拒绝了已废弃字段。

为什么只有子代理受影响

父会话重启后仍是活会话（sessions.get(id) !== undefined），走 projections.snapshot(live) 快路径，不读盘、不迁移。子代理是冷会话，必须回读磁盘，于是撞上迁移拒绝。

---

两个可独立修复的缺陷

缺陷 1：迁移器拒绝而非转换

header.system 已被 system/message 取代，而迁移器自己就认识这个类型 ——
dsh-session-format-v2-to-v3/lib/index.js 第 9 行的 SURFACE_TYPES 明确列有 "system/message"。

因此理论上可自动转换（把 header.system 抽成一条 system/message 事件），不必让整份日志不可用。若确实不做自动转换，也应明确指引"请升级 harness"，而不是让用户看到一个像是临时故障的状态。

值得注意的是：dsh-session-persistence-jsonl/lib/index.js:960（refuseForeignFormatVersion 的注释）已经声明了正确意图 ——

must see "upgrade the harness", never "corrupt session log".

但该路径只覆盖"外来格式版本"，没有覆盖 v0 → v3 的 header.system 这一情形，也没有贯彻到 subagent 的 catalog 路径。

缺陷 2：错误分类吞掉了不可重试的失败

dsh-subagent/lib/index.js:2245-2248 只把两种错误码映射为 corrupt，其余一律 unavailable，导致"格式不受支持、重试无用"被错误地划入"可重试"。

已验证：dsh-subagent 全文中 reason: 只出现 "corrupt"（2160、2255、2261 行）与 "unavailable"（2247 行），从不产生 "unsupported"。

因此浏览器端已有的 subagentDiagUnsupported（「子代理记录版本不受支持」）在该路径上永远不可达 —— 而它恰恰是本 bug 最该显示的文案。

---

建议修复

1. dsh-session-format-v2-to-v3：把 header.system 自动转换为 system/message（推荐），或至少将该失败标记为不可重试。
2. dsh-subagent：在 resolveColdIdentity 的错误分类中识别 SessionFormatUnsupportedMigrationError，映射为 unsupported，使 UI 显示「子代理记录版本不受支持」。
3. 可选：subagents.list 的载荷保留诊断原因字符串，便于用户与开发者定位。

---

影响

• 数据无损：日志完整，仅列表渲染退化。
• 用户无法从 UI 进入这些子代理的历史，也看不到标题 —— 已完成任务的成果实际被"藏起来"。
• 任何经历过 v0 → v3 格式演进、且派生过子代理的用户，重启后都可能命中。

---

附：如何自行验证（无需 GUI）

const { sessionFormatCatalog } = await import(
  '<dsh>/node_modules/@deepseek-ai/dsh-session-format-catalog/lib/index.js')

// 取任一带 header.system 的 v0 request/header 事件：
sessionFormatCatalog.encodeCurrentEvent(event)
// → throws "format v3 request/header rejects retired header.system"

[argszero]

复核结论：迁移器其实会转换 header.system，真正可证的是分类链

感谢这份报告——复现步骤、日志证据、以及"两个可独立修复的缺陷"的拆分方式都很清楚。我按你给的位置逐条核对了源码，并且用 0.1.5-rc.2 的已发布产物把整条迁移链跑了一遍。结论有一条重要更正，和一处比原报告更深的确证。我不是 maintainer，以下只代表我自己的读码与实测。

---

一、更正：v0 → v3 迁移不拒绝 header.system，它正好做了你建议的转换

packages/session/session-format-v2-to-v3/src/migration.ts 的 transformEvent 开头就是：

if (event.type === 'request/header') {
  const { system, ...header } = record(data['header'], 'request header')
  const prompt = typeof system === 'string' ? system : ''
  if (prompt !== this.prompt) this.emitSystem(prompt, event, context)
  source = { ...event, data: { ...data, header } }   // ← system 被摘掉，余下的 header 才进 v3
}

也就是说：system 被抽出来注入一条 system/message（migration.ts:109-135，source 为 { kind: 'plugin', plugin: '@deepseek-ai/dsh-system-prompt' }），而进入 v3 的那条 request/header 已经不含 system 了。这正是你"建议修复 1"里说的转换。

我用 0.1.5-rc.2 的已发布包实测（@deepseek-ai/dsh-session-format-catalog@0.1.5-rc.2，currentVersion = 3），构造一条 v0 日志：turn/start → step/start → request/header{system: 6910 字符} → step/end → turn/end：

OK -> v3 | types: turn/start,step/start,system/message,system/message,request/header,step/end,turn/end
migrated request/header still carries system? false
system/message chars=6914   head="SYSTEM PROMPT xxxx..."
prompt preserved in full? true

即：迁移成功、header.system 被剥掉、6910 字符的提示词逐字保全。同一段代码在 createRestore 下也返回 v3。所以报告 §③「迁移器直接拒绝」这一环，在你的日志形态下我无法重现；encodeCurrentEvent 抛的那个错，来自另一条路径。

二、那个错是原生 V3 的防御性准入检查，不是转换器

format v3 request/header rejects retired header.system 由 assertV3StructuralRow（session-format-v2-to-v3/src/payload.ts:212-219）抛出，只有两个生产者：

• codec.ts:84 的 assertV3RowAdmission — 由 session-persistence-jsonl/src/format.ts:491 的当前代扫描器调用，注释写得很直白："This scanner accepts only current-generation files. Owned structural refusal must precede its recoverable-tail suppression."
• releaseV3EventAdmission（validation.ts:81）。

关键证据在你没提到的一个测试里：session-persistence-jsonl/tests/migration-refusal.spec.ts 有一个 nativeRefusals 用例组，标题是 "refuses native V3 … instead of falling back to readable V2"。它先存一份 v2 日志并确认能正常读成 v3，然后写一份 v3 日志、其中 request/header 带 system，断言 open(id, 'read'|'write') 以 SessionFormatUnsupportedError 拒绝。

所以这条规则的对象是"已经是 v3、却还带着 v0 字段"的文件：v3 里 system 已由 system/message 承载，再出现即属自相矛盾。它是一道准入闸，不是"拒绝转换"。顺带一提，它在 0.1.3-alpha.2 的 catalog 上跑不到——那个版本的 catalog currentVersion = 2（我实测过），链在 v2 就停了。

三、缺陷 2 是真的，而且比"一个三元表达式"更深：分类在三层上各丢一次

你的第二点我完整核实并放大了一层：

1. 最底层根本没有这个档位。 session-query/src/config.ts:29-46 的 SessionQueryErrorCode 是一个封闭联合，成员里没有任何 unsupported 语义的码；最接近的是 SESSION_QUERY_PERSISTENCE_FAILED 和 SESSION_QUERY_CORRUPT_SESSION。
2. 映射函数按名字只认两种。 session-query/src/observation.ts:327-341 的 mapPersistenceFailure：SessionPersistenceNotFoundError → not found；SessionPersistenceCorruptionError → SESSION_QUERY_CORRUPT_SESSION；其余一律 SESSION_QUERY_PERSISTENCE_FAILED。SessionFormatUnsupportedError 没有分支，直接落进"后端失败、可重试"——这就是你说的"降级为 available/unavailable"的来源。
3. 子代理只读两个码。 subagent/subagent/src/list-children.ts:340-343：只有 SESSION_QUERY_CORRUPT_SESSION / SESSION_QUERY_SOURCE_CONFLICT 记 corrupt，其余 unavailable。与你的观察一致。

但这里有一处需要修正你的表述：maintainer 是知道这件事的，而且写在了契约注释里。subagent/subagent/src/control-types.ts:70-78：

'corrupt' for a settled candidate whose projection fold served no identity (a missing, malformed, or unrecognized-version descriptor — deliberately undistinguished) … unavailable when the candidate's Session observation was absent or transiently unreadable (retried on the next listing). unsupported is never produced; it remains in the union for consumers that route on it.

所以 unsupported 不是"漏了"，而是被有意留白的。这条注释也顺带指出你报告里最精确的那个问题：文档把 unavailable 定义为"缺失或暂时读不到、下次重列会重试"，而"格式不受支持"是确定性、永久性的——它既不该是 unavailable，按文档的既有口径也更接近 corrupt（"unrecognized-version descriptor, deliberately undistinguished"）。

这一点会影响修法：只加 'unsupported' 是"新建语义"；而把永久性格式拒绝从"可重试"里挪出去，是回归文档既有契约。两条路都行，但后者代价更小、且不与你引用的 dsh-session-persistence-jsonl 那段 "must see 'upgrade the harness', never 'corrupt session log'" 的意图冲突。

另外补一个你没提到的点：api/session-controller/src/history.ts:354-364 确实用 reason: 'unsupported'，但那是另一个条件（identity === undefined || identity.seq < inheritedEventCount，即"描述符缺席"），与"格式不受支持"不是同一件事。所以"浏览器端已有该文案却不可达"成立，但可达路径比"永远不可达"要细一点。

四、还差什么才能真正定位你那份日志

我能在已发布产物上复现的"确定性拒绝"是这几类（都归 SessionFormatUnsupportedMigrationError）：

• v3 文件里带 header.system（上面第一节的 native 准入）；
• 消息 source.kind 不在 SOURCE_KINDS 白名单内（payload.ts:118-120，cannot safely transform unclassified message source）——这是 v0→v1 阶段就会拒的，且插件自定义 source kind 正是常见触发源；
• 事件类型不在 RELEASED_V2_EVENT_DISPOSITIONS 内；
• request/header 的 reason 不是 initial|resume|change|series。

而你那份日志的形态（version 0、header.system 6910 字符）我实测是能迁过去的。所以你的 §③ 目前是"从 encoder 报错反推的因果"，缺一环直接证据。最有价值的一步是拿到 resolveColdIdentity 里那个被吞掉的原 error：list-children.ts:336 的 catch 分支，error 的 message/name 就是你 UI 上"不可用"背后的真实原因。如果你愿意，在 catch 里临时打一行 console.warn(String(error))，或者把其中一个失败子代理的日志头部 + 第一条被拒的行贴出来，我就能把根因钉死。

五、复现与打包级验证

上面所有结论都在已发布产物上跑过，不是只读源码：

npm i @deepseek-ai/dsh-session-format-catalog@0.1.5-rc.2 \
      @deepseek-ai/dsh-session-format-v2-to-v3@0.1.5-rc.2 \
      @deepseek-ai/dsh-session-format-v0-to-v1@0.1.5-rc.2 \
      @deepseek-ai/dsh-session-format-v1-to-v2@0.1.5-rc.2

对照 0.1.3-alpha.2 的 catalog（currentVersion = 2，链停在 v2、不剥 system），可以确认你的 repro 结论是随版本走的——这点报告里没区分，值得补一句，因为它决定了 ① 手上有 v0 日志的用户到底会看到什么。

六、关于"两个缺陷"的排序建议

• 缺陷 2 优先，且不必先改迁移器：分类链（3 层）是已经可达的确定性缺陷，migration-refusal.spec.ts 已经证明了原生 V3 拒绝走真实 open 路径；改完之后你报告的 UI 症状会自动从"暂不可用"变成可诊断文案之一。
• 缺陷 1 建议先降级为"待定"：因为 header.system 本身会被转换，真正需要你确认的是那份日志里另一个让迁移失败的因素。若你希望"整份日志在格式不受支持时仍可浏览"，那是产品决策（要不要为 v3 保留 system 的兼容读），建议单独开帖，不要和分类修复绑在一起。

七、一个可能的缓解（不是修复）

我这边有一个"会话可读性审计"的想法：挂一个插件，在启动或按需时用公开的 @deepseek-ai/dsh-session-format-catalog 遍历会话存储、对每个会话跑一次 createRestore + 逐行 decode，把哪些会话在打开时会失败、以及失败的确切原因输出成一份清单。它不能改变 core 的分类，但能让"UI 只显示不可用、日志本身完好"这种情况下用户至少拿到确切原因。如果你觉得有用我可以做出来；但这与上面的 core 修复是两件事，我不会把它当成"问题已解"。

---

声明：我不是本项目 maintainer，以上是个人复核，不代表项目结论。所有行号基于 master（c291e7961a）；实测基于 npm 上的 0.1.5-rc.2 产物。第一节的"迁移成功"是已发布包实测，第二节的 native 拒绝路径是仓库测试 + 源码确认。

[PerryLink]

核实结论:缺陷2(错误分类)成立且比原帖更深;缺陷1不成立——转换器恰好会做原帖建议的自动转换;缺的是那份日志被拒的真实错误.

1. 缺陷1不成立:packages/session/session-format-v2-to-v3/src/migration.ts:50-55 在 transformEvent 起手就摘出 header.system,经 emitSystem(:109-136)注入 system/message(source 插件 dsh-system-prompt),进 v3 的 request/header 已不含 system. 原帖 lib/index.js:236 的 throw 在本机构建产物同处命中,但它是 payload.ts:212-219 的 assertV3StructuralRow——原生 v3 防御性准入,由 encodeCurrentEvent(=currentEncoder.encodeEvent,session-format/src/catalog.ts:164→codec.ts:71-75)、decodeRow(codec.ts:27)与当前代扫描器(session-persistence-jsonl/src/format.ts:491)触发;migration-refusal.spec.ts:74-87,171 把它钉在 native V3 用例组. 原帖复现命令喂的是「当前格式编码器」而非迁移链,抛错不能反推迁移会拒. 此点与 [Bug] 重启后子代理列表全部显示"不可用"：v0 日志的 `header.system` 无法迁移到 v3，且错误被降级为可重试的 `unavailable` #6455 评论1(argszero)一致,他并用 0.1.5-rc.2 发布包实测 v0 日志带 6910 字符 header.system 迁移成功、逐字保全.
2. 缺陷2成立,三层各丢一次:session-query/config.ts:29-46 码表封闭、无 unsupported 档;observation.ts:327-341 只按名字认两类,SessionFormatUnsupportedError 原样透传(index.ts:673-687)后落 PERSISTENCE_FAILED;list-children.ts:340-343 只把两个码映 corrupt,余者 unavailable. 'unsupported' 确从不产生(control-types.ts:67-77 有意留白),history.ts:352-366 用它的语义是「描述符缺席」,与格式错误不同.
3. 修复:分类层把 SessionFormatUnsupportedError 映为 corrupt 或新开 unsupported,回归 refuseForeignFormatVersion 的既有意图(format.ts:334-337);不必改迁移器. 原帖 4 份日志的真实拒绝因子待其 catch 处原始 error 确认. 与 The v0 migration refuses `subagent/descriptor` version 2 on the number alone, so sessions written before 2026-08-24 will not open #6045(已核)、sessions: one non-vocabulary turn/end abort cause makes the whole session unreadable, with no in-product recovery #6236、升级到 0.1.5 后，以前的一些老会话打不开了 #6151 同属「冻结代际严格读 vs 写侧不设防」家族.