@zhushanwen/pi-session-reader 0.10.4 → 0.12.0

package/src/__tests__/subagents.test.ts

@@ -8,7 +8,11 @@ import {
   extractSessionIdFromFilename,
   type RecordManifest,
 } from '../discovery/subagents.js'
-import { resolveSessionRoots } from '../discovery/roots.js'
+import {
+  resolveSessionRoots,
+  resolveStoreSubagentSessionsDir,
+  resolveStoreSubagentRecordsDir,
+} from '../discovery/roots.js'
 import { parseSessionHeader, readSessionHeaderFirstLine } from '../discovery/session-header.js'
 
 // ---- fixture 常量（uuid 特征，满足 extractSessionIdFromFilename + 互不为子串）----
@@ -18,10 +22,20 @@ const SUB_REAL = '0aaaaaaa-bbbb-7ccc-dddd-000000000003'
 
 // ---- fixture helpers ----
 
+/**
+ * 建 mkdtemp dataDir 根（生产拓扑复刻，[session-store-layout-inversion] 布局 B）：
+ * agentDir = `<dataDir>/agent`（调用方经 agentDirOf 推导并传入被测函数），存储树 =
+ * `<dataDir>/ext-sessions`（fixture 经 roots.ts 生产同源推导函数落盘，禁手拼树根段字面量）。
+ */
 async function makeAgentDir(): Promise<string> {
   return mkdtemp(join(tmpdir(), 'subagents-test-'))
 }
 
+/** agentDir 推导（生产拓扑：agentDir = <dataDir>/agent，session-reader 的 agentDir 语义）。 */
+function agentDirOf(dataDir: string): string {
+  return join(dataDir, 'agent')
+}
+
 /** 写主 session 文件（首行 header）。返回绝对路径（供 fork 的 parentSession 指向）。 */
 async function writeMainSession(
   dir: string,
@@ -39,21 +53,22 @@ async function writeMainSession(
 }
 
 /**
- * 写 subagent session 文件：首行 header（真实 id）+ 占位 message + 尾行 identity。
+ * 写 subagent session 文件（新布局存储树：`<root>/<rootSessionId>/subagents/sessions/`，
+ * 分区键 = identity.rootSessionId，生产同源 resolveStoreSubagentSessionsDir 推导）：
+ * 首行 header（真实 id）+ 占位 message + 尾行 identity。
  * identity 在尾行（实测 pi 行为；subagent-identity 由 session-runner 在 session 创建后写）。
  * U4 扩展：identity.task/agent 可定制（P-fallback 测试用，默认 't'/'explorer'）。
  */
 async function writeSubagentSession(
   dir: string,
-  slug: string,
- realId: string,
+  realId: string,
   identity: { rootSessionId: string; slug: string; dataId?: string; task?: string; agent?: string },
 ): Promise<string> {
-  const sessionDir = join(dir, 'subagents', slug, 'sessions')
+  const sessionDir = resolveStoreSubagentSessionsDir(dir, identity.rootSessionId)
   await mkdir(sessionDir, { recursive: true })
   const path = join(sessionDir, `${realId}.jsonl`)
   const lines = [
-    JSON.stringify({ type: 'session', id: realId, cwd: `/proj/${slug}` }),
+    JSON.stringify({ type: 'session', id: realId, cwd: `/proj/${identity.slug}` }),
     JSON.stringify({
       type: 'message',
       id: 'm1',
@@ -84,14 +99,14 @@ async function writeSubagentSession(
  */
 async function writeAliveSubagentNoIdentity(
   dir: string,
-  slug: string,
+  rootSessionId: string,
   realId: string,
 ): Promise<string> {
-  const sessionDir = join(dir, 'subagents', slug, 'sessions')
+  const sessionDir = resolveStoreSubagentSessionsDir(dir, rootSessionId)
   await mkdir(sessionDir, { recursive: true })
   const path = join(sessionDir, `${realId}.jsonl`)
   const lines = [
-    JSON.stringify({ type: 'session', id: realId, cwd: `/proj/${slug}` }),
+    JSON.stringify({ type: 'session', id: realId, cwd: '/proj/root' }),
     JSON.stringify({
       type: 'message',
       id: 'm1',
@@ -103,10 +118,13 @@ async function writeAliveSubagentNoIdentity(
   return path
 }
 
-/** 写 records manifest（孤儿源）。U4 扩展：fields 支持富字段 task/slug/model/status。 */
+/**
+ * 写 records manifest（孤儿源；新布局 `<root>/<rootSessionId>/subagents/records/`，
+ * 分区键 = fields.rootSessionId，生产同源 resolveStoreSubagentRecordsDir 推导）。
+ * U4 扩展：fields 支持富字段 task/slug/model/status。
+ */
 async function writeRecordManifest(
   dir: string,
-  slug: string,
   id: string,
   fields: {
     rootSessionId: string
@@ -118,7 +136,7 @@ async function writeRecordManifest(
     status?: string
   },
 ): Promise<void> {
-  const recordsDir = join(dir, 'subagents', slug, 'records')
+  const recordsDir = resolveStoreSubagentRecordsDir(dir, fields.rootSessionId)
   await mkdir(recordsDir, { recursive: true })
   await writeFile(join(recordsDir, `${id}.json`), JSON.stringify({ id, ...fields }))
 }
@@ -128,13 +146,15 @@ async function writeRecordManifest(
 // ============================================================
 
 describe('buildFamilyFromFs - fixture', () => {
-  let dir: string
+  let dataDir: string
+  let dir: string // agentDir = <dataDir>/agent（生产拓扑复刻，见 makeAgentDir 注释）
 
   beforeEach(async () => {
-    dir = await makeAgentDir()
+    dataDir = await makeAgentDir()
+    dir = agentDirOf(dataDir)
   })
   afterEach(async () => {
-    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+    await rm(dataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
   })
 
   it('基础 family：root + fork + 隔代 subagent，SubagentRef.sessionId 是真实 id（非 sa-xxx）', async () => {
@@ -145,7 +165,7 @@ describe('buildFamilyFromFs - fixture', () => {
       parentSession: rootPath,
     })
     // subagent 挂在 fork 子代下（rootSessionId=FORK，非 ROOT）→ 隔代
-    await writeSubagentSession(dir, '--fork-cwd--', SUB_REAL, {
+    await writeSubagentSession(dir, SUB_REAL, {
       rootSessionId: FORK,
       slug: 'test-sub',
       dataId: 'sa-placeholder-1',
@@ -174,7 +194,7 @@ describe('buildFamilyFromFs - fixture', () => {
   it('从 fork 子代 resolve 也能关联到挂在其下的 subagent', async () => {
     const rootPath = await writeMainSession(dir, '--root-cwd--', ROOT)
     await writeMainSession(dir, '--fork-cwd--', FORK, { parentSession: rootPath })
-    await writeSubagentSession(dir, '--fork-cwd--', SUB_REAL, { rootSessionId: FORK, slug: 's' })
+    await writeSubagentSession(dir, SUB_REAL, { rootSessionId: FORK, slug: 's' })
 
     const family = await buildFamilyFromFs(FORK, dir)
     expect(family.subagents.some((s) => s.sessionId === SUB_REAL)).toBe(true)
@@ -183,7 +203,7 @@ describe('buildFamilyFromFs - fixture', () => {
   it('cleanedUp：manifest 孤儿（.jsonl 不存在）→ cleanedUp=true', async () => {
     await writeMainSession(dir, '--root-cwd--', ROOT, { cwd: '/proj/root' })
     // 孤儿 manifest：rootSessionId=ROOT，sessionFile 指向不存在路径（模拟 .jsonl 被 GC）
-    await writeRecordManifest(dir, '--root-cwd--', 'sa-ghost-id', {
+    await writeRecordManifest(dir, 'sa-ghost-id', {
       rootSessionId: ROOT,
       agentName: 'explorer',
       sessionFile: '/nonexistent/ghost.jsonl',
@@ -203,12 +223,12 @@ describe('buildFamilyFromFs - fixture', () => {
   it('alive subagent 同时有 manifest → 不重复计数（manifest 跳过 alive）', async () => {
     const rootPath = await writeMainSession(dir, '--root-cwd--', ROOT)
     await writeMainSession(dir, '--fork-cwd--', FORK, { parentSession: rootPath })
-    const subPath = await writeSubagentSession(dir, '--fork-cwd--', SUB_REAL, {
+    const subPath = await writeSubagentSession(dir, SUB_REAL, {
       rootSessionId: FORK,
       slug: 'dup-test',
     })
     // manifest 指向真实文件路径（alive）→ 应被跳过，不产生孤儿副本
-    await writeRecordManifest(dir, '--fork-cwd--', `sa-${SUB_REAL}`, {
+    await writeRecordManifest(dir, `sa-${SUB_REAL}`, {
       rootSessionId: FORK,
       agentName: 'explorer',
       sessionFile: subPath,
@@ -231,16 +251,14 @@ describe('buildFamilyFromFs - fixture', () => {
   it('workflows：v2 注册条目 record 流直读提 calls；命中 pathToRef 取完整 ref，GC\'d 路径回退最小 ref', async () => {
     await writeMainSession(dir, '--root-cwd--', ROOT, { cwd: '/proj/root' })
     // 真实存在的 subagent（步骤 2 扫到 → pathToRef 命中 → 完整 SessionRef）
-    const subPath = await writeSubagentSession(dir, '--root-cwd--', SUB_REAL, {
+    const subPath = await writeSubagentSession(dir, SUB_REAL, {
       rootSessionId: ROOT,
       slug: 'wf-sub',
     })
-    // GC'd 路径（文件不存在 → pathToRef 未命中 → sessionRefFromPath 最小 ref）
+    // GC'd 路径（文件不存在 → pathToRef 未命中 → sessionRefFromPath 最小 ref）；
+    // 新布局 subagent 会话路径形态（存储树分区，生产同源推导）
     const gced = join(
-      dir,
-      'subagents',
-      '--root-cwd--',
-      'sessions',
+      resolveStoreSubagentSessionsDir(dir, ROOT),
       '2026-08-07T16-49-48-393Z_019fdd21-8169-7a02-8f11-eef6c9ca11cc.jsonl',
     )
     // record 流：agent-settled 帧携带 result.sessionFile（两 call：命中 + GC 各一）
@@ -286,7 +304,7 @@ describe('buildFamilyFromFs - fixture', () => {
     expect(wf.calls[0].sessionId).toBe(SUB_REAL)
     expect(wf.calls[0].mtime).toBeGreaterThan(0)
     expect(wf.calls[0].sizeBytes).toBeGreaterThan(0)
-    expect(wf.calls[0].cwd).toBe('/proj/--root-cwd--')
+    expect(wf.calls[0].cwd).toBe('/proj/wf-sub') // cwd 从 subagent 文件首行 header 透传（fixture header.cwd = /proj/<identity.slug>）
     // GC'd 未命中：fileName-only 最小 ref（sessionId 从文件名提取，mtime/size/cwd 占位）
     expect(wf.calls[1].fileName).toBe(gced)
     expect(wf.calls[1].sessionId).toBe('019fdd21-8169-7a02-8f11-eef6c9ca11cc')
@@ -298,14 +316,14 @@ describe('buildFamilyFromFs - fixture', () => {
   it('MF-3 回归：alive 但无 identity 的 subagent（运行中）不被收编为 cleanedUp——U4 后 manifest 主路径建族', async () => {
     await writeMainSession(dir, '--root-cwd--', ROOT, { cwd: '/proj/root' })
     // 运行中 subagent：有效 header、无 identity 尾行（identity 完成时才写入），manifest 已存在
-    const subDir = join(dir, 'subagents', '--root-cwd--', 'sessions')
+    const subDir = resolveStoreSubagentSessionsDir(dir, ROOT)
     await mkdir(subDir, { recursive: true })
     const subPath = join(subDir, SUB_REAL + '.jsonl')
     await writeFile(
       subPath,
       JSON.stringify({ type: 'session', id: SUB_REAL, cwd: '/proj/root' }) + '\n',
     )
-    await writeRecordManifest(dir, '--root-cwd--', `sa-${SUB_REAL}`, {
+    await writeRecordManifest(dir, `sa-${SUB_REAL}`, {
       rootSessionId: ROOT,
       agentName: 'explorer',
       sessionFile: subPath,
@@ -332,17 +350,19 @@ describe('buildFamilyFromFs - fixture', () => {
 // ============================================================
 
 describe('listRecordManifests 导出（w2 TC1）', () => {
-  let dir: string
+  let dataDir: string
+  let dir: string // agentDir = <dataDir>/agent（生产拓扑复刻，见 makeAgentDir 注释）
 
   beforeEach(async () => {
-    dir = await makeAgentDir()
+    dataDir = await makeAgentDir()
+    dir = agentDirOf(dataDir)
   })
   afterEach(async () => {
-    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+    await rm(dataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
   })
 
   it('导出生效：import + 调用返回 RecordManifest[]，字段完整', async () => {
-    await writeRecordManifest(dir, '--demo-cwd--', 'sa-tc1', {
+    await writeRecordManifest(dir, 'sa-tc1', {
       rootSessionId: 'root-1',
       agentName: 'explorer',
       sessionFile: '/tmp/sa-tc1.jsonl',
@@ -355,6 +375,38 @@ describe('listRecordManifests 导出（w2 TC1）', () => {
     expect(m.agentName).toBe('explorer')
     expect(m.sessionFile).toBe('/tmp/sa-tc1.jsonl')
   })
+
+  it('D6 单新根锚定：旧布局 <agentDir>/subagents 造 record + 新根不造 → 不返回（存量不可见，防回归双根扫描）', async () => {
+    // 旧布局存量原位保留（D6 裁决：不迁移、不再读写）——旧根造一份合法 manifest
+    const legacyRecordsDir = join(dir, 'subagents', '--legacy-cwd--', 'records')
+    await mkdir(legacyRecordsDir, { recursive: true })
+    await writeFile(
+      join(legacyRecordsDir, 'sa-legacy.json'),
+      JSON.stringify({ id: 'sa-legacy', rootSessionId: 'root-legacy', sessionFile: '/nonexistent/legacy.jsonl' }),
+    )
+    // 单新根语义：旧根 manifest 不进结果集（result/find 面旧记录不可见是 D6 取舍清单明示项）
+    expect(await listRecordManifests(dir)).toHaveLength(0)
+  })
+
+  it('D6 单新根锚定：非会话分区目录（isPiSessionId 不过）剪枝跳过，合法分区正常读', async () => {
+    const { resolveSessionStoreRoot } = await import('../discovery/roots.js')
+    const storeRoot = resolveSessionStoreRoot(dir)
+    // 非法分区名（前导 - 违反 isPiSessionId 首字符规则）下的 records 不扫
+    const bogus = join(storeRoot, '-bogus-partition', 'subagents', 'records')
+    await mkdir(bogus, { recursive: true })
+    await writeFile(
+      join(bogus, 'sa-bogus.json'),
+      JSON.stringify({ id: 'sa-bogus', rootSessionId: '-bogus-partition', sessionFile: '/nonexistent/b.jsonl' }),
+    )
+    // 合法分区在场
+    await writeRecordManifest(dir, 'sa-ok', {
+      rootSessionId: 'root-ok',
+      agentName: 'explorer',
+      sessionFile: '/tmp/sa-ok.jsonl',
+    })
+    const manifests = await listRecordManifests(dir)
+    expect(manifests.map((m) => m.id)).toEqual(['sa-ok'])
+  })
 })
 
 // ============================================================
@@ -363,25 +415,27 @@ describe('listRecordManifests 导出（w2 TC1）', () => {
 // ============================================================
 
 describe('U4 buildFamilyFromFs 富化（manifest 主 / P-fallback）', () => {
-  let dir: string
+  let dataDir: string
+  let dir: string // agentDir = <dataDir>/agent（生产拓扑复刻，见 makeAgentDir 注释）
 
   beforeEach(async () => {
-    dir = await makeAgentDir()
+    dataDir = await makeAgentDir()
+    dir = agentDirOf(dataDir)
   })
   afterEach(async () => {
-    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+    await rm(dataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
   })
 
   it('TC-u4-manifest-enrich: alive + manifest 全字段 → SubagentRef 富字段全透传', async () => {
     await writeMainSession(dir, '--root-cwd--', ROOT, { cwd: '/proj/root' })
-    const subPath = await writeSubagentSession(dir, '--root-cwd--', SUB_REAL, {
+    const subPath = await writeSubagentSession(dir, SUB_REAL, {
       rootSessionId: ROOT,
       slug: 'identity-slug', // identity.slug，manifest 主时被 manifest.slug 覆盖
       task: 'identity-task', // identity.task，manifest 主时被 manifest.task 覆盖
       agent: 'worker', // identity.agent，manifest 主时被 manifest.agentName 覆盖
     })
     // manifest 全字段（命中 meta.path 索引 → 走 manifest 主路径，覆盖 identity 值）
-    await writeRecordManifest(dir, '--root-cwd--', `sa-${SUB_REAL}`, {
+    await writeRecordManifest(dir, `sa-${SUB_REAL}`, {
       rootSessionId: ROOT,
       agentName: 'explorer',
       sessionFile: subPath,
@@ -409,7 +463,7 @@ describe('U4 buildFamilyFromFs 富化（manifest 主 / P-fallback）', () => {
   it('TC-u4-pfallback-identity: alive 无 manifest + identity 含 task/agent → 回退 identity，model/status undefined', async () => {
     await writeMainSession(dir, '--root-cwd--', ROOT, { cwd: '/proj/root' })
     // 只写 alive session（含 identity 尾行），不写 manifest → P-fallback 路径
-    const subPath = await writeSubagentSession(dir, '--root-cwd--', SUB_REAL, {
+    const subPath = await writeSubagentSession(dir, SUB_REAL, {
       rootSessionId: ROOT,
       slug: 'fix',
       task: 'fix bug',
@@ -434,7 +488,7 @@ describe('U4 buildFamilyFromFs 富化（manifest 主 / P-fallback）', () => {
   it('TC-u4-pfallback-no-identity: alive 无 manifest 无 identity（运行中）→ 不入 family.subagents，不抛错', async () => {
     await writeMainSession(dir, '--root-cwd--', ROOT, { cwd: '/proj/root' })
     // alive 文件无 identity 尾行（运行中/异常），无 manifest
-    await writeAliveSubagentNoIdentity(dir, '--root-cwd--', SUB_REAL)
+    await writeAliveSubagentNoIdentity(dir, ROOT, SUB_REAL)
 
     // 核心断言：buildFamilyFromFs 不抛错、不崩溃
     const family = await buildFamilyFromFs(ROOT, dir)
@@ -447,7 +501,7 @@ describe('U4 buildFamilyFromFs 富化（manifest 主 / P-fallback）', () => {
   it('TC-u4-orphan-manifest: manifest 全字段 + sessionFile 指向不存在路径 → 孤儿 cleanedUp=true，富字段透传', async () => {
     await writeMainSession(dir, '--root-cwd--', ROOT, { cwd: '/proj/root' })
     const ghostPath = '/nonexistent/gc-ghost.jsonl' // .jsonl 已被 GC（不写该文件）
-    await writeRecordManifest(dir, '--root-cwd--', 'sa-ghost-id', {
+    await writeRecordManifest(dir, 'sa-ghost-id', {
       rootSessionId: ROOT,
       agentName: 'worker',
       sessionFile: ghostPath,
@@ -475,7 +529,7 @@ describe('U4 buildFamilyFromFs 富化（manifest 主 / P-fallback）', () => {
   it('TC-u4-recordmanifest-compat: 旧 manifest（仅 id/rootSessionId/sessionFile）→ 富字段 undefined，不抛错', async () => {
     await writeMainSession(dir, '--root-cwd--', ROOT, { cwd: '/proj/root' })
     // 旧格式 manifest：无 task/slug/model/status/agentName
-    await writeRecordManifest(dir, '--root-cwd--', 'sa-old', {
+    await writeRecordManifest(dir, 'sa-old', {
       rootSessionId: ROOT,
       sessionFile: '/nonexistent/old.jsonl',
     })
@@ -518,18 +572,20 @@ describe('U4 buildFamilyFromFs 富化（manifest 主 / P-fallback）', () => {
 //    扫描器即可与该文件族共存）。
 
 describe('.events 文件族结构性忽略（W1 D3 / 检查点④）', () => {
-  let dir: string
+  let dataDir: string
+  let dir: string // agentDir = <dataDir>/agent（生产拓扑复刻，见 makeAgentDir 注释）
 
   beforeEach(async () => {
-    dir = await makeAgentDir()
+    dataDir = await makeAgentDir()
+    dir = agentDirOf(dataDir)
   })
   afterEach(async () => {
-    await rm(dir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+    await rm(dataDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
   })
 
   /** 写 record 事件文件（首行头行 + 事件行集，形态对齐写侧 record-events.ts）。 */
-  async function writeEventsFile(slug: string, saId: string): Promise<string> {
-    const recordsDir = join(dir, 'subagents', slug, 'records')
+  async function writeEventsFile(saId: string): Promise<string> {
+    const recordsDir = resolveStoreSubagentRecordsDir(dir, ROOT)
     await mkdir(recordsDir, { recursive: true })
     const path = join(recordsDir, `${saId}.events`)
     const lines = [
@@ -543,11 +599,11 @@ describe('.events 文件族结构性忽略（W1 D3 / 检查点④）', () => {
 
   it('subagent 树扫描不收 .events：resolveSessionRoots 的 subagent 根 files 含 .jsonl 不含 .events', async () => {
     await writeMainSession(dir, '--root-cwd--', ROOT, { cwd: '/proj/root' })
-    const subPath = await writeSubagentSession(dir, '--root-cwd--', SUB_REAL, {
+    const subPath = await writeSubagentSession(dir, SUB_REAL, {
       rootSessionId: ROOT,
       slug: 'ev-sibling',
     })
-    await writeEventsFile('--root-cwd--', 'sa-ev-1')
+    await writeEventsFile('sa-ev-1')
 
     const roots = await resolveSessionRoots({ agentDir: dir })
     const subRoot = roots.find((r) => r.kind === 'subagent')
@@ -558,7 +614,7 @@ describe('.events 文件族结构性忽略（W1 D3 / 检查点④）', () => {
   })
 
   it('首行头行命中非 session header 即忽略：record-journal 头行 → parseSessionHeader 返回 null', async () => {
-    const eventsPath = await writeEventsFile('--root-cwd--', 'sa-ev-1')
+    const eventsPath = await writeEventsFile('sa-ev-1')
     // 检查点④形态：session-reader 对未知文件读首行判 header，非 session 行 → null
     //（即使未来通配规则把 .events 收进候选集，该文件也不会被误认成 session）
     const firstLine = await readSessionHeaderFirstLine(eventsPath)
@@ -568,11 +624,11 @@ describe('.events 文件族结构性忽略（W1 D3 / 检查点④）', () => {
 
   it('家族扫描：.events 与正常 subagent 同目录共存 → 家族正常、不产幻影 subagent 节点', async () => {
     await writeMainSession(dir, '--root-cwd--', ROOT, { cwd: '/proj/root' })
-    await writeSubagentSession(dir, '--root-cwd--', SUB_REAL, {
+    await writeSubagentSession(dir, SUB_REAL, {
       rootSessionId: ROOT,
       slug: 'ev-coexist',
     })
-    await writeEventsFile('--root-cwd--', 'sa-ev-1')
+    await writeEventsFile('sa-ev-1')
 
     const family = await buildFamilyFromFs(ROOT, dir)
 

package/src/__tests__/summary.test.ts

@@ -0,0 +1,223 @@
+import type { Theme } from '@earendil-works/pi-coding-agent'
+import { describe, expect, it } from 'vitest'
+
+import type { SessionReadParams, ToolResult } from '../tool-handler.js'
+import { buildSessionReadSummary, withResultSummary } from '../summary.js'
+import { renderSessionReadResult } from '../tui/tool-render.js'
+
+// ---- fixtures ----
+
+function params(overrides: Partial<SessionReadParams> & { action: SessionReadParams['action'] }): SessionReadParams {
+  return overrides as SessionReadParams
+}
+
+function toolResult(details: unknown, text = 'body text'): ToolResult {
+  return { content: [{ type: 'text', text }], details }
+}
+
+// ---- buildSessionReadSummary ----
+
+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 truncated = toolResult({ matches: [{}], truncated: true })
+    expect(buildSessionReadSummary(params({ action: 'find', query: 'login' }), truncated)).toBe(
+      'Found 1 sessions matching "login" (truncated)',
+    )
+  })
+
+  it('find 零匹配 → No sessions matching', () => {
+    const r = toolResult({ matches: [], truncated: false })
+    expect(buildSessionReadSummary(params({ action: 'find', query: 'gone' }), r)).toBe(
+      'No sessions matching "gone"',
+    )
+  })
+
+  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',
+    )
+  })
+
+  it('family flat → N relations（parents/forks/subagents/workflows 合计）', () => {
+    const family = {
+      root: { sessionId: 's1' },
+      parents: [{}],
+      forks: [{}, {}],
+      subagents: [{}],
+      workflows: [],
+    }
+    const r = toolResult(family)
+    expect(buildSessionReadSummary(params({ action: 'family', session: 's1' }), r)).toBe(
+      'Family of session s1: 4 relations',
+    )
+  })
+
+  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',
+    )
+  })
+
+  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('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',
+    )
+  })
+
+  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',
+    )
+  })
+
+  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"',
+    )
+  })
+
+  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',
+    )
+  })
+
+  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)',
+    )
+  })
+
+  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')
+  })
+
+  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)',
+    )
+  })
+
+  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',
+    )
+  })
+
+  it('doctor → roots 计数', () => {
+    const r = toolResult({ environment: {}, roots: [{ kind: 'default' }, { kind: 'legacy' }] })
+    expect(buildSessionReadSummary(params({ action: 'doctor' }), r)).toBe(
+      'Doctor: 2 roots checked',
+    )
+  })
+
+  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')
+  })
+})
+
+// ---- withResultSummary ----
+
+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"' })
+  })
+})
+
+// ---- 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('展开态 → content 纯文本（多行完整）', () => {
+    const r = toolResult({ matches: [] }, 'line1\nline2')
+    expect(renderedText(r, true)).toBe('line1\nline2')
+  })
+
+  it('无 summary（旧 entry）→ 折叠态回退 content 首行', () => {
+    const r = toolResult({}, 'Header line\ndetail body')
+    expect(renderedText(r, false)).toBe('Header line')
+  })
+})