[Bug] ptc 模式下中断/报错后 tool/ptc-dispatch* 落盘于 turn 之外，导致 session 历史永久无法加载

[iuuuuuuuu]

现象

某个会话打开时报错，整份历史不可读，无降级：

历史加载失败：stored session "session-xxx" is corrupt:
SessionFormatError: tool/ptc-dispatch-start is outside an open turn

环境

项	值
DSH 发行版	0.2.2-alpha.2（bundled）
@deepseek-ai/dsh-tools	0.2.1-rc.5
@deepseek-ai/dsh-session	0.2.1-rc.5
@deepseek-ai/dsh-session-persistence-jsonl	0.2.1-rc.5
OS	Windows 10 19045 / Node v25.9.0
agentPreset	ptc

触发条件

不是必现，但已复现 3 个独立会话损坏，共同点很稳定：

1. 会话跑在 ptc preset（只有 run_code 桥接才会产生 PTC 派发事件）
2. 损坏位置之前最近的 turn 以 aborted(user) 或 error(上游 401 / 502 TLS handshake eof) 结束
3. 孤立事件总是 tool/ptc-dispatch-start + tool/ptc-dispatch 成对出现，位置固定在 turn/end 之后、下一个 turn/start 之前

三个会话的孤立事件数量分别是 2 / 2 / 16（16 条 = 8 对，连续多轮中止时累积）。

实际落盘序列（实例）

seq=2242  turn/end   {"turn":3,"reason":{"kind":"completed"}}
seq=2243  tool/ptc-dispatch-start   ← 越界
seq=2244  tool/ptc-dispatch         ← 越界
seq=2245  subagent/catalog
seq=2246  agent/inbox/spliced
seq=2247  turn/start {"turn":4}

根因定位

写端在 packages/core/tools（@deepseek-ai/dsh-tools）的 run_code PTC 桥接里。以下行号取自发行版 bundle lib/index.js，源码对应 run_code 的 start() / settle 分支：

两条 append 路径没有任何 turn 存活判断：

// settle 分支：结果回来就写，不问 turn 还在不在
agent.session.append("tool/ptc-dispatch", {
  rootCallId, parentCallId, subCallId, name,
  arguments: normalized.logged, isError: result.isError,
  ...error/meta/content
});

// pendingQueue 项的 start()
async start() {
  exec.agent?.session.append("tool/ptc-dispatch-start", {
    rootCallId, parentCallId, subCallId, name, arguments: normalized.logged
  });
  ...
}

但同一个对象另外两个入口是有守卫的：

if (runOver()) throw new Error(`run_code run is over (...); ${name} not dispatched`);   // 调用入口
if (runOver()) throw new Error(`run_code run is over (...); ${name} result discarded`); // 结果回收

也就是说：同一个 runOver() 不变量，两个入口加了检查，两条真正写事件的路径漏了。

另外 abandon() 只做 reject(...)，没有取消已经排进 pendingQueue 的 start()，也没有在 append 前复查 runOver()，形成一个明确的竞态窗口。

时序

callSignal abort（用户中止 / LLM 报错）
  → onOuterAbort → runController.abort(reason)
  → agent 循环立刻写 turn/end，认为该轮已结束
  → 但 run_code 的 driver 协程仍在跑，pendingQueue 里已排队的 start()
    以及 settle 的 append 继续执行
  → tool/ptc-dispatch-start / tool/ptc-dispatch 落到 turn 之外
  → 紧接着 turn/start 开启下一轮
→ 坏数据落盘，本轮正常返回，无任何报错

为什么写入时没被拦住（关键）

同一个不变量，写端不守、读端死守：

层	行为
dsh-session append()	只做 validateSessionEventData（事件自身数据格式），不校验 turn 归属
dsh-session-persistence-jsonl requireTurn()	加载时严格校验，越界即抛 SessionFormatError，整份日志拒绝加载

结果：非法事件能静默落盘，只有当用户下次打开会话时才炸，而且没有 partial read / 降级恢复，一条坏事件让整段历史（本例 6000+ 事件）全部不可访问。

建议修复

1. dsh-tools（主责）：start() 与 settle 的 append 前加 if (runOver()) return;；abandon() 时把已排队的 pending 项标记为丢弃，避免 start() 在 abort 之后仍然执行
2. dsh-session（次责）：append() 对 turn 作用域事件做归属校验，写入时即抛错，把问题暴露在产生现场而不是下次加载
3. 读取器（加固）：单条非法事件降级为跳过 + 警告，而不是整份拒绝加载

已做的临时处置（供参考）

手工剔除越界事件并重映射其后所有 seq 引用，重映射范围需覆盖四处（少一处都会被验证器打回）：

• event.seq（必须 dense 连续）
• event.sourceEventSeqs（顶层字段，数字数组或 [start,end] 区间对，要求每个值 < 自身 seq 且唯一）
• event.surfaceOp.startSeq/endSeq
• data.*Seq / data.*Seqs 以及 data.*Range.{start,end}（compaction/prune 的 shadowedRange 键名是 start/end，不按 Seq 后缀命名，最容易漏）

修好后用官方 verifyJsonlCurrentGeneration 校验通过。tool/ptc-dispatch* 在 opaque 判定里不参与 surface，所以剔除它们不改变 surface 语义。

补充：第三个会话因为尾部有 91 条 compaction/prune，只重映射前三类字段时会被验证器以 compaction/prune shadowedSeqs do not name an exact current surface span 拒绝，必须同时处理 shadowedRange。这一点对将来做自动修复工具的人可能有用。

[iuuuuuuuu]

更正：问题不止 ptc preset

原帖把范围写成"ptc preset 专属"，这个表述不准确。我对本机 1914 个会话全量跑了官方 verifyJsonlCurrentGeneration，结果存在第二类错位，出现在 standard preset：

preset	会话数	验证失败
standard	1224	10
ptc	685	2（复核为并发写入假阳性，非损坏）
minimal	5	0

那 2 个 ptc 失败项报的是"事件数与期望不符"——因为我在统计事件数之后、验证器读取之前，文件仍被运行中的应用继续追加。属于并发读写，不是损坏。重新用准确计数复核，这 2 个会话实际是 0 越界。

第二类：step 编号在同一个 turn 内从头重数

9 个 standard 会话的失败签名完全一致，全是小会话（21–35 事件）：

seq=8   step/start  turn=1 step=1
seq=11  step/end    turn=1 step=1
seq=12  step/start  turn=1 step=1   ← 读取器期望 step=2
seq=19  step/end    turn=1 step=1
seq=20  turn/end    turn=1  {"kind":"aborted","reason":{"kind":"parent"}}

读取器规则（worker.cjs）：

case "step/start":
  if (this.turn === null || data.turn !== this.turn || this.step !== null
      || data.step !== this.nextStep) throw new SessionFormatError("step/start does not match the open turn and next step");
  this.step = this.nextStep;

case "step/end":
  this.requireStep(event, data);
  this.step = null;
  this.nextStep += 1;      // ← 这里之后 nextStep 应为 2

step/end 之后 nextStep 已经是 2，但写入方下一个 step/start 仍声明 step: 1。turn 没有切换（始终是 turn=1），所以这不是新开一轮，而是 turn 中途被打断后 step 计数器被重置回 1。

官方验证器对其中 3 个会话的实测确认：

FAIL ✗ step/start does not match the open turn and next step

两类问题的关系

	A 类（ptc）	B 类（standard）
报错	tool/ptc-dispatch-start is outside an open turn	step/start does not match the open turn and next step
错位对象	事件落在 turn 之外	turn 内 step 序号重数
损坏事件	tool/ptc-dispatch-start + tool/ptc-dispatch	step/start
疑似写入方	dsh-tools 的 PTC append 缺 runOver() 守卫	agent 循环的 step 记账（待定位）
时间分布	全部最近（11-02 / 11-03）	全部 4–12 天前，近期未再出现

相同点：都是事件坐标（turn / step）与实际状态不一致；写入侧不做校验，读取侧严格校验并整份拒绝加载。

不同点：A 类是"事件写在 turn 之外"；B 类是"step 序号在 turn 内被重置"。两者应分开定位和修复——B 类需要检查 turn 中途被打断（本例为 aborted / parent）后，重开 step 时是否复用了 nextStep 而没有重置它。

附带说明

此前修好的 3 个 ptc 会话经复查仍为 0 越界，文件在被应用继续正常追加，说明磁盘侧修复没有被打回。

[aturzone]

Cross-linking the first failure class from this thread (tool/ptc-dispatch* outside an open turn) plus a deterministic repro and patch.

Confirmed on master @ 8bd073392e (root 0.2.2-alpha.3, Linux, Node 24.22.2):

• Reader (packages/session/session-format-v3-to-v4/src/relationships.ts) rejects turn-scoped events outside a turn.
• Writer (Session.append) never tracked turn state.
• Trigger: agent-loop appends turn/end in a finally; the PTC start/settle lane keeps appending afterwards, so one abandoned run_code sub-call poisons the stored session. No model key is needed to reproduce: append turn/start, turn/end, tool/ptc-dispatch-start and feed the same events to restoreReleasedV4Artifact — writer accepts, reader throws.

Details, repro, and the fix design are in my comment on #11971: #11971 (comment)
Patch branch: https://github.com/aturzone/deepseek-harness/tree/fix/dsh-bug-triage

On your second class (step numbers restarting inside one turn, 9 small standard sessions): I suspect it is the same writer/reader disagreement one level deeper — the writer does not enforce step scope either — but I have not proven where the duplicate step/start comes from. I am reproducing it now. If you can paste one minimal failing session's seq/type dump (or attach one of the 9 logs), I will pin the exact append site.

[aturzone]

Follow-up on your second class (step numbers restarting inside one turn). I could not find a live writer path in current master that can produce that signature — here is the evidence, and what I need to go further.

Current writer analysis (packages/core/agent-loop/src/agent.ts, master 8bd073392e):

• The only step/start append site in the repository is agent.ts:361.
• It writes step = phase.step + 1 (:346), then commits phase.step = step (:362).
• phase.step is mutated in exactly two places: :362 (monotonic increment) and :431 (phase.step = 0), and :431 runs only after turn/end was appended, immediately before the next turn() call — which appends a fresh turn/start with turn + 1 (:334-340). The reader resets nextStep = 1 on turn/start, so that path is consistent.
• The driver loop is sequential (kick() → while (await this.turn())), and a second driver is rejected while the phase is active.
• Cross-process interleaving is excluded by the JSONL write lease (packages/session/session-persistence-jsonl/src/lease.ts): POSIX flock(2), Windows named semaphore, contention maps to SessionAlreadyOwnedError.

So on current master, step/start {turn:1, step:1} twice with no turn/end between them should be unreachable through the agent loop. Given your B-class files are all 4–12 days old and none are recent, the most likely explanations are (a) those logs were produced by an older build that had a step-accounting defect since fixed, or (b) a race we have not pinned down.

What would settle it: the dsh --version (or desktop build number) of the app that produced those 9 sessions, and one of the session files (or just a seq/type/data.turn/data.step dump). With one artifact I can bisect the producing build from the event signature and confirm whether the current writer can reproduce it. If it turns out to be a live race, I will extend the writer guard (the same SessionTurnScopeError mechanism used for the PTC class) to step coordinates.

One thing worth flagging regardless: the reader still has no repair/quarantine path for already-corrupted generations — those 9 files stay unloadable forever. If the maintainers want a proposal for a read-time quarantine (mark the generation corrupt, keep the bytes, allow listing) I can draft it separately from the writer fix.