dsh-sessions-manager 3.5.0 → 3.5.2

package/src/markdown.js

@@ -75,6 +75,83 @@ export function summarizeToolArguments(name, rawArguments) {
   return JSON.stringify(rest).slice(0, MAX_TOOL_ARG)
 }
 
+// Shared event fold. `out` accumulates markdown lines; both the one-shot
+// renderer and the streaming builder (large-log export, see export-md route)
+// consume it so their output is byte-identical for the same events.
+function createMarkdownFold(out, header, options) {
+  const includeReasoning = options.includeReasoning === true
+  const includeToolResults = options.includeToolResults === true
+  let title = typeof header.title === 'string' && header.title.trim() ? header.title.trim() : null
+  let turn = null
+  return {
+    get title() { return title },
+    // The last session/title event wins — DSH may retitle a session later on.
+    add(events) {
+      const list = Array.isArray(events) ? events : []
+      for (const ev of list) {
+        if (!ev || typeof ev !== 'object') continue
+        const data = ev.data && typeof ev.data === 'object' ? ev.data : {}
+        const type = ev.type
+
+        if (type === 'session/title' && data && typeof data.title === 'string' && data.title.trim()) {
+          title = data.title.trim()
+          continue
+        }
+
+        if (type === 'turn/start') {
+          const next = Number.isInteger(data.turn) ? data.turn : null
+          if (next !== null && next !== turn) {
+            turn = next
+            out.push('', `## 第 ${turn} 轮`)
+          }
+          continue
+        }
+
+        if (type === 'user/message') {
+          const blocks = blocksOf(data.content)
+          const text = textFromBlocks(blocks)
+          const images = imageCountOf(blocks)
+          if (!text && images === 0) continue
+          out.push('', '### 用户', '')
+          if (text) out.push(text)
+          for (let i = 0; i < images; i++) out.push('', `![图片 ${i + 1}](attachment)`)
+          continue
+        }
+
+        if (type === 'assistant/message') {
+          const message = data.message && typeof data.message === 'object' ? data.message : {}
+          const blocks = blocksOf(message.content)
+          const text = textFromBlocks(blocks)
+          const reasoning = includeReasoning ? reasoningFromBlocks(blocks) : ''
+          if (!text && !reasoning) continue
+          out.push('', '### 助手', '')
+          if (reasoning) out.push('> 思考：' + reasoning.split('\n').join('\n> '), '')
+          if (text) out.push(text)
+          continue
+        }
+
+        if (type === 'tool/call') {
+          const name = typeof data.name === 'string' && data.name ? data.name : 'tool'
+          const summary = summarizeToolArguments(name, data.arguments)
+          out.push('', `### 工具调用：\`${name}\``, '')
+          out.push(summary ? '```\n' + summary + '\n```' : '（无参数）')
+          continue
+        }
+
+        if (type === 'tool/result' && includeToolResults) {
+          const message = data.message && typeof data.message === 'object' ? data.message : {}
+          const blocks = blocksOf(message.content)
+          let text = ''
+          for (const block of blocks) {
+            if (block.type === 'tool-result') text = textFromBlocks(blocksOf(block.content))
+          }
+          if (text) out.push('', '<details><summary>工具结果</summary>', '', '```\n' + text.slice(0, 2000) + '\n```', '', '</details>')
+        }
+      }
+    },
+  }
+}
+
 /**
  * Render one session as Markdown.
  * @param {object} meta - Session header (`{ id, cwd, createdAt, title? }`).
@@ -86,19 +163,12 @@ export function summarizeToolArguments(name, rawArguments) {
  * @returns {string} Markdown document.
  */
 export function renderSessionMarkdown(meta, events, options = {}) {
-  const includeReasoning = options.includeReasoning === true
-  const includeToolResults = options.includeToolResults === true
   const header = meta && typeof meta === 'object' ? meta : {}
-  const list = Array.isArray(events) ? events : []
+  const out = []
 
-  // The last session/title event wins — DSH may retitle a session later on.
-  let title = typeof header.title === 'string' && header.title.trim() ? header.title.trim() : null
-  for (const ev of list) {
-    const data = ev && ev.data
-    if (ev && ev.type === 'session/title' && data && typeof data.title === 'string' && data.title.trim()) {
-      title = data.title.trim()
-    }
-  }
+  const fold = createMarkdownFold(out, header, options)
+  fold.add(events)
+  const title = fold.title
 
   const front = ['---']
   if (title) front.push(`title: ${yamlString(title)}`)
@@ -110,66 +180,47 @@ export function renderSessionMarkdown(meta, events, options = {}) {
   if (exported) front.push(`exportedAt: ${exported}`)
   front.push('---')
 
-  const out = [front.join('\n')]
-  if (title) out.push('', `# ${title}`)
+  const doc = [front.join('\n')]
+  if (title) doc.push('', `# ${title}`)
+  doc.push(...out, '')
+  return doc.join('\n')
+}
 
-  let turn = null
-  for (const ev of list) {
-    if (!ev || typeof ev !== 'object') continue
-    const data = ev.data && typeof ev.data === 'object' ? ev.data : {}
-    const type = ev.type
-
-    if (type === 'turn/start') {
-      const next = Number.isInteger(data.turn) ? data.turn : null
-      if (next !== null && next !== turn) {
-        turn = next
-        out.push('', `## 第 ${turn} 轮`)
-      }
-      continue
-    }
-
-    if (type === 'user/message') {
-      const blocks = blocksOf(data.content)
-      const text = textFromBlocks(blocks)
-      const images = imageCountOf(blocks)
-      if (!text && images === 0) continue
-      out.push('', '### 用户', '')
-      if (text) out.push(text)
-      for (let i = 0; i < images; i++) out.push('', `![图片 ${i + 1}](attachment)`)
-      continue
-    }
-
-    if (type === 'assistant/message') {
-      const message = data.message && typeof data.message === 'object' ? data.message : {}
-      const blocks = blocksOf(message.content)
-      const text = textFromBlocks(blocks)
-      const reasoning = includeReasoning ? reasoningFromBlocks(blocks) : ''
-      if (!text && !reasoning) continue
-      out.push('', '### 助手', '')
-      if (reasoning) out.push('> 思考：' + reasoning.split('\n').join('\n> '), '')
-      if (text) out.push(text)
-      continue
-    }
-
-    if (type === 'tool/call') {
-      const name = typeof data.name === 'string' && data.name ? data.name : 'tool'
-      const summary = summarizeToolArguments(name, data.arguments)
-      out.push('', `### 工具调用：\`${name}\``, '')
-      out.push(summary ? '```\n' + summary + '\n```' : '（无参数）')
-      continue
-    }
-
-    if (type === 'tool/result' && includeToolResults) {
-      const message = data.message && typeof data.message === 'object' ? data.message : {}
-      const blocks = blocksOf(message.content)
-      let text = ''
-      for (const block of blocks) {
-        if (block.type === 'tool-result') text = textFromBlocks(blocksOf(block.content))
-      }
-      if (text) out.push('', '<details><summary>工具结果</summary>', '', '```\n' + text.slice(0, 2000) + '\n```', '', '</details>')
-    }
+/**
+ * Streaming variant of {@link renderSessionMarkdown} for chunked log reads
+ * (SessionHandle.read offset/length). Feed event batches in log order via
+ * `addEvents`; call `finish()` to get the same markdown document the one-shot
+ * renderer would produce. Only the final title (last session/title event)
+ * lands in the front matter, so streaming cannot be wrong about it.
+ *
+ * `finish(metaOverride)` — when the caller streams first and only learns the
+ * authoritative header afterwards (adapter inspectSession returns `meta` with
+ * the summary), pass it here; it replaces the constructor `meta` for the front
+ * matter fields (id / cwd / createdAt). Title always comes from the folded
+ * events, never from the override.
+ */
+export function createSessionMarkdownBuilder(meta, options = {}) {
+  const header = meta && typeof meta === 'object' ? meta : {}
+  const body = []
+  const fold = createMarkdownFold(body, header, options)
+  return {
+    addEvents(events) { fold.add(events) },
+    finish(metaOverride) {
+      const effective = metaOverride && typeof metaOverride === 'object' ? metaOverride : header
+      const title = fold.title
+      const front = ['---']
+      if (title) front.push(`title: ${yamlString(title)}`)
+      if (typeof effective.id === 'string' && effective.id) front.push(`sessionId: ${yamlString(effective.id)}`)
+      if (typeof effective.cwd === 'string' && effective.cwd) front.push(`cwd: ${yamlString(effective.cwd)}`)
+      const created = isoTime(effective.createdAt)
+      if (created) front.push(`createdAt: ${created}`)
+      const exported = isoTime(options.exportedAt)
+      if (exported) front.push(`exportedAt: ${exported}`)
+      front.push('---')
+      const doc = [front.join('\n')]
+      if (title) doc.push('', `# ${title}`)
+      doc.push(...body, '')
+      return doc.join('\n')
+    },
   }
-
-  out.push('')
-  return out.join('\n')
 }

package/src/path-guard.js

@@ -0,0 +1,59 @@
+// path-guard.js — 回收站/彻底删除前的「日志路径归属」校验（纯函数）。
+//
+// purgeFromTrash 在物理 unlink 前必须确认目标路径真的属于该会话，防止把
+// 无关文件删掉。旧实现用 `basename(dirname(target)) === sid`，只对 POSIX
+// 分隔符成立：Windows 风格路径（`C:\\…\\<sid>\\session.jsonl.zstd`）在
+// POSIX 版 path.basename 下整串是一个 basename，校验会错误拒绝；反过来，
+// 混合分隔符或 URL 编码路径也可能造成误放行。这里统一按两种分隔符切分，
+// 并处理盘符前缀与尾部斜杠。
+//
+// 接受两种官方/历史布局：
+//   .../<sessionId>/session.jsonl.zstd   （目录名 = 会话 id）
+//   .../<sessionId>.jsonl.zstd           （旧后端：文件名含会话 id）
+
+function splitSegments(target) {
+  return String(target)
+    .replace(/[\\/]+$/, '')
+    .split(/[\\/]/)
+    .filter((seg) => seg.length > 0)
+}
+
+// 去掉 Windows 盘符段（"C:"），保留其余段。POSIX 路径不含盘符段：
+// 一个名为 "C:" 的目录段在 macOS/Linux 上合法但极罕见，把它当盘符
+// 处理对「会话 id 归属」判断没有影响（id 不会是 "C:"）。
+function stripDriveLetter(segments) {
+  return segments.length > 0 && /^[A-Za-z]:$/.test(segments[0]) ? segments.slice(1) : segments
+}
+
+/**
+ * Does `target` plausibly own `sid`'s stored log?
+ * @param {string} target - absolute-ish log path reported by the backend or the trash index.
+ * @param {string} sid - session id (already validated by isSafeSessionId: no separators).
+ * @returns {boolean}
+ */
+export function pathOwnsSession(target, sid) {
+  if (typeof target !== 'string' || target.length === 0) return false
+  if (typeof sid !== 'string' || sid.length === 0) return false
+  const segments = stripDriveLetter(splitSegments(target))
+  if (segments.length === 0) return false
+  const file = segments[segments.length - 1]
+  // Layout 1: the session id owns the parent directory.
+  if (segments.length >= 2 && segments[segments.length - 2] === sid) return true
+  // Layout 2: legacy flat layout — the id is part of the file name itself.
+  // Only a *standalone token* match counts: `sid` embedded in a longer id
+  // (abc ↔ abcdef) must NOT pass, otherwise a purge of `abc` could delete
+  // `abcdef`'s log. Extension punctuation (".jsonl.zstd") is not id-glue.
+  if (file.includes(sid)) {
+    const ID_CHAR = /[A-Za-z0-9_-]/
+    let from = 0
+    while (true) {
+      const at = file.indexOf(sid, from)
+      if (at < 0) return false
+      const before = at > 0 ? file[at - 1] : ''
+      const after = at + sid.length < file.length ? file[at + sid.length] : ''
+      if (!(before && ID_CHAR.test(before)) && !(after && ID_CHAR.test(after))) return true
+      from = at + 1
+    }
+  }
+  return false
+}

package/src/session-meta-cache.js

@@ -1,21 +1,31 @@
-// session-meta-cache.js — 会话「原始元数据」内存缓存（按日志文件指纹校验）。
+// session-meta-cache.js — 会话「原始元数据」内存缓存（按日志内容指纹校验）。
 //
 // 背景（issue #1）：列表构建原本对每条会话调用 readTitleSnapshot，而该调用会把
 // 会话日志（.jsonl.zstd）的**所有 zstd 帧**逐帧解压、逐行 JSON.parse，只为折叠出
 // 最新标题。大库（数十条会话、十万级帧）一次全表要几秒 CPU，且解码是同步块，
 // 会阻塞宿主事件循环，连累 session.history 之类的 RPC 超时。
 //
-// 关键观察：解码得出的元数据（title / cwd / createdAt）只随**日志文件内容**变化，
-// 而任何append/改名/移动都会更新日志文件的 mtime。所以只要记下当时的
-// (mtimeMs, size)，下次 stat 到相同指纹就可以直接复用缓存，跳过整本解码。
+// 指纹有两种来源（按 runtime 能力自动选择，调用方构造 stat 对象）：
 //
-// 为什么自己实现而不用 runtime 的 prepared 缓存：插件不能假设对方的 runtime 版本
-// （issue 报告者是 0.1.1-rc.2，本机是 0.1.2-rc.1），runtime 侧的缓存容量/命中策略
-// 各版本不同。本模块只用 node 原生能力与插件已有的 sp.locate + stat，任何版本行为一致。
+//   1. 文件指纹（legacy runtime）：记下日志的 (mtimeMs, size)。任何
+//      append/改名/移动都会更新 mtime，所以「stat 相同 ⇒ 内容没变」。
+//      该指纹可跨进程持久化（title-persist-index 用它做冷启动加速）。
 //
-// 失效策略（三重保险）：
-//   1. 指纹校验：mtimeMs 或 size 任一变化即视为过期（append 改 mtime、移动改写 frame0 也改 mtime）
-//   2. TTL：防止「mtime 精度/时钟回拨」导致的长期陈旧
+//   2. revision 指纹（SessionHandle 世代 runtime，0.1.3+）：sessionPersistence
+//      的 list()/stat() 返回 SessionPersistenceSnapshot，其 `revision` 是
+//      **不透明变更令牌**。官方契约：同一 service 实例、同一 session id 内，
+//      revision 相等可视为日志未变；除此之外 revision 不做任何承诺。
+//      ⚠️ 因此 revision 指纹**绝不能写入跨进程的持久缓存**（不同进程/重启后
+//      revision 值无意义，误用可能把陈旧数据当新鲜数据）。持久索引落盘前必须
+//      用 isPersistableFingerprint() 过滤。
+//
+// 为什么自己实现而不用 runtime 的 prepared 缓存：插件不能假设对方的 runtime 版本，
+// runtime 侧的缓存容量/命中策略各版本不同。本模块只用纯数据判定，任何版本行为一致。
+//
+// 失效策略：
+//   1. 指纹校验：revision 不相等 / mtimeMs 或 size 任一变化即视为过期
+//   2. TTL：仅对文件指纹生效（防 mtime 精度/时钟回拨）；revision 相等即权威，
+//      不受 TTL 影响（官方契约明文允许 treat equal revisions as unchanged）
 //   3. 显式 invalidate：删除 / 移动 / 归档等宿主操作后主动丢弃对应条目
 //
 // 纯逻辑与副作用分离：isFresh / partitionByCache 都是纯函数，便于单测。
@@ -23,11 +33,18 @@
 const DEFAULT_TTL_MS = 5 * 60 * 1000
 const DEFAULT_MAX = 4000
 
-// 文件指纹：只有同时拿到 mtime 与 size 才可信（两者都变才算内容变了）。
+const REVISION_PREFIX = 'rev:'
+
+// 文件指纹：只有同时拿到 mtime 与 size 才可信。
 // 拿不到 stat 信息时返回 null——表示「无法校验」，调用方必须按未命中处理，
 // 绝不能在有疑问时返回旧数据。
 export function fingerprintOf(stat) {
   if (!stat || typeof stat !== 'object') return null
+  // revision 指纹优先：SessionHandle 世代没有可靠的 locate/stat，
+  // snapshot.revision 是官方提供的唯一变更令牌。
+  if (typeof stat.revision === 'string' && stat.revision.length > 0) {
+    return REVISION_PREFIX + stat.revision
+  }
   const mtimeMs = stat.mtimeMs
   const size = stat.size
   if (typeof mtimeMs !== 'number' || !Number.isFinite(mtimeMs) || mtimeMs <= 0) return null
@@ -35,18 +52,27 @@ export function fingerprintOf(stat) {
   return `${Math.floor(mtimeMs)}:${size}`
 }
 
+// revision 指纹只在当前 service 实例内有意义，绝不能落盘作为跨进程指纹。
+// title-persist-index 等持久化层必须在写入前用它过滤。
+export function isPersistableFingerprint(fingerprint) {
+  return typeof fingerprint === 'string' && fingerprint !== '' && !fingerprint.startsWith(REVISION_PREFIX)
+}
+
 // 缓存条目是否仍然新鲜（纯函数）。
+// stat 传 { revision } 或 { mtimeMs, size }；两类指纹不能互相匹配。
 export function isFresh(entry, stat, now, ttlMs = DEFAULT_TTL_MS) {
   if (!entry) return false
   const fp = fingerprintOf(stat)
   if (!fp) return false
   if (entry.fingerprint !== fp) return false
   if (typeof entry.at !== 'number') return false
+  // revision 指纹不受 TTL 约束：契约允许把相等 revision 视为日志未变。
+  if (fp.startsWith(REVISION_PREFIX)) return true
   return (now - entry.at) <= ttlMs
 }
 
 // 把一批 id 分成「命中缓存」与「需要解码」两组（纯函数，便于单测）。
-// statsById: Map<id, {mtimeMs, size}>；cache: 与 SessionMetaCache 同构的 Map。
+// statsById: Map<id, {mtimeMs, size} | {revision}>；cache: 与 SessionMetaCache 同构的 Map。
 export function partitionByCache(ids, statsById, cache, now = Date.now(), ttlMs = DEFAULT_TTL_MS) {
   const cached = new Map()
   const missing = []
@@ -87,7 +113,8 @@ export function createSessionMetaCache(opts = {}) {
     set(id, stat, meta) {
       if (!meta) return null
       const fp = fingerprintOf(stat)
-      // 无法算出指纹（没 stat / stat 失败）时不写缓存：写进去就再也无法可靠失效。
+      // 无法算出指纹（没 stat / revision 缺失 / stat 失败）时不写缓存：
+      // 写进去就再也无法可靠失效。
       if (!fp) return null
       const key = String(id)
       map.delete(key)

package/src/title-persist-index.js

@@ -26,6 +26,10 @@ const MAX_ENTRIES = 20000
 
 // 条目只保留可序列化且对列表有用的字段；指纹缺失的条目无法校验，直接丢弃——
 // 宁可下次重解码，也不能把无法失效的数据当真。
+// ⚠️ revision 指纹（"rev:…"）只在当前 service 实例内有意义（官方 0.1.3 契约：
+// opaque token, same instance + same session id），绝不能落盘作为跨进程指纹——
+// 这里作为最后防线再次拦截（调用方 session-meta-cache.isPersistableFingerprint
+// 已先行过滤）。
 export function normalizeEntry(raw) {
   if (!raw || typeof raw !== 'object') return null
   const title = typeof raw.title === 'string' ? raw.title : null
@@ -33,7 +37,8 @@ export function normalizeEntry(raw) {
   const createdAt = typeof raw.createdAt === 'number' ? raw.createdAt : null
   const fingerprint = typeof raw.fingerprint === 'string' && raw.fingerprint ? raw.fingerprint : null
   const updatedAt = typeof raw.updatedAt === 'number' ? raw.updatedAt : 0
-  if (!fingerprint || (!title && !cwd)) return null
+  if (!fingerprint || fingerprint.startsWith('rev:')) return null
+  if (!title && !cwd) return null
   return { title, cwd, createdAt, fingerprint, updatedAt }
 }
 

package/src/zstd-frame.js

@@ -20,33 +20,71 @@ export const ZSTD_MAGIC = 0xFD2FB528
 const CHECKSUM_OPTS = { params: { [zlib.constants.ZSTD_c_checksumFlag]: 1 } }
 
 /**
- * Locate real zstd frame boundaries in a concatenated-frame buffer.
- *
- * Scanning for the 4-byte magic alone produces FALSE POSITIVES: the same byte
- * sequence can occur inside compressed data. Every candidate is therefore
- * validated by attempting decompression; only offsets that decode are kept.
+ * Parse complete concatenated Zstandard frames without decompressing them.
+ * Invalid complete structure rejects; EOF inside the final frame is reported
+ * as torn rather than guessed from magic bytes occurring in compressed data.
  *
  * @param {Buffer} buf
- * @returns {number[]} ascending offsets of real frame starts
+ * @param {number} maxFrames
+ * @returns {{frames: Array<{start:number,end:number}>, tornStart?: number}}
  */
-export function findZstdFrameStarts(buf) {
-  const starts = []
-  for (let i = 0; i + 4 <= buf.length; i++) {
-    if (buf.readUInt32LE(i) !== ZSTD_MAGIC) continue
-    try {
-      // Two checks are needed, not just one:
-      //  - a magic inside compressed data fails to decode and throws
-      //  - a BARE 4-byte magic at the very end of the buffer decodes to an
-      //    EMPTY result without throwing, so non-empty output is required too
-      // Every real frame carries at least one JSON line, so neither case can
-      // be a genuine frame start.
-      const out = zlib.zstdDecompressSync(buf.subarray(i, i + Math.min(buf.length - i, 1000000)))
-      if (out.length > 0) starts.push(i)
-    } catch (_) {
-      // Not a real frame boundary — the magic bytes occurred inside compressed data.
+export function scanZstdFrames(buf, maxFrames = Number.POSITIVE_INFINITY) {
+  const frames = []
+  let offset = 0
+  while (offset < buf.length) {
+    const start = offset
+    if (buf.length - offset < 4) return { frames, tornStart: start }
+    if (buf.readUInt32LE(offset) !== ZSTD_MAGIC) {
+      throw new Error(`会话日志格式异常（字节 ${offset} 的 zstd magic 无效）`)
+    }
+    offset += 4
+    if (offset === buf.length) return { frames, tornStart: start }
+
+    const descriptor = buf.readUInt8(offset++)
+    if ((descriptor & 0x18) !== 0) throw new Error(`会话日志格式异常（字节 ${offset - 1} 使用保留帧头位）`)
+    const contentSizeFlag = descriptor >>> 6
+    const singleSegment = (descriptor & 0x20) !== 0
+    const checksum = (descriptor & 0x04) !== 0
+    const dictionaryFlag = descriptor & 0x03
+    const dictionaryBytes = dictionaryFlag === 3 ? 4 : dictionaryFlag
+    const contentSizeBytes = contentSizeFlag === 0 ? (singleSegment ? 1 : 0) : 1 << contentSizeFlag
+    const remainingHeaderBytes = (singleSegment ? 0 : 1) + dictionaryBytes + contentSizeBytes
+    if (buf.length - offset < remainingHeaderBytes) return { frames, tornStart: start }
+    offset += remainingHeaderBytes
+
+    for (;;) {
+      if (buf.length - offset < 3) return { frames, tornStart: start }
+      const blockHeader = buf.readUIntLE(offset, 3)
+      offset += 3
+      const lastBlock = (blockHeader & 1) !== 0
+      const blockType = (blockHeader >>> 1) & 0x03
+      const blockSize = blockHeader >>> 3
+      if (blockType === 0x03) throw new Error(`会话日志格式异常（字节 ${offset - 3} 使用保留块类型）`)
+      const payloadBytes = blockType === 0x01 ? 1 : blockSize
+      if (buf.length - offset < payloadBytes) return { frames, tornStart: start }
+      offset += payloadBytes
+      if (lastBlock) break
+    }
+    if (checksum) {
+      if (buf.length - offset < 4) return { frames, tornStart: start }
+      offset += 4
     }
+    frames.push({ start, end: offset })
+    if (frames.length === maxFrames) return { frames }
   }
-  return starts
+  return { frames }
+}
+
+/** Backward-compatible frame-start view used by diagnostics and tests. */
+export function findZstdFrameStarts(buf) {
+  return scanZstdFrames(buf).frames.map((frame) => frame.start)
+}
+
+function firstFrame(buf) {
+  const scan = scanZstdFrames(buf, 1)
+  const frame = scan.frames[0]
+  if (!frame) throw new Error('会话日志格式异常（无完整 zstd 帧）')
+  return frame
 }
 
 /**
@@ -64,10 +102,9 @@ export function findZstdFrameStarts(buf) {
  */
 export function rewriteFrame0Cwd(filePath, newCwd) {
   const buf = readFileSync(filePath)
-  const starts = findZstdFrameStarts(buf)
-  if (starts.length === 0) throw new Error('会话日志格式异常（无 zstd 帧）')
-  const end0 = starts.length > 1 ? starts[1] : buf.length
-  const frame0 = buf.subarray(starts[0], end0)
+  const frame = firstFrame(buf)
+  const end0 = frame.end
+  const frame0 = buf.subarray(frame.start, end0)
   const text = zlib.zstdDecompressSync(frame0).toString('utf8')
   const nl = text.indexOf('\n')
   const line = nl >= 0 ? text.slice(0, nl) : text
@@ -91,10 +128,9 @@ export function rewriteFrame0Cwd(filePath, newCwd) {
  * @returns {Buffer} rewritten log
  */
 export function rewriteFrame0CwdInMemory(buf, newCwd) {
-  const starts = findZstdFrameStarts(buf)
-  if (starts.length === 0) throw new Error('会话日志格式异常（无 zstd 帧）')
-  const end0 = starts.length > 1 ? starts[1] : buf.length
-  const frame0 = buf.subarray(starts[0], end0)
+  const frame = firstFrame(buf)
+  const end0 = frame.end
+  const frame0 = buf.subarray(frame.start, end0)
   const text = zlib.zstdDecompressSync(frame0).toString('utf8')
   const nl = text.indexOf('\n')
   const line = nl >= 0 ? text.slice(0, nl) : text
@@ -128,10 +164,8 @@ export function buildSessionLog(header, events = []) {
  * @returns {{obj: object, lineCount: number}}
  */
 export function readFrame0(buf) {
-  const starts = findZstdFrameStarts(buf)
-  if (starts.length === 0) throw new Error('会话日志格式异常（无 zstd 帧）')
-  const end0 = starts.length > 1 ? starts[1] : buf.length
-  const text = zlib.zstdDecompressSync(buf.subarray(starts[0], end0)).toString('utf8')
+  const frame = firstFrame(buf)
+  const text = zlib.zstdDecompressSync(buf.subarray(frame.start, frame.end)).toString('utf8')
   const lines = text.split('\n').filter((l) => l.length > 0)
   return { obj: JSON.parse(lines[0]), lineCount: lines.length }
 }