Bug: 未捕获的 .kind 裸读导致 turn 以 UNKNOWN 失败（reason 可为 null/undefined）

[alasong]

Bug report: turn/end 的 reason 为 undefined 时，多处监听器裸读 .kind 导致整轮失败

目标版本：@deepseek-ai/* 0.2.1-rc.5（DeepSeek Harness Desktop，macOS）
仓库：https://github.com/deepseek-ai/deepseek-harness
报告日期：2026-10-31
证据来源：本机 ~/.dsh/sessions/ 下 340 个会话日志（统计时共 1813 条 turn/end），
以及 /Applications/DeepSeek Harness.app/Contents/Resources/app.asar 中经 sha256 校验的源码。

---

摘要

会话的某一轮结束后，界面只显示一行失败：

Cannot read properties of undefined (reading 'kind')

code 为 UNKNOWN。这不是模型或网络问题：它是 turn/end 事件上 .kind 的裸解引用
（前面任何一段可能是 undefined），在进程内抛出的 TypeError 被 agent loop 捕获，
再以 {kind: "error", error: {message, code: "UNKNOWN"}} 记进日志。

本机历史上发生 10 次，涉及 5 个会话。一旦某个会话触发，后续轮次会持续失败：
session-f7217f05 从 turn 11 连续崩到 turn 14，四轮全挂。会话不会自我恢复。

---

复现到的部分

1. 代码扫描：6 个独立位置存在同样的裸读

判据：.kind 之前的一段路径可能是 undefined。

#	包	文件:行	代码
1	dsh-goal-round-driver	lib/index.js:274	if (event.data.reason.kind === "max-tokens") {
2	dsh-goal-round-driver	lib/index.js:278	if (event.data.reason.kind !== "aborted") return;
3	dsh-session-telemetry	lib/index.js:224	case "turn/end": return event.data.reason.kind === "error" ? "error" : "info";
4	dsh-subagent	lib/index.js:226	switch (end?.data.reason.kind) { ← ?. 只护了最外层
5	dsh-subagent	lib/index.js:2668	lastTurnCompleted: event.data.reason.kind === "completed"
6	dsh-agent	lib/index.js:63 与 lib/types/consumed-work.js:24	function accountsForClaim(reason) { switch (reason.kind) {

第 6 项在两份产物里各出现一次，是同一个缺陷。

复现命令（本机使用；gates/test_turn_reason_guard.py 是本地脚手架，不入本报告所属仓库）：

python3 gates/test_turn_reason_guard.py <上述 5 个文件>
→ REASON-GUARD-FAIL 7 处裸读 turn/end 的 reason

2. 机制：turn/end 的 reason 允许为空

dsh-agent-loop/lib/index.js 的 turn 收尾：

let turnEnds = null;                                          // 951
...
} catch (error) {                                             // 1011
    turnEnds = { kind: "error", error: error instanceof LlmError ? error.failure : {
        message: errorChain(error), code: "UNKNOWN" } };      // 1020-1026
} finally {
    this.session.append("turn/end", { turn, reason: turnEnds });  // 1028-1032
}

step() 存在一条 return concluded ? { kind: "completed" } : null; —— concluded 为假时返回
null，随后被赋给 turnEnds。reason 因此可以为 null，而所有读 reason.kind
的地方都没有考虑这种情况。

已用最小复现确认：把 accountsForClaim / foldConsumedWork 原样抽出，喂入
turn/start → 认领(removedCount:1) → turn/end 缺 reason 的事件序列，得到与线上完全相同的
TypeError: Cannot read properties of undefined (reading 'kind')。

3. 真实失败分布

会话	崩溃轮次
session-1905fd5d-8797-4e39-b…	turn 1、2
session-567a0e1b-14e1-422d-8…	turn 1
session-1e2d2d0f-9ca3-4d58-a…	turn 6
session-63df0969-1efa-404a-a…	turn 24、25
session-f7217f05-141c-4b17-b…	turn 11、12、13、14

10 次失败的消息字面完全一致：Cannot read properties of undefined (reading 'kind')。

---

尚未定位的部分（如实说明）

具体是哪一处抛出，未能确定。

已经排除的候选，都附判据：

• dsh-goal-round-driver：session/event 监听只在 turn/end 分支读 reason.kind；而崩溃轮的输入
  来源是 user 与 tool-jobs，不是 goal 轮次，第 274 行在该路径上未被调用。
• dsh-session-telemetry：captureEvent 包在 contain() 内，其实现是
  try { step() } catch (e) { this.ctx.logger.warn(...) }，异常被吞掉，不会让整轮失败。
• 格式迁移 dsh-session-format-v0-to-v1：normalizeLegacyTurnEnd 先经
  releasedV0Record() 校验，不匹配时抛 malformedLegacy，不是 TypeError。

一个尚未解释的矛盾：现场 10 次全部是 "undefined"，而按 turnEnds = null 的路径应报
"null"。两者不一致，说明 reason 是在到达监听器之前就被置空的，而不是本文件里
let turnEnds = null 这条赋值造成的。这一点是推断，未实跑。

---

建议的修复方向

任选其一，二者不冲突：

1. 统一加可选链：把上述 6 处改为 event.data.reason?.kind、end?.data?.reason?.kind、
   reason?.kind。这是最小改动，单独即可消除崩溃。
2. 在源头拒绝空 reason：agent loop 的 finally 里，若 turnEnds == null 则回落为
   { kind: "error", error: { message: "turn ended without a recorded reason", code: "UNKNOWN" } }，
   并在 turn/end 的类型定义里把 reason 标成不可空。这样任何新增的监听器都不会再踩到。

建议 1 和 2 一起做：脚本侧兜底，类型侧收口。

---

附加观察（同批会话，未合并进本问题）

同一批日志里还有两类 UNKNOWN 失败，与本 report 的 .kind 问题无关，单列备查：

• next is not a function × 3（session-2d2c8398 等），发生在 workspace/changes 之后
• cannot get property "workingDirectory" without inject × 2

出现位置提示是插件钩子链问题，需要单独排查。

[Muguett-DBY]

感谢整理这么详细的现场信息。我核对了 npm 发布的 0.2.1-rc.5，有两个可能影响排查和修复方向的细节：

1. step() 返回 null 后，turn() 会继续循环；只有 turnEnds 有值时才会从循环退出，异常和取消则会设置各自的结束原因。因此，单凭 step() 返回 null，还不能推断最终写出了 reason: null。对应的当前源码也有这个判断。

2. 可选链需要留意一个副作用：在一组合成事件中，先有 turn/start、随后 inbox 认领了输入（removedCount: 1）、没有 step/start、最后的 turn/end 缺少 reason。若同时给 accountsForClaim 和 epochStopReason 的读取加可选链，rc.5 的 epochStopReason 会返回 completed。它原本把“没有结束事件”和“正常完成”共用一个分支；对于“已有结束事件但原因缺失”，也许应单独返回错误或报告无效事件，避免误报成功。相关分支在这里。

我用 OpenAI Codex 提取并检查了 rc.5 的实际方法，上述测试对会话、调度等依赖用了桩；没有复现完整 Desktop 环境，也还不能确定现场的 reason 是在哪里变成 undefined 的。