pi-condense 2.2.1 → 2.4.0

package/CHANGELOG.md

@@ -9,6 +9,14 @@ publishes via OIDC trusted publishing. See `.agents/skills/release/SKILL.md`.
 
 ## [Unreleased]
 
+## [2.4.0] - 2026-07-09
+
+- **Summarizer call timeout.** Every summarizer stream call is now bounded by an idle timeout (`summarizerIdleTimeoutMs`, default 20s - reset on every stream event, so it never false-aborts a flowing or reasoning generation) and a total-duration ceiling (`summarizerMaxTimeoutMs`, default 180s). Previously a stalled-but-open provider connection hung the whole agent turn indefinitely, since `runOnce` had no time budget and the automatic flush paths pass no abort signal. A timeout classifies as transient and feeds the existing outage-fallback retry (one bounded session-model attempt when a distinct `summarizerModel` is set), then surfaces a `warning` notice. Both timers are `0`-disablable and exposed in `/pruner settings` and `/pruner status`.
+
+## [2.3.0] - 2026-07-06
+
+- **Recovery grace window for `context_tree_query` output.** The pruner used to re-stub its own recovery output at the next turn boundary, forcing a retrieve -> re-stub -> re-query loop the agent experiences as "fighting the pruner" (observed in a real session: a recovered tool dump was re-summarized on the very next flush, so the agent had to keep re-querying the same ref). A new `recoveryGraceTurns` setting (default `3`, `0` disables) keeps a recovered output verbatim for that many user-turn-groups before reverting to the stub. Enforced at **render time** in two places - Phase 1 stub-replace (`src/pruner.ts`) and chain-compression eligibility (`src/chain-compressor.ts`, which defers compressing any chain whose span still holds an in-grace recovery id) - never at capture, so the frontier, dedup, spill, and live `turn_end` paths are unchanged. The window is computed positionally from the message stream (no new `ToolCallRecord` field). Default `3` covers ~81% of same-ref re-queries observed in the local session corpus; the accepted trade-off is that a reference past the window is re-stubbed and may be re-queried, keeping context regrowth bounded rather than permanent. Tunable via `/pruner recovery-grace [n]` and the `/pruner settings` overlay. See [PRUNING.md § What Pruning Does](PRUNING.md#what-pruning-does).
+
 ## [2.2.1] - 2026-07-06
 
 - **Fix probe starvation in the summarizer outage fallback.** `FallbackController.onFallbackOnlyFail` reset the re-probe cooldown on every steady-state fallback failure, so a fallback (session) model that failed at least once per 10-minute cooldown perpetually pushed out the primary re-probe - a recovered `summarizerModel` was never re-tested and summarization stayed on the pricier session model indefinitely (the exact stall the feature exists to kill, in the fallback direction). The method is now a no-op on `lastProbeAt`: the primary re-probe fires on schedule regardless of fallback failures. In-memory only; no wire/config change.

package/PRUNING.md

@@ -185,6 +185,9 @@ graph TB
 - Every pruned tool call is also copied into the pruner's runtime/session index with its `toolCallId`, tool name, args, status, turn index, timestamp, and full `resultText`.
 - A summary message is injected as a `"steer"` (`pi.sendMessage` runtime path) or appended directly via `sessionManager.appendCustomMessageEntry` (session path, used when Pi may already be shutting down). Both deliver before the next LLM call.
 - The session JSONL file retains the original tool-result entries unchanged — pruning only affects what the *next* request sees in active context.
+- **Recovery grace window (`recoveryGraceTurns`, default 3):** after the model recovers a tool call via `context_tree_query`, that tool call's output is rendered **verbatim** (not re-stubbed) for the next N user-turn-groups, then reverts to the normal stub. Without this, the pruner re-prunes its own recovery output on the very next flush, forcing the model into a retrieve -> re-stub -> re-query loop ("fighting the pruner") whenever it keeps referencing the same recovered data across a few turns.
+  - Enforced at **render time**, in Phase 1 stub-replace and in chain-compression eligibility — NOT at capture time. Capture-time exclusion would collide with frontier trim: a tool call already past the frontier is dropped forever, so excluding a recovered call from capture would either need to resurrect frontier state or degrade the lifetime bound into permanent verbatim retention for anything ever recovered.
+  - Trade-off: this bounds but does not eliminate regrowth. A tool call still referenced after its grace window expires is re-stubbed and may be re-queried again — the accepted cost of keeping the window's context-growth impact bounded instead of unbounded.
 
 ---
 

package/README.md

@@ -6,251 +6,173 @@
 
 [![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-donate-yellow?logo=buymeacoffee&logoColor=black)](https://buymeacoffee.com/jjurasszek)
 
-A [Pi coding-agent](https://github.com/earendil-works/pi) extension that summarizes completed tool-call batches, replaces raw tool outputs with short stubs in future context, and lets the LLM recover any original via the `context_tree_query` tool.
+A [Pi coding-agent](https://github.com/earendil-works/pi) extension that keeps long agent sessions cheap by pruning context - **the context-economy layer of the pi agent toolkit** (see below).
 
-The session JSONL file is never modified — pruning only affects what each *next* request sees.
+## The problem
 
-Adds pre-flush safeguards, agent-message batching, chain compression, and an npm release flow on top of the original approach from [`championswimmer/pi-context-prune`](https://github.com/championswimmer/pi-context-prune).
+Every long agent session accumulates raw tool output - file reads, command dumps, search results - that the model already used and will never need again verbatim. Left in context, it degrades reasoning on later turns, inflates the cost of *every* subsequent request, and pushes a smaller/cheaper model past the point where it can still drive. Provider prompt-caching does not fix this on its own: naive trimming actively fights it, because rewriting the prompt on every turn busts the cache you were relying on to keep costs down.
 
-📖 For the algorithm, design rationale, prompt-cache interaction, and the research behind summarization-based context management, see **[PRUNING.md](PRUNING.md)**.
+**pi-condense** replaces finished tool-call batches with short, recoverable summaries, timed around exactly that caching problem. Nothing is deleted - the session file on disk is untouched, and any summarized result can be pulled back verbatim via the `context_tree_query` tool. Net effect: long sessions stay affordable, and a smaller/cheaper driver model stays viable for longer.
 
-## Install
+## Why this, not naive trimming
 
-Published to npm as [`pi-condense`](https://www.npmjs.com/package/pi-condense).
+- **Recoverable, not lossy.** Originals are archived and addressable by a short ref. Summarizing only changes what the model *sees by default* - not what it can retrieve on demand.
+- **Batched against the cache, not per turn.** Pruning fires once per finished unit of work (configurable), so the prompt prefix stays stable in between and providers keep serving it from cache. Pruning every turn instead would bust the cache on every single turn - the opposite of the intended savings.
 
-**User scope** (all repos under your pi profile):
+The full argument, with diagrams, is in **[PRUNING.md](PRUNING.md)**; this README stays at the "why and how to use it" level.
 
-```bash
-pi install npm:pi-condense
-```
+## Part of the pi agent toolkit
 
-**Project scope** (current repo only, committable via `.pi/settings.json`):
+Four independent extensions for the [pi coding agent](https://github.com/earendil-works/pi), each owning one concern of running agents seriously:
 
-```bash
-pi install -l npm:pi-condense
+- [pi-quiver](https://github.com/jjuraszek/pi-quiver) - capabilities (fetch, doc conversion, session tools)
+- [pi-cohort](https://github.com/jjuraszek/pi-cohort) - coordination (delegate to focused child agents)
+- **pi-condense - context economy (this repo): prune context, keep it recoverable**
+- [pi-gauntlet](https://github.com/jjuraszek/pi-gauntlet) - process (the gated brainstorm->ship workflow)
+
+No code dependency either way. The practical coupling: pi-condense is what keeps a long pi-cohort fan-out or a long pi-gauntlet gated run affordable as it grows, and both can surface pi-condense's live cost via the shared `cost:external` channel (see [External cost channel](#external-cost-channel)).
+
+## Mental model
+
+Two-layer memory, not deletion:
+
+- **Hot:** a compact summary of a finished batch, kept in active context.
+- **Cold:** the full original tool results, archived in a session-local index and addressable by a short ref (`t1`, `t2`, ...).
+
+The model reads the hot summary by default and calls `context_tree_query` when it actually needs the cold original back. See [PRUNING.md](PRUNING.md) for the full before/after diagrams and the prefix-cache mechanics behind the batching schedule.
+
+```mermaid
+flowchart LR
+    B["finished tool-call batch<br/>(t1, t2, t3 ...)"] --> S[summarize into short stub]
+    S --> H["hot: model sees the stub"]
+    B -.archived, session file untouched.-> C["cold: originals by ref"]
+    H -->|"context_tree_query(t2)"| C
+    C -.restores original.-> H
 ```
 
-**Try without installing**:
+## Quick example
 
 ```bash
-pi -e npm:pi-condense
+pi install npm:pi-condense
 ```
 
-**From a local checkout** (for hacking on the extension itself):
-
 ```bash
-git clone git@github.com:jjuraszek/pi-condense.git ~/repos/pi-condense
-cd ~/path/to/your/repo
-pi install -l ~/repos/pi-condense
-# or one-shot, no install:
-pi -e ~/repos/pi-condense/index.ts
+/pruner on                          # enable pruning (off by default)
+/pruner model openai/gpt-4.1-mini   # pick a cheap summarizer
+/pruner status                      # see mode, model, trigger, cumulative stats
 ```
 
-Pin a specific version with `npm:pi-condense@X.Y.Z`. Upgrade by re-running `pi install`. Remove with `pi remove pi-condense`. Once installed, the extension auto-loads on every `pi` invocation; no flags needed.
+## Architecture
 
-> See [CHANGELOG.md](CHANGELOG.md) for release history.
+| Trigger mode | Fires | Cache impact |
+|---|---|---|
+| `agent-message` (default) | When the agent sends a final text-only reply | ~1 cache rewrite per task batch |
+| `on-demand` | Only when you run `/pruner now` | None until you ask |
 
-## Quick start
+Before any summarizer call, a pre-flush pipeline can drop or redirect a batch at zero LLM cost: protected tools/paths are never touched, content-hash duplicates are aliased to the original, batches too small to be worth summarizing are skipped outright, and oversized single results are spilled straight to a sidecar file. Closed tool-call chains older than a rolling window are additionally range-compressed. Full pipeline and each safeguard: [PRUNING.md § Pre-flush Pipeline & Safeguards](PRUNING.md#pre-flush-pipeline--safeguards), [§ Chain Compression](PRUNING.md#chain-compression).
 
-```bash
-/pruner on                          # enable pruning
-/pruner status                      # see current mode + cumulative cost
-/pruner model openai/gpt-4.1-mini   # pick a cheap summarizer
-/pruner now                         # flush pending batches immediately
-```
+### External cost channel
 
-By default the extension is **off**. Enable it once and it stays enabled across sessions in the same pi agent directory.
-
-## How it decides when to prune
-
-Two trigger modes. The mode controls *when* summarization fires; the algorithm is the same in each.
-
-| Mode | Trigger | Cache impact | Use when |
-|---|---|---|---|
-| `agent-message` (default) | When the agent sends a final text-only reply | One cache rewrite per task batch | Normal coding-agent work — best balance |
-| `on-demand` | Only when you run `/pruner now` | None until you ask | Long investigations; manual control |
-
-Why `agent-message` is the default: provider prefix caches (Anthropic, OpenAI, Bedrock, vLLM) only hit when the prompt prefix matches exactly. Every prune rewrites that prefix. Batching tool turns and pruning once per agent reply means roughly one cache miss per task instead of one per turn. See [PRUNING.md § The Sweet Spot](PRUNING.md#the-sweet-spot-batch-and-prune) for the full argument.
-
-## Configuration
-
-Settings live under the `contextPrune` key in `<agent-dir>/settings.json` (i.e. pi's own settings file). `<agent-dir>` is `$PI_CODING_AGENT_DIR` if set, otherwise `~/.pi/agent`. Each pi preset gets its own settings, so you can run different summarizer models per preset.
-
-```json
-{
-  "contextPrune": {
-    "enabled": false,
-    "showPruneStatusLine": true,
-    "summarizerModel": "default",
-    "summarizerThinking": "default",
-    "pruneOn": "agent-message",
-    "batchingMode": "turn",
-    "quietOversizedSkips": false,
-    "minBatchChars": 1000,
-    "protectedTools": [],
-    "protectedPaths": ["**/skills/**/*.md"],
-    "dedupByContentHash": true,
-    "autoBudgetThreshold": null,
-    "spillThreshold": 65536,
-    "spillPreviewBytes": 2048,
-    "budgetTurnDelta": null,
-    "chainCompression": {
-      "enabled": true,
-      "rollingWindow": 3,
-      "stripFinalAssistantThinking": true,
-      "fuseRangeSummary": true
-    },
-    "thinkingStrip": {
-      "enabled": true,
-      "keepLastTurns": 16
-    }
-  }
-}
-```
+Every summarizer cost update is emitted on the shared `pi.events` channel `cost:external` (`source: "pi-condense"`, cumulative per session, live only - not persisted, not re-seeded on restart). This is a generic channel: pi-condense is a producer, not the owner. [pi-cohort](https://github.com/jjuraszek/pi-cohort) is the canonical consumer, folding it into a single `Σ$` total alongside its own subagent costs.
 
-| Key | Values | Default | Notes |
-|---|---|---|---|
-| `enabled` | `true` / `false` | `false` | Master switch |
-| `showPruneStatusLine` | `true` / `false` | `true` | Footer widget + queued-turn notifications |
-| `summarizerModel` | `"default"` or `"provider/model-id"` | `"default"` | `default` = your active pi model. See [Choosing a summarizer model](#choosing-a-summarizer-model) |
-| `summarizerThinking` | `default`/`off`/`minimal`/`low`/`medium`/`high`/`xhigh` | `default` | Provider-specific reasoning effort knob |
-| `pruneOn` | see table above | `agent-message` | Trigger mode |
-| `batchingMode` | `turn` / `agent-message` | `turn` | How coarse each summary is (independent of `pruneOn`) |
-| `quietOversizedSkips` | `true` / `false` | `false` | Silences `skipped-oversized` / `skipped-trivial` info notifications |
-| `minBatchChars` | non-negative integer, `0` disables | `1000` | Pre-flush guard — batches smaller than this skip the LLM entirely |
-| `protectedTools` | `string[]` | `[]` | Never-pruned tool names (e.g. `["todowrite","todoread"]`). When a protected tool's chain is range-compressed, its output is preserved verbatim inside the `<compressed-chain>` block as `<protected-output>` — protected outputs are never lost. |
-| `protectedPaths` | `string[]` | `["**/skills/**/*.md"]` | Globs matched against a tool call's `args.path`; matching outputs are never pruned (same semantics as `protectedTools`, including `<protected-output>` relocation in compressed chains). Already-summarized matching reads are repaired on the next turn; chain-compressed ones are not. Set `[]` to disable. |
-| `dedupByContentHash` | `true` / `false` | `true` | Re-reads of identical (toolName, content) skip the LLM and alias the original |
-| `autoBudgetThreshold` | fraction `0`–`1`, or `null` | `null` | Token-budget auto-flush: force a prune when context usage reaches this share of the window, regardless of `pruneOn`. `0.8` = 80%, not `80`. `null` = off. See [Token-budget auto-flush](#token-budget-auto-flush) |
-| `spillThreshold` | positive integer | `65536` | Minimum chars (`resultText.length`) for a single tool result to be spilled eagerly to a sidecar file at capture time rather than waiting for normal summarization. Non-positive / invalid values fall back to the default; to effectively disable spilling, set it above any result you expect. See [Spilled outputs](#spilled-outputs) |
-| `spillPreviewBytes` | non-negative integer | `2048` | Head preview (bytes) kept inline in the stub and index record for a spilled result. Full body is on disk. |
-| `budgetTurnDelta` | fraction `0`–`1`, or `null` | `null` | Force a flush when a single turn's context-usage fraction jumps by at least this amount, ORed with `autoBudgetThreshold`. Catches sudden spikes a static threshold would miss until the next turn. `null` = off. |
-| `chainCompression.enabled` | `true` / `false` | `true` | Master toggle for chain-level range compression |
-| `chainCompression.rollingWindow` | positive integer | `3` | Keep this many most-recent closed chains raw; compress older ones |
-| `chainCompression.stripFinalAssistantThinking` | `true` / `false` | `true` | Strip thinking blocks from the kept final text-only assistant when compressing |
-| `chainCompression.fuseRangeSummary` | `true` / `false` | `true` | Fuse a compressed chain's per-batch summaries into one cohesive LLM summary (one extra summarizer call per multi-batch span); off keeps the per-batch concatenation |
-| `purgeErrors.enabled` | `true` / `false` | `true` | Replace failed toolCall argument bodies with compact stubs after cooldown |
-| `purgeErrors.cooldownTurns` | positive integer | `2` | Turns to wait after a tool error before purging its argument body |
-| `purgeErrors.minArgChars` | non-negative integer | `500` | Only purge arg bodies at least this many characters long |
-| `thinkingStrip.enabled` | `true` / `false` | `true` | Strip `thinking` blocks from assistant turns older than the last `keepLastTurns` |
-| `thinkingStrip.keepLastTurns` | positive integer | `16` | Keep thinking on the last N assistant turns; strip older. Counts assistant turns, not chains. No-op under N turns |
+## Key concepts
 
-See [PRUNING.md § Chain Compression](PRUNING.md#chain-compression), [PRUNING.md § Error Purge](PRUNING.md#error-purge), and [PRUNING.md § Main-loop Thinking Strip](PRUNING.md#main-loop-thinking-strip) for the full algorithms.
+| Term | Meaning |
+|---|---|
+| Stub | The short breadcrumb (`[Summarized in pruner summary, ref \`t1\`...]`) that replaces a pruned tool result in context |
+| `context_tree_query` | The tool the model calls to recover a stubbed original by ref |
+| Batch vs chain | A batch is one flush's worth of tool calls; a chain is a longer closed sequence eligible for range compression |
+| Prune frontier | The last attempted prune boundary - advances even on a skip, so nothing is reconsidered twice |
+| Prompt-cache interaction | Why batching (not per-turn pruning) is the default - see [PRUNING.md](PRUNING.md#how-prefix-caching-works) |
+| `cost:external` | The shared cost-reporting channel pi-condense emits on (see above) |
 
-The three pre-flush features (`minBatchChars`, `protectedTools`, `dedupByContentHash`) are explained in [PRUNING.md § Pre-flush Pipeline & Safeguards](PRUNING.md#pre-flush-pipeline--safeguards). They run BEFORE any summarizer LLM call and can each drop a batch outright while still advancing the prune frontier.
+## When to use / when NOT to use
 
-### Token-budget auto-flush
+**Use it for:** long coding or research sessions where tool output dominates the prompt; setups deliberately running a smaller/cheaper driver model; pi-cohort fan-outs or pi-gauntlet runs where cost compounds across many turns or many children.
 
-When `autoBudgetThreshold` is set to a value in `(0, 1]`, the extension checks context usage at the end of every tool-using turn. If `tokens / contextWindow` reaches the threshold, ALL pending batches are flushed immediately — regardless of `pruneOn` mode. This is an **additional** trigger layered on top of `pruneOn`, not a replacement.
+**Don't reach for it when:** the session is short and one-shot - there is nothing accumulated to prune, only latency to add. It also doesn't replace a provider's own native context-compaction feature if you already rely on that, and it doesn't reduce the cost of the *current* turn's tool calls - only of history that has already been produced.
 
-- `0.8` means 80% of the context window — it is a **fraction**, not a percentage. `0.8 ≠ 80`.
-- The trigger is a no-op when `tokens` is `null` (right after a provider-side compaction); it resumes once usage is known again.
-- Editable live via `/pruner settings` (row "Auto-flush at context %", presets Off / 60 / 70 / 80 / 90%).
-- Default `null` = off.
+## Limitations
 
-Inspired by DCP's `maxContextLimit` nudging; simplified to a single threshold that forces a flush rather than separate nudge/force levels.
+- Pruning only applies to batches captured *while enabled*. Enabling mid-session does not retroactively summarize earlier turns.
+- Summarizer calls run synchronously inside the turn boundary, so they add latency proportional to the summarizer model's response time. Pick a fast one.
+- Content-hash dedup only matches against records already in the indexer (cross-flush); two identical outputs within the *same* flush both go through the summarizer.
+- The tree browser (`/pruner tree`) does not inline original tool outputs - use `context_tree_query` for that.
 
-### Spilled outputs
+## Install
 
-Single tool results larger than `spillThreshold` chars are written to `<session-dir>/<sessionId>-blobs/<toolCallId>.txt` at capture time and replaced in context with a short stub (tool name, byte size, head preview, file path). The full body is recoverable via the native `read` tool at the embedded path (offset/limit supported) or via `context_tree_query` by id, which falls back to the inline preview if the sidecar is missing. Moving a session `.jsonl` without its `-blobs/` directory loses only the giant-blob recovery path; bodies under `spillThreshold` stay inline in the index entry as usual.
+Published to npm as [`pi-condense`](https://www.npmjs.com/package/pi-condense).
 
-### Choosing a summarizer model
+**User scope** (all repos under your pi profile):
 
-The `default` setting reuses whatever model you have active in pi — convenient but wasteful, since summary writing doesn't need a top-tier coding model. Picking the smallest/fastest model on your plan saves both latency and cost.
+```bash
+pi install npm:pi-condense
+```
 
-If the configured summarizer model suffers a transient outage while your active pi model is healthy, pi-condense automatically falls back to the session model for the duration (with a one-time notice) and probes the configured model back every few minutes — no configuration needed.
+**Project scope** (current repo only, committable via `.pi/settings.json`):
 
-| Plan | Suggested summarizer |
-|---|---|
-| OpenAI / Codex / Copilot | `openai/gpt-4.1-mini`, `google/gemini-2.5-flash`, `xai/grok-3-fast` |
-| OpenRouter | `openrouter/qwen/qwen3-30b-a3b` (cheap MoE) |
-| Anthropic direct | `anthropic/claude-haiku-3-5` |
-| Google AI direct | `google/gemini-2.5-flash` |
+```bash
+pi install -l npm:pi-condense
+```
 
-Set it from the slash command (saves immediately):
+**Try without installing**:
 
 ```bash
-/pruner model openai/gpt-4.1-mini
-/pruner thinking low
-# or both in one go:
-/pruner model openai/gpt-4.1-mini:low
+pi -e npm:pi-condense
 ```
 
-## Commands
+**From a local checkout** (for hacking on the extension itself):
 
-| Command | Effect |
-|---|---|
-| `/pruner` | Interactive picker over all subcommands |
-| `/pruner settings` | Settings overlay (toggle / cycle every option) |
-| `/pruner on` / `off` | Enable / disable pruning |
-| `/pruner status` | Show mode, model, trigger, cumulative stats |
-| `/pruner stats` | Detailed cumulative summarizer token/cost stats |
-| `/pruner model [id\[:thinking\]]` | Get / set summarizer model (and optionally thinking level) |
-| `/pruner thinking [level]` | Get / set summarizer reasoning effort |
-| `/pruner prune-on [mode]` | Get / set trigger mode |
-| `/pruner batching [mode]` | Get / set batching granularity (`turn` / `agent-message`) |
-| `/pruner protected-tools [names]` | Show or edit the never-pruned tool allowlist (comma- or space-separated; `none` clears) |
-| `/pruner protected-paths [globs]` | Show or edit the never-pruned path globs (`none` clears) |
-| `/pruner min-batch-chars [n]` | Show or set the pre-flush trivial-batch threshold (`0` disables) |
-| `/pruner dedup [on\|off\|status]` | Toggle pre-flush content-hash dedup |
-| `/pruner tree` | Foldable browser of pruned tool calls; `Ctrl-O` opens the full summary in an overlay |
-| `/pruner compact` | Retroactively compress every eligible closed chain (bypasses `rollingWindow`) |
-| `/pruner now` | Flush pending batches immediately with a multi-row progress widget above the input |
-| `/pruner help` | Full help text |
-
-## Tools surfaced to the LLM
-
-**`context_tree_query`** — always available when the extension is loaded. Pruned summaries end with short refs like `Summarized tool refs: \`t1\`, \`t2\`. Use \`context_tree_query\` with these refs to retrieve the original full outputs.` The model passes those refs (or full `toolCallId`s) and gets back the original tool result text from the session index. Each per-tool bullet in the summary also carries its own inline `` `tN` `` ref, so recovering a specific tool is a single hop; the footer still lists every ref as a fallback. Content-hash-deduped duplicates resolve to the original's record automatically.
-
-## Footer status widget
-
-A footer widget shows the current state, controlled by `showPruneStatusLine`:
-
-Every rendered state is wrapped in `│ … │` so the segment stays visually isolated in the shared footer regardless of where other extensions' status segments land (load-order independent).
-
-- `│ prune: OFF │` — disabled
-- `│ prune: ON │` — enabled, no flushes yet
-- `│ prune: ON · 92k->14k (-85%) │` — enabled; live reclaim ratio (estimated tokens before→after, percent reduction). Updates on every `pruneMessages` call.
-- `│ prune: 3 pending │` — batches queued, waiting for the trigger
-- `│ prune: summarizing… │` — flush in progress
-
-Setting `showPruneStatusLine: false` hides the widget and silences the queued-turn notice; pruning still runs.
-
-Cost no longer appears on the status line. Full token/cost detail is available via `/pruner stats`. The extension also emits cumulative session cost on the `cost:external` pi.events channel for external aggregators — see [External cost channel](#external-cost-channel).
-
-## External cost channel
-
-Every time the summarizer cost updates, the extension emits on the shared `pi.events` channel identified by the constant `EXTERNAL_COST_CHANNEL = "cost:external"`. Payload shape:
-
-```ts
-interface ExternalCostUpdate {
-  source: string;       // EXTERNAL_COST_SOURCE = "pi-condense"
-  totalCost: number;    // cumulative cost for the current session (USD)
-  inputTokens?: number;
-  outputTokens?: number;
-}
+```bash
+git clone git@github.com:jjuraszek/pi-condense.git ~/repos/pi-condense
+cd ~/path/to/your/repo
+pi install -l ~/repos/pi-condense
+# or one-shot, no install:
+pi -e ~/repos/pi-condense/index.ts
 ```
 
-Semantics:
+Pin a specific version with `npm:pi-condense@X.Y.Z`. Upgrade by re-running `pi install`. Remove with `pi remove pi-condense`. Once installed, the extension auto-loads on every `pi` invocation; no flags needed. See [CHANGELOG.md](CHANGELOG.md) for release history.
 
-- **Cumulative per session**, not all-time. Re-emitted on every update; aggregators key by `source` and replace the previous value.
-- **Live only.** Not persisted; not re-emitted on `session_start`. An aggregator that restarts mid-session sees cost from zero until the next summarizer call.
-- Designed for aggregators like pi-cohort that show a unified Σ$ total across extensions.
+By default the extension is **off**. `/pruner on` enables it and it stays enabled across sessions in the same pi agent directory.
 
-## Limitations
+## Configuration - the knobs most people touch
 
-- Pruning only applies to batches captured *while enabled*. Enabling mid-session does not retroactively summarize earlier turns.
-- Summarizer calls are synchronous inside `turn_end` (or `message_end` for `agent-message` mode), so they add latency between turns proportional to the summarizer model's response time. Pick a fast model.
-- Content-hash dedup only matches against records already in the indexer (cross-flush). Two identical outputs within the *same* flush are not deduped — both go through the summarizer.
-- The tree browser does not inline original tool outputs — use `context_tree_query` for that.
+Settings live under `contextPrune` in `<agent-dir>/settings.json` (`$PI_CODING_AGENT_DIR` if set, else `~/.pi/agent`). Each pi preset gets its own settings.
+
+| Key | Default | Notes |
+|---|---|---|
+| `enabled` | `false` | Master switch (or just use `/pruner on`) |
+| `summarizerModel` | `"default"` | Pin a cheap model instead of reusing your active one - see the plan-by-plan table in [doc/configuration.md](doc/configuration.md#choosing-a-summarizer-model) |
+| `pruneOn` | `agent-message` | Trigger mode - see Architecture above |
+| `autoBudgetThreshold` | `null` | Fraction (e.g. `0.8`) of the context window that force-flushes everything regardless of `pruneOn` |
+| `protectedTools` / `protectedPaths` | `[]` / `["**/skills/**/*.md"]` | Tool names / path globs that are never pruned |
+| `spillThreshold` | `65536` | Chars above which a single oversized result spills straight to a sidecar file |
+
+The full settings JSON, every key, the commands table, footer widget states, spilled-output details, and the summarizer-model-by-plan table live in **[doc/configuration.md](doc/configuration.md)**.
+
+## Relationship to the rest of the platform
+
+pi-condense is the context-economy layer: it has no code dependency on the other three, but it is what keeps a long [pi-cohort](https://github.com/jjuraszek/pi-cohort) parallel fan-out or a long [pi-gauntlet](https://github.com/jjuraszek/pi-gauntlet) gated run affordable as they grow, and research on summarization-based context management suggests it can also make a smaller driver model hold up better on long tasks (see [PRUNING.md § Research Evidence](PRUNING.md#why-summarization-works-research-evidence) - a cited hypothesis, not a benchmark run in this repo).
+
+## Roadmap
+
+No committed roadmap beyond what's already tracked in [CHANGELOG.md](CHANGELOG.md); proposals and in-progress work show up there and in repo issues first.
 
 ## Support
 
 If this saves you tokens, [buy me a coffee](https://buymeacoffee.com/jjurasszek).
 
+## Lineage
+
+Adds pre-flush safeguards, agent-message batching, chain compression, and an npm release flow on top of the original approach from [`championswimmer/pi-context-prune`](https://github.com/championswimmer/pi-context-prune).
+
 ## References
 
 - Anthropic prompt caching: <https://docs.claude.com/en/docs/build-with-claude/prompt-caching>
 - AWS Bedrock prompt caching: <https://docs.aws.amazon.com/bedrock/latest/userguide/prompt-caching.html>
 - OpenAI prompt caching: <https://platform.openai.com/docs/guides/prompt-caching>
 - Research backing summarization-based context management: see [PRUNING.md § Research Evidence](PRUNING.md#why-summarization-works-research-evidence)
+
+## License
+
+MIT - see [LICENSE](LICENSE).

package/index.ts

@@ -36,6 +36,7 @@ import { PruneFrontierTracker } from "./src/frontier.js";
 import { BlockRefIssuer } from "./src/block-refs.js";
 import { compressEligible } from "./src/chain-compressor.js";
 import { detectChains, withClosingMessage } from "./src/chain-detector.js";
+import { inGraceRecoveryToolCallIds } from "./src/recovery-grace.js";
 import { shouldBudgetFlush, shouldDeltaFlush, usageFraction } from "./src/budget.js";
 import { spillOversizedBatch } from "./src/spill.js";
 
@@ -530,6 +531,7 @@ export default function (pi: ExtensionAPI) {
           // message_end fires before pi persists the closing assistant, so thread it
           // in here; otherwise the newest chain reads as open and K over-retains by 1.
           const chains = detectChains(withClosingMessage(branchMessages, options.closingMessage), protectionPredicate);
+          const inGrace = inGraceRecoveryToolCallIds(branchMessages, currentConfig.value.recoveryGraceTurns);
           const { compressedEntries } = await compressEligible(
             chains,
             currentConfig.value.chainCompression.rollingWindow,
@@ -540,6 +542,7 @@ export default function (pi: ExtensionAPI) {
               now: () => Date.now(),
               fuseRange: makeFuseRange(ctx),
             },
+            inGrace,
           );
           if (compressedEntries.length > 0) {
             statsAccum.addChainsCompressed(compressedEntries.length);
@@ -825,6 +828,7 @@ export default function (pi: ExtensionAPI) {
       currentConfig.value.purgeErrors,
       currentConfig.value.thinkingStrip,
       currentConfig.value,
+      currentConfig.value.recoveryGraceTurns,
     );
     if (result.pruned) {
       messages = result.messages;
@@ -847,6 +851,7 @@ export default function (pi: ExtensionAPI) {
       .filter((e: any) => e.type === "message" && e.message)
       .map((e: any) => e.message);
     const chains = detectChains(branchMessages, protectionPredicate);
+    const inGrace = inGraceRecoveryToolCallIds(branchMessages, currentConfig.value.recoveryGraceTurns);
     const result = await compressEligible(
       chains,
       0, // effectiveK=0: compress every closed chain not already compressed
@@ -857,6 +862,7 @@ export default function (pi: ExtensionAPI) {
         now: () => Date.now(),
         fuseRange: makeFuseRange(ctx),
       },
+      inGrace,
     );
     if (result.compressedEntries.length > 0) {
       statsAccum.addChainsCompressed(result.compressedEntries.length);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-condense",
-  "version": "2.2.1",
+  "version": "2.4.0",
   "description": "Pi coding-agent extension that summarizes completed tool-call batches, replaces raw outputs with short stubs, compresses closed tool-call chains, and recovers any original on demand via context_tree_query.",
   "author": "Jacek Juraszek",
   "license": "MIT",
@@ -27,7 +27,7 @@
     "ai"
   ],
   "engines": {
-    "node": ">=20"
+    "node": ">=20.3.0"
   },
   "files": [
     "index.ts",

package/src/chain-compressor.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from "bun:test";
+import { describe, expect, it, test } from "bun:test";
 import { selectEligible, compressEligible } from "./chain-compressor.js";
 import type { ChainCompressorIndexerDeps } from "./chain-compressor.js";
 import type { ChainRange, ChainCompressionEntry } from "./types.js";
@@ -281,3 +281,35 @@ describe("compressEligible", () => {
     expect(result.compressedEntries[0].rangeSummaryText).toBeUndefined();
   });
 });
+
+describe("selectEligible - recovery grace deferral", () => {
+  const chain = (startTs: number, ids: string[]) =>
+    ({
+      startUserTimestamp: startTs,
+      finalAssistantTimestamp: startTs + 10,
+      middleToolCallIds: ids,
+      protectedToolCallIds: [],
+    }) as any;
+  it("defers a chain whose span holds an in-grace recovery id", () => {
+    const chains = [chain(1, ["a", "t1"]), chain(2, ["b"])];
+    const eligible = selectEligible(chains, 0, new Set(), new Set(["t1"]));
+    expect(eligible.map((c) => c.startUserTimestamp)).toEqual([2]);
+  });
+  it("compresses normally when no in-grace recovery id is present", () => {
+    const chains = [chain(1, ["a", "t1"]), chain(2, ["b"])];
+    const eligible = selectEligible(chains, 0, new Set(), new Set());
+    expect(eligible.map((c) => c.startUserTimestamp)).toEqual([1, 2]);
+  });
+  it("defers only the grace chain without shrinking the rolling-window buffer", () => {
+    // 5 eligible chains, rollingWindow=2 -> the window boundary is at n-W=3, so chains
+    // 1,2,3 are candidates for compression and 4,5 sit in the protected buffer.
+    // The in-grace id lives on chain 4, which is already outside the compress slice and
+    // must not affect it. A pre-slice filter (the bug) removes chain 4 from `candidates`
+    // before the boundary is computed, shrinking it to 4 items and shifting the cut to
+    // n-W=2 -> wrongly dropping chain 3 too. The fix computes the boundary first, so the
+    // in-buffer grace id changes nothing and the compress set stays [1, 2, 3].
+    const chains = [chain(1, ["a"]), chain(2, ["b"]), chain(3, ["c"]), chain(4, ["d", "t1"]), chain(5, ["e"])];
+    const eligible = selectEligible(chains, 2, new Set(), new Set(["t1"]));
+    expect(eligible.map((c) => c.startUserTimestamp)).toEqual([1, 2, 3]);
+  });
+});

package/src/chain-compressor.ts

@@ -13,11 +13,16 @@ import type { BlockRefIssuer } from "./block-refs.js";
  * @param chains Must be in chronological order (oldest first), as emitted by
  *   chain-detector. Ordering is not validated here; out-of-order input silently
  *   picks wrong chains because the rolling-window slice is positional.
+ * @param inGraceToolCallIds Recovery ids still within their grace window. Chains
+ *   spanning one of these ids are deferred from compression, but the rolling-window
+ *   boundary itself is computed BEFORE grace exclusion, so a grace-protected chain
+ *   never shrinks the window buffer or shifts which other chains become eligible.
  */
 export function selectEligible(
   chains: ChainRange[],
   rollingWindow: number,
   alreadyCompressed: Set<number>,
+  inGraceToolCallIds: Set<string> = new Set(),
 ): ChainRange[] {
   const candidates = chains.filter(
     (c) =>
@@ -25,7 +30,8 @@ export function selectEligible(
       !alreadyCompressed.has(c.startUserTimestamp) &&
       c.middleToolCallIds.length > 0,
   );
-  return candidates.slice(0, Math.max(0, candidates.length - rollingWindow));
+  const toCompress = candidates.slice(0, Math.max(0, candidates.length - rollingWindow));
+  return toCompress.filter((c) => !c.middleToolCallIds.some((id) => inGraceToolCallIds.has(id)));
 }
 
 /**
@@ -71,6 +77,7 @@ export async function compressEligible(
   chains: ChainRange[],
   rollingWindow: number,
   deps: CompressEligibleDeps,
+  inGraceToolCallIds: Set<string> = new Set(),
 ): Promise<CompressEligibleResult> {
   const alreadyCompressedTimestamps = new Set(
     deps.indexer.getChainEntries().map((e) => e.startUserTimestamp),
@@ -85,7 +92,7 @@ export async function compressEligible(
     }
   }
 
-  const eligible = selectEligible(chains, rollingWindow, alreadyCompressedTimestamps);
+  const eligible = selectEligible(chains, rollingWindow, alreadyCompressedTimestamps, inGraceToolCallIds);
 
   const compressedEntries: ChainCompressionEntry[] = [];
   for (const chain of eligible) {