[Bug] 一条 turn/end 的 reason 为 null 会让整个会话列表变空白（Agent Team 场景，附定位与修复建议）

[jianger114]

环境

• 应用：@deepseek-ai/dsh-desktop 0.2.0-rc.2（Electron 44.0.0 / Node 24.18.1 / win32 x64）
• profile bundles 含 @deepseek-ai/dsh-experimental-agent-team-profile
• 会话存储：session.v4.jsonl.zstd

现象

• 对话列表完全空白：新旧会话都不显示，重启应用无效
• 但工作区列表正常，会话数据文件也完好（未丢失、未被删除）
• 只有「轨迹」视图还能看到内容，普通会话视图加载不出来
• DevTools Console 持续报错：

[session-controller] event feed subscriber failed: TypeError: Cannot read properties of null (reading 'kind')
    at Object.start (client.js:998:1)
    at ConversationNodeAssembler.replayContext (client.js:2271:1)
    at ConversationNodeAssembler.acceptMatch (client.js:2199:1)
    at ConversationNodeAssembler.dispatchInput (client.js:2152:1)
    at ConversationNodeAssembler.matchInput (client.js:2128:1)
    at BoundConversation.replaceWindow (client.js:1941:1)

TypeError: Cannot read properties of null (reading 'kind')
    at turnProcessAlwaysOpen (client.js:1554:1)
    at ChatNodeSeat (client.js:1678:1)

slot entry crashed in 'conversation.view': TypeError: Cannot read properties of null (reading 'kind')

根因

客户端 turnProcessAlwaysOpen 的空值保护不足：

function turnProcessAlwaysOpen(node) {
    const location = node?.location;
    if (location?.kind !== "turn" && location?.kind !== "step") return false;
    const reason = location.turn.end?.data.reason.kind;   // ← 只保护了 end
    return location.turn.status === "open" || reason === "aborted" || reason === "error";
}

end?. 只保护 end 本身。只要存在一条 reason 为 null 的 turn/end，这里就抛 TypeError，导致该会话的 event feed 订阅整体失败，进而会话视图崩溃。

复现数据

扫描 88 个会话、约 12.2 万条记录，发现恰好 1 条 reason 为 null 的 turn/end。
其余 377 条 turn/end 的 reason.kind 分布：completed 343 / aborted 18 / error 14 / interrupted 2 —— 可见 null 属异常值。

该条记录的上下文（turn 因收到子代理消息而结束）：

[484] step/end            {turn:1, step:65}
[485] turn/end            {turn:1, reason:null}     ← 应为 {"kind":"completed"}
[486] workspace/changes   {turn:1}
[487] agent/inbox/spliced "Agent <subagent-id> sent a message: ..."
[488] turn/start          {turn:2}

推测：Agent Team / agent/inbox 触发 turn 结束时，没有补齐 reason.kind。

影响面（这条最严重）

单条记录的局部异常 → 全局 UI 不可用。 一个坏 turn 让所有会话（包括完全健康的那些）从列表里消失，用户会以为「对话全丢了」。这比数据本身的问题更值得修。

建议

1. 写入侧：agent/inbox 触发 turn 结束时补齐 reason.kind，至少不要写 null。
2. 读取侧：改为 location.turn.end?.data.reason?.kind，并对无法解析的记录降级跳过，而不是让整个 event feed 订阅失败。

临时处理（已验证有效）

把该条 reason 手工补成 {"kind":"completed"} 后，会话列表立即恢复正常。

相关

• 类似失效模式：Platform defect: one withdrawing conversation definition kills the session's event feed, and no history page can load past it #8822（one withdrawing conversation definition kills the session's event feed）
• 会话存储迁移相关：[Bug] DSH 0.2.0-rc.2 crashes (SIGABRT, exit 134) during session format v3→v4 migration — and older pinned versions can no longer read the store #8617、[Bug] 更新到最新 master 后，部分历史会话无法加载（v0 迁移校验过度严格） #5978

[PerryLink]

这条的要害是一条坏事件让整份列表不可渲染——请按这个定性提

1. 你给的三条事实已经把范围钉住了

• 会话列表完全空白（新旧都不显示），重启无效；
• 工作区列表正常、会话数据文件完好（未被删）；
• 只有「轨迹」视图还能看到内容；
• Console 持续报 [session-controller] event feed subscriber failed: TypeError: Cannot read…。

⇒ 合起来说明：数据没坏，是"由事件流推导列表"的那一步坏了——而它一旦抛错，整个列表就不出来。你说触发是"一条 turn/end 的 reason 为 null"，这与"can't read properties of…"完全相容（某处直接读了 reason.xxx，而 reason 是 null）。

2. 建议把诉求写成"一条坏记录不得让整份视图失败"

这比你现在的"请修这个空指针"更容易被接受，也覆盖同类：

事件流推导（列表投影）应当逐事件容错：单条事件的字段缺失/非法应被跳过或降级显示，而不是让整份列表渲染失败。

理由：reason: null 很可能不是唯一的坏形态（历史版本写过的事件、被手工编辑过的日志、未来的新事件类型都会带来类似情况）。逐条容错是一次性解法，修这个空指针只是治一个点。

3. 请补三样（让维护者能一步定位）

1. 完整的 TypeError 行（Cannot read properties of null (reading '…') 里那个属性名才是定位关键，你贴的是截断的）；
2. 那条 turn/end 的原始 JSON（证明 reason 确实是 null，而不是缺字段——这两种在代码里的处置可能不同）；
3. 版本基线：你写的是桌面 0.2.0-rc.2；⚠️ 当前最新是 0.2.1-alpha.1（packages/session 96 个提交、apps/desktop 94 个）⇒ 请在新版复核是否仍复现。

另外：我按你给的字符串在源码里检索 event feed subscriber failed 没有命中（它可能是产物里的措辞，或前缀由包名拼出）。⇒ 请补源码侧的包与符号（哪个订阅函数），否则维护者只能从产物里找。

4. 这是同日"坏输入处理"主题的第三个面

帖	坏输入	后果
#8792	两个插件同 id	宿主崩溃，应用起不来
#8817	MCP 输入 schema 未校验	参数静默渲染成 unknown
你这条	一条 turn/end 的 reason 为 null	整份会话列表空白

⇒ 三者共同点：一条坏数据导致大范围不可用（崩溃 / 静默劣化 / 整视图失败）。建议互相引用并写成同一条原则——"坏记录必须被局部化，不得升级为整体失败"。写成这一类，比三条各自修更容易被排期。

一条边界

我确认的是按你给的字符串在源码检索无命中（因此需要源码符号），以及你三条事实之间逻辑自洽（数据完好 + 只有列表不可渲染 ⇒ 推导层问题）。**"reason: null 是触发原因"**以你的定位为准——我没有该会话文件。

[spicytougan]

补三样（回应 @PerryLink）：

1. 完整 TypeError 行：TypeError: Cannot read properties of undefined (reading 'kind')，栈：at Object.match ← ConversationNodeAssembler.dispatchInput / matchInput / replaceWindow ← BoundConversation.replace / accept ← MutableSessionEventSource.publish / replace（另一条路径是 at turnProcessAlwaysOpen ← ChatNodeSeat，见 [Bug] Conversation pane goes blank on all sessions — TypeError: Cannot read properties of null (reading 'kind') #9156）。
2. 那条记录的原始 JSON：

{"type":"turn/end","seq":537,"time":1791482813806,"data":{"turn":2,"reason":null}}

是显式 null，不是缺字段（同一批共 8 条 / 5 个会话）。但渲染栈里打印的是 undefined —— 推测投影层把 null 变成了 undefined（未证实，请核对；这正是你问的 null / 缺字段之别）。
3. 版本基线：桌面 0.2.0-rc.2 复现；npm 最新 @deepseek-ai/dsh-client-ui-chat@0.2.1-alpha.2 的 11 处未保护读取仍在（end?.data.reason.kind ×3、event.data.reason.kind ×6、reason.reason.kind ×2）；@deepseek-ai/dsh-agent-loop@0.1.0-rc.6 的 let turnEnds = null; 也仍在。

另外补充：写出 null 的不止 agent/inbox。已确认的第二条路径是第三方插件用自定义 kind 调 agent.cancel → 内核 abortedCancelCause 的 default: assertNever 抛错 → turnEnds 保持 null → 落盘 reason:null（逐字代码与本机时间线见 #9156 的评论：插件 01:59:11 落盘，首条 null 02:05:34）。

赞同你提的定性：诉求写成「一条坏记录不得让整份视图失败」；同时写入侧也要堵，否则读侧每加一层容错，还会出现新的写出者。

---

本报告由账号主指导 DeepSeek V4.1 Flash 在 Hermes 上进行整理创作（因为我的 DeepSeek Harness 刚才挂掉了）。

[argszero]

Two measured write-side facts for this report; full chain in #9156 (discussioncomment-18866513).

The reason: null is a regression introduced in dsh-agent-loop@0.1.7. Verified by unpacking the published tarballs:

• 0.1.6-alpha.2 — the turn catch writes the abort reason verbatim (turnEnds = { kind:'aborted', reason: signal.reason }); abortedCancelCause does not exist in that build.
• 0.1.7-rc.2, 0.2.0-rc.2, 0.2.1-alpha.2 — the catch is const cause = abortedCancelCause(signal); if (cause !== void 0) { turnEnds = {kind:'aborted', reason: cause}; throw error }, and abortedCancelCause ends in default: return assertNever(cause). A cause whose kind is outside the closed union (user | parent | disposed | hook) throws inside the catch, so the assignment never runs, turnEnds is still null, and the finally appends turn/end with reason: null.

The write boundary does not check this field. Session.append snapshots the payload and calls validateSessionEventData (packages/core/session/src/surface.ts:166), which inspects surface message slots, request/header and tool/result only — turn/end.reason is a TypeScript-only invariant, so the null is admitted silently. That is why it is durably on disk.

On your projection hypothesis: the append-time snapshot does not convert null to undefined — walkJsonValue (packages/util/values/src/index.ts) has an explicit if (current === null) { assign(task.destination, null); continue }. So the log preserves the explicit null; the undefined seen in the render stack originates from a later stage, not from that projection.

Your suspicion that the writer is not necessarily agent/inbox holds: any agent.cancel(cause) with an out-of-union kind reaches that same default branch. The form that survives is the plugin-owned member — { kind:'hook', reason:'…' }, the shape core itself uses for deepseek-account/signed-out. Related: a repaired record must carry the full {"kind":"aborted","reason":{"kind":"hook","reason":"…"}}; the shorthand {"kind":"aborted"} trips the reason.reason.kind reads downstream.

[argszero]

Both producers located — they were our own plugins, and both are fixed.

Following up on this report, whose diagnosis of the null turn/end reason is what made the search possible: we swept every published package in this ecosystem for agent.cancel( callers and found exactly two producers, both community plugins, both passing a bare string where the closed AgentCancelCause union is required. Both are fixed and on npm:

• @argszero/cordis-plugin-thinking-loop-guard@0.1.12
• @argszero/cordis-plugin-turn-budget-guard@0.1.2

Both now emit the hook member they own — { kind: 'hook', reason: <configured cause> }, the shape core itself uses for deepseek-account/signed-out — so an aborted turn persists { kind: 'aborted', reason: { kind: 'hook', reason: '…' } } instead of a null. The plugin config surface is unchanged.

Two things that are easy to get wrong when tracing this class, and that the thread may want recorded:

1. The stack trace does not point here. The throw is in the turn loop's catch, at abortedCancelCause → default: return assertNever(cause). The loop therefore never reports a bad cause: the turnEnds = { kind: 'aborted', reason: cause } assignment never runs, let turnEnds = null survives into the finally, and the append writes the null. The stack in the log points at the original error that aborted the turn. Locating the producers took a source sweep — agent.cancel( across every published package — not log reading.
2. Nothing on the write path objects. Session.append's validateSessionEventData inspects surface messages, request/header and tool/result only, so a guard on reason would be a core-side change, not something a plugin can supply. In the meantime the only plugin-side lever is to not produce it.

Version boundary, measured rather than read: 0.1.6-alpha.2 has no abortedCancelCause at all (the abort reason was written verbatim), so it cannot produce a null this way. 0.1.7-rc.2, 0.2.0-rc.2 and 0.2.1-alpha.2 all carry the reader, and on all three a bare string still yields reason: null. scripts/witness-cancel-cause.mjs (in either plugin repo) measures exactly that by extracting the shipped abortedCancelCause out of each published @deepseek-ai/dsh-agent-loop tarball and executing it, rather than restating the source.

Generalisation for anyone writing a plugin that aborts a turn: the union is closed, but one member belongs to plugins and hook is it. The cast cause as unknown as AgentCancelCause typechecks and is still wrong — that is exactly what we were shipping.

[xiaoshenming]

补一条实测，可能改变这条缺陷的归类：文件本身是合法的。

我把一份真实 v4 会话里某条 turn/end 的 reason 改成 null 后实测：

• assertReleasedV4Relationships（关系折叠）：接受；
• Session.fromRestore（seed 构造）：接受。

折叠对 turn/end 只比对 data.turn 与"没有开着 step"，根本不看 reason 的形态。所以这条不是"日志坏了"，而是客户端在合法输入上崩了 —— 归类应该落在客户端健壮性（turnProcessAlwaysOpen 读 null.kind），而不是数据修复。这也解释了你们观察到的"会话数据文件完好、工作区列表正常"。

一个实用的定位办法（对已经中招、列表空白的人）：turn/end 的 reason 为 null 的那一条会话就是罪魁，把它移出 store（或改名）列表就回来了。逐会话 dump 后 grep 即可：

dsh-session-surgeon export <id> | grep '"reason":null'

我们这轮没有为它加探测器，理由写在上面：它不是磁盘拒读，修它需要替写入方"猜"一个 reason.kind（{kind:"aborted"} 是形状合法的候选，但那是猜，不是从日志还原）。如果之后有更多人撞上、且需要一个"告诉我该删哪条"的开关，我们再补一条只报告的健康码 —— 现在不加，是不想为一个已经修好写入方的形状扩合同。

@argszero 那条"两个生产者都是社区插件、都已修复"的记录很有用；剩下这半边（客户端别在 reason: null 上崩）才是这条帖真正的长期修复。

[PerryLink]

@spicytougan 你让我核对的那条假设，我核完了 —— 投影层没有把 null 变成 undefined，@argszero 的反驳成立。另外 @xiaoshenming 的归类我独立验证了，也成立。补一条决定了为什么 CI 从来没抓到它的细节。

1. null 在写入侧被完整保留

packages/util/values/src/index.ts:120：

if (current === null) {

⇒ append 期的 walkJsonValue 对 null 有显式分支，落盘的就是显式 null（与你给的原始 JSON 一致：{"type":"turn/end",…,"data":{"turn":2,"reason":null}}）。

所以渲染栈里看到的 undefined 来自更晚的阶段，不是写入投影。@argszero 这条判断准确。

2. 写入侧确实不检查这个字段

packages/core/session/src/surface.ts:159-171：

• :161 文档注释原文 → "This does not validate complete event payloads or embedded provider streams."
• :166 validateSessionEventData(event, subject)
• :171 if (SURFACE_EVENT_TYPES.has(event.type) && isRecord(data)) ⇒ 只看 surface 消息槽、request/header、tool/result 那几类

⇒ turn/end.reason 是纯 TypeScript 不变量，运行期无人过问。这就是它能落盘的原因。

3. 归类的半边：文件是合法的（@xiaoshenming 对）

packages/session/session-format-v3-to-v4/src/relationships.ts:281-282：

case 'turn/end':
  if (this.turn === null || data['turn'] !== this.turn || this.step !== null) throw new SessionFormatError('turn/end does not match the open turn with no open step')

只比对 turn 与"没有开着 step"，完全不看 reason。 我在该文件里 grep reason —— 0 命中。

⇒ 所以这不是"日志坏了"，而是客户端在合法输入上崩了。归类应落在客户端健壮性（读侧），数据修复只是止血。这条我同意 @xiaoshenming，并且它改变了修复落点。

4. ⭐ 没人提到的一条：两处注释各自编码了同一个错误假设

这是我认为最值得记进这条帖的东西 —— 它解释了为什么这个 bug 能活到线上：

(a) abortedCancelCause 的分支被明确排除出覆盖率统计。 packages/core/agent-loop/src/agent.ts:80-95：

function abortedCancelCause(signal: AbortSignal): AgentCancelCause | undefined {
  if (!signal.aborted) return undefined
  const cause = signal.reason as AgentCancelCause      // :83  ← 无运行期校验的断言
  switch (cause.kind) {
    case 'user': case 'parent': case 'disposed': return { kind: cause.kind }
    case 'hook': return { kind: 'hook', reason: cause.reason }
    /* v8 ignore next -- cancel accepts the closed AgentCancelCause union */   // :91
    default:
      return assertNever(cause)                        // :93
  }
}

:91 那句 v8 ignore 的理由是"cancel accepts the closed union" —— 也就是说代码自己声明了这个分支不可能到达，于是把它从覆盖率里摘出去了。而插件传一个裸字符串时 cause.kind === undefined，正好落进这个被摘掉的分支。

(b) turn/end 的写入处也断言了同一件事。 agent.ts:384-387：

} finally {
  try {
    // oxlint-disable-next-line typescript/no-non-null-assertion -- every exit assigns a turn ending
    this.session.append('turn/end', { turn, reason: turnEnds! })   // :387

:386 的注释写着 "every exit assigns a turn ending"，于是用了 turnEnds!。但 agent.ts:368-374 的 catch 里，abortedCancelCause(signal) 本身就抛（:93 的 assertNever），所以 :372 的 turnEnds = { kind: 'aborted', reason: cause } 永远不会执行 ⇒ :312 的 let turnEnds: TurnEndReason | null = null 原样带进 finally ⇒ turnEnds! 在运行期就是 null，写盘成 reason: null。

⇒ 两条注释（覆盖排除 + 非空断言）都建立在"这个联合一定是封闭的"之上。 插件破坏了这个前提，两处防护同时失效，而且都不会被 CI 或覆盖率发现。

附带一个细节：assertNever 定义在 packages/util/values/src/index.ts:12 —— 与第 1 节那个"保留 null"的 walkJsonValue 在同一个模块里。这个模块一边小心地保住 null，一边在另一个函数里因为"联合封闭"的假设而抛错，两个行为叠起来正好产出了你看到的现象。

5. 由此得到的两侧修法（我都同意，但顺序要摆正）

• 读侧（长期修复，且这条帖的要害）：客户端不得在合法输入上崩。turn/end.reason 的形态是合法输入空间的一部分，turnProcessAlwaysOpen 那条路径读 reason.kind 前必须容错。
• 写侧（纵深，需内核改动）：因为 validateSessionEventData 只覆盖 surface 槽，插件无法自行提供这个守卫。可行的两点：① abortedCancelCause 的 default 分支不要抛（改成退化成一个安全的 kind，或至少不让 catch 自身抛）；② 把 turn/end.reason 纳入运行期校验，让坏值在写入时被拒。①比②更根本 —— ②只是把"落盘 null"换成"落盘时报错"，而①能让 abort 路径无论如何都写出一个合法 reason。

我的建议：agent.ts:386 那条 "every exit assigns a turn ending" 的注释应当与 :91 的 v8 ignore 一并重审 —— 它们是同一个假设的两处化身，改一处不改另一处会留下同样的坑。

6. 一处我无法核实的

@argszero 引的 scripts/witness-cancel-cause.mjs（从已发布 tarball 里抽出 abortedCancelCause 执行）与两个插件的修复版本，我没有下载核对，所以不对那部分表态。上面第 4 节的两条注释则是 origin/master 上逐字可查的。