smartcompact 0.1.2 → 0.1.5

package/README.md

@@ -9,13 +9,13 @@
 <p align="center"><a href="https://github.com/coffeecoproject/SmartCompact/raw/main/docs/media/smartcompact-en.mp4"><img src="https://raw.githubusercontent.com/coffeecoproject/SmartCompact/main/docs/media/cover-en.jpg" alt="SmartCompact in 90 seconds (video)" width="100%"></a></p>
 <p align="center"><sub>▶ Watch the 90-second explainer (click the image to play)</sub></p>
 
-**SmartCompact lets long coding-agent sessions compact earlier, at a pause after a piece of work is finished.** On 18–60 consecutive coding tasks it cut cost by **7–44%** with no loss in hidden acceptance tests; the longer the session, the more it saves. In the longest runs (60 tasks, native sessions reaching 820k–960k tokens) the model missed 6 of 180 recall questions about details mentioned in passing much earlier ([test report](https://github.com/coffeecoproject/SmartCompact/blob/main/docs/TEST-REPORT.md), in Chinese).
+**SmartCompact lets long coding-agent sessions compact earlier, at a pause after a piece of work is finished.** On 18–60 consecutive coding tasks it cut cost by **7–44%** with no loss in hidden acceptance tests; the longer the session, the more it saves. In the longest runs (60 tasks, native sessions reaching 820k–960k tokens) the model missed 6 of 180 recall questions about details mentioned in passing much earlier ([how it was tested](https://github.com/coffeecoproject/SmartCompact/blob/main/docs/EVALUATION.md)).
 
 Every request re-reads the whole context, so a long context makes every step expensive. Native auto-compaction waits until the context is nearly full (close to 1M tokens in Claude Code, up to 800k in Codex if configured), and it ignores timing, so it often lands in the middle of a task. SmartCompact works with Claude Code (CLI and desktop app), [Pi](https://github.com/earendil-works/pi) and the Codex CLI:
 
 - **Compact at a good moment.** Once the context passes the **allow line** (200k tokens by default), it compacts when a turn ends, if a piece of work has been finished since the last compaction (a commit, tests passing, a task completed).
-- **Never in the middle of work.** It only decides when a turn ends, never mid-turn, and it waits while tests or the build are failing, errors keep repeating, or a background job is running.
-- **A fallback.** If no good moment comes and the context passes the **grace line** (allow line × 1.3), it compacts at the end of a turn.
+- **Never in the middle of work.** It only decides when a turn ends, never mid-turn, and it waits while tests or the build are failing or errors keep repeating.
+- **No limit of its own.** If no piece of work gets finished, the agent is usually deep in one large task, which is when a large context pays off. SmartCompact leaves it alone, and the platform's native compaction applies as it would without the plugin.
 - **A progress ledger bridges the gap.** Files changed, the latest commit and test result, and decisions the agent recorded are handed back to the model after compaction.
 - **No pointless compactions.** It skips compaction when it would not free enough space.
 
@@ -30,7 +30,7 @@ The same codebase and 18–30 consecutive development tasks, where later tasks c
 | Claude Code (Haiku 5.5, 30 tasks) | close to 1M | −7% (noisy) | 30/30 both | 90/90 both |
 | Claude Code (Haiku 5.5, 60 tasks) | close to 1M | **−44%** | native 59–60/60, SmartCompact 60/60 | native 180/180, SmartCompact 174/180 |
 
-Cost is converted to cached-input-token equivalents using each provider's price ratios. The later native compaction kicks in and the faster a session grows, the more it saves. Below 200k SmartCompact does nothing, so it costs nothing either. After a compaction the model spends extra requests getting familiar with the code again; that is included in the cost above. These are small samples on one codebase and one kind of task; the [report](https://github.com/coffeecoproject/SmartCompact/blob/main/docs/TEST-REPORT.md) has the method, the data and the limitations.
+Cost is converted to cached-input-token equivalents using each provider's price ratios. The later native compaction kicks in and the faster a session grows, the more it saves. Below 200k SmartCompact does nothing, so it costs nothing either. After a compaction the model spends extra requests getting familiar with the code again; that is included in the cost above. These are small samples on one codebase and one kind of task; the [evaluation](https://github.com/coffeecoproject/SmartCompact/blob/main/docs/EVALUATION.md) has the method, the data and the limitations.
 
 ## Install
 
@@ -41,7 +41,7 @@ Cost is converted to cached-input-token equivalents using each provider's price
 /plugin install smartcompact@smartcompact
 ```
 
-It takes effect in new sessions. The plugin moves the native auto-compaction to about the grace line; `/smartcompact pause` returns the current session to native behavior.
+It takes effect in new sessions. `/smartcompact pause` turns it off for the current session.
 
 **Pi**
 
@@ -54,31 +54,29 @@ With Pi's default settings, SmartCompact compacts at a finished piece of work wh
 **Codex CLI** (0.162 or later, Node.js 22.18 or later)
 
 ```bash
-git clone https://github.com/coffeecoproject/SmartCompact.git
-cd SmartCompact
-node scripts/codex.ts install
+codex plugin marketplace add coffeecoproject/SmartCompact
+codex plugin add smartcompact@smartcompact
 ```
 
-The script only appends one marked block of hooks to `~/.codex/config.toml` (or `$CODEX_HOME/config.toml`), backing up the file first. Trust the 4 hooks when Codex asks on its next start. Run install again after upgrading Node or moving the repository.
+Trust the plugin's 4 hooks when Codex asks on its next start. The hooks find a Node.js 22.18+ on their own (`PATH`, nvm, Homebrew; or set `SMARTCOMPACT_NODE`); without one they do nothing. To update, run `codex plugin marketplace upgrade smartcompact` and then the `codex plugin add` command again. If you installed an earlier version with `node scripts/codex.ts install`, run `node scripts/codex.ts uninstall` in that clone once, so the hooks do not run twice.
 
-Codex hooks cannot postpone a compaction in the middle of a turn, so SmartCompact decides when a turn ends and, if it should compact, starts the compaction through Codex's shared background server once the session is idle (the interactive UI uses it by default). `codex exec` does not use the shared server by default, and the Codex App (ChatGPT.app) currently cannot; there SmartCompact only hands back the progress ledger, and compaction follows Codex's native rules. For a fallback there, add Codex's own `model_post_turn_compact_threshold_percent` at the top of `config.toml`: it compacts after a turn ends once the context passes that percentage of the usable window (31 is about 260k for an 872k window; see the test report).
+Codex hooks cannot postpone a compaction in the middle of a turn, so SmartCompact decides when a turn ends and, if it should compact, starts the compaction through Codex's shared background server once the session is idle (the interactive UI uses it by default). `codex exec` does not use the shared server by default, and the Codex App (ChatGPT.app) currently cannot; there SmartCompact only hands back the progress ledger, and compaction follows Codex's native rules. If you want compaction to come earlier there, add Codex's own `model_post_turn_compact_threshold_percent` at the top of `config.toml`: it compacts after a turn ends once the context passes that percentage of the usable window (31 is about 260k for an 872k window; see the test report).
 
 ## Settings
 
 | Setting | Default | Meaning |
 |---|---|---|
 | Allow line | 200000 | Above it, compact when a turn ends once a piece of work has been finished |
-| Grace factor | 1.3 | Above allow line × factor, stop waiting for a finished piece of work |
 | Minimum freed | 60000 | Skip compaction if it is expected to free less than this |
 
-- Claude Code: the plugin options `allowLineTokens`, `graceFactor` and `minFreedTokens`; leave them empty for the defaults.
-- Pi: the flags `--smartcompact-allow-line`, `--smartcompact-grace` and `--smartcompact-min-freed`.
-- Codex: the environment variables `SMARTCOMPACT_ALLOW_LINE`, `SMARTCOMPACT_GRACE` and `SMARTCOMPACT_MIN_FREED`.
+- Claude Code: the plugin options `allowLineTokens` and `minFreedTokens`; leave them empty for the defaults.
+- Pi: the flags `--smartcompact-allow-line` and `--smartcompact-min-freed`.
+- Codex: the environment variables `SMARTCOMPACT_ALLOW_LINE` and `SMARTCOMPACT_MIN_FREED`.
 
 ## Seeing what it did
 
-- Claude Code and Pi: `/smartcompact` (or `/smartcompact report`) shows the three lines, the finished-work signals it saw and a cost estimate; `/smartcompact pause` and `resume` turn it off and on for the session. The model can also call a `checkpoint` tool to record decisions, which come back with the ledger after compaction.
-- Codex: `node adapters/codex/report.ts <session ID>`; records are kept in `~/.codex/smartcompact/`.
+- Claude Code and Pi: `/smartcompact` (or `/smartcompact report`) shows the allow line, the native compaction point, the finished-work signals it saw and a cost estimate; `/smartcompact pause` and `resume` turn it off and on for the session. The model can also call a `checkpoint` tool to record decisions, which come back with the ledger after compaction.
+- Codex: `node ~/.codex/plugins/cache/smartcompact/smartcompact/<version>/adapters/codex/report.ts <session ID>` (Node.js 22.18+); records are kept in `~/.codex/smartcompact/`.
 
 ## FAQ
 
@@ -86,13 +84,15 @@ Codex hooks cannot postpone a compaction in the middle of a turn, so SmartCompac
 
 **Will the model forget things after compaction?** Sometimes, for details mentioned in passing. The ledger only records files, commits, tests and decisions the model chose to record. Details the user mentions in passing are kept by asking the compaction summary to keep every specific fact the user stated. On Pi this clearly reduced losses, but it is not a guarantee.
 
-**Anything specific to Claude Code?** SmartCompact's fallback point is close to the native compaction point it moves. If it cannot recognize a finished piece of work for a long time, native compaction may still fire mid-turn. SmartCompact moves the native compaction point by setting `CLAUDE_CODE_AUTO_COMPACT_WINDOW` in the session, and processes started from that session inherit it: a `claude -p` or script the agent runs will compact at about 260k as well. Unset the variable for such processes if that matters.
+**Does it change Claude Code's own settings?** No. Native auto-compaction stays where it is (close to 1M). Versions up to 0.1.2 moved it to about 260k by setting `CLAUDE_CODE_AUTO_COMPACT_WINDOW` in the session (which child processes inherited) and also compacted there without a finished piece of work. 0.1.3 removed both: a long task is no longer cut off at a fixed size. A session opened on 0.1.2 or earlier keeps the old setting until you start a new one.
+
+**Does it help with a smaller context window?** Only when native compaction comes well after 200k. With a 200k window, native compaction comes first (about 167k in Claude Code) and SmartCompact never acts. On Codex's default 272k window, native compaction is at about 245k, which leaves only 200k–245k for SmartCompact, so it saves little unless `model_auto_compact_token_limit` is set higher. The allow line can be lowered (`allowLineTokens`, `--smartcompact-allow-line`, `SMARTCOMPACT_ALLOW_LINE`), but lower lines have not been evaluated.
 
 **How do I remove it?**
 
 - Claude Code: `/plugin uninstall smartcompact@smartcompact`.
 - Pi: `pi remove npm:smartcompact`.
-- Codex: `node scripts/codex.ts uninstall` in the repository.
+- Codex: `codex plugin remove smartcompact@smartcompact`.
 
 ## Development
 
@@ -105,7 +105,7 @@ This runs the structure checks, the core dependency boundary check and all tests
 - `plugin/`: the Claude Code plugin. `plugin/src/core/` holds the platform-independent decisions, signals, ledger and cost estimate that every adapter reuses.
 - `adapters/pi/`, `adapters/codex/`: the Pi and Codex adapters.
 - `eval/`: the A/B evaluation scripts (one each for Claude, Pi and Codex); the task format is described in `eval/day.py`. The tasks and hidden tests come from an internal project and are not published.
-- `DESIGN.md`: design notes; `docs/TEST-REPORT.md`: the test report (both in Chinese).
+- `docs/EVALUATION.md`: how the A/B runs were done and their results. `DESIGN.md`: design notes and `docs/TEST-REPORT.md`: the full test report (both in Chinese).
 
 ## License
 

package/README.zh-CN.md

@@ -14,8 +14,8 @@
 agent 每发一次请求，都要把整段上下文重新读一遍，上下文越长，每一步越贵。原生的自动压缩要等到快满了才触发（Claude Code 接近 100 万，Codex 可以配到 80 万），而且不看时机，常常发生在一件事做到一半的时候。SmartCompact 支持 Claude Code（终端和桌面 App）、[Pi](https://github.com/earendil-works/pi) 和 Codex 命令行：
 
 - **挑对时机压缩。** 上下文超过**允许压缩线**（默认 20 万）以后，只要上次压缩以来做完过一件事（一次提交、测试通过、任务完成），就在这一轮结束时压缩。
-- **不在做到一半时压缩。** 只在一轮结束时判断，从不在一轮中间主动压缩；测试失败、构建失败、连续报错或后台任务还在跑时先等着。
-- **有兜底。** 一直等不到合适时机、上下文超过**宽限线**（允许压缩线 × 1.3）时，在一轮结束时压缩。
+- **不在做到一半时压缩。** 只在一轮结束时判断，从不在一轮中间主动压缩；测试失败、构建失败或连续报错时先等着。
+- **不设自己的上限。** 一直没做完一件事，多半是在干一件大活，这时正需要大上下文。插件不去打断，压缩按平台原生规则来，和没装插件时一样。
 - **用进度笔记接上。** 改过的文件、最近的提交和测试结果、记下的决定，压缩后补回给模型。
 - **不做白费的压缩。** 预计腾不出足够空间时不压缩，避免刚压缩完又压缩。
 
@@ -41,7 +41,7 @@ agent 每发一次请求，都要把整段上下文重新读一遍，上下文
 /plugin install smartcompact@smartcompact
 ```
 
-装好后新开会话生效。插件会把原生自动压缩线调到宽限线附近，`/smartcompact pause` 可以让当前会话恢复原生行为。
+装好后新开会话生效。`/smartcompact pause` 可以暂停当前会话的插件。
 
 **Pi**
 
@@ -54,31 +54,29 @@ Pi 默认配置下，插件在一轮结束（`agent_settled`）时挑刚做完
 **Codex 命令行**（0.162 及以上，Node.js 22.18 及以上）
 
 ```bash
-git clone https://github.com/coffeecoproject/SmartCompact.git
-cd SmartCompact
-node scripts/codex.ts install
+codex plugin marketplace add coffeecoproject/SmartCompact
+codex plugin add smartcompact@smartcompact
 ```
 
-安装脚本只在 `~/.codex/config.toml`（或 `$CODEX_HOME/config.toml`）末尾写入一段带标记的 hook 配置，改之前备份原文件。下次启动 Codex 时按提示信任这 4 个 hook。升级 Node 或移动仓库后重新运行一次 install。
+下次启动 Codex 时按提示信任插件的 4 个 hook。hook 会自己找 22.18 及以上的 Node.js（PATH、nvm、Homebrew，也可以用 `SMARTCOMPACT_NODE` 指定），找不到就什么都不做。更新时运行 `codex plugin marketplace upgrade smartcompact`，再执行一次上面的 `codex plugin add`。以前用 `node scripts/codex.ts install` 装过的，先在那份仓库里运行一次 `node scripts/codex.ts uninstall`，避免 hook 运行两遍。
 
-Codex 的 hook 不能推迟一轮中间的压缩，所以插件在一轮结束时判断，需要压缩就通过 Codex 的共享后台服务（交互界面默认会用它）在会话空闲时发起。`codex exec` 默认不走共享后台服务，Codex App（ChatGPT.app）目前走不了，这时插件只补回进度笔记，压缩仍按 Codex 原生规则。想给它们也加个兜底，可以在 `config.toml` 顶部加上 Codex 自带的 `model_post_turn_compact_threshold_percent`：上下文超过可用窗口的这个百分比时，在一轮结束后压缩（窗口 87.2 万时设 31，约 26 万；详见测试报告）。
+Codex 的 hook 不能推迟一轮中间的压缩，所以插件在一轮结束时判断，需要压缩就通过 Codex 的共享后台服务（交互界面默认会用它）在会话空闲时发起。`codex exec` 默认不走共享后台服务，Codex App（ChatGPT.app）目前走不了，这时插件只补回进度笔记，压缩仍按 Codex 原生规则。想让它们早点压缩，可以在 `config.toml` 顶部加上 Codex 自带的 `model_post_turn_compact_threshold_percent`：上下文超过可用窗口的这个百分比时，在一轮结束后压缩（窗口 87.2 万时设 31，约 26 万；详见测试报告）。
 
 ## 参数
 
 | 参数 | 默认 | 含义 |
 |---|---|---|
 | 允许压缩线 | 200000 | 超过它、做完过一件事后，在一轮结束时压缩 |
-| 宽限倍数 | 1.3 | 超过 允许压缩线 × 倍数 时不再等刚做完一件事 |
 | 最少腾出空间 | 60000 | 预计腾出的空间少于它时不压缩 |
 
-- Claude Code：插件配置项 `allowLineTokens`、`graceFactor`、`minFreedTokens`，留空用默认值。
-- Pi：命令行开关 `--smartcompact-allow-line`、`--smartcompact-grace`、`--smartcompact-min-freed`。
-- Codex：环境变量 `SMARTCOMPACT_ALLOW_LINE`、`SMARTCOMPACT_GRACE`、`SMARTCOMPACT_MIN_FREED`。
+- Claude Code：插件配置项 `allowLineTokens`、`minFreedTokens`，留空用默认值。
+- Pi：命令行开关 `--smartcompact-allow-line`、`--smartcompact-min-freed`。
+- Codex：环境变量 `SMARTCOMPACT_ALLOW_LINE`、`SMARTCOMPACT_MIN_FREED`。
 
 ## 查看效果
 
-- Claude Code 和 Pi：`/smartcompact`（或 `/smartcompact report`）查看三条线、识别到的阶段节点和成本估算；`/smartcompact pause` / `resume` 暂停或恢复当前会话。模型还可以调用 `checkpoint` 工具记下决定，压缩后和进度笔记一起补回。
-- Codex：`node adapters/codex/report.ts <会话 ID>`，记录在 `~/.codex/smartcompact/`。
+- Claude Code 和 Pi：`/smartcompact`（或 `/smartcompact report`）查看允许压缩线、原生压缩点、识别到的阶段节点和成本估算；`/smartcompact pause` / `resume` 暂停或恢复当前会话。模型还可以调用 `checkpoint` 工具记下决定，压缩后和进度笔记一起补回。
+- Codex：`node ~/.codex/plugins/cache/smartcompact/smartcompact/<版本>/adapters/codex/report.ts <会话 ID>`（Node.js 22.18 及以上），记录在 `~/.codex/smartcompact/`。
 
 ## 常见问题
 
@@ -86,13 +84,15 @@ Codex 的 hook 不能推迟一轮中间的压缩，所以插件在一轮结束
 
 **压缩后模型会不会忘事？** 随口提到的细节有时会丢。进度笔记只记文件、提交、测试和模型主动记下的决定。用户在对话里随口交代的细节，靠压缩时要求摘要原样保留用户说过的具体信息。Pi 上这样做明显减少了丢失，但不能保证不丢。
 
-**Claude Code 上有什么要注意的？** 插件的兜底压缩点和它调整后的原生压缩点接近；长时间认不出刚做完一件事时，原生压缩仍可能在一轮中间触发。插件是通过在会话里设置 `CLAUDE_CODE_AUTO_COMPACT_WINDOW` 来调整原生压缩点的，从这个会话里启动的进程会继承它：agent 运行的 `claude -p` 或脚本里启动的 Claude，也会在 26 万左右压缩。需要的话，启动这类进程前去掉这个变量。
+**会改 Claude Code 自己的设置吗？** 不会，原生自动压缩点保持原样（接近 100 万）。0.1.2 及以前的版本会在会话里设置 `CLAUDE_CODE_AUTO_COMPACT_WINDOW`，把原生压缩点挪到约 26 万（子进程也会继承），并且到了那里不等做完一件事也压缩。0.1.3 去掉了这两点：大活不会再在固定大小处被打断。升级前就开着的会话还留着旧设置，新开一个会话就没有了。
+
+**上下文窗口小的模型有用吗？** 只有原生压缩点比 20 万高出一截时才有用。窗口只有 20 万时，原生先压（Claude Code 约 16.7 万），插件根本不会出手。Codex 默认窗口 27.2 万，原生约 24.5 万压，插件只有 20 万～24.5 万这一小段可用，省得不多，除非把 `model_auto_compact_token_limit` 调高。允许压缩线可以调低（`allowLineTokens`、`--smartcompact-allow-line`、`SMARTCOMPACT_ALLOW_LINE`），但调低后的效果没有评测过。
 
 **怎么卸载？**
 
 - Claude Code：`/plugin uninstall smartcompact@smartcompact`。
 - Pi：`pi remove npm:smartcompact`。
-- Codex：在仓库目录里运行 `node scripts/codex.ts uninstall`。
+- Codex：`codex plugin remove smartcompact@smartcompact`。
 
 ## 开发
 
@@ -105,7 +105,7 @@ sh scripts/check.sh
 - `plugin/`：Claude Code 插件；`plugin/src/core/` 是和平台无关的决策、信号、进度笔记和成本估算，其他适配都复用它。
 - `adapters/pi/`、`adapters/codex/`：Pi 和 Codex 的适配。
 - `eval/`：对照评测脚本（Claude、Pi、Codex 各一个），任务格式见 `eval/day.py`；评测用的题目和隐藏测试来自内部项目，没有放进仓库。
-- `DESIGN.md`：设计说明；`docs/TEST-REPORT.md`：测试报告。
+- `DESIGN.md`：设计说明；`docs/TEST-REPORT.md`：测试报告；`docs/EVALUATION.md`：对照评测的英文说明。
 
 ## 许可证
 

package/adapters/pi/index.ts

@@ -1,8 +1,7 @@
 // SmartCompact 的 pi 扩展：把 pi 的事件接到 core 的决策上。
-// 和 Claude 版的区别：插件改不了 pi 的原生压缩线。
-// - 兜底线 = pi 配置的原生压缩点（窗口 − reserveTokens），上限 = 窗口 − pi 默认预留。
-// - 默认配置下两者相同，插件只在 agent_settled（不会再自动继续时）挑阶段节点主动压缩；
-//   用户把 reserveTokens 调大、让原生压缩提前时，插件在提前的那个点按工作状态决定是否取消。
+// - 插件在 agent_settled（不会再自动继续时）挑做完一件事的时机主动压缩；等不到就交给 pi 原生压缩。
+// - 上限 = 窗口 − pi 默认预留。用户把 reserveTokens 调大、让原生压缩提前时，
+//   插件在提前的那个点按工作状态决定是否取消，最晚到上限放行。
 
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent'
 import { SettingsManager } from '@earendil-works/pi-coding-agent'
@@ -13,12 +12,15 @@ import type { Lines } from '../../plugin/src/core/lines.ts'
 import { resolveParams } from '../../plugin/src/core/params.ts'
 import { countDecisions, renderReport } from '../../plugin/src/core/report.ts'
 import {
+  cycleReads,
   type DecisionLogEntry,
   expectedAfterTokens,
+  growthSinceMilestone,
   INITIAL_SESSION_STATE,
   parseState,
   type SessionState,
   withCompaction,
+  withRead,
   withSample,
   withSignals,
 } from '../../plugin/src/core/state.ts'
@@ -41,7 +43,6 @@ const nudgeText = (tokens: number): string =>
 
 export default function smartCompact(pi: ExtensionAPI) {
   pi.registerFlag('smartcompact-allow-line', { description: 'SmartCompact 允许压缩线（token）', type: 'string' })
-  pi.registerFlag('smartcompact-grace', { description: 'SmartCompact 宽限倍数', type: 'string' })
   pi.registerFlag('smartcompact-min-freed', { description: 'SmartCompact 最少腾出空间（token）', type: 'string' })
 
   let state: SessionState = INITIAL_SESSION_STATE
@@ -64,7 +65,6 @@ export default function smartCompact(pi: ExtensionAPI) {
   const params = (ctx: ExtensionContext) =>
     resolveParams({
       allowLineTokens: Number(pi.getFlag('smartcompact-allow-line')) || undefined,
-      graceFactor: Number(pi.getFlag('smartcompact-grace')) || undefined,
       minFreedTokens: Number(pi.getFlag('smartcompact-min-freed')) || undefined,
       defaultAfterTokens: compactionSettings(ctx).keepRecent + PI_AFTER_OVERHEAD,
     })
@@ -73,21 +73,17 @@ export default function smartCompact(pi: ExtensionAPI) {
     const usage = ctx.getContextUsage()
     if (!usage) return null
     const { reserve } = compactionSettings(ctx)
-    return {
-      allow: params(ctx).allowLineTokens,
-      midTurn: usage.contextWindow - reserve,
-      ceiling: usage.contextWindow - Math.min(reserve, PI_DEFAULT_RESERVE),
-      adjustsNative: false,
-    }
+    return { allow: params(ctx).allowLineTokens, ceiling: usage.contextWindow - Math.min(reserve, PI_DEFAULT_RESERVE) }
   }
 
   const tokensOf = (ctx: ExtensionContext): number | undefined => ctx.getContextUsage()?.tokens ?? undefined
 
-  // 成本估算对比的是"没有插件时"：pi 原生会在它配置的压缩点（兜底线）压缩，而不是等到真正的极限。
+  // 成本估算对比的是"没有插件时"：pi 原生会在它配置的压缩点（窗口 − reserveTokens）压缩，而不是等到真正的极限。
   const sample = (ctx: ExtensionContext, current: Lines | null) => {
     const tokens = tokensOf(ctx)
+    const window = ctx.getContextUsage()?.contextWindow
     const model = `${ctx.model?.provider ?? ''} ${ctx.model?.id ?? ''}`
-    if (tokens !== undefined && current) state = withSample(state, tokens, current.midTurn, pricesFor(model))
+    if (tokens !== undefined && current && window) state = withSample(state, tokens, window - compactionSettings(ctx).reserve, pricesFor(model))
     return tokens
   }
 
@@ -169,8 +165,9 @@ export default function smartCompact(pi: ExtensionAPI) {
     if (event.toolName === CHECKPOINT_TOOL) return
     sample(ctx, lines(ctx))
     const text = event.content.flatMap(block => (block.type === 'text' ? [block.text] : [])).join('\n')
-    const { signals, ledger } = recognizePi({ toolName: event.toolName, input: event.input, isError: event.isError, text }, state.ledger)
+    const { signals, ledger, read } = recognizePi({ toolName: event.toolName, input: event.input, isError: event.isError, text }, state.ledger)
     state = withSignals({ ...state, ledger }, signals)
+    if (read) state = withRead(state, read)
   })
 
   pi.on('before_agent_start', async (_event, ctx) => {
@@ -191,7 +188,8 @@ export default function smartCompact(pi: ExtensionAPI) {
       { tokens, lines: current, work: state.work, expectedAfterTokens: expectedAfterTokens(state, params(ctx).defaultAfterTokens), paused: state.paused },
       params(ctx),
     )
-    if (decision.action !== 'none') log({ event: 'turn-end', action: decision.action, reason: decision.reason, tokens })
+    const sinceMilestoneTokens = decision.action === 'compact' ? growthSinceMilestone(state.work, tokens) : undefined
+    if (decision.action !== 'none') log({ event: 'turn-end', action: decision.action, reason: decision.reason, tokens, sinceMilestoneTokens })
     if (decision.action !== 'compact' || !ctx.isIdle() || ctx.hasPendingMessages()) return
     ours = true
     ctx.compact({
@@ -221,10 +219,11 @@ export default function smartCompact(pi: ExtensionAPI) {
     const fromPlugin = event.reason === 'manual' && ours
     ours = false
     const summaryTokens = Math.round(event.compactionEntry.summary.length / 4)
+    const reads = cycleReads(state)
     // 原生按阈值的压缩、溢出恢复和用户的 /compact，没有插件时也会发生；只有插件发起的压缩计入节省。
     state = withCompaction(state, event.compactionEntry.tokensBefore, summaryTokens, fromPlugin)
     persist()
-    log({ event: 'compacted', trigger: fromPlugin ? 'plugin' : event.reason === 'threshold' ? 'auto' : event.reason, tokensBefore: event.compactionEntry.tokensBefore })
+    log({ event: 'compacted', trigger: fromPlugin ? 'plugin' : event.reason === 'threshold' ? 'auto' : event.reason, tokensBefore: event.compactionEntry.tokensBefore, ...reads })
     pi.sendMessage(
       { customType: LEDGER_MESSAGE, content: renderLedger(state.ledger, params(ctx).ledgerMaxChars), display: false },
       { deliverAs: ctx.isIdle() ? 'nextTurn' : 'steer' },

package/adapters/pi/recognize.ts

@@ -14,7 +14,7 @@ export type PiToolOutcome = {
 
 const EDIT_TOOLS = new Set(['edit', 'write'])
 
-export function recognizePi(outcome: PiToolOutcome, ledger: Ledger): { signals: Signal[]; ledger: Ledger } {
+export function recognizePi(outcome: PiToolOutcome, ledger: Ledger): { signals: Signal[]; ledger: Ledger; read?: string } {
   const signals: Signal[] = [{ kind: 'tool-result', isError: outcome.isError }]
   let next = ledger
   const { path, command } = outcome.input
@@ -26,5 +26,6 @@ export function recognizePi(outcome: PiToolOutcome, ledger: Ledger): { signals:
     signals.push(...classified.signals)
     next = classified.ledger
   }
-  return { signals, ledger: next }
+  const read = outcome.toolName === 'read' && !outcome.isError && typeof path === 'string' && path ? path : undefined
+  return { signals, ledger: next, read }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smartcompact",
-  "version": "0.1.2",
+  "version": "0.1.5",
   "type": "module",
   "description": "Compact long agent sessions earlier, at a finished piece of work, to cut cost without losing results (Claude Code, pi, Codex)",
   "license": "MIT",

package/plugin/README.md

@@ -0,0 +1,35 @@
+# SmartCompact for Claude Code
+
+SmartCompact compacts long Claude Code sessions earlier, at a pause after a piece of work is finished, so every later request re-reads a smaller context. Once the context passes 200k tokens, it compacts at the end of a turn if a commit, passing tests or a completed task happened since the last compaction. It waits while tests or the build are failing or errors repeat. It sets no limit of its own: if no piece of work gets finished, the session keeps its context and Claude Code's native auto-compaction applies as usual. A short progress ledger (files changed, latest commit and test result, recorded decisions) is handed back to the model after compaction.
+
+In a 60-task A/B run on Claude Haiku it cut estimated cost by 44% with no loss in hidden acceptance tests; the model missed 6 of 180 recall questions about details mentioned in passing long before. Method and data: [docs/EVALUATION.md](https://github.com/coffeecoproject/SmartCompact/blob/main/docs/EVALUATION.md).
+
+## What it runs, reads and writes
+
+Everything runs locally inside Claude Code. **The plugin makes no network requests, starts no processes, and does not read or change environment variables or Claude Code's settings.**
+
+- **Reads**: the session's token usage; the tool name, input and success of each tool call, to recognize work: file paths from Edit/Write, Bash command text (to recognize `git commit` and test or build commands, and whether they failed), the `[branch hash] message` line from a commit's output, TodoWrite items and task events. It reads no credentials or tokens and no file contents, and nothing it reads leaves the machine.
+- **Writes**: only the plugin's own storage (`$.store`): per-session state and the progress ledger (file paths, the latest commit line, the latest test command and result, in-progress task names, notes recorded with the `checkpoint` tool) and a short decision log. Old session records are pruned automatically.
+
+### What each hook does
+
+All hooks live in one module, `hooks/register.ts`.
+
+- **Session start**: records the context window (for the cost estimate) and registers the `checkpoint` tool and the `/smartcompact` command.
+- **`/smartcompact` command**: answers only its own command (`report`, `pause`, `resume`).
+- **Tool calls**: answers calls to its own `checkpoint` tool by recording the note. For every other tool it only looks at the result to recognize commits, tests, builds and edited files, and passes the result through unchanged.
+- **Task created / completed**: keeps the list of in-progress task names for the ledger.
+- **Prompt submit**: adds context to the turn, never changes the user's message. After a compaction it adds the progress ledger; once per cycle, when the context nears the allow line, it adds a one-line reminder to record progress with `checkpoint`.
+- **Turn complete**: decides whether to compact. When it should, it compacts the session. Where a session cannot compact directly (headless sessions such as the desktop app), it runs the `/compact` command itself with SmartCompact's compaction instructions; it runs no other commands.
+- **Compaction**: never blocks or changes a compaction itself. After any compaction of the main session it appends the progress ledger to the compacted context. Subagent compactions are left alone.
+
+## Use
+
+- Install: `/plugin marketplace add coffeecoproject/SmartCompact`, then `/plugin install smartcompact@smartcompact`. It takes effect in new sessions.
+- `/smartcompact` (or `/smartcompact report`) shows the lines, recognized milestones and a cost estimate; `/smartcompact pause` and `/smartcompact resume` turn it off and on for the session.
+- Settings (optional, empty means default): `allowLineTokens` (200000), `minFreedTokens` (60000).
+- Remove: `/plugin uninstall smartcompact@smartcompact`.
+
+Full documentation, Pi and Codex versions: https://github.com/coffeecoproject/SmartCompact
+
+License: MIT.

package/plugin/src/core/decide.ts

@@ -1,4 +1,4 @@
-// 两个决策函数：一轮结束时要不要主动压缩；一轮进行中原生自动压缩来问时放不放行。
+// 两个决策函数：一轮结束时要不要主动压缩；一轮进行中原生自动压缩来问时放不放行（只有原生压缩点能提前的平台用到，目前是 pi）。
 // 读不到用量时一律不干预，按原生行为来。
 
 import type { Lines } from './lines.ts'
@@ -18,7 +18,7 @@ export type DecisionInput = {
 export type TurnEndDecision =
   | { action: 'none'; reason: 'paused' | 'no-reading' | 'below-line' }
   | { action: 'wait'; reason: HardSignal | 'insufficient-benefit' | 'waiting-for-milestone' }
-  | { action: 'compact'; reason: MilestoneSource | 'past-grace' }
+  | { action: 'compact'; reason: MilestoneSource }
 
 export type MidTurnDecision =
   | { action: 'allow'; reason: 'paused' | 'no-reading' | 'at-ceiling' | 'default' }
@@ -37,7 +37,7 @@ export function decideAtTurnEnd(input: DecisionInput, params: Params): TurnEndDe
   if (hard) return { action: 'wait', reason: hard }
   if (!freesEnough(tokens, input, params)) return { action: 'wait', reason: 'insufficient-benefit' }
   if (work.milestone) return { action: 'compact', reason: work.milestone }
-  if (tokens >= lines.midTurn) return { action: 'compact', reason: 'past-grace' }
+  // 不设兜底线：一直等不到做完一件事，多半是在做一件大活，正需要大上下文；交给原生在上限处压缩。
   return { action: 'wait', reason: 'waiting-for-milestone' }
 }
 

package/plugin/src/core/ledger.ts

@@ -128,9 +128,20 @@ export function applyCheckpoint(ledger: Ledger, input: CheckpointInput): Ledger
   }
 }
 
-/** 排版成补回上下文的文本，超长时截断。 */
+/** 排版成补回上下文的文本，超长时先丢最旧的决定、再丢最早改过的文件，仍超长才截断。 */
 export function renderLedger(ledger: Ledger, maxChars: number): string {
-  const { facts, notes } = ledger
+  let decisions = ledger.notes.decisions
+  let files = ledger.facts.filesChanged
+  let rendered = layoutLedger(ledger, decisions, files)
+  while (rendered.length > maxChars && (decisions.length || files.length)) {
+    if (decisions.length) decisions = decisions.slice(1)
+    else files = files.slice(1)
+    rendered = layoutLedger(ledger, decisions, files)
+  }
+  return rendered.length <= maxChars ? rendered : `${rendered.slice(0, maxChars - 20)}\n…(truncated)`
+}
+
+function layoutLedger({ facts, notes }: Ledger, decisions: readonly string[], files: readonly string[]): string {
   const lines = [
     LEDGER_MARKER,
     'Generated by the SmartCompact plugin to keep continuity across compaction. It is not a message from the user.',
@@ -139,19 +150,19 @@ export function renderLedger(ledger: Ledger, maxChars: number): string {
     const rows = body.filter((row): row is string => Boolean(row))
     if (rows.length) lines.push('', `## ${title}`, ...rows)
   }
+  const omitted = (dropped: number, what: string) => (dropped ? `- …(${dropped} earlier ${what} omitted)` : undefined)
   section('Goal', [notes.goal])
   section('Current state', [notes.current])
   section('Next', [notes.next])
-  section('Decisions', notes.decisions.map(decision => `- ${decision}`))
-  section('Tasks in progress', facts.tasksInProgress.map(task => `- ${task}`))
-  section('Files changed', facts.filesChanged.map(file => `- ${file}`))
   section('Latest results', [
     facts.lastTest && `- tests ${facts.lastTest.passed ? 'passed' : 'FAILED'}: ${facts.lastTest.command}`,
     facts.lastBuild && `- build ${facts.lastBuild.passed ? 'passed' : 'FAILED'}: ${facts.lastBuild.command}`,
     facts.lastCommit && `- last commit: ${facts.lastCommit.summary}`,
   ])
-  const rendered = lines.join('\n')
-  return rendered.length <= maxChars ? rendered : `${rendered.slice(0, maxChars - 20)}\n…(truncated)`
+  section('Tasks in progress', facts.tasksInProgress.map(task => `- ${task}`))
+  section('Decisions', [omitted(notes.decisions.length - decisions.length, 'decisions'), ...decisions.map(decision => `- ${decision}`)])
+  section('Files changed', [omitted(facts.filesChanged.length - files.length, 'files'), ...files.map(file => `- ${file}`)])
+  return lines.join('\n')
 }
 
 export function isLedgerText(value: string): boolean {

package/plugin/src/core/lines.ts

@@ -1,31 +1,7 @@
-// 三条线：允许压缩线 L、轮中兜底线 M、上限 C（原生压缩点）。
-
-import type { Params } from './params.ts'
+// 两条线：允许压缩线 L（超过它，做完一件事时压缩才划算）、上限 C（原生压缩点）。
+// 插件不设自己的兜底线：一直等不到做完一件事，就交给原生在上限处压缩，和没装插件时一样。
 
 export type Lines = {
   allow: number
-  midTurn: number
   ceiling: number
-  /** false 表示窗口本身放不下 L 和 M，插件不调整原生压缩线，只负责进度笔记 */
-  adjustsNative: boolean
-}
-
-/** CLAUDE_CODE_AUTO_COMPACT_WINDOW 允许的最小值 */
-export const MIN_NATIVE_SETTING = 100_000
-
-/**
- * @param nativeSettingTokens 插件调整之前，原生压缩线的设定值（窗口或用户自己的配置）
- */
-export function planLines(nativeSettingTokens: number, params: Params): Lines {
-  const ceiling = nativeSettingTokens - params.nativeBufferTokens
-  const allow = params.allowLineTokens
-  // 原生压缩线设定值有下限，M 不会低于它对应的触发点，否则算出的 M 与原生实际行为不符。
-  const midTurn = Math.max(Math.round(allow * params.graceFactor), MIN_NATIVE_SETTING - params.nativeBufferTokens)
-  if (midTurn >= ceiling) return { allow, midTurn: ceiling, ceiling, adjustsNative: false }
-  return { allow, midTurn, ceiling, adjustsNative: true }
-}
-
-/** 让原生自动压缩从 M 开始尝试，需要写入的压缩线设定值。 */
-export function nativeSettingFor(lines: Lines, params: Params): number {
-  return lines.midTurn + params.nativeBufferTokens
 }

package/plugin/src/core/params.ts

@@ -3,13 +3,11 @@
 export type Params = {
   /** 允许压缩线 L：一轮结束时超过它才考虑压缩 */
   allowLineTokens: number
-  /** 轮中兜底线 M = L × graceFactor */
-  graceFactor: number
   /** 一次压缩至少要腾出的空间，不够就不压，防止连续压缩 */
   minFreedTokens: number
   /** 还没实测到压缩后大小时，用这个估计值 */
   defaultAfterTokens: number
-  /** 原生触发点 ≈ 压缩线设定值 − 这个值（实测约 33k） */
+  /** Claude 原生触发点 ≈ 窗口 − 这个值（实测约 33k） */
   nativeBufferTokens: number
   /** 用量读数可能落后于最新的工具结果，接近上限时留出的余量 */
   ceilingMarginTokens: number
@@ -23,7 +21,6 @@ export type Params = {
 
 export const DEFAULT_PARAMS: Params = Object.freeze({
   allowLineTokens: 200_000,
-  graceFactor: 1.3,
   minFreedTokens: 60_000,
   defaultAfterTokens: 50_000,
   nativeBufferTokens: 33_000,
@@ -35,7 +32,6 @@ export const DEFAULT_PARAMS: Params = Object.freeze({
 
 const MINIMUMS: Record<keyof Params, number> = {
   allowLineTokens: 1,
-  graceFactor: 1,
   minFreedTokens: 0,
   defaultAfterTokens: 0,
   nativeBufferTokens: 0,

package/plugin/src/core/report.ts

@@ -29,10 +29,10 @@ export function renderReport(input: {
   const seen = state.seen
   return [
     `SmartCompact${state.paused ? '（已暂停）' : ''}`,
-    `- 当前用量 ${k(tokens)}；允许压缩线 ${k(lines.allow)}，兜底线 ${k(lines.midTurn)}，上限 ${k(lines.ceiling)}${lines.adjustsNative ? '' : '（原生压缩线未调整）'}`,
+    `- 当前用量 ${k(tokens)}；允许压缩线 ${k(lines.allow)}，原生压缩点 ${k(lines.ceiling)}`,
     `- 本会话压缩 ${state.compactions} 次；最近一次压缩后约 ${k(state.measuredAfterTokens)}`,
     `- 本会话决策：插件压缩 ${(counts['compacted:plugin'] ?? 0) + (counts['compacted:plugin-queued'] ?? 0)}，自动压缩放行 ${counts['compacted:auto'] ?? 0}，手动压缩 ${counts['compacted:manual'] ?? 0}，轮中否决 ${counts['mid-turn:veto'] ?? 0}，轮末等待 ${counts['turn-end:wait'] ?? 0}`,
-    `- 信号：提交 ${seen.commit}，测试通过 ${seen['tests-passed']}，任务完成 ${seen['task-completed']}，checkpoint 完成 ${seen.checkpoint}，后台任务 ${seen.background}`,
+    `- 信号：提交 ${seen.commit}，测试通过 ${seen['tests-passed']}，任务完成 ${seen['task-completed']}，checkpoint 完成 ${seen.checkpoint}`,
     `- 当前状态：${state.work.milestone ? `已到阶段节点（${state.work.milestone}）` : '等待阶段节点'}${state.work.testsFailing ? '，测试失败中' : ''}${state.work.buildFailing ? '，构建失败中' : ''}`,
     ratio === undefined
       ? '- 成本估算：还没有读数'

package/plugin/src/core/signals.ts

@@ -9,19 +9,19 @@ export type Signal =
   | { kind: 'task-completed' }
   | { kind: 'checkpoint'; milestone: boolean }
   | { kind: 'tool-result'; isError: boolean }
-  | { kind: 'background'; running: number }
 
 export type MilestoneSource = 'commit' | 'tests-passed' | 'task-completed' | 'checkpoint'
 
-export type HardSignal = 'tests-failing' | 'build-failing' | 'error-streak' | 'background-running'
+export type HardSignal = 'tests-failing' | 'build-failing' | 'error-streak'
 
 export type WorkState = {
   /** 自上次压缩以来最近的阶段节点 */
   milestone: MilestoneSource | null
+  /** 最近的阶段节点出现时的上下文用量，用来看它到压缩时隔了多远 */
+  milestoneTokens?: number
   testsFailing: boolean
   buildFailing: boolean
   errorStreak: number
-  backgroundRunning: number
 }
 
 export const INITIAL_WORK_STATE: WorkState = Object.freeze({
@@ -29,7 +29,6 @@ export const INITIAL_WORK_STATE: WorkState = Object.freeze({
   testsFailing: false,
   buildFailing: false,
   errorStreak: 0,
-  backgroundRunning: 0,
 })
 
 /** 这个信号代表哪种阶段节点，不是阶段节点时为 null。 */
@@ -49,7 +48,9 @@ export function milestoneOf(signal: Signal): MilestoneSource | null {
 }
 
 export function applySignal(state: WorkState, signal: Signal): WorkState {
-  const next = { ...state, milestone: milestoneOf(signal) ?? state.milestone }
+  const milestone = milestoneOf(signal)
+  // 失败之后又做完了一件事（比如提交、checkpoint），那段失败就算过去了，不再挡着压缩。
+  const next = milestone ? { ...state, milestone, testsFailing: false, buildFailing: false } : state
   switch (signal.kind) {
     case 'tests':
       return { ...next, testsFailing: !signal.passed }
@@ -57,16 +58,14 @@ export function applySignal(state: WorkState, signal: Signal): WorkState {
       return { ...next, buildFailing: !signal.passed }
     case 'tool-result':
       return { ...next, errorStreak: signal.isError ? state.errorStreak + 1 : 0 }
-    case 'background':
-      return { ...next, backgroundRunning: Math.max(0, signal.running) }
     default:
       return next
   }
 }
 
-/** 压缩后清空阶段节点；失败、后台任务这些仍然成立的事实保留。 */
+/** 压缩后清空阶段节点；失败这些仍然成立的事实保留。 */
 export function afterCompaction(state: WorkState): WorkState {
-  return { ...state, milestone: null }
+  return { ...state, milestone: null, milestoneTokens: undefined }
 }
 
 /** 表明工作做到一半的硬信号，没有则返回 null。 */
@@ -74,6 +73,5 @@ export function hardSignal(state: WorkState, params: Params): HardSignal | null
   if (state.testsFailing) return 'tests-failing'
   if (state.buildFailing) return 'build-failing'
   if (state.errorStreak >= params.errorStreakLimit) return 'error-streak'
-  if (state.backgroundRunning > 0) return 'background-running'
   return null
 }

package/plugin/src/core/state.ts

@@ -4,7 +4,7 @@ import { EMPTY_LEDGER, type Ledger } from './ledger.ts'
 import { afterCompaction, applySignal, INITIAL_WORK_STATE, milestoneOf, type MilestoneSource, type Signal, type WorkState } from './signals.ts'
 import { EMPTY_TALLY, type Prices, recordCompaction, recordSample, type UsageTally } from './usage.ts'
 
-export type SignalsSeen = Record<MilestoneSource | 'background', number>
+export type SignalsSeen = Record<MilestoneSource, number>
 
 export type SessionState = {
   work: WorkState
@@ -20,8 +20,24 @@ export type SessionState = {
   /** 各种信号出现过的次数，用于确认识别是否生效 */
   seen: SignalsSeen
   usage: UsageTally
+  /** 读文件的统计；平台认不出读文件时没有这一项 */
+  reads?: ReadStats
 }
 
+/** 用来看压缩后要花多少次读取重新熟悉代码。 */
+export type ReadStats = {
+  /** 上次压缩之前读过或改过的文件 */
+  known: string[]
+  /** 上次压缩以来读过的文件 */
+  current: string[]
+  /** 上次压缩以来读文件的次数 */
+  reads: number
+  /** 其中读的是压缩前已经看过的文件 */
+  rereads: number
+}
+
+const MAX_KNOWN_FILES = 300
+
 export const INITIAL_SESSION_STATE: SessionState = Object.freeze({
   work: INITIAL_WORK_STATE,
   ledger: EMPTY_LEDGER,
@@ -29,7 +45,7 @@ export const INITIAL_SESSION_STATE: SessionState = Object.freeze({
   paused: false,
   notesUpdated: false,
   nudged: false,
-  seen: Object.freeze({ commit: 0, 'tests-passed': 0, 'task-completed': 0, checkpoint: 0, background: 0 }),
+  seen: Object.freeze({ commit: 0, 'tests-passed': 0, 'task-completed': 0, checkpoint: 0 }),
   usage: EMPTY_TALLY,
 }) as SessionState
 
@@ -45,15 +61,21 @@ export function expectedAfterTokens(state: SessionState, defaultAfterTokens: num
   return state.measuredAfterTokens ?? defaultAfterTokens
 }
 
-/** 应用信号，同时更新信号计数。 */
+/** 应用信号，同时更新信号计数；出现阶段节点时记下当时的上下文用量（最近一次读数）。 */
 export function withSignals(state: SessionState, signals: readonly Signal[]): SessionState {
   const seen = { ...state.seen }
+  let work = signals.reduce(applySignal, state.work)
   for (const signal of signals) {
     const milestone = milestoneOf(signal)
     if (milestone) seen[milestone] += 1
-    if (signal.kind === 'background' && signal.running > 0) seen.background += 1
   }
-  return { ...state, work: signals.reduce(applySignal, state.work), seen }
+  if (signals.some(signal => milestoneOf(signal))) work = { ...work, milestoneTokens: state.usage.lastTokens }
+  return { ...state, work, seen }
+}
+
+/** 最近的阶段节点之后上下文又涨了多少；没有记录时为 undefined。 */
+export function growthSinceMilestone(work: WorkState, tokens: number | undefined): number | undefined {
+  return tokens === undefined || work.milestoneTokens === undefined ? undefined : tokens - work.milestoneTokens
 }
 
 /** 记一次用量读数：压缩后的第一次读数同时记为实测的压缩后大小。 */
@@ -67,8 +89,15 @@ export function withSample(state: SessionState, tokens: number, ceiling: number,
  * @param attributed 是否算作插件带来的压缩；用户手动 /compact 没有插件时也会发生，不计入节省
  */
 export function withCompaction(state: SessionState, before: number, summary: number, attributed = true): SessionState {
+  const reads = state.reads && {
+    known: [...new Set([...state.reads.known, ...state.reads.current, ...state.ledger.facts.filesChanged])].slice(-MAX_KNOWN_FILES),
+    current: [],
+    reads: 0,
+    rereads: 0,
+  }
   return {
     ...state,
+    ...(reads && { reads }),
     work: afterCompaction(state.work),
     compactions: state.compactions + 1,
     notesUpdated: false,
@@ -77,6 +106,25 @@ export function withCompaction(state: SessionState, before: number, summary: num
   }
 }
 
+/** 记一次读文件：读的是上次压缩前看过的文件就算重读。 */
+export function withRead(state: SessionState, path: string): SessionState {
+  const stats = state.reads ?? { known: [], current: [], reads: 0, rereads: 0 }
+  return {
+    ...state,
+    reads: {
+      known: stats.known,
+      current: [...stats.current.filter(file => file !== path), path].slice(-MAX_KNOWN_FILES),
+      reads: stats.reads + 1,
+      rereads: stats.rereads + (stats.known.includes(path) ? 1 : 0),
+    },
+  }
+}
+
+/** 压缩时记进日志的本周期读文件次数；平台认不出读文件时为空。 */
+export function cycleReads(state: SessionState): Pick<DecisionLogEntry, 'reads' | 'rereads'> {
+  return state.reads ? { reads: state.reads.reads, rereads: state.reads.rereads } : {}
+}
+
 export type DecisionLogEntry = {
   at: string
   /** 会话 ID，报告据此只统计当前会话 */
@@ -87,6 +135,11 @@ export type DecisionLogEntry = {
   tokens?: number
   tokensBefore?: number
   tokensAfter?: number
+  /** 决定压缩时，距离最近的阶段节点上下文涨了多少 */
+  sinceMilestoneTokens?: number
+  /** 压缩时：上次压缩以来读文件的次数，以及其中重读压缩前看过的文件的次数 */
+  reads?: number
+  rereads?: number
   trigger?: string
   detail?: string
 }