@zhushanwen/pi-session-reader 0.11.0 → 0.13.0

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

@@ -1,7 +1,7 @@
 import { describe, it, expect, beforeEach, afterEach } from 'vitest'
 import { tmpdir } from 'node:os'
 import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from 'node:fs'
-import { join } from 'node:path'
+import { join, dirname } from 'node:path'
 
 import { readZcodeManifest, listZcodeManifests } from '../discovery/zcode-manifest.js'
 import { findZcodeEntryAnchor } from '../discovery/entry-anchor.js'
@@ -10,10 +10,10 @@ import { findZcodeEntryAnchor } from '../discovery/entry-anchor.js'
 // 变体 M（设计 §4 场景 1a）：zcode manifest 直读（§3.1 第①步主路径）+ 枚举（family 用）。
 //
 // fixture 对齐 F21 磁盘真实形态：zcode manifest **无 sessionFile 键**
-// （投影函数照写 sessionFile: undefined，JSON.stringify 丢键）、engine:'zcode'、
+// （派生视图函数照写 sessionFile: undefined，JSON.stringify 丢键）、engine:'zcode'、
 // engineHandle.sessionRef 双键齐。
 //
-// 单元边界：只测「认出 zcode manifest + 提取锚」；白名单闸 / 错误码映射（U9）、
+// 单元边界：只测「认出 zcode manifest + 提取锚」；白名单门禁 / 错误码映射（U9）、
 // entry 兜底定位语义（U7 已交付）不在本文件展开。
 // ============================================================
 
@@ -21,9 +21,13 @@ const DB_PATH = '/data/agent/engines/zcode/session-db/db.sqlite'
 
 let agentDir: string
 
-/** 在 <agentDir>/subagents/<slug>/records/ 下写一个 manifest 文件（手写 JSON 字符串，忠实控制键） */
-function writeManifest(slug: string, name: string, content: string): string {
-  const recordsDir = join(agentDir, 'subagents', slug, 'records')
+/**
+ * 在存储树分区 <root>/<sid>/subagents/records/ 下写一个 manifest 文件（手写 JSON 字符串，
+ * 忠实控制键）。[session-store-layout-inversion D6/单新根] 新布局无 cwd-slug 层，
+ * slug 参数消亡（保留签名兼容既有调用点，弃用改名 _slug）；分区名固定合法 sid。
+ */
+function writeManifest(_slug: string, name: string, content: string): string {
+  const recordsDir = join(dirname(agentDir), 'ext-sessions', 'root-session-test', 'subagents', 'records')
   mkdirSync(recordsDir, { recursive: true })
   const file = join(recordsDir, name)
   writeFileSync(file, content, 'utf8')
@@ -73,7 +77,10 @@ function recordLine(saId: string, sessionRef: Record<string, string>): string {
 }
 
 beforeEach(() => {
-  agentDir = mkdtempSync(join(tmpdir(), 'zcode-manifest-test-'))
+  // agentDir 两层化（<mkdtemp>/agent）：存储树推导 = dirname(agentDir)/ext-sessions，
+  // 单层直接当 agentDir 会把扫描根泄到 tmpdir 公共层（跨测试污染——先例 reaper/family-zcode 同修）
+  agentDir = join(mkdtempSync(join(tmpdir(), 'zcode-manifest-test-')), 'agent')
+  mkdirSync(agentDir, { recursive: true })
 })
 afterEach(() => {
   rmSync(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
@@ -353,12 +360,13 @@ describe('listZcodeManifests 枚举（family 节点列表来源）', () => {
     expect(manifests.find((m) => m.id === 'sa-s2')?.slug).toBe('worker') // agentName 兜底
   })
 
-  it('subagents 根不存在 → 空数组（不报错；单节点不可达不炸整屏）', async () => {
-    const bareDir = mkdtempSync(join(tmpdir(), 'zcode-manifest-bare-'))
+  it('存储树根不存在 → 空数组（不报错；单节点不可达不炸整屏）', async () => {
+    // agentDir 两层化：扫描根 = dirname(agentDir)/ext-sessions（mkdtemp 私有层内，防公共层污染）
+    const bareDir = join(mkdtempSync(join(tmpdir(), 'zcode-manifest-bare-')), 'agent')
     try {
       expect(await listZcodeManifests(bareDir)).toEqual([])
     } finally {
-      rmSync(bareDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+      rmSync(dirname(bareDir), { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
     }
   })
 })

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

@@ -1,7 +1,7 @@
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
 import { tmpdir } from 'node:os'
 import { mkdtempSync, writeFileSync, mkdirSync, rmSync, existsSync, readFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { join, dirname } from 'node:path'
 import { DatabaseSync } from 'node:sqlite'
 import { Check } from 'typebox/value'
 
@@ -16,7 +16,7 @@ import sessionReaderExtension from '../index.js'
 import { setPiHandle } from '@zhushanwen/pi-extension-logger'
 
 // ============================================================
-// U9 路由 + 白名单闸 + 错误面集成测试（design session-reader-shared-core
+// U9 路由 + 白名单闸 + 错误范围集成测试（design session-reader-shared-core
 // §3.1 三层定位链 / §3.4 七码 + 检查顺序三段递进 / §4 场景 1a 变体 M/E +
 // 场景 2 family + 场景 5 八类失败 + 场景 3 pi 零回归 + D4 schema 零变化）。
 //
@@ -53,8 +53,8 @@ beforeEach(() => {
   mkdirSync(agentDir, { recursive: true })
   mkdirSync(liveDir, { recursive: true })
   dbPath = join(root, ...ISOLATED_DB_SEGMENTS)
-  // 结构化日志捕获：logger.warn 走 appendEntry 通道（不进 LLM 可见面——本文件同时
-  // 是「降级留痕不进 LLM 可见面」契约的断言面）。测试后清注入防跨文件泄漏。
+  // 结构化日志捕获：logger.warn 走 appendEntry 通道（不进 LLM 可见部分——本文件同时
+  // 是「降级留痕不进 LLM 可见部分」契约的断言范围）。测试后清注入防跨文件泄漏。
   appendEntries = vi.fn()
   setPiHandle({ appendEntry: appendEntries } as unknown as Parameters<typeof setPiHandle>[0])
 })
@@ -135,7 +135,7 @@ function assistantMsg(
 
 /**
  * 建真实 fixture 隔离库（WAL + session/message/part/schema_migration 四表，行形态 =
- * zcode-session-source helpers 同款宿主 schema 0.16.5 消费面子集）。
+ * zcode-session-source helpers 同款宿主 schema 0.16.5 消费方子集）。
  * 测试进程跑 node（node:sqlite 可用）；生产读链的驱动选择在 source 包内。
  */
 function createZcodeDb(path: string, schemaVersion = '0.16.5', sessions: SessionRows[] = []): void {
@@ -175,7 +175,9 @@ function writeZcodeManifest(
   saId: string,
   opts: { sessionRef?: Record<string, string>; omitEngineHandle?: boolean; engine?: string | true } = {},
 ): void {
-  const recordsDir = join(agentDir, 'subagents', 'proj-slug', 'records')
+  // [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,
@@ -210,8 +212,8 @@ function recordLine(entryId: string, saId: string, sessionRef: Record<string, st
 
 /**
  * pi 形态的 subagent-record custom entry 行（回归 A1 instrument）：engine 键缺省 +
- * sessionRef 无 dbPath——subagent-core record-entry.ts 的 pi 投影形态（engineHandle
- * 可选、sessionRef 整体透传不枚举内部键；最小可信子集，跨包漂移由 entry-anchor.test 守卫）。
+ * sessionRef 无 dbPath——subagent-core record-entry.ts 的 pi 派生视图形态（engineHandle
+ * 可选、sessionRef 整体透传不枚举内部键；最小可信子集，跨包漂移由 entry-anchor.test 检查）。
  */
 function piRecordLine(entryId: string, saId: string): string {
   return JSON.stringify({
@@ -220,7 +222,7 @@ function piRecordLine(entryId: string, saId: string): string {
     id: entryId,
     parentId: null,
     data: {
-      // 登记 §3.3：条目面 = v2 族——pi 形态 = 注册条（身份）+ 终态条（engineHandle 半键）。
+      // 登记 §3.3：条目范围 = v2 族——pi 形态 = 注册条（身份）+ 终态条（engineHandle 半键）。
       v: 2,
       kind: 'settled',
       id: saId,
@@ -260,7 +262,7 @@ function writeRootSessionFile(): void {
 
 /** pi manifest + pi subagent session 文件（pi 穿插断言用；engine 缺省 = pi 存量形态）。 */
 function writePiFixture(): void {
-  const subDir = join(agentDir, 'subagents', 'pi-slug', 'sessions')
+  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(
@@ -272,7 +274,7 @@ function writePiFixture(): void {
     ].join('\n') + '\n',
     'utf8',
   )
-  const recordsDir = join(agentDir, 'subagents', 'pi-slug', 'records')
+  const recordsDir = join(dirname(agentDir), 'ext-sessions', ROOT_SESSION, 'subagents', 'records')
   mkdirSync(recordsDir, { recursive: true })
   writeFileSync(
     join(recordsDir, 'sa-pi-1.json'),
@@ -433,7 +435,7 @@ describe('场景 5 八类失败（§3.4 表逐行 + 检查顺序三段递进）'
     await expect(handleSessionRead({ action: 'result', session: SA_M }, signals())).rejects.toThrow(
       'zcode_anchor_missing',
     )
-    // 归因进结构化日志不进 LLM 可见面（§3.4）：缺失键名可区分（missing-dbPath）
+    // 归因进结构化日志不进 LLM 可见部分（§3.4）：缺失键名可区分（missing-dbPath）
     expect(logCallsWithReason('missing-dbPath')).toBeGreaterThanOrEqual(1)
   })
 
@@ -521,14 +523,14 @@ describe('场景 5 八类失败（§3.4 表逐行 + 检查顺序三段递进）'
 })
 
 // ---------------------------------------------------------------------------
-// 驱动探测失败的错误面契约（跨包漂移守卫 + L4 包装形态映射）
+// 驱动探测失败的错误契约（跨包漂移检查 + L4 包装形态映射）
 // ---------------------------------------------------------------------------
 
-describe('驱动探测失败错误面：跨包契约 + L4 包装形态映射', () => {
+describe('驱动探测失败错误范围：跨包契约 + L4 包装形态映射', () => {
   it('跨包契约：SQLITE_DRIVER_UNSUPPORTED_MARK 子串在 zcode-session-source sqlite-driver 源文内（漂移即红）', () => {
     // 驱动探测错误无专用错误类型（该包不导出子类），reader 按消息特征识别——mark 与
     // sqlite-driver 源内错误字面量的绑定由本测试机器锚定（entry-anchor.test.ts 协议
-    // 字面量跨包漂移守卫同范式）：源文措辞变更不再含 mark → host_unsupported 面死亡，红。
+    // 字面量跨包漂移检查同范式）：源文措辞变更不再含 mark → host_unsupported 契约死亡，红。
     const source = readFileSync(
       new URL('../../../../../packages/zcode-session-source/src/sqlite-driver.ts', import.meta.url),
       'utf8',
@@ -689,7 +691,7 @@ describe('pi 穿插不受影响：同 fixture 内 pi 会话读取与 zcode 调
 /** `session_read` 输入 schema 的 JSON 序列化快照（防无意漂移的逐字节锚）。
  *
  * 快照锚的意图 = 无意漂移拦截（参数增删 / 文案改动即红，迫使有意确认）；
- * 有意的声明面压缩须同批重新生成快照。当前快照 = tool-declaration-slimming
+ * 有意的声明侧压缩须同批重新生成快照。当前快照 = tool-declaration-slimming
  * U-A1 压缩终态（D1 三层分工：action 功能语义唯一承载点 = 枚举 description；
  * 工具 description 只留定位 + 边界；guidelines 只留纪律）。重新生成：
  * tsx 起 extension 捕获 registerTool 的 parameters 后 JSON.stringify。
@@ -748,12 +750,12 @@ describe('session_read schema 快照（D4：不加任何工具参数，逐字节
 
 describe('session_read 锚词保留清单（D2：guidelines 纪律逐词锚定）', () => {
   // SCHEMA_SNAPSHOT 只逐字节锚 parameters schema，不覆盖 guidelines——本块是
-  // guidelines 锚词的机器防线：弱模型回归（P7/PB-weak）后对本工具声明面的
+  // 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"      —— 错误面恢复指针契约
+  //   3. "sa- ids route"         —— zcode 路由对 LLM 的唯一可见部分（U9）
+  //   4. "👉 recovery hint"      —— 错误范围恢复指针契约
   //   5. "doctor"                —— 环境自检入口（另被上方快照 action 枚举间接锚定）
   it('guidelines 5 锚词逐个在位（缺一词即红）', () => {
     const registerTool = vi.fn()

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

@@ -77,7 +77,7 @@ describe('assertZcodeDbPathAllowed：检查顺序三段递进（存在性先于
     )
   })
 
-  it('第 2 段路径：存在但集合外 → zcode_db_path_forbidden（安全面错误语义更重）', () => {
+  it('第 2 段路径：存在但集合外 → zcode_db_path_forbidden（安全侧错误语义更重）', () => {
     const outside = join(root, 'evil.sqlite')
     writeFileSync(outside, '', 'utf8')
     try {

package/src/core/family.ts

@@ -38,7 +38,7 @@ export interface SubagentRef extends SessionRef {
   task?: string
   /** agent 类型名（manifest.agentName，P-fallback 时 identity.data.agent；同语义异名） */
   agentName?: string
-  /** 模型 id（仅 manifest 有；P-fallback 时 undefined）。仅 details 可见，不进文本渲染（D2②：展示面只取 status/agentName/task） */
+  /** 模型 id（仅 manifest 有；P-fallback 时 undefined）。仅 details 可见，不进文本渲染（D2②：展示侧只取 status/agentName/task） */
   model?: string
   /** 终态 completed/failed/running（仅 manifest 有；P-fallback 时 undefined） */
   status?: string
@@ -60,7 +60,7 @@ export interface Family {
   forks: SessionRef[]
   /** 含隔代（design §3.3 D-7 Q1：对 fork 链每个节点查 subagentsByRoot 合并） */
   subagents: SubagentRef[]
-  /** M1 恒返回 []，workflow 腿需读 workflow-state 文件（IO）归 M2 */
+  /** M1 恒返回 []，workflow 路径需读 workflow-state 文件（IO）归 M2 */
   workflows: WorkflowRef[]
 }
 
@@ -146,12 +146,12 @@ export function buildZcodeSubagentsByRoot(
   return byRoot
 }
 
-// ---- 类型守卫：从 unknown 的 entry.data 提取 subagent identity 字段 ----
+// ---- 类型检查：从 unknown 的 entry.data 提取 subagent identity 字段 ----
 
 /**
  * identity 尾行 data 结构（读取视图，DM-IdentityData）。
  *
- * 守卫只强制 rootSessionId+slug（m0 契约），其余富字段全 optional——由 buildFamilyFromFs
+ * 检查只强制 rootSessionId+slug（m0 契约），其余富字段全 optional——由 buildFamilyFromFs
  * 按 manifest 主/P-fallback 回退路径组装时决定是否填入（manifest 主填全，P-fallback
  * 只填 task/agent/sessionFile，model/status 缺）。
  */
@@ -178,7 +178,7 @@ interface SubagentIdentityData {
 function isSubagentIdentityData(v: unknown): v is SubagentIdentityData {
   if (typeof v !== 'object' || v === null) return false
   const obj = v as Record<string, unknown>
-  // 守卫放宽：只校验 rootSessionId+slug 必填（m0 契约），task/agent/model/status/sessionFile optional
+	// 检查放宽：只校验 rootSessionId+slug 必填（m0 契约），task/agent/model/status/sessionFile optional
   return typeof obj.rootSessionId === 'string' && typeof obj.slug === 'string'
 }
 
@@ -380,7 +380,7 @@ export function resolveFamily(sessionId: string, index: FamilyIndex): Family {
     }
   }
 
-  // 5. workflows：M1 恒 []，workflow 腿需读 workflow-state 文件（IO）归 M2
+  // 5. workflows：M1 恒 []，workflow 路径需读 workflow-state 文件（IO）归 M2
   const workflows: WorkflowRef[] = []
 
   return { root, parents, forks, subagents, workflows }

package/src/core/render.ts

@@ -79,7 +79,7 @@ export interface OutlineOptions {
 }
 
 // ---------------------------------------------------------------------------
-// content 类型守卫与提取（message.content 是 unknown，design §3.4）
+// content 类型检查与提取（message.content 是 unknown，design §3.4）
 // ---------------------------------------------------------------------------
 
 interface ContentBlock {
@@ -454,7 +454,7 @@ export function renderOutline(
   const allBranches = options?.allBranches ?? false
   const granularity = options?.granularity ?? 'turn'
 
-  // 字节/条目统计保持全量口径（折叠是展示层行为，不丢数据面）；行与轮次计数走对话集
+  // 字节/条目统计保持全量口径（折叠是展示层行为，不丢数据）；行与轮次计数走对话集
   const parsedBytes = leafParsedBytes(turns)
   const leafEntryCount = turns.reduce((s, t) => s + t.entries.length, 0)
   // totalEntries = leaf + 旁支子树 + 孤儿；totalBytes 无原始文件字节数（签名不含 ParseResult），

package/src/core/toolcall.ts

@@ -69,7 +69,7 @@ function coerceArgs(raw: unknown): Record<string, unknown> {
 /**
  * 从 entry.message.content 的 `{type:"toolCall"}` block 提取工具调用列表。
  *
- * content 是 unknown 做类型守卫；非数组或无 toolCall block 返 []。
+ * content 是 unknown 做类型检查；非数组或无 toolCall block 返 []。
  * 仅纳入 id + name 均为 string 的 block（O2 靠 id 关联 toolResult，O1 靠 name 聚合；
  * 缺 id 的块无法关联，缺 name 无法摘要，跳过——实测 0 缺失）。
  */

package/src/core/workflow.ts

@@ -15,7 +15,7 @@
 
 import { isRecord } from '@zhushanwen/pi-ext-guards'
 
-// ---- 类型守卫 helpers ----
+// ---- 类型检查 helpers ----
 
 /** unknown → string 收窄（非 string → undefined）。快照可选字符串字段的统一入口。 */
 function strOr(v: unknown): string | undefined {
@@ -74,9 +74,9 @@ export interface WorkflowOverview {
   runId: string
   /** WorkflowRef.stateFile 透传 */
   stateFile: string
-  /** NEW state.status / OLD 顶层 status / record 流投影（[D2] 三态：running | interrupted | done） */
+  /** NEW state.status / OLD 顶层 status / record 流派生视图（[D2] 三态：running | interrupted | done） */
   status: string
-  /** details 格式标记（随 details.runs 透传给程序化消费方，文本渲染不读）。v2 读取面形状与 v1 一致（pi-subagent-workflow 8.x 一次性生命周期） */
+  /** details 格式标记（随 details.runs 透传给程序化消费方，文本渲染不读）。v2 读侧形状与 v1 一致（pi-subagent-workflow 8.x 一次性生命周期） */
   version: 'wf-run-v1' | 'wf-run-v2' | 'legacy'
   /** NEW spec.scriptName / spec.name / OLD name */
   script?: string
@@ -222,12 +222,12 @@ function parseLegacyRunSnapshot(
  *
  * 分支（C-parserunsnapshot-dualformat，TC-wf-snapshot-version-union）：
  * - 非对象 → null（调用方跳过，ES-wf-snapshot-unparseable）
- * - NEW (snapshot.v === 'wf-run-v1' 或 'wf-run-v2'，读取面形状一致)：state.* / meta.* / spec.*
+ * - NEW (snapshot.v === 'wf-run-v1' 或 'wf-run-v2'，读侧形状一致)：state.* / meta.* / spec.*
  * - OLD (无 v，有 callCache 数组或顶层 status)：顶层 status/budget/startedAt + callCache
  * - 既非 NEW 也非 OLD → null（未来版本（如 wf-run-v3）/ 异构内容）
  *
  * runId/stateFile 透传参数（不读 snapshot.runId，保证与 family.workflows 一致，避免 OLD 顶层
- * runId 可信度低的不一致）。零 any（全程 typeof/Array.isArray/isRecord 守卫收窄）。
+ * runId 可信度低的不一致）。零 any（全程 typeof/Array.isArray/isRecord 检查收窄）。
  */
 export function parseRunSnapshot(
   snapshot: unknown,
@@ -236,7 +236,7 @@ export function parseRunSnapshot(
 ): WorkflowOverview | null {
   if (!isRecord(snapshot)) return null
 
-  // NEW 格式（v === 'wf-run-v1' || 'wf-run-v2'，v2 读取面形状兼容 v1）
+  // NEW 格式（v === 'wf-run-v1' || 'wf-run-v2'，v2 读侧形状兼容 v1）
   const v = snapshot.v
   if (v === 'wf-run-v1' || v === 'wf-run-v2') {
     return parseNewRunSnapshot(snapshot, v, runId, stateFile)
@@ -331,7 +331,7 @@ interface RecordStreamLine {
   [key: string]: unknown
 }
 
-/** 流解析产物：run 装配面（runId 透传 + stateFile=record 流路径）。 */
+/** 流解析产物：run 装配侧（runId 透传 + stateFile=record 流路径）。 */
 interface RecordStreamFold {
   workflowName?: string
   startedAt?: number
@@ -371,7 +371,7 @@ function parseRecordStreamLine(line: string): RecordStreamLine | undefined {
  *   sessionId——家族链跳转入口）；
  * - run-interrupted：[D2] 中断转移 → status 'interrupted'（非终局）；
  * - run-resumed：[D2] 复活转移 → 清中断标记（status 回 running——lifecycle fold
- *   投影语义：run-resumed 是 interrupted → running 的转移证据，跳过会使 resume
+ *   派生视图语义：run-resumed 是 interrupted → running 的转移证据，跳过会使 resume
  *   续跑期间的概览停在 interrupted 直至终局）；
  * - run-settled：终局帧 → status 'done' + outcome（done/failed/cancelled/time_limited）；
  * - 其余（phase-started / phase-settled）：跳过（状态机转移不进概览文本——phase 分组展示
@@ -445,7 +445,7 @@ function applyAgentSettledToFold(
   })
 }
 
-/** [parseRunRecordStream 拆分] status 三态投影（[D2]）：终局帧 > 中断转移 > running（空流也 running——活跃兜底）。 */
+/** [parseRunRecordStream 拆分] status 三态派生视图（[D2]）：终局帧 > 中断转移 > running（空流也 running——活跃兜底）。 */
 function projectRecordStreamStatus(fold: RecordStreamFold): {
   status: string
   reason: string | undefined

package/src/discovery/archive-ledger.ts

@@ -0,0 +1,221 @@
+/**
+ * 归档簿记域（session-archive 设计 D7：session-reader 归档根感知）。
+ *
+ * taiji 归档功能把闲置 session 整体搬入 `<agentDir>/archive/`（D1 镜像布局）并
+ * zstd 压缩主文件，每个归档单元一份明文簿记 `<原主文件名>.archive.json`（D3
+ * schema）。本模块是 extension 侧的簿记消费子集：解析 + 扫描 + 归档态渲染——
+ * **类型自含**（universal 包不依赖 taiji workspace shared，簿记字段子集在本地
+ * 接口声明），零内部依赖（不 import 本包其他模块，roots.ts 单向消费本模块，
+ * 规避 archive-ledger→find→roots 的值级循环 import）。
+ *
+ * 收集契约（D7 硬约束）：归档根**只收 `.archive.json` 簿记、不收 `.jsonl`**——
+ * staging 期归档目录内暂存明文主文件，一旦误收会被当「可完整读取的在场 session」
+ * 进候选集，归档标注随之失效；`.restoring` 后缀（恢复中，D9）不以
+ * `.archive.json` 结尾，天然不进收集。
+ */
+import { readdir, readFile, stat } from 'node:fs/promises'
+import type { Dirent } from 'node:fs'
+import { join } from 'node:path'
+
+/** 归档根目录名（`<agentDir>/archive/`，与 sessions/ 平级——D1）。 */
+export const ARCHIVE_DIRNAME = 'archive'
+
+/** 归档根目录（`<agentDir>/archive/`，agentDir 注入推导）。 */
+export function resolveArchiveDir(agentDir: string): string {
+  return join(agentDir, ARCHIVE_DIRNAME)
+}
+
+/**
+ * 存储树分区目录名合法性正则（镜像 shared `PI_SESSION_ID_PATTERN` 与 roots.ts
+ * 同字面副本：首尾字母数字，中间 [A-Za-z0-9._-]，禁 `:`）。簿记 sessionId 是
+ * 路径消费与展示的锚，形态非法（含穿越片段）的簿记整条拒收。
+ */
+const PI_SESSION_ID_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/
+
+/** 摘要单 turn（D4 算法产出：user 原文 + agent 最后一段文本；agent null = 该 turn 以工具调用结束）。 */
+export interface ArchiveLedgerTurn { // oe-exempt:20261020:framework:SDK 契约接口——跨进程/跨包协议载体，接口先立、单实现常态
+  user: string
+  agent: string | null
+}
+
+/**
+ * 归档簿记消费子集（D3 schema 的本包视角）。仅声明本域消费字段——rawBytes/
+ * codec/sha256 等压缩侧字段不进（extension 侧不消费压缩体，D7：命中归档
+ * session 时不读压缩体）。
+ */
+export interface ArchiveLedgerEntry { // oe-exempt:20261020:framework:SDK 契约接口——跨进程/跨包协议载体，接口先立、单实现常态
+  /** 簿记文件绝对路径（`archive/<encodeCwd>/<原主文件名>.archive.json`） */
+  ledgerPath: string
+  sessionId: string
+  /** 归档时从明文 JSONL 提取的名称（免解压名称数据源，D3——名称片段匹配的键之一） */
+  name?: string
+  /** staging（搬移完成、摘要/压缩未完成）| archived（终态，摘要已入簿记） */
+  status: 'staging' | 'archived'
+  /** 摘要 turns；staging 期缺省 null（归档态返回走占位文案） */
+  summary: ArchiveLedgerTurn[] | null
+  /** 原工作目录（簿记可选字段，展示备用） */
+  cwd?: string
+  /** 归档时间（ISO 字符串，消歧展示用） */
+  archivedAt?: string
+  /** 簿记文件 mtime（ms，多命中排序键——簿记终态原子重写时间即归档完成时间） */
+  mtime: number
+}
+
+/** summary 字段的解析结果：turns 数组 / null / 非法（undefined）。 */
+function parseSummary(raw: unknown): ArchiveLedgerTurn[] | null | undefined {
+  if (raw === null) return null
+  // raw 非 null 已由上一行保证（summary 合法形态恰为 turns 数组或显式 null），此处只需挡非对象。
+  if (typeof raw !== 'object') return undefined
+  const turnsRaw = (raw as Record<string, unknown>).turns
+  if (!Array.isArray(turnsRaw)) return undefined
+  const turns: ArchiveLedgerTurn[] = []
+  for (const t of turnsRaw) {
+    if (typeof t !== 'object' || t === null) return undefined
+    const obj = t as Record<string, unknown>
+    if (typeof obj.user !== 'string') return undefined
+    if (obj.agent !== null && typeof obj.agent !== 'string') return undefined
+    turns.push({ user: obj.user, agent: obj.agent as string | null })
+  }
+  return turns
+}
+
+/**
+ * 解析簿记 JSON 文本（D3 消费子集）。非法形态返回 undefined 整条拒收：
+ * sessionId 缺失/形态非法、status 词表外、summary 结构非法——坏簿记不中断
+ * 扫描（调用方跳过），与 scanJsonlRecursive 的容错哲学一致。
+ */
+export function parseArchiveLedgerText(text: string): Omit<ArchiveLedgerEntry, 'ledgerPath' | 'mtime'> | undefined {
+  let raw: unknown
+  try {
+    raw = JSON.parse(text)
+  } catch {
+    return undefined
+  }
+  if (typeof raw !== 'object' || raw === null) return undefined
+  const obj = raw as Record<string, unknown>
+  if (typeof obj.sessionId !== 'string' || !PI_SESSION_ID_PATTERN.test(obj.sessionId)) {
+    return undefined
+  }
+  if (obj.status !== 'staging' && obj.status !== 'archived') return undefined
+  const summary = parseSummary(obj.summary)
+  if (summary === undefined) return undefined
+  const out: Omit<ArchiveLedgerEntry, 'ledgerPath' | 'mtime'> = {
+    sessionId: obj.sessionId,
+    status: obj.status,
+    summary,
+  }
+  if (typeof obj.name === 'string' && obj.name.length > 0) out.name = obj.name
+  if (typeof obj.cwd === 'string' && obj.cwd.length > 0) out.cwd = obj.cwd
+  if (typeof obj.archivedAt === 'string' && obj.archivedAt.length > 0) out.archivedAt = obj.archivedAt
+  return out
+}
+
+/**
+ * 归档根扫描时整体跳过的子目录名：`assets/` 是附件三目录区（D1 映射表），
+ * 体积可达归档单元的大头且无簿记，递归进去只耗 IO。
+ */
+const SKIP_DIRS_ARCHIVE = new Set(['assets'])
+
+/**
+ * 递归扫描归档根下全部 `.archive.json` 簿记并解析（D7 独立簿记收集器）。
+ * 只收 `.archive.json` 后缀——`.jsonl`（staging 明文主文件）与 `.restoring`
+ * （恢复中簿记）天然排除。单个簿记读/解析失败跳过不中断（容错）。根不存在/
+ * 无权限 → 空数组，不抛错（roots.ts 单根失败契约）。
+ */
+export async function scanArchiveLedgers(archiveRoot: string): Promise<ArchiveLedgerEntry[]> {
+  const results: ArchiveLedgerEntry[] = []
+
+  async function walk(currentDir: string): Promise<void> {
+    let entries: Dirent[]
+    try {
+      entries = await readdir(currentDir, { withFileTypes: true })
+    } catch {
+      return // 目录不存在/无权限 → 静默返回（容错，同 scanJsonlRecursive）
+    }
+    for (const entry of entries) {
+      const full = join(currentDir, entry.name)
+      if (entry.isDirectory()) {
+        if (SKIP_DIRS_ARCHIVE.has(entry.name)) continue
+        await walk(full)
+      } else if (entry.isFile() && entry.name.endsWith('.archive.json')) {
+        let text: string
+        try {
+          text = await readFile(full, 'utf8')
+        } catch {
+          continue // 并发删除/不可读 → 跳过该簿记
+        }
+        const parsed = parseArchiveLedgerText(text)
+        if (parsed === undefined) continue // 坏簿记跳过
+        try {
+          const s = await stat(full)
+          results.push({ ...parsed, ledgerPath: full, mtime: s.mtimeMs })
+        } catch {
+          continue
+        }
+      }
+    }
+  }
+
+  await walk(archiveRoot)
+  return results
+}
+
+// ============================================================
+// 归档态渲染（D7 返回形态——硬契约：agent 必须能区分摘要与完整历史）
+// ============================================================
+
+/** 归档态头部标注（D7 字面契约）。 */
+const ARCHIVED_HEADER = '状态: 已归档 (archived) — 完整内容已压缩离线，以下仅为摘要'
+
+/** staging 态头部标注（V10：头部 + 占位句 + 名称/id 元数据）。 */
+const STAGING_HEADER = '状态: 已归档 (staging) — 摘要生成中，请稍后再查'
+
+/** 尾注恢复指引（D7 字面契约）。 */
+const RESTORE_NOTE = '注: 如需完整历史，请让用户在归档列表中恢复该会话。'
+
+/** 纯图片/附件 user 消息的占位（D4：空串 user 文本，D11 同款占位语义）。 */
+const USER_ATTACHMENT_PLACEHOLDER = '[图片/附件消息]'
+
+/** turn 无 agent 文本的占位（D4：agent null = 以工具调用结束）。 */
+const AGENT_NO_TEXT_PLACEHOLDER = '（此 turn 以工具调用结束，无文本回复）'
+
+/**
+ * 渲染归档态返回正文（纯函数，两态）：
+ *
+ * - archived：头部标注 + 摘要 turns（`── turn N ──` 分隔，user / assistant (摘要)
+ *   两行，两类占位规则同 D11）+ 尾注恢复指引——**不含任何完整历史内容**
+ *   （turns 只来自簿记 summary，agent 可区分摘要与完整历史的硬契约）。
+ * - staging：头部（staging 标注）+ 名称/id 元数据 + 尾注；无摘要可渲染。
+ */
+export function formatArchivedText(entry: ArchiveLedgerEntry): string {
+  const lines: string[] = []
+  if (entry.status === 'staging') {
+    lines.push(`[session-reader] session: ${entry.name ?? entry.sessionId}（id: ${entry.sessionId}）`)
+    lines.push(STAGING_HEADER)
+    lines.push(RESTORE_NOTE)
+    return lines.join('\n')
+  }
+  lines.push(`[session-reader] session: ${entry.name ?? entry.sessionId}`)
+  lines.push(ARCHIVED_HEADER)
+  const turns = entry.summary ?? []
+  turns.forEach((t, i) => {
+    lines.push(`── turn ${i + 1} ──`)
+    lines.push(`user: ${t.user.length > 0 ? t.user : USER_ATTACHMENT_PLACEHOLDER}`)
+    lines.push(`assistant (摘要): ${t.agent ?? AGENT_NO_TEXT_PLACEHOLDER}`)
+  })
+  lines.push(RESTORE_NOTE)
+  return lines.join('\n')
+}
+
+/** 归档多命中消歧文案（F2 同构：列候选 + 👉 更精确重试，不抛错）。 */
+export function formatArchivedDisambiguation(query: string, entries: ArchiveLedgerEntry[]): string {
+  // mtime 倒序（最新归档在前，与 find 排序口径一致）
+  const sorted = [...entries].sort((a, b) => b.mtime - a.mtime)
+  const lines = [`多个归档 session 匹配 "${query}"，按归档时间倒序：`]
+  for (const e of sorted) {
+    const when = e.archivedAt !== undefined ? `，归档于 ${e.archivedAt}` : ''
+    lines.push(`  - ${e.name ?? '(未命名)'}（id: ${e.sessionId}${when}）`)
+  }
+  lines.push('👉 用完整 session id 或更长的名称片段重试（归档 session 直接用 session 参数引用，返回摘要）。')
+  return lines.join('\n')
+}