@zhushanwen/pi-session-reader 0.1.0

package/src/core/toolcall.ts

@@ -0,0 +1,168 @@
+/**
+ * toolCall 提取与摘要的共享层（O1 工具概览 + O2/O3 toolResult 类型化摘要 + O4 extract 复用）。
+ *
+ * 数据源（probe 019e6c96 实测确认）：
+ * - 工具调用在 assistant message.content 的 `{type:"toolCall", id, name, arguments}` block（519 个），
+ *   message.toolCalls 顶层字段从未存在——v1 render.ts 读 toolCalls 恒返 [] 是 O1 要修的 bug。
+ * - arguments 始终是 object（10 工具 100%）；string 形态做 JSON.parse 兜底（失败返 {}），防御历史/异类实现。
+ * - toolResult.message 自带 toolName + toolCallId（515/515，全部匹配 toolCall.id），
+ *   parser.ts 已 additive 透出这两个字段，O2/O3 据此精确关联取参数。
+ */
+import type { Entry } from './parser.js'
+
+/** 单次工具调用信息（从 assistant content 的 toolCall block 提取）。 */
+export interface ToolCallInfo {
+  id: string
+  name: string
+  arguments: Record<string, unknown>
+}
+
+/** 截断到 max 字符，超出加省略号（与 render.ts 的 truncate 同口径）。 */
+function truncate(s: string, max: number): string {
+  return s.length <= max ? s : s.slice(0, max) + '…'
+}
+
+/** 路径最后一段（去尾部斜杠后取 basename）。 */
+export function basename(path: string): string {
+  const clean = path.replace(/\/+$/, '')
+  const idx = clean.lastIndexOf('/')
+  return idx >= 0 ? clean.slice(idx + 1) : clean
+}
+
+/**
+ * 把 toolCall block 的 arguments 归一化为 Record<string, unknown>。
+ * - object（非数组、非 null）→ 原样用
+ * - string → JSON.parse 兜底（parse 失败或结果非对象 → {}）
+ * - 其他（number/boolean/null/undefined/数组）→ {}（实测 0%，纯防御）
+ */
+function coerceArgs(raw: unknown): Record<string, unknown> {
+  if (raw !== null && typeof raw === 'object' && !Array.isArray(raw)) {
+    return raw as Record<string, unknown>
+  }
+  if (typeof raw === 'string') {
+    try {
+      const parsed: unknown = JSON.parse(raw)
+      if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        return parsed as Record<string, unknown>
+      }
+    } catch {
+      // 非法 JSON 字符串 → 空对象兜底（实测 arguments 全为 object，此分支纯防御）
+    }
+  }
+  return {}
+}
+
+/**
+ * 从 entry.message.content 的 `{type:"toolCall"}` block 提取工具调用列表。
+ *
+ * content 是 unknown 做类型守卫；非数组或无 toolCall block 返 []。
+ * 仅纳入 id + name 均为 string 的 block（O2 靠 id 关联 toolResult，O1 靠 name 聚合；
+ * 缺 id 的块无法关联，缺 name 无法摘要，跳过——实测 0 缺失）。
+ */
+export function extractToolCalls(entry: Entry): ToolCallInfo[] {
+  const msg = entry.message
+  if (msg === undefined) return []
+  const content = msg.content
+  if (!Array.isArray(content)) return []
+  const out: ToolCallInfo[] = []
+  for (const block of content) {
+    if (block === null || typeof block !== 'object') continue
+    const b = block as Record<string, unknown>
+    if (b.type !== 'toolCall') continue
+    if (typeof b.id !== 'string' || typeof b.name !== 'string') continue
+    out.push({ id: b.id, name: b.name, arguments: coerceArgs(b.arguments) })
+  }
+  return out
+}
+
+/** 取 args[k] 为 string，否则 undefined（参数缺失统一入口）。 */
+function strArg(args: Record<string, unknown>, k: string): string | undefined {
+  const v = args[k]
+  return typeof v === 'string' ? v : undefined
+}
+
+/** 取 args[k] 为 number，否则 undefined。 */
+function numArg(args: Record<string, unknown>, k: string): number | undefined {
+  const v = args[k]
+  return typeof v === 'number' ? v : undefined
+}
+
+/**
+ * 按工具类型把 ToolCallInfo 映射成参数摘要串（design §3.3 D1 表）。
+ *
+ * 参数缺失时优雅降级（只输出工具名或省略对应维度）。未知工具 fallback 带 arguments JSON
+ * 前 50 字；arguments 为空对象时省略 JSON（`{}` 无信息量）。
+ *
+ * 单位口径：edit 的 blocks 是参数维度（edits 数组长度），write 的 KB 是参数维度（content 字节），
+ * 这两者已含参数规模；O2/O3 的 toolResult 摘要在此基础再加结果规模时，bash/read 单独 append
+ * 结果行数/KB（见 render.ts 的 formatToolResultSummary），避免与参数规模重复。
+ */
+export function formatToolCallSummary(tc: ToolCallInfo): string {
+  const { name, arguments: args } = tc
+
+  switch (name) {
+    case 'bash': {
+      const cmd = strArg(args, 'command')
+      return cmd !== undefined ? `bash: ${truncate(cmd, 60)}` : 'bash'
+    }
+    case 'read': {
+      const p = strArg(args, 'path')
+      return p !== undefined ? `read: ${basename(p)}` : 'read'
+    }
+    case 'edit': {
+      const p = strArg(args, 'path')
+      const edits = args.edits
+      const blocks = Array.isArray(edits) ? edits.length : undefined
+      const head = p !== undefined ? `edit: ${basename(p)}` : 'edit'
+      return blocks !== undefined ? `${head} (${blocks} blocks)` : head
+    }
+    case 'write': {
+      const p = strArg(args, 'path')
+      const c = strArg(args, 'content')
+      const head = p !== undefined ? `write: ${basename(p)}` : 'write'
+      if (c === undefined) return head
+      // utf8 字节转 KB 取整；小文件至少 1KB（0KB 无信息量）
+      const kb = Math.max(1, Math.round(Buffer.byteLength(c, 'utf8') / 1024))
+      return `${head} (${kb}KB)`
+    }
+    case 'subagent': {
+      const task = strArg(args, 'task')
+      return task !== undefined ? `subagent: ${truncate(task, 40)}` : 'subagent'
+    }
+    case 'head': {
+      const p = strArg(args, 'path')
+      // limit 可能是 number 或 string（实测 number，防御 string）
+      const lim: number | string | undefined = numArg(args, 'limit') ?? strArg(args, 'limit')
+      const head = p !== undefined ? `head: ${basename(p)}` : 'head'
+      return lim !== undefined ? `${head} (${lim})` : head
+    }
+    case 'todo': {
+      const action = strArg(args, 'action')
+      if (action === undefined) return 'todo'
+      // id 可能是 number（todo 列表 id）或 string
+      const id = args.id
+      const idStr =
+        typeof id === 'string' ? id : typeof id === 'number' ? String(id) : undefined
+      return idStr !== undefined ? `todo: ${action}(${idStr})` : `todo: ${action}`
+    }
+    case 'coding-workflow-gate': {
+      const phase = args.phase
+      return phase !== undefined ? `cw-gate: phase=${String(phase)}` : 'cw-gate'
+    }
+    case 'coding-workflow-init': {
+      const slug = strArg(args, 'slug')
+      return slug !== undefined ? `cw-init: ${slug}` : 'cw-init'
+    }
+    case 'coding-workflow-phase-start':
+      return 'cw-phase-start'
+    default: {
+      // 未知工具：arguments 非空 → name: <json 前50>；空对象 → 仅 name（{} 无信息量）
+      if (Object.keys(args).length === 0) return name
+      try {
+        return `${name}: ${truncate(JSON.stringify(args), 50)}`
+      } catch {
+        return name
+      }
+    }
+  }
+}

package/src/core/tree.ts

@@ -0,0 +1,93 @@
+import type { Entry } from './parser.js'
+
+export interface TreeView {
+  /** root → leaf 的 id 序列（pi 重开视角的当前对话线，design D-2） */
+  leafPath: string[]
+  /** forkPointId(=leafPath 上某节点 id) → 该分叉下旁支子树的 entry 数 */
+  branches: Map<string, number>
+  /** parentId 指向不存在 entry、且自身不在 leafPath 上的 entry id */
+  orphans: string[]
+}
+
+/**
+ * 沿祖先链找最近的、属于 leafSet 的分叉点。
+ * 返回 null：祖先链触不到 leafSet（多 root 独立子树）或检测到环。
+ *
+ * 计算旁支子树大小：对每个非主链 entry 沿祖先链归到最近 leafSet 节点计数（design §3.5
+ * 算法 2 步骤 5「按 forkPoint 聚合子树大小」）。如 A→D→E 旁支（D、E 都挂在 forkPoint A
+ * 下）count=2，而非只数直接子节点。
+ */
+function findForkPoint(
+  startId: string | null,
+  index: Map<string, Entry>,
+  leafSet: Set<string>,
+): string | null {
+  let cur = startId
+  const seen = new Set<string>()
+  while (cur !== null && index.has(cur) && !leafSet.has(cur)) {
+    if (seen.has(cur)) return null // 环防御（坏数据）
+    seen.add(cur)
+    cur = index.get(cur)!.parentId
+  }
+  if (cur !== null && leafSet.has(cur)) return cur
+  return null
+}
+
+/**
+ * 按 design §3.5 算法 2 重建 leaf 路径视图。
+ *
+ * leafId = entries 最后一条的 id（D-2：pi 重开时把 leafId 重置为文件最后 entry，
+ * 即用户 resume 看到的对话线）。从 leafId 沿 parentId 回溯到 root，遇 parentId 不在
+ * 索引（断点/孤儿 root）即停。
+ *
+ * orphans 只收集「不在 leafPath 上 + parentId 指向不存在」的 entry；leafPath 根自身
+ * 即使 parentId 断（断点处）也不重复计入——它已有归属（主链根），符合「孤儿=无归属」语义。
+ * design 步骤 6 字面未排除 leafPath 节点，此处按语义实现。
+ */
+export function buildTreeView(entries: Entry[]): TreeView {
+  const leafPath: string[] = []
+  const branches = new Map<string, number>()
+  const orphans: string[] = []
+
+  if (entries.length === 0) {
+    return { leafPath, branches, orphans }
+  }
+
+  // 1. id→entry 索引（同 id 后写覆盖先写）
+  const index = new Map<string, Entry>()
+  for (const e of entries) index.set(e.id, e)
+
+  // 2. leafId = 最后一条 entry 的 id
+  const leafId = entries[entries.length - 1].id
+
+  // 3. 从 leafId 沿 parentId 回溯到 root
+  let cur: string | null = leafId
+  const backtrackSeen = new Set<string>()
+  while (cur !== null && index.has(cur)) {
+    if (backtrackSeen.has(cur)) break // 环防御
+    backtrackSeen.add(cur)
+    leafPath.unshift(cur)
+    cur = index.get(cur)!.parentId
+  }
+
+  // 4. leafSet
+  const leafSet = new Set(leafPath)
+
+  // 5-6. 旁支计数 + 孤儿收集
+  for (const e of entries) {
+    if (leafSet.has(e.id)) continue // 主链节点
+    const pid = e.parentId
+    if (pid === null) continue // 独立 root（多 root 边界）：不在当前 leaf 视图，不计旁支不计孤儿
+    if (!index.has(pid)) {
+      orphans.push(e.id)
+      continue
+    }
+    const fp = findForkPoint(pid, index, leafSet)
+    if (fp !== null) {
+      branches.set(fp, (branches.get(fp) ?? 0) + 1)
+    }
+    // fp===null：祖先链触不到 leafSet（多 root 独立子树），静默忽略
+  }
+
+  return { leafPath, branches, orphans }
+}

package/src/core/turns.ts

@@ -0,0 +1,97 @@
+import type { Entry } from './parser.js'
+
+/**
+ * 一轮对话（design §3.5 算法 3 的分段产物，冻结接口）。
+ *
+ * - user turn：由 user message 开启，userEntry 指向该 user entry，isCompaction=false。
+ * - compaction turn：由 compaction entry 开启（语义断点），无 userEntry，isCompaction=true。
+ * - 前置 turn（preface）：首条 user/compaction 之前出现的 rule-4 entry
+ *  （assistant / model_change / thinking_level_change / custom / branch_summary）无处并入时
+ *   单独成 turn 0，无 userEntry，isCompaction=false。
+ */
+export interface Turn {
+  index: number
+  startTime?: string
+  /** 该 turn 全部 entry（含开启条 user/compaction + 后续并入条） */
+  entries: Entry[]
+  /** turn 起点；compaction turn 与前置 turn 无 userEntry */
+  userEntry?: Entry
+  isCompaction: boolean
+}
+
+/**
+ * 按 design §3.5 算法 3 把 leaf 视图 entry 序列分段为 turn。
+ *
+ * 严格按优先级（先命中先生效）：
+ * 1. `session` header → 忽略，不计 turn
+ * 2. `compaction` → 关闭当前 turn，开新 turn（isCompaction=true，无 userEntry）
+ * 3. `message` role=user → 关闭当前 turn，开新 turn（userEntry=user）
+ * 4. 其余（assistant/toolResult/custom/model_change/thinking_level_change/branch_summary
+ *    等一切非上述类型）→ 并入当前 turn
+ * 5. branch 边界：entry.id ∉ leafSet → 直接跳过（归旁支，不计 leaf 视图 turn）
+ *
+ * 孤儿处理：rule-4 entry 在首条 user/compaction 之前出现（无 current turn）→ 单独成「前置」turn。
+ * index 从 0 连续递增。空 entries（或 leafSet 全空）→ 返回 []。
+ */
+export function segmentTurns(entries: Entry[], leafSet: Set<string>): Turn[] {
+  const turns: Turn[] = []
+  let current: Turn | null = null
+
+  const closeCurrent = (): void => {
+    if (current !== null) {
+      turns.push(current)
+      current = null
+    }
+  }
+
+  for (const entry of entries) {
+    // 规则 1：session header 忽略
+    if (entry.type === 'session') continue
+    // 规则 5：branch 边界——不在 leaf 视图，跳过
+    if (!leafSet.has(entry.id)) continue
+
+    if (entry.type === 'compaction') {
+      // 规则 2：compaction 是语义断点，关闭当前并开新 compaction turn
+      closeCurrent()
+      current = {
+        index: 0,
+        entries: [entry],
+        isCompaction: true,
+      }
+      if (entry.timestamp !== undefined) current.startTime = entry.timestamp
+    } else if (
+      entry.type === 'message' &&
+      entry.message !== undefined &&
+      entry.message.role === 'user'
+    ) {
+      // 规则 3：user 开启新 turn
+      closeCurrent()
+      current = {
+        index: 0,
+        entries: [entry],
+        userEntry: entry,
+        isCompaction: false,
+      }
+      if (entry.timestamp !== undefined) current.startTime = entry.timestamp
+    } else {
+      // 规则 4：并入当前 turn；无 current（孤儿前置）则单独成 preface turn
+      if (current === null) {
+        current = {
+          index: 0,
+          entries: [entry],
+          isCompaction: false,
+        }
+        if (entry.timestamp !== undefined) current.startTime = entry.timestamp
+      } else {
+        current.entries.push(entry)
+      }
+    }
+  }
+  closeCurrent()
+
+  // index 从 0 连续递增（分段过程中先占位 0，最后统一赋值）
+  for (let i = 0; i < turns.length; i++) {
+    turns[i].index = i
+  }
+  return turns
+}

package/src/discovery/find.ts

@@ -0,0 +1,247 @@
+import { createReadStream, type ReadStream } from 'node:fs'
+import { open, type FileHandle } from 'node:fs/promises'
+import { createInterface } from 'node:readline'
+import type { SessionRef } from '../core/family.js'
+import { listMainSessions, type SessionFileMeta } from './roots.js'
+
+/**
+ * M2 discovery 发现层：按 query 定位 session（design §3.3 D-3 + §3.4 find action）。
+ *
+ * 匹配三路（D-3）：
+ * - uuid 片段子串：sessionId 含 query，或文件路径含 query
+ * - "recent" 特殊值：按 mtime 倒序返回最近 N 个（不经片段匹配）
+ * - 名称关键词：首消息预览含 query（fallback，仅在 uuid 片段零匹配且 query 非 uuid 特征时
+ *   对候选深读首消息——D-5：不为定位付全文解析成本）
+ *
+ * 首行扫描策略（D-5）：先全量首行扫描拿 header（id/cwd/parentSession），不做全文解析；
+ * 首消息预览仅在需要时（recent/uuid 匹配的最终结果 + 关键词 fallback）对候选单独深读。
+ *
+ * agentDir 注入：同 roots.ts，零 pi 依赖（仅 node:fs + 相对 import M1 core）。
+ */
+
+export interface MatchedSession extends SessionRef {
+  /** 首条 user message text 截 80 字符（从全文读，不只首行） */
+  firstMessagePreview?: string
+}
+
+const DEFAULT_LIMIT = 20
+const PREVIEW_MAX = 80
+/** readFirstLine 单次读取 buffer 上限。session header（id/cwd/parentSession）远小于此。 */
+const HEADER_READ_BYTES = 8192
+
+/**
+ * 读文件首行（header）。用定长 buffer 一次 read（避免 stream 开销），
+ * 空文件/读失败返回 undefined。header 超 8KB 的极端情况会截断致 parse 失败——
+ * session header（id+cwd）实测 < 300 字节，8KB 足够 27 倍余量。
+ */
+async function readFirstLine(path: string): Promise<string | undefined> {
+  let fh: FileHandle | undefined
+  try {
+    fh = await open(path, 'r')
+    const buf = Buffer.alloc(HEADER_READ_BYTES)
+    const { bytesRead } = await fh.read(buf, 0, HEADER_READ_BYTES, 0)
+    if (bytesRead === 0) return undefined
+    const content = buf.subarray(0, bytesRead).toString('utf8')
+    const nl = content.indexOf('\n')
+    return nl === -1 ? content : content.slice(0, nl)
+  } catch {
+    return undefined
+  } finally {
+    await fh?.close().catch(() => {})
+  }
+}
+
+/** 从单行 JSON 提取 message entry 的 user role 文本，非 user message 行返回 undefined。 */
+function extractUserText(line: string): string | undefined {
+  let raw: unknown
+  try {
+    raw = JSON.parse(line)
+  } catch {
+    return undefined
+  }
+  if (typeof raw !== 'object' || raw === null) return undefined
+  const obj = raw as Record<string, unknown>
+  if (obj.type !== 'message') return undefined
+  const msg = obj.message
+  if (typeof msg !== 'object' || msg === null) return undefined
+  const m = msg as Record<string, unknown>
+  if (m.role !== 'user') return undefined
+  return extractTextFromContent(m.content)
+}
+
+/**
+ * 从 message content 提取可读文本。
+ * 兼容 pi 两种形态：string content（直接用）与 array content（拼 type:text 项的 text）。
+ */
+function extractTextFromContent(content: unknown): string | undefined {
+  if (typeof content === 'string') return content
+  if (Array.isArray(content)) {
+    const parts: string[] = []
+    for (const item of content) {
+      if (typeof item === 'object' && item !== null) {
+        const it = item as Record<string, unknown>
+        if (it.type === 'text' && typeof it.text === 'string') {
+          parts.push(it.text)
+        }
+      }
+    }
+    return parts.length > 0 ? parts.join(' ') : undefined
+  }
+  return undefined
+}
+
+/**
+ * 读文件首条 user message 的文本。逐行扫描直到命中 role:user（不读全文，命中即停 stream）。
+ * 用于名称关键词匹配 + firstMessagePreview 填充。
+ */
+async function readFirstUserMessageText(path: string): Promise<string | undefined> {
+  let stream: ReadStream | undefined
+  try {
+    stream = createReadStream(path, { encoding: 'utf8' })
+    const rl = createInterface({ input: stream, crlfDelay: Infinity })
+    try {
+      for await (const line of rl) {
+        const text = extractUserText(line)
+        if (text !== undefined) return text
+      }
+    } finally {
+      rl.close()
+    }
+    return undefined // 无 user message（如纯 compaction session）
+  } catch {
+    return undefined
+  } finally {
+    stream?.destroy()
+  }
+}
+
+interface SessionHeader {
+  id: string
+  cwd?: string
+  parentSession?: string
+}
+
+/** 解析 header 首行为 SessionHeader。非 session 行/缺 id → null。 */
+function parseHeader(line: string | undefined): SessionHeader | null {
+  if (!line) return null
+  let raw: unknown
+  try {
+    raw = JSON.parse(line)
+  } catch {
+    return null
+  }
+  if (typeof raw !== 'object' || raw === null) return null
+  const obj = raw as Record<string, unknown>
+  if (obj.type !== 'session' || typeof obj.id !== 'string') return null
+  const header: SessionHeader = { id: obj.id }
+  if (typeof obj.cwd === 'string') header.cwd = obj.cwd
+  if (typeof obj.parentSession === 'string') header.parentSession = obj.parentSession
+  return header
+}
+
+/**
+ * query 是否具备 uuid 片段特征（仅十六进制字符与连字符）。
+ * 用于 uuid 片段零匹配时决定是否走名称关键词 fallback：纯十六进制 query（如 e6c96、019fe635）
+ * 几乎不会出现在自然语言首消息里，深读首消息徒劳，跳过；含非十六进制字符的 query（如 plugin、
+ * 重构）才走 fallback。边界词（如 abc，恰好全十六进制）会被判 uuid 特征不走 fallback——
+ * 可接受（abc 作为首消息关键词罕见，且 uuid 片段匹配已先尝试）。
+ */
+function looksLikeUuidFragment(query: string): boolean {
+  return /^[0-9a-f-]+$/i.test(query)
+}
+
+interface Candidate {
+  meta: SessionFileMeta
+  ref: SessionRef
+}
+
+interface Matched extends Candidate {
+  /** 名称关键词匹配路径已读出的预览；recent/uuid 路径 undefined，后续按需补读 */
+  preview?: string
+}
+
+/**
+ * 按 query 找 session（接口冻结，design §3.4 find action）。
+ *
+ * 返回按 mtime 倒序，limit 截断（默认 20），truncated 标记是否截断。
+ * cwd 过滤：opts.cwd 提供时只留 header.cwd === opts.cwd 的（在匹配前过滤，减少 fallback 深读量）。
+ * 匹配为空 → `{ matches: [], truncated: false }`（F1 恢复指引在 M3 tool-adapter 层）。
+ */
+export async function findSessions(
+  query: string,
+  agentDir: string,
+  opts?: { cwd?: string; limit?: number },
+): Promise<{ matches: MatchedSession[]; truncated: boolean }> {
+  const limit = opts?.limit ?? DEFAULT_LIMIT
+  const cwdFilter = opts?.cwd
+  const files = await listMainSessions(agentDir)
+
+  // 1. 首行扫描所有文件拿 header，建候选 SessionRef（cwd 过滤在此应用）
+  const candidates: Candidate[] = []
+  for (const meta of files) {
+    const headerLine = await readFirstLine(meta.path)
+    const header = parseHeader(headerLine)
+    if (!header) continue // 非 session 文件/坏 header → 跳过
+    if (cwdFilter !== undefined && (header.cwd ?? '') !== cwdFilter) continue
+    const ref: SessionRef = {
+      sessionId: header.id,
+      // 完整绝对路径（与 parentSession 同构，便于 family 按 includes(sid) 反查）
+      fileName: meta.path,
+      mtime: meta.mtime,
+      sizeBytes: meta.size,
+      cwd: header.cwd ?? '',
+    }
+    if (header.parentSession) ref.parentSession = header.parentSession
+    candidates.push({ meta, ref })
+  }
+
+  // 2. 匹配
+  let matched: Matched[]
+  if (query === 'recent') {
+    // recent：不经片段匹配，全部候选按 mtime 倒序后截 limit
+    matched = candidates.map((c) => ({ ...c }))
+  } else {
+    // 先 uuid 片段匹配（sessionId 或文件路径含 query）——cheap，已有 header
+    const uuidHits = candidates.filter(
+      (c) => c.ref.sessionId.includes(query) || c.meta.path.includes(query),
+    )
+    if (uuidHits.length > 0) {
+      matched = uuidHits.map((c) => ({ ...c }))
+    } else if (looksLikeUuidFragment(query)) {
+      // query 像 uuid 片段但无匹配 → uuid 写错的可能性高，不对全部候选深读首消息
+      matched = []
+    } else {
+      // 名称关键词 fallback：读所有候选首消息，预览含 query 入选
+      const keywordHits: Matched[] = []
+      for (const c of candidates) {
+        const text = await readFirstUserMessageText(c.meta.path)
+        if (text && text.includes(query)) {
+          keywordHits.push({ ...c, preview: text.slice(0, PREVIEW_MAX) })
+        }
+      }
+      matched = keywordHits
+    }
+  }
+
+  // 3. mtime 倒序
+  matched.sort((a, b) => b.ref.mtime - a.ref.mtime)
+
+  // 4. 截断
+  const truncated = matched.length > limit
+  const sliced = truncated ? matched.slice(0, limit) : matched
+
+  // 5. 填 firstMessagePreview（recent/uuid 路径未读，这里对最终 limit 个补读——最多 limit 个 IO）
+  const result: MatchedSession[] = []
+  for (const m of sliced) {
+    const out: MatchedSession = { ...m.ref }
+    if (m.preview !== undefined) {
+      out.firstMessagePreview = m.preview
+    } else {
+      const text = await readFirstUserMessageText(m.meta.path)
+      if (text) out.firstMessagePreview = text.slice(0, PREVIEW_MAX)
+    }
+    result.push(out)
+  }
+
+  return { matches: result, truncated }
+}