@zhushanwen/pi-session-reader 0.5.1 → 0.6.1

package/src/discovery/find.ts

@@ -1,15 +1,27 @@
 import { createReadStream, type ReadStream } from 'node:fs'
-import { open, stat, type FileHandle } from 'node:fs/promises'
+import { stat } from 'node:fs/promises'
 import { createInterface } from 'node:readline'
 import { basename, dirname } from 'node:path'
 import type { SessionRef } from '../core/family.js'
+import { textBlockParts } from '../core/render.js'
 import {
   resolveSessionRoots,
   type SessionFileMeta,
   type SessionRoot,
   type SessionRootSignals,
 } from './roots.js'
-import { listRecordManifests, extractSessionIdFromFilename, type RecordManifest } from './subagents.js'
+// 首行 header 读取/解析在 discovery/session-header.ts（D5 单源）。
+import {
+  parseSessionHeader,
+  readSessionHeaderFirstLine,
+  type SessionHeader,
+} from './session-header.js'
+import {
+  listRecordManifests,
+  extractSessionIdFromFilename,
+  readTailIdentity,
+  type RecordManifest,
+} from './subagents.js'
 
 /**
  * M2 discovery 发现层：按 query 定位 session（design §3.3 D-3 + §3.4 find action）。
@@ -59,8 +71,8 @@ export interface SessionMetadataEntry {
   cwd: string
   /** 用户标题（session_info entry 的 name）；旧 session 缺失 */
   name?: string
-  /** pi 返回 Date，测试替身可传 number */
-  modified: Date | number
+  /** pi 返回 Date（A4 收窄：原 `Date | number` 宽联合只服务测试替身，替身改传 Date） */
+  modified: Date
   /** 首消息全文（title 命中时填充 firstMessagePreview，免二次读文件） */
   firstMessage?: string
 }
@@ -74,30 +86,6 @@ export type SessionMetadataProvider = (dir: string) => Promise<SessionMetadataEn
 
 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 {
@@ -120,22 +108,12 @@ function extractUserText(line: string): string | undefined {
 /**
  * 从 message content 提取可读文本。
  * 兼容 pi 两种形态：string content（直接用）与 array content（拼 type:text 项的 text）。
+ * E11 归一：共享核 textBlockParts 组合调用，' ' join 与零 text 块返 undefined 的语义
+ * 留在本调用点（find 匹配把 undefined 当「无文本」信号，空串会被 includes('') 误吸）。
  */
 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
+  const parts = textBlockParts(content)
+  return parts.length > 0 ? parts.join(' ') : undefined
 }
 
 /**
@@ -163,30 +141,6 @@ async function readFirstUserMessageText(path: string): Promise<string | undefine
   }
 }
 
-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
-}
-
 /**
  * uuid 归一化键（design 2026-09-10 §6.7 子决策 1）：小写 + 去连字符。
  * 修复 §3.3 的两个盲区——大写 uuid（String.includes 大小写敏感）与去连字符 uuid
@@ -230,59 +184,6 @@ interface Matched extends Candidate {
 // U5：subagent task/slug/agentName 匹配（manifest 索引 + P-fallback identity 回退）
 // ============================================================
 
-/** P-fallback 尾行 identity 读取窗口（同 subagents.ts，task 文本可达数 KB）。 */
-const TAIL_READ_BYTES = 65536
-
-/**
- * 读 subagent 文件尾部（最后 64KB）找 subagent-identity entry，返回 task/slug/agent。
- *
- * find 的 P-fallback 路径（场景 A：subagent 无 manifest，本机 11.5%）：manifest 索引未命中时
- * 读尾行 identity 取 task/slug/agent 做 query 子串匹配。与 subagents.ts 的 readTailIdentity
- * 同源（64KB 窗口 + lastIndexOf 定位），但是 find 专用最小版（只取 task/slug/agent，不要
- * rootSessionId——find 候选已有 header.id）。不导出，不碰 subagents.ts（w3 冻结）。
- */
-async function readTailIdentityForMatch(
-  path: string,
-  size: number,
-): Promise<{ task?: string; slug?: string; agent?: string } | undefined> {
-  if (size === 0) return undefined
-  let fh: FileHandle | undefined
-  try {
-    fh = await open(path, 'r')
-    const len = Math.min(TAIL_READ_BYTES, size)
-    const buf = Buffer.alloc(len)
-    await fh.read(buf, 0, len, Math.max(0, size - len))
-    const text = buf.toString('utf8')
-    const idx = text.lastIndexOf('subagent-identity')
-    if (idx < 0) return undefined
-    const lineStartSearch = text.lastIndexOf('\n', idx)
-    if (lineStartSearch < 0 && size > len) return undefined
-    const start = lineStartSearch < 0 ? 0 : lineStartSearch + 1
-    let end = text.indexOf('\n', idx)
-    if (end < 0) end = text.length
-    const line = text.slice(start, end)
-    let raw: unknown
-    try {
-      raw = JSON.parse(line)
-    } catch {
-      return undefined
-    }
-    const data = (raw as Record<string, unknown> | undefined)?.data as
-      | Record<string, unknown>
-      | undefined
-    if (!data) return undefined
-    return {
-      task: typeof data.task === 'string' ? data.task : undefined,
-      slug: typeof data.slug === 'string' ? data.slug : undefined,
-      agent: typeof data.agent === 'string' ? data.agent : undefined,
-    }
-  } catch {
-    return undefined
-  } finally {
-    await fh?.close().catch(() => {})
-  }
-}
-
 /**
  * 建 sessionId→RecordManifest 索引（U5：subagent task/slug/agentName 匹配用）。
  *
@@ -325,8 +226,11 @@ async function matchSubagentMetadata(
       (manifest.agentName?.includes(query) ?? false)
     )
   }
-  // P-fallback：manifest 索引未命中 → 读尾行 identity 回退
-  const ident = await readTailIdentityForMatch(candidate.meta.path, candidate.meta.size)
+  // P-fallback：manifest 索引未命中 → 读尾行 identity 回退。E8（ext-simplify-04）：
+  // 复用 subagents.ts 的 readTailIdentity 单实现，取 task/slug/agent 子集。行为差异 =
+  // 缺 rootSessionId 的畸形 identity 行从「可匹配」变「不匹配」（m0 契约外数据，
+  // design §3.3 E8 登记为可接受）。
+  const ident = await readTailIdentity(candidate.meta.path, candidate.meta.size)
   if (!ident) return false
   return (
     (ident.task?.includes(query) ?? false) ||
@@ -362,9 +266,9 @@ function buildCandidate(
  *
  * u11 起直接消费 resolveSessionRoots 的根列表（单次实扫，files 与根归属信息同批产出——
  * 标题窄化策略需要「扫描结果无子目录的候选根」这一根级事实，薄包装的扁平列表给不出）。
- * 对只含 agentDir 的信号包，根集合 = [default]+[legacy]+[subagent]，与旧薄包装
- * listMainSessions/listSubagentSessions 的并集逐文件一致（含 workflow-state 跳过与
- * realpath 去重语义）；传 liveSessionDir 时按 §6.1 追加 [live] 根（realpath 去重保优先级）。
+ * 对只含 agentDir 的信号包，根集合 = [default]+[legacy]+[subagent]，与已删除薄包装
+ * listMainSessions/listSubagentSessions（ext-simplify-04 U4/A3）原并集逐文件一致（含
+ * workflow-state 跳过与 realpath 去重语义）；传 liveSessionDir 时按 §6.1 追加 [live] 根（realpath 去重保优先级）。
  */
 async function collectCandidates(
   roots: SessionRoot[],
@@ -376,7 +280,7 @@ async function collectCandidates(
     if (root.dedupedInto !== undefined) continue // 被去重根未实扫（files 恒空），不产候选
     if (sourceFilter !== undefined && root.source !== sourceFilter) continue
     for (const meta of root.files) {
-      const header = parseHeader(await readFirstLine(meta.path))
+      const header = parseSessionHeader(await readSessionHeaderFirstLine(meta.path))
       if (!header) continue // 非 session 文件/坏 header → 跳过
       if (cwdFilter !== undefined && (header.cwd ?? '') !== cwdFilter) continue
       candidates.push(buildCandidate(meta, header, root.source))
@@ -409,11 +313,6 @@ async function pathExistsDir(path: string): Promise<boolean> {
   }
 }
 
-/** 条目 modified 的可比数值（pi 返回 Date，测试替身可传 number）。 */
-function modifiedOf(e: SessionMetadataEntry): number {
-  return typeof e.modified === 'number' ? e.modified : e.modified.getTime()
-}
-
 /**
  * 平铺目录判据（§6.6 调用策略 ②）：本根实扫出的全部 .jsonl 都直接位于根本身
  *（即扫描结果无子目录）。listAll(dir) 实装语义是「只扫一层平铺目录」——平铺根意味着
@@ -428,7 +327,7 @@ function isFlatRoot(root: SessionRoot): boolean {
  * 加载标题元数据索引（u11）。仅 keyword 路径调用（惰性触发：uuid 精确/归一化两级零命中
  * 且 query 非纯 hex 才到达此处，§6.6 调用策略 ①）。
  *
- * 窄化目标（策略 ②，按序）：未剥层 liveSessionDir 本身（xyz-agent 下即平铺主根；纯 pi 下
+ * 窄化目标（策略 ②，按序）：未剥层 liveSessionDir 本身（taiji 下即平铺主根；纯 pi 下
  * 即当前 cwd 目录，小）+ 实扫结果无子目录的候选根。两条 guard：
  * - 仅对存在的根/目录调用（root.exists / stat liveSessionDir），且永传非空串——pi 的
  *   listAll 对空串 falsy 走默认全盘分支（数千项 / 秒级，hash-provider.ts 空参灾难先例）；
@@ -467,7 +366,7 @@ async function loadTitleIndex(ctx: MetadataContext): Promise<Map<string, Session
     }
     for (const e of entries) {
       const prev = index.get(e.id)
-      if (prev === undefined || modifiedOf(e) > modifiedOf(prev)) index.set(e.id, e)
+      if (prev === undefined || e.modified.getTime() > prev.modified.getTime()) index.set(e.id, e)
     }
   }
   return index
@@ -590,7 +489,7 @@ async function loadRecentTitles(
     }
     for (const e of entries) {
       const prev = titles.get(e.id)
-      if (prev === undefined || modifiedOf(e) > modifiedOf(prev)) titles.set(e.id, e)
+      if (prev === undefined || e.modified.getTime() > prev.modified.getTime()) titles.set(e.id, e)
     }
   }
   return titles
@@ -658,6 +557,12 @@ async function fillFirstMessagePreviews(
  *   去重）并作标题窄化目标；缺省 = 现状三根降级行为。
  * - opts.metadataProvider：标题元数据注入（仅 keyword 路径 + recent 截断后补充消费）；
  *   缺省 = undefined = 现状行为（标题检索不可用，首条 user 匹配不受影响）。
+ *
+ * E1 预解析根复用（ext-simplify-04 §3 D1）：opts.roots = 调用方预解析的根列表——同一
+ * 次 doFind 内多段查询（分组 main/subagent 两路）复用同一次根解析，目录扫描不随查询
+ * 段数翻倍。缺省 = 本函数自解析（既有测试与单段调用方零改动）。调用方须保证传入的
+ * roots 来自无 options 的 resolveSessionRoots 实扫（预解析是复用同一次实扫——根扫描
+ * 无缓存，doctor 缓存机已删除，ext-simplify-04 U3）。
  */
 export async function findSessions(
   query: string,
@@ -668,18 +573,21 @@ export async function findSessions(
     source?: SessionSource
     liveSessionDir?: string
     metadataProvider?: SessionMetadataProvider
+    /** 预解析根列表（E1/D1）：提供则跳过内部 resolveSessionRoots，直接消费 */
+    roots?: SessionRoot[]
   },
 ): Promise<{ matches: MatchedSession[]; truncated: boolean }> {
   const limit = opts?.limit ?? DEFAULT_LIMIT
   const cwdFilter = opts?.cwd
   const sourceFilter = opts?.source
 
-  // 0. 根解析（单次实扫，无 options——find 不读 doctor 缓存，§7B 要点 8 PS-14）
+  // 0. 根解析（单次实扫，无 options——根扫描无缓存）；
+  // E1：调用方已预解析（opts.roots）时复用，不再自扫
   const signals: SessionRootSignals =
     opts?.liveSessionDir !== undefined && opts.liveSessionDir.length > 0
       ? { agentDir, liveSessionDir: opts.liveSessionDir }
       : { agentDir }
-  const roots = await resolveSessionRoots(signals)
+  const roots = opts?.roots ?? (await resolveSessionRoots(signals))
   // 0+1. 逐根首行扫描建候选
   const candidates = await collectCandidates(roots, sourceFilter, cwdFilter)
   // 2. 三路匹配（recent / uuid 片段 / 名称关键词+U5 元数据+u11 标题）

package/src/discovery/roots.ts

@@ -13,9 +13,9 @@ import { performance } from 'node:perf_hooks'
  * U1（design 2026-09-10 §6.1/§7B）：新增 `resolveSessionRoots(signals)` —— 信号包 →
  * 带来源标签的候选根列表，逐根扫描、按 realpath 去重（同路径只扫一次，保留最高优先级
  * kind 标签）。B 收缩（design §6.13）：布局对齐后无 `[env]` 信号，`[default]` 为主根。
- * 旧签名 `listMainSessions`/`listSubagentSessions` 保留为薄包装（内部构造只含 agentDir
- * 的信号包 → main 源退化为 `[default]`+`[legacy]` 两根），存量调用（find.ts /
- * subagents.ts）不破。
+ * 旧签名 `listMainSessions`/`listSubagentSessions` 薄包装已删除（ext-simplify-04 U4/A3：
+ * 内部即「resolveSessionRoots + filter」恒等式，包内原唯一消费者 subagents.ts 改直调；
+ * npm 深 import 移除按 minor breaking 在 CHANGELOG 登记）。
  */
 
 // ============================================================
@@ -24,7 +24,7 @@ import { performance } from 'node:perf_hooks'
 
 /** 发现层信号包（index.ts 采集，全部可降级；本模块只消费不采集） */
 export interface SessionRootSignals {
-  /** pi agent 数据目录（两宿主均成立；B 后 xyz-agent = `<dataDir>/agent`） */
+  /** pi agent 数据目录（两宿主均成立；B 后 taiji = `<dataDir>/agent`） */
   agentDir: string
   /**
    * 宿主已解析的 live session 目录（`ctx.sessionManager.getSessionDir()`，§6.1 信号 1）。
@@ -39,9 +39,8 @@ export type SessionRootKind = 'live' | 'default' | 'legacy' | 'subagent'
 /** main 源 = 主 session 根（live/default/legacy）；subagent 源 = subagent 会话根 */
 export type SessionRootSource = 'main' | 'subagent'
 
-/** 候选根（含扫描结果）。id 恒等于 kind：去重后每 kind 至多一个根，作 doctor 表行键。 */
+/** 候选根（含扫描结果）。去重后每 kind 至多一个根，kind 即 doctor 表行键。 */
 export interface SessionRoot {
-  id: SessionRootKind
   kind: SessionRootKind
   /** 规范化后的绝对路径（`[live]` 已剥 encodeCwd 层） */
   path: string
@@ -55,17 +54,10 @@ export interface SessionRoot {
   /** 扫描所得文件列表（design §7B 要点 8「本就在返回值里」）；未扫描时空数组 */
   files: SessionFileMeta[]
   /**
-   * realpath 与更高优先级根同路径 → 指向保留根的 id，本根未扫描（doctor 渲染
+   * realpath 与更高优先级根同路径 → 指向保留根的 kind，本根未扫描（doctor 渲染
    * 「与 N 同路径，已去重」注记的依据，§7B 要点 4）。
    */
   dedupedInto?: SessionRootKind
-  /**
-   * 本根数据来自调用方注入缓存（resolveSessionRoots options.cache 命中）：fileCount/
-   * scanMs/exists 取缓存值，files 恒空数组——消费方不得把 cached 根的 files 当实扫
-   * 结果（u8 追加：doctor「同一数据源两处渲染」统一走 resolveSessionRoots，缓存语义
-   * 由调用方注入，§6.3）。
-   */
-  cached?: boolean
 }
 
 /** 各根固定子目录名（常量推导，不来自信号——§6.1 信号 5） */
@@ -74,7 +66,7 @@ const SUBAGENTS_DIRNAME = 'subagents'
 
 /**
  * `[live]` 规范化（§6.1/§7B 要点 3）：`getSessionDir()` 在纯 pi 返回按 cwd 编码的子目录
- *（`<agentDir>/sessions/--Users-x--`），在 xyz-agent 覆盖态返回根本身。判据：basename
+ *（`<agentDir>/sessions/--Users-x--`），在 taiji 覆盖态返回根本身。判据：basename
  * 匹配 encodeCwd 形态（`--` 开头 `--` 结尾，实证见 `~/.pi/agent/sessions/` 全部子目录
  * 与 real-data.ts）则取 dirname，否则取自身。
  */
@@ -103,8 +95,8 @@ function sessionRootSpecs(signals: SessionRootSignals): SessionRoot[] {
   return specs
 }
 
-function spec(id: SessionRootKind, source: SessionRootSource, path: string): SessionRoot {
-  return { id, kind: id, source, path, exists: false, files: [] }
+function spec(kind: SessionRootKind, source: SessionRootSource, path: string): SessionRoot {
+  return { kind, source, path, exists: false, files: [] }
 }
 
 /** realpath 解析失败（目录不存在等）→ 回退字面路径作去重键（同字面路径仍可去重） */
@@ -129,37 +121,18 @@ const SKIP_DIRS_NONE = new Set<string>()
 
 // ============================================================
 // 扫描 options（u8 追加：doctor「同一数据源两处渲染，不重复实现探测」§6.3——
-// doctor 经 options 驱动 subagent 根不扫与进程内缓存，本模块不内置 TTL/mtime
-// 失效逻辑，缓存语义全部由调用方注入的句柄定义）
+// doctor 经 options 驱动 subagent 根不扫。原 u8 的进程内缓存注入面已删除
+// （ext-simplify-04 U3）：每次调用实扫，本模块不再持有任何缓存语义）
 // ============================================================
 
-/** 缓存条目载荷（扫描统计快照；失效判定所需元数据由缓存实现方自持，不进本契约） */
-export interface SessionRootCacheEntry {
-  exists: boolean
-  fileCount: number
-  scanMs: number
-}
-
-/**
- * 根扫描的进程内缓存句柄（调用方注入）。get 返回 undefined = 未命中（含调用方判定
- * TTL 到期/目录 mtime 变化后自行淘汰）→ 本模块实扫并 set 回写；命中 → 直接以缓存值
- * 构造根（cached: true，files 恒空数组）。get/set 允许同步或异步实现。
- */
-export interface SessionRootCache {
-  get(key: string): Promise<SessionRootCacheEntry | undefined> | SessionRootCacheEntry | undefined
-  set(key: string, value: SessionRootCacheEntry): void | Promise<void>
-}
-
 /** resolveSessionRoots 扫描行为选项（全部可选，缺省 = 既有行为零变化） */
 export interface SessionRootScanOptions {
   /**
    * subagent 根扫描模式：`'scan'`（默认，现行为——递归扫出文件数）| `'stat'`
-   *（doctor 默认形态 §6.3——只做存在性检查，fileCount/scanMs 恒 undefined，
-   * 不产缓存条目）。subagent 根在纯 pi 下可达数千文件，doctor 可能被反复询问。
+   *（doctor 默认形态与 not-found 文案 §6.3——只做存在性检查，fileCount/scanMs
+   * 恒 undefined）。subagent 根在纯 pi 下可达数千文件，doctor 可能被反复询问。
    */
   subagents?: 'scan' | 'stat'
-  /** 根扫描缓存句柄（见 SessionRootCache）。缺省 = 每次实扫（find 路径永不传）。 */
-  cache?: SessionRootCache
 }
 
 /**
@@ -170,10 +143,9 @@ export interface SessionRootScanOptions {
  * 逐根复用 scanJsonlRecursive（main 源跳 workflow-state；subagent 源不跳）。单根失败
  * （不存在/无权限）→ 空结果继续，不抛错（沿用 listXxxSessions 契约）。
  *
- * options（u8 追加，全部缺省安全）：`subagents:'stat'` 让 subagent 根只做存在性检查；
- * `cache` 提供进程内缓存句柄（命中即不实扫，cached 根 files 恒空）——cache 命中优先于
- * 一切实扫，`set` 仅在实扫后回写（命中不回写）。find/F1 路径恒不传 options（自检行
- * 计数必须取本次实扫，§7B 要点 8 PS-14）。
+ * options（u8 追加，全部缺省安全）：`subagents:'stat'` 让 subagent 根只做存在性检查。
+ * 无缓存——每次调用实扫（原 u8 cache 注入面已删除，ext-simplify-04 U3；find/F1
+ * 自检行计数与 doctor 表计数同取本次实扫，§7B 要点 8）。
  */
 export async function resolveSessionRoots(
   signals: SessionRootSignals,
@@ -187,36 +159,19 @@ export async function resolveSessionRoots(
     const kept = byRealPath.get(key)
     if (kept) {
       // 同 realpath：不扫描，标注归属（exists 与保留根同目录，必然一致）
-      out.push({ ...candidate, exists: kept.exists, dedupedInto: kept.id })
+      out.push({ ...candidate, exists: kept.exists, dedupedInto: kept.kind })
       continue
     }
     if (candidate.source === 'subagent' && subagentMode === 'stat') {
-      // doctor 默认形态（§6.3）：只列路径与可扫性，不产文件数、不入缓存
+      // doctor 默认形态 / not-found 文案（§6.3）：只列路径与可扫性，不产文件数
       out.push({ ...candidate, exists: await pathExists(candidate.path) })
       continue
     }
-    const cached = options?.cache ? await options.cache.get(candidate.path) : undefined
-    if (cached) {
-      // 命中：缓存值即数据源（不实扫、不回写）；files 恒空——消费方不得当实扫结果
-      const root: SessionRoot = {
-        ...candidate,
-        exists: cached.exists,
-        fileCount: cached.fileCount,
-        scanMs: cached.scanMs,
-        cached: true,
-      }
-      byRealPath.set(key, root)
-      out.push(root)
-      continue
-    }
     const skipDirs = candidate.source === 'main' ? SKIP_DIRS_MAIN : SKIP_DIRS_NONE
     const t0 = performance.now()
     const files = await scanJsonlRecursive(candidate.path, skipDirs)
     const scanMs = performance.now() - t0
     const exists = await pathExists(candidate.path)
-    if (options?.cache) {
-      await options.cache.set(candidate.path, { exists, fileCount: files.length, scanMs })
-    }
     const root: SessionRoot = {
       ...candidate,
       exists,
@@ -295,29 +250,3 @@ async function scanJsonlRecursive(
   return results
 }
 
-/**
- * 旧签名薄包装（U1，design §7B 要点 7）：内部构造只含 agentDir 的信号包，main 源退化为
- * 「`[default]`+`[legacy]`」两根并集。工具运行路径后续单元改走 resolveSessionRoots 新签名，
- * 本包装仅为存量调用（find.ts / subagents.ts）与外部深 import 保持不破。
- *
- * 递归扫描子目录（cwd 编码目录如 --Users-foo--），glob *.jsonl，排除 *.jsonl.finalized
- *（design §3.3 D-7 Q2）；跳过 workflow-state 子目录（workflow 运行状态文件，非 session）。
- */
-export async function listMainSessions(agentDir: string): Promise<SessionFileMeta[]> {
-  const roots = await resolveSessionRoots({ agentDir })
-  return roots
-    .filter((r) => r.source === 'main' && r.dedupedInto === undefined)
-    .flatMap((r) => r.files)
-}
-
-/**
- * 旧签名薄包装：agentDir 信号包下 `[subagent]` 根 = `<agentDir>/subagents`（常量推导），
- * 行为与旧实现等价。结构：subagents/<cwd编码>/sessions/*.jsonl。records/ 子目录
- *（.json manifest）无 .jsonl，天然不被误收。
- */
-export async function listSubagentSessions(agentDir: string): Promise<SessionFileMeta[]> {
-  const roots = await resolveSessionRoots({ agentDir })
-  const sub = roots.find((r) => r.kind === 'subagent')
-  return sub?.files ?? []
-}
-

package/src/discovery/session-header.ts

@@ -0,0 +1,103 @@
+import { open, type FileHandle } from 'node:fs/promises'
+import { closeSync, openSync, readSync } from 'node:fs'
+
+/**
+ * [ext-simplify-18 D5] session 文件首行 header 读取的包内单源（原 subagents.ts / find.ts
+ * 两份 async 副本 + tool-handler.ts 一份 sync 副本合一）。不进 shared——跨包第二消费方
+ * 不存在（runtime 侧首行读取是另一形态 + 分层禁反向 import，设计负面清单同口径）。
+ */
+
+/** session header（首行 type==='session' entry 的消费子集）。 */
+export interface SessionHeader {
+  id: string
+  cwd?: string
+  parentSession?: string
+}
+
+/**
+ * 首行读取 buffer 上限。header 超 8KB 的极端情况会截断致 parse 失败（parseSessionHeader
+ * 返回 null）——session header（id/cwd/parentSession）实测 < 300 字节，8KB 约 27 倍余量。
+ */
+export const HEADER_READ_BYTES = 8192
+
+/** 读文件首行（header）。定长 8KB 一次 read；空文件/读失败返回 undefined。 */
+export async function readSessionHeaderFirstLine(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 text = buf.subarray(0, bytesRead).toString('utf8')
+    const nl = text.indexOf('\n')
+    return nl === -1 ? text : text.slice(0, nl)
+  } catch {
+    return undefined
+  } finally {
+    await fh?.close().catch(() => {})
+  }
+}
+
+/** 解析 header 首行为 SessionHeader。非 session 行/缺 id → null。 */
+export function parseSessionHeader(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 o = raw as Record<string, unknown>
+  if (o.type !== 'session' || typeof o.id !== 'string') return null
+  const h: SessionHeader = { id: o.id }
+  if (typeof o.cwd === 'string') h.cwd = o.cwd
+  if (typeof o.parentSession === 'string') h.parentSession = o.parentSession
+  return h
+}
+
+/** readSessionHeaderIdSync 读首行的 buffer 上限。session header 实测 < 300 字节，4KB 足够。 */
+const SYNC_HEADER_READ_BYTES = 4096
+
+/**
+ * 同步读 session 文件首行 header，返回 type==='session' 的 id。
+ *
+ * 任何异常（文件不存在/空文件/解析失败/type 不符）返回 undefined。与 async 版
+ * readSessionHeaderFirstLine/parseSessionHeader 同构（定长 buffer 读首行 + JSON.parse +
+ * type 校验），但用同步 fs API（resolveSessionId 内仅调用 1 次，同步开销可接受），
+ * 窗口取 4KB（仅取 id）——sync 形态与窗口差异是刻意的调用上下文适配，独立常量、
+ * 不与 async 版 8KB 强行统一。
+ */
+export function readSessionHeaderIdSync(filePath: string): string | undefined {
+  let fd: number | undefined
+  try {
+    fd = openSync(filePath, 'r')
+    const buf = Buffer.alloc(SYNC_HEADER_READ_BYTES)
+    const bytesRead = readSync(fd, buf, 0, SYNC_HEADER_READ_BYTES, 0)
+    if (bytesRead === 0) return undefined
+    const text = buf.subarray(0, bytesRead).toString('utf8')
+    const nl = text.indexOf('\n')
+    const line = nl === -1 ? text : text.slice(0, nl)
+    let raw: unknown
+    try {
+      raw = JSON.parse(line)
+    } catch {
+      return undefined
+    }
+    if (typeof raw !== 'object' || raw === null) return undefined
+    const o = raw as Record<string, unknown>
+    if (o.type !== 'session' || typeof o.id !== 'string') return undefined
+    return o.id
+  } catch {
+    return undefined
+  } finally {
+    if (fd !== undefined) {
+      try {
+        closeSync(fd)
+      } catch {
+        // closeSync 失败：fd 可能已无效，header 数据已读取，关闭失败不影响结果（best-effort）
+        void fd
+      }
+    }
+  }
+}