Let plugins mark out-of-tree session events as ignorable

[antst]

Problem

At commit 49a606bc, the generated session-event catalog explains that out-of-tree plugin events are absent from KNOWN_SESSION_EVENT_TYPES by construction and that persistence may read an unknown event only when its stored envelope carries ignorable: true (packages/core/session/src/known-event-types.ts:7-20). The envelope type includes that marker (packages/core/session/src/types.ts:436-454), but Session.append() accepts no way to set it and constructs an unmarked envelope (packages/core/session/src/index.ts:668-697). A plugin can declaration-merge its event into SessionEventMap for type-safe appends, but the resulting persisted session is rejected by a first-party reader because the event is unknown and required.

Minimal reproduction

1. In an out-of-tree plugin, augment SessionEventMap with a log-only event type.
2. Append that event, persist the session, and close it.
3. Reopen the session through DSH persistence.

The reopen fails because the event type is outside the generated catalog and the plugin could not mark its record ignorable.

Plugin use case

A workspace-restore plugin wants to record a durable, structured “workspace restored” event containing the target turn plus files written, deleted, and failed. It is informational: older readers may safely skip it because command lifecycle events still own execution and reconstruction. Without an append-side marker, the plugin must instead encode the report as flat command/done text.

Suggested API

Could DSH add a merge-extensible IgnorableSessionEventMap alongside SessionEventMap, plus an ignorable: true append option available only for event types declared in that map? A plugin would augment both maps and explicitly opt in at the append call; Session.append() would persist the envelope marker. This follows the existing MessageSourceMap declaration-merging pattern while preserving the safety default: undeclared or unmarked unknown events remain required and continue to fail closed.

This would not make all plugin events ignorable or treat installing a plugin as sufficient evidence that an unknown event is safe to omit.

[argszero]

Verified every citation at master 49a606b — all exact, and your proposal is the cleanest framing of this gap I have seen in six independent reports. The design you propose is not only sound, it matches the constraints the codebase itself documents.

Verification

• known-event-types.ts:7-20 — exactly as you quote, including the decisive sentence: "event-name registration was rejected because it does not classify omission safety and would make reads composition-dependent." Upstream already chose the per-event envelope marker as the durable contract over any registry.
• types.ts SessionEvent.ignorable?: true envelope doc: "Absent means required… defaulting to required means a forgotten marker over-refuses (an inconvenience) rather than silently resuming a gutted session."
• session/src/index.ts:668-697 — append opts tuple is T extends SurfaceEventType ? [opts: SurfaceIntent] : [] (empty for non-surface), and the constructed envelope never carries ignorable. Zero in-tree writers of the marker exist — it is a load-side escape hatch with no write-side producer.
• Read side already honors the marker: at 49a606b it moved from the old coordinator into session-persistence/src/storage-contract.ts:72 (validateStoredEvents: if (!KNOWN_SESSION_EVENT_TYPES.has(event.type) && event.ignorable !== true) throw …). The mechanism is live; only the writer is missing.

Family lineage — you are the sixth independent consumer
Same gap, six plugin authors: #1538 (dsh-agent-teams), #1584 (LoserFox/distill), #1619 (model-roles), #2778 (ref-lib), #3191 (dsh-click), now #5463 (workspace-restore). Every one appended a well-formed plugin event, the append "succeeded", and the whole session refused on the next cold load. The write side silently accepts any string type; the refusal only surfaces at read — a silent-write/loud-read asymmetry.

Assessment of your API
IgnorableSessionEventMap + append option gated to map members is strictly better than a free-form { ignorable?: true } on all non-surface events (which is what I had earlier proposed for this family):

• It keeps the safety default AND makes over-marking a compile error rather than a judgment call per call site.
• It is append-side only — reads never consult the map. That is the load-bearing invariant: a read that depended on which plugins are mounted would be composition-dependent, which is precisely the failure upstream rejected name registration for. Your persisted-marker design preserves it.
• One type-level note: because the gate lives in the opts tuple, it is expressible purely in types — T extends SurfaceEventType ? [SurfaceIntent] : T extends keyof IgnorableSessionEventMap ? [opts?: { ignorable: true }] : []. Runtime just passes the marker through (declaration merging erases at runtime, so there is no runtime map to check — and none is needed, since Session.append is the only envelope producer). Keep the option literal as ignorable: true only; an ignorable: false would misleadingly imply absence means something else.

Two supplements from the family history worth folding in

1. Warn at append: since the write side does no unknown-type check, poison accumulates silently until the next restart. A warning at the append site for an unknown non-ignorable type would surface the mistake when it happens. Your map gives a natural hook: warn when ignorable: true is passed for a type absent from IgnorableSessionEventMap (defense in depth under a JS caller), and warn when an appended type is outside KNOWN_SESSION_EVENT_TYPES and unmarked.
2. Refusal wording: storage-contract.ts:74 still says "it was likely written by a newer harness" — accurate for version skew but actively misleading for the plugin case (the report is in-repo vocabulary, not a newer build). One-line amend to mention out-of-tree plugin events would have saved all six authors a debugging cycle.

The fix shape is small (opts tuple + envelope passthrough + map declaration + two regression tests: marked unknown event loads and is skipped; same type unmarked still refuses) — consistent with the codebase's documented intent. Until it lands, your only workaround is the flat command/done encoding or a local patch; the architecture is already on your side.