@zhushanwen/pi-session-reader 0.12.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-session-reader",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "type": "module",
   "main": "index.ts",
   "taiji": {
@@ -16,7 +16,7 @@
     "pi-package"
   ],
   "dependencies": {
-    "@zhushanwen/extension-protocol": "0.22.0",
+    "@zhushanwen/extension-protocol": "0.23.0",
     "@zhushanwen/pi-ext-guards": "0.5.0",
     "@zhushanwen/pi-extension-logger": "0.6.2",
     "@zhushanwen/session-core": "0.12.0",
@@ -25,7 +25,7 @@
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.9",
     "vitest": "^4.1.8",
-    "@zhushanwen/subagent-core": "1.6.0"
+    "@zhushanwen/subagent-core": "1.6.1"
   },
   "files": [
     "index.ts",

package/src/__tests__/archive-ledger.test.ts

@@ -0,0 +1,447 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { tmpdir } from 'node:os'
+import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises'
+import { join, dirname } from 'node:path'
+import {
+  parseArchiveLedgerText,
+  scanArchiveLedgers,
+  formatArchivedText,
+  formatArchivedDisambiguation,
+  resolveArchiveDir,
+  type ArchiveLedgerEntry,
+} from '../discovery/archive-ledger.js'
+import { resolveSessionRoots } from '../discovery/roots.js'
+import { handleSessionRead } from '../tool-handler.js'
+import { FIX_E6 } from './fixtures.js'
+
+/**
+ * [session-archive D7] session-reader 归档根感知测试：簿记收集器（收 .archive.json
+ * 不收 .jsonl / 字段解析）+ 第五根「存在才纳入」+ 归档态返回形态（头部标注 /
+ * 摘要 turns / 尾注 / staging 占位）+ 无匹配路径回归。
+ *
+ * 全部用例数据 = mkdtemp 自建自删的最小归档目录（不触真实数据目录，测试防线纪律）。
+ */
+
+/** 真实形态的 cwd 编码目录名（encodeCwd：`--` 开头 `--` 结尾） */
+const SLUG = '--Users-foo--'
+
+/** 第二归档条目 id（多命中消歧用，合法 uuid 形态） */
+const SID2 = '0aaaaaaa-bbbb-7ccc-dddd-0000000000a2'
+
+/** 完整 archived 簿记样本（D3 schema 全字段；overrides 覆盖单测变化点）。 */
+function archivedLedger(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+  return {
+    sessionId: FIX_E6,
+    name: 'v0.10 renderer 重构',
+    originalFile: '2026-10-19T10-00-00_abc.jsonl',
+    cwd: '/Users/foo/proj',
+    archivedAt: '2026-10-19T12:00:00.000Z',
+    rawBytes: 1000,
+    compressedBytes: 200,
+    codec: 'zstd-3',
+    status: 'archived',
+    sha256: 'deadbeef',
+    summary: {
+      turns: [
+        { user: 'v0.10 的 renderer 重构开始，先出分层方案。', agent: '六层分层：Shell / Workspace。' },
+        { user: '', agent: null },
+      ],
+    },
+    ...overrides,
+  }
+}
+
+/** 写一份归档簿记（archive/<slug>/<base>.archive.json），返回其绝对路径。 */
+async function writeLedger(
+  agentDir: string,
+  base: string,
+  ledger: Record<string, unknown>,
+  slug = SLUG,
+): Promise<string> {
+  const dir = join(agentDir, 'archive', slug)
+  await mkdir(dir, { recursive: true })
+  const path = join(dir, `${base}.archive.json`)
+  await writeFile(path, JSON.stringify(ledger), 'utf8')
+  return path
+}
+
+/** 写 .jsonl fixture（父目录不存在自建），默认合法 session header。 */
+async function writeJsonl(path: string, content = '{"type":"session","id":"x"}\n'): Promise<void> {
+  await mkdir(dirname(path), { recursive: true })
+  await writeFile(path, content)
+}
+
+/** 归档条目（渲染/消歧单测的直造形态，绕过 fs）。 */
+function entry(overrides: Partial<ArchiveLedgerEntry> = {}): ArchiveLedgerEntry {
+  return {
+    ledgerPath: '/tmp/agent/archive/--Users-foo--/a.archive.json',
+    sessionId: FIX_E6,
+    name: 'v0.10 renderer 重构',
+    status: 'archived',
+    summary: [
+      { user: '先出分层方案。', agent: '六层分层。' },
+      { user: '', agent: null },
+    ],
+    archivedAt: '2026-10-19T12:00:00.000Z',
+    mtime: 1_000,
+    ...overrides,
+  }
+}
+
+// ============================================================
+// 簿记解析（parseArchiveLedgerText：字段解析 / 非法整条拒收）
+// ============================================================
+
+describe('parseArchiveLedgerText（D3 消费子集）', () => {
+  it('合法 archived 簿记解析全部消费字段', () => {
+    const parsed = parseArchiveLedgerText(JSON.stringify(archivedLedger()))
+    expect(parsed).toBeDefined()
+    expect(parsed!.sessionId).toBe(FIX_E6)
+    expect(parsed!.name).toBe('v0.10 renderer 重构')
+    expect(parsed!.status).toBe('archived')
+    expect(parsed!.summary).toEqual([
+      { user: 'v0.10 的 renderer 重构开始，先出分层方案。', agent: '六层分层：Shell / Workspace。' },
+      { user: '', agent: null },
+    ])
+    expect(parsed!.cwd).toBe('/Users/foo/proj')
+    expect(parsed!.archivedAt).toBe('2026-10-19T12:00:00.000Z')
+  })
+
+  it('staging 簿记：summary null + name 缺省可选', () => {
+    const parsed = parseArchiveLedgerText(
+      JSON.stringify(archivedLedger({ status: 'staging', summary: null, name: undefined })),
+    )
+    expect(parsed).toBeDefined()
+    expect(parsed!.status).toBe('staging')
+    expect(parsed!.summary).toBeNull()
+    expect(parsed!.name).toBeUndefined()
+  })
+
+  it('非法形态整条拒收（undefined）：坏 JSON / 缺 sessionId / id 形态非法 / status 词表外 / summary 结构非法', () => {
+    expect(parseArchiveLedgerText('{not json')).toBeUndefined()
+    expect(parseArchiveLedgerText(JSON.stringify({ status: 'archived', summary: null }))).toBeUndefined()
+    // btw 虚拟 id 冒号形态（禁 `:`）拒收
+    expect(
+      parseArchiveLedgerText(JSON.stringify(archivedLedger({ sessionId: 'btw:0aaa' }))),
+    ).toBeUndefined()
+    expect(
+      parseArchiveLedgerText(JSON.stringify(archivedLedger({ status: 'restoring' }))),
+    ).toBeUndefined()
+    // summary 非 null 非 { turns } / turns 元素 agent 类型非法
+    expect(
+      parseArchiveLedgerText(JSON.stringify(archivedLedger({ summary: { turns: 'x' } }))),
+    ).toBeUndefined()
+    expect(
+      parseArchiveLedgerText(
+        JSON.stringify(
+          archivedLedger({ summary: { turns: [{ user: 'u', agent: 42 }] } }),
+        ),
+      ),
+    ).toBeUndefined()
+  })
+})
+
+// ============================================================
+// 簿记收集器（scanArchiveLedgers：收 .archive.json 不收 .jsonl）
+// ============================================================
+
+describe('scanArchiveLedgers（D7 独立收集契约）', () => {
+  let agentDir: string
+
+  beforeEach(async () => {
+    agentDir = join(await mkdtemp(join(tmpdir(), 'archive-scan-')), 'agent')
+  })
+  afterEach(async () => {
+    await rm(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+  })
+
+  it('收 archive/<encodeCwd>/ 下 .archive.json 并解析字段（含 mtime）', async () => {
+    await writeLedger(agentDir, 'a', archivedLedger())
+    const entries = await scanArchiveLedgers(resolveArchiveDir(agentDir))
+    expect(entries).toHaveLength(1)
+    expect(entries[0]!.sessionId).toBe(FIX_E6)
+    expect(entries[0]!.status).toBe('archived')
+    expect(entries[0]!.ledgerPath.endsWith(join('archive', SLUG, 'a.archive.json'))).toBe(true)
+    expect(entries[0]!.mtime).toBeGreaterThan(0)
+  })
+
+  it('不收 .jsonl：staging 明文主文件不进收集（硬契约——收了会被当在场 session）', async () => {
+    await writeLedger(agentDir, 'a', archivedLedger({ status: 'staging', summary: null }))
+    // staging 期归档目录内的明文主文件 + 压缩体
+    await writeJsonl(join(agentDir, 'archive', SLUG, '2026-10-19T10-00-00_abc.jsonl'))
+    await writeJsonl(join(agentDir, 'archive', SLUG, '2026-10-19T10-00-00_abc.jsonl.zst'), 'x')
+    const entries = await scanArchiveLedgers(resolveArchiveDir(agentDir))
+    expect(entries).toHaveLength(1)
+    expect(entries[0]!.ledgerPath.endsWith('.archive.json')).toBe(true)
+  })
+
+  it('.restoring 后缀簿记不收（恢复中，D9 不在列表）', async () => {
+    const path = await writeLedger(agentDir, 'a', archivedLedger())
+    const restoringPath = path.replace(/\.archive\.json$/, '.restoring')
+    await writeFile(restoringPath, JSON.stringify(archivedLedger()), 'utf8')
+    const entries = await scanArchiveLedgers(resolveArchiveDir(agentDir))
+    expect(entries).toHaveLength(1)
+    expect(entries[0]!.ledgerPath).toBe(path)
+  })
+
+  it('assets 子目录不递归（附件区无簿记，只耗 IO）；深层簿记照收', async () => {
+    await writeLedger(agentDir, 'a', archivedLedger())
+    await mkdir(join(agentDir, 'archive', SLUG, 'assets', FIX_E6, 'attachments'), { recursive: true })
+    await writeFile(
+      join(agentDir, 'archive', SLUG, 'assets', FIX_E6, 'attachments', 'img.png'),
+      'x',
+    )
+    const entries = await scanArchiveLedgers(resolveArchiveDir(agentDir))
+    expect(entries).toHaveLength(1)
+  })
+
+  it('坏簿记跳过不中断（坏 JSON / 词表外 status 的条目丢弃，其余照收）', async () => {
+    await writeLedger(agentDir, 'a', archivedLedger())
+    await writeLedger(agentDir, 'b', archivedLedger({ sessionId: SID2, status: 'bogus' }))
+    const dir = join(agentDir, 'archive', SLUG)
+    await writeFile(join(dir, 'c.archive.json'), '{broken', 'utf8')
+    const entries = await scanArchiveLedgers(resolveArchiveDir(agentDir))
+    expect(entries).toHaveLength(1)
+    expect(entries[0]!.sessionId).toBe(FIX_E6)
+  })
+
+  it('归档根不存在 → 空数组不抛错', async () => {
+    await expect(scanArchiveLedgers(resolveArchiveDir(agentDir))).resolves.toEqual([])
+  })
+})
+
+// ============================================================
+// roots 第五根（存在才纳入 + 收集契约分流）
+// ============================================================
+
+describe('resolveSessionRoots 第五根 archive（存在才纳入）', () => {
+  let agentDir: string
+
+  beforeEach(async () => {
+    agentDir = join(await mkdtemp(join(tmpdir(), 'archive-roots-')), 'agent')
+  })
+  afterEach(async () => {
+    await rm(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+  })
+
+  it('archive 目录不存在 → 根不进返回（现有四根行为零变化，无归档目录环境回归锚）', async () => {
+    const roots = await resolveSessionRoots({ agentDir })
+    expect(roots.map((r) => r.kind)).toEqual(['default', 'legacy', 'subagent'])
+    expect(roots.some((r) => r.kind === 'archive')).toBe(false)
+  })
+
+  it('archive 目录存在 → 第五根纳入：fileCount = 簿记数、files 恒空（不收 .jsonl）、archiveEntries 在场', async () => {
+    await writeLedger(agentDir, 'a', archivedLedger())
+    await writeLedger(agentDir, 'b', archivedLedger({ sessionId: SID2, name: '另一个' }))
+    // staging 明文 .jsonl 不影响 fileCount（不收）
+    await writeJsonl(join(agentDir, 'archive', SLUG, 'plain.jsonl'))
+
+    const roots = await resolveSessionRoots({ agentDir })
+    expect(roots.map((r) => r.kind)).toEqual(['default', 'legacy', 'subagent', 'archive'])
+    const archive = roots.find((r) => r.kind === 'archive')!
+    expect(archive.path).toBe(resolveArchiveDir(agentDir))
+    expect(archive.exists).toBe(true)
+    expect(archive.source).toBe('main')
+    expect(archive.files).toEqual([])
+    expect(archive.fileCount).toBe(2)
+    expect(archive.archiveEntries).toHaveLength(2)
+    expect(typeof archive.scanMs).toBe('number')
+  })
+
+  it('doctor 渲染：archive 根行计数措辞为「N 归档单元」', async () => {
+    await writeLedger(agentDir, 'a', archivedLedger())
+    const r = await handleSessionRead({ action: 'doctor' }, { agentDir })
+    const text = r.content[0]!.text
+    expect(text).toContain('[archive]')
+    expect(text).toContain('1 归档单元')
+  })
+
+  it('同 realpath 去重：更高优先级根与归档目录同路径时 archive 根 dedupedInto，不重复成根', async () => {
+    // live 信号直接指向归档目录（basename 非 encodeCwd 形态 → 取自身，字面同路径
+    // realpath 必同）；优先级 live > archive，归档根不实扫簿记、标注归属——与普通根
+    // realpath 去重同构（§7B 要点 4）。回归锚：archive 分支漏 kept 检查时本用例红
+    //（out 出现两条同路径实扫根，且 byRealPath 被 archive 覆盖致 dedupedInto 失效）
+    await writeLedger(agentDir, 'a', archivedLedger())
+    const archiveDir = resolveArchiveDir(agentDir)
+
+    const roots = await resolveSessionRoots({ agentDir, liveSessionDir: archiveDir })
+    expect(roots.map((r) => r.kind)).toEqual(['live', 'default', 'legacy', 'subagent', 'archive'])
+    const archive = roots.find((r) => r.kind === 'archive')!
+    expect(archive.path).toBe(archiveDir)
+    expect(archive.dedupedInto).toBe('live')
+    // 被去重根不产生扫描统计，簿记收集未执行（与普通根去重同构）
+    expect(archive.fileCount).toBeUndefined()
+    expect(archive.scanMs).toBeUndefined()
+    expect(archive.archiveEntries).toBeUndefined()
+    // 同路径全列表只保留一个实扫根（= 更高优先级的 live），簿记不重复计数
+    const scannedAtSamePath = roots.filter(
+      (r) => r.path === archiveDir && r.dedupedInto === undefined,
+    )
+    expect(scannedAtSamePath).toHaveLength(1)
+    expect(scannedAtSamePath[0]!.kind).toBe('live')
+  })
+})
+
+// ============================================================
+// 归档态返回形态（handleSessionRead 集成：D7 硬契约）
+// ============================================================
+
+describe('归档态返回形态（片段命中归档回退）', () => {
+  let agentDir: string
+
+  beforeEach(async () => {
+    agentDir = join(await mkdtemp(join(tmpdir(), 'archive-read-')), 'agent')
+  })
+  afterEach(async () => {
+    await rm(agentDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 })
+  })
+
+  it('名称片段命中归档：头部标注 + 摘要 turns + 尾注恢复指引（§5.1 agent 引用样例形态）', async () => {
+    await writeLedger(agentDir, 'a', archivedLedger())
+    const r = await handleSessionRead(
+      { action: 'outline', session: 'renderer 重构' },
+      { agentDir },
+    )
+    const text = r.content[0]!.text
+    expect(text).toContain('[session-reader] session: v0.10 renderer 重构')
+    expect(text).toContain('状态: 已归档 (archived) — 完整内容已压缩离线，以下仅为摘要')
+    expect(text).toContain('── turn 1 ──')
+    expect(text).toContain('user: v0.10 的 renderer 重构开始，先出分层方案。')
+    expect(text).toContain('assistant (摘要): 六层分层：Shell / Workspace。')
+    expect(text).toContain('注: 如需完整历史，请让用户在归档列表中恢复该会话。')
+    // details 程序化标记：archived: true + 簿记条目
+    const d = r.details as { archived: boolean; entry: { sessionId: string } }
+    expect(d.archived).toBe(true)
+    expect(d.entry.sessionId).toBe(FIX_E6)
+  })
+
+  it('摘要占位规则：agent null → 无文本占位；user 空串 → 图片/附件占位', async () => {
+    await writeLedger(agentDir, 'a', archivedLedger())
+    const r = await handleSessionRead({ action: 'outline', session: 'renderer' }, { agentDir })
+    const text = r.content[0]!.text
+    expect(text).toContain('── turn 2 ──')
+    expect(text).toContain('user: [图片/附件消息]')
+    expect(text).toContain('assistant (摘要): （此 turn 以工具调用结束，无文本回复）')
+  })
+
+  it('staging 态（summary null）：头部 staging 标注 + 「摘要生成中」+ 名称/id 元数据', async () => {
+    await writeLedger(agentDir, 'a', archivedLedger({ status: 'staging', summary: null }))
+    const r = await handleSessionRead({ action: 'outline', session: 'renderer' }, { agentDir })
+    const text = r.content[0]!.text
+    expect(text).toContain('状态: 已归档 (staging) — 摘要生成中，请稍后再查')
+    expect(text).toContain(`（id: ${FIX_E6}）`)
+    expect(text).toContain('注: 如需完整历史，请让用户在归档列表中恢复该会话。')
+    expect(text).not.toContain('── turn')
+  })
+
+  it('sessionId 片段与归一化形态命中（大写/去连字符）', async () => {
+    await writeLedger(agentDir, 'a', archivedLedger())
+    const byFragment = await handleSessionRead({ action: 'detail', session: 'e6c96', turns: 'T000-T001' }, { agentDir })
+    expect(byFragment.content[0]!.text).toContain('已归档 (archived)')
+    const byNorm = await handleSessionRead(
+      { action: 'outline', session: FIX_E6.replace(/-/g, '').toUpperCase() },
+      { agentDir },
+    )
+    expect(byNorm.content[0]!.text).toContain('已归档 (archived)')
+  })
+
+  it('staging 明文 .jsonl 不被直读：同 id 明文在归档目录内仍返回归档形态（不读压缩体/明文）', async () => {
+    await writeLedger(agentDir, 'a', archivedLedger())
+    await writeJsonl(
+      join(agentDir, 'archive', SLUG, `${FIX_E6}.jsonl`),
+      `{"type":"session","id":"${FIX_E6}"}\n`,
+    )
+    const r = await handleSessionRead({ action: 'outline', session: 'e6c96' }, { agentDir })
+    expect(r.content[0]!.text).toContain('已归档 (archived)')
+  })
+
+  it('多归档命中 → 归档消歧列表（列候选 + 👉，不抛错）', async () => {
+    await writeLedger(agentDir, 'a', archivedLedger())
+    await writeLedger(
+      agentDir,
+      'b',
+      archivedLedger({ sessionId: SID2, name: 'v0.11 renderer 重构' }),
+    )
+    const r = await handleSessionRead({ action: 'outline', session: 'renderer' }, { agentDir })
+    const text = r.content[0]!.text
+    expect(text).toContain('多个归档 session 匹配 "renderer"')
+    expect(text).toContain(`v0.10 renderer 重构（id: ${FIX_E6}`)
+    expect(text).toContain(`v0.11 renderer 重构（id: ${SID2}`)
+    expect(text).toContain('👉')
+  })
+
+  it('在场优先：同片段在场 session 命中时返回在场内容，不走归档回退', async () => {
+    await writeJsonl(
+      join(agentDir, 'sessions', SLUG, `${FIX_E6}.jsonl`),
+      `{"type":"session","id":"${FIX_E6}"}\n`,
+    )
+    await writeLedger(agentDir, 'a', archivedLedger({ name: 'e6c96 主题' }))
+    const r = await handleSessionRead({ action: 'outline', session: 'e6c96' }, { agentDir })
+    expect(r.details).not.toHaveProperty('archived')
+    expect(r.content[0]!.text).not.toContain('已归档')
+  })
+
+  it('result action 命中归档：统一归档态摘要（批量链路的单 id 形态）', async () => {
+    await writeLedger(agentDir, 'a', archivedLedger())
+    const r = await handleSessionRead({ action: 'result', session: 'renderer' }, { agentDir })
+    expect(r.content[0]!.text).toContain('已归档 (archived)')
+    expect((r.details as { archived: boolean }).archived).toBe(true)
+  })
+
+  it('无匹配路径回归：无 archive 目录 + 在场零命中 → F1 照旧（无归档提示行、无 [archive] 根行）', async () => {
+    await expect(
+      handleSessionRead({ action: 'outline', session: 'zzz-nope' }, { agentDir }),
+    ).rejects.toThrow('无匹配 session')
+    await expect(
+      handleSessionRead({ action: 'outline', session: 'zzz-nope' }, { agentDir }),
+    ).rejects.toThrow(/自检（发现层，只陈述事实）：/)
+  })
+
+  it('F1 归档指引（条件行）：归档根存在且簿记非空 → find 零匹配文案含「目标可能已归档」', async () => {
+    await writeLedger(agentDir, 'a', archivedLedger())
+    const r = await handleSessionRead({ action: 'find', query: 'zzz-nope' }, { agentDir })
+    const text = r.content[0]!.text
+    expect(text).toContain('无匹配 session')
+    expect(text).toContain('目标可能已归档')
+    expect(text).toContain('[archive]')
+  })
+
+  it('F1 归档指引不出现：归档根存在但簿记为空（空目录）', async () => {
+    await mkdir(join(agentDir, 'archive', SLUG), { recursive: true })
+    const r = await handleSessionRead({ action: 'find', query: 'zzz-nope' }, { agentDir })
+    expect(r.content[0]!.text).not.toContain('目标可能已归档')
+  })
+})
+
+// ============================================================
+// 归档态渲染纯函数（formatArchivedText / formatArchivedDisambiguation 直测）
+// ============================================================
+
+describe('formatArchivedText（两态渲染纯函数）', () => {
+  it('无 name 时头行回退 sessionId', () => {
+    const text = formatArchivedText(entry({ name: undefined }))
+    expect(text).toContain(`[session-reader] session: ${FIX_E6}`)
+  })
+
+  it('archived 态无摘要 turns（summary 空数组）只出头部与尾注', () => {
+    const text = formatArchivedText(entry({ summary: [] }))
+    expect(text).toContain('已归档 (archived)')
+    expect(text).not.toContain('── turn')
+    expect(text).toContain('注: 如需完整历史')
+  })
+})
+
+describe('formatArchivedDisambiguation（多命中消歧）', () => {
+  it('按 mtime 倒序列候选并携带归档时间', () => {
+    const text = formatArchivedDisambiguation('q', [
+      entry({ mtime: 1, name: '旧条目' }),
+      entry({ mtime: 2, sessionId: SID2, name: '新条目' }),
+    ])
+    const newIdx = text.indexOf('新条目')
+    const oldIdx = text.indexOf('旧条目')
+    expect(newIdx).toBeGreaterThan(-1)
+    expect(oldIdx).toBeGreaterThan(newIdx)
+    expect(text).toContain(`id: ${SID2}`)
+    expect(text).toContain('归档于 2026-10-19T12:00:00.000Z')
+  })
+})

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')
+}

package/src/discovery/archive-match.ts

@@ -0,0 +1,84 @@
+/**
+ * [session-archive D7] 归档片段匹配编排 + 归档态 ToolResult 构造。
+ *
+ * 独立模块的原因（不并入 archive-ledger.ts）：匹配复用 find.ts 的
+ * normalizeUuidKey（uuid 归一化口径单一源，§6.7 子决策 1），而 archive-ledger
+ * 被 roots.ts 单向消费——并入会构成 archive-ledger→find→roots→archive-ledger
+ * 的值级循环 import。本模块依赖方向：find（纯函数）+ archive-ledger（扫描/
+ * 渲染）+ tool-handler（仅 type import，同 tool-format 先例），无环。
+ *
+ * 消费方：tool-handler 的 resolveByFragment（归档回退层）与 result-action
+ * （archivedResult）、tool-format 的 resolveNonOkResult（multi 消歧与归档态的
+ * 统一 non-ok 分发）。
+ */
+import { normalizeUuidKey } from './find.js'
+import {
+  formatArchivedDisambiguation,
+  formatArchivedText,
+  resolveArchiveDir,
+  scanArchiveLedgers,
+  type ArchiveLedgerEntry,
+} from './archive-ledger.js'
+import type { ToolResult } from '../tool-handler.js'
+
+/** 归档命中的两支形态（ResolveResult 对应支的结构子集）。 */
+export type ArchiveResolve =
+  | { kind: 'archived'; archive: ArchiveLedgerEntry }
+  | { kind: 'archived-multi'; query: string; entries: ArchiveLedgerEntry[] }
+
+/**
+ * 归档簿记片段匹配：sessionId（等值/子串/归一化，复用 find 的 normalizeUuidKey
+ * 两级口径）+ 簿记 name（名称片段的免解压数据源，D3）。归档根不存在/无簿记 →
+ * 空数组（无匹配路径零变化）。
+ */
+export async function matchArchiveLedgers(
+  query: string,
+  agentDir: string,
+): Promise<ArchiveLedgerEntry[]> {
+  const archiveRoot = resolveArchiveDir(agentDir)
+  const entries = await scanArchiveLedgers(archiveRoot)
+  const nq = normalizeUuidKey(query)
+  return entries.filter((e) => {
+    if (e.sessionId === query) return true
+    if (e.sessionId.includes(query)) return true
+    if (nq.length > 0 && normalizeUuidKey(e.sessionId).includes(nq)) return true
+    return e.name !== undefined && e.name.includes(query)
+  })
+}
+
+/**
+ * 归档回退层的解析入口（resolveByFragment 在场零命中后调用）：单命中 →
+ * archived；多命中 → archived-multi（消歧）；无簿记命中 → undefined（落 F1）。
+ */
+export async function resolveArchiveFragment(
+  query: string,
+  agentDir: string,
+): Promise<ArchiveResolve | undefined> {
+  const hits = await matchArchiveLedgers(query, agentDir)
+  if (hits.length === 1) {
+    return { kind: 'archived', archive: hits[0]! }
+  }
+  if (hits.length > 1) {
+    return { kind: 'archived-multi', query, entries: hits }
+  }
+  return undefined
+}
+
+/**
+ * 归档命中的统一 ToolResult（单条 + 多命中消歧）：正文 = archive-ledger 两态
+ * 渲染（头部标注 + 摘要 turns + 尾注 / staging 占位），不读压缩体（D7）。details
+ * 顶层 `archived: true` 供程序化消费方一眼区分归档态与常规结果。
+ */
+export function archivedResult(resolved: ArchiveResolve): ToolResult {
+  return resolved.kind === 'archived'
+    ? {
+        content: [{ type: 'text', text: formatArchivedText(resolved.archive) }],
+        details: { archived: true, entry: resolved.archive },
+      }
+    : {
+        content: [
+          { type: 'text', text: formatArchivedDisambiguation(resolved.query, resolved.entries) },
+        ],
+        details: { archived: true, candidates: resolved.entries },
+      }
+}

package/src/discovery/find.ts

@@ -354,6 +354,9 @@ async function loadTitleIndex(ctx: MetadataContext): Promise<Map<string, Session
     if (root.dedupedInto !== undefined) continue
     if (!root.exists) continue // guard：仅对存在的根调用
     if (!isFlatRoot(root)) continue // 策略 ②：含子目录根跳过 listAll
+    // [session-archive D7] 归档根不是标题数据源（listAll 只看一层 .jsonl，归档根
+    // 第一层是 encodeCwd 目录恒空手而归）——跳过多余调用
+    if (root.kind === 'archive') continue
     push(root.path)
   }
 

package/src/discovery/roots.ts

@@ -2,6 +2,11 @@ import { readdir, stat, realpath } from 'node:fs/promises'
 import type { Dirent } from 'node:fs'
 import { join, basename, dirname } from 'node:path'
 import { performance } from 'node:perf_hooks'
+import {
+  resolveArchiveDir,
+  scanArchiveLedgers,
+  type ArchiveLedgerEntry,
+} from './archive-ledger.js'
 
 /**
  * M2 discovery 发现层：文件系统扫描（design §3.3 D-5 首行扫描策略的文件定位部分）。
@@ -33,10 +38,10 @@ export interface SessionRootSignals {
   liveSessionDir?: string
 }
 
-/** 候选根来源标签；kind 优先级 live > default > legacy > subagent（§6.1 信号序） */
-export type SessionRootKind = 'live' | 'default' | 'legacy' | 'subagent'
+/** 候选根来源标签；kind 优先级 live > default > legacy > subagent > archive（§6.1 信号序 + D7 追加） */
+export type SessionRootKind = 'live' | 'default' | 'legacy' | 'subagent' | 'archive'
 
-/** main 源 = 主 session 根（live/default/legacy）；subagent 源 = subagent 会话根 */
+/** main 源 = 主 session 根（live/default/legacy/archive）；subagent 源 = subagent 会话根 */
 export type SessionRootSource = 'main' | 'subagent'
 
 /** 候选根（含扫描结果）。去重后每 kind 至多一个根，kind 即 doctor 表行键。 */
@@ -53,6 +58,12 @@ export interface SessionRoot {
   scanMs?: number
   /** 扫描所得文件列表（design §7B 要点 8「本就在返回值里」）；未扫描时空数组 */
   files: SessionFileMeta[]
+  /**
+   * 归档根（kind='archive'）专属：簿记收集器产出（D7 独立收集契约——收
+   * `.archive.json` 不收 `.jsonl`，故 files 恒空、fileCount = 簿记数）。
+   * 其余根不挂此字段。
+   */
+  archiveEntries?: ArchiveLedgerEntry[]
   /**
    * realpath 与更高优先级根同路径 → 指向保留根的 kind，本根未扫描（doctor 渲染
    * 「与 N 同路径，已去重」注记的依据，§7B 要点 4）。
@@ -140,7 +151,8 @@ export function normalizeLiveSessionDir(liveSessionDir: string): string {
 
 /**
  * 从信号包推导候选根（未扫描骨架），数组序 = 优先级序（§6.1）。
- * `[subagent]` 恒在（常量推导）；`[live]` 仅在信号存在时出现。
+ * `[subagent]` 恒在（常量推导）；`[live]` 仅在信号存在时出现；`[archive]` 恒在
+ * 骨架中（D7 第五根，纳入与否由 resolveSessionRoots 按「存在才扫」判定）。
  */
 function sessionRootSpecs(signals: SessionRootSignals): SessionRoot[] {
   // 空 agentDir 防御：派生式会退化为 cwd 相对路径（'sessions'/'./sessions'），可能扫到
@@ -156,6 +168,10 @@ function sessionRootSpecs(signals: SessionRootSignals): SessionRoot[] {
   // 扫描在 sid 分区内定向探 subagents/sessions/（scanStoreSubagentJsonl）；旧布局
   // `<agentDir>/subagents` 不再读（设计裁决 D6：存量原位保留、不可见）。
   specs.push(spec('subagent', 'subagent', resolveSessionStoreRoot(signals.agentDir)))
+  // [session-archive D7] 第五根 = 归档根（`<agentDir>/archive`，镜像 sessions 平级布局）。
+  // 收集契约与四根不同：不收 .jsonl、收 .archive.json 簿记（见 resolveSessionRoots
+  // 分流与 scanArchiveLedgers）；source=main（归档对象是主 session）。
+  specs.push(spec('archive', 'main', resolveArchiveDir(signals.agentDir)))
   return specs
 }
 
@@ -202,11 +218,13 @@ export interface SessionRootScanOptions {
 /**
  * 解析候选根并逐根扫描（design 2026-09-10 §6.1 候选根探测 / §7B 要点 3/4/6）。
  *
- * 优先级 live > default > legacy > subagent；按 realpath 去重：同路径多信号只扫一次，
- * 保留最高优先级 kind 标签，被去重的根以 `dedupedInto` 标注（不产生 fileCount/scanMs）。
- * 逐根扫描：main 源整树递归（跳 workflow-state）；subagent 源 = 存储树定向扫描
- *（[session-store-layout-inversion] 单新根，见 scanStoreSubagentJsonl）。单根失败
- * （不存在/无权限）→ 空结果继续，不抛错（沿用 listXxxSessions 契约）。
+ * 优先级 live > default > legacy > subagent > archive；按 realpath 去重：同路径多信号
+ * 只扫一次，保留最高优先级 kind 标签，被去重的根以 `dedupedInto` 标注（不产生
+ * fileCount/scanMs）。逐根扫描：main 源整树递归（跳 workflow-state）；subagent 源 =
+ * 存储树定向扫描（[session-store-layout-inversion] 单新根，见 scanStoreSubagentJsonl）；
+ * archive 源 = 簿记收集器（[session-archive D7] 收 .archive.json 不收 .jsonl，
+ * **存在才纳入**——目录不存在时该根不进返回列表，对无归档目录的环境零行为变化）。
+ * 单根失败（不存在/无权限）→ 空结果继续，不抛错（沿用 listXxxSessions 契约）。
  *
  * options（u8 追加，全部缺省安全）：`subagents:'stat'` 让 subagent 根只做存在性检查。
  * 无缓存——每次调用实扫（原 u8 cache 注入点已删除，ext-simplify-04 U3；find/F1
@@ -220,6 +238,35 @@ export async function resolveSessionRoots(
   const out: SessionRoot[] = []
   const byRealPath = new Map<string, SessionRoot>()
   for (const candidate of sessionRootSpecs(signals)) {
+    if (candidate.kind === 'archive') {
+      // [session-archive D7] 存在才纳入：目录不存在 → 整根不进返回（备注「目录存在即
+      // 纳入」的逆向——非 taiji/纯 pi 用户无 archive 目录，doctor 表与 F1 自检行零变化）
+      if (!(await pathExists(candidate.path))) continue
+      const key = await safeRealpath(candidate.path)
+      const kept = byRealPath.get(key)
+      if (kept) {
+        // 同 realpath：不扫描，标注归属（与普通根 kept 检查同构——archive kind 优先级
+        // 最低，归档目录与更高优先级根同路径时只保留一根，doctor 表不重复计数；
+        // 漏此检查会既出重复根、又以本根覆盖 byRealPath 致后续根 dedupedInto 失效）
+        out.push({ ...candidate, exists: true, dedupedInto: kept.kind })
+        continue
+      }
+      const t0 = performance.now()
+      const archiveEntries = await scanArchiveLedgers(candidate.path)
+      const scanMs = performance.now() - t0
+      // 归档根不走 scanJsonlRecursive（.jsonl 不收）：files 恒空，fileCount = 簿记数
+      const root: SessionRoot = {
+        ...candidate,
+        exists: true,
+        fileCount: archiveEntries.length,
+        scanMs,
+        files: [],
+        archiveEntries,
+      }
+      byRealPath.set(key, root)
+      out.push(root)
+      continue
+    }
     const key = await safeRealpath(candidate.path)
     const kept = byRealPath.get(key)
     if (kept) {

package/src/doctor.ts

@@ -93,6 +93,9 @@ function renderDoctor(
       // 仅 subagents:'stat' 的 subagent 根（doctor 默认形态）——其余根恒有计数（实扫）；
       // 被去重根已在上方提前返回
       facts.push('未扫描（subagent 根默认不扫，includeSubagents:true 开启）')
+    } else if (r.kind === 'archive') {
+      // [session-archive D7] 归档根计数 = 簿记数（非 .jsonl 文件数，措辞按实名）
+      facts.push(`${r.fileCount} 归档单元`, `扫 ${Math.round(r.scanMs ?? 0)}ms`)
     } else {
       facts.push(`${r.fileCount} 文件`, `扫 ${Math.round(r.scanMs ?? 0)}ms`)
     }

package/src/index.ts

@@ -159,6 +159,9 @@ const guidelines = [
   // zcode 路由（U9）对 LLM 的唯一可见部分：sa-id 输入自动路由，无需任何参数；首遇
   // zcode_* 错误码前先有背景预告。
   'sa- ids route transparently to pi or zcode engine sessions; sess_ prefixed ids are not accepted—use the completion-notice sa- id.',
+  // [session-archive D7] 归档态硬契约的 LLM 侧预告：引用已归档 session 只得摘要
+  //（返回头部显式标注「已归档」），恢复完整历史是用户操作。
+  'Archived sessions return summary-only views (marked 已归档/archived)—for full history, ask the user to restore the session.',
   'Errors carry a 👉 recovery hint—follow it to retry.',
   'Unsure about host environment or session roots? Run action:"doctor".',
 ]

package/src/no-match.ts

@@ -62,6 +62,13 @@ function buildSelfCheckLines(roots: SessionRoot[]): string[] {
       continue
     }
     const count = r.fileCount ?? r.files.length
+    // [session-archive D2 U2] 归档根不计入 find 候选集合计（find 只迭代在场 .jsonl，
+    // 归档根 files 恒空、fileCount = 簿记数——计入则「候选集非空」陈述失真）；
+    // 措辞对齐 doctor 的「N 归档单元」实名（区别于 .jsonl 文件计数）。
+    if (r.kind === 'archive') {
+      lines.push(`  [${r.kind}]`.padEnd(F1_ROOT_LABEL_PAD) + `${r.path}：${count} 归档单元`)
+      continue
+    }
     totalFiles += count
     lines.push(`  [${r.kind}]`.padEnd(F1_ROOT_LABEL_PAD) + `${r.path}：${count} 文件`)
   }
@@ -117,8 +124,15 @@ function formatSuggestionLines(suggestions: NoMatchSuggestion[], query: string):
   return lines
 }
 
-/** ③ 正确做法四条 + ④ 封死 shell 绕行（纯静态文案）。 */
-function guidanceLines(): string[] {
+/**
+ * ③ 正确做法四条 + ④ 封死 shell 绕行（纯静态文案）。
+ *
+ * [session-archive D7] archiveHint：归档根存在且有簿记时由 formatNoMatch 追加第
+ * 五条（目标可能已归档的引用指引）——find 结果不含归档条目，归档引用通道是深读
+ * action 的 session 参数（resolveByFragment 的归档回退层）。无归档目录 → 空数组，
+ * 文案零变化。
+ */
+function guidanceLines(archiveHint: string[] = []): string[] {
   return [
     '',
     '正确做法：',
@@ -126,6 +140,7 @@ function guidanceLines(): string[] {
     `  - 已知文件路径时直接传绝对路径：session_read { action:"outline", session:"<绝对路径>.jsonl" }`,
     `  - 截断/过期 id 用更短前缀：session_read { action:"find", query:"<更短前缀>" }`,
     `  - 想先看环境与根目录状态：session_read { action:"doctor" }`,
+    ...archiveHint,
     '',
     '不要用 shell find/ls/rg 搜 session 目录，不要 cat/read 原始 .jsonl —— session_read 是唯一入口。',
   ]
@@ -150,12 +165,22 @@ function guidanceLines(): string[] {
  * 无「👉 用 recent 看全量」误导指引（recent 候选对写错的 uuid 无自纠价值，§6.7 不采用项）。
  */
 export function formatNoMatch(query: string, roots: SessionRoot[]): string {
+  // [session-archive D7] 归档指引（条件行）：归档根存在且簿记非空才出现——自检行
+  // 已列 [archive] 根计数，此处补「怎么引用」的动作指引，find→深读链路对归档
+  // session 不断链。无归档目录的 roots 不含 archive 根，guidanceLines 零变化。
+  const archiveRoot = roots.find((r) => r.kind === 'archive' && r.dedupedInto === undefined)
+  const archiveHint =
+    archiveRoot !== undefined && (archiveRoot.fileCount ?? 0) > 0
+      ? [
+          `  - 目标可能已归档：直接用 session 参数引用（返回归档摘要），如 session_read { action:"outline", session:"<名称片段或id>" }`,
+        ]
+      : []
   return [
     `无匹配 session："${query}"`,
     '',
     ...buildSelfCheckLines(roots),
     '',
     ...formatSuggestionLines(collectSuggestions(query, roots), query),
-    ...guidanceLines(),
+    ...guidanceLines(archiveHint),
   ].join('\n')
 }

package/src/result-action.ts

@@ -17,6 +17,7 @@
  */
 import type { Entry, ParseResult } from '@zhushanwen/session-core'
 import { textBlockParts } from './core/render.js'
+import { archivedResult } from './discovery/archive-match.js'
 import type { MatchedSession } from './discovery/find.js'
 import { listRecordManifests, type RecordManifest } from './discovery/subagents.js'
 import { err, requireStr, SESSION_ID_PREFIX_LEN, stripHash } from './handler-utils.js'
@@ -208,6 +209,11 @@ export async function doResult(
   for (const id of ids) {
     const resolved = await deps.resolveSessionId(id, 'result', agentDir, params.source, prefetchedManifests)
     if (resolved.kind === 'multi') return deps.disambiguate(resolved.query, resolved.candidates)
+    // [session-archive D7] 片段命中归档 session：完整正文不可读，统一返回归档态摘要
+    //（构造与渲染收敛在 archive-match 的 archivedResult，与 tool-handler 同一出口）
+    if (resolved.kind === 'archived' || resolved.kind === 'archived-multi') {
+      return archivedResult(resolved)
+    }
     const { entries } = await deps.safeParse(resolved.fileName)
     const text = extractFinalAssistantText(entries)
     if (text.length === 0) {

package/src/tool-format.ts

@@ -33,7 +33,8 @@ import {
 import type { Family } from './core/family.js'
 import { SESSION_ID_PREFIX_LEN, rangeLabel } from './handler-utils.js'
 import { formatNoMatch } from './no-match.js'
-import type { ToolResult } from './tool-handler.js'
+import { archivedResult } from './discovery/archive-match.js'
+import type { ResolveResult, ToolResult } from './tool-handler.js'
 
 // 结构化日志通道（zcodeReadErrorMessage 的降级/TOCTOU warn）：getLogger 按名缓存
 // 单例，与 tool-handler 侧调用取同一实例，appendEntry/文件日志行为不变。
@@ -229,6 +230,16 @@ export function disambiguate(query: string, candidates: MatchedSession[]): ToolR
   return { content: [{ type: 'text', text }], details: { ambiguous: true, candidates } }
 }
 
+/**
+ * ResolveResult 非 ok 支的统一分发（[session-archive D7] 归并点）：multi → 既有
+ * F2 消歧；archived / archived-multi → 归档态返回（archive-match 两支渲染，不读
+ * 压缩体）。8 个 do* 的「multi 消歧 + 归档短路」重复分支收敛到本函数单一出口。
+ */
+export function resolveNonOkResult(resolved: Exclude<ResolveResult, { kind: 'ok' }>): ToolResult {
+  if (resolved.kind === 'multi') return disambiguate(resolved.query, resolved.candidates)
+  return archivedResult(resolved)
+}
+
 // ---------------------------------------------------------------------------
 // 文本渲染（content）
 // ---------------------------------------------------------------------------

package/src/tool-handler.ts

@@ -20,8 +20,10 @@
  * 本模块 re-export 供 index.ts 生产消费）。
  *
  * 错误规格 F1-F6：handler 抛 Error（message 含 👉 恢复指引），index.ts 的 execute 闭包
- * 原样传播给 pi——pi-agent-core 只对 execute throw 置 isError:true（返回值里的 isError
- * 字段被丢弃，agent-loop.js:453-483）。handler 可抛（纯逻辑可测）。
+ * 原样传播给 pi——execute throw → agent-loop catch 置 isError:true（pi-agent-core dist/
+ * agent-loop.js executePreparedToolCall，1.0.0 实读 catch :581-588；1.0.0 起正常 return 的
+ * isError 也被尊重——:579 isError: result.isError === true，0.84.4 才硬编码 false——本包
+ * 失败恒走 throw，行为不变）。handler 可抛（纯逻辑可测）。
  * 例外：F2 多匹配与 F1 find 零匹配「不视为错误」，返回消歧/提示结果而非抛错。
  */
 import { existsSync } from 'node:fs'
@@ -38,6 +40,10 @@ import {
   type SessionMetadataEntry,
   type SessionMetadataProvider,
 } from './discovery/find.js'
+import {
+  resolveArchiveFragment,
+  type ArchiveResolve,
+} from './discovery/archive-match.js'
 import { resolveSessionRoots } from './discovery/roots.js'
 import { readSessionHeaderIdSync } from './discovery/session-header.js'
 import { findZcodeEntryAnchor, type ZcodeAnchor } from './discovery/entry-anchor.js'
@@ -122,6 +128,7 @@ import {
   formatZcodeRecordNotFound,
   formatZcodeSessionNotFound,
   isToolResultSummary,
+  resolveNonOkResult,
   zcodeReadErrorMessage,
 } from './tool-format.js'
 import { doDoctor, type SessionReadSignals } from './doctor.js'
@@ -215,6 +222,13 @@ export type ResolveResult =
       zcodeAnchor?: ZcodeAnchor
     }
   | { kind: 'multi'; query: string; candidates: MatchedSession[] }
+  /**
+   * [session-archive D7] 片段命中归档 session（在场零命中后的归档回退层，两支
+   * 形态见 ArchiveResolve）：消费方（各 do* 的 non-ok 分发 resolveNonOkResult /
+   * result-action）统一返回归档态摘要——不读压缩体，头部显式标注归档态
+   * （agent 区分摘要与完整历史的硬契约）。
+   */
+  | ArchiveResolve
 
 // readSessionHeaderIdSync（同步读首行 header 取 id，resolveSessionId 形态①/②消费）
 // 在 discovery/session-header.ts（基座 readFirstJsonlLineSync 的谓词/降级薄包装，G2 单源）。
@@ -467,6 +481,11 @@ async function resolveByRecordId(session: string, agentDir: string, prefetchedMa
  * 形态③：其余片段 → findSessions 透传 source/liveSessionDir 沿用 F1（零匹配）/ F2（多匹配消歧）。
  * liveSessionDir 透传保证片段匹配与 find 同一 roots；F1 自检行同理须含 [live] 根行
  *（否则 [live]≠[default] 环境下自检行看不到最高优先级根，计数失真）。
+ *
+ * [session-archive D7] 归档回退层：在场匹配零命中 → 查归档簿记（archive-match）。
+ * 在场优先保证既有行为零变化（归档 session 不在 sessions/ 扫描范围，「在场零命中」
+ * 与「已归档」对同一 session 互斥成立——D9 不变量 1）；命中归档不走 F1（历史引用
+ * 不断链，D7 方案否决项「agent 完全不可见」）。
  */
 async function resolveByFragment(
   session: string,
@@ -481,6 +500,10 @@ async function resolveByFragment(
   }
   const { matches } = await findSessions(session, agentDir, opts)
   if (matches.length === 0) {
+    // [session-archive D7] 归档回退层：单命中返回归档态、多命中返回归档消歧
+    //（实现与匹配口径在 discovery/archive-match.ts）；无簿记命中落 F1。
+    const archive = await resolveArchiveFragment(session, agentDir)
+    if (archive !== undefined) return archive
     // F1 自检行需要发现层实况：无 options 的 resolveSessionRoots 恒实扫（根扫描无
     // 缓存——doctor 缓存机已删除，ext-simplify-04 U3），与 find 刚完成的扫描同一数据
     // 源（roots.ts 薄包装语义）；信号包同源（liveSessionDir 透传）——findSessions
@@ -719,7 +742,8 @@ async function doFamily(
     undefined,
     liveSessionDir,
   )
-  if (resolved.kind === 'multi') return disambiguate(resolved.query, resolved.candidates)
+  // non-ok 支统一分发（multi 消歧 / 归档态两支，[session-archive D7] 归并点）
+  if (resolved.kind !== 'ok') return resolveNonOkResult(resolved)
 
   // recursive=true：嵌套执行树（U7/U8）
   if (params.recursive) {
@@ -766,7 +790,8 @@ async function doOutline(
     undefined,
     liveSessionDir,
   )
-  if (resolved.kind === 'multi') return disambiguate(resolved.query, resolved.candidates)
+  // non-ok 支统一分发（multi 消歧 / 归档态两支，[session-archive D7] 归并点）
+  if (resolved.kind !== 'ok') return resolveNonOkResult(resolved)
   const { entries, totalBytes, skippedLines } = await loadParsed(resolved, agentDir)
   const tree = buildTreeView(entries)
   const turns = segmentTurns(entries, new Set(tree.leafPath))
@@ -802,7 +827,8 @@ async function doExpand(
     undefined,
     liveSessionDir,
   )
-  if (resolved.kind === 'multi') return disambiguate(resolved.query, resolved.candidates)
+  // non-ok 支统一分发（multi 消歧 / 归档态两支，[session-archive D7] 归并点）
+  if (resolved.kind !== 'ok') return resolveNonOkResult(resolved)
   const turnIdx = parseTurnIndex(requireStr(params.turn, 'turn', 'expand'))
   const { entries } = await loadParsed(resolved, agentDir)
   const tree = buildTreeView(entries)
@@ -835,7 +861,8 @@ async function doDetail(
     undefined,
     liveSessionDir,
   )
-  if (resolved.kind === 'multi') return disambiguate(resolved.query, resolved.candidates)
+  // non-ok 支统一分发（multi 消歧 / 归档态两支，[session-archive D7] 归并点）
+  if (resolved.kind !== 'ok') return resolveNonOkResult(resolved)
   const range = parseTurnsRange(requireStr(params.turns, 'turns', 'detail'))
   const { entries } = await loadParsed(resolved, agentDir)
   const tree = buildTreeView(entries)
@@ -893,7 +920,8 @@ async function doSearch(
     undefined,
     signals.liveSessionDir,
   )
-  if (resolved.kind === 'multi') return disambiguate(resolved.query, resolved.candidates)
+  // non-ok 支统一分发（multi 消歧 / 归档态两支，[session-archive D7] 归并点）
+  if (resolved.kind !== 'ok') return resolveNonOkResult(resolved)
   const scope = params.scope ?? 'all'
   const limit = params.limit ?? SEARCH_DEFAULT_LIMIT
   const { entries } = await loadParsed(resolved, agentDir)
@@ -927,7 +955,8 @@ async function doExport(
     undefined,
     liveSessionDir,
   )
-  if (resolved.kind === 'multi') return disambiguate(resolved.query, resolved.candidates)
+  // non-ok 支统一分发（multi 消歧 / 归档态两支，[session-archive D7] 归并点）
+  if (resolved.kind !== 'ok') return resolveNonOkResult(resolved)
 
   let text: string
   let label: string
@@ -1034,7 +1063,8 @@ async function doExtract(
     undefined,
     liveSessionDir,
   )
-  if (resolved.kind === 'multi') return disambiguate(resolved.query, resolved.candidates)
+  // non-ok 支统一分发（multi 消歧 / 归档态两支，[session-archive D7] 归并点）
+  if (resolved.kind !== 'ok') return resolveNonOkResult(resolved)
   const { entries } = await loadParsed(resolved, agentDir)
   // extract 遍历全量 entry（含旁支/压缩历史），与 outline/expand/detail 的 leaf 视图不同：
   // 素材提取要全量（design §2.3 实测全量 519 toolCall / 26 user / 515 toolResult），
@@ -1213,7 +1243,8 @@ async function doWorkflow(
     undefined,
     liveSessionDir,
   )
-  if (resolved.kind === 'multi') return disambiguate(resolved.query, resolved.candidates)
+  // non-ok 支统一分发（multi 消歧 / 归档态两支，[session-archive D7] 归并点）
+  if (resolved.kind !== 'ok') return resolveNonOkResult(resolved)
 
   let workflows: WorkflowRef[]
   try {