@zhushanwen/pi-session-reader 0.13.1 → 0.13.3

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

@@ -1,772 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
-import { tmpdir } from 'node:os'
-import { mkdtempSync, writeFileSync, mkdirSync, rmSync, existsSync, readFileSync } from 'node:fs'
-import { join, dirname } from 'node:path'
-import { DatabaseSync } from 'node:sqlite'
-import { Check } from 'typebox/value'
-
-import { handleSessionRead } from '../tool-handler.js'
-import {
-  SQLITE_DRIVER_UNSUPPORTED_MARK,
-  ZCODE_DB_MISSING_MARK,
-  zcodeReadErrorMessage,
-} from '../tool-format.js'
-import { SqliteUnreadableError } from '@zhushanwen/zcode-session-source'
-import sessionReaderExtension from '../index.js'
-import { setPiHandle } from '@zhushanwen/pi-extension-logger'
-
-// ============================================================
-// U9 路由 + 白名单闸 + 错误范围集成测试（design session-reader-shared-core
-// §3.1 三层定位链 / §3.4 七码 + 检查顺序三段递进 / §4 场景 1a 变体 M/E +
-// 场景 2 family + 场景 5 八类失败 + 场景 3 pi 零回归 + D4 schema 零变化）。
-//
-// fixture 骨架（mkdtemp 自建自删）：root/agent = agentDir（dirname = dataDir）、
-// root/engines/zcode/session-db/db.sqlite = 隔离库（白名单精确命中）、
-// root/live-sessions = liveSessionDir（entry 兜底候选根）、
-// root/agent/sessions = main 默认根（family/rootSession 视图的 header 来源）。
-//
-// 行集非平凡性：sess_aaa（ZASENTINEL）与 sess_bbb（ZBSENTINEL + ZZQFIXTURE +
-// toolCall 对 + compaction part）两个可区分行集——「取首条/合并/读错行集」的
-// 实现会直接失败。manifest 锚与 entry 锚刻意指向不同 session（变体 M 的
-// instrument：读到 manifest 的 sess_bbb 而非 entry 的 sess_aaa = 走对主路径）。
-// ============================================================
-
-const ISOLATED_DB_SEGMENTS = ['engines', 'zcode', 'session-db', 'db.sqlite']
-
-const SA_M = 'sa-fix1' // 变体 M / 八类失败主 sa-id
-const SA_E = 'sa-fix2' // 变体 E（manifest 缺位，entry 兜底）
-const SESS_A = 'sess_aaa'
-const SESS_B = 'sess_bbb'
-const ROOT_SESSION = 'root-session-1'
-const BASE_MS = 1758379200000
-
-let root: string
-let agentDir: string
-let dbPath: string
-let liveDir: string
-let appendEntries: ReturnType<typeof vi.fn>
-
-beforeEach(() => {
-  root = mkdtempSync(join(tmpdir(), 'zcode-routing-test-'))
-  agentDir = join(root, 'agent')
-  liveDir = join(root, 'live-sessions')
-  mkdirSync(agentDir, { recursive: true })
-  mkdirSync(liveDir, { recursive: true })
-  dbPath = join(root, ...ISOLATED_DB_SEGMENTS)
-  // 结构化日志捕获：logger.warn 走 appendEntry 通道（不进 LLM 可见部分——本文件同时
-  // 是「降级留痕不进 LLM 可见部分」契约的断言范围）。测试后清注入防跨文件泄漏。
-  appendEntries = vi.fn()
-  setPiHandle({ appendEntry: appendEntries } as unknown as Parameters<typeof setPiHandle>[0])
-})
-afterEach(() => {
-  setPiHandle(undefined)
-  rmSync(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
-})
-
-// ---------------------------------------------------------------------------
-// fixture builders
-// ---------------------------------------------------------------------------
-
-interface SessionRows {
-  id: string
-  title: string
-  messages: Array<{ id: string; role: string; parts: Array<Record<string, unknown>> }>
-}
-
-/** sess_aaa 行集：两轮对话，文本带 ZASENTINEL（entry 首条锚指向它）。 */
-function sessARows(): SessionRows {
-  return {
-    id: SESS_A,
-    title: 'sess A title',
-    messages: [
-      userMsg('m1', 0, '第一轮用户提问 ZASENTINEL 锚'),
-      assistantMsg('m2', 1, ['第一轮助手回答 ZASENTINEL']),
-      userMsg('m3', 2, '第二轮用户提问'),
-      assistantMsg('m4', 3, ['第二轮助手回答 ZASENTINEL']),
-    ],
-  }
-}
-
-/** sess_bbb 行集：两轮 + toolCall 对 + ZZQFIXTURE + compaction（manifest 锚指向它）。 */
-function sessBRows(): SessionRows {
-  return {
-    id: SESS_B,
-    title: 'sess B title',
-    messages: [
-      userMsg('m1', 0, '派发任务 ZZQFIXTURE 检索锚点'),
-      assistantMsg('m2', 1, [], {
-        toolPart: {
-          type: 'tool',
-          callID: 'tc-1',
-          tool: 'Bash',
-          state: { status: 'completed', input: { command: 'echo hi' }, output: 'hi' },
-        },
-        extraParts: [{ type: 'text', text: '工具执行完成', time: { start: BASE_MS + 20 } }],
-      }),
-      userMsg('m3', 2, '继续第二轮'),
-      assistantMsg('m4', 3, ['第二轮 ZBSENTINEL 收尾'], {
-        extraParts: [{ type: 'compaction', data: { trigger: 'auto' }, time: { start: BASE_MS + 40 } }],
-      }),
-    ],
-  }
-}
-
-function userMsg(id: string, seq: number, text: string): SessionRows['messages'][number] {
-  return {
-    id,
-    role: 'user',
-    parts: [{ type: 'text', text, time: { start: BASE_MS + seq * 10 } }],
-  }
-}
-
-function assistantMsg(
-  id: string,
-  seq: number,
-  texts: string[],
-  opts: { toolPart?: Record<string, unknown>; extraParts?: Array<Record<string, unknown>> } = {},
-): SessionRows['messages'][number] {
-  const parts: Array<Record<string, unknown>> = []
-  if (opts.toolPart) parts.push(opts.toolPart)
-  texts.forEach((t, i) => parts.push({ type: 'text', text: t, time: { start: BASE_MS + seq * 10 + i } }))
-  if (opts.extraParts) parts.push(...opts.extraParts)
-  parts.push({ type: 'step-finish', reason: 'stop', tokens: { input: 1, output: 1, total: 2 }, cost: 0 })
-  return { id, role: 'assistant', parts }
-}
-
-/**
- * 建真实 fixture 隔离库（WAL + session/message/part/schema_migration 四表，行形态 =
- * zcode-session-source helpers 同款宿主 schema 0.16.5 消费方子集）。
- * 测试进程跑 node（node:sqlite 可用）；生产读链的驱动选择在 source 包内。
- */
-function createZcodeDb(path: string, schemaVersion = '0.16.5', sessions: SessionRows[] = []): void {
-  mkdirSync(join(path, '..'), { recursive: true })
-  const db = new DatabaseSync(path)
-  try {
-    db.exec('PRAGMA journal_mode=WAL')
-    db.exec('BEGIN')
-    db.exec(
-      'CREATE TABLE session (id TEXT PRIMARY KEY, directory TEXT NOT NULL, title TEXT NOT NULL, ' +
-        "task_type TEXT NOT NULL DEFAULT 'interactive', time_created INTEGER NOT NULL, time_updated INTEGER NOT NULL)",
-    )
-    db.exec('CREATE TABLE message (id TEXT PRIMARY KEY, session_id TEXT NOT NULL, sequence INTEGER, data TEXT NOT NULL)')
-    db.exec('CREATE TABLE part (id TEXT PRIMARY KEY, message_id TEXT NOT NULL, session_id TEXT NOT NULL, sequence INTEGER, data TEXT NOT NULL)')
-    db.exec('CREATE TABLE schema_migration (id TEXT PRIMARY KEY, checksum TEXT NOT NULL, app_version TEXT, time_applied INTEGER NOT NULL)')
-    db.prepare('INSERT INTO schema_migration (id, checksum, app_version, time_applied) VALUES (?, ?, ?, ?)').run('0001_seed', 'x', schemaVersion, 1)
-    const insSession = db.prepare('INSERT INTO session (id, directory, title, task_type, time_created, time_updated) VALUES (?, ?, ?, ?, ?, ?)')
-    const insMessage = db.prepare('INSERT INTO message (id, session_id, sequence, data) VALUES (?, ?, ?, ?)')
-    const insPart = db.prepare('INSERT INTO part (id, message_id, session_id, sequence, data) VALUES (?, ?, ?, ?, ?)')
-    for (const [si, s] of sessions.entries()) {
-      insSession.run(s.id, '/tmp/fix', s.title, 'interactive', BASE_MS, BASE_MS + si * 10)
-      for (const [mi, m] of s.messages.entries()) {
-        insMessage.run(`${s.id}_${m.id}`, s.id, mi, JSON.stringify({ role: m.role, time: { created: BASE_MS + mi * 10 } }))
-        for (const [pi, p] of m.parts.entries()) {
-          insPart.run(`${s.id}_${m.id}_p${pi}`, `${s.id}_${m.id}`, s.id, pi, JSON.stringify(p))
-        }
-      }
-    }
-    db.exec('COMMIT')
-  } finally {
-    db.close()
-  }
-}
-
-/** zcode manifest（F21 磁盘真实形态：无 sessionFile 键）。 */
-function writeZcodeManifest(
-  saId: string,
-  opts: { sessionRef?: Record<string, string>; omitEngineHandle?: boolean; engine?: string | true } = {},
-): void {
-  // [session-store-layout-inversion D6/单新根] records 读侧 = 存储树分区固定位置
-  // <root>/<rootSid>/subagents/records/（旧根 <agentDir>/subagents 不再读写）。
-  const recordsDir = join(dirname(agentDir), 'ext-sessions', ROOT_SESSION, 'subagents', 'records')
-  mkdirSync(recordsDir, { recursive: true })
-  const m: Record<string, unknown> = {
-    id: saId,
-    rootSessionId: ROOT_SESSION,
-    agentName: 'worker',
-    task: 'fixture task',
-    status: 'running',
-  }
-  m.engine = opts.engine === undefined ? 'zcode' : opts.engine
-  if (!opts.omitEngineHandle) {
-    m.engineHandle = {
-      sessionRef: opts.sessionRef ?? { sessionId: SESS_B, dbPath },
-      poolKey: 'shared',
-    }
-  }
-  writeFileSync(join(recordsDir, `${saId}.json`), JSON.stringify(m), 'utf8')
-}
-
-/** subagent-record custom entry 行（U7 entry-anchor.test 同款形状）。 */
-function recordLine(entryId: string, saId: string, sessionRef: Record<string, string>): string {
-  return JSON.stringify({
-    type: 'custom',
-    customType: 'subagent-record',
-    id: entryId,
-    parentId: null,
-    data: {
-      v: 2, kind: 'settled', id: saId, status: 'idle', stopReason: 'completed', endedAt: BASE_MS + 1,
-      turns: 1, totalTokens: 10, engine: 'zcode', engineHandle: { sessionRef, poolKey: 'shared' },
-    },
-  })
-}
-
-/**
- * pi 形态的 subagent-record custom entry 行（回归 A1 instrument）：engine 键缺省 +
- * sessionRef 无 dbPath——subagent-core record-entry.ts 的 pi 派生视图形态（engineHandle
- * 可选、sessionRef 整体透传不枚举内部键；最小可信子集，跨包漂移由 entry-anchor.test 检查）。
- */
-function piRecordLine(entryId: string, saId: string): string {
-  return JSON.stringify({
-    type: 'custom',
-    customType: 'subagent-record',
-    id: entryId,
-    parentId: null,
-    data: {
-      // 登记 §3.3：条目范围 = v2 族——pi 形态 = 注册条（身份）+ 终态条（engineHandle 半键）。
-      v: 2,
-      kind: 'settled',
-      id: saId,
-      status: 'idle',
-      stopReason: 'completed',
-      endedAt: BASE_MS + 1,
-      turns: 1,
-      totalTokens: 10,
-      engineHandle: { sessionRef: { sessionId: SESS_A }, poolKey: 'shared' },
-    },
-  })
-}
-
-const HEADER_LINE = JSON.stringify({ type: 'session', id: 'main-session-1', cwd: '/proj' })
-const USER_LINE = JSON.stringify({
-  type: 'message',
-  id: 'u1',
-  parentId: null,
-  message: { role: 'user', content: [{ type: 'text', text: 'dispatch subagent' }] },
-})
-
-/** liveSessionDir 内的主 session 文件（entry 兜底候选）。 */
-function writeLiveMainSession(lines: string[]): void {
-  writeFileSync(join(liveDir, 'main-session.jsonl'), [HEADER_LINE, USER_LINE, ...lines].join('\n') + '\n', 'utf8')
-}
-
-/** main 默认根的 root session（family/rootSessionId 视图的 byId 素材）。 */
-function writeRootSessionFile(): void {
-  const sessionsDir = join(agentDir, 'sessions')
-  mkdirSync(sessionsDir, { recursive: true })
-  writeFileSync(
-    join(sessionsDir, `1700000000000_${ROOT_SESSION}.jsonl`),
-    JSON.stringify({ type: 'session', id: ROOT_SESSION, cwd: '/proj' }) + '\n',
-    'utf8',
-  )
-}
-
-/** pi manifest + pi subagent session 文件（pi 穿插断言用；engine 缺省 = pi 存量形态）。 */
-function writePiFixture(): void {
-  const subDir = join(dirname(agentDir), 'ext-sessions', ROOT_SESSION, 'subagents', 'sessions')
-  mkdirSync(subDir, { recursive: true })
-  const piSession = join(subDir, '019e6c96-pi-sub-agent-00000000004a4.jsonl')
-  writeFileSync(
-    piSession,
-    [
-      JSON.stringify({ type: 'session', id: '019e6c96-pi-sub-agent-00000000004a4', cwd: '/proj' }),
-      JSON.stringify({ type: 'message', id: 'p1', parentId: null, message: { role: 'user', content: [{ type: 'text', text: 'pi task' }] } }),
-      JSON.stringify({ type: 'message', id: 'p2', parentId: 'p1', message: { role: 'assistant', content: [{ type: 'text', text: 'PI-SENTINEL 正文内容' }] } }),
-    ].join('\n') + '\n',
-    'utf8',
-  )
-  const recordsDir = join(dirname(agentDir), 'ext-sessions', ROOT_SESSION, 'subagents', 'records')
-  mkdirSync(recordsDir, { recursive: true })
-  writeFileSync(
-    join(recordsDir, 'sa-pi-1.json'),
-    JSON.stringify({
-      id: 'sa-pi-1',
-      rootSessionId: ROOT_SESSION,
-      agentName: 'pi-agent',
-      sessionFile: piSession,
-      slug: 'pi-sub',
-      status: 'completed',
-    }),
-    'utf8',
-  )
-}
-
-const signals = () => ({ agentDir, liveSessionDir: liveDir })
-
-function logCallsWithReason(reason: string): number {
-  return appendEntries.mock.calls.filter(
-    ([ct, d]) => ct === 'session-reader:log' && (d as { data?: { reason?: string } })?.data?.reason === reason,
-  ).length
-}
-
-// ---------------------------------------------------------------------------
-// 变体 M（manifest 在场，主路径）+ 场景 2 动作覆盖
-// ---------------------------------------------------------------------------
-
-describe('变体 M：manifest 主路径（instrument：manifest 锚与 entry 锚不同 session）', () => {
-  beforeEach(() => {
-    createZcodeDb(dbPath, '0.16.5', [sessARows(), sessBRows()])
-    // manifest 锚 → sess_bbb；liveSessionDir entry 锚 → sess_aaa：读到 ZBSENTINEL
-    // 而非 ZASENTINEL = 走了 manifest 主路径（entry 兜底未被进入的输出级证据）
-    writeZcodeManifest(SA_M)
-    writeLiveMainSession([recordLine('e1', SA_M, { sessionId: SESS_A, dbPath })])
-    writeRootSessionFile()
-  })
-
-  it('outline：读到 manifest 锚的 sess_bbb（ZBSENTINEL 在，ZASENTINEL 不在），两轮 T001/T002', async () => {
-    const r = await handleSessionRead({ action: 'outline', session: SA_M }, signals())
-    const text = r.content[0]?.text ?? ''
-    expect(text).toContain('ZBSENTINEL')
-    expect(text).not.toContain('ZASENTINEL')
-    // D9② 占位行折叠：T000 = converter 注入的 session_info 前置条目（纯记录，非对话），
-    // 折叠后不产行；对话轮保留原 turn.index（T001/T002），totalTurns 仍 = 2
-    expect(text).toContain('T001')
-    expect(text).toContain('T002')
-    expect(text).not.toMatch(/\bT000\b/)
-    // outline 的 isCompaction 恒 false 属已登记形态（§4 已接受代价）——无独立压缩 turn
-    expect(text).not.toContain('compaction')
-  })
-
-  it('result：单 id 纯正文 = sess_bbb 最终 assistant 文本（末轮，非仅通知本轮）', async () => {
-    const r = await handleSessionRead({ action: 'result', session: SA_M }, signals())
-    expect(r.content[0]?.text).toBe('第二轮 ZBSENTINEL 收尾')
-  })
-
-  it('result 截断指针：zcode 路由抑制 read 半边（库路径二进制不可 read），只留 session_read detail 可执行半边', async () => {
-    const r = await handleSessionRead({ action: 'result', session: SA_M, limit: 5 }, signals())
-    const text = r.content[0]?.text ?? ''
-    expect(text).toContain('[truncated 5 of')
-    // 可执行半边在场（错误 → 权威源 → 重试闭环）
-    expect(text).toContain(`session_read { action:"detail", session:"${SA_M}" }`)
-    // read 半边被抑制：不指库路径，也不出现 "full text: read" 形态
-    expect(text).not.toContain(dbPath)
-    expect(text).not.toContain('full text: read')
-  })
-
-  it('detail：toolCall 全配对（bash）+ compaction custom entry 形态（渲染现状锚定）', async () => {
-    const r = await handleSessionRead({ action: 'detail', session: SA_M, turns: 'T000-T002' }, signals())
-    const text = r.content[0]?.text ?? ''
-    expect(text).toContain('ZZQFIXTURE')
-    expect(text).toContain('bash')
-    expect(text).toContain('[custom:zcode-import:compaction]')
-    // A6 断言强化①：compaction custom entry 计数等式（fixture 恰 1 个压缩点）——
-    // 防「既不多」方向无防护（多插压缩点/重复渲染的实现在此失败）
-    expect((text.match(/\[custom:zcode-import:compaction\]/g) ?? []).length).toBe(1)
-    // A6 断言强化②：toolCall/toolResult 按 toolCallId 全配对（全文态 entries 直读——
-    // 摘要态 ToolResultSummaryEntry 不携带 toolCallId，无法配对）。converter 契约
-    // 「未完成 tool 整对丢弃防 dangling」在此以集合配对相等 + 双向 0 dangling 锚定。
-    const full = await handleSessionRead(
-      { action: 'detail', session: SA_M, turns: 'T000-T002', includeToolResult: true },
-      signals(),
-    )
-    const entries = (full.details as { entries: Array<Record<string, unknown>> }).entries
-    const callIds = new Set<string>()
-    const resultIds = new Set<string>()
-    for (const e of entries) {
-      const msg = e.message as { role?: unknown; content?: unknown; toolCallId?: unknown } | undefined
-      if (msg === undefined) continue
-      if (Array.isArray(msg.content)) {
-        for (const b of msg.content) {
-          if (b && typeof b === 'object' && (b as Record<string, unknown>).type === 'toolCall') {
-            const id = (b as Record<string, unknown>).id
-            if (typeof id === 'string') callIds.add(id)
-          }
-        }
-      }
-      if (msg.role === 'toolResult' && typeof msg.toolCallId === 'string') {
-        resultIds.add(msg.toolCallId)
-      }
-    }
-    expect(resultIds).toEqual(callIds) // 配对相等 = 无 toolCall 缺 result、无 result 悬空
-    expect(callIds.size).toBe(1) // fixture 恰 1 对（tc-1）——非平凡性锚（空集恒配对不构成证明）
-  })
-
-  it('search：ZZQFIXTURE 命中（canonical entries 走既有检索管线）', async () => {
-    const r = await handleSessionRead({ action: 'search', session: SA_M, pattern: 'ZZQFIXTURE' }, signals())
-    const text = r.content[0]?.text ?? ''
-    expect(text).toContain('ZZQFIXTURE')
-    expect(text).toContain('1 hit')
-  })
-})
-
-// ---------------------------------------------------------------------------
-// 变体 E（manifest 缺位 → entry 兜底取末条）
-// ---------------------------------------------------------------------------
-
-describe('变体 E：manifest 缺位 → entry 兜底（liveSessionDir 内取文件顺序末条）', () => {
-  beforeEach(() => {
-    createZcodeDb(dbPath, '0.16.5', [sessARows(), sessBRows()])
-    // ≥2 条同 sa-id entry：首条 sess_aaa、末条 sess_bbb（F16 每轮覆写）——
-    // 取首条/合并的实现会输出 sess_aaa 行集，必失败
-    writeLiveMainSession([
-      recordLine('e1', SA_E, { sessionId: SESS_A, dbPath }),
-      recordLine('e2', SA_E, { sessionId: SESS_B, dbPath }),
-    ])
-  })
-
-  it('result：兜底命中末条 → sess_bbb 正文（ZBSENTINEL 在，ZASENTINEL 不在）', async () => {
-    const r = await handleSessionRead({ action: 'result', session: SA_E }, signals())
-    expect(r.content[0]?.text).toBe('第二轮 ZBSENTINEL 收尾')
-    expect(r.content[0]?.text).not.toContain('ZASENTINEL')
-  })
-
-  it('兜底越界：liveSessionDir 内无该 sa-id 的任何 entry → zcode_record_not_found + 指引', async () => {
-    await expect(
-      handleSessionRead({ action: 'result', session: 'sa-nowhere-1' }, signals()),
-    ).rejects.toThrow(/zcode_record_not_found[\s\S]*👉/)
-  })
-})
-
-// ---------------------------------------------------------------------------
-// 场景 5：八类失败逐一断言（错误码 + 👉 指引 + ④ 顺序断言两种构造）
-// ---------------------------------------------------------------------------
-
-describe('场景 5 八类失败（§3.4 表逐行 + 检查顺序三段递进）', () => {
-  it('① manifest engine=zcode 但 engineHandle 整体缺席 → zcode_anchor_missing（导入对话框指引）', async () => {
-    createZcodeDb(dbPath, '0.16.5', [sessBRows()])
-    writeZcodeManifest(SA_M, { omitEngineHandle: true })
-    await expect(handleSessionRead({ action: 'result', session: SA_M }, signals())).rejects.toThrow(
-      /zcode_anchor_missing[\s\S]*导入/,
-    )
-  })
-
-  it('② entry 的 sessionRef 只留 sessionId、删 dbPath → zcode_anchor_missing + 结构化日志记「缺 dbPath」', async () => {
-    createZcodeDb(dbPath, '0.16.5', [sessBRows()])
-    writeLiveMainSession([recordLine('e1', SA_M, { sessionId: SESS_B })])
-    await expect(handleSessionRead({ action: 'result', session: SA_M }, signals())).rejects.toThrow(
-      'zcode_anchor_missing',
-    )
-    // 归因进结构化日志不进 LLM 可见部分（§3.4）：缺失键名可区分（missing-dbPath）
-    expect(logCallsWithReason('missing-dbPath')).toBeGreaterThanOrEqual(1)
-  })
-
-  it('③ manifest 删除 + liveSessionDir 内无该 sa-id entry → zcode_record_not_found（三动作指引）', async () => {
-    createZcodeDb(dbPath, '0.16.5', [sessBRows()])
-    writeLiveMainSession([recordLine('e1', 'sa-other-1', { sessionId: SESS_B, dbPath })])
-    await expect(handleSessionRead({ action: 'result', session: SA_M }, signals())).rejects.toThrow(
-      /zcode_record_not_found[\s\S]*派发的那个会话[\s\S]*family[\s\S]*换一个已完成/,
-    )
-  })
-
-  it('③b pi 形态 entry（engine 缺省、sessionRef 无 dbPath）在场 + manifest 缺位 → zcode_record_not_found（engine 判别防误归因 anchor_missing）', async () => {
-    // 回归 A1：pi record register() 先于 manifest settle 的窗口——manifest 缺位 +
-    // entry 为 pi 形态。pi record 不是「旧版本 zcode 产物」（导入对话框指引不适用），
-    // 必须落 zcode_record_not_found；误归因 missing-dbPath → zcode_anchor_missing 即红。
-    createZcodeDb(dbPath, '0.16.5', [sessBRows()])
-    writeLiveMainSession([piRecordLine('e-pi-1', SA_M)])
-    await expect(handleSessionRead({ action: 'result', session: SA_M }, signals())).rejects.toThrow(
-      /zcode_record_not_found/,
-    )
-    await expect(handleSessionRead({ action: 'result', session: SA_M }, signals())).rejects.not.toThrow(
-      /zcode_anchor_missing/,
-    )
-  })
-
-  it('④a 顺序断言（构造一）：dbPath 集合外且文件真实存在 → zcode_db_path_forbidden', async () => {
-    createZcodeDb(dbPath, '0.16.5', [sessBRows()])
-    const evilPath = join(root, 'evil-whitelist-probe.sqlite')
-    writeFileSync(evilPath, 'not a real db', 'utf8') // 存在性为真 → 走到路径段
-    writeZcodeManifest(SA_M, { sessionRef: { sessionId: SESS_B, dbPath: evilPath } })
-    await expect(handleSessionRead({ action: 'result', session: SA_M }, signals())).rejects.toThrow(
-      /zcode_db_path_forbidden[\s\S]*👉/,
-    )
-    expect(existsSync(evilPath)).toBe(true)
-  })
-
-  it('④b 顺序断言（构造二）：同一集合外路径但文件不存在 → zcode_db_unreadable（存在性先于路径）', async () => {
-    createZcodeDb(dbPath, '0.16.5', [sessBRows()])
-    const missingEvil = join(root, 'evil-whitelist-probe-missing.sqlite')
-    writeZcodeManifest(SA_M, { sessionRef: { sessionId: SESS_B, dbPath: missingEvil } })
-    await expect(handleSessionRead({ action: 'result', session: SA_M }, signals())).rejects.toThrow(
-      /zcode_db_unreadable[\s\S]*👉/,
-    )
-  })
-
-  it('⑤ 白名单形态路径但库文件缺席 → zcode_db_unreadable（含 -wal 告诫指引）', async () => {
-    createZcodeDb(dbPath, '0.16.5', [sessBRows()])
-    const missingInLayout = join(root, ...ISOLATED_DB_SEGMENTS.slice(0, -1), 'missing.sqlite')
-    writeZcodeManifest(SA_M, { sessionRef: { sessionId: SESS_B, dbPath: missingInLayout } })
-    await expect(handleSessionRead({ action: 'result', session: SA_M }, signals())).rejects.toThrow(
-      /zcode_db_unreadable[\s\S]*👉[\s\S]*-wal/,
-    )
-  })
-
-  it('⑥ schema_migration 版本超出已知集 → zcode_schema_drift（升级 taiji 指引）', async () => {
-    createZcodeDb(dbPath, '9.9.9', [sessBRows()])
-    writeZcodeManifest(SA_M)
-    await expect(handleSessionRead({ action: 'result', session: SA_M }, signals())).rejects.toThrow(
-      /zcode_schema_drift[\s\S]*9\.9\.9[\s\S]*👉/,
-    )
-  })
-
-  it('⑦ 传入 sess_ 形态 id → zcode_param_invalid（换完整 sa- id 指引）', async () => {
-    await expect(
-      handleSessionRead({ action: 'result', session: SESS_B }, signals()),
-    ).rejects.toThrow(/zcode_param_invalid[\s\S]*👉[\s\S]*sa-/)
-  })
-
-  it('⑧ 锚可解析 + 库可开 + schema 兼容，但库内 session 行已删 → zcode_session_not_found', async () => {
-    createZcodeDb(dbPath, '0.16.5', [sessBRows()])
-    writeZcodeManifest(SA_M)
-    // 模拟 zcode 侧 GC：删 sess_bbb 的全部行（db 文件与 schema 保留）
-    const db = new DatabaseSync(dbPath)
-    try {
-      db.exec("DELETE FROM part WHERE session_id = 'sess_bbb'")
-      db.exec("DELETE FROM message WHERE session_id = 'sess_bbb'")
-      db.exec("DELETE FROM session WHERE id = 'sess_bbb'")
-    } finally {
-      db.close()
-    }
-    await expect(handleSessionRead({ action: 'result', session: SA_M }, signals())).rejects.toThrow(
-      /zcode_session_not_found[\s\S]*👉[\s\S]*原 sa-id[\s\S]*family/,
-    )
-  })
-})
-
-// ---------------------------------------------------------------------------
-// 驱动探测失败的错误契约（跨包漂移检查 + L4 包装形态映射）
-// ---------------------------------------------------------------------------
-
-describe('驱动探测失败错误范围：跨包契约 + L4 包装形态映射', () => {
-  it('跨包契约：SQLITE_DRIVER_UNSUPPORTED_MARK 子串在 zcode-session-source sqlite-driver 源文内（漂移即红）', () => {
-    // 驱动探测错误无专用错误类型（该包不导出子类），reader 按消息特征识别——mark 与
-    // sqlite-driver 源内错误字面量的绑定由本测试机器锚定（entry-anchor.test.ts 协议
-    // 字面量跨包漂移检查同范式）：源文措辞变更不再含 mark → host_unsupported 契约死亡，红。
-    const source = readFileSync(
-      new URL('../../../../../packages/zcode-session-source/src/sqlite-driver.ts', import.meta.url),
-      'utf8',
-    )
-    expect(source).toContain(SQLITE_DRIVER_UNSUPPORTED_MARK)
-  })
-
-  it('L4 包装形态映射：SqliteUnreadableError（message 含 mark，last failure 并入）→ host_unsupported（R1 回归锚）', () => {
-    // 生产路径上驱动探测错误恒经 recovery L4 包装（last failure 以字符串并入
-    // SqliteUnreadableError.message，mark 随之存活）——直接构造该形态，锁定
-    // instanceof 分支内的二次判别（分支顺序错误 → 误落 db_unreadable，本用例红）。
-    const wrapped = new SqliteUnreadableError(
-      ['L1-direct', 'L2-immutable'],
-      'zcode session db unreadable (recovery ladder exhausted): /tmp/none.sqlite — ' +
-        `last failure: 当前 node 运行时${SQLITE_DRIVER_UNSUPPORTED_MARK}（需 >=22.13），且宿主非 bun 运行时`,
-    )
-    const msg = zcodeReadErrorMessage(wrapped, agentDir)
-    expect(msg).toContain('zcode_host_unsupported')
-    expect(msg).not.toContain('zcode_db_unreadable')
-  })
-
-  it('无 mark 的 SqliteUnreadableError 维持 db_unreadable 面（对照：attempted 链进 detail）', () => {
-    const plain = new SqliteUnreadableError(
-      ['L1-direct'],
-      'zcode session db unreadable (recovery ladder exhausted): /tmp/none.sqlite — last failure: file is not a database',
-    )
-    const msg = zcodeReadErrorMessage(plain, agentDir)
-    expect(msg).toContain('zcode_db_unreadable')
-    expect(msg).toContain('L1-direct')
-    expect(msg).not.toContain('zcode_host_unsupported')
-  })
-
-  it('跨包契约：ZCODE_DB_MISSING_MARK 子串在 zcode-session-source sqlite-access 源文内（漂移即红）', () => {
-    // 库文件缺失（openZcodeSessionDb 开头 existsSync 失败）无专用错误类型（抛普通
-    // Error），reader 按消息特征识别（SQLITE_DRIVER_UNSUPPORTED_MARK 契约测试同范式）：
-    // sqlite-access 源文措辞变更不再含 mark → db_unreadable 面死亡、TOCTOU 缺失误标
-    // schema_drift，红。
-    const source = readFileSync(
-      new URL('../../../../../packages/zcode-session-source/src/sqlite-access.ts', import.meta.url),
-      'utf8',
-    )
-    expect(source).toContain(ZCODE_DB_MISSING_MARK)
-  })
-
-  it('TOCTOU 窗口：开库期库文件缺失普通 Error → db_unreadable 面（不误标 schema_drift，§3.4 第 4 行）', () => {
-    // 白名单闸 existsSync 通过后、openZcodeSessionDb 开库前文件被删的窗口：sqlite-access
-    // 抛普通 Error「db 文件不存在：<dbPath>」——落 db_unreadable（环境恢复指引），编程
-    // 错误兜底（schema_drift）只接真正的查询期 schema 漂移域。
-    const msg = zcodeReadErrorMessage(new Error(`db 文件不存在：/tmp/fixture/db.sqlite`), agentDir)
-    expect(msg).toContain('zcode_db_unreadable')
-    expect(msg).toContain('db 文件不存在：/tmp/fixture/db.sqlite')
-    expect(msg).toContain('👉')
-    expect(msg).not.toContain('zcode_schema_drift')
-  })
-
-  it('对照：不含缺失 mark 的普通 Error 仍落 schema_drift 兜底（编程错误域语义不扩）', () => {
-    const msg = zcodeReadErrorMessage(new Error('TypeError: cannot read properties of undefined'), agentDir)
-    expect(msg).toContain('zcode_schema_drift')
-    expect(msg).not.toContain('zcode_db_unreadable')
-  })
-})
-
-// ---------------------------------------------------------------------------
-// family 接线（buildFamilyFromFs zcode 分支 + sa-id family 路由）
-// ---------------------------------------------------------------------------
-
-describe('family：zcode 节点接线（D5-1 两态）与 sa-id family 路由', () => {
-  beforeEach(() => {
-    createZcodeDb(dbPath, '0.16.5', [sessBRows()])
-    writeZcodeManifest(SA_M)
-    writeRootSessionFile()
-  })
-
-  it('sa-id family：zcode 路由 → rootSessionId 视图，subagents 含 zcode 节点且 cleanedUp=false', async () => {
-    const r = await handleSessionRead({ action: 'family', session: SA_M }, signals())
-    const text = r.content[0]?.text ?? ''
-    expect(text).toContain(SA_M)
-    const family = r.details as { subagents: Array<{ sessionId: string; cleanedUp?: boolean }> }
-    const node = family.subagents.find((s) => s.sessionId === SA_M)
-    expect(node?.cleanedUp).toBe(false) // 库可达态（D5-1：锚可解析 ∧ 库文件存在）
-  })
-
-  it('sa-id family recursive=true：rootSessionId 反查回填 fileName → 树 main root 填真实 session 路径（MF-1 链路）', async () => {
-    const r = await handleSessionRead({ action: 'family', session: SA_M, recursive: true }, signals())
-    const tree = (
-      r.details as { tree: { root: { type: string; sessionId: string; sessionFile?: string } } }
-    ).tree
-    expect(tree.root.type).toBe('main')
-    expect(tree.root.sessionId).toBe(ROOT_SESSION)
-    // 反查命中默认根的 root session 文件（writeRootSessionFile 落的路径），非空串占位
-    expect(tree.root.sessionFile).toBe(join(agentDir, 'sessions', `1700000000000_${ROOT_SESSION}.jsonl`))
-  })
-
-  it('rootSessionId family：buildFamilyFromFs 接线后 zcode 节点进列表（真实 family action 输出）', async () => {
-    const r = await handleSessionRead({ action: 'family', session: ROOT_SESSION }, signals())
-    const family = r.details as { subagents: Array<{ sessionId: string; cleanedUp?: boolean }> }
-    expect(family.subagents.map((s) => s.sessionId)).toContain(SA_M)
-  })
-
-  it('库不存在态：dbPath 改指白名单布局内缺席路径 → cleanedUp=true（GC 语义，不报错）', async () => {
-    writeZcodeManifest(SA_M, {
-      sessionRef: { sessionId: SESS_B, dbPath: join(root, ...ISOLATED_DB_SEGMENTS.slice(0, -1), 'gone.sqlite') },
-    })
-    const r = await handleSessionRead({ action: 'family', session: ROOT_SESSION }, signals())
-    const family = r.details as { subagents: Array<{ sessionId: string; cleanedUp?: boolean }> }
-    expect(family.subagents.find((s) => s.sessionId === SA_M)?.cleanedUp).toBe(true)
-  })
-
-  it('反向断言：库文件在但库内 session 行被删 → family 仍 cleanedUp=false（列表视图不开库的分工）', async () => {
-    const db = new DatabaseSync(dbPath)
-    try {
-      db.exec("DELETE FROM part WHERE session_id = 'sess_bbb'")
-      db.exec("DELETE FROM message WHERE session_id = 'sess_bbb'")
-      db.exec("DELETE FROM session WHERE id = 'sess_bbb'")
-    } finally {
-      db.close()
-    }
-    const r = await handleSessionRead({ action: 'family', session: ROOT_SESSION }, signals())
-    const family = r.details as { subagents: Array<{ sessionId: string; cleanedUp?: boolean }> }
-    expect(family.subagents.find((s) => s.sessionId === SA_M)?.cleanedUp).toBe(false)
-  })
-})
-
-// ---------------------------------------------------------------------------
-// pi 穿插不受影响（场景 3 抽样：zcode 失败调用穿插前后 pi 输出不变）
-// ---------------------------------------------------------------------------
-
-describe('pi 穿插不受影响：同 fixture 内 pi 会话读取与 zcode 调用互不干扰', () => {
-  beforeEach(() => {
-    createZcodeDb(dbPath, '0.16.5', [sessBRows()])
-    writeZcodeManifest(SA_M)
-    writePiFixture()
-  })
-
-  it('result：pi sa-id 正文穿插 zcode 失败调用前后一致（PI-SENTINEL 恒在）', async () => {
-    // zcode 调用先失败（锚缺位形态）
-    writeZcodeManifest('sa-broken-1', { omitEngineHandle: true })
-    await expect(handleSessionRead({ action: 'result', session: 'sa-broken-1' }, signals())).rejects.toThrow(
-      'zcode_anchor_missing',
-    )
-    const pi = await handleSessionRead({ action: 'result', session: 'sa-pi-1' }, signals())
-    expect(pi.content[0]?.text).toContain('PI-SENTINEL 正文内容')
-    // 再穿插一次 zcode 成功调用，pi 输出仍一致
-    const piAgain = await handleSessionRead({ action: 'result', session: 'sa-pi-1' }, signals())
-    expect(piAgain.content[0]?.text).toBe(pi.content[0]?.text)
-  })
-
-  it('uuid 形态（resolveSessionId 形态③）与 pi sa-id 现路径零变化', async () => {
-    const pi = await handleSessionRead({ action: 'result', session: 'sa-pi-1' }, { agentDir })
-    expect(pi.content[0]?.text).toContain('PI-SENTINEL')
-  })
-})
-
-// ---------------------------------------------------------------------------
-// D4 schema 零变化（快照逐字节对照 + 合法形态冒烟）
-// ---------------------------------------------------------------------------
-
-/** `session_read` 输入 schema 的 JSON 序列化快照（防无意漂移的逐字节锚）。
- *
- * 快照锚的意图 = 无意漂移拦截（参数增删 / 文案改动即红，迫使有意确认）；
- * 有意的声明侧压缩须同批重新生成快照。当前快照 = tool-declaration-slimming
- * U-A1 压缩终态（D1 三层分工：action 功能语义唯一承载点 = 枚举 description；
- * 工具 description 只留定位 + 边界；guidelines 只留纪律）。重新生成：
- * tsx 起 extension 捕获 registerTool 的 parameters 后 JSON.stringify。
- */
-const SCHEMA_SNAPSHOT =
-  '{"type":"object","required":["action"],"properties":{"action":{"type":"string","enum":["find","famil'
-    + 'y","outline","expand","detail","search","export","extract","workflow","result","doctor"],"descriptio'
-    + 'n":"find (locate session), family (relations; recursive=tree), outline (turn overview), expand (one '
-    + 'turn), detail (full text), search (grep, cross-session, ≤10 ids), export (to file), extract (message'
-    + 's/commands/files/commits/tool results), workflow (run overview), result (subagent final text, batch '
-    + '≤10), doctor (environment diagnostics)."},"session":{"type":"string","description":"Session id, uuid'
-    + ' fragment (e6c96), subagent id (sa-xxx), or .jsonl path. Required by every action except find/doctor'
-    + '; result/search accept ≤10 comma-separated ids. # prefix auto-stripped."},"query":{"type":"string","'
-    + 'description":"find: uuid fragment / filename / name keyword / \\"recent\\" (recent N)."},"turns":{"typ'
-    + 'e":"string","description":"detail/extract: turn range \\"T013-T015\\" or \\"T013\\"."},"turn":{"type":"s'
-    + 'tring","description":"expand: turn \\"T013\\"."},"pattern":{"type":"string","description":"search: sub'
-    + 'string or regex."},"scope":{"type":"string","enum":["all","user","assistant","toolResult"],"descript'
-    + 'ion":"search: filter scope. Default all."},"format":{"type":"string","enum":["outline","full","famil'
-    + 'y"],"description":"export: materialized form. Default outline."},"includeToolResult":{"type":"boolea'
-    + 'n","description":"detail/export: include toolResult text. Default false."},"includeThinking":{"type"'
-    + ':"boolean","description":"detail: include thinking blocks. Default false."},"allBranches":{"type":"b'
-    + 'oolean","description":"outline/export: include abandoned side-branches. Default false."},"granularit'
-    + 'y":{"type":"string","enum":["turn","entry"],"description":"outline: turn-level or entry-flat. Defaul'
-    + 't turn."},"cwd":{"type":"string","description":"find: filter by cwd."},"source":{"type":"string","en'
-    + 'um":["main","subagent"],"description":"\\"main\\" = sessions/, \\"subagent\\" = subagents/. Default both'
-    + '."},"limit":{"type":"number","minimum":1,"description":"find/search: max results (default 20). resul'
-    + 't: max chars per item (default 8000, truncated with pointer)."},"what":{"type":"string","enum":["use'
-    + 'r-messages","commands","files","commits","tool-results"],"description":"extract: what to pull (requi'
-    + 'red)."},"tool":{"type":"string","description":"extract: filter by tool name (e.g. \\"bash\\")."},"runI'
-    + 'd":{"type":"string","description":"workflow: focus one run (omit = all)."},"recursive":{"type":"bool'
-    + 'ean","description":"family: nested execution tree. Default false (flat)."},"includeSubagents":{"type'
-    + '":"boolean","description":"doctor: also scan the subagent session root. Default false."}}}';
-
-describe('session_read schema 快照（D4：不加任何工具参数，逐字节一致）', () => {
-  it('TypeBox schema JSON 序列化与基线快照逐字节一致', () => {
-    const registerTool = vi.fn()
-    const pi = { registerTool, registerCommand: vi.fn(), addAutocompleteProvider: vi.fn(), on: vi.fn() }
-    ;(sessionReaderExtension as unknown as (p: unknown) => void)(pi)
-    const toolDef = registerTool.mock.calls[0][0] as { parameters: unknown }
-    expect(JSON.stringify(toolDef.parameters)).toBe(SCHEMA_SNAPSHOT)
-  })
-
-  it('既有合法调用形态仍通过 schema 校验（无新增必填参数）', () => {
-    const registerTool = vi.fn()
-    const pi = { registerTool, registerCommand: vi.fn(), addAutocompleteProvider: vi.fn(), on: vi.fn() }
-    ;(sessionReaderExtension as unknown as (p: unknown) => void)(pi)
-    const schema = (registerTool.mock.calls[0][0] as { parameters: unknown }).parameters
-    expect(Check(schema, { action: 'result', session: 'sa-xxx' })).toBe(true)
-    expect(Check(schema, { action: 'outline', session: 'e6c96' })).toBe(true)
-  })
-})
-
-// ---------------------------------------------------------------------------
-// D2 锚词保留清单（index.ts guidelines 上方注释登记的清单在此逐词 grep 锚定）
-// ---------------------------------------------------------------------------
-
-describe('session_read 锚词保留清单（D2：guidelines 纪律逐词锚定）', () => {
-  // SCHEMA_SNAPSHOT 只逐字节锚 parameters schema，不覆盖 guidelines——本块是
-  // guidelines 锚词的机器防线：弱模型回归（P7/PB-weak）后对本工具声明侧的
-  // 再压缩 / 措辞改动，逐词红灯迫使有意确认。清单与 index.ts 注释登记一致：
-  //   1. "Progressive reading"   —— 阅读纪律 outline → expand → detail
-  //   2. "Never read raw .jsonl" —— 禁直读原始 session 文件
-  //   3. "sa- ids route"         —— zcode 路由对 LLM 的唯一可见部分（U9）
-  //   4. "👉 recovery hint"      —— 错误范围恢复指针契约
-  //   5. "doctor"                —— 环境自检入口（另被上方快照 action 枚举间接锚定）
-  it('guidelines 5 锚词逐个在位（缺一词即红）', () => {
-    const registerTool = vi.fn()
-    const pi = { registerTool, registerCommand: vi.fn(), addAutocompleteProvider: vi.fn(), on: vi.fn() }
-    ;(sessionReaderExtension as unknown as (p: unknown) => void)(pi)
-    const toolDef = registerTool.mock.calls[0][0] as { promptGuidelines: string[] }
-    const guidelines = toolDef.promptGuidelines.join('\n')
-    expect(guidelines).toContain('Progressive reading')
-    expect(guidelines).toContain('Never read raw .jsonl')
-    expect(guidelines).toContain('sa- ids route')
-    expect(guidelines).toContain('👉 recovery hint')
-    expect(guidelines).toContain('doctor')
-  })
-})