@zhushanwen/pi-session-reader 0.3.1 → 0.5.0

package/src/__tests__/find.test.ts

@@ -1,9 +1,9 @@
-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, utimes } from 'node:fs/promises'
 import { join } from 'node:path'
 import { findSessions } from '../discovery/find.js'
-import { REAL_AGENT_DIR, HAS_E6, HAS_REAL_SUBAGENTS_DIR } from './real-data.js'
+import { REAL_AGENT_DIR, HAS_E6, HAS_REAL_SUBAGENTS_DIR, REAL_DATA_TIMEOUT_MS } from './real-data.js'
 
 /**
  * 建一个假 session 文件：首行 header（type=session，含 id/cwd/parentSession），
@@ -43,9 +43,9 @@ async function makeSession(
 }
 
 /**
- * 建 records manifest（U5 fixture）。manifest 在 subagent 创建时写入 records/<sa-id>.json，
- * sessionFile 指向 alive subagent session 的绝对路径（find 用 extractSessionIdFromFilename
- * 从该路径提取 sessionId 建索引）。
+ * 建 records manifest（U5 fixture）。manifest 由终态 finalize 或 sync 批落标出口写入
+ * records/<sa-id>.json（创建时不写），sessionFile 指向 alive subagent session 的绝对路径
+ * （find 用 extractSessionIdFromFilename 从该路径提取 sessionId 建索引）。
  */
 async function makeRecordManifest(
   recordsDir: string,
@@ -523,7 +523,7 @@ describe('findSessions', () => {
         expect(matches.every((m) => m.source === 'subagent')).toBe(true)
         expect(typeof truncated).toBe('boolean')
       },
-      30000,
+      REAL_DATA_TIMEOUT_MS,
     )
   })
 
@@ -536,7 +536,7 @@ describe('findSessions', () => {
     expect(hit.fileName).toContain('019e6c96')
     expect(hit.mtime).toBeGreaterThan(0)
     expect(hit.sizeBytes).toBeGreaterThan(0)
-  }, 30000)
+  }, REAL_DATA_TIMEOUT_MS)
 
   it.skipIf(!HAS_E6)("真实数据：recent 返回最近 N 个，mtime 倒序，truncated=true", async () => {
     const { matches, truncated } = await findSessions('recent', REAL_AGENT_DIR, { limit: 5 })
@@ -548,7 +548,7 @@ describe('findSessions', () => {
     }
     // 真实 session 文件远多于 5 → 截断
     expect(truncated).toBe(true)
-  }, 30000)
+  }, REAL_DATA_TIMEOUT_MS)
 
   it.skipIf(!HAS_REAL_SUBAGENTS_DIR)(
     "真实数据：source:'subagent' 能找到 completed subagent（§7 场景 1 find 部分）",
@@ -564,6 +564,211 @@ describe('findSessions', () => {
         expect(m.fileName).toContain('subagents')
       }
     },
-    30000,
+    REAL_DATA_TIMEOUT_MS,
   )
 })
+
+// ============================================================
+// u11：标题元数据 metadataProvider 注入（design 2026-09-10 §6.6）
+// 覆盖三条调用策略中的 ①惰性 ②窄化（TTL 缓存句柄在 tool-handler 注入侧，
+// 见 tool-handler.test.ts u11 段）+ 两条 guard + §11.3b 多目录合并语义
+// + 纯 TS 首条 user 降级路径保留。
+// provider 一律注入替身（不真调 pi SessionManager）。
+// ============================================================
+describe('u11 标题元数据（metadataProvider 注入，§6.6）', () => {
+  let root: string
+  let agentDir: string
+  /** 平铺 main 根（xyz-agent 形态：session 直在 sessions/ 下，[default] 根无子目录） */
+  let flatMain: string
+  /** legacy 根（dirname(agentDir)/sessions） */
+  let legacyDir: string
+
+  async function writeSession(
+    dir: string,
+    opts: { name: string; id: string; cwd?: string; firstUserText?: string },
+  ): Promise<string> {
+    await mkdir(dir, { recursive: true })
+    const lines = [JSON.stringify({ type: 'session', id: opts.id, cwd: opts.cwd ?? '/demo' })]
+    if (opts.firstUserText !== undefined) {
+      lines.push(
+        JSON.stringify({
+          type: 'message',
+          id: `${opts.id}-m1`,
+          message: { role: 'user', content: [{ type: 'text', text: opts.firstUserText }] },
+        }),
+      )
+    }
+    const path = join(dir, opts.name)
+    await writeFile(path, lines.join('\n') + '\n')
+    return path
+  }
+
+  beforeEach(async () => {
+    // agentDir 挂在 mkdtemp 子目录下，legacy 根（dirname(agentDir)/sessions）仍在
+    // 自建 tmp 树内，不污染共享 tmpdir（也不受其他用例残留影响）
+    root = await mkdtemp(join(tmpdir(), 'find-u11-'))
+    agentDir = join(root, 'agent')
+    flatMain = join(agentDir, 'sessions')
+    legacyDir = join(root, 'sessions')
+  })
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+  })
+
+  it('① 惰性触发：uuid 精确/归一化路径不调 provider（spy 计数 0）', async () => {
+    await writeSession(flatMain, { name: 'a.jsonl', id: '019cafe00001', firstUserText: '无关' })
+    const provider = vi.fn(async () => [])
+    // 精确子串层命中
+    await findSessions('019cafe00001', agentDir, { metadataProvider: provider })
+    expect(provider).not.toHaveBeenCalled()
+    // 归一化层命中（大写变体：精确层大小写敏感 0 命中，norm 层命中后短路）
+    await findSessions('019CAFE00001', agentDir, { metadataProvider: provider })
+    expect(provider).not.toHaveBeenCalled()
+  })
+
+  it('② keyword 路径调用 provider 且标题进匹配（name 命中，preview 取元数据首消息免深读）', async () => {
+    const pathA = await writeSession(flatMain, {
+      name: 'a.jsonl',
+      id: 'title-aaaa',
+      firstUserText: '首消息完全无关',
+    })
+    await writeSession(flatMain, { name: 'b.jsonl', id: 'title-bbbb', firstUserText: '另一个无关会话' })
+    const provider = vi.fn(async (dir: string) =>
+      dir === flatMain
+        ? [
+            {
+              path: pathA,
+              id: 'title-aaaa',
+              cwd: '/demo',
+              name: '福耀玻璃深度研究',
+              modified: new Date('2026-09-01'),
+              firstMessage: '首消息完全无关',
+            },
+          ]
+        : [],
+    )
+    const { matches } = await findSessions('福耀玻璃', agentDir, { metadataProvider: provider })
+    // 平铺存在的 [default] 根被调用，且永传非空串
+    expect(provider).toHaveBeenCalledTimes(1)
+    expect(provider.mock.calls[0][0]).toBe(flatMain)
+    expect(provider.mock.calls[0][0].length).toBeGreaterThan(0)
+    // 标题命中：name 透传 + preview 取元数据 firstMessage
+    expect(matches).toHaveLength(1)
+    expect(matches[0].sessionId).toBe('title-aaaa')
+    expect(matches[0].name).toBe('福耀玻璃深度研究')
+    expect(matches[0].firstMessagePreview).toBe('首消息完全无关')
+  })
+
+  it('③ 窄化：含子目录根跳过 provider，候选不退出 keyword 匹配（回退首条 user，标题留空）', async () => {
+    // 纯 pi 形态：文件在 encodeCwd 子目录 → [default] 根含子目录 → listAll 跳过
+    await writeSession(join(flatMain, '--Users-demo--'), {
+      name: 'a.jsonl',
+      id: 'nested-aaaa',
+      firstUserText: '重构插件架构 plugin review',
+    })
+    const provider = vi.fn(async () => [])
+    const { matches } = await findSessions('plugin', agentDir, { metadataProvider: provider })
+    expect(provider).not.toHaveBeenCalled()
+    expect(matches).toHaveLength(1)
+    expect(matches[0].sessionId).toBe('nested-aaaa')
+    expect(matches[0].firstMessagePreview).toContain('plugin')
+    // 标题维度降级留空：「能找到 session」不受影响（§6.6 降级路径）
+    expect(matches[0].name).toBeUndefined()
+  })
+
+  it('④ guard：provider 抛错降级（标题留空 + 不抛，回退首条 user 匹配）', async () => {
+    await writeSession(flatMain, {
+      name: 'a.jsonl',
+      id: 'err-aaaa',
+      firstUserText: '按首条消息命中的文本',
+    })
+    const provider = vi.fn(async () => {
+      throw new Error('listAll boom')
+    })
+    const { matches } = await findSessions('按首条消息命中', agentDir, {
+      metadataProvider: provider,
+    })
+    expect(provider).toHaveBeenCalledTimes(1) // 调用了但抛错
+    expect(matches).toHaveLength(1)
+    expect(matches[0].sessionId).toBe('err-aaaa')
+    expect(matches[0].name).toBeUndefined()
+    expect(matches[0].firstMessagePreview).toContain('按首条消息命中')
+  })
+
+  it('⑤ 多目录结果合并：按 id 去重、重复取新 modified（§11.3b）', async () => {
+    const pathA = await writeSession(flatMain, {
+      name: 'a.jsonl',
+      id: 'dup-id-0001',
+      firstUserText: '无关',
+    })
+    // legacy 根平铺存在（0 文件也算存在根，isFlatRoot 空集恒真）
+    await mkdir(legacyDir, { recursive: true })
+    const provider = vi.fn(async (dir: string) =>
+      dir === flatMain
+        ? [{ path: pathA, id: 'dup-id-0001', cwd: '/demo', name: '旧标题', modified: 1000 }]
+        : [{ path: pathA, id: 'dup-id-0001', cwd: '/demo', name: '新标题', modified: 2000 }],
+    )
+    const { matches } = await findSessions('新标题', agentDir, { metadataProvider: provider })
+    expect(provider).toHaveBeenCalledTimes(2) // 两个平铺存在的根各一次
+    expect(matches).toHaveLength(1)
+    expect(matches[0].name).toBe('新标题') // 同 id 重复 → 取新 modified 的条目
+    const miss = await findSessions('旧标题', agentDir, { metadataProvider: provider })
+    expect(miss.matches).toHaveLength(0) // 旧条目已按合并规则丢弃
+  })
+
+  it('⑥ guard：仅对存在的根调用且永传非空串（不存在根 / 不存在 liveSessionDir 不调）', async () => {
+    await writeSession(flatMain, { name: 'a.jsonl', id: 'guard-aaaa', firstUserText: '无关' })
+    const provider = vi.fn(async () => [])
+    await findSessions('zzznohit9q', agentDir, {
+      liveSessionDir: join(agentDir, 'no-such-dir'),
+      metadataProvider: provider,
+    })
+    // 仅平铺存在的 [default] 根被调；不存在的 liveSessionDir 与 [legacy] 根均被排除
+    expect(provider).toHaveBeenCalledTimes(1)
+    expect(provider.mock.calls[0][0]).toBe(flatMain)
+    expect(provider.mock.calls.every((c) => typeof c[0] === 'string' && c[0].length > 0)).toBe(true)
+  })
+
+  it('⑥b liveSessionDir 与平铺根同字面路径 → 同目录只调一次（字面路径去重）', async () => {
+    await writeSession(flatMain, { name: 'a.jsonl', id: 'dedup-aaaa', firstUserText: '无关' })
+    const provider = vi.fn(async () => [])
+    await findSessions('zzznohit9q', agentDir, {
+      liveSessionDir: flatMain,
+      metadataProvider: provider,
+    })
+    expect(provider).toHaveBeenCalledTimes(1)
+    expect(provider.mock.calls[0][0]).toBe(flatMain)
+  })
+
+  it('⑦ recent：仅对 limit 截断后的少数候选补元数据（旧候选所在根不调）', async () => {
+    const pNew1 = await writeSession(flatMain, { name: 'n1.jsonl', id: 'recent-new-1' })
+    const pNew2 = await writeSession(flatMain, { name: 'n2.jsonl', id: 'recent-new-2' })
+    await writeSession(legacyDir, { name: 'o1.jsonl', id: 'recent-old-1' })
+    await writeSession(legacyDir, { name: 'o2.jsonl', id: 'recent-old-2' })
+    const base = Math.floor(Date.now() / 1000)
+    await utimes(pNew1, base + 300, base + 300)
+    await utimes(pNew2, base + 200, base + 200)
+    await utimes(join(legacyDir, 'o1.jsonl'), base + 100, base + 100)
+    await utimes(join(legacyDir, 'o2.jsonl'), base + 50, base + 50)
+    const provider = vi.fn(async (dir: string) =>
+      dir === flatMain
+        ? [
+            { path: pNew1, id: 'recent-new-1', cwd: '/demo', name: '最新标题一', modified: (base + 300) * 1000 },
+            { path: pNew2, id: 'recent-new-2', cwd: '/demo', name: '最新标题二', modified: (base + 200) * 1000 },
+          ]
+        : [],
+    )
+    const { matches, truncated } = await findSessions('recent', agentDir, {
+      limit: 2,
+      metadataProvider: provider,
+    })
+    expect(truncated).toBe(true)
+    expect(matches.map((m) => m.sessionId)).toEqual(['recent-new-1', 'recent-new-2'])
+    // provider 只调最新两个候选所在的平铺根；被截断的 legacy 根候选不触发补元数据
+    expect(provider).toHaveBeenCalledTimes(1)
+    expect(provider.mock.calls[0][0]).toBe(flatMain)
+    // 截断后少数候选补到标题
+    expect(matches[0].name).toBe('最新标题一')
+    expect(matches[1].name).toBe('最新标题二')
+  })
+})

package/src/__tests__/hash-provider.test.ts

@@ -242,7 +242,7 @@ describe('provideHashCandidates', () => {
     await mkdir(otherCwdDir, { recursive: true })
   })
   afterEach(async () => {
-    await rm(agentDir, { recursive: true, force: true })
+    await rm(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
   })
 
   it('非 # 输入 → null（委托下家 provider）', async () => {
@@ -377,7 +377,7 @@ describe('createHashAutocompleteProvider - getSuggestions', () => {
     await mkdir(cwdSessionDir, { recursive: true })
   })
   afterEach(async () => {
-    await rm(agentDir, { recursive: true, force: true })
+    await rm(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
   })
 
   it('signal.aborted → 早退返 null，不调 current、不做 IO', async () => {

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 下）。 */