dsh-sessions-manager 3.6.0 → 3.6.2

package/src/index.js

@@ -18,7 +18,7 @@ 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, fingerprintOf, 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'
@@ -135,20 +135,8 @@ function getActiveSessionId(context) {
   return null
 }
 
-function foldTitle(events) {
-  let found = null
-  let firstUser = null
-  for (const ev of events) {
-    if (ev.type === 'session/title' && ev.data && typeof ev.data.title === 'string' && ev.data.title.length) {
-      found = ev.data.title
-    }
-    if (firstUser === null && ev.type === 'user/message' && ev.data && Array.isArray(ev.data.content)) {
-      const txt = ev.data.content.filter((b) => b && b.type === 'text').map((b) => b.text).filter(Boolean).join(' ').trim()
-      if (txt) firstUser = txt
-    }
-  }
-  return found || firstUser || null
-}
+// foldTitle（v3.6.1 删除路径的兜底折叠）随 v3.6.2 #7 的「删除路径零解码」一并
+// 移除；标题折叠逻辑的权威实现现在是 runtime 投影（src/index.js projectTitlesStatus）。
 
 export function apply(ctx) {
   const w = ctx.workspaceRegistry
@@ -179,9 +167,15 @@ 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
-      if (fp && entry.fingerprint === fp) {
+      // 持久索引只认可跨重启的指纹（legacy 的文件指纹 / handle 世代的 sz 指纹，
+      // 见 session-meta-cache.persistFingerprintOf——issue #8 之前 handle 世代
+      // 从不落盘，导致每次重启都全量重新解码）。
+      const fp = persistFingerprintOf(stat)
+      if (!fp) continue
+      // v3.6.2 #1：title 为 null 的条目必须是「投影确实成功过」（resolved）才可信。
+      // v3.6.1 把投影失败当结果落盘的污染条目（null 标题、无标记）在这里被丢弃，
+      // 调用方按未命中处理 → 重新入队预热，索引自愈。
+      if (entry.fingerprint === fp && (entry.title || entry.resolved)) {
         hits.set(id, { title: entry.title, cwd: entry.cwd, createdAt: entry.createdAt })
       }
     }
@@ -192,16 +186,20 @@ export function apply(ctx) {
   // 队列内部已串行化 + 原子替换）。**必须 await** —— 它是持久写入，浮动写入会在
   // 调用方/测试 teardown 已开始清理状态目录时落地（`ENOTEMPTY: rmdir .../state`），
   // 且"响应已返回但索引没落盘"时进程若恰好退出就会丢条目。
-  // ⚠️ revision 指纹（SessionHandle 世代）绝不落盘：它只在当前 service
-  // 实例内有意义，跨进程比较无意义，误用会把陈旧数据当新鲜数据。
+  // 指纹用 persistFingerprintOf：legacy 文件指纹 + handle 世代 sz(sizeBytes) 指纹
+  // 都可跨重启；rev: 指纹仍被排除（实例内 opaque token，issue #8）。
+  // v3.6.2 #1：decoded 的值是 { meta, resolved } —— resolved=false（投影失败）
+  // 的条目绝不落盘；null 标题只有 resolved=true 才允许（否则读取端会当污染丢弃）。
   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
-      batch[id] = { title: meta.title, cwd: meta.cwd, createdAt: meta.createdAt, fingerprint: fp, updatedAt: now }
+    for (const [id, pack] of decoded) {
+      if (!pack || !pack.resolved) continue
+      const meta = pack.meta
+      const fp = persistFingerprintOf(statsById.get(id))
+      if (!fp) continue
+      batch[id] = { title: meta.title, cwd: meta.cwd, createdAt: meta.createdAt, fingerprint: fp, updatedAt: now, resolved: 1 }
     }
     if (!Object.keys(batch).length) return
     try { await titleIndex.merge(batch) } catch (e) { /* 索引写失败不影响本次响应 */ }
@@ -284,65 +282,193 @@ 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
+  // 因此请求路径只消费两级缓存（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
+
+  // v3.6.2 #1：投影失败的三态处理（issue #8 审计）。旧实现把「投影失败」和
+  // 「会话真没标题」混为同一个 null → 失败被写进缓存/持久索引，跨重启固化成
+  // 永久占位且永不重试。现在：
+  //   - resolved（fulfilled，title 可以是 null = 事实无标题）→ 正常入缓存+落盘；
+  //   - failed（rejected / 批量异常 / 结果缺条）→ 不缓存、不落盘，按 id 计数退避。
+  // 退避：15s×2^n 递增，最多 WARM_MAX_ATTEMPTS 次；此后 parked 一小时后再探一次
+  // （坏日志长期停摆时不至于永久静默）。日志指纹任何变化都清零计数重新武装。
+  const WARM_MAX_ATTEMPTS = 5
+  const warmFail = new Map() // id → { count, fp, nextAt }
+
+  function warmFpOf(stat) {
+    return fingerprintOf(stat) || persistFingerprintOf(stat)
+  }
+
+  function warmBlocked(id, fp) {
+    const rec = warmFail.get(id)
+    if (!rec) return 0
+    if (fp && rec.fp && rec.fp !== fp) { warmFail.delete(id); return 0 } // 内容变了 → 重新武装
+    const now = Date.now()
+    return rec.nextAt > now ? rec.nextAt - now : 0
+  }
+
+  function warmMarkFailure(id, stat, header) {
+    const rec = warmFail.get(id) || { count: 0, fp: null, nextAt: 0 }
+    rec.count += 1
+    rec.fp = warmFpOf(stat) || rec.fp
+    // 退避到点后由 scheduleWarmRetry 原样重新入队（含本轮的 stat/header 快照）。
+    if (stat) rec.stat = stat
+    if (header) rec.header = header
+    const backoff = rec.count >= WARM_MAX_ATTEMPTS
+      ? 60 * 60 * 1000
+      : Math.min(5 * 60 * 1000, 15 * 1000 * Math.pow(2, rec.count))
+    rec.nextAt = Date.now() + backoff
+    warmFail.set(id, rec)
+  }
+
+  // 队列里还有「未放弃」的活 → 侧栏/面板应缩短轮询节拍（client 消费）。
+  function warmPendingNow() {
+    if (!warmHasApi) return false
+    if (warmRunning || warmQueue.size) return true
+    for (const rec of warmFail.values()) if (rec.nextAt > Date.now()) return true
+    return false
+  }
+
+  // 退避到点的条目由一个 unref 定时器重新入队（每轮只挂最近的一个）。
+  let warmRetryTimer = null
+  function scheduleWarmRetry() {
+    if (warmRetryTimer) return
+    let soonest = 0
+    for (const rec of warmFail.values()) {
+      const wait = rec.nextAt - Date.now()
+      if (wait <= 0) { soonest = 1; break }
+      if (!soonest || wait < soonest) soonest = wait
     }
-    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 */ }
+    if (!soonest) return
+    warmRetryTimer = setTimeout(() => {
+      warmRetryTimer = null
+      // 到点的条目重新入队（enqueue 时会重新校验 blocked/fp）。
+      const now = Date.now()
+      for (const [id, rec] of warmFail) {
+        if (rec.nextAt <= now && !warmQueue.has(id)) warmQueue.set(id, { stat: rec.stat || null, header: rec.header || null })
+      }
+      if (warmQueue.size) scheduleWarm()
+    }, soonest)
+    if (typeof warmRetryTimer.unref === 'function') warmRetryTimer.unref()
+  }
+
+  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
+    // 无投影 API 的 runtime：预热注定无果，不入队（占位行为退回「列表不带标题」
+    // 的诚实形态，而不是让退避定时器永远转下去）。
+    if (!warmHasApi) return
+    for (const id of ids) {
+      const key = String(id)
+      const stat = statsById ? (statsById.get(key) || null) : null
+      // #9：任何指纹都算不出来的会话（live 未落盘等）既进不了内存缓存也进不了
+      // 持久索引——投影结果注定无处安放，每轮轮询重复入队只是白烧 CPU（churn）。
+      // 跳过；这类行的标题由 DSH 自己的 live 渲染保证。
+      const fp = warmFpOf(stat)
+      if (!fp) continue
+      // #1：仍在失败退避窗口内的条目不重复入队（runWarm 会按 blocked 跳过）。
+      const blockedMs = warmBlocked(key, fp)
+      const entry = entryById ? entryById.get(key) : null
+      const rec = warmFail.get(key)
+      if (rec) { rec.stat = stat || rec.stat; if (entry) rec.header = entry.header || rec.header }
+      if (blockedMs > 0) continue
+      warmQueue.set(key, {
+        stat,
+        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 (warmQueue.size) scheduleWarm()
+    scheduleWarmRetry()
+  }
+
+  // #7：软删除时标题可能还没预热出来（回收站条目落一条 title:null 的诚实记录），
+  // 之后任何一轮 warm 解出该会话标题就补写进回收站索引——只补空标题，
+  // 绝不覆盖已有值。回收站渲染端（t.title || t.sessionId）随下次拉取自然更新。
+  async function backfillTrashTitles(decoded) {
+    if (!decoded || !decoded.size) return
+    try {
+      const items = await readTrash()
+      const worth = items.some((t) => !t.title && decoded.get(String(t.sessionId)) && decoded.get(String(t.sessionId)).meta && decoded.get(String(t.sessionId)).meta.title)
+      if (!worth) return
+      await mutateTrash((store) => {
+        for (const item of store.items) {
+          if (item.title) continue
+          const pack = decoded.get(String(item.sessionId))
+          const t = pack && pack.meta && pack.meta.title
+          if (t) item.title = String(t)
         }
-        if (!meta.title && foldedTitle) meta.title = foldedTitle
-      } catch (e2) { /* keep what we have */ }
+      })
+    } catch (e) { /* 补写失败无害：索引只是加速器 */ }
+  }
+
+  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 resultById = await projectTitlesStatus(ids)
+          const decoded = new Map()
+          const statsById = new Map()
+          for (const [id, desc] of batch) {
+            const r = resultById.get(id)
+            if (!r || !r.resolved) {
+              // 投影失败：绝不写缓存/持久索引（否则失败被固化为永久占位）。
+              warmMarkFailure(id, desc.stat, desc.header)
+              continue
+            }
+            warmFail.delete(id)
+            const meta = metaFromSnapshot(r.snapshot || null)
+            // 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)
+            decoded.set(id, { meta, resolved: true })
+          }
+          await persistDecoded(decoded, statsById)
+          // #7：回收站条目删除时可能没有标题（软删除只记录）；预热解出来后补写。
+          await backfillTrashTitles(decoded)
+        } catch (e) { /* 单批失败不影响后续批次：索引/缓存只是加速器 */ }
+        // 批间让步：保证宿主事件循环（RPC/心跳/其他插件）始终可调度。
+        await new Promise((resolve) => setImmediate(resolve))
+      }
+    } finally {
+      warmRunning = false
+      // 预热期间又有新请求入队 → 再排一轮。
+      if (warmQueue.size) scheduleWarm()
+      scheduleWarmRetry()
     }
-    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
@@ -373,10 +499,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))
@@ -491,25 +620,21 @@ export function apply(ctx) {
         title = header.title || (header.meta && header.meta.title) || null
       }
       if (!title) {
-        // 标题兜底优先走单会话标题投影（快照级，不读日志）；投影也没有时才
-        // 分块解码日志折叠标题（inspectSession 分块，不整本驻留内存）。
-        if (typeof sq.readTitleSnapshot === 'function') {
-          try {
-            const snap = unwrapSnapshot(await sq.readTitleSnapshot(sid))
-            if (snap && snap.title && snap.title.title) title = String(snap.title.title)
-            if (snap && snap.session) { if (!cwd) cwd = snap.session.cwd || null }
-          } catch (e) { /* fall through */ }
-        }
-      }
-      if (!title) {
+        // v3.6.2 #7：删除路径**绝不**做标题投影/分块解码——issue #8 的教训：
+        // 大日志上单条兜底投影也是整本解压，删除 = 秒级卡宿主。只消费现成缓存：
+        // metaCache（用 list 快照算指纹）→ 持久索引 → 侧栏权威缓存。都没有就存
+        // null（诚实占位，不再把 cwd/裸 id 冒充标题永久写进回收站），
+        // 后台预热解出标题后由 backfillTrashTitles 补写。
         try {
-          let folded = null
-          const summary = await persistence.inspectSession(sid, {
-            onEvents: (events) => { if (!folded) folded = foldTitle(events) },
-          })
-          if (summary && summary.meta && !cwd) cwd = summary.meta.cwd || null
-          title = folded
+          const delStat = persistenceEntry && typeof persistenceEntry.revision === 'string' && persistenceEntry.revision
+            ? { revision: persistenceEntry.revision, sizeBytes: Number.isFinite(persistenceEntry.sizeBytes) ? Number(persistenceEntry.sizeBytes) : undefined }
+            : (removedPath ? await stat(removedPath).then((st) => ({ mtimeMs: st.mtimeMs, size: st.size })) : null)
+          if (delStat) {
+            const m = metaCache.get(sid, delStat) || (await hydrateFromPersist([sid], new Map([[sid, delStat]]))).get(sid)
+            if (m && m.title) title = String(m.title)
+          }
         } catch (e) { /* best-effort */ }
+        if (!title) { const at = authorityTitleCache.get(sid); if (at) title = String(at) }
       }
     } catch (e) { /* best-effort */ }
     // Record in the trash index only — the log stays in its workspace dir.
@@ -521,7 +646,9 @@ export function apply(ctx) {
     const archived = await mutateArchived((list) => ({ next: null, value: list.includes(sid) })).catch(() => false)
     await mutateTrash((store) => {
       const entry = {
-        sessionId: sid, title: title || cwd || sid, cwd: cwd || null,
+        // v3.6.2 #7：不再把 cwd/裸 id 冒充标题永久定格——存 null，预热解出后
+        // backfillTrashTitles 补写；渲染端（t.title || t.sessionId）自然降级。
+        sessionId: sid, title: title || null, cwd: cwd || null,
         header: header || null, originalPath: removedPath || null,
         sizeBytes: persistenceEntry && Number.isFinite(persistenceEntry.sizeBytes) ? persistenceEntry.sizeBytes : null,
         wasArchived: archived, deletedAt: Date.now(),
@@ -1187,24 +1314,53 @@ export function apply(ctx) {
     })
   }
 
-  // 批量投影：一次调用把多条会话的标题/header 拿出来，避免逐条触发整本解码。
-  // 老 runtime 没有 readTitleSnapshots 时返回空 Map，调用方自然回退到逐条投影
-  // （功能不受影响，只是少了这层优化——插件不能假设对方的 runtime 版本）。
-  async function projectTitles(ids) {
+  // 批量投影（v3.6.2 #1 三态版）。返回 Map<id, { resolved, snapshot|null }>：
+  //   resolved=true  —— fulfilled 快照（title 可能为 null：会话真的没标题，
+  //                     这是事实，可以缓存/落盘）；
+  //   resolved=false —— rejected / 批量异常 / 结果缺条 / 无投影 API。
+  // 调用方（runWarm）只缓存 resolved 的条目；失败的进退避重试，绝不落盘——
+  // 否则「一次失败」被固化为跨重启的永久占位（v3.6.1 审计 #1）。
+  const warmHasApi = typeof sq.readTitleSnapshots === 'function' || typeof sq.readTitleSnapshot === 'function'
+
+  async function projectTitlesStatus(ids) {
     const out = new Map()
+    const markAll = (resolved) => { for (const id of ids) out.set(String(id), { resolved, snapshot: null }) }
     if (!ids || !ids.length) return out
-    if (typeof sq.readTitleSnapshots !== 'function') return out
-    try {
-      const results = await sq.readTitleSnapshots(ids)
-      if (!Array.isArray(results)) return out
-      results.forEach((result, index) => {
-        const id = String(ids[index])
-        out.set(id, unwrapSnapshot(result))
-      })
-    } catch (e) { /* 批量失败：逐条回退 */ }
+    if (!warmHasApi) { markAll(false); return out }
+    if (typeof sq.readTitleSnapshots === 'function') {
+      let results = null
+      try { results = await sq.readTitleSnapshots(ids) } catch (e) { results = null }
+      if (Array.isArray(results)) {
+        results.forEach((result, index) => {
+          const id = String(ids[index])
+          if (result && result.status === 'fulfilled') out.set(id, { resolved: true, snapshot: unwrapSnapshot(result) })
+          else if (result && result.status === 'rejected') out.set(id, { resolved: false, snapshot: null })
+          else if (result) out.set(id, { resolved: true, snapshot: unwrapSnapshot(result) }) // 最老形态：直接是快照
+          else out.set(id, { resolved: false, snapshot: null })
+        })
+        // 结果数组短于请求（runtime 行为异常）→ 缺的条目按失败处理。
+        for (const id of ids) if (!out.has(String(id))) out.set(String(id), { resolved: false, snapshot: null })
+        return out
+      }
+      // 批量形态不认识：退回逐条。
+    }
+    if (typeof sq.readTitleSnapshot === 'function') {
+      for (const raw of ids) {
+        const id = String(raw)
+        try {
+          const r = await sq.readTitleSnapshot(id)
+          if (r && r.status === 'rejected') out.set(id, { resolved: false, snapshot: null })
+          else out.set(id, { resolved: true, snapshot: unwrapSnapshot(r) })
+        } catch (e) { out.set(id, { resolved: false, snapshot: null }) }
+      }
+      return out
+    }
+    markAll(false)
     return out
   }
 
+  // 兼容旧调用点（暂无）：保留名字不导出，避免误用回「失败即 null」的旧语义。
+
   // opts.usage: expose sizeBytes + updatedAt on each item (storage analysis and
   // the auto-archive sweep need them; the panel list does not).
   //
@@ -1212,7 +1368,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
@@ -1242,37 +1399,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 }
     }
-    await 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()
@@ -1360,6 +1539,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) },
@@ -1367,30 +1547,23 @@ 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))
       }
-      await persistDecoded(decoded, statsById)
     }
     // 血缘分类（issue #6）：结构分类（子代理 / fork 分支）来自 list snapshot
     // 的 header，零解码；空白判定见下方 refineEmptyLineage（0.1.3 起体积法
@@ -1406,6 +1579,9 @@ export function apply(ctx) {
       trashedSessionIds: store.items.map((item) => String(item.sessionId)),
       purgedSessionIds: activeTombstones,
       lineage,
+      // v3.6.2：还有预热/退避重试在途 → client 缩短轮询节拍，预热一完成就把
+      // 补齐的标题送回（含面板自动刷新）。无预热 API 时恒 false，绝不假忙。
+      warmPending: warmPendingNow(),
     }
   }
 
@@ -1418,38 +1594,51 @@ export function apply(ctx) {
   // 的候选走官方 inspectSession 解码，按事件类型判定。超过上限的日志必有
   // 内容，直接跳过（维持体积法/结构分类的结果）。解码失败按「非空」处理：
   // 宁可漏判一个空会话，不能把有内容的会话错标成空。
+  // v3.6.2（分支标签延迟审计 #1 的速效半边）：旧实现把全部 ≤8KB 候选**串行**
+  // 解码在 sidebar-state 的请求路径里——冷启动（进程内缓存全空）时零解码成本
+  // 的血缘数据被这串慢解码挡在 return 之前，这正是「⑂ 分支」chip 晚出/32s 台阶
+  // 的直接门控。现在：并行限流 4 路 + 每请求预算 REFINE_BUDGET 条（超预算的
+  // 小日志下一拍继续，逐拍收敛；已缓存的条目零成本照常应用，不影响正确性）。
+  // 彻底解绑（精判挪进后台队列）是 3.7.0 的响应契约改造，不在热修范围。
+  const REFINE_BUDGET = 40
+  function applyEmptyScan(lineage, id, empty) {
+    if (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]
+    }
+  }
   async function refineEmptyLineage(lineage, entries) {
     if (!persistence || typeof persistence.inspectSession !== 'function') return
+    const limiter = createLimiter(4)
+    const todo = []
     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]
-      }
+      const scanned = emptyScanCache.get(id)
+      if (scanned && scanned.sizeBytes === size) { applyEmptyScan(lineage, id, scanned.empty); continue }
+      if (todo.length < REFINE_BUDGET) todo.push({ id, size })
     }
+    await Promise.all(todo.map(({ id, size }) => limiter(async () => {
+      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 }
+      emptyScanCache.set(id, { sizeBytes: size, empty: isEmpty })
+      applyEmptyScan(lineage, id, isEmpty)
+    })))
     // 缓存只保留「本轮仍参与判定」的会话：已彻底删除或日志膨胀超过解码
     // 上限的条目不再有用，淘汰掉防止 Map 随历史会话无限增长。
     const live = new Set()
@@ -1639,12 +1828,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)
@@ -1847,7 +2037,7 @@ export function apply(ctx) {
       path: '/archived-sessions/sessions',
       handler: async (req, res) => {
         try {
-          json(res, { items: await allSessionItems() })
+          json(res, { items: await allSessionItems(), warmPending: warmPendingNow() })
         } catch (e) {
           json(res, { error: String((e && e.message) || e) }, 500)
         }
@@ -1934,7 +2124,8 @@ export function apply(ctx) {
     // 子代理血缘树（管理视图数据面）：给定父会话，返回 origin==='subagent'
     // 的递归子树。DSH 原生目录（ui-subagent）只读，这里补管理能力的数据来源。
     // 只读官方 header 血缘字段（parentSession/origin/delegationDepth/createdAt），
-    // 标题走既有批量投影（readTitleSnapshots），零整本日志解码。
+    // 标题走 v3.6.2 的纯缓存读取（metaCache/持久索引/权威缓存），未命中入后台
+    // 预热、本轮返回 null；请求路径零解码。
     // live 标记 = 会话在内存里活着（正在运行或已打开）：批量清理必须跳过。
     disposers.push(ctx.webServer.register({
       kind: 'exact',
@@ -1970,9 +2161,29 @@ export function apply(ctx) {
             })
             if (Number.isFinite(sizeBytes)) sizeById.set(id, sizeBytes)
           }
+          // v3.6.2 #4：标题只读缓存（metaCache → 持久索引 → 权威缓存），未命中
+          // 入后台预热、本轮返回 null。旧实现在请求路径直调 projectTitles——
+          // 展开一个 N 子树的父会话 = N 次整本解码同步在请求路径上（issue #8
+          // 要消灭的形态在本路由的残留）。这里顺手记下指纹与原始 header，供
+          // 缓存读取与 enqueueWarm 使用。
+          const lineageStats = new Map()
+          const lineageHeaders = new Map()
           try {
             for (const entry of await persistence.listEntries()) {
               addHeader(entry.header, entry.sizeBytes)
+              const eid = entry && entry.id != null ? String(entry.id) : null
+              if (eid) {
+                lineageHeaders.set(eid, { header: (entry && entry.header) || null })
+                // 只有 handle 世代（snapshot 带 revision）才建 stats；legacy 的列表快照
+                // 本就没有这些观测，其标题经 sidebarAuthority 的 authorityTitleCache
+                // 兜住。刻意不在这里合成 sz-only stat——会和列表构建的 mtime:size
+                // 指纹在同一索引里乒乓覆盖，引发交替重复解码。
+                if (entry && typeof entry.revision === 'string' && entry.revision) {
+                  lineageStats.set(eid, Number.isFinite(entry.sizeBytes)
+                    ? { revision: entry.revision, sizeBytes: Number(entry.sizeBytes) }
+                    : { revision: entry.revision })
+                }
+              }
               if (entry && entry.id != null) persistedIds.add(String(entry.id))
             }
           } catch (e) { /* best-effort */ }
@@ -2020,11 +2231,19 @@ export function apply(ctx) {
           const allIds = [rootId]
           const walk = (n) => { allIds.push(n.sessionId); n.children.forEach(walk) }
           nodes.forEach(walk)
-          const titles = await projectTitles(allIds)
+          // v3.6.2 #4：缓存读取 + 预热入队，请求路径零解码。#12：标题按
+          // MAX_TITLE 截断，与列表输出口径一致。
+          const lineageIds = allIds.map(String)
+          const { cached: lineageCached, missing: lineageMissing } = metaCache.partition(lineageIds, lineageStats)
+          const lineagePersisted = await hydrateFromPersist(lineageMissing, lineageStats)
+          for (const [id, meta] of lineagePersisted) metaCache.set(id, lineageStats.get(id), meta)
+          const lineageRest = lineageMissing.filter((id) => !lineagePersisted.has(id))
+          if (lineageRest.length) enqueueWarm(lineageRest, lineageStats, lineageHeaders)
+          const truncateTitle = (t) => (t ? (t.length > MAX_TITLE ? t.slice(0, MAX_TITLE) + '…' : t) : null)
           const titleOf = (id) => {
-            const snap = titles.get(id)
-            const m = snap ? metaFromSnapshot(snap) : null
-            return (m && m.title) || null
+            const key = String(id)
+            const m = lineageCached.get(key) || lineagePersisted.get(key)
+            return truncateTitle((m && m.title) || authorityTitleCache.get(key) || null)
           }
           const fill = (n) => { n.title = titleOf(n.sessionId); n.children.forEach(fill) }
           nodes.forEach(fill)