@zhushanwen/pi-session-reader 0.6.1 → 0.8.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.8.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/session-core": "0.11.0",
+    "@zhushanwen/zcode-session-source": "0.2.1",
+    "@zhushanwen/pi-ext-guards": "0.4.2"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.9",
     "vitest": "^4.1.8",
-    "@zhushanwen/subagent-core": "0.10.5"
+    "@zhushanwen/subagent-core": "0.12.0"
   },
   "files": [
     "index.ts",

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

@@ -0,0 +1,370 @@
+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, SUBAGENT_RECORD_ENTRY_VERSION } 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 },
+  })
+}
+
+/**
+ * v2 终态条行（W1 D1：`{v:2, kind:"settled", id, engine?, engineHandle?, ...}`——
+ * 载荷形态对齐 subagent-core SubagentRecordSettledEntryData，锚取 engineHandle.sessionRef）。
+ */
+function v2SettledLine(
+  entryId: string,
+  saId: string,
+  opts: {
+    sessionRef?: Record<string, string>
+    engine?: string
+  } = {},
+): string {
+  const data: Record<string, unknown> = {
+    v: 2,
+    kind: 'settled',
+    id: saId,
+    status: 'idle',
+    stopReason: 'end_turn',
+    endedAt: 123,
+    turns: 1,
+    totalTokens: 10,
+    model: undefined,
+    thinkingLevel: undefined,
+  }
+  if (opts.engine !== undefined) data.engine = opts.engine
+  if (opts.sessionRef !== undefined) {
+    data.engineHandle = { sessionRef: opts.sessionRef, poolKey: 'shared' }
+  }
+  return JSON.stringify({
+    type: 'custom',
+    customType: 'subagent-record',
+    id: entryId,
+    parentId: null,
+    data,
+  })
+}
+
+/**
+ * v2 注册条行（`{v:2, kind:"registered", id, agent, task, ...}`——身份域字段，不携带
+ * engineHandle；设计 D1 裁决「sessionRef 双键取自终态条」，注册条目不是锚源）。
+ */
+function v2RegisteredLine(entryId: string, saId: string): string {
+  return JSON.stringify({
+    type: 'custom',
+    customType: 'subagent-record',
+    id: entryId,
+    parentId: null,
+    data: {
+      v: 2,
+      kind: 'registered',
+      id: saId,
+      agent: 'dev',
+      task: 't',
+      slug: 's',
+      origin: 'tool',
+      rootSessionId: 'root-1',
+      depth: 0,
+      startedAt: 1,
+    },
+  })
+}
+
+/** 缺 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 为认识的 v1/v2 之外的版本（future-v，如 3）不算命中，更早 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-V3', dbPath: DB_PATH }, 3),
+    ])
+
+    const anchor = await findZcodeEntryAnchor([file], 'sa-1')
+    expect(anchor?.sessionId).toBe('sess-A')
+    expect(anchor?.sessionId).not.toBe('sess-V3')
+  })
+})
+
+// ============================================================
+// v2 终态条锚定（W1 D1 版本门补齐：sessionRef 双键取自终态条）
+// ============================================================
+
+describe('v2 终态条锚定：kind="settled" + engineHandle.sessionRef 双键', () => {
+  it('v2 终态条完整锚（sessionRef 双键齐）→ 命中', async () => {
+    const file = writeMainSession('main.jsonl', [
+      JSON.stringify({ type: 'session', id: 'main-1' }),
+      messageLine('m1', 'dispatch'),
+      v2SettledLine('e1', 'sa-1', {
+        engine: 'zcode',
+        sessionRef: { sessionId: 'sess-V2A', dbPath: DB_PATH },
+      }),
+    ])
+
+    const anchor = await findZcodeEntryAnchor([file], 'sa-1')
+    expect(anchor).toBeDefined()
+    expect(anchor?.sessionId).toBe('sess-V2A')
+    expect(anchor?.dbPath).toBe(DB_PATH)
+  })
+
+  it('v2 注册条（kind="registered"，不携带 engineHandle）→ 不命中（锚只取自终态条）', async () => {
+    const file = writeMainSession('main.jsonl', [
+      JSON.stringify({ type: 'session', id: 'main-1' }),
+      v2RegisteredLine('e-reg', 'sa-1'),
+    ])
+
+    expect(await findZcodeEntryAnchor([file], 'sa-1')).toBeUndefined()
+  })
+
+  it('v1 快照条（早）+ v2 终态条（晚）→ 末条 v2 胜（末条锚定跨版本一致）', async () => {
+    const file = writeMainSession('main.jsonl', [
+      JSON.stringify({ type: 'session', id: 'main-1' }),
+      recordLine('e1', 'sa-1', { sessionId: 'sess-V1OLD', dbPath: DB_PATH }),
+      v2SettledLine('e2', 'sa-1', {
+        engine: 'zcode',
+        sessionRef: { sessionId: 'sess-V2NEW', dbPath: DB_PATH },
+      }),
+    ])
+
+    const anchor = await findZcodeEntryAnchor([file], 'sa-1')
+    expect(anchor?.sessionId).toBe('sess-V2NEW')
+    expect(anchor?.sessionId).not.toBe('sess-V1OLD')
+  })
+
+  it('v2 终态条锚残缺（缺 engineHandle）→ 不命中，更早 v1 完整条目仍可命中（缺键不遮蔽）', async () => {
+    const file = writeMainSession('main.jsonl', [
+      JSON.stringify({ type: 'session', id: 'main-1' }),
+      recordLine('e1', 'sa-1', { sessionId: 'sess-EARLY', dbPath: DB_PATH }),
+      v2SettledLine('e2', 'sa-1', { engine: 'zcode' }), // 无 sessionRef
+    ])
+
+    const anchor = await findZcodeEntryAnchor([file], 'sa-1')
+    expect(anchor?.sessionId).toBe('sess-EARLY')
+  })
+
+  it('v2 但 kind 不在词表（unknown-kind，非 registered/settled）→ 不命中', async () => {
+    const badKind = JSON.stringify({
+      type: 'custom',
+      customType: 'subagent-record',
+      id: 'e-bad',
+      parentId: null,
+      data: {
+        v: 2,
+        kind: 'migrated',
+        id: 'sa-1',
+        engineHandle: { sessionRef: { sessionId: 'sess-BAD', dbPath: DB_PATH }, poolKey: 'shared' },
+      },
+    })
+    const file = writeMainSession('main.jsonl', [
+      JSON.stringify({ type: 'session', id: 'main-1' }),
+      badKind,
+    ])
+
+    expect(await findZcodeEntryAnchor([file], 'sa-1')).toBeUndefined()
+  })
+})
+
+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')
+  })
+
+  it('entry-anchor 本地 v2 认识版本 === subagent-core 写侧单源（写侧再升版本本守卫先红）', () => {
+    expect(SUBAGENT_RECORD_ENTRY_VERSION).toBe(2)
+  })
+})

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

@@ -17,11 +17,9 @@ import { buildExecutionTree, formatExecutionTreeText, type ExecutionTreeNode } f
  * - TC-m3b-cycle-detection：workflow 指针环（A→B→A），visited Set 防环
  * - TC-m3b-single-node：单节点树（无后代，ES5）
  * - TC-m3b-source-priority：parentRecordId 三级数据源优先级（manifest>identity>flat，DM4）
- * - TC-m3b-real-data-guard：真实形态数据守卫（合成 fixture）。原直读本机 ~/.pi/agent 动态
- *   发现家族根（skipIf CI 无数据），真实数据演化后确定性红且触碰真实数据目录（TEST-STRATEGY
- *   红线），2026-09 数据面合成化：mkdtemp 临时目录仿真真实 agentDir 布局（时间戳前缀文件名 /
- *   新旧机制混合 / 孤儿 manifest / 坏 manifest / 外来家族），guard 语义不变——解析不抛错 /
- *   树非空 / 结构自洽，不锁 sourceMode 具体值
+ * - TC-m3b-real-data-guard：真实形态数据守卫（合成 fixture）：mkdtemp 临时目录仿真真实
+ *   agentDir 布局（时间戳前缀文件名 / 新旧机制混合 / 孤儿 manifest / 坏 manifest / 外来
+ *   家族），guard 语义断言——解析不抛错 / 树非空 / 结构自洽，不锁 sourceMode 具体值
  */
 
 // ---- fixture 常量（uuid 特征，互不为子串，满足 extractSessionIdFromFilename）----
@@ -596,6 +594,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 () => {
@@ -679,13 +683,9 @@ describe('buildExecutionTree - fixture', () => {
 })
 
 // ============================================================
-// 真实形态数据守卫（合成 fixture，2026-09 测试债修复）
+// 真实形态数据守卫（合成 fixture）：mkdtemp 临时目录仿真真实 agentDir 布局，
+// guard 语义断言（解析不抛错 / 树非空 / 结构自洽 / sourceMode 值域），不触碰真实数据目录。
 // ============================================================
-//
-// 原用例直读本机 ~/.pi/agent（execSync 探测 + findRealTreeRoot 扫真实 records 动态发现
-// 家族根，skipIf CI 无数据）：真实数据演化后确定性红（impl-plan 台账登记根因），且触碰
-// 真实数据目录违反 TEST-STRATEGY 红线。数据面合成化——mkdtemp 临时目录仿真真实 agentDir
-// 布局，guard 语义断言（解析不抛错 / 树非空 / 结构自洽 / sourceMode 值域）原样保留。
 
 describe('buildExecutionTree - 真实形态数据守卫（合成）', () => {
   let dir: string
@@ -698,7 +698,7 @@ describe('buildExecutionTree - 真实形态数据守卫（合成）', () => {
   })
 
   it('TC-m3b-real-data-guard：真实形态布局（时间戳文件名/新旧机制混合/孤儿 manifest/坏 manifest/外来家族）解析不抛错，树非空且结构自洽', async () => {
-    // 仿真真实 agentDir 数据形态（原直读本机 ~/.pi/agent，合成化后确定性可重跑）：
+    // 仿真真实 agentDir 数据形态（全部 mkdtemp 自建自删，确定性可重跑）：
     // - session 文件名带时间戳前缀（<ISO 时间戳>_<sessionId>.jsonl，真实 pi 落盘形态）
     // - 混合新旧机制：A 顶层（无 parentRecordId）→ B 嵌套（manifest.parentRecordId 精确链）；
     //   C 旧机制顶层（manifest/identity 均无 parentRecordId → flat 挂 main）