@zhushanwen/pi-session-reader 0.6.0 → 0.7.0

package/src/__tests__/result.test.ts

@@ -267,10 +267,10 @@ describe('result action（U6）', () => {
     }
   })
 
-  it('6. 不存在 id：sa-id 无 manifest → 无匹配 record；uuid 片段零匹配 → 无匹配 session', async () => {
+  it('6. 不存在 id：sa-id 无 manifest → zcode_record_not_found（U9 统一错误面）；uuid 片段零匹配 → 无匹配 session', async () => {
     await expect(
       handleSessionRead({ action: 'result', session: 'sa-nonexist-9999' }, { agentDir: dir }),
-    ).rejects.toThrow(/无匹配 record/)
+    ).rejects.toThrow(/zcode_record_not_found/)
     try {
       await handleSessionRead({ action: 'result', session: 'sa-nonexist-9999' }, { agentDir: dir })
     } catch (e) {

package/src/__tests__/roots.test.ts

@@ -214,7 +214,7 @@ const HOST_CASES: HostCase[] = [
     },
   },
   {
-    name: 'xyz-agent：live=根本身（RPC 覆盖态），default 去重，legacy 残留与 subagent 独立列出',
+    name: 'taiji：live=根本身（RPC 覆盖态），default 去重，legacy 残留与 subagent 独立列出',
     async build(tmp) {
       const dataDir = join(tmp, 'data')
       const agentDir = join(dataDir, 'agent')

package/src/__tests__/subagents.test.ts

@@ -10,16 +10,13 @@ import {
   extractSessionIdFromFilename,
   type RecordManifest,
 } from '../discovery/subagents.js'
-import { REAL_DATA_TIMEOUT_MS } from './real-data.js'
+import { REAL_AGENT_DIR, REAL_DATA_TIMEOUT_MS } from './real-data.js'
 
 // ---- fixture 常量（uuid 特征，满足 extractSessionIdFromFilename + 互不为子串）----
 const ROOT = '0aaaaaaa-bbbb-7ccc-dddd-000000000001'
 const FORK = '0aaaaaaa-bbbb-7ccc-dddd-000000000002'
 const SUB_REAL = '0aaaaaaa-bbbb-7ccc-dddd-000000000003'
 
-/** 真实 pi agent 目录（本机），用于集成测试。 */
-const REAL_AGENT_DIR = '/Users/zhushanwen/.pi/agent'
-
 // 同步探测真实 session 是否存在（不存在则 skip，避免在无该数据的机器上硬失败）
 function hasRealSession(sid: string): boolean {
   try {

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

@@ -30,11 +30,20 @@ import {
   hasRealSession,
 } from './real-data.js'
 
+// fs-guard：TC6 的「~ 前缀展开」语义需要 homedir，但真实 homedir 根在白名单外（禁止向用户
+// 主目录散落文件）。vi.mock 把 homedir 指到用例内 mkdtemp 的 tmp；fakeHome 未注入时回落真实值，
+// real-data.ts 模块初始化时推导 REAL_AGENT_DIR 不受影响（模块初始化先于任何用例执行）。
+const homeState = vi.hoisted(() => ({ fakeHome: undefined as string | undefined }))
+vi.mock('node:os', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('node:os')>()
+  return { ...actual, homedir: () => homeState.fakeHome ?? actual.homedir() }
+})
+
 /**
  * M3 tool-handler 集成测试。
  *
  * 测试框架 vitest（禁止 node:test/tsx）。直接调 handleSessionRead（纯逻辑，agentDir 注入），
- * 传真实 `/Users/zhushanwen/.pi/agent` 作 agentDir——用本机真实历史 session 数据，无需 mock。
+ * 传真实 `~/.pi/agent` 作 agentDir——用本机真实历史 session 数据，无需 mock。
  *
  * 覆盖全 11 action 主路径 + F1(find 零匹配)/F4(turn 越界)/F5(缺参)/resolveSessionId 片段等价，
  * 以及 u8 doctor / u9 归一化 / u10 find 分组 / u11 metadataProvider 缓存 / u12 跨会话检索（各见对应 describe）。
@@ -95,14 +104,21 @@ describe.skipIf(!HAS_REAL)('handleSessionRead', () => {
   })
 
   it('6. export outline materializes a .md file', async () => {
-    const r = await handleSessionRead(
-      { action: 'export', session: E6, format: 'outline' },
-      { agentDir: REAL },
-    )
-    const d = r.details as { path: string; sizeBytes: number }
-    expect(d.path).toMatch(/\.md$/)
-    expect(existsSync(d.path)).toBe(true)
-    expect(d.sizeBytes).toBeGreaterThan(0)
+    // fs-guard：export 写目标 = <agentDir>/tmp/，agentDir 传 REAL 会 mkdir 真实 ~/.pi/agent/tmp
+    // （白名单外）。读侧经 liveSessionDir=[live] 根仍扫真实数据，写侧落 mkdtemp tmp 自建自删。
+    const dir = await mkdtemp(join(tmpdir(), 'tool-handler-export-'))
+    try {
+      const r = await handleSessionRead(
+        { action: 'export', session: E6, format: 'outline' },
+        { agentDir: dir, liveSessionDir: join(REAL, 'sessions') },
+      )
+      const d = r.details as { path: string; sizeBytes: number }
+      expect(d.path).toMatch(/\.md$/)
+      expect(existsSync(d.path)).toBe(true)
+      expect(d.sizeBytes).toBeGreaterThan(0)
+    } finally {
+      await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+    }
   })
 
   // w1 合并 subagent 候选后，本机 subagent task 文本（含本用例 query 字符串本身，因当前
@@ -643,7 +659,7 @@ describe('extract commits 双路径（fixture：git-cmd 主路径 + commit-conte
         message: {
           role: 'assistant',
           content: [
-            { type: 'toolCall', id: 'tc-read-1', name: 'read', arguments: { path: '/tmp/log.txt' } },
+            { type: 'toolCall', id: 'tc-read-1', name: 'read', arguments: { path: join(tmpdir(), 'log.txt') } },
           ],
         },
       }),
@@ -667,7 +683,7 @@ describe('extract commits 双路径（fixture：git-cmd 主路径 + commit-conte
         message: {
           role: 'assistant',
           content: [
-            { type: 'toolCall', id: 'tc-read-2', name: 'read', arguments: { path: '/tmp/out.txt' } },
+            { type: 'toolCall', id: 'tc-read-2', name: 'read', arguments: { path: join(tmpdir(), 'out.txt') } },
           ],
         },
       }),
@@ -724,7 +740,7 @@ describe('extract commits 双路径（fixture：git-cmd 主路径 + commit-conte
         message: {
           role: 'assistant',
           content: [
-            { type: 'toolCall', id: 'tc-read-1', name: 'read', arguments: { path: '/tmp/deploy.txt' } },
+            { type: 'toolCall', id: 'tc-read-1', name: 'read', arguments: { path: join(tmpdir(), 'deploy.txt') } },
           ],
         },
       }),
@@ -933,24 +949,33 @@ describe('resolveSessionId ① 绝对路径形态（w2 TC2-TC6）', () => {
   })
 
   it('TC6: ~ 前缀展开到 homedir（文件实际在 homedir 下）', async () => {
-    const home = homedir()
-    const tmpUnderHome = await mkdtemp(join(home, '.sr-w2-test-'))
+    // fs-guard：真实 homedir 根在白名单外（禁止在用户主目录根散落 .sr-w2-test-*）——
+    // homedir 经文件头 vi.mock 指到 mkdtemp tmp（白名单内），「~ 前缀展开」断言语义不变
+    const fakeHome = await mkdtemp(join(tmpdir(), 'tool-handler-tc6-home-'))
+    homeState.fakeHome = fakeHome
     try {
-      const fileId = '019e6c96-dddd-eeee-ffff-0000000006c1'
-      const sessionFile = join(tmpUnderHome, 's.jsonl')
-      await writeFile(
-        sessionFile,
-        JSON.stringify({ type: 'session', id: fileId, cwd: '/demo' }) + '\n',
-      )
-      // ~/开头的相对 homedir 路径
-      const tildePath = '~/' + sessionFile.slice(home.length + 1)
-      const r = await handleSessionRead(
-        { action: 'export', session: tildePath, format: 'outline' },
-        { agentDir: dir },
-      )
-      expect((r.details as { path: string }).path).toContain(fileId)
+      const home = homedir()
+      const tmpUnderHome = await mkdtemp(join(home, '.sr-w2-test-'))
+      try {
+        const fileId = '019e6c96-dddd-eeee-ffff-0000000006c1'
+        const sessionFile = join(tmpUnderHome, 's.jsonl')
+        await writeFile(
+          sessionFile,
+          JSON.stringify({ type: 'session', id: fileId, cwd: '/demo' }) + '\n',
+        )
+        // ~/开头的相对 homedir 路径
+        const tildePath = '~/' + sessionFile.slice(home.length + 1)
+        const r = await handleSessionRead(
+          { action: 'export', session: tildePath, format: 'outline' },
+          { agentDir: dir },
+        )
+        expect((r.details as { path: string }).path).toContain(fileId)
+      } finally {
+        await rm(tmpUnderHome, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+      }
     } finally {
-      await rm(tmpUnderHome, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+      homeState.fakeHome = undefined
+      await rm(fakeHome, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
     }
   })
 })
@@ -1001,28 +1026,32 @@ describe('resolveSessionId ② sa-id 形态（w2 TC7-TC10 + CQ3）', () => {
     }
   })
 
-  it('TC9: sa-id 0 命中（可能 running）→ ES2（含 family 指引 + 完整 id 提示 + 👉）', async () => {
+  it('TC9: sa-id 0 命中（可能 running）→ zcode_record_not_found（U9：sa-id 语境统一错误面，含 family 指引 + 👉）', async () => {
     await expect(
       handleSessionRead({ action: 'outline', session: 'sa-nonexist-9999' }, { agentDir: dir }),
-    ).rejects.toThrow('无匹配 record')
+    ).rejects.toThrow('zcode_record_not_found')
     try {
       await handleSessionRead({ action: 'outline', session: 'sa-nonexist-9999' }, { agentDir: dir })
     } catch (e) {
       const msg = (e as Error).message
-      expect(msg).toContain('可能尚未落盘')
+      expect(msg).toContain('未落盘')
       expect(msg).toContain('action:"family"')
       expect(msg).toContain('👉')
     }
   })
 
-  it('TC10: sa-id 片段输入（精确相等不命中）→ ES2', async () => {
+  it('TC10: sa-id 片段输入（精确相等不命中）→ zcode_record_not_found + 完整 sa- id 重试指引（U9 统一错误面）', async () => {
     await makeFixtureSubagent(dir, 'sa-c8c8dfa8', {
       realSessionId: '019e6c96-dddd-eeee-ffff-0000000010a3',
     })
-    // 片段 sa-c8c8 不等于完整 sa-c8c8dfa8 → 精确相等不命中 → ES2
+    // 片段 sa-c8c8 不等于完整 sa-c8c8dfa8 → 精确相等不命中（兜底亦未命中）
     await expect(
       handleSessionRead({ action: 'outline', session: 'sa-c8c8' }, { agentDir: dir }),
-    ).rejects.toThrow('无匹配 record')
+    ).rejects.toThrow('zcode_record_not_found')
+    // 片段输入恢复路径在指引内可见（A4：ES2 原文案「用完整 sa- id 重试」的覆盖补全）
+    await expect(
+      handleSessionRead({ action: 'outline', session: 'sa-c8c8' }, { agentDir: dir }),
+    ).rejects.toThrow(/完整 sa- id（形如 `sa-xxxx`）后重试/)
   })
 
   it('sa-id 多 manifest 命中（数据异常）→ ES2 ambiguous（C4）', async () => {
@@ -1195,11 +1224,11 @@ describe.skipIf(!HAS_REAL_SUBAGENTS_DIR)('真实数据：subagent sa-id（w2 TC1
     ).rejects.toThrow('session 文件不存在')
   })
 
-  it('TC18: 不存在 sa-id → ES2（场景 4，可能 running 指引）', async () => {
+  it('TC18: 不存在 sa-id → zcode_record_not_found（场景 4，U9 统一错误面）', async () => {
     const fakeId = `sa-nonexist-${Date.now().toString(16)}-${Math.random().toString(16).slice(2, 8)}`
     await expect(
       handleSessionRead({ action: 'outline', session: fakeId }, { agentDir: REAL }),
-    ).rejects.toThrow('无匹配 record')
+    ).rejects.toThrow('zcode_record_not_found')
   })
 }, 60000)
 
@@ -1801,8 +1830,8 @@ describe('doctor action（u8：环境判定 + 根表 + 告警 + 残留 glob）',
   }
 
   /**
-   * xyz-agent 形态四根 fixture：dataDir 目录名带 .xyz-agent 前缀（detectEnvironment 的
-   * PI_CODING_AGENT_DIR 形态判据 `<*>/.xyz-agent*\/agent` 可命中，托管判定走正态）。
+   * taiji 形态四根 fixture：dataDir 目录名带 .taiji 前缀（detectEnvironment 的
+   * PI_CODING_AGENT_DIR 形态判据 `<*>/.taiji*\/agent` 可命中，托管判定走正态）。
    * live=agent/sessions 与 default 同字面路径（default 去重）、legacy 独立非空、subagent 独立。
    */
   async function buildFourRootFixture(): Promise<{
@@ -1810,7 +1839,7 @@ describe('doctor action（u8：环境判定 + 根表 + 告警 + 残留 glob）',
     agentDir: string
     signals: SessionReadSignals
   }> {
-    const dataDir = join(tmp, '.xyz-agent-fixture')
+    const dataDir = join(tmp, '.taiji-fixture')
     const agentDir = join(dataDir, 'agent')
     await writeJsonl(join(agentDir, 'sessions', SLUG, 'a.jsonl'), 'aaaaaaaa')
     await writeJsonl(join(agentDir, 'sessions', SLUG, 'b.jsonl'), 'bbbbbbbb')
@@ -1823,9 +1852,9 @@ describe('doctor action（u8：环境判定 + 根表 + 告警 + 残留 glob）',
         agentDir,
         liveSessionDir: join(agentDir, 'sessions'),
         env: {
-          XYZ_AGENT_EXT_LOG: '1',
+          TAIJI_AGENT_EXT_LOG: '1',
           PI_CODING_AGENT_DIR: agentDir,
-          XYZ_AGENT_DATA_DIR: dataDir,
+          TAIJI_AGENT_DATA_DIR: dataDir,
         },
       },
     }
@@ -1843,8 +1872,8 @@ describe('doctor action（u8：环境判定 + 根表 + 告警 + 残留 glob）',
     const r = await handleSessionRead({ action: 'doctor' }, signals)
     const text = r.content[0].text
 
-    // 环境判定行：双信号合取 → xyz-agent（托管）+ 数据目录 + evidence 正态
-    expect(text).toContain('环境判定：xyz-agent（托管）')
+    // 环境判定行：双信号合取 → taiji（托管）+ 数据目录 + evidence 正态
+    expect(text).toContain('环境判定：taiji（托管）')
     expect(text).toContain(`数据目录：${dataDir}`)
     expect(text).toContain('依据：')
     expect(text).toContain(`PI_CODING_AGENT_DIR='${agentDir}' → 形态匹配`)
@@ -1887,7 +1916,7 @@ describe('doctor action（u8：环境判定 + 根表 + 告警 + 残留 glob）',
     const { signals } = await buildFourRootFixture()
     const positive = await handleSessionRead({ action: 'doctor' }, signals)
     expect(positive.content[0].text).toContain(
-      `告警：[legacy] 根 ${join(tmp, '.xyz-agent-fixture', 'sessions')} 非空（1 文件）`,
+      `告警：[legacy] 根 ${join(tmp, '.taiji-fixture', 'sessions')} 非空（1 文件）`,
     )
 
     // 反态：legacy 目录不存在
@@ -1908,43 +1937,6 @@ describe('doctor action（u8：环境判定 + 根表 + 告警 + 残留 glob）',
     expect(deduped.content[0].text).toContain('已去重')
   })
 
-  it('独立 glob 残留探测：pi/ 含 agent|sessions 形态列出 + 迁移指引；pi.backup-v2-* 备份列出；基点 = dirname(agentDir)', async () => {
-    const dataDir = join(tmp, 'data')
-    const agentDir = join(dataDir, 'agent')
-    await writeJsonl(join(agentDir, 'sessions', SLUG, 'a.jsonl'))
-    // 未迁移旧布局 pi/（含 agent/ 形态）
-    await mkdir(join(dataDir, 'pi', 'agent'), { recursive: true })
-    await writeJsonl(join(dataDir, 'pi', 'agent', 'sessions', 'old.jsonl'), 'old-id')
-    // 迁移备份（含 sessions/ 形态——备份即原 pi/ 改名）
-    const backup = join(dataDir, 'pi.backup-v2-1725900000000')
-    await mkdir(join(backup, 'sessions'), { recursive: true })
-    await writeJsonl(join(backup, 'sessions', 'bak.jsonl'), 'bak-id')
-
-    const r = await handleSessionRead({ action: 'doctor' }, { agentDir })
-    const text = r.content[0].text
-    expect(text).toContain(`旧布局残留探测（基点 ${dataDir}）`)
-    expect(text).toContain(`  - ${join(dataDir, 'pi')}（未迁移旧布局 pi/）`)
-    expect(text).toContain(`  - ${backup}（迁移备份 pi.backup-v2-*）`)
-    // 同一迁移指引（§6.11：doctor 与 u14b 启动探测同指引）
-    expect(text).toContain('👉 关闭应用后运行 scripts/migrate-pi-layout-v2.mjs 完成迁移。')
-
-    const d = r.details as DoctorDetails
-    expect(d.globBase).toBe(dataDir)
-    expect(d.leftovers.map((l) => l.kind).sort()).toEqual(['backup', 'unmigrated'])
-  })
-
-  it('残留探测反态：pi/ 空壳（无 agent|sessions 子目录）不报——防纯 pi 宿主 ~/.pi/pi/ 误报（§6.11 v9.1）', async () => {
-    const dataDir = join(tmp, 'data')
-    const agentDir = join(dataDir, 'agent')
-    await writeJsonl(join(agentDir, 'sessions', SLUG, 'a.jsonl'))
-    // 纯 pi 宿主下任意来源的 pi/ 目录：只有无关子目录，无 agent/ 与 sessions/ 形态
-    await mkdir(join(dataDir, 'pi', 'extensions'), { recursive: true })
-
-    const r = await handleSessionRead({ action: 'doctor' }, { agentDir })
-    expect(r.content[0].text).not.toContain('旧布局残留')
-    expect((r.details as DoctorDetails).leftovers).toEqual([])
-  })
-
   it('subagent 根默认不扫（只列路径与可扫性）；includeSubagents:true 才扫出文件数（§6.3）', async () => {
     const { agentDir, signals } = await buildFourRootFixture()
 
@@ -1995,7 +1987,7 @@ describe('doctor action（u8：环境判定 + 根表 + 告警 + 残留 glob）',
     const r = await handleSessionRead({ action: 'doctor' }, { agentDir })
     const text = r.content[0].text
     expect(text).toContain('环境判定：standalone-pi · 发行形态：未知（不猜）')
-    expect(text).toContain('XYZ_AGENT_EXT_LOG=<未设置> → 未命中')
+    expect(text).toContain('TAIJI_AGENT_EXT_LOG=<未设置> → 未命中')
     expect(text).toContain('会话根（按优先级）')
     expect(text).toContain('[default]')
     expect(text).toContain(
@@ -2003,13 +1995,12 @@ describe('doctor action（u8：环境判定 + 根表 + 告警 + 残留 glob）',
     )
   })
 
-  it('空 agentDir 防御：无根表、诊断「无候选根」，残留探测不触发（不扫 cwd 相对路径）', async () => {
+  it('空 agentDir 防御：无根表、诊断「无候选根」（不扫 cwd 相对路径）', async () => {
     const r = await handleSessionRead({ action: 'doctor' }, { agentDir: '' })
     const text = r.content[0].text
     expect(text).toContain('诊断：无候选根')
     expect(text).not.toContain('[default]')
     expect((r.details as DoctorDetails).roots).toEqual([])
-    expect((r.details as DoctorDetails).leftovers).toEqual([])
   })
 })
 
@@ -2641,7 +2632,7 @@ describe('E1 find 单次根解析（探针 P1：resolveSessionRoots 恰 1 次）
 // ============================================================
 describe('u11 metadataProvider 注入 + TTL 缓存（fixture，§6.6）', () => {
   let tmp: string
-  /** 平铺 main 根（xyz-agent 形态），同时作 liveSessionDir（与 [default] 根同字面路径） */
+  /** 平铺 main 根（taiji 形态），同时作 liveSessionDir（与 [default] 根同字面路径） */
   let flatMain: string
 
   async function writeSession(

package/src/__tests__/toolcall.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest'
 import { extractToolCalls, formatToolCallSummary } from '../core/toolcall.js'
-import type { Entry } from '../core/parser.js'
+import type { Entry } from '@zhushanwen/session-core'
 
 /**
  * D1 映射表（design §3.3）确定性测试：formatToolCallSummary 12 个 switch 分支

package/src/__tests__/tree.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest'
 import { buildTreeView } from '../core/tree.js'
-import type { Entry } from '../core/parser.js'
+import type { Entry } from '@zhushanwen/session-core'
 
 /** 构造最小 Entry（tree.ts 只消费 type/id/parentId，其余字段省略） */
 function e(id: string, parentId: string | null): Entry {

package/src/__tests__/turns.test.ts

@@ -1,7 +1,6 @@
 import { describe, it, expect } from 'vitest'
 import { segmentTurns } from '../core/turns.js'
-import type { Entry } from '../core/parser.js'
-import { parseSessionFile } from '../core/parser.js'
+import { parseSessionFile, type Entry } from '@zhushanwen/session-core'
 import { buildTreeView } from '../core/tree.js'
 import { REAL_SESSION, HAS_REAL_SESSION } from './real-data.js'