Bug: plugin-authored session event types without ignorable make sessions unreadable (SessionFormatUnsupportedError) - dsh-talk/speech

[JudgeAllen]

Summary

Sessions that contain plugin-authored session event types (e.g. dsh-talk/speech from the dsh-talk plugin) fail to load with:

SessionFormatUnsupportedError: session "..." contains event type "dsh-talk/speech" (seq 16252) unknown to this harness and not marked ignorable; refusing to interpret the log — it was likely written by a newer harness

…even on the same harness version that wrote the log (0.1.0-rc.7, Windows, JSONL+zstd backend). Two sessions hit this on 2026-08-19; both are otherwise healthy (seq-contiguous, all other types core-known).

Root cause

1. Session.append(type, data, opts) (core/session/src/index.ts:604) accepts no ignorable option — opts is only SurfaceIntent (surfaceOp / sourceEventSeqs). The envelope's ignorable?: true marker (types.ts:422) can only enter the log via seed/restore or lower-level persistence writes.
2. Plugins therefore append their event types with a bare two-argument call — e.g. dsh-talk service.ts:238 session.append('dsh-talk/speech', event) (its own docs state the event is meant to be ignorable so builds without the plugin still read the session).
3. The persistence coordinator's assertEventsSupported (session-persistence/src/coordinator.ts:1061) accepts only types in the static KNOWN_SESSION_EVENT_TYPES set or events carrying ignorable: true — so the log is refused on every later load/prepare, by the same harness that wrote it.

Impact

• Any session where an installed plugin logged its own event type becomes permanently unloadable (history unavailable in the Web GUI) until the log is hand-patched.
• Affected here: 2 sessions × 8 dsh-talk/speech events total (6 + 2).

Suggested fixes

1. Expose the marker at append time: allow append(type, data, { ..., ignorable?: true }) (or a dedicated appendIgnorable) so plugin authors can fulfil the documented contract.
2. Auto-mark at append: Session.append could stamp ignorable: true on types outside the core known set (they are log-only by definition from the harness's perspective), which also fixes already-written logs on the next read.
3. Plugin side (dsh-talk 0.1.0): mark events ignorable once an API exists.

Workaround applied

Data patch: added "ignorable": true to the 8 stored dsh-talk/speech envelopes (frames re-encoded, rest byte-identical, full scan + support-check verified). Both sessions now load; the events remain in the log and the installed plugin's client renders them.

[denial123789]

The rc.7 source supports this diagnosis and adds one important boundary: keeping the plugin installed cannot make the event readable. Session.append() builds the stored envelope from SurfaceIntent only and has no path to emit ignorable. On load, assertEventsSupported() checks only the static KNOWN_SESSION_EVENT_TYPES set or event.ignorable === true; it does not query the active plugin graph or TypeScript declaration merges.

That explains the evidence combination here:

• valid frame and contiguous seq → not generic log corruption;
• same rc.7 reader → rollback alone does not help;
• plugin still installed → runtime presence does not register durable vocabulary;
• a copied, format-preserving artifact with ignorable: true passes → the missing envelope capability is the blocking boundary.

I would keep the proposed repair explicit rather than auto-mark every unknown type. Only the writer/plugin author can truthfully assert that dropping an event cannot change message reconstruction, tool identity, policy, approval, workspace, model route, or interpretation of later events. An appendIgnorable() or typed ignorable: true option for non-surface plugin events preserves that decision at the source.

For affected users, the data patch is useful forensic confirmation but should not become a generic live-log recipe. Stop all writers, preserve the original, use a version-aware tool on a copy, and validate frame layout, checksums, seq, references, and cold resume before replacement. Until a writer API ships, informational telemetry belongs in a plugin-owned versioned store keyed by Session id.

Updated source-pinned guide and cold-resume matrix: https://sandbaseai.github.io/deepseek-harness-handbook/custom-session-events.html

Disclosure: independent SandBase community handbook, not official DeepSeek documentation.