dsh-sessions-manager 3.5.4 → 3.6.1

package/src/index.js

@@ -7,27 +7,38 @@
 // (workspaceRegistry + storageDomain), folds titles/dates/workspace tags from
 // session persistence, physically removes a session's log file on delete, and
 // relocates a conversation (session) between workspaces on move.
-import { mkdir, readFile, realpath, rename, stat, unlink, writeFile } from 'node:fs/promises'
+import { mkdir, readFile, readdir, realpath, rename, rm, stat, unlink, writeFile } from 'node:fs/promises'
 import { basename, dirname, isAbsolute, join } from 'node:path'
 import { readFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { rewriteFrame0CwdInMemory, scanZstdFrames } from './zstd-frame.js'
 import { createSessionMarkdownBuilder } from './markdown.js'
 import { createStarIndex } from './star-index.js'
+import { createPendingMoveStore } from './pending-moves.js'
+import { sweepStaleStateTemps } from './state-temp-sweep.js'
 import { aggregateStorage } from './storage-stats.js'
 import { createAutoArchiveStore, pickInactiveCandidates } from './auto-archive.js'
-import { createSessionMetaCache, fingerprintOf, isPersistableFingerprint } from './session-meta-cache.js'
+import { createSessionMetaCache, persistFingerprintOf } from './session-meta-cache.js'
 import { createTitleIndexStore } from './title-persist-index.js'
 import { createPersistenceAdapter } from './compat/persistence.js'
 import { detectCapabilities, requireCapability } from './compat/capabilities.js'
 import { pathOwnsSession } from './path-guard.js'
 import { purgeSessionArtifacts, moveSessionToCwd } from './handle-era-ops.js'
+import { classifyLineage, isEmptyEventTypes, EMPTY_DECODE_LIMIT } from './lineage.js'
+
+// 构建指纹：build.mjs 以 define 在编译期注入；直接以源码运行（测试）时为 'dev'。
+// 用途：capabilities 带出 buildStamp，一眼判断「运行中的 host 是不是这份构建」——
+// 插件 host 端只在宿主启动时加载一次，改完 lib 不重启宿主等于白改。
+const BUILD_STAMP = typeof __BUILD_STAMP__ !== 'undefined' ? __BUILD_STAMP__ : 'dev'
 
 
 export const name = 'dsh-sessions-manager'
 export const inject = ['webServer', 'workspaceRegistry', 'sessionPersistence', 'sessionQuery', 'storageDomain']
 
 const MAX_TITLE = 80
+// 插件自有状态目录（星标 / 自动归档 / 标题索引共用）。与 star-index.js、auto-archive.js
+// 的默认目录保持一致，环境变量同名，便于测试注入。
+const STATE_DIR = process.env.DSH_SESSIONS_MANAGER_STAR_DIR || join(homedir(), '.dsh', 'sessions-manager')
 // Recycle bin (回收站): normal deletes land here instead of being erased.
 const TRASH_DIR = process.env.DSH_SESSIONS_MANAGER_TRASH_DIR || join(homedir(), '.dsh', 'sessions-manager-trash')
 const TRASH_INDEX = join(TRASH_DIR, 'index.json')
@@ -168,8 +179,11 @@ export function apply(ctx) {
       const stat = statsById.get(id)
       const entry = store && store[id]
       if (!stat || !entry) continue
-      const fp = fingerprintOf(stat)
-      if (!isPersistableFingerprint(fp)) continue
+      // 持久索引只认可跨重启的指纹（legacy 的文件指纹 / handle 世代的 sz 指纹，
+      // 见 session-meta-cache.persistFingerprintOf——issue #8 之前 handle 世代
+      // 从不落盘，导致每次重启都全量重新解码）。
+      const fp = persistFingerprintOf(stat)
+      if (!fp) continue
       if (fp && entry.fingerprint === fp) {
         hits.set(id, { title: entry.title, cwd: entry.cwd, createdAt: entry.createdAt })
       }
@@ -177,21 +191,23 @@ export function apply(ctx) {
     return hits
   }
 
-  // 把本批真正解码出的元数据异步回写持久索引（fire-and-forget：索引只是
-  // 加速器，写失败不影响响应，队列内部已串行化 + 原子替换）。
-  // ⚠️ revision 指纹（SessionHandle 世代）绝不落盘：它只在当前 service
-  // 实例内有意义，跨进程比较无意义，误用会把陈旧数据当新鲜数据。
-  function persistDecoded(decoded, statsById) {
+  // 把本批真正解码出的元数据回写持久索引（索引只是加速器：写失败不影响响应，
+  // 队列内部已串行化 + 原子替换）。**必须 await** —— 它是持久写入，浮动写入会在
+  // 调用方/测试 teardown 已开始清理状态目录时落地（`ENOTEMPTY: rmdir .../state`），
+  // 且"响应已返回但索引没落盘"时进程若恰好退出就会丢条目。
+  // 指纹用 persistFingerprintOf：legacy 文件指纹 + handle 世代 sz(sizeBytes) 指纹
+  // 都可跨重启；rev: 指纹仍被排除（实例内 opaque token，issue #8）。
+  async function persistDecoded(decoded, statsById) {
     if (!decoded || !decoded.size) return
     const batch = {}
     const now = Date.now()
     for (const [id, meta] of decoded) {
-      const fp = fingerprintOf(statsById.get(id))
-      if (!isPersistableFingerprint(fp)) continue
+      const fp = persistFingerprintOf(statsById.get(id))
+      if (!fp) continue
       batch[id] = { title: meta.title, cwd: meta.cwd, createdAt: meta.createdAt, fingerprint: fp, updatedAt: now }
     }
     if (!Object.keys(batch).length) return
-    titleIndex.merge(batch).catch(() => {})
+    try { await titleIndex.merge(batch) } catch (e) { /* 索引写失败不影响本次响应 */ }
   }
 
   // 从投影快照里抽出元数据；快照缺失/异常时返回零值 meta（调用方决定兜底）。
@@ -271,65 +287,82 @@ export function apply(ctx) {
 
   // Resolve one session's display metadata.
   //
-  // 成本模型（issue #1）：下面的解码路径会把整本 .jsonl.zstd 逐帧解压、逐行
-  // JSON.parse，只为折叠出标题——大库上一次全表要几秒阻塞式 CPU。日志内容没变
-  // 就意味着折叠结果不可能变（legacy 用 (mtime, size) 文件指纹；SessionHandle
-  // 世代用官方 snapshot.revision），命中即直接复用，跳过整本解码。
+  // 成本模型（issue #1 → issue #8）：runtime 的标题投影（readTitleSnapshots）
+  // 在 0.1.x 上对每条非 live 会话都是**整本日志解码**（SessionCorpus.projectMany
+  // → inspectPersisted）。列表构建绝不能在请求路径上同步触发它——issue #8 实测：
+  // 87 本日志 / 249MB 的库，一次冷启动全量投影把宿主打满 ~90s CPU。
   //
-  // 0.1.3-alpha 兼容（避免放大官方已知的历史会话加载性能回退）：
-  //   - cwd/createdAt 优先来自 list() 快照的 snapshot.header；
-  //   - 标题优先来自批量 readTitleSnapshots；
-  //   - **标题缺失绝不单独触发整本日志解码**——无标题就显示「(无标题)」。
-  //     只有在拿不到 cwd（工作区归属失效）或 runtime 完全没有标题投影能力时
-  //     才回退到日志解码，且该解码走 inspectSession 分块折叠，不做整本驻留。
-  async function resolveOne(id, usage, opts = {}) {
-    const key = String(id)
-    const statInfo = usage ? (usage.statsById ? usage.statsById.get(key) : null)
-      || { mtimeMs: usage.mtimeById && usage.mtimeById.get(key), size: usage.sizeById && usage.sizeById.get(key) } : null
-    const cached = metaCache.get(key, statInfo)
-    if (cached) return buildItem(key, cached, usage, opts.exposeUsage)
-
-    let meta = { title: null, cwd: null, createdAt: null }
-    // 第一来源：list() 返回的 SessionPersistenceSnapshot.header（0.1.3+ 官方
-    // 契约里 header 携带 cwd/createdAt，无需任何日志读取）。
-    if (opts.listHeader) {
-      if (typeof opts.listHeader.cwd === 'string') meta.cwd = opts.listHeader.cwd
-      if (opts.listHeader.createdAt != null) meta.createdAt = opts.listHeader.createdAt
-    }
-    if (opts.preloaded !== undefined) {
-      const projected = metaFromSnapshot(unwrapSnapshot(opts.preloaded))
-      if (projected.title) meta.title = projected.title
-      if (!meta.cwd && projected.cwd) meta.cwd = projected.cwd
-      if (!meta.createdAt && projected.createdAt) meta.createdAt = projected.createdAt
-    } else if (typeof sq.readTitleSnapshot === 'function') {
-      try {
-        const projected = metaFromSnapshot(await sq.readTitleSnapshot(id))
-        if (projected.title) meta.title = projected.title
-        if (!meta.cwd && projected.cwd) meta.cwd = projected.cwd
-        if (!meta.createdAt && projected.createdAt) meta.createdAt = projected.createdAt
-      } catch (e) { /* fall through */ }
+  // 因此请求路径只消费两级缓存（metaCache 内存缓存 → titleIndex 持久索引），
+  // 缺失的会话交给后台预热队列分批补齐（见 enqueueWarm/runWarm）；侧栏高频
+  // 轮询 + 管理面板刷新会让补齐结果自然浮现。
+  const EMPTY_META = { title: null, cwd: null, createdAt: null }
+
+  // —— 冷启动后台预热（issue #8）—————————————————————————————————————
+  // 单飞队列：请求路径发现缓存未命中的会话，把 { stat, header } 快照丢进
+  // warmQueue，由 runWarm 以小批次消费。每批之间 setImmediate 让步事件循环，
+  // 绝不独占宿主主线程；结果写 metaCache + 持久标题索引。stat 是入队时刻的
+  // 快照——若日志在预热期间又变了，下次请求的指纹比对会再次判未命中并重新
+  // 入队，天然自愈。
+  const WARM_CHUNK = 4
+  const warmQueue = new Map()
+  let warmRunning = false
+  let warmKickTimer = null
+
+  function scheduleWarm() {
+    if (warmKickTimer || warmRunning) return
+    warmKickTimer = setTimeout(() => { warmKickTimer = null; runWarm() }, 25)
+    // unref：预热绝不反过来把宿主进程钉住（与 autoArchive「无定时器」同一原则）。
+    if (typeof warmKickTimer.unref === 'function') warmKickTimer.unref()
+  }
+
+  function enqueueWarm(ids, statsById, entryById) {
+    if (!ids || !ids.length) return
+    for (const id of ids) {
+      const key = String(id)
+      const entry = entryById ? entryById.get(key) : null
+      warmQueue.set(key, {
+        stat: statsById ? (statsById.get(key) || null) : null,
+        header: (entry && entry.header) || null,
+      })
     }
-    // cwd 缺失 → 工作区归属失效，值得一次解码兜底（cwd 在 header 里，通常
-    // 快照已带回，这里只在快照缺 cwd 时发生）。runtime 完全没有标题投影能力
-    // 时（老后端无 readTitleSnapshot），解码同时兜底标题。
-    const projectionAvailable = typeof sq.readTitleSnapshot === 'function' || typeof sq.readTitleSnapshots === 'function'
-    if (!meta.cwd || (!meta.title && !projectionAvailable)) {
-      try {
-        let foldedTitle = null
-        const summary = await persistence.inspectSession(key, {
-          onEvents: (events) => { if (!foldedTitle) foldedTitle = foldTitle(events) },
-        })
-        if (summary && summary.meta) {
-          if (!meta.cwd) meta.cwd = summary.meta.cwd || null
-          if (!meta.createdAt) meta.createdAt = summary.meta.createdAt || null
-        }
-        if (!meta.title && foldedTitle) meta.title = foldedTitle
-      } catch (e2) { /* keep what we have */ }
+    scheduleWarm()
+  }
+
+  async function runWarm() {
+    if (warmRunning) return
+    warmRunning = true
+    try {
+      while (warmQueue.size) {
+        const batch = [...warmQueue.entries()].slice(0, WARM_CHUNK)
+        for (const [id] of batch) warmQueue.delete(id)
+        try {
+          const ids = batch.map(([id]) => id)
+          const snapshotById = await projectTitles(ids)
+          const decoded = new Map()
+          const statsById = new Map()
+          for (const [id, desc] of batch) {
+            const snapshot = snapshotById.has(id) ? snapshotById.get(id) : null
+            const meta = metaFromSnapshot(snapshot)
+            // cwd/createdAt 永远以最新 list header 为权威（投影的 session 头可能
+            // 陈旧；移动会话后尤其如此），投影只负责标题。
+            if (desc.header) {
+              if (typeof desc.header.cwd === 'string') meta.cwd = desc.header.cwd
+              if (desc.header.createdAt != null) meta.createdAt = desc.header.createdAt
+            }
+            metaCache.set(id, desc.stat, meta)
+            statsById.set(id, desc.stat)
+            if (desc.stat) decoded.set(id, meta)
+          }
+          await persistDecoded(decoded, statsById)
+        } catch (e) { /* 单批失败不影响后续批次：索引/缓存只是加速器 */ }
+        // 批间让步：保证宿主事件循环（RPC/心跳/其他插件）始终可调度。
+        await new Promise((resolve) => setImmediate(resolve))
+      }
+    } finally {
+      warmRunning = false
+      // 预热期间又有新请求入队 → 再排一轮。
+      if (warmQueue.size) scheduleWarm()
     }
-    metaCache.set(key, statInfo, meta)
-    // 本条是「真解码」出来的：交给调用方回写持久标题索引（P4 冷启动加速）。
-    if (opts.collectDecoded && statInfo) opts.collectDecoded(key, meta)
-    return buildItem(key, meta, usage, opts.exposeUsage)
   }
 
   // Disk usage + last-write time for every session, in one pass. Also produces
@@ -360,10 +393,13 @@ export function apply(ctx) {
         const id = entry && entry.id != null ? String(entry.id) : (header && header.id != null ? String(header.id) : null)
         if (!id) return
         // SessionHandle 世代：snapshot（header/revision/sizeBytes）是权威轻量
-        // 观察，绝不再绕道私有磁盘路径补 stat。
+        // 观察，绝不再绕道私有磁盘路径补 stat。revision 进内存缓存指纹；
+        // sizeBytes 供 persistFingerprintOf 派生跨重启的 sz 持久指纹（issue #8）。
         if (entry && typeof entry.revision === 'string' && entry.revision) {
           if (Number.isFinite(entry.sizeBytes)) sizeById.set(id, Number(entry.sizeBytes))
-          statsById.set(id, { revision: entry.revision })
+          statsById.set(id, Number.isFinite(entry.sizeBytes)
+            ? { revision: entry.revision, sizeBytes: Number(entry.sizeBytes) }
+            : { revision: entry.revision })
           return
         }
         if (entry && Number.isFinite(entry.sizeBytes)) sizeById.set(id, Number(entry.sizeBytes))
@@ -431,8 +467,14 @@ export function apply(ctx) {
   // when the session is really gone (purge, or externally removed; the latter
   // is caught by gcStars during list builds).
   const stars = createStarIndex()
+  // 待移动队列：会话被占用（DSH 打开中）时登记，等它释放后自动完成移动。
+  // 见 src/pending-moves.js 的模块注释（0.1.5 单写者锁没有公共释放 API）。
+  const pendingMoves = createPendingMoveStore()
   // Auto-archive settings live in their own schema-v4 store, off by default.
   const autoArchive = createAutoArchiveStore()
+  // 启动清扫：进程在「写临时文件 → rename」之间被杀会留下 .<name>-<pid>-<ts>.tmp
+  // 孤儿（实测一次累积 153 个）。这里把 1 小时前的旧临时文件收掉，不碰正在写的。
+  sweepStaleStateTemps([STATE_DIR, TRASH_DIR], {}).catch(() => {})
 
   async function gcStars(validIds) {
     try {
@@ -716,7 +758,11 @@ export function apply(ctx) {
       purged = true
     })
     if (!purged) throw new Error('彻底删除失败')
-    stars.removeIds([sid]).catch(() => {})
+    // 星标清理必须 await。原先这里是浮动写入（`stars.removeIds([sid]).catch(...)`）：
+    // 删除结果先返回、星标文件随后才落地，正好会撞上调用方（或测试 teardown）已开始的
+    // 状态目录清理 → `ENOTEMPTY: rmdir .../state`（全量测试里约 1/4 概率偶发失败）。
+    // 而且"删除成功"不该早于状态落盘：进程恰好在此刻退出就会留下指向已删会话的星标。
+    try { await stars.removeIds([sid]) } catch (e) { /* 星标清理失败不阻塞删除结果 */ }
     return { ok: true, purged: true }
   }
 
@@ -778,7 +824,10 @@ export function apply(ctx) {
     // crash-safe (backup + rollback) and re-syncs the live object.
     const activeId = getActiveSessionId(ctx)
     if (activeId != null && String(activeId) === String(sid)) {
-      throw new Error('该会话当前处于打开状态，请先切换到别的会话再移动。')
+      const error = new Error('会话正被 DSH 打开，暂时无法移动；请重启 DSH 后再试。')
+      error.status = 409
+      error.code = 'DSM_SESSION_BUSY'
+      throw error
     }
     const r = await persistence.readSession(sid, 0)
     if (!r || !r.meta) throw new Error('无法读取该会话的日志')
@@ -798,6 +847,10 @@ export function apply(ctx) {
 
     const newHeader = Object.assign({}, meta, { cwd: canonical })
 
+  // 移动过程的非致命提示（如源目录仍有旧代日志未能清理），随成功结果一并
+  // 回报给客户端展示。
+  const moveNotes = []
+
     // 1) Decide relocation strategy. `sessionPersistence.create()` rejects
     // ("already exists in this backend") for ANY session the host has
     // instantiated into its in-memory `states` — and DSH instantiates *every*
@@ -850,6 +903,8 @@ export function apply(ctx) {
         await rename(stagedPath, newPath)
         destinationInstalled = true
         await unlink(backupPath)
+        const keptInSource = await cleanupMovedSourceDir(dirname(oldPath))
+        if (keptInSource.length > 0) moveNotes.push(`源目录未能清理干净（残留 ${keptInSource.join('、')}），若后续移动报“duplicate”请手动清空该目录。`)
       } catch (e) {
         try { await unlink(stagedPath) } catch (_) {}
         if (destinationInstalled) { try { await unlink(newPath) } catch (_) {} }
@@ -873,6 +928,17 @@ export function apply(ctx) {
       return null
     }
 
+    // 移动成功后的源目录收尾（legacy 路径）：**整体移除**。目标侧已写入校验通过的
+    // 权威日志，源目录只要还留着任何一代日志（legacy 旧代 session.jsonl.zstd 或
+    // session.vN.jsonl.zstd），就会让同 id 出现在两个项目目录，后端 list/create
+    // 立刻报 duplicate。返回未能清理时的残留文件名（供如实回报）。
+    const cleanupMovedSourceDir = async (dir) => {
+      let entries = null
+      try { entries = await readdir(dir) } catch (e) { return [] }
+      try { await rm(dir, { recursive: true, force: true }) } catch (e) { return entries }
+      return []
+    }
+
     // Rewriting frame0's cwd now lives in src/zstd-frame.js so it can be
     // regression-tested directly. See that module for why frame boundaries are
     // validated by decompression and why a non-session frame0 is rejected
@@ -890,7 +956,13 @@ export function apply(ctx) {
         }
       }
       try {
-        await moveSessionToCwd({ sp, sid, header: meta, canonical, events, inheritedEventCount: r.inheritedEventCount })
+        const movedHandle = await moveSessionToCwd({ sp, sid, header: meta, canonical, events, inheritedEventCount: r.inheritedEventCount })
+        if (movedHandle && Array.isArray(movedHandle.reclaimedSiblings) && movedHandle.reclaimedSiblings.length > 0) {
+          moveNotes.push(`已顺带回收 ${movedHandle.reclaimedSiblings.length} 处被取代的旧代日志副本（历史移动残留），避免同一会话在多目录重复。`)
+        }
+        if (movedHandle && movedHandle.sourceCleanup && movedHandle.sourceCleanup.cleaned === false) {
+          moveNotes.push(`源目录未能清理干净（残留 ${movedHandle.sourceCleanup.leftover.join('、')}），若后续移动报“duplicate”请手动清空该目录。`)
+        }
       } catch (e) {
         if (e && e.status) throw e
         throw new Error('移动会话日志失败：' + String((e && e.message) || e))
@@ -937,6 +1009,10 @@ export function apply(ctx) {
             throw new Error('移动后校验失败：会话工作目录未正确更新')
           }
           if (backupPath) { try { await unlink(backupPath) } catch (e) {} }
+          if (oldPath) {
+            const keptInSource = await cleanupMovedSourceDir(dirname(oldPath))
+            if (keptInSource.length > 0) moveNotes.push(`源目录未能清理干净（残留 ${keptInSource.join('、')}），若后续移动报“duplicate”请手动清空该目录。`)
+          }
         } catch (e) {
           if (ALREADY_EXISTS_RE.test(String((e && e.message) || e))) {
             // Collision: the session is already materialized in states (archived
@@ -990,9 +1066,109 @@ export function apply(ctx) {
       workspaceId: target.id,
       workspaceTitle: target.title,
       workspacePath: canonical,
+      ...(moveNotes.length > 0 ? { notes: moveNotes } : {}),
     }
   }
 
+  // ---- 待移动队列（活跃 / 被占用的会话）-----------------------------------
+  // 0.1.5 的单写者锁由持有写句柄的进程掌控，插件既拿不到句柄也没有释放它的公共
+  // API；在占用期硬搬目录会让在写者继续写旧 inode 并在旧路径重建空壳。因此占用时
+  // 只登记排队，等宿主释放（session/disposed）或下次插件
+  // 启动时（会话尚未被打开）自动完成。
+  const QUEUE_NOTE = '已排队：该会话正被 DSH 打开（写所有权只在 DSH 退出时释放）。重启 DSH 时会自动完成，请先别打开它。'
+
+  function isBusyError(e) {
+    if (!e) return false
+    if (e.code === 'DSM_SESSION_BUSY') return true
+    const text = String((e && e.message) || e)
+    return /正被 DSH 打开|already owned/i.test(text)
+  }
+
+  // 移动入口：占用 → 排队；其它错误照旧抛出。返回成功结果或排队结果。
+  async function moveOrQueue(sid, targetPath) {
+    try {
+      return await moveOne(sid, targetPath)
+    } catch (e) {
+      if (!isBusyError(e)) throw e
+      await pendingMoves.queue(sid, targetPath)
+      return { ok: true, moved: false, queued: true, notes: [QUEUE_NOTE] }
+    }
+  }
+
+  // 启动后的「学步期」：这段时间内 moveOne 的非占用类失败只当环境未就绪，不计入
+  // 「多次失败即放弃」的计数（否则 boot 竞态会把用户的排队项白白丢掉）。
+  const BOOT_WARMUP_MS = 30000
+  const bootedAt = Date.now()
+
+  let queueRunning = false
+  async function runPendingMoves(reason) {
+    if (queueRunning) return { ran: false, moved: 0, kept: 0 }
+    queueRunning = true
+    let moved = 0
+    const notes = []
+    try {
+      const items = await pendingMoves.list()
+      for (const item of items) {
+        try {
+          await moveOne(item.sessionId, item.targetPath)
+          await pendingMoves.remove([item.sessionId])
+          metaCache.invalidate(item.sessionId)
+          moved++
+          notes.push(`排队中的移动已完成：${String(item.sessionId).slice(0, 18)}…`)
+        } catch (e) {
+          if (isBusyError(e)) continue // 仍被占用：留在队列里，等下一次触发
+          if (Date.now() - bootedAt < BOOT_WARMUP_MS) continue // boot 期未就绪：不记失败
+          const bumped = await pendingMoves.bumpAttempts(item.sessionId)
+          if (bumped && bumped.dropped) notes.push(`排队中的移动多次失败已放弃：${String(item.sessionId).slice(0, 18)}…（${String((e && e.message) || e)}）`)
+        }
+      }
+      if (moved > 0) { try { await reindexRegistry() } catch (e) { /* best-effort */ } }
+    } finally {
+      queueRunning = false
+    }
+    if (notes.length > 0) {
+      try { for (const n of notes) console.warn('[dsh-sessions-manager] ' + n) } catch (e) { /* ignore */ }
+    }
+    void reason
+    return { ran: true, moved, kept: (await pendingMoves.list()).length }
+  }
+
+  // 排队项的补跑时机。**关键前提**：0.1.5 的单写者所有权一经 open 就持有到**进程退出**
+  // 为止——官方没有任何「关闭会话 / 释放所有权」的公开入口（`dsh-commands` 只有
+  // compact/feedback/goal；宿主无 unloadSession/closeSession/evict），而浏览器一连上就会
+  // 自动打开/新建会话，一旦被打开就再也搬不动。所以唯一可靠窗口是**宿主刚起来、浏览器
+  // 还没连上**的那一两秒 ⇒ 启动后立刻试，并在前 30s 内密集重试；之后每 120s 兜底；
+  // 会话真被释放（session/disposed）时 500ms 后再试一次。
+  const queueEffect = typeof ctx.effect === 'function' ? ctx.effect.bind(ctx) : ((fn) => { fn() })
+  if (typeof ctx.on === 'function') {
+    queueEffect(() => ctx.on('session/disposed', (session) => {
+      const id = session && session.id != null ? String(session.id) : null
+      if (!id) return
+      pendingMoves.has(id).then((queued) => {
+        if (!queued) return
+        const t = setTimeout(() => { runPendingMoves('session-disposed').catch(() => {}) }, 500)
+        if (t && typeof t.unref === 'function') t.unref()
+      }).catch(() => {})
+    }))
+  }
+  queueEffect(() => {
+    // 每个启动补跑定时器都要 unref：宿主自己不会闲下来无所谓，但测试里未 unref 的
+    // 30s 定时器会让 node:test 多等 30s 才退出（整套测试被无谓拖长，实测见报告）。
+    const timers = [0, 1000, 3000, 6000, 12000, 30000].map((ms) => {
+      const t = setTimeout(() => {
+        runPendingMoves(ms === 0 ? 'startup' : `startup+${ms}`).catch(() => {})
+      }, ms)
+      if (t && typeof t.unref === 'function') t.unref()
+      return t
+    })
+    // 轻量周期重试：只在队列非空时干活（队列空 = 一次本地 JSON 读取）。
+    const tickTimer = setInterval(() => {
+      pendingMoves.list().then((items) => { if (items.length > 0) return runPendingMoves('tick') }).catch(() => {})
+    }, 120000)
+    if (tickTimer && typeof tickTimer.unref === 'function') tickTimer.unref()
+    return () => { for (const t of timers) clearTimeout(t); clearInterval(tickTimer) }
+  })
+
   // Force the host's WorkspaceRegistry to rebuild its in-memory sessionPath
   // index from the durable persistence headers. DSH's WorkspaceEntity.sessionIds
   // is a *getter* that filters record.sessionIds by `host.sessionPath(id) ===
@@ -1059,7 +1235,8 @@ export function apply(ctx) {
   //   1. sp.list() 只调一次（原先列了两遍目录）
   //   2. 变更令牌优先来自 list 快照：legacy 走 locate+stat，SessionHandle 世代
   //      直接用 snapshot.revision（无 locate 可用，也绝不绕私有路径补 stat）
-  //   3. 未命中缓存的会话走**一次**批量投影（sq.readTitleSnapshots），而不是逐条
+  //   3. 缓存未命中的会话**绝不在请求路径上同步投影**（issue #8：runtime 的
+  //      readTitleSnapshots 每条都是整本解码）——入队后台预热，先以占位元数据返回
   async function allSessionItemsDetailed(opts = {}) {
     let entries = []
     let headersOk = false
@@ -1089,37 +1266,59 @@ export function apply(ctx) {
     wsByPath = {}
     try { for (const ent of w.list()) wsByPath[ent.path] = ent } catch (e) { wsByPath = {} }
     const currentArchived = new Set((await archivedState().catch(() => ({ archivedSessionIds: [] }))).archivedSessionIds || [])
-    const items = []
     const usage = await collectUsage(entries)
-    // 先按指纹把「缓存命中」与「需要解码」分开，只对后者做批量投影。
+    // 先按指纹把「缓存命中」与「需要补齐」分开。
     const statsById = new Map(visibleIds.map((id) => [
       id,
       (usage.statsById && usage.statsById.get(id)) || { mtimeMs: usage.mtimeById.get(id), size: usage.sizeById.get(id) },
     ]))
-    const { missing } = metaCache.partition(visibleIds, statsById)
+    const { cached, missing } = metaCache.partition(visibleIds, statsById)
     // P4：missing 里先查持久标题索引（冷启动跳过整本解码），命中的回填内存缓存。
+    // cwd/createdAt 回填时以最新 list header 为权威——持久条目里的 cwd 可能因
+    // 移动会话而陈旧（sz 指纹对 cwd 无感知），标题才是索引的产出物。
     const persisted = await hydrateFromPersist(missing, statsById)
-    for (const [id, meta] of persisted) metaCache.set(id, statsById.get(id), meta)
+    for (const [id, meta] of persisted) {
+      const entry = entryById.get(id)
+      const header = entry && entry.header ? entry.header : null
+      metaCache.set(id, statsById.get(id), {
+        title: meta.title,
+        cwd: (header && typeof header.cwd === 'string' && header.cwd) ? header.cwd : meta.cwd,
+        createdAt: (header && header.createdAt != null) ? header.createdAt : meta.createdAt,
+      })
+    }
     const stillMissing = missing.filter((id) => !persisted.has(id))
-    const snapshotById = await projectTitles(stillMissing)
-    const decoded = new Map()
-    const collectDecoded = (id, meta) => { decoded.set(id, meta) }
-    const CHUNK = 6
-    for (let i = 0; i < visibleIds.length; i += CHUNK) {
-      // Arrow wrapper on purpose: Array#map passes (value, index, array), and
-      // resolveOne's second and third arguments are fixed here.
-      const res2 = await Promise.all(visibleIds.slice(i, i + CHUNK).map((id) => {
+    // issue #8：缺失部分交后台预热（分批 + 让步），请求路径零投影、零日志解码。
+    if (stillMissing.length) enqueueWarm(stillMissing, statsById, entryById)
+    const items = []
+    for (const id of visibleIds) {
+      // metaCache 优先：persisted 命中已带 header 权威 cwd/createdAt 回填进
+      // metaCache（persisted.get 里的 cwd 可能因移动会话而陈旧）。
+      // 完全未命中的会话也不能丢 cwd/createdAt——它们来自 list header，零成本
+      // 且是工作区归属/创建时间的权威来源；只有标题允许占位等后台预热（issue #8）。
+      let meta = metaCache.get(id, statsById.get(id)) || persisted.get(id) || null
+      if (!meta) {
+        meta = { title: null, cwd: null, createdAt: null }
         const entry = entryById.get(id)
-        return resolveOne(id, usage, {
-          exposeUsage: !!(opts && opts.usage),
-          listHeader: entry ? entry.header : null,
-          preloaded: snapshotById.has(id) ? snapshotById.get(id) : undefined,
-          collectDecoded,
-        })
-      }))
-      for (const it of res2) items.push({ ...it, archived: currentArchived.has(it.sessionId) })
+        const header = entry && entry.header ? entry.header : null
+        if (header) {
+          if (typeof header.cwd === 'string') meta.cwd = header.cwd
+          if (header.createdAt != null) meta.createdAt = header.createdAt
+        }
+      }
+      const it = buildItem(id, meta, usage, !!(opts && opts.usage))
+      items.push({ ...it, archived: currentArchived.has(it.sessionId) })
+    }
+    if (opts && opts.onlyArchived) {
+      // /archived-sessions/list 的语义：只返回归档集里仍然存在的会话，
+      // 且不带 archived 布尔注记（旧路由的输出形状）。
+      const archivedItems = []
+      for (const it of items) {
+        if (!it.archived) continue
+        const { archived: _drop, ...rest } = it
+        archivedItems.push(rest)
+      }
+      return { items: archivedItems, usage }
     }
-    persistDecoded(decoded, statsById)
     // Annotate stars; GC only when we have a trustworthy id baseline, so a
     // failing sp.list() can never wipe the whole index.
     let starredSet = new Set()
@@ -1207,6 +1406,7 @@ export function apply(ctx) {
     const activeTombstones = store.purgedSessionIds.map(String).filter((id) => !present.has(id))
     if (ids.length) {
       const usage = await collectUsage(entries)
+      const entryById = new Map(entries.map((entry) => [entry.id, entry]))
       const statsById = new Map(ids.map((id) => [
         id,
         (usage.statsById && usage.statsById.get(id)) || { mtimeMs: usage.mtimeById.get(id), size: usage.sizeById.get(id) },
@@ -1214,35 +1414,91 @@ export function apply(ctx) {
       const { cached, missing } = metaCache.partition(ids, statsById)
       // P4：与列表构建共用持久标题索引，冷启动零解码。
       const persisted = await hydrateFromPersist(missing, statsById)
-      for (const [id, meta] of persisted) metaCache.set(id, statsById.get(id), meta)
+      for (const [id, meta] of persisted) {
+        const entry = entryById.get(id)
+        const header = entry && entry.header ? entry.header : null
+        metaCache.set(id, statsById.get(id), {
+          title: meta.title,
+          cwd: (header && typeof header.cwd === 'string' && header.cwd) ? header.cwd : meta.cwd,
+          createdAt: (header && header.createdAt != null) ? header.createdAt : meta.createdAt,
+        })
+      }
       const rest = missing.filter((id) => !persisted.has(id))
-      const snapshotById = await projectTitles(rest)
-      const decoded = new Map()
-      const collectDecoded = (id, meta) => { decoded.set(id, meta) }
+      // issue #8：缺失标题不在请求路径上同步投影（runtime 投影 = 逐条整本解码），
+      // 交后台预热补齐；侧栏高频轮询会让补齐结果自然浮现。
+      if (rest.length) enqueueWarm(rest, statsById, entryById)
       for (const id of ids) {
-        let meta = cached.get(id) || persisted.get(id) || null
-        if (!meta) {
-          const entry = entries.find((e) => e.id === id)
-          const snapshot = snapshotById.has(id)
-            ? snapshotById.get(id)
-            : (typeof sq.readTitleSnapshot === 'function' ? await sq.readTitleSnapshot(id).catch(() => null) : null)
-          const next = metaFromSnapshot(snapshot)
-          if (entry && entry.header) {
-            if (!next.cwd && typeof entry.header.cwd === 'string') next.cwd = entry.header.cwd
-            if (!next.createdAt && entry.header.createdAt != null) next.createdAt = entry.header.createdAt
-          }
-          metaCache.set(id, statsById.get(id), next)
-          if (statsById.get(id)) collectDecoded(id, next)
-          meta = next
-        }
+        const meta = metaCache.get(id, statsById.get(id)) || persisted.get(id) || null
         if (meta && meta.title) authorityTitleCache.set(id, String(meta.title))
       }
-      persistDecoded(decoded, statsById)
     }
+    // 血缘分类（issue #6）：结构分类（子代理 / fork 分支）来自 list snapshot
+    // 的 header，零解码；空白判定见下方 refineEmptyLineage（0.1.3 起体积法
+    // 失效，改为事件类型精判）。普通顶层非空会话不产生条目，payload 最小。
+    const lineage = {}
+    for (const entry of entries) {
+      const info = classifyLineage(entry.header, entry.sizeBytes)
+      if (info) lineage[entry.id] = info
+    }
+    await refineEmptyLineage(lineage, entries)
     return {
       titles: Object.fromEntries(authorityTitleCache),
       trashedSessionIds: store.items.map((item) => String(item.sessionId)),
       purgedSessionIds: activeTombstones,
+      lineage,
+    }
+  }
+
+  // 空会话判定缓存：id → { sizeBytes, empty }。日志没变（sizeBytes 相同）
+  // 就不重复解码——authority 会被侧栏高频轮询，缓存让它保持在近零成本。
+  const emptyScanCache = new Map()
+
+  // 0.1.3 空会话精判（事件类型法，见 lineage.js）：体积阈值对新格式失效
+  // （头部扩容 + 恒存生命周期帧），改为对「压缩体积 ≤ EMPTY_DECODE_LIMIT」
+  // 的候选走官方 inspectSession 解码，按事件类型判定。超过上限的日志必有
+  // 内容，直接跳过（维持体积法/结构分类的结果）。解码失败按「非空」处理：
+  // 宁可漏判一个空会话，不能把有内容的会话错标成空。
+  async function refineEmptyLineage(lineage, entries) {
+    if (!persistence || typeof persistence.inspectSession !== 'function') return
+    for (const entry of entries) {
+      const size = entry && Number.isFinite(entry.sizeBytes) ? entry.sizeBytes : null
+      if (size === null || size > EMPTY_DECODE_LIMIT) continue
+      const id = String(entry.id)
+      let scanned = emptyScanCache.get(id)
+      if (!scanned || scanned.sizeBytes !== size) {
+        let isEmpty = false
+        try {
+          const types = []
+          await persistence.inspectSession(id, { onEvents: (batch) => {
+            for (const ev of batch || []) if (types.length < 64) types.push(ev && ev.type)
+          } })
+          isEmpty = isEmptyEventTypes(types)
+        } catch (e) { isEmpty = false }
+        scanned = { sizeBytes: size, empty: isEmpty }
+        emptyScanCache.set(id, scanned)
+      }
+      if (scanned.empty) {
+        // 结构分类没建条目的普通会话也要补上（0.1.3 空会话 header 无血缘字段，
+        // classifyLineage 对它们返回 null）。
+        const info = lineage[id] || (lineage[id] = { origin: null, parentSession: null, delegationDepth: 0, empty: false })
+        info.empty = true
+      } else if (lineage[id]) {
+        // 旧体积法在小日志上的假阳性（如 alpha.2 单事件日志）在这里纠正；
+        // 纠正后若无任何血缘结构，条目整个撤掉，维持「普通会话不产生条目」。
+        const info = lineage[id]
+        info.empty = false
+        if (!info.origin && !info.parentSession) delete lineage[id]
+      }
+    }
+    // 缓存只保留「本轮仍参与判定」的会话：已彻底删除或日志膨胀超过解码
+    // 上限的条目不再有用，淘汰掉防止 Map 随历史会话无限增长。
+    const live = new Set()
+    for (const entry of entries) {
+      const size = entry && Number.isFinite(entry.sizeBytes) ? entry.sizeBytes : null
+      if (size !== null && size <= EMPTY_DECODE_LIMIT) live.add(String(entry.id))
+    }
+    for (const key of emptyScanCache.keys()) {
+      if (!live.has(key)) emptyScanCache.delete(key)
     }
   }
 
@@ -1393,7 +1649,7 @@ export function apply(ctx) {
     disposers.push(ctx.webServer.register({
       kind: 'exact',
       path: '/archived-sessions/capabilities',
-      handler: async (req, res) => json(res, capabilities),
+      handler: async (req, res) => json(res, { ...capabilities, buildStamp: BUILD_STAMP }),
     }))
 
     disposers.push(ctx.webServer.register({
@@ -1423,12 +1679,13 @@ export function apply(ctx) {
           const idStrs = ids.map(String).filter((id) => !hidden.has(id) && (materialized.has(id) || (live && live.get(id))))
           wsByPath = {}
           try { for (const ent of w.list()) wsByPath[ent.path] = ent } catch (e) { wsByPath = {} }
-          const items = []
-          const CHUNK = 6
-          for (let i = 0; i < idStrs.length; i += CHUNK) {
-            const res2 = await Promise.all(idStrs.slice(i, i + CHUNK).map((id) => resolveOne(id)))
-            items.push.apply(items, res2)
-          }
+          // issue #8：归档列表也复用「缓存直读 + 后台预热」的统一管线。
+          // 旧实现逐条 resolveOne(id)（无 header、无指纹）——冷启动对每条归档
+          // 会话整本解码，且连进程内缓存都永远命中不了。
+          const wanted = new Set(idStrs)
+          const detailed = await allSessionItemsDetailed()
+          const items = detailed.items.filter((it) => wanted.has(String(it.sessionId)) && it.archived)
+          for (const it of items) delete it.archived
           json(res, { items })
         } catch (e) {
           json(res, { error: String((e && e.message) || e) }, 500)
@@ -1597,7 +1854,7 @@ export function apply(ctx) {
           const out = await purgeFromTrash(sid)
           metaCache.invalidate(sid)
           // 彻底删除：持久标题索引里的条目一并清掉（issue #1 P4）。
-          titleIndex.remove([sid]).catch(() => {})
+          try { await titleIndex.remove([sid]) } catch (e) { /* 索引清理失败不阻塞删除结果 */ }
           json(res, out)
         } catch (e) {
           json(res, { ok: false, code: e && e.code, error: String((e && e.message) || e) }, errorStatus(e))
@@ -1615,7 +1872,7 @@ export function apply(ctx) {
           if (!ids || ids.length === 0) return json(res, { ok: false, error: 'missing sessionIds' }, 400)
           const results = []
           for (const sid of ids) {
-            try { results.push({ sessionId: sid, ok: true, ...(await purgeFromTrash(sid)) }); metaCache.invalidate(sid); titleIndex.remove([sid]).catch(() => {}) }
+            try { results.push({ sessionId: sid, ok: true, ...(await purgeFromTrash(sid)) }); metaCache.invalidate(sid); await titleIndex.remove([sid]).catch(() => {}) }
             catch (e) { results.push({ sessionId: sid, ok: false, error: String((e && e.message) || e) }) }
           }
           json(res, { ok: true, purged: results.filter((r) => r.ok).length, results })
@@ -1715,6 +1972,110 @@ export function apply(ctx) {
       },
     }))
 
+    // 子代理血缘树（管理视图数据面）：给定父会话，返回 origin==='subagent'
+    // 的递归子树。DSH 原生目录（ui-subagent）只读，这里补管理能力的数据来源。
+    // 只读官方 header 血缘字段（parentSession/origin/delegationDepth/createdAt），
+    // 标题走既有批量投影（readTitleSnapshots），零整本日志解码。
+    // live 标记 = 会话在内存里活着（正在运行或已打开）：批量清理必须跳过。
+    disposers.push(ctx.webServer.register({
+      kind: 'exact',
+      path: '/archived-sessions/lineage-tree',
+      handler: async (req, res) => {
+        try {
+          const body = await readJsonBody(req)
+          const rootId = body && typeof body.sessionId === 'string' ? body.sessionId : ''
+          if (!rootId || !isSafeSessionId(rootId)) return json(res, { error: 'missing sessionId' }, 400)
+          const headerById = new Map()
+          const sizeById = new Map()
+          // 与会话列表同源的可见性判定：回收站项目一律不参与血缘树。
+          const trashedIds = new Set()
+          let purgedIds = []
+          const persistedIds = new Set()
+          try {
+            const store = await readTrashStore()
+            for (const item of store.items) trashedIds.add(String(item.sessionId))
+            purgedIds = store.purgedSessionIds.map(String)
+          } catch (e) { /* best-effort */ }
+          const addHeader = (h, sizeBytes) => {
+            if (!h || h.id == null) return
+            const id = String(h.id)
+            // 回收站里的会话（软删除后日志已搬走）不能出现在血缘树里，否则
+            // 会出现「删掉了侧栏还在」。彻底删除的墓碑在下面按「当前已不存在」
+            // 统一剔除，避免压住后来同 id 重建的会话。
+            if (headerById.has(id) || trashedIds.has(id)) return
+            headerById.set(id, {
+              parentSession: h.parentSession != null ? String(h.parentSession) : null,
+              subagent: h.origin === 'subagent',
+              delegationDepth: Number.isFinite(h.delegationDepth) ? h.delegationDepth : null,
+              createdAt: typeof h.createdAt === 'number' ? h.createdAt : null,
+            })
+            if (Number.isFinite(sizeBytes)) sizeById.set(id, sizeBytes)
+          }
+          try {
+            for (const entry of await persistence.listEntries()) {
+              addHeader(entry.header, entry.sizeBytes)
+              if (entry && entry.id != null) persistedIds.add(String(entry.id))
+            }
+          } catch (e) { /* best-effort */ }
+          const liveIds = new Set()
+          const live = ctx.get('sessions')
+          try {
+            if (live && typeof live.list === 'function') {
+              live.list().forEach((s) => { liveIds.add(String(s.id)); addHeader(s.header, undefined) })
+            }
+          } catch (e) { /* best-effort */ }
+          // 墓碑只对「持久层里确实没了」的 id 生效：同 id 会话后来重新出现时
+          // 必须让位，不能永久压住新会话（与会话列表同一套规则）。
+          for (const id of purgedIds) {
+            if (!persistedIds.has(id)) headerById.delete(id)
+          }
+          // 子代理索引：parentSession → 直接子代理 id 列表（只收 origin==='subagent'）。
+          const kidsOf = new Map()
+          for (const [id, h] of headerById) {
+            if (!h.subagent || !h.parentSession) continue
+            if (!kidsOf.has(h.parentSession)) kidsOf.set(h.parentSession, [])
+            kidsOf.get(h.parentSession).push(id)
+          }
+          // 递归展开：visited 防环，节点总数封顶防病态数据。
+          const MAX_NODES = 500
+          let nodeCount = 0
+          const build = (id, depth, visited) => {
+            nodeCount++
+            const h = headerById.get(id) || {}
+            const childVisited = new Set(visited)
+            childVisited.add(id)
+            const kidIds = nodeCount >= MAX_NODES ? [] : (kidsOf.get(id) || []).filter((k) => !childVisited.has(k))
+            return {
+              sessionId: id,
+              parentSession: h.parentSession || null,
+              delegationDepth: h.delegationDepth,
+              depth,
+              createdAt: h.createdAt || null,
+              sizeBytes: sizeById.has(id) ? sizeById.get(id) : null,
+              live: liveIds.has(id),
+              title: null,
+              children: kidIds.map((k) => build(k, depth + 1, childVisited)),
+            }
+          }
+          const nodes = (kidsOf.get(rootId) || []).map((k) => build(k, 1, new Set([rootId])))
+          const allIds = [rootId]
+          const walk = (n) => { allIds.push(n.sessionId); n.children.forEach(walk) }
+          nodes.forEach(walk)
+          const titles = await projectTitles(allIds)
+          const titleOf = (id) => {
+            const snap = titles.get(id)
+            const m = snap ? metaFromSnapshot(snap) : null
+            return (m && m.title) || null
+          }
+          const fill = (n) => { n.title = titleOf(n.sessionId); n.children.forEach(fill) }
+          nodes.forEach(fill)
+          json(res, { parent: { sessionId: rootId, title: titleOf(rootId) }, nodes })
+        } catch (e) {
+          json(res, { error: String((e && e.message) || e) }, errorStatus(e))
+        }
+      },
+    }))
+
     // Available target workspaces (for the move picker).
     disposers.push(ctx.webServer.register({
       kind: 'exact',
@@ -1739,7 +2100,8 @@ export function apply(ctx) {
           const target = body && typeof body.targetPath === 'string' ? body.targetPath : null
           if (!sid) return json(res, { ok: false, error: 'missing sessionId' }, 400)
           if (!target) return json(res, { ok: false, error: 'missing targetPath' }, 400)
-          const moved = await moveOne(sid, target)
+          const moved = await moveOrQueue(sid, target)
+          if (moved.queued) return json(res, { sessionId: sid, ...moved })
           // 移动会改写日志 frame0 的 cwd：元数据（cwd）已变，主动丢弃缓存条目，
           // 不等 mtime 指纹自然失效（Windows 上 mtime 精度较粗，指纹可能不变）。
           metaCache.invalidate(sid)
@@ -1756,6 +2118,77 @@ export function apply(ctx) {
       },
     }))
 
+    // Move many conversations to one target workspace (issue #7). Sequential
+    // on purpose: each move rewrites frame0 (file IO), and one bad session
+    // must not block the rest. Single reindex at the end covers all moves.
+    disposers.push(ctx.webServer.register({
+      kind: 'exact',
+      path: '/archived-sessions/move-many',
+      handler: async (req, res) => {
+        try {
+          const body = await readJsonBody(req)
+          const ids = Array.isArray(body && body.sessionIds)
+            ? [...new Set(body.sessionIds.filter((x) => typeof x === 'string' && x))]
+            : []
+          const target = body && typeof body.targetPath === 'string' ? body.targetPath : null
+          if (!ids.length) return json(res, { ok: false, error: 'missing sessionIds' }, 400)
+          if (!target) return json(res, { ok: false, error: 'missing targetPath' }, 400)
+          let moved = 0
+          const failed = []
+          const queued = []
+          for (const sid of ids) {
+            try {
+              const r = await moveOrQueue(sid, target)
+              if (r && r.queued) { queued.push(sid); continue }
+              // frame0 的 cwd 被改写：与单移动同理由，主动丢缓存不等指纹失效。
+              metaCache.invalidate(sid)
+              moved++
+            } catch (e) {
+              const err = e && e.code ? { sessionId: sid, error: String((e && e.message) || e), code: e.code } : { sessionId: sid, error: String((e && e.message) || e) }
+              failed.push(err)
+            }
+          }
+          try { await reindexRegistry() } catch (e) { /* best-effort */ }
+          json(res, {
+            moved,
+            failed,
+            ...(queued.length > 0 ? { queued, notes: [`${queued.length} 个会话已排队（正被 DSH 打开），重启 DSH 后会自动完成；重启后请先别打开它们。`] } : {}),
+          })
+        } catch (e) {
+          json(res, { ok: false, code: e && e.code, error: String((e && e.message) || e) }, errorStatus(e))
+        }
+      },
+    }))
+
+    // 待移动队列：查看 / 取消（会话被占用时排队，释放后自动完成）。
+    disposers.push(ctx.webServer.register({
+      kind: 'exact',
+      path: '/archived-sessions/pending-moves',
+      handler: async (req, res) => {
+        try {
+          const items = await pendingMoves.list()
+          json(res, { items: items.map((i) => ({ sessionId: i.sessionId, targetPath: i.targetPath, queuedAt: i.queuedAt, attempts: i.attempts })) })
+        } catch (e) {
+          json(res, { error: String((e && e.message) || e) }, 500)
+        }
+      },
+    }))
+    disposers.push(ctx.webServer.register({
+      kind: 'exact',
+      path: '/archived-sessions/pending-moves/cancel',
+      handler: async (req, res) => {
+        try {
+          const body = await readJsonBody(req)
+          const ids = parseIds(body)
+          if (!ids || ids.length === 0) return json(res, { ok: false, error: 'missing sessionIds' }, 400)
+          const removed = await pendingMoves.remove(ids)
+          json(res, { ok: true, removed })
+        } catch (e) {
+          json(res, { ok: false, error: String((e && e.message) || e) }, errorStatus(e))
+        }
+      },
+    }))
+
     // Archive (hide) one session.
     disposers.push(ctx.webServer.register({
       kind: 'exact',