@zhushanwen/pi-session-reader 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-session-reader",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "main": "index.ts",
   "pi": {

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__/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', () => {

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 用例）----
 
@@ -924,7 +932,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 +1305,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/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