@zhushanwen/pi-session-reader 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-session-reader",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
   "main": "index.ts",
   "taiji": {
@@ -17,14 +17,14 @@
   ],
   "dependencies": {
     "@zhushanwen/pi-extension-logger": "0.6.1",
-    "@zhushanwen/pi-ext-guards": "0.4.1",
     "@zhushanwen/session-core": "0.11.0",
-    "@zhushanwen/zcode-session-source": "0.2.0"
+    "@zhushanwen/zcode-session-source": "0.2.1",
+    "@zhushanwen/pi-ext-guards": "0.4.2"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.9",
     "vitest": "^4.1.8",
-    "@zhushanwen/subagent-core": "0.11.1"
+    "@zhushanwen/subagent-core": "0.12.0"
   },
   "files": [
     "index.ts",

package/src/__tests__/entry-anchor.test.ts

@@ -3,7 +3,7 @@ import { tmpdir } from 'node:os'
 import { mkdtempSync, writeFileSync, rmSync, mkdirSync } from 'node:fs'
 import { join } from 'node:path'
 
-import { SUBAGENT_RECORD_CUSTOM_TYPE } from '@zhushanwen/subagent-core'
+import { SUBAGENT_RECORD_CUSTOM_TYPE, SUBAGENT_RECORD_ENTRY_VERSION } from '@zhushanwen/subagent-core'
 
 import { findZcodeEntryAnchor, type ZcodeAnchor } from '../discovery/entry-anchor.js'
 
@@ -53,6 +53,68 @@ function messageLine(entryId: string, text: string): string {
   })
 }
 
+/**
+ * v2 终态条行（W1 D1：`{v:2, kind:"settled", id, engine?, engineHandle?, ...}`——
+ * 载荷形态对齐 subagent-core SubagentRecordSettledEntryData，锚取 engineHandle.sessionRef）。
+ */
+function v2SettledLine(
+  entryId: string,
+  saId: string,
+  opts: {
+    sessionRef?: Record<string, string>
+    engine?: string
+  } = {},
+): string {
+  const data: Record<string, unknown> = {
+    v: 2,
+    kind: 'settled',
+    id: saId,
+    status: 'idle',
+    stopReason: 'end_turn',
+    endedAt: 123,
+    turns: 1,
+    totalTokens: 10,
+    model: undefined,
+    thinkingLevel: undefined,
+  }
+  if (opts.engine !== undefined) data.engine = opts.engine
+  if (opts.sessionRef !== undefined) {
+    data.engineHandle = { sessionRef: opts.sessionRef, poolKey: 'shared' }
+  }
+  return JSON.stringify({
+    type: 'custom',
+    customType: 'subagent-record',
+    id: entryId,
+    parentId: null,
+    data,
+  })
+}
+
+/**
+ * v2 注册条行（`{v:2, kind:"registered", id, agent, task, ...}`——身份域字段，不携带
+ * engineHandle；设计 D1 裁决「sessionRef 双键取自终态条」，注册条目不是锚源）。
+ */
+function v2RegisteredLine(entryId: string, saId: string): string {
+  return JSON.stringify({
+    type: 'custom',
+    customType: 'subagent-record',
+    id: entryId,
+    parentId: null,
+    data: {
+      v: 2,
+      kind: 'registered',
+      id: saId,
+      agent: 'dev',
+      task: 't',
+      slug: 's',
+      origin: 'tool',
+      rootSessionId: 'root-1',
+      depth: 0,
+      startedAt: 1,
+    },
+  })
+}
+
 /** 缺 dbPath 的 sessionRef（pi record 形态：只有 sessionId 单键）。 */
 const REF_NO_DBPATH = { sessionId: 'sess-pi-x' }
 
@@ -146,16 +208,94 @@ describe('形状校验窄而严：缺键条目不算命中，继续找更早条
     expect(await findZcodeEntryAnchor([file], 'sa-1')).toBeUndefined()
   })
 
-  it('data.v ≠ 1 的条目不算命中，更早 v=1 条目仍可命中', async () => {
+  it('data.v 为认识的 v1/v2 之外的版本（future-v，如 3）不算命中，更早 v=1 条目仍可命中', async () => {
     const file = writeMainSession('main.jsonl', [
       JSON.stringify({ type: 'session', id: 'main-1' }),
       recordLine('e1', 'sa-1', { sessionId: 'sess-A', dbPath: DB_PATH }),
-      recordLine('e2', 'sa-1', { sessionId: 'sess-V2', dbPath: DB_PATH }, 2),
+      recordLine('e2', 'sa-1', { sessionId: 'sess-V3', dbPath: DB_PATH }, 3),
     ])
 
     const anchor = await findZcodeEntryAnchor([file], 'sa-1')
     expect(anchor?.sessionId).toBe('sess-A')
-    expect(anchor?.sessionId).not.toBe('sess-V2')
+    expect(anchor?.sessionId).not.toBe('sess-V3')
+  })
+})
+
+// ============================================================
+// v2 终态条锚定（W1 D1 版本门补齐：sessionRef 双键取自终态条）
+// ============================================================
+
+describe('v2 终态条锚定：kind="settled" + engineHandle.sessionRef 双键', () => {
+  it('v2 终态条完整锚（sessionRef 双键齐）→ 命中', async () => {
+    const file = writeMainSession('main.jsonl', [
+      JSON.stringify({ type: 'session', id: 'main-1' }),
+      messageLine('m1', 'dispatch'),
+      v2SettledLine('e1', 'sa-1', {
+        engine: 'zcode',
+        sessionRef: { sessionId: 'sess-V2A', dbPath: DB_PATH },
+      }),
+    ])
+
+    const anchor = await findZcodeEntryAnchor([file], 'sa-1')
+    expect(anchor).toBeDefined()
+    expect(anchor?.sessionId).toBe('sess-V2A')
+    expect(anchor?.dbPath).toBe(DB_PATH)
+  })
+
+  it('v2 注册条（kind="registered"，不携带 engineHandle）→ 不命中（锚只取自终态条）', async () => {
+    const file = writeMainSession('main.jsonl', [
+      JSON.stringify({ type: 'session', id: 'main-1' }),
+      v2RegisteredLine('e-reg', 'sa-1'),
+    ])
+
+    expect(await findZcodeEntryAnchor([file], 'sa-1')).toBeUndefined()
+  })
+
+  it('v1 快照条（早）+ v2 终态条（晚）→ 末条 v2 胜（末条锚定跨版本一致）', async () => {
+    const file = writeMainSession('main.jsonl', [
+      JSON.stringify({ type: 'session', id: 'main-1' }),
+      recordLine('e1', 'sa-1', { sessionId: 'sess-V1OLD', dbPath: DB_PATH }),
+      v2SettledLine('e2', 'sa-1', {
+        engine: 'zcode',
+        sessionRef: { sessionId: 'sess-V2NEW', dbPath: DB_PATH },
+      }),
+    ])
+
+    const anchor = await findZcodeEntryAnchor([file], 'sa-1')
+    expect(anchor?.sessionId).toBe('sess-V2NEW')
+    expect(anchor?.sessionId).not.toBe('sess-V1OLD')
+  })
+
+  it('v2 终态条锚残缺（缺 engineHandle）→ 不命中，更早 v1 完整条目仍可命中（缺键不遮蔽）', async () => {
+    const file = writeMainSession('main.jsonl', [
+      JSON.stringify({ type: 'session', id: 'main-1' }),
+      recordLine('e1', 'sa-1', { sessionId: 'sess-EARLY', dbPath: DB_PATH }),
+      v2SettledLine('e2', 'sa-1', { engine: 'zcode' }), // 无 sessionRef
+    ])
+
+    const anchor = await findZcodeEntryAnchor([file], 'sa-1')
+    expect(anchor?.sessionId).toBe('sess-EARLY')
+  })
+
+  it('v2 但 kind 不在词表（unknown-kind，非 registered/settled）→ 不命中', async () => {
+    const badKind = JSON.stringify({
+      type: 'custom',
+      customType: 'subagent-record',
+      id: 'e-bad',
+      parentId: null,
+      data: {
+        v: 2,
+        kind: 'migrated',
+        id: 'sa-1',
+        engineHandle: { sessionRef: { sessionId: 'sess-BAD', dbPath: DB_PATH }, poolKey: 'shared' },
+      },
+    })
+    const file = writeMainSession('main.jsonl', [
+      JSON.stringify({ type: 'session', id: 'main-1' }),
+      badKind,
+    ])
+
+    expect(await findZcodeEntryAnchor([file], 'sa-1')).toBeUndefined()
   })
 })
 
@@ -223,4 +363,8 @@ describe('协议字面量漂移守卫（跨包契约）', () => {
     // 源码本地持有磁盘协议字符串（生产依赖面不引 subagent-core），此处锚定两侧同值
     expect(SUBAGENT_RECORD_CUSTOM_TYPE).toBe('subagent-record')
   })
+
+  it('entry-anchor 本地 v2 认识版本 === subagent-core 写侧单源（写侧再升版本本守卫先红）', () => {
+    expect(SUBAGENT_RECORD_ENTRY_VERSION).toBe(2)
+  })
 })

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

@@ -17,11 +17,9 @@ import { buildExecutionTree, formatExecutionTreeText, type ExecutionTreeNode } f
  * - TC-m3b-cycle-detection：workflow 指针环（A→B→A），visited Set 防环
  * - TC-m3b-single-node：单节点树（无后代，ES5）
  * - TC-m3b-source-priority：parentRecordId 三级数据源优先级（manifest>identity>flat，DM4）
- * - TC-m3b-real-data-guard：真实形态数据守卫（合成 fixture）。原直读本机 ~/.pi/agent 动态
- *   发现家族根（skipIf CI 无数据），真实数据演化后确定性红且触碰真实数据目录（TEST-STRATEGY
- *   红线），2026-09 数据面合成化：mkdtemp 临时目录仿真真实 agentDir 布局（时间戳前缀文件名 /
- *   新旧机制混合 / 孤儿 manifest / 坏 manifest / 外来家族），guard 语义不变——解析不抛错 /
- *   树非空 / 结构自洽，不锁 sourceMode 具体值
+ * - TC-m3b-real-data-guard：真实形态数据守卫（合成 fixture）：mkdtemp 临时目录仿真真实
+ *   agentDir 布局（时间戳前缀文件名 / 新旧机制混合 / 孤儿 manifest / 坏 manifest / 外来
+ *   家族），guard 语义断言——解析不抛错 / 树非空 / 结构自洽，不锁 sourceMode 具体值
  */
 
 // ---- fixture 常量（uuid 特征，互不为子串，满足 extractSessionIdFromFilename）----
@@ -685,13 +683,9 @@ describe('buildExecutionTree - fixture', () => {
 })
 
 // ============================================================
-// 真实形态数据守卫（合成 fixture，2026-09 测试债修复）
+// 真实形态数据守卫（合成 fixture）：mkdtemp 临时目录仿真真实 agentDir 布局，
+// guard 语义断言（解析不抛错 / 树非空 / 结构自洽 / sourceMode 值域），不触碰真实数据目录。
 // ============================================================
-//
-// 原用例直读本机 ~/.pi/agent（execSync 探测 + findRealTreeRoot 扫真实 records 动态发现
-// 家族根，skipIf CI 无数据）：真实数据演化后确定性红（impl-plan 台账登记根因），且触碰
-// 真实数据目录违反 TEST-STRATEGY 红线。数据面合成化——mkdtemp 临时目录仿真真实 agentDir
-// 布局，guard 语义断言（解析不抛错 / 树非空 / 结构自洽 / sourceMode 值域）原样保留。
 
 describe('buildExecutionTree - 真实形态数据守卫（合成）', () => {
   let dir: string
@@ -704,7 +698,7 @@ describe('buildExecutionTree - 真实形态数据守卫（合成）', () => {
   })
 
   it('TC-m3b-real-data-guard：真实形态布局（时间戳文件名/新旧机制混合/孤儿 manifest/坏 manifest/外来家族）解析不抛错，树非空且结构自洽', async () => {
-    // 仿真真实 agentDir 数据形态（原直读本机 ~/.pi/agent，合成化后确定性可重跑）：
+    // 仿真真实 agentDir 数据形态（全部 mkdtemp 自建自删，确定性可重跑）：
     // - session 文件名带时间戳前缀（<ISO 时间戳>_<sessionId>.jsonl，真实 pi 落盘形态）
     // - 混合新旧机制：A 顶层（无 parentRecordId）→ B 嵌套（manifest.parentRecordId 精确链）；
     //   C 旧机制顶层（manifest/identity 均无 parentRecordId → flat 挂 main）

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, HAS_REAL_SUBAGENTS_DIR, REAL_DATA_TIMEOUT_MS } from './real-data.js'
+import { FIX_E6 } from './fixtures.js'
 
 /**
  * 建一个假 session 文件：首行 header（type=session，含 id/cwd/parentSession），
@@ -534,61 +534,21 @@ describe('findSessions', () => {
       // 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')
-      },
-      REAL_DATA_TIMEOUT_MS,
-    )
   })
 
-  it.skipIf(!HAS_E6)('真实数据：e6c96 匹配 019e6c96 开头的 session', async () => {
-    const { matches } = await findSessions('e6c96', REAL_AGENT_DIR)
+  it('uuid 片段命中候选补全元数据：fileName/mtime/sizeBytes 真实值（019e6c96 锚）', async () => {
+    // 2 条 session、恰 1 条 id 含片段 'e6c96'：uuid 片段路径命中后仍补读元数据字段。
+    // 命中文件按真实 pi 落盘命名（<id>.jsonl），fileName 断言含该 id
+    await makeSession(slugDir, { name: `${FIX_E6}.jsonl`, id: FIX_E6, cwd: '/demo' })
+    await makeSession(slugDir, { name: 'other.jsonl', id: '019ffff-cccc-dddd', cwd: '/demo' })
+
+    const { matches } = await findSessions('e6c96', agentDir)
     expect(matches.length).toBeGreaterThan(0)
-    expect(matches.some((m) => m.sessionId.startsWith('019e6c96'))).toBe(true)
-    // 真实值校验
     const hit = matches.find((m) => m.sessionId.startsWith('019e6c96'))!
     expect(hit.fileName).toContain('019e6c96')
     expect(hit.mtime).toBeGreaterThan(0)
     expect(hit.sizeBytes).toBeGreaterThan(0)
-  }, REAL_DATA_TIMEOUT_MS)
-
-  it.skipIf(!HAS_E6)("真实数据：recent 返回最近 N 个，mtime 倒序，truncated=true", async () => {
-    const { matches, truncated } = await findSessions('recent', REAL_AGENT_DIR, { limit: 5 })
-    expect(matches.length).toBeGreaterThan(0)
-    expect(matches.length).toBeLessThanOrEqual(5)
-    // mtime 倒序
-    for (let i = 1; i < matches.length; i++) {
-      expect(matches[i - 1].mtime).toBeGreaterThanOrEqual(matches[i].mtime)
-    }
-    // 真实 session 文件远多于 5 → 截断
-    expect(truncated).toBe(true)
-  }, REAL_DATA_TIMEOUT_MS)
-
-  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')
-      }
-    },
-    REAL_DATA_TIMEOUT_MS,
-  )
+  })
 })
 
 // ============================================================

package/src/__tests__/fixtures.ts

@@ -0,0 +1,15 @@
+/**
+ * 测试 fixture 常量（跨测试文件共享的 uuid 形态标识符）。
+ *
+ * 全部用例的项目内数据 = 各测试文件用 mkdtemp 自建自删的最小 session 文件
+ *（按测试断言逻辑构造，不读本机真实用户数据目录）。本文件只登记 uuid 常量，
+ * 取值约束：
+ * - 合法 uuid 形态（满足 extractSessionIdFromFilename / header id 谓词）；
+ * - FIX_E6 含十六进制片段 'e6c96'，作 uuid 片段匹配路径（find/resolveSessionId）的锚 id，
+ *   且完整 id 以 '019e6c96' 开头，供前缀断言。
+ *
+ * 本文件无 .test.ts 后缀，vitest include 只收集 `src/__tests__/` 下以 .test.ts 结尾的文件，不收集本文件。
+ */
+
+/** 主 fixture session id：片段 'e6c96' 命中 + 完整 id '019e6c96' 前缀断言的锚。 */
+export const FIX_E6 = '019e6c96-0a0c-74b8-a73f-d1854d88e2a7'

package/src/__tests__/parser.test.ts

@@ -1,6 +1,8 @@
 import { describe, it, expect } from 'vitest'
+import { mkdtemp, writeFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
 import { parseSessionContent, parseSessionFile, type Entry } from '@zhushanwen/session-core'
-import { REAL_SESSION, HAS_REAL_SESSION } from './real-data.js'
 
 /** 构造单行 JSONL entry 字符串 */
 function line(obj: Record<string, unknown>): string {
@@ -157,14 +159,37 @@ describe('parseSessionContent', () => {
 })
 
 describe('parseSessionFile', () => {
-  it.skipIf(!HAS_REAL_SESSION)('真实 session 019e6c96：1204 entries / 0 skipped / 非 partial', async () => {
-    const result = await parseSessionFile(REAL_SESSION)
-
-    expect(result.entries).toHaveLength(1204)
-    expect(result.skippedLines).toBe(0)
-    expect(result.lastLinePartial).toBe(false)
-    // 5.4MB 量级
-    expect(result.totalBytes).toBeGreaterThan(5_000_000)
-    // 5.6MB 全量解析在并发/高负载下可能超 vitest 默认 5s，显式放宽
-  }, 60000)
+  it('磁盘文件全量解析：entries 数 = 行数 / 0 skipped / 非 partial / totalBytes 与内容一致', async () => {
+    // mkdtemp 自建自删的 fixture 文件（不读本机真实数据目录）：session header +
+    // 10 条链式 message 的最小行集，验证「文件读取 → 逐行解析」回路的完整性与计数字段
+    const dir = await mkdtemp(join(tmpdir(), 'parser-file-'))
+    try {
+      const lines = [
+        line({ type: 'session', id: 's1', parentId: null, cwd: '/x' }),
+        ...Array.from({ length: 10 }, (_, i) =>
+          line({
+            type: 'message',
+            id: `m${i}`,
+            parentId: i === 0 ? 's1' : `m${i - 1}`,
+            message: {
+              role: i % 2 === 0 ? 'user' : 'assistant',
+              content: [{ type: 'text', text: `text ${i}` }],
+            },
+          }),
+        ),
+      ]
+      const content = lines.join('\n') + '\n'
+      const path = join(dir, 'fixture-session.jsonl')
+      await writeFile(path, content)
+
+      const result = await parseSessionFile(path)
+
+      expect(result.entries).toHaveLength(11)
+      expect(result.skippedLines).toBe(0)
+      expect(result.lastLinePartial).toBe(false)
+      expect(result.totalBytes).toBe(Buffer.byteLength(content, 'utf8'))
+    } finally {
+      await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+    }
+  })
 })

package/src/__tests__/render.test.ts

@@ -1,11 +1,8 @@
 import { describe, it, expect } from 'vitest'
 import { renderOutline, renderExpand, renderDetail, type ToolResultSummaryEntry } from '../core/render.js'
-import { parseSessionFile, type Entry } from '@zhushanwen/session-core'
+import type { Entry } from '@zhushanwen/session-core'
 import type { Turn } from '../core/turns.js'
 import type { TreeView } from '../core/tree.js'
-import { buildTreeView } from '../core/tree.js'
-import { segmentTurns } from '../core/turns.js'
-import { REAL_SESSION, HAS_REAL_SESSION } from './real-data.js'
 
 // ---- 构造助手 ----
 
@@ -203,25 +200,32 @@ describe('renderOutline', () => {
     expect(noBranch.lines).toEqual(['T000 · hi'])
   })
 
-  it.skipIf(!HAS_REAL_SESSION)('8. 真实 019e6c96：outline tokenEstimate <= 1500 + assistantBrief/toolSummary 非空（v2 O1）', async () => {
-    // v2 O1：加 assistantBrief + 修 toolSummary bug 后 outline 变长，阈值 600→1500（design §3.3 D4）
-    const parsed = await parseSessionFile(REAL_SESSION)
-    const tree = buildTreeView(parsed.entries)
-    const turns = segmentTurns(parsed.entries, new Set(tree.leafPath))
-    const result = renderOutline(turns, tree, { budget: 2000 })
+  it('8. 多 turn outline：tokenEstimate <= 1500 + assistantBrief/toolSummary 非空 + stats 完整（v2 O1）', () => {
+    // v2 O1：加 assistantBrief + 修 toolSummary bug 后 outline 行含结论与工具聚合，
+    // 阈值 1500（design §3.3 D4）。3 turn 合成数据，每 turn 带 toolCall + toolResult
+    const turns = [0, 1, 2].map((i) =>
+      turn(
+        i,
+        [
+          uEntry(`U${i}`, `问题 ${i}`),
+          aEntry(`A${i}`, `结论 ${i}`, [{ name: 'bash' }, { name: 'read' }]),
+          tEntry(`T${i}`, 'output'),
+        ],
+        { userEntry: uEntry(`U${i}`, `问题 ${i}`) },
+      ),
+    )
+    const result = renderOutline(turns, emptyTree(), { budget: 2000 })
 
-    expect(result.turns.length).toBe(32)
+    expect(result.turns.length).toBe(3)
     expect(result.tokenEstimate).toBeLessThanOrEqual(1500)
-    // v2 O1 验证：assistant 结论行存在（非空）+ toolSummary 显示真实工具（修 v1 恒空 bug）
+    // v2 O1 验证：assistant 结论行存在（非空）+ toolSummary 显示工具（修 v1 恒空 bug）
     expect(result.turns.some((b) => b.assistantBrief !== '')).toBe(true)
     expect(result.turns.some((b) => b.toolSummary !== '')).toBe(true)
     // stats 完整性
-    expect(result.stats.totalTurns).toBe(32)
-    // totalEntries 近似（leaf+branch+orphan）不含 session header（segmentTurns 规则1 跳过）；
-    // 工具层仅覆盖 stats.totalBytes 与 skippedLines（ParseResult 无 totalEntries 字段）。M1 验量级。
-    expect(result.stats.totalEntries).toBeGreaterThan(1000)
-    // 5.6MB 全量解析在并发/高负载下可能超 vitest 默认 5s，显式放宽
-  }, 60000)
+    expect(result.stats.totalTurns).toBe(3)
+    // totalEntries 近似（leaf+branch+orphan）不含 session header（segmentTurns 规则1 跳过）
+    expect(result.stats.totalEntries).toBeGreaterThan(0)
+  })
 })
 
 describe('renderExpand', () => {

package/src/__tests__/roots.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest'
 import { tmpdir } from 'node:os'
-import { mkdtemp, mkdir, readdir, writeFile, rm } from 'node:fs/promises'
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises'
 import { join, dirname } from 'node:path'
 import {
   resolveSessionRoots,
@@ -9,7 +9,7 @@ import {
   type SessionRootSignals,
 } from '../discovery/roots.js'
 import { buildFamilyFromFs } from '../discovery/subagents.js'
-import { REAL_AGENT_DIR, HAS_E6, HAS_REAL_AGENT_DIR, HAS_REAL_SUBAGENTS_DIR, REAL_DATA_TIMEOUT_MS } from './real-data.js'
+import { FIX_E6 } from './fixtures.js'
 
 // ============================================================
 // A3（ext-simplify-04 U4）：listMainSessions/listSubagentSessions 薄包装已删除，
@@ -35,7 +35,7 @@ async function writeJsonl(path: string, content = '{"type":"session","id":"x"}\n
   await writeFile(path, content)
 }
 
-/** 真实形态的 cwd 编码目录名（encodeCwd：`--` 开头 `--` 结尾，实证见 real-data.ts） */
+/** 真实形态的 cwd 编码目录名（encodeCwd：`--` 开头 `--` 结尾） */
 const SLUG = '--Users-foo--'
 
 describe('main 根过滤（原 listMainSessions 等价式，A3 退役后保覆盖）', () => {
@@ -100,8 +100,18 @@ describe('main 根过滤（原 listMainSessions 等价式，A3 退役后保覆
     await expect(mainSessionFiles(join(dir, 'no-such-dir'))).resolves.toEqual([])
   })
 
-  it.skipIf(!HAS_E6)('真实数据：扫描 ~/.pi/agent，含 019e6c96，不含 .finalized 与 wf-', async () => {
-    const result = await mainSessionFiles(REAL_AGENT_DIR)
+  it('扫描 sessions/：含目标 session，排除 .finalized 与 workflow-state 目录（019e6c96 锚）', async () => {
+    // wf-state 文件（wf-*.jsonl）经 workflow-state 目录跳过排除——main 根无独立的
+    // wf- 文件名前缀过滤，slug 顶层放 wf-*.jsonl 会被收进候选集（该形态不在真实
+    // 落盘布局中出现：wf-state 恒在 workflow-state/ 目录内）
+    const slug = '--Users-foo--'
+    const slugDir = join(dir, 'sessions', slug)
+    await mkdir(join(slugDir, 'workflow-state'), { recursive: true })
+    await writeFile(join(slugDir, `${FIX_E6}.jsonl`), `{"type":"session","id":"${FIX_E6}"}\n`)
+    await writeFile(join(slugDir, 'b.jsonl.finalized'), '{"type":"session","id":"b"}\n')
+    await writeFile(join(slugDir, 'workflow-state', 'wf-inner.jsonl'), '{"v":"wf-run-v1"}\n')
+
+    const result = await mainSessionFiles(dir)
     expect(result.length).toBeGreaterThan(0)
     // 含目标 session
     expect(result.some((m) => m.path.includes('019e6c96'))).toBe(true)
@@ -109,11 +119,9 @@ describe('main 根过滤（原 listMainSessions 等价式，A3 退役后保覆
     expect(result.every((m) => !m.path.endsWith('.finalized'))).toBe(true)
     // 排除 workflow-state 目录
     expect(result.every((m) => !m.path.includes('workflow-state'))).toBe(true)
-    // 排除 wf- 前缀文件名
-    expect(result.every((m) => !m.path.split('/').pop()!.startsWith('wf-'))).toBe(true)
     // mtime/size 真实
     expect(result.every((m) => m.mtime > 0 && m.size > 0)).toBe(true)
-  }, REAL_DATA_TIMEOUT_MS)
+  })
 })
 
 describe('subagent 根选择（原 listSubagentSessions 等价式，A3 退役后保覆盖）', () => {
@@ -156,12 +164,6 @@ describe('subagent 根选择（原 listSubagentSessions 等价式，A3 退役后
   it('无 subagents 目录返回 []，不抛错', async () => {
     await expect(subagentSessionFiles(dir)).resolves.toEqual([])
   })
-
-  it.skipIf(!HAS_REAL_SUBAGENTS_DIR)('真实数据：扫描 ~/.pi/agent/subagents 返回非空', async () => {
-    const result = await subagentSessionFiles(REAL_AGENT_DIR)
-    expect(result.length).toBeGreaterThan(0)
-    expect(result.every((m) => !m.path.endsWith('.finalized'))).toBe(true)
-  }, REAL_DATA_TIMEOUT_MS)
 })
 
 // ============================================================
@@ -320,26 +322,22 @@ describe('resolveSessionRoots', () => {
     await expect(resolveSessionRoots({ agentDir: '' })).resolves.toEqual([])
   })
 
-  it.skipIf(!HAS_REAL_AGENT_DIR)(
-    '§11.2 真实路径集合回归：encodeCwd 判据在真实 sessions 子目录上自洽，剥层分支被真实数据覆盖',
-    async () => {
-      const sessionsDir = join(REAL_AGENT_DIR, 'sessions')
-      const entries = await readdir(sessionsDir, { withFileTypes: true })
-      const dirs = entries.filter((e) => e.isDirectory())
-      expect(dirs.length).toBeGreaterThan(0)
-      let encodeCwdCount = 0
-      for (const d of dirs) {
-        const asLive = join(sessionsDir, d.name)
-        const matchesShape = d.name.startsWith('--') && d.name.endsWith('--')
-        // 判据自洽：匹配形态 → 剥层到父目录；不匹配（如 permission-forwarding/）→ 取自身
-        expect(normalizeLiveSessionDir(asLive)).toBe(matchesShape ? sessionsDir : asLive)
-        if (matchesShape) encodeCwdCount++
-      }
-      // 真实集合以 encodeCwd 目录为主体——剥层分支确实被真实数据覆盖
-      expect(encodeCwdCount).toBeGreaterThan(0)
-    },
-    30000,
-  )
+  it('encodeCwd 判据自洽：--xx-- 形态子目录剥层到 sessions 根，普通名子目录取自身', async () => {
+    // 两种目录形态各造一个：encodeCwd 编码目录（剥层分支）与普通目录名（取自身分支）
+    const tmp = await mkdtemp(join(tmpdir(), 'roots-encode-'))
+    try {
+      const sessionsDir = join(tmp, 'agent', 'sessions')
+      const encoded = join(sessionsDir, '--Users-foo--')
+      const plain = join(sessionsDir, 'permission-forwarding')
+      await writeJsonl(join(encoded, 'a.jsonl'))
+      await writeJsonl(join(plain, 'p.jsonl'))
+      // 判据自洽：匹配 encodeCwd 形态 → 剥层到父目录；不匹配（如 permission-forwarding/）→ 取自身
+      expect(normalizeLiveSessionDir(encoded)).toBe(sessionsDir)
+      expect(normalizeLiveSessionDir(plain)).toBe(plain)
+    } finally {
+      await rm(tmp, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+    }
+  })
 })
 
 describe('buildFamilyFromFs not-found 文案（U1 并入：列实际扫描候选根）', () => {