knowledge-session-state-and-context-session-catalog-fork-rewind-and-export

## Module Structure 该节点负责围绕持久 transcript 构建用户可操作的会话生命周期。所有读取先验证 Session 与 workspace 身份，再从有效事件投影目录、分支、回退结果、搜索命中或导出内容。 ### Directory Layout - `packages/cli/src/services/SessionService.ts`：会话元数据聚合与生命周期总入口 - `packages/cli/src/services/sessionCatalog.ts`：查询规范化、稳定排序和 cursor 编解码 - `packages/cli/src/services/sessionRewind.ts`：append-only rewind materialization 与 checkpoint 规划 - `packages/cli/src/services/TranscriptSearch.ts`：SQLite FTS 快路径和 JSONL 兼容扫描 - `packages/cli/src/services/SessionMarkdownExporter.ts`：可移植 Markdown 安全投影 - `packages/cli/src/services/SessionExportWriter.ts`：本地 no-clobber 文件落盘 - `packages/cli/src/slash-commands/`：resume、fork、archive、rewind、search 与 export 交互入口 ### Key Entry Points - `SessionService.listSessionPage()` / `listSessions()` in `packages/cli/src/services/SessionService.ts`：分页目录与任务过滤 - `SessionService.forkSession()` in `packages/cli/src/services/SessionService.ts`：从稳定有效历史创建独立 child - `SessionService.rewindSession()` in `packages/cli/src/services/SessionService.ts`：原子提交回退 marker 并可选恢复 snapshot - `SessionService.archiveSession()` / `unarchiveSession()` in `packages/cli/src/services/SessionService.ts`：可恢复归档生命周期 - `SessionService.exportSessionMarkdown()` in `packages/cli/src/services/SessionService.ts`：从 exact-workspace 稳定快照导出 ## Gotchas - Catalog cursor 绑定 `cwd`、`includeSubagents` 和 `archived` 查询域；把 active cursor 用于 archived 列表或改变 workspace/filter 会明确拒绝，而不是从近似位置继续 (`packages/cli/src/services/sessionCatalog.ts`) - 排序边界是 `lastMessageTime DESC -> projectPath ASC -> sessionId ASC`，cursor 还使用 UTF-16 code-unit sort key 对齐 SQLite；改一侧排序却不改另一侧会造成跨页重复或遗漏 (`packages/cli/src/services/sessionCatalog.ts`, `packages/cli/src/services/SessionService.ts`) - 无 workspace 的 ID 查询只在全局唯一时安全；`/resume`、`/fork` 和 archive 命令对同名跨工作区 Session 必须拒绝并要求用户选择 (`packages/cli/src/slash-commands/resume.ts`, `packages/cli/src/slash-commands/fork.ts`, `packages/cli/src/slash-commands/archive.ts`) - scoped load/delete/fork 不信任转义目录名，必须校验 `session_created.data.sessionId` 和 committed `cwd`；目录碰撞不能让另一个 workspace 的 transcript 被读取或删除 (`packages/cli/src/services/SessionService.ts`, `git:f764f682`) - fork 必须留在源 workspace，并从最多三次 stat/read/stat 一致的稳定快照创建；源在三次读取中持续变化时不产生 child (`packages/cli/src/services/SessionService.ts`, `git:375287f5`) - fork 复制 materialized 有效历史和 compaction checkpoint，但剥离 token handoff、inbox acknowledgement、pending interaction、review lifecycle 与 task 运行态；这些是父 Session 的恢复权限，不能继承到 child (`packages/cli/src/services/SessionService.ts`, `git:1cacc9eb`) - fork 的 prompt artifact 必须按 transcript 实际引用复制且重新校验；artifact 复制失败会删除已创建 child transcript 和 child artifact，不能留下只有预览而缺少完整请求的分支 (`packages/cli/src/services/SessionService.ts`, `packages/cli/src/agent/runtime/UserPromptArtifactStore.ts`) - rewind 不截断 JSONL；conversation/both 模式追加 marker 后由 projector 移除目标 user turn 及后续 conversation 生命周期，code-only 模式则保留 conversation (`packages/cli/src/services/sessionRewind.ts`, `packages/cli/src/services/SessionService.ts`) - code/both rewind 在 append marker 的 validated 临界区内先检查 snapshot 连续性和写后 hash；任一文件被外部修改时整组拒绝且 transcript 不新增 marker (`packages/cli/src/services/SessionService.ts`, `packages/cli/tests/unit/services/session-service-rewind.test.ts`) - 归档父 Session 只给根追加 `archivedAt`，后代状态由 lineage 投影继承；恢复父节点不会解除后代自己直接设置的归档 (`packages/cli/src/services/SessionService.ts`, `docs/reference/session-archive.md`) - 归档会先按稳定 ID 顺序获取根及全部 fork/subagent 后代的 lease，任一 queued/running 或被占用成员使整次操作零写入失败 (`packages/cli/src/services/SessionService.ts`, `packages/cli/src/agent/runtime/SessionLease.ts`) - TranscriptSearch 的 SQLite 路径只做 FTS 候选缩减，最终仍执行原 substring/snippet 判断；自定义 `storagePath`、索引不可用或异常时走 JSONL 扫描 (`packages/cli/src/services/TranscriptSearch.ts`) - SQLite 搜索结果的 `lineNumber` 为 0，而 JSONL 路径保留物理事件行号；调用方不能把该字段作为所有搜索路径都稳定的定位主键 (`packages/cli/src/services/TranscriptSearch.ts`) - Markdown 导出读取 stable JSONL 并应用 rewind，不从当前 Runtime、Web store 或 SQLite 拼接；否则 archived Session、冷导出和并发 append 会产生不同结果 (`packages/cli/src/services/SessionService.ts`, `packages/cli/src/services/SessionMarkdownExporter.ts`) - 本地导出使用 exclusive create 和 0600 权限，目标已存在时明确失败；ACP 只允许内联 Markdown 且上限 1 MiB，不能让 remote client 指定宿主路径 (`packages/cli/src/services/SessionExportWriter.ts`, `packages/cli/src/slash-commands/export.ts`) - exact-path 删除损坏 JSONL 仍保留 legacy 清理行为，当前无法从坏记录证明 committed cwd，且存储键注入性与跨进程锁仍是 `storage-v2` 债务 (`packages/cli/src/services/SessionService.ts`) ## Architecture - `projectMetadataFromEntries()` 先折叠 `session_created/session_updated` durable metadata，再用 materialized history 计算消息数、错误、pending interaction 和 review 派生态；SQLite 复用同一 deriver 保持 parity (`packages/cli/src/services/SessionService.ts`) - 分页优先使用 SQLite recursive CTE 计算继承归档状态，失败时回退全量 JSONL 扫描并复用同一 comparator/cursor 逻辑 (`packages/cli/src/services/SessionService.ts`, `packages/cli/src/context/storage/sqlite/projection.ts`) - rewind projector 是 catalog、resume、fork、search、export 和 context load 的共享依赖；新增 conversation event 时必须判断它是否属于 rewind 后缀，否则各读面会分叉 (`packages/cli/src/services/sessionRewind.ts`) - `loadSession()` 返回完整 UI 历史，`loadSessionModelContext()` 额外应用最新 compaction replacement；恢复界面和恢复 Provider 请求必须调用各自入口 (`packages/cli/src/services/SessionService.ts`) - 归档是 catalog projection，不是物理移动或删除；hard delete 才同步清除 transcript、inbox、goal、prompt artifact、browser artifact 和 SQLite 行 (`packages/cli/src/services/SessionService.ts`) ## Decisions - Session catalog 从宽松目录扫描演进为 scope-bound cursor、严格 ID/workspace 验证和跨目录去重，优先防止错误恢复而不是猜测用户想要哪个同名会话 (`packages/cli/src/services/sessionCatalog.ts`, `git:be64af77`, `git:aaa50c79`) - fork 采用完整 transcript exclusive create 而非共享父日志或 copy-on-write，使 child 可独立追加，同时通过 `rootId/parentId/relationType` 保留 lineage (`packages/cli/src/services/SessionService.ts`, `git:a141169b`) - rewind 采用审计 marker 和纯 materializer，而不是破坏性删行，使后续 fork、搜索、导出和 SQLite rebuild 都能重现当时选择 (`packages/cli/src/services/sessionRewind.ts`, `git:6bd75ab1`) - 导出正文 hash 刻意不覆盖可变化 metadata header；相同有效历史和 visibility 选项可得到稳定正文摘要 (`packages/cli/src/services/SessionMarkdownExporter.ts`) ## Security Considerations - 导出器对普通文本清理 ANSI、控制/隐藏 Unicode、私钥、Bearer/key 模式；tool activity 还递归清理敏感键、data URL、host path 和 URL 凭证 (`packages/cli/src/services/SessionMarkdownExporter.ts`) - 单项 activity 最多 64 KiB、完整导出最多 16 MiB；超出完整上限时整体失败而不是生成看似完整的静默截断文件 (`packages/cli/src/services/SessionMarkdownExporter.ts`) - rewind 文件路径由 SnapshotManager 的 workspace/session 分区和 PathSecurity 边界约束，同名 Session 的不同 workspace 不得共享 snapshot (`packages/cli/src/services/SessionService.ts`, `packages/cli/src/slash-commands/rewind.ts`) ## Compatibility - Cursor 接受带时区的非规范 ISO 时间并在解码后规范 workspace，但要求 canonical unpadded base64url 重编码一致，以兼容旧 cursor 又拒绝歧义编码 (`packages/cli/src/services/sessionCatalog.ts`, `git:2cd3c93d`) - TranscriptSearch 仍识别没有 `session_created` 的 legacy `message` JSONL；当前事件格式则先 materialize rewind，再只聚合 user/assistant text part (`packages/cli/src/services/TranscriptSearch.ts`) - 缺少 task metadata 的 legacy transcript 默认投影为 completed，避免历史普通会话被误当失败任务 (`packages/cli/src/services/SessionService.ts`)