@baique/pi-web-sky 0.1.56 → 0.1.57

package/lib/session-scanner.test.mjs

@@ -1,12 +1,17 @@
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, mkdtempSync, mkdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
 import { createJiti } from "jiti";
 
 const jiti = createJiti(import.meta.url);
-const { scanSessionFiles } = await jiti.import("./session-scanner.ts");
+const { scanOneSessionFile, readSessionTail } = await jiti.import("./session-scanner.ts");
+
+/** 单文件详情扫描（旧 scanSessionFiles 的全量入口已删：读取路径不再扫盘）。 */
+function scanFile(file) {
+  return scanOneSessionFile(file);
+}
 
 function makeRoot() {
   const root = mkdtempSync(join(tmpdir(), "pi-scan-"));
@@ -40,7 +45,7 @@ test("scanSessionFileMeta：阶段一只解析文件名 id+mtime，不读内容"
   }
 });
 
-test("scanSessionFiles：读取 header + 首条用户消息，忽略正文", async () => {
+test("scanOneSessionFile：读取 header + 首条用户消息，忽略正文", async () => {
   const { root, projDir } = makeRoot();
   try {
     const file = join(projDir, "2026-01-01T00-00-00-000Z_aaa.jsonl");
@@ -52,9 +57,8 @@ test("scanSessionFiles：读取 header + 首条用户消息，忽略正文", asy
       '{"type":"message","id":"u2","parentId":"a1","message":{"role":"user","content":"再帮我优化一下"}}',
     ].join("\n") + "\n");
 
-    const result = await scanSessionFiles(root);
-    assert.equal(result.length, 1);
-    const s = result[0];
+    const s = scanFile(file);
+    assert.ok(s, "会话文件可扫描");
     assert.equal(s.id, "aaa");
     assert.equal(s.cwd, "/home/wa/project/demo");
     assert.equal(s.firstMessage, "你好，请帮我看看这个项目");
@@ -67,7 +71,7 @@ test("scanSessionFiles：读取 header + 首条用户消息，忽略正文", asy
   }
 });
 
-test("scanSessionFiles：扫描读取最后一个 session_info 的自定义名", async () => {
+test("scanOneSessionFile：扫描读取最后一个 session_info 的自定义名", async () => {
   const { root, projDir } = makeRoot();
   try {
     const file = join(projDir, "2026-01-01T00-00-00-000Z_bbb.jsonl");
@@ -78,16 +82,14 @@ test("scanSessionFiles：扫描读取最后一个 session_info 的自定义名",
       '{"type":"session_info","id":"s2","parentId":"a1","name":"最终名字","timestamp":"2026-01-01T00:00:06.000Z"}',
     ].join("\n") + "\n");
 
-    const result = await scanSessionFiles(root);
-    assert.equal(result.length, 1);
     // 扫描直接读名字（反向分块），取最后一个 session_info。
-    assert.equal(result[0].name, "最终名字");
+    assert.equal(scanFile(file).name, "最终名字");
   } finally {
     rmSync(root, { recursive: true, force: true });
   }
 });
 
-test("scanSessionFiles：改名后大量新消息把 session_info 推远也能读到（旧 bug 场景）", async () => {
+test("scanOneSessionFile：改名后大量新消息把 session_info 推远也能读到（旧 bug 场景）", async () => {
   const { root, projDir } = makeRoot();
   try {
     const file = join(projDir, "2026-01-01T00-00-00-000Z_far.jsonl");
@@ -101,27 +103,27 @@ test("scanSessionFiles：改名后大量新消息把 session_info 推远也能
     }
     writeFileSync(file, lines.join("\n") + "\n");
 
-    const result = await scanSessionFiles(root);
-    assert.equal(result.length, 1);
-    assert.equal(result[0].name, "深藏的名字");
+    assert.equal(scanFile(file).name, "深藏的名字");
   } finally {
     rmSync(root, { recursive: true, force: true });
   }
 });
 
-test("scanSessionFiles：非会话文件（首行不是 session）跳过", async () => {
+test("scanOneSessionFile：非会话文件（首行不是 session）与空文件跳过", async () => {
   const { root, projDir } = makeRoot();
   try {
-    writeFileSync(join(projDir, "junk.jsonl"), '{"type":"message",...}\n');
-    writeFileSync(join(projDir, "empty.jsonl"), "");
-    const result = await scanSessionFiles(root);
-    assert.equal(result.length, 0);
+    const junk = join(projDir, "junk.jsonl");
+    const empty = join(projDir, "empty.jsonl");
+    writeFileSync(junk, '{"type":"message",...}\n');
+    writeFileSync(empty, "");
+    assert.equal(scanFile(junk), null, "首行不是 session → null");
+    assert.equal(scanFile(empty), null, "空文件 → null");
   } finally {
     rmSync(root, { recursive: true, force: true });
   }
 });
 
-test("scanSessionFiles：超大正文不影响扫描，只取首部简述", async () => {
+test("scanOneSessionFile：超大正文不影响扫描，只取首部简述", async () => {
   const { root, projDir } = makeRoot();
   try {
     const file = join(projDir, "2026-01-01T00-00-00-000Z_ccc.jsonl");
@@ -135,45 +137,156 @@ test("scanSessionFiles：超大正文不影响扫描，只取首部简述", asyn
     ].join("\n") + "\n");
 
     const t0 = Date.now();
-    const result = await scanSessionFiles(root);
+    const scanned = scanFile(file);
     const elapsed = Date.now() - t0;
-    assert.equal(result.length, 1);
-    assert.equal(result[0].id, "ccc");
-    assert.equal(result[0].firstMessage, "帮我写一篇文章");
+    assert.equal(scanned.id, "ccc");
+    assert.equal(scanned.firstMessage, "帮我写一篇文章");
     assert.ok(elapsed < 2000, `大文件扫描应远快于读全量（实际 ${elapsed}ms）`);
   } finally {
     rmSync(root, { recursive: true, force: true });
   }
 });
 
-test("scanSessionFiles：按 modified（文件 mtime）降序排序", async () => {
+test("readSessionTail：文件尾一次反向分块同时拿自定义名与最后一条 assistant 回复", async () => {
   const { root, projDir } = makeRoot();
   try {
-    const old = join(projDir, "2026-01-01T00-00-00-000Z_old.jsonl");
-    const fresh = join(projDir, "2026-01-02T00-00-00-000Z_new.jsonl");
-    writeFileSync(old, '{"type":"session","version":3,"id":"old","timestamp":"2026-01-01T00:00:00.000Z","cwd":"/home/wa/project/demo"}\n');
-    // 新文件 mtime 更新。
-    await new Promise((resolve) => setTimeout(resolve, 30));
-    writeFileSync(fresh, '{"type":"session","version":3,"id":"new","timestamp":"2026-01-02T00:00:00.000Z","cwd":"/home/wa/project/demo"}\n');
+    const file = join(projDir, "2026-01-01T00-00-00-000Z_tail.jsonl");
+    writeFileSync(file, [
+      '{"type":"session","version":3,"id":"tail","timestamp":"2026-01-01T00:00:00.000Z","cwd":"/home/wa/project/demo"}',
+      '{"type":"message","id":"u1","parentId":null,"message":{"role":"user","content":"问题"}}',
+      '{"type":"message","id":"a1","parentId":"u1","message":{"role":"assistant","content":[{"type":"text","text":"第一条回复"}]}}',
+      '{"type":"session_info","id":"s1","parentId":"a1","name":"我的会话"}',
+      '{"type":"message","id":"a2","parentId":"s1","message":{"role":"assistant","content":[{"type":"text","text":"最后一条回复"}]}}',
+    ].join("\n") + "\n");
+
+    assert.deepEqual(readSessionTail(file), { name: "我的会话", lastReply: "最后一条回复" });
+
+    // 只有用户消息（没有回复）→ lastReply 为空串（调用方据此写 ''，与「读不出来」区分）
+    const noReply = join(projDir, "2026-01-02T00-00-00-000Z_noreply.jsonl");
+    writeFileSync(noReply, [
+      '{"type":"session","version":3,"id":"noreply","timestamp":"2026-01-02T00:00:00.000Z","cwd":"/home/wa/project/demo"}',
+      '{"type":"message","id":"u1","parentId":null,"message":{"role":"user","content":"只有提问"}}',
+    ].join("\n") + "\n");
+    assert.deepEqual(readSessionTail(noReply), { name: undefined, lastReply: "" });
+
+    // 文件不存在/为空 → null（调用方保持「未回填」，下一轮再试）
+    assert.equal(readSessionTail(join(projDir, "missing.jsonl")), null);
+    const empty = join(projDir, "empty-tail.jsonl");
+    writeFileSync(empty, "");
+    assert.equal(readSessionTail(empty), null);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("readSessionTail 永不抛错：stat 能过但 open 失败（EACCES）/路径是目录 → null", async (t) => {
+  const { root, projDir } = makeRoot();
+  try {
+    // 路径是目录：stat 成功、不是文件 → null（不需要 open）
+    const dir = join(projDir, "a-directory.jsonl");
+    mkdirSync(dir, { recursive: true });
+    assert.equal(readSessionTail(dir), null, "目录不当会话文件");
+
+    if (process.getuid?.() === 0) {
+      t.diagnostic("以 root 运行：文件权限不生效，跳过「stat 可过但 open 失败」用例");
+      return;
+    }
+    // stat 能过、openSync 抛 EACCES：readSessionTail 必须吞掉（它是回填循环里的逐行调用，
+    // 抛出去会中止整轮扫描）。
+    const noRead = join(projDir, "2026-01-03T00-00-00-000Z_noread.jsonl");
+    writeFileSync(noRead, '{"type":"session","version":3,"id":"noread","cwd":"/x"}\n');
+    chmodSync(noRead, 0o000);
+    try {
+      assert.equal(readSessionTail(noRead), null, "不可读文件 → null，不抛");
+      assert.ok(statSync(noRead).size > 0, "stat 本身仍能过（确实是 stat 通过/open 失败）");
+    } finally {
+      chmodSync(noRead, 0o644);
+    }
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
 
-    const result = await scanSessionFiles(root);
-    assert.deepEqual(result.map((s) => s.id), ["new", "old"]);
+test("scanOneSessionFile / scanOneSessionHead 永不抛错：stat 能过但 open 失败（EACCES）→ null", async (t) => {
+  const { root, projDir } = makeRoot();
+  try {
+    const mod = await jiti.import("./session-scanner.ts");
+    // 目录路径：stat 成功但 isFile() 为 false → null（不用 open）
+    const dir = join(projDir, "2026-01-04T00-00-00-000Z_a-dir.jsonl");
+    mkdirSync(dir, { recursive: true });
+    assert.equal(mod.scanOneSessionFile(dir), null, "目录不当会话文件");
+    assert.equal(mod.scanOneSessionHead(dir), null);
+
+    if (process.getuid?.() === 0) {
+      t.diagnostic("以 root 运行：文件权限不生效，跳过「stat 可过但 open 失败」用例");
+      return;
+    }
+    // stat 能过、openSync 抛 EACCES：详情读取路径不能把异常抛给调用方
+    // （/api/sessions/summary 的「库内无行」回退——旧 bug 会让接口 500）。
+    const noRead = join(projDir, "2026-01-03T00-00-00-000Z_noread.jsonl");
+    writeFileSync(noRead, '{"type":"session","version":3,"id":"noread","cwd":"/x"}\n');
+    chmodSync(noRead, 0o000);
+    try {
+      assert.ok(statSync(noRead).size > 0, "stat 本身仍能过（确实是 stat 通过/open 失败）");
+      assert.equal(mod.scanOneSessionFile(noRead), null, "详情读取：open 失败 → null，不抛");
+      assert.equal(mod.scanOneSessionHead(noRead), null, "头部读取：open 失败 → null，不抛");
+    } finally {
+      chmodSync(noRead, 0o644);
+    }
   } finally {
     rmSync(root, { recursive: true, force: true });
   }
 });
 
-test("scanSessionFiles：缺失 timestamp 的 header 用 mtime 兜底", async () => {
+test("scanOneSessionFile：缺失 timestamp 的 header 用 mtime 兜底", async () => {
   const { root, projDir } = makeRoot();
   try {
-    writeFileSync(join(projDir, "2026-01-01T00-00-00-000Z_noTs.jsonl"), '{"type":"session","version":3,"id":"noTs","cwd":"/home/wa/project/demo"}\n');
-    const result = await scanSessionFiles(root);
-    assert.equal(result.length, 1);
-    assert.ok(Number.isFinite(result[0].created.getTime()), "created 不可为 Invalid Date");
+    const file = join(projDir, "2026-01-01T00-00-00-000Z_noTs.jsonl");
+    writeFileSync(file, '{"type":"session","version":3,"id":"noTs","cwd":"/home/wa/project/demo"}\n');
+    assert.ok(Number.isFinite(scanFile(file).created.getTime()), "created 不可为 Invalid Date");
   } finally {
     rmSync(root, { recursive: true, force: true });
   }
 });
+test("scanSessionFileMeta：递归进子目录（forks/、<session>/<run>/run-0/），隐藏目录不扫", async () => {
+  const { root, projDir } = makeRoot();
+  try {
+    const sessionDir = join(projDir, "2026-01-01T00-00-00-000Z_aaa");
+    const forksDir = join(sessionDir, "forks");
+    const runDir = join(sessionDir, "run-1", "run-0");
+    const hiddenDir = join(projDir, ".hidden");
+    mkdirSync(forksDir, { recursive: true });
+    mkdirSync(runDir, { recursive: true });
+    mkdirSync(hiddenDir, { recursive: true });
+    writeFileSync(join(projDir, "2026-01-01T00-00-00-000Z_aaa.jsonl"), '{"type":"session","version":3,"id":"aaa","cwd":"/x"}\n');
+    writeFileSync(join(forksDir, "2026-01-01T00-10-00-000Z_fork1.jsonl"), '{"type":"session","version":3,"id":"fork1","cwd":"/x"}\n');
+    writeFileSync(join(runDir, "session.jsonl"), '{"type":"session","version":3,"id":"run1","cwd":"/x"}\n');
+    writeFileSync(join(hiddenDir, "2026-01-01T00-00-00-000Z_hidden.jsonl"), '{"type":"session","version":3,"id":"hidden","cwd":"/x"}\n');
+
+    const mod = await jiti.import("./session-scanner.ts");
+    const result = await mod.scanSessionFileMeta(root);
+    assert.deepEqual(result.map((m) => m.id).sort(), ["", "aaa", "fork1"], "三个会话文件（含子目录）；隐藏目录不算");
+    const nameless = result.find((m) => m.path.endsWith("session.jsonl"));
+    assert.equal(nameless.id, "", "没有 `<timestamp>_<id>` 前缀的名字返回空串提示，id 交给 header");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("scanSessionFileMeta：超深目录不扫（深度上限护住每轮扫描成本）", async () => {
+  const { root, projDir } = makeRoot();
+  try {
+    let deep = projDir;
+    for (let i = 0; i < 10; i += 1) deep = join(deep, `d${i}`);
+    mkdirSync(deep, { recursive: true });
+    writeFileSync(join(deep, "2026-01-01T00-00-00-000Z_deep.jsonl"), '{"type":"session","version":3,"id":"deep"}\n');
+    const mod = await jiti.import("./session-scanner.ts");
+    assert.deepEqual(await mod.scanSessionFileMeta(root), [], "超出深度上限的目录不进入扫描");
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
 test("scanOneSessionHead：只读 header + 首条消息，不含自定义名/lastReply", async () => {
   const { root, projDir } = makeRoot();
   try {

package/lib/session-scanner.ts

@@ -35,7 +35,8 @@ export interface SessionScanResult {
 const HEAD_INITIAL_BYTES = 4 * 1024;
 const HEAD_MAX_BYTES = 48 * 1024;
 // 列表里的首条消息只做简述展示（sidebar 也只截取前 50 字符）。
-const FIRST_MESSAGE_PREVIEW_LENGTH = 300;
+// 导出给事件链路（rpc-manager 回填 first_message）复用同一上限。
+export const FIRST_MESSAGE_PREVIEW_LENGTH = 300;
 
 function parseLine(line: string): unknown {
   if (!line.trim()) return null;
@@ -63,10 +64,19 @@ function extractTextContent(message: { content?: unknown }): string {
  * 首行必须是 session 头，否则视为非本应用会话文件。
  */
 function scanHead(path: string, size: number): { header: HeaderEntry; firstMessage: string } | null {
-  let readLen = Math.min(HEAD_INITIAL_BYTES, size);
-  let text = "";
-  const fd = openSync(path, "r");
+  let fd: number;
   try {
+    fd = openSync(path, "r");
+  } catch {
+    // stat 通过但 open 失败（EACCES / 被并发换成目录等）→ 当作「读不出来」。
+    // 调用方（scanOneSessionHead / scanOneSessionFile）把 null 往下传，不向上抛：
+    // 详情读取路径是 /api/sessions/summary 的「库内无行」回退，一个打不开的文件
+    // 不该让整个接口 500。
+    return null;
+  }
+  try {
+    let readLen = Math.min(HEAD_INITIAL_BYTES, size);
+    let text = "";
     let header: HeaderEntry | null = null;
     let firstMessage = "";
 
@@ -109,8 +119,16 @@ function scanHead(path: string, size: number): { header: HeaderEntry; firstMessa
       if (readLen <= 0) break;
     }
     return { header, firstMessage };
+  } catch (error) {
+    // readSync 中途失败（EIO / 文件被重写 / 块大小异常）同样降级为「读不出来」。
+    console.warn(`[pi-web] 会话头部读取失败 path=${path}:`, error instanceof Error ? error.message : String(error));
+    return null;
   } finally {
-    closeSync(fd);
+    try {
+      closeSync(fd);
+    } catch {
+      // 已关闭/句柄失效：不影响返回值
+    }
   }
 }
 
@@ -152,14 +170,22 @@ export function scanOneSessionHead(path: string): { path: string; id: string; cw
 
 /** 读取文件尾部：最后一个 session_info 的自定义名 + 最后一条 assistant 回复。
  *  同一趟反向分块里同时取两样：名字（显式清空 → undefined）、
- *  lastReply（最后一个 text 块，完整不截断）。返回 { name, lastReply }。 */
+ *  lastReply（最后一个 text 块，完整不截断）。返回 { name, lastReply }；
+ *  open/read 任何异常 → **null**（读不出来），与「读了但没有回复」的
+ *  `{ name: undefined, lastReply: "" }` 区分——调用方据此决定要不要回填。
+ *  本函数永不抛错：scanOneSessionFile 是详情读取路径，一个打不开的文件不该让整个接口 500。 */
 function scanTail(
   path: string,
   size: number,
-): { name: string | undefined; lastReply: string } {
-  const result: { name: string | undefined; lastReply: string } = { name: undefined, lastReply: "" };
-  if (size <= 0) return result;
-  const fd = openSync(path, "r");
+): { name: string | undefined; lastReply: string } | null {
+  const empty: { name: string | undefined; lastReply: string } = { name: undefined, lastReply: "" };
+  if (size <= 0) return empty;
+  let fd: number;
+  try {
+    fd = openSync(path, "r");
+  } catch {
+    return null;
+  }
   try {
     let offset = size;
     for (let block = 0; block < NAME_MAX_BLOCKS && offset > 0; block++) {
@@ -172,30 +198,58 @@ function scanTail(
       // 块首可能截断一行（前一行的后半），跳过第一行；块尾对齐 offset 完整。
       // 从后往前找本块内最后一个 session_info 与最后一条 assistant 回复。
       for (let i = lines.length - 1; i >= 1; i--) {
-        if (result.name !== undefined && result.lastReply) continue;
+        if (empty.name !== undefined && empty.lastReply) continue;
         const entry = parseLine(lines[i]) as
           | { type?: string; name?: unknown; message?: { role?: unknown; content?: unknown } }
           | null;
         if (!entry) continue;
-        if (result.name === undefined && entry.type === "session_info" && typeof entry.name === "string") {
+        if (empty.name === undefined && entry.type === "session_info" && typeof entry.name === "string") {
           const name = entry.name.trim();
-          if (name) result.name = name; // 显式清空 → undefined
-        } else if (!result.lastReply && entry.type === "message" && entry.message?.role === "assistant") {
+          if (name) empty.name = name; // 显式清空 → undefined
+        } else if (!empty.lastReply && entry.type === "message" && entry.message?.role === "assistant") {
           const reply = extractTextContent(entry.message).trim();
           // 不截断：收合卡完整展示最后一条消息（跨 64KB 块的超大回复仍可能缺块首，极端场景）
-          if (reply) result.lastReply = reply;
+          if (reply) empty.lastReply = reply;
         }
-        if (result.name !== undefined && result.lastReply) break; // 两个都拿到，收工
+        if (empty.name !== undefined && empty.lastReply) break; // 两个都拿到，收工
       }
       offset = start;
     }
-    return result;
+    return empty;
+  } catch (error) {
+    console.warn(`[pi-web] 会话尾部读取失败 path=${path}:`, error instanceof Error ? error.message : String(error));
+    return null;
   } finally {
-    closeSync(fd);
+    try {
+      closeSync(fd);
+    } catch {
+      // 已关闭/句柄失效：不影响返回值
+    }
+  }
+}
+
+/** 单文件尾部轻量读：自定义名 + 最后一条 assistant 回复（反向分块，命中即停）。
+ *  这个函数**永不抛错**：文件不存在 / 不可读（EACCES）/ 打开后又读失败（EIO、文件被重写）
+ *  / 是目录 / 为空 → null。调用方区分「读不出来」（null，保持未回填、下轮再试）与
+ *  「读了但没有回复」（lastReply 为空串）。
+ *  为什么必须吞掉 open/read 的错：扫描器的 last_reply 回填逐行调用它，一个 EACCES
+ *  逃出去就会中止整轮扫描；查询无 ORDER BY，同一行每轮都被重新命中 → 它后面的行
+ *  永远得不到回填（冷启动时还会把异常抛到 ensureSessionIndexReady → /api/sessions 500）。
+ *  这是全库唯一的尾部反向分块实现——不要再写第二份。 */
+export function readSessionTail(path: string): { name?: string; lastReply: string } | null {
+  try {
+    const stat = statSync(path);
+    if (!stat.isFile() || stat.size === 0) return null;
+    // scanTail 自身不再抛错：open/read 失败返回 null（与这里「读不出来」的语义直接对齐）。
+    return scanTail(path, stat.size);
+  } catch {
+    return null;
   }
 }
 
-/** 单个会话文件详情（阶段二按需读取：只对当前页/置顶子集调用）。 */
+/** 单个会话文件详情（阶段二按需读取：只对当前页/置顶子集调用）。
+ *  本函数永不抛错：stat / 头部 / 尾部任一读取失败都降级为 null 或空字段——
+ *  调用方是 /api/sessions/summary 的「库内无行」回退，一个打不开的文件不该 500。 */
 export function scanOneSessionFile(path: string): SessionScanResult | null {
   let stat;
   try {
@@ -214,7 +268,9 @@ export function scanOneSessionFile(path: string): SessionScanResult | null {
   const created = new Date(typeof header.timestamp === "string" ? header.timestamp : "");
   if (Number.isNaN(created.getTime())) created.setTime(stat.mtime.getTime());
 
-  const tail = scanTail(path, stat.size);
+  // 尾部读不出来（open/read 失败）→ 空结果：详情仍可展示（名字/最后回复为空），
+  // 不像 readSessionTail 那样返回 null（那里要靠 null 区分「下轮再回填」）。
+  const tail = scanTail(path, stat.size) ?? { name: undefined, lastReply: "" };
 
   return {
     path,
@@ -229,28 +285,73 @@ export function scanOneSessionFile(path: string): SessionScanResult | null {
   };
 }
 
-/** 扫描 <agentDir>/sessions 下所有 jsonl。同步小 IO 串行即可（单文件只读
- *  头部小块 + 尾部反向分块），`sessionsDir` 仅在测试时注入。
- *  全量详情版本：每个文件读头部（首条消息）与尾部（自定义名/最后回复）。
- *  侧栏聊天区已走两阶段分页（见 scanSessionFileMeta），此函数保留供
- *  全量消费方（看板标题映射 / 会话恢复 / 无分页参数调用）使用。 */
-export async function scanSessionFiles(sessionsDir?: string): Promise<SessionScanResult[]> {
-  const metas = await scanSessionFileMeta(sessionsDir);
-  const results: SessionScanResult[] = [];
-  for (const meta of metas) {
-    const scanned = scanOneSessionFile(meta.path);
-    if (scanned) results.push(scanned);
+/* 全量详情扫描（scanSessionFiles / sessionScanner.scan）已删除：读取路径全部改查
+ * session_meta，扫描器只需阶段一元数据（scanSessionFileMeta）+ 单文件详情
+ * （scanOneSessionFile）。保留全量版本会让「列表=扫盘」的旧路径随时被重新接上。 */
+
+/** 阶段一元数据：目录项 + stat 即可，不读内容。`id` 是「文件名提示」
+ *  （可能为空串——如 `session.jsonl`，此时 id 由 header 决定）。 */
+export interface SessionFileMeta {
+  path: string;
+  id: string;
+  modified: Date;
+}
+
+/** 扫描深度上限（项目目录 = 1 层）：`<project>/<session>/<runId>/run-0/session.jsonl`
+ *  只到第 4 层，6 层留余量；没有上限的话一个异常目录树能把每轮扫描拖成深递归。 */
+const MAX_SCAN_DEPTH = 6;
+
+/** 会话文件候选 id：`<...>_<id>.jsonl` 取末段（本应用的命名约定，见
+ *  session-reader 的 findSessionPathByName）；`session.jsonl` 这类没有
+ *  `<timestamp>_<id>` 形状的名字返回 ""——不猜 id，交给 header 决定。 */
+function idHintFromName(name: string): string {
+  const parts = name.slice(0, -".jsonl".length).split("_");
+  if (parts.length < 2) return "";
+  const last = parts[parts.length - 1];
+  return /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(last) && !/^[0-9]+$/.test(last) ? last : "";
+}
+
+/** 递归收集目录下的 jsonl（深度优先，串行）。
+ *  隐藏目录跳过（.git 等不可能是会话目录）；符号链接目录不跟（防环）；
+ *  单个目录不可读 → 跳过，不影响其它目录。 */
+async function walkJsonl(dir: string, depth: number, out: SessionFileMeta[]): Promise<void> {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith(".")) continue;
+    const full = joinPath(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (depth < MAX_SCAN_DEPTH) await walkJsonl(full, depth + 1, out);
+      continue;
+    }
+    if (!entry.name.endsWith(".jsonl")) continue;
+    let stat;
+    try {
+      stat = statSync(full);
+    } catch {
+      continue;
+    }
+    if (!stat.isFile() || stat.size === 0) continue;
+    out.push({ path: full, id: idHintFromName(entry.name), modified: stat.mtime });
   }
-  results.sort((a, b) => b.modified.getTime() - a.modified.getTime());
-  return results;
 }
 
 /** 阶段一元数据：只读目录项 + stat，不碰文件内容。
  *  会话文件命名 `<timestamp>_<id>.jsonl`，id 直接从文件名解析（与 header 一致，
  *  见 scanOneSessionFile 校验）；mtime 即最后活动时间（侧栏排序键）。
- *  两阶段设计：这里全量便宜拿到 id+mtime 后，调用方先按归属过滤（聊天区
- *  排除任务会话），再对需要的页/置顶子集调用 scanOneSessionFile 读详情。 */
-export async function scanSessionFileMeta(sessionsDir?: string): Promise<Array<{ path: string; id: string; modified: Date }>> {
+ *  两阶段设计：这里全量便宜拿到 id+mtime 后，扫描器按 path 匹配建行/收敛，
+ *  读取路径（列表/任务区/看板摘要）则完全不再读文件。
+ *
+ *  递归扫描：外部 pi 系工具会在项目目录下造子目录布局
+ *  （`<session>/forks/<ts>_<id>.jsonl`、`<session>/<runId>/run-0/session.jsonl`、
+ *  `subagent-artifacts/*.jsonl`）。只做一层 readdir 会让这些会话永远不进库
+ *  （列表里等于不存在）。这里向下递归到 MAX_SCAN_DEPTH，id 仍是「文件名提示」
+ *  （可能为空串，由 header 决定，见 idHintFromName）。 */
+export async function scanSessionFileMeta(sessionsDir?: string): Promise<SessionFileMeta[]> {
   const root = sessionsDir ?? joinPath(getAgentDir(), "sessions");
   let projectDirs: string[];
   try {
@@ -262,33 +363,11 @@ export async function scanSessionFileMeta(sessionsDir?: string): Promise<Array<{
     return [];
   }
 
-  const metas: Array<{ path: string; id: string; modified: Date }> = [];
+  const metas: SessionFileMeta[] = [];
   for (const dir of projectDirs) {
-    let names: string[];
-    try {
-      names = await readdir(dir);
-    } catch {
-      continue; // 单目录不可读则跳过，不影响其它目录。
-    }
-    for (const name of names) {
-      if (!name.endsWith(".jsonl")) continue;
-      const path = joinPath(dir, name);
-      let stat;
-      try {
-        stat = statSync(path);
-      } catch {
-        continue;
-      }
-      if (!stat.isFile() || stat.size === 0) continue;
-      // 文件名 `..._<id>.jsonl`：下划线后到 .jsonl 之间即 session id。
-      const id = name.slice(0, -6).split("_").pop() ?? "";
-      if (!id) continue;
-      metas.push({ path, id, modified: stat.mtime });
-    }
+    // 项目目录自身算第 1 层：`<project>/<session>/<runId>/run-0/session.jsonl` 到第 4 层。
+    await walkJsonl(dir, 1, metas);
   }
   metas.sort((a, b) => b.modified.getTime() - a.modified.getTime());
   return metas;
 }
-
-// 以对象形式暴露扫描入口，测试可替换实现（ESM 的模块绑定本身只读）。
-export const sessionScanner = { scan: scanSessionFiles };

package/lib/session-search.ts

@@ -152,8 +152,8 @@ export async function ensureSearchIndex(
 ): Promise<{ indexing: boolean }> {
   let sessions = sessionsOverride;
   if (!sessions) {
-    const { listAllSessions } = await import("./session-reader");
-    sessions = await listAllSessions();
+    const { loadAllSessionIndex } = await import("./session-reader");
+    sessions = await loadAllSessionIndex();
   }
   const db = getDb();
 
@@ -221,7 +221,7 @@ export async function searchSessions(
 ): Promise<{ indexing: boolean; results: SearchResult[] }> {
   const query = q.trim();
   if (!query) return { indexing: false, results: [] };
-  const sessions = sessionsOverride ?? (await loadAllSessions());
+  const sessions = sessionsOverride ?? (await loadIndexedSessions());
   const indexed = await ensureSearchIndex(sessions);
 
   const cap = Math.min(Math.max(limit, 1), 50);
@@ -282,9 +282,10 @@ export async function searchSessions(
   return { indexing: indexed.indexing, results };
 }
 
-async function loadAllSessions(): Promise<SessionInfo[]> {
+/** 搜索基线：session_meta 全表索引（与 /api/sessions 无参同源，纯库查询）。 */
+async function loadIndexedSessions(): Promise<SessionInfo[]> {
   // 基线吃 session_meta 索引（与 /api/sessions 无参同源）：列表重构后磁盘扫描
-  // 已不是权威数据源，这里不再整盘扫。索引 modified 由扫描器维护（≤30s 滞后），
+  // 已不是权威数据源，读取路径也不再扫盘。索引 modified 由事件链路/扫描器维护，
   // 搜索索引重建随之滞后可接受（搜索非实时）。
   const { loadAllSessionIndex } = await import("./session-reader");
   return loadAllSessionIndex();

package/lib/sqlite-db.test.mjs

@@ -189,3 +189,29 @@ test("v10 database upgrades to v11 (session_meta index columns + project index)"
   assert.equal(row.task_id, "task-1");
   assert.equal(row.pinned, 1);
 });
+
+test("schema v12：老库升级后 session_meta 有 last_reply 列，新库直接具备", () => {
+  const old = new DatabaseSync(":memory:");
+  old.exec("PRAGMA user_version = 11");
+  old.exec(
+    "CREATE TABLE session_meta (session_id TEXT PRIMARY KEY, task_id TEXT, updated INTEGER NOT NULL, pinned INTEGER NOT NULL DEFAULT 0, path TEXT, cwd TEXT, project_key TEXT, title TEXT, first_message TEXT, parent_id TEXT, created INTEGER, modified INTEGER)",
+  );
+  old.prepare(
+    "INSERT INTO session_meta (session_id, updated, modified) VALUES ('s-old', 1, 2)",
+  ).run();
+
+  initSchema(old);
+
+  const cols = old.prepare("PRAGMA table_info(session_meta)").all().map((c) => c.name);
+  assert.ok(cols.includes("last_reply"), "v12 adds session_meta.last_reply");
+  assert.equal(old.prepare("PRAGMA user_version").get().user_version, 12);
+  // 老行保留，新列默认 NULL（"还没有最后一条消息"）
+  const kept = old.prepare("SELECT session_id, last_reply FROM session_meta WHERE session_id='s-old'").get();
+  assert.equal(kept.session_id, "s-old");
+  assert.equal(kept.last_reply, null);
+  // 新库第一次建表就该有该列（老库升级与新库同构）
+  const fresh = memoryDb();
+  const freshCols = fresh.prepare("PRAGMA table_info(session_meta)").all().map((c) => c.name);
+  assert.ok(freshCols.includes("last_reply"));
+  assert.equal(fresh.prepare("PRAGMA user_version").get().user_version, 12);
+});

package/lib/sqlite-db.ts

@@ -93,7 +93,7 @@ export function initSchema(db: DatabaseSync): void {
  * 老库打开时自动按序补齐缺失的迁移（每个迁移一个事务，成功后推进版本号），
  * 新库建表后从 v0 一路迁到 SCHEMA_VERSION。重复打开不再执行已完成的迁移。
  */
-export const SCHEMA_VERSION = 11;
+export const SCHEMA_VERSION = 12;
 
 interface Migration {
   version: number;
@@ -219,6 +219,15 @@ const MIGRATIONS: Migration[] = [
       "CREATE INDEX IF NOT EXISTS idx_meta_project_modified ON session_meta(project_key, modified DESC);",
     ],
   },
+  {
+    version: 12,
+    name: "session_meta.last_reply（最后一条消息入库，列表零扫盘）",
+    statements: [
+      // 「最后一条消息」原先靠读取期读文件尾（滞后且每次列表都要摸盘）。改由事件
+      // 链路在一轮循环结束时写入（agent_settled，含取消），读取路径不再读文件。
+      "ALTER TABLE session_meta ADD COLUMN last_reply TEXT;",
+    ],
+  },
 ];
 
 function migrate(db: DatabaseSync): void {