@zhushanwen/pi-session-reader 0.2.4 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-session-reader",
-  "version": "0.2.4",
+  "version": "0.3.1",
   "type": "module",
   "main": "index.ts",
   "xyz-agent": {

package/src/__tests__/find.test.ts

@@ -145,7 +145,7 @@ describe('findSessions', () => {
     recordsDir = join(agentDir, 'subagents', '--Users-demo--', 'records')
   })
   afterEach(async () => {
-    await rm(agentDir, { recursive: true, force: true })
+    await rm(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
   })
 
   it('uuid 片段匹配正确的 session（sessionId 含 query）', async () => {
@@ -256,6 +256,20 @@ describe('findSessions', () => {
     expect(result).toEqual({ matches: [], truncated: false })
   })
 
+  it('uuid 片段命中路径的 firstMessagePreview 补读（命中时未读首消息，第 5 步补）', async () => {
+    // uuid 片段直接命中 → 不走关键词层（preview 未读），最终结果仍应补读出首消息预览
+    await makeSession(slugDir, {
+      name: 'a.jsonl',
+      id: '019cafe0-aaaa-bbbb',
+      cwd: '/demo',
+      firstUserText: 'uuid 命中后补读的预览文本',
+    })
+    const { matches } = await findSessions('019cafe0', agentDir)
+    expect(matches).toHaveLength(1)
+    expect(matches[0].sessionId).toBe('019cafe0-aaaa-bbbb')
+    expect(matches[0].firstMessagePreview).toBe('uuid 命中后补读的预览文本')
+  })
+
   it('firstMessagePreview 截断到 80 字符', async () => {
     const longText = 'X'.repeat(200)
     await makeSession(slugDir, {

package/src/__tests__/render.test.ts

@@ -93,7 +93,7 @@ describe('renderOutline', () => {
   })
 
   it('2a. 降级：单行 toolSummary 过长超 perTurnBudget → 砍 toolSummary，保 userBrief 骨架', () => {
-    // L1 行不含 assistantBrief（design §3.5 算法1 step2）；budget=40, 3 turns → perTurnCharBudget≈53
+    // 预算紧张降级后 L1 行不含 assistantBrief（预算充足 level 0 行含）；budget=40, 3 turns → perTurnCharBudget≈53
     // 行 = head + userBrief(10) + toolSummary(20 个工具名≈63 chars) → ~80 > 53 → 砍 toolSummary
     const toolCalls = Array.from({ length: 20 }, (_, k) => ({ name: `t${String(k).padStart(2, '0')}` }))
     const turns = [0, 1, 2].map((i) =>
@@ -183,7 +183,7 @@ describe('renderOutline', () => {
     // stats 完整性
     expect(result.stats.totalTurns).toBe(32)
     // totalEntries 近似（leaf+branch+orphan）不含 session header（segmentTurns 规则1 跳过）；
-    // 准确值由 M2 工具层用 ParseResult.totalEntries 覆盖。M1 验量级。
+    // 工具层仅覆盖 stats.totalBytes 与 skippedLines（ParseResult 无 totalEntries 字段）。M1 验量级。
     expect(result.stats.totalEntries).toBeGreaterThan(1000)
     // 5.6MB 全量解析在并发/高负载下可能超 vitest 默认 5s，显式放宽
   }, 60000)

package/src/__tests__/tool-handler.test.ts

@@ -22,7 +22,7 @@ import {
  * 测试框架 vitest（禁止 node:test/tsx）。直接调 handleSessionRead（纯逻辑，agentDir 注入），
  * 传真实 `/Users/zhushanwen/.pi/agent` 作 agentDir——用本机真实历史 session 数据，无需 mock。
  *
- * 覆盖 7 action 主路径 + F1(find 零匹配)/F4(turn 越界)/F5(缺参)/resolveSessionId 片段等价。
+ * 覆盖 9 action 主路径 + F1(find 零匹配)/F4(turn 越界)/F5(缺参)/resolveSessionId 片段等价。
  *
  * 真实数据用例全部带 skipIf 守卫（CI 无本机 ~/.pi/agent → skip，不硬失败）；
  * renderExtractItems F9 截断是纯 fixture，无条件跑。
@@ -330,7 +330,7 @@ describe('F2 多匹配消歧（fixture，MF-9）', () => {
     dir = await mkdtemp(join(tmpdir(), 'tool-handler-f2-'))
   })
   afterEach(async () => {
-    await rm(dir, { recursive: true, force: true })
+    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
   })
 
   it('共享 uuid 片段 → 不抛错，content 含两候选 + 👉，details.ambiguous=true', async () => {
@@ -380,7 +380,7 @@ describe('outline skippedLines 报告（fixture，D8d 有检测必有报告）',
     dir = await mkdtemp(join(tmpdir(), 'tool-handler-skipped-'))
   })
   afterEach(async () => {
-    await rm(dir, { recursive: true, force: true })
+    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
   })
 
   it('坏行计入 stats.skippedLines 且文本尾部可见（不静默跳过）', async () => {
@@ -423,7 +423,7 @@ describe('search 灾难性正则降级 + abort（fixture，MF-5 回归）', () =
     await makeFixtureSession(dir, SID, 'aaa plugin 内容')
   })
   afterEach(async () => {
-    await rm(dir, { recursive: true, force: true })
+    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
   })
 
   it('嵌套量词 pattern (a+)+ → 降级字面子串（不挂死，零命中）', async () => {
@@ -523,6 +523,143 @@ describe('search 灾难性正则降级 + abort（fixture，MF-5 回归）', () =
   })
 })
 
+describe('extract commits 双路径（fixture：git-cmd 主路径 + commit-context 次路径 + 去重）', () => {
+  let dir: string
+  const SID = '019e6c96-bbbb-cccc-dddd-00000000000c'
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'tool-handler-commits-'))
+  })
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+  })
+
+  /** 写单个 session JSONL（commits 用例行内联传入）。 */
+  async function writeCommitsSession(id: string, lines: string[]): Promise<void> {
+    await mkdir(join(dir, 'sessions', '--demo-cwd--'), { recursive: true })
+    await writeFile(
+      join(dir, 'sessions', '--demo-cwd--', `${id}.jsonl`),
+      lines.join('\n') + '\n',
+    )
+  }
+
+  it('commit-context 次路径：非 git bash 的 toolResult，hash 邻近含关键词才收（D6）', async () => {
+    await writeCommitsSession(SID, [
+      JSON.stringify({ type: 'session', id: SID, cwd: '/demo' }),
+      JSON.stringify({
+        type: 'message',
+        id: `${SID}-m1`,
+        parentId: SID,
+        message: {
+          role: 'assistant',
+          content: [
+            { type: 'toolCall', id: 'tc-read-1', name: 'read', arguments: { path: '/tmp/log.txt' } },
+          ],
+        },
+      }),
+      // read 结果：hash 邻近 30 字符窗口含 'feat:' → commit-context 次路径纳入
+      JSON.stringify({
+        type: 'message',
+        id: `${SID}-m2`,
+        parentId: `${SID}-m1`,
+        message: {
+          role: 'toolResult',
+          toolName: 'read',
+          toolCallId: 'tc-read-1',
+          content: [{ type: 'text', text: 'deploy abc1234f done\nfeat: add login' }],
+        },
+      }),
+      // read 结果：hash 无关键词邻近 → 两路径都不收（过滤分支）
+      JSON.stringify({
+        type: 'message',
+        id: `${SID}-m3`,
+        parentId: `${SID}-m2`,
+        message: {
+          role: 'assistant',
+          content: [
+            { type: 'toolCall', id: 'tc-read-2', name: 'read', arguments: { path: '/tmp/out.txt' } },
+          ],
+        },
+      }),
+      JSON.stringify({
+        type: 'message',
+        id: `${SID}-m4`,
+        parentId: `${SID}-m3`,
+        message: {
+          role: 'toolResult',
+          toolName: 'read',
+          toolCallId: 'tc-read-2',
+          content: [{ type: 'text', text: 'output 9998887 plain text' }],
+        },
+      }),
+    ])
+    const r = await handleSessionRead({ action: 'extract', session: SID, what: 'commits' }, dir)
+    const d = r.details as { count: number; items: Array<{ hash: string; source: string }> }
+    const hashes = d.items.map((it) => it.hash)
+    expect(hashes).toContain('abc1234f')
+    expect(hashes).not.toContain('9998887')
+    expect(d.items.find((it) => it.hash === 'abc1234f')?.source).toBe('commit-context')
+  })
+
+  it('去重高置信优先：同 hash 同时命中 git-cmd 与 commit-context → 保留 git-cmd 一条', async () => {
+    await writeCommitsSession(SID, [
+      JSON.stringify({ type: 'session', id: SID, cwd: '/demo' }),
+      JSON.stringify({
+        type: 'message',
+        id: `${SID}-m1`,
+        parentId: SID,
+        message: {
+          role: 'assistant',
+          content: [
+            { type: 'toolCall', id: 'tc-bash-1', name: 'bash', arguments: { command: 'git log --oneline -3' } },
+          ],
+        },
+      }),
+      // bash + git log → git-cmd 高置信（含 def5678a）
+      JSON.stringify({
+        type: 'message',
+        id: `${SID}-m2`,
+        parentId: `${SID}-m1`,
+        message: {
+          role: 'toolResult',
+          toolName: 'bash',
+          toolCallId: 'tc-bash-1',
+          content: [{ type: 'text', text: 'def5678a feat: fix crash' }],
+        },
+      }),
+      JSON.stringify({
+        type: 'message',
+        id: `${SID}-m3`,
+        parentId: `${SID}-m2`,
+        message: {
+          role: 'assistant',
+          content: [
+            { type: 'toolCall', id: 'tc-read-1', name: 'read', arguments: { path: '/tmp/deploy.txt' } },
+          ],
+        },
+      }),
+      // read 结果同 hash def5678a + 关键词 merged → low 候选，去重后丢弃
+      JSON.stringify({
+        type: 'message',
+        id: `${SID}-m4`,
+        parentId: `${SID}-m3`,
+        message: {
+          role: 'toolResult',
+          toolName: 'read',
+          toolCallId: 'tc-read-1',
+          content: [{ type: 'text', text: 'deploy def5678a merged' }],
+        },
+      }),
+    ])
+    const r = await handleSessionRead({ action: 'extract', session: SID, what: 'commits' }, dir)
+    const d = r.details as { count: number; items: Array<{ hash: string; source: string }> }
+    const dupes = d.items.filter((it) => it.hash === 'def5678a')
+    expect(dupes).toHaveLength(1)
+    expect(dupes[0].source).toBe('git-cmd')
+    expect(d.count).toBe(1)
+  })
+})
+
 describe('renderExtractItems F9 截断（S3 首项超大 + S4 文案）', () => {
   it('S3: 首项超大内部截断 → body 不超预算，shown<count + truncated=true', () => {
     // 首项 10000 字符 >> EXTRACT_BUDGET_BYTES(8000)；旧逻辑放行首项致 body≈10KB
@@ -635,7 +772,7 @@ describe('resolveSessionId ① 绝对路径形态（w2 TC2-TC6）', () => {
     dir = await mkdtemp(join(tmpdir(), 'tool-handler-path-'))
   })
   afterEach(async () => {
-    await rm(dir, { recursive: true, force: true })
+    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
   })
 
   it('TC2: 绝对路径 outline → sessionId=header 真实 id（非文件名）', async () => {
@@ -723,7 +860,7 @@ describe('resolveSessionId ① 绝对路径形态（w2 TC2-TC6）', () => {
       )
       expect((r.details as { path: string }).path).toContain(fileId)
     } finally {
-      await rm(tmpUnderHome, { recursive: true, force: true })
+      await rm(tmpUnderHome, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
     }
   })
 })
@@ -735,7 +872,7 @@ describe('resolveSessionId ② sa-id 形态（w2 TC7-TC10 + CQ3）', () => {
     dir = await mkdtemp(join(tmpdir(), 'tool-handler-said-'))
   })
   afterEach(async () => {
-    await rm(dir, { recursive: true, force: true })
+    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
   })
 
   it('TC7: sa-id 恰 1 命中 + sessionFile 存在 → 成功，sessionId=header 真实 id（非 sa-）', async () => {
@@ -782,7 +919,7 @@ describe('resolveSessionId ② sa-id 形态（w2 TC7-TC10 + CQ3）', () => {
       await handleSessionRead({ action: 'outline', session: 'sa-nonexist-9999' }, dir)
     } catch (e) {
       const msg = (e as Error).message
-      expect(msg).toContain('可能仍在运行')
+      expect(msg).toContain('可能尚未落盘')
       expect(msg).toContain('action:"family"')
       expect(msg).toContain('👉')
     }
@@ -858,7 +995,7 @@ describe('source 透传（w2 TC12-TC13，依赖 w1 findSessions opts.source）',
     dir = await mkdtemp(join(tmpdir(), 'tool-handler-src-'))
   })
   afterEach(async () => {
-    await rm(dir, { recursive: true, force: true })
+    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
   })
 
   it('TC12: find source 过滤——subagent 只返回 subagent 候选，main 只返回 main', async () => {
@@ -1089,7 +1226,7 @@ describe('doWorkflow（w6，fixture）', () => {
     dir = await mkdtemp(join(tmpdir(), 'tool-handler-wf-'))
   })
   afterEach(async () => {
-    await rm(dir, { recursive: true, force: true })
+    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
   })
 
   it('TC-w6-single-run：单 run 概览，content 含 run 头行/budget/step，details.runs/runIds 非空', async () => {
@@ -1370,7 +1507,7 @@ describe('doFamily recursive（m3b U8 接入）', () => {
     })
   })
   afterEach(async () => {
-    await rm(dir, { recursive: true, force: true })
+    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
   })
 
   it('TC-m3b-dofamily-recursive-false：不传 recursive → flat family（m0-m2 零回归）', async () => {

package/src/__tests__/toolcall.test.ts

@@ -210,6 +210,19 @@ describe('formatToolCallSummary — coding-workflow-* / unknown fallback', () =>
     circ.self = circ
     expect(formatToolCallSummary({ id: 'c1', name: 'my-tool', arguments: circ })).toBe('my-tool')
   })
+
+  it('treats prototype-chain key names as unknown (Map lookup, no Object.prototype hit)', () => {
+    // 表驱动用 Map 查找的语义锚：普通对象下标会把 "constructor"/"toString"/"__proto__"
+    // 解析到 Object.prototype（formatter 命中非函数成员返回对象/抛 TypeError），
+    // 这里必须与其它未知 toolName 同走 formatUnknownTool fallback 分支。
+    expect(formatToolCallSummary({ id: 'c1', name: 'constructor', arguments: {} })).toBe(
+      'constructor',
+    )
+    expect(formatToolCallSummary({ id: 'c1', name: 'toString', arguments: {} })).toBe('toString')
+    expect(formatToolCallSummary({ id: 'c1', name: '__proto__', arguments: { a: 1 } })).toBe(
+      '__proto__: {"a":1}',
+    )
+  })
 })
 
 describe('extractToolCalls — 提取 + coerceArgs 兜底', () => {

package/src/__tests__/workflow.test.ts

@@ -151,6 +151,33 @@ describe('parseRunSnapshot', () => {
     expect(overview!.steps[1].contentPreview).toBe('OK')
   })
 
+  it('TC-w5-parse-new-status-unknown：NEW call.status 非 done/running/pending（如 failed）→ step.status=pending', () => {
+    // call.status 出现三态外的值（如上游异常态）时收窄为 pending，其余字段照常提取
+    const fixture = {
+      ...NEW_SNAPSHOT_FIXTURE,
+      state: {
+        ...NEW_SNAPSHOT_FIXTURE.state,
+        calls: [
+          {
+            id: 3,
+            opts: { description: 'step-3' },
+            status: 'failed',
+            result: { content: 'partial', durationMs: 9 },
+          },
+        ],
+      },
+    }
+    const overview = parseRunSnapshot(fixture, 'wf-status-runid', '/abs/wf.jsonl')
+    expect(overview).not.toBeNull()
+    expect(overview!.steps).toHaveLength(1)
+    const step = overview!.steps[0]
+    expect(step.index).toBe(3)
+    expect(step.status).toBe('pending')
+    expect(step.description).toBe('step-3')
+    expect(step.contentPreview).toBe('partial')
+    expect(step.durationMs).toBe(9)
+  })
+
   it('TC-w5-parse-old：OLD 格式 (无 v) 尽力解析为 legacy overview，step status 推测', () => {
     const overview = parseRunSnapshot(OLD_SNAPSHOT_FIXTURE, 'wf-old-link', '/abs/wf-old.jsonl')
     expect(overview).not.toBeNull()
@@ -199,6 +226,37 @@ describe('extractCallSessionFiles', () => {
     const files = extractCallSessionFiles(NEW_SNAPSHOT_FIXTURE)
     expect(files).toEqual(['/abs/session.jsonl'])
   })
+
+  it('OLD 快照（无 v，callCache）从 value 顶层与 value.result 提取 sessionFile', () => {
+    const files = extractCallSessionFiles({
+      callCache: [
+        { key: 0, value: { sessionFile: '/abs/old-call0.jsonl' } },
+        { key: 1, value: { result: { sessionFile: '/abs/old-call1.jsonl' } } },
+      ],
+    })
+    expect(files).toEqual(['/abs/old-call0.jsonl', '/abs/old-call1.jsonl'])
+  })
+
+  it('OLD 快照 value 无 sessionFile / value 非对象 → 跳过该 call，不产出路径', () => {
+    // 对齐 OLD_SNAPSHOT_FIXTURE 形状（旧 pi 不持久化 sessionFile）+ value 非对象脏数据回退 call 本身
+    const files = extractCallSessionFiles({
+      callCache: [
+        { key: 7, value: { content: '', usage: { input: 0 } } },
+        { key: 8, value: 42 },
+        { key: 9, sessionFile: '/abs/bare-call.jsonl' },
+      ],
+    })
+    expect(files).toEqual(['/abs/bare-call.jsonl'])
+  })
+
+  it('快照非对象 / calls 容器缺失 / call 元素非对象 → 空数组', () => {
+    expect(extractCallSessionFiles(null)).toEqual([])
+    expect(extractCallSessionFiles('wf-run-v1')).toEqual([])
+    expect(extractCallSessionFiles({ v: 'wf-run-v1', state: null })).toEqual([])
+    expect(extractCallSessionFiles({ v: 'wf-run-v1', state: {} })).toEqual([])
+    expect(extractCallSessionFiles({ callCache: 'not-an-array' })).toEqual([])
+    expect(extractCallSessionFiles({ callCache: [null, 7, 'x'] })).toEqual([])
+  })
 })
 
 // ============================================================
@@ -282,7 +340,7 @@ describe('renderWorkflowOverview', () => {
 describe('readRunSnapshot', () => {
   let dir: string
   afterEach(async () => {
-    if (dir) await rm(dir, { recursive: true, force: true }).catch(() => {})
+    if (dir) await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 }).catch(() => {})
   })
 
   it('TC-w5-read-tail-fallback：末行半截 JSON 回退倒数第二行完整快照', async () => {

package/src/core/execution-tree.ts

@@ -173,7 +173,6 @@ function collectRelatedRecords(
 // buildExecutionTree（IF3 核心）
 // ============================================================
 
-/** 建树过程的共享可变状态（避免递归函数参数爆炸，封装为 context）。 */
 /** 建树过程的共享可变状态（避免递归函数参数爆炸，封装为 context）。 */
 interface BuildContext {
   rootSessionId: string

package/src/core/family.ts

@@ -11,7 +11,7 @@ import type { Entry } from './parser.js'
  * - SessionRef.mtime/sizeBytes：从 fileStats 取（M1 key=sessionId），取不到为 0
  * - SubagentRef.sessionId：identity entry 不含 subagent session 的 id → 占位用 entry.id
  * - SubagentRef.cwd：identity entry（custom 类型）无 cwd → 占位空串
- * - fileStats 的 key：M1 用 sessionId（M2 改用真实文件路径），cleanedUp 逻辑 M1/M2 通用
+ * - fileStats 的 key：sessionId（M2 实现沿用此 key，cleanedUp 按 sessionId 命中），逻辑通用
  *
  * 隔代关联规则（design §3.3 D-7 Q1）见 resolveFamily 注释。
  */
@@ -24,7 +24,6 @@ export interface SessionRef {
   cwd: string
   /** fork 文件指向来源的路径（来自 header 的 parentSession，原始文件路径字符串） */
   parentSession?: string
-  name?: string
 }
 
 export interface SubagentRef extends SessionRef {
@@ -135,24 +134,12 @@ function resolveParentSessionId(
   return null
 }
 
-/**
- * 从已读入的 session headers + subagent identity entries 建家族索引（纯逻辑，无 IO）。
- *
- * - headers（type=session）→ byId + childrenOf（parentSession 文件路径反查父 sessionId）
- * - subagentIdentities（type=custom, customType=subagent-identity）→ subagentsByRoot
- * - fileStats 原样存入 index，供 cleanedUp 判断
- *
- * 坏数据容错：identity 缺 rootSessionId/slug 跳过；parentSession 反查不到父（父文件
- * 未被扫描到）该 entry 不进 childrenOf——均不报错，符合 pi 坏 session 容错（design §2）。
- */
-export function buildFamilyIndex(
+/** 阶段 1：headers → byId（SessionRef 组装，mtime/size 从 fileStats 取，取不到为 0）。 */
+function buildById(
   headers: Entry[],
-  subagentIdentities: Entry[],
   fileStats: Map<string, { mtime: number; size: number }>,
-): FamilyIndex {
+): Map<string, SessionRef> {
   const byId = new Map<string, SessionRef>()
-
-  // 1. headers → byId
   for (const h of headers) {
     const stat = fileStats.get(h.id)
     const ref: SessionRef = {
@@ -165,8 +152,17 @@ export function buildFamilyIndex(
     if (h.parentSession) ref.parentSession = h.parentSession
     byId.set(h.id, ref)
   }
+  return byId
+}
 
-  // 2. childrenOf：parentSession（文件路径）→ 反查父 sessionId → key 用父 sessionId
+/**
+ * 阶段 2：childrenOf——parentSession（文件路径）→ 反查父 sessionId → key 用父 sessionId。
+ * 反查不到父 → 无法建反查关系，跳过（不报错，design §2 容错）。
+ */
+function buildChildrenOf(
+  headers: Entry[],
+  byId: Map<string, SessionRef>,
+): Map<string, SessionRef[]> {
   const childrenOf = new Map<string, SessionRef[]>()
   for (const h of headers) {
     if (!h.parentSession) continue
@@ -178,8 +174,17 @@ export function buildFamilyIndex(
     list.push(childRef)
     childrenOf.set(parentSid, list)
   }
+  return childrenOf
+}
 
-  // 3. subagentIdentities → subagentsByRoot
+/**
+ * 阶段 3：subagentIdentities → subagentsByRoot。
+ * 坏数据（缺 rootSessionId/slug）跳过，不报错（design §2 容错）。
+ */
+function buildSubagentsByRoot(
+  subagentIdentities: Entry[],
+  fileStats: Map<string, { mtime: number; size: number }>,
+): Map<string, SubagentRef[]> {
   const subagentsByRoot = new Map<string, SubagentRef[]>()
   for (const ident of subagentIdentities) {
     if (!isSubagentIdentityData(ident.data)) continue // 坏数据（缺 rootSessionId/slug）跳过
@@ -194,7 +199,7 @@ export function buildFamilyIndex(
       mtime: stat?.mtime ?? 0,
       sizeBytes: stat?.size ?? 0,
       cwd: '', // identity entry 无 cwd；M2 从 subagent 文件 header 补
-      // M1: fileStats key=sessionId；M2 改用 subagent 真实文件路径（SubagentRef.fileName）查 fileStats
+      // fileStats key=sessionId（buildFamilyFromFs 以 header.id 写入），cleanedUp 按 sessionId 命中
       cleanedUp: !fileStats.has(ident.id),
       // U4 富字段：从 identity data 读（manifest 主/P-fallback 由 buildFamilyFromFs 组装时决定）
       task: ident.data.task,
@@ -208,7 +213,27 @@ export function buildFamilyIndex(
     list.push(ref)
     subagentsByRoot.set(ident.data.rootSessionId, list)
   }
+  return subagentsByRoot
+}
 
+/**
+ * 从已读入的 session headers + subagent identity entries 建家族索引（纯逻辑，无 IO）。
+ *
+ * - headers（type=session）→ byId + childrenOf（parentSession 文件路径反查父 sessionId）
+ * - subagentIdentities（type=custom, customType=subagent-identity）→ subagentsByRoot
+ * - fileStats 原样存入 index，供 cleanedUp 判断
+ *
+ * 坏数据容错：identity 缺 rootSessionId/slug 跳过；parentSession 反查不到父（父文件
+ * 未被扫描到）该 entry 不进 childrenOf——均不报错，符合 pi 坏 session 容错（design §2）。
+ */
+export function buildFamilyIndex(
+  headers: Entry[],
+  subagentIdentities: Entry[],
+  fileStats: Map<string, { mtime: number; size: number }>,
+): FamilyIndex {
+  const byId = buildById(headers, fileStats)
+  const childrenOf = buildChildrenOf(headers, byId)
+  const subagentsByRoot = buildSubagentsByRoot(subagentIdentities, fileStats)
   return { byId, childrenOf, subagentsByRoot, fileStats }
 }
 

package/src/core/parser.ts

@@ -51,6 +51,31 @@ function isMessageRole(v: unknown): v is 'user' | 'assistant' | 'toolResult' {
   return v === 'user' || v === 'assistant' || v === 'toolResult'
 }
 
+/**
+ * 归一化 message 字段（阶段 helper：role 经值守卫收窄，缺/非法 role 时
+ * 返回 undefined，调用方丢弃 message 字段——接口 role 必填）。
+ */
+function parseEntryMessage(raw: unknown): Entry['message'] | undefined {
+  if (raw === null || typeof raw !== 'object') return undefined
+  const m = raw as Record<string, unknown>
+  if (!isMessageRole(m.role)) return undefined
+  const message: NonNullable<Entry['message']> = { role: m.role, content: m.content }
+  if (Array.isArray(m.toolCalls)) message.toolCalls = m.toolCalls
+  // toolResult 自带的工具关联字段（O2/O3 用，additive，实测 515/515 存在）
+  if (typeof m.toolName === 'string') message.toolName = m.toolName
+  if (typeof m.toolCallId === 'string') message.toolCallId = m.toolCallId
+  return message
+}
+
+/** 归一化剩余可选字段（阶段 helper：customType/data/parentSession/cwd/summary）。 */
+function assignOptionalFields(obj: Record<string, unknown>, entry: Entry): void {
+  if (typeof obj.customType === 'string') entry.customType = obj.customType
+  if (obj.data !== undefined) entry.data = obj.data
+  if (typeof obj.parentSession === 'string') entry.parentSession = obj.parentSession
+  if (typeof obj.cwd === 'string') entry.cwd = obj.cwd
+  if (obj.summary !== undefined) entry.summary = obj.summary
+}
+
 /**
  * 把单个已 JSON.parse 成功的原始对象归一化为 Entry。
  * 缺必填结构字段（type/id）返回 undefined，调用方计为坏行（skippedLines++）。
@@ -74,24 +99,10 @@ function toEntry(raw: unknown): Entry | undefined {
   }
   if (typeof obj.timestamp === 'string') entry.timestamp = obj.timestamp
 
-  // message：role 经值守卫收窄，缺/非法 role 时丢弃 message 字段（接口 role 必填）
-  if (obj.message !== null && typeof obj.message === 'object') {
-    const m = obj.message as Record<string, unknown>
-    if (isMessageRole(m.role)) {
-      const message: NonNullable<Entry['message']> = { role: m.role, content: m.content }
-      if (Array.isArray(m.toolCalls)) message.toolCalls = m.toolCalls
-      // toolResult 自带的工具关联字段（O2/O3 用，additive，实测 515/515 存在）
-      if (typeof m.toolName === 'string') message.toolName = m.toolName
-      if (typeof m.toolCallId === 'string') message.toolCallId = m.toolCallId
-      entry.message = message
-    }
-  }
+  const message = parseEntryMessage(obj.message)
+  if (message !== undefined) entry.message = message
 
-  if (typeof obj.customType === 'string') entry.customType = obj.customType
-  if (obj.data !== undefined) entry.data = obj.data
-  if (typeof obj.parentSession === 'string') entry.parentSession = obj.parentSession
-  if (typeof obj.cwd === 'string') entry.cwd = obj.cwd
-  if (obj.summary !== undefined) entry.summary = obj.summary
+  assignOptionalFields(obj, entry)
 
   return entry
 }