Skip to content
dshdocs

Session Resume Breaks — DeepSeek Harness Guide

Symptom

Section titled “Symptom”

A third-party plugin declares its own custom session event type by declaration-merging into SessionEventMap, which is the documented extension pattern, and writes it with Session.append(). Nothing goes wrong while the process is up: the write succeeds, no error. Restart the process and try to resume that session, and loading throws SessionFormatUnsupportedError. The whole session log is then permanently unopenable, with no recovery path.

This isn’t specific to one plugin. Any plugin that writes a custom session event type hits it. The reporter found it while building dsh-meta-orchestrator and confirmed the pattern itself is the trigger.

Cause

Section titled “Cause”

On the read path, assertEventsSupported() in session-persistence/coordinator.ts refuses to load a session log containing any event type outside a fixed whitelist, KNOWN_SESSION_EVENT_TYPES, unless that type is explicitly marked ignorable. Custom event types fail that check for two reasons at once:

  • The whitelist is generated from the event types declared in the harness’s own repo, so a plugin’s SessionEventMap merge can never be in it.
  • Session.append() gives a plugin no way to mark its own event as ignorable when writing it.

Follow the documented pattern, then, and there’s no way to write an event the persistence layer will tolerate on reload. Nothing complains at write time. The failure surfaces on the next resume attempt, when the log already contains the unrecognized event and is stuck that way.

Solution

Section titled “Solution”

There is no confirmed workaround as of this Discussion. If you’re building a plugin:

  • Don’t write custom session event types if resumable sessions matter for your use case.
  • If you already have sessions broken this way, there’s no reported way to strip the offending event and recover the log.

The reporter asked for one of two things: a registration surface for plugin-declared event types, or ignorable support on append(). A code comment in known-event-types.ts already acknowledges that a registration surface is “deferred until such a consumer exists.” No fix had landed as of this report.

Source

Section titled “Source”

Discussion #918 — 插件写入自定义 session 事件类型会让会话永久无法恢复

Section titled “Related errors”