@zhushanwen/pi-session-reader 0.13.1 → 0.13.2

package/src/__tests__/tool-handler.test.ts

@@ -1,3347 +1,1003 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
-import { existsSync } from 'node:fs'
-import { mkdtemp, mkdir, writeFile, rm, utimes, readFile } from 'node:fs/promises'
-import { tmpdir, homedir } from 'node:os'
+// tool-handler.test.ts —— session-reader C07 簇合并产物（round5-G）。
+// 共同被测业务模块：`src/tool-handler.ts`。mock 相容：全簇零 vi.mock。
+// 顶层正文按来源包 describe 纯前缀分节，it 层名零改动。
+//
+// 来源：
+//   - src/__tests__/summary.test.ts（20 用例，skip 0）
+//   - src/__tests__/zcode-routing.test.ts（33 用例，skip 0）
+
+import { type Theme } from '@earendil-works/pi-coding-agent'
+import { describe, expect, it, beforeEach, afterEach, vi } from 'vitest'
+import { type SessionReadParams, type ToolResult, handleSessionRead } from '../tool-handler.js'
+import { buildSessionReadSummary, withResultSummary } from '../summary.js'
+import { renderSessionReadResult } from '../tui/tool-render.js'
+import { tmpdir } from 'node:os'
+import { mkdtempSync, writeFileSync, mkdirSync, rmSync, existsSync, readFileSync } from 'node:fs'
 import { join, dirname } from 'node:path'
-import {
-  handleSessionRead,
-  METADATA_CACHE_TTL_MS,
-  type SessionReadParams,
-  type SessionReadSignals,
-} from '../tool-handler.js'
-import {
-  resolveSessionStoreRoot,
-  resolveStoreSubagentSessionsDir,
-  resolveStoreSubagentRecordsDir,
-} from '../discovery/roots.js'
+import { DatabaseSync } from 'node:sqlite'
+import { Check } from 'typebox/value'
+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'
-import { type DoctorDetails } from '../doctor.js'
-import { levenshtein } from '../no-match.js'
-import {
-  MULTI_SEARCH_MAX_SESSIONS,
-  SEARCH_SCAN_BYTE_BUDGET,
-  searchAcrossSessions,
-} from '../search-across.js'
-import { renderExtractItems } from '../extract.js'
-import type { SessionMetadataProvider } from '../discovery/find.js'
-import { FIX_E6 } from './fixtures.js'
-
-// fs-guard：TC6 的「~ 前缀展开」语义需要 homedir，但真实 homedir 根在白名单外（禁止向用户
-// 主目录散落文件）。vi.mock 把 homedir 指到用例内 mkdtemp 的 tmp；fakeHome 未注入时回落真实值。
-const homeState = vi.hoisted(() => ({ fakeHome: undefined as string | undefined }))
-vi.mock('node:os', async (importOriginal) => {
-  const actual = await importOriginal<typeof import('node:os')>()
-  return { ...actual, homedir: () => homeState.fakeHome ?? actual.homedir() }
-})
-
-/**
- * M3 tool-handler 集成测试。
- *
- * 测试框架 vitest（禁止 node:test/tsx）。直接调 handleSessionRead（纯逻辑，agentDir 注入），
- * agentDir 全部指向 mkdtemp 自建自删的 fixture 目录（按断言逻辑构造的最小 session 文件，
- * 不读本机真实用户数据目录），fixture 生命周期与各 describe 的 beforeEach/afterEach 绑定。
- *
- * 覆盖全 11 action 主路径 + F1(find 零匹配)/F4(turn 越界)/F5(缺参)/resolveSessionId 片段等价，
- * 以及 u8 doctor / u9 归一化 / u10 find 分组 / u11 metadataProvider 缓存 / u12 跨会话检索（各见对应 describe）。
- */
 
-describe('handleSessionRead', () => {
-  let dataDir: string
-  let dir: string // agentDir = <dataDir>/agent（生产拓扑复刻）
-  const SLUG = '--demo-cwd--'
-  // 家族 fixture 组：根 FAM → fork 子代 FORK（跨 cwd，parentSession 指 FAM 文件）
-  // → 隔代 subagent SUB2（rootSessionId=FORK）。前缀互异，断言按 id 精确区分层级。
-  const FAM = '019fe620-8ae1-78a7-b76a-43a1ba4cc3c7'
-  const FORK = '019fe632-aaaa-7bbb-8ccc-00000000fe32'
-  const SUB2 = '019fe635-aaaa-7bbb-8ccc-00000000fe35'
+// ======== 来源：summary.test.ts ========
+describe("summary", () => {
+  // ---- fixtures ----
 
-  /**
-   * 主 fixture session（FIX_E6）：2 turn 的最小多形态 session——
-   * - T000 含 toolCall + toolResult（detail 摘要态断言），文本含 'plugin'（search 断言）
-   * - T001 纯文本收尾（outline 计数 / fragment 等价断言）
-   * 另加 1 条无关 session（id 不含 e6c96）：find 片段全扫「多条候选恰一条命中」语义。
-   */
-  async function writeMainFixtures(): Promise<void> {
-    const sessionDir = join(dir, 'sessions', SLUG)
-    await mkdir(sessionDir, { recursive: true })
-    const msg = (id: string, parentId: string, message: Record<string, unknown>): string =>
-      JSON.stringify({ type: 'message', id, parentId, message })
-    const e6Lines = [
-      JSON.stringify({ type: 'session', id: FIX_E6, cwd: '/demo' }),
-      msg(`${FIX_E6}-m0`, FIX_E6, {
-        role: 'user',
-        content: [{ type: 'text', text: '调研 plugin 架构怎么落地' }],
-      }),
-      msg(`${FIX_E6}-m1`, `${FIX_E6}-m0`, {
-        role: 'assistant',
-        content: [
-          { type: 'text', text: '先看现有目录结构' },
-          { type: 'toolCall', id: 'tc-e6-1', name: 'bash', arguments: { command: 'ls src' } },
-        ],
-      }),
-      msg(`${FIX_E6}-m2`, `${FIX_E6}-m1`, {
-        role: 'toolResult',
-        toolName: 'bash',
-        toolCallId: 'tc-e6-1',
-        content: [{ type: 'text', text: 'src/plugin.ts' }],
-      }),
-      msg(`${FIX_E6}-m3`, `${FIX_E6}-m2`, {
-        role: 'user',
-        content: [{ type: 'text', text: '继续深入' }],
-      }),
-      msg(`${FIX_E6}-m4`, `${FIX_E6}-m3`, {
-        role: 'assistant',
-        content: [{ type: 'text', text: '完成，共两轮。' }],
-      }),
-    ]
-    await writeFile(join(sessionDir, `${FIX_E6}.jsonl`), e6Lines.join('\n') + '\n')
-    await makeFixtureSession(dir, '019ffff-aaaa-bbbb-cccc-00000000ffff', '无关会话')
+  function params(overrides: Partial<SessionReadParams> & { action: SessionReadParams['action'] }): SessionReadParams {
+    return overrides as SessionReadParams
   }
 
-  /** 家族 fixture：FAM 根 + FORK（跨 cwd fork）+ 挂在 FORK 下的隔代 subagent（manifest 建族）。 */
-  async function writeFamilyFixtures(): Promise<void> {
-    const famPath = join(dir, 'sessions', SLUG, `${FAM}.jsonl`)
-    await writeFile(famPath, JSON.stringify({ type: 'session', id: FAM, cwd: '/demo' }) + '\n')
-    const forkDir = join(dir, 'sessions', '--fork-cwd--')
-    await mkdir(forkDir, { recursive: true })
-    await writeFile(
-      join(forkDir, `${FORK}.jsonl`),
-      JSON.stringify({ type: 'session', id: FORK, cwd: '/fork', parentSession: famPath }) + '\n',
-    )
-    await makeFixtureSubagent(dir, 'sa-fe635', { realSessionId: SUB2, rootSessionId: FORK })
+  function toolResult(details: unknown, text = 'body text'): ToolResult {
+    return { content: [{ type: 'text', text }], details }
   }
 
-  beforeEach(async () => {
-    dataDir = await mkdtemp(join(tmpdir(), 'tool-handler-main-'))
-    dir = join(dataDir, 'agent')
-    await writeMainFixtures()
-  })
-  afterEach(async () => {
-    await rm(dataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
-  })
+  // ---- buildSessionReadSummary ----
 
-  it('1. find by uuid fragment returns matching session', async () => {
-    const r = await handleSessionRead({ action: 'find', query: 'e6c96' }, { agentDir: dir })
-    const d = r.details as { matches: Array<{ sessionId: string }> }
-    expect(d.matches.some((m) => m.sessionId.startsWith('019e6c96'))).toBe(true)
-    expect(r.content[0]).toEqual({ type: 'text', text: expect.any(String) })
-  })
-
-  it('2. outline yields all turns within token budget (v2 O1: <=1500)', async () => {
-    const r = await handleSessionRead({ action: 'outline', session: FIX_E6 }, { agentDir: dir })
-    const d = r.details as { turns: unknown[]; tokenEstimate: number }
-    expect(d.turns.length).toBe(2)
-    // v2 O1：加 assistantBrief + 修 toolSummary bug 后阈值 1500（design §3.3 D4）
-    expect(d.tokenEstimate).toBeLessThanOrEqual(1500)
-  })
-
-  it('3. detail single turn returns toolResult summary by default (v2 O3)', async () => {
-    // fixture 的 T000 是含 toolCall + toolResult 的 turn
-    const r = await handleSessionRead({ action: 'detail', session: FIX_E6, turns: 'T000' }, { agentDir: dir })
-    const d = r.details as { entries: Array<{ type: string; message?: { role?: string } }> }
-    expect(d.entries.length).toBeGreaterThan(0)
-    // v2 O3：默认 toolResult 变摘要态（type=toolResultSummary），条目不消失
-    expect(d.entries.some((e) => e.type === 'toolResultSummary')).toBe(true)
-    // 不再有 role=toolResult 的原文 entry（除非 includeToolResult:true）
-    expect(d.entries.some((e) => e.message?.role === 'toolResult')).toBe(false)
-  })
-
-  it('4. family lists fork children and隔代 subagents', async () => {
-    await writeFamilyFixtures()
-    const r = await handleSessionRead({ action: 'family', session: FAM }, { agentDir: dir })
-    const d = r.details as {
-      forks: Array<{ sessionId: string }>
-      subagents: Array<{ sessionId: string }>
-    }
-    expect(d.forks.some((f) => f.sessionId === FORK)).toBe(true)
-    // 隔代：SUB2.rootSessionId=FORK（fork 子代），从家族根 FAM 出发仍能关联
-    expect(d.subagents.some((s) => s.sessionId === SUB2)).toBe(true)
-  })
-
-  it('5. search pattern returns hits', async () => {
-    const r = await handleSessionRead({ action: 'search', session: FIX_E6, pattern: 'plugin' }, { agentDir: dir })
-    const d = r.details as { hits: Array<{ turnIndex: number; matchSnippet: string }> }
-    expect(d.hits.length).toBeGreaterThan(0)
-    expect(typeof d.hits[0].matchSnippet).toBe('string')
-  })
-
-  it('6. export outline materializes a .md file under the session store tree', async () => {
-    // export 写目标 = <dataDir>/ext-sessions/<sid>/session-view.md（session-store-layout-
-    // inversion 域 6）：agentDir 参数 = <dataDir>/agent（mkdtemp tmp 子目录，导出树随 tmp
-    // 整体清理）；读侧经 liveSessionDir=[live] 根扫本 describe 的 fixture sessions 目录。
-    const dataDir = await mkdtemp(join(tmpdir(), 'tool-handler-export-'))
-    try {
-      const r = await handleSessionRead(
-        { action: 'export', session: FIX_E6, format: 'outline' },
-        { agentDir: join(dataDir, 'agent'), liveSessionDir: join(dir, 'sessions') },
+  describe('buildSessionReadSummary', () => {
+    it('find → Found N sessions matching "<query>"（截断带后缀）', () => {
+      const r = toolResult({ matches: [{}, {}, {}], truncated: false })
+      expect(buildSessionReadSummary(params({ action: 'find', query: 'login' }), r)).toBe(
+        'Found 3 sessions matching "login"',
       )
-      const d = r.details as { path: string; sizeBytes: number }
-      expect(d.path).toBe(join(dataDir, 'ext-sessions', FIX_E6, 'session-view.md'))
-      expect(existsSync(d.path)).toBe(true)
-      expect(d.sizeBytes).toBeGreaterThan(0)
-    } finally {
-      await rm(dataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
-    }
-  })
-
-  // source:'main' 收窄到 main 侧（显式 source 查询走单组原语义，见 TC12/TC13）
-  it('7. F1 find zero match returns empty matches + fact-based self-check (no throw)', async () => {
-    const r = await handleSessionRead(
-      { action: 'find', query: 'zzz-nonexistent-session-9q8x2', source: 'main' },
-      { agentDir: dir },
-    )
-    const d = r.details as { matches: unknown[]; truncated: boolean }
-    expect(d.matches).toEqual([])
-    expect(d.truncated).toBe(false)
-    // u9 F1 重写（§5.2）：事实型自检 + 无归因断言 + 无「recent 看全量」误导
-    expect(r.content[0].text).toContain('无匹配 session')
-    expect(r.content[0].text).toContain('自检（发现层，只陈述事实）')
-    expect(r.content[0].text).not.toContain('真的没有')
-    expect(r.content[0].text).not.toContain('recent')
-  })
-
-  it('8. F4 detail turn out of range throws with 越界', async () => {
-    await expect(
-      handleSessionRead({ action: 'detail', session: FIX_E6, turns: 'T999' }, { agentDir: dir }),
-    ).rejects.toThrow(/越界/)
-  })
-
-  it('9. F5 outline missing session throws naming session', async () => {
-    await expect(handleSessionRead({ action: 'outline' }, { agentDir: dir })).rejects.toThrow(/session/)
-  })
-
-  it('10. resolveSessionId fragment equivalent to full id', async () => {
-    const rFull = await handleSessionRead({ action: 'outline', session: FIX_E6 }, { agentDir: dir })
-    const rFrag = await handleSessionRead({ action: 'outline', session: 'e6c96' }, { agentDir: dir })
-    const dFull = rFull.details as { turns: unknown[] }
-    const dFrag = rFrag.details as { turns: unknown[] }
-    expect(dFrag.turns.length).toBe(dFull.turns.length)
-  })
-})
-
-describe('extract (v2 O4)', () => {
-  let dir: string
-  let dataDir: string
-  const SLUG = '--demo-cwd--'
-
-  /**
-   * extract fixture session（FIX_E6）：3 user turn 的最小多素材形态——
-   * - T000：bash git log（commits git-cmd 主路径：def5678a）+ bash ls + read
-   *  （commits commit-context 次路径：abc1234f，hash 邻近含 'feat:'）
-   * - T001：edit（files op 素材）
-   * - T002：纯文本收尾
-   * 计数锚：user 3 / toolCall 4（bash 2）/ toolResult 4（bash 2）。
-   */
-  async function writeExtractFixture(): Promise<void> {
-    const sessionDir = join(dir, 'sessions', SLUG)
-    await mkdir(sessionDir, { recursive: true })
-    const msg = (id: string, parentId: string, message: Record<string, unknown>): string =>
-      JSON.stringify({ type: 'message', id, parentId, message })
-    const lines = [
-      JSON.stringify({ type: 'session', id: FIX_E6, cwd: '/demo' }),
-      msg(`${FIX_E6}-m0`, FIX_E6, {
-        role: 'user',
-        content: [{ type: 'text', text: '第一条：查一下最近的提交' }],
-      }),
-      msg(`${FIX_E6}-m1`, `${FIX_E6}-m0`, {
-        role: 'assistant',
-        content: [
-          { type: 'text', text: '好，先看 git 记录' },
-          { type: 'toolCall', id: 'tc-git', name: 'bash', arguments: { command: 'git log --oneline -3' } },
-        ],
-      }),
-      msg(`${FIX_E6}-m2`, `${FIX_E6}-m1`, {
-        role: 'toolResult',
-        toolName: 'bash',
-        toolCallId: 'tc-git',
-        content: [{ type: 'text', text: 'def5678a feat: fix crash' }],
-      }),
-      msg(`${FIX_E6}-m3`, `${FIX_E6}-m2`, {
-        role: 'assistant',
-        content: [
-          { type: 'text', text: '再看下文件列表' },
-          { type: 'toolCall', id: 'tc-ls', name: 'bash', arguments: { command: 'ls src' } },
-        ],
-      }),
-      msg(`${FIX_E6}-m4`, `${FIX_E6}-m3`, {
-        role: 'toolResult',
-        toolName: 'bash',
-        toolCallId: 'tc-ls',
-        content: [{ type: 'text', text: 'src/index.ts' }],
-      }),
-      msg(`${FIX_E6}-m5`, `${FIX_E6}-m4`, {
-        role: 'assistant',
-        content: [
-          { type: 'text', text: '读一下说明' },
-          { type: 'toolCall', id: 'tc-read', name: 'read', arguments: { path: '/repo/README.md' } },
-        ],
-      }),
-      msg(`${FIX_E6}-m6`, `${FIX_E6}-m5`, {
-        role: 'toolResult',
-        toolName: 'read',
-        toolCallId: 'tc-read',
-        content: [{ type: 'text', text: 'deploy abc1234f done\nfeat: add login' }],
-      }),
-      msg(`${FIX_E6}-m7`, `${FIX_E6}-m6`, {
-        role: 'user',
-        content: [{ type: 'text', text: '第二条：改代码' }],
-      }),
-      msg(`${FIX_E6}-m8`, `${FIX_E6}-m7`, {
-        role: 'assistant',
-        content: [
-          { type: 'text', text: '来改' },
-          {
-            type: 'toolCall',
-            id: 'tc-edit',
-            name: 'edit',
-            arguments: { path: '/repo/src/app.ts', edits: [{ oldText: 'a', newText: 'b' }] },
-          },
-        ],
-      }),
-      msg(`${FIX_E6}-m9`, `${FIX_E6}-m8`, {
-        role: 'toolResult',
-        toolName: 'edit',
-        toolCallId: 'tc-edit',
-        content: [{ type: 'text', text: 'ok' }],
-      }),
-      msg(`${FIX_E6}-m10`, `${FIX_E6}-m9`, {
-        role: 'user',
-        content: [{ type: 'text', text: '第三条：完成' }],
-      }),
-      msg(`${FIX_E6}-m11`, `${FIX_E6}-m10`, {
-        role: 'assistant',
-        content: [{ type: 'text', text: '全部完成。' }],
-      }),
-    ]
-    await writeFile(join(sessionDir, `${FIX_E6}.jsonl`), lines.join('\n') + '\n')
-  }
-
-  beforeEach(async () => {
-    dataDir = await mkdtemp(join(tmpdir(), 'tool-handler-extract-'))
-    dir = join(dataDir, 'agent')
-    await writeExtractFixture()
-  })
-  afterEach(async () => {
-    await rm(dataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
-  })
-
-  it('user-messages returns all user entries with turn + full text', async () => {
-    const r = await handleSessionRead(
-      { action: 'extract', session: FIX_E6, what: 'user-messages' },
-      { agentDir: dir },
-    )
-    const d = r.details as {
-      what: string
-      count: number
-      shown: number
-      truncated: boolean
-      items: Array<{ turn: number; text: string }>
-    }
-    expect(d.what).toBe('user-messages')
-    expect(d.count).toBe(3) // 全量 user entry 计数锚（fixture 3 条 user）
-    // F9 预算可能截断：items 是 shown 子集，shown <= count
-    expect(d.shown).toBeLessThanOrEqual(d.count)
-    expect(d.items.length).toBe(d.shown)
-    expect(d.items.length).toBeGreaterThan(0)
-    expect(
-      d.items.every((it) => typeof it.turn === 'number' && typeof it.text === 'string'),
-    ).toBe(true)
-  })
-
-  it('commands (no filter) returns all tool calls with name + summary', async () => {
-    const r = await handleSessionRead(
-      { action: 'extract', session: FIX_E6, what: 'commands' },
-      { agentDir: dir },
-    )
-    const d = r.details as {
-      count: number
-      shown: number
-      items: Array<{ name: string; summary: string }>
-    }
-    expect(d.count).toBe(4) // 全量 toolCall 计数锚（fixture：bash×2 + read + edit）
-    expect(d.shown).toBeLessThanOrEqual(d.count)
-    expect(d.items.length).toBe(d.shown)
-    expect(
-      d.items.every((it) => typeof it.name === 'string' && typeof it.summary === 'string'),
-    ).toBe(true)
-    // 抽查 bash summary 含 "bash: "（D1 映射）
-    const bashItem = d.items.find((it) => it.name === 'bash')
-    if (bashItem !== undefined) {
-      expect(bashItem.summary).toContain('bash: ')
-    }
-  })
-
-  it('commands tool=bash returns 2 all bash', async () => {
-    const r = await handleSessionRead(
-      { action: 'extract', session: FIX_E6, what: 'commands', tool: 'bash' },
-      { agentDir: dir },
-    )
-    const d = r.details as {
-      count: number
-      shown: number
-      items: Array<{ name: string }>
-    }
-    expect(d.count).toBe(2) // bash toolCall 全量（F9 可能截断 shown 子集）
-    expect(d.items.every((it) => it.name === 'bash')).toBe(true)
-  })
-
-  it('commands tool=nonexist triggers F8 with tool distribution (no throw)', async () => {
-    const r = await handleSessionRead(
-      { action: 'extract', session: FIX_E6, what: 'commands', tool: 'nonexist' },
-      { agentDir: dir },
-    )
-    const d = r.details as {
-      toolDistribution: Array<{ name: string; count: number }>
-    }
-    expect(r.content[0].text).toContain('无匹配')
-    expect(r.content[0].text).toContain('bash×2')
-    expect(r.content[0].text).toContain('👉')
-    expect(d.toolDistribution.some((t) => t.name === 'bash' && t.count === 2)).toBe(true)
-  })
-
-  it('files returns deduped paths with op (read/edit/write/head)', async () => {
-    const r = await handleSessionRead(
-      { action: 'extract', session: FIX_E6, what: 'files' },
-      { agentDir: dir },
-    )
-    const d = r.details as {
-      count: number
-      items: Array<{ path: string; basename: string; op: string; turns: number[] }>
-    }
-    expect(d.count).toBeGreaterThan(0)
-    expect(d.items.length).toBeGreaterThan(0)
-    // 抽查含 .ts 或 .md 文件
-    expect(
-      d.items.some((it) => it.path.endsWith('.ts') || it.path.endsWith('.md')),
-    ).toBe(true)
-    // op 含 read/edit/write/head 之一
-    expect(d.items.some((it) => /read|edit|write|head/.test(it.op))).toBe(true)
-    // turns 是数组（去重后出现过的轮次）
-    expect(d.items.every((it) => Array.isArray(it.turns))).toBe(true)
-  })
-
-  it('commits returns hash list with 7-8 hex + source turn', async () => {
-    const r = await handleSessionRead(
-      { action: 'extract', session: FIX_E6, what: 'commits' },
-      { agentDir: dir },
-    )
-    const d = r.details as {
-      count: number
-      items: Array<{ hash: string; turn: number; source: string; context: string }>
-    }
-    // git-cmd 主路径（bash git log 结果）取到 hash
-    expect(d.count).toBeGreaterThan(0)
-    // commits 已知会误匹配/漏报（D6），只验每条格式
-    for (const it of d.items) {
-      expect(it.hash).toMatch(/^[0-9a-f]{7,8}$/)
-      expect(typeof it.turn).toBe('number')
-      expect(['git-cmd', 'commit-context']).toContain(it.source)
-    }
-  })
-
-  it('tool-results (no filter) returns all results with toolName + text', async () => {
-    const r = await handleSessionRead(
-      { action: 'extract', session: FIX_E6, what: 'tool-results' },
-      { agentDir: dir },
-    )
-    const d = r.details as {
-      count: number
-      shown: number
-      items: Array<{ toolName: string; text: string }>
-    }
-    expect(d.count).toBe(4) // 全量 toolResult 计数锚（fixture 4 条）
-    expect(d.shown).toBeLessThanOrEqual(d.count)
-    expect(
-      d.items.every((it) => typeof it.toolName === 'string' && typeof it.text === 'string'),
-    ).toBe(true)
-  })
-
-  it('tool-results tool=bash returns 2 all bash', async () => {
-    const r = await handleSessionRead(
-      { action: 'extract', session: FIX_E6, what: 'tool-results', tool: 'bash' },
-      { agentDir: dir },
-    )
-    const d = r.details as { count: number; items: Array<{ toolName: string }> }
-    expect(d.count).toBe(2)
-    expect(d.items.every((it) => it.toolName === 'bash')).toBe(true)
-  })
-
-  it('tool-results tool=nonexist triggers F8 (no throw)', async () => {
-    const r = await handleSessionRead(
-      { action: 'extract', session: FIX_E6, what: 'tool-results', tool: 'nonexist' },
-      { agentDir: dir },
-    )
-    expect(r.content[0].text).toContain('无匹配')
-    expect(r.content[0].text).toContain('bash×2')
-  })
-
-  it('F7 missing what throws with 无效 + valid values', async () => {
-    // what 缺失是合法 SessionReadParams（optional），handler 层 F7 防御校验。
-    // isExtractWhat 对 undefined 返 false → 同一 throw 路径，覆盖非法值场景。
-    const params: SessionReadParams = { action: 'extract', session: FIX_E6 }
-    await expect(handleSessionRead(params, { agentDir: dir })).rejects.toThrow(/无效/)
-    await expect(handleSessionRead(params, { agentDir: dir })).rejects.toThrow(
-      /user-messages\/commands\/files\/commits\/tool-results/,
-    )
-  })
-
-  it('S2: extract turns 越界文案说明 extract turn 体系（不指向 outline）', async () => {
-    // extract 用全量 entry 分段（含 compaction/旁支），turn index 与 outline leaf 视图不对齐
-    let msg = ''
-    try {
-      await handleSessionRead(
-        { action: 'extract', session: FIX_E6, what: 'user-messages', turns: 'T999' },
-        { agentDir: dir },
+      const truncated = toolResult({ matches: [{}], truncated: true })
+      expect(buildSessionReadSummary(params({ action: 'find', query: 'login' }), truncated)).toBe(
+        'Found 1 sessions matching "login" (truncated)',
       )
-    } catch (e) {
-      msg = (e as Error).message
-    }
-    expect(msg).toContain('extract 的 turn 范围与 outline 不同')
-    expect(msg).not.toContain('用 outline 重看有效范围')
-    expect(msg).toContain('该 session extract 共')
-  })
-})
-
-// ---- fixture 工具（tmpdir 造最小 session 文件，供 F2/MF-5 用例）----
-
-async function makeFixtureSession(
-  dir: string,
-  id: string,
-  firstUserText: string,
-): Promise<void> {
-  const slug = '--demo-cwd--'
-  await mkdir(join(dir, 'sessions', slug), { recursive: true })
-  const lines = [
-    JSON.stringify({ type: 'session', id, cwd: '/demo' }),
-    JSON.stringify({
-      type: 'message',
-      id: id + '-m1',
-      parentId: id,
-      message: { role: 'user', content: [{ type: 'text', text: firstUserText }] },
-    }),
-  ]
-  await writeFile(join(dir, 'sessions', slug, id + '.jsonl'), lines.join('\n') + '\n')
-}
-
-describe('F2 多匹配消歧（fixture，MF-9）', () => {
-  let dataDir: string
-  let dir: string // agentDir = <dataDir>/agent（生产拓扑复刻，[session-store-layout-inversion]）
-
-  beforeEach(async () => {
-    dataDir = await mkdtemp(join(tmpdir(), 'tool-handler-f2-'))
-    dir = join(dataDir, 'agent')
-  })
-  afterEach(async () => {
-    await rm(dataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
-  })
-
-  it('共享 uuid 片段 → 不抛错，content 含两候选 + 👉，details.ambiguous=true', async () => {
-    const ID1 = '019e6c96-aaaa-bbbb-cccc-000000000001'
-    const ID2 = '019e6c96-aaaa-bbbb-cccc-000000000002'
-    await makeFixtureSession(dir, ID1, '第一段内容')
-    await makeFixtureSession(dir, ID2, '第二段内容')
-
-    // outline 走 resolveSessionId → 2 匹配 → F2 消歧（不抛错）
-    const r = await handleSessionRead({ action: 'outline', session: '019e6c96-aaaa' }, { agentDir: dir })
-    const d = r.details as { ambiguous: boolean; candidates: Array<{ sessionId: string }> }
-    expect(d.ambiguous).toBe(true)
-    expect(d.candidates).toHaveLength(2)
-    expect(d.candidates.some((c) => c.sessionId === ID1)).toBe(true)
-    expect(d.candidates.some((c) => c.sessionId === ID2)).toBe(true)
-    const text = r.content[0].text
-    expect(text).toContain(ID1)
-    expect(text).toContain(ID2)
-    expect(text).toContain('👉')
-  })
-
-  it('search/detail/expand/extract 同样走 F2 消歧（不抛错）', async () => {
-    const ID1 = '019e6c96-aaaa-bbbb-cccc-000000000001'
-    const ID2 = '019e6c96-aaaa-bbbb-cccc-000000000002'
-    await makeFixtureSession(dir, ID1, '第一段内容')
-    await makeFixtureSession(dir, ID2, '第二段内容')
-
-    for (const action of ['detail', 'expand', 'search', 'export', 'extract'] as const) {
-      const params: SessionReadParams = { action, session: '019e6c96-aaaa' }
-      if (action === 'detail') params.turns = 'T001'
-      if (action === 'expand') params.turn = 'T001'
-      if (action === 'search') params.pattern = 'x'
-      if (action === 'extract') params.what = 'user-messages'
-      const r = await handleSessionRead(params, { agentDir: dir })
-      const d = r.details as { ambiguous: boolean }
-      expect(d.ambiguous, `action=${action}`).toBe(true)
-      expect(r.content[0].text).toContain('👉')
-    }
-  })
-})
-
-describe('outline skippedLines 报告（fixture，D8d 有检测必有报告）', () => {
-  let dir: string
-  let dataDir: string
-  const SID = '019e6c96-bbbb-cccc-dddd-00000000000b'
-
-  beforeEach(async () => {
-    dataDir = await mkdtemp(join(tmpdir(), 'tool-handler-skipped-'))
-    dir = join(dataDir, 'agent')
-  })
-  afterEach(async () => {
-    await rm(dataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
-  })
-
-  it('坏行计入 stats.skippedLines 且文本尾部可见（不静默跳过）', async () => {
-    // 中间注入 1 行坏 JSON（半截对象）：parser 计 skippedLines=1，outline 必须报告
-    const slug = '--demo-cwd--'
-    await mkdir(join(dir, 'sessions', slug), { recursive: true })
-    const lines = [
-      JSON.stringify({ type: 'session', id: SID, cwd: '/demo' }),
-      JSON.stringify({
-        type: 'message',
-        id: SID + '-m1',
-        parentId: SID,
-        message: { role: 'user', content: [{ type: 'text', text: 'hello' }] },
-      }),
-      '{"broken json line',
-    ]
-    await writeFile(join(dir, 'sessions', slug, SID + '.jsonl'), lines.join('\n') + '\n')
-
-    const r = await handleSessionRead({ action: 'outline', session: SID }, { agentDir: dir })
-    const d = r.details as { stats: { skippedLines: number } }
-    expect(d.stats.skippedLines).toBe(1)
-    expect(r.content[0].text).toContain('1 skipped lines')
-  })
-
-  it('无坏行时不输出 skipped 片段（正常 session 零噪音）', async () => {
-    await makeFixtureSession(dir, SID, 'clean session')
-    const r = await handleSessionRead({ action: 'outline', session: SID }, { agentDir: dir })
-    const d = r.details as { stats: { skippedLines: number } }
-    expect(d.stats.skippedLines).toBe(0)
-    expect(r.content[0].text).not.toContain('skipped lines')
-  })
-})
-
-// ============================================================
-// E7：行渲染统一（ext-simplify-04 U5，design D3）。outline 与 export {format:"outline"}
-// 共用 renderOutline 返回的渲染行（OutlineResult.lines）+ 同一尾段拼装——预算度量 =
-// 展示 by construction；旁支标记统一为 `[旁支 N entries]`（改前 handler 侧第二份行
-// 格式知识输出裸 `[旁支]`，已随 formatOutlineText 删除）。
-// ============================================================
-describe('E7 行渲染统一（outline 与 export outline 同一渲染行）', () => {
-  let dir: string
-  let dataDir: string
-  const SID = '019e6c96-bbbb-cccc-dddd-00000000000e'
-
-  /** 写含 fork 旁支的 session：主链 R→m1(user)→m2(assistant)，b1/b2 挂 m1 下成
-   * 旁支子树（buildTreeView：branches[m1]=2；segmentTurns：单 turn [m1, m2]，
-   * 旁支 entry 不进 leaf 视图）。 */
-  async function writeForkSession(): Promise<void> {
-    await mkdir(join(dir, 'sessions', '--demo-cwd--'), { recursive: true })
-    const msg = (id: string, parentId: string, role: 'user' | 'assistant', text: string) =>
-      JSON.stringify({
-        type: 'message',
-        id: `${SID}-${id}`,
-        parentId,
-        message: { role, content: [{ type: 'text', text }] },
-      })
-    const lines = [
-      JSON.stringify({ type: 'session', id: SID, cwd: '/demo' }),
-      msg('m1', SID, 'user', 'fork point turn'),
-      msg('b1', `${SID}-m1`, 'assistant', 'branch one'),
-      msg('b2', `${SID}-m1`, 'assistant', 'branch two'),
-      msg('m2', `${SID}-m1`, 'assistant', 'main line answer'),
-    ]
-    await writeFile(join(dir, 'sessions', '--demo-cwd--', `${SID}.jsonl`), lines.join('\n') + '\n')
-  }
-
-  beforeEach(async () => {
-    dataDir = await mkdtemp(join(tmpdir(), 'tool-handler-e7-'))
-    dir = join(dataDir, 'agent')
-  })
-  afterEach(async () => {
-    await rm(dataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
-  })
-
-  it('① allBranches:true → 旁支行标记 `[旁支 N entries]`（N=forkPoint 旁支子树 entry 数）+ 尾段同改前语义', async () => {
-    await writeForkSession()
-    const r = await handleSessionRead(
-      { action: 'outline', session: SID, allBranches: true },
-      { agentDir: dir },
-    )
-    const text = r.content[0].text
-    // 旁支标记带 entry 数；裸 `[旁支]` 旧形态零出现（'[旁支]' 与 '[旁支 2 entries]' 互不为子串）
-    expect(text).toContain('T000 · fork point turn · → main line answer · [旁支 2 entries]')
-    expect(text).not.toContain('[旁支]')
-    // stats 尾段与改前语义一致（totalEntries = leaf 2 + 旁支 2）
-    expect(text).toContain('1 turns · 4 entries · ')
-  })
-
-  it('② 两 action 一致性：export {format:"outline"} 物化全文 === outline content 文本（旁支行同形态）', async () => {
-    await writeForkSession()
-    const outline = await handleSessionRead(
-      { action: 'outline', session: SID, allBranches: true },
-      { agentDir: dir },
-    )
-    const exp = await handleSessionRead(
-      { action: 'export', session: SID, format: 'outline', allBranches: true },
-      { agentDir: dir },
-    )
-    const d = exp.details as { path: string }
-    const exported = await readFile(d.path, 'utf8')
-    // 干净 session（无坏行）下两 action 全文逐字节一致——同一 result.lines + 同一尾段拼装
-    expect(exported).toBe(outline.content[0].text)
-    expect(exported).toContain('[旁支 2 entries]')
-  })
-})
-
-describe('search 灾难性正则降级 + abort（fixture，MF-5 回归）', () => {
-  let dir: string
-  let dataDir: string
-  const SID = '019e6c96-bbbb-cccc-dddd-00000000000a'
-
-  beforeEach(async () => {
-    dataDir = await mkdtemp(join(tmpdir(), 'tool-handler-search-'))
-    dir = join(dataDir, 'agent')
-    await makeFixtureSession(dir, SID, 'aaa plugin 内容')
-  })
-  afterEach(async () => {
-    await rm(dataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
-  })
-
-  it('嵌套量词 pattern (a+)+ → 降级字面子串（不挂死，零命中）', async () => {
-    const r = await handleSessionRead({ action: 'search', session: SID, pattern: '(a+)+' }, { agentDir: dir })
-    const d = r.details as { hits: unknown[] }
-    // 字面量 '(a+)+' 不在内容里 → 0 命中（若按正则执行会命中 'aaa' 且可能指数回溯）
-    expect(d.hits).toHaveLength(0)
-  })
-
-  it('普通正则仍按正则匹配', async () => {
-    const r = await handleSessionRead({ action: 'search', session: SID, pattern: 'a+' }, { agentDir: dir })
-    const d = r.details as { hits: unknown[] }
-    expect(d.hits.length).toBeGreaterThan(0)
-  })
-
-  it('范围量词 {m,n} 形态 → 降级字面子串（(a{1,3})*、(a{0,2})*、(a{1,3}){2,}，MF-1 回归）', async () => {
-    for (const pattern of ['(a{1,3})*', '(a{0,2})*', '(a{1,3}){2,}']) {
-      const r = await handleSessionRead({ action: 'search', session: SID, pattern }, { agentDir: dir })
-      const d = r.details as { hits: unknown[] }
-      // 字面量不含这些 pattern → 0 命中；若按正则执行会指数回溯挂死
-      expect(d.hits, `pattern=${pattern}`).toHaveLength(0)
-    }
-  })
-
-  it('alternation/嵌套量词分支 (a|aa)+、(a*)* → 降级字面子串（MF-5 分支回归）', async () => {
-    for (const pattern of ['(a|aa)+', '(a*)*']) {
-      const r = await handleSessionRead({ action: 'search', session: SID, pattern }, { agentDir: dir })
-      const d = r.details as { hits: unknown[] }
-      expect(d.hits, `pattern=${pattern}`).toHaveLength(0)
-    }
-  })
-
-  it('(a{1,3}) 单独使用不被降级（组后无尾随量词，仍按正则执行）', async () => {
-    const r = await handleSessionRead(
-      { action: 'search', session: SID, pattern: '(a{1,3})' },
-      { agentDir: dir },
-    )
-    const d = r.details as { hits: unknown[] }
-    // 按正则执行命中 'aaa' → >0 命中（若被降级为字面量则 0 命中）
-    expect(d.hits.length).toBeGreaterThan(0)
-  })
-
-  it('降级标注：header 含「已降级为字面子串匹配」（S-3）', async () => {
-    const r = await handleSessionRead({ action: 'search', session: SID, pattern: '(a+)+' }, { agentDir: dir })
-    expect(r.content[0].text).toContain('已降级为字面子串匹配')
-  })
-
-  it('非法正则 pattern → 字面子串兜底不抛错（零命中，S-6）', async () => {
-    const r = await handleSessionRead({ action: 'search', session: SID, pattern: '[unclosed' }, { agentDir: dir })
-    const d = r.details as { hits: unknown[] }
-    expect(d.hits).toHaveLength(0)
-  })
-
-  it('scope 过滤：scope=assistant 零命中（fixture 仅 user 角色，S-6）', async () => {
-    const r = await handleSessionRead(
-      { action: 'search', session: SID, pattern: 'aaa', scope: 'assistant' },
-      { agentDir: dir },
-    )
-    const d = r.details as { hits: unknown[] }
-    expect(d.hits).toHaveLength(0)
-  })
-
-  it('limit 截断 → truncated=true + hits 限长（3 条命中 limit=2，S-6）', async () => {
-    const sid2 = '019e6c96-bbbb-cccc-dddd-00000000000b'
-    // message 链式 parentId（与真实 pi session 一致）：m0→session 根，m1→m0，m2→m1，
-    // 否则 buildTreeView 只回溯最后一条的父链，前两条被当旁支过滤
-    const lines = [
-      JSON.stringify({ type: 'session', id: sid2, cwd: '/demo' }),
-      ...['aa1', 'aa2', 'aa3'].map((t, i) =>
-        JSON.stringify({
-          type: 'message',
-          id: `${sid2}-m${i}`,
-          parentId: i === 0 ? sid2 : `${sid2}-m${i - 1}`,
-          message: { role: 'user', content: [{ type: 'text', text: t }] },
-        }),
-      ),
-    ]
-    await writeFile(
-      join(dir, 'sessions', '--demo-cwd--', `${sid2}.jsonl`),
-      lines.join('\n') + '\n',
-    )
-    const r = await handleSessionRead(
-      { action: 'search', session: sid2, pattern: 'aa', limit: 2 },
-      { agentDir: dir },
-    )
-    const d = r.details as { hits: unknown[]; truncated: boolean }
-    expect(d.truncated).toBe(true)
-    expect(d.hits).toHaveLength(2)
-  })
-
-  it('aborted signal → search 抛中断错误（不继续扫描）', async () => {
-    const ac = new AbortController()
-    ac.abort()
-    await expect(
-      handleSessionRead({ action: 'search', session: SID, pattern: 'x' }, { agentDir: dir }, ac.signal),
-    ).rejects.toThrow(/中断/)
-  })
-})
-
-describe('extract commits 双路径（fixture：git-cmd 主路径 + commit-context 次路径 + 去重）', () => {
-  let dir: string
-  let dataDir: string
-  const SID = '019e6c96-bbbb-cccc-dddd-00000000000c'
-
-  beforeEach(async () => {
-    dataDir = await mkdtemp(join(tmpdir(), 'tool-handler-commits-'))
-    dir = join(dataDir, 'agent')
-  })
-  afterEach(async () => {
-    await rm(dataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
-  })
-
-  /** 写单个 session JSONL（commits 用例行内联传入）。 */
-  async function writeCommitsSession(id: string, lines: string[]): Promise<void> {
-    await mkdir(join(dir, 'sessions', '--demo-cwd--'), { recursive: true })
-    await writeFile(
-      join(dir, 'sessions', '--demo-cwd--', `${id}.jsonl`),
-      lines.join('\n') + '\n',
-    )
-  }
-
-  it('commit-context 次路径：非 git bash 的 toolResult，hash 邻近含关键词才收（D6）', async () => {
-    await writeCommitsSession(SID, [
-      JSON.stringify({ type: 'session', id: SID, cwd: '/demo' }),
-      JSON.stringify({
-        type: 'message',
-        id: `${SID}-m1`,
-        parentId: SID,
-        message: {
-          role: 'assistant',
-          content: [
-            { type: 'toolCall', id: 'tc-read-1', name: 'read', arguments: { path: join(tmpdir(), 'log.txt') } },
-          ],
-        },
-      }),
-      // read 结果：hash 邻近 30 字符窗口含 'feat:' → commit-context 次路径纳入
-      JSON.stringify({
-        type: 'message',
-        id: `${SID}-m2`,
-        parentId: `${SID}-m1`,
-        message: {
-          role: 'toolResult',
-          toolName: 'read',
-          toolCallId: 'tc-read-1',
-          content: [{ type: 'text', text: 'deploy abc1234f done\nfeat: add login' }],
-        },
-      }),
-      // read 结果：hash 无关键词邻近 → 两路径都不收（过滤分支）
-      JSON.stringify({
-        type: 'message',
-        id: `${SID}-m3`,
-        parentId: `${SID}-m2`,
-        message: {
-          role: 'assistant',
-          content: [
-            { type: 'toolCall', id: 'tc-read-2', name: 'read', arguments: { path: join(tmpdir(), 'out.txt') } },
-          ],
-        },
-      }),
-      JSON.stringify({
-        type: 'message',
-        id: `${SID}-m4`,
-        parentId: `${SID}-m3`,
-        message: {
-          role: 'toolResult',
-          toolName: 'read',
-          toolCallId: 'tc-read-2',
-          content: [{ type: 'text', text: 'output 9998887 plain text' }],
-        },
-      }),
-    ])
-    const r = await handleSessionRead({ action: 'extract', session: SID, what: 'commits' }, { agentDir: dir })
-    const d = r.details as { count: number; items: Array<{ hash: string; source: string }> }
-    const hashes = d.items.map((it) => it.hash)
-    expect(hashes).toContain('abc1234f')
-    expect(hashes).not.toContain('9998887')
-    expect(d.items.find((it) => it.hash === 'abc1234f')?.source).toBe('commit-context')
-  })
-
-  it('去重高置信优先：同 hash 同时命中 git-cmd 与 commit-context → 保留 git-cmd 一条', async () => {
-    await writeCommitsSession(SID, [
-      JSON.stringify({ type: 'session', id: SID, cwd: '/demo' }),
-      JSON.stringify({
-        type: 'message',
-        id: `${SID}-m1`,
-        parentId: SID,
-        message: {
-          role: 'assistant',
-          content: [
-            { type: 'toolCall', id: 'tc-bash-1', name: 'bash', arguments: { command: 'git log --oneline -3' } },
-          ],
-        },
-      }),
-      // bash + git log → git-cmd 高置信（含 def5678a）
-      JSON.stringify({
-        type: 'message',
-        id: `${SID}-m2`,
-        parentId: `${SID}-m1`,
-        message: {
-          role: 'toolResult',
-          toolName: 'bash',
-          toolCallId: 'tc-bash-1',
-          content: [{ type: 'text', text: 'def5678a feat: fix crash' }],
-        },
-      }),
-      JSON.stringify({
-        type: 'message',
-        id: `${SID}-m3`,
-        parentId: `${SID}-m2`,
-        message: {
-          role: 'assistant',
-          content: [
-            { type: 'toolCall', id: 'tc-read-1', name: 'read', arguments: { path: join(tmpdir(), 'deploy.txt') } },
-          ],
-        },
-      }),
-      // read 结果同 hash def5678a + 关键词 merged → low 候选，去重后丢弃
-      JSON.stringify({
-        type: 'message',
-        id: `${SID}-m4`,
-        parentId: `${SID}-m3`,
-        message: {
-          role: 'toolResult',
-          toolName: 'read',
-          toolCallId: 'tc-read-1',
-          content: [{ type: 'text', text: 'deploy def5678a merged' }],
-        },
-      }),
-    ])
-    const r = await handleSessionRead({ action: 'extract', session: SID, what: 'commits' }, { agentDir: dir })
-    const d = r.details as { count: number; items: Array<{ hash: string; source: string }> }
-    const dupes = d.items.filter((it) => it.hash === 'def5678a')
-    expect(dupes).toHaveLength(1)
-    expect(dupes[0].source).toBe('git-cmd')
-    expect(d.count).toBe(1)
-  })
-})
-
-describe('renderExtractItems F9 截断（S3 首项超大 + S4 文案）', () => {
-  it('S3: 首项超大内部截断 → body 不超预算，shown<count + truncated=true', () => {
-    // 首项 10000 字符 >> EXTRACT_BUDGET_BYTES(8000)；旧逻辑放行首项致 body≈10KB
-    const longText = 'x'.repeat(10000)
-    const items = [
-      { turn: 5, text: longText },
-      { turn: 6, text: 'short6' },
-      { turn: 7, text: 'short7' },
-    ]
-    const r = renderExtractItems(
-      'user-messages',
-      items,
-      (it) => `T${String(it.turn).padStart(3, '0')}: ${it.text}`,
-      (it) => [it.turn],
-    )
-    const d = r.details as { what: string; count: number; shown: number; truncated: boolean }
-    expect(d.truncated).toBe(true)
-    expect(d.count).toBe(3)
-    expect(d.shown).toBe(1) // 首项截断后保留，后续项因预算用未加入
-    // body（含文案行）字节数远小于 3 项全量（30000+ 字节），≤ 预算 + 合理余量
-    const bodyBytes = Buffer.byteLength(r.content[0].text, 'utf8')
-    expect(bodyBytes).toBeLessThan(8000 * 1.5)
-    // 截断标记存在（首项被内部 slice + 省略号）
-    expect(r.content[0].text).toContain('…')
-    // 完整 longText 不在输出里（已被截断）
-    expect(r.content[0].text).not.toContain(longText)
-  })
-
-  it('S4: F9 文案含实际 turn 范围 + 实际 token（非固定 2000）', () => {
-    // 3 项各 ~3000 字节，累计超 8000 → 第 3 项触发截断（文案报 shown turn 范围）
-    const items = [
-      { turn: 10, text: 'a'.repeat(3000) },
-      { turn: 20, text: 'b'.repeat(3000) },
-      { turn: 30, text: 'c'.repeat(3000) },
-    ]
-    const r = renderExtractItems(
-      'user-messages',
-      items,
-      (it) => `T${String(it.turn).padStart(3, '0')}: ${it.text}`,
-      (it) => [it.turn],
-    )
-    const text = r.content[0].text
-    // 文案含 turn 范围（shown 的 min-max turn）
-    expect(text).toMatch(/T010-T0\d{2}/)
-    // 文案含实际 token（从 body 实际字节算），不再是固定 2000
-    expect(text).toContain('token 达预算上限')
-    expect(text).not.toContain('≈2000 token')
-    // 文案含 shown/count
-    expect(text).toMatch(/已显示 \d+\/\d+ 项/)
-  })
-})
-
-// ============================================================
-// w2 新增：resolveSessionId 三形态（① 绝对路径 / ② sa-id / ③ findSessions 透传 source）
-// + ES1/ES2 错误契约 + source 透传 + 真实数据检查（design TC2-TC18）
-// ============================================================
-
-/**
- * 造 subagent manifest + session 文件（TC7/TC8/TC10/CQ3/TC14-TC17 用）。
- * sessionFileExists:false 模拟 GC（manifest 存在但 session 文件不存在 → ES1）。
- * slug 可指定 cwd 编码目录名（TC15 worktree 形态），缺省 '--demo-cwd--'。
- * 返回 session 文件绝对路径（= manifest.sessionFile）。
- */
-async function makeFixtureSubagent(
-  dir: string,
-  saId: string,
-  opts: {
-    realSessionId: string
-    rootSessionId?: string
-    agentName?: string
-    sessionFileExists?: boolean
-    firstUserText?: string
-    slug?: string
-  },
-): Promise<string> {
-  // [session-store-layout-inversion] 新布局存储树：分区键 = rootSessionId（无 encodeCwd
-  // 目录层，opts.slug 已无布局语义，保留入参兼容旧调用点但不参与路径推导）
-  const rootSid = opts.rootSessionId ?? 'root-session-1'
-  const sessionFile = join(resolveStoreSubagentSessionsDir(dir, rootSid), `${opts.realSessionId}.jsonl`)
-  if (opts.sessionFileExists !== false) {
-    await mkdir(resolveStoreSubagentSessionsDir(dir, rootSid), { recursive: true })
-    const lines = [
-      JSON.stringify({ type: 'session', id: opts.realSessionId, cwd: '/demo' }),
-      JSON.stringify({
-        type: 'message',
-        id: opts.realSessionId + '-m1',
-        parentId: opts.realSessionId,
-        message: {
-          role: 'user',
-          content: [{ type: 'text', text: opts.firstUserText ?? 'subagent work' }],
-        },
-      }),
-    ]
-    await writeFile(sessionFile, lines.join('\n') + '\n')
-  }
-  const recordsDir = resolveStoreSubagentRecordsDir(dir, rootSid)
-  await mkdir(recordsDir, { recursive: true })
-  await writeFile(
-    join(recordsDir, `${saId}.json`),
-    JSON.stringify({
-      id: saId,
-      rootSessionId: rootSid,
-      agentName: opts.agentName ?? 'explorer',
-      sessionFile,
-    }),
-  )
-  return sessionFile
-}
-
-describe('resolveSessionId ① 绝对路径形态（w2 TC2-TC6）', () => {
-  let dataDir: string
-  let dir: string // agentDir = <dataDir>/agent（生产拓扑复刻，[session-store-layout-inversion]）
-
-  beforeEach(async () => {
-    dataDir = await mkdtemp(join(tmpdir(), 'tool-handler-path-'))
-    dir = join(dataDir, 'agent')
-  })
-  afterEach(async () => {
-    await rm(dataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
-  })
-
-  it('TC2: 绝对路径 outline → sessionId=header 真实 id（非文件名）', async () => {
-    const fileId = '019e6c96-dddd-eeee-ffff-000000000b1'
-    // 文件名 arbitrary-name 与 header id 不同，验 sessionId 取 header id
-    const filePath = join(dir, 'sessions', '--demo-cwd--', 'arbitrary-name.jsonl')
-    await mkdir(join(dir, 'sessions', '--demo-cwd--'), { recursive: true })
-    const lines = [
-      JSON.stringify({ type: 'session', id: fileId, cwd: '/demo' }),
-      JSON.stringify({
-        type: 'message',
-        id: fileId + '-m1',
-        parentId: fileId,
-        message: { role: 'user', content: [{ type: 'text', text: 'hi' }] },
-      }),
-    ]
-    await writeFile(filePath, lines.join('\n') + '\n')
-    // export 的 details.path = session-view-<sessionId>.md，含 header 真实 id，不含文件名
-    const r = await handleSessionRead(
-      { action: 'export', session: filePath, format: 'outline' },
-      { agentDir: dir },
-    )
-    const d = r.details as { path: string }
-    expect(d.path).toContain(fileId)
-    expect(d.path).not.toContain('arbitrary-name')
-  })
-
-  it('TC3: 绝对路径文件不存在 → F6 风格错误（含 👉）', async () => {
-    const filePath = join(
-      dir,
-      'sessions',
-      '--demo-cwd--',
-      `not-exist-${Date.now()}.jsonl`,
-    )
-    await expect(
-      handleSessionRead({ action: 'outline', session: filePath }, { agentDir: dir }),
-    ).rejects.toThrow(/读取失败.*文件不存在/)
-    await expect(
-      handleSessionRead({ action: 'outline', session: filePath }, { agentDir: dir }),
-    ).rejects.toThrow('👉')
-  })
-
-  it('TC4: 绝对路径非 .jsonl → F6 风格错误', async () => {
-    const filePath = join(dir, 'sessions', '--demo-cwd--', 'x.txt')
-    await mkdir(join(dir, 'sessions', '--demo-cwd--'), { recursive: true })
-    await writeFile(filePath, 'not jsonl')
-    await expect(
-      handleSessionRead({ action: 'outline', session: filePath }, { agentDir: dir }),
-    ).rejects.toThrow(/读取失败.*非 \.jsonl/)
-  })
-
-  it('TC5: 绝对路径 header 读不出（首行非 session header）→ F6 风格错误', async () => {
-    const filePath = join(dir, 'sessions', '--demo-cwd--', 'bad.jsonl')
-    await mkdir(join(dir, 'sessions', '--demo-cwd--'), { recursive: true })
-    await writeFile(filePath, JSON.stringify({ type: 'custom', customType: 'x' }) + '\n')
-    await expect(
-      handleSessionRead({ action: 'outline', session: filePath }, { agentDir: dir }),
-    ).rejects.toThrow(/读取失败.*首行非合法 session header/)
-  })
-
-  it('TC5 变体: 绝对路径空文件 → F6 风格错误', async () => {
-    const filePath = join(dir, 'sessions', '--demo-cwd--', 'empty.jsonl')
-    await mkdir(join(dir, 'sessions', '--demo-cwd--'), { recursive: true })
-    await writeFile(filePath, '')
-    await expect(
-      handleSessionRead({ action: 'outline', session: filePath }, { agentDir: dir }),
-    ).rejects.toThrow(/读取失败.*首行非合法 session header/)
-  })
-
-  it('TC6: ~ 前缀展开到 homedir（文件实际在 homedir 下）', async () => {
-    // fs-guard：真实 homedir 根在白名单外（禁止在用户主目录根散落 .sr-w2-test-*）——
-    // homedir 经文件头 vi.mock 指到 mkdtemp tmp（白名单内），「~ 前缀展开」断言语义不变
-    const fakeHome = await mkdtemp(join(tmpdir(), 'tool-handler-tc6-home-'))
-    homeState.fakeHome = fakeHome
-    try {
-      const home = homedir()
-      const tmpUnderHome = await mkdtemp(join(home, '.sr-w2-test-'))
-      try {
-        const fileId = '019e6c96-dddd-eeee-ffff-0000000006c1'
-        const sessionFile = join(tmpUnderHome, 's.jsonl')
-        await writeFile(
-          sessionFile,
-          JSON.stringify({ type: 'session', id: fileId, cwd: '/demo' }) + '\n',
-        )
-        // ~/开头的相对 homedir 路径
-        const tildePath = '~/' + sessionFile.slice(home.length + 1)
-        const r = await handleSessionRead(
-          { action: 'export', session: tildePath, format: 'outline' },
-          { agentDir: dir },
-        )
-        expect((r.details as { path: string }).path).toContain(fileId)
-      } finally {
-        await rm(tmpUnderHome, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
-      }
-    } finally {
-      homeState.fakeHome = undefined
-      await rm(fakeHome, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
-    }
-  })
-})
-
-describe('resolveSessionId ② sa-id 形态（w2 TC7-TC10 + CQ3）', () => {
-  let dataDir: string
-  let dir: string // agentDir = <dataDir>/agent（生产拓扑复刻，[session-store-layout-inversion]）
-
-  beforeEach(async () => {
-    dataDir = await mkdtemp(join(tmpdir(), 'tool-handler-said-'))
-    dir = join(dataDir, 'agent')
-  })
-  afterEach(async () => {
-    await rm(dataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
-  })
-
-  it('TC7: sa-id 恰 1 命中 + sessionFile 存在 → 成功，sessionId=header 真实 id（非 sa-）', async () => {
-    const realId = '019e6c96-dddd-eeee-ffff-0000000007a1'
-    await makeFixtureSubagent(dir, 'sa-aaa', { realSessionId: realId, firstUserText: 'do task' })
-    const r = await handleSessionRead(
-      { action: 'export', session: 'sa-aaa', format: 'outline' },
-      { agentDir: dir },
-    )
-    const d = r.details as { path: string }
-    expect(d.path).toContain(realId)
-    expect(d.path).not.toContain('sa-aaa')
-  })
-
-  it('TC8: sa-id 命中但 sessionFile 不存在（GC/未写入）→ ES1（含 manifest 元数据 + 👉）', async () => {
-    await makeFixtureSubagent(dir, 'sa-gc', {
-      realSessionId: '019e6c96-dddd-eeee-ffff-0000000008a2',
-      rootSessionId: 'root-1',
-      agentName: 'explorer',
-      sessionFileExists: false,
-    })
-    await expect(
-      handleSessionRead({ action: 'outline', session: 'sa-gc' }, { agentDir: dir }),
-    ).rejects.toThrow('session 文件不存在')
-    // 错误含 manifest 全部元数据 + 👉
-    try {
-      await handleSessionRead({ action: 'outline', session: 'sa-gc' }, { agentDir: dir })
-    } catch (e) {
-      const msg = (e as Error).message
-      expect(msg).toContain('sa-gc')
-      expect(msg).toContain('root-1')
-      expect(msg).toContain('explorer')
-      expect(msg).toContain('sessionFile:')
-      expect(msg).toContain('👉')
-      expect(msg).toContain('action:"family"')
-    }
-  })
-
-  it('TC9: sa-id 0 命中（可能 running）→ zcode_record_not_found（U9：sa-id 语境统一错误范围，含 family 指引 + 👉）', async () => {
-    await expect(
-      handleSessionRead({ action: 'outline', session: 'sa-nonexist-9999' }, { agentDir: dir }),
-    ).rejects.toThrow('zcode_record_not_found')
-    try {
-      await handleSessionRead({ action: 'outline', session: 'sa-nonexist-9999' }, { agentDir: dir })
-    } catch (e) {
-      const msg = (e as Error).message
-      expect(msg).toContain('未落盘')
-      expect(msg).toContain('action:"family"')
-      expect(msg).toContain('👉')
-    }
-  })
-
-  it('TC10: sa-id 片段输入（精确相等不命中）→ zcode_record_not_found + 完整 sa- id 重试指引（U9 统一错误范围）', async () => {
-    await makeFixtureSubagent(dir, 'sa-c8c8dfa8', {
-      realSessionId: '019e6c96-dddd-eeee-ffff-0000000010a3',
     })
-    // 片段 sa-c8c8 不等于完整 sa-c8c8dfa8 → 精确相等不命中（兜底亦未命中）
-    await expect(
-      handleSessionRead({ action: 'outline', session: 'sa-c8c8' }, { agentDir: dir }),
-    ).rejects.toThrow('zcode_record_not_found')
-    // 片段输入恢复路径在指引内可见（A4：ES2 原文案「用完整 sa- id 重试」的覆盖补全）
-    await expect(
-      handleSessionRead({ action: 'outline', session: 'sa-c8c8' }, { agentDir: dir }),
-    ).rejects.toThrow(/完整 sa- id（形如 `sa-xxxx`）后重试/)
-  })
 
-  it('sa-id 多 manifest 命中（数据异常）→ ES2 ambiguous（C4）', async () => {
-    // 同 sa-id 的两个 manifest（不同 rootSessionId 分区，模拟数据异常——新布局分区键 =
-    // rootSessionId，同分区同名 manifest 会互覆，双 manifest 只能跨分区构造）
-    for (const [rootSid, realId] of [
-      ['0aaaaaaa-bbbb-7ccc-dddd-0000000004r1', '019e6c96-dddd-eeee-ffff-0000000004a4'],
-      ['0aaaaaaa-bbbb-7ccc-dddd-0000000004r2', '019e6c96-dddd-eeee-ffff-0000000004a5'],
-    ] as const) {
-      const sessionsDir = resolveStoreSubagentSessionsDir(dir, rootSid)
-      const sessionFile = join(sessionsDir, `${realId}.jsonl`)
-      await mkdir(sessionsDir, { recursive: true })
-      await writeFile(
-        sessionFile,
-        JSON.stringify({ type: 'session', id: realId, cwd: '/demo' }) + '\n',
-      )
-      const recordsDir = resolveStoreSubagentRecordsDir(dir, rootSid)
-      await mkdir(recordsDir, { recursive: true })
-      await writeFile(
-        join(recordsDir, 'sa-dup.json'),
-        JSON.stringify({
-          id: 'sa-dup',
-          rootSessionId: rootSid,
-          agentName: 'a',
-          sessionFile,
-        }),
+    it('find 零匹配 → No sessions matching', () => {
+      const r = toolResult({ matches: [], truncated: false })
+      expect(buildSessionReadSummary(params({ action: 'find', query: 'gone' }), r)).toBe(
+        'No sessions matching "gone"',
       )
-    }
-    await expect(
-      handleSessionRead({ action: 'outline', session: 'sa-dup' }, { agentDir: dir }),
-    ).rejects.toThrow(/匹配 2 个 record.*数据异常/)
-  })
-
-  it('CQ3: sa-id 命中但 sessionFile header 读不出 → F6 风格（不降级 record.id 当 sessionId）', async () => {
-    // sessionFile 存在但首行非 session header → readSessionHeaderIdSync 返 undefined
-    const rootSid = 'r' // 合法 pi sid 形态（单字符分区）
-    const sessionFile = join(resolveStoreSubagentSessionsDir(dir, rootSid), 'bad.jsonl')
-    await mkdir(dirname(sessionFile), { recursive: true })
-    await writeFile(sessionFile, JSON.stringify({ type: 'custom', customType: 'x' }) + '\n')
-    const recordsDir = resolveStoreSubagentRecordsDir(dir, rootSid)
-    await mkdir(recordsDir, { recursive: true })
-    await writeFile(
-      join(recordsDir, 'sa-bad.json'),
-      JSON.stringify({
-        id: 'sa-bad',
-        rootSessionId: 'r',
-        agentName: 'a',
-        sessionFile,
-      }),
-    )
-    // 抛 F6 风格（读取失败 + 首行非合法 session header），不降级返回 sa-bad 当 sessionId
-    await expect(
-      handleSessionRead({ action: 'outline', session: 'sa-bad' }, { agentDir: dir }),
-    ).rejects.toThrow(/读取失败.*首行非合法 session header/)
-  })
-})
-
-describe('sa-id entry 兜底 v2 终态条锚定（W1 D1 版本门补齐，第三层兜底消费方）', () => {
-  // fixture 骨架对齐 zcode-routing.test.ts：root/agent = agentDir、root/live-sessions =
-  // liveSessionDir（entry 兜底候选根）、root/engines/zcode/session-db/db.sqlite = 隔离库
-  // 白名单形态路径（不落文件——正向用例锚命中后进 zcode 读链，在白名单存在性检查处
-  // 产出 zcode_db_unreadable，无需真实 sqlite）。
-  const ISOLATED_DB_SEGMENTS = ['engines', 'zcode', 'session-db', 'db.sqlite']
-  let root: string
-  let agentDir: string
-  let liveDir: string
-  let dbPath: string
-  let appendEntries: ReturnType<typeof vi.fn>
-
-  beforeEach(async () => {
-    root = await mkdtemp(join(tmpdir(), 'tool-handler-v2anchor-'))
-    agentDir = join(root, 'agent')
-    liveDir = join(root, 'live-sessions')
-    await mkdir(agentDir, { recursive: true })
-    await mkdir(liveDir, { recursive: true })
-    dbPath = join(root, ...ISOLATED_DB_SEGMENTS)
-    appendEntries = vi.fn()
-    setPiHandle({ appendEntry: appendEntries } as unknown as Parameters<typeof setPiHandle>[0])
-  })
-  afterEach(async () => {
-    setPiHandle(undefined)
-    await rm(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
-  })
-
-  /** live session 内追加 subagent-record custom 行（首行 session header）。 */
-  async function writeLiveEntryLine(lineData: Record<string, unknown>): Promise<void> {
-    const path = join(liveDir, 'main.jsonl')
-    await writeFile(
-      path,
-      JSON.stringify({ type: 'session', id: 'live-main-1', cwd: '/proj' }) +
-        '\n' +
-        JSON.stringify({ type: 'custom', customType: 'subagent-record', id: 'e-v2', parentId: null, data: lineData }) +
-        '\n',
-    )
-  }
-
-  /** v2 终态条 data（载荷形态对齐 subagent-core SubagentRecordSettledEntryData）。 */
-  function v2SettledData(opts: { engine?: string; sessionRef?: Record<string, string> } = {}): Record<string, unknown> {
-    const data: Record<string, unknown> = {
-      v: 2,
-      kind: 'settled',
-      id: 'sa-v2-1',
-      status: 'idle',
-      stopReason: 'end_turn',
-      endedAt: 123,
-      turns: 2,
-      totalTokens: 20,
-      model: undefined,
-      thinkingLevel: undefined,
-      result: 'done text',
-    }
-    if (opts.engine !== undefined) data.engine = opts.engine
-    if (opts.sessionRef !== undefined) {
-      data.engineHandle = { sessionRef: opts.sessionRef, poolKey: 'shared' }
-    }
-    return data
-  }
-
-  /** v2 注册条 data（身份域，不携带 engineHandle——非锚源）。 */
-  function v2RegisteredData(): Record<string, unknown> {
-    return {
-      v: 2,
-      kind: 'registered',
-      id: 'sa-v2-1',
-      agent: 'dev',
-      task: 't',
-      slug: 's',
-      origin: 'tool',
-      rootSessionId: 'live-main-1',
-      depth: 0,
-      startedAt: 1,
-    }
-  }
-
-  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
-  }
-
-  it('v2 终态条完整锚 → 兜底命中进 zcode 读链（dbPath 白名单内未落盘 → zcode_db_unreadable，非 not_found）', async () => {
-    await writeLiveEntryLine(v2SettledData({ engine: 'zcode', sessionRef: { sessionId: 'sess_v2', dbPath } }))
-    // 锚命中 → resolveZcodeRoute → zcode 读链 → 白名单存在性检查（文件未落盘）
-    // zcode_db_unreadable = 锚定成功的输出级证据（锚未命中此处是 zcode_record_not_found）
-    await expect(
-      handleSessionRead({ action: 'outline', session: 'sa-v2-1' }, { agentDir, liveSessionDir: liveDir }),
-    ).rejects.toThrow('zcode_db_unreadable')
-  })
-
-  it('v2 终态条 engine=zcode 但 sessionRef 缺 dbPath → zcode_anchor_missing + 结构化日志记「缺 dbPath」', async () => {
-    await writeLiveEntryLine(v2SettledData({ engine: 'zcode', sessionRef: { sessionId: 'sess_v2' } }))
-    await expect(
-      handleSessionRead({ action: 'outline', session: 'sa-v2-1' }, { agentDir, liveSessionDir: liveDir }),
-    ).rejects.toThrow('zcode_anchor_missing')
-    // 归因进结构化日志不进 LLM 可见部分（§3.4）：firstIncompleteAnchorReason 的 v2 分支
-    //（tool-handler 唯一消费点）产出 missing-dbPath
-    expect(logCallsWithReason('missing-dbPath')).toBeGreaterThanOrEqual(1)
-  })
-
-  it('v2 注册条（kind="registered"）不是锚源 → zcode_record_not_found（不误报 anchor_missing）', async () => {
-    await writeLiveEntryLine(v2RegisteredData())
-    await expect(
-      handleSessionRead({ action: 'outline', session: 'sa-v2-1' }, { agentDir, liveSessionDir: liveDir }),
-    ).rejects.toThrow('zcode_record_not_found')
-    await expect(
-      handleSessionRead({ action: 'outline', session: 'sa-v2-1' }, { agentDir, liveSessionDir: liveDir }),
-    ).rejects.not.toThrow('zcode_anchor_missing')
-  })
-
-  it('v2 终态条 engine 缺省（pi 形态 v2）→ zcode_record_not_found（D5 engine 判别防误归因）', async () => {
-    // pi record 的 v2 终态条：engine 缺省、sessionRef 无 dbPath——不是「zcode 锚不完整」，
-    // 不适用旧版本产物指引；误归因 missing-dbPath → zcode_anchor_missing 即红
-    await writeLiveEntryLine(v2SettledData())
-    await expect(
-      handleSessionRead({ action: 'outline', session: 'sa-v2-1' }, { agentDir, liveSessionDir: liveDir }),
-    ).rejects.toThrow('zcode_record_not_found')
-    await expect(
-      handleSessionRead({ action: 'outline', session: 'sa-v2-1' }, { agentDir, liveSessionDir: liveDir }),
-    ).rejects.not.toThrow('zcode_anchor_missing')
-  })
-})
-
-describe('source 透传（w2 TC12-TC13，依赖 w1 findSessions opts.source）', () => {
-  let dataDir: string
-  let dir: string // agentDir = <dataDir>/agent（生产拓扑复刻，[session-store-layout-inversion]）
-
-  beforeEach(async () => {
-    dataDir = await mkdtemp(join(tmpdir(), 'tool-handler-src-'))
-    dir = join(dataDir, 'agent')
-  })
-  afterEach(async () => {
-    await rm(dataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
-  })
-
-  it('TC12: find source 过滤——subagent 只返回 subagent 候选，main 只返回 main', async () => {
-    const sharedFragment = '019e6c96'
-    const mainId = `${sharedFragment}-aaaa-bbbb-cccc-0000000012d1`
-    const subId = `${sharedFragment}-aaaa-bbbb-cccc-0000000012d2`
-    await makeFixtureSession(dir, mainId, 'main content')
-    await makeFixtureSubagent(dir, 'sa-sub12', { realSessionId: subId, firstUserText: 'sub content' })
-
-    // 无 source → 两者
-    const rBoth = await handleSessionRead(
-      { action: 'find', query: sharedFragment },
-      { agentDir: dir },
-    )
-    const dBoth = rBoth.details as {
-      matches: Array<{ source: string; sessionId: string }>
-    }
-    expect(dBoth.matches.some((m) => m.sessionId === mainId)).toBe(true)
-    expect(dBoth.matches.some((m) => m.sessionId === subId)).toBe(true)
-
-    // source:subagent → 只 sub
-    const rSub = await handleSessionRead(
-      { action: 'find', query: sharedFragment, source: 'subagent' },
-      { agentDir: dir },
-    )
-    const dSub = rSub.details as {
-      matches: Array<{ source: string; sessionId: string }>
-    }
-    expect(dSub.matches.every((m) => m.source === 'subagent')).toBe(true)
-    expect(dSub.matches.some((m) => m.sessionId === subId)).toBe(true)
-    expect(dSub.matches.some((m) => m.sessionId === mainId)).toBe(false)
-
-    // source:main → 只 main
-    const rMain = await handleSessionRead(
-      { action: 'find', query: sharedFragment, source: 'main' },
-      { agentDir: dir },
-    )
-    const dMain = rMain.details as {
-      matches: Array<{ source: string; sessionId: string }>
-    }
-    expect(dMain.matches.every((m) => m.source === 'main')).toBe(true)
-    expect(dMain.matches.some((m) => m.sessionId === mainId)).toBe(true)
-    expect(dMain.matches.some((m) => m.sessionId === subId)).toBe(false)
-  })
-
-  it('TC13: outline source:main → resolveSessionId ③ 收窄到 main 候选（无 source 时多匹配 F2）', async () => {
-    const sharedFragment = '019e6c96'
-    const mainId = `${sharedFragment}-aaaa-bbbb-cccc-0000000013e1`
-    const subId = `${sharedFragment}-aaaa-bbbb-cccc-0000000013e2`
-    await makeFixtureSession(dir, mainId, 'main content')
-    await makeFixtureSubagent(dir, 'sa-sub13', { realSessionId: subId, firstUserText: 'sub content' })
-
-    // 无 source → main+sub 共享片段 → 2 匹配 → F2 消歧
-    const rMulti = await handleSessionRead(
-      { action: 'outline', session: sharedFragment },
-      { agentDir: dir },
-    )
-    expect((rMulti.details as { ambiguous: boolean }).ambiguous).toBe(true)
-
-    // source:main → 收窄到 main → 唯一匹配 → outline 成功，且是 main（export path 含 mainId）
-    const rExp = await handleSessionRead(
-      { action: 'export', session: sharedFragment, source: 'main', format: 'outline' },
-      { agentDir: dir },
-    )
-    expect((rExp.details as { path: string }).path).toContain(mainId)
-  })
-})
-
-describe('subagent sa-id（w2 TC14-TC17，fixture）', () => {
-  let dataDir: string
-  let dir: string // agentDir = <dataDir>/agent（生产拓扑复刻）
-  const TC14_ID = '0aaaaaaa-0000-7000-8000-0000000014a1'
-  const TC15_ID = '0aaaaaaa-0000-7000-8000-0000000015a2'
-
-  /**
-   * 两个存活 subagent + 一个 GC manifest：
-   * - TC14 走普通 slug（sa-id → manifest → sessionFile → outline）
-   * - TC15 的 sessionFile 落在 '--private-var-folders-' 编码目录（worktree cwd 形态），
-   *   覆盖 manifest 树的递归扫描
-   * - TC17 的 manifest sessionFile 指向不存在路径（模拟 .jsonl 被 GC）
-   */
-  beforeEach(async () => {
-    dataDir = await mkdtemp(join(tmpdir(), 'tool-handler-tc14-'))
-    dir = join(dataDir, 'agent')
-    await makeFixtureSubagent(dir, 'sa-tc14', {
-      realSessionId: TC14_ID,
-      firstUserText: 'subagent task',
-    })
-    await makeFixtureSubagent(dir, 'sa-tc15', {
-      realSessionId: TC15_ID,
-      slug: '--private-var-folders-abc--',
-      firstUserText: 'worktree subagent task',
     })
-    await makeFixtureSubagent(dir, 'sa-tc17-gc', {
-      realSessionId: '0aaaaaaa-0000-7000-8000-0000000017a3',
-      sessionFileExists: false,
-    })
-  })
-  afterEach(async () => {
-    await rm(dataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
-  })
-
-  it('TC14: completed subagent sa-id outline 成功（场景 1，sessionId=header 真实 id）', async () => {
-    const r = await handleSessionRead({ action: 'outline', session: 'sa-tc14' }, { agentDir: dir })
-    const d = r.details as { turns: unknown[] }
-    expect(d.turns.length).toBeGreaterThan(0)
-  })
-
-  it('TC15: worktree 编码目录 subagent 读取（场景 1b，递归扫描覆盖）', async () => {
-    const r = await handleSessionRead({ action: 'outline', session: 'sa-tc15' }, { agentDir: dir })
-    expect(((r.details as { turns: unknown[] }).turns).length).toBeGreaterThan(0)
-  })
-
-  it('TC16: 嵌套后代直接 outline（场景 1c，绝对路径形态读任意节点）', async () => {
-    // 绝对路径形态直接读（M0 入口不依赖 findSessions）
-    const r = await handleSessionRead(
-      {
-        action: 'outline',
-        session: join(resolveStoreSubagentSessionsDir(dir, 'root-session-1'), `${TC14_ID}.jsonl`),
-      },
-      { agentDir: dir },
-    )
-    expect(((r.details as { turns: unknown[] }).turns).length).toBeGreaterThan(0)
-  })
-
-  it('TC17: GC/failed manifest → ES1（场景 4，sessionFile 不存在）', async () => {
-    await expect(
-      handleSessionRead({ action: 'outline', session: 'sa-tc17-gc' }, { agentDir: dir }),
-    ).rejects.toThrow('session 文件不存在')
-  })
-})
-
-// ============================================================
-// w6: doWorkflow action（TC-w6-single-run/multi-run/runid-filter/runid-not-found/no-runs/snapshot-skip/call-jump）
-// ============================================================
-
-// ---- workflow fixture 常量（uuid 特征，互不为子串）----
-const WF_ROOT = '019w6aaa-0000-7000-b000-000000000001' // 发起 workflow 的 main session
-const WF_CALL = '019w6bbb-0000-7000-b000-000000000002' // workflow call 的目标 session（call-jump）
-const SUB_WF_ROOT = '019w6ccc-0000-7000-b000-000000000003' // 发起 workflow 的 subagent session（MF-2）
-
-/** 写 main session（header + 1 条 user message，让 outline 有 turn）。返回绝对路径。 */
-async function wfMainSession(
-  dir: string,
-  slug: string,
-  id: string,
-  opts?: { cwd?: string },
-): Promise<string> {
-  const sessionDir = join(dir, 'sessions', slug)
-  await mkdir(sessionDir, { recursive: true })
-  const path = join(sessionDir, `${id}.jsonl`)
-  const lines = [
-    JSON.stringify({ type: 'session', id, cwd: opts?.cwd ?? `/proj/${slug}` }),
-    JSON.stringify({
-      type: 'message',
-      id: `${id}-m1`,
-      parentId: id,
-      message: { role: 'user', content: [{ type: 'text', text: 'run workflow' }] },
-    }),
-  ]
-  await writeFile(path, lines.join('\n') + '\n')
-  return path
-}
-
-/** 写 wf-state 文件（每行一个快照 JSON）。返回绝对路径。 */
-async function wfStateFile(
-  dir: string,
-  slug: string,
-  fileName: string,
-  lines: string[],
-): Promise<string> {
-  const wfDir = join(dir, 'sessions', slug, 'workflow-state')
-  await mkdir(wfDir, { recursive: true })
-  const path = join(wfDir, fileName)
-  await writeFile(path, lines.join('\n') + '\n')
-  return path
-}
-
-describe('doWorkflow（w6，fixture）', () => {
-  let dataDir: string
-  let dir: string // agentDir = <dataDir>/agent（生产拓扑复刻，[session-store-layout-inversion]）
-
-  beforeEach(async () => {
-    dataDir = await mkdtemp(join(tmpdir(), 'tool-handler-wf-'))
-    dir = join(dataDir, 'agent')
-  })
-  afterEach(async () => {
-    await rm(dataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
-  })
-
-  // ---- [D16③] v2 record 流档概览（recordPath 锚点 = record 流路径）----
-
-  /** 向 main session 追加 workflow-record v2 注册条目行（recordPath 锚点指向 record 流）。 */
-  async function wfV2Registered(
-    dir: string,
-    slug: string,
-    id: string,
-    runId: string,
-    recordPath: string,
-  ): Promise<void> {
-    const sessionPath = join(dir, 'sessions', slug, `${id}.jsonl`)
-    const line = JSON.stringify({
-      type: 'custom',
-      id: `wf-reg-${runId}`,
-      parentId: id,
-      customType: 'workflow-record',
-      data: { v: 2, kind: 'registered', runId, workflowName: 'rec-flow', scriptName: 'rec-flow', slug: 'rec-flow', startedAt: 1758000000000, recordPath: recordPath },
-      timestamp: '2026-09-28T00:00:00Z',
-    })
-    await writeFile(sessionPath, line + '\n', { flag: 'a' })
-  }
-
-  /** 构造 v2 record 流文件（run-created + agent-settled[+终局] 帧提 calls）并写注册条目——
-   *  [ADR-0095] v1 读侧删除后的单档 fixture 形态（替代 wf-state 快照 + link 指针）。 */
-  async function wfV2Run(
-    dir: string,
-    slug: string,
-    id: string,
-    runId: string,
-    calls: Array<{ sessionId: string; sessionFile: string }>,
-    opts: { settled?: boolean } = {},
-  ): Promise<string> {
-    const lines = [
-      JSON.stringify({ type: 'run-created', seq: 1, ts: 1758000000000, runId, workflowName: 'test-wf', argsSummary: '{}' }),
-      ...calls.map((c, i) =>
-        JSON.stringify({ type: 'agent-settled', seq: 2 + i, ts: 1758000001000 + i, taskIndex: i, attempt: 1, outcome: 'done', durationMs: 100, result: { content: 'ok', sessionId: c.sessionId, sessionFile: c.sessionFile } }),
-      ),
-    ]
-    if (opts.settled) {
-      lines.push(JSON.stringify({ type: 'run-settled', seq: 2 + calls.length, ts: 1758000002000, outcome: 'done' }))
-    }
-    const recordPath = await wfStateFile(dir, slug, `${runId}.record.jsonl`, lines)
-    await wfV2Registered(dir, slug, id, runId, recordPath)
-    return recordPath
-  }
-
-  it('[D16③] v2 档 record 流概览：注册条目锚点直读流——steps 提 sessionFile、status 三态、不进 skippedRuns（活跃 run 红线）', async () => {
-    const slug = '--wf-record--'
-    await wfMainSession(dir, slug, WF_ROOT)
-    const callSession = join(dir, 'sessions', slug, `${WF_CALL}.jsonl`)
-    const recordPath = await wfStateFile(dir, slug, 'wf-rec-1.record.jsonl', [
-      JSON.stringify({ type: 'run-created', seq: 1, ts: 1758000000000, runId: 'wf-rec-1', workflowName: 'rec-flow', argsSummary: '{}' }),
-      JSON.stringify({ type: 'agent-started', seq: 2, ts: 1758000000100, taskIndex: 0, agentName: 'rec-step', attempt: 1 }),
-      JSON.stringify({ type: 'agent-settled', seq: 3, ts: 1758000001500, taskIndex: 0, attempt: 1, outcome: 'done', durationMs: 1400, result: { content: 'ok', sessionId: WF_CALL, sessionFile: callSession } }),
-      JSON.stringify({ type: 'run-settled', seq: 4, ts: 1758000002000, outcome: 'done', artifactsDir: '/tmp/wf' }),
-    ])
-    await wfV2Registered(dir, slug, WF_ROOT, 'wf-rec-1', recordPath)
-
-    const r = await handleSessionRead({ action: 'workflow', session: WF_ROOT }, { agentDir: dir })
-    const d = r.details as {
-      runs: Array<{ runId: string; status: string; script?: string; steps: Array<{ sessionId?: string; sessionFile?: string }> }>
-      skippedRuns?: unknown[]
-    }
-    // 红线：record 流 run 正常解析——不退化为 skippedRuns
-    expect(d.skippedRuns).toBeUndefined()
-    expect(d.runs).toHaveLength(1)
-    expect(d.runs[0].runId).toBe('wf-rec-1')
-    expect(d.runs[0].status).toBe('done')
-    expect(d.runs[0].script).toBe('rec-flow')
-    expect(d.runs[0].steps).toHaveLength(1)
-    expect(d.runs[0].steps[0].sessionFile).toBe(callSession)
-    expect(d.runs[0].steps[0].sessionId).toBe(WF_CALL)
-    expect(r.content[0].type).toBe('text')
-    expect((r.content[0] as { text: string }).text).toContain('wf-rec-1')
-    expect((r.content[0] as { text: string }).text).toContain('rec-step')
-  })
-
-  it('[D16③][D2] v2 档活跃 run（流无终局帧）→ status running、概览不退化为 skippedRuns；中断转移帧 → interrupted', async () => {
-    const slug = '--wf-running--'
-    await wfMainSession(dir, slug, WF_ROOT)
-    // 活跃：run-created + agent-started（无 settled/终局帧）
-    const activePath = await wfStateFile(dir, slug, 'wf-run-1.record.jsonl', [
-      JSON.stringify({ type: 'run-created', seq: 1, ts: 1758000000000, runId: 'wf-run-1', workflowName: 'run-flow', argsSummary: '{}' }),
-      JSON.stringify({ type: 'agent-started', seq: 2, ts: 1758000000100, taskIndex: 0, agentName: 'in-flight', attempt: 1 }),
-    ])
-    await wfV2Registered(dir, slug, WF_ROOT, 'wf-run-1', activePath)
-    const r1 = await handleSessionRead({ action: 'workflow', session: WF_ROOT }, { agentDir: dir })
-    const d1 = r1.details as { runs: Array<{ runId: string; status: string }>; skippedRuns?: unknown[] }
-    expect(d1.skippedRuns).toBeUndefined()
-    expect(d1.runs.find((x) => x.runId === 'wf-run-1')?.status).toBe('running')
-
-    // 中断：追加 run-interrupted 转移帧 → status interrupted（[D2] 暂停态）
-    // 同 slug 同 main session 追加条目（第二个 slug 目录会触发同 id 多匹配消歧）
-    const slug2 = slug
-    const intPath = await wfStateFile(dir, slug2, 'wf-int-1.record.jsonl', [
-      JSON.stringify({ type: 'run-created', seq: 1, ts: 1758000000000, runId: 'wf-int-1', workflowName: 'int-flow', argsSummary: '{}' }),
-      JSON.stringify({ type: 'agent-started', seq: 2, ts: 1758000000100, taskIndex: 0, agentName: 'crashed-step', attempt: 1 }),
-      JSON.stringify({ type: 'run-interrupted', seq: 3, ts: 1758000009000, errorCode: 'crashed', reason: 'process killed' }),
-    ])
-    await wfV2Registered(dir, slug2, WF_ROOT, 'wf-int-1', intPath)
-    const r2 = await handleSessionRead({ action: 'workflow', session: WF_ROOT }, { agentDir: dir })
-    const d2 = r2.details as { runs: Array<{ runId: string; status: string }>; skippedRuns?: unknown[] }
-    expect(d2.skippedRuns).toBeUndefined()
-    expect(d2.runs.find((x) => x.runId === 'wf-int-1')?.status).toBe('interrupted')
-  })
 
-  it('TC-w6-single-run：单 run 概览，content 含 run 头行/budget/step，details.runs/runIds 非空', async () => {
-    const slug = '--wf-single--'
-    await wfMainSession(dir, slug, WF_ROOT)
-    const callSession = join(dir, 'sessions', slug, `${WF_CALL}.jsonl`)
-    await wfV2Run(dir, slug, WF_ROOT, 'wf-single-1', [
-      { sessionId: WF_CALL, sessionFile: callSession },
-    ], { settled: true })
-
-    const r = await handleSessionRead({ action: 'workflow', session: WF_ROOT }, { agentDir: dir })
-    const d = r.details as {
-      runs: Array<{
-        runId: string
-        status: string
-        steps: Array<{ sessionId: string; sessionFile: string }>
-      }>
-      runIds: string[]
-    }
-    expect(d.runs).toHaveLength(1)
-    expect(d.runs[0].runId).toBe('wf-single-1')
-    expect(d.runs[0].status).toBe('done')
-    expect(d.runs[0].steps).toHaveLength(1)
-    expect(d.runs[0].steps[0].sessionId).toBe(WF_CALL)
-    expect(d.runs[0].steps[0].sessionFile).toBe(callSession)
-    expect(d.runIds).toEqual(['wf-single-1'])
-    // content 含 renderWorkflowOverview 输出
-    const text = r.content[0].text
-    expect(text).toContain('run: wf-single-1')
-    expect(text).toContain('[done]')
-    expect(text).toContain('budget:')
-    expect(text).toContain('#0')
-    expect(text).toContain('call=' + WF_CALL.slice(0, 12))
-    expect(text).toContain(callSession)
-  })
-
-  it('TC-w6-multi-run：多 run 拼接，content 含两段 overview，runs.length===2', async () => {
-    const slug = '--wf-multi--'
-    await wfMainSession(dir, slug, WF_ROOT)
-    await wfV2Run(dir, slug, WF_ROOT, 'wf-multi-1', [{ sessionId: WF_CALL, sessionFile: '/abs/a.jsonl' }], { settled: true })
-    await wfV2Run(dir, slug, WF_ROOT, 'wf-multi-2', [{ sessionId: WF_CALL, sessionFile: '/abs/b.jsonl' }], { settled: true })
-
-    const r = await handleSessionRead({ action: 'workflow', session: WF_ROOT }, { agentDir: dir })
-    const d = r.details as { runs: Array<{ runId: string }>; runIds: string[] }
-    expect(d.runs).toHaveLength(2)
-    expect(d.runIds).toHaveLength(2)
-    expect(d.runIds).toContain('wf-multi-1')
-    expect(d.runIds).toContain('wf-multi-2')
-    const text = r.content[0].text
-    expect(text).toContain('run: wf-multi-1')
-    expect(text).toContain('run: wf-multi-2')
-  })
-
-  it('TC-w6-runid-filter：runId 过滤命中单 run', async () => {
-    const slug = '--wf-filter--'
-    await wfMainSession(dir, slug, WF_ROOT)
-    await wfV2Run(dir, slug, WF_ROOT, 'wf-filter-1', [{ sessionId: WF_CALL, sessionFile: '/abs/a.jsonl' }], { settled: true })
-    await wfV2Run(dir, slug, WF_ROOT, 'wf-filter-2', [{ sessionId: WF_CALL, sessionFile: '/abs/b.jsonl' }], { settled: true })
-
-    const r = await handleSessionRead(
-      { action: 'workflow', session: WF_ROOT, runId: 'wf-filter-1' },
-      { agentDir: dir },
-    )
-    const d = r.details as {
-      runs: Array<{ runId: string }>
-      runIds: string[]
-      requestedRunId?: string
-    }
-    expect(d.runs).toHaveLength(1)
-    expect(d.runIds).toEqual(['wf-filter-1'])
-    expect(d.requestedRunId).toBe('wf-filter-1')
-    const text = r.content[0].text
-    expect(text).toContain('run: wf-filter-1')
-    expect(text).not.toContain('run: wf-filter-2')
-  })
-
-  it('TC-w6-runid-not-found：runId 无匹配→ES-wf-runid-not-found（列候选+👉，不抛错）', async () => {
-    const slug = '--wf-notfound--'
-    await wfMainSession(dir, slug, WF_ROOT)
-    await wfV2Run(dir, slug, WF_ROOT, 'wf-nf-1', [{ sessionId: WF_CALL, sessionFile: '/abs/a.jsonl' }], { settled: true })
-    await wfV2Run(dir, slug, WF_ROOT, 'wf-nf-2', [{ sessionId: WF_CALL, sessionFile: '/abs/b.jsonl' }], { settled: true })
-
-    const r = await handleSessionRead(
-      { action: 'workflow', session: WF_ROOT, runId: 'wf-nonexist' },
-      { agentDir: dir },
-    )
-    const d = r.details as { runs: unknown[]; runIds: string[]; requestedRunId?: string }
-    expect(d.runs).toEqual([])
-    expect(d.runIds).toContain('wf-nf-1')
-    expect(d.runIds).toContain('wf-nf-2')
-    expect(d.requestedRunId).toBe('wf-nonexist')
-    const text = r.content[0].text
-    expect(text).toContain('wf-nonexist')
-    expect(text).toContain('wf-nf-1')
-    expect(text).toContain('wf-nf-2')
-    expect(text).toContain('👉')
-  })
-
-  it('TC-w6-no-runs：无 workflow run→ES-wf-no-runs（提示+👉family，不抛错）', async () => {
-    const slug = '--wf-noruns--'
-    await wfMainSession(dir, slug, WF_ROOT)
-    // 无 wf-link（session 存在但未发起 workflow）
-
-    const r = await handleSessionRead({ action: 'workflow', session: WF_ROOT }, { agentDir: dir })
-    const d = r.details as { runs: unknown[]; runIds: unknown[]; sessionId?: string }
-    expect(d.runs).toEqual([])
-    expect(d.runIds).toEqual([])
-    expect(d.sessionId).toBe(WF_ROOT)
-    const text = r.content[0].text
-    expect(text).toContain('无 workflow run')
-    expect(text).toContain('👉')
-    expect(text).toContain('family')
-  })
-
-  // [ADR-0095] TC-w6-snapshot-skip（快照不可读 → skippedRuns）随 v1 读侧删除：
-  // 发现链收敛 v2 后 run 一律 record 流直读（读失败 → running 兜底不 skipped），
-  // skippedRuns 快照链对 v2 档不可达。
-
-  it('TC-w6-call-jump：workflow 概览 call sessionId 可被 resolveSessionId 深读（outline 跳转，§7 场景 2）', async () => {
-    const slug = '--wf-jump--'
-    await wfMainSession(dir, slug, WF_ROOT)
-    // 真实存在的 call session（main session 形态，findSessions 可匹配）
-    const callPath = await wfMainSession(dir, slug, WF_CALL, { cwd: '/proj/call' })
-    await wfV2Run(dir, slug, WF_ROOT, 'wf-jump-1', [{ sessionId: WF_CALL, sessionFile: callPath }], { settled: true })
-
-    // 第一次：workflow 概览，拿 call sessionId
-    const rWf = await handleSessionRead({ action: 'workflow', session: WF_ROOT }, { agentDir: dir })
-    const dWf = rWf.details as {
-      runs: Array<{ steps: Array<{ sessionId: string; sessionFile: string }> }>
-    }
-    expect(dWf.runs).toHaveLength(1)
-    const callSessionId = dWf.runs[0].steps[0].sessionId
-    expect(callSessionId).toBe(WF_CALL)
-
-    // 第二次：用 call sessionId 调 outline（m0 resolveSessionId 三形态复用）
-    const rOutline = await handleSessionRead(
-      { action: 'outline', session: callSessionId },
-      { agentDir: dir },
-    )
-    const dOutline = rOutline.details as { turns: unknown[] }
-    expect(dOutline.turns.length).toBeGreaterThan(0)
-  })
-
-  it('TC-w6-subagent-session：workflow action 对 subagent session 直读 wf-link 不抛错（MF-2）', async () => {
-    const slug = '--wf-subagent--'
-    // subagent session 放 subagents/ 下（不在 sessions/——buildFamilyFromFs 的 main byId
-    // 索引外，旧实现 resolveFamily 找不到会抛「session not found in family index」）
-    const subDir = resolveStoreSubagentSessionsDir(dir, SUB_WF_ROOT)
-    await mkdir(subDir, { recursive: true })
-    const subPath = join(subDir, `${SUB_WF_ROOT}.jsonl`)
-    await writeFile(
-      subPath,
-      JSON.stringify({ type: 'session', id: SUB_WF_ROOT, cwd: `/proj/${slug}` }) + '\n',
-    )
-    const callSession = join(dir, 'sessions', slug, `${WF_CALL}.jsonl`)
-    // subagent session 的 v2 注册条目（[ADR-0095] v1 link 形态删除；record 流直读同源）
-    const recordPath = await wfStateFile(dir, slug, 'wf-sub-1.record.jsonl', [
-      JSON.stringify({ type: 'run-created', seq: 1, ts: 1758000000000, runId: 'wf-sub-1', workflowName: 'test-wf', argsSummary: '{}' }),
-      JSON.stringify({ type: 'agent-settled', seq: 2, ts: 1758000001000, taskIndex: 0, attempt: 1, outcome: 'done', durationMs: 100, result: { content: 'ok', sessionId: WF_CALL, sessionFile: callSession } }),
-      JSON.stringify({ type: 'run-settled', seq: 3, ts: 1758000002000, outcome: 'done' }),
-    ])
-    await writeFile(
-      subPath,
-      JSON.stringify({
-        type: 'custom',
-        id: 'wf-reg-wf-sub-1',
-        parentId: SUB_WF_ROOT,
-        customType: 'workflow-record',
-        data: { v: 2, kind: 'registered', runId: 'wf-sub-1', workflowName: 'test-wf', scriptName: 'test-wf', slug: 'wf-sub', startedAt: 1758000000000, recordPath },
-        timestamp: '2026-09-28T00:00:00Z',
-      }) + '\n',
-      { flag: 'a' },
-    )
-
-    const r = await handleSessionRead({ action: 'workflow', session: SUB_WF_ROOT }, { agentDir: dir })
-    const d = r.details as { runs: Array<{ runId: string }>; runIds: string[] }
-    expect(d.runs).toHaveLength(1)
-    expect(d.runs[0].runId).toBe('wf-sub-1')
-    expect(d.runIds).toEqual(['wf-sub-1'])
-    expect(r.content[0].text).toContain('run: wf-sub-1')
-    expect(r.content[0].text).toContain('call=')
-  })
-})
-
-// ============================================================
-// m3b：doFamily recursive false/true（TC-m3b-dofamily-recursive-false/true）
-// ============================================================
-
-describe('doFamily recursive（m3b U8 接入）', () => {
-  let dataDir: string
-  let dir: string // agentDir = <dataDir>/agent（生产拓扑复刻）
-  const MAIN = '019e6c96-cccc-dddd-eeee-000000000001'
-  const SUB = '019e6c96-cccc-dddd-eeee-000000000002'
-
-  beforeEach(async () => {
-    dataDir = await mkdtemp(join(tmpdir(), 'tool-handler-recursive-'))
-    dir = join(dataDir, 'agent')
-    await makeFixtureSession(dir, MAIN, 'main session 内容')
-    // 顶层 subagent（rootSessionId=MAIN，无 parentRecordId → flat 回退）
-    await makeFixtureSubagent(dir, `sa-${SUB.slice(0, 8)}`, {
-      realSessionId: SUB,
-      rootSessionId: MAIN,
-      agentName: 'explorer',
-      firstUserText: 'subagent task',
+    it('ambiguous（任意 action 的多匹配消歧）→ N candidates', () => {
+      const r = toolResult({ ambiguous: true, candidates: [{}, {}] })
+      expect(buildSessionReadSummary(params({ action: 'outline', session: 'e6c9' }), r)).toBe(
+        'Ambiguous session "e6c9": 2 candidates',
+      )
     })
-  })
-  afterEach(async () => {
-    await rm(dataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
-  })
-
-  it('TC-m3b-dofamily-recursive-false：不传 recursive → flat family（m0-m2 零回归）', async () => {
-    const r = await handleSessionRead({ action: 'family', session: MAIN }, { agentDir: dir })
-    // details 是 Family 对象（root/subagents/workflows），非 { tree }
-    const d = r.details as {
-      root: { sessionId: string }
-      subagents: Array<{ sessionId: string; rootSessionId: string }>
-      workflows: unknown[]
-    }
-    expect(d.root.sessionId).toBe(MAIN)
-    expect(d.subagents.some((s) => s.sessionId === SUB)).toBe(true)
-    expect(Array.isArray(d.workflows)).toBe(true)
-    // content 是 formatFamilyText（非 formatExecutionTreeText）
-    expect(r.content[0].text).toContain('root:')
-    expect(r.content[0].text).not.toContain('execution tree')
-  })
 
-  it('TC-m3b-dofamily-recursive-true：recursive=true → ExecutionTree（details.tree）', async () => {
-    const r = await handleSessionRead(
-      { action: 'family', session: MAIN, recursive: true },
-      { agentDir: dir },
-    )
-    const d = r.details as {
-      tree: {
-        root: { type: string; sessionId: string; children: unknown[] }
-        totalNodes: number
-        maxDepth: number
-        sourceMode: string
-        truncated: boolean
+    it('family flat → N relations（parents/forks/subagents/workflows 合计）', () => {
+      const family = {
+        root: { sessionId: 's1' },
+        parents: [{}],
+        forks: [{}, {}],
+        subagents: [{}],
+        workflows: [],
       }
-    }
-    expect(d.tree).toBeDefined()
-    expect(d.tree.root.type).toBe('main')
-    expect(d.tree.root.sessionId).toBe(MAIN)
-    // subagent 挂 root（flat 回退，无 parentRecordId）
-    expect(d.tree.root.children).toHaveLength(1)
-    expect(d.tree.totalNodes).toBe(2) // main + subagent
-    expect(d.tree.sourceMode).toBe('flat-fallback') // 旧机制无 parentRecordId
-    expect(d.tree.truncated).toBe(false)
-    // content 是 formatExecutionTreeText（含 execution tree 头部）
-    expect(r.content[0].text).toContain('execution tree')
-    expect(r.content[0].text).toContain('node(s)')
-    expect(r.content[0].text).toContain('👉')
-  })
-})
-
-// ===========================================================================
-// ext-simplify-04 U4/E2（D2②）：formatFamilyText subagents 行富字段展示
-// status 终态短标签 + agent 名 + task 截 60 摘要；孤儿只标 [已清理]；P4 输出量级检查。
-// ===========================================================================
-
-describe('formatFamilyText subagents 行富字段（ext-simplify-04 U4 / E2）', () => {
-  const MAIN = '0aaaaaaa-bbbb-7ccc-dddd-0000000000f1'
-  const SUB = '0aaaaaaa-bbbb-7ccc-dddd-0000000000f2'
-  let dataDir: string
-  let dir: string // agentDir = <dataDir>/agent（生产拓扑复刻）
-
-  beforeEach(async () => {
-    dataDir = await mkdtemp(join(tmpdir(), 'tool-handler-family-rich-'))
-    dir = join(dataDir, 'agent')
-    await makeFixtureSession(dir, MAIN, 'main session')
-  })
-  afterEach(async () => {
-    await rm(dataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
-  })
-
-  /** alive subagent：session 文件（header + 可选 identity 尾行）+ 可选 manifest 富字段 */
-  async function writeSubagent(
-    realId: string,
-    opts: {
-      manifest?: { agentName?: string; task?: string; slug?: string; model?: string; status?: string }
-      identityTask?: string
-      identityAgent?: string
-    } = {},
-  ): Promise<void> {
-    const sessionDir = resolveStoreSubagentSessionsDir(dir, MAIN)
-    await mkdir(sessionDir, { recursive: true })
-    const subPath = join(sessionDir, `${realId}.jsonl`)
-    const lines = [JSON.stringify({ type: 'session', id: realId, cwd: '/demo' })]
-    if (opts.identityTask !== undefined || opts.identityAgent !== undefined) {
-      lines.push(
-        JSON.stringify({
-          type: 'custom',
-          customType: 'subagent-identity',
-          data: {
-            id: `sa-${realId.slice(0, 8)}`,
-            rootSessionId: MAIN,
-            slug: 'identity-slug',
-            agent: opts.identityAgent ?? 'explorer',
-            task: opts.identityTask ?? 't',
-          },
-        }),
+      const r = toolResult(family)
+      expect(buildSessionReadSummary(params({ action: 'family', session: 's1' }), r)).toBe(
+        'Family of session s1: 4 relations',
       )
-    }
-    await writeFile(subPath, lines.join('\n') + '\n')
-    if (opts.manifest) {
-      const recordsDir = resolveStoreSubagentRecordsDir(dir, MAIN)
-      await mkdir(recordsDir, { recursive: true })
-      await writeFile(
-        join(recordsDir, `sa-${realId}.json`),
-        JSON.stringify({
-          id: `sa-${realId}`,
-          rootSessionId: MAIN,
-          sessionFile: subPath,
-          ...opts.manifest,
-        }),
+    })
+
+    it('family recursive（details.tree）→ Execution tree', () => {
+      const r = toolResult({ tree: { root: {} } })
+      expect(buildSessionReadSummary(params({ action: 'family', session: 's1', recursive: true }), r)).toBe(
+        'Execution tree of session s1',
       )
-    }
-  }
+    })
 
-  /** 孤儿 manifest：sessionFile 指向不存在路径（模拟 .jsonl 被 GC） */
-  async function writeOrphanManifest(
-    saId: string,
-    fields: { agentName?: string; task?: string; slug?: string; status?: string } = {},
-  ): Promise<void> {
-    const recordsDir = resolveStoreSubagentRecordsDir(dir, MAIN)
-    await mkdir(recordsDir, { recursive: true })
-    await writeFile(
-      join(recordsDir, `${saId}.json`),
-      JSON.stringify({ id: saId, rootSessionId: MAIN, sessionFile: '/nonexistent/gc.jsonl', ...fields }),
-    )
-  }
+    it('outline → N turns（stats.totalTurns）', () => {
+      const r = toolResult({ turns: [], lines: [], stats: { totalTurns: 32, totalEntries: 90, totalBytes: 1, parsedBytes: 1, skippedLines: 0 }, tokenEstimate: 1 })
+      expect(buildSessionReadSummary(params({ action: 'outline', session: 's1' }), r)).toBe(
+        'Outline of session s1 · 32 turns',
+      )
+    })
 
-  it('manifest 主路径：subagents 行含 [status] agent 名 · task 摘要；root 段不变', async () => {
-    await writeSubagent(SUB, {
-      manifest: { agentName: 'coder', task: '修复登录表单校验并补测试', slug: 'fix-login', status: 'completed' },
+    it('expand → T 序号补零 + N entries', () => {
+      const r = toolResult({ turn: { index: 13 }, entries: [{}, {}, {}, {}] })
+      expect(buildSessionReadSummary(params({ action: 'expand', session: 's1', turn: 'T013' }), r)).toBe(
+        'Expanded turn T013 · 4 entries',
+      )
     })
-    const r = await handleSessionRead({ action: 'family', session: MAIN }, { agentDir: dir })
-    const text = r.content[0].text
-    // 富字段行形态（设计 §3.1）：slug 后接 [status] agent · task 摘要
-    expect(text).toContain('slug=fix-login [completed] coder · 修复登录表单校验并补测试')
-    // root/parents/forks/workflows 段不变（root 行含完整 id + 日期括号）
-    expect(text).toContain(`root: ${MAIN} (`)
-  })
 
-  it('P4 输出量级：task 截 60 字符（超出加省略号），换行压平不破坏行结构', async () => {
-    const SUB2 = '0aaaaaaa-bbbb-7ccc-dddd-0000000000f3'
-    await writeSubagent(SUB, {
-      manifest: { agentName: 'coder', task: 'A'.repeat(100), slug: 'long-task', status: 'running' },
+    it('detail → turns 范围标签 + N entries', () => {
+      const r = toolResult({ turns: 'T013-T015', entries: [{}, {}, {}] })
+      expect(buildSessionReadSummary(params({ action: 'detail', session: 's1', turns: 'T013-T015' }), r)).toBe(
+        'Read turns T013-T015 · 3 entries',
+      )
     })
-    await writeSubagent(SUB2, {
-      manifest: { agentName: 'worker', task: 'line1\nline2\ttabbed', slug: 'nl-task', status: 'failed' },
+
+    it('search → Found N hits / No hits', () => {
+      const r = toolResult({ hits: [{}, {}], truncated: false })
+      expect(buildSessionReadSummary(params({ action: 'search', session: 's1', pattern: 'fix' }), r)).toBe(
+        'Found 2 hits for "fix"',
+      )
+      const empty = toolResult({ hits: [], truncated: false })
+      expect(buildSessionReadSummary(params({ action: 'search', session: 's1', pattern: 'fix' }), empty)).toBe(
+        'No hits for "fix"',
+      )
     })
-    const r = await handleSessionRead({ action: 'family', session: MAIN }, { agentDir: dir })
-    const text = r.content[0].text
-    // 截断：恰 60 字符 + 省略号，原文 61+ 连续段不出现
-    expect(text).toContain(`${'A'.repeat(60)}…`)
-    expect(text).not.toContain('A'.repeat(61))
-    // 换行/制表压平为单空格
-    expect(text).toContain('slug=nl-task [failed] worker · line1 line2 tabbed')
-    // 行结构：subagents 段 = 头行 + 每 subagent 恰一行（换行未折叠出额外行）
-    const lines = text.split('\n')
-    const headIdx = lines.indexOf('subagents:')
-    const subLines = lines.slice(headIdx + 1)
-    expect(subLines).toHaveLength(2)
-    expect(subLines.every((l) => l.startsWith('  ') && l.trim().length > 0)).toBe(true)
-  })
 
-  it('孤儿（cleanedUp）：仍标 [已清理]，不展开 status/agent/task 摘要', async () => {
-    await writeOrphanManifest('sa-ghost-id', {
-      agentName: 'worker',
-      task: 'ghost task',
-      slug: 'ghost-slug',
-      status: 'completed',
+    it('export → format + sizeBytes', () => {
+      const r = toolResult({ path: '/tmp/x.md', sizeBytes: 2048 })
+      expect(buildSessionReadSummary(params({ action: 'export', session: 's1' }), r)).toBe(
+        'Exported outline view · 2048 bytes',
+      )
+      expect(buildSessionReadSummary(params({ action: 'export', session: 's1', format: 'full' }), r)).toBe(
+        'Exported full view · 2048 bytes',
+      )
     })
-    const r = await handleSessionRead({ action: 'family', session: MAIN }, { agentDir: dir })
-    const text = r.content[0].text
-    expect(text).toContain('slug=ghost-slug [已清理]')
-    // 已清理即终局：manifest 富字段不进文本（无深读入口，摘要无消费价值）
-    expect(text).not.toContain('ghost task')
-    expect(text).not.toContain('[completed]')
-  })
 
-  it('P-fallback（无 manifest）：identity 回退 task/agent 仍展示，status 无则无标签', async () => {
-    await writeSubagent(SUB, { identityTask: 'fix bug', identityAgent: 'worker' })
-    const r = await handleSessionRead({ action: 'family', session: MAIN }, { agentDir: dir })
-    const text = r.content[0].text
-    // P-fallback：task/agent 从 identity 回退（slug 取 identity.slug），status 不可回退 → 无 [x] 标签
-    expect(text).toContain('slug=identity-slug worker · fix bug')
-    expect(text).not.toContain('[completed]')
-    expect(text).not.toContain('[running]')
-  })
-})
+    it('extract → count / 零匹配 / 截断 showing', () => {
+      const r = toolResult({ what: 'user-messages', count: 26, shown: 26, truncated: false, items: [] })
+      expect(buildSessionReadSummary(params({ action: 'extract', session: 's1', what: 'user-messages' }), r)).toBe(
+        'Extracted 26 user-messages',
+      )
+      const empty = toolResult({ what: 'commands', count: 0, shown: 0, truncated: false, items: [] })
+      expect(buildSessionReadSummary(params({ action: 'extract', session: 's1', what: 'commands' }), empty)).toBe(
+        'No commands found',
+      )
+      const clipped = toolResult({ what: 'files', count: 500, shown: 120, truncated: true, items: [] })
+      expect(buildSessionReadSummary(params({ action: 'extract', session: 's1', what: 'files' }), clipped)).toBe(
+        'Extracted 500 files (showing 120)',
+      )
+    })
 
-// ===========================================================================
-// doctor action（u8：design 2026-09-10 §6.3/§6.4/§7B 要点 2/4/5/8 + §6.11 U14b 段）
-// 全部 mkdtemp fixture 自建自删，不触碰真实数据目录。
-// ===========================================================================
+    it('workflow → runs 计数 / 空 / skipped 后缀', () => {
+      expect(buildSessionReadSummary(params({ action: 'workflow', session: 's1' }), toolResult({ runs: [{}, {}], runIds: ['a', 'b'] }))).toBe(
+        'Found 2 workflow runs',
+      )
+      expect(buildSessionReadSummary(params({ action: 'workflow', session: 's1' }), toolResult({ runs: [], runIds: [] }))).toBe(
+        'No workflow runs',
+      )
+      expect(
+        buildSessionReadSummary(
+          params({ action: 'workflow', session: 's1' }),
+          toolResult({ runs: [{}], runIds: ['a'], skippedRuns: [{ runId: 'b', stateFile: 'x', reason: 'snapshot-unreadable' }] }),
+        ),
+      ).toBe('Found 1 workflow runs · 1 skipped')
+    })
 
-// doctor details 契约直用 doctor.ts 导出的 DoctorDetails（不再自建局部镜像——生产侧
-// 形状漂移由编译期捕捉，S-R2 同步）
+    it('result 单条 → session + totalChars（截断后缀）', () => {
+      const r = toolResult({ session: 'sa-abc', sessionId: 'uuid', sessionFile: '/x', totalChars: 8000, truncated: true, text: '...' })
+      expect(buildSessionReadSummary(params({ action: 'result', session: 'sa-abc' }), r)).toBe(
+        'Read final result of sa-abc · 8000 chars (truncated)',
+      )
+    })
 
-describe('doctor action（u8：环境判定 + 根表 + 告警 + 残留 glob）', () => {
-  let tmp: string
+    it('result 批量 → count + items 形态识别', () => {
+      const r = toolResult({ count: 3, items: [{}, {}, {}] })
+      expect(buildSessionReadSummary(params({ action: 'result', session: 'a,b,c' }), r)).toBe(
+        'Read 3 final results',
+      )
+    })
 
-  const SLUG = '--Users-foo--'
+    it('doctor → roots 计数', () => {
+      const r = toolResult({ environment: {}, roots: [{ kind: 'default' }, { kind: 'legacy' }] })
+      expect(buildSessionReadSummary(params({ action: 'doctor' }), r)).toBe(
+        'Doctor: 2 roots checked',
+      )
+    })
 
-  /** 写 .jsonl fixture（父目录自建），内容合法 session header */
-  async function writeJsonl(path: string, id = 'x'): Promise<void> {
-    await mkdir(dirname(path), { recursive: true })
-    await writeFile(path, `{"type":"session","id":"${id}"}\n`)
-  }
+    it('details 形态漂移（空对象）→ 各 action 兜底不抛错', () => {
+      const empty = toolResult({})
+      expect(buildSessionReadSummary(params({ action: 'outline', session: 's1' }), empty)).toBe(
+        'Outline of session s1',
+      )
+      expect(buildSessionReadSummary(params({ action: 'workflow', session: 's1' }), empty)).toBe(
+        'No workflow runs',
+      )
+      expect(buildSessionReadSummary(params({ action: 'doctor' }), empty)).toBe('Doctor check completed')
+      expect(buildSessionReadSummary(params({ action: 'extract', what: 'files' }), empty)).toBe('No files found')
+    })
+  })
 
-  /**
-   * taiji 形态四根 fixture：dataDir 目录名带 .taiji 前缀（detectEnvironment 的
-   * PI_CODING_AGENT_DIR 形态判据 `<*>/.taiji*\/agent` 可命中，托管判定走正态）。
-   * live=agent/sessions 与 default 同字面路径（default 去重）、legacy 独立非空、subagent 独立。
-   */
-  async function buildFourRootFixture(): Promise<{
-    dataDir: string
-    agentDir: string
-    signals: SessionReadSignals
-  }> {
-    const dataDir = join(tmp, '.taiji-fixture')
-    const agentDir = join(dataDir, 'agent')
-    await writeJsonl(join(agentDir, 'sessions', SLUG, 'a.jsonl'), 'aaaaaaaa')
-    await writeJsonl(join(agentDir, 'sessions', SLUG, 'b.jsonl'), 'bbbbbbbb')
-    await writeJsonl(join(dataDir, 'sessions', 'old.jsonl'), 'cccccccc') // legacy 非空
-    await writeJsonl(
-      join(resolveStoreSubagentSessionsDir(agentDir, '0aaaaaaa-bbbb-7ccc-dddd-000000000d1'), 's.jsonl'),
-      'dddddddd',
-    )
-    return {
-      dataDir,
-      agentDir,
-      signals: {
-        agentDir,
-        liveSessionDir: join(agentDir, 'sessions'),
-        env: {
-          TAIJI_AGENT_EXT_LOG: '1',
-          PI_CODING_AGENT_DIR: agentDir,
-          TAIJI_AGENT_DATA_DIR: dataDir,
-        },
-      },
-    }
-  }
+  // ---- withResultSummary ----
 
-  beforeEach(async () => {
-    tmp = await mkdtemp(join(tmpdir(), 'tool-handler-doctor-'))
-  })
-  afterEach(async () => {
-    await rm(tmp, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+  describe('withResultSummary', () => {
+    it('details 追加 summary，现有字段保留', () => {
+      const r = toolResult({ hits: [{}], truncated: false })
+      const out = withResultSummary(params({ action: 'search', pattern: 'fix' }), r)
+      expect(out.details).toEqual({ hits: [{}], truncated: false, summary: 'Found 1 hits for "fix"' })
+    })
   })
 
-  it('四根表渲染：优先级序 + 去重注记 + 文件数/耗时 + 托管判定行 + 事实型诊断（无归因断言）', async () => {
-    const { dataDir, agentDir, signals } = await buildFourRootFixture()
-    const r = await handleSessionRead({ action: 'doctor' }, signals)
-    const text = r.content[0].text
-
-    // 环境判定行：双信号合取 → taiji（托管）+ 数据目录 + evidence 正态
-    expect(text).toContain('环境判定：taiji（托管）')
-    expect(text).toContain(`数据目录：${dataDir}`)
-    expect(text).toContain('依据：')
-    expect(text).toContain(`PI_CODING_AGENT_DIR='${agentDir}' → 形态匹配`)
-
-    // 四根按优先级序渲染
-    const liveIdx = text.indexOf('[live]')
-    const defIdx = text.indexOf('[default]')
-    const legacyIdx = text.indexOf('[legacy]')
-    const subIdx = text.indexOf('[subagent]')
-    expect(liveIdx).toBeGreaterThan(-1)
-    expect(defIdx).toBeGreaterThan(liveIdx)
-    expect(legacyIdx).toBeGreaterThan(defIdx)
-    expect(subIdx).toBeGreaterThan(legacyIdx)
-
-    // 去重注记（§7B 要点 4）：default 与第 1 行（live）同路径，已去重
-    expect(text).toContain('与 1 同路径，已去重')
-
-    // 事实型诊断：只陈述最高优先级 main 根 N 文件；禁止归因断言（§7B 要点 5）
-    expect(text).toContain(
-      `诊断：最高优先级 main 根 [live] ${join(agentDir, 'sessions')}：2 文件。`,
-    )
-    expect(text).not.toContain('真的没有')
-
-    // details 程序化形态
-    const d = r.details as DoctorDetails
-    expect(d.roots.map((x) => x.kind)).toEqual(['live', 'default', 'legacy', 'subagent'])
-    expect(d.roots[0].fileCount).toBe(2)
-    expect(typeof d.roots[0].scanMs).toBe('number')
-    expect(d.roots[1].dedupedInto).toBe('live')
-    expect(d.roots[1].fileCount).toBeUndefined()
-    expect(d.roots[2].fileCount).toBe(1) // legacy 独立实扫
-    // subagent 默认 stat 模式：只列路径与可扫性，无计数
-    expect(d.roots[3].exists).toBe(true)
-    expect(d.roots[3].fileCount).toBeUndefined()
-    expect(d.roots[3].scanMs).toBeUndefined()
-  })
+  // ---- renderSessionReadResult（TUI renderResult）----
+
+  const mockTheme = {
+    fg: (_color: string, text: string) => text,
+    bg: (_color: string, text: string) => text,
+    bold: (text: string) => text,
+    italic: (text: string) => text,
+    underline: (text: string) => text,
+    inverse: (text: string) => text,
+    strikethrough: (text: string) => text,
+    getFgAnsi: (_color: string) => '',
+    getBgAnsi: (_color: string) => '',
+    getColorMode: () => 'truecolor' as const,
+    getThinkingBorderColor: () => (text: string) => text,
+    getBashModeBorderColor: () => (text: string) => text,
+  } as unknown as Theme
+
+  function renderedText(result: unknown, expanded: boolean): string {
+    return renderSessionReadResult(result, { expanded }, mockTheme)
+      .render(400)
+      .map((line) => line.trimEnd())
+      .join('\n')
+  }
+
+  describe('renderSessionReadResult', () => {
+    it('折叠态 → details.summary 一行', () => {
+      const r = toolResult({ matches: [], truncated: false }, 'multi\nline\nbody')
+      const withSummary = withResultSummary(params({ action: 'find', query: 'login' }), r)
+      expect(renderedText(withSummary, false)).toBe('No sessions matching "login"')
+    })
 
-  it('legacy 非空告警：独立非空 → 告警；不存在 → 无告警；与 live 同路径被去重 → 不告警（§5.1）', async () => {
-    // 正态：legacy 独立且非空
-    const { signals } = await buildFourRootFixture()
-    const positive = await handleSessionRead({ action: 'doctor' }, signals)
-    expect(positive.content[0].text).toContain(
-      `告警：[legacy] 根 ${join(tmp, '.taiji-fixture', 'sessions')} 非空（1 文件）`,
-    )
+    it('展开态 → content 纯文本（多行完整）', () => {
+      const r = toolResult({ matches: [] }, 'line1\nline2')
+      expect(renderedText(r, true)).toBe('line1\nline2')
+    })
 
-    // 反态：legacy 目录不存在
-    const agentDir2 = join(tmp, 'data2', 'agent')
-    await writeJsonl(join(agentDir2, 'sessions', SLUG, 'a.jsonl'))
-    const negative = await handleSessionRead({ action: 'doctor' }, { agentDir: agentDir2 })
-    expect(negative.content[0].text).not.toContain('告警：')
-
-    // 去重态：live 与 legacy 同路径（文件非空）→ 已去重不告警
-    const dataDir3 = join(tmp, 'data3')
-    const agentDir3 = join(dataDir3, 'agent')
-    await writeJsonl(join(dataDir3, 'sessions', SLUG, 'a.jsonl'))
-    const deduped = await handleSessionRead(
-      { action: 'doctor' },
-      { agentDir: agentDir3, liveSessionDir: join(dataDir3, 'sessions') },
-    )
-    expect(deduped.content[0].text).not.toContain('告警：')
-    expect(deduped.content[0].text).toContain('已去重')
+    it('无 summary（旧 entry）→ 折叠态回退 content 首行', () => {
+      const r = toolResult({}, 'Header line\ndetail body')
+      expect(renderedText(r, false)).toBe('Header line')
+    })
   })
+});
+
+// ======== 来源：zcode-routing.test.ts ========
+describe("zcode-routing", () => {
+  // ============================================================
+  // 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 = 走对主路径）。
+  // ============================================================
 
-  it('subagent 根默认不扫（只列路径与可扫性）；includeSubagents:true 才扫出文件数（§6.3）', async () => {
-    const { agentDir, signals } = await buildFourRootFixture()
+  const ISOLATED_DB_SEGMENTS = ['engines', 'zcode', 'session-db', 'db.sqlite']
 
-    const def = await handleSessionRead({ action: 'doctor' }, signals)
-    const defSub = (def.details as DoctorDetails).roots.find((x) => x.kind === 'subagent')
-    expect(defSub?.fileCount).toBeUndefined()
-    expect(defSub?.scanMs).toBeUndefined()
-    expect(defSub?.exists).toBe(true)
-    expect(def.content[0].text).toContain('未扫描（subagent 根默认不扫')
+  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
 
-    const full = await handleSessionRead({ action: 'doctor', includeSubagents: true }, signals)
-    const fullSub = (full.details as DoctorDetails).roots.find((x) => x.kind === 'subagent')
-    expect(fullSub?.fileCount).toBe(1)
-    expect(fullSub?.exists).toBe(true)
-  })
+  let root: string
+  let agentDir: string
+  let dbPath: string
+  let liveDir: string
+  let appendEntries: ReturnType<typeof vi.fn>
 
-  it('无缓存形态（ext-simplify-04 U3）：重复调用输出一致（每次实扫），新落盘文件立即可见', async () => {
-    // 原三个用例（缓存命中不重扫 / TTL 到期失效 / find 不读 doctor 缓存 PS-14）随
-    // doctor 缓存机删除而合并为本用例——无缓存层后「find/doctor 读到旧计数」的形态
-    // 在结构上不存在，检查点收敛为：输出无「缓存命中」行 + 每次调用实扫（新增文件
-    // 下一次调用即见，反而更实时）
-    const agentDir = join(tmp, 'agent')
-    await writeJsonl(join(agentDir, 'sessions', SLUG, 'a.jsonl'))
-    const signals: SessionReadSignals = { agentDir }
-
-    const first = (await handleSessionRead({ action: 'doctor' }, signals)).details as DoctorDetails
-    const firstDef = first.roots.find((x) => x.kind === 'default')!
-    expect(firstDef.fileCount).toBe(1)
-
-    const second = await handleSessionRead({ action: 'doctor' }, signals)
-    const secondDef = (second.details as DoctorDetails).roots.find((x) => x.kind === 'default')!
-    expect(secondDef.fileCount).toBe(1) // 两次输出一致（同目录无变化）
-    expect(second.content[0].text).not.toContain('缓存命中')
-
-    // 新 session 落盘 → 下一次 doctor / find 均立即可见（无缓存层，每次实扫）
-    await writeJsonl(join(agentDir, 'sessions', SLUG, 'b.jsonl'), 'bbbbbbbb')
-    const third = (await handleSessionRead({ action: 'doctor' }, signals)).details as DoctorDetails
-    expect(third.roots.find((x) => x.kind === 'default')!.fileCount).toBe(2)
-    const r = await handleSessionRead({ action: 'find', query: 'bbbbbbbb' }, { agentDir })
-    const d = r.details as { matches: Array<{ sessionId: string }> }
-    expect(d.matches.some((m) => m.sessionId.includes('bbbbbbbb'))).toBe(true)
+  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])
   })
 
-  it('env/bundleUrl 信号缺失降级：仍出环境判定行（standalone-pi · 未知）+ 完整根表，不抛错', async () => {
-    const agentDir = join(tmp, 'agent')
-    await writeJsonl(join(agentDir, 'sessions', SLUG, 'a.jsonl'))
-    // signals 无 env/bundleUrl 字段（u3 旧信号包形态）
-    const r = await handleSessionRead({ action: 'doctor' }, { agentDir })
-    const text = r.content[0].text
-    expect(text).toContain('环境判定：standalone-pi · 发行形态：未知（不猜）')
-    expect(text).toContain('TAIJI_AGENT_EXT_LOG=<未设置> → 未命中')
-    expect(text).toContain('会话根（按优先级）')
-    expect(text).toContain('[default]')
-    expect(text).toContain(
-      `诊断：最高优先级 main 根 [default] ${join(agentDir, 'sessions')}：1 文件。`,
-    )
+  afterEach(() => {
+    setPiHandle(undefined)
+    rmSync(root, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
   })
 
-  it('空 agentDir 防御：无根表、诊断「无候选根」（不扫 cwd 相对路径）', async () => {
-    const r = await handleSessionRead({ action: 'doctor' }, { agentDir: '' })
-    const text = r.content[0].text
-    expect(text).toContain('诊断：无候选根')
-    expect(text).not.toContain('[default]')
-    expect((r.details as DoctorDetails).roots).toEqual([])
-  })
-})
+  // ---------------------------------------------------------------------------
+  // fixture builders
+  // ---------------------------------------------------------------------------
 
-// ============================================================
-// u9：F1 重写（§5.2 事实型自检 + 编辑距离 top-3 + 四条做法 + 禁止项）
-// + uuid 归一化两级匹配（§6.7 子决策 1 + §11.5 对比基线）
-// ============================================================
+  interface SessionRows {
+    id: string
+    title: string
+    messages: Array<{ id: string; role: string; parts: Array<Record<string, unknown>> }>
+  }
 
-describe('u9 F1 重写 + uuid 归一化（fixture，§5.2 / §6.7 / §11.5）', () => {
-  let tmp: string
-  const SLUG = '--demo-cwd--'
-  const ID1 = '019e6c96-aaaa-bbbb-cccc-000000000001'
-  const ID2 = '019e6c96-aaaa-bbbb-cccc-000000000002'
+  /** 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']),
+      ],
+    }
+  }
 
-  /**
-   * 写 session 文件（文件名 = `${id}.jsonl`，extractSessionIdFromFilename 可提取——
-   * F1 编辑距离候选的 id 来源）。subagent:true 写入 subagent 根。
-   */
-  async function writeSession(
-    id: string,
-    opts?: { subagent?: boolean; firstUserText?: string },
-  ): Promise<void> {
-    // [session-store-layout-inversion] subagent 会话在新布局存储树（分区 sid 固定合法形态）
-    const dir = opts?.subagent
-      ? resolveStoreSubagentSessionsDir(join(tmp, 'agent'), '0aaaaaaa-bbbb-7ccc-dddd-0000000000s1')
-      : join(tmp, 'agent', 'sessions', SLUG)
-    await mkdir(dir, { recursive: true })
-    const lines = [JSON.stringify({ type: 'session', id, cwd: '/demo' })]
-    if (opts?.firstUserText !== undefined) {
-      lines.push(
-        JSON.stringify({
-          type: 'message',
-          id: `${id}-m1`,
-          message: { role: 'user', content: [{ type: 'text', text: opts.firstUserText }] },
+  /** 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 } }],
+        }),
+      ],
     }
-    await writeFile(join(dir, `${id}.jsonl`), lines.join('\n') + '\n')
   }
 
-  /** find action 便捷调用（agentDir = tmp/agent）。 */
-  function find(query: string, extra?: Partial<SessionReadParams>): Promise<ToolResultLike> {
-    return handleSessionRead({ action: 'find', query, ...extra }, { agentDir: join(tmp, 'agent') })
+  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 } }],
+    }
   }
 
-  interface ToolResultLike {
-    content: Array<{ type: string; text: string }>
-    details: unknown
+  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 }
   }
 
-  beforeEach(async () => {
-    tmp = await mkdtemp(join(tmpdir(), 'tool-handler-f1-'))
-  })
-  afterEach(async () => {
-    await rm(tmp, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
-  })
-
-  it('① 大写 uuid 片段命中（§3.3 盲区：String.includes 大小写敏感）', async () => {
-    await writeSession(ID1, { firstUserText: '无关内容' })
-    const r = await find('019E6C96-AAAA')
-    const d = r.details as { matches: Array<{ sessionId: string }> }
-    expect(d.matches).toHaveLength(1)
-    expect(d.matches[0].sessionId).toBe(ID1)
-  })
-
-  it('② 去连字符完整 uuid 命中（§3.3 盲区：与带连字符 id 不构成子串）', async () => {
-    await writeSession(ID1, { firstUserText: '无关内容' })
-    // 去连字符形态与 sessionId/path 均不构成精确子串，只能走归一化层
-    const r = await find('019e6c96aaaabbbbcccc000000000001')
-    const d = r.details as { matches: Array<{ sessionId: string }> }
-    expect(d.matches).toHaveLength(1)
-    expect(d.matches[0].sessionId).toBe(ID1)
-  })
-
-  it('③ F1 文案四要素 + 负向断言（无 recent 误导指引、无「真的没有」归因）', async () => {
-    await writeSession(ID1, { firstUserText: '无关内容' })
-    const r = await find('zzz-no-hit-9q8x')
-    const text = r.content[0].text
-
-    // 首行 + ①事实型自检行（根计数 / 候选集判定 / 归一化声明）
-    expect(text).toContain('无匹配 session："zzz-no-hit-9q8x"')
-    expect(text).toContain('自检（发现层，只陈述事实）')
-    expect(text).toContain('[default]')
-    expect(text).toContain('候选集非空（共 1 文件），根解析正常')
-    expect(text).toContain('查询已做 uuid 归一化匹配（小写 + 去连字符）后仍无命中')
-    // ②编辑距离候选段存在
-    expect(text).toContain('最接近的候选（编辑距离）')
-    // ③「正确做法」四条
-    expect(text).toContain('正确做法')
-    expect(text).toContain('改用标题/keyword')
-    expect(text).toContain('直接传绝对路径')
-    expect(text).toContain('更短前缀')
-    expect(text).toContain('action:"doctor"')
-    // ④最后一行封死 shell 绕行
-    expect(text).toContain('不要用 shell find/ls/rg 搜 session 目录，不要 cat/read 原始 .jsonl')
-    // 负向：无「recent 看全量」误导、无归因断言
-    expect(text).not.toContain('recent')
-    expect(text).not.toContain('真的没有')
-    // details 程序化契约保持（零匹配形态不变）
-    expect(r.details).toEqual({ matches: [], truncated: false })
-  })
+  /**
+ * 建真实 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()
+    }
+  }
 
-  it('④ 编辑距离 top-3：近似 id 入选（标注 source 与差异位），远 id 被挤出', async () => {
-    const near1 = '019aaabc-0000-7000-8000-00000000000a'
-    const near2 = '019aaabc-0000-7000-8000-00000000000b'
-    const near3 = '019aaabc-0000-7000-8000-00000000000c'
-    const far = 'ffffffff-ffff-ffff-ffff-ffffffffffff'
-    await writeSession(near1)
-    await writeSession(near2)
-    await writeSession(near3, { subagent: true })
-    await writeSession(far)
-    // 手算锚点：query 与 near* 前 33 字符相同，第 34 位起 z→0/z→0/z→a，距离 3
-    expect(levenshtein('019aaabc-0000-7000-8000-000000000zzz', near1)).toBe(3)
-    expect(levenshtein('kitten', 'sitting')).toBe(3)
-
-    const r = await find('019aaabc-0000-7000-8000-000000000zzz')
-    const text = r.content[0].text
-    // top-3 恰为三个近似候选（far 距离约 36，第 4 名被上限挤掉）
-    expect(text).toContain(near1)
-    expect(text).toContain(near2)
-    expect(text).toContain(near3)
-    expect(text).not.toContain(far)
-    // 差异位标注（首个差异字符，1-based）
-    expect(text).toContain('差异在第 34 位：z → 0')
-    // source 标注：near3 在 subagent 根，标注透传
-    expect(text).toContain(`${near3}  subagent`)
-  })
+  /** 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')
+  }
 
-  it('⑤ §11.5 归一化对比基线：增量仅限大小写/连字符变体，非 uuid 乱串不被 norm 误吸', async () => {
-    const idHit = '019cafe0-1234-7000-8000-deadbeef0001'
-    await writeSession(idHit, { firstUserText: '福耀玻璃深度研究' })
-    await writeSession(ID2, { firstUserText: '完全不同的另一个会话' })
-
-    // 现状基线：精确小写片段命中 1
-    const base = await find('019cafe0')
-    expect((base.details as { matches: unknown[] }).matches).toHaveLength(1)
-    // 大写变体：增量 = 同一 id（大小写变体），无新对象
-    const upper = await find('019CAFE0')
-    expect((upper.details as { matches: Array<{ sessionId: string }> }).matches.map((m) => m.sessionId)).toEqual([idHit])
-    // 去连字符变体：增量 = 同一 id（连字符变体），无新对象
-    const noDash = await find('019cafe0123470008000deadbeef0001')
-    expect((noDash.details as { matches: Array<{ sessionId: string }> }).matches.map((m) => m.sessionId)).toEqual([idHit])
-    // 'deadbeef' 段是带连字符 id 的连续子串——现状精确匹配已命中，norm 后命中数不变（无增量）
-    const deadbeef = await find('deadbeef')
-    expect((deadbeef.details as { matches: Array<{ sessionId: string }> }).matches.map((m) => m.sessionId)).toEqual([idHit])
-    // keyword 路径不受 norm 影响（非 uuid 特征照常回退首消息）
-    const kw = await find('福耀玻璃')
-    expect((kw.details as { matches: Array<{ sessionId: string }> }).matches.map((m) => m.sessionId)).toEqual([idHit])
-    // 非 uuid 乱串：0 命中（norm 不把乱串吸进 uuid 匹配）
-    const junk = await find('zzznotexist9q')
-    expect((junk.details as { matches: unknown[] }).matches).toHaveLength(0)
-    // hex 乱串（uuid 特征但非任何 id 子串）：两级均 0 → 短路不回退（与现状一致，无召回回归）
-    const hexJunk = await find('0123456789abcdef')
-    expect((hexJunk.details as { matches: unknown[] }).matches).toHaveLength(0)
-  })
+  /** 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' },
+      },
+    })
+  }
 
-  it('⑥ 自检行计数 = 本次实扫结果 + 去重根注记', async () => {
-    const agentDir = join(tmp, 'agent')
-    // 根扫描无缓存（doctor 缓存机已删，ext-simplify-04 U3）——doctor 首跑后落盘的
-    // 文件，find 自检行照实扫计数（原 PS-14「doctor 缓存 0 文件」形态结构性不存在）
-    await mkdir(join(agentDir, 'sessions'), { recursive: true })
-    await handleSessionRead({ action: 'doctor' }, { agentDir })
-    // 之后 session 落盘（main 2 + subagent 1）
-    await writeSession(ID1)
-    await writeSession(ID2)
-    await writeSession('019e6c96-aaaa-bbbb-cccc-000000000003', { subagent: true })
-
-    const r = await handleSessionRead(
-      { action: 'find', query: 'zzz-no-hit-9q8x' },
-      { agentDir },
-    )
-    const text = r.content[0].text
-    expect(text).toContain(`${join(agentDir, 'sessions')}：2 文件`)
-    expect(text).toContain(`${resolveSessionStoreRoot(agentDir)}：1 文件`)
-    expect(text).toContain('候选集非空（共 3 文件）')
-
-    // 完整信号包（live 与 default 同路径）→ 去重根注记，不重复计数
-    const deduped = await handleSessionRead(
-      { action: 'find', query: 'zzz-no-hit-9q8x' },
-      { agentDir, liveSessionDir: join(agentDir, 'sessions') },
-    )
-    expect(deduped.content[0].text).toContain('同路径，已去重')
-    expect(deduped.content[0].text).toContain('候选集非空（共 3 文件）')
-  })
-})
-
-// ============================================================
-// 片段解析接通 [live] 根（同一 roots 契约）：resolveByFragment/doXxx 透传
-// liveSessionDir——[live]≠[default] 环境（纯 pi + 显式 --session-dir）下，find
-// 能列出的 session 在 outline/result 等解析路径同样可达；F1 自检行含 [live] 根行。
-// 全部 mkdtemp fixture 自建自删，不触碰真实数据目录。
-// ============================================================
-
-describe('片段解析接通 [live] 根（fixture，同一 roots 契约）', () => {
-  let tmp: string
-  const SLUG = '--live-cwd--'
-  const ID = '019e6c96-aaaa-bbbb-cccc-0000000000aa'
-  const FRAGMENT = '0000000000aa'
-  let agentDir: string
-  /** liveSessionDir 信号（encodeCwd 形态，normalizeLiveSessionDir 剥层到 sessions/ 根）。 */
-  let liveDir: string
-  /** 剥层后的 [live] 根路径（F1 自检行的显示形态）。 */
-  let liveRoot: string
-
-  /** 在指定目录写 session 文件（header + user 消息，extraLines 追加 assistant 等条目）。 */
-  async function writeSessionAt(dir: string, id: string, extraLines: string[] = []): Promise<void> {
-    await mkdir(dir, { recursive: true })
-    const lines = [
-      JSON.stringify({ type: 'session', id, cwd: '/demo' }),
-      JSON.stringify({
-        type: 'message',
-        id: `${id}-m1`,
-        parentId: id,
-        message: { role: 'user', content: [{ type: 'text', text: 'live 根里的会话' }] },
-      }),
-      ...extraLines,
-    ]
-    await writeFile(join(dir, `${id}.jsonl`), lines.join('\n') + '\n')
+  /**
+ * 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' },
+      },
+    })
   }
 
-  beforeEach(async () => {
-    tmp = await mkdtemp(join(tmpdir(), 'tool-handler-live-'))
-    agentDir = join(tmp, 'agent')
-    await mkdir(join(agentDir, 'sessions'), { recursive: true }) // [default] 空根
-    liveDir = join(tmp, 'pi-live', 'sessions', SLUG)
-    liveRoot = join(tmp, 'pi-live', 'sessions')
-  })
-  afterEach(async () => {
-    await rm(tmp, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
-  })
+  const HEADER_LINE = JSON.stringify({ type: 'session', id: 'main-session-1', cwd: '/proj' })
 
-  it('① [live]≠[default]：outline 片段解析到 [live] 根 session；不传信号则 F1（负向对照）', async () => {
-    await writeSessionAt(liveDir, ID)
-    // 接通后：片段解析可达 [live] 根，outline 正常产出
-    const r = await handleSessionRead(
-      { action: 'outline', session: FRAGMENT },
-      { agentDir, liveSessionDir: liveDir },
-    )
-    const d = r.details as { stats: { totalTurns: number } }
-    expect(d.stats.totalTurns).toBeGreaterThanOrEqual(1)
-    // 负向对照：不传 liveSessionDir（三根降级）→ 同一片段 F1 零匹配
-    //（[default]/[legacy]/[subagent] 均无此文件——证明命中确实来自 [live] 根）
-    await expect(
-      handleSessionRead({ action: 'outline', session: FRAGMENT }, { agentDir }),
-    ).rejects.toThrow(/无匹配 session/)
+  const USER_LINE = JSON.stringify({
+    type: 'message',
+    id: 'u1',
+    parentId: null,
+    message: { role: 'user', content: [{ type: 'text', text: 'dispatch subagent' }] },
   })
 
-  it('② F1 自检行含 [live] 根行（剥层路径 + 实扫计数），与 [default] 空根同表可见', async () => {
-    await writeSessionAt(liveDir, ID)
-    const caught = await handleSessionRead(
-      { action: 'outline', session: 'zzz-no-hit-9q8x' },
-      { agentDir, liveSessionDir: liveDir },
-    ).catch((e: unknown) => e)
-    expect(caught).toBeInstanceOf(Error)
-    const text = (caught as Error).message
-    expect(text).toContain('无匹配 session："zzz-no-hit-9q8x"')
-    expect(text).toContain('自检（发现层，只陈述事实）')
-    // [live] 根行：encodeCwd 已剥层到 sessions/ 根，计数 = 本次实扫
-    expect(text).toContain(`${liveRoot}：1 文件`)
-    // [default] 空根同表可见（同一 roots 契约的全貌）
-    expect(text).toContain(`${join(agentDir, 'sessions')}：0 文件`)
-  })
+  /** liveSessionDir 内的主 session 文件（entry 兜底候选）。 */
+  function writeLiveMainSession(lines: string[]): void {
+    writeFileSync(join(liveDir, 'main-session.jsonl'), [HEADER_LINE, USER_LINE, ...lines].join('\n') + '\n', 'utf8')
+  }
 
-  it('③ result 片段形态同样可达 [live] 根（per-call deps 接线）', async () => {
-    await writeSessionAt(liveDir, ID, [
-      JSON.stringify({
-        type: 'message',
-        id: `${ID}-a1`,
-        parentId: `${ID}-m1`,
-        message: { role: 'assistant', content: [{ type: 'text', text: '最终结论正文' }] },
-      }),
-    ])
-    const r = await handleSessionRead(
-      { action: 'result', session: FRAGMENT },
-      { agentDir, liveSessionDir: liveDir },
+  /** 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',
     )
-    expect(r.content[0].text).toContain('最终结论正文')
-  })
-})
-
-// ============================================================
-// u10：find 分组输出（design 2026-09-10 §5.1 形态 / §6.7 子决策 2/3 / §8.2 回归基线）
-// ============================================================
-
-describe('u10 find 分组输出（fixture，§6.7 子决策 2/3 + §8.2 回归基线）', () => {
-  let tmp: string
-  const SLUG = '--demo-cwd--'
-  // uuidv7 同毫秒时间前缀碰撞是现网「34 条 subagent」形态的成因（§3.4），fixture 沿用共享前缀
-  const PREFIX = '019e6c96'
-  const mainId = (n: number) => `${PREFIX}-aaaa-bbbb-cccc-d${String(n).padStart(11, '0')}`
-  const subId = (n: number) => `${PREFIX}-aaaa-bbbb-cccc-e${String(n).padStart(11, '0')}`
-
-  /** 写 session 文件（subagent:true 写入 subagent 根），形态同 u9 段 writeSession。 */
-  async function writeSession(
-    id: string,
-    opts?: { subagent?: boolean; firstUserText?: string },
-  ): Promise<void> {
-    // [session-store-layout-inversion] subagent 会话在新布局存储树（分区 sid 固定合法形态）
-    const dir = opts?.subagent
-      ? resolveStoreSubagentSessionsDir(join(tmp, 'agent'), '0aaaaaaa-bbbb-7ccc-dddd-0000000000s1')
-      : join(tmp, 'agent', 'sessions', SLUG)
-    await mkdir(dir, { recursive: true })
-    const lines = [JSON.stringify({ type: 'session', id, cwd: '/demo' })]
-    if (opts?.firstUserText !== undefined) {
-      lines.push(
-        JSON.stringify({
-          type: 'message',
-          id: `${id}-m1`,
-          message: { role: 'user', content: [{ type: 'text', text: opts.firstUserText }] },
-        }),
-      )
-    }
-    await writeFile(join(dir, `${id}.jsonl`), lines.join('\n') + '\n')
   }
 
-  /**
-   * 写带 assistant 正文的 subagent（manifest + session 文件三行形态），
-   * 供 result action 批量调用（回归基线：批量头行 8 字符短 id 不受 u10 影响）。
-   */
-  async function writeSubagentWithResult(saId: string, id: string, body: string): Promise<void> {
-    const sessionFile = join(
-      resolveStoreSubagentSessionsDir(join(tmp, 'agent'), 'root-u10'),
-      `${id}.jsonl`,
+  /** 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',
     )
-    await mkdir(dirname(sessionFile), { recursive: true })
-    const lines = [
-      JSON.stringify({ type: 'session', id, cwd: '/demo' }),
+    const recordsDir = join(dirname(agentDir), 'ext-sessions', ROOT_SESSION, 'subagents', 'records')
+    mkdirSync(recordsDir, { recursive: true })
+    writeFileSync(
+      join(recordsDir, 'sa-pi-1.json'),
       JSON.stringify({
-        type: 'message',
-        id: `${id}-m1`,
-        message: { role: 'user', content: [{ type: 'text', text: 'task' }] },
+        id: 'sa-pi-1',
+        rootSessionId: ROOT_SESSION,
+        agentName: 'pi-agent',
+        sessionFile: piSession,
+        slug: 'pi-sub',
+        status: 'completed',
       }),
-      JSON.stringify({
-        type: 'message',
-        id: `${id}-a1`,
-        message: { role: 'assistant', content: [{ type: 'text', text: body }] },
-      }),
-    ]
-    await writeFile(sessionFile, lines.join('\n') + '\n')
-    const recordsDir = resolveStoreSubagentRecordsDir(join(tmp, 'agent'), 'root-u10')
-    await mkdir(recordsDir, { recursive: true })
-    await writeFile(
-      join(recordsDir, `${saId}.json`),
-      JSON.stringify({ id: saId, rootSessionId: 'root-u10', agentName: 'explorer', sessionFile }),
+      'utf8',
     )
   }
 
-  function find(
-    query: string,
-    extra?: Partial<SessionReadParams>,
-  ): ReturnType<typeof handleSessionRead> {
-    return handleSessionRead({ action: 'find', query, ...extra }, { agentDir: join(tmp, 'agent') })
-  }
+  const signals = () => ({ agentDir, liveSessionDir: liveDir })
 
-  interface FindDetails {
-    matches: Array<{ source: string; sessionId: string }>
-    truncated: boolean
+  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
   }
 
-  beforeEach(async () => {
-    tmp = await mkdtemp(join(tmpdir(), 'tool-handler-u10-'))
-  })
-  afterEach(async () => {
-    await rm(tmp, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
-  })
+  // ---------------------------------------------------------------------------
+  // 变体 M（manifest 在场，主路径）+ 场景 2 动作覆盖
+  // ---------------------------------------------------------------------------
 
-  it('① main 置顶 + 全 id + ↳ 可复制调用串 + 编号跨组连续（§5.1 全列出形态）', async () => {
-    const M1 = mainId(1)
-    const S1 = subId(1)
-    const S2 = subId(2)
-    await writeSession(M1, { firstUserText: 'main content' })
-    await writeSession(S1, { subagent: true, firstUserText: 'sub content one' })
-    await writeSession(S2, { subagent: true, firstUserText: 'sub content two' })
-
-    const r = await find(PREFIX)
-    const text = r.content[0].text
-    // main 段置顶：main 组头与 main id 均先于 subagent 出现
-    expect(text.indexOf('main（')).toBeLessThan(text.indexOf('subagent（'))
-    expect(text.indexOf(M1)).toBeLessThan(text.indexOf(S1))
-    expect(text).toContain('main（1 条命中）：')
-    expect(text).toContain('subagent（2 条命中）：')
-    // 全 id：36 字符完整出现，8 字符截断形态消失（§6.7 子决策 3）
-    expect(text).toContain(M1)
-    expect(text).not.toContain(`${M1.slice(0, 8)}…`)
-    // ↳ 可复制调用串只附 main 候选（subagent 噪声不配指针）
-    expect(text).toContain(`↳ session_read { action:"outline", session:"${M1}" }`)
-    expect(text).not.toContain(`session:"${S1}"`)
-    // 编号跨组连续：main 是 1 号，subagent 段续 2 号（组内 mtime 序不固定，用正则）
-    expect(text).toContain(`  1. ${M1}`)
-    expect(text).toMatch(/  2\. 019e6c96-aaaa-bbbb-cccc-e0000000000[12]/)
-    // details 合并列表：main 首位、集合完整、无截断
-    const d = r.details as FindDetails
-    expect(d.truncated).toBe(false)
-    expect(d.matches[0]).toMatchObject({ source: 'main', sessionId: M1 })
-    expect(new Set(d.matches.map((m) => m.sessionId))).toEqual(new Set([M1, S1, S2]))
-  })
+  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('② subagent 超剩余配额 → 折叠计数行 + 加 source:"subagent" 提示（§6.7 子决策 2）', async () => {
-    const M1 = mainId(1)
-    await writeSession(M1)
-    for (let i = 1; i <= 3; i++) await writeSession(subId(i), { subagent: true })
-
-    // limit 2：main 1 条（无溢出）→ 剩余配额 1 → subagent 展示 1 条 + 溢出折叠
-    const r = await find(PREFIX, { limit: 2 })
-    const text = r.content[0].text
-    expect(text).toContain('main（1 条命中）：')
-    expect(text).toContain('subagent（>1 条命中，显示前 1 条）：')
-    expect(text).toContain('… 另有 subagent 命中未显示。👉 加 source:"subagent" 查看')
-    const d = r.details as FindDetails
-    expect(d.truncated).toBe(true)
-    expect(d.matches).toHaveLength(2)
-    expect(d.matches[0].source).toBe('main')
-    expect(d.matches.filter((m) => m.source === 'subagent')).toHaveLength(1)
-  })
+    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('③ main 命中占满 limit → subagent 段 0 条仅显示计数（§6.7：main 优先占满）', async () => {
-    for (let i = 1; i <= 3; i++) await writeSession(mainId(i))
-    for (let i = 1; i <= 2; i++) await writeSession(subId(i), { subagent: true })
-
-    const r = await find(PREFIX, { limit: 3 })
-    const text = r.content[0].text
-    expect(text).toContain('main（3 条命中）：')
-    expect(text).toContain('subagent（有命中未显示——展示配额已被 main 占满）：')
-    expect(text).toContain('👉 加 source:"subagent" 查看')
-    // subagent 条目与调用串不出现（0 条展示）
-    expect(text).not.toContain(subId(1))
-    const d = r.details as FindDetails
-    expect(d.matches).toHaveLength(3)
-    expect(d.matches.every((m) => m.source === 'main')).toBe(true)
-    // 合并总量：命中 3 main + 2 sub > 展示 3 → truncated=true
-    expect(d.truncated).toBe(true)
-  })
+    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('④ truncated 按合并总量计算（命中总数 vs 实际输出数，含 main 恰满边界）', async () => {
-    for (let i = 1; i <= 2; i++) await writeSession(mainId(i))
-    for (let i = 1; i <= 2; i++) await writeSession(subId(i), { subagent: true })
-
-    // a) 全列出（4 ≤ 20）：truncated=false
-    const all = (await find(PREFIX)).details as FindDetails
-    expect(all.matches).toHaveLength(4)
-    expect(all.truncated).toBe(false)
-
-    // b) main 恰好占满 limit（2/2）+ subagent 有命中 → 仍截断（防 main 恰满漏探测 subagent）
-    const exact = (await find(PREFIX, { limit: 2 })).details as FindDetails
-    expect(exact.matches).toHaveLength(2)
-    expect(exact.matches.every((m) => m.source === 'main')).toBe(true)
-    expect(exact.truncated).toBe(true)
-
-    // c) 混合截断：展示 3（2 main + 1 sub）< 命中 4 → truncated=true
-    const mixed = (await find(PREFIX, { limit: 3 })).details as FindDetails
-    expect(mixed.matches).toHaveLength(3)
-    expect(mixed.matches.filter((m) => m.source === 'main')).toHaveLength(2)
-    expect(mixed.matches.filter((m) => m.source === 'subagent')).toHaveLength(1)
-    expect(mixed.truncated).toBe(true)
-  })
+    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('⑤a 回归基线：find{query:<前缀>, limit:100} main 0 条 + subagent 全列（现网 34 条形态）', async () => {
-    for (let i = 1; i <= 34; i++) await writeSession(subId(i), { subagent: true })
-
-    const r = await find(PREFIX, { limit: 100 })
-    const d = r.details as FindDetails
-    expect(d.matches).toHaveLength(34)
-    expect(d.matches.every((m) => m.source === 'subagent')).toBe(true)
-    expect(d.truncated).toBe(false)
-    const text = r.content[0].text
-    // main 段 0 条可辨识（防「全是 subagent」被误读），subagent 段全列不折叠
-    expect(text).toContain('main（0 条命中）：')
-    expect(text).toContain('subagent（34 条命中）：')
-    expect(text).not.toContain('加 source:"subagent"')
+    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')
+    })
   })
 
-  it('⑤b 回归基线：result 批量头行仍 8 字符短 id（SESSION_ID_PREFIX_LEN 通路不动）', async () => {
-    const R1 = `${PREFIX}-aaaa-bbbb-cccc-f00000000001`
-    const R2 = `${PREFIX}-aaaa-bbbb-cccc-f00000000002`
-    await writeSubagentWithResult('sa-u10-r1', R1, 'alpha body')
-    await writeSubagentWithResult('sa-u10-r2', R2, 'beta body')
+  // ---------------------------------------------------------------------------
+  // 变体 E（manifest 缺位 → entry 兜底取末条）
+  // ---------------------------------------------------------------------------
 
-    const res = await handleSessionRead(
-      { action: 'result', session: 'sa-u10-r1,sa-u10-r2' },
-      { agentDir: join(tmp, 'agent') },
-    )
-    const text = res.content[0].text
-    expect(text).toContain(`(session ${R1.slice(0, 8)}…)`)
-    expect(text).toContain(`(session ${R2.slice(0, 8)}…)`)
-  })
+  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('⑤c 回归基线：recent 查询 main 段置顶可辨识', async () => {
-    for (let i = 1; i <= 2; i++) await writeSession(mainId(i))
-    for (let i = 1; i <= 2; i++) await writeSession(subId(i), { subagent: true })
-
-    const r = await find('recent')
-    const text = r.content[0].text
-    expect(text.indexOf('main（2 条命中）：')).toBeLessThan(text.indexOf('subagent（2 条命中）：'))
-    const d = r.details as FindDetails
-    expect(d.matches).toHaveLength(4)
-    // 分组价值：main/subagent 的 mtime 交错也被 main 段置顶（§8.2「main 段置顶后可辨识」）
-    expect(d.matches.slice(0, 2).every((m) => m.source === 'main')).toBe(true)
-    expect(d.truncated).toBe(false)
-  })
+    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('⑥ resolveByFragment 独立无分组语义：outline 片段多匹配 → F2 全量候选（不被配额截断）', async () => {
-    for (let i = 1; i <= 2; i++) await writeSession(mainId(i))
-    for (let i = 1; i <= 3; i++) await writeSession(subId(i), { subagent: true })
-
-    // 解析路径（resolveByFragment → findSessions limit:10 无 source）保持 mtime 排序 +
-    // limit 截断原语义：5 命中全进 F2 消歧候选，无 main 置顶/配额分组介入（§6.7 末条）
-    const r = await handleSessionRead({ action: 'outline', session: PREFIX }, { agentDir: join(tmp, 'agent') })
-    const d = r.details as { ambiguous: boolean; candidates: Array<{ sessionId: string }> }
-    expect(d.ambiguous).toBe(true)
-    expect(d.candidates).toHaveLength(5)
-    expect(new Set(d.candidates.map((c) => c.sessionId))).toEqual(
-      new Set([mainId(1), mainId(2), subId(1), subId(2), subId(3)]),
-    )
+    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]*👉/)
+    })
   })
 
-  it('⑥b 显式 source 查询走单组原语义：不折叠、保持 mtime+limit 截断', async () => {
-    for (let i = 1; i <= 3; i++) await writeSession(subId(i), { subagent: true })
-
-    // 显式 source 本身就是折叠提示所指的展开动作，不再折叠
-    const r = await find(PREFIX, { source: 'subagent', limit: 1 })
-    const text = r.content[0].text
-    expect(text).toContain('subagent（1 条命中）：')
-    expect(text).not.toContain('加 source:"subagent"')
-    const d = r.details as FindDetails
-    expect(d.matches).toHaveLength(1)
-    expect(d.matches[0].source).toBe('subagent')
-    expect(d.truncated).toBe(true)
-  })
-})
-
-// ============================================================
-// E1：find 单次根解析（ext-simplify-04 U2，探针 P1）。spy 打在 roots 模块命名空间
-// 上跨模块拦截（find.ts / findNoMatch 渲染链的消费点全走同一入口），断言 doFind
-// 全路径（分组 / 显式 source / 零匹配）resolveSessionRoots 恰调用 1 次——改前分组
-// 2 次、零匹配 3 次（impl-plan D-15④ 登记的分组双倍实扫债），预解析根复用后恒 1 次。
-// ============================================================
-describe('E1 find 单次根解析（探针 P1：resolveSessionRoots 恰 1 次）', () => {
-  let tmp: string
-  const SLUG = '--e1-cwd--'
-  const PREFIX = '019e7e10'
-  const mainId = (n: number) => `${PREFIX}-aaaa-bbbb-cccc-d${String(n).padStart(11, '0')}`
-  const subId = (n: number) => `${PREFIX}-aaaa-bbbb-cccc-e${String(n).padStart(11, '0')}`
-
-  /** 写 session 文件（subagent:true 写入 subagent 根），形态同 u10 段 writeSession。 */
-  async function writeSession(id: string, opts?: { subagent?: boolean }): Promise<void> {
-    // [session-store-layout-inversion] subagent 会话在新布局存储树（分区 sid 固定合法形态）
-    const dir = opts?.subagent
-      ? resolveStoreSubagentSessionsDir(join(tmp, 'agent'), '0aaaaaaa-bbbb-7ccc-dddd-0000000000s1')
-      : join(tmp, 'agent', 'sessions', SLUG)
-    await mkdir(dir, { recursive: true })
-    await writeFile(
-      join(dir, `${id}.jsonl`),
-      JSON.stringify({ type: 'session', id, cwd: '/e1' }) + '\n',
-    )
-  }
+  // ---------------------------------------------------------------------------
+  // 场景 5：八类失败逐一断言（错误码 + 👉 指引 + ④ 顺序断言两种构造）
+  // ---------------------------------------------------------------------------
 
-  function find(
-    query: string,
-    extra?: Partial<SessionReadParams>,
-  ): ReturnType<typeof handleSessionRead> {
-    return handleSessionRead({ action: 'find', query, ...extra }, { agentDir: join(tmp, 'agent') })
-  }
+  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]*导入/,
+      )
+    })
 
-  /** spy 计数器 + 断言 helper：包装一段 find 调用，返回 { 结果, 调用次数 }。 */
-  async function findCounting(
-    query: string,
-    extra?: Partial<SessionReadParams>,
-  ): Promise<{ result: Awaited<ReturnType<typeof handleSessionRead>>; resolveCalls: number }> {
-    const rootsModule = await import('../discovery/roots.js')
-    const spy = vi.spyOn(rootsModule, 'resolveSessionRoots')
-    try {
-      const result = await find(query, extra)
-      return { result, resolveCalls: spy.mock.calls.length }
-    } finally {
-      spy.mockRestore()
-    }
-  }
+    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)
+    })
 
-  beforeEach(async () => {
-    tmp = await mkdtemp(join(tmpdir(), 'tool-handler-e1-'))
-  })
-  afterEach(async () => {
-    await rm(tmp, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
-  })
+    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('① 分组路径（main + subagent 两段查询，有命中）：恰 1 次', async () => {
-    await writeSession(mainId(1))
-    await writeSession(subId(1), { subagent: true })
-    const { result, resolveCalls } = await findCounting(PREFIX)
-    const d = result.details as { matches: Array<{ source: string }>; truncated: boolean }
-    // 前置：两段确实各自命中（分组语义不变），再断言扫描收敛
-    expect(d.matches).toHaveLength(2)
-    expect(new Set(d.matches.map((m) => m.source))).toEqual(new Set(['main', 'subagent']))
-    expect(d.truncated).toBe(false)
-    expect(resolveCalls).toBe(1)
-  })
+    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('② 显式 source 路径（单组查询，有命中）：恰 1 次', async () => {
-    await writeSession(mainId(1))
-    await writeSession(subId(1), { subagent: true })
-    const { result, resolveCalls } = await findCounting(PREFIX, { source: 'subagent' })
-    const d = result.details as { matches: Array<{ source: string }> }
-    expect(d.matches).toHaveLength(1)
-    expect(d.matches[0].source).toBe('subagent')
-    expect(resolveCalls).toBe(1)
-  })
+    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('③ 分组零匹配 → F1 自检行：恰 1 次（改前 3 次）且根表仍进渲染', async () => {
-    await writeSession(mainId(1))
-    const { result, resolveCalls } = await findCounting('zzz-e1-no-hit-9q8x')
-    const d = result.details as { matches: unknown[]; truncated: boolean }
-    expect(d.matches).toEqual([])
-    expect(d.truncated).toBe(false)
-    // F1 自检行消费预解析根表（非空根计数可见 = roots 确实传入而非空列表）
-    expect(result.content[0].text).toContain('自检（发现层，只陈述事实）')
-    expect(result.content[0].text).toContain('候选集非空')
-    expect(resolveCalls).toBe(1)
-  })
+    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('④ 显式 source 零匹配 → F1 自检行：恰 1 次（改前 2 次）', async () => {
-    await writeSession(subId(1), { subagent: true })
-    const { result, resolveCalls } = await findCounting('zzz-e1-no-hit-9q8x', { source: 'main' })
-    expect(result.content[0].text).toContain('无匹配 session')
-    expect(result.content[0].text).toContain('自检（发现层，只陈述事实）')
-    expect(resolveCalls).toBe(1)
-  })
-})
-
-// ============================================================
-// u11：metadataProvider 注入 + TTL 缓存（design 2026-09-10 §6.6）
-// handler 级集成：注入包装（metadata 缓存独立实例——根扫描无缓存，doctor 缓存机
-// 已删除，ext-simplify-04 U3，不存在串扰面）
-// + 标题渲染（§5.1 候选行标题优先）+ provider 抛错降级不外抛。
-// 策略①惰性/②窄化/合并语义在 find.test.ts u11 段覆盖。
-// ============================================================
-describe('u11 metadataProvider 注入 + TTL 缓存（fixture，§6.6）', () => {
-  let tmp: string
-  /** 平铺 main 根（taiji 形态），同时作 liveSessionDir（与 [default] 根同字面路径） */
-  let flatMain: string
-
-  async function writeSession(
-    id: string,
-    opts?: { firstUserText?: string },
-  ): Promise<string> {
-    await mkdir(flatMain, { recursive: true })
-    const lines = [JSON.stringify({ type: 'session', id, cwd: '/demo' })]
-    if (opts?.firstUserText !== undefined) {
-      lines.push(
-        JSON.stringify({
-          type: 'message',
-          id: `${id}-m1`,
-          message: { role: 'user', content: [{ type: 'text', text: opts.firstUserText }] },
-        }),
+    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/,
       )
-    }
-    const path = join(flatMain, `${id}.jsonl`)
-    await writeFile(path, lines.join('\n') + '\n')
-    return path
-  }
+    })
 
-  function findWithProvider(
-    query: string,
-    provider: SessionMetadataProvider,
-  ): ReturnType<typeof handleSessionRead> {
-    return handleSessionRead(
-      { action: 'find', query },
-      { agentDir: join(tmp, 'agent'), liveSessionDir: flatMain },
-      undefined,
-      provider,
-    )
-  }
+    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]*👉/,
+      )
+    })
 
-  beforeEach(async () => {
-    tmp = await mkdtemp(join(tmpdir(), 'tool-handler-u11-'))
-    flatMain = join(tmp, 'agent', 'sessions')
-  })
-  afterEach(async () => {
-    await rm(tmp, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
-  })
+    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('② 标题进匹配与渲染：keyword 命中 name → 候选行标题优先展示 + details.matches[].name 透传', async () => {
-    const id = 'm-title-0001'
-    const p = await writeSession(id, { firstUserText: '首消息无关' })
-    const provider = vi.fn(async (dir: string) =>
-      dir === flatMain
-        ? [
-            {
-              path: p,
-              id,
-              cwd: '/demo',
-              name: '太保寿险深度研究攻坚',
-              modified: new Date(),
-              firstMessage: '首消息无关',
-            },
-          ]
-        : [],
-    )
-    const r = await findWithProvider('太保寿险', provider)
-    const text = r.content[0].text
-    // §5.1 形态：候选行末段为标题（name 优先于首消息预览）
-    expect(text).toContain('太保寿险深度研究攻坚')
-    const d = r.details as { matches: Array<{ sessionId: string; name?: string }> }
-    expect(d.matches[0].sessionId).toBe(id)
-    expect(d.matches[0].name).toBe('太保寿险深度研究攻坚')
-    // 注入边界生效：provider 被 TTL 包装调用且实参非空串
-    expect(provider).toHaveBeenCalledTimes(1)
-    expect(provider.mock.calls[0][0]).toBe(flatMain)
+    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/,
+      )
+    })
   })
 
-  it('④ provider 抛错 → handler 不抛，降级首条 user 匹配（标题留空，错误不外泄）', async () => {
-    const id = 'err-handler-01'
-    await writeSession(id, { firstUserText: 'handler 降级命中文本' })
-    const provider = vi.fn(async () => {
-      throw new Error('listAll secret boom')
+  // ---------------------------------------------------------------------------
+  // 驱动探测失败的错误契约（跨包漂移检查 + 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)
     })
-    const r = await findWithProvider('handler 降级命中', provider)
-    const d = r.details as { matches: Array<{ sessionId: string; name?: string }> }
-    expect(d.matches).toHaveLength(1)
-    expect(d.matches[0].sessionId).toBe(id)
-    expect(d.matches[0].name).toBeUndefined()
-    // 错误细节不进工具输出（降级不是错误）
-    expect(r.content[0].text).not.toContain('boom')
-  })
 
-  it('⑤ TTL 缓存（fake timers）：TTL 内不重调、过期重调、目录 mtime 变化失效', async () => {
-    const id = 'ttl-00000001'
-    const p = await writeSession(id, { firstUserText: '无关' })
-    const provider = vi.fn(async (dir: string) =>
-      dir === flatMain
-        ? [{ path: p, id, cwd: '/demo', name: '标题', modified: new Date() }]
-        : [],
-    )
-    // 仅 fake Date（缓存 TTL 判定用），fs/performance 走真实实现
-    vi.useFakeTimers({ toFake: ['Date'] })
-    try {
-      // 首查：cache miss → 调 1 次
-      await findWithProvider('zzznohit9q', provider)
-      expect(provider).toHaveBeenCalledTimes(1)
-      // TTL 内二查：命中缓存不重调
-      await findWithProvider('zzznohit9q', provider)
-      expect(provider).toHaveBeenCalledTimes(1)
-      // TTL 过期 → 重调
-      vi.setSystemTime(Date.now() + METADATA_CACHE_TTL_MS + 1)
-      await findWithProvider('zzznohit9q', provider)
-      expect(provider).toHaveBeenCalledTimes(2)
-      // TTL 内但目录 mtime 变化 → 失效重调
-      const bumped = new Date(Date.now() + 60_000)
-      await utimes(flatMain, bumped, bumped)
-      await findWithProvider('zzznohit9q', provider)
-      expect(provider).toHaveBeenCalledTimes(3)
-    } finally {
-      vi.useRealTimers()
-    }
-  })
-})
-
-// ---------------------------------------------------------------------------
-// u12 跨会话内容检索（fixture，§2 目标 5 / §8.2 V8：窄化前置 + 字节上限 + 渲染）
-// 全部 mkdtemp fixture 自建自删，不触碰真实数据目录。
-// ---------------------------------------------------------------------------
-
-describe('u12 跨会话内容检索（fixture，V8）', () => {
-  let tmp: string
-  /** main 根（平铺，[default] 根直扫）与 subagent 根 */
-  let mainDir: string
-  const SLUG = '--demo-cwd--'
-  // uuidv7 风格形态（find 输出的完整 id 即此形态；u12 索引按 header id，不依赖文件名反推）
-  const mainId = (n: number) => `019e6c96-aaaa-bbbb-cccc-d${String(n).padStart(11, '0')}`
-  const subId = (n: number) => `019e6c96-aaaa-bbbb-cccc-e${String(n).padStart(11, '0')}`
+    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')
+    })
 
-  /**
-   * 写多 turn session（链式 parentId——buildTreeView leaf 回溯需要，无链的后行 entry
-   * 会被当旁支过滤，MF-5 段同款教训）。turn 分段：user 开新 turn，assistant 并入当前。
-   */
-  async function writeSession(
-    id: string,
-    turns: Array<{ role: 'user' | 'assistant'; text: string }>,
-    opts?: { subagent?: boolean },
-  ): Promise<void> {
-    const dir = opts?.subagent
-      ? resolveStoreSubagentSessionsDir(join(tmp, 'agent'), '0aaaaaaa-bbbb-7ccc-dddd-0000000000s2')
-      : join(tmp, 'agent', 'sessions')
-    await mkdir(dir, { recursive: true })
-    const lines = [JSON.stringify({ type: 'session', id, cwd: '/demo' })]
-    turns.forEach((t, i) => {
-      lines.push(
-        JSON.stringify({
-          type: 'message',
-          id: `${id}-m${i}`,
-          parentId: i === 0 ? id : `${id}-m${i - 1}`,
-          message: { role: t.role, content: [{ type: 'text', text: t.text }] },
-        }),
+    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')
     })
-    await writeFile(join(dir, `${id}.jsonl`), lines.join('\n') + '\n')
-  }
 
-  /** 造大文件：追加一条 2KB filler 文本（字节上限用例用，pattern 避开 filler 字符）。 */
-  async function writeFatSession(id: string): Promise<void> {
-    await writeSession(id, [
-      { role: 'user', text: `filler ${'x'.repeat(2048)}` },
-      { role: 'assistant', text: 'done' },
-    ])
-  }
+    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)
+    })
 
-  interface CrossDetails {
-    rejected?: boolean
-    candidateCount?: number
-    pattern: string
-    scope: string
-    degraded: boolean
-    byteBudget: number
-    scannedBytes: number
-    scanned: Array<{
-      sessionId: string
-      source: string
-      name?: string
-      hits: Array<{ turnIndex: number; entryIndex: number; role: string; matchSnippet: string }>
-      hitsTotal?: number
-    }>
-    skipped: Array<{ sessionId: string; reason: string; sizeBytes?: number }>
-    truncated: boolean
-  }
+    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')
+    })
 
-  beforeEach(async () => {
-    tmp = await mkdtemp(join(tmpdir(), 'tool-handler-u12-'))
-    mainDir = join(tmp, 'agent', 'sessions')
-  })
-  afterEach(async () => {
-    await rm(tmp, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+    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')
+    })
   })
 
-  it('① 窄化拒绝：候选超上限 → 拒绝文案 + 先 find 指引，不深扫（V8）', async () => {
-    // 库中放一个真实可命中的 session——拒绝路径不得把它扫出来
-    await writeSession(mainId(1), [
-      { role: 'user', text: '讨论 adj_factor 的历史数据' },
-      { role: 'assistant', text: 'adj_factor 表在 dws 库' },
-    ])
-    const ids = Array.from({ length: MULTI_SEARCH_MAX_SESSIONS + 1 }, (_, i) => mainId(i + 10))
-    const r = await handleSessionRead(
-      { action: 'search', session: ids.join(','), pattern: 'adj_factor' },
-      { agentDir: join(tmp, 'agent') },
-    )
-    const text = r.content[0].text
-    expect(text).toContain('跨会话检索已拒绝')
-    expect(text).toContain(`超出单次上限 ${MULTI_SEARCH_MAX_SESSIONS} 个`)
-    expect(text).toContain('先窄化')
-    expect(text).toContain('action:"find"')
-    expect(text).toContain('action:"search", session:"<id1>,<id2>"')
-    const d = r.details as Partial<CrossDetails>
-    expect(d.rejected).toBe(true)
-    expect(d.candidateCount).toBe(MULTI_SEARCH_MAX_SESSIONS + 1)
-    // 不深扫：可命中内容与命中结构都不出现
-    expect(text).not.toContain('adj_factor 表在 dws 库')
-    expect(text).not.toContain('hits:')
-    expect(d.scanned).toBeUndefined()
-  })
+  // ---------------------------------------------------------------------------
+  // family 接线（buildFamilyFromFs zcode 分支 + sa-id family 路由）
+  // ---------------------------------------------------------------------------
 
-  it('②a 字节上限截断：预算按序消耗，放不下的文件起整段停止并报告已扫范围', async () => {
-    const A = mainId(1)
-    const B = mainId(2)
-    await writeSession(A, [
-      { role: 'user', text: 'small session' },
-      { role: 'assistant', text: 'ok' },
-    ])
-    await writeFatSession(B)
-    // 直接调导出函数注入小预算（工具路径走默认 64MB，fixture 不构造 64MB 文件）
-    const r = await searchAcrossSessions([A, B], 'zzzkw', { agentDir: join(tmp, 'agent') }, {
-      byteBudget: 1024,
+  describe('family：zcode 节点接线（D5-1 两态）与 sa-id family 路由', () => {
+    beforeEach(() => {
+      createZcodeDb(dbPath, '0.16.5', [sessBRows()])
+      writeZcodeManifest(SA_M)
+      writeRootSessionFile()
     })
-    const d = r.details as CrossDetails
-    // A 扫完（无命中也入 scanned），B 放不下 → byte-budget，且其 sizeBytes 有报告
-    expect(d.scanned).toHaveLength(1)
-    expect(d.scanned[0].sessionId).toBe(A)
-    expect(d.scannedBytes).toBeGreaterThan(0)
-    expect(d.scannedBytes).toBeLessThanOrEqual(1024)
-    expect(d.skipped).toHaveLength(1)
-    expect(d.skipped[0]).toMatchObject({ sessionId: B, reason: 'byte-budget' })
-    expect(d.skipped[0].sizeBytes).toBeGreaterThan(1024)
-    const text = r.content[0].text
-    expect(text).toContain('not scanned')
-    expect(text).toContain(B)
-    expect(text).toContain(A)
-    // 未扫 id 附单独检索指引
-    expect(text).toContain(`action:"search", session:"${B}", pattern:"zzzkw"`)
-  })
 
-  it('②b 首个文件即超预算 → 0 扫描，整段未扫报告（不突破上限）', async () => {
-    const B = mainId(2)
-    await writeFatSession(B)
-    const r = await searchAcrossSessions([B], 'zzzkw', { agentDir: join(tmp, 'agent') }, {
-      byteBudget: 512,
+    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：锚可解析 ∧ 库文件存在）
     })
-    const d = r.details as CrossDetails
-    expect(d.scanned).toHaveLength(0)
-    expect(d.scannedBytes).toBe(0)
-    expect(d.skipped).toEqual([{ sessionId: B, reason: 'byte-budget', sizeBytes: expect.any(Number) }])
-    expect(r.content[0].text).toContain('not scanned')
-  })
 
-  it('③ 命中渲染：session 列表（完整 id+source+标题）+ turn 索引/角色/片段 + 可执行调用串', async () => {
-    const A = mainId(1)
-    const B = subId(1)
-    const C = mainId(2)
-    // A：T000 两命中（user+assistant）+ T001 一命中（assistant）
-    await writeSession(A, [
-      { role: 'user', text: '查询 adj_factor 的历史数据' },
-      { role: 'assistant', text: 'adj_factor 表在 dws 库' },
-      { role: 'user', text: '换一个话题' },
-      { role: 'assistant', text: '再看 adj_factor 的最新分区' },
-    ])
-    await writeSession(B, [
-      { role: 'user', text: 'subagent task 无关键词' },
-      { role: 'assistant', text: '结果里含 adj_factor 字样' },
-    ], { subagent: true })
-    await writeSession(C, [
-      { role: 'user', text: '完全没有关键词的内容' },
-    ])
-    const provider: SessionMetadataProvider = async (dir) =>
-      dir === mainDir
-        ? [{ path: join(mainDir, `${A}.jsonl`), id: A, cwd: '/demo', name: '太保寿险深度研究', modified: new Date() }]
-        : []
-    const r = await handleSessionRead(
-      { action: 'search', session: `${A},${B},${C}`, pattern: 'adj_factor' },
-      { agentDir: join(tmp, 'agent'), liveSessionDir: mainDir },
-      undefined,
-      provider,
-    )
-    const text = r.content[0].text
-    // header：命中/已扫计数 + 默认预算标注（handleSessionRead 路径走 SEARCH_SCAN_BYTE_BUDGET，
-    // formatScanBytes 的 MB 形态恒 1 位小数）
-    expect(text).toContain('2/3 session(s) hit for /adj_factor/')
-    expect(text).toContain(`${(SEARCH_SCAN_BYTE_BUDGET / (1024 * 1024)).toFixed(1)}MB budget`)
-    // 命中块：完整 id + source + 标题（provider 注入）+ 命中数，列表序 = 传入序
-    expect(text).toContain(`1. ${A} · main · 太保寿险深度研究（3 hits）`)
-    expect(text).toContain(`2. ${B} · subagent（1 hit）`)
-    // turn 索引 + entry 序号 + 角色 + 片段
-    expect(text).toContain('     T000 #0 user: ')
-    expect(text).toContain('     T000 #1 assistant: ')
-    expect(text).toContain('     T001 #1 assistant: ')
-    // 可直接执行的调用串（真实参数 = pattern）
-    expect(text).toContain(`↳ session_read { action:"search", session:"${A}", pattern:"adj_factor" }`)
-    expect(text).toContain(`↳ session_read { action:"search", session:"${B}", pattern:"adj_factor" }`)
-    // 已扫无命中段
-    expect(text).toContain('scanned, no hit:')
-    expect(text).toContain(`${C} · main`)
-    const d = r.details as CrossDetails
-    expect(d.rejected).toBeUndefined()
-    expect(d.truncated).toBe(false)
-    expect(d.degraded).toBe(false)
-    expect(d.byteBudget).toBe(SEARCH_SCAN_BYTE_BUDGET)
-    expect(d.skipped).toEqual([])
-    expect(d.scanned.map((s) => s.sessionId)).toEqual([A, B, C])
-    expect(d.scanned[0].hits).toHaveLength(3)
-    expect(d.scanned[0].name).toBe('太保寿险深度研究')
-    expect(d.scanned[1].hits).toHaveLength(1)
-    // B 只有一条 user → 单 turn，assistant 命中在 T000 #1
-    expect(d.scanned[1].hits[0]).toMatchObject({
-      turnIndex: 0,
-      entryIndex: 1,
-      role: 'assistant',
+    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`))
     })
-    expect(d.scanned[2].hits).toHaveLength(0)
-  })
 
-  it('④ 无命中形态 + not-found 报告（不在库中的 id 不中断整体）', async () => {
-    const A = mainId(1)
-    const GHOST = mainId(99)
-    await writeSession(A, [{ role: 'user', text: '普通内容' }])
-    const r = await handleSessionRead(
-      { action: 'search', session: `${A},${GHOST}`, pattern: 'zzznothing' },
-      { agentDir: join(tmp, 'agent') },
-    )
-    const text = r.content[0].text
-    expect(text).toContain('0/1 session(s) hit for /zzznothing/')
-    expect(text).toContain('scanned, no hit:')
-    expect(text).toContain(`${A} · main`)
-    expect(text).toContain('换更精确 pattern')
-    expect(text).toContain('not found in library')
-    expect(text).toContain(`- ${GHOST}`)
-    const d = r.details as CrossDetails
-    expect(d.scanned).toHaveLength(1)
-    expect(d.scanned[0].hits).toHaveLength(0)
-    expect(d.skipped).toEqual([{ sessionId: GHOST, reason: 'not-found' }])
+    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)
+    })
   })
 
-  it('⑤ 单会话语义无回归：无逗号 session 走原路径（hits 结构），pattern 含逗号不误分流', async () => {
-    const A = mainId(1)
-    await writeSession(A, [
-      { role: 'user', text: 'aaa plugin 内容' },
-      { role: 'assistant', text: 'bbb' },
-    ])
-    // 单 id：原 details.hits 结构与 header 形态不变
-    const r = await handleSessionRead(
-      { action: 'search', session: A, pattern: 'plugin' },
-      { agentDir: join(tmp, 'agent') },
-    )
-    expect(r.content[0].text).toContain('1 hit(s) for /plugin/')
-    const d = r.details as { hits: unknown[]; truncated: boolean; scanned?: unknown }
-    expect(d.hits).toHaveLength(1)
-    expect(d.truncated).toBe(false)
-    expect(d.scanned).toBeUndefined()
-    // pattern 含逗号不触发跨会话（分流只看 session）
-    const r2 = await handleSessionRead(
-      { action: 'search', session: A, pattern: 'aaa,bbb' },
-      { agentDir: join(tmp, 'agent') },
-    )
-    expect((r2.details as { hits: unknown[] }).hits).toHaveLength(0)
-    expect((r2.details as { scanned?: unknown }).scanned).toBeUndefined()
-    expect(r2.content[0].text).not.toContain('session(s) hit')
+  // ---------------------------------------------------------------------------
+  // 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')
+    })
   })
 
-  it('⑥ per-session limit 截断：超限 session 标注 >N hits，truncated=true', async () => {
-    const A = mainId(1)
-    await writeSession(A, [
-      { role: 'user', text: 'kw one' },
-      { role: 'assistant', text: 'kw two' },
-      { role: 'user', text: 'kw three' },
-    ])
-    const r = await searchAcrossSessions([A], 'kw', { agentDir: join(tmp, 'agent') }, { limit: 2 })
-    const d = r.details as CrossDetails
-    expect(d.truncated).toBe(true)
-    expect(d.scanned[0].hits).toHaveLength(2)
-    expect(d.scanned[0].hitsTotal).toBe(3)
-    expect(r.content[0].text).toContain('（>3 hits, showing first 2）')
+  // ---------------------------------------------------------------------------
+  // 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)
+    })
   })
 
-  it('⑦ abort 信号透传：跨会话扫描中断抛错（与单会话 MF-5 语义一致）', async () => {
-    const A = mainId(1)
-    await writeSession(A, [{ role: 'user', text: 'content' }])
-    const ac = new AbortController()
-    ac.abort()
-    await expect(
-      searchAcrossSessions([A], 'kw', { agentDir: join(tmp, 'agent') }, { signal: ac.signal }),
-    ).rejects.toThrow(/中断/)
+  // ---------------------------------------------------------------------------
+  // 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')
+    })
   })
-})
+});