@zhushanwen/pi-session-reader 0.5.1 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-session-reader",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "type": "module",
   "main": "index.ts",
   "xyz-agent": {
@@ -15,10 +15,13 @@
   "keywords": [
     "pi-package"
   ],
+  "dependencies": {
+    "@zhushanwen/pi-ext-guards": "0.4.0"
+  },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.9",
     "vitest": "^4.1.8",
-    "@zhushanwen/subagent-core": "0.10.0"
+    "@zhushanwen/subagent-core": "0.10.1"
   },
   "files": [
     "index.ts",

package/src/__tests__/cross-package-subagent-core.test.ts

@@ -213,13 +213,14 @@ describe('跨包集成：subagent-core E1 落标 manifest → session-reader res
     return childFile
   }
 
-  /** 种「崩溃前主文件末条序列」：register（running+sync）→ 轮终（running+resumable+
-   *  result 全文 + sessionFile）——成功成员崩溃时的真实末条形态。 */
+  /** 种「崩溃前主文件末条序列」：register（running+sync）→ 轮终（idle + result
+   *  全文 + sessionFile）——[U4/D4] 翻边后成功成员崩溃时的真实末条形态（U5 前的
+   *  running+resumable 桥接形态已随字段退役消亡）。 */
   function seedRoundTerminalEntries(m: MemberSeed, childFile: string): void {
     const store = makeSeedStore()
     store.reportSubagentRecord(memberRecord({ id: m.id, sessionFile: childFile, model: m.model }))
     store.reportSubagentRecord(
-      memberRecord({ id: m.id, sessionFile: childFile, model: m.model, resumable: true, result: m.resultText }),
+      memberRecord({ id: m.id, sessionFile: childFile, model: m.model, status: 'idle', result: m.resultText }),
     )
   }
 
@@ -280,7 +281,7 @@ describe('跨包集成：subagent-core E1 落标 manifest → session-reader res
     })
 
     // session-reader 侧：sa- id 反查（v1 此处报「无匹配 record」——manifest 惰性不落盘）
-    const r = await handleSessionRead({ action: 'result', session: 'sa-cross-1' }, agentDir)
+    const r = await handleSessionRead({ action: 'result', session: 'sa-cross-1' }, { agentDir })
     // 同源语义：跨 assistant message "\n\n" join、thinking 块排除——与 record.result 逐字节一致
     expect(r.content[0]?.text).toBe(resultText)
     const d = r.details as {
@@ -304,7 +305,7 @@ describe('跨包集成：subagent-core E1 落标 manifest → session-reader res
     ]
     await driveSyncBatchRecovery(members)
 
-    const r = await handleSessionRead({ action: 'result', session: 'sa-cross-a,sa-cross-b' }, agentDir)
+    const r = await handleSessionRead({ action: 'result', session: 'sa-cross-a,sa-cross-b' }, { agentDir })
     const text = r.content[0]?.text ?? ''
     expect(text).toContain('[1/2] sa-cross-a')
     expect(text).toContain('[2/2] sa-cross-b')

package/src/__tests__/family.test.ts

@@ -107,13 +107,6 @@ describe('buildFamilyIndex', () => {
     expect(index.childrenOf.get('aaa')?.[0].sessionId).toBe('bbb')
   })
 
-  it('parentSession 直接是 sessionId 也兼容（简化 fixture）', () => {
-    const headers = [header('aaa'), header('bbb', { parentSession: 'aaa' })]
-    const index = buildFamilyIndex(headers, [], new Map())
-
-    expect(index.childrenOf.get('aaa')?.[0].sessionId).toBe('bbb')
-  })
-
   it('parentSession 反查不到父 → 该 entry 不进 childrenOf（不报错）', () => {
     const headers = [header('bbb', { parentSession: '/missing.jsonl' })]
     const index = buildFamilyIndex(headers, [], new Map())

package/src/__tests__/find.test.ts

@@ -133,7 +133,7 @@ async function makeSubagentSession(
 describe('findSessions', () => {
   let agentDir: string
   let slugDir: string
-  /** subagent fixture 目录（模拟 subagents/<cwd编码>/sessions/ 结构，roots.listSubagentSessions 扫描路径） */
+  /** subagent fixture 目录（模拟 subagents/<cwd编码>/sessions/ 结构，resolveSessionRoots [subagent] 根扫描路径） */
   let saDir: string
 
   let recordsDir: string
@@ -705,8 +705,8 @@ describe('u11 标题元数据（metadataProvider 注入，§6.6）', () => {
     await mkdir(legacyDir, { recursive: true })
     const provider = vi.fn(async (dir: string) =>
       dir === flatMain
-        ? [{ path: pathA, id: 'dup-id-0001', cwd: '/demo', name: '旧标题', modified: 1000 }]
-        : [{ path: pathA, id: 'dup-id-0001', cwd: '/demo', name: '新标题', modified: 2000 }],
+        ? [{ path: pathA, id: 'dup-id-0001', cwd: '/demo', name: '旧标题', modified: new Date(1000) }]
+        : [{ path: pathA, id: 'dup-id-0001', cwd: '/demo', name: '新标题', modified: new Date(2000) }],
     )
     const { matches } = await findSessions('新标题', agentDir, { metadataProvider: provider })
     expect(provider).toHaveBeenCalledTimes(2) // 两个平铺存在的根各一次
@@ -753,8 +753,8 @@ describe('u11 标题元数据（metadataProvider 注入，§6.6）', () => {
     const provider = vi.fn(async (dir: string) =>
       dir === flatMain
         ? [
-            { path: pNew1, id: 'recent-new-1', cwd: '/demo', name: '最新标题一', modified: (base + 300) * 1000 },
-            { path: pNew2, id: 'recent-new-2', cwd: '/demo', name: '最新标题二', modified: (base + 200) * 1000 },
+            { path: pNew1, id: 'recent-new-1', cwd: '/demo', name: '最新标题一', modified: new Date((base + 300) * 1000) },
+            { path: pNew2, id: 'recent-new-2', cwd: '/demo', name: '最新标题二', modified: new Date((base + 200) * 1000) },
           ]
         : [],
     )

package/src/__tests__/real-data.ts

@@ -22,7 +22,7 @@ export const REAL_AGENT_DIR = '/Users/zhushanwen/.pi/agent'
  * 这类用例遍历本机 ~/.pi/agent 全量会话语料（实测 4600+ 文件），空载单用例已需 6-10s；
  * 38 包并行全量测试时 CPU/IO 争抢可降速 3-4 倍，30s 标定必假红。90s ≈ 空载 9 倍余量，
  * 仍能兜住真正的挂死。仅用于遍历全量语料的用例（findSessions / buildFamilyFromFs /
- * listMainSessions 等）；读已知单文件的用例不需要放宽。
+ * resolveSessionRoots 等）；读已知单文件的用例不需要放宽。
  */
 export const REAL_DATA_TIMEOUT_MS = 90_000
 

package/src/__tests__/render.test.ts

@@ -90,6 +90,8 @@ describe('renderOutline', () => {
     // thinking 'secret'(6B) + toolResult 'output'(6B)
     expect(b.omittedBytes).toBe(12)
     expect(result.truncated).toBeUndefined()
+    // E7 行渲染统一：lines 随结果返回，与 turns 一一对应（预算度量 = 展示行同一份）
+    expect(result.lines).toEqual(['T000 · do something · bash×2,read×2 · → sure · [12B omitted]'])
   })
 
   it('2a. 降级：单行 toolSummary 过长超 perTurnBudget → 砍 toolSummary，保 userBrief 骨架', () => {
@@ -108,6 +110,25 @@ describe('renderOutline', () => {
       expect(b.toolSummary).toBe('') // 被砍（降级）
       expect(b.userBrief).toBe('u'.repeat(10)) // 骨架保留
     }
+    // E7：降级后的渲染行（骨架形态）与 briefs 字段同步——行内无 → 结论段、无工具聚合段
+    expect(result.lines).toHaveLength(3)
+    expect(result.lines).toEqual(['T000 · uuuuuuuuuu', 'T001 · uuuuuuuuuu', 'T002 · uuuuuuuuuu'])
+    expect(result.truncated).toBeUndefined()
+  })
+
+  it('2b. 降级（砍 assistantBrief 档）：行内 → 结论段消失、toolSummary 保留，与改前语义一致', () => {
+    // budget=20 → perTurnCharBudget=80；level 0 行 = T000 · u*10 · bash×2 · → a*80… ≈112 > 80
+    // → 砍 assistantBrief 后 ≈26 ≤ 80 停（S3：该档形态与改前 handler 侧渲染降级后 briefs 等价）
+    const t = turn(
+      0,
+      [uEntry('U', 'u'.repeat(10)), aEntry('A', 'a'.repeat(100), [{ name: 'bash' }, { name: 'bash' }])],
+      { userEntry: uEntry('U', 'u'.repeat(10)) },
+    )
+    const result = renderOutline([t], emptyTree(), { budget: 20 })
+
+    expect(result.turns[0].assistantBrief).toBe('') // 被砍
+    expect(result.turns[0].toolSummary).toBe('bash×2') // 保留
+    expect(result.lines).toEqual(['T000 · uuuuuuuuuu · bash×2'])
     expect(result.truncated).toBeUndefined()
   })
 
@@ -122,6 +143,8 @@ describe('renderOutline', () => {
 
     expect(result.truncated).toBe(3)
     expect(result.turns).toHaveLength(2)
+    // E7：lines 与 turns 同步截短（truncateToTotalBudget 双数组一致）
+    expect(result.lines).toHaveLength(2)
   })
 
   it('4. toolSummary 聚合：同名计数 ×N，不同名逗号分隔', () => {
@@ -168,6 +191,19 @@ describe('renderOutline', () => {
     expect(withoutBranches.turns[0].branch).toBeUndefined()
   })
 
+  it('7b. E7 旁支标记统一：渲染行 `[旁支 N entries]`（N = 该 forkPoint 下旁支子树 entry 数）', () => {
+    // branches: U → 3 entries 旁支子树（E7/D3：outline 与 export 两条路径共用此形态）
+    const tree: TreeView = { leafPath: ['U'], branches: new Map([['U', 3]]), orphans: [] }
+    const userEntry = uEntry('U', 'hi')
+    const turns = [turn(0, [userEntry], { userEntry })]
+
+    const result = renderOutline(turns, tree, { allBranches: true })
+    expect(result.lines).toEqual(['T000 · hi · [旁支 3 entries]'])
+    // branchSize 缺失（allBranches:false）不标旁支
+    const noBranch = renderOutline(turns, tree, { allBranches: false })
+    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)
@@ -310,7 +346,6 @@ describe('renderDetail', () => {
     expect(summary.summary).toMatch(/^read: f\.ts \(\d+KB\)$/)
     expect(summary.totalLines).toBe(4)
     expect(summary.headLines).toContain('line1')
-    expect(summary.fullEntry.message?.role).toBe('toolResult')
 
     // includeToolResult 全文：返回原 Entry
     const full = renderDetail([t], { includeToolResult: true })

package/src/__tests__/result.test.ts

@@ -2,11 +2,8 @@ import { describe, it, expect, beforeEach, afterEach } from 'vitest'
 import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
-import {
-  handleSessionRead,
-  extractFinalAssistantText,
-  type SessionReadParams,
-} from '../tool-handler.js'
+import { handleSessionRead, type SessionReadParams } from '../tool-handler.js'
+import { extractFinalAssistantText } from '../result-action.js'
 
 /**
  * U6 result action 测试（design subagent-sync-collect §3.1.3 + impl-plan U6）。
@@ -152,7 +149,7 @@ describe('result action（U6）', () => {
         assistantEntry(`${realId}-a2`, [{ type: 'text', text: 'second part' }]),
       ],
     })
-    const r = await handleSessionRead({ action: 'result', session: 'sa-one' }, dir)
+    const r = await handleSessionRead({ action: 'result', session: 'sa-one' }, { agentDir: dir })
     // 与 record.result 同源：全部 assistant 正文非空过滤 '\n\n' join，无任何包装
     expect(r.content[0]?.text).toBe('FINAL RESULT\n\nsecond part')
     const d = r.details as {
@@ -184,7 +181,7 @@ describe('result action（U6）', () => {
     }
     const r = await handleSessionRead(
       { action: 'result', session: 'sa-b1,sa-b2,sa-b3' },
-      dir,
+      { agentDir: dir },
     )
     const text = r.content[0]?.text ?? ''
     expect(text).toContain('[1/3] sa-b1')
@@ -207,10 +204,10 @@ describe('result action（U6）', () => {
   it('3. 批量 >10：11 id 拒绝，报错含上限 10 与分批指引（解析先于 fs，无需 fixture）', async () => {
     const list = Array.from({ length: 11 }, (_, i) => `sa-x${i}`).join(',')
     await expect(
-      handleSessionRead({ action: 'result', session: list }, dir),
+      handleSessionRead({ action: 'result', session: list }, { agentDir: dir }),
     ).rejects.toThrow(/最多 10 个/)
     try {
-      await handleSessionRead({ action: 'result', session: list }, dir)
+      await handleSessionRead({ action: 'result', session: list }, { agentDir: dir })
     } catch (e) {
       const msg = (e as Error).message
       expect(msg).toContain('11')
@@ -226,7 +223,7 @@ describe('result action（U6）', () => {
       realId,
       entries: [assistantEntry(`${realId}-a1`, [{ type: 'text', text: longText }])],
     })
-    const r = await handleSessionRead({ action: 'result', session: 'sa-long' }, dir)
+    const r = await handleSessionRead({ action: 'result', session: 'sa-long' }, { agentDir: dir })
     const text = r.content[0]?.text ?? ''
     // 截断到 8000：第 8001 个 x 不在正文，但提示行给出计数
     expect(text.startsWith('x'.repeat(8000))).toBe(true)
@@ -249,7 +246,7 @@ describe('result action（U6）', () => {
     })
     const cut = await handleSessionRead(
       { action: 'result', session: 'sa-lim', limit: 5 },
-      dir,
+      { agentDir: dir },
     )
     expect(cut.content[0]?.text).toBe(
       'abcde\n\n[truncated 5 of 10 chars — full text: read ' +
@@ -258,31 +255,31 @@ describe('result action（U6）', () => {
     )
     const exact = await handleSessionRead(
       { action: 'result', session: 'sa-lim', limit: 10 },
-      dir,
+      { agentDir: dir },
     )
     expect(exact.content[0]?.text).toBe('abcdefghij')
     const d = exact.details as { truncated: boolean }
     expect(d.truncated).toBe(false)
     for (const bad of [0, -1, Number.NaN]) {
       await expect(
-        handleSessionRead({ action: 'result', session: 'sa-lim', limit: bad }, dir),
+        handleSessionRead({ action: 'result', session: 'sa-lim', limit: bad }, { agentDir: dir }),
       ).rejects.toThrow(/limit.*无效/)
     }
   })
 
   it('6. 不存在 id：sa-id 无 manifest → 无匹配 record；uuid 片段零匹配 → 无匹配 session', async () => {
     await expect(
-      handleSessionRead({ action: 'result', session: 'sa-nonexist-9999' }, dir),
+      handleSessionRead({ action: 'result', session: 'sa-nonexist-9999' }, { agentDir: dir }),
     ).rejects.toThrow(/无匹配 record/)
     try {
-      await handleSessionRead({ action: 'result', session: 'sa-nonexist-9999' }, dir)
+      await handleSessionRead({ action: 'result', session: 'sa-nonexist-9999' }, { agentDir: dir })
     } catch (e) {
       const msg = (e as Error).message
       expect(msg).toContain('👉')
       expect(msg).toContain('family')
     }
     await expect(
-      handleSessionRead({ action: 'result', session: 'zzz-nonexistent-9q8x2' }, dir),
+      handleSessionRead({ action: 'result', session: 'zzz-nonexistent-9q8x2' }, { agentDir: dir }),
     ).rejects.toThrow(/无匹配 session/)
   })
 
@@ -293,10 +290,10 @@ describe('result action（U6）', () => {
       sessionFileExists: false,
     })
     await expect(
-      handleSessionRead({ action: 'result', session: 'sa-flush' }, dir),
+      handleSessionRead({ action: 'result', session: 'sa-flush' }, { agentDir: dir }),
     ).rejects.toThrow(/session 文件不存在/)
     try {
-      await handleSessionRead({ action: 'result', session: 'sa-flush' }, dir)
+      await handleSessionRead({ action: 'result', session: 'sa-flush' }, { agentDir: dir })
     } catch (e) {
       const msg = (e as Error).message
       expect(msg).toContain('未写入')
@@ -310,10 +307,10 @@ describe('result action（U6）', () => {
       realId: '019e6c96-0000-0000-0000-000000000a01',
     })
     await expect(
-      handleSessionRead({ action: 'result', session: 'sa-empty' }, dir),
+      handleSessionRead({ action: 'result', session: 'sa-empty' }, { agentDir: dir }),
     ).rejects.toThrow(/尚无 assistant 输出/)
     try {
-      await handleSessionRead({ action: 'result', session: 'sa-empty' }, dir)
+      await handleSessionRead({ action: 'result', session: 'sa-empty' }, { agentDir: dir })
     } catch (e) {
       const msg = (e as Error).message
       expect(msg).toContain('sa-empty')
@@ -323,10 +320,10 @@ describe('result action（U6）', () => {
 
   it('9. 参数防御：缺 session / 空条目（尾逗号）均报错', async () => {
     await expect(
-      handleSessionRead({ action: 'result' } as SessionReadParams, dir),
+      handleSessionRead({ action: 'result' } as SessionReadParams, { agentDir: dir }),
     ).rejects.toThrow(/需要参数 "session"/)
     await expect(
-      handleSessionRead({ action: 'result', session: 'sa-a,' }, dir),
+      handleSessionRead({ action: 'result', session: 'sa-a,' }, { agentDir: dir }),
     ).rejects.toThrow(/空条目/)
   })
 
@@ -334,7 +331,7 @@ describe('result action（U6）', () => {
     await expect(
       handleSessionRead(
         { action: 'bogus' } as unknown as SessionReadParams,
-        dir,
+        { agentDir: dir },
       ),
     ).rejects.toThrow(/find\/family\/outline\/expand\/detail\/search\/export\/extract\/workflow\/result\/doctor/)
   })

package/src/__tests__/roots.test.ts

@@ -1,10 +1,8 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
 import { tmpdir } from 'node:os'
 import { mkdtemp, mkdir, readdir, writeFile, rm } from 'node:fs/promises'
 import { join, dirname } from 'node:path'
 import {
-  listMainSessions,
-  listSubagentSessions,
   resolveSessionRoots,
   normalizeLiveSessionDir,
   type SessionRoot,
@@ -13,6 +11,24 @@ import {
 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'
 
+// ============================================================
+// A3（ext-simplify-04 U4）：listMainSessions/listSubagentSessions 薄包装已删除，
+// subagents.ts 直调 resolveSessionRoots+filter。以下 describe 用同一等价式作入口，
+// 保过滤语义覆盖（.finalized 排除 / workflow-state 跳过 / 递归 / 根选择 / 空目录容错）。
+// ============================================================
+
+/** 原 listMainSessions 等价式：agentDir 信号包下未去重 main 根的文件并集 */
+async function mainSessionFiles(agentDir: string) {
+  return (await resolveSessionRoots({ agentDir }))
+    .filter((r) => r.source === 'main' && r.dedupedInto === undefined)
+    .flatMap((r) => r.files)
+}
+
+/** 原 listSubagentSessions 等价式：agentDir 信号包下 [subagent] 根文件集 */
+async function subagentSessionFiles(agentDir: string) {
+  return (await resolveSessionRoots({ agentDir })).find((r) => r.kind === 'subagent')?.files ?? []
+}
+
 /** 写 .jsonl fixture（父目录不存在则自建），内容默认合法 session header */
 async function writeJsonl(path: string, content = '{"type":"session","id":"x"}\n') {
   await mkdir(dirname(path), { recursive: true })
@@ -22,7 +38,7 @@ async function writeJsonl(path: string, content = '{"type":"session","id":"x"}\n
 /** 真实形态的 cwd 编码目录名（encodeCwd：`--` 开头 `--` 结尾，实证见 real-data.ts） */
 const SLUG = '--Users-foo--'
 
-describe('listMainSessions', () => {
+describe('main 根过滤（原 listMainSessions 等价式，A3 退役后保覆盖）', () => {
   let dir: string
 
   beforeEach(async () => {
@@ -38,7 +54,7 @@ describe('listMainSessions', () => {
     await writeFile(join(dir, 'sessions', slug, 'a.jsonl'), '{"type":"session","id":"a"}\n')
     await writeFile(join(dir, 'sessions', slug, 'b.jsonl.finalized'), '{"type":"session","id":"b"}\n')
 
-    const result = await listMainSessions(dir)
+    const result = await mainSessionFiles(dir)
     expect(result).toHaveLength(1)
     expect(result[0].path.endsWith('a.jsonl')).toBe(true)
     expect(result[0].path.endsWith('.finalized')).toBe(false)
@@ -54,7 +70,7 @@ describe('listMainSessions', () => {
     // 同 slug 直接层也放一个，验证同一 slug 下平铺与嵌套并存
     await writeFile(join(dir, 'sessions', 'slug', 'top.jsonl'), '{}\n')
 
-    const result = await listMainSessions(dir)
+    const result = await mainSessionFiles(dir)
     const names = result.map((m) => m.path.split('/').pop()!)
     expect(names).toContain('d.jsonl')
     expect(names).toContain('top.jsonl')
@@ -70,22 +86,22 @@ describe('listMainSessions', () => {
       '{"v":"wf-run-v1"}\n',
     )
 
-    const result = await listMainSessions(dir)
+    const result = await mainSessionFiles(dir)
     expect(result).toHaveLength(1)
     expect(result[0].path.endsWith('real.jsonl')).toBe(true)
     expect(result.every((m) => !m.path.includes('workflow-state'))).toBe(true)
   })
 
   it('空 agentDir（无 sessions 目录）返回 []，不抛错', async () => {
-    await expect(listMainSessions(dir)).resolves.toEqual([])
+    await expect(mainSessionFiles(dir)).resolves.toEqual([])
   })
 
   it('不存在的 agentDir 返回 []，不抛错', async () => {
-    await expect(listMainSessions(join(dir, 'no-such-dir'))).resolves.toEqual([])
+    await expect(mainSessionFiles(join(dir, 'no-such-dir'))).resolves.toEqual([])
   })
 
   it.skipIf(!HAS_E6)('真实数据：扫描 ~/.pi/agent，含 019e6c96，不含 .finalized 与 wf-', async () => {
-    const result = await listMainSessions(REAL_AGENT_DIR)
+    const result = await mainSessionFiles(REAL_AGENT_DIR)
     expect(result.length).toBeGreaterThan(0)
     // 含目标 session
     expect(result.some((m) => m.path.includes('019e6c96'))).toBe(true)
@@ -100,7 +116,7 @@ describe('listMainSessions', () => {
   }, REAL_DATA_TIMEOUT_MS)
 })
 
-describe('listSubagentSessions', () => {
+describe('subagent 根选择（原 listSubagentSessions 等价式，A3 退役后保覆盖）', () => {
   let dir: string
 
   beforeEach(async () => {
@@ -119,7 +135,7 @@ describe('listSubagentSessions', () => {
       '{"type":"session"}\n',
     )
 
-    const result = await listSubagentSessions(dir)
+    const result = await subagentSessionFiles(dir)
     expect(result).toHaveLength(1)
     expect(result[0].path.endsWith('c.jsonl')).toBe(true)
     expect(result[0].path.endsWith('.finalized')).toBe(false)
@@ -132,17 +148,17 @@ describe('listSubagentSessions', () => {
     await writeFile(join(dir, 'subagents', slug, 'records', 'manifest.json'), '{}\n')
     await writeFile(join(dir, 'subagents', slug, 'sessions', 'sub.jsonl'), '{"type":"session"}\n')
 
-    const result = await listSubagentSessions(dir)
+    const result = await subagentSessionFiles(dir)
     expect(result).toHaveLength(1)
     expect(result[0].path.endsWith('sub.jsonl')).toBe(true)
   })
 
   it('无 subagents 目录返回 []，不抛错', async () => {
-    await expect(listSubagentSessions(dir)).resolves.toEqual([])
+    await expect(subagentSessionFiles(dir)).resolves.toEqual([])
   })
 
   it.skipIf(!HAS_REAL_SUBAGENTS_DIR)('真实数据：扫描 ~/.pi/agent/subagents 返回非空', async () => {
-    const result = await listSubagentSessions(REAL_AGENT_DIR)
+    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)
@@ -364,11 +380,11 @@ describe('buildFamilyFromFs not-found 文案（U1 并入：列实际扫描候选
 
 // ============================================================
 // u8 追加：resolveSessionRoots options（doctor 统一数据源，design §6.3「同一数据源
-// 两处渲染，不重复实现探测」——subagent 扫描模式与进程内缓存经 options 由调用方
-// 驱动，本模块不内置 TTL/mtime 失效逻辑）
+// 两处渲染，不重复实现探测」——subagent 扫描模式经 options 由调用方驱动；原 u8 的
+// 注入式缓存面已删除，ext-simplify-04 U3，每次调用实扫）
 // ============================================================
 
-describe('resolveSessionRoots options（u8：subagents 模式 + 注入式缓存）', () => {
+describe('resolveSessionRoots options（u8：subagents 模式）', () => {
   /** 最小 fixture：default 根 1 文件 + subagent 根 1 文件（legacy 不存在） */
   async function buildMinimalFixture(): Promise<{ tmp: string; agentDir: string }> {
     const tmp = await mkdtemp(join(tmpdir(), 'roots-opts-'))
@@ -413,71 +429,21 @@ describe('resolveSessionRoots options（u8：subagents 模式 + 注入式缓存
     }
   })
 
-  it('cache：未命中实扫后 set 回写；命中以缓存值构造根（cached 标记、files 空、不再回写）', async () => {
+  it('重复调用每次实扫（无缓存）：两次结果独立完整，files 恒非空实扫值', async () => {
+    // 原三个 cache 用例（set 回写 / 命中优先 / stat × cache）随缓存注入面删除
+    // （ext-simplify-04 U3）；本用例钉死删除后契约——不存在任何缓存层
     const { tmp, agentDir } = await buildMinimalFixture()
     try {
-      const store = new Map<string, { exists: boolean; fileCount: number; scanMs: number }>()
-      const setSpy = vi.fn((key: string, value: { exists: boolean; fileCount: number; scanMs: number }) => {
-        store.set(key, value)
-      })
-      const getSpy = vi.fn(async (key: string) => store.get(key))
-      const cache = { get: getSpy, set: setSpy }
-
-      // 首扫：get 未命中 → 实扫 → 逐非去重根 set（default + legacy + subagent = 3）
-      const first = await resolveSessionRoots({ agentDir }, { cache })
-      const firstDef = first.find((r) => r.kind === 'default')!
-      expect(firstDef.cached).toBeUndefined()
-      expect(firstDef.fileCount).toBe(1)
-      expect(getSpy).toHaveBeenCalled()
-      expect(setSpy).toHaveBeenCalledTimes(3)
-
-      // 二扫：命中 → 缓存值即数据源，无新回写
-      const second = await resolveSessionRoots({ agentDir }, { cache })
-      const secondDef = second.find((r) => r.kind === 'default')!
-      expect(secondDef.cached).toBe(true)
-      expect(secondDef.fileCount).toBe(1)
-      expect(secondDef.files).toEqual([])
-      expect(setSpy).toHaveBeenCalledTimes(3)
-    } finally {
-      await rm(tmp, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
-    }
-  })
-
-  it('cache 命中值优先于磁盘（roots 不旁路缓存实扫——TTL/mtime 失效语义全在缓存实现侧）', async () => {
-    const { tmp, agentDir } = await buildMinimalFixture()
-    try {
-      const setSpy = vi.fn()
-      const cache = {
-        get: async () => ({ exists: true, fileCount: 99, scanMs: 7 }),
-        set: setSpy,
+      const first = await resolveSessionRoots({ agentDir })
+      const second = await resolveSessionRoots({ agentDir })
+      for (const roots of [first, second]) {
+        const def = roots.find((r) => r.kind === 'default')!
+        expect(def.fileCount).toBe(1)
+        expect(def.files).toHaveLength(1)
+        const sub = roots.find((r) => r.kind === 'subagent')!
+        expect(sub.fileCount).toBe(1)
+        expect(sub.files).toHaveLength(1)
       }
-      const roots = await resolveSessionRoots({ agentDir }, { cache })
-      const def = roots.find((r) => r.kind === 'default')!
-      expect(def.fileCount).toBe(99)
-      expect(def.scanMs).toBe(7)
-      expect(def.cached).toBe(true)
-      expect(def.files).toEqual([])
-      expect(setSpy).not.toHaveBeenCalled() // 命中不回写
-    } finally {
-      await rm(tmp, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
-    }
-  })
-
-  it("stat × cache 组合：'stat' 的 subagent 根不产缓存条目（缓存只服务扫盘贵的根）", async () => {
-    const { tmp, agentDir } = await buildMinimalFixture()
-    try {
-      const setKeys: string[] = []
-      await resolveSessionRoots({ agentDir }, {
-        subagents: 'stat',
-        cache: {
-          get: async () => undefined,
-          set: (key) => {
-            setKeys.push(key)
-          },
-        },
-      })
-      expect(setKeys).not.toContain(join(agentDir, 'subagents'))
-      expect(setKeys).toContain(join(agentDir, 'sessions'))
     } finally {
       await rm(tmp, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
     }

package/src/__tests__/session-command.test.ts

@@ -3,6 +3,7 @@ import { tmpdir } from 'node:os'
 import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises'
 import { join } from 'node:path'
 import { createSessionCommand } from '../tui/session-command.js'
+import { SessionManager } from '@earendil-works/pi-coding-agent'
 import type { ExtensionCommandContext } from '@earendil-works/pi-coding-agent'
 
 /**
@@ -117,6 +118,16 @@ describe('createSessionCommand - getArgumentCompletions', () => {
     const cmd = createSessionCommand(() => cwdSessionDir)
     expect(await cmd.getArgumentCompletions('deadbeef')).toBeNull()
   })
+
+  it('空 getCwdSessionDir → 秒回 null，不调 listAll（A1：无 live session 上下文不触发全盘分支）', async () => {
+    // mock 拦断言用：guard 失效误调 listAll('') 时 pi 会走真实全盘扫描（实测 3488 项 / ~8s），
+    // mock 掉保证失败态也是秒级红灯
+    const listAllSpy = vi.spyOn(SessionManager, 'listAll').mockResolvedValue([])
+    const cmd = createSessionCommand(() => '')
+    expect(await cmd.getArgumentCompletions('')).toBeNull()
+    expect(listAllSpy).not.toHaveBeenCalled()
+    listAllSpy.mockRestore()
+  })
 })
 
 describe('createSessionCommand - handler select 流程', () => {
@@ -175,6 +186,18 @@ describe('createSessionCommand - handler select 流程', () => {
     expect(setEditorText).not.toHaveBeenCalled()
   })
 
+  it('空 getCwdSessionDir → 按零匹配 notify，不调 listAll（A1：handler 侧同款空串 guard）', async () => {
+    const listAllSpy = vi.spyOn(SessionManager, 'listAll').mockResolvedValue([])
+    const cmd = createSessionCommand(() => '')
+    const { ctx, select, notify, setEditorText } = makeFakeCtx()
+    await cmd.handler('', ctx)
+    expect(notify).toHaveBeenCalledWith('未找到匹配的 session。', 'warning')
+    expect(select).not.toHaveBeenCalled()
+    expect(setEditorText).not.toHaveBeenCalled()
+    expect(listAllSpy).not.toHaveBeenCalled()
+    listAllSpy.mockRestore()
+  })
+
   it('MF-2 回归：同 cwd 同预览同 age 桶 → label 带短 uuid 后缀消歧，选第 2 条插第 2 条 uuid', async () => {
     // 两 session：相同首消息 + 相同 timestamp（同 age 桶）→ toCandidate label 完全相同
     const ID1 = '019e6c96-0a0c-74b8-a73f-d1854d88e2a7'

package/src/__tests__/subagents.test.ts

@@ -228,9 +228,10 @@ describe('buildFamilyFromFs - fixture', () => {
     expect(sub!.rootSessionId).toBe(FORK)
     expect(sub!.slug).toBe('test-sub')
     expect(sub!.cleanedUp).toBe(false)
-    // enrich：fileName/cwd 已补真实值（非 M1 占位空串）
-    expect(sub!.fileName.length).toBeGreaterThan(0)
-    expect(sub!.cwd).toBe('/proj/--fork-cwd--')
+    // enrichRefs 已删除（ext-simplify-04 U4/E2）：family 路径 fileName/cwd 维持 core 占位空串
+    //（SessionRef 与 find 路径共享，find 侧有真实消费者；workflow calls 反查走 pathToRef 不受影响）
+    expect(sub!.fileName).toBe('')
+    expect(sub!.cwd).toBe('')
   })
 
   it('从 fork 子代 resolve 也能关联到挂在其下的 subagent', async () => {