@zhushanwen/pi-session-reader 0.3.1 → 0.5.0

package/src/__tests__/roots.test.ts

@@ -1,9 +1,26 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
 import { tmpdir } from 'node:os'
-import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises'
-import { join } from 'node:path'
-import { listMainSessions, listSubagentSessions } from '../discovery/roots.js'
-import { REAL_AGENT_DIR, HAS_E6, HAS_REAL_SUBAGENTS_DIR } from './real-data.js'
+import { mkdtemp, mkdir, readdir, writeFile, rm } from 'node:fs/promises'
+import { join, dirname } from 'node:path'
+import {
+  listMainSessions,
+  listSubagentSessions,
+  resolveSessionRoots,
+  normalizeLiveSessionDir,
+  type SessionRoot,
+  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'
+
+/** 写 .jsonl fixture（父目录不存在则自建），内容默认合法 session header */
+async function writeJsonl(path: string, content = '{"type":"session","id":"x"}\n') {
+  await mkdir(dirname(path), { recursive: true })
+  await writeFile(path, content)
+}
+
+/** 真实形态的 cwd 编码目录名（encodeCwd：`--` 开头 `--` 结尾，实证见 real-data.ts） */
+const SLUG = '--Users-foo--'
 
 describe('listMainSessions', () => {
   let dir: string
@@ -12,7 +29,7 @@ describe('listMainSessions', () => {
     dir = await mkdtemp(join(tmpdir(), 'roots-test-'))
   })
   afterEach(async () => {
-    await rm(dir, { recursive: true, force: true })
+    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
   })
 
   it('扫描 sessions/<slug>/*.jsonl，排除 *.jsonl.finalized', async () => {
@@ -80,7 +97,7 @@ describe('listMainSessions', () => {
     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)
-  }, 30000)
+  }, REAL_DATA_TIMEOUT_MS)
 })
 
 describe('listSubagentSessions', () => {
@@ -90,7 +107,7 @@ describe('listSubagentSessions', () => {
     dir = await mkdtemp(join(tmpdir(), 'roots-sub-test-'))
   })
   afterEach(async () => {
-    await rm(dir, { recursive: true, force: true })
+    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
   })
 
   it('扫描 subagents/<slug>/sessions/*.jsonl，排除 .finalized', async () => {
@@ -128,5 +145,341 @@ describe('listSubagentSessions', () => {
     const result = await listSubagentSessions(REAL_AGENT_DIR)
     expect(result.length).toBeGreaterThan(0)
     expect(result.every((m) => !m.path.endsWith('.finalized'))).toBe(true)
-  }, 30000)
+  }, REAL_DATA_TIMEOUT_MS)
+})
+
+// ============================================================
+// U1 resolveSessionRoots（design 2026-09-10 §6.1 / §7B 要点 2/3/4/6/7；B 收缩无 [env]）
+// ============================================================
+
+/** 三宿主信号包用例的行内校验上下文 */
+interface HostCaseCtx {
+  tmp: string
+  agentDir: string
+}
+
+interface HostCase {
+  name: string
+  build: (tmp: string) => Promise<{ agentDir: string; signals: SessionRootSignals }>
+  verify: (ctx: HostCaseCtx, roots: SessionRoot[]) => void
+}
+
+const HOST_CASES: HostCase[] = [
+  {
+    name: '纯 pi：live=encodeCwd 子目录，剥层后与 default 同路径去重，保留 live 标签',
+    async build(tmp) {
+      const agentDir = join(tmp, 'agent')
+      await writeJsonl(join(agentDir, 'sessions', SLUG, 'a.jsonl'))
+      return {
+        agentDir,
+        signals: { agentDir, liveSessionDir: join(agentDir, 'sessions', SLUG) },
+      }
+    },
+    verify({ agentDir }, roots) {
+      // kind 序 = 优先级序（live > default > legacy > subagent；B 收缩无 env）
+      expect(roots.map((r) => r.kind)).toEqual(['live', 'default', 'legacy', 'subagent'])
+      const live = roots.find((r) => r.kind === 'live')!
+      // 剥层（§7B 要点 3）：父目录名为 sessions 的真实形态 → dirname
+      expect(live.path).toBe(join(agentDir, 'sessions'))
+      expect(live.exists).toBe(true)
+      expect(live.fileCount).toBe(1)
+      const def = roots.find((r) => r.kind === 'default')!
+      expect(def.path).toBe(join(agentDir, 'sessions'))
+      // realpath 去重（§7B 要点 4）：同路径只扫一次，保留最高优先级 kind
+      expect(def.dedupedInto).toBe('live')
+      expect(def.files).toHaveLength(0)
+      expect(def.fileCount).toBeUndefined()
+      // 该路径在全列表中只被一个根实扫（文件不重复计入）
+      const scannedAtSamePath = roots.filter(
+        (r) => r.path === join(agentDir, 'sessions') && r.dedupedInto === undefined,
+      )
+      expect(scannedAtSamePath).toHaveLength(1)
+      expect(roots.reduce((n, r) => n + r.files.length, 0)).toBe(1)
+    },
+  },
+  {
+    name: 'xyz-agent：live=根本身（RPC 覆盖态），default 去重，legacy 残留与 subagent 独立列出',
+    async build(tmp) {
+      const dataDir = join(tmp, 'data')
+      const agentDir = join(dataDir, 'agent')
+      await writeJsonl(join(agentDir, 'sessions', SLUG, 'x.jsonl'))
+      await writeJsonl(join(dataDir, 'sessions', 'old.jsonl')) // 旧旧布局迁移残留（§6.13 U1 行）
+      await writeJsonl(join(agentDir, 'subagents', SLUG, 'sessions', 's.jsonl'))
+      return { agentDir, signals: { agentDir, liveSessionDir: join(agentDir, 'sessions') } }
+    },
+    verify({ agentDir, tmp }, roots) {
+      expect(roots.map((r) => r.kind)).toEqual(['live', 'default', 'legacy', 'subagent'])
+      // live=根本身（basename 非 encodeCwd 形态）→ 取自身，与 default 同字面路径 → 去重
+      const scanned = roots.filter((r) => r.dedupedInto === undefined)
+      expect(scanned.map((r) => r.kind)).toEqual(['live', 'legacy', 'subagent'])
+      const live = scanned[0]!
+      expect(live.path).toBe(join(agentDir, 'sessions'))
+      expect(live.fileCount).toBe(1) // 递归扫到 encodeCwd 子目录内的文件
+      const def = roots.find((r) => r.kind === 'default')!
+      expect(def.dedupedInto).toBe('live')
+      // legacy（<dataDir>/sessions 残留）非空即纳入候选，独立成根
+      const legacy = roots.find((r) => r.kind === 'legacy')!
+      expect(legacy.path).toBe(join(tmp, 'data', 'sessions'))
+      expect(legacy.exists).toBe(true)
+      expect(legacy.fileCount).toBe(1)
+      const sub = roots.find((r) => r.kind === 'subagent')!
+      expect(sub.exists).toBe(true)
+      expect(sub.fileCount).toBe(1)
+      expect(sub.files[0]!.path.endsWith('s.jsonl')).toBe(true)
+    },
+  },
+  {
+    name: 'liveSessionDir 缺失降级：default/legacy/subagent 三根仍可用，无 live 根',
+    async build(tmp) {
+      const agentDir = join(tmp, 'agent')
+      await writeJsonl(join(agentDir, 'sessions', SLUG, 'a.jsonl'))
+      return { agentDir, signals: { agentDir } }
+    },
+    verify({ agentDir, tmp }, roots) {
+      expect(roots.map((r) => r.kind)).toEqual(['default', 'legacy', 'subagent'])
+      const def = roots.find((r) => r.kind === 'default')!
+      expect(def.path).toBe(join(agentDir, 'sessions'))
+      expect(def.exists).toBe(true)
+      expect(def.fileCount).toBe(1)
+      expect(roots.find((r) => r.kind === 'legacy')!.path).toBe(join(tmp, 'sessions'))
+      // live 缺席 → 无去重发生
+      expect(roots.every((r) => r.dedupedInto === undefined)).toBe(true)
+    },
+  },
+]
+
+describe('resolveSessionRoots', () => {
+  it.each(HOST_CASES)('$name', async ({ build, verify }) => {
+    const tmp = await mkdtemp(join(tmpdir(), 'roots-resolve-'))
+    try {
+      const { agentDir, signals } = await build(tmp)
+      const roots = await resolveSessionRoots(signals)
+
+      // ④ subagent 根恒在（常量推导，不来自任何信号，§6.1 信号 5）
+      const sub = roots.find((r) => r.kind === 'subagent')
+      expect(sub).toBeDefined()
+      expect(sub!.source).toBe('subagent')
+      expect(sub!.path).toBe(join(agentDir, 'subagents'))
+
+      // ⑤ 已扫描根 fileCount/scanMs 恒填充且与 files 一致；被去重根不产生扫描统计
+      for (const r of roots) {
+        if (r.dedupedInto !== undefined) {
+          expect(r.fileCount).toBeUndefined()
+          expect(r.scanMs).toBeUndefined()
+        } else {
+          expect(typeof r.fileCount).toBe('number')
+          expect(r.fileCount).toBe(r.files.length)
+          expect(typeof r.scanMs).toBe('number')
+          expect(r.scanMs!).toBeGreaterThanOrEqual(0)
+        }
+      }
+
+      verify({ tmp, agentDir }, roots)
+    } finally {
+      await rm(tmp, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+    }
+  })
+
+  it('[live] 规范化第二形态：普通目录（basename 非 encodeCwd 形态）取自身，不剥层', async () => {
+    const tmp = await mkdtemp(join(tmpdir(), 'roots-live-plain-'))
+    try {
+      const agentDir = join(tmp, 'agent')
+      const liveDir = join(tmp, 'live-sessions')
+      await writeJsonl(join(liveDir, 'b.jsonl'))
+
+      const roots = await resolveSessionRoots({ agentDir, liveSessionDir: liveDir })
+      const live = roots.find((r) => r.kind === 'live')!
+      expect(live.path).toBe(liveDir)
+      expect(live.exists).toBe(true)
+      expect(live.fileCount).toBe(1)
+      // default/legacy 独立列出，互不干扰
+      expect(roots.find((r) => r.kind === 'default')!.path).toBe(join(agentDir, 'sessions'))
+      expect(roots.every((r) => r.dedupedInto === undefined)).toBe(true)
+    } finally {
+      await rm(tmp, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+    }
+  })
+
+  it('空 agentDir 防御：不派生任何根（避免扫到进程 cwd 相对路径）', async () => {
+    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,
+  )
+})
+
+describe('buildFamilyFromFs not-found 文案（U1 并入：列实际扫描候选根）', () => {
+  let tmp: string
+
+  beforeEach(async () => {
+    tmp = await mkdtemp(join(tmpdir(), 'roots-notfound-'))
+  })
+  afterEach(async () => {
+    await rm(tmp, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+  })
+
+  it('错误信息含各候选根路径、kind 标签与文件数（default/legacy），保留 findSessions 指引', async () => {
+    const agentDir = join(tmp, 'data', 'agent')
+    await writeJsonl(
+      join(agentDir, 'sessions', SLUG, 'known.jsonl'),
+      '{"type":"session","id":"known-id"}\n',
+    )
+
+    const msg = await buildFamilyFromFs('missing-id', agentDir).then(
+      () => {
+        throw new Error('buildFamilyFromFs should reject for unknown sessionId')
+      },
+      (e: unknown) => (e instanceof Error ? e.message : String(e)),
+    )
+    expect(msg).toContain('not found')
+    expect(msg).toContain(join(agentDir, 'sessions'))
+    expect(msg).toContain('[default]')
+    expect(msg).toContain('1 file(s)')
+    expect(msg).toContain(join(tmp, 'data', 'sessions'))
+    expect(msg).toContain('[legacy]')
+    expect(msg).toContain('not exists')
+    // 只列 main 候选根（collectMainSessions 实扫集合），不含 subagent 根
+    expect(msg).not.toContain('[subagent]')
+    expect(msg).toContain('findSessions')
+  })
+})
+
+// ============================================================
+// u8 追加：resolveSessionRoots options（doctor 统一数据源，design §6.3「同一数据源
+// 两处渲染，不重复实现探测」——subagent 扫描模式与进程内缓存经 options 由调用方
+// 驱动，本模块不内置 TTL/mtime 失效逻辑）
+// ============================================================
+
+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-'))
+    const agentDir = join(tmp, 'agent')
+    await mkdir(join(agentDir, 'sessions', SLUG), { recursive: true })
+    await writeFile(join(agentDir, 'sessions', SLUG, 'a.jsonl'), '{"type":"session"}\n')
+    await mkdir(join(agentDir, 'subagents', SLUG, 'sessions'), { recursive: true })
+    await writeFile(join(agentDir, 'subagents', SLUG, 'sessions', 's.jsonl'), '{"type":"session"}\n')
+    return { tmp, agentDir }
+  }
+
+  it("subagents:'stat'：subagent 根只 stat（无计数/耗时/files 空），main 根照常实扫", async () => {
+    const { tmp, agentDir } = await buildMinimalFixture()
+    try {
+      const roots = await resolveSessionRoots({ agentDir }, { subagents: 'stat' })
+      const sub = roots.find((r) => r.kind === 'subagent')!
+      expect(sub.exists).toBe(true)
+      expect(sub.fileCount).toBeUndefined()
+      expect(sub.scanMs).toBeUndefined()
+      expect(sub.files).toEqual([])
+      expect(sub.dedupedInto).toBeUndefined()
+      // main 根不受影响：照常实扫
+      const def = roots.find((r) => r.kind === 'default')!
+      expect(def.fileCount).toBe(1)
+      expect(def.files).toHaveLength(1)
+    } finally {
+      await rm(tmp, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+    }
+  })
+
+  it("options 缺省与 subagents:'scan'：subagent 根照旧全扫（现有调用方零破坏）", async () => {
+    const { tmp, agentDir } = await buildMinimalFixture()
+    try {
+      for (const options of [undefined, { subagents: 'scan' as const }]) {
+        const roots = await resolveSessionRoots({ agentDir }, options)
+        const sub = roots.find((r) => r.kind === 'subagent')!
+        expect(sub.fileCount).toBe(1)
+        expect(sub.files).toHaveLength(1)
+      }
+    } finally {
+      await rm(tmp, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+    }
+  })
+
+  it('cache：未命中实扫后 set 回写；命中以缓存值构造根（cached 标记、files 空、不再回写）', async () => {
+    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 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

@@ -72,7 +72,7 @@ describe('createSessionCommand - getArgumentCompletions', () => {
     await mkdir(cwdSessionDir, { recursive: true })
   })
   afterEach(async () => {
-    await rm(agentDir, { recursive: true, force: true })
+    await rm(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
   })
 
   it('空参数 → recent 列表（value=完整 uuid 剥 #，label 含预览）', async () => {
@@ -129,7 +129,7 @@ describe('createSessionCommand - handler select 流程', () => {
     await mkdir(cwdSessionDir, { recursive: true })
   })
   afterEach(async () => {
-    await rm(agentDir, { recursive: true, force: true })
+    await rm(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
   })
 
   it('选中 label → setEditorText(#完整 uuid + 尾随空格)（value 语义保持完整 uuid）', async () => {

package/src/__tests__/subagents.test.ts

@@ -10,6 +10,7 @@ import {
   extractSessionIdFromFilename,
   type RecordManifest,
 } from '../discovery/subagents.js'
+import { REAL_DATA_TIMEOUT_MS } from './real-data.js'
 
 // ---- fixture 常量（uuid 特征，满足 extractSessionIdFromFilename + 互不为子串）----
 const ROOT = '0aaaaaaa-bbbb-7ccc-dddd-000000000001'
@@ -196,7 +197,7 @@ describe('buildFamilyFromFs - fixture', () => {
     dir = await makeAgentDir()
   })
   afterEach(async () => {
-    await rm(dir, { recursive: true, force: true })
+    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
   })
 
   it('基础 family：root + fork + 隔代 subagent，SubagentRef.sessionId 是真实 id（非 sa-xxx）', async () => {
@@ -471,7 +472,7 @@ describe.skipIf(!HAS_REAL_ROOT)('buildFamilyFromFs - 真实数据 ~/.pi/agent',
     )
     expect(sub).toBeDefined()
     expect(sub!.sessionId.startsWith('sa-')).toBe(false)
-  }, 30000)
+  }, REAL_DATA_TIMEOUT_MS)
 })
 
 describe.skipIf(!HAS_REAL_WF)('buildFamilyFromFs - 真实 workflow 数据', () => {
@@ -500,7 +501,7 @@ describe.skipIf(!HAS_REAL_WF)('buildFamilyFromFs - 真实 workflow 数据', () =
     // stateFile 是 wf-state 文件绝对路径
     expect(rich!.stateFile.endsWith('.jsonl')).toBe(true)
     expect(rich!.runId.startsWith('wf-')).toBe(true)
-  }, 30000)
+  }, REAL_DATA_TIMEOUT_MS)
 })
 
 // ============================================================
@@ -514,7 +515,7 @@ describe('listRecordManifests 导出（w2 TC1）', () => {
     dir = await makeAgentDir()
   })
   afterEach(async () => {
-    await rm(dir, { recursive: true, force: true })
+    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
   })
 
   it('导出生效：import + 调用返回 RecordManifest[]，字段完整', async () => {
@@ -545,7 +546,7 @@ describe('U4 buildFamilyFromFs 富化（manifest 主 / P-fallback）', () => {
     dir = await makeAgentDir()
   })
   afterEach(async () => {
-    await rm(dir, { recursive: true, force: true })
+    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
   })
 
   it('TC-u4-manifest-enrich: alive + manifest 全字段 → SubagentRef 富字段全透传', async () => {
@@ -735,5 +736,5 @@ describe.skipIf(!HAS_REAL_ROOT || !HAS_REAL_SUBAGENTS_DIR)('U4 真实数据守
 
     // 所有 subagent 的 sessionFile 非空（manifest.sessionFile 或 alive meta.path）
     expect(family.subagents.every((s) => typeof s.sessionFile === 'string' && s.sessionFile.length > 0)).toBe(true)
-  }, 30000)
+  }, REAL_DATA_TIMEOUT_MS)
 })