feat: unify context compaction

AGENTS.md

@@ -52,7 +52,6 @@
 - 上游来源：<https://github.com/kitfunso/hippo-memory>
 - 初始导入快照：`e928179a3b35e8fe5837878aed071d6025ced45c`（`v1.33.0`）。
 - 官方 npm tarball 不包含 Pi Extension；仓库保留官方 README、LICENSE 和来源说明，匹配 CLI 版本由 `config/hippo-memory-version` 声明。
-- `@ogulcancelik/pi-codex-compaction@0.1.3`：为 `openai-codex` 提供原生远程 compaction，默认阈值为 90%。
 - `pi-minimal-footer/`：基于上游紧凑 footer，保留上下文仪表、订阅用量条和扩展状态，并在 Codex Fast 模式开启时显示 `Fast on`。
 - 上游来源：<https://github.com/ogulcancelik/pi-extensions/tree/main/packages/pi-minimal-footer>
 - 初始导入快照：`77bd1e175003cd08e6d05d9e7fed695f86ae87b7`（`@ogulcancelik/pi-minimal-footer@0.1.10`）。
@@ -65,11 +64,11 @@
 - 上游来源：<https://github.com/Firstp1ck/pi-coding-agent-forge/tree/main/pi-extension-codex-fast-mode>
 - 初始导入快照：`f1d0efd24a7f4ae99d19e10c5f4c3770a3bdd845`（`@firstpick/pi-extension-codex-fast-mode@0.1.1`）。
 - 该目录从上游源码仓库导入并由本仓库直接维护，不使用 npm 预编译产物，不是 submodule，也不保留嵌套 `.git`。
-- `pi-condense/`：总结已完成的工具调用批次，以短 stub 替换历史原始输出，并通过 `context_tree_query` 按需恢复；瞬时摘要故障使用有界指数退避，默认最多重试 2 次。
-- 上游来源：<https://github.com/jjuraszek/pi-condense>
-- 初始导入快照：`59c95110aacd8131db71e21296765dd80b72fae8`（`v2.9.1`）。
-- 该目录从官方明确 tag 的源码导入并由本仓库直接维护，不使用 npm 预编译产物，不是 submodule，也不保留嵌套 `.git`、上游 `.pi` / agent 状态、`node_modules` 或构建产物。
-- 根包还固定安装 `@tavily/pi-extension@0.1.2`、`@keenable/pi-search@0.1.2`、`pi-hashline-edit@0.8.3`、`typescript-language-server@5.3.0`、`typescript@6.0.3` 和 `pi-context-view`；`@firstpick/pi-extension-codex-fast-mode`、`@gotgenes/pi-permission-system`、`@smoose/pi-notify`、`pi-ask-user`、`pi-chrome`、`pi-condense`、`pi-minimal-footer`、`pi-ssh` 与 `pi-tool-search` 分别指向仓库内对应目录的本地 `file:` 依赖；`pi-subagents/` 仅保留源码，不作为根运行时依赖。
+- `pi-compaction/`：统一管理增量 Session segment、确定性工具结果压缩、后台语义摘要、effective token 口径、`context_tree_query`、portable checkpoint 与 Codex native compaction；普通 Provider、native compaction、footer 和本地 context observer 必须消费同一个不可变 projection snapshot。
+- 上游参考一：<https://github.com/jjuraszek/pi-condense>，快照 `59c95110aacd8131db71e21296765dd80b72fae8`（`v2.9.1`）。
+- 上游来源二：<https://github.com/ogulcancelik/pi-extensions/tree/main/packages/pi-codex-compaction>，导入快照 `c4d6ca8fb484ba51684296ba8b4715f8c7b3ac91`（`0.1.4`）。
+- `pi-compaction` 采用全新的 `pi-compaction` version 1 Session 记录和 `settings.json.piCompaction` 配置，不读取或迁移旧 `context-prune-*`、`contextPrune` 或 `openai-codex-native-compaction` 状态；切换后应使用新 Session。两份上游 MIT 许可证及来源差异保留在包内。
+- 根包还固定安装 `@tavily/pi-extension@0.1.2`、`@keenable/pi-search@0.1.2`、`pi-hashline-edit@0.8.3`、`typescript-language-server@5.3.0` 和 `typescript@6.0.3`；`@firstpick/pi-extension-codex-fast-mode`、`@gotgenes/pi-permission-system`、`@smoose/pi-notify`、`pi-ask-user`、`pi-chrome`、`pi-compaction`、`pi-minimal-footer`、`pi-ssh` 与 `pi-tool-search` 分别指向仓库内对应目录的本地 `file:` 依赖；`pi-subagents/` 仅保留源码，不作为根运行时依赖。
 - `install.sh`：先安装根组合包，再交互检查 Hippo Memory CLI、Kitty/Solarized Dark、Oh My Zsh/Powerlevel10k/Zsh 插件、CodeGraph、Kotlin LSP、Java 21+ 和 JDT LS；缺失项目只在用户明确选择 `Y` 后安装或配置。Hippo 项目目录与 `hippo init` 始终由用户自行决定。Powerlevel10k 默认配置来自仓库内置的 `config/p10k.zsh`（当前 Rainbow/ASCII 单行紧凑主题）。
 - `update.sh`：先通过 `pi update` 升级根组合包，再只升级当前已安装的终端环境和机器级依赖；未安装项直接跳过。不得在 `pi update` 前预清理安装缓存；仅当默认 Git 来源首次升级失败、Pi 的精确中断标记存在、canonical checkout 根目录和 `origin` 均通过身份校验时，才允许对该缓存执行最多 4 次连续 `git clean -fdx`，随后只重试一次 `pi update`，由 Pi 自己恢复依赖和清除标记；自定义来源、标记缺失或身份不匹配必须保持 fail-fast。升级成功后只能调用可定位的更新后组合包 Node helper 检查 Pi agent `settings.json`：只有 `toolSearch` 完整精确匹配旧版 `3` 组 / `20` 工具默认快照时，才创建从生成起即为权限 `600` 的时间戳备份、以同目录临时文件原子迁移到 `5` / `28` 并写入 `bundleDefaultsVersion: 2`；任何自定义或无效配置必须保留，提交前检测到内容变化必须中止。无法从 `PI_PACKAGE_SOURCE` 定位更新后 helper 时必须保留配置并报告失败，不能回退到可能陈旧的脚本目录 helper。其他组件升级前先查询并比较本地与远端版本，只有版本不同时才下载或替换；Powerlevel10k 配置优先从 `pi update` 后的已安装组合包读取，并与 `.zshrc` 受管块一起按内容比较后增量同步。
 - `uninstall.sh`：先移除根组合包；若检测到 Hippo Memory CLI，再明确询问是否卸载确认属于 npm 全局安装的 `hippo-memory`，默认保留且始终不删除 `.hippo/` 或用户记忆数据。其他共享终端环境和机器工具不卸载。
@@ -96,9 +95,11 @@
 - 所有 MCP 服务必须合并到 `extensions/mcp.ts` 创建的唯一 `pi-mcp-adapter` 实例；不得新增独立 adapter 扩展入口，否则会重复注册 `--mcp-config`、`/mcp` 等全局接口。根测试必须扫描全部本地扩展入口并强制这一不变量。
 - Exa MCP 使用托管 Streamable HTTP 端点和 `eager` lifecycle；`EXA_API_KEY` 通过 `x-api-key` 请求头发送，不得放入 URL、仓库文件或日志。所有在线搜索工具统一采用“来源名 + 原始语义工具名”的命名形式，例如 `tavily_web_search`、`exa_web_search`、`keenable_search`。Exa 高级搜索必须显式约束结果数量和文本长度；Tavily 输出默认控制 `max_results` 且非必要不请求 raw content；Keenable 优先利用中文、站点和日期筛选能力。
 - 搜索 key 默认保存在 `${XDG_CONFIG_HOME:-$HOME/.config}/my-pi/search.env`，文件必须为 `600` 且不得提交；`search_config.sh` 只输出配置状态，禁止回显 key。
-- `pi-context-view` 只观察上下文占用，不参与压缩策略。
-- `pi-condense` 负责压缩已经进入会话的历史工具结果，与 Context Mode 的输入隔离职责互补；根组合包直接加载 `pi-condense/index.ts`，不得恢复 `extensions/condense.ts` / `extensions/condense-config.ts` 注入层或同时加载 npm 实现。维护默认值直接位于 `pi-condense/src/types.ts`，缺失字段只在内存中归一化，扩展加载不得写回 `settings.json`，全部用户显式值（包括 `enabled: false` 与重试 `0`）必须保留。默认开启，使用 `agent-message` 触发、`turn` 批处理、73.5% 总预算与 4% 单轮增量触发，摘要模型和 thinking 均为 `default`，单次空闲/总超时为 90 秒/5 分钟，`quietOversizedSkips` 为 `false`，skill 路径保护保持上游值。
-- 摘要瞬时错误默认 `summarizerMaxRetries: 2`，即初始尝试加 2 次重试共最多 3 次请求；`summarizerRetryBaseDelayMs: 1000` 与 `summarizerRetryMaxDelayMs: 8000` 在默认重试数下形成 1/2 秒有界指数退避，最终耗尽后才通知错误。认证失败、空/长度截断摘要和用户取消不得重试，取消在 backoff 中也必须立即生效。配置独立摘要模型时最后一个重试名额用于会话模型 fallback，整个调用仍不得超过 `1 + summarizerMaxRetries` 次；设为 `0` 必须同时禁用自动重试和 fallback 救援。
+- `extensions/context-view.ts` 是只读的本地 effective-context observer，只读取 `pi-compaction/src/service.ts` 发布的 projection metrics，不注册生产 `context` writer；`pi-minimal-footer` 优先显示同一 effective usage，snapshot 尚未建立时才回退宿主原始 usage。
+- `pi-compaction` 负责已经进入 Session 的历史投影，与 Context Mode 的输入隔离职责互补。首次 Session hydration 允许一次完整扫描；后续普通 `context` hot path 必须复用不可变 snapshot 或只处理 delta，不得调用 summarizer、写 Session 或重新构建完整 branch。
+- 已闭合工具结果先同步生成保留工具名、参数、状态、首尾证据和 source key 的有界确定性 stub；大于 `semantic.minInputChars` 的结果再进入单 Session 有界后台语义 worker。后台结果只在安全事件边界提交，陈旧 hash 必须丢弃，Provider 请求不得等待后台摘要。
+- effective token 默认使用 Provider usage-backed baseline 加 projected delta；无可靠 baseline 时使用带上下界的估算。Pi Core raw threshold 只负责唤醒，只有 effective lower bound 达到 `hardRatio` 才执行 threshold compaction；manual 与 overflow 不得被阻断。
+- Codex native compaction 必须直接消费当前 projection 生成的 ResponseItems，不得从 raw branch 重建输入；native checkpoint 同时保存有界 portable summary 供模型或 Provider 切换。配置只从 `settings.json.piCompaction` 读取且不写回，默认 soft/hard/target 比例为 72%/90%/55%。
 - Codex fast mode 只为符合条件的 `openai-codex-responses` 请求设置 priority service tier。`/fast-mode on|off` 同时更新当前分支记录与 Pi agent 目录中的 owner-only 全局默认值；新会话继承全局值，已有分支记录优先，配置缺失或无效时回退为关闭。
 - Kitty 完成通知只在 TUI 模式的 `agent_settled` 后发送；自动重试、自动 compaction 和 follow-up 期间不得提前通知或重置总耗时。权限通知只订阅 `permissions:ui_prompt`，在人类确认界面即将出现时立即发送，不得为策略或 AutoReview 已直接决定的请求通知，也不受完成通知时长门槛影响。默认 `o=always`、`a=focus`，每个 Pi Session 使用独立稳定 ID，标题和正文必须 Base64 编码。
 - `/notify on|off` 只覆盖当前 Session；持久默认来自 `PI_NOTIFY_*` 环境变量。`PI_NOTIFY_MESSAGE_SOURCE=none` 必须继续提供不泄露回复正文、权限值或请求者细节的隐私模式，非 TUI 模式不得写入 OSC 序列。
@@ -189,13 +190,15 @@
 - 修改该扩展后至少运行包内 `npm test`、`npm run check`、`npm run smoke` 与 `npm pack --dry-run --json`；加载或依赖入口变化还要运行根扩展联合加载测试和实际 packed tarball 的隔离安装验证。
 
 
-## `pi-condense` 开发约定
+## `pi-compaction` 开发约定
 
-- 扩展入口是 `pi-condense/index.ts`，主要实现和测试位于 `pi-condense/src/`，来源记录是 `pi-condense/UPSTREAM.md`。
-- 同步上游必须从官方 `jjuraszek/pi-condense` 的明确 tag/commit 移植并保留 README、CHANGELOG、PRUNING、规格文档、作者和 LICENSE；不得以 npm tarball、缓存、`node_modules` 或构建产物覆盖本地源码。
-- 根包必须通过 `file:./pi-condense` 提供依赖并直接加载仓库源码；本地包只保留宿主 peer dependencies，不得把 Pi host runtime 的 upstream devDependencies 带入根安装或锁文件。
-- 修改默认配置、归一化、设置 UI、重试/timeout/fallback、摘要通知或取消语义时，必须同步包内 README、配置文档、CHANGELOG、根 README、测试与本节。显式用户配置必须优先，扩展初始化不得为了部署默认值写入用户 `settings.json`。
-- 重试上限表示初始请求之后的重试次数；带独立摘要模型的 session fallback 必须占用最后一个重试名额而不是额外增加请求。只重试 `runOnce` 已分类的 transient outcome，auth/unusable/abort 不得重试，backoff 必须可取消。
+- 扩展入口是 `pi-compaction/index.ts`，增量索引、投影、后台摘要、服务与 Codex native 实现在 `pi-compaction/src/`，测试位于 `pi-compaction/test/`，双上游来源记录是 `pi-compaction/UPSTREAM.md`。
+- 根包必须通过 `file:./pi-compaction` 提供依赖并直接加载源码；不得重新声明或加载 `pi-condense`、npm `@ogulcancelik/pi-codex-compaction` 或 npm `pi-context-view`。
+- `pi-compaction` 只支持自己的 version 1 记录和 `piCompaction` 配置，不得恢复旧状态兼容、自动迁移或加载时写回 `settings.json`。
+- Context Authority 是 compaction 唯一生产投影者。普通 Provider、Codex native、`/context`、`/compaction-status` 和 footer 必须消费同一 snapshot；background worker 不得在 Provider 请求中被 await。
+- Segment custom entry 只能保存摘要、hash 和 source reference，不得复制完整原始工具输出。`context_tree_query` 恢复结果必须有界，native checkpoint 的 portable summary 也必须有界。
+- 修改 projection、token accounting、threshold、checkpoint、模型切换、后台并发或恢复索引后，至少运行 `npm test`、`npm run check`、`npm pack --dry-run --json`、根扩展联合加载、packed 根 tarball 隔离加载和性能回归。性能门禁为 cache-hit P95 <2ms、delta projection P95 <10ms，普通 hot path 不得扫描完整 branch。
+- 同步 Codex 协议代码必须从官方 `ogulcancelik/pi-extensions` 明确 commit 移植并保留对应 MIT 许可证；不得从 npm tarball、缓存、`node_modules` 或构建产物导入。
 
 
 ## `pi-subagents` 开发约定
@@ -279,7 +282,7 @@ Hippo 脚本变化必须额外用隔离 HOME/PATH 和 mock `pi`、`npm`、`hippo
 
 在 `pi-notify/` 内至少运行 `npm run typecheck`、`npm run test` 和 `npm pack --dry-run --json`；涉及加载入口或 lifecycle 时还要运行根扩展联合加载测试和实际 packed tarball 的隔离安装验证。
 
-在 `pi-condense/` 内至少运行 `npm test` 和 `npm pack --dry-run --json`；涉及依赖或加载入口时还要验证根 `npm install` 幂等、锁文件仅包含本地 link 变化、根扩展联合加载测试，以及实际 packed 根 tarball 的隔离安装/加载。
+在 `pi-compaction/` 内至少运行 `npm test`、`npm run check` 和 `npm pack --dry-run --json`；涉及依赖、加载入口、context writer、footer 或 observer 时还要验证根 `npm install` 幂等、锁文件仅包含预期本地 link 变化、根扩展联合加载、性能回归，以及实际 packed 根 tarball 的隔离安装/加载。
 
 
 在 `pi-tool-search/` 内至少运行 `npm run typecheck`、`npm run test` 和 `npm run build`；涉及加载入口或 active-tool 行为时还要运行根扩展联合加载测试和实际 packed tarball 的隔离安装验证。