@zhushanwen/pi-session-reader 0.5.1 → 0.6.0

package/src/__tests__/workflow.test.ts

@@ -30,7 +30,6 @@ const NEW_SNAPSHOT_FIXTURE = {
         opts: {
           prompt: 'Reply with exactly: PROBE-OK',
           model: 'deepseek-router/ds-pro',
-          thinkingLevel: 'high',
           description: 'step-0',
         },
         status: 'done',
@@ -64,7 +63,7 @@ const V2_SNAPSHOT_FIXTURE = {
     calls: [
       {
         id: 0,
-        opts: { prompt: 'task 0', model: 'default', thinkingLevel: 'high', description: 'v2-step-0' },
+        opts: { prompt: 'task 0', model: 'default', description: 'v2-step-0' },
         status: 'done',
         attempts: 1,
         sessionId: '019v2a',
@@ -126,12 +125,10 @@ describe('parseRunSnapshot', () => {
     expect(step.status).toBe('done')
     expect(step.description).toBe('step-0')
     expect(step.model).toBe('deepseek-router/ds-pro')
-    expect(step.thinkingLevel).toBe('high')
     expect(step.attempts).toBe(1)
     expect(step.durationMs).toBe(1234)
     expect(step.sessionId).toBe('019xxx')
     expect(step.sessionFile).toBe('/abs/session.jsonl')
-    expect(step.contentPreview).toBe('PROBE-OK')
   })
 
   it('TC-w5-parse-new-v2：v2 快照（pi-subagent-workflow 8.x 写入）解析非 null，calls sessionFile 读出', () => {
@@ -148,7 +145,6 @@ describe('parseRunSnapshot', () => {
     expect(overview!.steps[0].description).toBe('v2-step-0')
     expect(overview!.steps[1].sessionFile).toBe('/abs/v2-call1.jsonl')
     expect(overview!.steps[1].sessionId).toBe('019v2b')
-    expect(overview!.steps[1].contentPreview).toBe('OK')
   })
 
   it('TC-w5-parse-new-status-unknown：NEW call.status 非 done/running/pending（如 failed）→ step.status=pending', () => {
@@ -174,7 +170,6 @@ describe('parseRunSnapshot', () => {
     expect(step.index).toBe(3)
     expect(step.status).toBe('pending')
     expect(step.description).toBe('step-3')
-    expect(step.contentPreview).toBe('partial')
     expect(step.durationMs).toBe(9)
   })
 
@@ -193,7 +188,6 @@ describe('parseRunSnapshot', () => {
     expect(step.index).toBe(0) // callCache 顺序索引
     expect(step.status).toBe('pending') // content='' 空串不算完成标志 → pending
     expect(step.sessionFile).toBeUndefined() // OLD 未持久化
-    expect(step.contentPreview).toBe('') // value.content='' 仍提取
   })
 
   it('TC-w5-parse-corrupt-nonobject：非对象输入（null/undefined/string/number/array）返回 null', () => {

package/src/core/execution-tree.ts

@@ -59,6 +59,7 @@ export interface ExecutionTreeNode {
   agentName?: string
   slug?: string
   task?: string
+  /** 仅 details 可见，不进文本渲染（formatExecutionTreeText 渲染 status/slug/agentName/task，与 SubagentRef.model 同口径） */
   model?: string
   /** subagent 终态 completed/failed/running（manifest.status） */
   status?: string

package/src/core/family.ts

@@ -6,11 +6,14 @@ import type { Entry } from './parser.js'
  * M1 范围：纯逻辑层。buildFamilyIndex 接收已读入的 entry 数组（不做文件 IO），
  * 文件扫描/首行读取归 M2 discovery 层（roots.ts/find.ts/subagents.ts）。
  *
- * M1 占位约定（M2 discovery 层补全真实值，逻辑不变）：
- * - SessionRef.fileName：session header 推不出文件路径 → 占位空串
+ * 占位约定（原「M2 回填补全」双阶段约定已随 enrichRefs 删除退役，ext-simplify-04 U4/E2
+ * ——回填的 fileName/cwd 零文本读者；SessionRef 类型与 find 路径共享，find 侧两字段有
+ * 真实消费者，字段本身保留）：
+ * - SessionRef.fileName / subagent cwd：family 路径恒为占位空串（session header 推不出
+ *   路径 / identity entry 无 cwd），不再回填
  * - SessionRef.mtime/sizeBytes：从 fileStats 取（M1 key=sessionId），取不到为 0
  * - SubagentRef.sessionId：identity entry 不含 subagent session 的 id → 占位用 entry.id
- * - SubagentRef.cwd：identity entry（custom 类型）无 cwd → 占位空串
+ *   （M2 buildFamilyFromFs 以 header.id 替换为真实 id）
  * - fileStats 的 key：sessionId（M2 实现沿用此 key，cleanedUp 按 sessionId 命中），逻辑通用
  *
  * 隔代关联规则（design §3.3 D-7 Q1）见 resolveFamily 注释。
@@ -35,11 +38,11 @@ export interface SubagentRef extends SessionRef {
   task?: string
   /** agent 类型名（manifest.agentName，P-fallback 时 identity.data.agent；同语义异名） */
   agentName?: string
-  /** 模型 id（仅 manifest 有；P-fallback 时 undefined） */
+  /** 模型 id（仅 manifest 有；P-fallback 时 undefined）。仅 details 可见，不进文本渲染（D2②：展示面只取 status/agentName/task） */
   model?: string
   /** 终态 completed/failed/running（仅 manifest 有；P-fallback 时 undefined） */
   status?: string
-  /** subagent session.jsonl 绝对路径（manifest.sessionFile 或 alive 文件 meta.path） */
+  /** subagent session.jsonl 绝对路径（manifest.sessionFile 或 alive 文件 meta.path）。仅 details 可见，不进文本渲染 */
   sessionFile?: string
 }
 
@@ -118,16 +121,16 @@ function isSubagentIdentityData(v: unknown): v is SubagentIdentityData {
  * 文件名格式 `<timestamp>_<sessionId>.jsonl`，故路径字符串含父 sessionId。
  * 遍历已知 sessionId 做子串匹配反查。
  *
- * 兼容 parentSession 直接就是 sessionId 的简化场景（测试 fixture 常用）。
  * 假设 sessionId 互不为子串（pi 用 UUID，满足）；M2 可优化为 fileName→sessionId
  * 索引反查（O(1)），当前遍历 O(N)，家族索引文件数通常几十到几百，可接受。
+ *（原「parentSession 直接是 sessionId」快路径已删除，ext-simplify-04 A4——生产数据
+ * 恒为文件路径，该分支只服务测试 fixture 简化形态。）
  */
 function resolveParentSessionId(
   parentSession: string | undefined,
   byId: Map<string, SessionRef>,
 ): string | null {
   if (!parentSession) return null
-  if (byId.has(parentSession)) return parentSession // 直接是 sessionId（简化场景）
   for (const sid of byId.keys()) {
     if (parentSession.includes(sid)) return sid
   }
@@ -144,7 +147,7 @@ function buildById(
     const stat = fileStats.get(h.id)
     const ref: SessionRef = {
       sessionId: h.id,
-      fileName: '', // M1 占位：M2 discovery 补真实文件路径
+      fileName: '', // 占位空串：family 路径不回填（enrichRefs 已删除，ext-simplify-04 U4）
       mtime: stat?.mtime ?? 0,
       sizeBytes: stat?.size ?? 0,
       cwd: h.cwd ?? '',
@@ -198,7 +201,7 @@ function buildSubagentsByRoot(
       fileName: '', // M1 占位
       mtime: stat?.mtime ?? 0,
       sizeBytes: stat?.size ?? 0,
-      cwd: '', // identity entry 无 cwd；M2 从 subagent 文件 header 补
+      cwd: '', // identity entry 无 cwd；family 路径不回填（enrichRefs 已删除，ext-simplify-04 U4）
       // fileStats key=sessionId（buildFamilyFromFs 以 header.id 写入），cleanedUp 按 sessionId 命中
       cleanedUp: !fileStats.has(ident.id),
       // U4 富字段：从 identity data 读（manifest 主/P-fallback 由 buildFamilyFromFs 组装时决定）

package/src/core/render.ts

@@ -17,7 +17,8 @@ const ASSISTANT_BRIEF_MAX_CHARS = 80
 const ENTRY_BRIEF_MAX_CHARS = 100
 /** turn 索引显示宽度（T013 三位补零）。 */
 const TURN_INDEX_WIDTH = 3
-/** outline 默认 token 预算（OutlineOptions.budget 缺省值）。 */
+/** outline 默认 token 预算（OutlineOptions.budget 缺省值）。生产路径（doOutline/doExport）
+ * 唯一取值：outline 是设计定档的 ~1500 token 全貌 TOC，无按调用方调节的需求。 */
 const OUTLINE_DEFAULT_BUDGET_TOKENS = 2000
 /** token 估算换算基数（chars/4，与 tokenEstimate 口径一致）。 */
 const CHARS_PER_TOKEN = 4
@@ -55,6 +56,11 @@ export interface TurnBrief {
 
 export interface OutlineResult {
   turns: TurnBrief[]
+  /**
+   * 渲染行（E7/D3 行渲染统一）：formatLine 产出、降级与总预算截断后的最终展示行——
+   * 预算度量与工具层展示共用同一份（度量 = 展示 by construction），展示侧不得重建行格式。
+   */
+  lines: string[]
   /** skippedLines：JSON 解析失败/缺结构字段的行数（parser 检测，工具层覆盖精确值；render 层无 ParseResult 恒 0） */
   stats: { totalTurns: number; totalEntries: number; totalBytes: number; parsedBytes: number; skippedLines: number }
   /** chars / 4 近似（与 design P-outline 口径一致） */
@@ -64,7 +70,9 @@ export interface OutlineResult {
 }
 
 export interface OutlineOptions {
-  /** 默认 2000（token） */
+  /** 测试注入缝（E10 定性）：非模型可见参数——session_read schema 无 budget 入参，模型
+   * 无法也无需调节；存在动机 = 测试注入小预算触发降级档用例（砍 assistantBrief / 骨架档）。
+   * 生产路径不传，走 OUTLINE_DEFAULT_BUDGET_TOKENS 默认。 */
   budget?: number
   allBranches?: boolean
   /** 默认 turn；entry = 每 entry 一行不聚合（D-1 兜底，坏 session 调试） */
@@ -101,6 +109,26 @@ function blockThinking(block: ContentBlock): string {
   return ''
 }
 
+/**
+ * E11 共享核：白名单提取 message.content 中 `type==='text'` 块的 text 字段（块 → string[]）。
+ * string content 直取为单元素数组；非 string 非数组返回空数组。join 语义（''/'\n'/' '）
+ * 与空态语义（空串 vs undefined）留在各调用点组合——S7 警告适用：join 差异是行为敏感点，
+ * 不可在共享核合并。消费方：result-action（'' join）/ extract（'\n' join）/ find（' ' join
+ * + 空返 undefined）。
+ */
+export function textBlockParts(content: unknown): string[] {
+  if (typeof content === 'string') return [content]
+  if (!Array.isArray(content)) return []
+  const parts: string[] = []
+  for (const b of content) {
+    if (b !== null && typeof b === 'object') {
+      const o = b as Record<string, unknown>
+      if (o.type === 'text' && typeof o.text === 'string') parts.push(o.text)
+    }
+  }
+  return parts
+}
+
 /** 拼接 text 块文本（排除 thinking / toolCall / tool_use / tool_result 块）。 */
 function extractText(content: unknown): string {
   if (isStringContent(content)) return content
@@ -276,7 +304,7 @@ function findBranchForkPoint(turn: Turn, tree: TreeView): string | undefined {
 }
 
 // ---------------------------------------------------------------------------
-// 行渲染（预算度量依据）
+// 行渲染（预算度量与展示同一份渲染行，E7/D3 行渲染统一）
 // ---------------------------------------------------------------------------
 
 function formatHHMM(timestamp?: string): string {
@@ -292,10 +320,11 @@ export function formatBytesMarker(bytes: number): string {
 }
 
 /**
- * 渲染单行为字符串（用于预算度量与降级判断）。
+ * 渲染单行为字符串（E7 行渲染统一：预算度量与展示同一份渲染行，OutlineResult.lines 的行工厂）。
  * v2 O1：L1 行含 assistantBrief（补 assistant 结论行让 outline 单独可决策，不再逼反复 expand）。
  * level: 0=全有（toolSummary + assistantBrief）/ 1=砍 assistantBrief / 2=再砍 toolSummary（骨架）。
  * userBrief + omittedBytes 骨架永保。assistantBrief 格式 `→ <结论>`，在 toolSummary 后、omitted 前。
+ * 旁支标记 `[旁支 N entries]`（branchSize = 该 forkPoint 下旁支子树 entry 数）。
  */
 function formatLine(b: TurnBrief, level: LineLevel, branchSize?: number): string {
   const parts: string[] = []
@@ -341,7 +370,8 @@ function applyBranchLabels(briefs: TurnBrief[], turns: Turn[], tree: TreeView):
 /**
  * 降级序逐行渲染（design §3.5 算法 1 step3）：level 0 全有；超预算降到 level 1
  * 砍 assistantBrief；仍超降到 level 2 砍 toolSummary（骨架）。
- * 直接改写 brief 的 assistantBrief/toolSummary 字段，返回行缓存。
+ * 直接改写 brief 的 assistantBrief/toolSummary 字段，返回行缓存（E7 后随结果
+ * 返回为 OutlineResult.lines，预算度量与展示同一份）。
  */
 function renderDegradingLines(
   briefs: TurnBrief[],
@@ -408,7 +438,7 @@ export function renderOutline(
   }
 
   if (turns.length === 0) {
-    return { turns: [], stats, tokenEstimate: 0 }
+    return { turns: [], lines: [], stats, tokenEstimate: 0 }
   }
 
   // granularity:entry —— 每 entry 一行，不聚合 turn（D-1 兜底）
@@ -428,11 +458,11 @@ export function renderOutline(
   // 3. 降级序渲染：level 0 全有 → level 1 砍 assistantBrief → level 2 骨架
   const lineCache = renderDegradingLines(briefs, tree, perTurnCharBudget)
 
-  // 4. 总预算截断（从尾部丢弃）
+  // 4. 总预算截断（从尾部丢弃，lines 与 briefs 同步截短）
   const { totalChars, truncated } = truncateToTotalBudget(briefs, lineCache, budget)
 
   const tokenEstimate = Math.ceil(totalChars / CHARS_PER_TOKEN)
-  return { turns: briefs, stats, tokenEstimate, truncated }
+  return { turns: briefs, lines: lineCache, stats, tokenEstimate, truncated }
 }
 
 /** granularity:entry 模式：每 entry 一行 TurnBrief，不聚合，仅总预算截断。 */
@@ -486,6 +516,7 @@ function renderEntryGranularity(
   }
   return {
     turns: briefs,
+    lines,
     stats,
     tokenEstimate: Math.ceil(totalChars / CHARS_PER_TOKEN),
     truncated,
@@ -568,7 +599,7 @@ function stripThinking(content: unknown): unknown {
 
 /**
  * L3 detail 默认摘要态的 toolResult entry（v2 O3：toolResult 不再整条消失，给中间态）。
- * includeToolResult:true 时 renderDetail 返回原 Entry（全文），否则返回此摘要。
+ * includeToolResult:true 时 renderDetail 直接 push 原 Entry（全文态真实路径），否则返回此摘要。
  */
 export interface ToolResultSummaryEntry {
   type: 'toolResultSummary'
@@ -580,8 +611,6 @@ export interface ToolResultSummaryEntry {
   headLines: string
   /** 结果文本总行数 */
   totalLines: number
-  /** 原 toolResult entry（includeToolResult:true 时 renderDetail 改用此返回全文） */
-  fullEntry: Entry
 }
 
 export function renderDetail(
@@ -620,7 +649,6 @@ export function renderDetail(
             summary: formatToolResultSummary(msg.toolName, tc, text),
             headLines,
             totalLines: lines.length,
-            fullEntry: e,
           })
         }
         continue

package/src/core/workflow.ts

@@ -11,25 +11,20 @@
 // 升版连带编译期影响本扩展；且上游类型只描述 NEW，OLD 仍需自处理（TC-wf-snapshot-version-union）。
 // session-reader 作为纯读取者，按字段存在性 + v 标记分支做「结构化快照」式解析，与上游解耦。
 
-// ---- 类型守卫 helpers ----
+import { isRecord } from '@zhushanwen/pi-ext-guards'
 
-/** unknown → Record<string, unknown> 守卫（非对象或 null → false）。 */
-function isRecord(v: unknown): v is Record<string, unknown> {
-  return typeof v === 'object' && v !== null
-}
+// ---- 类型守卫 helpers ----
 
 /** unknown → string 收窄（非 string → undefined）。快照可选字符串字段的统一入口。 */
 function strOr(v: unknown): string | undefined {
   return typeof v === 'string' ? v : undefined
 }
 
-/** 字符串截断（超 max 加省略号）。概览预览用，全文走 detail。 */
+/** 字符串截断（超 max 加省略号）。step 行渲染用。 */
 function truncate(s: string, max: number): string {
   return s.length <= max ? s : s.slice(0, max) + '…'
 }
 
-/** contentPreview 截断长度（概览预览，全文走 detail）。 */
-const CONTENT_PREVIEW_MAX = 120
 /** step 行 call sessionId 显示截断长度（uuid 前缀段，LLM 可读）。 */
 const SESSION_ID_PREVIEW_MAX = 12
 
@@ -61,8 +56,6 @@ export interface WorkflowStep {
   description?: string
   /** NEW call.opts.model */
   model?: string
-  /** NEW call.opts.thinkingLevel */
-  thinkingLevel?: string
   /** NEW call.attempts / OLD 无 → undefined */
   attempts?: number
   /** NEW call.result.durationMs / OLD value.result.durationMs */
@@ -71,8 +64,6 @@ export interface WorkflowStep {
   sessionId?: string
   /** call.sessionFile 或 result.sessionFile（LLM 跳 outline/detail 的绝对路径入口，OLD 多数为 undefined） */
   sessionFile?: string
-  /** result.content 截断前 120 字（概览预览，全文走 detail） */
-  contentPreview?: string
 }
 
 /** workflow run 概览（parseRunSnapshot 输出 / renderWorkflowOverview 输入）。 */
@@ -83,7 +74,7 @@ export interface WorkflowOverview {
   stateFile: string
   /** NEW state.status / OLD 顶层 status */
   status: string
-  /** 格式标记（渲染/调试用）。v2 读取面形状与 v1 一致（pi-subagent-workflow 8.x 一次性生命周期） */
+  /** details 格式标记（随 details.runs 透传给程序化消费方，文本渲染不读）。v2 读取面形状与 v1 一致（pi-subagent-workflow 8.x 一次性生命周期） */
   version: 'wf-run-v1' | 'wf-run-v2' | 'legacy'
   /** NEW spec.scriptName / spec.name / OLD name */
   script?: string
@@ -138,19 +129,16 @@ function mapCallToStep(call: unknown, fallbackIndex: number): WorkflowStep {
   const index = typeof call.id === 'number' ? call.id : fallbackIndex
   const status = normalizeCallStatus(strOr(call.status) ?? '')
   const refs = pickSessionRefs(call, result)
-  const content = strOr(result.content)
 
   return {
     index,
     status,
     description: strOr(opts.description),
     model: strOr(opts.model),
-    thinkingLevel: strOr(opts.thinkingLevel),
     attempts: typeof call.attempts === 'number' ? call.attempts : undefined,
     durationMs: typeof result.durationMs === 'number' ? result.durationMs : undefined,
     sessionId: refs.sessionId,
     sessionFile: refs.sessionFile,
-    contentPreview: content !== undefined ? truncate(content, CONTENT_PREVIEW_MAX) : undefined,
   }
 }
 
@@ -162,11 +150,11 @@ function mapCacheEntryToStep(entry: unknown, index: number): WorkflowStep {
 
   // sessionFile/sessionId: value.sessionFile 或 value.result.sessionFile（OLD 多数缺失，探针 112 文件 0）
   const refs = pickSessionRefs(value, result)
-  // content：真实 OLD 数据 value.content（wf-skip-ok）与测试 fixture value.result.content 并存
+  // content：真实 OLD 数据 value.content（wf-skip-ok）与测试 fixture value.result.content 并存，
+  // 仅用于 status 推测（A4 死字段删除：contentPreview 已删，不再随 step 输出）
   const content = strOr(result.content) ?? strOr(value.content)
   // OLD 无 status 字段：有 sessionFile 或非空 content → done，否则 pending
-  //（空 content 如 wf-skip-ok 的 '' 不算完成标志，对齐 TC-w5-parse-old expected status='pending'；
-  // content 仍提取为 contentPreview=''）
+  //（空 content 如 wf-skip-ok 的 '' 不算完成标志，对齐 TC-w5-parse-old expected status='pending'）
   const hasContent = content !== undefined && content.length > 0
   const status: WorkflowStep['status'] =
     refs.sessionFile !== undefined || hasContent ? 'done' : 'pending'
@@ -177,7 +165,6 @@ function mapCacheEntryToStep(entry: unknown, index: number): WorkflowStep {
     durationMs: typeof result.durationMs === 'number' ? result.durationMs : undefined,
     sessionId: refs.sessionId,
     sessionFile: refs.sessionFile,
-    contentPreview: content !== undefined ? truncate(content, CONTENT_PREVIEW_MAX) : undefined,
   }
 }
 

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) 实装语义是「只扫一层平铺目录」——平铺根意味着
@@ -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 标题）