@zhushanwen/pi-session-reader 0.4.0 → 0.5.0

package/src/__tests__/index.test.ts

@@ -1,4 +1,7 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
 import { Check } from 'typebox/value'
 
@@ -13,19 +16,26 @@ import { Check } from 'typebox/value'
  * 4. typeof ctx.ui.addAutocompleteProvider 运行时守卫（ui 缺方法 → 跳过，不崩）
  * 5. registerCommand + addAutocompleteProvider 组装（tui 模式下各注册一次）
  * 6. TypeBox schema 与 SessionReadParams 对齐：合法 params 过、非法 action/scope 拒
+ * 7. U3 信号包采集降级：sessionManager 缺 getSessionDir 方法 / getSessionDir 抛错 →
+ *    liveSessionDir 降级 undefined，find 正常返回不抛（ctx===undefined 形态由 1 覆盖）
  *
  * 不触碰真实文件系统：getAgentDir mock 固定假路径（execute 用例只触发 F5 抛错路径，
  * 不读盘）。
  */
 
 // vi.mock 在 import 前 hoist；SessionManager stub 仅防 session-command/hash-provider
-// 模块加载期缺导出（本文件用例不调用它）
+// 模块加载期缺导出（本文件用例不调用它）。u11：state/listAll 经 vi.hoisted 可控——
+// getAgentDir 可指向真实 tmp fixture，listAll 为 spy，供 execute 接线断言。
+const piMocks = vi.hoisted(() => {
+  const state = { agentDir: '/tmp/pi-session-reader-test-agent' }
+  const listAll = vi.fn(async (_dir: string) => [] as Array<Record<string, unknown>>)
+  return { state, listAll }
+})
+
 vi.mock('@earendil-works/pi-coding-agent', () => ({
-  getAgentDir: () => '/tmp/pi-session-reader-test-agent',
+  getAgentDir: () => piMocks.state.agentDir,
   SessionManager: class {
-    static async listAll(): Promise<never[]> {
-      return []
-    }
+    static listAll = piMocks.listAll
   },
 }))
 
@@ -99,6 +109,119 @@ describe('sessionReaderExtension - execute 契约', () => {
   })
 })
 
+describe('sessionReaderExtension - execute 信号包采集（U3：ctx 全形态降级）', () => {
+  type ExecFn = (
+    toolCallId: string,
+    params: unknown,
+    signal: AbortSignal | undefined,
+    onUpdate: unknown,
+    ctx: unknown,
+  ) => Promise<{ content: Array<{ type: string; text: string }> }>
+
+  let execute: ExecFn
+
+  beforeEach(() => {
+    const fake = makeFakePi()
+    sessionReaderExtension(fake.pi as unknown as ExtensionAPI)
+    execute = (fake.registerTool.mock.calls[0][0] as { execute: ExecFn }).execute
+  })
+
+  // find 零匹配不抛（返回提示文本）——用例只断言「正常返回」降级语义，不碰真实数据目录
+  //（mock agentDir = /tmp/pi-session-reader-test-agent 及其派生根均不存在，扫描瞬时零文件）
+  const FIND_NO_MATCH = { action: 'find', query: 'zzznoindexmatch' } as const
+
+  it('sessionManager 存在但缺 getSessionDir 方法 → 降级 liveSessionDir=undefined，find 正常返回不抛', async () => {
+    const ctx = { mode: 'tui', sessionManager: {} }
+    const r = await execute('tc-u3-1', FIND_NO_MATCH, undefined, undefined, ctx)
+    expect(r.content[0]?.type).toBe('text')
+  })
+
+  it('getSessionDir 调用抛错 → 同样降级不抛（可选链只防缺失，调用抛错由 try/catch 兜住）', async () => {
+    const ctx = {
+      mode: 'tui',
+      sessionManager: {
+        getSessionDir: () => {
+          throw new Error('boom')
+        },
+      },
+    }
+    const r = await execute('tc-u3-2', FIND_NO_MATCH, undefined, undefined, ctx)
+    expect(r.content[0]?.type).toBe('text')
+  })
+
+  it('ctx 提供正常 getSessionDir → 信号被采集（调用一次）且 find 正常返回', async () => {
+    const getSessionDir = vi.fn(() => '/tmp/pi-session-reader-test-live-dir')
+    const ctx = { mode: 'tui', sessionManager: { getSessionDir } }
+    const r = await execute('tc-u3-3', FIND_NO_MATCH, undefined, undefined, ctx)
+    expect(getSessionDir).toHaveBeenCalledTimes(1)
+    expect(r.content[0]?.type).toBe('text')
+  })
+
+  it('u8：doctor 经 execute 走通——env/bundleUrl 补采 + ctx===undefined 降级仍出环境判定与根表', async () => {
+    // mock agentDir（/tmp/pi-session-reader-test-agent）及其派生根均不存在 → 根表全空仍渲染；
+    // 残留 glob 基点 = /tmp，只读 readdir（无写操作），不触碰任何真实数据目录。
+    const r = await execute('tc-u8-1', { action: 'doctor' }, undefined, undefined, undefined)
+    const text = r.content[0]?.text as string
+    expect(text).toContain('环境判定：')
+    // bundleUrl 信号已采集：测试内 import.meta.url 为仓库源码路径 → dev（非打包资源目录）
+    expect(text).toContain('发行形态：dev')
+    expect(text).toContain('会话根（按优先级）')
+  })
+
+  it('u11：execute 构造 metadataProvider 接 SessionManager.listAll——keyword 标题命中端到端', async () => {
+    // fixture：平铺 main 根（xyz-agent 形态），session 首消息不含 query，标题经 mock listAll 注入
+    const tmp = await mkdtemp(join(tmpdir(), 'index-u11-'))
+    try {
+      const agentDir = join(tmp, 'agent')
+      const liveDir = join(agentDir, 'sessions')
+      await mkdir(liveDir, { recursive: true })
+      const id = 'm-wire-0001'
+      await writeFile(
+        join(liveDir, 'a.jsonl'),
+        [
+          JSON.stringify({ type: 'session', id, cwd: '/demo' }),
+          JSON.stringify({
+            type: 'message',
+            id: `${id}-m1`,
+            message: { role: 'user', content: [{ type: 'text', text: '完全无关的首消息' }] },
+          }),
+        ].join('\n') + '\n',
+      )
+      piMocks.state.agentDir = agentDir
+      piMocks.listAll.mockResolvedValue([
+        {
+          path: join(liveDir, 'a.jsonl'),
+          id,
+          cwd: '/demo',
+          name: '接线标题命中',
+          modified: new Date(),
+          firstMessage: '完全无关的首消息',
+          created: new Date(),
+          messageCount: 1,
+          allMessagesText: '完全无关的首消息',
+        },
+      ])
+      const ctx = { mode: 'rpc', sessionManager: { getSessionDir: () => liveDir } }
+      const r = await execute('tc-u11-1', { action: 'find', query: '接线标题' }, undefined, undefined, ctx)
+      // provider 已接线：listAll 被调，且实参恒为非空串（永传非空串 guard）
+      expect(piMocks.listAll).toHaveBeenCalledTimes(1)
+      expect(piMocks.listAll.mock.calls[0][0]).toBe(liveDir)
+      expect(piMocks.listAll.mock.calls[0][0].length).toBeGreaterThan(0)
+      // 标题命中路径端到端：文本与 details 都带 name
+      const text = r.content[0]?.text as string
+      expect(text).toContain('接线标题命中')
+      const d = r.details as { matches: Array<{ sessionId: string; name?: string }> }
+      expect(d.matches[0]?.sessionId).toBe(id)
+      expect(d.matches[0]?.name).toBe('接线标题命中')
+    } finally {
+      // 还原 mock 态，不污染同文件其他用例
+      piMocks.state.agentDir = '/tmp/pi-session-reader-test-agent'
+      piMocks.listAll.mockReset()
+      await rm(tmp, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+    }
+  })
+})
+
 describe('sessionReaderExtension - session_start TUI 注册', () => {
   it('mode !== tui → 不注册 command/provider', () => {
     const fake = makeFakePi()
@@ -237,4 +360,33 @@ describe('sessionReaderExtension - TypeBox schema 与 SessionReadParams 对齐',
     expect(Check(schema, { action: 'family', session: 'x', recursive: 'yes' })).toBe(false)
     expect(Check(schema, { action: 'family', session: 'x', recursive: 1 })).toBe(false)
   })
+
+  it('limit 退化输入：minimum:1 在 schema 校验层拒绝 0/负数（不落入 find F1「无匹配」措辞面）', () => {
+    const fake = makeFakePi()
+    sessionReaderExtension(fake.pi as unknown as ExtensionAPI)
+    const toolDef = fake.registerTool.mock.calls[0][0] as { parameters: unknown }
+    const schema = toolDef.parameters
+
+    // 0/负数被 schema 拒绝（minimum:1），不会进入 find/F1 输出「无匹配 session」
+    expect(Check(schema, { action: 'find', query: 'x', limit: 0 })).toBe(false)
+    expect(Check(schema, { action: 'find', query: 'x', limit: -3 })).toBe(false)
+    // 正数合法；result 消费同一 limit 字段（正数合法）
+    expect(Check(schema, { action: 'find', query: 'x', limit: 1 })).toBe(true)
+    expect(Check(schema, { action: 'result', session: 'sa-x', limit: 100 })).toBe(true)
+    // 不传 limit 向后兼容（缺省语义不变）
+    expect(Check(schema, { action: 'find', query: 'x' })).toBe(true)
+  })
+
+  it('TC-u8-schema-doctor：action enum 含 doctor + includeSubagents optional boolean', () => {
+    const fake = makeFakePi()
+    sessionReaderExtension(fake.pi as unknown as ExtensionAPI)
+    const toolDef = fake.registerTool.mock.calls[0][0] as { parameters: unknown }
+    const schema = toolDef.parameters
+
+    expect(Check(schema, { action: 'doctor' })).toBe(true)
+    expect(Check(schema, { action: 'doctor', includeSubagents: true })).toBe(true)
+    expect(Check(schema, { action: 'doctor', includeSubagents: false })).toBe(true)
+    expect(Check(schema, { action: 'doctor', includeSubagents: 'yes' })).toBe(false)
+    expect(Check(schema, { action: 'doctor', includeSubagents: 1 })).toBe(false)
+  })
 })

package/src/__tests__/real-data.ts

@@ -16,6 +16,16 @@ import { join } from 'node:path'
 /** 真实 pi agent 目录（本机），用于集成测试。 */
 export const REAL_AGENT_DIR = '/Users/zhushanwen/.pi/agent'
 
+/**
+ * 全量扫描类真实数据用例的统一超时标定（90s）。
+ *
+ * 这类用例遍历本机 ~/.pi/agent 全量会话语料（实测 4600+ 文件），空载单用例已需 6-10s；
+ * 38 包并行全量测试时 CPU/IO 争抢可降速 3-4 倍，30s 标定必假红。90s ≈ 空载 9 倍余量，
+ * 仍能兜住真正的挂死。仅用于遍历全量语料的用例（findSessions / buildFamilyFromFs /
+ * listMainSessions 等）；读已知单文件的用例不需要放宽。
+ */
+export const REAL_DATA_TIMEOUT_MS = 90_000
+
 /** 5.4MB / 32 turn / 1204 entry 的真实 session（feat-plugin-arch-3 目录）。 */
 export const E6 = '019e6c96-0a0c-74b8-a73f-d1854d88e2a7'
 /** 真实 fork 家族根（fork 子代 019fe632，隔代 subagent 019fe635 挂在 019fe632 下）。 */

package/src/__tests__/result.test.ts

@@ -330,12 +330,12 @@ describe('result action（U6）', () => {
     ).rejects.toThrow(/空条目/)
   })
 
-  it('10. 未知 action 报错文案含 result（10 action 全列举）', async () => {
+  it('10. 未知 action 报错文案含 result（11 action 全列举，含 doctor）', async () => {
     await expect(
       handleSessionRead(
         { action: 'bogus' } as unknown as SessionReadParams,
         dir,
       ),
-    ).rejects.toThrow(/find\/family\/outline\/expand\/detail\/search\/export\/extract\/workflow\/result/)
+    ).rejects.toThrow(/find\/family\/outline\/expand\/detail\/search\/export\/extract\/workflow\/result\/doctor/)
   })
 })

package/src/__tests__/roots.test.ts

@@ -1,9 +1,26 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
 import { tmpdir } from 'node:os'
-import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises'
-import { join } from 'node:path'
-import { listMainSessions, listSubagentSessions } from '../discovery/roots.js'
-import { REAL_AGENT_DIR, HAS_E6, HAS_REAL_SUBAGENTS_DIR } from './real-data.js'
+import { mkdtemp, mkdir, readdir, writeFile, rm } from 'node:fs/promises'
+import { join, dirname } from 'node:path'
+import {
+  listMainSessions,
+  listSubagentSessions,
+  resolveSessionRoots,
+  normalizeLiveSessionDir,
+  type SessionRoot,
+  type SessionRootSignals,
+} from '../discovery/roots.js'
+import { buildFamilyFromFs } from '../discovery/subagents.js'
+import { REAL_AGENT_DIR, HAS_E6, HAS_REAL_AGENT_DIR, HAS_REAL_SUBAGENTS_DIR, REAL_DATA_TIMEOUT_MS } from './real-data.js'
+
+/** 写 .jsonl fixture（父目录不存在则自建），内容默认合法 session header */
+async function writeJsonl(path: string, content = '{"type":"session","id":"x"}\n') {
+  await mkdir(dirname(path), { recursive: true })
+  await writeFile(path, content)
+}
+
+/** 真实形态的 cwd 编码目录名（encodeCwd：`--` 开头 `--` 结尾，实证见 real-data.ts） */
+const SLUG = '--Users-foo--'
 
 describe('listMainSessions', () => {
   let dir: string
@@ -80,7 +97,7 @@ describe('listMainSessions', () => {
     expect(result.every((m) => !m.path.split('/').pop()!.startsWith('wf-'))).toBe(true)
     // mtime/size 真实
     expect(result.every((m) => m.mtime > 0 && m.size > 0)).toBe(true)
-  }, 30000)
+  }, REAL_DATA_TIMEOUT_MS)
 })
 
 describe('listSubagentSessions', () => {
@@ -128,5 +145,341 @@ describe('listSubagentSessions', () => {
     const result = await listSubagentSessions(REAL_AGENT_DIR)
     expect(result.length).toBeGreaterThan(0)
     expect(result.every((m) => !m.path.endsWith('.finalized'))).toBe(true)
-  }, 30000)
+  }, REAL_DATA_TIMEOUT_MS)
+})
+
+// ============================================================
+// U1 resolveSessionRoots（design 2026-09-10 §6.1 / §7B 要点 2/3/4/6/7；B 收缩无 [env]）
+// ============================================================
+
+/** 三宿主信号包用例的行内校验上下文 */
+interface HostCaseCtx {
+  tmp: string
+  agentDir: string
+}
+
+interface HostCase {
+  name: string
+  build: (tmp: string) => Promise<{ agentDir: string; signals: SessionRootSignals }>
+  verify: (ctx: HostCaseCtx, roots: SessionRoot[]) => void
+}
+
+const HOST_CASES: HostCase[] = [
+  {
+    name: '纯 pi：live=encodeCwd 子目录，剥层后与 default 同路径去重，保留 live 标签',
+    async build(tmp) {
+      const agentDir = join(tmp, 'agent')
+      await writeJsonl(join(agentDir, 'sessions', SLUG, 'a.jsonl'))
+      return {
+        agentDir,
+        signals: { agentDir, liveSessionDir: join(agentDir, 'sessions', SLUG) },
+      }
+    },
+    verify({ agentDir }, roots) {
+      // kind 序 = 优先级序（live > default > legacy > subagent；B 收缩无 env）
+      expect(roots.map((r) => r.kind)).toEqual(['live', 'default', 'legacy', 'subagent'])
+      const live = roots.find((r) => r.kind === 'live')!
+      // 剥层（§7B 要点 3）：父目录名为 sessions 的真实形态 → dirname
+      expect(live.path).toBe(join(agentDir, 'sessions'))
+      expect(live.exists).toBe(true)
+      expect(live.fileCount).toBe(1)
+      const def = roots.find((r) => r.kind === 'default')!
+      expect(def.path).toBe(join(agentDir, 'sessions'))
+      // realpath 去重（§7B 要点 4）：同路径只扫一次，保留最高优先级 kind
+      expect(def.dedupedInto).toBe('live')
+      expect(def.files).toHaveLength(0)
+      expect(def.fileCount).toBeUndefined()
+      // 该路径在全列表中只被一个根实扫（文件不重复计入）
+      const scannedAtSamePath = roots.filter(
+        (r) => r.path === join(agentDir, 'sessions') && r.dedupedInto === undefined,
+      )
+      expect(scannedAtSamePath).toHaveLength(1)
+      expect(roots.reduce((n, r) => n + r.files.length, 0)).toBe(1)
+    },
+  },
+  {
+    name: 'xyz-agent：live=根本身（RPC 覆盖态），default 去重，legacy 残留与 subagent 独立列出',
+    async build(tmp) {
+      const dataDir = join(tmp, 'data')
+      const agentDir = join(dataDir, 'agent')
+      await writeJsonl(join(agentDir, 'sessions', SLUG, 'x.jsonl'))
+      await writeJsonl(join(dataDir, 'sessions', 'old.jsonl')) // 旧旧布局迁移残留（§6.13 U1 行）
+      await writeJsonl(join(agentDir, 'subagents', SLUG, 'sessions', 's.jsonl'))
+      return { agentDir, signals: { agentDir, liveSessionDir: join(agentDir, 'sessions') } }
+    },
+    verify({ agentDir, tmp }, roots) {
+      expect(roots.map((r) => r.kind)).toEqual(['live', 'default', 'legacy', 'subagent'])
+      // live=根本身（basename 非 encodeCwd 形态）→ 取自身，与 default 同字面路径 → 去重
+      const scanned = roots.filter((r) => r.dedupedInto === undefined)
+      expect(scanned.map((r) => r.kind)).toEqual(['live', 'legacy', 'subagent'])
+      const live = scanned[0]!
+      expect(live.path).toBe(join(agentDir, 'sessions'))
+      expect(live.fileCount).toBe(1) // 递归扫到 encodeCwd 子目录内的文件
+      const def = roots.find((r) => r.kind === 'default')!
+      expect(def.dedupedInto).toBe('live')
+      // legacy（<dataDir>/sessions 残留）非空即纳入候选，独立成根
+      const legacy = roots.find((r) => r.kind === 'legacy')!
+      expect(legacy.path).toBe(join(tmp, 'data', 'sessions'))
+      expect(legacy.exists).toBe(true)
+      expect(legacy.fileCount).toBe(1)
+      const sub = roots.find((r) => r.kind === 'subagent')!
+      expect(sub.exists).toBe(true)
+      expect(sub.fileCount).toBe(1)
+      expect(sub.files[0]!.path.endsWith('s.jsonl')).toBe(true)
+    },
+  },
+  {
+    name: 'liveSessionDir 缺失降级：default/legacy/subagent 三根仍可用，无 live 根',
+    async build(tmp) {
+      const agentDir = join(tmp, 'agent')
+      await writeJsonl(join(agentDir, 'sessions', SLUG, 'a.jsonl'))
+      return { agentDir, signals: { agentDir } }
+    },
+    verify({ agentDir, tmp }, roots) {
+      expect(roots.map((r) => r.kind)).toEqual(['default', 'legacy', 'subagent'])
+      const def = roots.find((r) => r.kind === 'default')!
+      expect(def.path).toBe(join(agentDir, 'sessions'))
+      expect(def.exists).toBe(true)
+      expect(def.fileCount).toBe(1)
+      expect(roots.find((r) => r.kind === 'legacy')!.path).toBe(join(tmp, 'sessions'))
+      // live 缺席 → 无去重发生
+      expect(roots.every((r) => r.dedupedInto === undefined)).toBe(true)
+    },
+  },
+]
+
+describe('resolveSessionRoots', () => {
+  it.each(HOST_CASES)('$name', async ({ build, verify }) => {
+    const tmp = await mkdtemp(join(tmpdir(), 'roots-resolve-'))
+    try {
+      const { agentDir, signals } = await build(tmp)
+      const roots = await resolveSessionRoots(signals)
+
+      // ④ subagent 根恒在（常量推导，不来自任何信号，§6.1 信号 5）
+      const sub = roots.find((r) => r.kind === 'subagent')
+      expect(sub).toBeDefined()
+      expect(sub!.source).toBe('subagent')
+      expect(sub!.path).toBe(join(agentDir, 'subagents'))
+
+      // ⑤ 已扫描根 fileCount/scanMs 恒填充且与 files 一致；被去重根不产生扫描统计
+      for (const r of roots) {
+        if (r.dedupedInto !== undefined) {
+          expect(r.fileCount).toBeUndefined()
+          expect(r.scanMs).toBeUndefined()
+        } else {
+          expect(typeof r.fileCount).toBe('number')
+          expect(r.fileCount).toBe(r.files.length)
+          expect(typeof r.scanMs).toBe('number')
+          expect(r.scanMs!).toBeGreaterThanOrEqual(0)
+        }
+      }
+
+      verify({ tmp, agentDir }, roots)
+    } finally {
+      await rm(tmp, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+    }
+  })
+
+  it('[live] 规范化第二形态：普通目录（basename 非 encodeCwd 形态）取自身，不剥层', async () => {
+    const tmp = await mkdtemp(join(tmpdir(), 'roots-live-plain-'))
+    try {
+      const agentDir = join(tmp, 'agent')
+      const liveDir = join(tmp, 'live-sessions')
+      await writeJsonl(join(liveDir, 'b.jsonl'))
+
+      const roots = await resolveSessionRoots({ agentDir, liveSessionDir: liveDir })
+      const live = roots.find((r) => r.kind === 'live')!
+      expect(live.path).toBe(liveDir)
+      expect(live.exists).toBe(true)
+      expect(live.fileCount).toBe(1)
+      // default/legacy 独立列出，互不干扰
+      expect(roots.find((r) => r.kind === 'default')!.path).toBe(join(agentDir, 'sessions'))
+      expect(roots.every((r) => r.dedupedInto === undefined)).toBe(true)
+    } finally {
+      await rm(tmp, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+    }
+  })
+
+  it('空 agentDir 防御：不派生任何根（避免扫到进程 cwd 相对路径）', async () => {
+    await expect(resolveSessionRoots({ agentDir: '' })).resolves.toEqual([])
+  })
+
+  it.skipIf(!HAS_REAL_AGENT_DIR)(
+    '§11.2 真实路径集合回归：encodeCwd 判据在真实 sessions 子目录上自洽，剥层分支被真实数据覆盖',
+    async () => {
+      const sessionsDir = join(REAL_AGENT_DIR, 'sessions')
+      const entries = await readdir(sessionsDir, { withFileTypes: true })
+      const dirs = entries.filter((e) => e.isDirectory())
+      expect(dirs.length).toBeGreaterThan(0)
+      let encodeCwdCount = 0
+      for (const d of dirs) {
+        const asLive = join(sessionsDir, d.name)
+        const matchesShape = d.name.startsWith('--') && d.name.endsWith('--')
+        // 判据自洽：匹配形态 → 剥层到父目录；不匹配（如 permission-forwarding/）→ 取自身
+        expect(normalizeLiveSessionDir(asLive)).toBe(matchesShape ? sessionsDir : asLive)
+        if (matchesShape) encodeCwdCount++
+      }
+      // 真实集合以 encodeCwd 目录为主体——剥层分支确实被真实数据覆盖
+      expect(encodeCwdCount).toBeGreaterThan(0)
+    },
+    30000,
+  )
+})
+
+describe('buildFamilyFromFs not-found 文案（U1 并入：列实际扫描候选根）', () => {
+  let tmp: string
+
+  beforeEach(async () => {
+    tmp = await mkdtemp(join(tmpdir(), 'roots-notfound-'))
+  })
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+  })
+
+  it('错误信息含各候选根路径、kind 标签与文件数（default/legacy），保留 findSessions 指引', async () => {
+    const agentDir = join(tmp, 'data', 'agent')
+    await writeJsonl(
+      join(agentDir, 'sessions', SLUG, 'known.jsonl'),
+      '{"type":"session","id":"known-id"}\n',
+    )
+
+    const msg = await buildFamilyFromFs('missing-id', agentDir).then(
+      () => {
+        throw new Error('buildFamilyFromFs should reject for unknown sessionId')
+      },
+      (e: unknown) => (e instanceof Error ? e.message : String(e)),
+    )
+    expect(msg).toContain('not found')
+    expect(msg).toContain(join(agentDir, 'sessions'))
+    expect(msg).toContain('[default]')
+    expect(msg).toContain('1 file(s)')
+    expect(msg).toContain(join(tmp, 'data', 'sessions'))
+    expect(msg).toContain('[legacy]')
+    expect(msg).toContain('not exists')
+    // 只列 main 候选根（collectMainSessions 实扫集合），不含 subagent 根
+    expect(msg).not.toContain('[subagent]')
+    expect(msg).toContain('findSessions')
+  })
+})
+
+// ============================================================
+// u8 追加：resolveSessionRoots options（doctor 统一数据源，design §6.3「同一数据源
+// 两处渲染，不重复实现探测」——subagent 扫描模式与进程内缓存经 options 由调用方
+// 驱动，本模块不内置 TTL/mtime 失效逻辑）
+// ============================================================
+
+describe('resolveSessionRoots options（u8：subagents 模式 + 注入式缓存）', () => {
+  /** 最小 fixture：default 根 1 文件 + subagent 根 1 文件（legacy 不存在） */
+  async function buildMinimalFixture(): Promise<{ tmp: string; agentDir: string }> {
+    const tmp = await mkdtemp(join(tmpdir(), 'roots-opts-'))
+    const agentDir = join(tmp, 'agent')
+    await mkdir(join(agentDir, 'sessions', SLUG), { recursive: true })
+    await writeFile(join(agentDir, 'sessions', SLUG, 'a.jsonl'), '{"type":"session"}\n')
+    await mkdir(join(agentDir, 'subagents', SLUG, 'sessions'), { recursive: true })
+    await writeFile(join(agentDir, 'subagents', SLUG, 'sessions', 's.jsonl'), '{"type":"session"}\n')
+    return { tmp, agentDir }
+  }
+
+  it("subagents:'stat'：subagent 根只 stat（无计数/耗时/files 空），main 根照常实扫", async () => {
+    const { tmp, agentDir } = await buildMinimalFixture()
+    try {
+      const roots = await resolveSessionRoots({ agentDir }, { subagents: 'stat' })
+      const sub = roots.find((r) => r.kind === 'subagent')!
+      expect(sub.exists).toBe(true)
+      expect(sub.fileCount).toBeUndefined()
+      expect(sub.scanMs).toBeUndefined()
+      expect(sub.files).toEqual([])
+      expect(sub.dedupedInto).toBeUndefined()
+      // main 根不受影响：照常实扫
+      const def = roots.find((r) => r.kind === 'default')!
+      expect(def.fileCount).toBe(1)
+      expect(def.files).toHaveLength(1)
+    } finally {
+      await rm(tmp, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+    }
+  })
+
+  it("options 缺省与 subagents:'scan'：subagent 根照旧全扫（现有调用方零破坏）", async () => {
+    const { tmp, agentDir } = await buildMinimalFixture()
+    try {
+      for (const options of [undefined, { subagents: 'scan' as const }]) {
+        const roots = await resolveSessionRoots({ agentDir }, options)
+        const sub = roots.find((r) => r.kind === 'subagent')!
+        expect(sub.fileCount).toBe(1)
+        expect(sub.files).toHaveLength(1)
+      }
+    } finally {
+      await rm(tmp, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+    }
+  })
+
+  it('cache：未命中实扫后 set 回写；命中以缓存值构造根（cached 标记、files 空、不再回写）', async () => {
+    const { tmp, agentDir } = await buildMinimalFixture()
+    try {
+      const store = new Map<string, { exists: boolean; fileCount: number; scanMs: number }>()
+      const setSpy = vi.fn((key: string, value: { exists: boolean; fileCount: number; scanMs: number }) => {
+        store.set(key, value)
+      })
+      const getSpy = vi.fn(async (key: string) => store.get(key))
+      const cache = { get: getSpy, set: setSpy }
+
+      // 首扫：get 未命中 → 实扫 → 逐非去重根 set（default + legacy + subagent = 3）
+      const first = await resolveSessionRoots({ agentDir }, { cache })
+      const firstDef = first.find((r) => r.kind === 'default')!
+      expect(firstDef.cached).toBeUndefined()
+      expect(firstDef.fileCount).toBe(1)
+      expect(getSpy).toHaveBeenCalled()
+      expect(setSpy).toHaveBeenCalledTimes(3)
+
+      // 二扫：命中 → 缓存值即数据源，无新回写
+      const second = await resolveSessionRoots({ agentDir }, { cache })
+      const secondDef = second.find((r) => r.kind === 'default')!
+      expect(secondDef.cached).toBe(true)
+      expect(secondDef.fileCount).toBe(1)
+      expect(secondDef.files).toEqual([])
+      expect(setSpy).toHaveBeenCalledTimes(3)
+    } finally {
+      await rm(tmp, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+    }
+  })
+
+  it('cache 命中值优先于磁盘（roots 不旁路缓存实扫——TTL/mtime 失效语义全在缓存实现侧）', async () => {
+    const { tmp, agentDir } = await buildMinimalFixture()
+    try {
+      const setSpy = vi.fn()
+      const cache = {
+        get: async () => ({ exists: true, fileCount: 99, scanMs: 7 }),
+        set: setSpy,
+      }
+      const roots = await resolveSessionRoots({ agentDir }, { cache })
+      const def = roots.find((r) => r.kind === 'default')!
+      expect(def.fileCount).toBe(99)
+      expect(def.scanMs).toBe(7)
+      expect(def.cached).toBe(true)
+      expect(def.files).toEqual([])
+      expect(setSpy).not.toHaveBeenCalled() // 命中不回写
+    } finally {
+      await rm(tmp, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+    }
+  })
+
+  it("stat × cache 组合：'stat' 的 subagent 根不产缓存条目（缓存只服务扫盘贵的根）", async () => {
+    const { tmp, agentDir } = await buildMinimalFixture()
+    try {
+      const setKeys: string[] = []
+      await resolveSessionRoots({ agentDir }, {
+        subagents: 'stat',
+        cache: {
+          get: async () => undefined,
+          set: (key) => {
+            setKeys.push(key)
+          },
+        },
+      })
+      expect(setKeys).not.toContain(join(agentDir, 'subagents'))
+      expect(setKeys).toContain(join(agentDir, 'sessions'))
+    } finally {
+      await rm(tmp, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+    }
+  })
 })

package/src/__tests__/subagents.test.ts

@@ -10,6 +10,7 @@ import {
   extractSessionIdFromFilename,
   type RecordManifest,
 } from '../discovery/subagents.js'
+import { REAL_DATA_TIMEOUT_MS } from './real-data.js'
 
 // ---- fixture 常量（uuid 特征，满足 extractSessionIdFromFilename + 互不为子串）----
 const ROOT = '0aaaaaaa-bbbb-7ccc-dddd-000000000001'
@@ -471,7 +472,7 @@ describe.skipIf(!HAS_REAL_ROOT)('buildFamilyFromFs - 真实数据 ~/.pi/agent',
     )
     expect(sub).toBeDefined()
     expect(sub!.sessionId.startsWith('sa-')).toBe(false)
-  }, 30000)
+  }, REAL_DATA_TIMEOUT_MS)
 })
 
 describe.skipIf(!HAS_REAL_WF)('buildFamilyFromFs - 真实 workflow 数据', () => {
@@ -500,7 +501,7 @@ describe.skipIf(!HAS_REAL_WF)('buildFamilyFromFs - 真实 workflow 数据', () =
     // stateFile 是 wf-state 文件绝对路径
     expect(rich!.stateFile.endsWith('.jsonl')).toBe(true)
     expect(rich!.runId.startsWith('wf-')).toBe(true)
-  }, 30000)
+  }, REAL_DATA_TIMEOUT_MS)
 })
 
 // ============================================================
@@ -735,5 +736,5 @@ describe.skipIf(!HAS_REAL_ROOT || !HAS_REAL_SUBAGENTS_DIR)('U4 真实数据守
 
     // 所有 subagent 的 sessionFile 非空（manifest.sessionFile 或 alive meta.path）
     expect(family.subagents.every((s) => typeof s.sessionFile === 'string' && s.sessionFile.length > 0)).toBe(true)
-  }, 30000)
+  }, REAL_DATA_TIMEOUT_MS)
 })