@zhushanwen/pi-session-reader 0.6.0 → 0.7.0

package/src/__tests__/env.test.ts

@@ -1,9 +1,9 @@
 import { describe, it, expect } from 'vitest'
 import {
   detectEnvironment,
-  XYZ_AGENT_EXT_LOG_ENV,
+  TAIJI_AGENT_EXT_LOG_ENV,
   PI_CODING_AGENT_DIR_ENV,
-  XYZ_AGENT_DATA_DIR_ENV,
+  TAIJI_AGENT_DATA_DIR_ENV,
   type EnvironmentSignals,
 } from '../discovery/env.js'
 
@@ -22,54 +22,54 @@ function signals(overrides: Partial<EnvironmentSignals> = {}): EnvironmentSignal
 }
 
 describe('detectEnvironment 托管合取判定', () => {
-  it('双信号齐备 + B 后新布局 <dataDir>/agent → xyz-agent（packaged）', () => {
+  it('双信号齐备 + B 后新布局 <dataDir>/agent → taiji（packaged）', () => {
     const r = detectEnvironment(
       signals({
         env: {
-          [XYZ_AGENT_EXT_LOG_ENV]: '1',
-          [PI_CODING_AGENT_DIR_ENV]: '/Users/u/.xyz-agent/agent',
+          [TAIJI_AGENT_EXT_LOG_ENV]: '1',
+          [PI_CODING_AGENT_DIR_ENV]: '/Users/u/.taiji/agent',
         },
         bundleUrl:
           'file:///Applications/TaiJi.app/Contents/Resources/extensions/@zhushanwen/pi-session-reader/index.mjs',
       }),
     )
-    expect(r.kind).toBe('xyz-agent')
+    expect(r.kind).toBe('taiji')
     expect(r.distribution).toBe('packaged')
-    expect(r.dataDir).toBe('/Users/u/.xyz-agent')
+    expect(r.dataDir).toBe('/Users/u/.taiji')
   })
 
-  it('双信号齐备 + B 前旧布局 <dataDir>/pi/agent → xyz-agent（迁移窗口期双形态兼容）', () => {
+  it('双信号齐备 + B 前旧布局 <dataDir>/pi/agent → taiji（迁移窗口期双形态兼容）', () => {
     const r = detectEnvironment(
       signals({
         env: {
-          [XYZ_AGENT_EXT_LOG_ENV]: '1',
-          [PI_CODING_AGENT_DIR_ENV]: '/Users/u/.xyz-agent-dev/pi/agent',
+          [TAIJI_AGENT_EXT_LOG_ENV]: '1',
+          [PI_CODING_AGENT_DIR_ENV]: '/Users/u/.taiji-dev/pi/agent',
         },
-        bundleUrl: 'file:///Users/u/Code/xyz-agent/extensions/universal/session-reader/src/index.ts',
+        bundleUrl: 'file:///Users/u/Code/taiji/extensions/universal/session-reader/src/index.ts',
       }),
     )
-    expect(r.kind).toBe('xyz-agent')
+    expect(r.kind).toBe('taiji')
     expect(r.distribution).toBe('dev')
-    expect(r.dataDir).toBe('/Users/u/.xyz-agent-dev')
+    expect(r.dataDir).toBe('/Users/u/.taiji-dev')
   })
 
-  it('透传污染反例 1：仅 XYZ_AGENT_EXT_LOG=1（PI_CODING_AGENT_DIR 未设）→ standalone-pi，evidence 点名孤置信号', () => {
+  it('透传污染反例 1：仅 TAIJI_AGENT_EXT_LOG=1（PI_CODING_AGENT_DIR 未设）→ standalone-pi，evidence 点名孤置信号', () => {
     const r = detectEnvironment(
-      signals({ env: { [XYZ_AGENT_EXT_LOG_ENV]: '1' } }),
+      signals({ env: { [TAIJI_AGENT_EXT_LOG_ENV]: '1' } }),
     )
     expect(r.kind).toBe('standalone-pi')
     expect(r.dataDir).toBeUndefined()
     const joined = r.evidence.join('\n')
-    expect(joined).toContain(`${XYZ_AGENT_EXT_LOG_ENV}='1' → 命中`)
+    expect(joined).toContain(`${TAIJI_AGENT_EXT_LOG_ENV}='1' → 命中`)
     expect(joined).toContain('单独成立不合取')
-    expect(joined).toContain(XYZ_AGENT_EXT_LOG_ENV)
+    expect(joined).toContain(TAIJI_AGENT_EXT_LOG_ENV)
   })
 
-  it('透传污染反例 2：仅 XYZ_AGENT_EXT_LOG=1 且 PI_CODING_AGENT_DIR 为裸 pi 形态 → standalone-pi', () => {
+  it('透传污染反例 2：仅 TAIJI_AGENT_EXT_LOG=1 且 PI_CODING_AGENT_DIR 为裸 pi 形态 → standalone-pi', () => {
     const r = detectEnvironment(
       signals({
         env: {
-          [XYZ_AGENT_EXT_LOG_ENV]: '1',
+          [TAIJI_AGENT_EXT_LOG_ENV]: '1',
           [PI_CODING_AGENT_DIR_ENV]: '/home/u/.pi/agent',
         },
       }),
@@ -81,7 +81,7 @@ describe('detectEnvironment 托管合取判定', () => {
   it('透传污染反例 3：仅 PI_CODING_AGENT_DIR 形态匹配（EXT_LOG 未设）→ standalone-pi，evidence 点名孤置信号', () => {
     const r = detectEnvironment(
       signals({
-        env: { [PI_CODING_AGENT_DIR_ENV]: '/Users/u/.xyz-agent/agent' },
+        env: { [PI_CODING_AGENT_DIR_ENV]: '/Users/u/.taiji/agent' },
       }),
     )
     expect(r.kind).toBe('standalone-pi')
@@ -92,13 +92,13 @@ describe('detectEnvironment 托管合取判定', () => {
     expect(joined).toContain(PI_CODING_AGENT_DIR_ENV)
   })
 
-  it('XYZ_AGENT_EXT_LOG 非 1 值（如 0 / true）不构成命中', () => {
+  it('TAIJI_AGENT_EXT_LOG 非 1 值（如 0 / true）不构成命中', () => {
     for (const value of ['0', 'true', '']) {
       const r = detectEnvironment(
         signals({
           env: {
-            [XYZ_AGENT_EXT_LOG_ENV]: value,
-            [PI_CODING_AGENT_DIR_ENV]: '/Users/u/.xyz-agent/agent',
+            [TAIJI_AGENT_EXT_LOG_ENV]: value,
+            [PI_CODING_AGENT_DIR_ENV]: '/Users/u/.taiji/agent',
           },
         }),
       )
@@ -106,12 +106,12 @@ describe('detectEnvironment 托管合取判定', () => {
     }
   })
 
-  it('形态防误报：无点前缀 xyz-agent、嵌套浅段不匹配', () => {
-    for (const dir of ['/home/u/xyz-agent/agent', '/home/u/.xyz/agent', '/.pi/agent']) {
+  it('形态防误报：无点前缀 taiji、嵌套浅段不匹配', () => {
+    for (const dir of ['/home/u/taiji/agent', '/home/u/.foo/agent', '/.pi/agent']) {
       const r = detectEnvironment(
         signals({
           env: {
-            [XYZ_AGENT_EXT_LOG_ENV]: '1',
+            [TAIJI_AGENT_EXT_LOG_ENV]: '1',
             [PI_CODING_AGENT_DIR_ENV]: dir,
           },
         }),
@@ -144,8 +144,8 @@ describe('detectEnvironment distribution（bundle 路径三态）', () => {
 
   it('仓库路径（源码与 dev staged 资源根两种）→ dev，staged 根不被误判 packaged', () => {
     for (const url of [
-      'file:///Users/u/Code/xyz-agent/extensions/universal/session-reader/src/index.ts',
-      'file:///Users/u/Code/xyz-agent/apps/electron/resources/extensions/@zhushanwen/pi-session-reader/index.mjs',
+      'file:///Users/u/Code/taiji/extensions/universal/session-reader/src/index.ts',
+      'file:///Users/u/Code/taiji/apps/electron/resources/extensions/@zhushanwen/pi-session-reader/index.mjs',
     ]) {
       const r = detectEnvironment(signals({ bundleUrl: url }))
       expect(r.distribution, `${url} 应判 dev`).toBe('dev')
@@ -160,48 +160,48 @@ describe('detectEnvironment distribution（bundle 路径三态）', () => {
 })
 
 describe('detectEnvironment dataDir 推导', () => {
-  it('托管：XYZ_AGENT_DATA_DIR 优先于 PI_CODING_AGENT_DIR 剥层', () => {
+  it('托管：TAIJI_AGENT_DATA_DIR 优先于 PI_CODING_AGENT_DIR 剥层', () => {
     const r = detectEnvironment(
       signals({
         env: {
-          [XYZ_AGENT_EXT_LOG_ENV]: '1',
-          [PI_CODING_AGENT_DIR_ENV]: '/data/.xyz-agent/pi/agent',
-          [XYZ_AGENT_DATA_DIR_ENV]: '/data/.xyz-agent',
+          [TAIJI_AGENT_EXT_LOG_ENV]: '1',
+          [PI_CODING_AGENT_DIR_ENV]: '/data/.taiji/pi/agent',
+          [TAIJI_AGENT_DATA_DIR_ENV]: '/data/.taiji',
         },
       }),
     )
-    expect(r.kind).toBe('xyz-agent')
-    expect(r.dataDir).toBe('/data/.xyz-agent')
-    expect(r.evidence.join('\n')).toContain(`来源：${XYZ_AGENT_DATA_DIR_ENV}`)
+    expect(r.kind).toBe('taiji')
+    expect(r.dataDir).toBe('/data/.taiji')
+    expect(r.evidence.join('\n')).toContain(`来源：${TAIJI_AGENT_DATA_DIR_ENV}`)
   })
 
   it('托管：无 DATA_DIR 时按布局剥层——新布局剥一层、旧布局剥两层', () => {
     const newLayout = detectEnvironment(
       signals({
         env: {
-          [XYZ_AGENT_EXT_LOG_ENV]: '1',
-          [PI_CODING_AGENT_DIR_ENV]: '/data/.xyz-agent/agent',
+          [TAIJI_AGENT_EXT_LOG_ENV]: '1',
+          [PI_CODING_AGENT_DIR_ENV]: '/data/.taiji/agent',
         },
       }),
     )
-    expect(newLayout.dataDir).toBe('/data/.xyz-agent')
+    expect(newLayout.dataDir).toBe('/data/.taiji')
 
     const oldLayout = detectEnvironment(
       signals({
         env: {
-          [XYZ_AGENT_EXT_LOG_ENV]: '1',
-          [PI_CODING_AGENT_DIR_ENV]: '/data/.xyz-agent/pi/agent',
+          [TAIJI_AGENT_EXT_LOG_ENV]: '1',
+          [PI_CODING_AGENT_DIR_ENV]: '/data/.taiji/pi/agent',
         },
       }),
     )
-    expect(oldLayout.dataDir).toBe('/data/.xyz-agent')
+    expect(oldLayout.dataDir).toBe('/data/.taiji')
   })
 
-  it('standalone：即使 XYZ_AGENT_DATA_DIR 被设置也恒 undefined', () => {
+  it('standalone：即使 TAIJI_AGENT_DATA_DIR 被设置也恒 undefined', () => {
     const r = detectEnvironment(
       signals({
         env: {
-          [XYZ_AGENT_DATA_DIR_ENV]: '/data/.xyz-agent',
+          [TAIJI_AGENT_DATA_DIR_ENV]: '/data/.taiji',
         },
       }),
     )
@@ -215,15 +215,15 @@ describe('detectEnvironment evidence', () => {
     ['全信号缺失', signals({})],
     ['托管全信号', signals({
       env: {
-        [XYZ_AGENT_EXT_LOG_ENV]: '1',
-        [PI_CODING_AGENT_DIR_ENV]: '/data/.xyz-agent/agent',
-        [XYZ_AGENT_DATA_DIR_ENV]: '/data/.xyz-agent',
+        [TAIJI_AGENT_EXT_LOG_ENV]: '1',
+        [PI_CODING_AGENT_DIR_ENV]: '/data/.taiji/agent',
+        [TAIJI_AGENT_DATA_DIR_ENV]: '/data/.taiji',
       },
       bundleUrl:
         'file:///Applications/TaiJi.app/Contents/Resources/extensions/@zhushanwen/pi-session-reader/index.mjs',
     })],
-    ['EXT_LOG 孤置', signals({ env: { [XYZ_AGENT_EXT_LOG_ENV]: '1' } })],
-    ['agentDir 孤置', signals({ env: { [PI_CODING_AGENT_DIR_ENV]: '/data/.xyz-agent/agent' } })],
+    ['EXT_LOG 孤置', signals({ env: { [TAIJI_AGENT_EXT_LOG_ENV]: '1' } })],
+    ['agentDir 孤置', signals({ env: { [PI_CODING_AGENT_DIR_ENV]: '/data/.taiji/agent' } })],
     ['bundleUrl 缺失', signals({})],
   ]
 
@@ -238,20 +238,20 @@ describe('detectEnvironment evidence', () => {
     const r = detectEnvironment(
       signals({
         env: {
-          [XYZ_AGENT_EXT_LOG_ENV]: '0',
-          [PI_CODING_AGENT_DIR_ENV]: '/data/.xyz-agent/pi/agent',
+          [TAIJI_AGENT_EXT_LOG_ENV]: '0',
+          [PI_CODING_AGENT_DIR_ENV]: '/data/.taiji/pi/agent',
         },
-        agentDir: '/data/.xyz-agent/pi/agent',
+        agentDir: '/data/.taiji/pi/agent',
       }),
     )
     const joined = r.evidence.join('\n')
     // 未命中信号：原文 + 未命中注记
-    expect(joined).toContain(`${XYZ_AGENT_EXT_LOG_ENV}='0' → 未命中`)
+    expect(joined).toContain(`${TAIJI_AGENT_EXT_LOG_ENV}='0' → 未命中`)
     // 命中信号：原文 + 匹配注记
-    expect(joined).toContain(`${PI_CODING_AGENT_DIR_ENV}='/data/.xyz-agent/pi/agent'`)
+    expect(joined).toContain(`${PI_CODING_AGENT_DIR_ENV}='/data/.taiji/pi/agent'`)
     expect(joined).toContain('形态匹配')
     // 第三条输入：agentDir 透传记录
-    expect(joined).toContain(`agentDir='/data/.xyz-agent/pi/agent'`)
+    expect(joined).toContain(`agentDir='/data/.taiji/pi/agent'`)
     // 判定结论行
     expect(joined).toContain('standalone-pi')
   })

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

@@ -596,6 +596,12 @@ describe('buildExecutionTree - fixture', () => {
     const tree2 = await buildExecutionTree(MAIN, dir)
     expect(tree2.root.sessionFile).toBeUndefined()
     expect(tree2.totalNodes).toBe(1)
+
+    // 空串哨兵归一：mainSessionFile=''（zcode family 路由反查未命中的降级形态）与
+    // 不传等价——root 节点 details 不携带 sessionFile:"" 这类非路径占位值
+    const tree3 = await buildExecutionTree(MAIN, dir, '')
+    expect(tree3.root.sessionFile).toBeUndefined()
+    expect(tree3.totalNodes).toBe(1)
   })
 
   it('TC-m3b-max-depth：21+ 层 parentRecordId 链在 MAX_DEPTH(20) 截断，truncated=true 不抛错（MF-4）', async () => {

package/src/__tests__/family-zcode.test.ts

@@ -0,0 +1,255 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { tmpdir } from 'node:os'
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import { DatabaseSync } from 'node:sqlite'
+
+import { buildFamilyIndex, resolveFamily, buildZcodeSubagentsByRoot } from '../core/family.js'
+import type { Entry, ZcodeFamilyNode } from '../core/family.js'
+import { listZcodeManifests } from '../discovery/zcode-manifest.js'
+
+// ============================================================
+// family zcode 分支（design session-reader-shared-core §3.3 D5-1 / §4 场景 2）。
+//
+// 判据（两项、不开库）：锚可解析（枚举谓词已过）∧ 库文件存在（stat）→ cleanedUp=false；
+// 缺一 → true（GC 语义，不报错不抛异常）。刻意不含「库内 session 查询」第三项——
+// 静息态 CANTOPEN 会误判活会话 + 列表视图不开库；反向断言（库文件在但库内 session
+// 行被删 → 仍 false）即「列表视图不开库」的分工声明断言。
+//
+// 与 pi 判据不同构（D5-1 显式声明）：pi = fileStats JSONL 存在性；zcode 节点无
+// JSONL 文件，按「库可达」判。pi 侧既有 fixture 行为零变化由 family.test.ts 全绿守卫
+// （本文件零改动 family.test.ts——更强的零涟漪证据）。
+// ============================================================
+
+const ROOT = 'root-session-1'
+
+let dir: string
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'family-zcode-test-'))
+})
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+})
+
+function header(id: string): Entry {
+  return { type: 'session', id, parentId: null, cwd: '/proj' }
+}
+
+/** zcode 节点（core 层判据输入，与 ZcodeManifestRecord 结构兼容） */
+function zcodeNode(opts: Partial<ZcodeFamilyNode> & { id: string }): ZcodeFamilyNode {
+  return {
+    rootSessionId: ROOT,
+    slug: 'worker',
+    dbPath: join(dir, 'db.sqlite'),
+    dbFileExists: false,
+    ...opts,
+  }
+}
+
+/** 在 <agentDir>/subagents/<slug>/records/ 下写 zcode manifest（F21 磁盘真实形态：无 sessionFile 键） */
+function writeZcodeManifest(
+  agentDir: string,
+  saId: string,
+  sessionRef: Record<string, string>,
+): void {
+  const recordsDir = join(agentDir, 'subagents', 'proj-a', 'records')
+  mkdirSync(recordsDir, { recursive: true })
+  writeFileSync(
+    join(recordsDir, `${saId}.json`),
+    JSON.stringify({
+      id: saId,
+      rootSessionId: ROOT,
+      agentName: 'worker',
+      status: 'running',
+      engine: 'zcode',
+      engineHandle: { sessionRef, poolKey: 'shared' },
+    }),
+    'utf8',
+  )
+}
+
+/** 造一个真实 sqlite 库（session/message/part 三级表先例形态）并插入 sess 行 */
+function createFixtureDb(dbPath: string, sessionId: string): void {
+  const db = new DatabaseSync(dbPath)
+  try {
+    db.exec('CREATE TABLE session (id TEXT PRIMARY KEY, title TEXT)')
+    db.exec('CREATE TABLE message (id TEXT PRIMARY KEY, session_id TEXT, sequence INTEGER)')
+    db.exec('CREATE TABLE part (id TEXT PRIMARY KEY, message_id TEXT, session_id TEXT)')
+    db.prepare('INSERT INTO session (id, title) VALUES (?, ?)').run(sessionId, 'fixture')
+  } finally {
+    db.close()
+  }
+}
+
+describe('core：buildZcodeSubagentsByRoot / buildFamilyIndex 的 zcode 分支（D5-1 两态）', () => {
+  it('库文件存在 → cleanedUp=false；库文件缺席 → cleanedUp=true（缺一即 true，不抛错）', () => {
+    const index = buildFamilyIndex([header(ROOT)], [], new Map(), [
+      zcodeNode({ id: 'sa-alive', dbFileExists: true }),
+      zcodeNode({ id: 'sa-gone', dbFileExists: false }),
+    ])
+    const family = resolveFamily(ROOT, index)
+
+    const alive = family.subagents.find((s) => s.sessionId === 'sa-alive')
+    const gone = family.subagents.find((s) => s.sessionId === 'sa-gone')
+    expect(alive?.cleanedUp).toBe(false)
+    expect(gone?.cleanedUp).toBe(true)
+  })
+
+  it('zcode 节点按 rootSessionId 挂载，隔代场景与 pi 同链合并（resolveFamily 消费同一 subagentsByRoot）', () => {
+    const FORK = 'fork-session-1'
+    const headers = [header(ROOT), { ...header(FORK), parentSession: `/s/_${ROOT}.jsonl` }]
+    const index = buildFamilyIndex(headers, [], new Map(), [
+      zcodeNode({ id: 'sa-deep', rootSessionId: FORK }),
+    ])
+    // Q1 隔代：zcode subagent 挂在 fork 子代下，从 ROOT resolve 仍可见
+    expect(resolveFamily(ROOT, index).subagents.map((s) => s.sessionId)).toContain('sa-deep')
+  })
+
+  it('不传 zcodeNodes / 传空数组 → pi 行为不变（零涟漪等价）', () => {
+    const piIdent: Entry = {
+      type: 'custom',
+      id: 'sa-pi',
+      parentId: null,
+      customType: 'subagent-identity',
+      data: { rootSessionId: ROOT, slug: 'pi-sub' },
+    }
+    const stats = new Map([[ROOT, { mtime: 1, size: 2 }], ['sa-pi', { mtime: 3, size: 4 }]])
+    const without = buildFamilyIndex([header(ROOT)], [piIdent], stats)
+    const withEmpty = buildFamilyIndex([header(ROOT)], [piIdent], stats, [])
+    const a = resolveFamily(ROOT, without)
+    const b = resolveFamily(ROOT, withEmpty)
+    expect(b.subagents).toEqual(a.subagents)
+    expect(b.subagents[0]?.cleanedUp).toBe(false) // pi 判据：fileStats 命中
+  })
+
+  it('zcode 节点与 pi 孤儿节点并存：判据互不污染（不同构声明断言）', () => {
+    // pi 孤儿：identity 在但 fileStats 不含 → cleanedUp=true（JSONL GC）
+    const piOrphan: Entry = {
+      type: 'custom',
+      id: 'sa-pi-orphan',
+      parentId: null,
+      customType: 'subagent-identity',
+      data: { rootSessionId: ROOT, slug: 'orphan' },
+    }
+    const index = buildFamilyIndex([header(ROOT)], [piOrphan], new Map(), [
+      zcodeNode({ id: 'sa-zcode-gone', dbFileExists: false }),
+    ])
+    const subs = resolveFamily(ROOT, index).subagents
+    // 两节点都 cleanedUp=true，但判据来源不同：pi 走 fileStats，zcode 走 dbFileExists
+    expect(subs.find((s) => s.sessionId === 'sa-pi-orphan')?.cleanedUp).toBe(true)
+    expect(subs.find((s) => s.sessionId === 'sa-zcode-gone')?.cleanedUp).toBe(true)
+  })
+
+  it('SubagentRef 字段映射：富字段透传、sessionFile 不设、mtime/sizeBytes 占位 0', () => {
+    const byRoot = buildZcodeSubagentsByRoot([
+      zcodeNode({
+        id: 'sa-rich',
+        slug: 'rich-slug',
+        agentName: 'explorer',
+        task: 'do research',
+        model: 'glm-5.3',
+        status: 'closed',
+        dbFileExists: true,
+      }),
+    ])
+    const ref = byRoot.get(ROOT)?.[0]
+    expect(ref?.slug).toBe('rich-slug')
+    expect(ref?.agentName).toBe('explorer')
+    expect(ref?.task).toBe('do research')
+    expect(ref?.model).toBe('glm-5.3')
+    expect(ref?.status).toBe('closed')
+    expect(ref?.sessionFile).toBeUndefined() // zcode 无 session.jsonl
+    expect(ref?.mtime).toBe(0)
+    expect(ref?.sizeBytes).toBe(0)
+  })
+})
+
+describe('集成：listZcodeManifests → buildFamilyIndex → resolveFamily（场景 2 两态 + 反向断言）', () => {
+  it('库可达态（dbPath 指向真实 fixture 库）→ cleanedUp=false', async () => {
+    const dbPath = join(dir, 'isolated.sqlite')
+    createFixtureDb(dbPath, 'sess_live')
+    writeZcodeManifest(dir, 'sa-live', { sessionId: 'sess_live', dbPath })
+
+    const nodes = await listZcodeManifests(dir)
+    expect(nodes).toHaveLength(1)
+    expect(nodes[0]?.dbFileExists).toBe(true)
+
+    const family = resolveFamily(ROOT, buildFamilyIndex([header(ROOT)], [], new Map(), nodes))
+    const sub = family.subagents.find((s) => s.sessionId === 'sa-live')
+    expect(sub?.cleanedUp).toBe(false)
+  })
+
+  it('库不存在态（dbPath 指向不存在路径）→ cleanedUp=true（GC 语义，不报错）', async () => {
+    writeZcodeManifest(dir, 'sa-gone', {
+      sessionId: 'sess_gone',
+      dbPath: join(dir, 'subagents', 'proj-a', 'missing.sqlite'),
+    })
+
+    const nodes = await listZcodeManifests(dir)
+    expect(nodes[0]?.dbFileExists).toBe(false)
+
+    const family = resolveFamily(ROOT, buildFamilyIndex([header(ROOT)], [], new Map(), nodes))
+    expect(family.subagents.find((s) => s.sessionId === 'sa-gone')?.cleanedUp).toBe(true)
+  })
+
+  it('反向断言：库文件在但库内 session 行被删 → 仍 cleanedUp=false（列表视图不开库的分工声明）', async () => {
+    // 分工（D5-1）：库内 session 已被 zcode GC 的情形由 read 路径 zcode_session_not_found
+    // 权威承接；family 只 stat 文件存在性。本用例删行留文件，断言 family 不受库内容影响。
+    const dbPath = join(dir, 'gc.sqlite')
+    createFixtureDb(dbPath, 'sess_victim')
+    writeZcodeManifest(dir, 'sa-gced', { sessionId: 'sess_victim', dbPath })
+
+    // 前置核实：fixture 库里确实有该 session 行（反向断言的非平凡性前提）
+    {
+      const db = new DatabaseSync(dbPath)
+      try {
+        const row = db.prepare('SELECT COUNT(*) AS c FROM session WHERE id = ?').get('sess_victim') as
+          | { c: number }
+          | undefined
+        expect(row?.c).toBe(1)
+      } finally {
+        db.close()
+      }
+    }
+
+    // 删库内 session 行（含 message/part 级联），db 文件保留
+    {
+      const db = new DatabaseSync(dbPath)
+      try {
+        db.prepare('DELETE FROM part WHERE session_id = ?').run('sess_victim')
+        db.prepare('DELETE FROM message WHERE session_id = ?').run('sess_victim')
+        db.prepare('DELETE FROM session WHERE id = ?').run('sess_victim')
+      } finally {
+        db.close()
+      }
+    }
+
+    const nodes = await listZcodeManifests(dir)
+    expect(nodes[0]?.dbFileExists).toBe(true) // 只 stat：文件在即 true，不看内容
+
+    const family = resolveFamily(ROOT, buildFamilyIndex([header(ROOT)], [], new Map(), nodes))
+    expect(family.subagents.find((s) => s.sessionId === 'sa-gced')?.cleanedUp).toBe(false)
+  })
+
+  it('坏 manifest 与缺库节点混排 → 好节点照常输出（单节点不可达不炸整屏）', async () => {
+    const dbPath = join(dir, 'ok.sqlite')
+    createFixtureDb(dbPath, 'sess_ok')
+    writeZcodeManifest(dir, 'sa-ok', { sessionId: 'sess_ok', dbPath })
+    // 缺库节点：合法 zcode 形态（dbFileExists=false，不抛错），不剔除出列表
+    writeZcodeManifest(dir, 'sa-broken-manifest', { sessionId: 'sess_x', dbPath: '/nonexistent/x.sqlite' })
+    // 坏 JSON manifest：枚举跳过（不中断）
+    writeFileSync(
+      join(dir, 'subagents', 'proj-a', 'records', 'sa-corrupt.json'),
+      '{{{broken',
+      'utf8',
+    )
+
+    const nodes = await listZcodeManifests(dir)
+    expect(nodes.map((n) => n.id).sort()).toEqual(['sa-broken-manifest', 'sa-ok'])
+
+    const family = resolveFamily(ROOT, buildFamilyIndex([header(ROOT)], [], new Map(), nodes))
+    expect(family.subagents.find((s) => s.sessionId === 'sa-ok')?.cleanedUp).toBe(false)
+    expect(family.subagents.find((s) => s.sessionId === 'sa-broken-manifest')?.cleanedUp).toBe(true)
+  })
+})

package/src/__tests__/family.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect } from 'vitest'
 import { buildFamilyIndex, resolveFamily } from '../core/family.js'
-import type { Entry } from '../core/parser.js'
+import type { Entry } from '@zhushanwen/session-core'
 
 // ---- fixture 常量（映射 design §3.3 D-7 Q1 真实场景）----
 const ROOT = '019fe620' // 家族根（无 parentSession）

package/src/__tests__/find.test.ts

@@ -186,6 +186,29 @@ describe('findSessions', () => {
     expect(matches[0].cwd).toBe('/proj-a')
   })
 
+  it('缺 cwd 的 header 进候选集（谓词不统一负面锚，design §4 负面行为验证）', async () => {
+    // header 行只有 id（无 cwd/timestamp）：runtime 导入侧「id+cwd 非空」严谓词会拒收，
+    // reader 宽谓词（仅要求 type==='session' ∧ id 为 string）必须照常收录——基座化
+    // （readFirstJsonlLine 改指 session-core）不得顺手统一谓词，本用例即机器锚。
+    const headerPath = join(slugDir, 'no-cwd.jsonl')
+    await mkdir(slugDir, { recursive: true })
+    await writeFile(headerPath, JSON.stringify({ type: 'session', id: '019e0001-no-cwd' }) + '\n')
+    await makeSession(slugDir, { name: 'with-cwd.jsonl', id: '019e0002-with-cwd', cwd: '/demo' })
+
+    // find 结果：缺 cwd header 命中，cwd 归一化为空串（buildCandidate 的 header.cwd ?? ''）
+    const { matches } = await findSessions('no-cwd', agentDir)
+    expect(matches).toHaveLength(1)
+    expect(matches[0].sessionId).toBe('019e0001-no-cwd')
+    expect(matches[0].cwd).toBe('')
+
+    // 候选枚举（recent 路径枚举全部候选）：缺 cwd header 未被候选集排除
+    const recent = await findSessions('recent', agentDir)
+    expect(recent.matches.map((m) => m.sessionId).sort()).toEqual([
+      '019e0001-no-cwd',
+      '019e0002-with-cwd',
+    ])
+  })
+
   it('limit 截断：truncated 标记正确', async () => {
     // 5 个文件 id 都含 "common"，uuid 片段 "common" 全匹配
     for (let i = 0; i < 5; i++) {
@@ -578,7 +601,7 @@ describe('findSessions', () => {
 describe('u11 标题元数据（metadataProvider 注入，§6.6）', () => {
   let root: string
   let agentDir: string
-  /** 平铺 main 根（xyz-agent 形态：session 直在 sessions/ 下，[default] 根无子目录） */
+  /** 平铺 main 根（taiji 形态：session 直在 sessions/ 下，[default] 根无子目录） */
   let flatMain: string
   /** legacy 根（dirname(agentDir)/sessions） */
   let legacyDir: string

package/src/__tests__/index.test.ts

@@ -169,7 +169,7 @@ describe('sessionReaderExtension - execute 信号包采集（U3：ctx 全形态
   })
 
   it('u11：execute 构造 metadataProvider 接 SessionManager.listAll——keyword 标题命中端到端', async () => {
-    // fixture：平铺 main 根（xyz-agent 形态），session 首消息不含 query，标题经 mock listAll 注入
+    // fixture：平铺 main 根（taiji 形态），session 首消息不含 query，标题经 mock listAll 注入
     const tmp = await mkdtemp(join(tmpdir(), 'index-u11-'))
     try {
       const agentDir = join(tmp, 'agent')

package/src/__tests__/parser.test.ts

@@ -1,6 +1,5 @@
 import { describe, it, expect } from 'vitest'
-import { parseSessionContent, parseSessionFile } from '../core/parser.js'
-import type { Entry } from '../core/parser.js'
+import { parseSessionContent, parseSessionFile, type Entry } from '@zhushanwen/session-core'
 import { REAL_SESSION, HAS_REAL_SESSION } from './real-data.js'
 
 /** 构造单行 JSONL entry 字符串 */

package/src/__tests__/real-data.ts

@@ -1,5 +1,6 @@
 import { existsSync } from 'node:fs'
 import { execSync } from 'node:child_process'
+import { homedir } from 'node:os'
 import { join } from 'node:path'
 
 /**
@@ -13,8 +14,8 @@ import { join } from 'node:path'
  * 本文件无 .test.ts 后缀，vitest include 只收集 `src/__tests__/` 下以 .test.ts 结尾的文件，不收集本文件。
  */
 
-/** 真实 pi agent 目录（本机），用于集成测试。 */
-export const REAL_AGENT_DIR = '/Users/zhushanwen/.pi/agent'
+/** 真实 pi agent 目录（pi 官方家目录布局，随宿主 homedir 推导），用于集成测试。 */
+export const REAL_AGENT_DIR = join(homedir(), '.pi', 'agent')
 
 /**
  * 全量扫描类真实数据用例的统一超时标定（90s）。
@@ -31,13 +32,25 @@ export const E6 = '019e6c96-0a0c-74b8-a73f-d1854d88e2a7'
 /** 真实 fork 家族根（fork 子代 019fe632，隔代 subagent 019fe635 挂在 019fe632 下）。 */
 export const FAM = '019fe620-8ae1-78a7-b76a-43a1ba4cc3c7'
 
-/** E6 的完整文件路径（parser/turns/render 直接 parseSessionFile 用）。 */
-export const REAL_SESSION = join(
-  REAL_AGENT_DIR,
-  'sessions',
-  '--Users-zhushanwen-Code-xyz-agent-workspace-feat-plugin-arch-3--',
-  `2026-05-28T03-17-12-844Z_${E6}.jsonl`,
-)
+/**
+ * E6 的完整文件路径（parser/turns/render 直接 parseSessionFile 用）。
+ * 按 sid 运行时定位而非硬编码宿主 workspace 目录名：真实文件挂在哪个 slug 目录随采集机器而异，
+ * 硬编码会绑死本机路径形态；定位不到时回落相对布局，由下方 HAS_REAL_SESSION 守卫 skip。
+ */
+export const REAL_SESSION = (() => {
+  const fallback = join(REAL_AGENT_DIR, 'sessions', `2026-05-28T03-17-12-844Z_${E6}.jsonl`)
+  if (!existsSync(REAL_AGENT_DIR)) return fallback
+  try {
+    return (
+      execSync(
+        `find ${REAL_AGENT_DIR}/sessions -name '*${E6}*' -name '*.jsonl' ! -name '*.finalized' 2>/dev/null | head -1`,
+        { encoding: 'utf8' },
+      ).trim() || fallback
+    )
+  } catch {
+    return fallback
+  }
+})()
 
 /** 同步探测真实 session 文件是否存在（不存在则 skip，避免在无该数据的机器上硬失败）。 */
 export function hasRealSession(sid: string): boolean {

package/src/__tests__/render.test.ts

@@ -1,9 +1,8 @@
 import { describe, it, expect } from 'vitest'
 import { renderOutline, renderExpand, renderDetail, type ToolResultSummaryEntry } from '../core/render.js'
-import type { Entry } from '../core/parser.js'
+import { parseSessionFile, type Entry } from '@zhushanwen/session-core'
 import type { Turn } from '../core/turns.js'
 import type { TreeView } from '../core/tree.js'
-import { parseSessionFile } from '../core/parser.js'
 import { buildTreeView } from '../core/tree.js'
 import { segmentTurns } from '../core/turns.js'
 import { REAL_SESSION, HAS_REAL_SESSION } from './real-data.js'