[bug] 第三方插件写入的 session event 会让会话永久打不开

[yexiyue]

现象

第三方插件调 session.append 写入自己声明的事件类型之后，那个会话就无法再打开——
不是丢失几行，是整份日志被拒绝解释。

版本：0.1.0-rc.8。

最小复现

一个十行的插件：

// index.ts
import type { Context } from '@deepseek-ai/cordis'

declare module '@deepseek-ai/dsh-session/types' {
  interface SessionEventMap {
    'demo/hello': { version: 1 }
  }
}

export const name = 'demo'
export const inject = ['agents']

export function apply(ctx: Context): void {
  ctx.on('agent/session-start', ({ agent }) => {
    agent.session.append('demo/hello', { version: 1 })
  })
}

装上、开一个会话（agent/session-start 就会写入，不必发消息）、重启 dsh，
再打开那个会话：

history unavailable for session "session-…": SessionFormatUnsupportedError:
session "session-…" contains event type "demo/hello" (seq 3) unknown to this
harness and not marked ignorable; refusing to interpret the log — it was likely
written by a newer harness

此后该会话一直打不开，插件仍然装着也一样。

⚠️ 重启那一步不能省。 会话还在内存里时读的不是持久化路径，刷新页面看起来一切正常；
要等进程重启后从磁盘恢复，assertEventsSupported 才会拒绝。所以在真实使用中它的形态是
「写入当天没事，第二天打不开」。

机制

拒绝发生在 packages/session/session-persistence/src/coordinator.ts 的
assertEventsSupported：

if (KNOWN_SESSION_EVENT_TYPES.has(event.type) || event.ignorable === true) continue
throw this.unsupported(meta, `… unknown to this harness and not marked ignorable; …`)

两个放行条件对仓外插件都不成立：

① KNOWN_SESSION_EVENT_TYPES 是生成的。
packages/core/session/src/known-event-types.ts 的文件头是
GENERATED by scripts/gen-persistence-catalog.ts，内容是「Every SessionEventMap member
declared in this repository」。同一段文档也写明了仓外类型的处境：

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

② Session.append() 不接受 ignorable。
它在 packages/core/session/src/index.ts 里自行构造 envelope，可选参数位是
T extends SurfaceEventType ? [opts: SurfaceIntent] : []，而 SurfaceIntent 中只有
sourceEventSeqs 与 surfaceOp 会被读出。写入方没有途径把 ignorable 放到 envelope 上。

现有 workaround 的边界

我们在插件加载时把自己的事件类型 add 进 KNOWN_SESSION_EVENT_TYPES（运行时它是个真
Set）。两处它覆盖不到：

a) 插件卸载后，那些会话仍然打不开。

b) 它要求插件与 dsh 解析到同一个 @deepseek-ai/dsh-session 模块实例。
普通安装成立；dsh 从源码 checkout 用 tsx 运行时不成立——两侧得到各自的模块图。
同一进程内加探针实测：

[plugin]      before 48  →  after 52   has('swarmdrop/sent') = true
[coordinator] known size 48            has('swarmdrop/sent') = false

背景

这个 consumer 是 dsh-swarmdrop，用
session event 承载对话行与 @ 引用候选。

需要更多细节或复现环境的话我们可以提供。

[xiaoshenming]

这条和 seq gap 不一样：日志结构是完整的，但仓外插件写了 KNOWN_SESSION_EVENT_TYPES 里没有、又没带 ignorable: true 的 type。官方下次从磁盘恢复时 assertEventsSupported 会整份拒读——「写入当天没事，第二天打不开」说得很准。

dsh-session-surgeon 能做的、和不能做的：

• inspect 会标 unknown-type，告诉你哪一类事件官方不认识。
• 不会给别人的自定义事件补 ignorable，也不会从日志里删掉这些行（那会改语义）。根因还是 Session.append() 不接受 ignorable、仓外类型进不了生成清单——得官方开登记口，或插件自己停写。
• 另一类「整份打不开」我们会修：seq gap / torn zstd / 孤立代理字符，以及 user/message 等缺 message.id（官方报 lacks an identified message）。缺 id 只补 id 字段，不丢事件。

dsh plugin --profile web add "github:xiaoshenming/dsh-session-surgeon#main"

重启 dsh web 后：会话 ⋯ → 复制会话 ID；左侧「会话医生」可看对话、预览修复。默认 dry-run。