Plugin-written session events have no registration surface — a third-party plugin event makes whole session logs unloadable on rc.6

[qiuyu-jii]

Plugin-written session events have no registration surface — a third-party plugin event makes whole session logs unloadable on rc.6

TL;DR

dsh-session validates persisted logs against a static list of known event types, and there is no way for a plugin to register its own event types — nor to mark an event as ignorable. A third-party plugin that appends a custom session event therefore makes the entire session log unloadable: no history, no resume. This is a real API gap, not a version mismatch.

---

Problem

The source itself acknowledges the gap:

Downstream (out-of-repo) plugin events are outside this list by construction; a registration surface for them is deferred until such a consumer exists.
— dsh-session lib/index.js

That consumer now exists: plugins like LoserFox/distill (a skill-distillation plugin) append custom session events via session.append(type, data). On rc.6 two facts combine into a hard failure:

1. Write side: session.append(type, data, opts) accepts only sourceEventSeqs / surfaceOp — a plugin cannot set ignorable: true on the envelope, even though the load side (assertSessionEventEnvelope) already understands that key.
2. Read side: assertEventsSupported refuses the whole log if it contains a type outside KNOWN_SESSION_EVENT_TYPES that is not marked ignorable → SessionFormatUnsupportedError.

The error message ("it was likely written by a newer harness") is misleading here: the log is perfectly valid, the harness just doesn't know the plugin's event type.

Impact

• Every session touched by such a plugin becomes permanently unloadable (no history view, no resume) until manually repaired.
• With the plugin's default minUserMessages: 3, essentially every active session is affected.
• The offending event here is a log-only diagnostic (used to reconstruct model-visible input) — dropping it changes nothing about the conversation. It is exactly the kind of event the ignorable contract was designed for, yet the API makes it impossible to mark as such.

Suggested fixes (in priority order)

1. Add a plugin-side registration surface for session event types — e.g. registerSessionEventType(type) on the session service/store.
2. Allow session.append(type, data, opts) to carry ignorable: true on the envelope, so log-only/diagnostic plugin events that are safe to skip can opt in.
3. At minimum, fix the refusal message: name the offending event type and point at the ignorable contract, instead of blaming a newer harness.

Repro

# dsh 0.1.0-rc.6; any plugin that appends a custom event type
# (e.g. session/distill-review-request from LoserFox/distill)
dsh web
# use a session until the plugin appends its custom event, then restart
# open the session → SessionFormatUnsupportedError, whole log refused

Workaround (local, non-durable — lost on npm update)

• Option A: manually add the type to KNOWN_SESSION_EVENT_TYPES in the installed dsh-session:
  node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/dsh-session/lib/index.js
• Option B: for already-broken logs, decompress the log (unzstd), add "ignorable": true to that event's envelope, recompress (zstd).

Both restore full loading; Option B is safe here because the event is log-only and sits outside any turn.

[argszero]

Verified all three claims against master (47f9438) — and this is the same write-side gap I confirmed in #1538 (out-of-repo plugin dsh-agent-teams, same Session.append opts tuple). Your report adds what #1538 lacked: a concrete consumer (LoserFox/distill) and the read-side consequence. Three source-level details the thread doesn't have yet:

1. ignorable is dead on the write side for EVERYONE — not just plugins. No in-tree code writes ignorable: true at all (grep finds zero writers outside tests; SurfaceIntent carries only surfaceOp/sourceEventSeqs, types.ts:380-391). The marker is a load-side forward-compat escape hatch: per types.ts:49 it "covers vocabulary growth" — a log written by a newer harness contains types this build doesn't know, and the marker lets an older build skip them safely. assertSessionEventEnvelope (index.ts:213-241) validates it (and only accepts === true), the sqlite backend persists it as a nullable column, but nothing can set it through the API — surface events included. So your Option B workaround (hand-editing the envelope) is literally the only path that produces the marker today.

2. The failure is silent at write, loud at read — the log can be poisoned for a long time before any symptom. append (index.ts:604-653) performs no runtime unknown-type check: a JS plugin passing session.append('distill/review-request', {...}) clears the JSON snapshot check, assertSupportedRequestHeader, and surfaceManager.validateNext (surface-only), then lands in the log with seq = log.length. The refusal happens only at the next cold load (assertEventsSupported, session-persistence/src/coordinator.ts:1061-1067). So the plugin author gets zero feedback at write time; every session the plugin touches accumulates the poison until the next restart. A cheap hygiene add: warn at the append site when the type is outside KNOWN_SESSION_EVENT_TYPES and not ignorable.

3. A registration surface (your fix #1) cannot fix the persisted-log read path by itself — the marker is the only durable contract. KNOWN_SESSION_EVENT_TYPES is generated (scripts/gen-persistence-catalog.ts) and closed to out-of-repo types; a runtime registration would live in core/session, but the refusal runs in session-persistence's coordinator — which may read a log before (or without) the registering plugin being mounted. Registrations don't survive restarts unless re-registered at boot, and if the user removes the plugin, old logs containing its events become unreadable again unless each event was also marked ignorable. So your fix #2 (allow append opts to carry ignorable: true) is the load-bearing one; fix #1 is same-boot ergonomics at best; fix #3 is a one-line wording tweak (the message at coordinator.ts:1064 already names the type and the ignorable contract — only the tail "it was likely written by a newer harness" is misleading for the plugin case).

One design note to weigh when opening the opt-in: I argued in #1586 against decoder-side heuristics for the corruption family, because strict unknown-type refusal is the family's integrity backstop — a plugin that marks a required event ignorable would silently reconstruct a wrong session. The safe shape is: strict typing on the opts (T extends NonSurfaceEventType ? [opts?: { ignorable?: true }] : ...), refusal unchanged for unknown-and-not-ignorable, and the per-event marker as an explicit author decision (your distill-review-request is honestly log-only, so the opt-in is sound there). This mirrors the minimal fix proposed in #1538 and, for the record, the same signature is already an offline check (S8) in moonquake2004's dsh-doctor.