@zhushanwen/pi-session-reader 0.2.0 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-session-reader",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "type": "module",
   "main": "index.ts",
   "pi": {
@@ -13,6 +13,7 @@
     "pi-package"
   ],
   "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.9",
     "vitest": "^4.1.8"
   },
   "files": [

package/src/__tests__/execution-tree.test.ts

@@ -703,7 +703,7 @@ describe.skipIf(!HAS_REAL)('buildExecutionTree - 真实数据守卫', () => {
     // 不抛错（已隐含：到这行说明成功）
     expect(tree.root.type).toBe('main')
     expect(tree.root.sessionId).toBe(FAM)
-  })
+  }, 60000)
 })
 
 // ============================================================

package/src/__tests__/index.test.ts

@@ -6,7 +6,8 @@ import { Check } from 'typebox/value'
  * M3 pi 边界层（src/index.ts）单测（MF-6：此前该层零测试）。
  *
  * mock pi/ctx（as unknown as ExtensionAPI），测：
- * 1. execute catch → isError:true 文本返回（「execute 不向 pi 抛」契约守护）
+ * 1. execute 错误路径 throw（W4：pi 只对 execute throw 置 isError:true——agent-loop
+ *    丢弃返回值里的 isError 字段，「错误轮被标成功」契约守护）
  * 2. session_start handler 的 ctx.mode!=='tui' 守卫
  * 3. registeredPis WeakSet 去重：同 pi 二次 session_start 不重复注册；不同 pi 可注册
  * 4. typeof ctx.ui.addAutocompleteProvider 运行时守卫（ui 缺方法 → 跳过，不崩）
@@ -78,7 +79,7 @@ describe('sessionReaderExtension - execute 契约', () => {
     sessionReaderExtension(fake.pi as unknown as ExtensionAPI)
   })
 
-  it('handler 抛错 → execute 返回 isError:true + 👉 文本，不向 pi 抛', async () => {
+  it('handler 抛错 → execute 向 pi throw（W4：throw 才置 isError:true，返回值 isError 被 agent-loop 丢弃）', async () => {
     const toolDef = fake.registerTool.mock.calls[0][0] as {
       name: string
       execute: (
@@ -87,18 +88,14 @@ describe('sessionReaderExtension - execute 契约', () => {
         signal: AbortSignal | undefined,
         onUpdate: unknown,
         ctx: unknown,
-      ) => Promise<{ content: Array<{ type: string; text: string }>; isError?: boolean }>
+      ) => Promise<{ content: Array<{ type: string; text: string }> }>
     }
     expect(toolDef.name).toBe('session_read')
-    // action=find 缺 query → F5 requireStr 抛错 → execute catch 转换
-    const result = await toolDef.execute('tc-1', { action: 'find' }, undefined, undefined, undefined)
-    expect(result.isError).toBe(true)
-    expect(result.content[0].type).toBe('text')
-    expect(result.content[0].text).toContain('👉')
-    // 非 Error 抛错（string）也能转文本
-    const result2 = await toolDef.execute('tc-2', { action: 123 }, undefined, undefined, undefined)
-    expect(result2.isError).toBe(true)
-    expect(typeof result2.content[0].text).toBe('string')
+    // action=find 缺 query → F5 requireStr 抛错 → execute 原样传播（pi catch 后
+    // isError:true + message 成为 toolResult content[0].text）
+    await expect(
+      toolDef.execute('tc-1', { action: 'find' }, undefined, undefined, undefined),
+    ).rejects.toThrow(/👉/)
   })
 })
 

package/src/__tests__/parser.test.ts

@@ -117,18 +117,22 @@ describe('parseSessionContent', () => {
     expect(result.lastLinePartial).toBe(true)
   })
 
-  it('custom entry 无顶层 id 时 fallback 到 data.id（pi subagent-identity 等格式）', () => {
-    const content = line({
-      type: 'custom',
-      customType: 'subagent-identity',
-      data: { id: 'sa-abc123', rootSessionId: 'sess-1', slug: 'fix' },
-    })
+  it('custom entry 无顶层 id → 坏行跳过（W4：data.id fallback 死分支已删，pi appendCustomEntry 恒写顶层 id）', () => {
+    // pi appendCustomEntry 恒写顶层 id（session-manager.js:820-828）；data.id 是扩展
+    // 业务字段而非 entry id。无顶层 id 的行按坏行跳过（skippedLines++）。
+    const content = [
+      line({ type: 'custom', customType: 'ok-entry', id: 'top-level-id', data: {} }),
+      line({
+        type: 'custom',
+        customType: 'subagent-identity',
+        data: { id: 'sa-abc123', rootSessionId: 'sess-1', slug: 'fix' },
+      }),
+    ].join('\n')
     const result = parseSessionContent(content)
 
     expect(result.entries).toHaveLength(1)
-    expect(result.entries[0].id).toBe('sa-abc123')
-    expect(result.entries[0].customType).toBe('subagent-identity')
-    expect(result.skippedLines).toBe(0)
+    expect(result.entries[0].id).toBe('top-level-id')
+    expect(result.skippedLines).toBe(1)
   })
 
   it('session header 无 parentId → 归一化为 null（root 判定）', () => {
@@ -162,5 +166,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', () => {

package/src/__tests__/subagents.test.ts

@@ -32,6 +32,21 @@ function hasRealSession(sid: string): boolean {
     return false
   }
 }
+
+// 双目录版探测：subagent session 文件在 subagents/ 下，hasRealSession 扫不到。
+// 用于对活跃数据目录中具体文件（fork 子代/隔代 subagent）存在性的守卫。
+function hasAnyRealSession(fragment: string): boolean {
+  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
+  }
+}
 const HAS_REAL_ROOT = hasRealSession('019fe620-8ae1-78a7-b76a-43a1ba4cc3c7')
 const HAS_REAL_WF = hasRealSession('019fdcda-75c7-74b7-a160-f67f6bf88384')
 
@@ -440,6 +455,9 @@ describe('buildFamilyFromFs - fixture', () => {
 
 describe.skipIf(!HAS_REAL_ROOT)('buildFamilyFromFs - 真实数据 ~/.pi/agent', () => {
   it('019fe620 family：fork 019fe632（跨 cwd）+ 隔代 subagent 019fe635（真实 id）', async () => {
+    // 数据守卫：019fe632（sessions/）与 019fe635（subagents/）位于活跃数据目录，
+    // 被 GC/重命名时跳过而非失败（同 TC14-TC18 守卫模式），避免偶发红。
+    if (!hasAnyRealSession('019fe632') || !hasAnyRealSession('019fe635')) return
     const family = await buildFamilyFromFs(
       '019fe620-8ae1-78a7-b76a-43a1ba4cc3c7',
       REAL_AGENT_DIR,
@@ -458,6 +476,17 @@ describe.skipIf(!HAS_REAL_ROOT)('buildFamilyFromFs - 真实数据 ~/.pi/agent',
 
 describe.skipIf(!HAS_REAL_WF)('buildFamilyFromFs - 真实 workflow 数据', () => {
   it('019fdcda：workflows 非空，至少一个 workflow calls>=4', async () => {
+    // 数据守卫：workflow-state 快照文件可能被清理（wf-state 是会话运行产物），
+    // 019fdcda 的 workflow-state-link 指向的快照不存在时跳过而非失败。
+    const wfFile = execSync(
+      `find ${REAL_AGENT_DIR}/sessions -name '*019fdcda*' -name '*.jsonl' ! -name '*.finalized' 2>/dev/null | head -1`,
+      { encoding: 'utf8' },
+    ).trim()
+    if (!wfFile) return
+    const raw = execSync(`grep -c 'workflow-state-link' '${wfFile}' 2>/dev/null || true`, {
+      encoding: 'utf8',
+    }).trim()
+    if (raw === '0' || raw === '') return
     const family = await buildFamilyFromFs(
       '019fdcda-75c7-74b7-a160-f67f6bf88384',
       REAL_AGENT_DIR,
@@ -682,6 +711,9 @@ const HAS_REAL_SUBAGENTS_DIR = existsSync(join(REAL_AGENT_DIR, 'subagents'))
 
 describe.skipIf(!HAS_REAL_ROOT || !HAS_REAL_SUBAGENTS_DIR)('U4 真实数据守卫：~/.pi/agent', () => {
   it('TC-u4-real-data-guard: 019fe620 subagents 富字段透传（manifest 主 task 非空率 > 80%）', async () => {
+    // 数据守卫：019fe635 是 019fe620 家族已知的隔代 subagent（含 task 富字段的锚点），
+    // 被 GC 后跳过富字段验证（manifest 数据不可复现，跳过比失败合理）。
+    if (!hasAnyRealSession('019fe635')) return
     const family = await buildFamilyFromFs(
       '019fe620-8ae1-78a7-b76a-43a1ba4cc3c7',
       REAL_AGENT_DIR,

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

@@ -12,6 +12,7 @@ import {
   HAS_E6,
   HAS_REAL,
   HAS_REAL_SUBAGENTS_DIR,
+  hasAnyRealSession,
   hasRealSession,
 } from './real-data.js'
 
@@ -27,6 +28,8 @@ import {
  * renderExtractItems F9 截断是纯 fixture，无条件跑。
  */
 
+// 真实数据套件 timeout 说明：find 全扫描 + 5.6MB 文件解析在并发/高负载下可能超过
+// vitest 默认 5s（pnpm extensions:test 全量跑时多包集成测试并发 IO），显式放宽到 60s。
 describe.skipIf(!HAS_REAL)('handleSessionRead', () => {
   it('1. find by uuid fragment returns matching session', async () => {
     const r = await handleSessionRead({ action: 'find', query: 'e6c96' }, REAL)
@@ -54,6 +57,11 @@ describe.skipIf(!HAS_REAL)('handleSessionRead', () => {
   })
 
   it('4. family lists fork children and隔代 subagents', async () => {
+    // 数据守卫：fork 子代 019fe632（sessions/）与隔代 subagent 019fe635（subagents/）
+    // 位于活跃数据目录（subagents 目录随 GC/新建持续变化），文件被清理/重命名时跳过
+    // 而非失败——与 TC14-TC18 的「数据不存在则 return」守卫模式一致，避免偶发红。
+    // 注意必须用 hasAnyRealSession（双目录），hasRealSession 只扫 sessions/ 扫不到 019fe635。
+    if (!hasAnyRealSession('019fe632') || !hasAnyRealSession('019fe635')) return
     const r = await handleSessionRead({ action: 'family', session: FAM }, REAL)
     const d = r.details as {
       forks: Array<{ sessionId: string }>
@@ -114,7 +122,7 @@ describe.skipIf(!HAS_REAL)('handleSessionRead', () => {
     const dFrag = rFrag.details as { turns: unknown[] }
     expect(dFrag.turns.length).toBe(dFull.turns.length)
   })
-})
+}, 60000)
 
 describe.skipIf(!HAS_E6)('extract (v2 O4)', () => {
   it('user-messages returns 26 user entries with turn + full text', async () => {
@@ -292,7 +300,7 @@ describe.skipIf(!HAS_E6)('extract (v2 O4)', () => {
     expect(msg).not.toContain('用 outline 重看有效范围')
     expect(msg).toContain('该 session extract 共')
   })
-})
+}, 60000)
 
 // ---- fixture 工具（tmpdir 造最小 session 文件，供 F2/MF-5 用例）----
 
@@ -364,6 +372,48 @@ describe('F2 多匹配消歧（fixture，MF-9）', () => {
   })
 })
 
+describe('outline skippedLines 报告（fixture，D8d 有检测必有报告）', () => {
+  let dir: string
+  const SID = '019e6c96-bbbb-cccc-dddd-00000000000b'
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'tool-handler-skipped-'))
+  })
+  afterEach(async () => {
+    await rm(dir, { recursive: true, force: true })
+  })
+
+  it('坏行计入 stats.skippedLines 且文本尾部可见（不静默跳过）', async () => {
+    // 中间注入 1 行坏 JSON（半截对象）：parser 计 skippedLines=1，outline 必须报告
+    const slug = '--demo-cwd--'
+    await mkdir(join(dir, 'sessions', slug), { recursive: true })
+    const lines = [
+      JSON.stringify({ type: 'session', id: SID, cwd: '/demo' }),
+      JSON.stringify({
+        type: 'message',
+        id: SID + '-m1',
+        parentId: SID,
+        message: { role: 'user', content: [{ type: 'text', text: 'hello' }] },
+      }),
+      '{"broken json line',
+    ]
+    await writeFile(join(dir, 'sessions', slug, SID + '.jsonl'), lines.join('\n') + '\n')
+
+    const r = await handleSessionRead({ action: 'outline', session: SID }, dir)
+    const d = r.details as { stats: { skippedLines: number } }
+    expect(d.stats.skippedLines).toBe(1)
+    expect(r.content[0].text).toContain('1 skipped lines')
+  })
+
+  it('无坏行时不输出 skipped 片段（正常 session 零噪音）', async () => {
+    await makeFixtureSession(dir, SID, 'clean session')
+    const r = await handleSessionRead({ action: 'outline', session: SID }, dir)
+    const d = r.details as { stats: { skippedLines: number } }
+    expect(d.stats.skippedLines).toBe(0)
+    expect(r.content[0].text).not.toContain('skipped lines')
+  })
+})
+
 describe('search 灾难性正则降级 + abort（fixture，MF-5 回归）', () => {
   let dir: string
   const SID = '019e6c96-bbbb-cccc-dddd-00000000000a'
@@ -924,7 +974,7 @@ describe.skipIf(!HAS_REAL_SUBAGENTS_DIR)('真实数据：subagent sa-id（w2 TC1
       handleSessionRead({ action: 'outline', session: fakeId }, REAL),
     ).rejects.toThrow('无匹配 record')
   })
-})
+}, 60000)
 
 // ============================================================
 // w6: doWorkflow action（TC-w6-single-run/multi-run/runid-filter/runid-not-found/no-runs/snapshot-skip/call-jump）
@@ -1297,7 +1347,7 @@ describe.skipIf(!HAS_REAL_WF_SESSION)('doWorkflow - 真实数据守卫', () => {
     expect(r.content[0].text).toContain('run:')
     expect(r.content[0].text).toContain('budget:')
   }, 30000)
-})
+}, 60000)
 
 // ============================================================
 // m3b：doFamily recursive false/true（TC-m3b-dofamily-recursive-false/true）

package/src/__tests__/turns.test.ts

@@ -138,5 +138,6 @@ describe('segmentTurns', () => {
     expect(turns.filter((t) => t.isCompaction).length).toBe(5)
     // 其中有 26 个 user turn
     expect(turns.filter((t) => t.userEntry !== undefined).length).toBe(26)
-  })
+    // 5.6MB 全量解析在并发/高负载下可能超 vitest 默认 5s，显式放宽
+  }, 60000)
 })

package/src/__tests__/workflow.test.ts

@@ -5,7 +5,7 @@ import { mkdtemp, writeFile, rm } from 'node:fs/promises'
 import { join } from 'node:path'
 
 import { parseRunSnapshot, renderWorkflowOverview } from '../core/workflow.js'
-import { readRunSnapshot } from '../discovery/workflows.js'
+import { extractCallSessionFiles, readRunSnapshot } from '../discovery/workflows.js'
 import { REAL_AGENT_DIR } from './real-data.js'
 
 // ============================================================
@@ -48,6 +48,42 @@ const NEW_SNAPSHOT_FIXTURE = {
   meta: { startedAt: '2026-08-03T13:05:50.111Z', completedAt: '2026-08-03T13:05:55.384Z' },
 }
 
+/**
+ * v2 格式 fixture（pi-subagent-workflow 8.x 一次性生命周期写入的 wf-run-v2 快照）。
+ * 读取面形状与 v1 一致（state.calls[].sessionFile/result 保留），差异仅版本字面量与
+ * status 两态（running/done）、meta 无 pausedAt——v2 不该因版本字面量被挡在读之外。
+ */
+const V2_SNAPSHOT_FIXTURE = {
+  v: 'wf-run-v2',
+  runId: 'wf-ignore',
+  spec: { scriptName: 'one-shot-flow', name: 'Flow Name', scriptSource: '// ...' },
+  state: {
+    status: 'done',
+    reason: 'completed',
+    budget: { usedTokens: 22000, usedCost: 0, totalCallCount: 2, maxTokens: 200000 },
+    calls: [
+      {
+        id: 0,
+        opts: { prompt: 'task 0', model: 'default', thinkingLevel: 'high', description: 'v2-step-0' },
+        status: 'done',
+        attempts: 1,
+        sessionId: '019v2a',
+        sessionFile: '/abs/v2-call0.jsonl',
+        traceNode: { stepIndex: 0, agent: 'dev-W1', task: 'task 0', model: 'default', status: 'completed', phase: 'P0' },
+      },
+      {
+        id: 1,
+        opts: { prompt: 'task 1', model: 'default' },
+        status: 'done',
+        attempts: 1,
+        result: { content: 'OK', durationMs: 567, sessionId: '019v2b', sessionFile: '/abs/v2-call1.jsonl' },
+        traceNode: { stepIndex: 1, agent: 'dev-W2', task: 'task 1', model: 'default', status: 'completed', phase: 'P1' },
+      },
+    ],
+  },
+  meta: { startedAt: '2026-08-10T10:00:00.000Z', completedAt: '2026-08-10T10:05:00.000Z' },
+}
+
 /** OLD 格式 fixture（对齐 wf-skip-ok.jsonl：无 v，callCache value 无 sessionFile/result）。 */
 const OLD_SNAPSHOT_FIXTURE = {
   runId: 'wf-old-ignore',
@@ -98,6 +134,23 @@ describe('parseRunSnapshot', () => {
     expect(step.contentPreview).toBe('PROBE-OK')
   })
 
+  it('TC-w5-parse-new-v2：v2 快照（pi-subagent-workflow 8.x 写入）解析非 null，calls sessionFile 读出', () => {
+    const overview = parseRunSnapshot(V2_SNAPSHOT_FIXTURE, 'wf-v2-link-runid', '/abs/wf-v2.jsonl')
+    expect(overview).not.toBeNull()
+    expect(overview!.version).toBe('wf-run-v2')
+    expect(overview!.status).toBe('done')
+    expect(overview!.reason).toBe('completed')
+    expect(overview!.script).toBe('one-shot-flow')
+    // steps：两个 call 的 sessionFile 均读出（顶层优先 / result.sessionFile 回退）
+    expect(overview!.steps).toHaveLength(2)
+    expect(overview!.steps[0].sessionFile).toBe('/abs/v2-call0.jsonl')
+    expect(overview!.steps[0].sessionId).toBe('019v2a')
+    expect(overview!.steps[0].description).toBe('v2-step-0')
+    expect(overview!.steps[1].sessionFile).toBe('/abs/v2-call1.jsonl')
+    expect(overview!.steps[1].sessionId).toBe('019v2b')
+    expect(overview!.steps[1].contentPreview).toBe('OK')
+  })
+
   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()
@@ -123,13 +176,31 @@ describe('parseRunSnapshot', () => {
   })
 
   it('TC-w5-parse-malformed：既非 NEW 也非 OLD（缺关键字段）返回 null', () => {
-    // (a) 有 v 但 v!=='wf-run-v1' 且无 callCache（未来版本 wf-run-v2）
-    expect(parseRunSnapshot({ v: 'wf-run-v2', state: { calls: [] } }, 'r', 's')).toBeNull()
+    // (a) 有 v 但 v 非 v1/v2 且无 callCache（未来版本 wf-run-v3 及之后——届时须评估
+    // 新版本读取面形状再扩判定，v2 因形状兼容被接受）
+    expect(parseRunSnapshot({ v: 'wf-run-v3', state: { calls: [] } }, 'r', 's')).toBeNull()
     // (b) 无 v 无 callCache 无 status（异构对象）
     expect(parseRunSnapshot({ foo: 'bar', baz: 1 }, 'r', 's')).toBeNull()
   })
 })
 
+// ============================================================
+// extractCallSessionFiles（纯逻辑，family/workflows 腿的 sessionFile 提取入口）
+// ============================================================
+
+describe('extractCallSessionFiles', () => {
+  it('v2 快照（wf-run-v2）state.calls 的 sessionFile 能被读出，不因版本字面量挡读', () => {
+    const files = extractCallSessionFiles(V2_SNAPSHOT_FIXTURE)
+    // 顶层 sessionFile + result.sessionFile 回退，两个 call 都读出
+    expect(files).toEqual(['/abs/v2-call0.jsonl', '/abs/v2-call1.jsonl'])
+  })
+
+  it('v1 快照（wf-run-v1）行为不变：state.calls 提取', () => {
+    const files = extractCallSessionFiles(NEW_SNAPSHOT_FIXTURE)
+    expect(files).toEqual(['/abs/session.jsonl'])
+  })
+})
+
 // ============================================================
 // renderWorkflowOverview（纯逻辑，TC-w5-render-new/old）
 // ============================================================

package/src/core/parser.ts

@@ -60,15 +60,11 @@ function toEntry(raw: unknown): Entry | undefined {
   const obj = raw as Record<string, unknown>
   if (typeof obj.type !== 'string') return undefined
 
-  // id 解析：顶层 id 优先；custom entry 无顶层 id 时 fallback 到 data.id
-  //（pi 的 subagent-identity 等 custom entry 把 id 放在 data.id，非顶层——真实样本确认）
-  let id: unknown = obj.id
-  if (typeof id !== 'string' && obj.type === 'custom') {
-    const data = obj.data
-    if (typeof data === 'object' && data !== null && typeof (data as Record<string, unknown>).id === 'string') {
-      id = (data as Record<string, unknown>).id
-    }
-  }
+  // id 解析：pi appendCustomEntry 恒写顶层 id（session-manager.js:820-828）——
+  // 无需 fallback。data.id 是扩展业务字段（如 subagent-identity payload），不是 entry id。
+  // [W4 删除] 原 data.id fallback 分支对 pi 写出的 entry 是死分支（对历史/异构文件
+  // 也无必要——entry id 语义以顶层为准）。
+  const id: unknown = obj.id
   if (typeof id !== 'string') return undefined
 
   const entry: Entry = {

package/src/core/render.ts

@@ -26,7 +26,8 @@ export interface TurnBrief {
 
 export interface OutlineResult {
   turns: TurnBrief[]
-  stats: { totalTurns: number; totalEntries: number; totalBytes: number; parsedBytes: number }
+  /** skippedLines：JSON 解析失败/缺结构字段的行数（parser 检测，工具层覆盖精确值；render 层无 ParseResult 恒 0） */
+  stats: { totalTurns: number; totalEntries: number; totalBytes: number; parsedBytes: number; skippedLines: number }
   /** chars / 4 近似（与 design P-outline 口径一致） */
   tokenEstimate: number
   /** 被总预算截断的 turn 数（从尾部丢弃） */
@@ -319,6 +320,7 @@ export function renderOutline(
     totalEntries: totalEntriesAll,
     totalBytes: parsedBytes,
     parsedBytes,
+    skippedLines: 0,
   }
 
   if (turns.length === 0) {

package/src/core/workflow.ts

@@ -3,7 +3,7 @@
 // ============================================================
 //
 // 本文件消费 discovery/workflows.ts 的 readRunSnapshot（返 unknown 原始快照对象），
-// 把 unknown 类型化为 WorkflowOverview（NEW v='wf-run-v1' / OLD 无 v 双格式分支），
+// 把 unknown 类型化为 WorkflowOverview（NEW v='wf-run-v1'/'wf-run-v2' / OLD 无 v 双格式分支），
 // 再渲染为人类可读文本。零 IO：parseRunSnapshot/renderWorkflowOverview 喂 mock 即可单测
 //（w5 TC-wf-core-pure-logic，对齐 session-reader core/* 纯逻辑约定）。
 //
@@ -78,8 +78,8 @@ export interface WorkflowOverview {
   stateFile: string
   /** NEW state.status / OLD 顶层 status */
   status: string
-  /** 格式标记（渲染/调试用） */
-  version: 'wf-run-v1' | 'legacy'
+  /** 格式标记（渲染/调试用）。v2 读取面形状与 v1 一致（pi-subagent-workflow 8.x 一次性生命周期） */
+  version: 'wf-run-v1' | 'wf-run-v2' | 'legacy'
   /** NEW spec.scriptName / spec.name / OLD name */
   script?: string
   /** NEW meta.startedAt / OLD startedAt（统一 string） */
@@ -199,9 +199,9 @@ function mapCacheEntryToStep(entry: unknown, index: number): WorkflowStep {
  *
  * 分支（C-parserunsnapshot-dualformat，TC-wf-snapshot-version-union）：
  * - 非对象 → null（调用方跳过，ES-wf-snapshot-unparseable）
- * - NEW (snapshot.v === 'wf-run-v1')：state.* / meta.* / spec.*
+ * - NEW (snapshot.v === 'wf-run-v1' 或 'wf-run-v2'，读取面形状一致)：state.* / meta.* / spec.*
  * - OLD (无 v，有 callCache 数组或顶层 status)：顶层 status/budget/startedAt + callCache
- * - 既非 NEW 也非 OLD → null（未来版本 wf-run-v2 / 异构内容）
+ * - 既非 NEW 也非 OLD → null（未来版本（如 wf-run-v3）/ 异构内容）
  *
  * runId/stateFile 透传参数（不读 snapshot.runId，保证与 family.workflows 一致，避免 OLD 顶层
  * runId 可信度低的不一致）。零 any（全程 typeof/Array.isArray/isRecord 守卫收窄）。
@@ -213,8 +213,9 @@ export function parseRunSnapshot(
 ): WorkflowOverview | null {
   if (!isRecord(snapshot)) return null
 
-  // NEW 格式（v === 'wf-run-v1'）
-  if (snapshot.v === 'wf-run-v1') {
+  // NEW 格式（v === 'wf-run-v1' || 'wf-run-v2'，v2 读取面形状兼容 v1）
+  const v = snapshot.v
+  if (v === 'wf-run-v1' || v === 'wf-run-v2') {
     const state = isRecord(snapshot.state) ? snapshot.state : {}
     const meta = isRecord(snapshot.meta) ? snapshot.meta : {}
     const spec = isRecord(snapshot.spec) ? snapshot.spec : {}
@@ -223,7 +224,7 @@ export function parseRunSnapshot(
       runId,
       stateFile,
       status: typeof state.status === 'string' ? state.status : '',
-      version: 'wf-run-v1',
+      version: v,
       script:
         typeof spec.scriptName === 'string'
           ? spec.scriptName

package/src/discovery/roots.ts

@@ -19,8 +19,9 @@ export interface SessionFileMeta {
 
 /**
  * main sessions 扫描时整体跳过的子目录名。
- * `workflow-state` 目录存放 workflow 运行状态文件（wf-*.jsonl，首行 `{"v":"wf-run-v1"...}`），
- * 非 session 文件——属 family 腿独立处理（design §3.3 D-7），扫描 main sessions 时排除，
+ * `workflow-state` 目录存放 workflow 运行状态文件（wf-*.jsonl，首行 `{"v":"wf-run-v1"|"wf-run-v2"...}`，
+ * 版本随 subagent-workflow 快照格式演进，读取侧 v1/v2 兼容），非 session 文件——属 family 腿
+ * 独立处理（design §3.3 D-7），扫描 main sessions 时排除，
  * 否则会把 wf 文件误收为 session（且 find.ts 读其首行 header 时会因 type≠session 被丢弃，
  * 在此排除可避免这批无效首行扫描）。
  */

package/src/discovery/workflows.ts

@@ -25,14 +25,16 @@ import { extractSessionIdFromFilename } from './subagents.js'
  * 从 wf-state 快照对象提取 calls[].sessionFile（绝对路径数组）。
  *
  * 两种格式（探查确认，本机 371 个 wf 文件）：
- * - NEW (v="wf-run-v1")：state.calls[]，每项顶层 .sessionFile（258 文件 / 1590 sessionFile）
+ * - NEW (v="wf-run-v1" 或 "wf-run-v2"，读取面形状一致)：state.calls[]，每项顶层
+ *   .sessionFile（258 文件 / 1590 sessionFile）。v2 由 pi-subagent-workflow 8.x 一次性
+ *   生命周期收敛引入（status 两态、无 pausedAt），calls[].sessionFile/result 保留
  * - OLD (无 v)：callCache[]=[{key,value}]，value.sessionFile（112 文件 / 0 sessionFile，旧 pi 不持久化）
  */
 export function extractCallSessionFiles(snap: unknown): string[] {
   const out: string[] = []
   if (typeof snap !== 'object' || snap === null) return out
   const s = snap as Record<string, unknown>
-  const isNew = s.v === 'wf-run-v1'
+  const isNew = s.v === 'wf-run-v1' || s.v === 'wf-run-v2'
   let callsRaw: unknown
   if (isNew) {
     const state = s.state

package/src/index.ts

@@ -12,7 +12,9 @@ import { createSessionCommand } from './tui/session-command.js'
  * 分层（同 scheduler/cw-tool）：
  * - tool-handler.ts：纯逻辑 handler，agentDir 注入，零 pi 依赖，可单测
  * - index.ts（本文件）：pi 依赖层，registerTool + getAgentDir() 调用 + execute 闭包
- *   （catch handler 抛的 Error 转 isError:true，execute 不向 pi 抛——pi 工具契约）
+ *   （错误直接 throw 给 pi——pi-agent-core agent-loop 只对 execute throw 置
+ *   isError:true，返回值里的 isError 字段被丢弃；W4 修复，锚点
+ *   agent-loop.js:453-483/525-547，pi 自带 bash 工具同范式）
  *
  * M4 将在此 addAutocompleteProvider（TUI # 补全，ctx.mode === 'tui' 时）。
  */
@@ -164,17 +166,12 @@ export default function sessionReaderExtension(pi: ExtensionAPI): void {
       _onUpdate: unknown,
       _ctx: ExtensionContext,
     ) {
-      try {
-        // signal 仅 search 消费（MF-5：长扫描可中断，Esc 不再挂死）；其余 action 有界不接
-        return await handleSessionRead(params, getAgentDir(), signal)
-      } catch (e) {
-        const msg = e instanceof Error ? e.message : String(e)
-        return {
-          content: [{ type: 'text' as const, text: msg }],
-          details: {},
-          isError: true,
-        }
-      }
+      // 错误路径直接 throw：pi 契约只有 throw 才置 isError:true（tool_execution_end /
+      // ToolResultMessage），handler 抛的 Error 文案（含 👉 恢复提示）原样成为
+      // toolResult content，模型仍可读到。曾用 return {isError:true}——被 agent-loop
+      // 丢弃，错误轮被标成功（W4 修复）。
+      // signal 仅 search 消费（MF-5：长扫描可中断，Esc 不再挂死）；其余 action 有界不接
+      return handleSessionRead(params, getAgentDir(), signal)
     },
   })
 

package/src/tool-handler.ts

@@ -7,8 +7,9 @@
  * 按 action 分发到 8 条路径，串联 M1 core（parser/tree/turns/render）+ M2 discovery
  *（find/subagents）。content 给 LLM 读（人类可读摘要），details 供程序化消费/测试断言。
  *
- * 错误规格 F1-F6：handler 抛 Error（message 含 👉 恢复指引），由 index.ts 的 execute
- * 闭包 catch 转 isError:true 文本返回——handler 可抛（纯逻辑可测），execute 不抛（pi 契约）。
+ * 错误规格 F1-F6：handler 抛 Error（message 含 👉 恢复指引），index.ts 的 execute 闭包
+ * 原样传播给 pi——pi-agent-core 只对 execute throw 置 isError:true（返回值里的 isError
+ * 字段被丢弃，agent-loop.js:453-483）。handler 可抛（纯逻辑可测）。
  * 例外：F2 多匹配与 F1 find 零匹配「不视为错误」，返回消歧/提示结果而非抛错。
  */
 import { existsSync, openSync, readSync, closeSync } from 'node:fs'
@@ -425,7 +426,9 @@ function formatOutlineText(r: OutlineResult): string {
   })
   const tail = [
     '',
-    `${r.stats.totalTurns} turns · ${r.stats.totalEntries} entries · ~${r.tokenEstimate} tokens`,
+    `${r.stats.totalTurns} turns · ${r.stats.totalEntries} entries · ~${r.tokenEstimate} tokens${
+      r.stats.skippedLines > 0 ? ` · ${r.stats.skippedLines} skipped lines` : ''
+    }`,
     r.truncated ? `[还有 ${r.truncated} 轮未显示，用 detail 或调大 budget]` : '',
   ]
     .filter(Boolean)
@@ -677,7 +680,7 @@ async function doFamily(params: SessionReadParams, agentDir: string): Promise<To
 async function doOutline(params: SessionReadParams, agentDir: string): Promise<ToolResult> {
   const resolved = await resolveSessionId(params.session, 'outline', agentDir, params.source)
   if (resolved.kind === 'multi') return disambiguate(resolved.query, resolved.candidates)
-  const { entries, totalBytes } = await safeParse(resolved.fileName)
+  const { entries, totalBytes, skippedLines } = await safeParse(resolved.fileName)
   const tree = buildTreeView(entries)
   const turns = segmentTurns(entries, new Set(tree.leafPath))
   const opts: OutlineOptions = {
@@ -689,6 +692,9 @@ async function doOutline(params: SessionReadParams, agentDir: string): Promise<T
   // 覆盖 stats.totalBytes：render 用 parsedBytes（leaf entry JSON 字节和）近似，
   // 此处用 ParseResult.totalBytes（原始文件字节数，design §3.4 stats.totalBytes 语义）
   result.stats.totalBytes = totalBytes
+  // [D8d] skippedLines 同模式覆盖：parser 已检测坏行计数（render 签名不含 ParseResult 恒 0），
+  // 有检测必有报告——静默跳过行对调用方不可见 = 数据完整性缺口
+  result.stats.skippedLines = skippedLines
   return { content: [{ type: 'text', text: formatOutlineText(result) }], details: result }
 }