@zhushanwen/pi-session-reader 0.2.3 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-session-reader",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "type": "module",
   "main": "index.ts",
   "xyz-agent": {
@@ -25,9 +25,9 @@
     "vitest.config.ts"
   ],
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.84.1",
-    "@earendil-works/pi-ai": "^0.84.1",
-    "@earendil-works/pi-tui": "^0.84.1",
+    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "@earendil-works/pi-ai": "^0.84.4",
+    "@earendil-works/pi-tui": "^0.84.4",
     "typebox": "*"
   },
   "peerDependenciesMeta": {

package/src/__tests__/render.test.ts

@@ -93,7 +93,7 @@ describe('renderOutline', () => {
   })
 
   it('2a. 降级：单行 toolSummary 过长超 perTurnBudget → 砍 toolSummary，保 userBrief 骨架', () => {
-    // L1 行不含 assistantBrief（design §3.5 算法1 step2）；budget=40, 3 turns → perTurnCharBudget≈53
+    // 预算紧张降级后 L1 行不含 assistantBrief（预算充足 level 0 行含）；budget=40, 3 turns → perTurnCharBudget≈53
     // 行 = head + userBrief(10) + toolSummary(20 个工具名≈63 chars) → ~80 > 53 → 砍 toolSummary
     const toolCalls = Array.from({ length: 20 }, (_, k) => ({ name: `t${String(k).padStart(2, '0')}` }))
     const turns = [0, 1, 2].map((i) =>
@@ -183,7 +183,7 @@ describe('renderOutline', () => {
     // stats 完整性
     expect(result.stats.totalTurns).toBe(32)
     // totalEntries 近似（leaf+branch+orphan）不含 session header（segmentTurns 规则1 跳过）；
-    // 准确值由 M2 工具层用 ParseResult.totalEntries 覆盖。M1 验量级。
+    // 工具层仅覆盖 stats.totalBytes 与 skippedLines（ParseResult 无 totalEntries 字段）。M1 验量级。
     expect(result.stats.totalEntries).toBeGreaterThan(1000)
     // 5.6MB 全量解析在并发/高负载下可能超 vitest 默认 5s，显式放宽
   }, 60000)

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

@@ -22,7 +22,7 @@ import {
  * 测试框架 vitest（禁止 node:test/tsx）。直接调 handleSessionRead（纯逻辑，agentDir 注入），
  * 传真实 `/Users/zhushanwen/.pi/agent` 作 agentDir——用本机真实历史 session 数据，无需 mock。
  *
- * 覆盖 7 action 主路径 + F1(find 零匹配)/F4(turn 越界)/F5(缺参)/resolveSessionId 片段等价。
+ * 覆盖 9 action 主路径 + F1(find 零匹配)/F4(turn 越界)/F5(缺参)/resolveSessionId 片段等价。
  *
  * 真实数据用例全部带 skipIf 守卫（CI 无本机 ~/.pi/agent → skip，不硬失败）；
  * renderExtractItems F9 截断是纯 fixture，无条件跑。
@@ -782,7 +782,7 @@ describe('resolveSessionId ② sa-id 形态（w2 TC7-TC10 + CQ3）', () => {
       await handleSessionRead({ action: 'outline', session: 'sa-nonexist-9999' }, dir)
     } catch (e) {
       const msg = (e as Error).message
-      expect(msg).toContain('可能仍在运行')
+      expect(msg).toContain('可能尚未落盘')
       expect(msg).toContain('action:"family"')
       expect(msg).toContain('👉')
     }

package/src/core/execution-tree.ts

@@ -173,7 +173,6 @@ function collectRelatedRecords(
 // buildExecutionTree（IF3 核心）
 // ============================================================
 
-/** 建树过程的共享可变状态（避免递归函数参数爆炸，封装为 context）。 */
 /** 建树过程的共享可变状态（避免递归函数参数爆炸，封装为 context）。 */
 interface BuildContext {
   rootSessionId: string

package/src/core/family.ts

@@ -11,7 +11,7 @@ import type { Entry } from './parser.js'
  * - SessionRef.mtime/sizeBytes：从 fileStats 取（M1 key=sessionId），取不到为 0
  * - SubagentRef.sessionId：identity entry 不含 subagent session 的 id → 占位用 entry.id
  * - SubagentRef.cwd：identity entry（custom 类型）无 cwd → 占位空串
- * - fileStats 的 key：M1 用 sessionId（M2 改用真实文件路径），cleanedUp 逻辑 M1/M2 通用
+ * - fileStats 的 key：sessionId（M2 实现沿用此 key，cleanedUp 按 sessionId 命中），逻辑通用
  *
  * 隔代关联规则（design §3.3 D-7 Q1）见 resolveFamily 注释。
  */
@@ -24,7 +24,6 @@ export interface SessionRef {
   cwd: string
   /** fork 文件指向来源的路径（来自 header 的 parentSession，原始文件路径字符串） */
   parentSession?: string
-  name?: string
 }
 
 export interface SubagentRef extends SessionRef {
@@ -194,7 +193,7 @@ export function buildFamilyIndex(
       mtime: stat?.mtime ?? 0,
       sizeBytes: stat?.size ?? 0,
       cwd: '', // identity entry 无 cwd；M2 从 subagent 文件 header 补
-      // M1: fileStats key=sessionId；M2 改用 subagent 真实文件路径（SubagentRef.fileName）查 fileStats
+      // fileStats key=sessionId（buildFamilyFromFs 以 header.id 写入），cleanedUp 按 sessionId 命中
       cleanedUp: !fileStats.has(ident.id),
       // U4 富字段：从 identity data 读（manifest 主/P-fallback 由 buildFamilyFromFs 组装时决定）
       task: ident.data.task,

package/src/core/render.ts

@@ -3,6 +3,35 @@ import { extractToolCalls, formatToolCallSummary, type ToolCallInfo } from './to
 import type { Turn } from './turns.js'
 import type { TreeView } from './tree.js'
 
+// ---------------------------------------------------------------------------
+// 模块常量（渲染口径：截断宽度 / 换算基数 / 降级档位）
+// ---------------------------------------------------------------------------
+
+/** bytes→KB 换算基数（omitted 字节 / read 结果规模的 KB 显示）。 */
+const BYTES_PER_KB = 1024
+/** userBrief 截断字符数（TurnBrief.userBrief 文档口径「截 60 字符」）。 */
+const USER_BRIEF_MAX_CHARS = 60
+/** assistantBrief 截断字符数（TurnBrief.assistantBrief 文档口径「截 80 字符」）。 */
+const ASSISTANT_BRIEF_MAX_CHARS = 80
+/** L2 expand 单 entry brief 截断字符数。 */
+const ENTRY_BRIEF_MAX_CHARS = 100
+/** turn 索引显示宽度（T013 三位补零）。 */
+const TURN_INDEX_WIDTH = 3
+/** outline 默认 token 预算（OutlineOptions.budget 缺省值）。 */
+const OUTLINE_DEFAULT_BUDGET_TOKENS = 2000
+/** token 估算换算基数（chars/4，与 tokenEstimate 口径一致）。 */
+const CHARS_PER_TOKEN = 4
+/** toolResult 摘要头行数（O3 摘要态展示前 N 行）。 */
+const SUMMARY_HEAD_LINE_COUNT = 3
+/** toolResult 摘要单头行截断字符数。 */
+const SUMMARY_HEAD_LINE_MAX_CHARS = 80
+
+/** 行渲染降级档位（design §3.5 算法 1 step3）：0=全有 / 1=砍 assistantBrief / 2=再砍 toolSummary（骨架）。 */
+const LINE_LEVEL_FULL = 0
+const LINE_LEVEL_NO_ASSISTANT = 1
+const LINE_LEVEL_SKELETON = 2
+type LineLevel = typeof LINE_LEVEL_FULL | typeof LINE_LEVEL_NO_ASSISTANT | typeof LINE_LEVEL_SKELETON
+
 /**
  * L1 outline 的单行 turn 摘要（design §3.5 算法 1 的渲染单元，冻结接口）。
  *
@@ -163,7 +192,7 @@ function formatToolResultSummary(
   }
   if (toolName === 'read') {
     if (resultText === '') return base
-    const kb = Math.max(1, Math.round(utf8Bytes(resultText) / 1024))
+    const kb = Math.max(1, Math.round(utf8Bytes(resultText) / BYTES_PER_KB))
     return `${base} (${kb}KB)`
   }
   return base
@@ -216,7 +245,7 @@ function computeBrief(turn: Turn): TurnBrief {
   if (turn.isCompaction) {
     const first = turn.entries[0]
     const summaryStr = typeof first?.summary === 'string' ? first.summary : ''
-    userBrief = truncate('[compaction] ' + summaryStr, 60)
+    userBrief = truncate('[compaction] ' + summaryStr, USER_BRIEF_MAX_CHARS)
   } else {
     let userText = ''
     for (const entry of turn.entries) {
@@ -225,7 +254,7 @@ function computeBrief(turn: Turn): TurnBrief {
         userText += extractText(msg.content)
       }
     }
-    userBrief = truncate(userText, 60)
+    userBrief = truncate(userText, USER_BRIEF_MAX_CHARS)
   }
 
   return {
@@ -233,7 +262,7 @@ function computeBrief(turn: Turn): TurnBrief {
     startTime: turn.startTime,
     userBrief,
     toolSummary: formatToolSummary(toolCounts),
-    assistantBrief: truncate(assistantText, 80),
+    assistantBrief: truncate(assistantText, ASSISTANT_BRIEF_MAX_CHARS),
     omittedBytes: omitted,
   }
 }
@@ -256,10 +285,10 @@ function formatHHMM(timestamp?: string): string {
   return m ? `${m[1]}:${m[2]}` : ''
 }
 
-function formatBytesMarker(bytes: number): string {
+export function formatBytesMarker(bytes: number): string {
   if (bytes <= 0) return ''
-  if (bytes < 1024) return `[${bytes}B omitted]`
-  return `[${Math.round(bytes / 1024)}KB omitted]`
+  if (bytes < BYTES_PER_KB) return `[${bytes}B omitted]`
+  return `[${Math.round(bytes / BYTES_PER_KB)}KB omitted]`
 }
 
 /**
@@ -268,14 +297,14 @@ function formatBytesMarker(bytes: number): string {
  * level: 0=全有（toolSummary + assistantBrief）/ 1=砍 assistantBrief / 2=再砍 toolSummary（骨架）。
  * userBrief + omittedBytes 骨架永保。assistantBrief 格式 `→ <结论>`，在 toolSummary 后、omitted 前。
  */
-function formatLine(b: TurnBrief, level: 0 | 1 | 2, branchSize?: number): string {
+function formatLine(b: TurnBrief, level: LineLevel, branchSize?: number): string {
   const parts: string[] = []
-  const head = `T${String(b.index).padStart(3, '0')}`
+  const head = `T${String(b.index).padStart(TURN_INDEX_WIDTH, '0')}`
   const time = formatHHMM(b.startTime)
   parts.push(time ? `${head} ${time}` : head)
   if (b.userBrief) parts.push(b.userBrief)
-  if (level <= 1 && b.toolSummary) parts.push(b.toolSummary)
-  if (level <= 0 && b.assistantBrief) parts.push(`→ ${b.assistantBrief}`)
+  if (level <= LINE_LEVEL_NO_ASSISTANT && b.toolSummary) parts.push(b.toolSummary)
+  if (level <= LINE_LEVEL_FULL && b.assistantBrief) parts.push(`→ ${b.assistantBrief}`)
   const marker = formatBytesMarker(b.omittedBytes)
   if (marker) parts.push(marker)
   if (branchSize !== undefined && branchSize > 0) parts.push(`[旁支 ${branchSize} entries]`)
@@ -306,7 +335,7 @@ export function renderOutline(
   tree: TreeView,
   options?: OutlineOptions,
 ): OutlineResult {
-  const budget = options?.budget ?? 2000
+  const budget = options?.budget ?? OUTLINE_DEFAULT_BUDGET_TOKENS
   const allBranches = options?.allBranches ?? false
   const granularity = options?.granularity ?? 'turn'
 
@@ -344,20 +373,20 @@ export function renderOutline(
   }
 
   // 2. perTurnBudget（token → chars×4）
-  const perTurnCharBudget = (budget / turns.length) * 4
+  const perTurnCharBudget = (budget / turns.length) * CHARS_PER_TOKEN
 
   // 3. 降级序：level 0 全有；超预算降到 level 1 砍 assistantBrief；仍超降到 level 2 砍 toolSummary（骨架）。design §3.5 算法 1 step3
   const lineCache: string[] = []
   for (const b of briefs) {
     const branchSize = b.branch !== undefined ? tree.branches.get(b.branch) : undefined
-    let line = formatLine(b, 0, branchSize)
+    let line = formatLine(b, LINE_LEVEL_FULL, branchSize)
     if (line.length > perTurnCharBudget) {
       // 超预算：先砍 assistantBrief（level 1），仍超再砍 toolSummary（level 2，骨架）
       b.assistantBrief = ''
-      line = formatLine(b, 1, branchSize)
+      line = formatLine(b, LINE_LEVEL_NO_ASSISTANT, branchSize)
       if (line.length > perTurnCharBudget) {
         b.toolSummary = ''
-        line = formatLine(b, 2, branchSize)
+        line = formatLine(b, LINE_LEVEL_SKELETON, branchSize)
       }
     }
     lineCache.push(line)
@@ -366,9 +395,9 @@ export function renderOutline(
   // 4. 总预算截断（从尾部丢弃）
   let totalChars = lineCache.reduce((s, l) => s + l.length, 0)
   let truncated: number | undefined
-  if (totalChars / 4 > budget) {
+  if (totalChars / CHARS_PER_TOKEN > budget) {
     let kept = lineCache.length
-    while (kept > 0 && totalChars / 4 > budget) {
+    while (kept > 0 && totalChars / CHARS_PER_TOKEN > budget) {
       kept--
       totalChars -= lineCache[kept].length
     }
@@ -377,7 +406,7 @@ export function renderOutline(
     briefs.length = kept
   }
 
-  const tokenEstimate = Math.ceil(totalChars / 4)
+  const tokenEstimate = Math.ceil(totalChars / CHARS_PER_TOKEN)
   return { turns: briefs, stats, tokenEstimate, truncated }
 }
 
@@ -405,7 +434,7 @@ function renderEntryGranularity(
       const b: TurnBrief = {
         index: entryIdx++,
         startTime: e.timestamp,
-        userBrief: truncate(text, 60) || `[${e.type}]`,
+        userBrief: truncate(text, USER_BRIEF_MAX_CHARS) || `[${e.type}]`,
         toolSummary: formatToolSummary(counts),
         assistantBrief: '',
         omittedBytes: entryOmittedBytes(e),
@@ -416,13 +445,13 @@ function renderEntryGranularity(
   }
 
   const lines = briefs.map((b) =>
-    formatLine(b, 0, b.branch !== undefined ? tree.branches.get(b.branch) : undefined),
+    formatLine(b, LINE_LEVEL_FULL, b.branch !== undefined ? tree.branches.get(b.branch) : undefined),
   )
   let totalChars = lines.reduce((s, l) => s + l.length, 0)
   let truncated: number | undefined
-  if (totalChars / 4 > budget) {
+  if (totalChars / CHARS_PER_TOKEN > budget) {
     let kept = lines.length
-    while (kept > 0 && totalChars / 4 > budget) {
+    while (kept > 0 && totalChars / CHARS_PER_TOKEN > budget) {
       kept--
       totalChars -= lines[kept].length
     }
@@ -433,7 +462,7 @@ function renderEntryGranularity(
   return {
     turns: briefs,
     stats,
-    tokenEstimate: Math.ceil(totalChars / 4),
+    tokenEstimate: Math.ceil(totalChars / CHARS_PER_TOKEN),
     truncated,
   }
 }
@@ -459,7 +488,7 @@ function entryBrief(e: Entry, tcMap?: Map<string, ToolCallInfo>): string {
   const msg = e.message
   if (msg !== undefined) {
     if (msg.role === 'user' || msg.role === 'assistant') {
-      return truncate(extractText(msg.content), 100) || `[${msg.role}]`
+      return truncate(extractText(msg.content), ENTRY_BRIEF_MAX_CHARS) || `[${msg.role}]`
     }
     if (msg.role === 'toolResult') {
       const toolCallId = msg.toolCallId
@@ -469,7 +498,7 @@ function entryBrief(e: Entry, tcMap?: Map<string, ToolCallInfo>): string {
   }
   if (e.type === 'compaction') {
     const s = typeof e.summary === 'string' ? e.summary : '[compaction]'
-    return truncate(s, 100)
+    return truncate(s, ENTRY_BRIEF_MAX_CHARS)
   }
   if (e.type === 'custom') return `[custom:${e.customType ?? 'unknown'}]`
   return `[${e.type}]`
@@ -479,7 +508,7 @@ export function renderExpand(turn: Turn): {
   turn: string
   entries: EntryBrief[]
 } {
-  const head = `T${String(turn.index).padStart(3, '0')}`
+  const head = `T${String(turn.index).padStart(TURN_INDEX_WIDTH, '0')}`
   const bits = [`${turn.entries.length} entries`]
   if (turn.startTime !== undefined) bits.push(`started ${formatHHMM(turn.startTime)}`)
   if (turn.isCompaction) bits.push('compaction')
@@ -559,7 +588,7 @@ export function renderDetail(
           // 空文本口径与 formatToolResultSummary 一致：空结果 = 0 行
           //（''.split('\n') 返 [''] length=1，会与 summary 的 (0行) 自相矛盾）
           const lines = text === '' ? [] : text.split('\n')
-          const headLines = lines.slice(0, 3).map((l) => truncate(l, 80)).join(' | ')
+          const headLines = lines.slice(0, SUMMARY_HEAD_LINE_COUNT).map((l) => truncate(l, SUMMARY_HEAD_LINE_MAX_CHARS)).join(' | ')
           out.push({
             type: 'toolResultSummary',
             id: e.id,

package/src/core/toolcall.ts

@@ -10,6 +10,19 @@
  */
 import type { Entry } from './parser.js'
 
+// ---------------------------------------------------------------------------
+// 模块常量（参数摘要的截断宽度 / 换算基数）
+// ---------------------------------------------------------------------------
+
+/** bash 命令参数摘要截断字符数。 */
+const BASH_CMD_MAX_CHARS = 60
+/** subagent task 参数摘要截断字符数。 */
+const SUBAGENT_TASK_MAX_CHARS = 40
+/** 未知工具 arguments JSON 摘要截断字符数。 */
+const ARGS_JSON_MAX_CHARS = 50
+/** bytes→KB 换算基数（write content 的 KB 显示）。 */
+const BYTES_PER_KB = 1024
+
 /** 单次工具调用信息（从 assistant content 的 toolCall block 提取）。 */
 export interface ToolCallInfo {
   id: string
@@ -45,8 +58,10 @@ function coerceArgs(raw: unknown): Record<string, unknown> {
       if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
         return parsed as Record<string, unknown>
       }
-    } catch {
-      // 非法 JSON 字符串 → 空对象兜底（实测 arguments 全为 object，此分支纯防御）
+    } catch (err) {
+      // 非法 JSON 字符串 → 空对象兜底（实测 arguments 全为 object，此分支纯防御）；
+      // 共享层保持零依赖（无 logger 可用），不留 void err 以外的语句
+      void err
     }
   }
   return {}
@@ -103,7 +118,7 @@ export function formatToolCallSummary(tc: ToolCallInfo): string {
   switch (name) {
     case 'bash': {
       const cmd = strArg(args, 'command')
-      return cmd !== undefined ? `bash: ${truncate(cmd, 60)}` : 'bash'
+      return cmd !== undefined ? `bash: ${truncate(cmd, BASH_CMD_MAX_CHARS)}` : 'bash'
     }
     case 'read': {
       const p = strArg(args, 'path')
@@ -122,12 +137,12 @@ export function formatToolCallSummary(tc: ToolCallInfo): string {
       const head = p !== undefined ? `write: ${basename(p)}` : 'write'
       if (c === undefined) return head
       // utf8 字节转 KB 取整；小文件至少 1KB（0KB 无信息量）
-      const kb = Math.max(1, Math.round(Buffer.byteLength(c, 'utf8') / 1024))
+      const kb = Math.max(1, Math.round(Buffer.byteLength(c, 'utf8') / BYTES_PER_KB))
       return `${head} (${kb}KB)`
     }
     case 'subagent': {
       const task = strArg(args, 'task')
-      return task !== undefined ? `subagent: ${truncate(task, 40)}` : 'subagent'
+      return task !== undefined ? `subagent: ${truncate(task, SUBAGENT_TASK_MAX_CHARS)}` : 'subagent'
     }
     case 'head': {
       const p = strArg(args, 'path')
@@ -159,7 +174,7 @@ export function formatToolCallSummary(tc: ToolCallInfo): string {
       // 未知工具：arguments 非空 → name: <json 前50>；空对象 → 仅 name（{} 无信息量）
       if (Object.keys(args).length === 0) return name
       try {
-        return `${name}: ${truncate(JSON.stringify(args), 50)}`
+        return `${name}: ${truncate(JSON.stringify(args), ARGS_JSON_MAX_CHARS)}`
       } catch {
         return name
       }

package/src/discovery/roots.ts

@@ -62,8 +62,10 @@ async function scanJsonlRecursive(
         try {
           const s = await stat(full)
           results.push({ path: full, mtime: s.mtimeMs, size: s.size })
-        } catch {
-          // 文件并发删除等致 stat 失败 → 跳过（不中断整体扫描）
+        } catch (err) {
+          // 文件并发删除等致 stat 失败 → 跳过（不中断整体扫描）；
+          // 本模块零 pi 依赖（无 logger 可用），不留 void err 以外的语句
+          void err
         }
       }
     }

package/src/discovery/subagents.ts

@@ -23,7 +23,8 @@ import { resolveWorkflows } from './workflows.js'
  *   是 records/<sa-id>.json manifest（subagent 创建时写入，持久存在）。故 manifest 是孤儿/
  *   cleanedUp 的来源（design §3.3 D-7 "records/*.json manifest 作孤儿补充"）。
  * - workflows：M1 resolveFamily 恒返回 []。M2 在此单独读目标 session 的 workflow-state-link
- *   custom entry → link.data.path（wf-state 文件绝对路径）→ 读该文件最后一行（最新快照）取 calls。
+ *   custom entry → link.data.path（wf-state 文件绝对路径）→ 从文件尾向头找首个非空且
+ *   JSON.parse 成功的行（最新快照，容错尾半截 JSON）取 calls。
  *
  * @throws sessionId 不在任意 main session header → Error（M3 tool-adapter 层转 F1 恢复指引）
  */
@@ -87,7 +88,7 @@ export async function buildFamilyFromFs(sessionId: string, agentDir: string): Pr
       // manifest 主（TC-u4-manifest-enrich）：透 task/slug/model/status/sessionFile 全字段
       data = {
         rootSessionId: manifest.rootSessionId,
-        slug: manifest.slug ?? '', // slug 兼容旧 manifest（缺→空串兑底，m0 契约）
+        slug: manifest.slug ?? '', // slug 兼容旧 manifest（缺→空串兜底，m0 契约）
         task: manifest.task,
         agent: manifest.agentName, // 同语义异名：manifest.agentName ↔ identity.data.agent
         model: manifest.model,
@@ -163,7 +164,7 @@ export async function buildFamilyFromFs(sessionId: string, agentDir: string): Pr
   const family = resolveFamily(sessionId, index)
 
   // ---- 6. 补 M1 占位字段（fileName / subagent cwd）+ workflows ----
-  enrichRefs(family, sessionIdToPath, pathToRef)
+  enrichRefs(family, pathToRef)
   family.workflows = await resolveWorkflows(sessionId, sessionIdToPath, pathToRef)
 
   return family
@@ -330,11 +331,6 @@ function isRecordManifest(v: unknown): v is RecordManifest {
   )
 }
 
-/**
- * 扫描 subagents/<cwdSlug>/records/*.json —— subagent 注册清单。
- * 每个 manifest 在 subagent 创建时写入，持久存在即使 .jsonl 被 GC。坏 manifest（缺必填字段
- * /JSON 损坏）跳过，不中断扫描。
- */
 /** 读单个 manifest 文件并校验；坏 manifest（JSON 损坏/缺必填字段）返回 undefined。 */
 async function tryReadManifest(path: string): Promise<RecordManifest | undefined> {
   try {
@@ -345,6 +341,11 @@ async function tryReadManifest(path: string): Promise<RecordManifest | undefined
   }
 }
 
+/**
+ * 扫描 subagents/<cwdSlug>/records/*.json —— subagent 注册清单。
+ * 每个 manifest 在 subagent 创建时写入，持久存在即使 .jsonl 被 GC。坏 manifest（缺必填字段
+ * /JSON 损坏）跳过，不中断扫描。
+ */
 export async function listRecordManifests(agentDir: string): Promise<RecordManifest[]> {
   const root = join(agentDir, 'subagents')
   const out: RecordManifest[] = []
@@ -395,11 +396,7 @@ export function extractSessionIdFromFilename(name: string): string {
  *（identity 无 cwd）。此处用已扫描的真实文件信息补全：alive 的 ref 补 fileName + cwd；
  * cleanedUp 孤儿（无文件）保持占位。
  */
-function enrichRefs(
-  family: Family,
-  sessionIdToPath: Map<string, string>,
-  pathToRef: Map<string, SessionRef>,
-): void {
+function enrichRefs(family: Family, pathToRef: Map<string, SessionRef>): void {
   // sessionId → 完整 ref（含真实 fileName/cwd），由 pathToRef 反建
   const bySid = new Map<string, SessionRef>()
   for (const ref of pathToRef.values()) bySid.set(ref.sessionId, ref)
@@ -426,6 +423,4 @@ function enrichRefs(
       cwd: full.cwd || s.cwd,
     } as SubagentRef
   })
-  // sessionIdToPath 仅用于类型完整性占位引用，避免未用警告（实际路径信息已在 pathToRef）
-  void sessionIdToPath
 }

package/src/index.ts

@@ -15,8 +15,6 @@ import { createSessionCommand } from './tui/session-command.js'
  *   （错误直接 throw 给 pi——pi-agent-core agent-loop 只对 execute throw 置
  *   isError:true，返回值里的 isError 字段被丢弃；W4 修复，锚点
  *   agent-loop.js:453-483/525-547，pi 自带 bash 工具同范式）
- *
- * M4 将在此 addAutocompleteProvider（TUI # 补全，ctx.mode === 'tui' 时）。
  */
 
 // ---- TypeBox 参数 schema（design §3.4 14 字段）----
@@ -32,7 +30,7 @@ const SessionReadSchema = Type.Object({
   session: Type.Optional(
     Type.String({
       description:
-        'Session id, uuid fragment (e.g. e6c96), subagent record id (sa-xxx, precise lookup), or absolute .jsonl path (~ or ~/ allowed). Required for family/outline/expand/detail/search/export/workflow. # prefix auto-stripped.',
+        'Session id, uuid fragment (e.g. e6c96), subagent record id (sa-xxx, precise lookup), or absolute .jsonl path (~ or ~/ allowed). Required for family/outline/expand/detail/search/export/extract/workflow. # prefix auto-stripped.',
     }),
   ),
   query: Type.Optional(
@@ -43,7 +41,7 @@ const SessionReadSchema = Type.Object({
   ),
   turns: Type.Optional(
     Type.String({
-      description: 'detail action: turn range, "T013-T015" or "T013".',
+      description: 'detail/extract action: turn range, "T013-T015" or "T013".',
     }),
   ),
   turn: Type.Optional(
@@ -74,7 +72,8 @@ const SessionReadSchema = Type.Object({
   ),
   allBranches: Type.Optional(
     Type.Boolean({
-      description: 'outline/family: include abandoned side-branches. Default false.',
+      description:
+        "outline (and export's outline section): include abandoned side-branches. Not supported by family. Default false.",
     }),
   ),
   granularity: Type.Optional(
@@ -87,7 +86,8 @@ const SessionReadSchema = Type.Object({
   ),
   source: Type.Optional(
     StringEnum(['main', 'subagent'], {
-      description: 'find action: filter by source. "main" = sessions/, "subagent" = subagents/. Default both (merged).',
+      description:
+        'find and session-resolving actions: filter by source. "main" = sessions/, "subagent" = subagents/. Default both (merged).',
     }),
   ),
   limit: Type.Optional(
@@ -123,8 +123,8 @@ const SessionReadSchema = Type.Object({
 // ---- guidelines（注入 LLM，design §3.4）----
 
 const guidelines = [
-  'Progressive reading: outline (~500 token overview) → expand (one turn) → detail (full text). Default omits toolResult/thinking noise.',
-  'find first to locate a session by uuid fragment or name. TUI #references are uuid fragments.',
+  'Progressive reading: outline (~1500 token overview) → expand (one turn) → detail (full text). Default omits toolResult/thinking noise.',
+  'find first to locate a session by uuid fragment or name. TUI #references are full uuids.',
   'outline before detail. Never read raw .jsonl files—use this tool.',
   'family traces fork parents/children, subagent sessions, and workflow runs.',
   'extract what=<type> to pull user messages / commands / files / commits / tool results across turns (optional tool= filter for commands/tool-results).',
@@ -134,7 +134,7 @@ const guidelines = [
 
 // ---- 工具 description（design §3.4，照搬措辞）----
 
-const description = `Read pi session files (conversation history) by semantic structure instead of raw bytes. Use when you need to review another session, trace a fork/subagent/workflow family, or locate a past decision. Nine actions: find (locate by name/uuid fragment), family (fork/subagent/workflow relations), outline (turn-level overview, ~500 token), expand (single-turn entry list), detail (full text of turns), search (full-text grep across a session), export (materialize to file), extract (pull user messages / commands / files / commits / tool results by type), workflow (workflow run overview: status/budget/steps, step call sessionId jumps to outline/detail). Progressive reading: outline → expand → detail. Do NOT use for the current session (use get_messages) or to edit sessions (pi has /resume /fork).`
+const description = `Read pi session files (conversation history) by semantic structure instead of raw bytes. Use when you need to review another session, trace a fork/subagent/workflow family, or locate a past decision. Nine actions: find (locate by name/uuid fragment), family (fork/subagent/workflow relations), outline (turn-level overview, ~1500 token), expand (single-turn entry list), detail (full text of turns), search (full-text grep across a session), export (materialize to file), extract (pull user messages / commands / files / commits / tool results by type), workflow (workflow run overview: status/budget/steps, step call sessionId jumps to outline/detail). Progressive reading: outline → expand → detail. Do NOT use for the current session (the host provides current-session access) or to edit sessions (pi has /resume /fork).`
 
 /**
  * 已注册过 TUI provider/command 的 pi 实例集合。

package/src/tool-handler.ts

@@ -4,7 +4,7 @@
  * 分层约定（同 scheduler/cw-tool）：本文件零 pi 依赖——agentDir 作参数注入，
  * 不调用 getAgentDir()，可完全单测；pi 注册与 getAgentDir() 调用在 index.ts。
  *
- * 按 action 分发到 8 条路径，串联 M1 core（parser/tree/turns/render）+ M2 discovery
+ * 按 action 分发到 9 条路径，串联 M1 core（parser/tree/turns/render）+ M2 discovery
  *（find/subagents）。content 给 LLM 读（人类可读摘要），details 供程序化消费/测试断言。
  *
  * 错误规格 F1-F6：handler 抛 Error（message 含 👉 恢复指引），index.ts 的 execute 闭包
@@ -28,6 +28,7 @@ import {
   renderOutline,
   renderExpand,
   renderDetail,
+  formatBytesMarker,
   type OutlineOptions,
   type OutlineResult,
   type EntryBrief,
@@ -91,7 +92,10 @@ export interface ToolResult {
 // 小工具
 // ---------------------------------------------------------------------------
 
-const pad = (n: number): string => String(n).padStart(3, '0')
+/** turn 索引显示宽度（T013 三位补零）。 */
+const TURN_INDEX_WIDTH = 3
+
+const pad = (n: number): string => String(n).padStart(TURN_INDEX_WIDTH, '0')
 
 /** 构造带 👉 恢复指引的 Error（handler 抛出，由 execute 闭包 catch）。 */
 function err(message: string): Error {
@@ -103,24 +107,24 @@ function stripHash(s: string): string {
   return s.replace(/^#+/, '')
 }
 
+/** formatDate 日期段（月/日）补零宽度。 */
+const DATE_FIELD_WIDTH = 2
+
 function formatDate(ms: number): string {
   if (!ms) return ''
   const d = new Date(ms)
-  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(DATE_FIELD_WIDTH, '0')}-${String(
     d.getDate(),
-  ).padStart(2, '0')}`
+  ).padStart(DATE_FIELD_WIDTH, '0')}`
 }
 
+/** shortCwd 保留的目录末段数。 */
+const SHORT_CWD_SEGMENTS = 2
+
 /** cwd 取末两段缩短显示（完整 cwd 在 details 里）。 */
 function shortCwd(cwd: string): string {
   const parts = cwd.split('/').filter(Boolean)
-  return parts.slice(-2).join('/')
-}
-
-function formatOmitted(bytes: number): string {
-  if (bytes <= 0) return ''
-  if (bytes < 1024) return `[${bytes}B omitted]`
-  return `[${Math.round(bytes / 1024)}KB omitted]`
+  return parts.slice(-SHORT_CWD_SEGMENTS).join('/')
 }
 
 /** F5 必填参数校验。 */
@@ -151,13 +155,16 @@ function parseTurnIndex(raw: string): number {
   return parseInt(m[1], 10)
 }
 
+/** turns 范围 "T013-T015" 的段数。 */
+const TURNS_RANGE_PARTS = 2
+
 function parseTurnsRange(raw: string): { start: number; end: number } {
   const parts = raw.split('-').map((s) => s.trim())
   if (parts.length === 1) {
     const i = parseTurnIndex(parts[0])
     return { start: i, end: i }
   }
-  if (parts.length === 2) {
+  if (parts.length === TURNS_RANGE_PARTS) {
     const start = parseTurnIndex(parts[0])
     const end = parseTurnIndex(parts[1])
     if (end < start) {
@@ -332,7 +339,7 @@ function formatSessionGc(record: RecordManifest): string {
 /** ES2（SA_ID_NO_MATCH）：sa-id 无精确匹配（可能仍在运行 / 片段输入）。 */
 function formatSaIdNotFound(saId: string): string {
   return (
-    `subagent "${saId}" 无匹配 record（可能仍在运行——终态 record 在 completed/failed 后才写）。` +
+    `subagent "${saId}" 无匹配 record（若刚启动，record 可能尚未落盘）。` +
     `\n👉 用 session_read { action:"family" } 查活跃/已完成的 subagent；` +
     `若是片段输入，请用完整 sa- id 或 action:"find" 重试。`
   )
@@ -349,10 +356,15 @@ function formatSaIdAmbiguous(saId: string, records: RecordManifest[]): string {
   )
 }
 
+/** sessionId 列表行内的短显前缀长度。 */
+const SESSION_ID_PREFIX_LEN = 8
+/** 消歧提示的 uuid 片段长度（比短显略长，引导输入更长片段消歧）。 */
+const HINT_ID_PREFIX_LEN = 12
+
 /** F1 无匹配 message（含最近 10 + 👉）。 */
 function formatNoMatch(query: string, recent: MatchedSession[]): string {
   const lines: string[] = recent.length
-    ? recent.map((m, i) => `  ${i + 1}. ${m.sessionId.slice(0, 8)}… ${m.firstMessagePreview ?? ''}`.trimEnd())
+    ? recent.map((m, i) => `  ${i + 1}. ${m.sessionId.slice(0, SESSION_ID_PREFIX_LEN)}… ${m.firstMessagePreview ?? ''}`.trimEnd())
     : ['  （无历史 session）']
   return (
     `无匹配 session："${query}"。最近 ${recent.length} 个 session：\n${lines.join('\n')}\n` +
@@ -368,7 +380,7 @@ function disambiguate(query: string, candidates: MatchedSession[]): ToolResult {
   )
   const hint =
     candidates[0] !== undefined
-      ? `（如 ${candidates[0].sessionId.slice(0, 12)}）`
+      ? `（如 ${candidates[0].sessionId.slice(0, HINT_ID_PREFIX_LEN)}）`
       : ''
   const text =
     `${candidates.length} 个匹配 "${query}"：\n${lines.join('\n')}\n` +
@@ -400,7 +412,7 @@ function formatFindContent(
   truncated: boolean,
 ): string {
   const lines = matches.map((m, i) => {
-    const parts = [`${i + 1}. ${m.sessionId.slice(0, 8)}…`, formatDate(m.mtime)]
+    const parts = [`${i + 1}. ${m.sessionId.slice(0, SESSION_ID_PREFIX_LEN)}…`, formatDate(m.mtime)]
     if (m.cwd) parts.push(shortCwd(m.cwd))
     if (m.firstMessagePreview) parts.push(m.firstMessagePreview)
     return parts.join(' · ')
@@ -419,7 +431,7 @@ function formatOutlineText(r: OutlineResult): string {
     if (b.toolSummary) parts.push(b.toolSummary)
     // v2 O1：补 assistant 结论行（→ ）让 outline 单独可决策
     if (b.assistantBrief) parts.push('→ ' + b.assistantBrief)
-    const om = formatOmitted(b.omittedBytes)
+    const om = formatBytesMarker(b.omittedBytes)
     if (om) parts.push(om)
     if (b.branch) parts.push('[旁支]')
     return parts.join(' · ')
@@ -429,7 +441,7 @@ function formatOutlineText(r: OutlineResult): string {
     `${r.stats.totalTurns} turns · ${r.stats.totalEntries} entries · ~${r.tokenEstimate} tokens${
       r.stats.skippedLines > 0 ? ` · ${r.stats.skippedLines} skipped lines` : ''
     }`,
-    r.truncated ? `[还有 ${r.truncated} 轮未显示，用 detail 或调大 budget]` : '',
+    r.truncated ? `[还有 ${r.truncated} 轮未显示，用 detail 的 turns 参数看指定 turn 范围]` : '',
   ]
     .filter(Boolean)
     .join('\n')
@@ -440,7 +452,7 @@ function formatExpandText(turn: string, entries: EntryBrief[]): string {
   const lines = entries.map(
     (e) =>
       `  [${e.index}] ${e.type}${e.role ? '/' + e.role : ''} ${e.brief}${
-        e.omittedBytes > 0 ? ' ' + formatOmitted(e.omittedBytes) : ''
+        e.omittedBytes > 0 ? ' ' + formatBytesMarker(e.omittedBytes) : ''
       }`,
   )
   return `${turn}\n${lines.join('\n')}`
@@ -504,10 +516,10 @@ function formatDetailText(
     .map((e) => {
       if (isToolResultSummary(e)) {
         // v2 O3：摘要态渲染（summary + 头 3 行 + 看全文提示）
-        return `---\ntoolResultSummary (${e.id.slice(0, 8)})\n${e.summary}\n     │ 共 ${e.totalLines} 行，前 3 行：${e.headLines}\n     │ （+ includeToolResult:true 看全文）`
+        return `---\ntoolResultSummary (${e.id.slice(0, SESSION_ID_PREFIX_LEN)})\n${e.summary}\n     │ 共 ${e.totalLines} 行，前 3 行：${e.headLines}\n     │ （+ includeToolResult:true 看全文）`
       }
       const role = e.message ? `/${e.message.role}` : ''
-      return `---\n${e.type}${role} (${e.id.slice(0, 8)})\n${entryReadableText(e)}`
+      return `---\n${e.type}${role} (${e.id.slice(0, SESSION_ID_PREFIX_LEN)})\n${entryReadableText(e)}`
     })
     .join('\n')
   return `${head}\n${body}`
@@ -517,15 +529,15 @@ function formatFamilyText(f: Family): string {
   const lines: string[] = []
   lines.push(`root: ${f.root.sessionId} (${formatDate(f.root.mtime)})`)
   if (f.parents.length)
-    lines.push(`parents: ${f.parents.map((p) => p.sessionId.slice(0, 8)).join(', ')}`)
+    lines.push(`parents: ${f.parents.map((p) => p.sessionId.slice(0, SESSION_ID_PREFIX_LEN)).join(', ')}`)
   if (f.forks.length)
-    lines.push(`forks: ${f.forks.map((p) => p.sessionId.slice(0, 8)).join(', ')}`)
+    lines.push(`forks: ${f.forks.map((p) => p.sessionId.slice(0, SESSION_ID_PREFIX_LEN)).join(', ')}`)
   if (f.subagents.length)
     lines.push(
       `subagents:\n${f.subagents
         .map(
           (s) =>
-            `  ${s.sessionId.slice(0, 8)} root=${s.rootSessionId.slice(0, 8)} slug=${s.slug}${
+            `  ${s.sessionId.slice(0, SESSION_ID_PREFIX_LEN)} root=${s.rootSessionId.slice(0, SESSION_ID_PREFIX_LEN)} slug=${s.slug}${
               s.cleanedUp ? ' [已清理]' : ''
             }`,
         )
@@ -600,9 +612,12 @@ function searchableText(content: unknown): string {
   return safeStringify(content)
 }
 
+/** search 命中片段的前后上下文字符数。 */
+const SNIPPET_CONTEXT_CHARS = 20
+
 function snippet(text: string, idx: number, len: number): string {
-  const start = Math.max(0, idx - 20)
-  const end = Math.min(text.length, idx + len + 20)
+  const start = Math.max(0, idx - SNIPPET_CONTEXT_CHARS)
+  const end = Math.min(text.length, idx + len + SNIPPET_CONTEXT_CHARS)
   return (
     (start > 0 ? '…' : '') +
     text.slice(start, end).replace(/\s+/g, ' ').trim() +
@@ -614,12 +629,15 @@ function snippet(text: string, idx: number, len: number): string {
 // 各 action 实现
 // ===========================================================================
 
+/** find action 的默认匹配数上限。 */
+const FIND_DEFAULT_LIMIT = 20
+
 /** find：按片段/名称/recent 定位 session（design §3.4 find）。零匹配不抛，返回提示。 */
 async function doFind(params: SessionReadParams, agentDir: string): Promise<ToolResult> {
   const query = requireStr(params.query, 'query', 'find')
   const { matches, truncated } = await findSessions(query, agentDir, {
     cwd: params.cwd,
-    limit: params.limit ?? 20,
+    limit: params.limit ?? FIND_DEFAULT_LIMIT,
     ...(params.source ? { source: params.source } : {}),
   })
   if (matches.length === 0) {
@@ -655,7 +673,7 @@ async function doFamily(params: SessionReadParams, agentDir: string): Promise<To
       tree = await buildExecutionTree(resolved.sessionId, agentDir, resolved.fileName)
     } catch (e) {
       throw err(
-        `构建执行树失败：${resolved.sessionId}（${e instanceof Error ? e.message : String(e)}）。👉 检查 session 或用 find 重新定位，或改用 recursive:false 看 flat family 兑底。`,
+        `构建执行树失败：${resolved.sessionId}（${e instanceof Error ? e.message : String(e)}）。👉 检查 session 或用 find 重新定位，或改用 recursive:false 看 flat family 兜底。`,
       )
     }
     return {
@@ -676,7 +694,7 @@ async function doFamily(params: SessionReadParams, agentDir: string): Promise<To
   return { content: [{ type: 'text', text: formatFamilyText(family) }], details: family }
 }
 
-/** outline：turn 级全貌 TOC（design §3.4 outline，~500 token）。 */
+/** outline：turn 级全貌 TOC（design §3.4 outline，~1500 token；render budget 硬编码 2000）。 */
 async function doOutline(params: SessionReadParams, agentDir: string): Promise<ToolResult> {
   const resolved = await resolveSessionId(params.session, 'outline', agentDir, params.source)
   if (resolved.kind === 'multi') return disambiguate(resolved.query, resolved.candidates)
@@ -745,6 +763,9 @@ async function doDetail(params: SessionReadParams, agentDir: string): Promise<To
   }
 }
 
+/** search action 的默认命中数上限。 */
+const SEARCH_DEFAULT_LIMIT = 20
+
 /** search：session 内全文检索（design §3.4 search，M3 新实现）。 */
 async function doSearch(
   params: SessionReadParams,
@@ -755,7 +776,7 @@ async function doSearch(
   if (resolved.kind === 'multi') return disambiguate(resolved.query, resolved.candidates)
   const pattern = requireStr(params.pattern, 'pattern', 'search')
   const scope = params.scope ?? 'all'
-  const limit = params.limit ?? 20
+  const limit = params.limit ?? SEARCH_DEFAULT_LIMIT
   const { entries } = await safeParse(resolved.fileName)
   const tree = buildTreeView(entries)
   const turns = segmentTurns(entries, new Set(tree.leafPath))
@@ -800,6 +821,9 @@ async function doSearch(
   return { content: [{ type: 'text', text }], details: { hits: sliced, truncated } }
 }
 
+/** export full 模式的 entry 分隔线（'=' 重复）宽度。 */
+const EXPORT_SEPARATOR_LEN = 40
+
 /** export：物化摘要到 <agentDir>/tmp/session-view-<id>.md（design §3.4 export，D-8）。 */
 async function doExport(params: SessionReadParams, agentDir: string): Promise<ToolResult> {
   const format = params.format ?? 'outline'
@@ -830,9 +854,9 @@ async function doExport(params: SessionReadParams, agentDir: string): Promise<To
     text = det
       .map((e) => {
         if (isToolResultSummary(e)) {
-          return `${'='.repeat(40)}\ntoolResultSummary (${e.id.slice(0, 8)})\n${entryReadableText(e)}`
+          return `${'='.repeat(EXPORT_SEPARATOR_LEN)}\ntoolResultSummary (${e.id.slice(0, SESSION_ID_PREFIX_LEN)})\n${entryReadableText(e)}`
         }
-        return `${'='.repeat(40)}\n${e.type}${e.message ? '/' + e.message.role : ''} (${e.id.slice(0, 8)})\n${entryReadableText(e)}`
+        return `${'='.repeat(EXPORT_SEPARATOR_LEN)}\n${e.type}${e.message ? '/' + e.message.role : ''} (${e.id.slice(0, SESSION_ID_PREFIX_LEN)})\n${entryReadableText(e)}`
       })
       .join('\n')
     label = 'full'
@@ -927,10 +951,13 @@ function truncateText(s: string, max: number): string {
   return s.length <= max ? s : s.slice(0, max) + '…'
 }
 
+/** turnsLabel 展示的 turn 数上限（超出折叠为 +N）。 */
+const TURNS_LABEL_HEAD_COUNT = 5
+
 /** turns 数组紧凑标签（前 5 个 + +N，避免一行过长撑爆预算）。 */
 function turnsLabel(turns: number[]): string {
-  const head = turns.slice(0, 5).map((n) => `T${pad(n)}`)
-  const suffix = turns.length > 5 ? `+${turns.length - 5}` : ''
+  const head = turns.slice(0, TURNS_LABEL_HEAD_COUNT).map((n) => `T${pad(n)}`)
+  const suffix = turns.length > TURNS_LABEL_HEAD_COUNT ? `+${turns.length - TURNS_LABEL_HEAD_COUNT}` : ''
   return head.join(',') + suffix
 }
 
@@ -955,9 +982,12 @@ function computeToolDistribution(
     .sort((a, b) => b.count - a.count)
 }
 
+/** F8 提示展示的工具分布条数上限。 */
+const TOOL_DISTRIBUTION_LIMIT = 10
+
 /** F8：commands/tool-results 的 tool 过滤零匹配 → 返回工具分布 + 👉（不抛错，design §3.3 F8）。 */
 function f8ToolNoMatch(what: ExtractWhat, tool: string, turns: Turn[]): ToolResult {
-  const dist = computeToolDistribution(turns).slice(0, 10)
+  const dist = computeToolDistribution(turns).slice(0, TOOL_DISTRIBUTION_LIMIT)
   const distStr = dist.map((d) => `${d.name}×${d.count}`).join(', ')
   const text = `what=${what} tool="${tool}" 无匹配。该 session 工具：${distStr}。👉 用存在的工具名重试。`
   return { content: [{ type: 'text', text }], details: { what, tool, toolDistribution: dist } }
@@ -975,6 +1005,12 @@ function f8ToolNoMatch(what: ExtractWhat, tool: string, turns: Turn[]): ToolResu
  *
  * getTurns：从 item 提取 turn 列表（files 是 turns 数组，其余单值包数组），供 F9 文案报 turn 范围。
  */
+
+/** UTF8 单字符最大字节数（预算字节→字符的保守换算基数，防多字节字符被切半）。 */
+const UTF8_MAX_BYTES_PER_CHAR = 3
+/** token 估算换算基数（bytes/4 口径，与 render 层 chars/4 同近似）。 */
+const CHARS_PER_TOKEN = 4
+
 export function renderExtractItems<I>(
   what: ExtractWhat,
   items: I[],
@@ -999,7 +1035,7 @@ export function renderExtractItems<I>(
     if (bytes + lineBytes > EXTRACT_BUDGET_BYTES) {
       // 超预算：对当前 line 内部截断到剩余预算（首项超大也截断，但保留截断后的内容）
       const remainingBytes = EXTRACT_BUDGET_BYTES - bytes
-      const charBudget = Math.floor(remainingBytes / 3) // 字节→字符 ×3 近似防 UTF8 切半
+      const charBudget = Math.floor(remainingBytes / UTF8_MAX_BYTES_PER_CHAR) // 字节→字符 ×3 近似防 UTF8 切半
       if (charBudget > 0) {
         const sliced = line.slice(0, charBudget) + '…'
         shown.push(item)
@@ -1031,7 +1067,7 @@ export function renderExtractItems<I>(
     shownTurns.length > 0
       ? `（T${pad(Math.min(...shownTurns))}-T${pad(Math.max(...shownTurns))}）`
       : ''
-  const actualTokens = Math.round(Buffer.byteLength(body, 'utf8') / 4)
+  const actualTokens = Math.round(Buffer.byteLength(body, 'utf8') / CHARS_PER_TOKEN)
   const text =
     body +
     `\n[what=${what} 已显示 ${shown.length}/${items.length} 项${turnRange}，约 ${actualTokens} token 达预算上限。👉 用较小 turns 范围（如 T000-T005）缩小，或换 what 重试。]`
@@ -1148,6 +1184,9 @@ function extractFiles(turns: Turn[]): ToolResult {
  *（git 操作未被 toolResult 捕获）或误报（git log 输出里的其他 hex）。每条标注来源 turn
  * + source + context，agent 可快速辨认。完全语义判断需 LLM，本工具零 LLM 依赖。
  */
+/** commits 提取的 hash 前后上下文字符数（次路径关键词判定窗口）。 */
+const COMMIT_CONTEXT_CHARS = 30
+
 function extractCommits(turns: Turn[]): ToolResult {
   // 建 toolCallId → bash command 映射（用于判定 toolResult 是否来自 git 命令）
   const bashCmds = new Map<string, string>()
@@ -1184,7 +1223,7 @@ function extractCommits(turns: Turn[]): ToolResult {
         const hash = m[0]
         const idx = m.index ?? 0
         const ctx = text
-          .slice(Math.max(0, idx - 30), idx + hash.length + 30)
+          .slice(Math.max(0, idx - COMMIT_CONTEXT_CHARS), idx + hash.length + COMMIT_CONTEXT_CHARS)
           .replace(/\s+/g, ' ')
           .trim()
         if (isGitBash) {
@@ -1219,6 +1258,9 @@ function extractCommits(turns: Turn[]): ToolResult {
   )
 }
 
+/** tool-results 正文截断上限（防爆）。 */
+const TOOL_RESULT_TEXT_MAX_CHARS = 500
+
 /**
  * 预设 5：tool-results——role==='toolResult' 文本（design §3.3 D3）。
  * text 截断到 500 字防爆；可选 tool 过滤（msg.toolName）；过滤零匹配 → F8。
@@ -1231,7 +1273,7 @@ function extractToolResults(turns: Turn[], tool: string | undefined): ToolResult
       if (e.message?.role !== 'toolResult') continue
       const tn = e.message.toolName ?? '?'
       if (tool !== undefined && tn !== tool) continue
-      const text = truncateText(extractContentText(e.message.content), 500)
+      const text = truncateText(extractContentText(e.message.content), TOOL_RESULT_TEXT_MAX_CHARS)
       items.push({ turn: t.index, index: ei, toolName: tn, text })
     }
   }
@@ -1335,8 +1377,9 @@ interface SkippedRun {
  * session 会抛「session not found in family index」）——resolveSessionId 已把 session 解析到
  * 真实文件（kind==='ok' 保证文件存在，三形态：绝对路径/sa-id 均 existsSync 校验，片段匹配
  * 来自实际 fs 扫描），直接用 resolved.fileName 构造单条目 sessionIdToPath 调 resolveWorkflows
- *（与 buildFamilyFromFs 步骤 6 的 workflow 腿同源）。pathToRef 仅含目标 session，call 引用
- * 走 sessionRefFromPath 文件名最小回退（sessionId+fileName，足够 LLM 跳 outline/detail 深读）。
+ *（与 buildFamilyFromFs 步骤 6 的 workflow 腿同源）。pathToRef 传空 Map（单条目链路无其他
+ * 文件可反查），call 引用 100% 走 sessionRefFromPath 文件名最小回退（sessionId+fileName，
+ * 足够 LLM 跳 outline/detail 深读）。
  *
  * 错误契约（C2）：workflow 概览探索语义，三类错误均返回 ToolResult 不抛错。
  * step 的 call sessionId/sessionFile 是 LLM 跳 outline/detail 的入口（m0 resolveSessionId
@@ -1418,7 +1461,7 @@ async function doWorkflow(params: SessionReadParams, agentDir: string): Promise<
   if (requestedRunId !== undefined) details.requestedRunId = requestedRunId
   if (skippedRuns.length > 0) details.skippedRuns = skippedRuns
 
-  // 全部 run 都跳过的兑底提示（ES-wf-snapshot-read-fail 末段）
+  // 全部 run 都跳过的兜底提示（ES-wf-snapshot-read-fail 末段）
   let text: string
   if (runs.length === 0) {
     text =

package/src/tui/hash-provider.ts

@@ -47,8 +47,6 @@ const AGE_NUM_DIGITS = 2
 export interface AutocompleteCandidate {
   /** 显示文本（满宽 label）。`${age} ${预览/name}`，如 "01m 看看 pi-session-reader..." */
   label: string
-  /** 副信息（次列）。本 provider 不设（undefined）——触发 SelectList 满宽 label 分支 */
-  description?: string
   /** 插入编辑器，如 "#019e6c96-aaaa-bbbb-cccc-dddddddddddd"（design D-3：完整 uuid，非名称；不显示给用户看） */
   insertText: string
 }
@@ -203,7 +201,6 @@ export function createHashAutocompleteProvider(
       const items: AutocompleteItem[] = candidates.map((c) => ({
         value: c.insertText,
         label: c.label,
-        description: c.description,
       }))
       // prefix = 光标前匹配到的整段（# 及片段），applyCompletion 据此定位替换区间
       return { items, prefix: `#${fragment}` }

package/src/tui/session-command.ts

@@ -36,7 +36,7 @@ export function createSessionCommand(
   handler(args: string, ctx: ExtensionCommandContext): Promise<void>
 } {
   return {
-    description: 'Pick a session and insert a #uuid-fragment reference into the editor.',
+    description: 'Pick a session and insert a #uuid reference into the editor.',
     async getArgumentCompletions(argumentPrefix) {
       const trimmed = argumentPrefix.trim()
       const all = await SessionManager.listAll(getCwdSessionDir())