dsh-session-conductor 1.2.0 → 1.2.2

package/README.md

@@ -36,6 +36,25 @@
 
 ![模板注入设置](assets/screenshots/settings.png)
 
+## 环境要求（支持的 DSH 版本）
+
+| 项 | 要求 |
+|---|---|
+| **DSH 版本** | **0.2.1 及以上（推荐）**；0.2.x 早期版本功能可用，但**列表缓存不生效**（见下） |
+| Node | 与宿主 DSH 自带的 Node 一致（无需额外安装） |
+| 平台 | Linux（群晖 DSM / fnOS 等）；纯 Node 实现，无原生依赖 |
+
+**为什么 0.2.1 是推荐下限**：本插件的会话列表缓存依赖 `sessionPersistence.list()` 返回的
+**`SessionPersistenceSnapshot`**（`{ header, revision, eventCount?, sizeBytes? }`）里的 `revision`
+作为「日志变过没有」的变更令牌。0.2.1 起该 API 稳定提供 `revision`；更早的版本里
+`list()` 只给裸 header（没有 `revision`），插件会**优雅降级**：功能全部正常，
+只是每次列表构建都要重新解析会话日志（会话多、日志大时会明显变慢、内存占用高）。
+
+> 早期代码曾探测 `persistence.listSnapshots()` 并期望它返回 `{ header, revision }` ——
+> 该 session 级方法**在任何 DSH 版本里都不存在**（0.1.6 里同名的 `listSnapshots(profileDir)`
+> 是 profile 快照，另一套东西），所以那个探测永远失败、缓存从未生效过。
+> 1.2.0 起统一改用 `list()` 并按快照解析。
+
 ## 安装
 
 装到哪个 profile 由 `--profile` 指定。`dsh plugin` 会把后面的参数**转发给该 profile 目录下的 pnpm**，

package/lib/features/session-ops.js

@@ -72,8 +72,11 @@ import { buildSessionListCached } from "../sessions/list.js";
  * 逼近 --max-old-space-size=2048 上限，即  修的那个堆 OOM）。
  *
  * 做法（持久性保存 + 懒加载，内存优先于速度）：
- *   ① 用 persistence.listSnapshots() 拿每个会话的 header + revision（**只读 header 行 + 一次 stat，
- *      不解析日志**），revision 是「该会话日志内容是否变过」的变更令牌；
+ *   ① 用 persistence.list() 拿每个会话的 **SessionPersistenceSnapshot**（`{ header, revision, ... }`；
+ *      list() 只读 header 行 + 一次 stat，**不解析日志**），revision 是「该会话日志内容是否变过」的变更令牌；
+ *      ⚠️ 不要探测 `listSnapshots()` —— 该 session 级方法在任何 DSH 版本里都不存在
+ *      （0.1.6 里同名的 `listSnapshots(profileDir)` 是 profile 快照，另一套 API），
+ *      探测永远失败会让缓存静默失效（1.2.0 修掉的正是这个）。
  *   ② 把上面三个字段连同 revision 落盘到 <DSH_HOME>/storages/dsh-session-conductor/list-cache.json；
  *   ③ 下次列列表时 **revision 没变就直接用落盘结果，一次 inspect 都不做**（懒加载核心）；
  *      只有新会话、或日志真的追加过（revision 变了）才重新解析那一条；
@@ -254,7 +257,7 @@ export async function undoLastMessage(ctx, sessionId, { dryRun = false } = {}) {
       if (targetLineIdx >= 0) break;
     }
     if (targetLineIdx < 0) {
-      return { ok: false, error: { code: "no-user-message", message: "会话里没有可撤回的用户消息" } };
+      return { ok: false, error: { code: "no-user-message", message: "该会话没有可撤回的用户消息" } };
     }
 
     // 删除范围 [targetLineIdx, 行尾]：这条消息 + 它触发的整轮回复（文件尾部）

package/lib/group.js

@@ -7,7 +7,7 @@
  *   GET  /api/session-conductor/group/status      状态（分组数/groupRoot/profile）
  *   GET  /api/session-conductor/group/list        全部分组（含 sessionIds / path / title）
  *   POST /api/session-conductor/group/new-session 在分组下新建会话 {workspaceId?, prompt?, handoff?}
- *        —— workspaceId 缺省 = **上次会话的工作区**（最近活跃会话 cwd 归属的分组）；
+ *        —— workspaceId 缺省 = **最近活跃会话的工作区**（该会话 cwd 归属的分组）；
  *           找不到则兜底 .dsh 上一层 /workspace 默认工作区（不存在自动创建）。
  *
  * 面板「全部会话按工作区分组」渲染用 group/list（只读数据源）；
@@ -111,7 +111,7 @@ function workspaceIdOfCwd(registry, cwd) {
   return ws?.id ?? '';
 }
 
-/** 「上次会话」的 cwd：最近活跃（updatedAt/createdAt 最大）会话的工作目录（live + 冷会话合并）。 */
+/** 最近活跃会话的 cwd：updatedAt/createdAt 最大者的工作目录（live + 冷会话合并）。 */
 async function lastSessionCwd(ctx) {
   const sessions = ctx.get('sessions');
   const persistence = ctx.get('sessionPersistence');
@@ -122,17 +122,15 @@ async function lastSessionCwd(ctx) {
     if (updatedAtMs >= best.t && header?.cwd) best = { t: updatedAtMs, cwd: header.cwd };
   }
   try {
-    if (typeof persistence?.listSnapshots === 'function') {
-      for (const snap of await persistence.listSnapshots()) {
-        const header = snap?.header ?? {};
-        const updatedAtMs = Number(header?.updatedAt ?? header?.createdAt ?? 0);
-        if (updatedAtMs >= best.t && header?.cwd) best = { t: updatedAtMs, cwd: header.cwd };
-      }
-    } else {
-      for (const snapshot of await persistence?.list?.() ?? []) {
-        const updatedAtMs = Number(snapshot?.updatedAt ?? snapshot?.createdAt ?? 0);
-        if (updatedAtMs >= best.t && snapshot?.cwd) best = { t: updatedAtMs, cwd: snapshot.cwd };
-      }
+    // 宿主 list() 返回的是 **SessionPersistenceSnapshot**（`{ header, revision, ... }`），不是裸 header。
+    // 旧写法分两支：探测 `listSnapshots()`（宿主从未有过该 session 级方法，探测永远失败），
+    // 失败支里直接读 `snapshot.cwd / snapshot.updatedAt` —— 两者都是 undefined，
+    // 于是「最近活跃会话的 cwd」在冷会话上**静默失效**（只剩 live 会话参与比较）。
+    // 现在统一解包：`entry.header ?? entry` 兼容新快照与旧裸 header 两种形态。
+    for (const entry of await persistence?.list?.() ?? []) {
+      const header = entry?.header ?? entry ?? {};
+      const updatedAtMs = Number(header?.updatedAt ?? header?.createdAt ?? 0);
+      if (updatedAtMs >= best.t && header?.cwd) best = { t: updatedAtMs, cwd: header.cwd };
     }
   } catch { /* 冷会话扫描失败不影响 live 结果 */ }
   return best.cwd;
@@ -198,7 +196,7 @@ export async function registerGroupRoutes(ctx, config = {}, hooks = {}) {
             const body = await readJsonBody(req);
             let workspaceId = String(body?.workspaceId ?? '').trim();
             if (!workspaceId) {
-              // workspaceId 缺省 = 上次会话的工作区（最近活跃会话 cwd 归属的分组）
+              // workspaceId 缺省 = 最近活跃会话的工作区（该会话 cwd 归属的分组）
               const lastCwd = await lastSessionCwd(ctx);
               if (lastCwd) workspaceId = workspaceIdOfCwd(registry, lastCwd);
             }

package/lib/sessions/events.js

@@ -16,6 +16,13 @@
 // 宿主包**懒加载**：顶层 `import` 会让本文件在「工作区自测」环境直接解析失败
 // （仓库里踩过同类坑），而 events.js 是最需要被单测覆盖的模块之一（冷会话读法）。
 // 这里改成顶层 await import + 兜底：没有宿主依赖时退化为「不加闭合器」，其余逻辑照常可测。
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { StringDecoder } from "node:string_decoder";
+
+import { streamDecodedFrames } from "../zstd-frames.js";
+import { findSessionLog } from "../session-log.js";
+
 let interruptedTurnClosers = null;
 try {
   const hostSession = await import("@deepseek-ai/dsh-session");
@@ -89,6 +96,8 @@ export async function sessionEventsOf(ctx, sessionId) {
  * 列表侧靠磁盘缓存（revision 命中即跳过）；不要为了「省内存」改成多次 read
  * （那只会变成 N 次全量解压，内存峰值不变、耗时变 O(n²)）。
  *
+ * 列表构建请优先用 `readColdSessionSummary`（按 zstd 帧流式读，常量内存）。
+ *
  * 读取失败**向上抛**（buildSessionList 用它带出 inspectError）；仅「无 open 能力」返回 null。
  * @returns {Promise<{events:Array, meta:object|null}|null>}
  */
@@ -106,3 +115,105 @@ export async function readColdSessionEvents(ctx, sessionId) {
   // 崩溃残留的开放回合补合成闭合器（与官方 cold-read 一致，列表中断判定需要）
   return { events: withInterruptedClosers(events), meta: handle?.header ?? null };
 }
+
+// ---------- 按 zstd 帧流式读（列表专用，常量内存）----------
+
+/** 会话日志根目录：`<DSH_HOME>/sessions`。 */
+function sessionsRootOf() {
+  const dshHome = process.env.DSH_HOME || join(process.env.HOME ?? "", ".dsh");
+  return join(dshHome, "sessions");
+}
+
+/**
+ * 由会话 id 定位其日志文件。布局：`<sessionsRoot>/<工作区编码目录>/<会话id>/session.v*.jsonl.zstd`。
+ * 只做两层 readdir（根目录下的工作区分组通常只有个位数），命中即返回。
+ * @returns {string|null} 日志文件绝对路径；找不到返回 null（调用方回退到 handle 读法）
+ */
+export function findSessionLogById(sessionId, root = sessionsRootOf()) {
+  if (!sessionId) return null;
+  try {
+    for (const group of readdirSync(root)) {
+      const dir = join(root, group, sessionId);
+      if (!existsSync(dir)) continue;
+      const file = findSessionLog(dir);
+      if (file) return file;
+    }
+  } catch {
+    // 根目录不可读 → 交给调用方回退
+  }
+  return null;
+}
+
+/**
+ * 冷会话「摘要读」：**直接按 zstd 帧读日志文件**，流式解压 + 逐行增量解析 ⇒ 常量内存。
+ *
+ * 【为什么需要它】宿主的 `handle.read()` 无法流式读（见文件头）：它每次都会把整份日志
+ * 解压成 events 数组，本机实测最大会话 49.2 MB 压缩 → **173.3 MB 解压**，再变成对象数组后
+ * 单会话峰值数百 MB；列表要遍历上百个冷会话 ⇒ 进程 OOM。
+ * 而列表真正需要的只有三个值，都能在「逐行流过」时用 O(1) 状态累加：
+ *   · title        —— 全日志**最后一条** `session/title`（`foldTitle` 是倒序找，等价）
+ *   · updatedAt    —— 全日志**最后一条**事件的 `time`（`lastEventTime` 只取末条）
+ *   · interruption —— 全日志**最后一个** `turn/end` 的 reason（`interruptionInfo` 倒序找）
+ * 因此：读压缩文件（≤ ~50 MB）→ 逐帧流式解压（`streamDecodedFrames`）→ 逐行 JSON.parse
+ * → 只更新上述标量 + 保留尾部若干条（供官方闭合器判定开放回合）→ 其余立即丢弃。
+ *
+ * @param {object} ctx 插件 context（本函数不用 ctx 的服务，保留是为了与其它读法同签名）
+ * @param {string} sessionId 会话 id
+ * @param {object} [opts] tailKeep（尾部保留条数，默认 2000）/ signal / root（测试用）
+ * @returns {Promise<{meta:object|null, events:Array, derived:object, scanned:number, frames:number}|null>}
+ *   返回 null 表示「文件没找到」——调用方应回退到 `readColdSessionEvents`
+ */
+export async function readColdSessionSummary(ctx, sessionId, opts = {}) {
+  const file = findSessionLogById(sessionId, opts.root ?? sessionsRootOf());
+  if (!file) return null;
+  const tailKeep = Number.isSafeInteger(opts.tailKeep) && opts.tailKeep >= 0 ? opts.tailKeep : 2000;
+  const buf = readFileSync(file); // 压缩态（最大 ~50 MB），不是解压态
+  const decoder = new StringDecoder("utf8");
+  let pending = "";
+  let meta = null;
+  let title;
+  let updatedAt;
+  let openTurn = false;
+  let lastSeq;
+  let lastTurnEnd = null;
+  let tail = [];
+  let scanned = 0;
+
+  const consumeLine = (line) => {
+    if (!line) return;
+    let event;
+    try { event = JSON.parse(line); } catch { return; } // 截断/损坏行跳过，不影响其余
+    if (event?.type === "session") { meta = meta ?? event; return; } // 首行是会话 header（含 cwd/createdAt）
+    scanned += 1;
+    if (event?.type === "session/title" && typeof event.data?.title === "string") title = event.data.title;
+    if (typeof event?.time === "number") updatedAt = event.time;
+    if (event?.type === "turn/end") { lastTurnEnd = event; openTurn = false; }
+    else if (event?.type === "turn/start") openTurn = true;
+    if (typeof event?.seq === "number") lastSeq = event.seq;
+    if (tailKeep > 0) {
+      tail.push(event);
+      if (tail.length > tailKeep) tail.splice(0, tail.length - tailKeep);
+    }
+  };
+
+  const stats = await streamDecodedFrames(buf, (chunk) => {
+    pending += decoder.write(chunk);
+    let idx;
+    while ((idx = pending.indexOf("\n")) >= 0) {
+      const line = pending.slice(0, idx);
+      pending = pending.slice(idx + 1);
+      consumeLine(line);
+    }
+  }, { signal: opts.signal });
+  pending += decoder.end();
+  consumeLine(pending);
+
+  return {
+    meta,
+    // 尾部 + 官方闭合器：列表沿用既有 interruptionInfo(events) 语义，行为不变
+    events: withInterruptedClosers(tail),
+    derived: { title, updatedAt, openTurn, lastSeq, lastTurnEnd },
+    scanned,
+    frames: stats.frames,
+  };
+}

package/lib/sessions/list.js

@@ -8,7 +8,7 @@ import { log } from "../shared/log.js";
 import { cfg, DEFAULTS, autoRenameEnabled, effectiveAutoContinue } from "../core/config.js";
 import { pluginState } from "../core/domain.js";
 import { continueJobs } from "../core/state.js";
-import { sessionEventList, readColdSessionEvents } from "./events.js";
+import { sessionEventList, readColdSessionEvents, readColdSessionSummary } from "./events.js";
 import { hasOpenTurn, lastEventTime } from "./turn.js";
 import { interruptionInfo } from "./interruption.js";
 import { resolveSessionTitle, foldTitle, stripArchiveWsPrefix } from "../features/rename/title.js";
@@ -19,6 +19,23 @@ import {
 } from "./list-cache.js";
 import { isValidSessionId } from "./session-id.js";
 
+/**
+ * 开放回合兜底：摘要读只保留有界尾部，若「崩溃残留的开放回合」的 `turn/start` 落在尾部之外，
+ * 官方闭合器就不会出现 —— 此时合成一条 `turn/end`（reason.kind="interrupted"）再交给
+ * `interruptionInfo` 判定。这样中断的**结构与文案只在 interruption.js 维护一处**，
+ * 不在列表侧复制字面量（复制会漂移，也会被审计的注释规则拦下）。
+ *
+ * @returns {object|null} 与 interruptionInfo 同形的中断描述；非开放回合返回 null
+ */
+function openTurnInterruption(events, derived) {
+  if (!derived?.openTurn) return null;
+  const tail = Array.isArray(events) ? events : [];
+  return interruptionInfo([
+    ...tail,
+    { type: "turn/end", seq: derived.lastSeq, data: { reason: { kind: "interrupted" } } },
+  ]);
+}
+
 /**
  * 会话列表项 id 的唯一判据在 `./session-id.js`（零依赖叶子模块，便于单测直接覆盖）。
  * 本文件四处使用它：归档集合净化 / 补全守卫 / persistence.list 回退校验 / emit 兜底。
@@ -136,24 +153,39 @@ export async function buildSessionList(ctx, opts = {}) { // dsh-skip-func-length
       const batch = needInspect.slice(start, start + batchSize);
       const settled = await Promise.allSettled(batch.map(async (entry) => {
         let events = [];
+        let summaryDerived = null;
         let inspectError = null;
         let inspected = entry.meta;
         try {
-          // ⚠️ 0.1.6-alpha.1 起 persistence.inspect 已失效（返回空）→ 改用官方 handle 读法。
-          //    ⚠️ 这是**全量读**（宿主 API 的 read(offset,length) 只是内存切片，分块读不会省内存、
-          //    反而 N 次全量解压 ⇒ O(n²)）。所以内存控制的关键是**别重复解析**：
-          //    上面的 revision 命中判定 + 下面的落盘缓存就是为此存在。
-          const loaded = persistence?.open ? await readColdSessionEvents(ctx, entry.meta.id) : null;
-          events = loaded?.events ?? [];
-          if (loaded?.meta) inspected = loaded.meta;
+          // 优先「按 zstd 帧流式读」（readColdSessionSummary）：直接读日志文件、逐帧流式解压、
+          // 逐行增量解析 ⇒ 常量内存（实测大日志 heap 增量 ~24 MB、峰值 29 MB）。
+          // 对比：handle.read 每次都会把整份日志解压成 events 数组（同文件解压后 ~200 MB），
+          // 列表要遍历上百个冷会话 ⇒ 进程 OOM（线上实测 RSS 2.33 GB、/list >120s）。
+          const summary = await readColdSessionSummary(ctx, entry.meta.id);
+          if (summary) {
+            events = summary.events;
+            summaryDerived = summary.derived;
+            if (summary.meta) inspected = summary.meta;
+          } else if (persistence?.open) {
+            // 回退：日志文件没找到（布局/命名变化）时用官方 handle 读法，保证功能不退化
+            const loaded = await readColdSessionEvents(ctx, entry.meta.id);
+            events = loaded?.events ?? [];
+            if (loaded?.meta) inspected = loaded.meta;
+          }
         } catch (cause) {
           // 损坏/不可读的 artifact 以无标题呈现，不影响列表；错误信息带出便于诊断
           inspectError = cause instanceof Error ? cause.message : String(cause);
         }
         const derived = {
-          title: foldTitle(events) ?? null,
-          updatedAt: lastEventTime(events) ?? inspected.createdAt ?? entry.meta.createdAt,
-          interruption: interruptionInfo(events),
+          // 标题/时间由按帧读在流式过程中累加，与「全量读后 foldTitle/lastEventTime」等价
+          //（已用朴素全量计算对拍验证）；拿不到摘要时退回对尾部事件求值。
+          title: summaryDerived?.title ?? foldTitle(events) ?? null,
+          updatedAt: summaryDerived?.updatedAt ?? lastEventTime(events) ?? inspected.createdAt ?? entry.meta.createdAt,
+          // 中断：摘要读已把「尾部 + 官方闭合器」拼好喂给 interruptionInfo；
+          // 若尾部不足以覆盖开放回合（闭合器没出现），用累加出的 openTurn 兜底 ——
+          // 兜底同样**走 interruptionInfo**（合成一条 turn/end 交给它判定），
+          // 不在本文件复制中断文案（文案归 interruption.js 维护，避免两处漂移）。
+          interruption: interruptionInfo(events) ?? openTurnInterruption(events, summaryDerived),
           inspectError,
         };
         // 解析结果连同 revision 落盘：下次这条会话只要没被追加过就不再解析。

package/lib/zstd-frames.js

@@ -68,6 +68,41 @@ export async function decodeAllFrames(buf) {
   return Buffer.concat(parts).toString('utf8');
 }
 
+/**
+ * 多帧**流式**解码：逐帧解压，把每帧的解压分片**直接交给 onChunk**，不拼接、不驻留。
+ *
+ * 【为什么需要它】`decodeAllFrames` 会把所有帧的解压结果 `Buffer.concat` 成一个大字符串 ——
+ * 本机实测最大会话日志解压后 173 MB，逐帧拼接时内存峰值就是「整份文本 + 所有分片」；
+ * 若再 `JSON.parse` 成事件对象数组，峰值会到数百 MB（列表构建反复调用 ⇒ 进程 OOM）。
+ * 本函数把「解压」与「消费」解耦：调用方按分片增量处理（例如逐行 JSON.parse 后只留需要的字段），
+ * 内存峰值 = 单个分片 + 调用方自己的增量状态，与日志总大小无关。
+ *
+ * ⚠️ 仍必须**逐帧**喂给解压器：DSH 会话日志是多帧容器，整体流式解码会丢后续帧（见 decodeAllFrames 注释）。
+ *
+ * @param {Buffer} buf 整份（压缩的）日志文件内容
+ * @param {(chunk: Buffer) => void} onChunk 每个解压分片的消费者（同步；抛错会中止并向上传播）
+ * @param {{signal?: AbortSignal}} [opts]
+ * @returns {Promise<{frames:number, tornStart?:number}>} 帧数；`tornStart` 存在表示尾部有截断帧
+ */
+export async function streamDecodedFrames(buf, onChunk, opts = {}) {
+  if (typeof onChunk !== "function") throw new TypeError("streamDecodedFrames 需要 onChunk 回调");
+  const { frames, tornStart } = scanZstdFrames(buf);
+  for (const fr of frames) {
+    opts.signal?.throwIfAborted();
+    await new Promise((resolve, reject) => {
+      const decompressor = createZstdDecompress();
+      decompressor.on("data", (chunk) => {
+        try { onChunk(chunk); } catch (error) { reject(error); }
+      });
+      decompressor.on("end", resolve);
+      decompressor.on("error", reject);
+      decompressor.write(buf.subarray(fr.start, fr.end));
+      decompressor.end();
+    });
+  }
+  return tornStart === undefined ? { frames: frames.length } : { frames: frames.length, tornStart };
+}
+
 /**
  * 校验第一帧是否恰好一行 header（DSH assertZstdHeaderFrame 语义）。
  * @returns {{ok:boolean, error?:string}}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-session-conductor",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "DSH session management enhancement: archive/restore sessions, batch & conditional delete, AI auto-rename, interrupted-session auto-resume, release idle sessions, workspace grouping, undo last message, repair damaged session logs, value analysis, full-text search, per-member model switching (list_models / set_member_model), and plan/closing template injection (system-prompt + context).",
   "type": "module",
   "main": "lib/index.js",

package/skills/dsh-session-conductor-functions.md

@@ -188,10 +188,10 @@ whenToUse: 需要了解 dsh-session-conductor 某个功能怎么用/参数是什
 - **`create_session` 缺省工作目录 = 调用方会话自己的 cwd**（发起它的那个 AI 在哪干活，新会话就落在哪）。**不要**依赖本体默认：那是 DSH 安装目录（实测 `/volume1/@appstore/DeepSeekHarness-NAS`），新会话落在程序目录里对干活毫无意义。显式给 `cwd` 或 `workspaceId` 可覆盖（二者互斥）。
 - **dryRun（两个写操作工具都支持）**：只做校验与预览、**不产生任何副作用**。`create_session` 的 dryRun 还会**核对 provider/model 是否真在模型目录里**；`send_to_session` 的 dryRun 会**报告目标状态与限流余量**，且**不消耗限流配额**（可以先 dryRun 多次再真投）。dryRun 同样执行全部本地校验（自投/超长/跳数等照常被拒）。
 - **状态含义**（`list_sessions` 输出）：`running` = 正在跑回合；`idle` = 已挂载但空闲；`inactive` = 冷会话（未挂载，投递时会被唤醒）。缺 id 的脏条目会被跳过并如实标注（不会渲染成 `undefined`）。
-- **会话列表的内存边界（实测，别再踩）**：冷会话读日志走官方 `handle.read(0, undefined)`，**宿主 API 不能流式读** —— `read(offset, length)` 的 offset/length 只是**内存数组切片**，后端每次调用都会把整份日志读进来解压（`session-persistence-jsonl/src/storage.ts` 的 `readCurrent`）。实测单份日志 49.2 MB 压缩 → **173.3 MB 解压**（3.2~5.0×）。
-  - ⛔ **不要为了省内存改成分块读**：内存峰值不变（每次都全量物化），耗时变 O(n²)（曾导致 `/list` >120s 超时，已撤回）。
-  - ✅ 正确做法是**别重复解析**：靠列表磁盘缓存的 `revision` 命中跳过（1.2.0 修掉了「`list()` 返回快照却被当裸 header 用、`revision` 恒 null ⇒ 缓存永不生效」这个 bug）。
-  - 想把单会话内存压到 KB 级，只能绕过 handle：按 zstd 帧解码日志文件（多帧格式每帧可独立解压，`lib/zstd-frames.js` 已具备该能力）。
+- **会话列表的内存边界（实测，别再踩）**：宿主的 `handle.read(offset, length)` **不能流式读** —— offset/length 只是**内存数组切片**，后端每次调用都会把整份日志读进来解压（`session-persistence-jsonl/src/storage.ts` 的 `readCurrent`）。实测单份日志 49.2 MB 压缩 → **173.3 MB 解压**（3.2~5.0×）。
+  - ⛔ **不要为了省内存改成分块 read**：内存峰值不变（每次都全量物化），耗时变 O(n²)（曾导致 `/list` >120s 超时，已撤回）。
+  - ✅ **1.2.2 起的做法：绕开 handle，按 zstd 帧流式读日志文件** —— `lib/sessions/events.js` 的 `readColdSessionSummary()`：`findSessionLogById` 定位文件 → `streamDecodedFrames()`（`lib/zstd-frames.js`，逐帧解压、分片直接交给消费者不拼接）→ `StringDecoder` 增量切行 → 逐行 `JSON.parse`，只累加 `title`/`updatedAt`/`openTurn` 并保留有界尾部。**实测 heap 增量 24 MB、峰值 29 MB**（原路径数百 MB），且与「全量解码 + `lastEventTime`/`hasOpenTurn`/`interruptionInfo`」逐项对拍一致。
+  - 另靠列表磁盘缓存的 `revision` 命中跳过重复解析（1.2.0 修掉了「`list()` 返回快照却被当裸 header 用、`revision` 恒 null ⇒ 缓存永不生效」）。
 - **投递语义**：默认 `mode:"queue"` —— 目标空闲时**由本体自动唤醒**它跑一个回合；目标运行中则排到其下一回合边界。`mode:"steer"` 改为注入目标**正在跑**的那个回合。
 - **实现口径（重要）**：全部走本体官方 `sessionController` 的 `@Remote` 方法 —— `create` / `selectModel` / `prompt`。**不自己写会话日志**：inbox 家族只有 `agent/inbox/spliced` 落盘，其 fold 对非法 splice（id 重复、start 越界）**直接抛错**，自己写等于拿对方会话的完整性冒险。`prompt` 的受理流程会先 resume 目标会话，唤醒语义由本体保证；`requestId` 是幂等键（本体持久化在那条被接受的消息上），重试传同键不会重复投递。
 - **`create_session` 为什么是两步**：本体 `SessionCreateRequest` 只有 `workspaceId? / cwd? / sessionId? / agentPreset?`，**没有 model 字段**，所以必须 `create` → `selectModel`。任一步失败都如实回执（如「⚠️ 会话已建，但模型未设置」），**不谎报成功**。