[Bug] source.kind `agent-teams-command` 未在 DSH 0.1.5 的迁移白名单内，导致用过 /agent-teams 的历史会话升级后全部无法打开

[gitdawei]

[spacexun2]

Confirming the plugin side of this from current main: the kind is still being minted today. src/command.ts attaches source: { kind: 'agent-teams-command' } to the directive messages injected by the agent/pre-step handler — both the parse-failure branch and the normal activation branch — so every captain session that has ever used /agent-teams on a 0.1.2-era host carries these records into any later host upgrade.

Cross-checking against the harness 0.1.5-rc.1 core, the string appears nowhere: it is absent from KNOWN_SESSION_EVENT_TYPES (dsh-session) and from the released-format source-kind vocabulary (dsh-session-format-v0-to-v1) alike, so the upgrade path has no record of this kind anywhere.

One caveat I want to be precise about: the released-format source validator's default branch only requires the kind to be a non-empty string, so I could not pin from code alone which migration step refuses it. If you still have a failing session at hand, the exact SessionFormatError line would identify the gate.

Two-sided fix shape, for what it's worth: plugin-side, reusing the established { kind: 'plugin', plugin: 'dsh-agent-teams' } source (the shape the delivery paths already use) instead of a bespoke kind would stop new sessions from being written with an out-of-vocabulary marker, with goal/profile already carried in the message text. Sessions already containing the historical kind would still need a host-side allowance to reopen.

[chenkai2]

补上这个 issue 缺失的两块关键信息：① 具体是哪一步迁移拒载（@spacexun2 在代码里没能定位到的那一点），② 一条不依赖任何受影响会话数据的最小复现，并附上在本机真实语料上的影响面统计与一种无损自救路径。

---

① 拒载点：v2 → v3 这一条迁移边的来源种类白名单

拒载发生在 @deepseek-ai/dsh-session-format-v2-to-v3 的 payload 审计里，函数 assertSource()：

• 该包维护一个 SOURCE_KINDS 白名单（user / plugin / model / tool / agent-instructions / session-reference / team-message / goal / skill-invocation / skill-catalog / coordinator / subagent-report / subagent-settled / webhook / agent-message）；发布版里不含 agent-teams-command。
• 命中不到白名单就抛：
  SessionFormatUnsupportedMigrationError: cannot safely transform unclassified message source

为什么"只有 v2 会中招"（这也是同一个 kind 生死相反的原因）：

读端路径	是否校验来源种类	结果
原生 v3 准入（assertV3Event）	不校验 source.kind，只校验事件信封与内容块	v3 日志里的该 kind 原样保留、正常加载
v2→v3 迁移（assertSource）	白名单外一律拒	整份会话拒载，源文件字节不变
v0→v1（payload-validation.ts 的 default: 分支）	只要求非空字符串	宽松，不是它拒的
核心 Session（packages/core/session/src/index.ts）	只要求 source.kind 为非空字符串	宽松，不是它拒的

迁移只在 catalog 判定 migration-required（即存储代次 < 当前代次）时执行；v3 判为 current 时整条迁移链不参与。所以：同一条消息、同一个 kind，落在 v3 日志里能读，落在 v0/v1/v2 日志里打不开。

② 最小复现（不依赖任何真实会话）

mkdir repro && cd repro && npm init -y
npm i @deepseek-ai/dsh-session-format-catalog@0.1.5-rc.2
node repro.mjs

// repro.mjs
import { sessionFormatCatalog } from '@deepseek-ai/dsh-session-format-catalog'

const message = (id, source) => ({ id, role: 'user', content: [{ type: 'text', text: 'captain activation' }], source })
const event = (type, seq, data, extra = {}) => ({ type, seq, time: 1 + seq, data, ...extra })
const prefix = row => [
  event('turn/start', 0, { turn: 1 }),
  event('step/start', 1, { turn: 1, step: 1 }),
  row,
  event('step/end', 3, { turn: 1, step: 1 }),
  event('turn/end', 4, { turn: 1, reason: { kind: 'completed' } }),
]
const row = (id, source) => event('user/message', 2, message(id, source), { surfaceOp: 'append' })

function restore(headerValue, rows, label) {
  try {
    const restore = sessionFormatCatalog.createRestore(headerValue, { recovery: 'strict', validation: 'current' })
    for (const row of rows) restore.decodeRow(row)
    const artifact = restore.finish()
    console.log(`PASS  ${label}  -> v${artifact.header.version}, ${artifact.events.length} events`)
  } catch (error) {
    console.log(`FAIL  ${label}\n      ${error.constructor.name}: ${error.message}`)
  }
}

const v2Header = { type: 'session', version: 2, id: 'session-repro', createdAt: 1, isSeeded: false, delegationDepth: 0 }
const v3Header = { ...v2Header, version: 3 }
const pluginSource = { kind: 'agent-teams-command', goal: 'demo' }

restore(v2Header, prefix(row('m1', pluginSource)), 'v2 row with a plugin-defined source kind')
restore(v3Header, prefix(row('m2', pluginSource)), 'native v3 row with the same source kind')
restore(v2Header, prefix(row('m3', { kind: 'user' })), 'v2 row with a built-in source kind (control)')

在 未打补丁的发布包 0.1.5-rc.2 上的实际输出：

catalog currentVersion = 3 

FAIL  v2 row with a plugin-defined source kind
      SessionFormatUnsupportedMigrationError: cannot safely transform unclassified message source
PASS  native v3 row with the same source kind  -> v3, 5 events
PASS  v2 row with a built-in source kind (control)  -> v3, 6 events

第 2、3 行是同一结构、同一 surfaceOp，唯一变量是存储代次，所以复现本身排除了"样例写坏"的可能。

插件侧确认（main / 0.1.18）

• src/command.ts 的 agent/pre-step gesture boundary 两条分支都会挂这个 kind：正常激活分支带 { goal, profile? }，profile 解析失败分支只有 { kind }。
• 补充一点值得注意的：parseCommandText 在没有任何 profile 配置时也会经 parseProfileInvocation 返回 { goal }，因此这个 kind 是每次 /agent-teams 调用都会写入，与是否使用 profile 无关。真实日志里可以看到同一次调用落盘两条用户消息 —— 原始命令是 kind:"user"，紧接着注入的激活指令才是 kind:"agent-teams-command"。
• 插件是通过 declare module '@deepseek-ai/dsh-llm' { interface MessageSourceMap { ... } } 做的 module augmentation，也就是官方声明支持的合并扩展方式；harness 侧的 MessageSourceMap 注释也写着 "an absent or unknown value is the documented default, presented as opaque content"。所以问题不在"插件乱造字段"，而在于迁移边的白名单没有兑现这个契约。

影响面（单机真实语料）

对 ~/.dsh/sessions 全部日志逐文件交叉统计：

日志代次	含 agent-teams-command	不含	读取结果
v0	15	157	含该 kind 的 15 份全部拒载（GUI 里完全打不开）
v3	16	15	含该 kind 的 16 份全部可读

另外，同类机制还影响其他插件的自定义 kind（例如 instruction-hint、at-file-mention），并非本插件独有。

两处可选修法

1. 插件侧（能立刻止住新增）：把这批注入消息的来源改成既有词汇，例如 { kind: 'plugin', plugin: 'dsh-agent-teams', form: 'instructions' }，或者直接复用 { kind: 'user' }（goal/profile 本来就已经在消息文本里）。这样新会话不再写入白名单外的 kind。
2. 宿主侧（才能救存量）：v2→v3 的来源审计对未知 kind 只校验"非空字符串 + 原样保留"，与原生 v3 准入保持一致；已知 kind 仍走精确审计。来源是归属信息、不含 Session 坐标，原样保留不涉及往日志里写猜测值。

只做 1 的话，已经写进历史的 15 份会话仍然打不开（迁移在读路径、插件加载之前执行），所以两者需要各修一半。

受影响用户的无损自救（不改写源代次）

我这边用官方持久层自身的 write-open（迁移 + Worker 校验 + 不可覆盖发布）把历史会话升成 v3 代次：

• 发布 session.v3.jsonl.zstd，源代次字节保持不变，原版 DSH 直接按"当前格式"读取；
• 本机 16 个受影响会话已全部恢复，strict + current 校验 16/16 通过；
• 相关脚本与说明我放在 https://github.com/chenkai2/dsh-tools（dsh-migrate-sessions.mjs）。

如果需要，我可以把上面第 1 条的插件侧改动整理成 PR。

[NanmiCoder]

保留。本次 0.1.21 修复的 #196 是新 V4 持久消息的 producer source；它不能修复已有 V2 日志中 agent-teams-command 被迁移白名单拒绝的问题。当前 command 激活路径仍使用该来源，#169 也尚未合并。需要对新写入和历史日志迁移分别做回归，不能把“新会话/冷恢复通过”当作全部旧会话可以恢复。