pi-midcompact 0.2.1 → 0.4.0

package/README.md

@@ -1,14 +1,104 @@
 # pi-midcompact
 
-**Compress stale parts of a long Pi session without deleting the original history.**
+[简体中文](./README.zh-CN.md)
 
-Long-running work accumulates exploration, command output, rejected approaches, and completed phases. `pi-midcompact` lets you and the Agent replace only the parts you have reviewed with concise summaries, leaving the current task and important decisions in full context.
+**Attention-aware mid-context compression: compress the noise, keep the signal.**
+
+“Attention-aware” borrows the core idea of neural attention: keep in working context what future work still needs to attend to, rather than deciding from message age alone. A long session does not become stale uniformly. Exploratory reads, failed attempts, routine tool output, and implementation work that is already complete can occupy most of the context window after their value has largely expired. A user requirement, hard-won decision, or unresolved failure from much earlier may still need to remain verbatim.
+
+Pi's built-in `/compact` behaves like **prefix compaction**: it turns an older contiguous prefix into one summary and retains a recent tail. That is appropriate automatic maintenance, but the cut itself does not distinguish a dispensable old exploration from an older decision worth keeping raw.
+
+The name `pi-midcompact` points to the other option: **mid-context compression**. It compresses selected spans inside the active context while leaving valuable raw context on either side in place, and preserves the original session history for recall.
 
 - Choose exactly which conversation ranges to compress.
 - Review the proposed boundaries and summaries before anything changes.
 - Keep the original Pi session entries available for later recall.
 - Keep compression local to the current session-tree branch.
 
+## What it does
+
+At a natural checkpoint, `pi-midcompact` freezes the active session leaf as an anchor and opens a separate transaction. The Agent proposes ranges for completed low-value phases, preserves load-bearing messages verbatim, and prepares a draft for review. Nothing changes until you explicitly commit the plan.
+
+### User-directed depth, Agent-designed plan
+
+The workflow is **Agent-driven but user-directed**. You describe the desired retention depth and what must remain visible; the Agent examines the frozen anchor, discusses trade-offs with you, and drafts selective ranges and summaries. You do not need to select atom IDs yourself.
+
+> “I only want to reclaim roughly 30% of the stale context. Do not compress aggressively; keep the reasoning behind earlier decisions verbatim.”
+
+That is planning guidance, not an enforced token target: semantic importance wins over an exact percentage. The Agent turns it into a reviewable proposal—selected ranges, explicit `KEEP` holes, and summaries—then you approve, revise, or reject it before committing.
+
+### A selective projection, prepared on a temporary branch
+
+`/midcompact start` freezes the current session leaf as an **anchor**. Planning happens on a disposable child branch, so the discussion used to create and edit the draft never becomes part of the committed working context.
+
+```text
+Frozen anchor: raw session history
+
+  [early exploration]──[decision to KEEP]──[routine tool output]──[latest work]  ◀ anchor
+         ╰──── d1 ────╯                       ╰──── d2 ────╯
+
+Planning is isolated on a temporary branch:
+
+  ... [latest work] ──┬── [transaction] ── [draft v1] ── [draft v2]  ◀ review / edit
+                      │                    (abandoned at commit)
+                      └── [midcompact-state]                         ◀ committed leaf
+                            (reviewed selection metadata, not a model message; written only by /midcompact commit)
+
+Later model requests see a selective projection:
+
+  [summary d1]──[decision to KEEP]──[summary d2]──[latest work]
+
+The raw session JSONL still contains:
+
+  [original d1]──[decision to KEEP]──[original d2]──[latest work]
+```
+
+### A reviewed draft can reclaim meaningful context
+
+The browser review captured below selects **42 of 73 atoms** in **2 ranges**: approximately **31.0k → 488 tokens**, for an estimated **30.6k-token reduction**. The other 31 atoms remain unselected and visible as raw context. Click either image to open it at full resolution.
+
+<p align="center">
+  <a href="./figures/review-webui.png">
+    <img src="./figures/review-webui.png" alt="Browser review UI showing 42 of 73 atoms selected across two compression ranges" width="49%">
+  </a>
+  <a href="./figures/review-tui.png">
+    <img src="./figures/review-tui.png" alt="Native TUI review showing a selected compression range and its retained atoms" width="49%">
+  </a>
+</p>
+
+<p align="center"><sub>Editable browser review UI · Native Pi TUI review</sub></p>
+
+### Prefix compaction versus mid-context compression
+
+Both mechanisms preserve the stored JSONL history, but they decide what later model requests see in different ways:
+
+```text
+Pi built-in /compact — automatic threshold or one manual command
+
+  [older contiguous history────────────────────][recent tail]
+                         │
+                         ▼
+  [one compaction summary──────────────────────][recent tail]
+
+pi-midcompact — mid-context compression, review, then human commit
+
+  [stale phase]──[load-bearing decision]──[routine output]──[recent work]
+       d1                  KEEP                  d2
+        │                                         │
+        ▼                                         ▼
+  [summary d1]──[load-bearing decision]──[summary d2]──[recent work]
+```
+
+| | Pi `/compact` | `pi-midcompact` |
+| --- | --- | --- |
+| Starts | Automatically near the context limit, or with `/compact` | At an explicit natural checkpoint with `/midcompact start` |
+| Selects | One older contiguous prefix; keeps a recent token-budgeted tail | One or more reviewed ranges, including non-contiguous ranges and `KEEP` holes |
+| Planning | Optional one-shot instruction to focus the generated summary | User states scope and retention depth; the Agent discusses trade-offs and drafts selective ranges and summaries |
+| Decision gate | Generates a compaction checkpoint directly | Draft → TUI or browser review → explicit human `/midcompact commit` |
+| Best fit | Automatic context maintenance and overflow recovery | Deliberate cleanup of completed phases while retaining specific decisions verbatim |
+
+`pi-midcompact` does not disable or replace Pi's automatic compaction; it gives you a separate, human-reviewed way to make selective reductions. See [Pi's compaction documentation](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/docs/compaction.md) for the built-in mechanism.
+
 ## Install
 
 From npm:
@@ -34,10 +124,14 @@ Start a transaction at a natural breakpoint: the current work is complete enough
 Run:
 
 ```text
-/midcompact
+/midcompact start
 ```
 
-Pi creates a temporary transaction after the anchor and tells the Agent how to plan the compression. No conversation is changed yet.
+Pi asks for confirmation, then creates a temporary transaction after the anchor and tells the Agent how to plan the compression. No conversation is changed yet. You can include the initial scope in the same command:
+
+```text
+/midcompact start Compress the early repository exploration, but keep user requirements verbatim.
+```
 
 ### 2. Discuss what to compress with the Agent
 
@@ -46,7 +140,7 @@ Describe the goal in normal language. For example:
 ```text
 Compress the early repository exploration and routine command output.
 Keep the user's requirements, the rejected database decision, and the final validation errors verbatim.
-Aim for a moderate reduction, not the smallest possible context.
+Reclaim roughly 30% of the stale context, but preserve semantic distinctions rather than chasing an exact token number.
 ```
 
 The Agent locates relevant parts of the frozen conversation, proposes one or more ranges, and writes a summary for each range. You can ask it to preserve a specific message, split a range, or revise a summary.
@@ -59,9 +153,15 @@ Run:
 /midcompact review
 ```
 
-The native TUI displays the frozen conversation as a linear timeline. Each item is marked either `KEEP` or as belonging to a proposed range. Review the range boundaries and the summary that will replace each range.
+In interactive mode, the native TUI displays the frozen conversation as a linear timeline. Each item is marked either `KEEP` or as belonging to a proposed range. Review the range boundaries and the summary that will replace each range.
+
+For RPC, print, or other no-TUI modes, use the editable local browser interface instead:
+
+```text
+/midcompact review-webui
+```
 
-You can edit a selected summary or topic in the TUI. To change range boundaries or leave an important hole uncompressed, tell the Agent what to keep and ask it to revise the plan, then review it again.
+You can edit a selected summary or topic, remove a range, and switch between compression ranges in either review surface. To change range boundaries or leave an important hole uncompressed, tell the Agent what to keep and ask it to revise the plan, then review it again.
 
 ### 4. Commit the reviewed compression
 
@@ -75,8 +175,6 @@ This is deliberately a human command. The Agent cannot commit compression itself
 
 Pi returns to the anchor, discards the temporary planning branch, stores the reviewed compression state, and resumes work from the committed branch. Future model requests receive the selected old ranges as summaries instead of raw messages.
 
-![A compression transaction keeps planning separate from the working branch.](./figures/transaction-lifecycle.svg)
-
 ### 5. Continue working or abort
 
 Keep working normally after committing. If you decide not to compress, run:
@@ -87,37 +185,7 @@ Keep working normally after committing. If you decide not to compress, run:
 
 This returns to the anchor and discards the transaction without changing the active context.
 
-## What the Agent Does
-
-During an active transaction, the Agent uses the `midcompact` tool against the frozen anchor snapshot:
-
-![How the Agent turns semantic judgment into a reviewed compression plan.](./figures/agent-planning.svg)
-
-| Action | Purpose |
-| --- | --- |
-| `locate` | Finds likely conversation landmarks and shows readable previews. |
-| `plan` | Adds, revises, removes, or displays proposed compression ranges and summaries. |
-| `recall` | Searches committed summaries or temporarily retrieves original content from a compressed block. |
-
-The Agent makes semantic decisions: which exploration is stale, which user requirements and decisions must stay visible, and what a useful summary needs to retain. The extension enforces the mechanical rules: ranges cannot overlap, incomplete tool exchanges cannot be compressed, and the Agent cannot bypass the human commit gate.
-
-Temporary references such as `a0007` exist only during planning. They are not inserted into normal prompts or retained as permanent message identifiers.
-
-## What Happens Behind the Scenes
-
-A committed compression does not rewrite or delete the Pi session.
-
-![Compression replaces a reviewed range only in later model requests.](./figures/context-projection.svg)
-
-1. `/midcompact` freezes the current session-tree leaf as the anchor and starts a temporary maintenance branch.
-2. The Agent and you discuss a draft on that branch. This planning chatter is abandoned at commit.
-3. `/midcompact commit` returns to the anchor and saves a branch-local `midcompact-state` entry containing the reviewed ranges and summaries.
-4. Before later model requests, the extension finds the exact selected raw message sequences and projects them into summary messages.
-5. The underlying session entries remain unchanged. If an exact match cannot be found, the extension keeps the raw messages rather than removing uncertain content.
-
-This is why the process is both selective and reversible at the information-access level: a summary saves context, while the source history remains available through recall or the Pi session tree.
-
-## Review Controls
+## Native TUI Controls
 
 Inside `/midcompact review`:
 
@@ -136,8 +204,9 @@ Enter/Esc/q        close
 
 | Command | Result |
 | --- | --- |
-| `/midcompact` | Starts a transaction at the current session-tree leaf. |
-| `/midcompact review` | Opens the draft review timeline. |
+| `/midcompact start [instructions]` | Confirms and starts a transaction at the current session-tree leaf, optionally with an initial compression focus. |
+| `/midcompact review` | Opens the draft review timeline in the native TUI; in non-TUI modes, points to `review-webui`. |
+| `/midcompact review-webui` | Starts an editable local browser review page; works without a TUI. |
 | `/midcompact commit` | Commits the reviewed draft. Human only. |
 | `/midcompact abort` | Abandons the transaction and returns to the anchor. |
 | `/midcompact status` | Displays the current draft, or the committed compression state on this branch. |
@@ -147,9 +216,12 @@ The extension shows planning status in Pi's footer only while a transaction is a
 ## Guarantees and Limits
 
 - **Original history is retained.** Compression changes what later model requests see, not the stored Pi messages.
+- **Fail-open projection.** If an exact reviewed sequence no longer resolves, the extension sends the raw history unchanged rather than removing uncertain content.
 - **State is branch-local.** Navigating with `/tree` to a point before a committed state restores raw history; returning to its descendant restores the projection.
 - **Human review is required.** The Agent can propose a plan but cannot execute `/midcompact commit`.
 - **Tool protocol is protected.** Unknown, incomplete, or orphaned tool exchanges are not compressible.
 - **Repeated transactions work.** Later transactions can compress newly accumulated raw context; existing summaries remain protected.
 - **Native Pi `/compact` interaction needs more real-session validation.** Avoid relying on mixed automatic/native compaction behavior for critical work until it has been exercised in your environment.
-- **Review is TUI-only.** There is no browser review interface in this version.
+- **Provider and extension interoperability needs more real-session validation.** Unusual message shapes, third-party context-transform ordering, and long-lived exact message fingerprints have not been broadly exercised.
+- **Very long sessions are not stress-tested.** Large review snapshots and repeated block accumulation may eventually require consolidation.
+- **Browser review is local.** `review-webui` binds to loopback, opens an editable review page, and keeps the draft mutations in the same branch-local transaction as the native TUI.

package/README.zh-CN.md

@@ -0,0 +1,227 @@
+# pi-midcompact
+
+[English](./README.md)
+
+**Attention-aware 的上下文中段压缩：压缩噪声，保留关键信息。**
+
+这里的 Attention-aware 借用注意力机制的核心想法：保留与压缩的判断，要看后续工作仍需关注什么，不能只按消息新旧划分。长会话里的内容不会同时失去价值。早期探索、失败尝试、常规工具输出，以及已经完成的实现过程，在对应工作结束后往往只有很少的后续价值，却可能占据大部分上下文。相比之下，较早的用户需求、关键决策或尚未解决的错误，仍可能需要保留原文。
+
+Pi 内置的 `/compact` 可理解为**前缀压缩**（prefix compaction）：它把一段较早的连续历史汇总为一份摘要，并保留近期上下文。这适合自动维护会话；不过，切分边界本身不会区分可舍弃的早期探索和应保留原文的较早决策。
+
+`pi-midcompact` 名称中的 mid 指向另一种做法：**上下文中段压缩**（mid-context compression）。它在活跃上下文内部选择区段压缩，让两侧仍有价值的内容保留原文，并保留原始会话历史，供需要时召回。
+
+- 可选择多个对话区段进行压缩。
+- 区段边界和摘要均须审查后才会生效。
+- 原始 Pi 会话条目可在需要时由 Agent 召回。
+- 压缩状态只在当前会话树分支生效。
+
+## 它解决什么问题
+
+在合适的工作节点，`pi-midcompact` 会把当前会话叶节点冻结为锚点，并开启独立事务。Agent 负责为已经完成、后续价值较低的阶段拟定压缩区段，关键消息保留原文；草案必须经过审查，只有显式提交后才会生效。
+
+### 用户确定方向，Agent 设计方案
+
+这套流程由 Agent 推动，方向由用户确定。用户只需说明希望保留什么、准备压缩到什么程度；Agent 会查看冻结后的锚点，与用户讨论取舍，拟定待压缩区段和摘要。用户不必自己定位对话原子编号。
+
+> “我只想回收大约 30% 的陈旧上下文，不要压得太狠；早期决策背后的推理请保留原文。”
+
+这里的比例只作规划参考，语义上的重要性高于精确比例。Agent 会把要求转成一份可审查的方案：列出拟压缩区段、明确 `KEEP` 保留区，并为每个区段撰写摘要。用户可以批准、修改或否决，再决定是否提交。
+
+### 在临时分支中规划，提交后选择性投影
+
+`/midcompact start` 会把当前会话叶节点冻结为**锚点**。规划工作发生在临时子分支上，因此用于制定和修改草案的对话不会进入提交后的工作上下文。
+
+```text
+冻结锚点：原始会话历史
+
+  [早期探索]────[保留的决策]────[常规工具输出]────[最近工作]  ◀ 锚点
+      ╰── d1 ──╯                       ╰── d2 ──╯
+
+规划工作在临时分支上进行：
+
+  ... [最近工作] ──┬── [事务] ── [草案 v1] ── [草案 v2]  ◀ 审查 / 修改
+                   │                  （提交时舍弃）
+                   └── [midcompact-state]                ◀ 提交后的叶节点
+                         （记录已审查的选择；不是模型消息；仅由 /midcompact commit 写入）
+
+后续模型请求看到的是选择性投影后的上下文：
+
+  [d1 摘要]────[保留的决策]────[d2 摘要]────[最近工作]
+
+原始会话 JSONL 仍保留：
+
+  [d1 原文]────[保留的决策]────[d2 原文]────[最近工作]
+```
+
+### 实际压缩效果
+
+下方浏览器审查界面中的草案包含 **2 个区段**，覆盖 **73 个对话原子（atom，最小可压缩单元）中的 42 个**：约从 **31.0k token 降至 488 token**，预计减少 **30.6k token**。其余 31 个原子未被选中，仍以原文留在上下文中。点击图片可查看原图。
+
+<p align="center">
+  <a href="./figures/review-webui.png">
+    <img src="./figures/review-webui.png" alt="浏览器审查界面：73 个对话原子中有 42 个分布在两个压缩区段内" width="49%">
+  </a>
+  <a href="./figures/review-tui.png">
+    <img src="./figures/review-tui.png" alt="原生 TUI 审查界面：展示选中的压缩区段及其中的对话原子" width="49%">
+  </a>
+</p>
+
+<p align="center"><sub>可编辑的浏览器审查界面 · Pi 原生 TUI 审查界面</sub></p>
+
+### 前缀压缩与上下文中段压缩
+
+两种机制都保留 JSONL 中存储的原始历史，但它们决定后续模型请求内容的方式不同：
+
+```text
+Pi 内置 /compact —— 达到阈值时自动执行，或手动执行一次命令
+
+  [较早的一段连续历史────────────────────][保留的近期上下文]
+                         │
+                         ▼
+  [一份压缩摘要──────────────────────────][保留的近期上下文]
+
+pi-midcompact —— 上下文中段压缩，审查后由用户提交
+
+  [陈旧阶段]────[关键决策]────[常规输出]────[近期工作]
+      d1             KEEP            d2
+       │                               │
+       ▼                               ▼
+  [d1 摘要]────[关键决策]────[d2 摘要]────[近期工作]
+```
+
+| 项目 | Pi `/compact` | `pi-midcompact` |
+| --- | --- | --- |
+| 开始条件 | 接近上下文上限时自动触发，或运行 `/compact` | 在合适的工作节点运行 `/midcompact start` |
+| 选择范围 | 一段较早的连续前缀，并按 token 预算保留近期内容 | 一个或多个经过审查的区段；支持不连续区段和 `KEEP` 保留区 |
+| 规划方式 | 支持一次性指令，用于限定生成摘要的重点 | 用户说明范围和保留深度；Agent 讨论取舍并拟定区段与摘要 |
+| 提交约束 | 直接生成压缩检查点 | 先形成草案，再用 TUI 或浏览器审查，最后由用户运行 `/midcompact commit` |
+| 适用场景 | 自动维护上下文、从上下文溢出中恢复 | 清理已经完成的工作阶段，同时保留特定决策原文 |
+
+`pi-midcompact` 不会关闭或替代 Pi 的自动压缩；它提供另一条经过人工审查的选择性压缩路径。Pi 内置机制可参阅 [Pi 的 compaction 文档](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/docs/compaction.md)。
+
+## 安装
+
+从 npm 安装：
+
+```bash
+pi install npm:pi-midcompact
+```
+
+从 GitHub 安装：
+
+```bash
+pi install git:github.com/frostime/pi-midcompact
+```
+
+安装后重启 Pi，或运行 `/reload`。此扩展适用于 Pi `0.84.x`。
+
+## 使用方法
+
+应在合适的工作节点启动事务：当前阶段已完成到足以概括的程度，且 Pi 处于空闲状态。当前节点会成为冻结的**锚点**。Agent 只针对这个快照拟定方案，之后的规划对话不会意外进入被压缩的工作上下文。
+
+### 1. 设置压缩检查点
+
+运行：
+
+```text
+/midcompact start
+```
+
+Pi 会要求确认，随后在锚点之后创建临时事务，并提示 Agent 开始规划。此时尚未改动任何会话内容。也可以在命令中直接写明初始范围：
+
+```text
+/midcompact start 压缩前期仓库探索过程，但保留用户需求原文。
+```
+
+### 2. 与 Agent 讨论压缩方案
+
+直接用自然语言说明目标，例如：
+
+```text
+压缩前期仓库探索和常规命令输出。
+保留用户需求、被否决的数据库方案，以及最终验证错误的原文。
+希望回收约 30% 的陈旧上下文，但不要为了凑精确数字而丢失语义差别。
+```
+
+Agent 会在冻结的会话快照中定位相关内容，提出一个或多个区段，并为每个区段撰写摘要。可以要求它保留某条消息、拆分区段，或重写摘要。
+
+### 3. 审查草案
+
+运行：
+
+```text
+/midcompact review
+```
+
+在交互模式下，原生 TUI 会把冻结的对话显示为线性时间线。每个条目都会标为 `KEEP`，或标明其所属的拟压缩区段。请检查区段边界，以及将用来替换原文的摘要。
+
+在 RPC、print 或其他没有 TUI 的模式下，请改用可编辑的本地浏览器界面：
+
+```text
+/midcompact review-webui
+```
+
+两种审查界面都可以修改所选区段的摘要或主题、移除区段、切换不同区段。若需调整边界，或保留一个重要的未压缩部分，请告诉 Agent 保留什么，并要求它修订方案后再次审查。
+
+### 4. 提交已审查的压缩
+
+方案确认后，运行：
+
+```text
+/midcompact commit
+```
+
+这个命令只能由用户执行，Agent 无法自行提交压缩。
+
+Pi 会回到锚点，放弃临时规划分支，保存已审查的压缩状态，然后从提交后的分支继续工作。后续模型请求会收到所选旧区段的摘要，而不是原始消息。
+
+### 5. 继续工作或放弃事务
+
+提交后可以继续正常工作。若决定不压缩，运行：
+
+```text
+/midcompact abort
+```
+
+该命令会回到锚点，丢弃事务，不改变当前生效的上下文。
+
+## 原生 TUI 快捷键
+
+在 `/midcompact review` 中：
+
+```text
+n/p 或 Left/Right  选择拟压缩区段
+Up/Down、j/k       滚动
+PgUp/PgDn          翻页
+x                  展开所选区段中的对话原子
+e                  编辑所选摘要
+t                  编辑所选主题
+d                  移除所选区段
+Enter/Esc/q        关闭
+```
+
+## 命令
+
+| 命令 | 作用 |
+| --- | --- |
+| `/midcompact start [instructions]` | 确认后在当前会话树叶节点启动事务；可选地提供初始压缩重点。 |
+| `/midcompact review` | 在原生 TUI 中打开草案审查；非 TUI 模式下会提示使用 `review-webui`。 |
+| `/midcompact review-webui` | 启动可编辑的本地浏览器审查页面；无需 TUI。 |
+| `/midcompact commit` | 提交已审查的草案；只能由用户执行。 |
+| `/midcompact abort` | 放弃事务并回到锚点。 |
+| `/midcompact status` | 显示当前草案，或本分支已提交的压缩状态。 |
+
+扩展只在事务进行期间在 Pi 页脚显示规划状态；提交或放弃后会自动清除。
+
+## 保证与限制
+
+- **保留原始历史。** 压缩只改变后续模型请求看到的内容，不改写存储的 Pi 消息。
+- **匹配失败时保留原文。** 若无法精确定位已审查的消息序列，扩展会原样发送历史，而不会删除不确定的内容。
+- **状态只在分支内生效。** 用 `/tree` 回到压缩状态之前的节点会恢复原始历史；回到其后代节点则恢复投影。
+- **必须人工审查。** Agent 可以提出方案，不能执行 `/midcompact commit`。
+- **保护工具调用协议。** 未知、不完整或孤立的工具调用交互不能压缩。
+- **支持重复事务。** 后续事务可以继续压缩新积累的原始上下文；已有摘要保持受保护状态。
+- **与 Pi 原生 `/compact` 的组合仍需更多真实会话验证。** 在完成充分验证前，不应在关键工作中依赖两者混用。
+- **Provider 与扩展互操作性仍需更多真实会话验证。** 非常规消息形态、第三方上下文转换顺序，以及长时间运行的精确消息指纹尚未得到广泛验证。
+- **超长会话尚未完成压力测试。** 审查快照很大、压缩块反复累积时，最终可能需要进一步整合。
+- **浏览器审查仅在本机开放。** `review-webui` 绑定到 loopback 地址，提供可编辑的审查页面；其草案修改与原生 TUI 使用同一条分支事务。

package/figures/transaction-lifecycle.svg

@@ -52,7 +52,7 @@
   <circle cx="245" cy="505" r="23" class="anchor"/>
   <polygon points="245,489 249,499 260,499 251,506 255,517 245,511 235,517 239,506 230,499 241,499" fill="#2563eb"/>
   <text x="290" y="512" class="label blue">T50 · anchor</text>
-  <text x="290" y="537" class="small blue">/midcompact freezes the snapshot here</text>
+  <text x="290" y="537" class="small blue">/midcompact start freezes here</text>
 
   <!-- maintenance branch -->
   <path d="M268 505 H 575" class="dash"/>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-midcompact",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Branch-aware mid-context compression for the Pi coding agent",
   "author": "frostime",
   "repository": {
@@ -27,6 +27,7 @@
     "src",
     "skills",
     "README.md",
+    "README.zh-CN.md",
     "figures"
   ],
   "scripts": {

package/skills/midcompact/SKILL.md

@@ -1,57 +1,117 @@
 ---
 name: midcompact
-description: Use during an active /midcompact transaction to selectively compress stale middle sections of a long Pi conversation, or later to recall exact details from compressed blocks.
+description: Use during an active /midcompact transaction to plan and draft selective compression of stale middle sections of a long Pi conversation, or independently to retrieve details from previously compressed blocks. Covers how to choose compression ranges, how to negotiate compression depth with the user, and the midcompact tool interface.
 ---
 
 # Midcompact
 
-Use this skill only when a `/midcompact` transaction is active, or when exact information must be recovered from a previously compressed block.
+Use this skill when a `/midcompact start` transaction is active, or when information must be retrieved from a previously compressed block.
 
-## Mental model
+## What compression does
 
-The transaction is based on a frozen anchor snapshot. Maintenance discussion, locator calls, draft revisions, and review happen on a temporary branch. A successful commit returns to the anchor without summarizing that maintenance branch, then stores only the reviewed compression projection.
+Mid-context compaction is **selective replacement** inside one linear conversation, not a restart:
 
-The extension handles session-tree mechanics and protocol safety. You decide semantic value.
+```
+A → B → C → ... → NOW
+      └─ selected slices become summaries; everything else stays verbatim
+```
 
-Do not infer importance from a tool name. A user constraint, approval, correction, decision, or other critical fact may appear inside any message or tool exchange. Inspect actual content.
+Three mechanical facts shape how you work:
 
-## Context awareness
+- **KEEP by omission.** Anything outside a draft range stays verbatim. You declare only what to compress, never what to preserve.
+- **Originals survive.** Session entries stay on disk, and `action="recall"` brings an active committed block back into view. Compression is reversible at the information-access level, not a deletion — but recall returns a readable rendering, not a byte-exact replay, so it is no substitute for keeping something verbatim.
+- **Projection is layered.** Compression applies to what future models see, not to stored history.
 
-The tool reports approximate context telemetry while planning:
+## Who decides what
 
-- anchor usage captured when `/midcompact` started;
-- approximate raw tokens selected by the current draft;
-- approximate summary tokens;
-- approximate whole-context usage if the draft were committed now.
+| Actor | Owns |
+|-------|------|
+| Extension | Session-tree mechanics, projection, protocol safety |
+| You | Semantic judgment: which content may yield to a summary, and what each summary must carry |
+| User | Compression scope and depth; the only actor that can commit |
 
-Treat these numbers as **awareness, not a target**. Do not maximize token reduction or keep adding ranges merely because more compression is possible. Use the scale information together with semantic value and the user's conversational guidance. If the user says they only want a modest reduction, preserve more context; if they want more headroom, look for additional stale regions.
+You cannot commit. `/midcompact commit` is the user's gate. Your output is a proposal.
 
-Projected values are estimates. Prefer semantic correctness over apparent numeric precision.
+## What may be compressed
 
-## Compression workflow
+One conservation law decides every case:
 
-1. Decide which completed or stale regions are candidates for compression.
-2. Use `midcompact(action="locate", ...)` to resolve semantic landmarks to atom refs. Locator results include readable previews; request `detail="full"` when a boundary is ambiguous.
-3. Build a draft with `midcompact(action="plan", op="add", start=..., end=..., summary=...)`.
-   - Use multiple ranges for non-contiguous compression.
-   - To preserve an important atom verbatim inside a broader phase, split the compression into ranges around that atom.
-   - Prefer KEEP-by-omission when uncertain.
-   - After each meaningful draft change, use the returned context telemetry to understand its scale; do not treat it as a quota.
-4. Use `midcompact(action="plan", op="show")` and present the complete proposed plan to the user. Include what each range begins/ends with, not only atom IDs.
-5. Recommend `/midcompact review` when the user wants to inspect the linear anchor timeline, proposed ranges, summaries, and KEEP holes. Incorporate requested changes with `op="update"`, `op="remove"`, additional ranges, or the review UI.
-6. After the user is satisfied, ask them to run `/midcompact commit`. The Agent cannot commit itself. The explicit user command is the commit gate and returns the session tree to the anchor before persisting the projection.
+> Compression must conserve every fact that can still affect the work **in the projected context**. After a range is replaced, each such fact must remain available with sufficient fidelity, either in text left verbatim outside the ranges or in the replacement summary.
 
-A good summary preserves what the next working Agent needs: user intent and constraints, decisions and rationale, relevant file paths/signatures/errors, validation state, rejected approaches when the reason matters, unresolved issues, and the next useful state. Remove repetitive exploration and process noise rather than merely shortening prose.
+Not age. Not token count. Not whether it is a tool call or prose. Two consequences follow:
+
+- **The summary is load-bearing.** When a fact lives only inside a compressed range, omitting it from the summary removes it from the projected context. Recall is a recovery path, not a default carrier.
+- **Some information must not be entrusted to paraphrase.** Exact requirement wording, literal error text, decision-critical evidence, protocol structure. When exact form or provenance matters, keep the source verbatim unless the replacement preserves it with equivalent fidelity.
+
+Illustrative cases, derived from the law:
+
+- Work that reached a conclusion or resolved result, with nothing downstream depending on how it got there → the summary states the outcome, or the concluding atom stays outside the range → compressible.
+- Tool output fully absorbed into the answer that follows it → the answer sits outside the range → a thin summary suffices.
+- A constraint, correction, or approval the user stated once → if the wording itself carries the constraint, keep it verbatim; otherwise the summary must state it explicitly.
+- A rejected approach whose rejection reason still constrains current work → the summary must carry the reason; the exploration around it can go.
+
+**Reverse failure.** Some content looks stale but is the only record of an environment quirk, a version-specific behavior, or a failure mode that will resurface. If you cannot state faithfully what a segment established, you cannot summarize it conservingly — keep it verbatim.
+
+**Your summary becomes the successor.** The next working Agent — likely you, after commit — sees only your summary. Write what it needs to avoid redoing or breaking work: user intent and constraints, decisions and their rationale, file paths and signatures, validation state, unresolved issues, and the next useful state. Cutting repetitive exploration is the goal; shortening prose is not.
+
+## Phase 1 — read, segment, propose, align
+
+**Do not call `plan` until you have presented the semantic candidates and the user has confirmed or adjusted the direction**, unless the user explicitly instructs you to skip the proposal.
+
+1. Read back over the conversation in your current context and segment it semantically — by phase of work, not by message count.
+2. Judge each segment against the conservation law. For each candidate, be able to say where its load-bearing facts would end up.
+3. Present candidates: where each begins and ends, roughly how large it is, and what its summary would carry. Name segments you deliberately excluded when the exclusion is non-obvious.
+4. If scope or depth is still unresolved, ask how deep to go and which regions matter. Depth is the user's decision, not a number you optimize.
+
+`locate` is read-only and may be used sparingly here to confirm a boundary you are about to propose, but not to scan exploratorily. A session that has reached compression is already near its limit: speculative calls, and a plan rebuilt after review, both consume what you are trying to reclaim.
+
+If `/midcompact start` carried an instruction (it arrives as `User focus: ...`), treat it as guidance for whichever of scope and depth it specifies. Still propose, but briefly; ask only what the instruction leaves open.
+
+## Phase 2 — locate, draft, review
+
+1. `action="locate"` to resolve the landmarks you agreed on into atom refs. Results include previews; request `detail="full"` when a boundary is ambiguous.
+2. `action="plan", op="add"` per range — several ranges for non-contiguous compression. To keep one important atom verbatim inside a broader phase, add ranges around it; that is KEEP by omission in practice.
+3. `action="plan", op="show"`, then present the complete plan described by content rather than atom IDs.
+4. Recommend `/midcompact review` when the user wants to inspect the anchor timeline, ranges, summaries, and KEEP holes visually. In non-interactive modes (no TUI, RPC, print), `/midcompact review` only warns and points to `/midcompact review-webui`, which starts a local web page that works without a TUI. Apply changes with `op="update"`, `op="remove"`, or new ranges.
+5. Ask the user to run `/midcompact commit` when satisfied.
+
+## Tool interface
+
+**Atoms are not messages.** An atom is the smallest compressible unit. One assistant message containing one or more tool calls, plus its immediately following matching results, forms a single `tool_exchange` atom; you cannot compress half of one.
+
+**Two ref namespaces.** `a0001` is an atom ref, valid only within the current transaction's anchor snapshot — indices shift after every commit, so never reuse one across transactions; re-run `locate`. `c0001` is a compressed block id, stable while that block stays active on the current branch, used by `recall`.
+
+`action="locate"` — pass either `ref` for a direct lookup, or at least one real filter: `pattern`, `tool_name`, or a `source` other than `any`. With none it returns nothing rather than an error. Optional: `direction` (`oldest`/`newest`), `limit` (default 5, max 20), `detail` (`brief`/`full`).
+
+`action="plan"` — `op` defaults to `show`.
+
+| op | Requires |
+|----|----------|
+| `show` | — |
+| `add` | `start`, `end`, `summary`; `topic` optional |
+| `update` | `draft_id` and at least one of `summary`, `topic` |
+| `remove` | `draft_id` |
+
+`op="add"` rejects a range when any of the following holds. These are mechanical constraints, independent of semantic value — a range must satisfy both.
+
+| Condition | Meaning |
+|-----------|---------|
+| Range crosses a protected atom | Split the plan around it. An atom is protected when its tool-call protocol is still open (an incomplete `tool_exchange`, or an orphaned tool result), when it is an existing compressed block, when its message kind is not one the extension can compress, or when its messages have no persistent session entry to anchor to. |
+| Range overlaps an existing draft range | Remove or update that range instead. |
+| `start` occurs after `end` | Refs are positional; order them. |
+| Unknown atom ref | Usually a typo or a ref carried over from an earlier transaction. Re-run `locate` against the current snapshot. |
+
+**Telemetry** accompanies every `plan` result: anchor usage at start, approximate raw and summary tokens for the draft, and projected whole-context usage if committed now. Use it to check the draft against the depth agreed in Phase 1. It is awareness, not a target, and the projections are estimates.
 
 ## Repeated compression
 
-A session may be midcompacted multiple times. Existing compressed blocks remain active and protected; a later transaction can compress newly accumulated raw history around them. Do not attempt to recursively compress an already compressed block in the current version.
+A session may be compacted multiple times. Committed blocks stay active and appear as protected atoms in later snapshots, so they cannot be recompressed. A later transaction compresses raw history accumulated around them.
 
 ## Recall
 
-Compression is reversible at the information-access level. Original session entries remain stored.
+`action="recall"` works whether or not a transaction is active, does not change the projection, and reads blocks active on the current branch.
 
-- `midcompact(action="recall", pattern="...")` searches active compressed block summaries/topics.
-- `midcompact(action="recall", ref="c0001")` temporarily returns the original content for that block.
+- `pattern="..."` searches topics and summaries of active blocks (`limit` default 8, max 20).
+- `ref="c0001"` returns a readable, structure-flattened rendering of that block's messages, truncated if long. On a truncation marker, retry the same ref with `detail="full"`; if that still truncates, inspect the session tree. There is no paging.
 
-Recall does not change the compression projection. Use it when a summary lacks a detail needed for current work.
+Every summary in context states its own block id and the exact recall call for it. Use recall when a summary lacks a detail the current work needs.