Session.append() 静默丢弃 ignorable 标记 —— 第三方插件事件可写入，但整条日志在重载时被拒绝

[gaolizheng]

我理解 SessionEvent.ignorable?: true 标记的存在，是为了让插件能把自己的事件类型持久化进 session 日志，并且之后还能重载。然而在当前 dsh-v0.1.3-alpha.1 版本上，没有任何写入路径能打上这个标记：Session.append() 会静默丢弃调用方传入的ignorable 选项。
后果：插件的事件成功写入，但重载时整条日志被拒绝（SessionFormatUnsupportedError），任何依赖自定义
session 事件的插件，其崩溃恢复能力都被破坏。

opts 上的其他键（包括 ignorable）都被静默丢弃：
`
append(
type: T,
data: SessionEventMap[T],
...opts: T extends SurfaceEventType ? [opts: SurfaceIntent] : []
): SessionEvent {
const surfaceOpts: SurfaceIntent | undefined = opts[0]
const surfaceMetadata = {
...surfaceOpts?.sourceEventSeqs === undefined ? {} : { sourceEventSeqs: surfaceOpts.sourceEventSeqs },
...surfaceOpts?.surfaceOp === undefined ? {} : { surfaceOp: surfaceOpts.surfaceOp },
}

`

[argszero]

This is a well-known gap — yours is the 8th independent report of the same mechanism. I can confirm the source exactly, and the fix shape has been stable across several of the best-documented reports.

Confirmed at current master (v0.1.3-alpha.1):

• append<T extends SessionEventType>(type, data, ...opts) at packages/core/session/src/index.ts:699. For non-surface events the opts tuple is [], and the constructed envelope (:726) carries only surfaceMetadata (sourceEventSeqs/surfaceOp) — ignorable is dropped / not even reachable. So there is zero in-tree way to produce the marker.
• The read side is strict: validateStoredEvents at packages/session/session-persistence/src/storage-contract.ts:69, rejecting at :75 when !KNOWN_SESSION_EVENT_TYPES.has(event.type) && event.ignorable !== true. KNOWN_SESSION_EVENT_TYPES is a generated repo-internal whitelist, and out-of-repo plugin event types are outside it by construction (known-event-types.ts). So a plugin event writes fine but the whole log is refused on the next cold load.

Why it's a gap, not a bug to work around: the read side already honors ignorable (:75) — the load-side SessionEvent.ignorable marker is documented as the compatibility mechanism for out-of-repo plugin events. The write side just never lets a plugin set it. This is the "silent-write / loud-read" asymmetry: append does no runtime unknown-type check, so any string type lands in the log; refusal only surfaces on reload, by which point the plugin event is already persisted.

The fix shape that's been agreed across the best reports (starting with #5463 antst's IgnorableSessionEventMap, refined in #5474): a merge-extensible IgnorableSessionEventMap alongside SessionEventMap, and append opts gated to map members so over-marking becomes a compile error:

opts: T extends SurfaceEventType ? [opts: SurfaceIntent<T>]
     : T extends keyof IgnorableSessionEventMap ? [opts?: { ignorable: true }]
     : []

Runtime just passes the marker through (decl-merge erases at type level); Session.append is the only envelope producer. The load-bearing invariant: the map is append-side only — reads never consult it, so it doesn't reintroduce the composition-dependence the upstream rejection explicitly avoided.

Two adjacent warts worth addressing in the same pass:

1. Warn at the append site for an unknown, unmarked non-surface type — today it's silently accepted, so a plugin author gets no signal until a hard restart fails to load the session.
2. The refusal wording at storage-contract.ts:77 — "likely written by a newer harness" is misleading for the plugin case (the author is on this harness; the event is theirs). Should mention out-of-tree plugin events.

There's a documented design note (.agents/notes/implemented/architecture/2026-08-30-retain-ignorable-external-session-events.md) that captures exactly this rationale. The fix is small (opts tuple + passthrough + map decl + regression tests) and the read-side strictness should stay as-is — that's the corruption family's integrity backstop. Your diagnosis is spot-on.

[argszero]

Just wanted to close the loop and let the community know there's now a plugin that detects this failure mode proactively.

I published @argszero/cordis-plugin-session-audit@0.1.2 — a proactive session-log completeness audit that, among other things, scans a stored .jsonl session log for any event type that is outside the known vocabulary and not marked ignorable.

Two things it gets right about the #5769 failure mode:

1. It treats an unmarked unknown type as a hard error (needsManual: true), not a soft warning — matching the harness read path, which throws SessionFormatUnsupportedError on such a log. So the audit correctly predicts that a reload of that session will hard-fail, instead of saying "a newer-harness reader may refuse".
2. It makes the fix actionable: the offending event's writer must mark it ignorable (or the log must be repaired), otherwise the session is unrecoverable. This is exactly the "silent write, loud read" asymmetry — a third-party plugin can append a custom event type successfully, but the whole log is then rejected on the next cold load.

It ships as a slash command (/session-audit) when mounted in a cordis.yml, and as a one-shot npx bin that runs under plain Node with no dsh runtime needed. It never mutates a log — it's purely diagnostic, so it's the right tool to confirm whether a session is already poisoned before replay crashes.

Note: this is a diagnostic for the write-side gap you've identified. The actual fix (append carrying ignorable, per the map-gated design from #5463) is an in-tree Session.append change that only the maintainers can ship — the plugin is the community-side safety net until then.