@zhushanwen/pi-session-reader 0.1.0 → 0.2.1

package/src/__tests__/family.test.ts

@@ -6,6 +6,7 @@ import type { Entry } from '../core/parser.js'
 const ROOT = '019fe620' // 家族根（无 parentSession）
 const FORK = '019fe632' // fork 子代（parentSession 指向 ROOT 的文件）
 const SUB = '019fe635' // subagent（rootSessionId=FORK，挂在 fork 子代下，非家族根）
+const SUB2 = '019fe636' // U4 第二个 subagent（多 subagent 场景）
 
 // ---- fixture helpers ----
 
@@ -32,6 +33,31 @@ function subagentIdentity(id: string, rootSessionId: string, slug: string): Entr
   }
 }
 
+/** U4 富字段（可选，模拟 manifest 主/P-fallback identity 回退组装的 data） */
+interface SubagentRichFields {
+  task?: string
+  agent?: string
+  model?: string
+  status?: string
+  sessionFile?: string
+}
+
+/** 构造带 U4 富字段的 subagent-identity custom entry（manifest 主/P-fallback 两种 data 形态） */
+function subagentIdentityRich(
+  id: string,
+  rootSessionId: string,
+  slug: string,
+  rich?: SubagentRichFields,
+): Entry {
+  const data: Record<string, unknown> = { rootSessionId, slug }
+  if (rich?.task !== undefined) data.task = rich.task
+  if (rich?.agent !== undefined) data.agent = rich.agent
+  if (rich?.model !== undefined) data.model = rich.model
+  if (rich?.status !== undefined) data.status = rich.status
+  if (rich?.sessionFile !== undefined) data.sessionFile = rich.sessionFile
+  return { type: 'custom', id, parentId: null, customType: 'subagent-identity', data }
+}
+
 /** 构造 fileStats Map（M1 key=sessionId） */
 function makeStats(
   keys: string[],
@@ -205,3 +231,127 @@ describe('resolveFamily - 错误', () => {
     expect(() => resolveFamily('unknown-session', index)).toThrow(/not found in family index/)
   })
 })
+
+// ============================================================
+// U4: SubagentRef 富字段（manifest 主 / P-fallback identity 回退）
+// 验证 buildFamilyIndex 从 identity entry.data 读 task/agent/model/status/sessionFile
+// 填 SubagentRef，异名映射（data.agent → agentName），守卫放宽（只校验 rootSessionId+slug）。
+// ============================================================
+
+describe('U4: SubagentRef 富字段（buildFamilyIndex 透传）', () => {
+  it('TC-u4-manifest-enrich: manifest 主路径，富字段全透传到 SubagentRef', () => {
+    const identities = [
+      subagentIdentityRich(SUB, ROOT, 'codex-research', {
+        task: '调研 codex',
+        agent: 'explorer',
+        model: 'glm-5.2',
+        status: 'completed',
+        sessionFile: '/path/to/sub.jsonl',
+      }),
+    ]
+    const index = buildFamilyIndex([header(ROOT)], identities, makeStats([ROOT, SUB]))
+
+    const sub = resolveFamily(ROOT, index).subagents.find((s) => s.sessionId === SUB)
+    expect(sub?.task).toBe('调研 codex')
+    expect(sub?.slug).toBe('codex-research')
+    // 异名映射核心断言：identity.data.agent → SubagentRef.agentName
+    expect(sub?.agentName).toBe('explorer')
+    expect(sub?.model).toBe('glm-5.2')
+    expect(sub?.status).toBe('completed')
+    expect(sub?.sessionFile).toBe('/path/to/sub.jsonl')
+    expect(sub?.cleanedUp).toBe(false)
+  })
+
+  it('TC-u4-pfallback-identity: P-fallback（有 identity 无 model/status），task/agent/sessionFile 透传', () => {
+    const identities = [
+      subagentIdentityRich(SUB, ROOT, 'fix', {
+        task: 'fix bug',
+        agent: 'worker',
+        sessionFile: '/alive/sub.jsonl',
+        // 无 model/status（P-fallback identity 不含这两项，探针 15/15 确认）
+      }),
+    ]
+    const index = buildFamilyIndex([header(ROOT)], identities, makeStats([ROOT, SUB]))
+
+    const sub = resolveFamily(ROOT, index).subagents.find((s) => s.sessionId === SUB)
+    expect(sub?.task).toBe('fix bug')
+    expect(sub?.slug).toBe('fix')
+    expect(sub?.agentName).toBe('worker')
+    expect(sub?.sessionFile).toBe('/alive/sub.jsonl')
+    // P-fallback 核心断言：model/status 必 undefined（identity 不可回退）
+    expect(sub?.model).toBeUndefined()
+    expect(sub?.status).toBeUndefined()
+  })
+
+  it('TC-u4-pfallback-no-identity: data 缺 rootSessionId → 守卫拒掉，不入 subagentsByRoot，不抛错', () => {
+    // 模拟无 identity（运行中/异常，尾行是 message 非 identity）：data 只有 slug 无 rootSessionId
+    const noRoot: Entry = {
+      type: 'custom',
+      id: 'no-root',
+      parentId: null,
+      customType: 'subagent-identity',
+      data: { slug: 'dangling', task: 't' }, // 缺 rootSessionId
+    }
+    const index = buildFamilyIndex([header(ROOT)], [noRoot], makeStats([ROOT]))
+
+    // 守卫拒掉 → 不入 subagentsByRoot
+    expect(index.subagentsByRoot.size).toBe(0)
+    // resolveFamily 不抛错，subagents 空
+    const family = resolveFamily(ROOT, index)
+    expect(family.subagents).toHaveLength(0)
+  })
+
+  it('TC-u4-orphan-manifest: fileStats 不含 id → cleanedUp=true，富字段仍透传（GC 路径保留）', () => {
+    const identities = [
+      subagentIdentityRich('sa-ghost', ROOT, 'ghost-slug', {
+        task: 'ghost task',
+        agent: 'worker',
+        model: 'gpt-4',
+        status: 'completed',
+        sessionFile: '/gc/ghost.jsonl',
+      }),
+    ]
+    // fileStats 不含 'sa-ghost'（模拟 .jsonl 被 GC，manifest 残留）→ cleanedUp=true
+    const index = buildFamilyIndex([header(ROOT)], identities, makeStats([ROOT]))
+
+    const sub = resolveFamily(ROOT, index).subagents.find((s) => s.sessionId === 'sa-ghost')
+    expect(sub?.cleanedUp).toBe(true)
+    expect(sub?.task).toBe('ghost task')
+    expect(sub?.agentName).toBe('worker')
+    expect(sub?.model).toBe('gpt-4')
+    expect(sub?.status).toBe('completed')
+    expect(sub?.sessionFile).toBe('/gc/ghost.jsonl') // GC 路径保留（不置空）
+  })
+
+  it('TC-u4-recordmanifest-compat: 最小 identity（仅 rootSessionId+slug）→ 富字段全 undefined，不抛错', () => {
+    // 模拟旧 manifest（无 task/slug/model/status/agentName）经 buildFamilyFromFs 转成的最小 identity
+    const identities = [subagentIdentity(SUB, ROOT, 'legacy')]
+    const index = buildFamilyIndex([header(ROOT)], identities, makeStats([ROOT, SUB]))
+
+    const sub = resolveFamily(ROOT, index).subagents.find((s) => s.sessionId === SUB)
+    expect(sub?.slug).toBe('legacy')
+    expect(sub?.rootSessionId).toBe(ROOT)
+    expect(sub?.task).toBeUndefined()
+    expect(sub?.agentName).toBeUndefined()
+    expect(sub?.model).toBeUndefined()
+    expect(sub?.status).toBeUndefined()
+    expect(sub?.sessionFile).toBeUndefined()
+  })
+
+  it('isSubagentIdentityData 守卫放宽：富字段部分缺失/全缺都通过（只校验 rootSessionId+slug）', () => {
+    const identities = [
+      subagentIdentityRich(SUB, ROOT, 's1', { task: 'only-task' }), // 部分富字段
+      subagentIdentity(SUB2, ROOT, 's2'), // 完全无富字段（旧 manifest 形态）
+    ]
+    const index = buildFamilyIndex([header(ROOT)], identities, makeStats([ROOT, SUB, SUB2]))
+
+    const family = resolveFamily(ROOT, index)
+    expect(family.subagents).toHaveLength(2)
+    const s1 = family.subagents.find((s) => s.sessionId === SUB)
+    expect(s1?.task).toBe('only-task')
+    expect(s1?.model).toBeUndefined()
+    const s2 = family.subagents.find((s) => s.sessionId === SUB2)
+    expect(s2?.task).toBeUndefined()
+    expect(s2?.agentName).toBeUndefined()
+  })
+})

package/src/__tests__/find.test.ts

@@ -3,7 +3,7 @@ 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 } from './real-data.js'
+import { REAL_AGENT_DIR, HAS_E6, HAS_REAL_SUBAGENTS_DIR } from './real-data.js'
 
 /**
  * 建一个假 session 文件：首行 header（type=session，含 id/cwd/parentSession），
@@ -42,13 +42,107 @@ async function makeSession(
   return path
 }
 
+/**
+ * 建 records manifest（U5 fixture）。manifest 在 subagent 创建时写入 records/<sa-id>.json，
+ * sessionFile 指向 alive subagent session 的绝对路径（find 用 extractSessionIdFromFilename
+ * 从该路径提取 sessionId 建索引）。
+ */
+async function makeRecordManifest(
+  recordsDir: string,
+  opts: {
+    id: string
+    rootSessionId: string
+    sessionFile: string
+    agentName?: string
+    task?: string
+    slug?: string
+    model?: string
+    status?: string
+  },
+): Promise<void> {
+  const m: Record<string, unknown> = {
+    id: opts.id,
+    rootSessionId: opts.rootSessionId,
+    sessionFile: opts.sessionFile,
+  }
+  if (opts.agentName !== undefined) m.agentName = opts.agentName
+  if (opts.task !== undefined) m.task = opts.task
+  if (opts.slug !== undefined) m.slug = opts.slug
+  if (opts.model !== undefined) m.model = opts.model
+  if (opts.status !== undefined) m.status = opts.status
+  await mkdir(recordsDir, { recursive: true })
+  await writeFile(join(recordsDir, `${opts.id}.json`), JSON.stringify(m))
+}
+
+/**
+ * 建 subagent session 文件（header + 可选首消息 + 可选尾行 identity）。返回绝对路径。
+ *
+ * 文件名用 `<ts>_<sessionId>.jsonl` 格式（满足 extractSessionIdFromFilename）。传 rootSessionId
+ * 时追加尾行 subagent-identity custom entry（P-fallback fixture 用）；不传则只有 header（manifest 主 fixture 用）。
+ */
+async function makeSubagentSession(
+  dir: string,
+  opts: {
+    name: string
+    id: string
+    cwd?: string
+    rootSessionId?: string
+    slug?: string
+    task?: string
+    agent?: string
+    firstUserText?: string
+  },
+): Promise<string> {
+  const header: Record<string, unknown> = {
+    type: 'session',
+    id: opts.id,
+    timestamp: '2026-01-01T00:00:00.000Z',
+  }
+  if (opts.cwd) header.cwd = opts.cwd
+  const lines: string[] = [JSON.stringify(header)]
+  if (opts.firstUserText) {
+    lines.push(
+      JSON.stringify({
+        type: 'message',
+        id: opts.id + '-m1',
+        message: { role: 'user', content: [{ type: 'text', text: opts.firstUserText }] },
+      }),
+    )
+  }
+  if (opts.rootSessionId !== undefined) {
+    const data: Record<string, unknown> = {
+      id: 'sa-' + opts.id,
+      agent: opts.agent ?? 'worker',
+      mode: 'background',
+      task: opts.task ?? '',
+      slug: opts.slug ?? '',
+      startedAt: Date.now(),
+      rootSessionId: opts.rootSessionId,
+      depth: 1,
+    }
+    lines.push(
+      JSON.stringify({ type: 'custom', id: opts.id, customType: 'subagent-identity', data }),
+    )
+  }
+  await mkdir(dir, { recursive: true })
+  const path = join(dir, opts.name)
+  await writeFile(path, lines.join('\n') + '\n')
+  return path
+}
+
 describe('findSessions', () => {
   let agentDir: string
   let slugDir: string
+  /** subagent fixture 目录（模拟 subagents/<cwd编码>/sessions/ 结构，roots.listSubagentSessions 扫描路径） */
+  let saDir: string
+
+  let recordsDir: string
 
   beforeEach(async () => {
     agentDir = await mkdtemp(join(tmpdir(), 'find-test-'))
     slugDir = join(agentDir, 'sessions', '--Users-demo--')
+    saDir = join(agentDir, 'subagents', '--Users-demo--', 'sessions')
+    recordsDir = join(agentDir, 'subagents', '--Users-demo--', 'records')
   })
   afterEach(async () => {
     await rm(agentDir, { recursive: true, force: true })
@@ -189,6 +283,236 @@ describe('findSessions', () => {
     expect(result.truncated).toBe(false)
   })
 
+  it('缺省合并：main + subagent 候选都返回，source 标记正确（DM1）', async () => {
+    await makeSession(slugDir, { name: 'm.jsonl', id: 'main-shared', cwd: '/demo' })
+    await makeSession(saDir, { name: 's.jsonl', id: 'sub-shared', cwd: '/demo' })
+
+    const { matches } = await findSessions('shared', agentDir)
+    expect(matches).toHaveLength(2)
+    // source 必填标记（DM1）+ 集合为 {main, subagent}
+    const sources = matches.map((m) => m.source).sort()
+    expect(sources).toEqual(['main', 'subagent'])
+    // fileName 指向各自目录
+    const mainHit = matches.find((m) => m.source === 'main')!
+    const subHit = matches.find((m) => m.source === 'subagent')!
+    expect(mainHit.sessionId).toBe('main-shared')
+    expect(mainHit.fileName).not.toContain('subagents')
+    expect(subHit.sessionId).toBe('sub-shared')
+    expect(subHit.fileName).toContain('subagents')
+  })
+
+  it("source:'main' 只含 main 候选（subagent 被过滤）", async () => {
+    await makeSession(slugDir, { name: 'm.jsonl', id: 'main-shared', cwd: '/demo' })
+    await makeSession(saDir, { name: 's.jsonl', id: 'sub-shared', cwd: '/demo' })
+
+    const { matches } = await findSessions('shared', agentDir, { source: 'main' })
+    expect(matches).toHaveLength(1)
+    expect(matches[0].source).toBe('main')
+    expect(matches[0].sessionId).toBe('main-shared')
+  })
+
+  it("source:'subagent' 只含 subagent 候选（main 被过滤）", async () => {
+    await makeSession(slugDir, { name: 'm.jsonl', id: 'main-shared', cwd: '/demo' })
+    await makeSession(saDir, { name: 's.jsonl', id: 'sub-shared', cwd: '/demo' })
+
+    const { matches } = await findSessions('shared', agentDir, { source: 'subagent' })
+    expect(matches).toHaveLength(1)
+    expect(matches[0].source).toBe('subagent')
+    expect(matches[0].sessionId).toBe('sub-shared')
+    expect(matches[0].fileName).toContain('subagents')
+  })
+
+  it("recent 也尊重 source 过滤（含不传 source 时两侧按 mtime 混合倒序）", async () => {
+    const mainPath = await makeSession(slugDir, { name: 'm.jsonl', id: 'r-main', cwd: '/demo' })
+    const subPath = await makeSession(saDir, { name: 's.jsonl', id: 'r-sub', cwd: '/demo' })
+    // subagent mtime 更新
+    const base = Math.floor(Date.now() / 1000)
+    await utimes(mainPath, base, base)
+    await utimes(subPath, base + 100, base + 100)
+
+    // source:'main' → 只 main 侧，subagent 被过滤
+    const mainOnly = await findSessions('recent', agentDir, { source: 'main' })
+    expect(mainOnly.matches).toHaveLength(1)
+    expect(mainOnly.matches[0].source).toBe('main')
+    expect(mainOnly.matches[0].sessionId).toBe('r-main')
+
+    // 不传 source → 两侧合并按 mtime 倒序（subagent 更新排前）
+    const merged = await findSessions('recent', agentDir)
+    expect(merged.matches).toHaveLength(2)
+    expect(merged.matches[0].sessionId).toBe('r-sub')
+    expect(merged.matches[0].source).toBe('subagent')
+    expect(merged.matches[1].sessionId).toBe('r-main')
+    expect(merged.matches[1].source).toBe('main')
+  })
+
+  // ============================================================
+  // U5：subagent task/slug/agentName 匹配（manifest 索引 + P-fallback identity 回退）
+  // ============================================================
+  describe('U5 task/slug/agentName 匹配', () => {
+    it('TC-u5-find-task：manifest.task 含 query 入选（main 首消息不含 query 不入选）', async () => {
+      const subId = '0aaaaaaa-bbbb-cccc-dddd-000000000001'
+      const subPath = await makeSubagentSession(saDir, {
+        name: `1234567890_${subId}.jsonl`,
+        id: subId,
+        cwd: '/demo',
+      })
+      await makeRecordManifest(recordsDir, {
+        id: `sa-${subId}`,
+        rootSessionId: 'root-1',
+        sessionFile: subPath,
+        task: '调研 codex CLI 的功能',
+      })
+      // main 首消息不含 codex → 关键词层不命中
+      await makeSession(slugDir, {
+        name: 'main.jsonl',
+        id: 'main-no-task-match',
+        cwd: '/demo',
+        firstUserText: '完全无关的对话内容',
+      })
+
+      const { matches } = await findSessions('codex', agentDir)
+      expect(matches).toHaveLength(1)
+      expect(matches[0].source).toBe('subagent')
+      expect(matches[0].sessionId).toBe(subId)
+    })
+
+    it('TC-u5-find-slug：manifest.slug 子串命中入选', async () => {
+      const subId = '0aaaaaaa-bbbb-cccc-dddd-000000000002'
+      const subPath = await makeSubagentSession(saDir, {
+        name: `1234567890_${subId}.jsonl`,
+        id: subId,
+        cwd: '/demo',
+      })
+      await makeRecordManifest(recordsDir, {
+        id: `sa-${subId}`,
+        rootSessionId: 'root-2',
+        sessionFile: subPath,
+        slug: 'codex-ask-user-research',
+        task: '其他不含 ask-user 的任务文本',
+      })
+
+      const { matches } = await findSessions('ask-user', agentDir)
+      expect(matches).toHaveLength(1)
+      expect(matches[0].source).toBe('subagent')
+      expect(matches[0].sessionId).toBe(subId)
+    })
+
+    it('TC-u5-find-agentname：manifest.agentName 命中入选', async () => {
+      const subId = '0aaaaaaa-bbbb-cccc-dddd-000000000003'
+      const subPath = await makeSubagentSession(saDir, {
+        name: `1234567890_${subId}.jsonl`,
+        id: subId,
+        cwd: '/demo',
+      })
+      await makeRecordManifest(recordsDir, {
+        id: `sa-${subId}`,
+        rootSessionId: 'root-3',
+        sessionFile: subPath,
+        agentName: 'explorer',
+        task: '不含 explorer 的任务',
+        slug: '不含-explorer-的-slug',
+      })
+
+      const { matches } = await findSessions('explorer', agentDir)
+      expect(matches).toHaveLength(1)
+      expect(matches[0].source).toBe('subagent')
+      expect(matches[0].sessionId).toBe(subId)
+    })
+
+    it('TC-u5-find-source-task-combo：source:subagent 过滤 + task 匹配正交（与 m0 U1 source 过滤组合）', async () => {
+      // main：首消息含 codex，但 source:'subagent' 在文件列表层排除 sessions/ 目录（不扫 main）
+      await makeSession(slugDir, {
+        name: 'main.jsonl',
+        id: 'main-with-codex',
+        cwd: '/demo',
+        firstUserText: '讨论 codex 工具的使用',
+      })
+      // subagent：task 含 codex
+      const subId = '0aaaaaaa-bbbb-cccc-dddd-000000000004'
+      const subPath = await makeSubagentSession(saDir, {
+        name: `1234567890_${subId}.jsonl`,
+        id: subId,
+        cwd: '/demo',
+      })
+      await makeRecordManifest(recordsDir, {
+        id: `sa-${subId}`,
+        rootSessionId: 'root-4',
+        sessionFile: subPath,
+        task: '用 codex 完成任务',
+      })
+
+      const { matches } = await findSessions('codex', agentDir, { source: 'subagent' })
+      expect(matches.length).toBeGreaterThanOrEqual(1)
+      expect(matches.every((m) => m.source === 'subagent')).toBe(true)
+      expect(matches.some((m) => m.sessionId === subId)).toBe(true)
+      // main 被 source 过滤排除（文件列表层不扫 sessions/）
+      expect(matches.some((m) => m.source === 'main')).toBe(false)
+    })
+
+    it('TC-u5-find-pfallback：无 manifest，读尾行 identity.task 回退匹配（场景 A）', async () => {
+      // subagent：无 manifest（P-fallback），但 session 文件尾行 identity.task 含 'resolve-bug'
+      const subId = '0aaaaaaa-bbbb-cccc-dddd-000000000005'
+      await makeSubagentSession(saDir, {
+        name: `1234567890_${subId}.jsonl`,
+        id: subId,
+        cwd: '/demo',
+        rootSessionId: 'root-5',
+        task: '修复 resolve-bug 这个问题',
+        slug: 'fix',
+        agent: 'worker',
+      })
+
+      const { matches } = await findSessions('resolve', agentDir)
+      expect(matches).toHaveLength(1)
+      expect(matches[0].source).toBe('subagent')
+      expect(matches[0].sessionId).toBe(subId)
+    })
+
+    it('TC-u5-find-uuid-priority：uuid 片段命中后短路，不走 task 匹配（TC-find-match-priority）', async () => {
+      // subagent A：sessionId 含 'abc123'（uuid 片段命中）
+      const idA = 'aabc123e-0000-0000-0000-000000000001'
+      await makeSubagentSession(saDir, {
+        name: `1111111111_${idA}.jsonl`,
+        id: idA,
+        cwd: '/demo',
+      })
+      // subagent B：sessionId 不含 abc123，但 manifest.task 含 abc123
+      const idB = '0aaaaaaa-bbbb-cccc-dddd-000000000006'
+      const subPathB = await makeSubagentSession(saDir, {
+        name: `2222222222_${idB}.jsonl`,
+        id: idB,
+        cwd: '/demo',
+      })
+      await makeRecordManifest(recordsDir, {
+        id: `sa-${idB}`,
+        rootSessionId: 'root-6',
+        sessionFile: subPathB,
+        task: '任务包含 abc123 关键词',
+      })
+
+      // 'abc123' 全十六进制 → uuid 特征；A 的 sessionId 含 abc123 → uuid 片段命中 → 短路
+      const { matches } = await findSessions('abc123', agentDir)
+      expect(matches).toHaveLength(1)
+      expect(matches[0].sessionId).toBe(idA)
+      // B 不入选（uuid 命中短路，不走 task 匹配）
+      expect(matches.some((m) => m.sessionId === idB)).toBe(false)
+    })
+
+    it.skipIf(!HAS_REAL_SUBAGENTS_DIR)(
+      'TC-u5-real-data-guard：find codex source:subagent 命中（本机有 codex 相关 subagent task）',
+      async () => {
+        const { matches, truncated } = await findSessions('codex', REAL_AGENT_DIR, {
+          source: 'subagent',
+          limit: 50,
+        })
+        expect(matches.length).toBeGreaterThan(0)
+        expect(matches.every((m) => m.source === 'subagent')).toBe(true)
+        expect(typeof truncated).toBe('boolean')
+      },
+      30000,
+    )
+  })
+
   it.skipIf(!HAS_E6)('真实数据：e6c96 匹配 019e6c96 开头的 session', async () => {
     const { matches } = await findSessions('e6c96', REAL_AGENT_DIR)
     expect(matches.length).toBeGreaterThan(0)
@@ -211,4 +535,21 @@ describe('findSessions', () => {
     // 真实 session 文件远多于 5 → 截断
     expect(truncated).toBe(true)
   }, 30000)
+
+  it.skipIf(!HAS_REAL_SUBAGENTS_DIR)(
+    "真实数据：source:'subagent' 能找到 completed subagent（§7 场景 1 find 部分）",
+    async () => {
+      const { matches } = await findSessions('recent', REAL_AGENT_DIR, {
+        source: 'subagent',
+        limit: 5,
+      })
+      expect(matches.length).toBeGreaterThan(0)
+      // 全部 source==='subagent'，fileName 在 subagents/ 目录下
+      for (const m of matches) {
+        expect(m.source).toBe('subagent')
+        expect(m.fileName).toContain('subagents')
+      }
+    },
+    30000,
+  )
 })

package/src/__tests__/index.test.ts

@@ -190,4 +190,54 @@ describe('sessionReaderExtension - TypeBox schema 与 SessionReadParams 对齐',
     expect(Check(schema, { action: 42 })).toBe(false)
     expect(Check(schema, {})).toBe(false) // 缺必填 action
   })
+
+  it('source 字段：合法值（main/subagent）通过、非法值拒绝；不传 source 向后兼容', () => {
+    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
+
+    // 合法值通过（enum 约束）
+    expect(Check(schema, { action: 'find', query: 'x', source: 'main' })).toBe(true)
+    expect(Check(schema, { action: 'find', query: 'x', source: 'subagent' })).toBe(true)
+    // 非法值被拒
+    expect(Check(schema, { action: 'find', query: 'x', source: 'bogus' })).toBe(false)
+    // 不传 source 向后兼容（既有合法形态仍 true）
+    expect(Check(schema, { action: 'find', query: 'x' })).toBe(true)
+  })
+
+  it('TC-w6-schema-action：action enum 含 workflow + runId optional（w6）', () => {
+    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
+
+    // action='workflow' 不传 runId（合法）
+    expect(Check(schema, { action: 'workflow', session: 'e6c96' })).toBe(true)
+    // action='workflow' 传 runId（合法）
+    expect(Check(schema, { action: 'workflow', session: 'e6c96', runId: 'wf-1' })).toBe(true)
+    // runId 传任意 action 均合法（其他 action 忽略 runId，不报错）
+    expect(Check(schema, { action: 'find', query: 'x', runId: 'wf-1' })).toBe(true)
+    // 不传 runId 向后兼容
+    expect(Check(schema, { action: 'outline', session: 'e6c96' })).toBe(true)
+    // runId 类型校验：非 string 被拒
+    expect(Check(schema, { action: 'workflow', session: 'x', runId: 123 })).toBe(false)
+  })
+
+  it('TC-m3b-schema-recursive：recursive optional boolean（family 专用）', () => {
+    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
+
+    // recursive=true（合法）
+    expect(Check(schema, { action: 'family', session: 'e6c96', recursive: true })).toBe(true)
+    // 不传 recursive（向后兼容，合法）
+    expect(Check(schema, { action: 'family', session: 'e6c96' })).toBe(true)
+    // recursive=false（合法）
+    expect(Check(schema, { action: 'family', session: 'e6c96', recursive: false })).toBe(true)
+    // recursive 非 boolean 被拒
+    expect(Check(schema, { action: 'family', session: 'x', recursive: 'yes' })).toBe(false)
+    expect(Check(schema, { action: 'family', session: 'x', recursive: 1 })).toBe(false)
+  })
 })

package/src/__tests__/parser.test.ts

@@ -162,5 +162,6 @@ describe('parseSessionFile', () => {
     expect(result.lastLinePartial).toBe(false)
     // 5.4MB 量级
     expect(result.totalBytes).toBeGreaterThan(5_000_000)
-  })
+    // 5.6MB 全量解析在并发/高负载下可能超 vitest 默认 5s，显式放宽
+  }, 60000)
 })

package/src/__tests__/real-data.ts

@@ -44,6 +44,26 @@ export function hasRealSession(sid: string): boolean {
   }
 }
 
+/**
+ * 同步探测真实数据中任意 session 文件存在（main sessions/ 与 subagents/ 双目录）。
+ * 与 hasRealSession 的区别：subagent session 文件位于 subagents/<cwd>/sessions/ 下，
+ * hasRealSession 只扫主 sessions/ 目录扫不到。用于对活跃数据目录中具体文件（如 fork
+ * 子代/隔代 subagent）存在性的守卫探测。
+ */
+export function hasAnyRealSession(fragment: string): boolean {
+  if (!existsSync(REAL_AGENT_DIR)) return false
+  try {
+    return (
+      execSync(
+        `find ${REAL_AGENT_DIR}/sessions ${REAL_AGENT_DIR}/subagents -name '*${fragment}*' -name '*.jsonl' ! -name '*.finalized' 2>/dev/null | head -1`,
+        { encoding: 'utf8' },
+      ).trim().length > 0
+    )
+  } catch {
+    return false
+  }
+}
+
 export const HAS_REAL_AGENT_DIR = existsSync(REAL_AGENT_DIR)
 export const HAS_REAL_SUBAGENTS_DIR = existsSync(join(REAL_AGENT_DIR, 'subagents'))
 export const HAS_REAL_SESSION = existsSync(REAL_SESSION)

package/src/__tests__/render.test.ts

@@ -185,7 +185,8 @@ describe('renderOutline', () => {
     // totalEntries 近似（leaf+branch+orphan）不含 session header（segmentTurns 规则1 跳过）；
     // 准确值由 M2 工具层用 ParseResult.totalEntries 覆盖。M1 验量级。
     expect(result.stats.totalEntries).toBeGreaterThan(1000)
-  })
+    // 5.6MB 全量解析在并发/高负载下可能超 vitest 默认 5s，显式放宽
+  }, 60000)
 })
 
 describe('renderExpand', () => {