@zhushanwen/pi-session-reader 0.5.0 → 0.6.0

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 登记）。
  */
 
 // ============================================================
@@ -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） */
@@ -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
+      }
+    }
+  }
+}

package/src/discovery/subagents.ts

@@ -2,9 +2,10 @@ import { readFile, readdir, open, stat } from 'node:fs/promises'
 import type { FileHandle } from 'node:fs/promises'
 import { join, basename } from 'node:path'
 import type { Entry } from '../core/parser.js'
-import type { Family, SessionRef, SubagentRef } from '../core/family.js'
+import type { Family, SessionRef } from '../core/family.js'
 import { buildFamilyIndex, resolveFamily } from '../core/family.js'
-import { listMainSessions, listSubagentSessions, resolveSessionRoots, type SessionFileMeta } from './roots.js'
+import { resolveSessionRoots, type SessionFileMeta } from './roots.js'
+import { parseSessionHeader, readSessionHeaderFirstLine } from './session-header.js'
 import { resolveWorkflows } from './workflows.js'
 
 /**
@@ -56,8 +57,8 @@ export async function buildFamilyFromFs(sessionId: string, agentDir: string): Pr
   const index = buildFamilyIndex(scan.headers, scan.identities, scan.fileStats)
   const family = resolveFamily(sessionId, index)
 
-  // ---- 6. 补 M1 占位字段（fileName / subagent cwd）+ workflows ----
-  enrichRefs(family, scan.pathToRef)
+  // ---- 6. workflows（enrichRefs 回填已删除，ext-simplify-04 U4/E2：fileName/cwd 占位
+  //      零文本读者，family 路径维持 core 层占位空串；富字段的消费者 = formatFamilyText 展示）----
   family.workflows = await resolveWorkflows(sessionId, scan.sessionIdToPath, scan.pathToRef)
 
   return family
@@ -71,10 +72,12 @@ export async function buildFamilyFromFs(sessionId: string, agentDir: string): Pr
  * not-found 错误文案：列出实际扫描过的 main 候选根（U1 并入部分，design §6.1 自证能力
  * ——「没有这条 session」与「根配错了」必须可区分，错误信息携带发现层内部状态）。
  * 仅失败路径调用，额外一次 resolveSessionRoots 的扫描成本可接受；根过滤条件与
- * collectMainSessions 实扫集合一致（listMainSessions = agentDir 信号包下未去重的 main 根）。
+ * collectMainSessions 实扫集合一致（agentDir 信号包下未去重的 main 根）。
  */
 async function formatSessionNotFound(sessionId: string, agentDir: string): Promise<string> {
-  const mainRoots = (await resolveSessionRoots({ agentDir })).filter(
+  // subagents:'stat'——本路径只渲染 main 根行，subagent 根不做深扫（ext-simplify-04 A2：
+  // 原默认 'scan' 白扫整个 subagent 根后 filter 丢弃）
+  const mainRoots = (await resolveSessionRoots({ agentDir }, { subagents: 'stat' })).filter(
     (r) => r.source === 'main' && r.dedupedInto === undefined,
   )
   const lines = mainRoots.map((r) => {
@@ -97,9 +100,9 @@ interface FamilyFsScan {
   identities: Entry[]
   /** sessionId → { mtime, size }（buildFamilyIndex 存活判定素材） */
   fileStats: Map<string, { mtime: number; size: number }>
-  /** sessionId → 真实文件路径，供 workflows 找目标文件 + enrich 补 fileName */
+  /** sessionId → 真实文件路径，供 workflows 找目标文件 */
   sessionIdToPath: Map<string, string>
-  /** path → 完整 SessionRef（含真实 cwd/fileName/mtime/size），供 enrich + workflow calls 反查 */
+  /** path → 完整 SessionRef（含真实 cwd/fileName/mtime/size），供 workflow calls 反查 */
   pathToRef: Map<string, SessionRef>
   /** 已扫描到的 subagent 文件路径集合，供 manifest 孤儿判定（alive 则跳过 manifest） */
   aliveSubPaths: Set<string>
@@ -114,9 +117,13 @@ function indexManifestsBySessionFile(manifests: RecordManifest[]): Map<string, R
 
 /** 步骤 1：main sessions —— 首行 header → headers + fileStats + 路径反查 */
 async function collectMainSessions(agentDir: string, scan: FamilyFsScan): Promise<void> {
-  const mainMetas = await listMainSessions(agentDir)
+  // A3（ext-simplify-04）：直调 resolveSessionRoots + filter（原 listMainSessions 薄包装
+  // 已删除）——agentDir 信号包下 main 源未去重根（[default]+[legacy]，被 [live] 去重的除外）的文件并集
+  const mainMetas = (await resolveSessionRoots({ agentDir }))
+    .filter((r) => r.source === 'main' && r.dedupedInto === undefined)
+    .flatMap((r) => r.files)
   for (const meta of mainMetas) {
-    const h = parseHeaderLine(await readFirstLine(meta.path))
+    const h = parseSessionHeader(await readSessionHeaderFirstLine(meta.path))
     if (!h) continue // 非 session/坏 header → 跳过（不入 byId）
     const entry: Entry = { type: 'session', id: h.id, parentId: null, cwd: h.cwd ?? '' }
     if (h.parentSession) entry.parentSession = h.parentSession
@@ -171,9 +178,12 @@ async function collectSubagentIdentities(
 ): Promise<void> {
   // U4 数据流：manifest 命中透全字段；未命中 P-fallback 读尾行 identity 取 task/slug/agent
   //（model/status 不可回退，留 undefined）；无 manifest 无 identity（运行中/异常）跳过。
-  const subMetas = await listSubagentSessions(agentDir)
+  // A3（ext-simplify-04）：直调 resolveSessionRoots（原 listSubagentSessions 薄包装已删除）
+  //——agentDir 信号包下 [subagent] 根 = <agentDir>/subagents（常量推导，恒唯一）
+  const subMetas =
+    (await resolveSessionRoots({ agentDir })).find((r) => r.kind === 'subagent')?.files ?? []
   for (const meta of subMetas) {
-    const h = parseHeaderLine(await readFirstLine(meta.path))
+    const h = parseSessionHeader(await readSessionHeaderFirstLine(meta.path))
     if (!h) continue // 非 session/坏 header → 无真实 session id，无法 id 修正，跳过
     const realId = h.id
     // header 可解析即视为 alive（MF-3）：identity 在文件尾行、完成时才写入，运行中的 subagent
@@ -244,55 +254,12 @@ function appendOrphanIdentities(manifests: RecordManifest[], scan: FamilyFsScan)
 
 // ============================================================
 // 文件读取 helpers（定长 buffer，避免全文读：subagent 文件均 269KB、总量 ~923MB）
+// 首行 header 读取/解析在 session-header.ts（D5 单源）；本文件仅保留尾行 identity 读取。
 // ============================================================
 
-/** 首行读取 buffer 上限。session header（id/cwd/parentSession）实测 < 300 字节，8KB 足够。 */
-const HEADER_READ_BYTES = 8192
 /** 尾行 identity 读取 buffer 上限。identity 含完整 task 文本可达数 KB；实测 64KB 覆盖 3203/3430。 */
 const TAIL_READ_BYTES = 65536
 
-/** 读文件首行（header）。定长 8KB 一次 read；空文件/读失败返回 undefined。 */
-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 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(() => {})
-  }
-}
-
-interface SessionHeader {
-  id: string
-  cwd?: string
-  parentSession?: string
-}
-
-/** 解析 header 首行为 SessionHeader。非 session 行/缺 id → null。 */
-function parseHeaderLine(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
-}
-
 /** readTailIdentity 的成功返回形状（rootSessionId 必有，其余存在才带） */
 type TailIdentity = {
   rootSessionId: string
@@ -488,41 +455,3 @@ export function extractSessionIdFromFilename(name: string): string {
   const candidate = idx >= 0 ? noExt.slice(idx + 1) : noExt
   return /^[0-9a-f-]{8,}$/i.test(candidate) ? candidate : ''
 }
-
-// ============================================================
-// enrich：补 M1 占位字段（fileName / subagent cwd）
-// ============================================================
-
-/**
- * M1 buildFamilyIndex 设 SessionRef.fileName=''（header 推不出路径）、subagent cwd=''
- *（identity 无 cwd）。此处用已扫描的真实文件信息补全：alive 的 ref 补 fileName + cwd；
- * cleanedUp 孤儿（无文件）保持占位。
- */
-function enrichRefs(family: Family, pathToRef: Map<string, SessionRef>): void {
-  // sessionId → 完整 ref（含真实 fileName/cwd），由 pathToRef 反建
-  const bySid = new Map<string, SessionRef>()
-  for (const ref of pathToRef.values()) bySid.set(ref.sessionId, ref)
-
-  const enrichSessionRef = (ref: SessionRef): SessionRef => {
-    const full = bySid.get(ref.sessionId)
-    if (!full) return ref
-    return {
-      ...ref,
-      fileName: full.fileName || ref.fileName,
-      cwd: full.cwd || ref.cwd,
-    }
-  }
-
-  family.root = enrichSessionRef(family.root)
-  family.parents = family.parents.map(enrichSessionRef)
-  family.forks = family.forks.map(enrichSessionRef)
-  family.subagents = family.subagents.map((s) => {
-    const full = bySid.get(s.sessionId)
-    if (!full) return s
-    return {
-      ...s,
-      fileName: full.fileName || s.fileName,
-      cwd: full.cwd || s.cwd,
-    } as SubagentRef
-  })
-}

package/src/doctor.ts

@@ -2,21 +2,15 @@
  * doctor action（u8：design 2026-09-10 §6.2/§6.3/§6.4/§7B 要点 2/4/5/8 + §6.11 U14b 段）。
  *
  * 从 tool-handler.ts 机械提取（max-lines 拆分轮，零行为变更）：环境判定 + 根表渲染 +
- * doctor 扫描缓存 + 旧布局残留 glob 探测。SessionReadSignals（u3 信号包超集）随域迁移，
- * tool-handler re-export 保持导出面不变（index.ts / 单测白盒 import 路径不变）。
- * statDirMtimeOrNull / DOCTOR_CACHE_TTL_MS 供留守的 u11 metadata 缓存复用（一并导出）。
+ * 旧布局残留 glob 探测。SessionReadSignals（u3 信号包超集）在域内定义，tool-handler
+ * re-export 供 index.ts 生产消费。原 u8 的扫描缓存机已删除（ext-simplify-04 U3）：
+ * 每次调用实扫，无缓存命中语义；TTL/mtime 判定随 metadata 缓存留在 tool-handler 侧。
  */
 import { existsSync } from 'node:fs'
-import { readdir, stat } from 'node:fs/promises'
+import { readdir } from 'node:fs/promises'
 import { join, dirname } from 'node:path'
 import { detectEnvironment, type DetectedEnvironment } from './discovery/env.js'
-import {
-  resolveSessionRoots,
-  type SessionRoot,
-  type SessionRootCache,
-  type SessionRootCacheEntry,
-  type SessionRootSignals,
-} from './discovery/roots.js'
+import { resolveSessionRoots, type SessionRoot, type SessionRootSignals } from './discovery/roots.js'
 import type { SessionReadParams, ToolResult } from './tool-handler.js'
 
 /**
@@ -32,69 +26,9 @@ export interface SessionReadSignals extends SessionRootSignals {
   bundleUrl?: string
 }
 
-/**
- * doctor 扫描缓存（进程内，keyed by 根字面路径；Map 生命周期 = pi 进程生命周期，
- * 即「进程生命周期兜底上限」）。失效 = 秒级 TTL 到期 **或** 根目录 mtime 变化（任一）。
- *
- * 以 SessionRootCache 句柄注入 resolveSessionRoots（§6.3「同一数据源两处渲染」——根
- * 骨架/去重/扫描全在 roots.ts，doctor 只注入缓存与 subagent 扫描模式）；TTL/mtime
- * 失效判定全在本侧实现，roots.ts 不内置。**仅 doctor 消费——find 一律不读缓存**
- *（§7B 要点 8）：find 恒不传 options；若 find 读缓存，最坏形态是 PS-14（首条
- * assistant 前 main 根 0 文件被缓存，之后每次都把「根解析正常」误报成「主根为空」）
- * ——正是本设计要消灭的错误归因。
- */
-interface DoctorCacheEntry extends SessionRootCacheEntry {
-  /** 写入时刻（Date.now()），TTL 判定用 */
-  cachedAt: number
-  /** 根目录 mtime(ms)；目录不存在为 null（存在性翻转即失效） */
-  dirMtimeMs: number | null
-}
-
-const doctorScanCache = new Map<string, DoctorCacheEntry>()
-// §7.5 豁免（development-guide.md「纯性能缓存豁免」）：TTL 纯性能缓存，jiti 双路径加载
-// 分裂成两份仅多一次 miss 重扫，无正确性影响，不升级 globalThis 单例。
-
 /** doctor 根表来源标签列宽（最长 `[subagent]` 10 字符 + 1 对齐间距，§5.1 表格形态）。 */
 const DOCTOR_ROOT_LABEL_PAD = 11
 
-/** 缓存 TTL（秒级，§6.3）。mtime 是主失效通道；TTL 兜「子目录内增删不改变根 mtime」的陈旧面。 */
-export const DOCTOR_CACHE_TTL_MS = 5000
-
-/** stat 根目录 mtime；不存在返回 null（与缓存条目的 null 比对 = 存在性未翻转）。 */
-export async function statDirMtimeOrNull(path: string): Promise<number | null> {
-  try {
-    return (await stat(path)).mtimeMs
-  } catch (err) {
-    // 目录不存在是 doctor 的常态输入（三根降级形态），非异常——void 同 roots.ts 容错
-    void err
-    return null
-  }
-}
-
-/** doctor 侧缓存句柄：get 做失效判定（未命中即删除条目），set 快照 mtime 与写入时刻。 */
-const doctorRootCache: SessionRootCache = {
-  async get(key) {
-    const hit = doctorScanCache.get(key)
-    if (hit === undefined) return undefined
-    if (Date.now() - hit.cachedAt >= DOCTOR_CACHE_TTL_MS) {
-      doctorScanCache.delete(key)
-      return undefined
-    }
-    if ((await statDirMtimeOrNull(key)) !== hit.dirMtimeMs) {
-      doctorScanCache.delete(key)
-      return undefined
-    }
-    return { exists: hit.exists, fileCount: hit.fileCount, scanMs: hit.scanMs }
-  },
-  async set(key, value) {
-    doctorScanCache.set(key, {
-      ...value,
-      cachedAt: Date.now(),
-      dirMtimeMs: await statDirMtimeOrNull(key),
-    })
-  },
-}
-
 /** 旧布局残留条目（§6.11 U14b doctor 侧独立 glob 探测）。 */
 /** 旧布局残留探测单条命中（doctor 与 u14b 启动探测同源判据，§6.11）。 */
 export interface PiLayoutLeftover {
@@ -110,6 +44,8 @@ export interface PiLayoutLeftover {
  * 形态判据（与 u14b 启动探测 / u14a 脚本 0a 同源）：目录下含 `agent/` 或 `sessions/`
  * 子目录才算残留——防纯 pi 宿主下任意来源的 `~/.pi/pi/` 目录误报。读探测，每次现查
  * 不入缓存（两次 readdir 成本可忽略，缓存只服务扫盘贵的根）。
+ *
+ * 迁移期支持（A4 登记）：本探测服务于 v2 布局迁移窗口，全量迁移确认后可整段删除。
  */
 async function detectPiLayoutLeftovers(
   agentDir: string,
@@ -155,9 +91,8 @@ export async function doDoctor(
   })
   const roots = await resolveSessionRoots(signals, {
     // subagent 根默认只 stat（§6.3 成本控制：只列路径与可扫性）；includeSubagents:true
-    // 才扫（走同一缓存句柄）。find/F1 路径恒不传 options——不读缓存（§7B 要点 8）。
+    // 才扫。无缓存——每次实扫（原缓存机已删，ext-simplify-04 U3，§7B 要点 8 新态）。
     subagents: params.includeSubagents === true ? 'scan' : 'stat',
-    cache: doctorRootCache,
   })
   const leftovers = await detectPiLayoutLeftovers(signals.agentDir)
   return renderDoctor(roots, environment, leftovers)
@@ -206,19 +141,18 @@ function renderDoctor(
     }
     const facts = [r.exists ? '存在' : '不存在']
     if (r.fileCount === undefined) {
-      // 仅 subagents:'stat' 的 subagent 根（doctor 默认形态）——其余根恒有计数
-      //（实扫或缓存命中）；被去重根已在上方提前返回
+      // 仅 subagents:'stat' 的 subagent 根（doctor 默认形态）——其余根恒有计数（实扫）；
+      // 被去重根已在上方提前返回
       facts.push('未扫描（subagent 根默认不扫，includeSubagents:true 开启）')
     } else {
       facts.push(`${r.fileCount} 文件`, `扫 ${Math.round(r.scanMs ?? 0)}ms`)
     }
-    if (r.cached === true) facts.push('缓存命中')
     facts.push(r.source === 'main' ? 'main' : 'subagent')
     lines.push(`     ${facts.join(' · ')}`)
   })
 
   // 事实型诊断（§7B 要点 5）：列表内首个 main 根即最高优先级 main 根（去重只移除后位根，
-  // 首位根恒有计数——实扫或缓存命中）。0 文件也是事实——首条 assistant 前 jsonl 不落盘
+  // 首位根恒有计数——实扫）。0 文件也是事实——首条 assistant 前 jsonl 不落盘
   //（PS-14），不做归因。
   lines.push('')
   const firstMain = roots.find((r) => r.source === 'main')

package/src/extract.ts

@@ -4,9 +4,9 @@
  * 从 tool-handler.ts 机械提取（max-lines 拆分轮，零行为变更）。
  * design §3.3 D3 的 5 个预设 + F8/F9 规格；F7（what 校验）与 doExtract 编排
  *（resolveSessionId/safeParse/turns 范围限定依赖 tool-handler 私有定位层）留守
- * tool-handler，经本模块导出的 5 预设函数分发。renderExtractItems 导出面不变：
- * tool-handler re-export（单测 F9 白盒 import 路径不变）。纯提取，不调 LLM。
+ * tool-handler，经本模块导出的 5 预设函数分发。纯提取，不调 LLM。
  */
+import { textBlockParts } from './core/render.js'
 import { extractToolCalls, formatToolCallSummary, basename } from './core/toolcall.js'
 import type { Turn } from './core/turns.js'
 import { pad } from './handler-utils.js'
@@ -29,25 +29,12 @@ const SHORT_HASH_RE = /\b[0-9a-f]{7,8}\b/g
 const COMMIT_CTX_RE = /feat:|fix:|refactor:|chore:|docs:|\b(commit|commits|merged|pushed|merge)\b/i
 
 /**
- * 从 message.content 提取纯 text（string 直取；数组拼接 text 块）。
- *
- * 与 render.ts 内部 extractText 同语义，但那未导出；extract 仅需纯 text
- *（user-messages / tool-results 的正文），不要 thinking/toolCall 占位，本地实现。
- * content 是 unknown 做类型守卫。
+ * 从 message.content 提取纯 text（E11 归一：共享核 textBlockParts 组合调用，'\n' join
+ * 语义留在本调用点）。extract 仅需纯 text（user-messages / tool-results 的正文），
+ * 不要 thinking/toolCall 占位。
  */
 function extractContentText(content: unknown): string {
-  if (typeof content === 'string') return content
-  if (Array.isArray(content)) {
-    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.join('\n')
-  }
-  return ''
+  return textBlockParts(content).join('\n')
 }
 
 /** 截断到 max 字符，超出加省略号（防爆；tool-results 正文用）。 */