pi-midcompact 0.4.0 → 0.5.1

package/README.md

@@ -55,7 +55,7 @@ The raw session JSONL still contains:
 
 ### 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.
+The earlier browser and TUI captures below illustrate a draft with **2 ranges** covering **42 of 73 atoms**, while the other 31 atoms remain verbatim. The current UI reports Pi-provided anchor usage separately from factual content chars and image counts; it does not derive projected token savings from local character estimates. Click either image to open it at full resolution.
 
 <p align="center">
   <a href="./figures/review-webui.png">
@@ -127,7 +127,7 @@ Run:
 /midcompact start
 ```
 
-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:
+Pi opens a three-way chooser before creating transaction state: **Agent direct**, **User manual**, or **Drop**. Agent direct is the first and default-highlighted option, matching the previous fast path. The chooser is the standard `select` dialog, identical in interactive and RPC mode; RPC carries it as an extension UI `select` message with a bounded timeout, so an unresponsive client cancels instead of blocking. print/JSON modes have no dialog and default to **Agent direct**. Agent direct starts the existing inventory-first Agent workflow. User manual sends the same transaction guidance with a final “acknowledge only” instruction; after the Agent replies briefly, the Selection workbench opens (browser-based outside interactive mode). It does not start planning or mutate the DraftPlan until the user hands off later. Save the initial DraftPlan, close the UI, then tell the Agent to continue when you are ready. You can include an initial focus in the same command:
 
 ```text
 /midcompact start Compress the early repository exploration, but keep user requirements verbatim.
@@ -161,7 +161,14 @@ For RPC, print, or other no-TUI modes, use the editable local browser interface
 /midcompact review-webui
 ```
 
-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.
+Use Selection to create or change ranges and KEEP holes:
+
+```text
+/midcompact select
+/midcompact select-webui
+```
+
+Use the TUI or local browser Review surface to edit summaries/topics and reject ranges. Review deliberately does not create or resize ranges; reopen Selection for boundary changes. To continue with Agent after a user-created plan, send a normal message asking it to continue the current midcompact draft; the Agent is prompted to read the existing plan first.
 
 ### 4. Commit the reviewed compression
 
@@ -204,9 +211,11 @@ Enter/Esc/q        close
 
 | Command | Result |
 | --- | --- |
-| `/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 start [instructions]` | Opens Agent direct / User manual / Drop, then starts a transaction at the current session-tree leaf. |
+| `/midcompact select` | Opens the native TUI Selection workbench for range and KEEP editing. |
+| `/midcompact select-webui` | Opens the local browser Selection workbench. |
+| `/midcompact review` | Opens summary/topic review in the native TUI. |
+| `/midcompact review-webui` | Opens summary/topic review in a local browser. |
 | `/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. |
@@ -224,4 +233,4 @@ The extension shows planning status in Pi's footer only while a transaction is a
 - **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.
 - **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.
+- **Browser workbenches are local.** `select-webui` and `review-webui` bind to loopback and mutate the same branch-local DraftPlan as the native TUI surfaces.

package/README.zh-CN.md

@@ -55,7 +55,7 @@ Pi 内置的 `/compact` 可理解为**前缀压缩**（prefix compaction）：
 
 ### 实际压缩效果
 
-下方浏览器审查界面中的草案包含 **2 个区段**，覆盖 **73 个对话原子（atom，最小可压缩单元）中的 42 个**：约从 **31.0k token 降至 488 token**，预计减少 **30.6k token**。其余 31 个原子未被选中，仍以原文留在上下文中。点击图片可查看原图。
+下面的早期浏览器和 TUI 截图展示了一份包含 **2 个区段**、覆盖 **73 个 atom 中 42 个**的草案，其余 31 个 atom 保留原文。当前 UI 会把 Pi 提供的锚点 usage 与扩展统计的 content chars、图片数量分开显示，不再根据本地字符估算推导预计 token 节省量。点击图片可查看原图。
 
 <p align="center">
   <a href="./figures/review-webui.png">
@@ -127,7 +127,7 @@ pi install git:github.com/frostime/pi-midcompact
 /midcompact start
 ```
 
-Pi 会要求确认，随后在锚点之后创建临时事务，并提示 Agent 开始规划。此时尚未改动任何会话内容。也可以在命令中直接写明初始范围：
+Pi 会在创建事务状态前提供三个选项：**Drop**、**Agent direct** 和 **User manual**。Agent direct 进入现有的 inventory-first Agent 流程；User manual 会发送同样的事务说明，但末尾要求 Agent 只确认知悉。Agent 简短回复后，才打开 Selection 工作台；在用户交接前不会开始规划或修改 DraftPlan。用户保存初始 DraftPlan 并关闭界面后，可在准备好时再让 Agent 继续。也可以在命令中直接写明初始重点：
 
 ```text
 /midcompact start 压缩前期仓库探索过程，但保留用户需求原文。
@@ -161,7 +161,14 @@ Agent 会在冻结的会话快照中定位相关内容，提出一个或多个
 /midcompact review-webui
 ```
 
-两种审查界面都可以修改所选区段的摘要或主题、移除区段、切换不同区段。若需调整边界，或保留一个重要的未压缩部分，请告诉 Agent 保留什么，并要求它修订方案后再次审查。
+需要创建或调整区段与 `KEEP` 保留洞时，使用 Selection：
+
+```text
+/midcompact select
+/midcompact select-webui
+```
+
+TUI 与本地浏览器 Review 界面用于编辑摘要/主题和否决区段。Review 不创建或调整区段边界；边界变化应重新打开 Selection。用户先创建计划后，只需发送普通消息要求 Agent 继续当前 midcompact draft，Agent 会先读取已有计划。
 
 ### 4. 提交已审查的压缩
 
@@ -204,9 +211,11 @@ Enter/Esc/q        关闭
 
 | 命令 | 作用 |
 | --- | --- |
-| `/midcompact start [instructions]` | 确认后在当前会话树叶节点启动事务；可选地提供初始压缩重点。 |
-| `/midcompact review` | 在原生 TUI 中打开草案审查；非 TUI 模式下会提示使用 `review-webui`。 |
-| `/midcompact review-webui` | 启动可编辑的本地浏览器审查页面；无需 TUI。 |
+| `/midcompact start [instructions]` | 显示 Drop / Agent direct / User manual，并在当前会话树叶节点启动事务。 |
+| `/midcompact select` | 在原生 TUI 中打开 Selection 工作台，编辑区段和 `KEEP`。 |
+| `/midcompact select-webui` | 在本地浏览器中打开 Selection 工作台。 |
+| `/midcompact review` | 在原生 TUI 中审查摘要和主题。 |
+| `/midcompact review-webui` | 在本地浏览器中审查摘要和主题。 |
 | `/midcompact commit` | 提交已审查的草案；只能由用户执行。 |
 | `/midcompact abort` | 放弃事务并回到锚点。 |
 | `/midcompact status` | 显示当前草案，或本分支已提交的压缩状态。 |
@@ -224,4 +233,4 @@ Enter/Esc/q        关闭
 - **与 Pi 原生 `/compact` 的组合仍需更多真实会话验证。** 在完成充分验证前，不应在关键工作中依赖两者混用。
 - **Provider 与扩展互操作性仍需更多真实会话验证。** 非常规消息形态、第三方上下文转换顺序，以及长时间运行的精确消息指纹尚未得到广泛验证。
 - **超长会话尚未完成压力测试。** 审查快照很大、压缩块反复累积时，最终可能需要进一步整合。
-- **浏览器审查仅在本机开放。** `review-webui` 绑定到 loopback 地址，提供可编辑的审查页面；其草案修改与原生 TUI 使用同一条分支事务。
+- **浏览器工作台仅在本机开放。** `select-webui` 与 `review-webui` 绑定到 loopback，并与原生 TUI 操作同一份分支内 DraftPlan。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-midcompact",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Branch-aware mid-context compression for the Pi coding agent",
   "author": "frostime",
   "repository": {
@@ -32,7 +32,7 @@
   ],
   "scripts": {
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "rm -rf .test-dist && tsc -p tsconfig.test.json && node test/install-mocks.mjs && node --test test/core.test.mjs test/runtime.test.mjs",
+    "test": "rm -rf .test-dist && tsc -p tsconfig.test.json && node test/install-mocks.mjs && node --test test/core.test.mjs test/runtime-start.test.mjs test/runtime-agent.test.mjs test/runtime-user.test.mjs test/runtime-transaction.test.mjs test/runtime-lock.test.mjs",
     "typecheck:contract": "tsc -p tsconfig.test.json --noEmit",
     "pack:check": "npm pack --dry-run"
   },

package/skills/midcompact/SKILL.md

@@ -1,117 +1,132 @@
 ---
 name: midcompact
-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.
+description: Use when a midcompact runtime prompt starts or hands off a compression-planning transaction, or when current work needs details from an active committed midcompact block. Guides user-aligned candidate discovery, effort-scaled inspect/locate/plan work, replacement-summary writing, and recall.
 ---
 
 # Midcompact
 
-Use this skill when a `/midcompact start` transaction is active, or when information must be retrieved from a previously compressed block.
+## Route the activation
 
-## What compression does
+This skill handles two independent tasks: planning compression and recalling committed content. Choose the route before calling the tool.
 
-Mid-context compaction is **selective replacement** inside one linear conversation, not a restart:
+| Signal | Immediate duty | First action |
+|--------|----------------|--------------|
+| Runtime prompt says `FINAL STATE: USER MANUAL` | Let the user create the initial DraftPlan | Reply exactly `OK`; call no midcompact tool |
+| Runtime prompt says `FINAL STATE: AGENT DIRECT` | Start from the new empty draft | `action="inspect"` |
+| A handoff reports a persisted DraftPlan and the user asks to continue | Read the shared selection and determine what help the user wants | `action="plan", op="show"` |
+| The user or a projected summary needs detail from a committed block | Retrieve that history only | Follow **Recall workflow** |
 
-```
-A → B → C → ... → NOW
-      └─ selected slices become summaries; everything else stays verbatim
-```
+The state-specific runtime prompt is authoritative. Recall does not enter planning or mutate the DraftPlan. During the User-manual acknowledgement turn, the no-tool instruction overrides every other route.
+
+## Plan compression
+
+Selected ranges become summaries in future model context; content outside them stays verbatim. Originals remain stored, but recall is a recovery path, not a substitute for a sufficient summary. Agent and user edit one DraftPlan; the user retains final control through review and `/midcompact commit`.
+
+The start mode controls how the first draft is created. It does not determine whether a user selection is final, how much initiative the Agent should take, or how deeply the history should be investigated.
+
+Apply one invariant:
+
+> Every fact that can still affect future work must remain with sufficient fidelity, either outside the selected ranges or in their replacement summaries.
+
+### Planning workflow
 
-Three mechanical facts shape how you work:
+#### 1. Read the entry state and user intent
 
-- **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.
+For a fresh Agent-direct transaction, begin with `action="inspect"`. For a handed-off DraftPlan, begin with `action="plan", op="show"`; inspect the anchor only if the requested work needs broader context.
 
-## Who decides what
+Establish the user's desired scope, fidelity, and planning effort from their words, current selection, `User focus: ...`, and surrounding interaction. Treat answers collected through question, questionnaire, or similar tools as user-originated input even when represented as tool results.
 
-| 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 |
+A manual selection records what the user selected, not whether they mean "only this" or "help me refine it." Follow a clear intent directly. If different interpretations would materially change the work, ask briefly whether to limit work to the selection or inspect and suggest changes. Do not force clarification when the user has already expressed a preference or delegated the judgment.
 
-You cannot commit. `/midcompact commit` is the user's gate. Your output is a proposal.
+Match effort to the requested fidelity. A quick or approximate request calls for bounded planning; a precision-sensitive request may justify deeper work after alignment.
 
-## What may be compressed
+#### 2. Form a bounded semantic view
 
-One conservation law decides every case:
+`inspect` returns factual structure with bounded user landmarks, grouped by user message. Use it for structure and volume, not to invent semantics. Ground candidates in visible conversation or a few targeted `locate` calls, and stop paging after the potentially relevant region. When exact candidate spans are known and their relative volume could change the choice, use read-only `inspect` spans to compare them without mutating the DraftPlan.
 
-> 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.
+Segment by completed work phase, not message count. User-originated input and concluding Agent responses are useful landmarks for intent and outcome, but are not automatically KEEP. Intermediate tool exchanges may also contain decisions or evidence absent from the final response.
 
-Not age. Not token count. Not whether it is a tool call or prose. Two consequences follow:
+| Often able to yield to a summary | Often load-bearing |
+|-----------------------------------|--------------------|
+| Repetitive or superseded exploration | Current intent and active constraints |
+| Tool output absorbed into a conclusion | Exact errors, evidence, or wording whose form matters |
+| A completed subtask's intermediate process | Decisions and rationale still governing the work |
+| A rejected attempt's mechanics | Its still-relevant failure reason |
 
-- **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.
+Use little or no `locate` during this reconnaissance. If a phase cannot yet be described faithfully, omit it from the proposal or mark it as needing confirmation rather than exploring the anchor broadly.
 
-Illustrative cases, derived from the law:
+#### 3. Present semantic options and align
 
-- 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.
+Before deep `locate` work or substantial DraftPlan mutation, establish the user's compression preference through explicit instruction, a reliable implication, or concise clarification.
 
-**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.
+Describe each proposal in recognizable conversation terms:
 
-**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.
+> From `<semantic start>` to `<semantic end>`, `<replace the whole phase / keep the endpoints and compress the work between>`; preserve `<load-bearing information>` in the summary.
 
-## Phase 1 — read, segment, propose, align
+Use short recognizable excerpts when available and clear paraphrases otherwise. State whether the endpoint messages remain verbatim, what intermediate work disappears, and what the summary carries. Do not identify a user-facing range primarily by atom refs, DraftPlan ids, or arbitrary item numbers.
 
-**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.
+When treatments involve a meaningful tradeoff, present concise alternatives and recommend one. A clear quick request may need only one proportionate proposal. Add factual content or image measurements only when they help the choice, and do not convert them into unsupported token-savings claims.
 
-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.
+#### 4. Resolve boundaries and build the DraftPlan
 
-`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.
+After the intended treatment is clear, use `action="locate"` for targeted content and boundary checks. An atom is the smallest selectable unit; a tool call and its matching results form one indivisible `tool_exchange` atom. Keep source text outside a range when exact wording or provenance matters and a summary cannot preserve it equivalently.
 
-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.
+Choose boundaries from the information that must survive, not from a fixed category. A range may replace a whole semantic phase, including its initiating and concluding messages. It may instead retain a load-bearing user instruction and concluding Agent response while replacing only the execution between them. It may split around important material to leave KEEP holes. These are reasoning patterns, not rules tied to start mode, message age, or one prescribed kind of work.
 
-## Phase 2 — locate, draft, review
+Build or refine the shared DraftPlan with `plan add`, `update`, `remove`, and `show`. A handed-off selection may be preserved or revised as the user's intent permits. Use separate ranges for non-contiguous phases; fill pending summaries before commit. If deeper inspection would materially change the agreed treatment, surface the change instead of silently applying it.
 
-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.
+Read `references/tool-interface.md` before retrying a rejected operation or when exact parameters, protected-atom causes, or measurements matter.
 
-## Tool interface
+#### 5. Write replacement summaries
+
+A replacement summary is successor context for a future Agent, not a transcript or a prompt to perform compression. State the resulting knowledge and working state directly.
+
+Preserve, when applicable:
+
+- user intent and active constraints;
+- decisions, conclusions, and necessary rationale;
+- relevant files, symbols, interfaces, commands, or configuration;
+- completed changes and validation results;
+- rejected approaches only when their failure reason still matters;
+- unresolved issues and any established next step or continuation state.
+
+Remove repetitive exploration, superseded hypotheses, raw output captured by a conclusion, and chronology with no remaining consequence. Do not turn uncertainty into fact, invent a next action, or use references that only make sense inside the removed text. If retained endpoint messages already carry part of the intended context, do not duplicate them mechanically; use the summary to preserve what would otherwise be lost.
+
+Organize by future utility rather than original chronology. When useful, use this compact frame without forcing empty fields:
+
+```text
+Goal and constraints:
+Established state and decisions:
+Artifacts and validation:
+Open issues and established next state:
+```
 
-**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.
+Length follows the information that must survive, not a target ratio. Final test: could a fresh Agent continue correctly from this summary plus retained context, without repeating work or violating a prior decision?
 
-**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`.
+#### 6. Verify and hand off
 
-`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`).
+Call `action="plan", op="show"`. Check that the intended semantic phases are covered, KEEP holes remain outside ranges, every range has a summary, and the summaries conserve the future working state.
 
-`action="plan"` — `op` defaults to `show`.
+Describe the completed proposal with the same recognizable landmarks used during alignment. Direct the user to `/midcompact select` or `/midcompact select-webui` for boundaries and KEEP holes, and to `/midcompact review` or `/midcompact review-webui` for summary inspection or rejection. Use browser variants when the TUI is unavailable or preferred. Ask the user to run `/midcompact commit` when ready; never commit for them.
 
-| op | Requires |
-|----|----------|
-| `show` | — |
-| `add` | `start`, `end`, `summary`; `topic` optional |
-| `update` | `draft_id` and at least one of `summary`, `topic` |
-| `remove` | `draft_id` |
+## Recall compressed content
 
-`op="add"` rejects a range when any of the following holds. These are mechanical constraints, independent of semantic value — a range must satisfy both.
+Recall works with or without an active planning transaction. It reads committed blocks active on the current branch without changing projection or DraftPlan.
 
-| 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. |
+### Recall workflow
 
-**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.
+#### 1. Find the block
 
-## Repeated compression
+If its id is unknown, call `action="recall", pattern="..."` to search active topics and summaries. A projected summary also states its block id and exact recall call.
 
-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.
+#### 2. Retrieve the detail
 
-## Recall
+Call `action="recall", ref="c0001"`. If the readable, structure-flattened result ends with a truncation marker, retry with `detail="full"`. Retrieve only what the current task needs; do not start or change a plan merely to recall history.
 
-`action="recall"` works whether or not a transaction is active, does not change the projection, and reads blocks active on the current branch.
+## Tool conventions
 
-- `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.
+- `g0001` labels an inventory group; use its `a...` span as internal landmarks.
+- `a0001` is a transaction-local atom ref; `d1` is a DraftPlan range id; `c0001` is an active committed-block id.
+- Protected atoms cannot enter a range. Split around them.
 
-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.
+These refs are planning handles, not the primary way to explain compression to the user. Read `references/tool-interface.md` for exact defaults and limits, rejected operations, protected-atom causes, measurements, repeated compression, or recall truncation.

package/skills/midcompact/references/tool-interface.md

@@ -0,0 +1,83 @@
+# Midcompact Tool Interface
+
+Read this reference when exact call requirements, limits, rejection behavior, repeated compression, or recall truncation matters. The main workflow remains in `../SKILL.md`.
+
+## Inspect
+
+Without `spans`, `action="inspect"` inventories the frozen anchor. It returns factual structure and bounded user landmarks, not full message bodies, assistant/tool previews, summaries, or image base64.
+
+- `page_size`: default 20 groups, maximum 50.
+- `cursor`: opaque value returned by the previous page.
+- Results include group refs, atom spans, content chars, image facts, protected/compressible counts, and Pi-reported anchor usage.
+
+Stop paging after the candidate regions are covered.
+
+To compare explicit candidates without mutating the DraftPlan, pass one or more possibly overlapping spans:
+
+```text
+midcompact(action="inspect", spans=[
+  {"start":"a0006","end":"a0014"},
+  {"start":"a0006","end":"a0020"}
+])
+```
+
+Span inspection reports bounded endpoint landmarks, atom/message and role counts, tool exchanges and calls, factual content share, images, and protected/compressible counts. It has a 12,000-character total output budget and reports how many requested spans fit. It does not report per-span tokens: Pi supplies usage for the whole anchor, not token attribution by range. Do not combine `spans` with `page_size` or `cursor`.
+
+## Locate
+
+`action="locate"` returns atoms from the frozen anchor. Supply either:
+
+- `ref`: one direct atom lookup; or
+- at least one real filter: `pattern`, `tool_name`, or `source` other than `any`.
+
+With no lookup or filter it returns no matches rather than an error. Filtered searches return at most three brief candidates; when more match, the result reports the total and asks for a more specific pattern or additional filter. `direction` is `oldest` by default or `newest`; `limit` may request one to three results.
+
+Brief direct lookups preserve both ends of an atom landmark. Pattern searches show a bounded excerpt around the match rather than the atom prefix. `detail="full"` is allowed only with one direct `ref` and preserves both ends with an explicit middle-omission marker when the 12,000-character atom limit is exceeded.
+
+A `g...` inventory ref is not a locate ref; use the group's `a...` start/end landmarks.
+
+## Plan
+
+`action="plan"` uses `op="show"` by default. Agent and user mutate the same DraftPlan.
+
+| op | Required fields |
+|----|-----------------|
+| `show` | none; optional `draft_id` for one range |
+| `add` | `start`, `end`; optional `summary`, `topic` |
+| `update` | `draft_id` and at least one of `summary`, `topic` |
+| `remove` | `draft_id` |
+
+Default show lists each range with bounded `from`, `to`, and `summary` landmarks plus factual metrics. Use `op="show", detail="full", draft_id="d1"` for one stored summary and endpoint previews under a 40,000-character total budget; full detail without `draft_id` is rejected. Show is read-only and does not persist a duplicate DraftPlan entry.
+
+Add/update return the changed range in brief form; remove returns its id and compact draft totals. Mutation responses omit the Pi-awareness header and unchanged ranges. Use explicit show when complete awareness is needed.
+
+An omitted or empty `summary` creates a pending range. Review can open it, but commit requires at least one range and a non-empty summary for every range. Changing boundaries requires removing the old range and adding the replacement.
+
+### Add rejection conditions
+
+| Condition | Response |
+|-----------|----------|
+| The range crosses a protected atom | Split the range around that atom |
+| The range overlaps an existing draft range | Remove or replace the existing range first |
+| `start` occurs after `end` | Correct the positional order |
+| An atom ref is unknown | Re-run inspect/locate against the current transaction snapshot |
+
+An atom is protected when its tool protocol is incomplete or orphaned, it represents an existing compressed block, its message kind is unsupported, or it lacks the persistent session entry needed to anchor compression.
+
+## Telemetry
+
+Explicit `plan show` includes Pi-reported anchor usage when available and factual draft measurements: original/replacement content chars, image count, and decoded payload bytes. Mutation results omit awareness and report only compact totals plus the changed range where one remains. Local character or image measurements are not converted into token savings or projected-token percentages. Use measurements to compare the proposal with user-directed depth, not as an optimization target.
+
+## Repeated compression
+
+Committed blocks appear as protected atoms in later transaction snapshots and cannot be compressed again. A later transaction may compress newly accumulated raw history around those blocks. Re-run inspect/locate because atom refs are transaction-local.
+
+## Recall
+
+`action="recall"` works independently of a planning transaction and reads committed blocks active on the current branch.
+
+- Without `ref`, `pattern` searches block topics and summaries; `limit` defaults to 8 and has a maximum of 20.
+- With `ref="c0001"`, the tool renders that block's stored messages.
+- `detail="full"` raises the rendering cap when the normal result is truncated.
+
+Recall has no paging. The truncation marker is `[truncated; refine the recall request or inspect the source session for more]`. If `detail="full"` still truncates before the needed detail, report that recall cannot expose the omitted content; do not infer it.

package/src/atoms.ts

@@ -1,5 +1,6 @@
 import type { Atom, LocateQuery, MessageLike, MessageRef, SessionEntryLike } from "./types.js";
-import { approxTokens, mapEntryIds, messageKey, renderMessage, toolCalls, truncate } from "./messages.js";
+import { aggregateMetrics, measureMessage } from "./content-metrics.js";
+import { approxTokens, excerptAround, mapEntryIds, messageKey, renderMessage, toolCalls, truncateMiddle } from "./messages.js";
 
 export function buildAtoms(messages: MessageLike[], branch: readonly SessionEntryLike[]): Atom[] {
   const entryIds = mapEntryIds(messages, branch);
@@ -70,6 +71,11 @@ export function buildAtoms(messages: MessageLike[], branch: readonly SessionEntr
   return atoms;
 }
 
+/** A protected atom cannot be part of any compressible range. */
+export function isProtectedAtom(atom: Atom): boolean {
+  return !atom.compressible || !atom.protocolClosed || atom.kind === "compressed";
+}
+
 function hasEntry(ref: MessageRef): boolean {
   return typeof ref.entryId === "string" && ref.entryId.length > 0;
 }
@@ -103,8 +109,9 @@ function makeAtom(
     messages,
     entryIds: messages.flatMap((ref) => (ref.entryId ? [ref.entryId] : [])),
     messageKeys: messages.map((ref) => ref.key),
-    preview: truncate(fullText, 700),
+    preview: truncateMiddle(fullText, 700),
     fullText,
+    metrics: aggregateMetrics(messages.map((ref) => measureMessage(ref.message))),
     approxTokens: approxTokens(fullText),
     compressible,
     protocolClosed,
@@ -114,10 +121,17 @@ function makeAtom(
   };
 }
 
-export function locateAtoms(atoms: Atom[], query: LocateQuery): Atom[] {
+export const MAX_LOCATE_MATCHES = 3;
+
+export interface LocatedAtoms {
+  atoms: Atom[];
+  totalMatches: number;
+}
+
+export function locateAtomMatches(atoms: Atom[], query: LocateQuery): LocatedAtoms {
   if (query.ref) {
     const atom = atoms.find((candidate) => candidate.ref === query.ref);
-    return atom ? [atom] : [];
+    return { atoms: atom ? [atom] : [], totalMatches: atom ? 1 : 0 };
   }
   const pattern = query.pattern?.toLocaleLowerCase();
   const toolName = query.toolName?.toLocaleLowerCase();
@@ -129,7 +143,13 @@ export function locateAtoms(atoms: Atom[], query: LocateQuery): Atom[] {
     return Boolean(pattern || toolName || source !== "any");
   });
   if ((query.direction ?? "oldest") === "newest") matches = matches.reverse();
-  return matches.slice(0, Math.max(1, Math.min(query.limit ?? 5, 20)));
+  const totalMatches = matches.length;
+  const limit = Math.max(1, Math.min(query.limit ?? MAX_LOCATE_MATCHES, MAX_LOCATE_MATCHES));
+  return { atoms: matches.slice(0, limit), totalMatches };
+}
+
+export function locateAtoms(atoms: Atom[], query: LocateQuery): Atom[] {
+  return locateAtomMatches(atoms, query).atoms;
 }
 
 function matchesSource(atom: Atom, source: NonNullable<LocateQuery["source"]>): boolean {
@@ -141,9 +161,13 @@ function matchesSource(atom: Atom, source: NonNullable<LocateQuery["source"]>):
   return false;
 }
 
-export function formatLocatedAtom(atom: Atom, detail: "brief" | "full" = "brief"): string {
+export function formatLocatedAtom(atom: Atom, detail: "brief" | "full" = "brief", pattern?: string): string {
   const flags = [atom.kind, atom.compressible ? "compressible" : "protected", atom.protocolClosed ? "closed" : "open"].join(", ");
-  const text = detail === "full" ? truncate(atom.fullText, 12_000) : atom.preview;
+  const text = detail === "full"
+    ? atom.fullText.length <= 12_000 ? atom.fullText : truncateMiddle(atom.fullText, 12_000)
+    : pattern
+      ? excerptAround(atom.fullText, pattern, 700)
+      : atom.preview;
   return [
     `${atom.ref} | position ${atom.index + 1} | ${flags}`,
     atom.toolNames.length ? `tools: ${atom.toolNames.join(", ")}` : "",