@240xu/dsh-message-ops 0.2.2

package/test/fence.test.js

@@ -0,0 +1,208 @@
+/**
+ * dsh-message-ops — 评审修复测试（node --test）。
+ * 覆盖：HTTP 信任围栏（P0）、写操作 Content-Type/413、写端 replace 拼写
+ * 运行时探测（P1 前向雷）、异步逐帧读取与 partial 语义（P1）。
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+process.env.DSH_HOME = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-msgops-fence-'))
+
+const { isTrustedApiRequest, isJsonContentType, applySurfaceReplace, _resetReplaceShape, OpsError } =
+  await import('../src/ops-core.js')
+const { encodeSessionFile, readSessionFileAsync, computeShadowed } = await import('../src/session-file.js')
+const { apply } = await import('../src/index.js')
+
+// --- 围栏纯函数 ----------------------------------------------------------------
+
+function req(headers) { return { headers } }
+
+test('isTrustedApiRequest：回环 Host 放行（localhost / 127.x / ::1）', () => {
+  assert.equal(isTrustedApiRequest(req({ host: 'localhost:3080' })), true)
+  assert.equal(isTrustedApiRequest(req({ host: '127.0.0.1:3080' })), true)
+  assert.equal(isTrustedApiRequest(req({ host: '127.7.7.7' })), true)
+  assert.equal(isTrustedApiRequest(req({ host: "[::1]:3080" })), true)
+})
+
+test('isTrustedApiRequest：非回环 Host / 缺 Host 拒绝（DNS rebinding）', () => {
+  assert.equal(isTrustedApiRequest(req({ host: 'evil.com:3080' })), false)
+  // 2130706433 是十进制 IPv4，WHATWG URL 会规范化为 127.0.0.1 → 本就是回环，放行
+  assert.equal(isTrustedApiRequest(req({ host: '2130706433' })), true)
+  assert.equal(isTrustedApiRequest(req({})), false)
+  assert.equal(isTrustedApiRequest(req({ host: '127.0.0.999' })), false)
+  assert.equal(isTrustedApiRequest(req({ host: 'foo.127.0.0.1' })), false)
+})
+
+test('isTrustedApiRequest：sec-fetch-site cross-site / Origin 不同源拒绝；同源放行', () => {
+  const h = { host: '127.0.0.1:3080' }
+  assert.equal(isTrustedApiRequest(req({ ...h, 'sec-fetch-site': 'cross-site' })), false)
+  assert.equal(isTrustedApiRequest(req({ ...h, origin: 'http://evil.com' })), false)
+  assert.equal(isTrustedApiRequest(req({ ...h, origin: 'http://127.0.0.1:3080' })), true)
+  assert.equal(isTrustedApiRequest(req({ ...h, 'sec-fetch-site': 'same-origin' })), true)
+  assert.equal(isTrustedApiRequest(req({ ...h, origin: 'not a url' })), false)
+})
+
+test('isJsonContentType：application/json（含 charset 后缀）通过，其余拒绝', () => {
+  assert.equal(isJsonContentType(req({ 'content-type': 'application/json' })), true)
+  assert.equal(isJsonContentType(req({ 'content-type': 'application/json; charset=utf-8' })), true)
+  assert.equal(isJsonContentType(req({ 'content-type': 'text/plain' })), false)
+  assert.equal(isJsonContentType(req({})), false)
+})
+
+// --- 路由级围栏（mock req/res 直接驱动注册的 handler） --------------------------
+
+function makeCtx() {
+  const routes = new Map()
+  const ctx = {
+    get(k) { return k === 'webServer' ? { register: (r) => routes.set(r.path, r.handler) } : undefined },
+    inject() {},
+    effect(fn) { return fn() },
+  }
+  apply(ctx)
+  return routes
+}
+
+function mockReq({ method = 'GET', url = '/', headers = {}, body } = {}) {
+  const chunks = body === undefined ? [] : [Buffer.from(body)]
+  return {
+    method, url, headers,
+    async *[Symbol.asyncIterator]() { for (const c of chunks) yield c },
+  }
+}
+
+function mockRes() {
+  const out = { status: null, headers: null, body: '' }
+  out.writeHead = (status, headers) => { out.status = status; out.headers = headers || {} }
+  out.end = (b) => { out.body = b == null ? '' : String(b) }
+  return out
+}
+
+test('路由级：非回环 Host → 403；cross-site POST → 403（先于业务校验）', async () => {
+  const routes = makeCtx()
+  const res1 = mockRes()
+  await routes.get('/api/message-ops/messages')(mockReq({ url: '/api/message-ops/messages?sessionId=x', headers: { host: 'evil.com' } }), res1)
+  assert.equal(res1.status, 403)
+  const res2 = mockRes()
+  await routes.get('/api/message-ops/revert')(mockReq({
+    method: 'POST', url: '/api/message-ops/revert', headers: { host: '127.0.0.1', 'sec-fetch-site': 'cross-site', origin: 'http://evil.com' },
+  }), res2)
+  assert.equal(res2.status, 403)
+})
+
+test('路由级：写操作 text/plain 绕预检 → 415；超大 body → 413', async () => {
+  const routes = makeCtx()
+  const res1 = mockRes()
+  await routes.get('/api/message-ops/revert')(mockReq({
+    method: 'POST', url: '/api/message-ops/revert',
+    headers: { host: '127.0.0.1', 'content-type': 'text/plain' }, body: '{"sessionId":"x","seq":1}',
+  }), res1)
+  assert.equal(res1.status, 415)
+
+  const big = Buffer.alloc(1024 * 1024 + 1, 0x61).toString()
+  const res2 = mockRes()
+  await routes.get('/api/message-ops/revert')(mockReq({
+    method: 'POST', url: '/api/message-ops/revert',
+    headers: { host: '127.0.0.1', 'content-type': 'application/json' }, body: big,
+  }), res2)
+  assert.equal(res2.status, 413)
+})
+
+test('路由级：回环同源 GET export → 200 附件；非法 body JSON → 400', async () => {
+  const id = 'session-99999999-8888-7777-6666-555555555555'
+  const dir = path.join(process.env.DSH_HOME, 'sessions', 'proj-fence', id)
+  fs.mkdirSync(dir, { recursive: true })
+  const events = [
+    { type: 'user/message', seq: 0, surfaceOp: 'append', data: { message: { role: 'user', content: [{ type: 'text', text: '围栏测试' }] } } },
+  ]
+  fs.writeFileSync(path.join(dir, 'session.v3.jsonl.zstd'), encodeSessionFile({ type: 'session', version: 3, id, createdAt: 1 }, events))
+
+  const routes = makeCtx()
+  const res1 = mockRes()
+  await routes.get('/api/message-ops/export')(mockReq({
+    url: `/api/message-ops/export?sessionId=${id}`,
+    headers: { host: 'localhost:3080', origin: 'http://localhost:3080' },
+  }), res1)
+  assert.equal(res1.status, 200)
+  assert.match(res1.headers['content-type'], /text\/markdown/)
+  assert.match(res1.headers['content-disposition'], /attachment/)
+  assert.match(res1.body, /围栏测试/)
+
+  const res2 = mockRes()
+  await routes.get('/api/message-ops/revert')(mockReq({
+    method: 'POST', url: '/api/message-ops/revert',
+    headers: { host: '127.0.0.1', 'content-type': 'application/json' }, body: '{broken',
+  }), res2)
+  assert.equal(res2.status, 400)
+})
+
+// --- 写端 replace 拼写运行时探测（P1 前向雷） -----------------------------------
+
+function probingSession(failLegacy) {
+  const appends = []
+  return {
+    appends,
+    append(type, data, opts) {
+      appends.push(opts)
+      const op = opts && opts.surfaceOp
+      if (failLegacy && op && typeof op === 'object' && op.op === 'replace' && 'startSeq' in op) {
+        throw new Error('session event "system/message" carries an invalid replace surfaceOp')
+      }
+      return { seq: appends.length - 1, type, data, opts }
+    },
+  }
+}
+
+test('applySurfaceReplace：新引擎（拒 startSeq）自动降级 {start,end} 并记住拼写', () => {
+  _resetReplaceShape()
+  const session = probingSession(true)
+  const ev = applySurfaceReplace(session, 3, 4, [3, 4], 'notice')
+  assert.equal(ev.seq, 1)
+  // appends[0] 是被引擎拒绝的 legacy 尝试，appends[1] 是降级重试
+  assert.deepEqual(session.appends[0].surfaceOp, { op: 'replace', startSeq: 3, endSeq: 4 })
+  assert.deepEqual(ev.opts.surfaceOp, { op: 'replace', start: 3, end: 4 })
+  // 第二次直接用新拼写，不再探测
+  const ev2 = applySurfaceReplace(session, 5, 6, [5, 6], 'n2')
+  assert.deepEqual(ev2.opts.surfaceOp, { op: 'replace', start: 5, end: 6 })
+})
+
+test('applySurfaceReplace：当前引擎（收 startSeq）保持原拼写；无关错误原样抛出', () => {
+  _resetReplaceShape()
+  const session = probingSession(false)
+  applySurfaceReplace(session, 1, 2, [1, 2], 'n')
+  assert.deepEqual(session.appends[0].surfaceOp, { op: 'replace', startSeq: 1, endSeq: 2 })
+  _resetReplaceShape()
+  const boom = { append() { throw new Error('disk on fire') } }
+  assert.throws(() => applySurfaceReplace(boom, 1, 1, [1], 'n'), /disk on fire/)
+})
+
+// --- 异步逐帧读取 + partial 语义 + 双拼写 computeShadowed -----------------------
+
+test('readSessionFileAsync：事件完整恢复，返回 frameCount；超 frameBudget 置 partial', async () => {
+  const id = 'session-aaaa0000-0000-0000-0000-00000000f001'
+  const dir = path.join(process.env.DSH_HOME, 'sessions', 'proj-async', id)
+  fs.mkdirSync(dir, { recursive: true })
+  const events = [{ type: 'user/message', seq: 0, surfaceOp: 'append', data: { message: { role: 'user', content: [{ type: 'text', text: '异步读取' }] } } }]
+  const file = path.join(dir, 'session.v3.jsonl.zstd')
+  fs.writeFileSync(file, encodeSessionFile({ type: 'session', version: 3, id, createdAt: 1 }, events))
+
+  const r1 = await readSessionFileAsync(file)
+  assert.equal(r1.partial, false)
+  assert.equal(r1.frameCount, 1)
+  assert.equal(r1.events[0].data.message.content[0].text, '异步读取')
+  // encodeSessionFile 产生 header 帧 + 1 个事件帧；用最小 frameBudget 触发 partial
+  const r2 = await readSessionFileAsync(file, { frameBudget: 0 })
+  assert.equal(r2.partial, true)
+})
+
+test('computeShadowed：双拼写（startSeq/endSeq 与 start/end）都能推导遮蔽', () => {
+  const shadowed = computeShadowed([
+    { seq: 0, surfaceOp: { op: 'replace', startSeq: 0, endSeq: 1 } },
+    { seq: 2, surfaceOp: { op: 'replace', start: 2, end: 3 } },
+    { seq: 4, surfaceOp: { op: 'replace', startSeq: 4, start: 4 } }, // 半残：非法忽略
+  ])
+  assert.ok([0, 1, 2, 3].every((s) => shadowed.has(s)))
+  assert.ok(!shadowed.has(4))
+})

package/test/ops-core.test.js

@@ -0,0 +1,216 @@
+/**
+ * dsh-message-ops — 新功能零依赖测试（node --test）。
+ * 覆盖：export Markdown、restore 重放规划/落定、message_ops 工具构造与
+ * 容错注册（缺 tools 服务 / 缺 dsh-tools 包均不 fatal）。
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+
+const { OpsError, planRestore, applyRestore, exportMarkdown, messageText } =
+  await import('../src/ops-core.js')
+const { createMessageOpsTool, apply } = await import('../src/index.js')
+
+function msg(type, seq, text, role) {
+  return {
+    type, seq, time: Date.now(), surfaceOp: 'append',
+    data: { turn: 1, message: { role: role || (type === 'user/message' ? 'user' : 'assistant'), content: [{ type: 'text', text }] } },
+  }
+}
+
+function sampleEvents() {
+  return [
+    msg('user/message', 0, '第一问'),
+    msg('assistant/message', 1, '第一答'),
+    { type: 'tool/call', seq: 2, data: { name: 'bash', call: { name: 'bash', arguments: { command: 'ls' } } } },
+    msg('user/message', 3, '第二问'),
+    msg('assistant/message', 4, '第二答'),
+    // 一次 revert 落定：遮蔽 3..4，sourceEventSeqs 覆盖被遮蔽节点
+    {
+      type: 'system/message', seq: 5, time: Date.now(),
+      surfaceOp: { op: 'replace', startSeq: 3, endSeq: 4 },
+      sourceEventSeqs: [3, 4],
+      data: { message: { role: 'system', content: [{ type: 'text', text: '[消息回滚] 已回滚到 seq 3（含）之后的 2 个节点' }] } },
+    },
+  ]
+}
+
+const header = { type: 'session', version: 3, id: 'session-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee', createdAt: 1, cwd: '/tmp/x' }
+
+// --- exportMarkdown ----------------------------------------------------------
+
+test('exportMarkdown：消息按角色小节展开，工具调用折叠为单行', () => {
+  const md = exportMarkdown(header, sampleEvents())
+  assert.match(md, /^# DSH 会话导出：session-aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/m)
+  assert.match(md, /## \[seq 0\] user\n\n第一问/)
+  assert.match(md, /## \[seq 1\] assistant\n\n第一答/)
+  // 工具调用是单行引用，且含参数提示
+  const toolLines = md.split('\n').filter((l) => l.startsWith('> [seq 2]'))
+  assert.equal(toolLines.length, 1)
+  assert.match(toolLines[0], /🔧 工具调用：bash/)
+  assert.match(toolLines[0], /command/)
+  // revert 标记本身是 system 消息，也展开
+  assert.match(md, /## \[seq 5\] system/)
+})
+
+test('exportMarkdown：seq 上界只导出 ≤ 上界的事件', () => {
+  const md = exportMarkdown(header, sampleEvents(), 1)
+  assert.match(md, /seq ≤ 1/)
+  assert.match(md, /第一问/)
+  assert.doesNotMatch(md, /第二问/)
+  assert.doesNotMatch(md, /工具调用：bash/)
+})
+
+test('exportMarkdown：非法 seq 抛 OpsError(400)', () => {
+  assert.throws(() => exportMarkdown(header, sampleEvents(), -1), (e) => e instanceof OpsError && e.status === 400)
+  assert.throws(() => exportMarkdown(header, sampleEvents(), 1.5), OpsError)
+})
+
+// --- planRestore / applyRestore ----------------------------------------------
+
+test('planRestore：从 revert 标记事件规划重放（含 user/assistant，跳过 tool）', () => {
+  const plan = planRestore(sampleEvents(), 5)
+  assert.equal(plan.startSeq, 3)
+  assert.equal(plan.endSeq, 4)
+  assert.equal(plan.replayable.length, 2)
+  assert.equal(plan.skipped, 0)
+  assert.deepEqual(plan.replayable.map((r) => [r.role, r.seq, r.text]), [
+    ['user', 3, '第二问'],
+    ['assistant', 4, '第二答'],
+  ])
+})
+
+test('planRestore：兼容 start/end 拼写（dsh-src 较新引擎形状）', () => {
+  const events = [
+    msg('user/message', 0, 'a'),
+    { type: 'system/message', seq: 1, surfaceOp: { op: 'replace', start: 0, end: 0 }, sourceEventSeqs: [0] },
+  ]
+  const plan = planRestore(events, 1)
+  assert.equal(plan.startSeq, 0)
+  assert.equal(plan.replayable[0].text, 'a')
+})
+
+test('planRestore：非标记事件 / 越界 seq / 无可重放消息 均拒绝', () => {
+  const events = sampleEvents()
+  assert.throws(() => planRestore(events, 99), (e) => e instanceof OpsError && e.status === 404)
+  assert.throws(() => planRestore(events, 0), (e) => e instanceof OpsError && e.status === 409) // 普通消息非标记
+  assert.throws(() => planRestore(events, -1), (e) => e instanceof OpsError && e.status === 400)
+  // 区间内只有 tool 事件 → 无可重放
+  const onlyTool = [
+    { type: 'tool/call', seq: 0, data: { name: 'bash' } },
+    { type: 'system/message', seq: 1, surfaceOp: { op: 'replace', startSeq: 0, endSeq: 0 }, sourceEventSeqs: [0] },
+  ]
+  assert.throws(() => planRestore(onlyTool, 1), (e) => e instanceof OpsError && e.status === 409)
+})
+
+test('applyRestore：重放 append 带 [恢复] 前缀 + system 说明，flush 被调用', () => {
+  const appended = []
+  let seq = 10
+  const session = {
+    append(type, data, opts) {
+      const event = { seq: seq++, type, data, opts }
+      appended.push(event)
+      return event
+    },
+  }
+  const plan = planRestore(sampleEvents(), 5)
+  let flushed = 0
+  const result = applyRestore(session, plan, { flush: () => flushed++ })
+  assert.equal(flushed, 1)
+  assert.equal(result.restoredCount, 2)
+  assert.equal(result.skipped, 0)
+  assert.equal(appended.length, 3)
+  assert.equal(appended[0].type, 'system/message')
+  assert.match(appended[0].data.message.content[0].text, /\[消息恢复\] 重放 seq 3\.\.4 的 2 条消息/)
+  assert.equal(appended[1].type, 'user/message')
+  assert.equal(appended[1].data.message.content[0].text, '[恢复] 第二问')
+  assert.equal(appended[2].data.message.content[0].text, '[恢复] 第二答')
+  for (const a of appended) assert.equal(a.opts.surfaceOp, 'append')
+})
+
+test('messageText：数组 content 提取首个非空 text；data.content 兼容', () => {
+  assert.equal(messageText(msg('user/message', 0, 'hi')), 'hi')
+  assert.equal(messageText({ type: 'user/message', data: { content: [{ type: 'text', text: 'legacy' }] } }), 'legacy')
+  assert.equal(messageText({ type: 'user/message', data: {} }), '')
+})
+
+// --- message_ops 工具（桩 defineTool + 桩 ops） --------------------------------
+
+function stubDefineTool(def) {
+  def.__compiled = true
+  return def
+}
+
+test('createMessageOpsTool：defineTool 桩拿到 name/parameters/execute，execute 分发到 ops', async () => {
+  const calls = []
+  const ops = {
+    list: (ctx, id) => { calls.push(['list', id]); return { ok: true, session: { id }, running: false, total: 0, visibleCount: 0, messages: [] } },
+    revert: (ctx, id, seq) => { calls.push(['revert', id, seq]); return { mode: 'revert', seq, shadowedCount: 2, eventSeq: 9 } },
+  }
+  const tool = createMessageOpsTool({ defineTool: stubDefineTool, ops, ctx: {} })
+  assert.equal(tool.name, 'message_ops')
+  assert.ok(tool.__compiled)
+  assert.equal(tool.parameters.action.enum.length, 6)
+  assert.ok(tool.parameters.sessionId.required)
+  const out = await tool.execute({ action: 'list', sessionId: 'session-x' })
+  assert.match(out, /session session-x/)
+  const out2 = await tool.execute({ action: 'revert', sessionId: 'session-x', seq: 3 })
+  assert.match(out2, /revert ok: shadowed 2 node\(s\) from seq 3; marker event seq 9/)
+  assert.deepEqual(calls[1], ['revert', 'session-x', 3])
+})
+
+test('createMessageOpsTool：execute 捕获 OpsError 为失败文本而非抛出', async () => {
+  const ops = { delete: () => { throw new OpsError('seq 3 not visible on current surface', 409) } }
+  const tool = createMessageOpsTool({ defineTool: stubDefineTool, ops, ctx: {} })
+  const out = await tool.execute({ action: 'delete', sessionId: 'session-x', seq: 3 })
+  assert.match(out, /^delete failed: seq 3 not visible/)
+})
+
+// --- index.js apply：工具注册容错（不 fatal） ----------------------------------
+
+function mockCtx({ tools, webServer } = {}) {
+  const registrations = []
+  const injects = []
+  const host = { register: (route) => registrations.push(route) }
+  return {
+    registrations, injects, host,
+    get(key) {
+      if (key === 'webServer') return webServer === undefined ? undefined : webServer
+      if (key === 'tools') return tools
+      return undefined
+    },
+    inject(deps, fn) { injects.push([deps, fn]) },
+    effect(fn) { return fn() },
+  }
+}
+
+test('apply：无 webServer、无 tools 时走 inject 等待，不抛错', () => {
+  const ctx = mockCtx()
+  assert.doesNotThrow(() => apply(ctx))
+  assert.deepEqual(ctx.injects.map((i) => i[0]), [['webServer'], ['tools']])
+  assert.equal(ctx.registrations.length, 0)
+})
+
+test('apply：webServer 存在时注册全部 6 条路由；tools 缺失走 inject 等待', () => {
+  const ctx = mockCtx({ webServer: { register: (route) => ctx.registrations.push(route) } })
+  assert.doesNotThrow(() => apply(ctx))
+  const paths = ctx.registrations.map((r) => r.path).sort()
+  assert.deepEqual(paths, [
+    '/api/message-ops/branch',
+    '/api/message-ops/delete',
+    '/api/message-ops/export',
+    '/api/message-ops/messages',
+    '/api/message-ops/restore',
+    '/api/message-ops/revert',
+  ])
+  // tools 缺失 → 容错等待而非 fatal
+  assert.ok(ctx.injects.some(([deps]) => deps[0] === 'tools'))
+})
+
+test('apply：tools 服务存在时直接进入注册路径（包缺失时 catch 静默跳过）', () => {
+  const registered = []
+  const ctx = mockCtx({ webServer: { register: () => {} }, tools: { register: (t) => registered.push(t) } })
+  assert.doesNotThrow(() => apply(ctx))
+  // 动态 import('@deepseek-ai/dsh-tools') 在本测试环境不可解析 → 工具跳过，
+  // 但绝不能让插件 apply 抛错；异步分支也不能产生未处理拒绝。
+  assert.equal(registered.length, 0)
+})

package/test/session-file.test.js

@@ -0,0 +1,110 @@
+/**
+ * dsh-message-ops — 零依赖测试（node --test）。
+ * 覆盖：帧扫描/读写往返、消息列表、遮蔽推导、分支规划与落盘（临时目录）。
+ */
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+process.env.DSH_HOME = fs.mkdtempSync(path.join(os.tmpdir(), 'dsh-msgops-'))
+
+const { scanZstdFrames, readSessionFile, encodeSessionFile, findSessionDirs, listMessages, computeShadowed } =
+  await import('../src/session-file.js')
+const { planBranch, applyBranch } = await import('../src/branch.js')
+
+const MAGIC = 0xfd2fb528
+
+function header(id) {
+  return { type: 'session', version: 3, id, createdAt: Date.now(), cwd: '/tmp/x', delegationDepth: 0 }
+}
+function msg(type, seq, text) {
+  return { type, seq, time: Date.now(), surfaceOp: 'append', data: { turn: 1, step: 1, message: { role: type === 'user/message' ? 'user' : 'assistant', content: [{ type: 'text', text }] } } }
+}
+
+function writeLog(dir, header, events) {
+  fs.mkdirSync(dir, { recursive: true })
+  const p = path.join(dir, 'session.v3.jsonl.zstd')
+  fs.writeFileSync(p, encodeSessionFile(header, events))
+  return p
+}
+
+test('zstd 帧扫描定位每个魔数边界', () => {
+  const a = encodeSessionFile(header('session-00000000-0000-0000-0000-000000000001'), [msg('user/message', 0, 'hi')])
+  const b = encodeSessionFile(header('session-00000000-0000-0000-0000-000000000002'), [msg('user/message', 0, 'yo')])
+  const buf = Buffer.concat([a, b])
+  const { frames } = scanZstdFrames(buf)
+  assert.equal(frames.length, 4) // 2 files × (header frame + event frame)
+  for (const f of frames) assert.equal(buf.readUInt32LE(f.start), MAGIC)
+})
+
+test('读写往返：header 与事件完整恢复', () => {
+  const events = [
+    msg('user/message', 0, '你好'),
+    msg('assistant/message', 1, '你好！有什么可以帮你？'),
+    { type: 'tool/call', seq: 2, data: { name: 'bash' } },
+  ]
+  const p = writeLog(path.join(process.env.DSH_HOME, 'sessions', 'proj-a', 'session-00000000-0000-0000-0000-000000000003'), header('session-00000000-0000-0000-0000-000000000003'), events)
+  const { header: h, events: evs } = readSessionFile(p)
+  assert.equal(h.type, 'session')
+  assert.equal(evs.length, 3)
+  assert.equal(evs[0].data.message.content[0].text, '你好')
+})
+
+test('listMessages 提取 role/snippet 与 tool 摘要', () => {
+  const events = [msg('user/message', 0, '  多  空格\n文本 '), msg('assistant/message', 1, '回复'), { type: 'tool/call', seq: 2, data: { name: 'bash' } }]
+  const ms = listMessages(events)
+  assert.equal(ms.length, 3)
+  assert.equal(ms[0].role, 'user')
+  assert.equal(ms[0].snippet, '多 空格 文本')
+  assert.equal(ms[2].role, 'tool')
+  assert.match(ms[2].snippet, /\[tool\] bash/)
+})
+
+test('computeShadowed 识别 surface replace 遮蔽区间', () => {
+  const events = [
+    msg('user/message', 0, 'a'),
+    msg('assistant/message', 1, 'b'),
+    msg('user/message', 2, 'c'),
+    { type: 'system/message', seq: 3, surfaceOp: { op: 'replace', startSeq: 1, endSeq: 2 }, data: { message: { role: 'system', content: [{ type: 'text', text: '[回滚]' }] } } },
+  ]
+  const shadowed = computeShadowed(events)
+  assert.ok(shadowed.has(1) && shadowed.has(2))
+  assert.ok(!shadowed.has(0))
+})
+
+test('planBranch 生成新 id + parentSession，事件截断正确', () => {
+  const h = header('session-00000000-0000-0000-0000-000000000004')
+  const events = [msg('user/message', 0, 'a'), msg('assistant/message', 1, 'b'), msg('user/message', 2, 'c')]
+  const { header: nh, events: kept } = planBranch(h, events, 1)
+  assert.notEqual(nh.id, h.id)
+  assert.equal(nh.parentSession, h.id)
+  assert.match(nh.id, /^session-[0-9a-f-]{36}$/)
+  assert.equal(kept.length, 2)
+  assert.throws(() => planBranch(h, events, -1))
+})
+
+test('applyBranch 落盘：新目录 + 新日志 + 原文件字节不变', () => {
+  const id = 'session-00000000-0000-0000-0000-000000000005'
+  const events = [msg('user/message', 0, 'a'), msg('assistant/message', 1, 'b'), msg('user/message', 2, 'c')]
+  const origLog = writeLog(path.join(process.env.DSH_HOME, 'sessions', 'proj-b', id), header(id), events)
+  const before = fs.readFileSync(origLog)
+  const result = applyBranch(origLog, 1)
+  assert.match(result.newId, /^session-[0-9a-f-]{36}$/)
+  assert.ok(fs.existsSync(result.logPath))
+  const { header: nh, events: kept } = readSessionFile(result.logPath)
+  assert.equal(nh.parentSession, id)
+  assert.equal(kept.length, 2)
+  assert.deepEqual(fs.readFileSync(origLog), before)
+})
+
+test('findSessionDirs 两种 id 拼写均可定位', () => {
+  const uuid = '11111111-2222-3333-4444-555555555555'
+  writeLog(path.join(process.env.DSH_HOME, 'sessions', 'proj-c', `session-${uuid}`), header(`session-${uuid}`), [msg('user/message', 0, 'x')])
+  const byFull = findSessionDirs(`session-${uuid}`)
+  const byBare = findSessionDirs(uuid)
+  assert.equal(byFull.length, 1)
+  assert.equal(byBare.length, 1)
+  assert.equal(byFull[0].dir, byBare[0].dir)
+})