@zhushanwen/pi-session-reader 0.6.0 → 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,9 +1,9 @@
 {
   "name": "@zhushanwen/pi-session-reader",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "main": "index.ts",
-  "xyz-agent": {
+  "taiji": {
     "role": "universal"
   },
   "pi": {
@@ -16,12 +16,15 @@
     "pi-package"
   ],
   "dependencies": {
-    "@zhushanwen/pi-ext-guards": "0.4.0"
+    "@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.1"
+    "@zhushanwen/subagent-core": "0.11.1"
   },
   "files": [
     "index.ts",

package/src/__tests__/cross-package-subagent-core.test.ts

@@ -20,20 +20,21 @@ import {
 } from '@zhushanwen/subagent-core/execution/assembly/path-encoding.ts'
 
 /**
- * W4 跨包集成测试（subagent-sync-collect v2 impl-plan W4 验收条款①，设计 §5 W4：
- * 「subagent-core 真实 tmpdir 产出磁盘状态 → session-reader result action sa- id 反查，
- * 不 mock manifest 写入」）。
+ * W4 跨包集成测试（[collect 退役] 改造保留：原「E1 落标出口产出 manifest」驱动面
+ * 随 sync 批机制删除，现行真实投影出口 = store 重建通道 rebuildIndexes——manifest
+ * 是可丢缓存，boot 全量腿按磁盘子文件锚幂等补缺）。「subagent-core 真实 tmpdir
+ * 产出磁盘状态 → session-reader result action sa- id 反查，不 mock manifest 写入」
+ * 的跨包契约保持不变。
  *
- * 与 result.test.ts 的分工：result.test.ts 的 fixture **手工预写** manifest（U6 时期
- * W3 投影代码尚不存在）；本文件 manifest 内容必须来自 v2 W3 的投影代码路径——
- * subagent-core 侧真实驱动 E1 崩溃恢复（kill -9 同构链路：真实 RecordStore 落盘
- * register/轮终 entry → initSession 内 orphan 覆写真实跑 → recoverSyncCollectBatch
- * 落标出口 appendBatchFinalizedEntry fire-and-forget 真写 records/<sa-id>.json），
- * session-reader 侧零 mock 读同一 tmpdir 断言反查闭环。
+ * 与 result.test.ts 的分工：result.test.ts 的 fixture **手工预写** manifest；本文件
+ * manifest 内容必须来自投影代码路径——subagent-core 侧真实驱动（真实 RecordStore
+ * 落盘 register/轮终 entry → initSession 内 orphan 覆写真实跑 → rebuildIndexes
+ * derivedManifestRecord 投影真写 records/<sa-id>.json），session-reader 侧零 mock
+ * 读同一 tmpdir 断言反查闭环。
  *
  * 构造形态取自 subagent-core sync-collect-recovery.test.ts 的 kill -9 同构主用例
- * （W1 领地，形态同构是 v1 教训「种子绕过真实链路 = 假绿」的执行）：子 session 文件
- * 在其基础上补 message entries（result action 的正文提取源）。
+ * （形态同构是 v1 教训「种子绕过真实链路 = 假绿」的执行）：子 session 文件在其
+ * 基础上补 message entries（result action 的正文提取源）。
  *
  * mock 面最小：仅构造 SubagentService 所需的最小 pi 形状（appendEntry 真写主文件，
  * 其余 no-op stub）——零 vi.mock、notifier/store/config 全真实实现，agentDir 全部
@@ -48,9 +49,9 @@ const ENV_KEYS_TO_STRIP = [
   'PI_SUBAGENT_DEPTH',
   'PI_SUBAGENT_ROOT_CWD',
   'PI_SUBAGENT_FORK_DEPTH',
-  'XYZ_SUBAGENT_RELAY_SOCKET',
-  'XYZ_SUBAGENT_RELAY_NODE',
-  'XYZ_SUBAGENT_RELAY_SCRIPT',
+  'TAIJI_SUBAGENT_RELAY_SOCKET',
+  'TAIJI_SUBAGENT_RELAY_NODE',
+  'TAIJI_SUBAGENT_RELAY_SCRIPT',
 ] as const
 
 const ROOT_SESSION = 'root-cross-pkg'
@@ -102,8 +103,6 @@ function memberRecord(overrides: Partial<SubagentRecord> & { id: string }): Suba
     result: undefined,
     error: undefined,
     sessionFile: undefined,
-    chatMode: false,
-    collectMode: 'sync',
     ...overrides,
   }
 }
@@ -118,7 +117,7 @@ interface MemberSeed {
   model: string
 }
 
-describe('跨包集成：subagent-core E1 落标 manifest → session-reader result 反查（W4）', () => {
+describe('跨包集成：subagent-core 重建 manifest → session-reader result 反查（W4）', () => {
   let agentDir: string
   let mainFile: string
   let services: SubagentService[]
@@ -224,21 +223,11 @@ describe('跨包集成：subagent-core E1 落标 manifest → session-reader res
     )
   }
 
-  /** 手写短轮询（真实 timers，vitest 4.1.8 vi.waitFor 对 falsy callback 不轮询——
-   *  subagent-core 同款纪律）：manifest 为 fire-and-forget 异步写，需轮询等落盘。 */
-  async function until(cond: () => boolean, timeoutMs = 3000): Promise<void> {
-    const start = Date.now()
-    while (!cond()) {
-      if (Date.now() - start > timeoutMs) {
-        throw new Error(`cross-pkg: condition not met within ${timeoutMs}ms`)
-      }
-      await new Promise((resolve) => setTimeout(resolve, 10))
-    }
-  }
-
-  /** 全链路驱动：种子 → 恢复 service（orphan 覆写）→ E1（落标出口真写 manifest）。
-   *  返回子 session 文件路径表。 */
-  async function driveSyncBatchRecovery(members: MemberSeed[]): Promise<Map<string, string>> {
+  /** 全链路驱动：种子 → 恢复 service（orphan 覆写）→ rebuildIndexes（现行 boot
+   *  全量重建通道——derivedManifestRecord 投影真写 manifest）。返回子 session 文件
+   *  路径表。[collect 退役] 原 E1 落标出口（recoverSyncCollectBatch →
+   *  appendBatchFinalizedEntry）随 sync 批机制删除。 */
+  async function driveManifestRebuild(members: MemberSeed[]): Promise<Map<string, string>> {
     const childFiles = new Map<string, string>()
     for (const m of members) {
       const childFile = writeChildSessionFile(m)
@@ -246,12 +235,15 @@ describe('跨包集成：subagent-core E1 落标 manifest → session-reader res
       seedRoundTerminalEntries(m, childFile)
     }
     const service = makeRecoveryService()
-    service.recoverSyncCollectBatch()
-    // E1 落标出口 appendBatchFinalizedEntry 的 manifest 是 fire-and-forget best-effort
-    // 写——轮询等全部成员 manifest 真实落盘（W3 投影代码路径的产物）。
-    await until(() =>
-      members.every((m) => fs.existsSync(path.join(getSubagentRecordsDir(agentDir, agentDir), `${m.id}.json`))),
-    )
+    service.rebuildIndexes()
+    // derivedManifestRecord 投影为同步落盘——全成员 manifest 即刻可见（W3 投影
+    // 代码路径的产物，非手工预写）。
+    for (const m of members) {
+      expect(
+        fs.existsSync(path.join(getSubagentRecordsDir(agentDir, agentDir), `${m.id}.json`)),
+        `manifest of ${m.id}`,
+      ).toBe(true)
+    }
     return childFiles
   }
 
@@ -263,12 +255,12 @@ describe('跨包集成：subagent-core E1 落标 manifest → session-reader res
       assistantParts: ['part one', 'part two'],
       model: 'prov/round-m',
     }
-    const childFiles = await driveSyncBatchRecovery([m])
+    const childFiles = await driveManifestRebuild([m])
 
-    // manifest 内容断言（W3 appendBatchFinalizedEntry 投影路径的产物，非手工预写）：
-    // sessionFile 来自 W1 投影扩展。[U2/U3 两态桥接] E1 落标成员经恢复链覆写后处于
-    // idle（重建单规则）/running 形态、无旧终态遗留位 → legacy status 如实投影
-    // "running"（batchManifestRecord 单点派生，session-reader 视角的活跃成员）。
+    // manifest 内容断言（rebuildIndexes → derivedManifestRecord 投影路径的产物，
+    // 非手工预写）：sessionFile 来自 W1 投影扩展。[U2/U3 两态桥接] 恢复链覆写后成员
+    // 处于 idle（重建单规则）、无旧终态遗留位 → legacy status 如实投影 "running"
+    //（legacyManifestStatusFields 单点派生，session-reader 视角的活跃成员）。
     const manifest = JSON.parse(
       fs.readFileSync(path.join(getSubagentRecordsDir(agentDir, agentDir), 'sa-cross-1.json'), 'utf-8'),
     ) as Record<string, unknown>
@@ -303,7 +295,7 @@ describe('跨包集成：subagent-core E1 落标 manifest → session-reader res
       { id: 'sa-cross-a', resultText: 'alpha final answer', assistantParts: ['alpha final answer'], model: 'prov/ma' },
       { id: 'sa-cross-b', resultText: 'beta final answer', assistantParts: ['beta final answer'], model: 'prov/mb' },
     ]
-    await driveSyncBatchRecovery(members)
+    await driveManifestRebuild(members)
 
     const r = await handleSessionRead({ action: 'result', session: 'sa-cross-a,sa-cross-b' }, { agentDir })
     const text = r.content[0]?.text ?? ''

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')
+  })
+})