@zhushanwen/pi-session-reader 0.6.1 → 0.7.0

package/README.md

@@ -0,0 +1,100 @@
+# @zhushanwen/pi-session-reader
+
+按语义结构读取 pi session 文件（对话历史）的工具：`session_read` 提供 11 个 action，覆盖 session 定位、fork/subagent/workflow 家族追踪、渐进式阅读（概览 → 单 turn → 全文）、全文/跨 session 搜索、素材提取、workflow run 概览、subagent 结果获取与环境自检——不需要直接读原始 `.jsonl`。
+
+## 提供的工具
+
+### `session_read`
+
+所有 action 共用一套参数，按 action 取用：
+
+| action | 关键参数 | 用途 |
+|--------|---------|------|
+| `find` | `query`（uuid 片段 / 文件名 / name 关键词 / `"recent"`） | 定位 session；可选 `cwd` / `source`（`main` / `subagent`）/ `limit`（默认 20）；零匹配返回提示不报错 |
+| `family` | `session` | fork 父子 / subagent / workflow 关系；`recursive: true` 返回任意深度嵌套的执行树 |
+| `outline` | `session` | turn 级概览（约 1500 token）；`granularity: "entry"` 平铺到 entry、`allBranches` 含废弃侧分支 |
+| `expand` | `session` + `turn`（如 `"T013"`） | 单 turn 的 entry 列表 |
+| `detail` | `session` + `turns`（如 `"T013-T015"` 或 `"T013"`） | turn 全文；`includeToolResult` / `includeThinking` 控制是否包含噪音（默认省略） |
+| `search` | `session` + `pattern` | 全文 grep（子串或正则）；`session` 可传逗号分隔 ≤10 个完整 id 做跨 session 搜索；`scope` 过滤 `all`（默认）/ `user` / `assistant` / `toolResult` |
+| `export` | `session` | 物化到文件；`format`: `outline`（默认）/ `full` / `family`；`includeToolResult` / `allBranches` 亦作用于本 action |
+| `extract` | `session` + `what` | 按类型抽取素材：`user-messages` / `commands` / `files` / `commits` / `tool-results`；`tool` 按工具名过滤 commands/tool-results；可选 `turns` 限定范围（按全量分段序号，含 compaction 周期/旁支，与 outline 的 leaf turn 序号不一致） |
+| `workflow` | `session` | workflow run 概览（status / budget / steps）；`runId` 聚焦单个 run；step 的 call sessionId 可跳转 outline/detail |
+| `result` | `session` | 取 subagent 最终结果正文（与其完成通知同内容）；单个 id 或逗号分隔 ≤10 个批量；`limit` 限每条字符数（默认 8000，超长截断并附全文文件指引） |
+| `doctor` | — | 环境自检：host 环境判定（纯 pi / taiji）+ 候选 session 根目录诊断；`includeSubagents: true` 附带扫描 subagent 根文件数 |
+
+`session` 参数支持四种形态：完整 uuid、uuid 片段（如 `e6c96`）、subagent record id（`sa-xxx` 精确反查）、`.jsonl` 绝对路径（支持 `~` 前缀）；`#` 前缀自动剥离。
+
+**渐进式阅读**：`outline`（概览）→ `expand`（单 turn）→ `detail`(全文)，默认省略 toolResult / thinking 噪音。不用于当前 session（宿主已提供当前会话访问），也不用于编辑 session（pi 有 `/resume` `/fork`）。
+
+## TUI 附加能力（仅 TUI 模式）
+
+- `/session-pick` 命令：交互式选择当前 cwd 目录下的 session
+- `#` 前缀自动补全：编辑器输入 `#` 弹出当前目录的 session 引用补全
+
+RPC 模式（如 taiji 子进程）自动跳过 TUI 注册，`session_read` 工具本身不受影响。
+
+## 核心机制
+
+- **分层**：`tool-handler.ts` 纯逻辑 handler（agentDir / 环境信号注入，零 pi 依赖，可单测）+ `index.ts` pi 注册层（registerTool + TUI 挂载）
+- **多根发现与降级**：session 根按 [live]（当前 session 目录）→ [default] → [legacy] 及 subagent 根多根合并扫描；`doctor` 可诊断实际生效的根
+- **session 解析三形态**：绝对路径直读首行 header → `sa-` 前缀经 record manifest 精确反查 → 片段模糊匹配（多匹配返回消歧候选列表而非报错）
+- **错误契约**：handler 抛出含 👉 恢复指引的 Error，pi 置 `isError: true`，模型可按指引一步修正重试
+- **成本控制**：标题元数据走 pi `SessionManager.listAll`（仅当前 cwd 目录，惰性调用）；search 长扫描可被 AbortSignal 中断
+
+## 安装
+
+```bash
+# npm 方式（正式）
+pi install npm:@zhushanwen/pi-session-reader
+```
+
+本地开发可用 `--extension` 直接加载：
+
+```bash
+pi --extension <repo>/extensions/universal/session-reader/index.ts "<prompt>"
+```
+
+## 使用示例
+
+```jsonc
+// 定位 session（片段匹配，多命中返回候选列表）
+{ "action": "find", "query": "e6c96" }
+
+// 概览 → 深读某段 turn
+{ "action": "outline", "session": "e6c96" }
+{ "action": "detail", "session": "e6c96", "turns": "T013-T015" }
+
+// 追踪 fork / subagent 家族（嵌套执行树）
+{ "action": "family", "session": "e6c96", "recursive": true }
+
+// 取 subagent 最终结果（批量 ≤10）
+{ "action": "result", "session": "sa-abc123, sa-def456" }
+
+// 跨 session 搜索用户消息
+{ "action": "search", "session": "<id1>,<id2>", "pattern": "登录逻辑", "scope": "user" }
+
+// 抽取全部 bash 命令
+{ "action": "extract", "session": "e6c96", "what": "commands", "tool": "bash" }
+
+// 环境自检
+{ "action": "doctor" }
+```
+
+## 文件结构
+
+```
+session-reader/
+├── index.ts              # 入口 — re-export src/index.ts
+└── src/
+    ├── index.ts          # pi 注册层（registerTool + promptGuidelines + TUI 命令/补全挂载）
+    ├── tool-handler.ts   # 纯逻辑 handler（action 分发 + session 解析 + 各 action 编排）
+    ├── search-across.ts  # search 管线（单 session / 跨 session）
+    ├── extract.ts        # extract 预设（user-messages/commands/files/commits/tool-results）
+    ├── result-action.ts  # result action（subagent 最终结果，批量 ≤10）
+    ├── doctor.ts         # doctor action（host 环境判定 + 根目录诊断）
+    ├── no-match.ts       # find 零匹配自检行
+    ├── handler-utils.ts  # 低层小工具（pad/err/stripHash/turn 解析等）
+    ├── core/             # 解析与渲染（parser / tree / turns / family / execution-tree / workflow / render / toolcall）
+    ├── discovery/        # session 发现（roots / find / subagents / workflows / env / session-header）
+    └── tui/              # TUI 挂载（session-pick 命令 + # 补全 provider）
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-session-reader",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "type": "module",
   "main": "index.ts",
   "taiji": {
@@ -16,12 +16,15 @@
     "pi-package"
   ],
   "dependencies": {
-    "@zhushanwen/pi-ext-guards": "0.4.1"
+    "@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"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.9",
     "vitest": "^4.1.8",
-    "@zhushanwen/subagent-core": "0.10.5"
+    "@zhushanwen/subagent-core": "0.11.1"
   },
   "files": [
     "index.ts",

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

@@ -0,0 +1,226 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+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 { findZcodeEntryAnchor, type ZcodeAnchor } from '../discovery/entry-anchor.js'
+
+// ============================================================
+// 变体 E（设计 §4 场景 1a）：manifest 缺席时 entry 兜底定位（F16 每轮覆写 → 取文件
+// 顺序末条，collectLastRecordEntries 同构）。
+//
+// 单元边界：本文件只测「定位」（sa-id → sessionRef 锚）；「读到 sess-B 行集内容」的
+// 库读取断言属 U9 集成测试（场景 1a 变体 E 全量断言），此处不引入 sqlite 依赖。
+// sess-A / sess-B 本身即两个可区分的锚值——取首条或合并的实现会直接失败。
+// ============================================================
+
+const DB_PATH = '/data/agent/engines/zcode/session-db/db.sqlite'
+
+let dir: string
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'entry-anchor-test-'))
+})
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+})
+
+/** subagent-record custom entry 行（顶层 id = entry id；data.id = record id 即 sa-id）。 */
+function recordLine(
+  entryId: string,
+  saId: string,
+  sessionRef: Record<string, string>,
+  v = 1,
+): string {
+  return JSON.stringify({
+    type: 'custom',
+    customType: 'subagent-record',
+    id: entryId,
+    parentId: null,
+    data: { v, id: saId, engine: 'zcode', engineHandle: { sessionRef, poolKey: 'shared' } },
+  })
+}
+
+/** pi 形态 message 行（真实感填充）。 */
+function messageLine(entryId: string, text: string): string {
+  return JSON.stringify({
+    type: 'message',
+    id: entryId,
+    parentId: null,
+    message: { role: 'user', content: text },
+  })
+}
+
+/** 缺 dbPath 的 sessionRef（pi record 形态：只有 sessionId 单键）。 */
+const REF_NO_DBPATH = { sessionId: 'sess-pi-x' }
+
+/** 缺 sessionId 的 sessionRef（半键）。 */
+const REF_NO_SESSION_ID = { dbPath: DB_PATH }
+
+function writeMainSession(name: string, lines: string[]): string {
+  mkdirSync(dir, { recursive: true })
+  const file = join(dir, name)
+  writeFileSync(file, lines.join('\n') + '\n', 'utf8')
+  return file
+}
+
+describe('变体 E：同 sa-id 多条 entry 取文件顺序末条（F16 覆写）', () => {
+  it('首条 sess-A / 末条 sess-B → 命中 sess-B 且 ≠ sess-A（取首条/合并必失败）', async () => {
+    const file = writeMainSession('main.jsonl', [
+      JSON.stringify({ type: 'session', id: 'main-1', cwd: '/tmp/proj' }),
+      messageLine('m1', 'dispatch subagent'),
+      recordLine('e1', 'sa-1', { sessionId: 'sess-A', dbPath: DB_PATH }),
+      messageLine('m2', 'round 1 done'),
+      recordLine('e2', 'sa-1', { sessionId: 'sess-B', dbPath: DB_PATH }),
+    ])
+
+    const anchor = await findZcodeEntryAnchor([file], 'sa-1')
+
+    // 非平凡断言：两个不同锚值使「末条 vs 首条」结果可区分
+    expect(anchor).toBeDefined()
+    expect(anchor?.sessionId).toBe('sess-B')
+    expect(anchor?.sessionId).not.toBe('sess-A')
+    expect(anchor?.dbPath).toBe(DB_PATH)
+  })
+
+  it('多条不同 sa-id 交错：只命中目标 id 的末条，不串锚', async () => {
+    const file = writeMainSession('main.jsonl', [
+      JSON.stringify({ type: 'session', id: 'main-1' }),
+      recordLine('e1', 'sa-1', { sessionId: 'sa1-r1', dbPath: DB_PATH }),
+      recordLine('e2', 'sa-2', { sessionId: 'sa2-r1', dbPath: DB_PATH }),
+      recordLine('e3', 'sa-1', { sessionId: 'sa1-r2', dbPath: DB_PATH }),
+      recordLine('e4', 'sa-2', { sessionId: 'sa2-r2', dbPath: DB_PATH }),
+      recordLine('e5', 'sa-1', { sessionId: 'sa1-r3', dbPath: DB_PATH }),
+    ])
+
+    expect((await findZcodeEntryAnchor([file], 'sa-1'))?.sessionId).toBe('sa1-r3')
+    expect((await findZcodeEntryAnchor([file], 'sa-2'))?.sessionId).toBe('sa2-r2')
+  })
+})
+
+describe('行级容错（best-effort，不因一行坏 JSON 失败整文件）', () => {
+  it('坏行穿插 + 末行半行：正常命中末条完整条目', async () => {
+    const file = writeMainSession('main.jsonl', [
+      JSON.stringify({ type: 'session', id: 'main-1' }),
+      'not-json-at-all{{{',
+      recordLine('e1', 'sa-1', { sessionId: 'sess-A', dbPath: DB_PATH }),
+      '{"type":"custom","customType":"subagent-record","data":{"broken"',
+    ])
+
+    const anchor = await findZcodeEntryAnchor([file], 'sa-1')
+    expect(anchor?.sessionId).toBe('sess-A')
+  })
+})
+
+describe('形状校验窄而严：缺键条目不算命中，继续找更早条目', () => {
+  it('末条 sessionRef 缺 dbPath → 命中更早的完整条目', async () => {
+    const file = writeMainSession('main.jsonl', [
+      JSON.stringify({ type: 'session', id: 'main-1' }),
+      recordLine('e1', 'sa-1', { sessionId: 'sess-EARLY', dbPath: DB_PATH }),
+      recordLine('e2', 'sa-1', REF_NO_DBPATH),
+    ])
+
+    const anchor = await findZcodeEntryAnchor([file], 'sa-1')
+    expect(anchor?.sessionId).toBe('sess-EARLY')
+  })
+
+  it('全部条目缺双键 → not-found（undefined）', async () => {
+    const file = writeMainSession('main.jsonl', [
+      JSON.stringify({ type: 'session', id: 'main-1' }),
+      recordLine('e1', 'sa-1', REF_NO_DBPATH),
+      recordLine('e2', 'sa-1', REF_NO_SESSION_ID),
+    ])
+
+    expect(await findZcodeEntryAnchor([file], 'sa-1')).toBeUndefined()
+  })
+
+  it('sessionRef 键为空串 → 不算命中（非空 string 才算锚）', async () => {
+    const file = writeMainSession('main.jsonl', [
+      JSON.stringify({ type: 'session', id: 'main-1' }),
+      recordLine('e1', 'sa-1', { sessionId: '', dbPath: DB_PATH }),
+      recordLine('e2', 'sa-1', { sessionId: 'sess-A', dbPath: '' }),
+    ])
+
+    expect(await findZcodeEntryAnchor([file], 'sa-1')).toBeUndefined()
+  })
+
+  it('data.v ≠ 1 的条目不算命中，更早 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),
+    ])
+
+    const anchor = await findZcodeEntryAnchor([file], 'sa-1')
+    expect(anchor?.sessionId).toBe('sess-A')
+    expect(anchor?.sessionId).not.toBe('sess-V2')
+  })
+})
+
+describe('无关条目不命中', () => {
+  it('非 subagent-record 的 custom entry、id 不匹配的 record 均跳过', async () => {
+    const todoLine = JSON.stringify({
+      type: 'custom',
+      customType: 'todo',
+      id: 't1',
+      parentId: null,
+      data: { v: 1, id: 'sa-1', engineHandle: { sessionRef: { sessionId: 'sess-TODO', dbPath: DB_PATH } } },
+    })
+    const file = writeMainSession('main.jsonl', [
+      JSON.stringify({ type: 'session', id: 'main-1' }),
+      todoLine,
+      recordLine('e1', 'sa-other', { sessionId: 'sess-OTHER', dbPath: DB_PATH }),
+    ])
+
+    expect(await findZcodeEntryAnchor([file], 'sa-1')).toBeUndefined()
+    expect((await findZcodeEntryAnchor([file], 'sa-other'))?.sessionId).toBe('sess-OTHER')
+  })
+})
+
+describe('候选文件列表：顺序回退 + 命中即止（越界语义由调用方承载）', () => {
+  it('前一候选未命中 → 后一候选命中', async () => {
+    const empty = writeMainSession('empty.jsonl', [JSON.stringify({ type: 'session', id: 's0' })])
+    const withAnchor = writeMainSession('with-anchor.jsonl', [
+      JSON.stringify({ type: 'session', id: 'main-2' }),
+      recordLine('e1', 'sa-1', { sessionId: 'sess-B', dbPath: DB_PATH }),
+    ])
+
+    const anchor: ZcodeAnchor | undefined = await findZcodeEntryAnchor([empty, withAnchor], 'sa-1')
+    expect(anchor?.sessionId).toBe('sess-B')
+  })
+
+  it('前一候选命中即止：不跨文件合并（后一候选的更新条目不覆盖）', async () => {
+    const first = writeMainSession('first.jsonl', [
+      JSON.stringify({ type: 'session', id: 'main-1' }),
+      recordLine('e1', 'sa-1', { sessionId: 'sess-A', dbPath: DB_PATH }),
+    ])
+    const second = writeMainSession('second.jsonl', [
+      JSON.stringify({ type: 'session', id: 'main-2' }),
+      recordLine('e2', 'sa-1', { sessionId: 'sess-B', dbPath: DB_PATH }),
+    ])
+
+    const anchor = await findZcodeEntryAnchor([first, second], 'sa-1')
+    expect(anchor?.sessionId).toBe('sess-A')
+    expect(anchor?.sessionId).not.toBe('sess-B')
+  })
+
+  it('候选不可读（不存在）→ 跳过继续，全不可读 → not-found', async () => {
+    const withAnchor = writeMainSession('with-anchor.jsonl', [
+      JSON.stringify({ type: 'session', id: 'main-1' }),
+      recordLine('e1', 'sa-1', { sessionId: 'sess-B', dbPath: DB_PATH }),
+    ])
+
+    expect((await findZcodeEntryAnchor([join(dir, 'missing.jsonl'), withAnchor], 'sa-1'))?.sessionId).toBe('sess-B')
+    expect(await findZcodeEntryAnchor([join(dir, 'missing.jsonl')], 'sa-1')).toBeUndefined()
+    expect(await findZcodeEntryAnchor([], 'sa-1')).toBeUndefined()
+  })
+})
+
+describe('协议字面量漂移守卫（跨包契约）', () => {
+  it('entry-anchor 本地 customType 字面量 === subagent-core 写侧单源', () => {
+    // 源码本地持有磁盘协议字符串（生产依赖面不引 subagent-core），此处锚定两侧同值
+    expect(SUBAGENT_RECORD_CUSTOM_TYPE).toBe('subagent-record')
+  })
+})

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++) {

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 字符串 */