[Bug] ReactLoopAgent.cancel() does not validate cause at entry, writing {"reason":null} on turn/end and permanently crashing Chat UI

[kelly345]

Summary

When a runtime caller or third-party plugin invokes agent.cancel(cause) with a malformed runtime cause (for example passing a string 'disposed' instead of { kind: 'disposed' }), ReactLoopAgent.cancel() does not validate cause at the call site and passes it directly to this.phase.abort.abort(cause).

When the active turn catches the abort and calls abortedCancelCause(signal), assertNever(cause) throws inside the catch block before turnEnds is assigned. The finally block then executes this.session.append('turn/end', { turn, reason: turnEnds! }) with turnEnds === null, durably persisting {"type":"turn/end",...,"data":{"turn":N,"reason":null}} into the session log (session.v4.jsonl.zstd).

Once this event is persisted, @deepseek-ai/dsh-client-ui-chat permanently white-screens on that session across restarts when reading event.data.reason.kind.

Reproduction

Minimal reproduction using @deepseek-ai/dsh-agent-loop:

import { Context } from '@deepseek-ai/cordis'
import LlmRuntime, { createUserMessage } from '@deepseek-ai/dsh-llm'
import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
import ToolRuntime from '@deepseek-ai/dsh-tools'
import AgentRegistry, { type AgentCancelCause } from '@deepseek-ai/dsh-agent'
import AgentLoop from '@deepseek-ai/dsh-agent-loop'

// Inside an active turn (e.g. during `agent/request` or tool execution):
agent.cancel('disposed' as unknown as AgentCancelCause)
await agent.whenIdle()

const turnEnd = agent.session.snapshotEvents().find(e => e.type === 'turn/end')
console.log(turnEnd)
// => { type: 'turn/end', seq: ..., time: ..., data: { turn: 1, reason: null } }

Current behavior

1. ReactLoopAgent.cancel(cause) (packages/core/agent-loop/src/agent.ts:174-180) clears the inbox and calls this.phase.abort.abort(cause) without validating cause.
2. In ReactLoopAgent.turn() (packages/core/agent-loop/src/agent.ts:369-394):

   } catch (error: unknown) {
     // A cause is present exactly while the signal is aborted.
     const cause = abortedCancelCause(signal)
     if (cause !== undefined) {
       turnEnds = { kind: 'aborted', reason: cause }
       throw error
     }
     ...
   } 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! })
     } catch (error: unknown) {
       this.throwError(error)
     }
   }

   Because abortedCancelCause(signal) (packages/core/agent-loop/src/agent.ts:78-92) throws Error: unreachable variant: "disposed" inside the catch block, turnEnds remains null.
3. this.session.append('turn/end', { turn, reason: turnEnds! }) succeeds because null is valid JSON and validateSessionEventData (packages/core/session/src/surface.ts:207) does not validate turn/end payloads.
4. Persisted session log (session.v4.jsonl.zstd) now contains:

   {"type":"turn/end","seq":49,"time":1791626380934,"data":{"turn":4,"reason":null}}

5. In @deepseek-ai/dsh-client-ui-chat (e.g. packages/client/ui-chat/src/client/apply.ts:106, ChatGroupSeat.tsx:149, TurnProcessNodeView.tsx:20, conversation-nodes/turn-error.ts:66, conversation-nodes/turn-max-tokens.ts:51, conversation-nodes/turn-tail.ts:82), event.data.reason.kind is accessed assuming reason is non-null, throwing TypeError: Cannot read properties of null (reading 'kind') and causing the Chat view to white-screen even after restarting the desktop app (while the Trajectory view still renders).

Expected behavior

1. Fail at the entry boundary (ReactLoopAgent.cancel): cancel(cause) should validate cause synchronously before clearing the inbox or aborting this.phase.abort, throwing immediately at the caller site if cause is not a valid AgentCancelCause object.
2. Never append turn/end with reason: null: Session / ReactLoopAgent.turn() should never commit a turn/end event with a null reason to the durable event log.

Environment

• Commit / Version: master (d743267388, dsh-v0.2.1-alpha.2) and Desktop 0.1.0-alpha.12
• OS: Windows & macOS

[argszero]

I re-checked this against the current master (571902028a). The mechanism is unchanged, and I think the report is better served by separating the two halves of its "Expected behaviour" — only one of them is entry validation.

Re-verified on 571902028a

• cancel is still unvalidated at the boundary: packages/core/agent-loop/src/agent.ts:175 takes cause: AgentCancelCause and :180 is this.phase.abort.abort(cause).
• abortedCancelCause is :80, and its switch still ends in assertNever(cause) at :93 — under a coverage annotation that states the assumption out loud (:91, /* v8 ignore next -- cancel accepts the closed AgentCancelCause union */), with :82 saying cancel() is the only aborter of the signals this loop owns.
• That call is still made from inside the turn's catch (:370), before the assignment at :372, while turnEnds is still initialized to null at :312.
• The finally (:384) still appends unconditionally at :387 — this.session.append('turn/end', { turn, reason: turnEnds! }) — so the non-null assertion on that line is exactly the guarantee the throw inside catch breaks.

The union itself is packages/core/session/src/types.ts:190 — user | parent | hook { reason } | disposed — and TurnEndCancelCause is that plus legacy (:197).

The two halves are not the same bug

1. The entry does not validate — a caller can pass anything, and the first code that notices is the one place with no way to report it (a catch that is already handling another error).
2. The write is not conditioned on the value — the finally commits whatever turnEnds holds, so the caller's mistake is made durable. Even with (1) fixed, this is the property that turns a bad argument into a permanently unreadable conversation. It is the half your second expected-behaviour item names, and it stands on its own.

On (1): the check needs a decision attached, not just a throw

Throwing synchronously at the call site is the right default, but it is a behaviour change for the caller, not only for the log. Today agent.cancel('disposed') does stop the turn — the abort lands, the turn dies, and only the reporting is broken. So a throw converts "appears to work, poisons the log later" into "fails loudly at the caller", and the caller is typically a plugin that has been getting away with it.

Whichever way that goes, hook is the union's own slot for a cause that arrived from outside it, which offers a normalization path that stays inside the union ({ kind: 'hook', reason }) rather than a new variant every reader has to be taught. It is the member reserved for plugins — a plugin did cancel the turn, and the reason can name which one.

On (2): the invariant belongs where the assertion is

No turn/end row should reach the log carrying a reason a reader cannot dereference, and validateSessionEventData will not catch it — correctly, since it inspects surface message slots, request/header and tool/result, which leaves this a TypeScript-only invariant. The writer is the only place it can be enforced.

It is worth doing even for users pinned to a line, because the shape of the failure changed under callers that did not: before 0.1.7 there was no abortedCancelCause, and the same abuse produced a malformed-but-readable row; from 0.1.7-rc.2 on it is fatal. Same sibling reports: #8832, #9156, #9646 — all four end at the same row.

A plugin that covers both halves from outside

For anyone who needs the log protected before a fix lands, I published:

@argszero/dsh-cancel-cause-guard@0.2.0 — https://www.npmjs.com/package/@argszero/dsh-cancel-cause-guard

npm install @argszero/dsh-cancel-cause-guard

then in the profile bundle patch:

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

It listens to agent/created — the awaited lifecycle edge that hands over the live agent instance — and:

• at the entry, shadows that instance's cancel so anything outside the union is carried as { kind: 'hook', reason: <the value's own name> } before the loop ever sees it;
• at the write, shadows the same edge's live session so a turn/end row whose reason no reader can dereference is committed as { kind: 'aborted', reason: { kind: 'hook', reason: … } } instead of null.

Both are one own-property write over a prototype method, which is what makes them cover every instance-level writer rather than one registered path. Each rewrite and each repaired row is logged with the offending value rendered as JSON, so the producer can be found and fixed. backstop: false turns the second arm off for a deployment that already owns that method, and mode: 'observe' reports both without rewriting.

Two honest limits: it reads no history, so it cannot repair rows already on disk — mounting it bounds the defect from that point on; and a check inside cancel is strictly stronger than the entry arm, because the plugin cannot reach a caller that goes through the class rather than the instance. That gap is what the write arm exists for, and it is the reason this is a mitigation rather than a fix.

Measured green against 0.1.7-rc.2, 0.2.0-rc.2 and 0.2.1-alpha.2; source at https://github.com/argszero/dsh-cancel-cause-guard.

[aiheliangbakai]

Still reproducible on Desktop 0.2.1-rc.2 - a concrete producer found in a published plugin

Environment: DeepSeek Harness Desktop 0.2.1-rc.2, Windows 11, Node 24.14, session format v4. Reproduced several times, including twice today (2026-10-20).

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

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

thinking-guard is not a member of the closed AgentCancelCause union. The turn's catch then calls abortedCancelCause(signal), whose assertNever throws, turnEnds keeps its null initializer, and the finally appends {"type":"turn/end",...,"reason":null}. This matches the analysis above exactly; the new part is that the producer is a real published plugin, not just a synthetic repro.

Client on 0.2.1-rc.2: the crashing slot is now conversation.chat.flow / ChatGroupSeat (not conversation.view / turnProcessAlwaysOpen as in #8832 / #9156):

slot entry crashed in 'conversation.chat.flow': TypeError: Cannot read properties of null (reading 'kind')
    at ChatGroupSeat (client.js:4158:1)

The error boundary blanks the whole chat pane; the trajectory view keeps working.

One behavior worth recording: repairing the poisoned row on disk is not enough while the host is running - the live session keeps the old event in memory, and the client keeps crashing until the display process is restarted (a page reload does not clear it).

What we did locally (three layers, none of them touching the DSH install):

1. Producer fix: emit a legal member - agent.cancel({ kind: 'hook', reason: 'thinking-guard: ' + reason }).

2. Write-path guard in a small host plugin: wrap agent.cancel (normalize any cause outside the union to {kind:'hook',reason}) and wrap session.append (rewrite turn/end with reason == null to {kind:'completed'} immediately before the write). The append wrapper is the important half: even if another caller passes garbage, a null can never reach the log or the client event stream. It patches live instances only and restores them on unload. Log evidence from the first real turn after mounting:

   2026-10-20T12:18:34Z patched turn/end reason:null -> completed session=f2d43dc6. turn=3
   

3. Repair for already-poisoned logs: a script that validates each session.v4.jsonl.zstd frame structure (first frame must be exactly one header line), rewrites only the frames containing a bad turn/end, keeps a backup, and re-verifies record count and remaining nulls.

Suggested upstream order (cheapest first):

• In ReactLoopAgent.turn()'s finally: reason: turnEnds ?? { kind: 'completed' } (or refuse the append) - the log becomes unpoisonable regardless of callers.
• Validate cause at cancel() entry; unknown causes become { kind: 'hook', reason }.
• Client: reason?.kind at the ~11 read sites, so one bad row can never blank the whole pane again.