dsh-sessions-manager 3.5.3 → 3.6.0

package/src/client/logic.js

@@ -69,3 +69,82 @@ export function workspaceForNodes(nodes) {
 export function starredOf(items) {
   return (items || []).filter((item) => item && item.starred)
 }
+
+// 血缘折叠：把 origin === 'subagent' 的会话挂到父会话下，返回顶层列表 + 父子
+// 映射 + 折叠数量。
+//
+// 关键约束：从顶层移除的是「子代理自己」，父会话必须保留在顶层——折叠按钮就
+// 渲染在父会话卡片里，父一旦被一起过滤掉，界面上就只剩平铺的子代理，看起来
+// 像「折叠完全没生效」。
+// 父会话不在当前列表（被筛选掉 / 已删除）时子代理保持在顶层，保证搜得到就
+// 看得见。
+export function foldSubagents(items, lineage) {
+  const list = items || []
+  const table = lineage || {}
+  const kidsOf = new Map()
+  const foldedIds = new Set()
+  const byId = new Map()
+  for (const item of list) byId.set(String(item.sessionId), item)
+  for (const item of list) {
+    const id = String(item.sessionId)
+    const info = table[id]
+    const parentId = info && info.origin === 'subagent' && info.parentSession ? String(info.parentSession) : null
+    if (!parentId || parentId === id || !byId.has(parentId)) continue
+    if (!kidsOf.has(parentId)) kidsOf.set(parentId, [])
+    kidsOf.get(parentId).push(item)
+    foldedIds.add(id)
+  }
+  return {
+    topList: foldedIds.size ? list.filter((item) => !foldedIds.has(String(item.sessionId))) : list,
+    kidsOf,
+    foldedCount: foldedIds.size,
+  }
+}
+
+// 列表里只显示会话 ID 的短片段。完整 UUID 有 36 个字符，塞进 meta 行会把整
+// 行撑到换行、卡片高度跟着浮动——短 ID 是「列表定高」的前提之一。完整值保留
+// 在 title 属性与详情面板里，信息不丢。
+export function shortId(id) {
+  const raw = String(id == null ? '' : id)
+  const tail = raw.startsWith('session-') ? raw.slice(8) : raw
+  if (!tail) return ''
+  return tail.length <= 10 ? tail : tail.slice(0, 8) + '…'
+}
+
+// 打开子代理之后的提示文案。三种结果要传达三件不同的事，混成一句「打不开」
+// 会让人既不知道原因、也不知道下一步：
+//   ok         → 已经切过去了；在设置面板里会话区被挡着，得提醒关掉才看得到
+//   no-service → 这个 runtime 没开放会话切换接口，只能手动切
+//   failed     → 自动切换没成功，给出确定可走的替代路径（侧栏父会话头部的
+//                「/ N」官方子代理目录）
+// where: 'panel'（设置面板内）| 'sidebar'（侧栏注入行）
+export function openSubagentToast(result, name, where) {
+  const label = name || '子代理'
+  if (result === 'ok') {
+    return {
+      kind: 'ok',
+      text: where === 'sidebar' ? `已打开「${label}」` : `已打开「${label}」— 关掉设置即可看到`,
+    }
+  }
+  if (result === 'no-service') {
+    return { kind: 'err', text: '这个 DSH 版本没有开放会话切换接口，请在侧边栏手动切换' }
+  }
+  return {
+    kind: 'err',
+    text: where === 'sidebar'
+      ? '打不开这个子代理：请选中它的父会话，点标题栏的「/ N」子代理目录'
+      : '打不开：请在侧边栏选中它的父会话，点标题栏的「/ N」子代理目录',
+  }
+}
+
+// 提示（toast）停留时长：按**可读字数**给，而不是固定 2.4s / 2.6s。
+// 中文舒适阅读约 6 字/秒，留 40% 余量后夹在 [2.6s, 11s]；失败类再 ×1.25（同样受上限约束）。
+// 背景（2026-09-10 用户反馈）：排队/失败类文案动辄 40~100 字，"还没读完提示就不见了"。
+export const TOAST_MIN_MS = 2600
+export const TOAST_MAX_MS = 11000
+export function toastDurationFor(text, kind) {
+  const chars = String(text == null ? '' : text).length
+  const readingMs = Math.round((chars / 6) * 1000 * 1.4)
+  const scaled = kind === 'err' ? Math.round(readingMs * 1.25) : readingMs
+  return Math.min(TOAST_MAX_MS, Math.max(TOAST_MIN_MS, scaled))
+}

package/src/compat/persistence.js

@@ -19,10 +19,24 @@ const DEFAULT_CHUNK = 400
 // 防御上限：一次 inspect 的分块循环绝不能无限自旋（后端 read 行为异常时快速失败）。
 const MAX_CHUNKS = 20000
 
+// SessionHandle.read() 的返回值在 0.1.3 / 0.1.5 之间换过形态，这里统一成事件数组：
+//   - 0.1.3：直接是事件数组（或可迭代对象）
+//   - 0.1.5：**{ eventState: 'shared-frozen' | …, events: [...] }**（不再是数组！
+//     末尾读取同样是这个形状，只是 events: []）
+//   - 未知形态**抛错而不是当空数组**：静默返回 [] 的代价是灾难性的——
+//     2026-09-10 实测，0.1.5 升级后读取恒为空，移动"用空事件重建日志"把两个会话
+//     削成只剩头部的空壳。任何无法识别的返回值都必须让调用方看到错误。
 function normalizeReadResult(events) {
+  if (events === undefined || events === null) return []
   if (Array.isArray(events)) return events
-  if (events && typeof events[Symbol.iterator] === 'function') return [...events]
-  return []
+  if (typeof events === 'object' && Array.isArray(events.events)) return events.events
+  if (typeof events[Symbol.iterator] === 'function') return [...events]
+  const error = new Error(
+    'DSH 会话读取返回了无法识别的结构（runtime 接口可能已变更），已停止解析以免误判为空：' +
+    Object.prototype.toString.call(events),
+  )
+  error.code = 'DSM_READ_SHAPE_UNKNOWN'
+  throw error
 }
 
 async function closeQuietly(handle) {

package/src/handle-era-ops.js

@@ -14,17 +14,110 @@
 //     （活跃写者 → 409 拒绝），然后整目录删除会话目录（basename 已由路径
 //     守卫验证），最后以官方 stat 复核该 id 已消失。
 //
-// 活跃写者策略：两个操作都拒绝「正在进行中」的会话，而不是照 legacy 那样
-// 改写活跃对象——handle 时代的写句柄所有权在官方 tracker 内部，与其打补丁
-// 不如如实拒绝，风险面更小。
+// 活跃写者策略：两个操作都拒绝「被 DSH 打开、写权限已被占用」的会话，而不是照
+// legacy 那样改写活跃对象——handle 时代的写句柄所有权在官方 tracker 内部，
+// 与其打补丁不如如实拒绝，风险面更小。
+//
+// 注意这与 legacy 时代的可用范围不同：legacy 时代没有单写者所有权，插件直接改
+// 文件 + 同步 live 对象就能移动任意会话；0.1.3 引入 handle 后，agent-loop 在
+// resume 会话时先取写所有权（core/agent-loop resumeWith: "Taking write ownership
+// FIRST"）并持有到 agent 卸载，于是「在 DSH 里点开过的会话」一律处于占用态。
+// 这是宿主机制决定的硬约束，不是插件能绕开的判定，提示必须如实说明。
 
-import { mkdir, readFile, rename, rm, unlink, writeFile } from 'node:fs/promises'
-import { join } from 'node:path'
+import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises'
+import { basename, dirname, join } from 'node:path'
 import { rewriteFrame0CwdInMemory, scanZstdFrames } from './zstd-frame.js'
-import { deriveSessionDir, locateSessionArtifacts } from './handle-era-paths.js'
+import { deriveSessionDir, encodeSegmentFor, generationVersionOf, locateSessionArtifacts } from './handle-era-paths.js'
 
 const MOVE_BATCH = 400
 
+// 真实日志判定：官方命名是 session.vN.jsonl[.zstd]，legacy 时代是
+// session.jsonl[.zstd]——锚定结尾，其他后缀（如测试残渣 *.jsonl.zstd.test）
+// 不算真日志；只有本插件移动过程的临时名（.move-backup- / .move-stage-）
+// 也不算。
+const REAL_LOG_RE = /^session.*\.jsonl(\.zst(d)?)?$/
+const MOVE_TEMP_RE = /\.move-(backup|stage)-/
+// 会话目录里"本会话自己的"非日志文件（lease / flock / 官方临时产物）。用于判定
+// 一个仅剩旧代的目录是不是可以安全回收——夹带别的文件就交人工裁决。
+const SESSION_LOCAL_JUNK_RE = /^(\.?session\.lock.*|\.lock.*|.*\.lock|.*\.tmp|.*\.stage|.*\.bak|\.DS_Store)$/
+
+// 同 id 跨目录残留处理。后端在 create/list 时扫全盘：同一会话 id 出现在多个
+// 项目目录即报 “duplicate JSONL session id ... appears in multiple project
+// directories”。三类残留区别对待（判定顺序即风险从低到高）：
+//
+//   1) 空壳：目录里没有任何真实日志 → 纯垃圾，直接删。
+//   2) 只含**被取代的旧代**日志（最高代版本号严格低于当前目录的最高代）→ 也删。
+//      0.1.5 起官方「发布新代但不删旧代」（实测同一目录里 session.v2 与
+//      session.v3 并存），而历史版本的插件移动时只搬走当前代，留下的旧代会让该
+//      id 永远处于"跨目录重复"状态，之后所有移动/彻底删除都被拒。旧代内容已被
+//      新代取代（官方读取恒定取最高代），删除不丢数据，且会以 note 如实回报。
+//      为稳妥只删"纯日志目录"（除日志外只允许 lock/临时文件），夹带未知文件时
+//      降级为第 3 类人工裁决。
+//   3) 版本相同或更高 → 真重复，无法判断哪份权威 → 拒绝移动并给出清单。
+async function cleanSiblingCopies(root, sid, keepDir, keepVersion) {
+  let projects
+  try { projects = await readdir(root, { withFileTypes: true }) } catch (e) { return { removed: 0, superseded: [], real: [] } }
+  let segment
+  try { segment = encodeSegmentFor(sid) } catch (e) { return { removed: 0, superseded: [], real: [] } }
+  let removed = 0
+  const superseded = []
+  const real = []
+  for (const ent of projects) {
+    if (!ent.isDirectory()) continue
+    const candidate = join(root, ent.name, segment)
+    if (keepDir && candidate === keepDir) continue
+    let entries
+    try {
+      const st = await stat(candidate)
+      if (!st.isDirectory()) continue
+      entries = await readdir(candidate)
+    } catch (e) { continue }
+    const logs = entries.filter((name) => REAL_LOG_RE.test(name) && !MOVE_TEMP_RE.test(name))
+    if (logs.length === 0) {
+      try { await rm(candidate, { recursive: true, force: true }); removed++ } catch (e) { /* 清不掉的壳由真重复检查兜底 */ }
+      continue
+    }
+    const highest = Math.max(...logs.map(generationVersionOf))
+    const onlyLogsAndLocalJunk = entries.every((name) =>
+      (REAL_LOG_RE.test(name) && !MOVE_TEMP_RE.test(name)) || SESSION_LOCAL_JUNK_RE.test(name))
+    if (Number.isSafeInteger(keepVersion) && highest < keepVersion && onlyLogsAndLocalJunk) {
+      try {
+        await rm(candidate, { recursive: true, force: true })
+        superseded.push(candidate)
+      } catch (e) { real.push(candidate) }
+      continue
+    }
+    real.push(candidate)
+  }
+  return { removed, superseded, real }
+}
+
+// 移动成功后的源目录收尾。目标侧已经 create + append + 校验出一份完整权威日志，
+// 源目录必须**整体移除**：
+//   - 0.1.5 起官方发布新代不删旧代，若只搬走当前代，源目录里的旧代会让同 id 出现
+//     在两个项目目录 → 官方 listArtifacts/stat 立刻报 duplicate（实测根因）；
+//   - 目录本身已由 locateSessionArtifacts 校验过 basename === encodeSegment(id)
+//     且 id 归属正确，删的是该会话自己的目录，不是"疑似别人的数据"。
+// 返回 { cleaned, leftover }：cleaned=false + leftover 名单用于如实回报清理失败。
+async function removeSourceDir(sessionDir) {
+  let entries
+  try { entries = await readdir(sessionDir) } catch (e) { return { cleaned: true, leftover: [] } }
+  try {
+    await rm(sessionDir, { recursive: true, force: true })
+  } catch (e) {
+    return { cleaned: false, leftover: entries }
+  }
+  return { cleaned: true, leftover: [] }
+}
+
+// 活跃写者（409）提示。0.1.3 起官方 session handle 是「单写者」：agent-loop
+// 在 resume 一个会话时先 open(id,'write') 取写所有权并持有到 agent 卸载，所以
+// 在 DSH 里点开过的会话都处于被占用状态。runtime 未提供任何能远程释放该所有权
+// 的公共 API（无 unloadSession / closeSession / evict），因此插件不能替用户解锁，
+// 只能如实说明可操作的自救路径，并靠「重试」让用户切走会话后原地再试一次。
+const BUSY_MOVE_MESSAGE = '会话正被 DSH 打开，暂时无法移动；请重启 DSH 后再试。'
+const BUSY_PURGE_MESSAGE = '会话正被 DSH 打开，暂时无法彻底删除；请重启 DSH 后再试。'
+
 function conflictError(message) {
   const error = new Error(message)
   error.status = 409
@@ -56,7 +149,7 @@ export async function ensureNoActiveWriter(sp, sid) {
   try {
     handle = await sp.open(sid, 'write')
   } catch (e) {
-    if (isAlreadyOwned(e)) throw conflictError('该会话正在进行中（存在活跃写入），请先切换到别的会话再操作。')
+    if (isAlreadyOwned(e)) throw conflictError(BUSY_MOVE_MESSAGE)
     throw e
   }
   await closeQuietly(handle)
@@ -75,7 +168,7 @@ export async function purgeSessionArtifacts(sp, sid, header) {
   try {
     writer = await sp.open(sid, 'write')
   } catch (e) {
-    if (isAlreadyOwned(e)) throw conflictError('该会话正在进行中（存在活跃写入），无法彻底删除。')
+    if (isAlreadyOwned(e)) throw conflictError(BUSY_PURGE_MESSAGE)
     throw e
   }
   // 句柄从未 append 过，先释放再删目录（Windows 上打开中的文件无法删除）。
@@ -104,8 +197,8 @@ export async function purgeSessionArtifacts(sp, sid, header) {
 
 // frame0 改写回退：把备份日志的 frame0 cwd 改写为目标工作区后搬入目标会话目录。
 // 校验与 legacy relocateLog 完全一致：帧数不变 + frame0 之外字节逐位相等。
-async function relocateRewrittenBackup({ sid, canonical, backupPath, artifacts }) {
-  const original = await readFile(backupPath)
+async function relocateRewrittenBackup({ sid, canonical, backupLogPath, artifacts }) {
+  const original = await readFile(backupLogPath)
   const frames = scanZstdFrames(original).frames
   if (frames.length === 0) throw new Error('移动前校验失败：会话日志没有完整 zstd 帧')
   const rewritten = rewriteFrame0CwdInMemory(original, canonical)
@@ -126,22 +219,82 @@ async function relocateRewrittenBackup({ sid, canonical, backupPath, artifacts }
 // seeded（fork 溯源）日志的物理事件 seq 不从 0 起步时，官方 assertContiguous
 // 会拒绝直录——此时把副本日志的 seq 重排为 0 起步（仅副本的存储序，事件内容
 // 不变），并在 create 时如实携带 inheritedEventCount 溯源。
+//
+// 0.1.5 关键约束（实测）：官方在 open(id,'write') 时会为历史代**发布当前代**
+// （v0/v2 → v3）且**不删旧代**，一个会话目录里可同时有 v0/v2/v3；而官方
+// listArtifacts/findLog 会跨项目目录解析同一个 id，**任意两个目录同时持有该 id
+// 的日志（无论哪一代）都会抛 duplicate**。所以搬运必须是：
+//   探测（会发布新代，必须先做）→ 定位 → 同 id 残留清理
+//   → **把整个源会话目录改名移开**（对官方彻底不可见，而不是只搬单个文件）
+//   → 目标侧 create+append+校验 → 成功则删除移开的源目录，失败则整体改回。
 export async function moveSessionToCwd({ sp, sid, header, canonical, events = [], inheritedEventCount = 0 }) {
+  // 1) 写所有权探测放最前：它可能发布新代，之后定位到的才是权威路径。
+  // 非「已被占用」的探测失败（后端异常等）不在此处立即上抛——先看能否定位，
+  // 定位也失败时如实回报定位错误（提示更可操作），能定位时才报告写状态未知。
+  let probeError = null
+  try {
+    await ensureNoActiveWriter(sp, sid)
+  } catch (e) {
+    if (e && e.status === 409) throw e
+    probeError = e
+  }
   const artifacts = await locateSessionArtifacts(sp, header)
   if (!artifacts) {
     const error = new Error('无法定位该会话的物理日志，已停止移动')
     error.status = 409
     throw error
   }
-  await ensureNoActiveWriter(sp, sid)
+  if (probeError) {
+    const error = new Error('无法确认该会话是否正被写入，已停止移动：' + String((probeError && probeError.message) || probeError))
+    error.status = 409
+    throw error
+  }
+  // 数据安全守卫（最后一层保险）：源日志明显不只是头部（> 4KB），但我们拿到的事件
+  // 是空的 —— 说明读取链路出了问题。此时若继续，就是"用空事件重建日志"再删掉源目录，
+  // 等于清空会话。2026-09-10 实测过一次（0.1.5 读取返回结构变更），绝不能再发生。
+  const HEADER_ONLY_MAX = 4096
+  if (events.length === 0) {
+    let sourceBytes = null
+    try { sourceBytes = (await stat(artifacts.logPath)).size } catch (e) { sourceBytes = null }
+    if (sourceBytes !== null && sourceBytes > HEADER_ONLY_MAX) {
+      const error = new Error(
+        `移动前校验失败：源日志有 ${sourceBytes} 字节但读到 0 条事件（读取链路异常），已停止移动以免丢失会话内容。`,
+      )
+      error.status = 409
+      error.code = 'DSM_MOVE_EMPTY_READ'
+      throw error
+    }
+  }
+  // 2) 同 id 跨目录残留：空壳与被取代的旧代直接回收（会以 note 回报），
+  //    版本相同/更高的真重复拒绝移动并给出清单。必须在 rename 备份之前做——
+  //    rename 后源目录暂时变成壳，会干扰判定。
+  const siblings = await cleanSiblingCopies(artifacts.root, sid, artifacts.sessionDir, artifacts.generationVersion)
+  if (siblings.real.length > 0) {
+    const error = new Error(
+      '无法移动：在其他工作区目录发现同一会话的日志副本，请先确认保留哪一份：\n' +
+      siblings.real.map((p) => '· ' + p).join('\n')
+    )
+    error.status = 409
+    error.code = 'DSM_SESSION_DUP_LOG'
+    throw error
+  }
   const newHeader = Object.assign({}, header, { cwd: canonical })
   const firstSeq = events.length ? Number(events[0].seq) : 0
   const replay = firstSeq !== 0 ? events.map((event, index) => ({ ...event, seq: index })) : events
   const createOptions = header.isSeeded && Number.isSafeInteger(inheritedEventCount) && inheritedEventCount > 0
     ? { inheritedEventCount }
     : undefined
-  const backupPath = `${artifacts.logPath}.move-backup-${process.pid}-${Date.now()}`
-  await rename(artifacts.logPath, backupPath)
+  // 3) 把**整个源会话目录**移出 sessions 根，而不是只 rename 当前代那一个文件：
+  //    - 只搬单个文件会留下并存的其他代（0.1.5 的 v0/v2/v3 多代共存），
+  //    - 在本项目目录里改名也不够：官方 listSessionDirs 枚举项目目录下的**所有**
+  //      子目录（不按名字过滤），listArtifacts 会读每个目录里的日志头，仍会看到
+  //      同一个 id → duplicate。必须移到 root 之外（与回收站同级）才对官方扫描
+  //      彻底不可见。
+  const backupRoot = join(dirname(artifacts.root), 'sessions-manager-move-backup')
+  const backupDir = join(backupRoot, `${encodeSegmentFor(sid)}-${process.pid}-${Date.now()}`)
+  await mkdir(backupRoot, { recursive: true })
+  const backupLogPath = join(backupDir, basename(artifacts.logPath))
+  await rename(artifacts.sessionDir, backupDir)
   let writer = null
   try {
     try {
@@ -156,7 +309,7 @@ export async function moveSessionToCwd({ sp, sid, header, canonical, events = []
       if (isAlreadyExists(e)) {
         // 后端内存里已有同 id 记录（created-but-unmaterialized 幽灵等）：
         // 回退到 frame0 改写搬运，不再走 create。
-        await relocateRewrittenBackup({ sid, canonical, backupPath, artifacts })
+        await relocateRewrittenBackup({ sid, canonical, backupLogPath, artifacts })
       } else {
         throw e
       }
@@ -171,15 +324,22 @@ export async function moveSessionToCwd({ sp, sid, header, canonical, events = []
       throw new Error(`移动后校验失败：事件数不一致（源 ${events.length}，副本 ${after.eventCount}）`)
     }
   } catch (e) {
-    // 回滚：清掉目标目录里的半成品，把备份改名回原位。
+    // 回滚：清掉目标目录里的半成品，把整个源目录移回原位（多代日志一起复原）。
     await closeQuietly(writer)
     try { await rm(deriveSessionDir(artifacts.root, canonical, sid), { recursive: true, force: true }) } catch (_) {}
-    try { await rename(backupPath, artifacts.logPath) } catch (_) {}
+    try { await mkdir(dirname(artifacts.sessionDir), { recursive: true }) } catch (_) {}
+    try { await rename(backupDir, artifacts.sessionDir) } catch (_) {}
     if (e && e.status) throw e
     const error = new Error('移动会话日志失败：' + String((e && e.message) || e))
     error.status = 500
     throw error
   }
-  try { await unlink(backupPath) } catch (e) { /* 备份清理失败不阻塞成功结果 */ }
-  return { sessionDir: deriveSessionDir(artifacts.root, canonical, sid) }
+  // 4) 成功：删掉移开的源目录（含全部旧代日志）。留着它等于让同一个 id 出现在
+  //    两个项目目录，下一次 create/list 立刻被后端 duplicate 检查拒绝。
+  const sourceCleanup = await removeSourceDir(backupDir)
+  return {
+    sessionDir: deriveSessionDir(artifacts.root, canonical, sid),
+    sourceCleanup,
+    reclaimedSiblings: siblings.superseded,
+  }
 }

package/src/handle-era-paths.js

@@ -26,7 +26,13 @@ import { readdir, stat } from 'node:fs/promises'
 import { basename, join } from 'node:path'
 import { pathOwnsSession } from './path-guard.js'
 
-const GENERATION_LOG_RE = /^session\.v\d+\.jsonl(\.zst(d)?)?$/
+// 规范 generation 文件：官方 `session.vN.jsonl[.zstd]`，**v0 代无 `.vN.` 分量**
+// （即 `session.jsonl[.zstd]`，legacy 时代产物）。官方
+// `parseSessionFormatLogFilename` 把 v0 当 version 0 参与「最高代优先」，
+// 所以这里也必须收 v0，否则「只有 v0 代」的会话会被误判为不可定位
+// （移动/彻底删除静默禁用）。临时备份名（`.move-backup-…`）不以
+// `.jsonl`/`.zstd` 结尾，天然不匹配。
+const GENERATION_LOG_RE = /^session(\.v\d+)?\.jsonl(\.zst(d)?)?$/
 
 function isSafeChar(ch) {
   return ch !== '~' && /^[A-Za-z0-9._-]$/.test(ch)
@@ -80,8 +86,16 @@ export function deriveSessionDir(root, cwd, id) {
 }
 
 // 纯推导（不做磁盘校验）。供测试与上层组合使用。
-export function deriveGenerationLogPath(root, cwd, id, { compression = 'zstd' } = {}) {
-  return join(deriveSessionDir(root, cwd, id), `session.v2.jsonl${compression === 'zstd' ? '.zstd' : ''}`)
+// `generation` 只是名字里的 `.vN` 分量：0 = legacy 的 `session.jsonl`，2 = `session.v2.jsonl`。
+// 实际落盘版本由 runtime 的格式目录决定，此处不假设“当前版本是几”。
+export function deriveGenerationLogPath(root, cwd, id, { compression = 'zstd', generation = 2 } = {}) {
+  const base = generation === 0 ? 'session.jsonl' : `session.v${generation}.jsonl`
+  return join(deriveSessionDir(root, cwd, id), `${base}${compression === 'zstd' ? '.zstd' : ''}`)
+}
+
+// 名字里的代版本号（`session.v3.jsonl.zstd` → 3；`session.jsonl.zstd` → 0）。
+export function generationVersionOf(name) {
+  return Number((String(name).match(/^session\.v(\d+)\./) || [])[1] || 0)
 }
 
 // 定位一个已落盘会话的全部物理坐标；三层守卫在此汇合。返回
@@ -108,12 +122,8 @@ export async function locateSessionArtifacts(sp, header) {
   }
   const generationFiles = entries.filter((name) => GENERATION_LOG_RE.test(name))
   if (generationFiles.length === 0) return null
-  // 优先 current generation（v2 → 最高版本号），保持确定性。
-  generationFiles.sort((a, b) => {
-    const va = Number((a.match(/^session\.v(\d+)\./) || [])[1] || 0)
-    const vb = Number((b.match(/^session\.v(\d+)\./) || [])[1] || 0)
-    return vb - va
-  })
+  // 优先 current generation（v0/legacy 也是候选，版本号最小），保持确定性。
+  generationFiles.sort((a, b) => generationVersionOf(b) - generationVersionOf(a))
   const logPath = join(sessionDir, generationFiles[0])
   if (!pathOwnsSession(logPath, sid)) return null
   return {
@@ -122,5 +132,8 @@ export async function locateSessionArtifacts(sp, header) {
     sessionDir,
     logPath,
     generationFiles,
+    // 最高代版本号：0 = legacy `session.jsonl[.zstd]`，≥1 = `session.vN.jsonl[.zstd]`。
+    // 上层用它判断「另一个目录里的同 id 副本是不是被取代的旧代」。
+    generationVersion: generationVersionOf(generationFiles[0]),
   }
 }