DSH Bug 报告：单条 turn/end 的 reason: null 会让整个 Chat 视图永久崩溃，并牵连所有会话

[xiaope233]

DSH-bug报告-turn-end-reason-null.md

[argszero]

Your title names the symptom exactly. I traced the same row at d743267388 (0.2.1-alpha.2): the null is produced by the write path, so it is already on disk before any reader sees it — the reader is where it becomes visible. Two related threads: #8832 and #9156.

How reason becomes null

1. Something calls agent.cancel(cause). AgentCancelCause is a closed four-member union — {kind:'user'} | {kind:'parent'} | {kind:'hook'; reason} | {kind:'disposed'} (packages/core/session/src/types.ts:189). hook is the member reserved for plugins.
2. ReactLoopAgent.cancel (packages/core/agent-loop/src/agent.ts:175) only runs this.phase.abort.abort(cause), so signal.reason === cause.
3. The turn's catch calls abortedCancelCause(signal) (agent.ts:80-95). Its switch covers those four cases and ends with default: return assertNever(cause).
4. A cause outside the union therefore throws inside the catch body — the usual shape is a plugin passing a bare string, e.g. cancel('my-guard'). turnEnds is still its initializer null (agent.ts:310), and the finally appends unconditionally: this.session.append('turn/end', { turn, reason: turnEnds! }) (agent.ts:385) — the non-null assertion is the lie.
5. What lands on disk: {"type":"turn/end","data":{"turn":N,"reason":null}}.

Nothing between there and the file rejects it: Session.append runs snapshotJsonValue plus validateSessionEventData, and that validator only looks at surface message slots, request/header and tool/result. turn/end.reason is a TypeScript-only invariant with no runtime check.

Also worth knowing: the row carries an explicit null, it is not a missing field. walkJsonValue has a current === null branch (packages/util/values/src/index.ts:120) that preserves null through projection, so the snapshot layer keeps it rather than degrading it to undefined.

Version boundary (read out of the published tarballs)

abortedCancelCause does not exist in @deepseek-ai/dsh-agent-loop@0.1.6-alpha.2 — that version stored signal.reason verbatim, so a bad cause produced a malformed but tolerable row. The function is present and throwing in 0.1.7-rc.2, 0.2.0-rc.2 and 0.2.1-alpha.2. So latest (0.1.0-rc.6) cannot produce a null; the poisoning starts with the 0.1.7 line.

The reading side

reason === null reaches packages/client/ui-chat/src/client/ unguarded at roughly eleven sites — contract/turn-process.ts:72 (turnProcessAlwaysOpen, the direct crash point: location.turn.end?.data.reason.kind), chat/ChatGroupSeat.tsx:149, chat/TurnProcessNodeView.tsx:20, apply.ts:106, conversation-nodes/turn-error.ts:34/35/66/67, conversation-nodes/turn-max-tokens.ts:42/51, conversation-nodes/turn-tail.ts:82, plus ui-trajectory and ui-workflow-run. Each does a reason.kind-style read, so one poisoned row throws while the conversation view renders — which is why a single session's row blanks the whole chat area and the effect looks like it spread to every session.

Producing it correctly, and repairing a log

The plugin-side fix is one line of shape: emit { kind: 'hook', reason: '<your cause string>' } instead of a bare string. That member is carried through abortedCancelCause verbatim and renders normally (turn-error.ts special-cases only signed-out).

If you are repairing an already-written log by hand, write the full shape {"kind":"aborted","reason":{"kind":"hook","reason":"…"}}. The short form {"kind":"aborted"} just moves the crash to reason.reason.kind.

Two of the plugins that produced this were ours (they passed bare strings); we shipped the corrected emission in @argszero/cordis-plugin-thinking-loop-guard 0.1.12 and @argszero/cordis-plugin-turn-budget-guard 0.1.2, so the remaining exposure is third-party producers.

What a plugin can and cannot reach here

The write-side validator has no hook, and the client read path is internal (a client half can only register modules) — neither is plugin-reachable. The reachable prevention point is agent/created: it is dispatched serially and awaited (packages/core/agent/src/index.ts:550), so a listener that wraps the agent instance's cancel before the first turn can normalize every out-of-union cause, from every producer, in one place.

[argszero]

A plugin now closes this seam: @argszero/dsh-cancel-cause-guard

Thank you for the report — the mechanism you describe reproduces exactly against the published sources, and a prevention arm is now available.

What I confirmed at the source level. ReactLoopAgent.cancel hands the argument to AbortController.abort(), so it becomes signal.reason; the turn's catch reads it back through abortedCancelCause (dsh-agent-loop/src/agent.ts:80), whose switch ends in assertNever — inside the catch body. The assignment never runs, turnEnds stays at its null initializer, and the finally appends unconditionally (agent.ts:385; the non-null assertion on the line is what makes it compile). Nothing on the write path refuses it: the append-time validator inspects surface message slots, request/header and tool/result, so turn/end.reason is a TypeScript-only invariant. That is why the same row also breaks the chat view for newly created sessions.

There is a version boundary worth recording: a harness older than 0.1.7 had no such function (the catch wrote { kind: 'aborted', reason: signal.reason } verbatim), so the same abuse produced a malformed-but-readable row. From 0.1.7-rc.2 on it is fatal — the failure changed shape under callers that had not changed at all. This is the third report of the family (#8832, #9156, and yours).

The plugin. @argszero/dsh-cancel-cause-guard listens to agent/created — the serial, awaited lifecycle edge that hands over the live agent instance (dsh-agent/src/index.ts:550) — and shadows that instance's cancel with a wrapper that carries anything outside the union as { kind: 'hook', reason: <the value's own name> } before the loop ever sees it. hook is the member the union reserves for plugins, so the rewrite is not a lie: a plugin did cancel the turn, and the reason names which one. One own-property write covers every instance-level caller — the loop's own agent.cancel({ kind: 'user' }), the client's stop button, and any third-party plugin — because ReactLoopAgent.cancel is a prototype method.

It never refuses a cancellation, forwards an already-valid cause by reference, and logs every rewrite with the offending value rendered as JSON, so the producing plugin can be found and fixed rather than merely tolerated. mode: 'observe' reports the value and passes it through untouched, for an operator who wants to see the failure happen.

- insert:
    - id: cancel-cause-guard
      name: '@argszero/dsh-cancel-cause-guard'

• npm: https://www.npmjs.com/package/@argszero/dsh-cancel-cause-guard
• source: https://github.com/argszero/dsh-cancel-cause-guard

What it cannot do. It reads no history, so it cannot repair a session that already carries a null row — those rows are on disk, and the sessions with one stay unreadable until the row is removed. Mounting it bounds the defect from that point on.

Evidence. The consequence is proved against the published @deepseek-ai/dsh-agent-loop tarballs rather than a stand-in (npm run witness:cancel-cause): a bare-string cause throws unreachable variant: "thinking-loop" unguarded and returns { kind: 'hook', reason: 'thinking-loop' } guarded, on 0.1.7-rc.2, 0.2.0-rc.2 and 0.2.1-alpha.2, with 0.1.6-alpha.2 recorded as the boundary. The suite is 69/69 on each of those three lines, and 34 injected defects are each caught (0 silent).

[aiheliangbakai]

???????(??? 0.2.1-rc.2,2026-10-20 ???):

????????:dsh-thinking-guard@1.0.2 ? lib/index.js:295 ???

agent.cancel({ kind: 'thinking-guard', reason, detail, sessionId: st.sessionId });

kind ????? ? catch ? abortedCancelCause ? assertNever ?? ? turnEnds ?? null ? finally ?? reason:null????????????????"?????"?

??? 0.2.1-rc.2 ????? conversation.chat.flow / ChatGroupSeat (client.js:4158),????? conversation.view / turnProcessAlwaysOpen;???????????????????

??:?????????,host ???? live session ??????,???????????(??????)?

????????(?????):

1. ?????????:agent.cancel({ kind: 'hook', reason: 'thinking-guard: ' + reason });
2. host ?????? agent.cancel(?? cause ???? {kind:'hook',reason})? session.append(???? turn/end ? null ?? {kind:'completed'}),??????????;
3. ?????????:?? zstd ???(???????? header)?????????????????????

??????????????????? #9699 ?????:
#9699 (comment)